@orkestrel/markdown 0.0.11 → 0.0.13

package/dist/src/core/index.cjs

@@ -3,17 +3,17 @@ let _orkestrel_contract = require("@orkestrel/contract");
 let _orkestrel_html = require("@orkestrel/html");
 //#region src/core/constants.ts
 /**
-* The maximum recursion depth the parse pipeline (`parseDocument` and its
-* `parsers.ts` helpers) and the `helpers.ts` traversal / projection functions
-* (`markdownToHTML`, `renderHTML`, `renderMarkdown`, `walkNodes`, `foldNode`,
-* `rewriteDocument`) honor before degrading. It bounds blockquote nesting, inline
+* Caps the recursion depth the parse pipeline (`parseDocument` and its
+* `parsers.ts` helpers), the `helpers.ts` traversal / projection functions
+* (`markdownToHTML`, `renderMarkdown`, `walkNodes`, `foldNode`, `rewriteDocument`),
+* and the `compilers.ts` renderer (`renderHTML`) honor before degrading. It bounds blockquote nesting, inline
 * nesting (emphasis / links), and traversal / projection recursion so pathological
 * or hostile input cannot exhaust the call stack. {@link htmlToMarkdown} is the
 * inherited exception: its fold and depth cap belong to `@orkestrel/html`.
 */
 var MAX_DEPTH = 64;
 /**
-* The frozen empty HTML-to-markdown projection from which projection factories
+* Holds the frozen empty HTML-to-markdown projection from which projection factories
 * default every absent field.
 *
 * @example
@@ -32,182 +32,66 @@ var EMPTY_PROJECTION = Object.freeze({
 //#endregion
 //#region src/core/validators.ts
 /**
-* Whether `character` is an inline whitespace character (space / tab / newline) - the
-* emphasis flanking rule's space test.
+* Determines whether a node is a heading block.
 *
-* @param character - The character to test
-* @returns `true` when it is inline whitespace
-*
-* @example
-* ```ts
-* isWhitespace(' ') // true
-* isWhitespace('a') // false
-* ```
-*/
-function isWhitespace(character) {
-	return character === " " || character === "	" || character === "\n";
-}
-/**
-* Whether `character` is escapable by a leading backslash - the ASCII punctuation
-* markdown gives meaning to (so `\*` becomes `*` but `\.` stays `\.`).
-*
-* @param character - The single character after a backslash
-* @returns `true` when a backslash before it is an escape
-*
-* @example
-* ```ts
-* isEscapable('*') // true
-* isEscapable('a') // false
-* ```
-*/
-function isEscapable(character) {
-	return /[\\`*_{}[\]()#+\-.!>~|]/.test(character);
-}
-/**
-* Whether `line` is blank - empty, or containing only whitespace - the markdown
-* definition of a blank line that block parsing uses to separate paragraphs, skip
-* gaps, and end list continuations.
-*
-* @param line - The candidate line
-* @returns `true` when the line is blank
-*
-* @example
-* ```ts
-* isBlankLine('   ') // true
-* ```
-*/
-function isBlankLine(line) {
-	return (0, _orkestrel_contract.isEmptyString)(line.trim());
-}
-/**
-* Whether `line` is a blockquote line (`>` optionally indented up to three spaces) -
-* its content is de-quoted by {@link stripQuote}.
-*
-* @param line - The candidate line
-* @returns `true` when the line begins a blockquote
-*
-* @example
-* ```ts
-* isQuote('> quoted') // true
-* ```
-*/
-function isQuote(line) {
-	return /^\s{0,3}>/.test(line);
-}
-/**
-* Whether `line` closes a fence opened by `marker` - the same fence character, a run
-* at least as long, and nothing else but surrounding whitespace.
-*
-* @param line - The candidate closing line
-* @param marker - The opening fence's marker run (from {@link extractFence})
-* @returns `true` when `line` closes the fence
-*
-* @example
-* ```ts
-* isFenceClose('```', '```') // true
-* ```
-*/
-function isFenceClose(line, marker) {
-	const character = marker[0] === "~" ? "~" : "`";
-	let index = 0;
-	while (index < line.length && isFenceWhitespace(line[index])) index++;
-	let run = 0;
-	while (index < line.length && line[index] === character) {
-		run++;
-		index++;
-	}
-	if (run < marker.length) return false;
-	while (index < line.length && isFenceWhitespace(line[index])) index++;
-	return index === line.length;
-}
-/**
-* Whether `character` is a regex-`\s`-equivalent whitespace character - the
-* character class {@link isFenceClose}'s scan treats as surrounding padding.
-*
-* @param character - The single character to test, or `undefined` past the end of a line
-* @returns `true` when it is whitespace
+* @param node - The AST node to test
+* @returns True if the node is a {@link HeadingNode}; false otherwise
 *
 * @example
 * ```ts
-* isFenceWhitespace(' ')         // true
-* isFenceWhitespace(undefined)   // false
+* isHeadingNode({ element: 'heading', level: 1, children: [] }) // true
 * ```
 */
-function isFenceWhitespace(character) {
-	return character === " " || character === "	" || character === "\n" || character === "\r" || character === "\f" || character === "\v";
+function isHeadingNode(node) {
+	return node.element === "heading";
 }
 /**
-* Whether `line` is a thematic break (horizontal rule) - three or more of the SAME
-* marker `-`, `*`, or `_` (optionally space-separated) and nothing else (`---`,
-* `***`, `___`, `- - -`).
+* Determines whether a node is a paragraph block.
 *
-* @param line - The candidate line
-* @returns `true` when the line is a thematic break
+* @param node - The AST node to test
+* @returns True if the node is a {@link ParagraphNode}; false otherwise
 *
 * @example
 * ```ts
-* isThematicBreak('---') // true
+* isParagraphNode({ element: 'paragraph', children: [] }) // true
 * ```
 */
-function isThematicBreak(line) {
-	const stripped = line.trim().replace(/\s+/g, "");
-	if (stripped.length < 3) return false;
-	const marker = stripped[0];
-	if (marker !== "-" && marker !== "*" && marker !== "_") return false;
-	return [...stripped].every((character) => character === marker);
+function isParagraphNode(node) {
+	return node.element === "paragraph";
 }
 /**
-* Whether the pair (`header`, `delimiter`) opens a GFM table - `delimiter` is a row of
-* `|`-separated cells each matching `:?-+:?`, the GFM rule that a table requires a
-* header row IMMEDIATELY followed by a delimiter row.
+* Determines whether a node is a list block.
 *
-* @param header - The candidate header line
-* @param delimiter - The line after it (the candidate delimiter)
-* @returns `true` when the two lines open a table
+* @param node - The AST node to test
+* @returns True if the node is a {@link ListNode}; false otherwise
 *
 * @example
 * ```ts
-* isTableStart('| a |', '| - |') // true
+* isListNode({ element: 'list', ordered: false, start: 1, items: [] }) // true
 * ```
 */
-function isTableStart(header, delimiter) {
-	if (delimiter === void 0 || !header.includes("|")) return false;
-	const cells = splitTableRow(delimiter);
-	if (cells.length === 0) return false;
-	return cells.every((cell) => /^:?-+:?$/.test(cell.trim()));
-}
-/** Determine whether a node is a heading block. */
-function isHeadingNode(node) {
-	return node.element === "heading";
+function isListNode(node) {
+	return node.element === "list";
 }
 /**
-* Determine whether a node is a paragraph block.
+* Determines whether a node is a GFM table block.
 *
-* @example
-* ```ts
-* isParagraphNode({ element: 'paragraph', children: [] }) // true
-* ```
-*/
-function isParagraphNode(node) {
-	return node.element === "paragraph";
-}
-/**
-* Determine whether a node is a list block.
+* @param node - The AST node to test
+* @returns True if the node is a {@link TableNode}; false otherwise
 *
 * @example
 * ```ts
-* isListNode({ element: 'list', ordered: false, start: 1, items: [] }) // true
+* isTableNode({ element: 'table', header: [], rows: [], align: [] }) // true
 * ```
 */
-function isListNode(node) {
-	return node.element === "list";
-}
-/** Determine whether a node is a GFM table block. */
 function isTableNode(node) {
 	return node.element === "table";
 }
 /**
-* Determine whether a node is a fenced code block.
+* Determines whether a node is a fenced code block.
+*
+* @param node - The AST node to test
+* @returns True if the node is a {@link CodeBlockNode}; false otherwise
 *
 * @example
 * ```ts
@@ -218,7 +102,10 @@ function isCodeBlockNode(node) {
 	return node.element === "codeBlock";
 }
 /**
-* Determine whether a node is a blockquote block.
+* Determines whether a node is a blockquote block.
+*
+* @param node - The AST node to test
+* @returns True if the node is a {@link BlockquoteNode}; false otherwise
 *
 * @example
 * ```ts
@@ -229,7 +116,10 @@ function isBlockquoteNode(node) {
 	return node.element === "blockquote";
 }
 /**
-* Determine whether a node is a thematic break (horizontal rule) block.
+* Determines whether a node is a thematic break (horizontal rule) block.
+*
+* @param node - The AST node to test
+* @returns True if the node is a {@link ThematicBreakNode}; false otherwise
 *
 * @example
 * ```ts
@@ -240,7 +130,10 @@ function isThematicBreakNode(node) {
 	return node.element === "thematicBreak";
 }
 /**
-* Determine whether a node is a plain text run.
+* Determines whether a node is a plain text run.
+*
+* @param node - The AST node to test
+* @returns True if the node is a {@link TextNode}; false otherwise
 *
 * @example
 * ```ts
@@ -251,7 +144,10 @@ function isTextNode(node) {
 	return node.element === "text";
 }
 /**
-* Determine whether a node is an emphasis run (`*em*` / `**strong**`).
+* Determines whether a node is an emphasis run (`*em*` / `**strong**`).
+*
+* @param node - The AST node to test
+* @returns True if the node is an {@link EmphasisNode}; false otherwise
 *
 * @example
 * ```ts
@@ -262,12 +158,15 @@ function isEmphasisNode(node) {
 	return node.element === "emphasis";
 }
 /**
-* Determine whether a node is an inline code span.
+* Determines whether a node is an inline code span.
 *
 * @remarks
 * Narrows to {@link CodeSpanNode} - the node whose `element` discriminant is
 * `'codeSpan'`.
 *
+* @param node - The AST node to test
+* @returns True if the node is a {@link CodeSpanNode}; false otherwise
+*
 * @example
 * ```ts
 * isCodeSpanNode({ element: 'codeSpan', value: 'x' }) // true
@@ -277,7 +176,10 @@ function isCodeSpanNode(node) {
 	return node.element === "codeSpan";
 }
 /**
-* Determine whether a node is a GFM hard line break.
+* Determines whether a node is a GFM hard line break.
+*
+* @param node - The AST node to test
+* @returns True if the node is a {@link LineBreakNode}; false otherwise
 *
 * @example
 * ```ts
@@ -287,12 +189,25 @@ function isCodeSpanNode(node) {
 function isLineBreakNode(node) {
 	return node.element === "break";
 }
-/** Determine whether a node is a link. */
+/**
+* Determines whether a node is a link.
+*
+* @param node - The AST node to test
+* @returns True if the node is a {@link LinkNode}; false otherwise
+*
+* @example
+* ```ts
+* isLinkNode({ element: 'link', href: 'https://example.dev', children: [] }) // true
+* ```
+*/
 function isLinkNode(node) {
 	return node.element === "link";
 }
 /**
-* Determine whether a node is an image.
+* Determines whether a node is an image.
+*
+* @param node - The AST node to test
+* @returns True if the node is an {@link ImageNode}; false otherwise
 *
 * @example
 * ```ts
@@ -303,16 +218,16 @@ function isImageNode(node) {
 	return node.element === "image";
 }
 /**
-* Determine whether an arbitrary value is a valid {@link InlineNode} - a text
+* Determines whether an arbitrary value is a valid {@link InlineNode} - a text
 * run, emphasis, code span, hard break, link, or image, recursively validated.
 *
 * @remarks
 * Total: never throws, even on cyclic or pathologically deep input - every
 * combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
-* throw-contained per the `@orkestrel/contract` guard contract (AGENTS §14).
+* throw-contained per the `@orkestrel/contract` guard contract.
 *
 * @param value - The value to test
-* @returns `true` when `value` is a well-formed {@link InlineNode}
+* @returns True if `value` is a well-formed {@link InlineNode}; false otherwise
 *
 * @example
 * ```ts
@@ -342,19 +257,19 @@ var isInlineNode = (0, _orkestrel_contract.unionOf)((0, _orkestrel_contract.reco
 	children: (0, _orkestrel_contract.arrayOf)((0, _orkestrel_contract.lazyOf)(() => isInlineNode))
 }));
 /**
-* Determine whether an arbitrary value is a valid {@link BlockNode} - a
+* Determines whether an arbitrary value is a valid {@link BlockNode} - a
 * heading, paragraph, list, table, code block, blockquote, or thematic break,
 * recursively validated.
 *
 * @remarks
 * Total: never throws, even on cyclic or pathologically deep input - every
 * combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
-* throw-contained per the `@orkestrel/contract` guard contract (AGENTS §14).
+* throw-contained per the `@orkestrel/contract` guard contract.
 * A list item's shape is inlined here (and in {@link isMarkdownNode}) rather
 * than named separately - it is used at exactly these two sites.
 *
 * @param value - The value to test
-* @returns `true` when `value` is a well-formed {@link BlockNode}
+* @returns True if `value` is a well-formed {@link BlockNode}; false otherwise
 *
 * @example
 * ```ts
@@ -393,19 +308,19 @@ var isBlockNode = (0, _orkestrel_contract.unionOf)((0, _orkestrel_contract.recor
 	children: (0, _orkestrel_contract.arrayOf)((0, _orkestrel_contract.lazyOf)(() => isBlockNode))
 }), (0, _orkestrel_contract.recordOf)({ element: (0, _orkestrel_contract.literalOf)("thematicBreak") }));
 /**
-* Determine whether an arbitrary value is a valid {@link MarkdownNode} - the
+* Determines whether an arbitrary value is a valid {@link MarkdownNode} - the
 * {@link MarkdownDocument} root, a {@link BlockNode}, a {@link ListItemNode}, or
 * an {@link InlineNode}, recursively validated.
 *
 * @remarks
 * Total: never throws, even on cyclic or pathologically deep input - every
 * combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
-* throw-contained per the `@orkestrel/contract` guard contract (AGENTS §14).
+* throw-contained per the `@orkestrel/contract` guard contract.
 * A list item's shape is inlined here (and in {@link isBlockNode}) rather than
 * named separately - it is used at exactly these two sites.
 *
 * @param value - The value to test
-* @returns `true` when `value` is a well-formed {@link MarkdownNode}
+* @returns True if `value` is a well-formed {@link MarkdownNode}; false otherwise
 *
 * @example
 * ```ts
@@ -420,17 +335,17 @@ var isMarkdownNode = (0, _orkestrel_contract.unionOf)((0, _orkestrel_contract.la
 	children: (0, _orkestrel_contract.arrayOf)((0, _orkestrel_contract.lazyOf)(() => isBlockNode))
 }), (0, _orkestrel_contract.lazyOf)(() => isInlineNode));
 /**
-* Determine whether an arbitrary value is a valid {@link MarkdownDocument} -
+* Determines whether an arbitrary value is a valid {@link MarkdownDocument} -
 * the parsed-AST root {@link parseDocument} returns, recursively
 * validated.
 *
 * @remarks
 * Total: never throws, even on cyclic or pathologically deep input - every
 * combinator involved (`recordOf`, `arrayOf`) is throw-contained per the
-* `@orkestrel/contract` guard contract (AGENTS §14).
+* `@orkestrel/contract` guard contract.
 *
 * @param value - The value to test
-* @returns `true` when `value` is a well-formed {@link MarkdownDocument}
+* @returns True if `value` is a well-formed {@link MarkdownDocument}; false otherwise
 *
 * @example
 * ```ts
@@ -452,109 +367,188 @@ 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;
 }
 /**
-* Parses a markdown string into a typed {@link MarkdownDocument} AST via the
+* Parses a markdown string into a typed {@link MarkdownDocument} AST through the
 * block phase.
 *
 * @param markdown - The markdown source to parse.
 * @returns The parsed document.
+*
+* @example
+* ```ts
+* parseDocument('# Hi') // { element: 'document', children: [{ element: 'heading', ... }] }
+* ```
 */
 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.
+*
+* @example
+* ```ts
+* const [document, spans] = parseProvenance('# Hi')
+* spans.get(document) // { start: 0, end: 4 }
+* ```
+*/
+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
@@ -562,462 +556,426 @@ function parseDocument(markdown) {
 *
 * @param text - The inline markdown text to parse.
 * @returns The parsed inline nodes.
+*
+* @example
+* ```ts
+* parseInline('a *b*') // [{ element: 'text', value: 'a ' }, { element: 'emphasis', ... }]
+* ```
 */
 function parseInline(text) {
 	return coalesceText(scanInline(text, 0, text.length));
 }
 //#endregion
-//#region src/core/Markdown.ts
+//#region src/core/helpers.ts
 /**
-* 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.
+* 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.
 *
-* @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.
-* - **Immutable.** {@link map} never mutates the stored AST - it returns a NEW `Markdown`
-*   instance; the document root invariant (`element: 'document'`) always holds.
-* - **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.
+* @param markdown - The raw markdown source
+* @returns The document's lines with their original-string coordinates
 *
 * @example
 * ```ts
-* import { Markdown, isHeadingNode, renderMarkdown } from '@src/core'
-*
-* const markdown = new Markdown('# Title\n\nA **bold** [link](https://x.dev).')
-* const heading = markdown.find(isHeadingNode) // the HeadingNode, or undefined
-* const shouted = markdown.map((node) =>
-*   node.element === 'text' ? { element: 'text', value: node.value.toUpperCase() } : node,
-* )
-* renderMarkdown(shouted.document) // '# TITLE\n\nA **BOLD** [LINK](https://x.dev).'
+* splitLines('a\r\nb') // [{ text: 'a', segments: [{ offset: 0, start: 0, end: 1 }] }, ...]
 * ```
 */
-var Markdown = class Markdown {
-	#document;
-	constructor(input) {
-		this.#document = typeof input === "string" ? parseDocument(input) : input;
-	}
-	/** The stored {@link MarkdownDocument} AST root. */
-	get document() {
-		return this.#document;
+function splitLines(markdown) {
+	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;
 	}
-	/**
-	* 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.
-	*
-	* @example
-	* ```ts
-	* for (const node of markdown.walk()) {
-	*   // every node, depth-first, pre-order, root-inclusive
-	* }
-	*
-	* // also consumable by for-await - JS accepts a sync iterable in for-await
-	* for await (const node of markdown.walk()) {
-	*   // same sequence, no separate async iterator needed
-	* }
-	* ```
-	*/
-	*walk() {
-		yield* walkNodes(this.#document);
+	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
+		});
 	}
-	find(predicate) {
-		for (const node of this.walk()) if (predicate(node)) return node;
+	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;
 	}
-	filter(predicate) {
-		const out = [];
-		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}. */
-	map(rewrite) {
-		return new Markdown(rewriteDocument(this.#document, rewrite));
-	}
-	/** Folds the AST depth-first, pre-order into an accumulator. */
-	reduce(callback, initial) {
-		let accumulator = initial;
-		for (const node of this.walk()) accumulator = callback(accumulator, node);
-		return accumulator;
-	}
-	/** Runs a total catamorphism over the document using a {@link MarkdownHandlers} table. */
-	fold(handlers) {
-		return foldNode(this.#document, handlers, 0);
-	}
-	/**
-	* A web-standard {@link ReadableStream} over the document's top-level block nodes
-	* (shallow, source order) - a fresh, pull-based source per call: one block is
-	* enqueued per `pull`, so a slow reader's backpressure is respected. Cancellable,
-	* async-iterable wherever the platform supports it (Node, Deno), and pipeable
-	* through any {@link TransformStream} / {@link WritableStream}.
-	*
-	* @example
-	* ```ts
-	* // universal - works in every ReadableStream-supporting environment
-	* const reader = markdown.stream().getReader()
-	* for (let result = await reader.read(); !result.done; result = await reader.read()) {
-	*   console.log(result.value) // one BlockNode
-	* }
-	*
-	* // Node / Deno / Firefox support async iteration of ReadableStream natively;
-	* // other environments should use the reader loop above instead.
-	* for await (const block of markdown.stream()) {
-	*   console.log(block)
-	* }
-	* ```
-	*/
-	stream() {
-		const blocks = this.#document.children;
-		let index = 0;
-		return new ReadableStream({ pull(controller) {
-			if (index < blocks.length) {
-				const block = blocks[index];
-				if (block === void 0) {
-					controller.close();
-					return;
-				}
-				controller.enqueue(block);
-				index += 1;
-			} else controller.close();
-		} });
-	}
-};
-//#endregion
-//#region src/core/shapers.ts
+	return {
+		text,
+		segments
+	};
+}
 /**
-* The shape of a {@link TextNode} - a plain-text leaf inline run.
+* 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
-* import { createContract } from '@orkestrel/contract'
-* import { textShape } from '@src/core'
-*
-* const text = createContract(textShape)
-* text.is({ element: 'text', value: 'hi' }) // true
+* projectSpan({ text: 'a', segments: [{ offset: 0, start: 4, end: 5 }] }, 0, 1)
+* // { start: 4, end: 5 }
 * ```
 */
-var textShape = (0, _orkestrel_contract.objectShape)({
-	element: (0, _orkestrel_contract.literalShape)(["text"]),
-	value: (0, _orkestrel_contract.stringShape)()
-});
+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
+	};
+}
 /**
-* The shape of a {@link CodeSpanNode} - an inline code span (`` `code` ``).
+* 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
-* import { createContract } from '@orkestrel/contract'
-* import { codeSpanShape } from '@src/core'
-*
-* const codeSpan = createContract(codeSpanShape)
-* codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
+* trimSource({ text: ' a ', segments: [{ offset: 0, start: 4, end: 7 }] })
+* // { text: 'a', segments: [{ offset: 0, start: 5, end: 6 }] }
 * ```
 */
-var codeSpanShape = (0, _orkestrel_contract.objectShape)({
-	element: (0, _orkestrel_contract.literalShape)(["codeSpan"]),
-	value: (0, _orkestrel_contract.stringShape)()
-});
+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));
+}
 /**
-* The shape of a {@link LineBreakNode} - a GFM hard line-break leaf.
+* 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
-* import { createContract } from '@orkestrel/contract'
-* import { lineBreakShape } from '@src/core'
-*
-* const lineBreak = createContract(lineBreakShape)
-* lineBreak.is({ element: 'break' }) // true
+* normalizeParagraphLine(splitLines('text   \nnext')[0], true).text // 'text  '
 * ```
 */
-var lineBreakShape = (0, _orkestrel_contract.objectShape)({ element: (0, _orkestrel_contract.literalShape)(["break"]) });
+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 shape of a {@link CodeBlockNode} - a fenced code block. `lang` is
-* optional (absent when the opening fence carries no info-string).
+* Counts the leading space / tab characters on `line` (a tab counts as one) - the
+* indent that decides whether a list item's continuation belongs to the item.
+*
+* @param line - The line to measure
+* @returns The number of leading space / tab characters
 *
 * @example
 * ```ts
-* import { createContract } from '@orkestrel/contract'
-* import { codeBlockShape } from '@src/core'
-*
-* const codeBlock = createContract(codeBlockShape)
-* codeBlock.is({ element: 'codeBlock', code: 'x' })                    // true
-* codeBlock.is({ element: 'codeBlock', code: 'x', lang: 'ts' })        // true
+* countIndent('  text') // 2
 * ```
 */
-var codeBlockShape = (0, _orkestrel_contract.objectShape)({
-	element: (0, _orkestrel_contract.literalShape)(["codeBlock"]),
-	lang: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.stringShape)()),
-	code: (0, _orkestrel_contract.stringShape)()
-});
+function countIndent(line) {
+	let count = 0;
+	for (const character of line) if (character === " " || character === "	") count += 1;
+	else break;
+	return count;
+}
 /**
-* The shape of a {@link ThematicBreakNode} - a horizontal rule. Carries no
-* fields beyond its `element` discriminant.
+* Checks whether `character` is whitespace under the emphasis flanking rule - a space, a
+* tab, or a newline.
+*
+* @param character - The character to test
+* @returns True if the flanking rule counts it as whitespace; false otherwise
 *
 * @example
 * ```ts
-* import { createContract } from '@orkestrel/contract'
-* import { thematicBreakShape } from '@src/core'
-*
-* const thematicBreak = createContract(thematicBreakShape)
-* thematicBreak.is({ element: 'thematicBreak' }) // true
+* isFlankingWhitespace(' ') // true
+* isFlankingWhitespace('a') // false
 * ```
 */
