@orkestrel/markdown 0.0.11 → 0.0.13

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

@@ -13,21 +13,22 @@ 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)
+ * @param spans - The optional operation-owned node span recorder
  * @returns The nodes with consecutive text nodes concatenated
  *
  * @example
@@ -36,24 +37,24 @@ export declare interface BlockquoteNode {
  * // [{ element: 'text', value: 'ab' }]
  * ```
  */
-export declare function coalesceText(nodes: readonly InlineNode[]): readonly InlineNode[];
+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
@@ -73,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
@@ -107,17 +119,16 @@ export declare const codeSpanShape: ObjectShape<{
  * @param lines - The markdown lines to scan.
  * @param start - The index of the first list item.
  * @param depth - The current recursion depth (each item recurses at `depth + 1`).
+ * @param spans - The optional operation-owned node span recorder.
+ * @param end - The original-source end of this line run, including a removed terminator.
  * @returns The parsed list node and the index of the first line after it.
  *
  * @example
  * ```ts
- * collectList(['- item'], 0, 0) // { node: { element: 'list', ... }, next: 1 }
+ * collectList(splitLines('- item'), 0, 0) // { node: { element: 'list', ... }, next: 1 }
  * ```
  */
-export declare function collectList(lines: readonly string[], start: number, depth: 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
@@ -125,20 +136,18 @@ export declare function collectList(lines: readonly string[], start: number, dep
  *
  * @param lines - The markdown lines to scan.
  * @param start - The index of the header row.
+ * @param spans - The optional operation-owned node span recorder.
  * @returns The parsed table node and the index of the first line after it.
  *
  * @example
  * ```ts
- * collectTable(['| a |', '| - |'], 0) // { node: { element: 'table', ... }, next: 2 }
+ * collectTable(splitLines('| a |\n| - |'), 0) // { node: { element: 'table', ... }, next: 2 }
  * ```
  */
-export declare function collectTable(lines: readonly string[], start: number): {
-    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
@@ -152,9 +161,9 @@ export declare function collectTable(lines: readonly string[], start: number): {
 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`
  *
@@ -169,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`
  *
@@ -186,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`
@@ -201,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.
  *
@@ -229,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
@@ -251,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`
  *
@@ -268,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`
  *
@@ -285,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`.
  *
@@ -300,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
@@ -326,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.
@@ -339,32 +374,26 @@ 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;
 
 /**
- * Extract an ATX heading line (`#` … `######` followed by text) into its
- * `{ level, text }`, or `undefined` when `line` is not a heading. A run of more than 6
- * `#`s, or `#`s not followed by whitespace + text, is not a
- * heading; an optional closing `###` run is stripped.
+ * Extracts an ATX heading line (`#` … `######` followed by text) into its level,
+ * trimmed text, and the text's offset inside the line. A run of more than 6 `#`s, or
+ * `#`s not followed by whitespace + text, is not a heading; an optional closing
+ * `###` run is stripped.
  *
  * @param line - The candidate line
- * @returns The heading level (1–6) and its raw inline text, or `undefined`
+ * @returns The heading level (1–6), raw inline text, and text offset, or `undefined`
  *
  * @example
  * ```ts
- * extractHeading('## Title') // { level: 2, text: 'Title' }
+ * extractHeading('## Title') // { level: 2, text: 'Title', offset: 3 }
  * ```
  */
-export declare function extractHeading(line: string): {
-    readonly level: number;
-    readonly text: string;
-} | 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).
@@ -380,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).
@@ -404,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.
  *
@@ -421,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
@@ -495,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
@@ -525,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
@@ -550,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
@@ -560,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
@@ -570,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
@@ -584,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
@@ -594,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
@@ -609,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
@@ -624,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
@@ -638,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
@@ -652,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
@@ -674,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
@@ -683,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
@@ -697,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
@@ -720,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
@@ -745,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
@@ -755,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
@@ -768,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
@@ -788,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
@@ -798,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
@@ -813,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
@@ -823,27 +951,28 @@ 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.
+ * Joins offset-bearing markdown sources while mapping a separator to the original
+ * region between adjacent mapped sources.
  *
- * @param character - The character to test
- * @returns `true` when it is inline whitespace
+ * @param sources - The sources to join
+ * @param separator - The derived text inserted between sources
+ * @returns The joined text and every source-backed segment
  *
  * @example
  * ```ts
- * isWhitespace(' ') // true
- * isWhitespace('a') // false
+ * joinSources(splitLines('a\nb'), '\n')
+ * // { text: 'a\nb', segments: [...] }
  * ```
  */
