@orkestrel/markdown 0.0.12 → 0.0.13

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

@@ -13,18 +13,18 @@ import { OptionalShape } from '@orkestrel/contract';
 import { StringShape } from '@orkestrel/contract';
 import { 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
@@ -74,18 +74,29 @@ export declare const codeBlockShape: ObjectShape<{
 }, 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
@@ -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
+ * Compiles 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).
+ * 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
+ * Compiles 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).
+ * 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,7 +210,7 @@ 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
+ * 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.
  *
@@ -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
+ * Compiles 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).
+ * 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
+ * Compiles 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).
+ * 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,7 +409,18 @@ 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 /
+ * 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,7 +444,7 @@ 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.
  *
@@ -426,35 +461,48 @@ 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
@@ -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
  * 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.
  *
  * @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
  * `'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
  * 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
  * 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
  * 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.
  *
  * @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.
  *
  * @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,13 @@ 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. */
 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
@@ -880,37 +988,70 @@ export declare const lineBreakShape: ObjectShape<{
 }, 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.
  *
@@ -931,26 +1072,26 @@ export declare const listItemMatchShape: ObjectShape<{
     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[];
 }
 
@@ -972,12 +1113,7 @@ 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 `(`
@@ -995,13 +1131,10 @@ 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.
  *
@@ -1026,7 +1159,7 @@ export declare function locateLink(source: string, start: number, to: number): {
  *   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});
+ *   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
@@ -1044,7 +1177,7 @@ export declare function locateLink(source: string, start: number, to: number): {
 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 +1198,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,10 +1231,10 @@ 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
+     * 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
@@ -1116,7 +1249,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,11 +1258,11 @@ 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`. */
 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[];
 }
 
@@ -1163,28 +1296,28 @@ 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
+ * 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 MarkdownHandlers} catamorphism table.
+ * {@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. */
@@ -1224,7 +1357,7 @@ 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
@@ -1237,7 +1370,7 @@ export declare interface MarkdownHandlers<T> {
  * - **`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
  *   `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 +1379,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
@@ -1290,10 +1423,10 @@ export declare interface 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
+     * 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.
      */
@@ -1301,7 +1434,7 @@ export declare interface MarkdownInterface {
 }
 
 /**
- * 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.
  */
@@ -1326,7 +1459,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
@@ -1348,20 +1481,20 @@ spans: ReadonlyMap<MarkdownNode, MarkdownSpan>
  *   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).
  */
@@ -1395,11 +1528,11 @@ export declare type MarkdownRewriteHandler = (node: MarkdownNode) => MarkdownNod
  * 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;
 }
 
@@ -1423,9 +1556,9 @@ 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[];
 }
 
@@ -1446,14 +1579,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 +1607,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. 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,7 +1618,7 @@ 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.
  *
@@ -1513,7 +1646,7 @@ 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.
  *
@@ -1526,8 +1659,8 @@ export declare function mergeProjections(children: readonly MarkdownProjection[]
  * 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 +1687,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,11 +1712,16 @@ 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
+ * Parses a markdown string into a typed {@link MarkdownDocument} AST through the
  * block phase.
  *
  * @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;
 
@@ -1593,6 +1731,11 @@ export declare function parseDocument(markdown: string): MarkdownDocument;
  *
  * @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[];
 
@@ -1601,11 +1744,17 @@ export declare function parseInline(text: string): readonly InlineNode[];
  *
  * @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,7 +1775,7 @@ 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
+ * 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.
  *
@@ -1663,7 +1812,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 +1833,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,7 +1871,7 @@ 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
  * Markdown widens `@orkestrel/html`'s attribute floor by exactly `src`, because image
@@ -1743,7 +1892,7 @@ 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
+ * Renders a {@link MarkdownNode} to its CANONICAL markdown source - the inverse
  * projection of `renderHTML`, and 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
@@ -1752,8 +1901,8 @@ export declare function renderHTML(node: MarkdownNode): string;
  * `> `-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).
+ * 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,7 +1923,7 @@ 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.
@@ -1809,7 +1958,7 @@ 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
+ * 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,10 +1973,7 @@ 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
@@ -1851,13 +1997,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,10 +2010,11 @@ 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.
+ *   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
@@ -1888,7 +2032,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
@@ -1925,10 +2071,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,7 +2106,7 @@ 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
+ * Splits 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.
@@ -1993,7 +2136,7 @@ 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
+ * 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
@@ -2001,7 +2144,7 @@ export declare function splitTableSources(row: MarkdownSource): readonly Markdow
  *
  * @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,7 +2170,7 @@ 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
@@ -2036,7 +2179,7 @@ export declare function stripQuote(source: MarkdownSource): MarkdownSource;
 export declare type TableAlign = 'left' | 'right' | 'center';
 
 /**
- * The shape of a {@link TableAlign} - the per-column GFM table alignment
+ * Describes the shape of a {@link TableAlign} - the per-column GFM table alignment
  * literal.
  *
  * @example
@@ -2053,19 +2196,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 +2228,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
@@ -2102,13 +2256,13 @@ export declare const textShape: ObjectShape<{
     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
@@ -2125,7 +2279,7 @@ export declare const thematicBreakShape: ObjectShape<{
 }, false>;
 
 /**
- * Trim the whitespace at the two ends of an inline run - the leading whitespace of a
+ * 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.
  *
@@ -2159,7 +2313,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 +2327,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.
  *