@orkestrel/markdown 0.0.12 → 0.0.14

package/dist/src/core/index.d.cts

@@ -1,30 +1,30 @@
 import { BooleanShape } from '@orkestrel/contract';
-import { CommentNode } from '@orkestrel/html';
-import { ContractInterface } from '@orkestrel/contract';
-import { DoctypeNode } from '@orkestrel/html';
-import { ElementNode } from '@orkestrel/html';
-import { Guard } from '@orkestrel/contract';
-import { HTMLDocument } from '@orkestrel/html';
-import { HTMLNode } from '@orkestrel/html';
+import type { CommentNode } from '@orkestrel/html';
+import type { ContractInterface } from '@orkestrel/contract';
+import type { DoctypeNode } from '@orkestrel/html';
+import type { ElementNode } from '@orkestrel/html';
+import type { Guard } from '@orkestrel/contract';
+import type { HTMLDocument } from '@orkestrel/html';
+import type { HTMLNode } from '@orkestrel/html';
 import { LiteralShape } from '@orkestrel/contract';
 import { NumberShape } from '@orkestrel/contract';
 import { ObjectShape } from '@orkestrel/contract';
 import { OptionalShape } from '@orkestrel/contract';
 import { StringShape } from '@orkestrel/contract';
-import { TextNode as TextNode_2 } from '@orkestrel/html';
+import type { TextNode as TextNode_2 } from '@orkestrel/html';
 
-/** A node that can appear at the block level of a document (or inside a list item / blockquote). */
+/** Represents a node that can appear at the block level of a document (or inside a list item / blockquote). */
 export declare type BlockNode = HeadingNode | ParagraphNode | ListNode | TableNode | CodeBlockNode | BlockquoteNode | ThematicBreakNode;
 
-/** A blockquote - `>`-prefixed lines; `children` the block content parsed from the de-quoted lines (so quotes nest). */
+/** Represents a blockquote — `>`-prefixed lines; `children` the block content parsed from the de-quoted lines (so quotes nest). */
 export declare interface BlockquoteNode {
     readonly element: 'blockquote';
-    /** The block content of the quote (the `>`-stripped lines, re-parsed as blocks). */
+    /** Holds the block content of the quote (the `>`-stripped lines, re-parsed as blocks). */
     readonly children: readonly BlockNode[];
 }
 
 /**
- * Merge adjacent text nodes into one - the inline scanner emits a text node per
+ * Merges adjacent text nodes into one — the inline scanner emits a text node per
  * unrecognized character, so coalescing keeps the AST clean and assertion-friendly.
  *
  * @param nodes - The inline nodes (possibly with adjacent text runs)
@@ -40,21 +40,21 @@ export declare interface BlockquoteNode {
 export declare function coalesceText(nodes: readonly InlineNode[], spans?: Map<MarkdownNode, MarkdownSpan>): readonly InlineNode[];
 
 /**
- * A fenced code block - ```` ```lang ````. `code` is the verbatim block content (no
+ * Represents a fenced code block — ```` ```lang ````. `code` is the verbatim block content (no
  * inner markdown; the closing fence and the trailing newline are stripped), `lang`
  * the info-string language tag (the first word after the opening fence), absent when
  * none was given.
  */
 export declare interface CodeBlockNode {
     readonly element: 'codeBlock';
-    /** The info-string language tag (first word after the opening fence), if any. */
+    /** Holds the info-string language tag (first word after the opening fence), if any. */
     readonly lang?: string;
-    /** The verbatim code content (no inner markdown; HTML-escaped at render). */
+    /** Holds the verbatim code content (no inner markdown; HTML-escaped at render). */
     readonly code: string;
 }
 
 /**
- * The shape of a {@link CodeBlockNode} - a fenced code block. `lang` is
+ * Describes the shape of a {@link CodeBlockNode} — a fenced code block. `lang` is
  * optional (absent when the opening fence carries no info-string).
  *
  * @example
@@ -67,25 +67,36 @@ export declare interface CodeBlockNode {
  * codeBlock.is({ element: 'codeBlock', code: 'x', lang: 'ts' })        // true
  * ```
  */