-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
@@ -859,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.
  *
@@ -910,43 +1072,94 @@ 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[];
 }
 
 /**
- * A stateful, parsed markdown document - wraps a typed {@link MarkdownDocument} AST
+ * 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
+ * the content and syntax bounds, or `undefined` when no valid closer exists (it then degrades to
+ * a literal marker).
+ *
+ * @param source - The inline source text
+ * @param start - The index of the opening marker
+ * @param to - The exclusive end of the scan window
+ * @returns The content and syntax bounds, or `undefined`
+ *
+ * @example
+ * ```ts
+ * locateEmphasis('*em*', 0, 4) // { strong: false, open: 1, close: 3, end: 4 }
+ * ```
+ */
+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 `(`
+ * 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 `[`).
+ *
+ * @param source - The inline source text
+ * @param start - The index of the opening `[`
+ * @param to - The exclusive end of the scan window
+ * @returns The label close and syntax end indices, or `undefined`
+ *
+ * @example
+ * ```ts
+ * locateLink('[text](url)', 0, 11) // { close: 5, end: 11 }
+ * ```
+ */
+export declare function locateLink(source: string, start: number, to: number): LinkBounds | undefined;
+
+/**
+ * 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 parseDocument} (the
- *   block phase then the inline phase) to build the AST. Given a {@link MarkdownDocument},
- *   the document is adopted AS-IS and is NOT re-validated - a caller adopting an
- *   untrusted value should gate it with `isMarkdownDocument` first.
+ * - **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
+ *   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,
+ *   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
+ *   from separate source nodes reports `undefined`.
+ *   {@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`
- *   instance; the document root invariant (`element: 'document'`) always holds.
+ *   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
@@ -964,10 +1177,28 @@ export declare interface ListNode {
 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;
     /**
-     * THE deep traversal - a lazy, depth-first, pre-order, root-inclusive generator
+     * Reads the region of the original markdown string a node of this handle's tree was
+     * produced from.
+     *
+     * @param node - The node whose provenance to read
+     * @returns A fresh {@link MarkdownSpan}, or `undefined` when this handle holds no
+     * region for the node
+     *
+     * @example
+     * ```ts
+     * const source = '# Title\n\npara'
+     * const markdown = new Markdown(source)
+     * const heading = markdown.find(isHeadingNode)
+     * const span = heading && markdown.span(heading)
+     * span && source.slice(span.start, span.end) // '# Title'
+     * ```
+     */
+    span(node: MarkdownNode): MarkdownSpan | undefined;
+    /**
+     * 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.
      *
@@ -988,14 +1219,22 @@ export declare class Markdown implements MarkdownInterface {
     find(predicate: (node: MarkdownNode) => boolean): MarkdownNode | undefined;
     filter<T extends MarkdownNode>(guard: (node: MarkdownNode) => node is T): readonly T[];
     filter(predicate: (node: MarkdownNode) => boolean): readonly MarkdownNode[];
-    /** Rewrites the AST bottom-up (copy-on-write) and returns a new {@link Markdown}. */
+    /**
+     * Rewrites the AST bottom-up (copy-on-write) and returns a new {@link Markdown},
+     * carrying each output node's provenance across the rewrite. A rewrite that returns
+     * its node unchanged shares that subtree instead of copying it, so an identity
+     * rewrite copies no node and still returns a new handle.
+     *
+     * @param rewrite - The bottom-up node rewrite
+     * @returns A new handle over the rewritten document
+     */
     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
@@ -1010,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)
      * }
