@orkestrel/markdown 0.0.10 → 0.0.12

package/dist/src/core/index.cjs

@@ -452,94 +452,146 @@ var isMarkdownDocument = (0, _orkestrel_contract.recordOf)({
 *
 * @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: [...] }]
 * ```
 */
-function parseBlocks(lines, depth) {
-	if (depth >= 64) return lines.length > 0 ? [{
-		element: "paragraph",
-		children: [{
+function parseBlocks(lines, depth, spans = /* @__PURE__ */ new Map(), end) {
+	const text = lines.map((line) => line.text);
+	if (depth >= 64) {
+		if (lines.length === 0) return [];
+		const source = joinSources(lines, "\n");
+		const inline = {
 			element: "text",
-			value: lines.join("\n")
-		}]
-	}] : [];
+			value: source.text
+		};
+		const paragraph = {
+			element: "paragraph",
+			children: [inline]
+		};
+		const span = projectSpan(source, 0, source.text.length);
+		if (span !== void 0) {
+			spans.set(inline, span);
+			spans.set(paragraph, span);
+		}
+		return [paragraph];
+	}
 	const blocks = [];
 	let index = 0;
 	while (index < lines.length) {
-		const line = lines[index] ?? "";
+		const line = text[index] ?? "";
 		if (isBlankLine(line)) {
 			index += 1;
 			continue;
 		}
 		const fence = extractFence(line);
 		if (fence) {
+			const start = index;
 			const body = [];
+			let closed = false;
 			index += 1;
-			while (index < lines.length && !isFenceClose(lines[index] ?? "", fence.marker)) {
-				body.push(lines[index] ?? "");
+			while (index < lines.length && !isFenceClose(text[index] ?? "", fence.marker)) {
+				const bodyLine = lines[index];
+				if (bodyLine !== void 0) body.push(bodyLine);
 				index += 1;
 			}
-			index += 1;
-			blocks.push({
+			if (index < lines.length) {
+				closed = true;
+				index += 1;
+			}
+			const node = {
 				element: "codeBlock",
 				...fence.lang === void 0 ? {} : { lang: fence.lang },
-				code: body.join("\n")
-			});
+				code: joinSources(body, "\n").text
+			};
+			const source = joinSources(lines.slice(start, index), "\n");
+			const span = projectSpan(source, 0, source.text.length);
+			if (span !== void 0) spans.set(node, !closed && end !== void 0 ? {
+				start: span.start,
+				end
+			} : span);
+			blocks.push(node);
 			continue;
 		}
 		if (isThematicBreak(line)) {
-			blocks.push({ element: "thematicBreak" });
+			const node = { element: "thematicBreak" };
+			const source = lines[index];
+			const span = source === void 0 ? void 0 : projectSpan(source, 0, source.text.length);
+			if (span !== void 0) spans.set(node, span);
+			blocks.push(node);
 			index += 1;
 			continue;
 		}
 		const heading = extractHeading(line);
 		if (heading) {
-			blocks.push({
+			const source = lines[index];
+			const content = source === void 0 ? {
+				text: heading.text,
+				segments: []
+			} : sliceSource(source, heading.offset, heading.offset + heading.text.length);
+			const node = {
 				element: "heading",
 				level: heading.level,
-				children: parseInline(heading.text)
-			});
+				children: coalesceText(scanInlineSource(content, 0, content.text.length, spans), spans)
+			};
+			const span = source === void 0 ? void 0 : projectSpan(source, 0, source.text.length);
+			if (span !== void 0) spans.set(node, span);
+			blocks.push(node);
 			index += 1;
 			continue;
 		}
 		if (isQuote(line)) {
+			const start = index;
 			const quoted = [];
-			while (index < lines.length && isQuote(lines[index] ?? "")) {
-				quoted.push(stripQuote(lines[index] ?? ""));
+			while (index < lines.length && isQuote(text[index] ?? "")) {
+				const quotedLine = lines[index];
+				if (quotedLine === void 0) break;
+				quoted.push(stripQuote(quotedLine));
 				index += 1;
 			}
-			blocks.push({
+			const source = joinSources(lines.slice(start, index), "\n");
+			const span = projectSpan(source, 0, source.text.length);
+			const node = {
 				element: "blockquote",
-				children: parseBlocks(quoted, depth + 1)
-			});
+				children: parseBlocks(quoted, depth + 1, spans, index === lines.length && end !== void 0 ? end : span?.end)
+			};
+			if (span !== void 0) spans.set(node, span);
+			blocks.push(node);
 			continue;
 		}
-		if (isTableStart(line, lines[index + 1])) {
-			const table = collectTable(lines, index);
+		if (isTableStart(line, text[index + 1])) {
+			const table = collectTable(lines, index, spans);
 			blocks.push(table.node);
 			index = table.next;
 			continue;
 		}
 		if (extractListItem(line)) {
-			const list = collectList(lines, index, depth);
+			const list = collectList(lines, index, depth, spans, end);
 			blocks.push(list.node);
 			index = list.next;
 			continue;
 		}
+		const start = index;
 		const paragraph = [];
-		while (index < lines.length && !isBlankLine(lines[index] ?? "") && !((0, _orkestrel_contract.isNonEmptyArray)(paragraph) && startsBlock(lines, index))) {
-			paragraph.push(lines[index] ?? "");
+		while (index < lines.length && !isBlankLine(text[index] ?? "") && !((0, _orkestrel_contract.isNonEmptyArray)(paragraph) && startsBlock(text, index))) {
+			const paragraphLine = lines[index];
+			if (paragraphLine !== void 0) paragraph.push(paragraphLine);
 			index += 1;
 		}
-		const source = paragraph.map((paragraphLine, position) => position < paragraph.length - 1 && paragraphLine.endsWith("  ") ? `${paragraphLine.trim()}  ` : paragraphLine.trim()).join("\n");
-		blocks.push({
+		const source = joinSources(paragraph.map((paragraphLine, position) => normalizeParagraphLine(paragraphLine, position < paragraph.length - 1)), "\n");
+		const node = {
 			element: "paragraph",
-			children: parseInline(source)
-		});
+			children: coalesceText(scanInlineSource(source, 0, source.text.length, spans), spans)
+		};
+		const region = joinSources(lines.slice(start, index), "\n");
+		const span = projectSpan(region, 0, region.text.length);
+		if (span !== void 0) spans.set(node, span);
+		blocks.push(node);
 	}
 	return blocks;
 }
@@ -551,10 +603,26 @@ function parseBlocks(lines, depth) {
 * @returns The parsed document.
 */
 function parseDocument(markdown) {
-	return {
+	const [document] = parseProvenance(markdown);
+	return document;
+}
+/**
+* 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.
+*/
+function parseProvenance(markdown) {
+	const spans = /* @__PURE__ */ new Map();
+	const document = {
 		element: "document",
-		children: parseBlocks(splitLines(markdown), 0)
+		children: parseBlocks(splitLines(markdown), 0, spans, markdown.length)
 	};
+	spans.set(document, {
+		start: 0,
+		end: markdown.length
+	});
+	return [document, spans];
 }
 /**
 * Parses inline markdown text (emphasis, code spans, links, images, and hard
@@ -574,12 +642,25 @@ function parseInline(text) {
 * 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.
@@ -598,14 +679,46 @@ function parseInline(text) {
 */
 var Markdown = class Markdown {
 	#document;
+	#spans;
 	constructor(input) {
-		this.#document = typeof input === "string" ? parseDocument(input) : input;
+		if (typeof input === "string") {
+			const [document, spans] = parseProvenance(input);
+			this.#document = document;
+			this.#spans = new Map(spans);
+		} else {
+			this.#document = input;
+			this.#spans = /* @__PURE__ */ new Map();
+		}
 	}
 	/** The stored {@link MarkdownDocument} AST root. */
 	get document() {
 		return this.#document;
 	}
 	/**
+	* 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) {
+		const span = this.#spans.get(node);
+		return span === void 0 ? void 0 : {
+			start: span.start,
+			end: span.end
+		};
+	}
+	/**
 	* 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.
@@ -633,9 +746,18 @@ var Markdown = class Markdown {
 		for (const node of this.walk()) if (predicate(node)) out.push(node);
 		return out;
 	}
-	/** 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) {
-		return new Markdown(rewriteDocument(this.#document, rewrite));
+		const [document, derivations] = rewriteDocument(this.#document, rewrite);
+		return this.#derive(document, derivations);
 	}
 	/** Folds the AST depth-first, pre-order into an accumulator. */
 	reduce(callback, initial) {
@@ -684,6 +806,21 @@ var Markdown = class Markdown {
 			} else controller.close();
 		} });
 	}
+	#derive(document, derivations) {
+		const derived = new Markdown(document);
+		for (const node of walkNodes(document)) {
+			const own = this.#spans.get(node);
+			if (own !== void 0) {
+				derived.#spans.set(node, own);
+				continue;
+			}
+			const source = derivations.get(node);
+			if (source === void 0) continue;
+			const span = this.#spans.get(source);
+			if (span !== void 0) derived.#spans.set(node, span);
+		}
+		return derived;
+	}
 };
 //#endregion
 //#region src/core/shapers.ts
@@ -958,25 +1095,220 @@ function createThematicBreakContract() {
 //#endregion
 //#region src/core/helpers.ts
 /**
-* 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 }] }, ...]
 * ```
 */
 function splitLines(markdown) {
-	const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
-	if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
+	const lines = [];
+	let start = 0;
+	let index = 0;
+	while (index < markdown.length) {
+		const character = markdown[index];
+		if (character !== "\r" && character !== "\n") {
+			index += 1;
+			continue;
+		}
+		lines.push({
+			text: markdown.slice(start, index),
+			segments: [{
+				offset: 0,
+				start,
+				end: index
+			}]
+		});
+		index += character === "\r" && markdown[index + 1] === "\n" ? 2 : 1;
+		start = index;
+	}
+	lines.push({
+		text: markdown.slice(start),
+		segments: [{
+			offset: 0,
+			start,
+			end: markdown.length
+		}]
+	});
+	if (lines.length > 1 && lines[lines.length - 1]?.text === "") lines.pop();
 	return lines;
 }
 /**
+* 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 }] }
+* ```
+*/
+function sliceSource(source, from, to) {
+	const start = Math.max(0, Math.min(from, source.text.length));
+	const end = Math.max(start, Math.min(to, source.text.length));
+	const segments = [];
+	for (let index = 0; index < source.segments.length; index += 1) {
+		const segment = source.segments[index];
+		if (segment === void 0) continue;
+		const next = source.segments[index + 1];
+		const limit = Math.min(segment.offset + (segment.end - segment.start), next === void 0 ? source.text.length : next.offset);
+		const overlapStart = Math.max(start, segment.offset);
+		const overlapEnd = Math.min(end, limit);
+		const empty = segment.offset === limit && overlapStart === segment.offset;
+		if (overlapStart >= overlapEnd && !empty) continue;
+		const originalStart = overlapStart === limit ? segment.end : Math.min(segment.end, segment.start + overlapStart - segment.offset);
+		const originalEnd = overlapEnd === limit ? segment.end : Math.min(segment.end, segment.start + overlapEnd - segment.offset);
+		segments.push({
+			offset: overlapStart - start,
+			start: originalStart,
+			end: originalEnd
+		});
+	}
+	return {
+		text: source.text.slice(start, end),
+		segments
+	};
+}
+/**
+* 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: [...] }
+* ```
+*/
+function joinSources(sources, separator) {
+	let text = "";
+	const segments = [];
+	for (let index = 0; index < sources.length; index += 1) {
+		const source = sources[index];
+		if (source === void 0) continue;
+		if (index > 0) {
+			const previous = sources[index - 1];
+			const left = previous?.segments[previous.segments.length - 1];
+			const right = source.segments[0];
+			if (separator.length > 0 && left !== void 0 && right !== void 0 && left.end < right.start) segments.push({
+				offset: text.length,
+				start: left.end,
+				end: right.start
+			});
+			text += separator;
+		}
+		for (const segment of source.segments) segments.push({
+			offset: text.length + segment.offset,
+			start: segment.start,
+			end: segment.end
+		});
+		text += source.text;
+	}
+	return {
+		text,
+		segments
+	};
+}
+/**
+* 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 }
+* ```
+*/
+function projectSpan(source, from, to) {
+	if (from < 0 || to < from || to > source.text.length) return void 0;
+	let start;
+	let end;
+	for (let index = 0; index < source.segments.length; index += 1) {
+		const segment = source.segments[index];
+		if (segment === void 0) continue;
+		const next = source.segments[index + 1];
+		const limit = Math.min(segment.offset + (segment.end - segment.start), next === void 0 ? source.text.length : next.offset);
+		if (from === to && from >= segment.offset && from <= limit) {
+			if (next !== void 0 && from === next.offset) continue;
+			const position = from === limit ? segment.end : Math.min(segment.end, segment.start + from - segment.offset);
+			return {
+				start: position,
+				end: position
+			};
+		}
+		if (start === void 0 && from >= segment.offset && from < limit) start = segment.start + from - segment.offset;
+		if (to > segment.offset && to <= limit) end = to === limit ? segment.end : Math.min(segment.end, segment.start + to - segment.offset);
+	}
+	return start === void 0 || end === void 0 ? void 0 : {
+		start,
+		end
+	};
+}
+/**
+* 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 }] }
+* ```
+*/
+function trimSource(source) {
+	const start = source.text.length - source.text.trimStart().length;
+	const end = source.text.trimEnd().length;
+	return sliceSource(source, start, Math.max(start, end));
+}
+/**
+* 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  '
+* ```
+*/
+function normalizeParagraphLine(source, breaks) {
+	if (!breaks || !source.text.endsWith("  ")) return trimSource(source);
+	const contentEnd = source.text.trimEnd().length;
+	const content = trimSource(sliceSource(source, 0, contentEnd));
+	const span = projectSpan(source, contentEnd, source.text.length);
+	return joinSources([content, {
+		text: "  ",
+		segments: span === void 0 ? [] : [{
+			offset: 0,
+			start: span.start,
+			end: span.end
+		}]
+	}], "");
+}
+/**
 * The count of 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.
 *
@@ -995,25 +1327,33 @@ function countIndent(line) {
 	return count;
 }
 /**
-* 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 }
 * ```
 */
 function extractHeading(line) {
-	const match = /^(#{1,6})(?:\s+(.*))?$/.exec(line.trimStart());
+	const trimmed = line.trimStart();
+	const match = /^(#{1,6})(?:\s+(.*))?$/.exec(trimmed);
 	if (!match || match[1] === void 0) return void 0;
+	const level = match[1].length;
+	const raw = match[2] ?? "";
+	const withoutClosing = raw.replace(/\s+#+\s*$/, "");
+	const text = withoutClosing.trim();
+	const found = raw.length === 0 ? trimmed.length : trimmed.indexOf(raw, level);
+	const content = found < 0 ? trimmed.length : found;
 	return {
-		level: match[1].length,
-		text: (match[2] ?? "").replace(/\s+#+\s*$/, "").trim()
+		level,
+		text,
+		offset: line.length - trimmed.length + content + withoutClosing.length - withoutClosing.trimStart().length
 	};
 }
 /**
@@ -1082,24 +1422,27 @@ function extractListItem(line) {
 	}
 }
 /**
-* 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 }] }
 * ```
 */
-function stripQuote(line) {
-	return line.replace(/^\s{0,3}>\s?/, "");
+function stripQuote(source) {
+	return sliceSource(source, (/^\s{0,3}>\s?/.exec(source.text)?.[0] ?? "").length, source.text.length);
 }
 /**
 * 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
@@ -1110,22 +1453,55 @@ function stripQuote(line) {
 * ```
 */
 function splitTableRow(row) {
+	return splitTableSources({
+		text: row,
+		segments: []
+	}).map((cell) => cell.text);
+}
+/**
+* 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 ']
+* ```
+*/
+function splitTableSources(row) {
+	const source = trimSource(row);
 	const cells = [];
-	let current = "";
-	const trimmed = row.trim();
-	for (let index = 0; index < trimmed.length; index += 1) {
-		const character = trimmed[index];
-		if (character === "\\" && trimmed[index + 1] === "|") {
-			current += "|";
+	let pieces = [];
+	let start = 0;
+	for (let index = 0; index < source.text.length; index += 1) {
+		const character = source.text[index];
+		if (character === "\\" && source.text[index + 1] === "|") {
+			pieces.push(sliceSource(source, start, index));
+			const span = projectSpan(source, index, index + 2);
+			pieces.push({
+				text: "|",
+				segments: span === void 0 ? [] : [{
+					offset: 0,
+					start: span.start,
+					end: span.end
+				}]
+			});
 			index += 1;
-		} else if (character === "|") {
-			cells.push(current);
-			current = "";
-		} else current += character;
+			start = index + 1;
+			continue;
+		}
+		if (character !== "|") continue;
+		pieces.push(sliceSource(source, start, index));
+		cells.push(joinSources(pieces, ""));
+		pieces = [];
+		start = index + 1;
 	}
-	cells.push(current);
-	if ((0, _orkestrel_contract.isNonEmptyArray)(cells) && (0, _orkestrel_contract.isEmptyString)((cells[0] ?? "").trim())) cells.shift();
-	if ((0, _orkestrel_contract.isNonEmptyArray)(cells) && (0, _orkestrel_contract.isEmptyString)((cells[cells.length - 1] ?? "").trim())) cells.pop();
+	pieces.push(sliceSource(source, start, source.text.length));
+	cells.push(joinSources(pieces, ""));
+	if ((0, _orkestrel_contract.isNonEmptyArray)(cells) && (0, _orkestrel_contract.isEmptyString)((cells[0]?.text ?? "").trim())) cells.shift();
+	if ((0, _orkestrel_contract.isNonEmptyArray)(cells) && (0, _orkestrel_contract.isEmptyString)((cells[cells.length - 1]?.text ?? "").trim())) cells.pop();
 	return cells;
 }
 /**
@@ -1200,6 +1576,7 @@ function unescapeText(text) {
 * 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
@@ -1208,15 +1585,27 @@ function unescapeText(text) {
 * // [{ element: 'text', value: 'ab' }]
 * ```
 */
-function coalesceText(nodes) {
+function coalesceText(nodes, spans) {
 	const out = [];
 	for (const node of nodes) {
 		const last = out[out.length - 1];
-		if (node.element === "text" && last !== void 0 && last.element === "text") out[out.length - 1] = {
-			element: "text",
-			value: last.value + node.value
-		};
-		else out.push(node);
+		if (node.element === "text" && last !== void 0 && last.element === "text") {
+			const merged = {
+				element: "text",
+				value: last.value + node.value
+			};
+			const left = spans?.get(last);
+			const right = spans?.get(node);
+			if (spans !== void 0) {
+				spans.delete(last);
+				spans.delete(node);
+				if (left !== void 0 && right !== void 0) spans.set(merged, {
+					start: left.start,
+					end: right.end
+				});
+			}
+			out[out.length - 1] = merged;
+		} else out.push(node);
 	}
 	return out;
 }
@@ -1256,26 +1645,22 @@ function scanCode(source, start, to) {
 	}
 }
 /**
-* Scan a link `[text](href)` at `start` - the text runs to a BALANCED `]`, then `(`
+* Locates a link `[text](href)` at `start` - the text runs to a BALANCED `]`, then `(`
 * must immediately follow and the destination runs to the matching `)` (both respect
-* nested delimiters + escapes). Returns the link node, or `undefined` when the shape
+* 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
-* @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`
+* @returns The label close and syntax end indices, or `undefined`
 *
 * @example
 * ```ts
-* scanLink('[text](url)', 0, 11)
-* // { node: { element: 'link', href: 'url', children: [...] }, end: 11 }
+* locateLink('[text](url)', 0, 11) // { close: 5, end: 11 }
 * ```
 */
-function scanLink(source, start, to, depth = 0) {
+function locateLink(source, start, to) {
 	let bracketDepth = 0;
 	let close = -1;
 	for (let index = start; index < to; index += 1) {
@@ -1312,38 +1697,63 @@ function scanLink(source, start, to, depth = 0) {
 		}
 	}
 	if (parenClose === -1) return void 0;
+	return {
+		close,
+		end: parenClose + 1
+	};
+}
+/**
+* Scans a link `[text](href)` at `start` - the text runs to a BALANCED `]`, then `(`
+* must immediately follow and the destination runs to the matching `)` (both respect
+* nested delimiters + escapes) through {@link locateLink}, and returns the parsed node
+* and end index. Returns `undefined` when the shape does not hold (it then degrades to
+* 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, 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: [{ element: 'text', value: 'text' }] }, end: 11 }
+* ```
+*/
+function scanLink(source, start, to, depth = 0) {
+	const located = locateLink(source, start, to);
+	if (located === void 0) return void 0;
 	return {
 		node: {
 			element: "link",
-			href: unescapeText(source.slice(close + 2, parenClose).trim()),
-			children: scanInline(source, start + 1, close, depth + 1)
+			href: unescapeText(source.slice(located.close + 2, located.end - 1).trim()),
+			children: scanInline(source, start + 1, located.close, depth + 1)
 		},
-		end: parenClose + 1
+		end: located.end
 	};
 }
 /**
-* Scan an emphasis run at `start` (`*` / `_`, doubled for strong) - finds the nearest
+* Locates an emphasis run at `start` (`*` / `_`, doubled for strong) - finds the nearest
 * matching closing run of the same marker + width while skipping complete nested
 * runs from the other marker family, and requires non-space immediately inside both
 * delimiters (the CommonMark flanking simplification that blocks `* x *`). Returns
-* the emphasis node, or `undefined` when no valid closer exists (it then degrades to
+* 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
-* @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`
+* @returns The content and syntax bounds, or `undefined`
 *
 * @example
 * ```ts
-* scanEmphasis('*em*', 0, 4)
-* // { node: { element: 'emphasis', strong: false, children: [...] }, end: 4 }
+* locateEmphasis('*em*', 0, 4) // { strong: false, open: 1, close: 3, end: 4 }
 * ```
 */
-function scanEmphasis(source, start, to, depth = 0) {
+function locateEmphasis(source, start, to) {
 	const marker = source[start] ?? "";
 	let run = 0;
 	while (start + run < to && source[start + run] === marker && run < 2) run += 1;
@@ -1363,7 +1773,7 @@ function scanEmphasis(source, start, to, depth = 0) {
 			continue;
 		}
 		if ((character === "*" || character === "_") && character !== marker) {
-			const nested = scanEmphasis(source, index, to, depth + 1);
+			const nested = locateEmphasis(source, index, to);
 			if (nested !== void 0) {
 				index = nested.end;
 				continue;
@@ -1373,11 +1783,9 @@ function scanEmphasis(source, start, to, depth = 0) {
 			let closeRun = 0;
 			while (index + closeRun < to && source[index + closeRun] === marker) closeRun += 1;
 			if (closeRun >= run && !isWhitespace(source[index - 1] ?? "")) return {
-				node: {
-					element: "emphasis",
-					strong,
-					children: scanInline(source, openEnd, index, depth + 1)
-				},
+				strong,
+				open: openEnd,
+				close: index,
 				end: index + run
 			};
 			index += closeRun;
@@ -1387,6 +1795,40 @@ function scanEmphasis(source, start, to, depth = 0) {
 	}
 }
 /**
+* 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, 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: [{ element: 'text', value: 'em' }] }, end: 4 }
+* ```
+*/
+function scanEmphasis(source, start, to, depth = 0) {
+	const located = locateEmphasis(source, start, to);
+	if (located === void 0) return void 0;
+	return {
+		node: {
+			element: "emphasis",
+			strong: located.strong,
+			children: scanInline(source, located.open, located.close, depth + 1)
+		},
+		end: located.end
+	};
+}
+/**
 * Scan 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:
@@ -1409,40 +1851,86 @@ function scanEmphasis(source, start, to, depth = 0) {
 * ```
 */
 function scanInline(source, from, to, depth = 0) {
-	if (depth >= 64) return from < to ? [{
-		element: "text",
-		value: source.slice(from, to)
-	}] : [];
+	return scanInlineSource({
+		text: source,
+		segments: [{
+			offset: 0,
+			start: 0,
+			end: source.length
+		}]
+	}, from, to, /* @__PURE__ */ new Map(), depth);
+}
+/**
+* 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', ... }]
+* ```
+*/
+function scanInlineSource(source, from, to, spans, depth = 0) {
+	if (depth >= 64) if (from < to) {
+		const node = {
+			element: "text",
+			value: source.text.slice(from, to)
+		};
+		const span = projectSpan(source, from, to);
+		if (span !== void 0) spans.set(node, span);
+		return [node];
+	} else return [];
 	const nodes = [];
 	let index = from;
 	let pending = "";
+	let pendingStart = from;
 	while (index < to) {
-		const character = source[index] ?? "";
-		if (character === "\\" && index + 1 < to && isEscapable(source[index + 1] ?? "")) {
-			pending += source[index + 1] ?? "";
+		const character = source.text[index] ?? "";
+		if (character === "\\" && index + 1 < to && isEscapable(source.text[index + 1] ?? "")) {
+			if (pending.length === 0) pendingStart = index;
+			pending += source.text[index + 1] ?? "";
 			index += 2;
 			continue;
 		}
 		if (character === " ") {
 			let spaceEnd = index;
-			while (spaceEnd < to && source[spaceEnd] === " ") spaceEnd += 1;
-			if (spaceEnd - index >= 2 && source[spaceEnd] === "\n") {
+			while (spaceEnd < to && source.text[spaceEnd] === " ") spaceEnd += 1;
+			if (spaceEnd - index >= 2 && source.text[spaceEnd] === "\n") {
 				if (pending.length > 0) {
-					nodes.push({
+					const node = {
 						element: "text",
 						value: pending
-					});
+					};
+					const span = projectSpan(source, pendingStart, index);
+					if (span !== void 0) spans.set(node, span);
+					nodes.push(node);
 					pending = "";
 				}
-				nodes.push({ element: "break" });
+				const node = { element: "break" };
+				const span = projectSpan(source, index, spaceEnd + 1);
+				if (span !== void 0) spans.set(node, span);
+				nodes.push(node);
 				index = spaceEnd + 1;
+				pendingStart = index;
 				continue;
 			}
 		}
 		let scanned;
 		let end = index;
 		if (character === "`") {
-			const span = scanCode(source, index, to);
+			const span = scanCode(source.text, index, to);
 			if (span) {
 				scanned = {
 					element: "codeSpan",
@@ -1451,50 +1939,70 @@ function scanInline(source, from, to, depth = 0) {
 				end = span.end;
 			}
 		}
-		if (character === "!" && source[index + 1] === "[") {
-			const link = scanLink(source, index + 1, to, depth);
-			if (link) {
+		if (character === "!" && source.text[index + 1] === "[") {
+			const link = locateLink(source.text, index + 1, to);
+			if (link !== void 0) {
 				scanned = {
 					element: "image",
-					src: link.node.href,
-					children: link.node.children
+					src: unescapeText(source.text.slice(link.close + 2, link.end - 1).trim()),
+					children: coalesceText(scanInlineSource(source, index + 2, link.close, spans, depth + 1), spans)
 				};
 				end = link.end;
 			}
 		}
 		if (character === "[") {
-			const link = scanLink(source, index, to, depth);
-			if (link) {
-				scanned = link.node;
+			const link = locateLink(source.text, index, to);
+			if (link !== void 0) {
+				scanned = {
+					element: "link",
+					href: unescapeText(source.text.slice(link.close + 2, link.end - 1).trim()),
+					children: coalesceText(scanInlineSource(source, index + 1, link.close, spans, depth + 1), spans)
+				};
 				end = link.end;
 			}
 		}
 		if (character === "*" || character === "_") {
-			const emphasis = scanEmphasis(source, index, to, depth);
-			if (emphasis) {
-				scanned = emphasis.node;
+			const emphasis = locateEmphasis(source.text, index, to);
+			if (emphasis !== void 0) {
+				scanned = {
+					element: "emphasis",
+					strong: emphasis.strong,
+					children: coalesceText(scanInlineSource(source, emphasis.open, emphasis.close, spans, depth + 1), spans)
+				};
 				end = emphasis.end;
 			}
 		}
 		if (scanned !== void 0) {
 			if (pending.length > 0) {
-				nodes.push({
+				const node = {
 					element: "text",
 					value: pending
-				});
+				};
+				const span = projectSpan(source, pendingStart, index);
+				if (span !== void 0) spans.set(node, span);
+				nodes.push(node);
 				pending = "";
 			}
+			const span = projectSpan(source, index, end);
+			if (span !== void 0) spans.set(scanned, span);
 			nodes.push(scanned);
 			index = end;
+			pendingStart = index;
 			continue;
 		}
+		if (pending.length === 0) pendingStart = index;
 		pending += character;
 		index += 1;
 	}
-	if (pending.length > 0) nodes.push({
-		element: "text",
-		value: pending
-	});
+	if (pending.length > 0) {
+		const node = {
+			element: "text",
+			value: pending
+		};
+		const span = projectSpan(source, pendingStart, index);
+		if (span !== void 0) spans.set(node, span);
+		nodes.push(node);
+	}
 	return nodes;
 }
 /**
@@ -1503,36 +2011,56 @@ function scanInline(source, from, to, depth = 0) {
 *
 * @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 }
 * ```
 */
-function collectTable(lines, start) {
-	const headerCells = splitTableRow(lines[start] ?? "");
+function collectTable(lines, start, spans = /* @__PURE__ */ new Map()) {
+	const headerCells = splitTableSources(lines[start] ?? {
+		text: "",
+		segments: []
+	});
 	const columns = headerCells.length;
-	const header = headerCells.map((cell) => parseInline(cell.trim()));
-	const align = delimiterToAlignments(lines[start + 1] ?? "");
+	const header = headerCells.map((cell) => {
+		const source = trimSource(cell);
+		return coalesceText(scanInlineSource(source, 0, source.text.length, spans), spans);
+	});
+	const align = delimiterToAlignments(lines[start + 1]?.text ?? "");
 	const padded = [];
 	for (let column = 0; column < columns; column += 1) padded.push(align[column] ?? null);
 	const rows = [];
 	let index = start + 2;
-	while (index < lines.length && !isBlankLine(lines[index] ?? "") && (lines[index] ?? "").includes("|")) {
-		const cells = splitTableRow(lines[index] ?? "");
+	while (index < lines.length && !isBlankLine(lines[index]?.text ?? "") && (lines[index]?.text ?? "").includes("|")) {
+		const cells = splitTableSources(lines[index] ?? {
+			text: "",
+			segments: []
+		});
 		const row = [];
-		for (let column = 0; column < columns; column += 1) row.push(parseInline((cells[column] ?? "").trim()));
+		for (let column = 0; column < columns; column += 1) {
+			const source = trimSource(cells[column] ?? {
+				text: "",
+				segments: []
+			});
+			row.push(coalesceText(scanInlineSource(source, 0, source.text.length, spans), spans));
+		}
 		rows.push(row);
 		index += 1;
 	}
+	const node = {
+		element: "table",
+		header,
+		rows,
+		align: padded
+	};
+	const source = joinSources(lines.slice(start, index), "\n");
+	const span = projectSpan(source, 0, source.text.length);
+	if (span !== void 0) spans.set(node, span);
 	return {
-		node: {
-			element: "table",
-			header,
-			rows,
-			align: padded
-		},
+		node,
 		next: index
 	};
 }
@@ -1543,15 +2071,18 @@ function collectTable(lines, start) {
 * @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 }
 * ```
 */
-function collectList(lines, start, depth) {
-	const first = extractListItem(lines[start] ?? "");
+function collectList(lines, start, depth, spans = /* @__PURE__ */ new Map(), end) {
+	const text = lines.map((line) => line.text);
+	const first = extractListItem(text[start] ?? "");
 	const ordered = first?.ordered ?? false;
 	const startOrdinal = first?.start ?? 1;
 	const topIndent = first?.indent ?? 0;
@@ -1559,7 +2090,7 @@ function collectList(lines, start, depth) {
 	const chain = [];
 	let nested = true;
 	for (let cursor = start; cursor < lines.length; cursor += 1) {
-		const parsed = extractListItem(lines[cursor] ?? "");
+		const parsed = extractListItem(text[cursor] ?? "");
 		const previous = chain[chain.length - 1];
 		if (parsed === void 0 || previous !== void 0 && (previous.content.length > 0 || parsed.indent !== previous.marker)) {
 			nested = false;
@@ -1570,29 +2101,48 @@ function collectList(lines, start, depth) {
 	const remaining = 64 - depth;
 	if (nested && remaining > 0 && chain.length > remaining) {
 		const terminal = chain[remaining - 1];
-		if (terminal !== void 0) {
-			const source = [terminal.content];
-			for (let cursor = start + remaining; cursor < lines.length; cursor += 1) source.push((lines[cursor] ?? "").slice(terminal.marker));
-			let children = [{
+		const terminalLine = lines[start + remaining - 1];
+		if (terminal !== void 0 && terminalLine !== void 0) {
+			const sources = [sliceSource(terminalLine, terminal.marker, terminalLine.text.length)];
+			for (let cursor = start + remaining; cursor < lines.length; cursor += 1) {
+				const line = lines[cursor];
+				if (line !== void 0) sources.push(sliceSource(line, terminal.marker, line.text.length));
+			}
+			const source = joinSources(sources, "\n");
+			const textNode = {
+				element: "text",
+				value: source.text
+			};
+			const paragraph = {
 				element: "paragraph",
-				children: [{
-					element: "text",
-					value: source.join("\n")
-				}]
-			}];
+				children: [textNode]
+			};
+			const residualSpan = projectSpan(source, 0, source.text.length);
+			if (residualSpan !== void 0) {
+				spans.set(textNode, residualSpan);
+				spans.set(paragraph, residualSpan);
+			}
+			let children = [paragraph];
 			let node;
 			for (let cursor = remaining - 1; cursor >= 0; cursor -= 1) {
 				const parsed = chain[cursor];
 				if (parsed === void 0) continue;
+				const item = {
+					element: "listItem",
+					children
+				};
 				node = {
 					element: "list",
 					ordered: parsed.ordered,
 					start: parsed.start,
-					items: [{
-						element: "listItem",
-						children
-					}]
+					items: [item]
 				};
+				const region = joinSources(lines.slice(start + cursor).map((line) => sliceSource(line, parsed.indent, line.text.length)), "\n");
+				const span = projectSpan(region, 0, region.text.length);
+				if (span !== void 0) {
+					spans.set(item, span);
+					spans.set(node, span);
+				}
 				children = [node];
 			}
 			if (node !== void 0) return {
@@ -1603,43 +2153,59 @@ function collectList(lines, start, depth) {
 	}
 	let index = start;
 	while (index < lines.length) {
-		const parsed = extractListItem(lines[index] ?? "");
+		const parsed = extractListItem(text[index] ?? "");
 		if (!parsed || parsed.indent > topIndent || parsed.ordered !== ordered) break;
-		const itemLines = [parsed.content];
+		const itemStart = index;
+		const itemLine = lines[index];
+		if (itemLine === void 0) break;
+		const itemLines = [sliceSource(itemLine, parsed.marker, itemLine.text.length)];
 		const continuation = parsed.marker;
 		index += 1;
 		while (index < lines.length) {
-			const next = lines[index] ?? "";
+			const nextSource = lines[index];
+			if (nextSource === void 0) break;
+			const next = nextSource.text;
 			if (isBlankLine(next)) {
-				const after = lines[index + 1] ?? "";
+				const after = lines[index + 1]?.text ?? "";
 				if (index + 1 < lines.length && !isBlankLine(after) && countIndent(after) >= continuation) {
-					itemLines.push("");
+					itemLines.push(sliceSource(nextSource, 0, 0));
 					index += 1;
 					continue;
 				}
 				break;
 			}
 			if (countIndent(next) >= continuation) {
-				itemLines.push(next.slice(continuation));
+				itemLines.push(sliceSource(nextSource, continuation, next.length));
 				index += 1;
 				continue;
 			}
-			if (extractListItem(next) || startsBlock(lines, index)) break;
-			itemLines.push(next.trim());
+			if (extractListItem(next) || startsBlock(text, index)) break;
+			itemLines.push(trimSource(nextSource));
 			index += 1;
 		}
-		items.push({
+		const tail = itemLines[itemLines.length - 1];
+		const segment = tail?.segments[tail.segments.length - 1];
+		const itemEnd = index === lines.length && end !== void 0 ? end : segment?.end;
+		const item = {
 			element: "listItem",
-			children: parseBlocks(itemLines, depth + 1)
-		});
+			children: parseBlocks(itemLines, depth + 1, spans, itemEnd)
+		};
+		const source = joinSources(lines.slice(itemStart, index), "\n");
+		const span = projectSpan(source, 0, source.text.length);
+		if (span !== void 0) spans.set(item, span);
+		items.push(item);
 	}
+	const node = {
+		element: "list",
+		ordered,
+		start: startOrdinal,
+		items
+	};
+	const source = joinSources(lines.slice(start, index), "\n");
+	const span = projectSpan(source, 0, source.text.length);
+	if (span !== void 0) spans.set(node, span);
 	return {
-		node: {
-			element: "list",
-			ordered,
-			start: startOrdinal,
-			items
-		},
+		node,
 		next: index
 	};
 }
@@ -3170,13 +3736,14 @@ function foldNode(node, handlers, depth) {
 * 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
@@ -3186,11 +3753,11 @@ function foldNode(node, handlers, depth) {
 *
 * @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,
 * )
 * ```
@@ -3203,6 +3770,7 @@ function rewriteDocument(document, rewrite) {
 		count: 0
 	}];
 	const values = [];
+	const derivations = /* @__PURE__ */ new Map();
 	while (stack.length > 0) {
 		const frame = stack.pop();
 		if (frame === void 0) continue;
@@ -3256,6 +3824,7 @@ function rewriteDocument(document, rewrite) {
 		}
 		const children = frame.count === 0 ? [] : values.splice(values.length - frame.count, frame.count);
 		let rebuilt = current;
+		let changed = false;
 		switch (current.element) {
 			case "document": {
 				const blocks = [];
@@ -3263,16 +3832,16 @@ function rewriteDocument(document, rewrite) {
 				for (const block of current.children) {
 					if (block === void 0) continue;
 					const child = children[offset];
-					blocks.push(child !== void 0 && isBlockNode(child) ? child : block);
+					const accepted = child !== void 0 && isBlockNode(child) ? child : block;
+					blocks.push(accepted);
+					if (accepted !== block) changed = true;
 					offset += 1;
 				}
-				const result = {
+				if (changed) rebuilt = {
 					element: "document",
 					children: blocks
 				};
-				if (stack.length === 0) return result;
-				values.push(result);
-				continue;
+				break;
 			}
 			case "heading":
 			case "paragraph": {
@@ -3281,10 +3850,12 @@ function rewriteDocument(document, rewrite) {
 				for (const inline of current.children) {
 					if (inline === void 0) continue;
 					const child = children[offset];
-					inlines.push(child !== void 0 && isInlineNode(child) ? child : inline);
+					const accepted = child !== void 0 && isInlineNode(child) ? child : inline;
+					inlines.push(accepted);
+					if (accepted !== inline) changed = true;
 					offset += 1;
 				}
-				rebuilt = {
+				if (changed) rebuilt = {
 					...current,
 					children: inlines
 				};
@@ -3296,10 +3867,12 @@ function rewriteDocument(document, rewrite) {
 				for (const block of current.children) {
 					if (block === void 0) continue;
 					const child = children[offset];
-					blocks.push(child !== void 0 && isBlockNode(child) ? child : block);
+					const accepted = child !== void 0 && isBlockNode(child) ? child : block;
+					blocks.push(accepted);
+					if (accepted !== block) changed = true;
 					offset += 1;
 				}
-				rebuilt = {
+				if (changed) rebuilt = {
 					...current,
 					children: blocks
 				};
@@ -3311,10 +3884,12 @@ function rewriteDocument(document, rewrite) {
 				for (const block of current.children) {
 					if (block === void 0) continue;
 					const child = children[offset];
-					blocks.push(child !== void 0 && isBlockNode(child) ? child : block);
+					const accepted = child !== void 0 && isBlockNode(child) ? child : block;
+					blocks.push(accepted);
+					if (accepted !== block) changed = true;
 					offset += 1;
 				}
-				rebuilt = {
+				if (changed) rebuilt = {
 					element: "listItem",
 					children: blocks
 				};
@@ -3328,10 +3903,12 @@ function rewriteDocument(document, rewrite) {
 				for (const inline of current.children) {
 					if (inline === void 0) continue;
 					const child = children[offset];
-					inlines.push(child !== void 0 && isInlineNode(child) ? child : inline);
+					const accepted = child !== void 0 && isInlineNode(child) ? child : inline;
+					inlines.push(accepted);
+					if (accepted !== inline) changed = true;
 					offset += 1;
 				}
-				rebuilt = {
+				if (changed) rebuilt = {
 					...current,
 					children: inlines
 				};
@@ -3343,10 +3920,12 @@ function rewriteDocument(document, rewrite) {
 				for (const item of current.items) {
 					if (item === void 0) continue;
 					const child = children[offset];
-					items.push(child?.element === "listItem" ? child : item);
+					const accepted = child?.element === "listItem" ? child : item;
+					items.push(accepted);
+					if (accepted !== item) changed = true;
 					offset += 1;
 				}
-				rebuilt = {
+				if (changed) rebuilt = {
 					...current,
 					items
 				};
@@ -3361,7 +3940,9 @@ function rewriteDocument(document, rewrite) {
 					for (const inline of cell) {
 						if (inline === void 0) continue;
 						const child = children[offset];
-						inlines.push(child !== void 0 && isInlineNode(child) ? child : inline);
+						const accepted = child !== void 0 && isInlineNode(child) ? child : inline;
+						inlines.push(accepted);
+						if (accepted !== inline) changed = true;
 						offset += 1;
 					}
 					header.push(inlines);
@@ -3376,14 +3957,16 @@ function rewriteDocument(document, rewrite) {
 						for (const inline of cell) {
 							if (inline === void 0) continue;
 							const child = children[offset];
-							inlines.push(child !== void 0 && isInlineNode(child) ? child : inline);
+							const accepted = child !== void 0 && isInlineNode(child) ? child : inline;
+							inlines.push(accepted);
+							if (accepted !== inline) changed = true;
 							offset += 1;
 						}
 						cells.push(inlines);
 					}
 					rows.push(cells);
 				}
-				rebuilt = {
+				if (changed) rebuilt = {
 					...current,
 					header,
 					rows
@@ -3391,6 +3974,14 @@ function rewriteDocument(document, rewrite) {
 				break;
 			}
 		}
+		if (rebuilt !== current) derivations.set(rebuilt, current);
+		if (current.element === "document") {
+			const result = rebuilt.element === "document" ? rebuilt : current;
+			const output = new Set(walkNodes(result));
+			const retained = /* @__PURE__ */ new Map();
+			for (const [node, source] of derivations) if (output.has(node)) retained.set(node, source);
+			return [result, retained];
+		}
 		const result = rewrite(rebuilt);
 		let accepted = rebuilt;
 		switch (current.element) {
@@ -3413,12 +4004,13 @@ function rewriteDocument(document, rewrite) {
 				break;
 			case "listItem": if (result.element === "listItem") accepted = result;
 		}
+		if (accepted !== rebuilt && accepted !== current) {
+			if (derivations.has(accepted) && derivations.get(accepted) !== current) derivations.set(accepted, void 0);
+			else derivations.set(accepted, current);
+		}
 		values.push(accepted);
 	}
-	return {
-		element: "document",
-		children: [...document.children]
-	};
+	return [document, /* @__PURE__ */ new Map()];
 }
 /**
 * Concatenate the `value` / `code` content of every descendant text / code-span /
@@ -3542,16 +4134,22 @@ exports.isTextNode = isTextNode;
 exports.isThematicBreak = isThematicBreak;
 exports.isThematicBreakNode = isThematicBreakNode;
 exports.isWhitespace = isWhitespace;
+exports.joinSources = joinSources;
 exports.lineBreakShape = lineBreakShape;
 exports.listItemMatchShape = listItemMatchShape;
+exports.locateEmphasis = locateEmphasis;
+exports.locateLink = locateLink;
 exports.markdownToHTML = markdownToHTML;
 exports.mergeProjections = mergeProjections;
 exports.normalizeInlines = normalizeInlines;
+exports.normalizeParagraphLine = normalizeParagraphLine;
 exports.parseBlocks = parseBlocks;
 exports.parseDocument = parseDocument;
 exports.parseInline = parseInline;
+exports.parseProvenance = parseProvenance;
 exports.projectHTMLLeaf = projectHTMLLeaf;
 exports.projectHTMLNode = projectHTMLNode;
+exports.projectSpan = projectSpan;
 exports.projectionToBlocks = projectionToBlocks;
 exports.projectionToInlines = projectionToInlines;
 exports.renderHTML = renderHTML;
@@ -3560,15 +4158,19 @@ exports.rewriteDocument = rewriteDocument;
 exports.scanCode = scanCode;
 exports.scanEmphasis = scanEmphasis;
 exports.scanInline = scanInline;
+exports.scanInlineSource = scanInlineSource;
 exports.scanLink = scanLink;
+exports.sliceSource = sliceSource;
 exports.splitLines = splitLines;
 exports.splitTableRow = splitTableRow;
+exports.splitTableSources = splitTableSources;
 exports.startsBlock = startsBlock;
 exports.stripQuote = stripQuote;
 exports.tableAlignShape = tableAlignShape;
 exports.textShape = textShape;
 exports.thematicBreakShape = thematicBreakShape;
 exports.trimInlines = trimInlines;
+exports.trimSource = trimSource;
 exports.unescapeText = unescapeText;
 exports.walkNodes = walkNodes;