@orkestrel/markdown 0.0.12 → 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
@@ -596,11 +511,16 @@ function parseBlocks(lines, depth, spans = /* @__PURE__ */ new Map(), end) {
 	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) {
 	const [document] = parseProvenance(markdown);
@@ -611,6 +531,12 @@ function parseDocument(markdown) {
 *
 * @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();
@@ -630,714 +556,406 @@ function parseProvenance(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 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 (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;
-	#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();
+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 stored {@link MarkdownDocument} AST root. */
-	get document() {
-		return this.#document;
-	}
-	/**
-	* Reads the region of the original markdown string a node of this handle's tree was
-	* produced from.
-	*
-	* @param node - The node whose provenance to read
-	* @returns A fresh {@link MarkdownSpan}, or `undefined` when this handle holds no
-	* region for the node
-	*
-	* @example
-	* ```ts
-	* const source = '# Title\n\npara'
-	* const markdown = new Markdown(source)
-	* const heading = markdown.find(isHeadingNode)
-	* const span = heading && markdown.span(heading)
-	* span && source.slice(span.start, span.end) // '# Title'
-	* ```
-	*/
-	span(node) {
-		const span = this.#spans.get(node);
-		return span === void 0 ? void 0 : {
-			start: span.start,
-			end: span.end
-		};
-	}
-	/**
-	* THE deep traversal - a lazy, depth-first, pre-order, root-inclusive generator
-	* over every {@link MarkdownNode} in the document. `find` / `filter` / `reduce`
-	* all iterate this single traversal.
-	*
-	* @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 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();
-		} });
-	}
-	#derive(document, derivations) {
-		const derived = new Markdown(document);
-		for (const node of walkNodes(document)) {
-			const own = this.#spans.get(node);
-			if (own !== void 0) {
-				derived.#spans.set(node, own);
-				continue;
-			}
-			const source = derivations.get(node);
-			if (source === void 0) continue;
-			const span = this.#spans.get(source);
-			if (span !== void 0) derived.#spans.set(node, span);
-		}
-		return derived;
-	}
-};
-//#endregion
-//#region src/core/shapers.ts
+	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;
+}
 /**
-* The shape of a {@link TextNode} - a plain-text leaf inline run.
+* 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
-* import { createContract } from '@orkestrel/contract'
-* import { textShape } from '@src/core'
-*
-* const text = createContract(textShape)
-* text.is({ element: 'text', value: 'hi' }) // true
+* sliceSource({ text: 'abc', segments: [{ offset: 0, start: 4, end: 7 }] }, 1, 3)
+* // { text: 'bc', segments: [{ offset: 0, start: 5, end: 7 }] }
 * ```
 */
-var textShape = (0, _orkestrel_contract.objectShape)({
-	element: (0, _orkestrel_contract.literalShape)(["text"]),
-	value: (0, _orkestrel_contract.stringShape)()
-});
+function sliceSource(source, from, to) {
+	const start = Math.max(0, Math.min(from, source.text.length));
+	const end = Math.max(start, Math.min(to, source.text.length));
+	const segments = [];
+	for (let index = 0; index < source.segments.length; index += 1) {
+		const segment = source.segments[index];
+		if (segment === void 0) continue;
+		const next = source.segments[index + 1];
+		const limit = Math.min(segment.offset + (segment.end - segment.start), next === void 0 ? source.text.length : next.offset);
+		const overlapStart = Math.max(start, segment.offset);
+		const overlapEnd = Math.min(end, limit);
+		const empty = segment.offset === limit && overlapStart === segment.offset;
+		if (overlapStart >= overlapEnd && !empty) continue;
+		const originalStart = overlapStart === limit ? segment.end : Math.min(segment.end, segment.start + overlapStart - segment.offset);
+		const originalEnd = overlapEnd === limit ? segment.end : Math.min(segment.end, segment.start + overlapEnd - segment.offset);
+		segments.push({
+			offset: overlapStart - start,
+			start: originalStart,
+			end: originalEnd
+		});
+	}
+	return {
+		text: source.text.slice(start, end),
+		segments
+	};
+}
 /**
-* The shape of a {@link CodeSpanNode} - an inline code span (`` `code` ``).
+* 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
-* import { createContract } from '@orkestrel/contract'
-* import { codeSpanShape } from '@src/core'
-*
-* const codeSpan = createContract(codeSpanShape)
-* codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
+* joinSources(splitLines('a\nb'), '\n')
+* // { text: 'a\nb', segments: [...] }
 * ```
 */
-var codeSpanShape = (0, _orkestrel_contract.objectShape)({
-	element: (0, _orkestrel_contract.literalShape)(["codeSpan"]),
-	value: (0, _orkestrel_contract.stringShape)()
-});
+function joinSources(sources, separator) {
+	let text = "";
+	const segments = [];
+	for (let index = 0; index < sources.length; index += 1) {
+		const source = sources[index];
+		if (source === void 0) continue;
+		if (index > 0) {
+			const previous = sources[index - 1];
+			const left = previous?.segments[previous.segments.length - 1];
+			const right = source.segments[0];
+			if (separator.length > 0 && left !== void 0 && right !== void 0 && left.end < right.start) segments.push({
+				offset: text.length,
+				start: left.end,
+				end: right.start
+			});
+			text += separator;
+		}
+		for (const segment of source.segments) segments.push({
+			offset: text.length + segment.offset,
+			start: segment.start,
+			end: segment.end
+		});
+		text += source.text;
+	}
+	return {
+		text,
+		segments
+	};
+}
 /**
-* The shape of a {@link LineBreakNode} - a GFM hard line-break leaf.
+* 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 { lineBreakShape } from '@src/core'
-*
-* const lineBreak = createContract(lineBreakShape)
-* lineBreak.is({ element: 'break' }) // true
+* projectSpan({ text: 'a', segments: [{ offset: 0, start: 4, end: 5 }] }, 0, 1)
+* // { start: 4, end: 5 }
 * ```
 */
-var lineBreakShape = (0, _orkestrel_contract.objectShape)({ element: (0, _orkestrel_contract.literalShape)(["break"]) });
+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 CodeBlockNode} - a fenced code block. `lang` is
-* optional (absent when the opening fence carries no info-string).
+* 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 { codeBlockShape } from '@src/core'
-*
-* const codeBlock = createContract(codeBlockShape)
-* codeBlock.is({ element: 'codeBlock', code: 'x' })                    // true
-* codeBlock.is({ element: 'codeBlock', code: 'x', lang: 'ts' })        // true
+* trimSource({ text: ' a ', segments: [{ offset: 0, start: 4, end: 7 }] })
+* // { text: 'a', segments: [{ offset: 0, start: 5, end: 6 }] }
 * ```
 */
-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)()
-});
-/**
-* The shape of a {@link ThematicBreakNode} - a horizontal rule. Carries no
-* fields beyond its `element` discriminant.
+function trimSource(source) {
+	const start = source.text.length - source.text.trimStart().length;
+	const end = source.text.trimEnd().length;
+	return sliceSource(source, start, Math.max(start, end));
+}
+/**
+* Normalizes one paragraph line while retaining the full source run consumed by a
+* trailing-space hard break.
+*
+* @param source - The offset-bearing paragraph line
+* @param breaks - If `true`, preserves a trailing run of at least two spaces as the
+*   scanner's two-space hard-break syntax; if `false`, trims the line normally
+* @returns The normalized line and its original-string segments
 *
 * @example
 * ```ts
-* import { createContract } from '@orkestrel/contract'
-* import { thematicBreakShape } from '@src/core'
-*
-* const thematicBreak = createContract(thematicBreakShape)
-* thematicBreak.is({ element: 'thematicBreak' }) // true
+* normalizeParagraphLine(splitLines('text   \nnext')[0], true).text // 'text  '
 * ```
 */
-var thematicBreakShape = (0, _orkestrel_contract.objectShape)({ element: (0, _orkestrel_contract.literalShape)(["thematicBreak"]) });
+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 TableAlign} - the per-column GFM table alignment
-* literal.
+* 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 { tableAlignShape } from '@src/core'
-*
-* const tableAlign = createContract(tableAlignShape)
-* tableAlign.is('left')   // true
-* tableAlign.is('center') // true
-* tableAlign.is('top')    // false
+* countIndent('  text') // 2
 * ```
 */
-var tableAlignShape = (0, _orkestrel_contract.literalShape)([
-	"left",
-	"right",
-	"center"
-]);
+function countIndent(line) {
+	let count = 0;
+	for (const character of line) if (character === " " || character === "	") count += 1;
+	else break;
+	return count;
+}
 /**
-* 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 `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 { listItemMatchShape } from '@src/core'
-*
-* const listItemParts = createContract(listItemMatchShape)
-* listItemParts.is({ ordered: false, start: 1, content: 'hi', indent: 0, marker: 2 }) // true
+* isFlankingWhitespace(' ') // true
+* isFlankingWhitespace('a') // false
 * ```
 */
-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 isFlankingWhitespace(character) {
+	return character === " " || character === "	" || character === "\n";
+}
 /**
-* 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 `character` is escapable by a leading backslash - the ASCII punctuation
+* markdown gives meaning to (so `\*` becomes `*` but `\.` stays `\.`).
 *
-* @param parts - The projection fields to provide
-* @returns A complete invariant-preserving projection
+* @param character - The single character after a backslash
+* @returns True if a backslash before it is an escape; false otherwise
 *
 * @example
 * ```ts
-* createProjection({
-*   blocks: [{ element: 'thematicBreak' }],
-*   inlines: [{ element: 'text', value: 'discarded' }],
-* })
-* // { blocks: [{ element: 'thematicBreak' }], inlines: [], text: '', cells: [], rows: [] }
+* isEscapable('*') // true
+* isEscapable('a') // false
 * ```
 */
-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 isEscapable(character) {
+	return /[\\`*_{}[\]()#+\-.!>~|]/.test(character);
 }
 /**
-* 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` 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 input - A markdown string to parse, or an already-parsed {@link MarkdownDocument}
-* @returns A working {@link MarkdownInterface}
+* @param line - The candidate line
+* @returns True if the line is blank; 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', ... }
+* isBlankLine('   ') // true
 * ```
 */
-function createMarkdown(input) {
-	return new Markdown(input);
+function isBlankLine(line) {
+	return (0, _orkestrel_contract.isEmptyString)(line.trim());
 }
 /**
-* 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 `line` is a blockquote line (`>` optionally indented up to three spaces) -
+* its content is de-quoted by {@link stripQuote}.
 *
-* @returns A `TextNode` contract bundling `schema` / `is` / `parse` / `generate`
+* @param line - The candidate line
+* @returns True if the line begins a blockquote; false otherwise
 *
 * @example
 * ```ts
-* import { createTextContract } from '@src/core'
-*
-* const text = createTextContract()
-* text.is({ element: 'text', value: 'hi' }) // true
+* isQuote('> quoted') // true
 * ```
 */
-function createTextContract() {
-	return (0, _orkestrel_contract.createContract)(textShape);
+function isQuote(line) {
+	return /^\s{0,3}>/.test(line);
 }
 /**
-* 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` closes a fence opened by `marker` - the same fence character, a run
+* at least as long, and nothing else but surrounding whitespace.
 *
-* @returns A `CodeSpanNode` contract bundling `schema` / `is` / `parse` / `generate`
+* @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 { createCodeSpanContract } from '@src/core'
-*
-* const codeSpan = createCodeSpanContract()
-* codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
+* isFenceClose('```', '```') // true
 * ```
 */
-function createCodeSpanContract() {
-	return (0, _orkestrel_contract.createContract)(codeSpanShape);
+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 lineBreakShape} into a {@link ContractInterface} for
-* {@link LineBreakNode}.
+* Checks whether `character` is a regex-`\s`-equivalent whitespace character - the
+* character class {@link isFenceClose}'s scan treats as surrounding padding.
 *
-* @returns A `LineBreakNode` 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 { createLineBreakContract } from '@src/core'
-*
-* createLineBreakContract().is({ element: 'break' }) // true
+* isFenceWhitespace(' ')         // true
+* isFenceWhitespace(undefined)   // false
 * ```
 */
-function createLineBreakContract() {
-	return (0, _orkestrel_contract.createContract)(lineBreakShape);
+function isFenceWhitespace(character) {
+	return character === " " || character === "	" || character === "\n" || character === "\r" || character === "\f" || character === "\v";
 }
 /**
-* 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).
+* 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 `CodeBlockNode` 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 { createCodeBlockContract } from '@src/core'
-*
-* const codeBlock = createCodeBlockContract()
-* codeBlock.is({ element: 'codeBlock', code: 'x' }) // true
+* isThematicBreak('---') // true
 * ```
 */
-function createCodeBlockContract() {
-	return (0, _orkestrel_contract.createContract)(codeBlockShape);
+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);
 }
 /**
-* 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).
+* 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.
 *
-* @returns A `ThematicBreakNode` contract bundling `schema` / `is` / `parse` / `generate`
+* @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
-* import { createThematicBreakContract } from '@src/core'
-*
-* const thematicBreak = createThematicBreakContract()
-* thematicBreak.is({ element: 'thematicBreak' }) // true
+* isTableStart('| a |', '| - |') // true
 * ```
 */
-function createThematicBreakContract() {
-	return (0, _orkestrel_contract.createContract)(thematicBreakShape);
+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()));
 }
-//#endregion
-//#region src/core/helpers.ts
 /**
-* 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.
+* 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 markdown - The raw markdown source
-* @returns The document's lines with their original-string coordinates
+* @param line - The candidate line
+* @returns The heading level (1–6), raw inline text, and text offset, or `undefined`
 *
 * @example
 * ```ts
-* splitLines('a\r\nb') // [{ text: 'a', segments: [{ offset: 0, start: 0, end: 1 }] }, ...]
-* ```
-*/
-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;
-	}
-	lines.push({
-		text: markdown.slice(start),
-		segments: [{
-			offset: 0,
-			start,
-			end: markdown.length
-		}]
-	});
-	if (lines.length > 1 && lines[lines.length - 1]?.text === "") lines.pop();
-	return lines;
-}
-/**
-* Slices derived markdown text and narrows each intersecting source segment to the
-* same text-relative range.
-*
-* @param source - The offset-bearing source to slice
-* @param from - The inclusive text offset
-* @param to - The exclusive text offset
-* @returns The sliced text and its narrowed original-string segments
-*
-* @example
-* ```ts
-* sliceSource({ text: 'abc', segments: [{ offset: 0, start: 4, end: 7 }] }, 1, 3)
-* // { text: 'bc', segments: [{ offset: 0, start: 5, end: 7 }] }
-* ```
-*/
-function sliceSource(source, from, to) {
-	const start = Math.max(0, Math.min(from, source.text.length));
-	const end = Math.max(start, Math.min(to, source.text.length));
-	const segments = [];
-	for (let index = 0; index < source.segments.length; index += 1) {
-		const segment = source.segments[index];
-		if (segment === void 0) continue;
-		const next = source.segments[index + 1];
-		const limit = Math.min(segment.offset + (segment.end - segment.start), next === void 0 ? source.text.length : next.offset);
-		const overlapStart = Math.max(start, segment.offset);
-		const overlapEnd = Math.min(end, limit);
-		const empty = segment.offset === limit && overlapStart === segment.offset;
-		if (overlapStart >= overlapEnd && !empty) continue;
-		const originalStart = overlapStart === limit ? segment.end : Math.min(segment.end, segment.start + overlapStart - segment.offset);
-		const originalEnd = overlapEnd === limit ? segment.end : Math.min(segment.end, segment.start + overlapEnd - segment.offset);
-		segments.push({
-			offset: overlapStart - start,
-			start: originalStart,
-			end: originalEnd
-		});
-	}
-	return {
-		text: source.text.slice(start, end),
-		segments
-	};
-}
-/**
-* Joins offset-bearing markdown sources while mapping a separator to the original
-* region between adjacent mapped sources.
-*
-* @param sources - The sources to join
-* @param separator - The derived text inserted between sources
-* @returns The joined text and every source-backed segment
-*
-* @example
-* ```ts
-* joinSources(splitLines('a\nb'), '\n')
-* // { text: 'a\nb', segments: [...] }
-* ```
-*/
-function joinSources(sources, separator) {
-	let text = "";
-	const segments = [];
-	for (let index = 0; index < sources.length; index += 1) {
-		const source = sources[index];
-		if (source === void 0) continue;
-		if (index > 0) {
-			const previous = sources[index - 1];
-			const left = previous?.segments[previous.segments.length - 1];
-			const right = source.segments[0];
-			if (separator.length > 0 && left !== void 0 && right !== void 0 && left.end < right.start) segments.push({
-				offset: text.length,
-				start: left.end,
-				end: right.start
-			});
-			text += separator;
-		}
-		for (const segment of source.segments) segments.push({
-			offset: text.length + segment.offset,
-			start: segment.start,
-			end: segment.end
-		});
-		text += source.text;
-	}
-	return {
-		text,
-		segments
-	};
-}
-/**
-* Projects a derived text range through its segments to a half-open region of the
-* original markdown string.
-*
-* @param source - The offset-bearing source carrying the range
-* @param from - The inclusive derived-text boundary
-* @param to - The exclusive derived-text boundary
-* @returns The original-string span, or `undefined` when either boundary is unmapped
-*
-* @example
-* ```ts
-* projectSpan({ text: 'a', segments: [{ offset: 0, start: 4, end: 5 }] }, 0, 1)
-* // { start: 4, end: 5 }
-* ```
-*/
-function projectSpan(source, from, to) {
-	if (from < 0 || to < from || to > source.text.length) return void 0;
-	let start;
-	let end;
-	for (let index = 0; index < source.segments.length; index += 1) {
-		const segment = source.segments[index];
-		if (segment === void 0) continue;
-		const next = source.segments[index + 1];
-		const limit = Math.min(segment.offset + (segment.end - segment.start), next === void 0 ? source.text.length : next.offset);
-		if (from === to && from >= segment.offset && from <= limit) {
-			if (next !== void 0 && from === next.offset) continue;
-			const position = from === limit ? segment.end : Math.min(segment.end, segment.start + from - segment.offset);
-			return {
-				start: position,
-				end: position
-			};
-		}
-		if (start === void 0 && from >= segment.offset && from < limit) start = segment.start + from - segment.offset;
-		if (to > segment.offset && to <= limit) end = to === limit ? segment.end : Math.min(segment.end, segment.start + to - segment.offset);
-	}
-	return start === void 0 || end === void 0 ? void 0 : {
-		start,
-		end
-	};
-}
-/**
-* Trims an offset-bearing source without losing the coordinates of its retained text.
-*
-* @param source - The source to trim
-* @returns The trimmed text and its narrowed original-string segments
-*
-* @example
-* ```ts
-* trimSource({ text: ' a ', segments: [{ offset: 0, start: 4, end: 7 }] })
-* // { text: 'a', segments: [{ offset: 0, start: 5, end: 6 }] }
-* ```
-*/
-function trimSource(source) {
-	const start = source.text.length - source.text.trimStart().length;
-	const end = source.text.trimEnd().length;
-	return sliceSource(source, start, Math.max(start, end));
-}
-/**
-* Normalizes one paragraph line while retaining the full source run consumed by a
-* trailing-space hard break.
-*
-* @param source - The offset-bearing paragraph line
-* @param breaks - If `true`, preserves a trailing run of at least two spaces as the
-*   scanner's two-space hard-break syntax; if `false`, trims the line normally
-* @returns The normalized line and its original-string segments
-*
-* @example
-* ```ts
-* normalizeParagraphLine(splitLines('text   \nnext')[0], true).text // 'text  '
-* ```
-*/
-function normalizeParagraphLine(source, breaks) {
-	if (!breaks || !source.text.endsWith("  ")) return trimSource(source);
-	const contentEnd = source.text.trimEnd().length;
-	const content = trimSource(sliceSource(source, 0, contentEnd));
-	const span = projectSpan(source, contentEnd, source.text.length);
-	return joinSources([content, {
-		text: "  ",
-		segments: span === void 0 ? [] : [{
-			offset: 0,
-			start: span.start,
-			end: span.end
-		}]
-	}], "");
-}
-/**
-* The count of leading space / tab characters on `line` (a tab counts as one) - the
-* indent that decides whether a list item's continuation belongs to the item.
-*
-* @param line - The line to measure
-* @returns The number of leading space / tab characters
-*
-* @example
-* ```ts
-* countIndent('  text') // 2
-* ```
-*/
-function countIndent(line) {
-	let count = 0;
-	for (const character of line) if (character === " " || character === "	") count += 1;
-	else break;
-	return count;
-}
-/**
-* 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), raw inline text, and text offset, or `undefined`
-*
-* @example
-* ```ts
-* extractHeading('## Title') // { level: 2, text: 'Title', offset: 3 }
+* extractHeading('## Title') // { level: 2, text: 'Title', offset: 3 }
 * ```
 */
 function extractHeading(line) {
@@ -1357,7 +975,7 @@ function extractHeading(line) {
 	};
 }
 /**
-* 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.
@@ -1382,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).
@@ -1439,7 +1057,7 @@ 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. Derives the string
 * form from {@link splitTableSources}, which owns the escaped-pipe splitting rule.
@@ -1505,7 +1123,7 @@ function splitTableSources(row) {
 	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`.
 *
@@ -1529,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
@@ -1537,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
@@ -1549,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
@@ -1572,7 +1190,7 @@ 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)
@@ -1610,7 +1228,7 @@ function coalesceText(nodes, spans) {
 	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).
@@ -1759,7 +1377,7 @@ function locateEmphasis(source, start, to) {
 	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] ?? "";
@@ -1782,7 +1400,7 @@ function locateEmphasis(source, start, to) {
 		if (character === marker) {
 			let closeRun = 0;
 			while (index + closeRun < to && source[index + closeRun] === marker) closeRun += 1;
-			if (closeRun >= run && !isWhitespace(source[index - 1] ?? "")) return {
+			if (closeRun >= run && !isFlankingWhitespace(source[index - 1] ?? "")) return {
 				strong,
 				open: openEnd,
 				close: index,
@@ -1829,7 +1447,7 @@ function scanEmphasis(source, start, to, depth = 0) {
 	};
 }
 /**
-* Scan the window `[from, to)` of `source` into inline nodes - the single recursive
+* Scans the window `[from, to)` of `source` into inline nodes - the single recursive
 * engine the inline phase runs on (emphasis, link text, and image alternative
 * content recurse through it). Linear:
 * each character is consumed once; a failed construct emits its opening character as
@@ -1839,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
@@ -1868,7 +1487,9 @@ function scanInline(source, from, to, depth = 0) {
 * @param from - The inclusive start of the scan window
 * @param to - The exclusive end of the scan window
 * @param spans - The operation-owned node span recorder
-* @param depth - The current inline-recursion depth
+* @param depth - The current inline-recursion depth, incremented by one on every
+*   recursive descent this function makes into itself for a link's text, an image's
+*   alternative content, or an emphasis run's children
 * @returns The parsed inline nodes before adjacent text coalescing
 *
 * @example
@@ -2210,7 +1831,7 @@ function collectList(lines, start, depth, spans = /* @__PURE__ */ new Map(), end
 	};
 }
 /**
-* 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
@@ -2539,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
@@ -2570,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
@@ -2856,32 +2455,62 @@ 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] = {
-			element: "text",
+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
 		};
 	}
@@ -2897,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.
 *
@@ -2910,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
@@ -2962,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.
 *
@@ -3049,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
@@ -3095,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
@@ -3115,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
@@ -3152,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.
 *
@@ -3301,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",
@@ -3459,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
@@ -3515,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.
 *
@@ -3578,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.
 *
@@ -3595,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
 * }
@@ -3730,7 +3359,7 @@ 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.
@@ -4013,7 +3642,7 @@ function rewriteDocument(document, rewrite) {
 	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).
@@ -4086,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;
@@ -4118,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;
@@ -4133,7 +4215,6 @@ exports.isTableStart = isTableStart;
 exports.isTextNode = isTextNode;
 exports.isThematicBreak = isThematicBreak;
 exports.isThematicBreakNode = isThematicBreakNode;
-exports.isWhitespace = isWhitespace;
 exports.joinSources = joinSources;
 exports.lineBreakShape = lineBreakShape;
 exports.listItemMatchShape = listItemMatchShape;