-var thematicBreakShape = (0, _orkestrel_contract.objectShape)({ element: (0, _orkestrel_contract.literalShape)(["thematicBreak"]) });
+function isFlankingWhitespace(character) {
+	return character === " " || character === "	" || character === "\n";
+}
 /**
-* The shape of a {@link TableAlign} - the per-column GFM table alignment
-* literal.
+* Checks whether `character` is escapable by a leading backslash - the ASCII punctuation
+* markdown gives meaning to (so `\*` becomes `*` but `\.` stays `\.`).
+*
+* @param character - The single character after a backslash
+* @returns True if a backslash before it is an escape; false otherwise
 *
 * @example
 * ```ts
-* import { createContract } from '@orkestrel/contract'
-* import { tableAlignShape } from '@src/core'
-*
-* const tableAlign = createContract(tableAlignShape)
-* tableAlign.is('left')   // true
-* tableAlign.is('center') // true
-* tableAlign.is('top')    // false
+* isEscapable('*') // true
+* isEscapable('a') // false
 * ```
 */
-var tableAlignShape = (0, _orkestrel_contract.literalShape)([
-	"left",
-	"right",
-	"center"
-]);
+function isEscapable(character) {
+	return /[\\`*_{}[\]()#+\-.!>~|]/.test(character);
+}
 /**
-* The shape of {@link ListItemMatch} - the parsed parts of a single list-item
-* line the block phase's list detector returns. Fully non-recursive (no
-* nested node fields), so every field shapes directly.
+* Checks whether `line` is blank - empty, or containing only whitespace - the markdown
+* definition of a blank line that block parsing uses to separate paragraphs, skip
+* gaps, and end list continuations.
+*
+* @param line - The candidate line
+* @returns True if the line is blank; false otherwise
 *
 * @example
 * ```ts
-* import { createContract } from '@orkestrel/contract'
-* import { listItemMatchShape } from '@src/core'
-*
-* const listItemParts = createContract(listItemMatchShape)
-* listItemParts.is({ ordered: false, start: 1, content: 'hi', indent: 0, marker: 2 }) // true
+* isBlankLine('   ') // true
 * ```
 */
-var listItemMatchShape = (0, _orkestrel_contract.objectShape)({
-	ordered: (0, _orkestrel_contract.booleanShape)(),
-	start: (0, _orkestrel_contract.integerShape)(),
-	content: (0, _orkestrel_contract.stringShape)(),
-	indent: (0, _orkestrel_contract.integerShape)(),
-	marker: (0, _orkestrel_contract.integerShape)()
-});
-//#endregion
-//#region src/core/factories.ts
+function isBlankLine(line) {
+	return (0, _orkestrel_contract.isEmptyString)(line.trim());
+}
 /**
-* Create an HTML-to-markdown projection with absent fields defaulted from
-* {@link EMPTY_PROJECTION} and the block/inline exclusivity invariant enforced.
-*
-* @remarks
-* A block-bearing projection cannot also expose inline content. Callers may provide
-* both views, but `inlines` is flushed whenever `blocks` is non-empty.
+* Checks whether `line` is a blockquote line (`>` optionally indented up to three spaces) -
+* its content is de-quoted by {@link stripQuote}.
 *
-* @param parts - The projection fields to provide
-* @returns A complete invariant-preserving projection
+* @param line - The candidate line
+* @returns True if the line begins a blockquote; false otherwise
 *
 * @example
 * ```ts
-* createProjection({
-*   blocks: [{ element: 'thematicBreak' }],
-*   inlines: [{ element: 'text', value: 'discarded' }],
-* })
-* // { blocks: [{ element: 'thematicBreak' }], inlines: [], text: '', cells: [], rows: [] }
+* isQuote('> quoted') // true
 * ```
 */
-function createProjection(parts = {}) {
-	const blocks = parts.blocks ?? EMPTY_PROJECTION.blocks;
-	return {
-		blocks,
-		inlines: blocks.length === 0 ? parts.inlines ?? EMPTY_PROJECTION.inlines : [],
-		text: parts.text ?? EMPTY_PROJECTION.text,
-		cells: parts.cells ?? EMPTY_PROJECTION.cells,
-		rows: parts.rows ?? EMPTY_PROJECTION.rows
-	};
+function isQuote(line) {
+	return /^\s{0,3}>/.test(line);
 }
 /**
-* Create a stateful markdown handle from a markdown string or an already-parsed
-* {@link MarkdownDocument} - a typed AST plus the query, rewrite, and fold operations
-* {@link MarkdownInterface} exposes.
-*
-* @remarks
-* Given a `string`, runs a block phase (headings / paragraphs / lists / GFM tables /
-* fenced code / blockquotes / thematic breaks) then an inline phase (emphasis /
-* inline code / links / images / hard breaks) to build a render-agnostic
-* {@link MarkdownDocument}. Given a
-* {@link MarkdownDocument}, adopts it AS-IS without re-validation - gate an untrusted
-* value with `isMarkdownDocument` first. Pure + total parse (malformed markdown
-* degrades to text, never throws) and zero-dependency - a hand-written scanner, no
-* regex-only structural parse, linear-time (no ReDoS).
+* Checks whether `line` closes a fence opened by `marker` - the same fence character, a run
+* at least as long, and nothing else but surrounding whitespace.
 *
-* @param input - A markdown string to parse, or an already-parsed {@link MarkdownDocument}
-* @returns A working {@link MarkdownInterface}
+* @param line - The candidate closing line
+* @param marker - The opening fence's marker run (from {@link extractFence})
+* @returns True if `line` closes the fence; false otherwise
 *
 * @example
 * ```ts
-* import { createMarkdown } from '@src/core'
-*
-* const markdown = createMarkdown('# Hi\n\nRead the [guide](./guide.md).')
-* markdown.document.children[0] // { element: 'heading', ... }
+* isFenceClose('```', '```') // true
 * ```
 */
-function createMarkdown(input) {
-	return new Markdown(input);
+function isFenceClose(line, marker) {
+	const character = marker[0] === "~" ? "~" : "`";
+	let index = 0;
+	while (index < line.length && isFenceWhitespace(line[index])) index++;
+	let run = 0;
+	while (index < line.length && line[index] === character) {
+		run++;
+		index++;
+	}
+	if (run < marker.length) return false;
+	while (index < line.length && isFenceWhitespace(line[index])) index++;
+	return index === line.length;
 }
 /**
-* Compile the {@link textShape} into a {@link ContractInterface} for
-* {@link TextNode} - a guard, coercing parser, JSON Schema, and seeded
-* generator from one shape declaration (AGENTS §14).
+* Checks whether `character` is a regex-`\s`-equivalent whitespace character - the
+* character class {@link isFenceClose}'s scan treats as surrounding padding.
 *
-* @returns A `TextNode` contract bundling `schema` / `is` / `parse` / `generate`
+* @param character - The single character to test, or `undefined` past the end of a line
+* @returns True if it is whitespace; false otherwise
 *
 * @example
 * ```ts
-* import { createTextContract } from '@src/core'
-*
-* const text = createTextContract()
-* text.is({ element: 'text', value: 'hi' }) // true
+* isFenceWhitespace(' ')         // true
+* isFenceWhitespace(undefined)   // false
 * ```
 */
-function createTextContract() {
-	return (0, _orkestrel_contract.createContract)(textShape);
+function isFenceWhitespace(character) {
+	return character === " " || character === "	" || character === "\n" || character === "\r" || character === "\f" || character === "\v";
 }
 /**
-* Compile the {@link codeSpanShape} into a {@link ContractInterface} for
-* {@link CodeSpanNode} - a guard, coercing parser, JSON Schema, and seeded
-* generator from one shape declaration (AGENTS §14).
+* Checks whether `line` is a thematic break (horizontal rule) - three or more of the SAME
+* marker `-`, `*`, or `_` (optionally space-separated) and nothing else (`---`,
+* `***`, `___`, `- - -`).
 *
-* @returns A `CodeSpanNode` contract bundling `schema` / `is` / `parse` / `generate`
+* @param line - The candidate line
+* @returns True if the line is a thematic break; false otherwise
 *
 * @example
 * ```ts
-* import { createCodeSpanContract } from '@src/core'
-*
-* const codeSpan = createCodeSpanContract()
-* codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
-* ```
-*/
-function createCodeSpanContract() {
-	return (0, _orkestrel_contract.createContract)(codeSpanShape);
-}
-/**
-* Compile the {@link lineBreakShape} into a {@link ContractInterface} for
-* {@link LineBreakNode}.
-*
-* @returns A `LineBreakNode` contract bundling `schema` / `is` / `parse` / `generate`
-*
-* @example
-* ```ts
-* import { createLineBreakContract } from '@src/core'
-*
-* createLineBreakContract().is({ element: 'break' }) // true
-* ```
-*/
-function createLineBreakContract() {
-	return (0, _orkestrel_contract.createContract)(lineBreakShape);
-}
-/**
-* Compile the {@link codeBlockShape} into a {@link ContractInterface} for
-* {@link CodeBlockNode} - a guard, coercing parser, JSON Schema, and seeded
-* generator from one shape declaration (AGENTS §14).
-*
-* @returns A `CodeBlockNode` contract bundling `schema` / `is` / `parse` / `generate`
-*
-* @example
-* ```ts
-* import { createCodeBlockContract } from '@src/core'
-*
-* const codeBlock = createCodeBlockContract()
-* codeBlock.is({ element: 'codeBlock', code: 'x' }) // true
-* ```
-*/
-function createCodeBlockContract() {
-	return (0, _orkestrel_contract.createContract)(codeBlockShape);
-}
-/**
-* Compile the {@link thematicBreakShape} into a {@link ContractInterface} for
-* {@link ThematicBreakNode} - a guard, coercing parser, JSON Schema, and
-* seeded generator from one shape declaration (AGENTS §14).
-*
-* @returns A `ThematicBreakNode` contract bundling `schema` / `is` / `parse` / `generate`
-*
-* @example
-* ```ts
-* import { createThematicBreakContract } from '@src/core'
-*
-* const thematicBreak = createThematicBreakContract()
-* thematicBreak.is({ element: 'thematicBreak' }) // true
-* ```
-*/
-function createThematicBreakContract() {
-	return (0, _orkestrel_contract.createContract)(thematicBreakShape);
-}
-//#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.
-*
-* @param markdown - The raw markdown source
-* @returns The document's lines, line-terminators stripped
-*
-* @example
-* ```ts
-* splitLines('a\r\nb\nc') // ['a', 'b', 'c']
+* isThematicBreak('---') // true
 * ```
 */
-function splitLines(markdown) {
-	const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
-	if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
-	return lines;
+function isThematicBreak(line) {
+	const stripped = line.trim().replace(/\s+/g, "");
+	if (stripped.length < 3) return false;
+	const marker = stripped[0];
+	if (marker !== "-" && marker !== "*" && marker !== "_") return false;
+	return [...stripped].every((character) => character === marker);
 }
 /**
-* 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.
+* Checks whether the pair (`header`, `delimiter`) opens a GFM table - `delimiter` is a row of
+* `|`-separated cells each matching `:?-+:?`, the GFM rule that a table requires a
+* header row IMMEDIATELY followed by a delimiter row.
 *
-* @param line - The line to measure
-* @returns The number of leading space / tab characters
+* @param header - The candidate header line
+* @param delimiter - The line after it (the candidate delimiter)
+* @returns True if the two lines open a table; false otherwise
 *
 * @example
 * ```ts
-* countIndent('  text') // 2
+* isTableStart('| a |', '| - |') // true
 * ```
 */
-function countIndent(line) {
-	let count = 0;
-	for (const character of line) if (character === " " || character === "	") count += 1;
-	else break;
-	return count;
+function isTableStart(header, delimiter) {
+	if (delimiter === void 0 || !header.includes("|")) return false;
+	const cells = splitTableRow(delimiter);
+	if (cells.length === 0) return false;
+	return cells.every((cell) => /^:?-+:?$/.test(cell.trim()));
 }
 /**
-* 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
 	};
 }
 /**
-* Extract a fenced-code opening line (```` ``` ```` or `~~~`, optionally with an info
+* Extracts a fenced-code opening line (```` ``` ```` or `~~~`, optionally with an info
 * string) into its `{ marker, lang }`, or `undefined` when `line` is not a fence
 * opener. `marker` is the exact fence run (the closer must match the same character +
 * at least the same length); `lang` is the first word of the info string.
@@ -1042,7 +1000,7 @@ function extractFence(line) {
 	};
 }
 /**
-* Extract a list-item line (`-` / `*` / `+` bullet, or `1.` / `1)` ordinal, followed by
+* Extracts a list-item line (`-` / `*` / `+` bullet, or `1.` / `1)` ordinal, followed by
 * a space) into its {@link ListItemMatch}, or `undefined` when `line` is not a list
 * item. `content` is the text after the marker; `marker` is the full marker-plus-space
 * width (for measuring a continuation's indent).
@@ -1082,24 +1040,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
+* Splits one GFM table row into its cell strings - outer pipes are optional, an escaped
 * pipe (`\|`) inside a cell is NOT a separator (it becomes a literal `|`), and the
-* empty leading / trailing cell produced by an outer `|` is dropped.
+* empty leading / trailing cell produced by an outer `|` is dropped. Derives the string
+* form from {@link splitTableSources}, which owns the escaped-pipe splitting rule.
 *
 * @param row - The raw table row line
 * @returns The row's cells, in column order
@@ -1110,26 +1071,59 @@ 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;
 }
 /**
-* Derive the per-column {@link TableAlign} list from a GFM delimiter row - `:---`
+* Derives the per-column {@link TableAlign} list from a GFM delimiter row - `:---`
 * left, `---:` right, `:---:` center, and `---` as the explicit no-alignment
 * marker represented by `null`.
 *
@@ -1153,7 +1147,7 @@ function delimiterToAlignments(delimiter) {
 	});
 }
 /**
-* Whether the line at `index` starts a NEW block kind (heading / fence / thematic
+* Checks whether the line at `index` starts a NEW block kind (heading / fence / thematic
 * break / blockquote / list / table) - the paragraph collector stops at such a line
 * so a block following a paragraph without a blank line still parses (a trusted-input
 * caller writing a `##` heading directly under a paragraph, with no intervening blank
@@ -1161,7 +1155,7 @@ function delimiterToAlignments(delimiter) {
 *
 * @param lines - The document's lines
 * @param index - The line index to test
-* @returns `true` when the line begins a different block
+* @returns True if the line begins a different block; false otherwise
 *
 * @example
 * ```ts
@@ -1173,7 +1167,7 @@ function startsBlock(lines, index) {
 	return extractHeading(line) !== void 0 || extractFence(line) !== void 0 || isThematicBreak(line) || isQuote(line) || extractListItem(line) !== void 0 || isTableStart(line, lines[index + 1]);
 }
 /**
-* Resolve backslash escapes in a raw string to their literal characters - used for a
+* Resolves backslash escapes in a raw string to their literal characters - used for a
 * link `href` (which is not otherwise inline-parsed) and any plain text run.
 *
 * @param text - The raw text possibly carrying `\x` escapes
@@ -1196,10 +1190,11 @@ function unescapeText(text) {
 	return out;
 }
 /**
-* Merge adjacent text nodes into one - the inline scanner emits a text node per
+* Merges adjacent text nodes into one - the inline scanner emits a text node per
 * unrecognized character, so coalescing keeps the AST clean and assertion-friendly.
 *
 * @param nodes - The inline nodes (possibly with adjacent text runs)
+* @param spans - The optional operation-owned node span recorder
 * @returns The nodes with consecutive text nodes concatenated
 *
 * @example
@@ -1208,20 +1203,32 @@ 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;
 }
 /**
-* Scan an inline code span at `start` (a `` ` ``-run … a matching `` ` ``-run of the
+* Scans an inline code span at `start` (a `` ` ``-run … a matching `` ` ``-run of the
 * SAME length, the CommonMark rule that lets a span contain backticks). Returns the
 * span's literal text + end index, or `undefined` when no matching closer exists (it
 * then degrades to literal backticks).
@@ -1256,26 +1263,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,44 +1315,69 @@ 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;
 	const strong = run === 2;
 	const openEnd = start + run;
-	if (openEnd >= to || isWhitespace(source[openEnd] ?? "")) return void 0;
+	if (openEnd >= to || isFlankingWhitespace(source[openEnd] ?? "")) return void 0;
 	let index = openEnd;
 	while (index < to) {
 		const character = source[index] ?? "";
@@ -1363,7 +1391,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;
@@ -1372,12 +1400,10 @@ function scanEmphasis(source, start, to, depth = 0) {
 		if (character === marker) {
 			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)
-				},
+			if (closeRun >= run && !isFlankingWhitespace(source[index - 1] ?? "")) return {
+				strong,
+				open: openEnd,
+				close: index,
 				end: index + run
 			};
 			index += closeRun;
@@ -1387,7 +1413,41 @@ function scanEmphasis(source, start, to, depth = 0) {
 	}
 }
 /**
-* Scan the window `[from, to)` of `source` into inline nodes - the single recursive
+* 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
+	};
+}
+/**
+* Scans the window `[from, to)` of `source` into inline nodes - the single recursive
 * engine the inline phase runs on (emphasis, link text, and image alternative
 * content recurse through it). Linear:
 * each character is consumed once; a failed construct emits its opening character as
@@ -1397,10 +1457,11 @@ function scanEmphasis(source, start, to, depth = 0) {
 * @param from - The inclusive start of the scan window
 * @param to - The exclusive end of the scan window
 * @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
-*   incremented by one on every recursive descent through {@link scanLink} /
-*   {@link scanEmphasis}. At {@link MAX_DEPTH} the window is never scanned for markup -
-*   it emits as a single literal text node - so pathological nesting (`[[[[…`,
-*   `****…`) cannot exhaust the call stack.
+*   incremented by one on every recursive descent {@link scanInlineSource} makes into
+*   itself for a link's text, an image's alternative content, or an emphasis run's
+*   children. At {@link MAX_DEPTH} the window is never scanned for markup - it emits as
+*   a single literal text node - so pathological nesting (`[[[[…`, `****…`) cannot
+*   exhaust the call stack.
 * @returns The parsed inline nodes (NOT yet coalesced)
 *
 * @example
@@ -1409,40 +1470,88 @@ 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, incremented by one on every
+*   recursive descent this function makes into itself for a link's text, an image's
+*   alternative content, or an emphasis run's children
+* @returns The parsed inline nodes before adjacent text coalescing
+*
+* @example
+* ```ts
+* scanInlineSource(
+* 	{ text: 'hi *there*', segments: [{ offset: 0, start: 0, end: 10 }] },
+* 	0,
+* 	10,
+* 	new Map(),
+* )
+* // [{ element: 'text', value: 'hi ' }, { element: 'emphasis', ... }]
+* ```
+*/
+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 +1560,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 +1632,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 +1692,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 +1711,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 +1722,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,48 +1774,64 @@ 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
 	};
 }
 /**
-* Project a {@link MarkdownNode} into an unsanitized {@link HTMLDocument}.
+* Projects a {@link MarkdownNode} into an unsanitized {@link HTMLDocument}.
 *
 * @remarks
 * The projection is pure and iterative. Text and attribute values remain literal for
@@ -1973,29 +2160,7 @@ function markdownToHTML(node) {
 	};
 }
 /**
-* Render a {@link MarkdownNode} to sanitized canonical HTML.
-*
-* @remarks
-* Markdown widens `@orkestrel/html`'s attribute floor by exactly `src`, because image
-* syntax is meaningless without its source. `src` is still a URL attribute, so the
-* floor refuses `javascript:`, `data:`, `vbscript:`, and `file:` values. A stricter
-* consumer can compose {@link markdownToHTML} with `@orkestrel/html`'s `HTML` class
-* directly.
-*
-* @param node - The markdown document or bare node to render
-* @returns Sanitized canonical HTML
-*
-* @example
-* ```ts
-* renderHTML({ element: 'paragraph', children: [{ element: 'text', value: 'a & b' }] })
-* // '<p>a &amp; b</p>'
-* ```
-*/
-function renderHTML(node) {
-	return (0, _orkestrel_html.renderHTML)(new _orkestrel_html.HTML(markdownToHTML(node)).sanitize({ attributes: [..._orkestrel_html.SAFE_ATTRIBUTES, "src"] }).document);
-}
-/**
-* Render a {@link MarkdownNode} to its CANONICAL markdown source - the inverse
+* Renders a {@link MarkdownNode} to its CANONICAL markdown source - the inverse
 * projection of `renderHTML`, and the serializer a `parse(renderMarkdown(doc))`
 * round-trip is built on. Canonical forms: `*` / `**` emphasis at even emphasis
 * nesting depths and `_` / `__` at odd depths, `- ` bullets, `N. ` sequential
@@ -2004,8 +2169,8 @@ function renderHTML(node) {
 * `> `-prefixed blockquote lines, GFM tables (1-space-padded cells, `\|`-escaped
 * pipes, an alignment delimiter row), `[text](href)` links, `![alt](src)` images,
 * and two-space hard breaks. A `text` node's literal content is backslash-escaped
-* wherever it would otherwise re-parse as markup (AGENTS §14 parse↔render
-* soundness).
+* wherever it would otherwise re-parse as markup, so parsing the rendered source
+* returns the node it was rendered from.
 *
 * @remarks
 * Total: never throws. At {@link MAX_DEPTH} a value-bearing node degrades to its
@@ -2290,31 +2455,61 @@ function renderMarkdown(node) {
 	return "";
 }
 /**
-* Trim the whitespace at the two ends of an inline run - the leading whitespace of a
-* leading text node and the trailing whitespace of a trailing one - dropping either
-* node when nothing survives.
+* Builds an HTML-to-markdown projection with absent fields defaulted from
+* {@link EMPTY_PROJECTION} and the block/inline exclusivity invariant enforced.
 *
 * @remarks
-* Markdown trims every line of a paragraph, a heading's text, and a table cell, so an
-* untrimmed run would come back from a re-parse a different AST. Expects a coalesced
-* run (see {@link coalesceText}): only the outermost node on each side is examined.
+* A block-bearing projection cannot also expose inline content. Callers may provide
+* both views, but `inlines` is flushed whenever `blocks` is non-empty.
 *
-* @param nodes - The inline run to trim
-* @returns The run with its edge whitespace removed
+* @param parts - The projection fields to provide
+* @returns A complete invariant-preserving projection
 *
 * @example
 * ```ts
-* trimInlines([{ element: 'text', value: ' a ' }]) // [{ element: 'text', value: 'a' }]
+* createProjection({
+*   blocks: [{ element: 'thematicBreak' }],
+*   inlines: [{ element: 'text', value: 'discarded' }],
+* })
+* // { blocks: [{ element: 'thematicBreak' }], inlines: [], text: '', cells: [], rows: [] }
 * ```
 */
-function trimInlines(nodes) {
-	const out = [];
-	for (const node of nodes) if (node !== void 0) out.push(node);
-	const first = out[0];
-	if (first !== void 0 && first.element === "text") {
-		const value = first.value.replace(/^\s+/, "");
-		if ((0, _orkestrel_contract.isEmptyString)(value)) out.shift();
-		else out[0] = {
+function createProjection(parts = {}) {
+	const blocks = parts.blocks ?? EMPTY_PROJECTION.blocks;
+	return {
+		blocks,
+		inlines: blocks.length === 0 ? parts.inlines ?? EMPTY_PROJECTION.inlines : [],
+		text: parts.text ?? EMPTY_PROJECTION.text,
+		cells: parts.cells ?? EMPTY_PROJECTION.cells,
+		rows: parts.rows ?? EMPTY_PROJECTION.rows
+	};
+}
+/**
+* Trims the whitespace at the two ends of an inline run - the leading whitespace of a
+* leading text node and the trailing whitespace of a trailing one - dropping either
+* node when nothing survives.
+*
+* @remarks
+* Markdown trims every line of a paragraph, a heading's text, and a table cell, so an
+* untrimmed run would come back from a re-parse a different AST. Expects a coalesced
+* run (see {@link coalesceText}): only the outermost node on each side is examined.
+*
+* @param nodes - The inline run to trim
+* @returns The run with its edge whitespace removed
+*
+* @example
+* ```ts
+* trimInlines([{ element: 'text', value: ' a ' }]) // [{ element: 'text', value: 'a' }]
+* ```
+*/
+function trimInlines(nodes) {
+	const out = [];
+	for (const node of nodes) if (node !== void 0) out.push(node);
+	const first = out[0];
+	if (first !== void 0 && first.element === "text") {
+		const value = first.value.replace(/^\s+/, "");
+		if ((0, _orkestrel_contract.isEmptyString)(value)) out.shift();
+		else out[0] = {
 			element: "text",
 			value
 		};
@@ -2331,7 +2526,7 @@ function trimInlines(nodes) {
 	return out;
 }
 /**
-* Reduce an inline run to the shape markdown can actually write back: adjacent text
+* Reduces an inline run to the shape markdown can actually write back: adjacent text
 * coalesced, empty text dropped, and every hard break either kept as a real line
 * ending or spent as a space.
 *
@@ -2344,8 +2539,8 @@ function trimInlines(nodes) {
 * becomes the space it stood for.
 *
 * @param nodes - The inline run to normalize
-* @param breaks - Whether the target context can carry a hard break at all; `false` for
-*   a heading or a table cell, where every break becomes a space
+* @param breaks - If `true`, keeps each hard break as a real line ending; if `false`, spends
+*   every break as the space it stood for, as a heading or a table cell requires
 * @returns The normalized run
 *
 * @example
@@ -2396,7 +2591,7 @@ function normalizeInlines(nodes, breaks) {
 	return coalesceText(out);
 }
 /**
-* Combine the projections of one node's children into the projection of that node -
+* Combines the projections of one node's children into the projection of that node -
 * the single place inline runs become paragraphs, so no ancestor has to decide it
 * twice.
 *
@@ -2483,7 +2678,7 @@ function mergeProjections(children) {
 	});
 }
 /**
-* Read a projection as BLOCK content - the view a document, a blockquote, and a list
+* Reads a projection as BLOCK content - the view a document, a blockquote, and a list
 * item each need.
 *
 * @remarks
@@ -2529,7 +2724,7 @@ function projectionToBlocks(projection) {
 	return blocks;
 }
 /**
-* Read a projection as INLINE content - the view a link, an emphasis, and a table cell
+* Reads a projection as INLINE content - the view a link, an emphasis, and a table cell
 * each need.
 *
 * @remarks
@@ -2549,14 +2744,14 @@ function projectionToBlocks(projection) {
 */
 function projectionToInlines(projection) {
 	if (!(0, _orkestrel_contract.isNonEmptyArray)(projection.blocks) && !(0, _orkestrel_contract.isNonEmptyArray)(projection.cells) && !(0, _orkestrel_contract.isNonEmptyArray)(projection.rows)) return coalesceText(projection.inlines);
-	const value = projectionToBlocks(projection).map(flattenText).join(" ").replace(/\s+/g, " ").trim();
+	const value = (0, _orkestrel_html.collapseSpace)(projectionToBlocks(projection).map(flattenText).join(" "));
 	return (0, _orkestrel_contract.isEmptyString)(value) ? [] : [{
 		element: "text",
 		value
 	}];
 }
 /**
-* Project one HTML leaf - a text node, a comment, or a doctype - to its
+* Projects one HTML leaf - a text node, a comment, or a doctype - to its
 * {@link MarkdownProjection}.
 *
 * @remarks
@@ -2586,7 +2781,7 @@ function projectHTMLLeaf(leaf) {
 	});
 }
 /**
-* Project one HTML container - the document root or an element - from its children's
+* Projects one HTML container - the document root or an element - from its children's
 * already-computed projections. THE element mapping, and the only place that decides
 * what an HTML tag becomes in markdown.
 *
@@ -2735,7 +2930,7 @@ function projectHTMLNode(node, children) {
 			text: merged.text
 		});
 		case "img": {
-			const alt = ((0, _orkestrel_html.attributeOf)(node, "alt") ?? "").replace(/\s+/g, " ").trim();
+			const alt = (0, _orkestrel_html.collapseSpace)((0, _orkestrel_html.attributeOf)(node, "alt") ?? "");
 			return createProjection({
 				inlines: [{
 					element: "image",
@@ -2893,7 +3088,7 @@ function projectHTMLNode(node, children) {
 	return merged;
 }
 /**
-* Project an `@orkestrel/html` {@link HTMLNode} into a {@link MarkdownDocument} - the
+* Projects an `@orkestrel/html` {@link HTMLNode} into a {@link MarkdownDocument} - the
 * HTML→markdown direction, and the inverse of {@link markdownToHTML}.
 *
 * @remarks
@@ -2949,7 +3144,7 @@ function htmlToMarkdown(node) {
 	};
 }
 /**
-* Depth-first, pre-order, root-inclusive traversal of a {@link MarkdownNode} - yields
+* Walks a {@link MarkdownNode} depth-first, pre-order, root-inclusive - yields
 * the node itself, then recurses into its children (block children, list items,
 * image/link inline children, table header/row cells' inline nodes) in walk order.
 *
@@ -3012,7 +3207,7 @@ function* walkNodes(node) {
 	}
 }
 /**
-* Fold a {@link MarkdownNode} into a `T` via a total catamorphism - children are
+* Folds a {@link MarkdownNode} into a `T` through a total catamorphism - children are
 * folded first (post-order), then the node's own {@link MarkdownHandler} is invoked
 * with the already-folded children.
 *
@@ -3029,13 +3224,13 @@ function* walkNodes(node) {
 * with an empty children list instead of recursing further.
 *
 * @param node - The AST node to fold
-* @param handlers - The total {@link MarkdownHandlers} table, one handler per element
+* @param handlers - The total {@link MarkdownHandlerMap} table, one handler per element
 * @param depth - The starting recursion depth (pass `0` at the entry point)
 * @returns The folded `T`
 *
 * @example
 * ```ts
-* const countHandlers: MarkdownHandlers<number> = {
+* const countHandlers: MarkdownHandlerMap<number> = {
 *   document: (_, children) => children.reduce((a, b) => a + b, 1),
 *   // ...one handler per element, each summing its folded children
 * }
@@ -3164,19 +3359,20 @@ function foldNode(node, handlers, depth) {
 	}
 }
 /**
-* Rewrite a {@link MarkdownDocument} bottom-up (copy-on-write) - each node's children
+* Rewrites a {@link MarkdownDocument} bottom-up (copy-on-write) - each node's children
 * are rewritten first (post-order), then `rewrite` is applied to the node itself; the
 * document ROOT is never passed to `rewrite` (the `element: 'document'` invariant
 * always holds). A table's inline cells and a list's items ARE rewritten.
 *
 * @remarks
-* Never mutates `document` - every level is rebuilt into a fresh object/array, even
-* when `rewrite` returns its input unchanged. When `rewrite` returns a node whose
-* `element` does not fit the slot it was called for (a block slot handed a
+* Never mutates `document`. An unchanged subtree keeps its input identity. A parent
+* is rebuilt only when an accepted child changes, and the returned derivation map
+* associates each rebuilt output with its input node. When `rewrite` returns a node
+* whose `element` does not fit the slot it was called for (a block slot handed a
 * non-{@link BlockNode}, an inline slot handed a non-{@link InlineNode}, a list-item
-* slot handed a non-`listItem`), the ill-fitting result is discarded and the
-* freshly-rebuilt (unrewritten-at-this-level) node is kept instead - `rewriteDocument`
-* stays total and never produces a structurally invalid document.
+* slot handed a non-`listItem`), the ill-fitting result is discarded and the accepted
+* input child is reused - `rewriteDocument` stays total and never produces a
+* structurally invalid document.
 *
 * Descent is capped at {@link MAX_DEPTH}, the same cap {@link walkNodes} and
 * {@link foldNode} observe: at `depth >= MAX_DEPTH` the subtree is passed through
@@ -3186,11 +3382,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 +3399,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 +3453,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 +3461,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 +3479,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 +3496,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 +3513,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 +3532,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 +3549,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 +3569,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 +3586,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 +3603,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,15 +3633,16 @@ 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 /
+* Concatenates the `value` / `code` content of every descendant text / code-span /
 * code-block node under `node`, including image alternative content, in walk order -
 * the plain-text projection of an AST (search indexing, word counts, a text-only
 * preview).
@@ -3494,6 +3715,458 @@ function flattenText(node) {
 	return value;
 }
 //#endregion
+//#region src/core/compilers.ts
+/**
+* Renders a {@link MarkdownNode} to sanitized canonical HTML.
+*
+* @remarks
+* Markdown widens `@orkestrel/html`'s attribute floor by exactly `src`, because image
+* syntax is meaningless without its source. `src` is still a URL attribute, so the
+* floor refuses `javascript:`, `data:`, `vbscript:`, and `file:` values. A stricter
+* consumer can compose {@link markdownToHTML} with `@orkestrel/html`'s `HTML` class
+* directly.
+*
+* @param node - The markdown document or bare node to render
+* @returns Sanitized canonical HTML
+*
+* @example
+* ```ts
+* renderHTML({ element: 'paragraph', children: [{ element: 'text', value: 'a & b' }] })
+* // '<p>a &amp; b</p>'
+* ```
+*/
+function renderHTML(node) {
+	return (0, _orkestrel_html.renderHTML)(new _orkestrel_html.HTML(markdownToHTML(node)).sanitize({ attributes: [..._orkestrel_html.SAFE_ATTRIBUTES, "src"] }).document);
+}
+//#endregion
+//#region src/core/shapers.ts
+/**
+* Describes the shape of a {@link TextNode} - a plain-text leaf inline run.
+*
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { textShape } from '@src/core'
+*
+* const text = createContract(textShape)
+* text.is({ element: 'text', value: 'hi' }) // true
+* ```
+*/
+var textShape = (0, _orkestrel_contract.objectShape)({
+	element: (0, _orkestrel_contract.literalShape)(["text"]),
+	value: (0, _orkestrel_contract.stringShape)()
+});
+/**
+* Describes the shape of a {@link CodeSpanNode} - an inline code span (`` `code` ``).
+*
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { codeSpanShape } from '@src/core'
+*
+* const codeSpan = createContract(codeSpanShape)
+* codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
+* ```
+*/
+var codeSpanShape = (0, _orkestrel_contract.objectShape)({
+	element: (0, _orkestrel_contract.literalShape)(["codeSpan"]),
+	value: (0, _orkestrel_contract.stringShape)()
+});
+/**
+* Describes the shape of a {@link LineBreakNode} - a GFM hard line-break leaf.
+*
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { lineBreakShape } from '@src/core'
+*
+* const lineBreak = createContract(lineBreakShape)
+* lineBreak.is({ element: 'break' }) // true
+* ```
+*/
+var lineBreakShape = (0, _orkestrel_contract.objectShape)({ element: (0, _orkestrel_contract.literalShape)(["break"]) });
+/**
+* Describes the shape of a {@link CodeBlockNode} - a fenced code block. `lang` is
+* optional (absent when the opening fence carries no info-string).
+*
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { codeBlockShape } from '@src/core'
+*
+* const codeBlock = createContract(codeBlockShape)
+* codeBlock.is({ element: 'codeBlock', code: 'x' })                    // true
+* codeBlock.is({ element: 'codeBlock', code: 'x', lang: 'ts' })        // true
+* ```
+*/
+var codeBlockShape = (0, _orkestrel_contract.objectShape)({
+	element: (0, _orkestrel_contract.literalShape)(["codeBlock"]),
+	lang: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.stringShape)()),
+	code: (0, _orkestrel_contract.stringShape)()
+});
+/**
+* Describes the shape of a {@link ThematicBreakNode} - a horizontal rule. Carries no
+* fields beyond its `element` discriminant.
+*
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { thematicBreakShape } from '@src/core'
+*
+* const thematicBreak = createContract(thematicBreakShape)
+* thematicBreak.is({ element: 'thematicBreak' }) // true
+* ```
+*/
+var thematicBreakShape = (0, _orkestrel_contract.objectShape)({ element: (0, _orkestrel_contract.literalShape)(["thematicBreak"]) });
+/**
+* Describes the shape of a {@link TableAlign} - the per-column GFM table alignment
+* literal.
+*
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { tableAlignShape } from '@src/core'
+*
+* const tableAlign = createContract(tableAlignShape)
+* tableAlign.is('left')   // true
+* tableAlign.is('center') // true
+* tableAlign.is('top')    // false
+* ```
+*/
+var tableAlignShape = (0, _orkestrel_contract.literalShape)([
+	"left",
+	"right",
+	"center"
+]);
+/**
+* Describes the shape of {@link ListItemMatch} - the parsed parts of a single list-item
+* line the block phase's list detector returns. Fully non-recursive (no
+* nested node fields), so every field shapes directly.
+*
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { listItemMatchShape } from '@src/core'
+*
+* const listItemParts = createContract(listItemMatchShape)
+* listItemParts.is({ ordered: false, start: 1, content: 'hi', indent: 0, marker: 2 }) // true
+* ```
+*/
+var listItemMatchShape = (0, _orkestrel_contract.objectShape)({
+	ordered: (0, _orkestrel_contract.booleanShape)(),
+	start: (0, _orkestrel_contract.integerShape)(),
+	content: (0, _orkestrel_contract.stringShape)(),
+	indent: (0, _orkestrel_contract.integerShape)(),
+	marker: (0, _orkestrel_contract.integerShape)()
+});
+//#endregion
+//#region src/core/Markdown.ts
+/**
+* Wraps a typed {@link MarkdownDocument} AST as a stateful, parsed markdown document
+* with the query (`find` / `filter` / `reduce` / iteration), rewrite (`map`), fold, and
+* streaming operations {@link MarkdownInterface} declares.
+*
+* @remarks
+* - **Construction.** Given a `string`, the constructor runs {@link parseProvenance} (the
+*   block phase then the inline phase) once, keeping the AST and a COPY of the span map
+*   that parse recorded. Given a {@link MarkdownDocument}, the document is adopted AS-IS
+*   and is NOT re-validated - gate an untrusted value with `isMarkdownDocument` first.
+* - **Provenance.** {@link span} reads the region of the ORIGINAL constructor string a
+*   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. 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 (through {@link walkNodes});
+*   `stream` is shallow - only the document's direct block children.
+*
+* @example
+* ```ts
+* import { Markdown, isHeadingNode, renderMarkdown } from '@src/core'
+*
+* const markdown = new Markdown('# Title\n\nA **bold** [link](https://x.dev).')
+* const heading = markdown.find(isHeadingNode) // the HeadingNode, or undefined
+* const shouted = markdown.map((node) =>
+*   node.element === 'text' ? { element: 'text', value: node.value.toUpperCase() } : node,
+* )
+* renderMarkdown(shouted.document) // '# TITLE\n\nA **BOLD** [LINK](https://x.dev).'
+* ```
+*/
+var Markdown = class Markdown {
+	#document;
+	#spans;
+	constructor(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();
+		}
+	}
+	/** Holds 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
+		};
+	}
+	/**
+	* Returns THE deep traversal - a lazy, depth-first, pre-order, root-inclusive generator
+	* over every {@link MarkdownNode} in the document. `find` / `filter` / `reduce`
+	* all iterate this single traversal.
+	*
+	* @example
+	* ```ts
+	* for (const node of markdown.walk()) {
+	*   // every node, depth-first, pre-order, root-inclusive
+	* }
+	*
+	* // also consumable by for-await - JS accepts a sync iterable in for-await
+	* for await (const node of markdown.walk()) {
+	*   // same sequence, no separate async iterator needed
+	* }
+	* ```
+	*/
+	*walk() {
+		yield* walkNodes(this.#document);
+	}
+	find(predicate) {
+		for (const node of this.walk()) if (predicate(node)) return node;
+	}
+	filter(predicate) {
+		const out = [];
+		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},
+	* 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) {
+		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) {
+		let accumulator = initial;
+		for (const node of this.walk()) accumulator = callback(accumulator, node);
+		return accumulator;
+	}
+	/** Runs a total catamorphism over the document using a {@link MarkdownHandlerMap} table. */
+	fold(handlers) {
+		return foldNode(this.#document, handlers, 0);
+	}
+	/**
+	* Returns a web-standard {@link ReadableStream} over the document's top-level block nodes
+	* (shallow, source order) - a fresh, pull-based source per call: one block is
+	* enqueued per `pull`, so a slow reader's backpressure is respected. Cancellable,
+	* async-iterable wherever the platform supports it (Node, Deno), and pipeable
+	* through any {@link TransformStream} / {@link WritableStream}.
+	*
+	* @example
+	* ```ts
+	* // universal - works in every ReadableStream-supporting environment
+	* const reader = markdown.stream().getReader()
+	* for (let result = await reader.read(); !result.done; result = await reader.read()) {
+	*   console.log(result.value) // one BlockNode
+	* }
+	*
+	* // Node / Deno / Firefox support async iteration of ReadableStream natively;
+	* // other environments use the reader loop shown earlier.
+	* for await (const block of markdown.stream()) {
+	*   console.log(block)
+	* }
+	* ```
+	*/
+	stream() {
+		const blocks = this.#document.children;
+		let index = 0;
+		return new ReadableStream({ pull(controller) {
+			if (index < blocks.length) {
+				const block = blocks[index];
+				if (block === void 0) {
+					controller.close();
+					return;
+				}
+				controller.enqueue(block);
+				index += 1;
+			} 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/factories.ts
+/**
+* Creates a stateful markdown handle from a markdown string or an already-parsed
+* {@link MarkdownDocument} - a typed AST plus the query, rewrite, and fold operations
+* {@link MarkdownInterface} exposes.
+*
+* @remarks
+* Given a `string`, runs a block phase (headings / paragraphs / lists / GFM tables /
+* fenced code / blockquotes / thematic breaks) then an inline phase (emphasis /
+* inline code / links / images / hard breaks) to build a render-agnostic
+* {@link MarkdownDocument}. Given a
+* {@link MarkdownDocument}, adopts it AS-IS without re-validation - gate an untrusted
+* value with `isMarkdownDocument` first. Pure + total parse (malformed markdown
+* degrades to text, never throws) and zero-dependency - a hand-written scanner, no
+* regex-only structural parse, linear-time (no ReDoS).
+*
+* @param input - A markdown string to parse, or an already-parsed {@link MarkdownDocument}
+* @returns A working {@link MarkdownInterface}
+*
+* @example
+* ```ts
+* import { createMarkdown } from '@src/core'
+*
+* const markdown = createMarkdown('# Hi\n\nRead the [guide](./guide.md).')
+* markdown.document.children[0] // { element: 'heading', ... }
+* ```
+*/
+function createMarkdown(input) {
+	return new Markdown(input);
+}
+/**
+* Compiles the {@link textShape} into a {@link ContractInterface} for
+* {@link TextNode} - a guard, coercing parser, JSON Schema, and seeded
+* generator from one shape declaration.
+*
+* @returns A `TextNode` contract bundling `schema` / `is` / `parse` / `generate`
+*
+* @example
+* ```ts
+* import { createTextContract } from '@src/core'
+*
+* const text = createTextContract()
+* text.is({ element: 'text', value: 'hi' }) // true
+* ```
+*/
+function createTextContract() {
+	return (0, _orkestrel_contract.createContract)(textShape);
+}
+/**
+* Compiles the {@link codeSpanShape} into a {@link ContractInterface} for
+* {@link CodeSpanNode} - a guard, coercing parser, JSON Schema, and seeded
+* generator from one shape declaration.
+*
+* @returns A `CodeSpanNode` contract bundling `schema` / `is` / `parse` / `generate`
+*
+* @example
+* ```ts
+* import { createCodeSpanContract } from '@src/core'
+*
+* const codeSpan = createCodeSpanContract()
+* codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
+* ```
+*/
+function createCodeSpanContract() {
+	return (0, _orkestrel_contract.createContract)(codeSpanShape);
+}
+/**
+* Compiles the {@link lineBreakShape} into a {@link ContractInterface} for
+* {@link LineBreakNode}.
+*
+* @returns A `LineBreakNode` contract bundling `schema` / `is` / `parse` / `generate`
+*
+* @example
+* ```ts
+* import { createLineBreakContract } from '@src/core'
+*
+* createLineBreakContract().is({ element: 'break' }) // true
+* ```
+*/
+function createLineBreakContract() {
+	return (0, _orkestrel_contract.createContract)(lineBreakShape);
+}
+/**
+* Compiles the {@link codeBlockShape} into a {@link ContractInterface} for
+* {@link CodeBlockNode} - a guard, coercing parser, JSON Schema, and seeded
+* generator from one shape declaration.
+*
+* @returns A `CodeBlockNode` contract bundling `schema` / `is` / `parse` / `generate`
+*
+* @example
+* ```ts
+* import { createCodeBlockContract } from '@src/core'
+*
+* const codeBlock = createCodeBlockContract()
+* codeBlock.is({ element: 'codeBlock', code: 'x' }) // true
+* ```
+*/
+function createCodeBlockContract() {
+	return (0, _orkestrel_contract.createContract)(codeBlockShape);
+}
+/**
+* Compiles the {@link thematicBreakShape} into a {@link ContractInterface} for
+* {@link ThematicBreakNode} - a guard, coercing parser, JSON Schema, and
+* seeded generator from one shape declaration.
+*
+* @returns A `ThematicBreakNode` contract bundling `schema` / `is` / `parse` / `generate`
+*
+* @example
+* ```ts
+* import { createThematicBreakContract } from '@src/core'
+*
+* const thematicBreak = createThematicBreakContract()
+* thematicBreak.is({ element: 'thematicBreak' }) // true
+* ```
+*/
+function createThematicBreakContract() {
+	return (0, _orkestrel_contract.createContract)(thematicBreakShape);
+}
+//#endregion
 exports.EMPTY_PROJECTION = EMPTY_PROJECTION;
 exports.MAX_DEPTH = MAX_DEPTH;
 exports.Markdown = Markdown;
@@ -3526,6 +4199,7 @@ exports.isEmphasisNode = isEmphasisNode;
 exports.isEscapable = isEscapable;
 exports.isFenceClose = isFenceClose;
 exports.isFenceWhitespace = isFenceWhitespace;
+exports.isFlankingWhitespace = isFlankingWhitespace;
 exports.isHeadingNode = isHeadingNode;
 exports.isImageNode = isImageNode;
 exports.isInlineNode = isInlineNode;
@@ -3541,17 +4215,22 @@ exports.isTableStart = isTableStart;
 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 +4239,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;