-export declare const codeBlockShape: ObjectShape<{
-    element: LiteralShape<readonly ["codeBlock"]>;
-    lang: OptionalShape<StringShape>;
-    code: StringShape;
+export declare const codeBlockShape: ObjectShape<    {
+element: LiteralShape<readonly ["codeBlock"]>;
+lang: OptionalShape<StringShape>;
+code: StringShape;
 }, false>;
 
 /**
- * An inline code span - `` `code` ``. `value` is the verbatim span text; no inner
+ * Represents the located extent of one inline code span — the value the inline phase's code
+ * scanner returns for a matched backtick run.
+ */
+export declare interface CodeSpanMatch {
+    /** Holds the span's literal text, with one padding space stripped from each end. */
+    readonly value: string;
+    /** Holds the index one past the span's closing backtick run, exclusive. */
+    readonly end: number;
+}
+
+/**
+ * Represents an inline code span — `` `code` ``. `value` is the verbatim span text; no inner
  * markdown is parsed (code is literal), and the renderer HTML-escapes it inside a
  * `<code>` element.
  */
 export declare interface CodeSpanNode {
     readonly element: 'codeSpan';
-    /** The verbatim code text (no inner markdown; HTML-escaped at render). */
+    /** Holds the verbatim code text (no inner markdown; HTML-escaped at render). */
     readonly value: string;
 }
 
 /**
- * The shape of a {@link CodeSpanNode} - an inline code span (`` `code` ``).
+ * Describes the shape of a {@link CodeSpanNode} — an inline code span (`` `code` ``).
  *
  * @example
  * ```ts
@@ -96,9 +107,9 @@ export declare interface CodeSpanNode {
  * codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
  * ```
  */
-export declare const codeSpanShape: ObjectShape<{
-    element: LiteralShape<readonly ["codeSpan"]>;
-    value: StringShape;
+export declare const codeSpanShape: ObjectShape<    {
+element: LiteralShape<readonly ["codeSpan"]>;
+value: StringShape;
 }, false>;
 
 /**
@@ -117,10 +128,7 @@ export declare const codeSpanShape: ObjectShape<{
  * collectList(splitLines('- item'), 0, 0) // { node: { element: 'list', ... }, next: 1 }
  * ```
  */
-export declare function collectList(lines: readonly MarkdownSource[], start: number, depth: number, spans?: Map<MarkdownNode, MarkdownSpan>, end?: number): {
-    readonly node: ListNode;
-    readonly next: number;
-};
+export declare function collectList(lines: readonly MarkdownSource[], start: number, depth: number, spans?: Map<MarkdownNode, MarkdownSpan>, end?: number): ListCollection;
 
 /**
  * Collects a GFM table starting at a header row, parsing the header, the
@@ -136,13 +144,10 @@ export declare function collectList(lines: readonly MarkdownSource[], start: num
  * collectTable(splitLines('| a |\n| - |'), 0) // { node: { element: 'table', ... }, next: 2 }
  * ```
  */
-export declare function collectTable(lines: readonly MarkdownSource[], start: number, spans?: Map<MarkdownNode, MarkdownSpan>): {
-    readonly node: TableNode;
-    readonly next: number;
-};
+export declare function collectTable(lines: readonly MarkdownSource[], start: number, spans?: Map<MarkdownNode, MarkdownSpan>): TableCollection;
 
 /**
- * The count of leading space / tab characters on `line` (a tab counts as one) - the
+ * Counts the leading space / tab characters on `line` (a tab counts as one) — the
  * indent that decides whether a list item's continuation belongs to the item.
  *
  * @param line - The line to measure
@@ -156,9 +161,9 @@ export declare function collectTable(lines: readonly MarkdownSource[], start: nu
 export declare function countIndent(line: string): number;
 
 /**
- * Compile the {@link codeBlockShape} into a {@link ContractInterface} for
- * {@link CodeBlockNode} - a guard, coercing parser, JSON Schema, and seeded
- * generator from one shape declaration (AGENTS §14).
+ * Compiles the {@link codeBlockShape} into a {@link ContractInterface} for
+ * {@link CodeBlockNode} — a guard, coercing parser, JSON Schema, and seeded
+ * generator from one shape declaration.
  *
  * @returns A `CodeBlockNode` contract bundling `schema` / `is` / `parse` / `generate`
  *
@@ -173,9 +178,9 @@ export declare function countIndent(line: string): number;
 export declare function createCodeBlockContract(): ContractInterface<CodeBlockNode>;
 
 /**
- * Compile the {@link codeSpanShape} into a {@link ContractInterface} for
- * {@link CodeSpanNode} - a guard, coercing parser, JSON Schema, and seeded
- * generator from one shape declaration (AGENTS §14).
+ * Compiles the {@link codeSpanShape} into a {@link ContractInterface} for
+ * {@link CodeSpanNode} — a guard, coercing parser, JSON Schema, and seeded
+ * generator from one shape declaration.
  *
  * @returns A `CodeSpanNode` contract bundling `schema` / `is` / `parse` / `generate`
  *
@@ -190,7 +195,7 @@ export declare function createCodeBlockContract(): ContractInterface<CodeBlockNo
 export declare function createCodeSpanContract(): ContractInterface<CodeSpanNode>;
 
 /**
- * Compile the {@link lineBreakShape} into a {@link ContractInterface} for
+ * Compiles the {@link lineBreakShape} into a {@link ContractInterface} for
  * {@link LineBreakNode}.
  *
  * @returns A `LineBreakNode` contract bundling `schema` / `is` / `parse` / `generate`
@@ -205,8 +210,8 @@ export declare function createCodeSpanContract(): ContractInterface<CodeSpanNode
 export declare function createLineBreakContract(): ContractInterface<LineBreakNode>;
 
 /**
- * Create a stateful markdown handle from a markdown string or an already-parsed
- * {@link MarkdownDocument} - a typed AST plus the query, rewrite, and fold operations
+ * Creates a stateful markdown handle from a markdown string or an already-parsed
+ * {@link MarkdownDocument} — a typed AST plus the query, rewrite, and fold operations
  * {@link MarkdownInterface} exposes.
  *
  * @remarks
@@ -214,9 +219,9 @@ export declare function createLineBreakContract(): ContractInterface<LineBreakNo
  * fenced code / blockquotes / thematic breaks) then an inline phase (emphasis /
  * inline code / links / images / hard breaks) to build a render-agnostic
  * {@link MarkdownDocument}. Given a
- * {@link MarkdownDocument}, adopts it AS-IS without re-validation - gate an untrusted
+ * {@link MarkdownDocument}, adopts it as-is without re-validation — gate an untrusted
  * value with `isMarkdownDocument` first. Pure + total parse (malformed markdown
- * degrades to text, never throws) and zero-dependency - a hand-written scanner, no
+ * degrades to text, never throws) and zero-dependency — a hand-written scanner, no
  * regex-only structural parse, linear-time (no ReDoS).
  *
  * @param input - A markdown string to parse, or an already-parsed {@link MarkdownDocument}
@@ -233,7 +238,7 @@ export declare function createLineBreakContract(): ContractInterface<LineBreakNo
 export declare function createMarkdown(input: string | MarkdownDocument): MarkdownInterface;
 
 /**
- * Create an HTML-to-markdown projection with absent fields defaulted from
+ * Builds an HTML-to-markdown projection with absent fields defaulted from
  * {@link EMPTY_PROJECTION} and the block/inline exclusivity invariant enforced.
  *
  * @remarks
@@ -255,9 +260,9 @@ export declare function createMarkdown(input: string | MarkdownDocument): Markdo
 export declare function createProjection(parts?: Partial<MarkdownProjection>): MarkdownProjection;
 
 /**
- * Compile the {@link textShape} into a {@link ContractInterface} for
- * {@link TextNode} - a guard, coercing parser, JSON Schema, and seeded
- * generator from one shape declaration (AGENTS §14).
+ * Compiles the {@link textShape} into a {@link ContractInterface} for
+ * {@link TextNode} — a guard, coercing parser, JSON Schema, and seeded
+ * generator from one shape declaration.
  *
  * @returns A `TextNode` contract bundling `schema` / `is` / `parse` / `generate`
  *
@@ -272,9 +277,9 @@ export declare function createProjection(parts?: Partial<MarkdownProjection>): M
 export declare function createTextContract(): ContractInterface<TextNode>;
 
 /**
- * Compile the {@link thematicBreakShape} into a {@link ContractInterface} for
- * {@link ThematicBreakNode} - a guard, coercing parser, JSON Schema, and
- * seeded generator from one shape declaration (AGENTS §14).
+ * Compiles the {@link thematicBreakShape} into a {@link ContractInterface} for
+ * {@link ThematicBreakNode} — a guard, coercing parser, JSON Schema, and
+ * seeded generator from one shape declaration.
  *
  * @returns A `ThematicBreakNode` contract bundling `schema` / `is` / `parse` / `generate`
  *
@@ -289,7 +294,7 @@ export declare function createTextContract(): ContractInterface<TextNode>;
 export declare function createThematicBreakContract(): ContractInterface<ThematicBreakNode>;
 
 /**
- * Derive the per-column {@link TableAlign} list from a GFM delimiter row - `:---`
+ * Derives the per-column {@link TableAlign} list from a GFM delimiter row — `:---`
  * left, `---:` right, `:---:` center, and `---` as the explicit no-alignment
  * marker represented by `null`.
  *
@@ -304,21 +309,47 @@ export declare function createThematicBreakContract(): ContractInterface<Themati
 export declare function delimiterToAlignments(delimiter: string): ReadonlyArray<TableAlign | null>;
 
 /**
- * Emphasized inline content - `*italic*` / `_italic_` (`strong: false`) or
+ * Represents the located content and syntax bounds of one emphasis run — the value the inline
+ * phase's emphasis locator returns for a matched marker run.
+ */
+export declare interface EmphasisBounds {
+    /** Holds `true` for a doubled marker (`**strong**`), `false` for a single one (`*em*`). */
+    readonly strong: boolean;
+    /** Holds the index of the run's first content character. */
+    readonly open: number;
+    /** Holds the index of the closing marker run's first character. */
+    readonly close: number;
+    /** Holds the index one past the closing marker run, exclusive. */
+    readonly end: number;
+}
+
+/**
+ * Represents emphasized inline content — `*italic*` / `_italic_` (`strong: false`) or
  * `**bold**` / `__bold__` (`strong: true`). `children` are the nested inline nodes,
  * so emphasis composes (a `**bold _and italic_**` is a strong node wrapping a text
  * node and an emphasis node).
  */
 export declare interface EmphasisNode {
     readonly element: 'emphasis';
-    /** `true` for strong (`**` / `__`, → `<strong>`); `false` for ordinary emphasis (`*` / `_`, → `<em>`). */
+    /** Holds `true` for strong (`**` / `__`, → `<strong>`); `false` for ordinary emphasis (`*` / `_`, → `<em>`). */
     readonly strong: boolean;
-    /** The emphasized inline content. */
+    /** Holds the emphasized inline content. */
     readonly children: readonly InlineNode[];
 }
 
 /**
- * The frozen empty HTML-to-markdown projection from which projection factories
+ * Represents the scanned result of one emphasis run — the node the inline phase's emphasis
+ * scanner built from {@link EmphasisBounds} and where the scan resumes.
+ */
+export declare interface EmphasisScan {
+    /** Holds the scanned emphasis run, its content already scanned into inline children. */
+    readonly node: EmphasisNode;
+    /** Holds the index one past the closing marker run, exclusive. */
+    readonly end: number;
+}
+
+/**
+ * Holds the frozen empty HTML-to-markdown projection from which projection factories
  * default every absent field.
  *
  * @example
@@ -330,7 +361,7 @@ export declare interface EmphasisNode {
 export declare const EMPTY_PROJECTION: MarkdownProjection;
 
 /**
- * Extract a fenced-code opening line (```` ``` ```` or `~~~`, optionally with an info
+ * Extracts a fenced-code opening line (```` ``` ```` or `~~~`, optionally with an info
  * string) into its `{ marker, lang }`, or `undefined` when `line` is not a fence
  * opener. `marker` is the exact fence run (the closer must match the same character +
  * at least the same length); `lang` is the first word of the info string.
@@ -343,10 +374,7 @@ export declare const EMPTY_PROJECTION: MarkdownProjection;
  * extractFence('```ts') // { marker: '```', lang: 'ts' }
  * ```
  */
-export declare function extractFence(line: string): {
-    readonly marker: string;
-    readonly lang: string | undefined;
-} | undefined;
+export declare function extractFence(line: string): FenceMatch | undefined;
 
 /**
  * Extracts an ATX heading line (`#` … `######` followed by text) into its level,
@@ -362,14 +390,10 @@ export declare function extractFence(line: string): {
  * extractHeading('## Title') // { level: 2, text: 'Title', offset: 3 }
  * ```
  */
-export declare function extractHeading(line: string): {
-    readonly level: number;
-    readonly text: string;
-    readonly offset: number;
-} | undefined;
+export declare function extractHeading(line: string): HeadingMatch | undefined;
 
 /**
- * Extract a list-item line (`-` / `*` / `+` bullet, or `1.` / `1)` ordinal, followed by
+ * Extracts a list-item line (`-` / `*` / `+` bullet, or `1.` / `1)` ordinal, followed by
  * a space) into its {@link ListItemMatch}, or `undefined` when `line` is not a list
  * item. `content` is the text after the marker; `marker` is the full marker-plus-space
  * width (for measuring a continuation's indent).
@@ -385,8 +409,19 @@ export declare function extractHeading(line: string): {
 export declare function extractListItem(line: string): ListItemMatch | undefined;
 
 /**
- * Concatenate the `value` / `code` content of every descendant text / code-span /
- * code-block node under `node`, including image alternative content, in walk order -
+ * Represents the parsed parts of a fenced-code opening line — the value the block phase's fence
+ * detector returns for a ```` ``` ```` or `~~~` opener.
+ */
+export declare interface FenceMatch {
+    /** Holds the exact fence run; a closer must repeat the same character at least as long. */
+    readonly marker: string;
+    /** Holds the first word of the info string, or `undefined` when the fence declares none. */
+    readonly lang: string | undefined;
+}
+
+/**
+ * Concatenates the `value` / `code` content of every descendant text / code-span /
+ * code-block node under `node`, including image alternative content, in walk order —
  * the plain-text projection of an AST (search indexing, word counts, a text-only
  * preview).
  *
@@ -409,16 +444,16 @@ export declare function extractListItem(line: string): ListItemMatch | undefined
 export declare function flattenText(node: MarkdownNode): string;
 
 /**
- * Fold a {@link MarkdownNode} into a `T` via a total catamorphism - children are
+ * Folds a {@link MarkdownNode} into a `T` through a total catamorphism — children are
  * folded first (post-order), then the node's own {@link MarkdownHandler} is invoked
  * with the already-folded children.
  *
  * @remarks
- * **Table contract.** A {@link TableNode} has no single `children` array - its cells
+ * **Table contract.** A {@link TableNode} has no single `children` array — its cells
  * live in `header` (one inline-node list per column) and `rows` (a list of such
- * rows). The `table` handler receives ONE folded `T` per inline node, flattened in
- * walk order across ALL cells - every header cell's inline nodes (column order), then
- * every body row's cells' inline nodes (row order, then column order) - and reads
+ * rows). The `table` handler receives one folded `T` per inline node, flattened in
+ * walk order across all cells — every header cell's inline nodes (column order), then
+ * every body row's cells' inline nodes (row order, then column order) — and reads
  * `node.header[c].length` / `node.rows[r][c].length` off the table node itself to
  * recover cell boundaries within the flat list.
  *
@@ -426,64 +461,77 @@ export declare function flattenText(node: MarkdownNode): string;
  * with an empty children list instead of recursing further.
  *
  * @param node - The AST node to fold
- * @param handlers - The total {@link MarkdownHandlers} table, one handler per element
+ * @param handlers - The total {@link MarkdownHandlerMap} table, one handler per element
  * @param depth - The starting recursion depth (pass `0` at the entry point)
  * @returns The folded `T`
  *
  * @example
  * ```ts
- * const countHandlers: MarkdownHandlers<number> = {
+ * const countHandlers: MarkdownHandlerMap<number> = {
  *   document: (_, children) => children.reduce((a, b) => a + b, 1),
  *   // ...one handler per element, each summing its folded children
  * }
  * foldNode(document, countHandlers, 0) // total node count
  * ```
  */
-export declare function foldNode<T>(node: MarkdownNode, handlers: MarkdownHandlers<T>, depth: number): T;
+export declare function foldNode<T>(node: MarkdownNode, handlers: MarkdownHandlerMap<T>, depth: number): T;
 
 /**
- * An ATX heading - `#` … `######`. `level` is 1–6 (the number of leading `#`),
+ * Represents the parsed parts of a single ATX heading line — the value the block phase's heading
+ * detector returns for a `#` … `######` line.
+ */
+export declare interface HeadingMatch {
+    /** Holds the heading's level, 1 to 6. */
+    readonly level: number;
+    /** Holds the heading's raw inline text, with an optional closing `#` run stripped. */
+    readonly text: string;
+    /** Holds the offset of {@link HeadingMatch.text} inside the original line. */
+    readonly offset: number;
+}
+
+/**
+ * Represents an ATX heading — `#` … `######`. `level` is 1–6 (the number of leading `#`),
  * `children` the inline content of the heading text.
  */
 export declare interface HeadingNode {
     readonly element: 'heading';
-    /** The heading level, 1 (`#`) through 6 (`######`). */
+    /** Holds the heading level, 1 (`#`) through 6 (`######`). */
     readonly level: number;
-    /** The inline content of the heading text. */
+    /** Holds the inline content of the heading text. */
     readonly children: readonly InlineNode[];
 }
 
 /**
- * Project an `@orkestrel/html` {@link HTMLNode} into a {@link MarkdownDocument} - the
+ * Projects an `@orkestrel/html` {@link HTMLNode} into a {@link MarkdownDocument} — the
  * HTML→markdown direction, and the inverse of {@link markdownToHTML}.
  *
  * @remarks
- * **Engine.** One total handler table - {@link projectHTMLNode} for the containers,
- * {@link projectHTMLLeaf} for the leaves - folded by `@orkestrel/html`'s own `foldNode`, so
+ * **Engine.** One total handler table — {@link projectHTMLNode} for the containers,
+ * {@link projectHTMLLeaf} for the leaves — folded by `@orkestrel/html`'s own `foldNode`, so
  * depth capping, cycle safety, and bottom-up ordering are inherited rather than
  * rebuilt. Total: hostile, cyclic, and pathologically deep input degrades instead of
  * throwing.
  *
  * **Composed depth.** Both packages cap recursion at 64, and html's cap is reached
- * first: a document nested past it projects to a chain bounded by THAT cap, with the
+ * first: a document nested past it projects to a chain bounded by that cap, with the
  * content below it truncated before markdown ever sees it. Since the projected chain
  * can be a level or two deeper than {@link MAX_DEPTH}, the serializer's own cap can
- * then truncate again - so the anchor law below is a law within the depth budget, and
+ * then truncate again — so the anchor law that follows is a law within the depth budget, and
  * beyond it only totality is promised.
  *
  * **Safety.** Every `href` and `src` is re-sanitized through
  * `sanitizeURL(value, SAFE_URL_SCHEMES)` whether or not the AST was ever sanitized,
  * because a hand-built one never was. A refused destination empties to `''` and the
- * link or image is KEPT - `[text]()` - since a bad URL is no reason to lose the words
+ * link or image is kept — `[text]()` — because a bad URL is no reason to lose the words
  * around it. An `UNSAFE_ELEMENTS` subtree contributes nothing at all, text included, so
  * a `script` body can never resurface as prose.
  *
  * **The anchor law.** HTML→markdown is lossy, so the fixpoint that matters is the
- * PROJECTED AST, not the input bytes:
+ * projected AST, not the input bytes:
  * `parseDocument(renderMarkdown(htmlToMarkdown(x)))` deep-equals `htmlToMarkdown(x)`.
  * The projection therefore emits canonical markdown shapes rather than literal
- * translations - whitespace collapsed, edges trimmed, a blank paragraph dropped, a hard
- * break only where a line can end - because a shape markdown cannot write back is a
+ * translations — whitespace collapsed, edges trimmed, a blank paragraph dropped, a hard
+ * break only where a line can end — because a shape markdown cannot write back is a
  * shape this projection has no business producing.
  *
  * @param node - The HTML document or bare node to project
@@ -500,27 +548,27 @@ export declare interface HeadingNode {
 export declare function htmlToMarkdown(node: HTMLNode): MarkdownDocument;
 
 /**
- * An inline image - `![alt](src)`. `children` are the inline nodes of the
+ * Represents an inline image — `![alt](src)`. `children` are the inline nodes of the
  * alternative content and `src` is the image destination.
  */
 export declare interface ImageNode {
     readonly element: 'image';
-    /** The image destination. */
+    /** Holds the image destination. */
     readonly src: string;
-    /** The inline alternative content. */
+    /** Holds the inline alternative content. */
     readonly children: readonly InlineNode[];
 }
 
-/** A node that can appear inside inline content (a heading / paragraph / cell / list item / link text). */
+/** Represents a node that can appear inside inline content (a heading / paragraph / cell / list item / link text). */
 export declare type InlineNode = TextNode | EmphasisNode | CodeSpanNode | LineBreakNode | LinkNode | ImageNode;
 
 /**
- * Whether `line` is blank - empty, or containing only whitespace - the markdown
+ * Checks whether `line` is blank — empty, or containing only whitespace — the markdown
  * definition of a blank line that block parsing uses to separate paragraphs, skip
  * gaps, and end list continuations.
  *
  * @param line - The candidate line
- * @returns `true` when the line is blank
+ * @returns True if the line is blank; false otherwise
  *
  * @example
  * ```ts
@@ -530,19 +578,19 @@ export declare type InlineNode = TextNode | EmphasisNode | CodeSpanNode | LineBr
 export declare function isBlankLine(line: string): boolean;
 
 /**
- * Determine whether an arbitrary value is a valid {@link BlockNode} - a
+ * Determines whether an arbitrary value is a valid {@link BlockNode} — a
  * heading, paragraph, list, table, code block, blockquote, or thematic break,
  * recursively validated.
  *
  * @remarks
- * Total: never throws, even on cyclic or pathologically deep input - every
+ * Total: never throws, even on cyclic or pathologically deep input — every
  * combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
- * throw-contained per the `@orkestrel/contract` guard contract (AGENTS §14).
+ * throw-contained per the `@orkestrel/contract` guard contract.
  * A list item's shape is inlined here (and in {@link isMarkdownNode}) rather
- * than named separately - it is used at exactly these two sites.
+ * than named separately — it is used at exactly these two sites.
  *
  * @param value - The value to test
- * @returns `true` when `value` is a well-formed {@link BlockNode}
+ * @returns True if `value` is a well-formed {@link BlockNode}; false otherwise
  *
  * @example
  * ```ts
@@ -555,7 +603,10 @@ export declare function isBlankLine(line: string): boolean;
 export declare const isBlockNode: Guard<BlockNode>;
 
 /**
- * Determine whether a node is a blockquote block.
+ * Determines whether a node is a blockquote block.
+ *
+ * @param node - The AST node to test
+ * @returns True if the node is a {@link BlockquoteNode}; false otherwise
  *
  * @example
  * ```ts
@@ -565,7 +616,10 @@ export declare const isBlockNode: Guard<BlockNode>;
 export declare function isBlockquoteNode(node: MarkdownNode): node is BlockquoteNode;
 
 /**
- * Determine whether a node is a fenced code block.
+ * Determines whether a node is a fenced code block.
+ *
+ * @param node - The AST node to test
+ * @returns True if the node is a {@link CodeBlockNode}; false otherwise
  *
  * @example
  * ```ts
@@ -575,12 +629,15 @@ export declare function isBlockquoteNode(node: MarkdownNode): node is Blockquote
 export declare function isCodeBlockNode(node: MarkdownNode): node is CodeBlockNode;
 
 /**
- * Determine whether a node is an inline code span.
+ * Determines whether a node is an inline code span.
  *
  * @remarks
- * Narrows to {@link CodeSpanNode} - the node whose `element` discriminant is
+ * Narrows to {@link CodeSpanNode} — the node whose `element` discriminant is
  * `'codeSpan'`.
  *
+ * @param node - The AST node to test
+ * @returns True if the node is a {@link CodeSpanNode}; false otherwise
+ *
  * @example
  * ```ts
  * isCodeSpanNode({ element: 'codeSpan', value: 'x' }) // true
@@ -589,7 +646,10 @@ export declare function isCodeBlockNode(node: MarkdownNode): node is CodeBlockNo
 export declare function isCodeSpanNode(node: MarkdownNode): node is CodeSpanNode;
 
 /**
- * Determine whether a node is an emphasis run (`*em*` / `**strong**`).
+ * Determines whether a node is an emphasis run (`*em*` / `**strong**`).
+ *
+ * @param node - The AST node to test
+ * @returns True if the node is an {@link EmphasisNode}; false otherwise
  *
  * @example
  * ```ts
@@ -599,11 +659,11 @@ export declare function isCodeSpanNode(node: MarkdownNode): node is CodeSpanNode
 export declare function isEmphasisNode(node: MarkdownNode): node is EmphasisNode;
 
 /**
- * Whether `character` is escapable by a leading backslash - the ASCII punctuation
+ * Checks whether `character` is escapable by a leading backslash — the ASCII punctuation
  * markdown gives meaning to (so `\*` becomes `*` but `\.` stays `\.`).
  *
  * @param character - The single character after a backslash
- * @returns `true` when a backslash before it is an escape
+ * @returns True if a backslash before it is an escape; false otherwise
  *
  * @example
  * ```ts
@@ -614,12 +674,12 @@ export declare function isEmphasisNode(node: MarkdownNode): node is EmphasisNode
 export declare function isEscapable(character: string): boolean;
 
 /**
- * Whether `line` closes a fence opened by `marker` - the same fence character, a run
+ * Checks whether `line` closes a fence opened by `marker` — the same fence character, a run
  * at least as long, and nothing else but surrounding whitespace.
  *
  * @param line - The candidate closing line
  * @param marker - The opening fence's marker run (from {@link extractFence})
- * @returns `true` when `line` closes the fence
+ * @returns True if `line` closes the fence; false otherwise
  *
  * @example
  * ```ts
@@ -629,11 +689,11 @@ export declare function isEscapable(character: string): boolean;
 export declare function isFenceClose(line: string, marker: string): boolean;
 
 /**
- * Whether `character` is a regex-`\s`-equivalent whitespace character - the
+ * Checks whether `character` is a regex-`\s`-equivalent whitespace character — the
  * character class {@link isFenceClose}'s scan treats as surrounding padding.
  *
  * @param character - The single character to test, or `undefined` past the end of a line
- * @returns `true` when it is whitespace
+ * @returns True if it is whitespace; false otherwise
  *
  * @example
  * ```ts
@@ -643,11 +703,39 @@ export declare function isFenceClose(line: string, marker: string): boolean;
  */
 export declare function isFenceWhitespace(character: string | undefined): boolean;
 
-/** Determine whether a node is a heading block. */
+/**
+ * Checks whether `character` is whitespace under the emphasis flanking rule — a space, a
+ * tab, or a newline.
+ *
+ * @param character - The character to test
+ * @returns True if the flanking rule counts it as whitespace; false otherwise
+ *
+ * @example
+ * ```ts
+ * isFlankingWhitespace(' ') // true
+ * isFlankingWhitespace('a') // false
+ * ```
+ */
+export declare function isFlankingWhitespace(character: string): boolean;
+
+/**
+ * Determines whether a node is a heading block.
+ *
+ * @param node - The AST node to test
+ * @returns True if the node is a {@link HeadingNode}; false otherwise
+ *
+ * @example
+ * ```ts
+ * isHeadingNode({ element: 'heading', level: 1, children: [] }) // true
+ * ```
+ */
 export declare function isHeadingNode(node: MarkdownNode): node is HeadingNode;
 
 /**
- * Determine whether a node is an image.
+ * Determines whether a node is an image.
+ *
+ * @param node - The AST node to test
+ * @returns True if the node is an {@link ImageNode}; false otherwise
  *
  * @example
  * ```ts
@@ -657,16 +745,16 @@ export declare function isHeadingNode(node: MarkdownNode): node is HeadingNode;
 export declare function isImageNode(node: MarkdownNode): node is ImageNode;
 
 /**
- * Determine whether an arbitrary value is a valid {@link InlineNode} - a text
+ * Determines whether an arbitrary value is a valid {@link InlineNode} — a text
  * run, emphasis, code span, hard break, link, or image, recursively validated.
  *
  * @remarks
- * Total: never throws, even on cyclic or pathologically deep input - every
+ * Total: never throws, even on cyclic or pathologically deep input — every
  * combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
- * throw-contained per the `@orkestrel/contract` guard contract (AGENTS §14).
+ * throw-contained per the `@orkestrel/contract` guard contract.
  *
  * @param value - The value to test
- * @returns `true` when `value` is a well-formed {@link InlineNode}
+ * @returns True if `value` is a well-formed {@link InlineNode}; false otherwise
  *
  * @example
  * ```ts
@@ -679,7 +767,10 @@ export declare function isImageNode(node: MarkdownNode): node is ImageNode;
 export declare const isInlineNode: Guard<InlineNode>;
 
 /**
- * Determine whether a node is a GFM hard line break.
+ * Determines whether a node is a GFM hard line break.
+ *
+ * @param node - The AST node to test
+ * @returns True if the node is a {@link LineBreakNode}; false otherwise
  *
  * @example
  * ```ts
@@ -688,11 +779,24 @@ export declare const isInlineNode: Guard<InlineNode>;
  */
 export declare function isLineBreakNode(node: MarkdownNode): node is LineBreakNode;
 
-/** Determine whether a node is a link. */
+/**
+ * Determines whether a node is a link.
+ *
+ * @param node - The AST node to test
+ * @returns True if the node is a {@link LinkNode}; false otherwise
+ *
+ * @example
+ * ```ts
+ * isLinkNode({ element: 'link', href: 'https://example.dev', children: [] }) // true
+ * ```
+ */
 export declare function isLinkNode(node: MarkdownNode): node is LinkNode;
 
 /**
- * Determine whether a node is a list block.
+ * Determines whether a node is a list block.
+ *
+ * @param node - The AST node to test
+ * @returns True if the node is a {@link ListNode}; false otherwise
  *
  * @example
  * ```ts
@@ -702,17 +806,17 @@ export declare function isLinkNode(node: MarkdownNode): node is LinkNode;
 export declare function isListNode(node: MarkdownNode): node is ListNode;
 
 /**
- * Determine whether an arbitrary value is a valid {@link MarkdownDocument} -
+ * Determines whether an arbitrary value is a valid {@link MarkdownDocument} —
  * the parsed-AST root {@link parseDocument} returns, recursively
  * validated.
  *
  * @remarks
- * Total: never throws, even on cyclic or pathologically deep input - every
+ * Total: never throws, even on cyclic or pathologically deep input — every
  * combinator involved (`recordOf`, `arrayOf`) is throw-contained per the
- * `@orkestrel/contract` guard contract (AGENTS §14).
+ * `@orkestrel/contract` guard contract.
  *
  * @param value - The value to test
- * @returns `true` when `value` is a well-formed {@link MarkdownDocument}
+ * @returns True if `value` is a well-formed {@link MarkdownDocument}; false otherwise
  *
  * @example
  * ```ts
@@ -725,19 +829,19 @@ export declare function isListNode(node: MarkdownNode): node is ListNode;
 export declare const isMarkdownDocument: Guard<MarkdownDocument>;
 
 /**
- * Determine whether an arbitrary value is a valid {@link MarkdownNode} - the
+ * Determines whether an arbitrary value is a valid {@link MarkdownNode} — the
  * {@link MarkdownDocument} root, a {@link BlockNode}, a {@link ListItemNode}, or
  * an {@link InlineNode}, recursively validated.
  *
  * @remarks
- * Total: never throws, even on cyclic or pathologically deep input - every
+ * Total: never throws, even on cyclic or pathologically deep input — every
  * combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
- * throw-contained per the `@orkestrel/contract` guard contract (AGENTS §14).
+ * throw-contained per the `@orkestrel/contract` guard contract.
  * A list item's shape is inlined here (and in {@link isBlockNode}) rather than
- * named separately - it is used at exactly these two sites.
+ * named separately — it is used at exactly these two sites.
  *
  * @param value - The value to test
- * @returns `true` when `value` is a well-formed {@link MarkdownNode}
+ * @returns True if `value` is a well-formed {@link MarkdownNode}; false otherwise
  *
  * @example
  * ```ts
@@ -750,7 +854,10 @@ export declare const isMarkdownDocument: Guard<MarkdownDocument>;
 export declare const isMarkdownNode: Guard<MarkdownNode>;
 
 /**
- * Determine whether a node is a paragraph block.
+ * Determines whether a node is a paragraph block.
+ *
+ * @param node - The AST node to test
+ * @returns True if the node is a {@link ParagraphNode}; false otherwise
  *
  * @example
  * ```ts
@@ -760,11 +867,11 @@ export declare const isMarkdownNode: Guard<MarkdownNode>;
 export declare function isParagraphNode(node: MarkdownNode): node is ParagraphNode;
 
 /**
- * Whether `line` is a blockquote line (`>` optionally indented up to three spaces) -
+ * Checks whether `line` is a blockquote line (`>` optionally indented up to three spaces) —
  * its content is de-quoted by {@link stripQuote}.
  *
  * @param line - The candidate line
- * @returns `true` when the line begins a blockquote
+ * @returns True if the line begins a blockquote; false otherwise
  *
  * @example
  * ```ts
@@ -773,17 +880,27 @@ export declare function isParagraphNode(node: MarkdownNode): node is ParagraphNo
  */
 export declare function isQuote(line: string): boolean;
 
-/** Determine whether a node is a GFM table block. */
+/**
+ * Determines whether a node is a GFM table block.
+ *
+ * @param node - The AST node to test
+ * @returns True if the node is a {@link TableNode}; false otherwise
+ *
+ * @example
+ * ```ts
+ * isTableNode({ element: 'table', header: [], rows: [], align: [] }) // true
+ * ```
+ */
 export declare function isTableNode(node: MarkdownNode): node is TableNode;
 
 /**
- * Whether the pair (`header`, `delimiter`) opens a GFM table - `delimiter` is a row of
+ * Checks whether the pair (`header`, `delimiter`) opens a GFM table — `delimiter` is a row of
  * `|`-separated cells each matching `:?-+:?`, the GFM rule that a table requires a
- * header row IMMEDIATELY followed by a delimiter row.
+ * header row immediately followed by a delimiter row.
  *
  * @param header - The candidate header line
  * @param delimiter - The line after it (the candidate delimiter)
- * @returns `true` when the two lines open a table
+ * @returns True if the two lines open a table; false otherwise
  *
  * @example
  * ```ts
@@ -793,7 +910,10 @@ export declare function isTableNode(node: MarkdownNode): node is TableNode;
 export declare function isTableStart(header: string, delimiter: string | undefined): boolean;
 
 /**
- * Determine whether a node is a plain text run.
+ * Determines whether a node is a plain text run.
+ *
+ * @param node - The AST node to test
+ * @returns True if the node is a {@link TextNode}; false otherwise
  *
  * @example
  * ```ts
@@ -803,12 +923,12 @@ export declare function isTableStart(header: string, delimiter: string | undefin
 export declare function isTextNode(node: MarkdownNode): node is TextNode;
 
 /**
- * Whether `line` is a thematic break (horizontal rule) - three or more of the SAME
+ * Checks whether `line` is a thematic break (horizontal rule) — three or more of the same
  * marker `-`, `*`, or `_` (optionally space-separated) and nothing else (`---`,
  * `***`, `___`, `- - -`).
  *
  * @param line - The candidate line
- * @returns `true` when the line is a thematic break
+ * @returns True if the line is a thematic break; false otherwise
  *
  * @example
  * ```ts
@@ -818,7 +938,10 @@ export declare function isTextNode(node: MarkdownNode): node is TextNode;
 export declare function isThematicBreak(line: string): boolean;
 
 /**
- * Determine whether a node is a thematic break (horizontal rule) block.
+ * Determines whether a node is a thematic break (horizontal rule) block.
+ *
+ * @param node - The AST node to test
+ * @returns True if the node is a {@link ThematicBreakNode}; false otherwise
  *
  * @example
  * ```ts
@@ -827,21 +950,6 @@ export declare function isThematicBreak(line: string): boolean;
  */
 export declare function isThematicBreakNode(node: MarkdownNode): node is ThematicBreakNode;
 
-/**
- * Whether `character` is an inline whitespace character (space / tab / newline) - the
- * emphasis flanking rule's space test.
- *
- * @param character - The character to test
- * @returns `true` when it is inline whitespace
- *
- * @example
- * ```ts
- * isWhitespace(' ') // true
- * isWhitespace('a') // false
- * ```
- */
-export declare function isWhitespace(character: string): boolean;
-
 /**
  * Joins offset-bearing markdown sources while mapping a separator to the original
  * region between adjacent mapped sources.
@@ -858,13 +966,16 @@ export declare function isWhitespace(character: string): boolean;
  */
 export declare function joinSources(sources: readonly MarkdownSource[], separator: string): MarkdownSource;
 
-/** A GFM hard line break - two or more trailing spaces before a newline. */
+/**
+ * Represents a GFM hard line break — two or more trailing spaces before a newline in
+ * markdown source, a `br` element in HTML.
+ */
 export declare interface LineBreakNode {
     readonly element: 'break';
 }
 
 /**
- * The shape of a {@link LineBreakNode} - a GFM hard line-break leaf.
+ * Describes the shape of a {@link LineBreakNode} — a GFM hard line-break leaf.
  *
  * @example
  * ```ts
@@ -875,42 +986,75 @@ export declare interface LineBreakNode {
  * lineBreak.is({ element: 'break' }) // true
  * ```
  */
-export declare const lineBreakShape: ObjectShape<{
-    element: LiteralShape<readonly ["break"]>;
+export declare const lineBreakShape: ObjectShape<    {
+element: LiteralShape<readonly ["break"]>;
 }, false>;
 
 /**
- * An inline link - `[text](href)`. `children` are the inline nodes of the link text.
+ * Represents the located syntax bounds of one `[text](href)` link — the value the inline phase's
+ * link locator returns for a balanced label followed by a destination.
+ */
+export declare interface LinkBounds {
+    /** Holds the index of the label's closing `]`. */
+    readonly close: number;
+    /** Holds the index one past the destination's closing `)`, exclusive. */
+    readonly end: number;
+}
+
+/**
+ * Represents an inline link — `[text](href)`. `children` are the inline nodes of the link text.
  * At render, html's floor removes a refused `href` attribute and the link keeps its
  * text; {@link htmlToMarkdown} instead stores a refused destination as `''`.
  */
 export declare interface LinkNode {
     readonly element: 'link';
-    /** The link destination (sanitized + attribute-escaped at render). */
+    /** Holds the link destination (sanitized + attribute-escaped at render). */
     readonly href: string;
-    /** The inline content of the link text. */
+    /** Holds the inline content of the link text. */
     readonly children: readonly InlineNode[];
 }
 
 /**
- * The parsed parts of a single list-item line - the value the block phase's
+ * Represents the scanned result of one `[text](href)` link — the node the inline phase's link
+ * scanner built from {@link LinkBounds} and where the scan resumes.
+ */
+export declare interface LinkScan {
+    /** Holds the scanned link, its text already scanned into inline children. */
+    readonly node: LinkNode;
+    /** Holds the index one past the destination's closing `)`, exclusive. */
+    readonly end: number;
+}
+
+/**
+ * Represents the result of collecting one list — the node the construct scanner built and where
+ * the block phase resumes.
+ */
+export declare interface ListCollection {
+    /** Holds the collected list. */
+    readonly node: ListNode;
+    /** Holds the index of the first line after the list. */
+    readonly next: number;
+}
+
+/**
+ * Represents the parsed parts of a single list-item line — the value the block phase's
  * list detector returns for a `-` / `*` / `+` bullet or a `1.` / `1)` ordinal line.
  */
 export declare interface ListItemMatch {
-    /** `true` for an ordered (`1.` / `1)`) item, `false` for a bullet (`-` / `*` / `+`). */
+    /** Holds `true` for an ordered (`1.` / `1)`) item, `false` for a bullet (`-` / `*` / `+`). */
     readonly ordered: boolean;
-    /** The ordinal of an ordered item (its number); `1` for a bullet. */
+    /** Holds the ordinal of an ordered item (its number); `1` for a bullet. */
     readonly start: number;
-    /** The item's text after the marker. */
+    /** Holds the item's text after the marker. */
     readonly content: string;
-    /** The leading-space indent of the marker. */
+    /** Holds the leading-space indent of the marker. */
     readonly indent: number;
-    /** The full marker width (indent + bullet/ordinal + the following space) - the continuation indent. */
+    /** Holds the full marker width (indent + bullet/ordinal + the following space) — the continuation indent. */
     readonly marker: number;
 }
 
 /**
- * The shape of {@link ListItemMatch} - the parsed parts of a single list-item
+ * Describes the shape of {@link ListItemMatch} — the parsed parts of a single list-item
  * line the block phase's list detector returns. Fully non-recursive (no
  * nested node fields), so every field shapes directly.
  *
@@ -923,39 +1067,39 @@ export declare interface ListItemMatch {
  * listItemParts.is({ ordered: false, start: 1, content: 'hi', indent: 0, marker: 2 }) // true
  * ```
  */
-export declare const listItemMatchShape: ObjectShape<{
-    ordered: BooleanShape;
-    start: NumberShape;
-    content: StringShape;
-    indent: NumberShape;
-    marker: NumberShape;
+export declare const listItemMatchShape: ObjectShape<    {
+ordered: BooleanShape;
+start: NumberShape;
+content: StringShape;
+indent: NumberShape;
+marker: NumberShape;
 }, false>;
 
-/** One item of a {@link ListNode} - `children` the block content of the item (typically one paragraph, plus any nested list). */
+/** Represents one item of a {@link ListNode} — `children` the block content of the item (typically one paragraph, plus any nested list). */
 export declare interface ListItemNode {
     readonly element: 'listItem';
-    /** The block content of the list item (its text as a paragraph, plus any nested list). */
+    /** Holds the block content of the list item (its text as a paragraph, plus any nested list). */
     readonly children: readonly BlockNode[];
 }
 
 /**
- * A list - bulleted (`-` / `*` / `+`, `ordered: false`) or numbered (`1.` / `1)`,
+ * Represents a list — bulleted (`-` / `*` / `+`, `ordered: false`) or numbered (`1.` / `1)`,
  * `ordered: true`). `start` is the first ordinal of an ordered list (usually `1`).
  * Nesting is expressed by a {@link ListNode} appearing in a {@link ListItemNode}'s
  * `children`.
  */
 export declare interface ListNode {
     readonly element: 'list';
-    /** `true` for an ordered (numbered) list (→ `<ol>`); `false` for a bulleted list (→ `<ul>`). */
+    /** Holds `true` for an ordered (numbered) list (→ `<ol>`); `false` for a bulleted list (→ `<ul>`). */
     readonly ordered: boolean;
-    /** The starting ordinal of an ordered list (the first item's number); `1` for a bulleted list. */
+    /** Holds the starting ordinal of an ordered list (the first item's number); `1` for a bulleted list. */
     readonly start: number;
-    /** The list's items, in order. */
+    /** Holds the list's items, in order. */
     readonly items: readonly ListItemNode[];
 }
 
 /**
- * Locates an emphasis run at `start` (`*` / `_`, doubled for strong) - finds the nearest
+ * Locates an emphasis run at `start` (`*` / `_`, doubled for strong) — finds the nearest
  * matching closing run of the same marker + width while skipping complete nested
  * runs from the other marker family, and requires non-space immediately inside both
  * delimiters (the CommonMark flanking simplification that blocks `* x *`). Returns
@@ -972,15 +1116,10 @@ export declare interface ListNode {
  * locateEmphasis('*em*', 0, 4) // { strong: false, open: 1, close: 3, end: 4 }
  * ```
  */
-export declare function locateEmphasis(source: string, start: number, to: number): {
-    readonly strong: boolean;
-    readonly open: number;
-    readonly close: number;
-    readonly end: number;
-} | undefined;
+export declare function locateEmphasis(source: string, start: number, to: number): EmphasisBounds | undefined;
 
 /**
- * Locates a link `[text](href)` at `start` - the text runs to a BALANCED `]`, then `(`
+ * Locates a link `[text](href)` at `start` — the text runs to a balanced `]`, then `(`
  * must immediately follow and the destination runs to the matching `)` (both respect
  * nested delimiters + escapes). Returns the label close and syntax end, or `undefined` when the shape
  * does not hold (it then degrades to a literal `[`).
@@ -995,26 +1134,23 @@ export declare function locateEmphasis(source: string, start: number, to: number
  * locateLink('[text](url)', 0, 11) // { close: 5, end: 11 }
  * ```
  */
-export declare function locateLink(source: string, start: number, to: number): {
-    readonly close: number;
-    readonly end: number;
-} | undefined;
+export declare function locateLink(source: string, start: number, to: number): LinkBounds | undefined;
 
 /**
- * A stateful, parsed markdown document - wraps a typed {@link MarkdownDocument} AST
+ * Wraps a typed {@link MarkdownDocument} AST as a stateful, parsed markdown document
  * with the query (`find` / `filter` / `reduce` / iteration), rewrite (`map`), fold, and
  * streaming operations {@link MarkdownInterface} declares.
  *
  * @remarks
  * - **Construction.** Given a `string`, the constructor runs {@link parseProvenance} (the
- *   block phase then the inline phase) once, keeping the AST and a COPY of the span map
- *   that parse recorded. Given a {@link MarkdownDocument}, the document is adopted AS-IS
- *   and is NOT re-validated - gate an untrusted value with `isMarkdownDocument` first.
- * - **Provenance.** {@link span} reads the region of the ORIGINAL constructor string a
+ *   block phase then the inline phase) once, keeping the AST and a copy of the span map
+ *   that parse recorded. Given a {@link MarkdownDocument}, the document is adopted as-is
+ *   and is not re-validated — gate an untrusted value with `isMarkdownDocument` first.
+ * - **Provenance.** {@link span} reads the region of the original constructor string a
  *   node was produced from, and it is handle-relative: a string-constructed handle exposes
  *   the regions of the nodes it parsed, an adopted document exposes none, and a node from
  *   another handle reports `undefined` here whatever that handle reports. Each call
- *   returns a fresh value. A node reports the region THIS handle holds for its identity,
+ *   returns a fresh value. A node reports the region this handle holds for its identity,
  *   else the region of the direct input a rewrite named for it, else `undefined`: a text
  *   run the parse joined from adjacent scanner output reports the region enclosing its
  *   parts, and only a rewrite output that holds no region of its own and was assembled
@@ -1022,29 +1158,28 @@ export declare function locateLink(source: string, start: number, to: number): {
  *   {@link map} carries provenance across the rewrite: an unchanged node keeps its
  *   region, a one-source replacement takes the region of the node it replaced, and a
  *   rebuilt parent takes its original's.
- * - **Immutable.** {@link map} never mutates the stored AST - it returns a NEW `Markdown`
+ * - **Immutable.** {@link map} never mutates the stored AST — it returns a new `Markdown`
  *   instance; the document root invariant (`element: 'document'`) always holds. An
  *   identity rewrite still returns a new handle, over the same document tree.
  * - **Traversal order.** {@link walk} and the `find` / `filter` / `reduce` queries built
- *   on it walk the AST depth-first, pre-order, root-inclusive (via {@link walkNodes});
- *   `stream` is shallow - only the document's direct block children.
+ *   on it walk the AST depth-first, pre-order, root-inclusive (through {@link walkNodes});
+ *   `stream` is shallow — only the document's direct block children.
  *
- * @example
+ * @example Construct from a string and narrow with a guard
  * ```ts
- * import { Markdown, isHeadingNode, renderMarkdown } from '@src/core'
+ * import { Markdown, isHeadingNode } from '@orkestrel/markdown'
  *
  * const markdown = new Markdown('# Title\n\nA **bold** [link](https://x.dev).')
- * const heading = markdown.find(isHeadingNode) // the HeadingNode, or undefined
- * const shouted = markdown.map((node) =>
- *   node.element === 'text' ? { element: 'text', value: node.value.toUpperCase() } : node,
- * )
- * renderMarkdown(shouted.document) // '# TITLE\n\nA **BOLD** [LINK](https://x.dev).'
+ * markdown.document.children[0] // { element: 'heading', level: 1, children: [...] }
+ *
+ * const heading = markdown.find(isHeadingNode) // HeadingNode | undefined, narrowed
+ * if (heading !== undefined) heading.level // number — narrowed to HeadingNode
  * ```
  */
 export declare class Markdown implements MarkdownInterface {
     #private;
     constructor(input: string | MarkdownDocument);
-    /** The stored {@link MarkdownDocument} AST root. */
+    /** Holds the stored {@link MarkdownDocument} AST root. */
     get document(): MarkdownDocument;
     /**
      * Reads the region of the original markdown string a node of this handle's tree was
@@ -1065,7 +1200,7 @@ export declare class Markdown implements MarkdownInterface {
      */
     span(node: MarkdownNode): MarkdownSpan | undefined;
     /**
-     * THE deep traversal - a lazy, depth-first, pre-order, root-inclusive generator
+     * Returns the deep traversal — a lazy, depth-first, pre-order, root-inclusive generator
      * over every {@link MarkdownNode} in the document. `find` / `filter` / `reduce`
      * all iterate this single traversal.
      *
@@ -1098,11 +1233,11 @@ export declare class Markdown implements MarkdownInterface {
     map(rewrite: MarkdownRewriteHandler): MarkdownInterface;
     /** Folds the AST depth-first, pre-order into an accumulator. */
     reduce<T>(callback: (accumulator: T, node: MarkdownNode) => T, initial: T): T;
-    /** Runs a total catamorphism over the document using a {@link MarkdownHandlers} table. */
-    fold<T>(handlers: MarkdownHandlers<T>): T;
+    /** Runs a total catamorphism over the document using a {@link MarkdownHandlerMap} table. */
+    fold<T>(handlers: MarkdownHandlerMap<T>): T;
     /**
-     * A web-standard {@link ReadableStream} over the document's top-level block nodes
-     * (shallow, source order) - a fresh, pull-based source per call: one block is
+     * Returns a web-standard {@link ReadableStream} over the document's top-level block nodes
+     * (shallow, source order) — a fresh, pull-based source per call: one block is
      * enqueued per `pull`, so a slow reader's backpressure is respected. Cancellable,
      * async-iterable wherever the platform supports it (Node, Deno), and pipeable
      * through any {@link TransformStream} / {@link WritableStream}.
@@ -1116,7 +1251,7 @@ export declare class Markdown implements MarkdownInterface {
      * }
      *
      * // Node / Deno / Firefox support async iteration of ReadableStream natively;
-     * // other environments should use the reader loop above instead.
+     * // other environments use the reader loop shown earlier.
      * for await (const block of markdown.stream()) {
      *   console.log(block)
      * }
@@ -1125,28 +1260,35 @@ export declare class Markdown implements MarkdownInterface {
     stream(): ReadableStream<BlockNode>;
 }
 
-/** One projected table cell - the inline content and alignment of a `th` / `td`. */
+/**
+ * Represents one projected table cell — the inline content and alignment of a `th` / `td`.
+ *
+ * @remarks
+ * {@link htmlToMarkdown} derives a projected table's header row from the source HTML
+ * structure rather than from any flag a cell carries: the header is the first
+ * `th`-bearing row, and every row after it becomes a body row.
+ */
 export declare interface MarkdownCell {
-    /** The alignment the cell's `align` attribute declared; `undefined` when it declared none. */
+    /** Holds the alignment the cell's `align` attribute declared; `undefined` when it declared none. */
     readonly align: TableAlign | undefined;
-    /** The cell's inline content - a table cell is inline-only, so block content flattens to text. */
+    /** Holds the cell's inline content — a table cell is inline-only, so block content flattens to text. */
     readonly inlines: readonly InlineNode[];
 }
 
 /**
- * Pairs a rewritten value with the input node each rewritten node was produced from -
+ * Pairs a rewritten value with the input node each rewritten node was produced from —
  * what `rewriteDocument` returns, so provenance survives a rewrite instead of ending at
  * it. `T` is the rewritten value: the document for a whole-document rewrite.
  *
  * @remarks
- * `derivations` is keyed by the nodes of the OUTPUT, and each entry names the DIRECT
+ * `derivations` is keyed by the nodes of the output, and each entry names the direct
  * input the rewrite drew that output from. {@link MarkdownInterface.map} resolves each
  * output node against the source handle's own spans in a fixed order, and follows no
  * second derivation edge:
  *
- * - the output identity's OWN span in the source handle wins, whatever the map says,
- *   so an identity the rewrite reused - one node returned for several inputs, or a
- *   node the handler moved elsewhere in the tree - keeps the region it already had;
+ * - the output identity's own span in the source handle wins, whatever the map says,
+ *   so an identity the rewrite reused — one node returned for several inputs, or a
+ *   node the handler moved elsewhere in the tree — keeps the region it already had;
  * - otherwise the span of the direct input the entry names, where that input has one;
  * - otherwise none. Where the output identity holds no region of its own, a node mapped
  *   to `undefined`, a node whose direct input has no span, and a node with no entry at
@@ -1163,39 +1305,39 @@ derivations: ReadonlyMap<MarkdownNode, MarkdownNode | undefined>
 ];
 
 /**
- * The root of a parsed markdown AST - the ordered block children of the whole
+ * Represents the root of a parsed markdown AST — the ordered block children of the whole
  * document. The value {@link MarkdownInterface.document} holds.
  */
 export declare interface MarkdownDocument {
     readonly element: 'document';
-    /** The document's top-level block nodes, in source order. */
+    /** Holds the document's top-level block nodes, in source order. */
     readonly children: readonly BlockNode[];
 }
 
 /**
- * A fold handler for one AST element - receives the node and its children
- * ALREADY folded to `T`, and produces the node's own `T`. The building block of a
- * {@link MarkdownHandlers} catamorphism table.
+ * Represents a fold handler for one AST element — receives the node and its children
+ * already folded to `T`, and produces the node's own `T`. The building block of a
+ * {@link MarkdownHandlerMap} catamorphism table.
  */
 export declare type MarkdownHandler<TNode, T> = (node: TNode, children: readonly T[]) => T;
 
 /**
- * The total catamorphism table for {@link MarkdownInterface.fold} - one
+ * Represents the total catamorphism table for {@link MarkdownInterface.fold} — one
  * {@link MarkdownHandler} per AST element, keyed by its `element` discriminant. Every
  * key is required: a fold is total over the AST, so there is no element it can skip.
  */
-export declare interface MarkdownHandlers<T> {
+export declare interface MarkdownHandlerMap<T> {
     /** Folds a {@link MarkdownDocument} root from its already-folded block children. */
     readonly document: MarkdownHandler<MarkdownDocument, T>;
     /** Folds a {@link HeadingNode} from its already-folded inline children. */
     readonly heading: MarkdownHandler<HeadingNode, T>;
     /** Folds a {@link ParagraphNode} from its already-folded inline children. */
     readonly paragraph: MarkdownHandler<ParagraphNode, T>;
-    /** Folds a {@link ThematicBreakNode} (leaf - always called with an empty children list). */
+    /** Folds a {@link ThematicBreakNode} (leaf — always called with an empty children list). */
     readonly thematicBreak: MarkdownHandler<ThematicBreakNode, T>;
     /** Folds a {@link BlockquoteNode} from its already-folded block children. */
     readonly blockquote: MarkdownHandler<BlockquoteNode, T>;
-    /** Folds a {@link CodeBlockNode} (leaf - always called with an empty children list). */
+    /** Folds a {@link CodeBlockNode} (leaf — always called with an empty children list). */
     readonly codeBlock: MarkdownHandler<CodeBlockNode, T>;
     /** Folds a {@link ListNode} from its already-folded item children. */
     readonly list: MarkdownHandler<ListNode, T>;
@@ -1203,19 +1345,19 @@ export declare interface MarkdownHandlers<T> {
     readonly listItem: MarkdownHandler<ListItemNode, T>;
     /**
      * Folds a {@link TableNode} from its cells' already-folded inline nodes, flattened
-     * to ONE folded `T` per inline node - header cells first (column order), then body
-     * rows' cells (row order, then column order). It is NOT a leaf: recover cell
+     * to one folded `T` per inline node — header cells first (column order), then body
+     * rows' cells (row order, then column order). It is not a leaf: recover cell
      * boundaries from `node.header[c].length` / `node.rows[r][c].length` against the
      * flat `children` list.
      */
     readonly table: MarkdownHandler<TableNode, T>;
-    /** Folds a {@link TextNode} (leaf - always called with an empty children list). */
+    /** Folds a {@link TextNode} (leaf — always called with an empty children list). */
     readonly text: MarkdownHandler<TextNode, T>;
     /** Folds an {@link EmphasisNode} from its already-folded inline children. */
     readonly emphasis: MarkdownHandler<EmphasisNode, T>;
-    /** Folds a {@link CodeSpanNode} (leaf - always called with an empty children list). */
+    /** Folds a {@link CodeSpanNode} (leaf — always called with an empty children list). */
     readonly codeSpan: MarkdownHandler<CodeSpanNode, T>;
-    /** Folds a {@link LineBreakNode} (leaf - always called with an empty children list). */
+    /** Folds a {@link LineBreakNode} (leaf — always called with an empty children list). */
     readonly break: MarkdownHandler<LineBreakNode, T>;
     /** Folds a {@link LinkNode} from its already-folded inline children. */
     readonly link: MarkdownHandler<LinkNode, T>;
@@ -1224,20 +1366,20 @@ export declare interface MarkdownHandlers<T> {
 }
 
 /**
- * A stateful, parsed markdown document: the typed {@link MarkdownDocument} AST plus
+ * Represents a stateful, parsed markdown document: the typed {@link MarkdownDocument} AST plus
  * the query, rewrite, and fold operations over it.
  *
  * @remarks
- * - **Immutable.** {@link MarkdownInterface.map} never mutates the stored AST - it
- *   returns a NEW {@link MarkdownInterface} instance; the document root invariant
+ * - **Immutable.** {@link MarkdownInterface.map} never mutates the stored AST — it
+ *   returns a new {@link MarkdownInterface} instance; the document root invariant
  *   (`element: 'document'`) always holds.
  * - **Traversal order.** `walk` / `find` / `filter` / `reduce` walk the AST
- *   depth-first, pre-order, root-inclusive; `stream` is shallow - only the
+ *   depth-first, pre-order, root-inclusive; `stream` is shallow — only the
  *   document's direct block children.
  * - **`stream`.** Returns a web-standard {@link ReadableStream} over the top-level
- *   blocks - a fresh, pull-based source per call: exactly one block is enqueued per
+ *   blocks — a fresh, pull-based source per call: exactly one block is enqueued per
  *   `pull`, so a slow consumer's backpressure is respected and no work happens ahead
- *   of demand. Cancellable via the returned stream's own `cancel()`, async-iterable
+ *   of demand. Cancellable through the returned stream's own `cancel()`, async-iterable
  *   wherever the platform supports it (Node, Deno, and browsers that ship the
  *   proposal), and pipeable through any {@link TransformStream} / {@link WritableStream}.
  * - **The surface.** `document` (the AST root), `walk` (the deep traversal), `find` /
@@ -1246,10 +1388,10 @@ export declare interface MarkdownHandlers<T> {
  *   total catamorphism), and `stream` (the shallow, backpressured top-level source).
  */
 export declare interface MarkdownInterface {
-    /** The stored {@link MarkdownDocument} AST root. */
+    /** Holds the stored {@link MarkdownDocument} AST root. */
     readonly document: MarkdownDocument;
     /**
-     * THE deep traversal - a lazy, depth-first, pre-order, root-inclusive
+     * Returns the deep traversal — a lazy, depth-first, pre-order, root-inclusive
      * {@link Generator} over every {@link MarkdownNode} in the document. The sync
      * `for (const node of markdown.walk())` surface is also consumable by
      * `for await (const node of markdown.walk())` (JavaScript accepts a sync
@@ -1258,11 +1400,17 @@ export declare interface MarkdownInterface {
      * is shallow (top-level blocks only) and backpressure-respecting.
      */
     walk(): Generator<MarkdownNode>;
-    /** Finds the first node (depth-first, pre-order) narrowed by a type guard. */
+    /**
+     * Finds the first node (depth-first, pre-order) narrowed by a type guard, and returns
+     * `undefined` when no node matches; a second overload takes a plain predicate.
+     */
     find<T extends MarkdownNode>(guard: (node: MarkdownNode) => node is T): T | undefined;
     /** Finds the first node (depth-first, pre-order) matching a predicate. */
     find(predicate: (node: MarkdownNode) => boolean): MarkdownNode | undefined;
-    /** Collects every node (depth-first, pre-order) narrowed by a type guard. */
+    /**
+     * Collects every node (depth-first, pre-order) narrowed by a type guard; a second
+     * overload takes a plain predicate.
+     */
     filter<T extends MarkdownNode>(guard: (node: MarkdownNode) => node is T): readonly T[];
     /** Collects every node (depth-first, pre-order) matching a predicate. */
     filter(predicate: (node: MarkdownNode) => boolean): readonly MarkdownNode[];
@@ -1275,11 +1423,11 @@ export declare interface MarkdownInterface {
      *
      * @remarks
      * Provenance is per handle and per node identity, so a node reports a region only
-     * where THIS handle holds coordinates for it. A handle constructed from an adopted
+     * where this handle holds coordinates for it. A handle constructed from an adopted
      * {@link MarkdownDocument} reports `undefined` for every node: it parsed no string,
-     * so no coordinates exist to report. A text run the PARSE joined from adjacent
+     * so no coordinates exist to report. A text run the parse joined from adjacent
      * scanner output reports the region enclosing its parts rather than `undefined`;
-     * only a REWRITE output that holds no region of its own and was assembled from
+     * only a rewrite output that holds no region of its own and was assembled from
      * separate source nodes reports `undefined`. The region a node does report is the
      * original source it was produced from, which can include syntax its value drops
      * and characters that normalization removed. Each call returns a fresh value rather
@@ -1288,33 +1436,33 @@ export declare interface MarkdownInterface {
     span(node: MarkdownNode): MarkdownSpan | undefined;
     /** Rewrites the AST bottom-up (copy-on-write) and returns a new {@link MarkdownInterface}. */
     map(rewrite: MarkdownRewriteHandler): MarkdownInterface;
-    /** Folds the AST depth-first, pre-order into an accumulator. */
+    /** Folds the AST depth-first, pre-order into an accumulator through a reducer callback. */
     reduce<T>(callback: (accumulator: T, node: MarkdownNode) => T, initial: T): T;
-    /** Runs a total catamorphism over the document using a {@link MarkdownHandlers} table. */
-    fold<T>(handlers: MarkdownHandlers<T>): T;
+    /** Runs a total catamorphism over the document using a {@link MarkdownHandlerMap} table. */
+    fold<T>(handlers: MarkdownHandlerMap<T>): T;
     /**
-     * A web-standard {@link ReadableStream} over the document's top-level block nodes
-     * (shallow, source order) - a lazy, pull-based, backpressure-respecting source. A
+     * Returns a web-standard {@link ReadableStream} over the document's top-level block nodes
+     * (shallow, source order) — a lazy, pull-based, backpressure-respecting source. A
      * fresh, independently-replayable stream every call; never mutates the document.
      */
     stream(): ReadableStream<BlockNode>;
 }
 
 /**
- * Any node in a markdown AST - the {@link MarkdownDocument} root, a {@link BlockNode},
+ * Represents any node in a markdown AST — the {@link MarkdownDocument} root, a {@link BlockNode},
  * a {@link ListItemNode}, or an {@link InlineNode}. The exhaustive set every
  * projection's `switch` covers.
  */
 export declare type MarkdownNode = MarkdownDocument | BlockNode | ListItemNode | InlineNode;
 
 /**
- * Pairs a parsed document with the {@link MarkdownSpan} of each of its nodes - what
+ * Pairs a parsed document with the {@link MarkdownSpan} of each of its nodes — what
  * `parseProvenance` returns, and what `parseDocument` projects the document out of.
  *
  * @remarks
- * `spans` is keyed by node identity, so it addresses the nodes of THAT document and
- * no other. A node the parse merged from adjacent scanner output - the text run
- * `coalesceText` joins - is present and carries the region ENCLOSING its parts, from
+ * `spans` is keyed by node identity, so it addresses the nodes of that document and
+ * no other. A node the parse merged from adjacent scanner output — the text run
+ * `coalesceText` joins — is present and carries the region enclosing its parts, from
  * the first part's `start` to the last part's `end`, which can include original text
  * lying between them. Absence means the parse recorded no region for the node, not
  * that the node was assembled from more than one region. Destructure it as
@@ -1326,7 +1474,7 @@ spans: ReadonlyMap<MarkdownNode, MarkdownSpan>
 ];
 
 /**
- * What one HTML node projects to on the way to markdown - the fold value
+ * Represents what one HTML node projects to on the way to markdown — the fold value
  * `htmlToMarkdown` carries up the AST.
  *
  * @remarks
@@ -1336,45 +1484,45 @@ spans: ReadonlyMap<MarkdownNode, MarkdownSpan>
  * under a `pre`. Rather than guess, each node reports every view its ancestors could
  * need, and the ancestor that knows the context takes the one it wants.
  *
- * - `blocks` / `inlines` - the block and inline views. They are exclusive by
+ * - `blocks` / `inlines` — the block and inline views. They are exclusive by
  *   construction: as soon as a node contributes a block, the inline runs around it
  *   are wrapped into paragraphs, so `blocks` being non-empty means `inlines` is
  *   empty and no interleaving is ever lost.
- * - `text` - the raw, uncollapsed, unescaped subtree text a code span and a
+ * - `text` — the raw, uncollapsed, unescaped subtree text a code span and a
  *   `pre > code` body need verbatim. An `UNSAFE_ELEMENTS` subtree contributes none
  *   of it, so a script body can never resurface as prose.
- * - `cells` / `rows` - table structure in flight. A cell travels up to its `tr` and a
+ * - `cells` / `rows` — table structure in flight. A cell travels up to its `tr` and a
  *   row up to its `table`, passing through the `thead` / `tbody` wrappers between
  *   them untouched; whatever never reaches a table degrades to paragraphs.
  */
 export declare interface MarkdownProjection {
-    /** The node's block content, with any surrounding inline runs already wrapped into paragraphs. */
+    /** Holds the node's block content, with any surrounding inline runs already wrapped into paragraphs. */
     readonly blocks: readonly BlockNode[];
-    /** The node's inline content; empty whenever `blocks` is not. */
+    /** Holds the node's inline content; empty whenever `blocks` is not. */
     readonly inlines: readonly InlineNode[];
-    /** The raw subtree text, whitespace uncollapsed and escapes unresolved. */
+    /** Holds the raw subtree text, whitespace uncollapsed and escapes unresolved. */
     readonly text: string;
-    /** The cells this node contributes to an enclosing row. */
+    /** Holds the cells this node contributes to an enclosing row. */
     readonly cells: readonly MarkdownCell[];
-    /** The rows this node contributes to an enclosing table - each its cells, in column order. */
+    /** Holds the rows this node contributes to an enclosing table — each its cells, in column order. */
     readonly rows: ReadonlyArray<readonly MarkdownCell[]>;
 }
 
 /**
- * A copy-on-write node rewrite applied bottom-up by {@link MarkdownInterface.map} -
+ * Represents a copy-on-write node rewrite applied bottom-up by {@link MarkdownInterface.map} —
  * receives one node (its own children already rewritten) and returns its
  * replacement (the same node, unchanged, or a new node).
  */
 export declare type MarkdownRewriteHandler = (node: MarkdownNode) => MarkdownNode;
 
 /**
- * Maps one run of a {@link MarkdownSource} back to the region of the ORIGINAL
+ * Maps one run of a {@link MarkdownSource} back to the region of the original
  * markdown string it was taken from.
  *
  * @remarks
  * `offset` addresses {@link MarkdownSource.text}; `start` and `end` address the
  * original string. The run's original length derives from `end - start` rather than
- * being stored beside them, so no length member exists to drift. The run's DERIVED
+ * being stored beside them, so no length member exists to drift. The run's derived
  * extent ends where the next segment's `offset` begins, so a run may cover more of the
  * original than it holds derived: the separator run `joinSources` records over a
  * normalized `\r\n` terminator is one derived code unit over a two-unit original
@@ -1385,27 +1533,27 @@ export declare type MarkdownRewriteHandler = (node: MarkdownNode) => MarkdownNod
  *
  * - strictly inside the run, `p` projects to `start + (p - offset)`;
  * - at the run's derived end, `p` projects to `end`, so the boundary claims the run's
- *   whole original region instead of the prefix an affine step would reach - which is
+ *   whole original region instead of the prefix an affine step would reach — which is
  *   how the one-unit `\r\n` separator run above reports its two-unit region;
  * - a zero-width `p` that coincides with a later segment's `offset` resolves through the
- *   LAST segment whose `offset` equals `p`, skipping every earlier segment at that
+ *   last segment whose `offset` equals `p`, skipping every earlier segment at that
  *   position whatever its extent, so a discontinuous abutment reports that final run's
  *   `start` rather than the earlier run's `end`.
  *
  * The mapping is therefore affine strictly inside a run and clamped at its end.
  */
 export declare interface MarkdownSegment {
-    /** The first code unit of the run inside {@link MarkdownSource.text}. */
+    /** Holds the first code unit of the run inside {@link MarkdownSource.text}. */
     readonly offset: number;
-    /** The first code unit of the original-string region the run was produced from, inclusive. */
+    /** Holds the first code unit of the original-string region the run was produced from, inclusive. */
     readonly start: number;
-    /** The code unit one past that region's last, exclusive. */
+    /** Holds the code unit one past that region's last, exclusive. */
     readonly end: number;
 }
 
 /**
  * Pairs a piece of derived markdown text with the runs mapping it back to the
- * original string - what `splitLines` returns per line, so every phase downstream of
+ * original string — what `splitLines` returns per line, so every phase downstream of
  * it keeps original coordinates instead of reconstructing them from node values.
  *
  * @remarks
@@ -1423,21 +1571,21 @@ export declare interface MarkdownSegment {
  * coverage with `projectSpan` rather than assuming it.
  */
 export declare interface MarkdownSource {
-    /** The derived text a parser reads. */
+    /** Holds the derived text a parser reads. */
     readonly text: string;
-    /** The runs mapping `text` back to the original string, in ascending `offset` order. */
+    /** Holds the runs mapping `text` back to the original string, in ascending `offset` order. */
     readonly segments: readonly MarkdownSegment[];
 }
 
 /**
- * Addresses a half-open region of the ORIGINAL markdown string, in UTF-16 code units -
+ * Addresses a half-open region of the original markdown string, in UTF-16 code units —
  * `start` inclusive, `end` exclusive. The provenance a parse records for a node and
  * {@link MarkdownInterface.span} reads back.
  *
  * @remarks
  * The coordinates address the string the handle was constructed from, never the line
  * text a later phase walks, so `markdown.slice(span.start, span.end)` returns the
- * ORIGINAL source region the node was produced from. That region is not the node's
+ * original source region the node was produced from. That region is not the node's
  * value: it carries the syntax the value drops, such as a `\` escape marker, and the
  * characters that normalization removed, such as a trailing space the paragraph phase
  * trimmed. The text node of `'a \nb'` has the `value` `a\nb` and reports
@@ -1446,14 +1594,14 @@ export declare interface MarkdownSource {
  * is `end - start`; no length member exists to drift from the two offsets.
  */
 export declare interface MarkdownSpan {
-    /** The first code unit of the region, inclusive. */
+    /** Holds the first code unit of the region, inclusive. */
     readonly start: number;
-    /** The code unit one past the region's last, exclusive. */
+    /** Holds the code unit one past the region's last, exclusive. */
     readonly end: number;
 }
 
 /**
- * Project a {@link MarkdownNode} into an unsanitized {@link HTMLDocument}.
+ * Projects a {@link MarkdownNode} into an unsanitized {@link HTMLDocument}.
  *
  * @remarks
  * The projection is pure and iterative. Text and attribute values remain literal for
@@ -1474,10 +1622,10 @@ export declare interface MarkdownSpan {
 export declare function markdownToHTML(node: MarkdownNode): HTMLDocument;
 
 /**
- * The maximum recursion depth the parse pipeline (`parseDocument` and its
- * `parsers.ts` helpers) and the `helpers.ts` traversal / projection functions
- * (`markdownToHTML`, `renderHTML`, `renderMarkdown`, `walkNodes`, `foldNode`,
- * `rewriteDocument`) honor before degrading. It bounds blockquote nesting, inline
+ * Caps the recursion depth the parse pipeline (`parseDocument` and its
+ * `parsers.ts` helpers), the `helpers.ts` traversal / projection functions
+ * (`markdownToHTML`, `renderMarkdown`, `walkNodes`, `foldNode`, `rewriteDocument`),
+ * and the `compilers.ts` renderer (`renderHTML`) honor before degrading, at 64. It bounds blockquote nesting, inline
  * nesting (emphasis / links), and traversal / projection recursion so pathological
  * or hostile input cannot exhaust the call stack. {@link htmlToMarkdown} is the
  * inherited exception: its fold and depth cap belong to `@orkestrel/html`.
@@ -1485,14 +1633,14 @@ export declare function markdownToHTML(node: MarkdownNode): HTMLDocument;
 export declare const MAX_DEPTH = 64;
 
 /**
- * Combine the projections of one node's children into the projection of that node -
+ * Combines the projections of one node's children into the projection of that node —
  * the single place inline runs become paragraphs, so no ancestor has to decide it
  * twice.
  *
  * @remarks
  * A child is either inline or block, never both, so merging preserves source order
  * exactly: an inline run is held pending until a block arrives, then written out as a
- * paragraph BEFORE it. That is what keeps `<div>lead<p>a</p></div>` two paragraphs in
+ * paragraph before it. That is what keeps `<div>lead<p>a</p></div>` two paragraphs in
  * the order they were written rather than two lists that lost their interleaving. A
  * pending run carrying no text is dropped rather than becoming a blank paragraph.
  * Direct cells become one row before a later row, while cells/rows before a block
@@ -1513,21 +1661,21 @@ export declare const MAX_DEPTH = 64;
 export declare function mergeProjections(children: readonly MarkdownProjection[]): MarkdownProjection;
 
 /**
- * Reduce an inline run to the shape markdown can actually write back: adjacent text
+ * Reduces an inline run to the shape markdown can actually write back: adjacent text
  * coalesced, empty text dropped, and every hard break either kept as a real line
  * ending or spent as a space.
  *
  * @remarks
- * A hard break is `  \n` in markdown source, so it survives a re-parse only BETWEEN
+ * A hard break is `  \n` in markdown source, so it survives a re-parse only between
  * two lines of content and only with no whitespace touching it: a leading or trailing
  * break has no line to end, a run of breaks reads as one blank line (which would end
  * the paragraph), and a space beside one is eaten by the parser's line trimming. Where
- * a break cannot be written at all - a heading and a table cell are one line each - it
+ * a break cannot be written at all — a heading and a table cell are one line each — it
  * becomes the space it stood for.
  *
  * @param nodes - The inline run to normalize
- * @param breaks - Whether the target context can carry a hard break at all; `false` for
- *   a heading or a table cell, where every break becomes a space
+ * @param breaks - If `true`, keeps each hard break as a real line ending; if `false`, spends
+ *   every break as the space it stood for, as a heading or a table cell requires
  * @returns The normalized run
  *
  * @example
@@ -1554,10 +1702,10 @@ export declare function normalizeInlines(nodes: readonly InlineNode[], breaks: b
  */
 export declare function normalizeParagraphLine(source: MarkdownSource, breaks: boolean): MarkdownSource;
 
-/** A paragraph - a run of non-blank lines that is not another block; `children` its inline content. */
+/** Represents a paragraph — a run of non-blank lines that is not another block; `children` its inline content. */
 export declare interface ParagraphNode {
     readonly element: 'paragraph';
-    /** The inline content of the paragraph. */
+    /** Holds the inline content of the paragraph. */
     readonly children: readonly InlineNode[];
 }
 
@@ -1579,33 +1727,52 @@ export declare interface ParagraphNode {
 export declare function parseBlocks(lines: readonly MarkdownSource[], depth: number, spans?: Map<MarkdownNode, MarkdownSpan>, end?: number): readonly BlockNode[];
 
 /**
- * Parses a markdown string into a typed {@link MarkdownDocument} AST via the
- * block phase.
+ * Parses a markdown string into a typed {@link MarkdownDocument} AST through the
+ * block phase — the document half of what {@link parseProvenance} returns. Malformed
+ * markdown degrades to literal text, so the parse never throws.
  *
  * @param markdown - The markdown source to parse.
  * @returns The parsed document.
+ *
+ * @example
+ * ```ts
+ * parseDocument('# Hi') // { element: 'document', children: [{ element: 'heading', ... }] }
+ * ```
  */
 export declare function parseDocument(markdown: string): MarkdownDocument;
 
 /**
  * Parses inline markdown text (emphasis, code spans, links, images, and hard
- * breaks) into inline AST nodes, coalescing adjacent text runs.
+ * breaks) into inline AST nodes, coalescing adjacent text runs and reading no block
+ * structure. Malformed markdown degrades to literal text, so the parse never throws.
  *
  * @param text - The inline markdown text to parse.
  * @returns The parsed inline nodes.
+ *
+ * @example
+ * ```ts
+ * parseInline('a *b*') // [{ element: 'text', value: 'a ' }, { element: 'emphasis', ... }]
+ * ```
  */
 export declare function parseInline(text: string): readonly InlineNode[];
 
 /**
- * Parses a markdown string into a document and its original-source spans.
+ * Parses a markdown string into a document and its original-source spans. Malformed
+ * markdown degrades to literal text, so the parse never throws.
  *
  * @param markdown - The markdown source to parse.
  * @returns The parsed document and its node-identity span map.
+ *
+ * @example
+ * ```ts
+ * const [document, spans] = parseProvenance('# Hi')
+ * spans.get(document) // { start: 0, end: 4 }
+ * ```
  */
 export declare function parseProvenance(markdown: string): MarkdownParseResult;
 
 /**
- * Project one HTML leaf - a text node, a comment, or a doctype - to its
+ * Projects one HTML leaf — a text node, a comment, or a doctype — to its
  * {@link MarkdownProjection}.
  *
  * @remarks
@@ -1626,8 +1793,8 @@ export declare function parseProvenance(markdown: string): MarkdownParseResult;
 export declare function projectHTMLLeaf(leaf: CommentNode | DoctypeNode | TextNode_2): MarkdownProjection;
 
 /**
- * Project one HTML container - the document root or an element - from its children's
- * already-computed projections. THE element mapping, and the only place that decides
+ * Projects one HTML container — the document root or an element — from its children's
+ * already-computed projections. The element mapping, and the only place that decides
  * what an HTML tag becomes in markdown.
  *
  * @remarks
@@ -1639,13 +1806,13 @@ export declare function projectHTMLLeaf(leaf: CommentNode | DoctypeNode | TextNo
  * inline runs wrapped in paragraphs; `ul` / `ol` a list, ordered from the tag and
  * numbered from `start`; `th` / `td`, `tr`, and `table` a GFM table whose column
  * alignment comes from each header-position cell's `align` attribute. Every
- * `UNSAFE_ELEMENTS` subtree contributes nothing at all, text included. Every OTHER
+ * `UNSAFE_ELEMENTS` subtree contributes nothing at all, text included. Every other
  * element unwraps to its children, so wrapper soup melts while its content keeps its
- * shape - `<div><p>a</p><p>b</p></div>` stays two paragraphs.
+ * shape — `<div><p>a</p><p>b</p></div>` stays two paragraphs.
  *
  * Three mappings read their own node rather than only their children's projections,
  * because HTML puts the fact in a position rather than in a value: a `pre` takes its
- * body from its `code` child's raw text, and a list takes one item per `li` child - so
+ * body from its `code` child's raw text, and a list takes one item per `li` child — so
  * an empty `<li>` is still an item, while the whitespace between two of them is not.
  * A `tr` accepts only its own direct cells, and a table derives the first `th`-bearing
  * row from its own source structure.
@@ -1663,7 +1830,7 @@ export declare function projectHTMLLeaf(leaf: CommentNode | DoctypeNode | TextNo
 export declare function projectHTMLNode(node: ElementNode | HTMLDocument, children: readonly MarkdownProjection[]): MarkdownProjection;
 
 /**
- * Read a projection as BLOCK content - the view a document, a blockquote, and a list
+ * Reads a projection as block content — the view a document, a blockquote, and a list
  * item each need.
  *
  * @remarks
@@ -1684,7 +1851,7 @@ export declare function projectHTMLNode(node: ElementNode | HTMLDocument, childr
 export declare function projectionToBlocks(projection: MarkdownProjection): readonly BlockNode[];
 
 /**
- * Read a projection as INLINE content - the view a link, an emphasis, and a table cell
+ * Reads a projection as inline content — the view a link, an emphasis, and a table cell
  * each need.
  *
  * @remarks
@@ -1722,9 +1889,12 @@ export declare function projectionToInlines(projection: MarkdownProjection): rea
 export declare function projectSpan(source: MarkdownSource, from: number, to: number): MarkdownSpan | undefined;
 
 /**
- * Render a {@link MarkdownNode} to sanitized canonical HTML.
+ * Renders a {@link MarkdownNode} to sanitized canonical HTML.
  *
  * @remarks
+ * Sanitization is unconditional: the function takes one argument and declares no
+ * options, so no call shape opts out of it.
+ *
  * Markdown widens `@orkestrel/html`'s attribute floor by exactly `src`, because image
  * syntax is meaningless without its source. `src` is still a URL attribute, so the
  * floor refuses `javascript:`, `data:`, `vbscript:`, and `file:` values. A stricter
@@ -1743,17 +1913,17 @@ export declare function projectSpan(source: MarkdownSource, from: number, to: nu
 export declare function renderHTML(node: MarkdownNode): string;
 
 /**
- * Render a {@link MarkdownNode} to its CANONICAL markdown source - the inverse
- * projection of `renderHTML`, and the serializer a `parse(renderMarkdown(doc))`
+ * Renders a {@link MarkdownNode} to its canonical markdown source — the inverse
+ * projection of `renderHTML`. It is the serializer a `parse(renderMarkdown(doc))`
  * round-trip is built on. Canonical forms: `*` / `**` emphasis at even emphasis
  * nesting depths and `_` / `__` at odd depths, `- ` bullets, `N. ` sequential
  * ordinals (from the list's `start`), `---` thematic breaks, fenced code blocks
  * (backtick run widened past any 3+ backtick run inside the body), ATX headings,
- * `> `-prefixed blockquote lines, GFM tables (1-space-padded cells, `\|`-escaped
- * pipes, an alignment delimiter row), `[text](href)` links, `![alt](src)` images,
- * and two-space hard breaks. A `text` node's literal content is backslash-escaped
- * wherever it would otherwise re-parse as markup (AGENTS §14 parse↔render
- * soundness).
+ * `> `-prefixed blockquote lines, GFM tables (1-space-padded cells, a backslash
+ * before each literal pipe, an alignment delimiter row), `[text](href)` links,
+ * `![alt](src)` images, and two-space hard breaks. A `text` node's literal content is backslash-escaped
+ * wherever it would otherwise re-parse as markup, so parsing the rendered source
+ * returns the node it was rendered from.
  *
  * @remarks
  * Total: never throws. At {@link MAX_DEPTH} a value-bearing node degrades to its
@@ -1774,10 +1944,10 @@ export declare function renderHTML(node: MarkdownNode): string;
 export declare function renderMarkdown(node: MarkdownNode): string;
 
 /**
- * Rewrite a {@link MarkdownDocument} bottom-up (copy-on-write) - each node's children
+ * Rewrites a {@link MarkdownDocument} bottom-up (copy-on-write) — each node's children
  * are rewritten first (post-order), then `rewrite` is applied to the node itself; the
- * document ROOT is never passed to `rewrite` (the `element: 'document'` invariant
- * always holds). A table's inline cells and a list's items ARE rewritten.
+ * document root is never passed to `rewrite` (the `element: 'document'` invariant
+ * always holds). A table's inline cells and a list's items are rewritten too.
  *
  * @remarks
  * Never mutates `document`. An unchanged subtree keeps its input identity. A parent
@@ -1786,12 +1956,12 @@ export declare function renderMarkdown(node: MarkdownNode): string;
  * whose `element` does not fit the slot it was called for (a block slot handed a
  * non-{@link BlockNode}, an inline slot handed a non-{@link InlineNode}, a list-item
  * slot handed a non-`listItem`), the ill-fitting result is discarded and the accepted
- * input child is reused - `rewriteDocument` stays total and never produces a
+ * input child is reused — `rewriteDocument` stays total and never produces a
  * structurally invalid document.
  *
  * Descent is capped at {@link MAX_DEPTH}, the same cap {@link walkNodes} and
  * {@link foldNode} observe: at `depth >= MAX_DEPTH` the subtree is passed through
- * UNCHANGED (by reference, not rebuilt, and `rewrite` is not invoked on it) instead of
+ * unchanged (by reference, not rebuilt, and `rewrite` is not invoked on it) instead of
  * recursing further, so a pathologically deep adopted document cannot exhaust the
  * call stack. {@link MarkdownInterface.map} inherits this cap since it delegates here.
  *
@@ -1809,8 +1979,8 @@ export declare function renderMarkdown(node: MarkdownNode): string;
 export declare function rewriteDocument(document: MarkdownDocument, rewrite: MarkdownRewriteHandler): MarkdownDerivation<MarkdownDocument>;
 
 /**
- * Scan an inline code span at `start` (a `` ` ``-run … a matching `` ` ``-run of the
- * SAME length, the CommonMark rule that lets a span contain backticks). Returns the
+ * Scans an inline code span at `start` (a `` ` ``-run … a matching `` ` ``-run of the
+ * same length, the CommonMark rule that lets a span contain backticks). Returns the
  * span's literal text + end index, or `undefined` when no matching closer exists (it
  * then degrades to literal backticks).
  *
@@ -1824,13 +1994,10 @@ export declare function rewriteDocument(document: MarkdownDocument, rewrite: Mar
  * scanCode('`code`', 0, 6) // { value: 'code', end: 6 }
  * ```
  */
-export declare function scanCode(source: string, start: number, to: number): {
-    readonly value: string;
-    readonly end: number;
-} | undefined;
+export declare function scanCode(source: string, start: number, to: number): CodeSpanMatch | undefined;
 
 /**
- * Scans an emphasis run at `start` (`*` / `_`, doubled for strong) - finds the nearest
+ * Scans an emphasis run at `start` (`*` / `_`, doubled for strong) — finds the nearest
  * matching closing run of the same marker + width while skipping complete nested runs
  * from the other marker family, and requires non-space immediately inside both
  * delimiters (the CommonMark flanking simplification that blocks `* x *`) through
@@ -1851,13 +2018,10 @@ export declare function scanCode(source: string, start: number, to: number): {
  * // { node: { element: 'emphasis', strong: false, children: [{ element: 'text', value: 'em' }] }, end: 4 }
  * ```
  */
-export declare function scanEmphasis(source: string, start: number, to: number, depth?: number): {
-    readonly node: EmphasisNode;
-    readonly end: number;
-} | undefined;
+export declare function scanEmphasis(source: string, start: number, to: number, depth?: number): EmphasisScan | undefined;
 
 /**
- * Scan the window `[from, to)` of `source` into inline nodes - the single recursive
+ * Scans the window `[from, to)` of `source` into inline nodes — the single recursive
  * engine the inline phase runs on (emphasis, link text, and image alternative
  * content recurse through it). Linear:
  * each character is consumed once; a failed construct emits its opening character as
@@ -1867,11 +2031,12 @@ export declare function scanEmphasis(source: string, start: number, to: number,
  * @param from - The inclusive start of the scan window
  * @param to - The exclusive end of the scan window
  * @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
- *   incremented by one on every recursive descent through {@link scanLink} /
- *   {@link scanEmphasis}. At {@link MAX_DEPTH} the window is never scanned for markup -
- *   it emits as a single literal text node - so pathological nesting (`[[[[…`,
- *   `****…`) cannot exhaust the call stack.
- * @returns The parsed inline nodes (NOT yet coalesced)
+ *   incremented by one on every recursive descent {@link scanInlineSource} makes into
+ *   itself for a link's text, an image's alternative content, or an emphasis run's
+ *   children. At {@link MAX_DEPTH} the window is never scanned for markup — it emits as
+ *   a single literal text node — so pathological nesting (`[[[[…`, `****…`) cannot
+ *   exhaust the call stack.
+ * @returns The parsed inline nodes (not yet coalesced)
  *
  * @example
  * ```ts
@@ -1888,7 +2053,9 @@ export declare function scanInline(source: string, from: number, to: number, dep
  * @param from - The inclusive start of the scan window
  * @param to - The exclusive end of the scan window
  * @param spans - The operation-owned node span recorder
- * @param depth - The current inline-recursion depth
+ * @param depth - The current inline-recursion depth, incremented by one on every
+ *   recursive descent this function makes into itself for a link's text, an image's
+ *   alternative content, or an emphasis run's children
  * @returns The parsed inline nodes before adjacent text coalescing
  *
  * @example
@@ -1905,7 +2072,7 @@ export declare function scanInline(source: string, from: number, to: number, dep
 export declare function scanInlineSource(source: MarkdownSource, from: number, to: number, spans: Map<MarkdownNode, MarkdownSpan>, depth?: number): readonly InlineNode[];
 
 /**
- * Scans a link `[text](href)` at `start` - the text runs to a BALANCED `]`, then `(`
+ * Scans a link `[text](href)` at `start` — the text runs to a balanced `]`, then `(`
  * must immediately follow and the destination runs to the matching `)` (both respect
  * nested delimiters + escapes) through {@link locateLink}, and returns the parsed node
  * and end index. Returns `undefined` when the shape does not hold (it then degrades to
@@ -1925,10 +2092,7 @@ export declare function scanInlineSource(source: MarkdownSource, from: number, t
  * // { node: { element: 'link', href: 'url', children: [{ element: 'text', value: 'text' }] }, end: 11 }
  * ```
  */
-export declare function scanLink(source: string, start: number, to: number, depth?: number): {
-    readonly node: LinkNode;
-    readonly end: number;
-} | undefined;
+export declare function scanLink(source: string, start: number, to: number, depth?: number): LinkScan | undefined;
 
 /**
  * Slices derived markdown text and narrows each intersecting source segment to the
@@ -1963,10 +2127,11 @@ export declare function sliceSource(source: MarkdownSource, from: number, to: nu
 export declare function splitLines(markdown: string): readonly MarkdownSource[];
 
 /**
- * Split one GFM table row into its cell strings - outer pipes are optional, an escaped
- * pipe (`\|`) inside a cell is NOT a separator (it becomes a literal `|`), and the
- * empty leading / trailing cell produced by an outer `|` is dropped. Derives the string
- * form from {@link splitTableSources}, which owns the escaped-pipe splitting rule.
+ * Splits one GFM table row into its cell strings — outer pipes are optional, a pipe
+ * escaped by a leading backslash inside a cell is not a separator (it becomes a literal
+ * pipe character), and the empty leading / trailing cell an outer pipe produces is
+ * dropped. Derives the string form from {@link splitTableSources}, which owns the
+ * escaped-pipe splitting rule.
  *
  * @param row - The raw table row line
  * @returns The row's cells, in column order
@@ -1993,15 +2158,15 @@ export declare function splitTableRow(row: string): readonly string[];
 export declare function splitTableSources(row: MarkdownSource): readonly MarkdownSource[];
 
 /**
- * Whether the line at `index` starts a NEW block kind (heading / fence / thematic
- * break / blockquote / list / table) - the paragraph collector stops at such a line
+ * Checks whether the line at `index` starts a new block kind (heading / fence / thematic
+ * break / blockquote / list / table) — the paragraph collector stops at such a line
  * so a block following a paragraph without a blank line still parses (a trusted-input
  * caller writing a `##` heading directly under a paragraph, with no intervening blank
  * line).
  *
  * @param lines - The document's lines
  * @param index - The line index to test
- * @returns `true` when the line begins a different block
+ * @returns True if the line begins a different block; false otherwise
  *
  * @example
  * ```ts
@@ -2027,17 +2192,24 @@ export declare function startsBlock(lines: readonly string[], index: number): bo
 export declare function stripQuote(source: MarkdownSource): MarkdownSource;
 
 /**
- * The horizontal alignment of a GFM table column, as declared by its delimiter row
+ * Names the horizontal alignment of a GFM table column, as declared by its delimiter row
  * (`:---` left, `---:` right, `:---:` center). A bare `---` delimiter is represented
  * by `null` in {@link TableNode.align}: the positional array requires one entry per
  * column, JSON cannot carry `undefined` in an array, and the bare delimiter is an
  * explicit no-alignment marker rather than an omitted value.
+ *
+ * @remarks
+ * The other place absence appears is {@link MarkdownCell.align}, which holds
+ * `undefined` when the projected cell declared no alignment. That member is a plain
+ * optional property on one cell rather than an entry in a positional array, so it
+ * takes the ordinary `undefined` instead of the in-band `null` marker.
  */
 export declare type TableAlign = 'left' | 'right' | 'center';
 
 /**
- * The shape of a {@link TableAlign} - the per-column GFM table alignment
- * literal.
+ * Describes the shape of a {@link TableAlign} — the per-column GFM table alignment
+ * literal. Absence is no member of it, so the shape refuses the `null` a bare `---`
+ * delimiter takes in a `TableNode`'s `align` list.
  *
  * @example
  * ```ts
@@ -2053,19 +2225,30 @@ export declare type TableAlign = 'left' | 'right' | 'center';
 export declare const tableAlignShape: LiteralShape<readonly ["left", "right", "center"]>;
 
 /**
- * A GFM table - `header` the inline content of each header cell, `rows` the body
+ * Represents the result of collecting one GFM table — the node the construct scanner built and
+ * where the block phase resumes.
+ */
+export declare interface TableCollection {
+    /** Holds the collected table. */
+    readonly node: TableNode;
+    /** Holds the index of the first line after the table. */
+    readonly next: number;
+}
+
+/**
+ * Represents a GFM table — `header` the inline content of each header cell, `rows` the body
  * rows (each a list of cells, each cell inline content), `align` the per-column
  * alignment from the delimiter row. A short body row is padded with empty cells; an
  * over-long one is truncated to the header's column count.
  */
 export declare interface TableNode {
     readonly element: 'table';
-    /** The header row - one cell of inline content per column. */
+    /** Holds the header row — one cell of inline content per column. */
     readonly header: ReadonlyArray<readonly InlineNode[]>;
-    /** The body rows - each a list of cells, each cell inline content. */
+    /** Holds the body rows — each a list of cells, each cell inline content. */
     readonly rows: ReadonlyArray<ReadonlyArray<readonly InlineNode[]>>;
     /**
-     * The per-column alignment from the delimiter row, in column order. `null`
+     * Holds the per-column alignment from the delimiter row, in column order. `null`
      * represents a bare `---` delimiter because this positional array requires one
      * entry per column, JSON cannot carry `undefined` in an array, and the delimiter
      * is an explicit no-alignment marker rather than an omitted value.
@@ -2074,19 +2257,19 @@ export declare interface TableNode {
 }
 
 /**
- * A run of plain text - the leaf inline node. `value` is the decoded text with
+ * Represents a run of plain text — the leaf inline node. `value` is the decoded text with
  * markdown escapes (`\*`, `\_`, …) already resolved to their literal characters;
  * html's text encoder escapes `&`, `<`, `>` on the way out; `"` and `'` stay literal
  * in character data.
  */
 export declare interface TextNode {
     readonly element: 'text';
-    /** The literal text content (escapes resolved, NOT yet HTML-escaped). */
+    /** Holds the literal text content (escapes resolved, not yet HTML-escaped). */
     readonly value: string;
 }
 
 /**
- * The shape of a {@link TextNode} - a plain-text leaf inline run.
+ * Describes the shape of a {@link TextNode} — a plain-text leaf inline run.
  *
  * @example
  * ```ts
@@ -2097,18 +2280,18 @@ export declare interface TextNode {
  * text.is({ element: 'text', value: 'hi' }) // true
  * ```
  */
-export declare const textShape: ObjectShape<{
-    element: LiteralShape<readonly ["text"]>;
-    value: StringShape;
+export declare const textShape: ObjectShape<    {
+element: LiteralShape<readonly ["text"]>;
+value: StringShape;
 }, false>;
 
-/** A thematic break - a horizontal rule (`---` / `***` / `___` on its own line). */
+/** Represents a thematic break — a horizontal rule (`---` / `***` / `___` on its own line). */
 export declare interface ThematicBreakNode {
     readonly element: 'thematicBreak';
 }
 
 /**
- * The shape of a {@link ThematicBreakNode} - a horizontal rule. Carries no
+ * Describes the shape of a {@link ThematicBreakNode} — a horizontal rule. Carries no
  * fields beyond its `element` discriminant.
  *
  * @example
@@ -2120,13 +2303,13 @@ export declare interface ThematicBreakNode {
  * thematicBreak.is({ element: 'thematicBreak' }) // true
  * ```
  */
-export declare const thematicBreakShape: ObjectShape<{
-    element: LiteralShape<readonly ["thematicBreak"]>;
+export declare const thematicBreakShape: ObjectShape<    {
+element: LiteralShape<readonly ["thematicBreak"]>;
 }, false>;
 
 /**
- * Trim the whitespace at the two ends of an inline run - the leading whitespace of a
- * leading text node and the trailing whitespace of a trailing one - dropping either
+ * Trims the whitespace at the two ends of an inline run — the leading whitespace of a
+ * leading text node and the trailing whitespace of a trailing one — dropping either
  * node when nothing survives.
  *
  * @remarks
@@ -2159,7 +2342,7 @@ export declare function trimInlines(nodes: readonly InlineNode[]): readonly Inli
 export declare function trimSource(source: MarkdownSource): MarkdownSource;
 
 /**
- * Resolve backslash escapes in a raw string to their literal characters - used for a
+ * Resolves backslash escapes in a raw string to their literal characters — used for a
  * link `href` (which is not otherwise inline-parsed) and any plain text run.
  *
  * @param text - The raw text possibly carrying `\x` escapes
@@ -2173,7 +2356,7 @@ export declare function trimSource(source: MarkdownSource): MarkdownSource;
 export declare function unescapeText(text: string): string;
 
 /**
- * Depth-first, pre-order, root-inclusive traversal of a {@link MarkdownNode} - yields
+ * Walks a {@link MarkdownNode} depth-first, pre-order, root-inclusive — yields
  * the node itself, then recurses into its children (block children, list items,
  * image/link inline children, table header/row cells' inline nodes) in walk order.
  *