@@ -1019,37 +1258,66 @@ 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[];
 }
 
 /**
- * The root of a parsed markdown AST - the ordered block children of the whole
+ * 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
+ * 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;
+ * - 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
+ *   all each report `undefined`. Own-region resolution runs first, so an identity that
+ *   does hold a region keeps it in every one of those cases.
+ *
+ * An absent entry does not by itself mean the output node kept its identity. A node
+ * the handler synthesized beneath its replacement is absent too, and it reports no
+ * span because the rewrite named no input for it.
+ */
+export declare type MarkdownDerivation<T> = readonly [
+value: T,
+derivations: ReadonlyMap<MarkdownNode, MarkdownNode | undefined>
+];
+
+/**
+ * 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. */
@@ -1089,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
@@ -1102,19 +1370,19 @@ 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 seven-method surface.** `document` (the AST root), `walk` (the deep
- *   traversal), `find` / `filter` / `reduce` (queries built on `walk`), `map` (the
- *   bottom-up rewrite), `fold` (the total catamorphism), and `stream` (the shallow,
- *   backpressured top-level source).
+ * - **The surface.** `document` (the AST root), `walk` (the deep traversal), `find` /
+ *   `filter` / `reduce` (queries built on `walk`), `span` (the region of the original
+ *   markdown a node was parsed from), `map` (the bottom-up rewrite), `fold` (the
+ *   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
@@ -1131,14 +1399,34 @@ export declare interface MarkdownInterface {
     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[];
+    /**
+     * Reads the region of the original markdown string a node was produced from.
+     *
+     * @param node - A node of this handle's document.
+     * @returns A fresh {@link MarkdownSpan}, or `undefined` when this handle holds no
+     * region for the node.
+     *
+     * @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
+     * {@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
+     * 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
+     * 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
+     * than the stored one.
+     */
+    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. */
     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.
      */
@@ -1146,14 +1434,32 @@ 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.
  */
 export declare type MarkdownNode = MarkdownDocument | BlockNode | ListItemNode | InlineNode;
 
 /**
- * What one HTML node projects to on the way to markdown - the fold value
+ * 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
+ * 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
+ * `const [document, spans] = parseProvenance(markdown)`.
+ */
+export declare type MarkdownParseResult = readonly [
+document: MarkdownDocument,
+spans: ReadonlyMap<MarkdownNode, MarkdownSpan>
+];
+
+/**
+ * Represents what one HTML node projects to on the way to markdown - the fold value
  * `htmlToMarkdown` carries up the AST.
  *
  * @remarks
@@ -1175,27 +1481,112 @@ export declare type MarkdownNode = MarkdownDocument | BlockNode | ListItemNode |
  *   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;
 
 /**
- * Project a {@link MarkdownNode} into an unsanitized {@link HTMLDocument}.
+ * 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
+ * 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
+ * region.
+ *
+ * `projectSpan` resolves a derived position `p` against that shape by the following
+ * rules rather than by a single affine relation:
+ *
+ * - 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
+ *   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
+ *   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 {
+    /** Holds the first code unit of the run inside {@link MarkdownSource.text}. */
+    readonly offset: number;
+    /** Holds the first code unit of the original-string region the run was produced from, inclusive. */
+    readonly start: number;
+    /** 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
+ * it keeps original coordinates instead of reconstructing them from node values.
+ *
+ * @remarks
+ * `text` is the line a parser reads: its terminator, `>` quote marker, or leading
+ * indent already removed. `segments` run in ascending `offset` order, one run per
+ * contiguous stretch of the original; a piece assembled from separate stretches
+ * carries one segment per stretch.
+ *
+ * The runs need not cover every position of `text`. `joinSources` records a segment
+ * for its separator only where the two sides leave a gap in the original, so joining
+ * two abutting regions with a separator leaves that separator's derived position
+ * uncovered. `projectSpan` resolves a range's two boundaries against the runs
+ * independently: it reports `undefined` when either boundary lands in an uncovered
+ * position, and it bridges an uncovered interior when both boundaries resolve. Test
+ * coverage with `projectSpan` rather than assuming it.
+ */
+export declare interface MarkdownSource {
+    /** Holds the derived text a parser reads. */
+    readonly text: string;
+    /** 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 -
+ * `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
+ * 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
+ * `{ start: 0, end: 4 }`, which slices the whole `a \nb`. Read a value off the node
+ * and a region off the source; never derive either from the other. The region's length
+ * is `end - start`; no length member exists to drift from the two offsets.
+ */
+export declare interface MarkdownSpan {
+    /** Holds the first code unit of the region, inclusive. */
+    readonly start: number;
+    /** Holds the code unit one past the region's last, exclusive. */
+    readonly end: number;
+}
+
+/**
+ * Projects a {@link MarkdownNode} into an unsanitized {@link HTMLDocument}.
  *
  * @remarks
  * The projection is pure and iterative. Text and attribute values remain literal for
@@ -1216,10 +1607,10 @@ export declare type MarkdownRewriteHandler = (node: MarkdownNode) => MarkdownNod
 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`.
@@ -1227,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.
  *
@@ -1255,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.
  *
@@ -1268,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
@@ -1280,10 +1671,26 @@ export declare function mergeProjections(children: readonly MarkdownProjection[]
  */
 export declare function normalizeInlines(nodes: readonly InlineNode[], breaks: boolean): readonly InlineNode[];
 
-/** A paragraph - a run of non-blank lines that is not another block; `children` its inline content. */
+/**
+ * Normalizes one paragraph line while retaining the full source run consumed by a
+ * trailing-space hard break.
+ *
+ * @param source - The offset-bearing paragraph line
+ * @param breaks - If `true`, preserves a trailing run of at least two spaces as the
+ *   scanner's two-space hard-break syntax; if `false`, trims the line normally
+ * @returns The normalized line and its original-string segments
+ *
+ * @example
+ * ```ts
+ * normalizeParagraphLine(splitLines('text   \nnext')[0], true).text // 'text  '
+ * ```
+ */
+export declare function normalizeParagraphLine(source: MarkdownSource, breaks: boolean): MarkdownSource;
+
+/** 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[];
 }
 
@@ -1293,21 +1700,28 @@ export declare interface ParagraphNode {
  *
  * @param lines - The markdown lines to parse.
  * @param depth - The current recursion depth (blockquotes/lists increment it).
+ * @param spans - The optional operation-owned node span recorder.
+ * @param end - The original-source end of this line run, including a removed terminator.
  * @returns The parsed block nodes.
  *
  * @example
  * ```ts
- * parseBlocks(['# Hi'], 0) // [{ element: 'heading', level: 1, children: [...] }]
+ * parseBlocks(splitLines('# Hi'), 0) // [{ element: 'heading', level: 1, children: [...] }]
  * ```
  */
-export declare function parseBlocks(lines: readonly string[], depth: number): readonly BlockNode[];
+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;
 
@@ -1317,11 +1731,30 @@ 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[];
 
 /**
- * Project one HTML leaf - a text node, a comment, or a doctype - to its
+ * Parses a markdown string into a document and its original-source spans.
+ *
+ * @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;
+
+/**
+ * Projects one HTML leaf - a text node, a comment, or a doctype - to its
  * {@link MarkdownProjection}.
  *
  * @remarks
@@ -1342,7 +1775,7 @@ export declare function parseInline(text: string): readonly InlineNode[];
 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.
  *
@@ -1379,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
@@ -1400,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
@@ -1421,7 +1854,24 @@ export declare function projectionToBlocks(projection: MarkdownProjection): read
 export declare function projectionToInlines(projection: MarkdownProjection): readonly InlineNode[];
 
 /**
- * Render a {@link MarkdownNode} to sanitized canonical HTML.
+ * Projects a derived text range through its segments to a half-open region of the
+ * original markdown string.
+ *
+ * @param source - The offset-bearing source carrying the range
+ * @param from - The inclusive derived-text boundary
+ * @param to - The exclusive derived-text boundary
+ * @returns The original-string span, or `undefined` when either boundary is unmapped
+ *
+ * @example
+ * ```ts
+ * projectSpan({ text: 'a', segments: [{ offset: 0, start: 4, end: 5 }] }, 0, 1)
+ * // { start: 4, end: 5 }
+ * ```
+ */
+export declare function projectSpan(source: MarkdownSource, from: number, to: number): MarkdownSpan | undefined;
+
+/**
+ * Renders a {@link MarkdownNode} to sanitized canonical HTML.
  *
  * @remarks
  * Markdown widens `@orkestrel/html`'s attribute floor by exactly `src`, because image
@@ -1442,7 +1892,7 @@ export declare function projectionToInlines(projection: MarkdownProjection): rea
 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
@@ -1451,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
@@ -1473,19 +1923,20 @@ 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.
  *
  * @remarks
- * Never mutates `document` - every level is rebuilt into a fresh object/array, even
- * when `rewrite` returns its input unchanged. When `rewrite` returns a node whose
- * `element` does not fit the slot it was called for (a block slot handed a
+ * Never mutates `document`. An unchanged subtree keeps its input identity. A parent
+ * is rebuilt only when an accepted child changes, and the returned derivation map
+ * associates each rebuilt output with its input node. When `rewrite` returns a node
+ * 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
- * freshly-rebuilt (unrewritten-at-this-level) node is kept instead - `rewriteDocument`
- * stays total and never produces a structurally invalid document.
+ * 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
+ * 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
@@ -1495,19 +1946,19 @@ export declare function renderMarkdown(node: MarkdownNode): string;
  *
  * @param document - The document AST to rewrite
  * @param rewrite - The bottom-up {@link MarkdownRewriteHandler}
- * @returns A new, rewritten {@link MarkdownDocument}
+ * @returns The rewritten document and its output-to-input derivations
  *
  * @example
  * ```ts
- * rewriteDocument(document, (node) =>
+ * const [rewritten, derivations] = rewriteDocument(document, (node) =>
  *   node.element === 'text' ? { element: 'text', value: node.value.toUpperCase() } : node,
  * )
  * ```
  */
-export declare function rewriteDocument(document: MarkdownDocument, rewrite: MarkdownRewriteHandler): MarkdownDocument;
+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).
@@ -1522,40 +1973,34 @@ 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;
 
 /**
- * Scan 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
- * the emphasis node, or `undefined` when no valid closer exists (it then degrades to
- * a literal marker).
+ * 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
+ * {@link locateEmphasis}, and returns the parsed node and end index. Returns
+ * `undefined` when no valid closer exists (it then degrades to a literal marker).
  *
  * @param source - The inline source text
  * @param start - The index of the opening marker
  * @param to - The exclusive end of the scan window
- * @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
- *   at {@link MAX_DEPTH} the emphasis's children degrade to literal text instead of
- *   recursing further
- * @returns The parsed {@link EmphasisNode} + end index, or `undefined`
+ * @param depth - The current inline-recursion depth, forwarded to {@link scanInline}
+ *   incremented by one for the run's children. At {@link MAX_DEPTH} that recursion
+ *   emits the content as a single literal text node instead of scanning it.
+ * @returns The parsed emphasis and end index, or `undefined` when no closer exists
  *
  * @example
  * ```ts
  * scanEmphasis('*em*', 0, 4)
- * // { node: { element: 'emphasis', strong: false, children: [...] }, end: 4 }
+ * // { 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
@@ -1565,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
@@ -1579,50 +2025,91 @@ export declare function scanEmphasis(source: string, start: number, to: number,
 export declare function scanInline(source: string, from: number, to: number, depth?: number): readonly InlineNode[];
 
 /**
- * Scan a link `[text](href)` at `start` - the text runs to a BALANCED `]`, then `(`
+ * Scans an offset-bearing inline window with the same engine as {@link scanInline}
+ * and records each emitted node against the original markdown string.
+ *
+ * @param source - The offset-bearing inline source
+ * @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, 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
+ * ```ts
+ * scanInlineSource(
+ * 	{ text: 'hi *there*', segments: [{ offset: 0, start: 0, end: 10 }] },
+ * 	0,
+ * 	10,
+ * 	new Map(),
+ * )
+ * // [{ element: 'text', value: 'hi ' }, { element: 'emphasis', ... }]
+ * ```
+ */
+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 `(`
  * must immediately follow and the destination runs to the matching `)` (both respect
- * nested delimiters + escapes). Returns the link node, or `undefined` when the shape
- * does not hold (it then degrades to a literal `[`).
+ * 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
+ * a literal `[`).
  *
  * @param source - The inline source text
  * @param start - The index of the opening `[`
  * @param to - The exclusive end of the scan window
- * @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
- *   at {@link MAX_DEPTH} the link's text children degrade to literal text instead of
- *   recursing further
- * @returns The parsed {@link LinkNode} + end index, or `undefined`
+ * @param depth - The current inline-recursion depth, forwarded to {@link scanInline}
+ *   incremented by one for the link text's children. At {@link MAX_DEPTH} that
+ *   recursion emits the text as a single literal text node instead of scanning it.
+ * @returns The parsed link and end index, or `undefined` when the shape does not hold
  *
  * @example
  * ```ts
  * scanLink('[text](url)', 0, 11)
- * // { node: { element: 'link', href: 'url', children: [...] }, end: 11 }
+ * // { 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
+ * same text-relative range.
+ *
+ * @param source - The offset-bearing source to slice
+ * @param from - The inclusive text offset
+ * @param to - The exclusive text offset
+ * @returns The sliced text and its narrowed original-string segments
+ *
+ * @example
+ * ```ts
+ * sliceSource({ text: 'abc', segments: [{ offset: 0, start: 4, end: 7 }] }, 1, 3)
+ * // { text: 'bc', segments: [{ offset: 0, start: 5, end: 7 }] }
+ * ```
+ */
+export declare function sliceSource(source: MarkdownSource, from: number, to: number): MarkdownSource;
 
 /**
- * Normalize line endings to `\n` and split a markdown document into its lines - CRLF
- * (`\r\n`) and bare CR (`\r`) both collapse to `\n` first, so a Windows-origin
- * document parses identically. A single trailing newline does not yield a final
- * empty line.
+ * Splits a markdown document into offset-bearing lines while normalizing CRLF and
+ * bare CR terminators at the line boundary. A single trailing terminator does not
+ * yield a final empty line.
  *
  * @param markdown - The raw markdown source
- * @returns The document's lines, line-terminators stripped
+ * @returns The document's lines with their original-string coordinates
  *
  * @example
  * ```ts
- * splitLines('a\r\nb\nc') // ['a', 'b', 'c']
+ * splitLines('a\r\nb') // [{ text: 'a', segments: [{ offset: 0, start: 0, end: 1 }] }, ...]
  * ```
  */
-export declare function splitLines(markdown: string): readonly string[];
+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.
+ * empty leading / trailing cell produced by an outer `|` 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
@@ -1635,7 +2122,21 @@ export declare function splitLines(markdown: string): readonly string[];
 export declare function splitTableRow(row: string): readonly string[];
 
 /**
- * Whether the line at `index` starts a NEW block kind (heading / fence / thematic
+ * Splits an offset-bearing GFM table row into offset-bearing cells, retaining the
+ * complete source spelling of an escaped pipe while exposing its literal value.
+ *
+ * @param row - The offset-bearing table row
+ * @returns The row's cells with their original-string coordinates
+ *
+ * @example
+ * ```ts
+ * splitTableSources(splitLines('| a\\|b |')[0]).map((cell) => cell.text) // [' a|b ']
+ * ```
+ */
+export declare function splitTableSources(row: MarkdownSource): readonly MarkdownSource[];
+
+/**
+ * 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
@@ -1643,7 +2144,7 @@ export declare function splitTableRow(row: string): readonly string[];
  *
  * @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
@@ -1653,21 +2154,23 @@ export declare function splitTableRow(row: string): readonly string[];
 export declare function startsBlock(lines: readonly string[], index: number): boolean;
 
 /**
- * Strip one level of blockquote marker (`>` plus one optional following space) from a
- * blockquote line, so the de-quoted lines re-parse as nested blocks.
+ * Strips one level of blockquote marker (`>` plus one optional following space) from
+ * an offset-bearing blockquote line, so the de-quoted source re-parses as nested
+ * blocks without losing its original coordinates.
  *
- * @param line - A blockquote line (per {@link isQuote})
- * @returns The line with its leading `>` (and one space) removed
+ * @param source - A blockquote line (per {@link isQuote})
+ * @returns The source with its leading `>` and optional space removed
  *
  * @example
  * ```ts
- * stripQuote('> text') // 'text'
+ * stripQuote({ text: '> text', segments: [{ offset: 0, start: 0, end: 6 }] })
+ * // { text: 'text', segments: [{ offset: 0, start: 2, end: 6 }] }
  * ```
  */
-export declare function stripQuote(line: string): string;
+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
@@ -1676,7 +2179,7 @@ export declare function stripQuote(line: string): string;
 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
@@ -1693,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.
@@ -1714,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
@@ -1742,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
@@ -1765,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.
  *
@@ -1785,7 +2299,21 @@ export declare const thematicBreakShape: ObjectShape<{
 export declare function trimInlines(nodes: readonly InlineNode[]): readonly InlineNode[];
 
 /**
- * Resolve backslash escapes in a raw string to their literal characters - used for a
+ * Trims an offset-bearing source without losing the coordinates of its retained text.
+ *
+ * @param source - The source to trim
+ * @returns The trimmed text and its narrowed original-string segments
+ *
+ * @example
+ * ```ts
+ * trimSource({ text: ' a ', segments: [{ offset: 0, start: 4, end: 7 }] })
+ * // { text: 'a', segments: [{ offset: 0, start: 5, end: 6 }] }
+ * ```
+ */
+export declare function trimSource(source: MarkdownSource): MarkdownSource;
+
+/**
+ * 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
@@ -1799,7 +2327,7 @@ export declare function trimInlines(nodes: readonly InlineNode[]): readonly Inli
 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.
  *