@orkestrel/markdown 0.0.10 → 0.0.12

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

@@ -28,6 +28,7 @@ export declare interface BlockquoteNode {
  * 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,7 +37,7 @@ 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
@@ -107,14 +108,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): {
+export declare function collectList(lines: readonly MarkdownSource[], start: number, depth: number, spans?: Map<MarkdownNode, MarkdownSpan>, end?: number): {
     readonly node: ListNode;
     readonly next: number;
 };
@@ -125,14 +128,15 @@ 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): {
+export declare function collectTable(lines: readonly MarkdownSource[], start: number, spans?: Map<MarkdownNode, MarkdownSpan>): {
     readonly node: TableNode;
     readonly next: number;
 };
@@ -345,22 +349,23 @@ export declare function extractFence(line: string): {
 } | 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;
+    readonly offset: number;
 } | undefined;
 
 /**
@@ -837,6 +842,22 @@ export declare function isThematicBreakNode(node: MarkdownNode): node is Themati
  */
 export declare function isWhitespace(character: string): boolean;
 
+/**
+ * Joins offset-bearing markdown sources while mapping a separator to the original
+ * region between adjacent mapped sources.
+ *
+ * @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
+ * joinSources(splitLines('a\nb'), '\n')
+ * // { text: 'a\nb', segments: [...] }
+ * ```
+ */
+export declare function joinSources(sources: readonly MarkdownSource[], separator: string): MarkdownSource;
+
 /** A GFM hard line break - two or more trailing spaces before a newline. */
 export declare interface LineBreakNode {
     readonly element: 'break';
@@ -933,18 +954,77 @@ export declare interface ListNode {
     readonly items: readonly ListItemNode[];
 }
 
+/**
+ * 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): {
+    readonly strong: boolean;
+    readonly open: number;
+    readonly close: number;
+    readonly end: number;
+} | 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): {
+    readonly close: number;
+    readonly end: number;
+} | undefined;
+
 /**
  * A stateful, parsed markdown document - wraps a typed {@link MarkdownDocument} AST
  * 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});
  *   `stream` is shallow - only the document's direct block children.
@@ -966,6 +1046,24 @@ export declare class Markdown implements MarkdownInterface {
     constructor(input: string | MarkdownDocument);
     /** The stored {@link MarkdownDocument} AST root. */
     get document(): MarkdownDocument;
+    /**
+     * Reads the region of the original markdown string a node of this handle's tree was
+     * 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;
     /**
      * THE deep traversal - a lazy, depth-first, pre-order, root-inclusive generator
      * over every {@link MarkdownNode} in the document. `find` / `filter` / `reduce`
@@ -988,7 +1086,15 @@ 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;
@@ -1027,6 +1133,35 @@ export declare interface MarkdownCell {
     readonly inlines: readonly InlineNode[];
 }
 
+/**
+ * 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>
+];
+
 /**
  * The root of a parsed markdown AST - the ordered block children of the whole
  * document. The value {@link MarkdownInterface.document} holds.
@@ -1105,10 +1240,10 @@ export declare interface MarkdownHandlers<T> {
  *   of demand. Cancellable via 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. */
@@ -1131,6 +1266,26 @@ 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. */
@@ -1152,6 +1307,24 @@ export declare interface MarkdownInterface {
  */
 export declare type MarkdownNode = MarkdownDocument | BlockNode | ListItemNode | InlineNode;
 
+/**
+ * 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>
+];
+
 /**
  * What one HTML node projects to on the way to markdown - the fold value
  * `htmlToMarkdown` carries up the AST.
@@ -1194,6 +1367,91 @@ export declare interface MarkdownProjection {
  */
 export declare type MarkdownRewriteHandler = (node: MarkdownNode) => MarkdownNode;
 
+/**
+ * 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 {
+    /** The first code unit of the run inside {@link MarkdownSource.text}. */
+    readonly offset: number;
+    /** The first code unit of the original-string region the run was produced from, inclusive. */
+    readonly start: number;
+    /** 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 {
+    /** The derived text a parser reads. */
+    readonly text: string;
+    /** 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 {
+    /** The first code unit of the region, inclusive. */
+    readonly start: number;
+    /** The code unit one past the region's last, exclusive. */
+    readonly end: number;
+}
+
 /**
  * Project a {@link MarkdownNode} into an unsanitized {@link HTMLDocument}.
  *
@@ -1280,6 +1538,22 @@ export declare function mergeProjections(children: readonly MarkdownProjection[]
  */
 export declare function normalizeInlines(nodes: readonly InlineNode[], breaks: boolean): readonly InlineNode[];
 
+/**
+ * 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;
+
 /** A paragraph - a run of non-blank lines that is not another block; `children` its inline content. */
 export declare interface ParagraphNode {
     readonly element: 'paragraph';
@@ -1293,14 +1567,16 @@ 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
@@ -1320,6 +1596,14 @@ export declare function parseDocument(markdown: string): MarkdownDocument;
  */
 export declare function parseInline(text: string): readonly InlineNode[];
 
+/**
+ * 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.
+ */
+export declare function parseProvenance(markdown: string): MarkdownParseResult;
+
 /**
  * Project one HTML leaf - a text node, a comment, or a doctype - to its
  * {@link MarkdownProjection}.
@@ -1420,6 +1704,23 @@ export declare function projectionToBlocks(projection: MarkdownProjection): read
  */
 export declare function projectionToInlines(projection: MarkdownProjection): readonly InlineNode[];
 
+/**
+ * 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;
+
 /**
  * Render a {@link MarkdownNode} to sanitized canonical HTML.
  *
@@ -1479,13 +1780,14 @@ export declare function renderMarkdown(node: MarkdownNode): string;
  * 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,16 +1797,16 @@ 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
@@ -1528,25 +1830,25 @@ export declare function scanCode(source: string, start: number, to: number): {
 } | 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): {
@@ -1579,23 +1881,48 @@ 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
+ * @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): {
@@ -1604,25 +1931,42 @@ export declare function scanLink(source: string, start: number, to: number, dept
 } | undefined;
 
 /**
- * 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.
+ * 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;
+
+/**
+ * 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
  * 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
@@ -1634,6 +1978,20 @@ export declare function splitLines(markdown: string): readonly string[];
  */
 export declare function splitTableRow(row: string): readonly string[];
 
+/**
+ * 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[];
+
 /**
  * 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
@@ -1653,18 +2011,20 @@ 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
@@ -1784,6 +2144,20 @@ export declare const thematicBreakShape: ObjectShape<{
  */
 export declare function trimInlines(nodes: readonly InlineNode[]): readonly InlineNode[];
 
+/**
+ * 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;
+
 /**
  * Resolve 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.