@orkestrel/markdown 0.0.6 → 0.0.7

package/dist/src/core/index.js

@@ -1,27 +1,33 @@
-import { arrayOf, booleanShape, createContract, integerShape, isBoolean, isEmptyString, isNonEmptyArray, isNonEmptyString, isNumber, isString, lazyOf, literalOf, literalShape, objectShape, optionalShape, parseInteger, recordOf, stringShape, unionOf } from "@orkestrel/contract";
+import { arrayOf, booleanShape, createContract, integerShape, isBoolean, isEmptyString, isNonEmptyArray, isNonEmptyString, isNumber, isString, lazyOf, literalOf, literalShape, nullableOf, objectShape, optionalShape, parseInteger, recordOf, stringShape, unionOf } from "@orkestrel/contract";
+import { HTML, SAFE_ATTRIBUTES, SAFE_URL_SCHEMES, TABLE_ALIGNMENTS, UNSAFE_ELEMENTS, attributeOf, foldNode as foldNode$1, renderHTML as renderHTML$1, renderText, sanitizeURL } from "@orkestrel/html";
 //#region src/core/constants.ts
 /**
-* The URL schemes `renderHTML` permits on a link `href` - anything else (notably
-* `javascript:`, `data:`, `vbscript:`, `file:`) is dropped to an empty `href` so a
-* hostile link can never execute. Frozen, lower-case; a relative / anchor /
-* scheme-less `href` (no `scheme:` prefix) is always allowed.
-*/
-var SAFE_URL_SCHEMES = /* @__PURE__ */ new Set([
-	"http",
-	"https",
-	"mailto",
-	"tel"
-]);
-/**
 * The maximum recursion depth the parse pipeline (`parseDocument` and its
-* `parsers.ts` helpers) and the `helpers.ts` traversal / render functions
-* (`renderHTML`, `renderMarkdown`, `walkNodes`, `foldNode`) honor before degrading to
-* literal text - bounds blockquote nesting, inline nesting (emphasis / links), and
-* traversal/render recursion so pathological or hostile input (deeply nested
-* blockquotes, runaway emphasis) cannot exhaust the call stack. Past this depth the
-* parser treats the remaining content as literal text instead of recursing further.
+* `parsers.ts` helpers) and the `helpers.ts` traversal / projection functions
+* (`markdownToHTML`, `renderHTML`, `renderMarkdown`, `walkNodes`, `foldNode`,
+* `rewriteDocument`) 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
+* default every absent field.
+*
+* @example
+* ```ts
+* EMPTY_PROJECTION.blocks // []
+* Object.isFrozen(EMPTY_PROJECTION) // true
+* ```
+*/
+var EMPTY_PROJECTION = Object.freeze({
+	blocks: Object.freeze([]),
+	inlines: Object.freeze([]),
+	text: "",
+	cells: Object.freeze([]),
+	rows: Object.freeze([])
+});
 //#endregion
 //#region src/core/validators.ts
 /**
@@ -269,13 +275,35 @@ function isEmphasisNode(node) {
 function isCodeSpanNode(node) {
 	return node.element === "codeSpan";
 }
+/**
+* Determine whether a node is a GFM hard line break.
+*
+* @example
+* ```ts
+* isLineBreakNode({ element: 'break' }) // true
+* ```
+*/
+function isLineBreakNode(node) {
+	return node.element === "break";
+}
 /** Determine whether a node is a link. */
 function isLinkNode(node) {
 	return node.element === "link";
 }
 /**
+* Determine whether a node is an image.
+*
+* @example
+* ```ts
+* isImageNode({ element: 'image', src: 'x.png', children: [] }) // true
+* ```
+*/
+function isImageNode(node) {
+	return node.element === "image";
+}
+/**
 * Determine whether an arbitrary value is a valid {@link InlineNode} - a text
-* run, emphasis, code span, or link, recursively validated.
+* run, emphasis, code span, hard break, link, or image, recursively validated.
 *
 * @remarks
 * Total: never throws, even on cyclic or pathologically deep input - every
@@ -303,10 +331,14 @@ var isInlineNode = unionOf(recordOf({
 }), recordOf({
 	element: literalOf("codeSpan"),
 	value: isString
-}), recordOf({
+}), recordOf({ element: literalOf("break") }), recordOf({
 	element: literalOf("link"),
 	href: isString,
 	children: arrayOf(lazyOf(() => isInlineNode))
+}), recordOf({
+	element: literalOf("image"),
+	src: isString,
+	children: arrayOf(lazyOf(() => isInlineNode))
 }));
 /**
 * Determine whether an arbitrary value is a valid {@link BlockNode} - a
@@ -350,7 +382,7 @@ var isBlockNode = unionOf(recordOf({
 	element: literalOf("table"),
 	header: arrayOf(arrayOf(isInlineNode)),
 	rows: arrayOf(arrayOf(arrayOf(isInlineNode))),
-	align: arrayOf(literalOf("none", "left", "right", "center"))
+	align: arrayOf(nullableOf(literalOf("left", "right", "center")))
 }), recordOf({
 	element: literalOf("codeBlock"),
 	lang: isString,
@@ -412,1074 +444,1227 @@ var isMarkdownDocument = recordOf({
 	children: arrayOf(isBlockNode)
 });
 //#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']
-* ```
-*/
-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;
-}
-/**
-* 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
-* leadingIndent('  text') // 2
-* ```
-*/
-function leadingIndent(line) {
-	let count = 0;
-	for (const character of line) if (character === " " || character === "	") count += 1;
-	else break;
-	return count;
-}
+//#region src/core/parsers.ts
 /**
-* 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.
+* Parses a run of markdown lines into a block AST, recursing into nested
+* blockquotes, list items, and depth-capped degrade paragraphs.
 *
-* @param line - The candidate line
-* @returns The heading level (1–6) and its raw inline text, or `undefined`
+* @param lines - The markdown lines to parse.
+* @param depth - The current recursion depth (blockquotes/lists increment it).
+* @returns The parsed block nodes.
 *
 * @example
 * ```ts
-* extractHeading('## Title') // { level: 2, text: 'Title' }
+* parseBlocks(['# Hi'], 0) // [{ element: 'heading', level: 1, children: [...] }]
 * ```
 */
-function extractHeading(line) {
-	const match = /^(#{1,6})(?:\s+(.*))?$/.exec(line.trimStart());
-	if (!match || match[1] === void 0) return void 0;
-	return {
-		level: match[1].length,
-		text: (match[2] ?? "").replace(/\s+#+\s*$/, "").trim()
-	};
+function parseBlocks(lines, depth) {
+	if (depth >= 64) return lines.length > 0 ? [{
+		element: "paragraph",
+		children: [{
+			element: "text",
+			value: lines.join("\n")
+		}]
+	}] : [];
+	const blocks = [];
+	let index = 0;
+	while (index < lines.length) {
+		const line = lines[index] ?? "";
+		if (isBlankLine(line)) {
+			index += 1;
+			continue;
+		}
+		const fence = extractFence(line);
+		if (fence) {
+			const body = [];
+			index += 1;
+			while (index < lines.length && !isFenceClose(lines[index] ?? "", fence.marker)) {
+				body.push(lines[index] ?? "");
+				index += 1;
+			}
+			index += 1;
+			blocks.push({
+				element: "codeBlock",
+				...fence.lang === void 0 ? {} : { lang: fence.lang },
+				code: body.join("\n")
+			});
+			continue;
+		}
+		if (isThematicBreak(line)) {
+			blocks.push({ element: "thematicBreak" });
+			index += 1;
+			continue;
+		}
+		const heading = extractHeading(line);
+		if (heading) {
+			blocks.push({
+				element: "heading",
+				level: heading.level,
+				children: parseInline(heading.text)
+			});
+			index += 1;
+			continue;
+		}
+		if (isQuote(line)) {
+			const quoted = [];
+			while (index < lines.length && isQuote(lines[index] ?? "")) {
+				quoted.push(stripQuote(lines[index] ?? ""));
+				index += 1;
+			}
+			blocks.push({
+				element: "blockquote",
+				children: parseBlocks(quoted, depth + 1)
+			});
+			continue;
+		}
+		if (isTableStart(line, lines[index + 1])) {
+			const table = collectTable(lines, index);
+			blocks.push(table.node);
+			index = table.next;
+			continue;
+		}
+		if (extractListItem(line)) {
+			const list = collectList(lines, index, depth);
+			blocks.push(list.node);
+			index = list.next;
+			continue;
+		}
+		const paragraph = [];
+		while (index < lines.length && !isBlankLine(lines[index] ?? "") && !(isNonEmptyArray(paragraph) && startsBlock(lines, index))) {
+			paragraph.push(lines[index] ?? "");
+			index += 1;
+		}
+		const source = paragraph.map((paragraphLine, position) => position < paragraph.length - 1 && paragraphLine.endsWith("  ") ? `${paragraphLine.trim()}  ` : paragraphLine.trim()).join("\n");
+		blocks.push({
+			element: "paragraph",
+			children: parseInline(source)
+		});
+	}
+	return blocks;
 }
 /**
-* Extract 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.
+* Collects a GFM table starting at a header row, parsing the header, the
+* alignment row, and every contiguous body row that follows.
 *
-* @param line - The candidate line
-* @returns The fence marker run and its language tag, or `undefined`
+* @param lines - The markdown lines to scan.
+* @param start - The index of the header row.
+* @returns The parsed table node and the index of the first line after it.
 *
 * @example
 * ```ts
-* extractFence('```ts') // { marker: '```', lang: 'ts' }
+* collectTable(['| a |', '| - |'], 0) // { node: { element: 'table', ... }, next: 2 }
 * ```
 */
-function extractFence(line) {
-	const match = /^\s*(`{3,}|~{3,})\s*(.*)$/.exec(line);
-	if (!match || match[1] === void 0) return void 0;
-	const info = (match[2] ?? "").trim();
-	if (match[1].startsWith("`") && info.includes("`")) return void 0;
-	const lang = isNonEmptyString(info) ? info.split(/\s+/)[0] : void 0;
+function collectTable(lines, start) {
+	const headerCells = splitTableRow(lines[start] ?? "");
+	const columns = headerCells.length;
+	const header = headerCells.map((cell) => parseInline(cell.trim()));
+	const align = delimiterToAlignments(lines[start + 1] ?? "");
+	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] ?? "");
+		const row = [];
+		for (let column = 0; column < columns; column += 1) row.push(parseInline((cells[column] ?? "").trim()));
+		rows.push(row);
+		index += 1;
+	}
 	return {
-		marker: match[1],
-		lang
+		node: {
+			element: "table",
+			header,
+			rows,
+			align: padded
+		},
+		next: index
 	};
 }
 /**
-* Extract a list-item line (`-` / `*` / `+` bullet, or `1.` / `1)` ordinal, followed by
-* a space) into its {@link ListItemParts}, 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).
+* Collects a list starting at the first item, gathering sibling items at the
+* same indent/ordering and recursing into each item's own block content.
 *
-* @param line - The candidate line
-* @returns The list-item parts, or `undefined` when not a list item
+* @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`).
+* @returns The parsed list node and the index of the first line after it.
 *
 * @example
 * ```ts
-* extractListItem('- item') // { ordered: false, start: 1, content: 'item', indent: 0, marker: 2 }
+* collectList(['- item'], 0, 0) // { node: { element: 'list', ... }, next: 1 }
 * ```
 */
-function extractListItem(line) {
-	const unordered = /^(\s*)([-*+])\s+(.*)$/.exec(line);
-	if (unordered && unordered[1] !== void 0) {
-		const indent = unordered[1].length;
-		const content = unordered[3] ?? "";
-		return {
-			ordered: false,
-			start: 1,
-			content,
-			indent,
-			marker: line.length - content.length
-		};
+function collectList(lines, start, depth) {
+	const first = extractListItem(lines[start] ?? "");
+	const ordered = first?.ordered ?? false;
+	const startOrdinal = first?.start ?? 1;
+	const topIndent = first?.indent ?? 0;
+	const items = [];
+	const chain = [];
+	let nested = true;
+	for (let cursor = start; cursor < lines.length; cursor += 1) {
+		const parsed = extractListItem(lines[cursor] ?? "");
+		const previous = chain[chain.length - 1];
+		if (parsed === void 0 || previous !== void 0 && (previous.content.length > 0 || parsed.indent !== previous.marker)) {
+			nested = false;
+			break;
+		}
+		chain.push(parsed);
 	}
-	const ordered = /^(\s*)(\d{1,9})[.)]\s+(.*)$/.exec(line);
-	if (ordered && ordered[1] !== void 0 && ordered[2] !== void 0) {
-		const indent = ordered[1].length;
-		const content = ordered[3] ?? "";
-		return {
-			ordered: true,
-			start: parseInteger(ordered[2]) ?? 1,
-			content,
-			indent,
-			marker: line.length - content.length
-		};
+	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 = [{
+				element: "paragraph",
+				children: [{
+					element: "text",
+					value: source.join("\n")
+				}]
+			}];
+			let node;
+			for (let cursor = remaining - 1; cursor >= 0; cursor -= 1) {
+				const parsed = chain[cursor];
+				if (parsed === void 0) continue;
+				node = {
+					element: "list",
+					ordered: parsed.ordered,
+					start: parsed.start,
+					items: [{
+						element: "listItem",
+						children
+					}]
+				};
+				children = [node];
+			}
+			if (node !== void 0) return {
+				node,
+				next: lines.length
+			};
+		}
 	}
-}
-/**
-* 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.
-*
-* @param line - A blockquote line (per {@link isQuote})
-* @returns The line with its leading `>` (and one space) removed
-*
-* @example
-* ```ts
-* stripQuote('> text') // 'text'
-* ```
-*/
-function stripQuote(line) {
-	return line.replace(/^\s{0,3}>\s?/, "");
-}
-/**
-* Split one GFM table row into its cell strings - outer pipes are optional, an escaped
-* pipe (`\|`) inside a cell is NOT a separator (it becomes a literal `|`), and the
-* empty leading / trailing cell produced by an outer `|` is dropped.
-*
-* @param row - The raw table row line
-* @returns The row's cells, in column order
-*
-* @example
-* ```ts
-* splitTableRow('|a|b|') // ['a', 'b']
-* ```
-*/
-function splitTableRow(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 index = start;
+	while (index < lines.length) {
+		const parsed = extractListItem(lines[index] ?? "");
+		if (!parsed || parsed.indent > topIndent || parsed.ordered !== ordered) break;
+		const itemLines = [parsed.content];
+		const continuation = parsed.marker;
+		index += 1;
+		while (index < lines.length) {
+			const next = lines[index] ?? "";
+			if (isBlankLine(next)) {
+				const after = lines[index + 1] ?? "";
+				if (index + 1 < lines.length && !isBlankLine(after) && countIndent(after) >= continuation) {
+					itemLines.push("");
+					index += 1;
+					continue;
+				}
+				break;
+			}
+			if (countIndent(next) >= continuation) {
+				itemLines.push(next.slice(continuation));
+				index += 1;
+				continue;
+			}
+			if (extractListItem(next) || startsBlock(lines, index)) break;
+			itemLines.push(next.trim());
 			index += 1;
-		} else if (character === "|") {
-			cells.push(current);
-			current = "";
-		} else current += character;
+		}
+		items.push({
+			element: "listItem",
+			children: parseBlocks(itemLines, depth + 1)
+		});
 	}
-	cells.push(current);
-	if (isNonEmptyArray(cells) && isEmptyString((cells[0] ?? "").trim())) cells.shift();
-	if (isNonEmptyArray(cells) && isEmptyString((cells[cells.length - 1] ?? "").trim())) cells.pop();
-	return cells;
+	return {
+		node: {
+			element: "list",
+			ordered,
+			start: startOrdinal,
+			items
+		},
+		next: index
+	};
 }
 /**
-* Derive the per-column {@link TableAlign} list from a GFM delimiter row - `:---`
-* left, `---:` right, `:---:` center, `---` none.
-*
-* @param delimiter - The table's delimiter row
-* @returns One alignment per column, in column order
+* Parses a markdown string into a typed {@link MarkdownDocument} AST via the
+* block phase.
 *
-* @example
-* ```ts
-* tableAlignments('| :--- | ---: |') // ['left', 'right']
-* ```
+* @param markdown - The markdown source to parse.
+* @returns The parsed document.
 */
-function tableAlignments(delimiter) {
-	return splitTableRow(delimiter).map((cell) => {
-		const text = cell.trim();
-		const left = text.startsWith(":");
-		const right = text.endsWith(":");
-		if (left && right) return "center";
-		if (right) return "right";
-		if (left) return "left";
-		return "none";
-	});
+function parseDocument(markdown) {
+	return {
+		element: "document",
+		children: parseBlocks(splitLines(markdown), 0)
+	};
 }
 /**
-* 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
-* line).
-*
-* @param lines - The document's lines
-* @param index - The line index to test
-* @returns `true` when the line begins a different block
+* Parses inline markdown text (emphasis, code spans, links, images, and hard
+* breaks) into inline AST nodes, coalescing adjacent text runs.
 *
-* @example
-* ```ts
-* startsBlock(['text', '## Heading'], 1) // true
-* ```
+* @param text - The inline markdown text to parse.
+* @returns The parsed inline nodes.
 */
-function startsBlock(lines, index) {
-	const line = lines[index] ?? "";
-	return extractHeading(line) !== void 0 || extractFence(line) !== void 0 || isThematicBreak(line) || isQuote(line) || extractListItem(line) !== void 0 || isTableStart(line, lines[index + 1]);
+function parseInline(text) {
+	return coalesceText(scanInline(text, 0, text.length));
 }
+//#endregion
+//#region src/core/Markdown.ts
 /**
-* Resolve backslash escapes in a raw string to their literal characters - used for a
-* link `href` (which is not otherwise inline-parsed) and any plain text run.
+* 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.
 *
-* @param text - The raw text possibly carrying `\x` escapes
-* @returns The text with escapable `\x` reduced to `x`
+* @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.
 *
 * @example
 * ```ts
-* unescapeText('\\*hi\\*') // '*hi*'
-* ```
-*/
-function unescapeText(text) {
-	let out = "";
-	for (let index = 0; index < text.length; index += 1) {
-		const character = text[index] ?? "";
-		if (character === "\\" && isEscapable(text[index + 1] ?? "")) {
-			out += text[index + 1] ?? "";
-			index += 1;
-		} else out += character;
-	}
-	return out;
-}
-/**
-* Merge 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)
-* @returns The nodes with consecutive text nodes concatenated
+* import { Markdown, isHeadingNode, renderMarkdown } from '@src/core'
 *
-* @example
-* ```ts
-* coalesceText([{ element: 'text', value: 'a' }, { element: 'text', value: 'b' }])
-* // [{ element: 'text', value: 'ab' }]
+* 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).'
 * ```
 */
-function coalesceText(nodes) {
-	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);
+var Markdown = class Markdown {
+	#document;
+	constructor(input) {
+		this.#document = typeof input === "string" ? parseDocument(input) : input;
 	}
-	return out;
-}
-/**
-* Scan 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).
-*
-* @param source - The inline source text
-* @param start - The index of the opening backtick
-* @param to - The exclusive end of the scan window
-* @returns The span text + end index, or `undefined`
-*
-* @example
-* ```ts
-* scanCode('`code`', 0, 6) // { value: 'code', end: 6 }
-* ```
-*/
-function scanCode(source, start, to) {
-	let run = 0;
-	while (start + run < to && source[start + run] === "`") run += 1;
-	const open = "`".repeat(run);
-	let search = start + run;
-	for (;;) {
-		const closeAt = source.indexOf(open, search);
-		if (closeAt === -1 || closeAt + run > to) return void 0;
-		if (source[closeAt - 1] !== "`" && source[closeAt + run] !== "`") {
-			let value = source.slice(start + run, closeAt);
-			if (value.length > 2 && value.startsWith(" ") && value.endsWith(" ") && value.trim().length > 0) value = value.slice(1, -1);
-			return {
-				value,
-				end: closeAt + run
-			};
-		}
-		search = closeAt + 1;
+	/** The stored {@link MarkdownDocument} AST root. */
+	get document() {
+		return this.#document;
 	}
-}
+	/**
+	* 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}. */
+	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
 /**
-* Scan a link `[text](href)` at `start` - the text runs to a BALANCED `]`, then `(`
-* must immediately follow and the destination runs to the matching `)` (both respect
-* nested delimiters + escapes). Returns the link node, or `undefined` when the shape
-* does not hold (it then degrades to a literal `[`).
-*
-* @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`
+* The shape of a {@link TextNode} - a plain-text leaf inline run.
 *
 * @example
 * ```ts
-* scanLink('[text](url)', 0, 11)
-* // { node: { element: 'link', href: 'url', children: [...] }, end: 11 }
+* import { createContract } from '@orkestrel/contract'
+* import { textShape } from '@src/core'
+*
+* const text = createContract(textShape)
+* text.is({ element: 'text', value: 'hi' }) // true
 * ```
 */
-function scanLink(source, start, to, depth = 0) {
-	let bracketDepth = 0;
-	let close = -1;
-	for (let index = start; index < to; index += 1) {
-		const character = source[index] ?? "";
-		if (character === "\\") {
-			index += 1;
-			continue;
-		}
-		if (character === "[") bracketDepth += 1;
-		else if (character === "]") {
-			bracketDepth -= 1;
-			if (bracketDepth === 0) {
-				close = index;
-				break;
-			}
-		}
-	}
-	if (close === -1 || source[close + 1] !== "(") return void 0;
-	let parenDepth = 0;
-	let parenClose = -1;
-	for (let index = close + 1; index < to; index += 1) {
-		const character = source[index] ?? "";
-		if (character === "\\") {
-			index += 1;
-			continue;
-		}
-		if (character === "(") parenDepth += 1;
-		else if (character === ")") {
-			parenDepth -= 1;
-			if (parenDepth === 0) {
-				parenClose = index;
-				break;
-			}
-		}
-	}
-	if (parenClose === -1) return void 0;
-	return {
-		node: {
-			element: "link",
-			href: unescapeText(source.slice(close + 2, parenClose).trim()),
-			children: scanInline(source, start + 1, close, depth + 1)
-		},
-		end: parenClose + 1
-	};
-}
+var textShape = objectShape({
+	element: literalShape(["text"]),
+	value: stringShape()
+});
 /**
-* Scan an emphasis run at `start` (`*` / `_`, doubled for strong) - finds the nearest
-* matching closing run of the same marker + width, requiring non-space immediately
-* inside both delimiters (the CommonMark flanking simplification that blocks `* x *`).
-* Returns the emphasis node, or `undefined` when no valid closer exists (it then
-* degrades to a literal marker).
-*
-* @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`
+* The shape of a {@link CodeSpanNode} - an inline code span (`` `code` ``).
 *
 * @example
 * ```ts
-* scanEmphasis('*em*', 0, 4)
-* // { node: { element: 'emphasis', strong: false, children: [...] }, end: 4 }
+* import { createContract } from '@orkestrel/contract'
+* import { codeSpanShape } from '@src/core'
+*
+* const codeSpan = createContract(codeSpanShape)
+* codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
 * ```
 */
-function scanEmphasis(source, start, to, depth = 0) {
-	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;
-	let index = openEnd;
-	while (index < to) {
-		const character = source[index] ?? "";
-		if (character === "\\") {
-			index += 2;
-			continue;
-		}
-		if (character === "`") {
-			const span = scanCode(source, index, to);
-			index = span ? span.end : index + 1;
-			continue;
-		}
-		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)
-				},
-				end: index + run
-			};
-			index += closeRun;
-			continue;
-		}
-		index += 1;
-	}
-}
+var codeSpanShape = objectShape({
+	element: literalShape(["codeSpan"]),
+	value: stringShape()
+});
 /**
-* Scan the window `[from, to)` of `source` into inline nodes - the single recursive
-* engine the inline phase runs on (emphasis / link text recurse through it). Linear:
-* each character is consumed once; a failed construct emits its opening character as
-* text and advances by one, so there is no re-scan (no ReDoS).
+* The shape of a {@link LineBreakNode} - a GFM hard line-break leaf.
 *
-* @param source - The inline source text
-* @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.
-* @returns The parsed inline nodes (NOT yet coalesced)
+* @example
+* ```ts
+* import { createContract } from '@orkestrel/contract'
+* import { lineBreakShape } from '@src/core'
+*
+* const lineBreak = createContract(lineBreakShape)
+* lineBreak.is({ element: 'break' }) // true
+* ```
+*/
+var lineBreakShape = objectShape({ element: literalShape(["break"]) });
+/**
+* The shape of a {@link CodeBlockNode} - a fenced code block. `lang` is
+* optional (absent when the opening fence carries no info-string).
 *
 * @example
 * ```ts
-* scanInline('hi *there*', 0, 10) // [{ element: 'text', value: 'hi ' }, { element: 'emphasis', ... }]
+* 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
 * ```
 */
-function scanInline(source, from, to, depth = 0) {
-	if (depth >= 64) return from < to ? [{
-		element: "text",
-		value: source.slice(from, to)
-	}] : [];
-	const nodes = [];
-	let index = from;
-	let pending = "";
-	while (index < to) {
-		const character = source[index] ?? "";
-		if (character === "\\" && index + 1 < to && isEscapable(source[index + 1] ?? "")) {
-			pending += source[index + 1] ?? "";
-			index += 2;
-			continue;
-		}
-		let scanned;
-		let end = index;
-		if (character === "`") {
-			const span = scanCode(source, index, to);
-			if (span) {
-				scanned = {
-					element: "codeSpan",
-					value: span.value
-				};
-				end = span.end;
-			}
-		}
-		if (character === "[") {
-			const link = scanLink(source, index, to, depth);
-			if (link) {
-				scanned = link.node;
-				end = link.end;
-			}
-		}
-		if (character === "*" || character === "_") {
-			const emphasis = scanEmphasis(source, index, to, depth);
-			if (emphasis) {
-				scanned = emphasis.node;
-				end = emphasis.end;
-			}
-		}
-		if (scanned !== void 0) {
-			if (pending.length > 0) {
-				nodes.push({
-					element: "text",
-					value: pending
-				});
-				pending = "";
-			}
-			nodes.push(scanned);
-			index = end;
-			continue;
-		}
-		pending += character;
-		index += 1;
-	}
-	if (pending.length > 0) nodes.push({
-		element: "text",
-		value: pending
-	});
-	return nodes;
-}
+var codeBlockShape = objectShape({
+	element: literalShape(["codeBlock"]),
+	lang: optionalShape(stringShape()),
+	code: stringShape()
+});
 /**
-* HTML-escape text content - `&` / `<` / `>` / `"` / `'` to their entities - so text
-* from a markdown document can never inject markup. The renderer applies this to every
-* text run, code body, and (escaped further) attribute value.
-*
-* @param text - The raw text
-* @returns The HTML-escaped text
+* The shape of a {@link ThematicBreakNode} - a horizontal rule. Carries no
+* fields beyond its `element` discriminant.
 *
 * @example
 * ```ts
-* escapeHtml('<a>&"\'') // '&lt;a&gt;&amp;&quot;&#39;'
+* import { createContract } from '@orkestrel/contract'
+* import { thematicBreakShape } from '@src/core'
+*
+* const thematicBreak = createContract(thematicBreakShape)
+* thematicBreak.is({ element: 'thematicBreak' }) // true
 * ```
 */
-function escapeHtml(text) {
-	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
-}
+var thematicBreakShape = objectShape({ element: literalShape(["thematicBreak"]) });
 /**
-* Sanitize + HTML-attribute-escape a link `href` - a destination whose scheme is not
-* in {@link SAFE_URL_SCHEMES} (notably `javascript:` / `data:` / `vbscript:`), or that
-* is protocol-relative (`//host/path`, or a backslash variant a browser normalizes to
-* the same effect - `\\host`, `/\host`, `\/host` - inherits whatever scheme the
-* embedding page is served over, including an unsafe one), is dropped to an empty
-* string; a relative / anchor / scheme-less (and non-protocol-relative) destination
-* (including a SINGLE leading `/` or `\`) is kept;
-* the surviving value is then HTML-escaped. Defence-in-depth against an XSS `href`,
-* even though the input is trusted.
+* 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'
 *
-* @param href - The raw link destination
-* @returns A safe, escaped `href` (empty when the scheme is unsafe or protocol-relative)
+* const tableAlign = createContract(tableAlignShape)
+* tableAlign.is('left')   // true
+* tableAlign.is('center') // true
+* tableAlign.is('top')    // false
+* ```
+*/
+var tableAlignShape = literalShape([
+	"left",
+	"right",
+	"center"
+]);
+/**
+* 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
-* sanitizeUrl('javascript:alert(1)') // ''
-* sanitizeUrl('/path')               // '/path'
+* 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
 * ```
 */
-function sanitizeUrl(href) {
-	let cleaned = "";
-	for (const character of href) {
-		const code = character.codePointAt(0) ?? 0;
-		if (code > 32 && !(code >= 127 && code <= 159)) cleaned += character;
-	}
-	if (/^[/\\]{2}/.exec(cleaned)) return "";
-	const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(cleaned);
-	if (scheme && scheme[1] !== void 0 && !SAFE_URL_SCHEMES.has(scheme[1].toLowerCase())) return "";
-	return escapeHtml(cleaned);
-}
+var listItemMatchShape = objectShape({
+	ordered: booleanShape(),
+	start: integerShape(),
+	content: stringShape(),
+	indent: integerShape(),
+	marker: integerShape()
+});
+//#endregion
+//#region src/core/factories.ts
 /**
-* Render a {@link MarkdownNode} (typically a {@link MarkdownDocument}) to a safe HTML
-* string - the recursive AST → HTML engine (headings, paragraphs, lists, GFM tables,
-* fenced code, blockquotes, links, emphasis, inline code), escaping every text run and
-* sanitizing every link `href`.
+* Create an HTML-to-markdown projection with absent fields defaulted from
+* {@link EMPTY_PROJECTION} and the block/inline exclusivity invariant enforced.
 *
 * @remarks
-* Total: never throws. At {@link MAX_DEPTH} a value-bearing node (`text` / `codeSpan`)
-* degrades to its escaped `value`; any other node degrades to `''` instead of
-* recursing further, so pathologically deep input cannot exhaust the call stack.
+* A block-bearing projection cannot also expose inline content. Callers may provide
+* both views, but `inlines` is flushed whenever `blocks` is non-empty.
 *
-* @param node - The AST node to render (a full document, or any sub-node)
-* @returns The rendered, XSS-safe HTML string
+* @param parts - The projection fields to provide
+* @returns A complete invariant-preserving projection
 *
 * @example
 * ```ts
-* renderHTML({ element: 'document', children: [
-*   { element: 'heading', level: 1, children: [{ element: 'text', value: 'Hi' }] },
-* ] })
-* // '<h1>Hi</h1>'
+* createProjection({
+*   blocks: [{ element: 'thematicBreak' }],
+*   inlines: [{ element: 'text', value: 'discarded' }],
+* })
+* // { blocks: [{ element: 'thematicBreak' }], inlines: [], text: '', cells: [], rows: [] }
 * ```
 */
-function renderHTML(node) {
-	const stack = [{
-		node,
-		depth: 0,
-		expanded: false,
-		count: 0
-	}];
-	const values = [];
-	while (stack.length > 0) {
-		const frame = stack.pop();
-		if (frame === void 0) continue;
-		const current = frame.node;
-		if (!frame.expanded) {
-			if (frame.depth >= 64) {
-				values.push("value" in current && typeof current.value === "string" ? escapeHtml(current.value) : "");
-				continue;
-			}
-			const children = [];
-			let depth = frame.depth + 1;
-			switch (current.element) {
-				case "document":
-				case "heading":
-				case "paragraph":
-				case "blockquote":
-					for (const child of current.children) if (child !== void 0) children.push(child);
-					break;
-				case "listItem": {
-					const only = current.children[0];
-					if (current.children.length === 1 && only !== void 0 && only.element === "paragraph") {
-						for (const child of only.children) if (child !== void 0) children.push(child);
-					} else for (const child of current.children) if (child !== void 0) children.push(child);
-					break;
-				}
-				case "emphasis":
-				case "link":
-					for (const child of current.children) if (child !== void 0) children.push(child);
-					depth += 1;
-					break;
-				case "list":
-					for (const child of current.items) if (child !== void 0) children.push(child);
-					break;
-				case "table":
-					for (const cell of current.header) if (cell !== void 0) {
-						for (const child of cell) if (child !== void 0) children.push(child);
-					}
-					for (const row of current.rows) if (row !== void 0) {
-						for (const cell of row) if (cell !== void 0) {
-							for (const child of cell) if (child !== void 0) children.push(child);
-						}
-					}
-					depth += 1;
-					break;
-			}
-			stack.push({
-				...frame,
-				expanded: true,
-				count: children.length
-			});
-			for (let index = children.length - 1; index >= 0; index -= 1) {
-				const child = children[index];
-				if (child !== void 0) stack.push({
-					node: child,
-					depth,
-					expanded: false,
-					count: 0
-				});
-			}
-			continue;
-		}
-		const children = frame.count === 0 ? [] : values.splice(values.length - frame.count, frame.count);
-		let value = "";
-		switch (current.element) {
-			case "document":
-				value = children.join("\n");
-				break;
-			case "heading":
-				value = `<h${current.level}>${children.join("")}</h${current.level}>`;
-				break;
-			case "paragraph":
-				value = `<p>${children.join("")}</p>`;
-				break;
-			case "thematicBreak":
-				value = "<hr>";
-				break;
-			case "blockquote":
-				value = `<blockquote>\n${children.join("\n")}\n</blockquote>`;
-				break;
-			case "codeBlock":
-				value = `<pre>${current.lang === void 0 ? "<code>" : `<code class="language-${escapeHtml(current.lang)}">`}${escapeHtml(current.code)}</code></pre>`;
-				break;
-			case "list": {
-				const items = children.join("\n");
-				if (!current.ordered) {
-					value = `<ul>\n${items}\n</ul>`;
-					break;
-				}
-				value = `<ol${current.start !== 1 ? ` start="${current.start}"` : ""}>\n${items}\n</ol>`;
-				break;
-			}
-			case "listItem":
-				value = `<li>${children.join(current.children.length === 1 && current.children[0]?.element === "paragraph" ? "" : "\n")}</li>`;
-				break;
-			case "table": {
-				let offset = 0;
-				const header = [];
-				for (const [column, cell] of current.header.entries()) {
-					if (cell === void 0) continue;
-					const align = current.align[column];
-					const style = align === "left" || align === "right" || align === "center" ? ` style="text-align:${align}"` : "";
-					let count = 0;
-					for (const child of cell) if (child !== void 0) count += 1;
-					header.push(`<th${style}>${children.slice(offset, offset + count).join("")}</th>`);
-					offset += count;
-				}
-				const rows = [];
-				for (const row of current.rows) {
-					const cells = [];
-					for (const [column, cell] of row.entries()) {
-						if (cell === void 0) continue;
-						const align = current.align[column];
-						const style = align === "left" || align === "right" || align === "center" ? ` style="text-align:${align}"` : "";
-						let count = 0;
-						for (const child of cell) if (child !== void 0) count += 1;
-						cells.push(`<td${style}>${children.slice(offset, offset + count).join("")}</td>`);
-						offset += count;
-					}
-					rows.push(`<tr>${cells.join("")}</tr>`);
-				}
-				const body = rows.join("\n");
-				const bodyHtml = isNonEmptyArray(current.rows) ? `\n<tbody>\n${body}\n</tbody>` : "";
-				value = `<table>\n<thead>\n<tr>${header.join("")}</tr>\n</thead>${bodyHtml}\n</table>`;
-				break;
-			}
-			case "text":
-				value = escapeHtml(current.value);
-				break;
-			case "emphasis":
-				value = current.strong ? `<strong>${children.join("")}</strong>` : `<em>${children.join("")}</em>`;
-				break;
-			case "codeSpan":
-				value = `<code>${escapeHtml(current.value)}</code>`;
-				break;
-			case "link":
-				value = `<a href="${sanitizeUrl(current.href)}">${children.join("")}</a>`;
-				break;
-			default:
-				value = "";
-				break;
-		}
-		if (stack.length === 0) return value;
-		values.push(value);
-	}
-	return "";
+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
+	};
 }
 /**
-* Render 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: `*em*` / `**strong**` (underscore emphasis
-* normalizes to asterisks), `- ` bullets, `N. ` sequential ordinals (from the list's
-* `start`), `---` thematic breaks, fenced code blocks (backtick run widened past any
-* 3+ backtick run inside the body), ATX headings, `> `-prefixed blockquote lines, GFM
-* tables (1-space-padded cells, `\|`-escaped pipes, an alignment delimiter row), and
-* `[text](href)` links. A `text` node's literal content is backslash-escaped wherever
-* it would otherwise re-parse as markup (AGENTS §14 parse↔render soundness).
+* 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
-* Total: never throws. At {@link MAX_DEPTH} a value-bearing node degrades to its
-* escaped `value`; any other node degrades to `''`. Blocks are joined by exactly one
-* blank line; a document with zero blocks renders `''`.
+* 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 node - The AST node to render (a full document, or any sub-node)
-* @returns The canonical markdown source
+* @param input - A markdown string to parse, or an already-parsed {@link MarkdownDocument}
+* @returns A working {@link MarkdownInterface}
 *
 * @example
 * ```ts
-* renderMarkdown({ element: 'document', children: [
-*   { element: 'heading', level: 2, children: [{ element: 'text', value: 'Hi' }] },
-* ] })
-* // '## Hi'
+* import { createMarkdown } from '@src/core'
+*
+* const markdown = createMarkdown('# Hi\n\nRead the [guide](./guide.md).')
+* markdown.document.children[0] // { element: 'heading', ... }
 * ```
 */
-function renderMarkdown(node) {
-	const stack = [{
-		node,
-		depth: 0,
-		expanded: false,
-		count: 0,
-		escaped: ""
-	}];
-	const values = [];
-	while (stack.length > 0) {
-		const frame = stack.pop();
-		if (frame === void 0) continue;
-		const current = frame.node;
-		if (!frame.expanded) {
-			let escaped = "";
-			if ((frame.depth >= 64 || current.element === "text") && "value" in current && typeof current.value === "string") for (let index = 0; index < current.value.length; index += 1) {
-				const character = current.value[index] ?? "";
-				const atLineStart = index === 0 || current.value[index - 1] === "\n";
-				if (character === "\\" || character === "*" || character === "_" || character === "`" || character === "[" || character === "]") {
-					escaped += `\\${character}`;
-					continue;
-				}
-				if (atLineStart) {
-					if (character === "#" || character === ">") {
-						escaped += `\\${character}`;
-						continue;
-					}
-					if ((character === "-" || character === "+") && (current.value[index + 1] ?? " ") === " ") {
-						escaped += `\\${character}`;
-						continue;
-					}
-					if (/[0-9]/.test(character)) {
-						let end = index;
-						while (end < current.value.length && /[0-9]/.test(current.value[end] ?? "")) end += 1;
-						const marker = current.value[end];
-						if ((marker === "." || marker === ")") && current.value[end + 1] === " ") {
-							escaped += `${current.value.slice(index, end)}\\${marker}`;
-							index = end;
-							continue;
-						}
-					}
-				}
-				escaped += character;
-			}
-			if (frame.depth >= 64) {
-				values.push(escaped);
-				continue;
-			}
-			const children = [];
-			let depth = frame.depth + 1;
-			switch (current.element) {
-				case "document":
-				case "heading":
-				case "paragraph":
-				case "blockquote":
-				case "listItem":
-				case "emphasis":
-				case "link":
-					for (const child of current.children) if (child !== void 0) children.push(child);
-					break;
-				case "list":
-					for (const child of current.items) if (child !== void 0) children.push(child);
-					break;
-				case "table":
-					for (const cell of current.header) if (cell !== void 0) {
-						for (const child of cell) if (child !== void 0) children.push(child);
-					}
-					for (const row of current.rows) {
-						if (row === void 0) continue;
-						for (let column = 0; column < current.header.length; column += 1) {
-							const cell = row[column];
-							if (cell !== void 0) {
-								for (const child of cell) if (child !== void 0) children.push(child);
-							}
-						}
-					}
-					depth += 1;
-					break;
-			}
-			stack.push({
-				...frame,
-				expanded: true,
-				count: children.length,
-				escaped
-			});
-			for (let index = children.length - 1; index >= 0; index -= 1) {
-				const child = children[index];
-				if (child !== void 0) stack.push({
-					node: child,
-					depth,
-					expanded: false,
-					count: 0,
-					escaped: ""
-				});
-			}
+function createMarkdown(input) {
+	return new Markdown(input);
+}
+/**
+* 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).
+*
+* @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 createContract(textShape);
+}
+/**
+* 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).
+*
+* @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 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 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 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 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']
+* ```
+*/
+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;
+}
+/**
+* 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;
+}
+/**
+* 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.
+*
+* @param line - The candidate line
+* @returns The heading level (1–6) and its raw inline text, or `undefined`
+*
+* @example
+* ```ts
+* extractHeading('## Title') // { level: 2, text: 'Title' }
+* ```
+*/
+function extractHeading(line) {
+	const match = /^(#{1,6})(?:\s+(.*))?$/.exec(line.trimStart());
+	if (!match || match[1] === void 0) return void 0;
+	return {
+		level: match[1].length,
+		text: (match[2] ?? "").replace(/\s+#+\s*$/, "").trim()
+	};
+}
+/**
+* Extract 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.
+*
+* @param line - The candidate line
+* @returns The fence marker run and its language tag, or `undefined`
+*
+* @example
+* ```ts
+* extractFence('```ts') // { marker: '```', lang: 'ts' }
+* ```
+*/
+function extractFence(line) {
+	const match = /^\s*(`{3,}|~{3,})\s*(.*)$/.exec(line);
+	if (!match || match[1] === void 0) return void 0;
+	const info = (match[2] ?? "").trim();
+	if (match[1].startsWith("`") && info.includes("`")) return void 0;
+	const lang = isNonEmptyString(info) ? info.split(/\s+/)[0] : void 0;
+	return {
+		marker: match[1],
+		lang
+	};
+}
+/**
+* Extract 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).
+*
+* @param line - The candidate line
+* @returns The list-item parts, or `undefined` when not a list item
+*
+* @example
+* ```ts
+* extractListItem('- item') // { ordered: false, start: 1, content: 'item', indent: 0, marker: 2 }
+* ```
+*/
+function extractListItem(line) {
+	const unordered = /^(\s*)([-*+])\s+(.*)$/.exec(line);
+	if (unordered && unordered[1] !== void 0) {
+		const indent = unordered[1].length;
+		const content = unordered[3] ?? "";
+		return {
+			ordered: false,
+			start: 1,
+			content,
+			indent,
+			marker: line.length - content.length
+		};
+	}
+	const ordered = /^(\s*)(\d{1,9})[.)]\s+(.*)$/.exec(line);
+	if (ordered && ordered[1] !== void 0 && ordered[2] !== void 0) {
+		const indent = ordered[1].length;
+		const content = ordered[3] ?? "";
+		return {
+			ordered: true,
+			start: parseInteger(ordered[2]) ?? 1,
+			content,
+			indent,
+			marker: line.length - content.length
+		};
+	}
+}
+/**
+* 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.
+*
+* @param line - A blockquote line (per {@link isQuote})
+* @returns The line with its leading `>` (and one space) removed
+*
+* @example
+* ```ts
+* stripQuote('> text') // 'text'
+* ```
+*/
+function stripQuote(line) {
+	return line.replace(/^\s{0,3}>\s?/, "");
+}
+/**
+* Split one GFM table row into its cell strings - outer pipes are optional, an escaped
+* pipe (`\|`) inside a cell is NOT a separator (it becomes a literal `|`), and the
+* empty leading / trailing cell produced by an outer `|` is dropped.
+*
+* @param row - The raw table row line
+* @returns The row's cells, in column order
+*
+* @example
+* ```ts
+* splitTableRow('|a|b|') // ['a', 'b']
+* ```
+*/
+function splitTableRow(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 += "|";
+			index += 1;
+		} else if (character === "|") {
+			cells.push(current);
+			current = "";
+		} else current += character;
+	}
+	cells.push(current);
+	if (isNonEmptyArray(cells) && isEmptyString((cells[0] ?? "").trim())) cells.shift();
+	if (isNonEmptyArray(cells) && isEmptyString((cells[cells.length - 1] ?? "").trim())) cells.pop();
+	return cells;
+}
+/**
+* Derive the per-column {@link TableAlign} list from a GFM delimiter row - `:---`
+* left, `---:` right, `:---:` center, and `---` as the explicit no-alignment
+* marker represented by `null`.
+*
+* @param delimiter - The table's delimiter row
+* @returns One alignment per column, in column order
+*
+* @example
+* ```ts
+* delimiterToAlignments('| :--- | ---: |') // ['left', 'right']
+* ```
+*/
+function delimiterToAlignments(delimiter) {
+	return splitTableRow(delimiter).map((cell) => {
+		const text = cell.trim();
+		const left = text.startsWith(":");
+		const right = text.endsWith(":");
+		if (left && right) return "center";
+		if (right) return "right";
+		if (left) return "left";
+		return null;
+	});
+}
+/**
+* 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
+* line).
+*
+* @param lines - The document's lines
+* @param index - The line index to test
+* @returns `true` when the line begins a different block
+*
+* @example
+* ```ts
+* startsBlock(['text', '## Heading'], 1) // true
+* ```
+*/
+function startsBlock(lines, index) {
+	const line = 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
+* link `href` (which is not otherwise inline-parsed) and any plain text run.
+*
+* @param text - The raw text possibly carrying `\x` escapes
+* @returns The text with escapable `\x` reduced to `x`
+*
+* @example
+* ```ts
+* unescapeText('\\*hi\\*') // '*hi*'
+* ```
+*/
+function unescapeText(text) {
+	let out = "";
+	for (let index = 0; index < text.length; index += 1) {
+		const character = text[index] ?? "";
+		if (character === "\\" && isEscapable(text[index + 1] ?? "")) {
+			out += text[index + 1] ?? "";
+			index += 1;
+		} else out += character;
+	}
+	return out;
+}
+/**
+* Merge 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)
+* @returns The nodes with consecutive text nodes concatenated
+*
+* @example
+* ```ts
+* coalesceText([{ element: 'text', value: 'a' }, { element: 'text', value: 'b' }])
+* // [{ element: 'text', value: 'ab' }]
+* ```
+*/
+function coalesceText(nodes) {
+	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);
+	}
+	return out;
+}
+/**
+* Scan 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).
+*
+* @param source - The inline source text
+* @param start - The index of the opening backtick
+* @param to - The exclusive end of the scan window
+* @returns The span text + end index, or `undefined`
+*
+* @example
+* ```ts
+* scanCode('`code`', 0, 6) // { value: 'code', end: 6 }
+* ```
+*/
+function scanCode(source, start, to) {
+	let run = 0;
+	while (start + run < to && source[start + run] === "`") run += 1;
+	const open = "`".repeat(run);
+	let search = start + run;
+	for (;;) {
+		const closeAt = source.indexOf(open, search);
+		if (closeAt === -1 || closeAt + run > to) return void 0;
+		if (source[closeAt - 1] !== "`" && source[closeAt + run] !== "`") {
+			let value = source.slice(start + run, closeAt);
+			if (value.length > 2 && value.startsWith(" ") && value.endsWith(" ") && value.trim().length > 0) value = value.slice(1, -1);
+			return {
+				value,
+				end: closeAt + run
+			};
+		}
+		search = closeAt + 1;
+	}
+}
+/**
+* Scan a link `[text](href)` at `start` - the text runs to a BALANCED `]`, then `(`
+* must immediately follow and the destination runs to the matching `)` (both respect
+* nested delimiters + escapes). Returns the link node, or `undefined` when the shape
+* does not hold (it then degrades to a literal `[`).
+*
+* @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`
+*
+* @example
+* ```ts
+* scanLink('[text](url)', 0, 11)
+* // { node: { element: 'link', href: 'url', children: [...] }, end: 11 }
+* ```
+*/
+function scanLink(source, start, to, depth = 0) {
+	let bracketDepth = 0;
+	let close = -1;
+	for (let index = start; index < to; index += 1) {
+		const character = source[index] ?? "";
+		if (character === "\\") {
+			index += 1;
 			continue;
 		}
-		const children = frame.count === 0 ? [] : values.splice(values.length - frame.count, frame.count);
-		let value = "";
-		switch (current.element) {
-			case "codeBlock":
-			case "codeSpan": {
-				const body = current.element === "codeBlock" ? current.code : current.value;
-				let longest = 0;
-				let run = 0;
-				for (const character of body) if (character === "`") {
-					run += 1;
-					longest = Math.max(longest, run);
-				} else run = 0;
-				const fence = "`".repeat(Math.max(current.element === "codeBlock" ? 3 : 1, longest + 1));
-				if (current.element === "codeBlock") {
-					value = `${fence}${current.lang === void 0 ? "" : current.lang}\n${current.code}\n${fence}`;
-					break;
-				}
-				const pad = current.value.startsWith("`") || current.value.endsWith("`") ? " " : "";
-				value = `${fence}${pad}${current.value}${pad}${fence}`;
-				break;
-			}
-			case "document":
-				value = children.join("\n\n");
-				break;
-			case "heading": {
-				const escaped = children.join("").replace(/(^|[^\\])(#+)$/, (_match, before, hashes) => {
-					return `${before}\\${hashes[0] ?? ""}${hashes.slice(1)}`;
-				});
-				value = `${"#".repeat(current.level)} ${escaped}`;
-				break;
-			}
-			case "paragraph":
-				value = children.join("");
-				break;
-			case "thematicBreak":
-				value = "---";
-				break;
-			case "blockquote":
-				value = children.join("\n\n").split("\n").map((line) => line === "" ? ">" : `> ${line}`).join("\n");
-				break;
-			case "list": {
-				const items = [];
-				let ordinal = current.start;
-				for (const body of children) {
-					const marker = current.ordered ? `${ordinal}. ` : "- ";
-					ordinal += 1;
-					const pad = " ".repeat(marker.length);
-					items.push(body.split("\n").map((line, index) => index === 0 ? marker + line : line === "" ? "" : pad + line).join("\n"));
-				}
-				value = items.join("\n");
-				break;
-			}
-			case "listItem":
-				value = children.join("\n\n");
-				break;
-			case "table": {
-				let offset = 0;
-				const header = [];
-				for (const cell of current.header) {
-					if (cell === void 0) {
-						header.push("");
-						continue;
-					}
-					let count = 0;
-					for (const child of cell) if (child !== void 0) count += 1;
-					header.push(children.slice(offset, offset + count).join("").replace(/\|/g, "\\|"));
-					offset += count;
-				}
-				const delimiter = current.align.map((align) => {
-					if (align === "left") return ":--";
-					if (align === "right") return "--:";
-					if (align === "center") return ":-:";
-					return "---";
-				});
-				const rows = [];
-				for (const row of current.rows) {
-					const cells = [];
-					for (let column = 0; column < current.header.length; column += 1) {
-						const cell = row[column];
-						if (cell === void 0) {
-							cells.push("");
-							continue;
-						}
-						let count = 0;
-						for (const child of cell) if (child !== void 0) count += 1;
-						cells.push(children.slice(offset, offset + count).join("").replace(/\|/g, "\\|"));
-						offset += count;
-					}
-					rows.push(`| ${cells.join(" | ")} |`);
-				}
-				value = [
-					`| ${header.join(" | ")} |`,
-					`| ${delimiter.join(" | ")} |`,
-					...rows
-				].join("\n");
+		if (character === "[") bracketDepth += 1;
+		else if (character === "]") {
+			bracketDepth -= 1;
+			if (bracketDepth === 0) {
+				close = index;
 				break;
 			}
-			case "text":
-				value = frame.escaped;
-				break;
-			case "emphasis": {
-				const marker = current.strong ? "**" : "*";
-				value = `${marker}${children.join("")}${marker}`;
+		}
+	}
+	if (close === -1 || source[close + 1] !== "(") return void 0;
+	let parenDepth = 0;
+	let parenClose = -1;
+	for (let index = close + 1; index < to; index += 1) {
+		const character = source[index] ?? "";
+		if (character === "\\") {
+			index += 1;
+			continue;
+		}
+		if (character === "(") parenDepth += 1;
+		else if (character === ")") {
+			parenDepth -= 1;
+			if (parenDepth === 0) {
+				parenClose = index;
 				break;
 			}
-			case "link": {
-				const href = current.href.replace(/[\\()]/g, (character) => `\\${character}`);
-				value = `[${children.join("")}](${href})`;
-				break;
+		}
+	}
+	if (parenClose === -1) return void 0;
+	return {
+		node: {
+			element: "link",
+			href: unescapeText(source.slice(close + 2, parenClose).trim()),
+			children: scanInline(source, start + 1, close, depth + 1)
+		},
+		end: parenClose + 1
+	};
+}
+/**
+* Scan an emphasis run at `start` (`*` / `_`, doubled for strong) - finds the nearest
+* matching closing run of the same marker + width while skipping complete nested
+* runs from the other marker family, and requires non-space immediately inside both
+* delimiters (the CommonMark flanking simplification that blocks `* x *`). Returns
+* the emphasis node, or `undefined` when no valid closer exists (it then degrades to
+* a literal marker).
+*
+* @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`
+*
+* @example
+* ```ts
+* scanEmphasis('*em*', 0, 4)
+* // { node: { element: 'emphasis', strong: false, children: [...] }, end: 4 }
+* ```
+*/
+function scanEmphasis(source, start, to, depth = 0) {
+	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;
+	let index = openEnd;
+	while (index < to) {
+		const character = source[index] ?? "";
+		if (character === "\\") {
+			index += 2;
+			continue;
+		}
+		if (character === "`") {
+			const span = scanCode(source, index, to);
+			index = span ? span.end : index + 1;
+			continue;
+		}
+		if ((character === "*" || character === "_") && character !== marker) {
+			const nested = scanEmphasis(source, index, to, depth + 1);
+			if (nested !== void 0) {
+				index = nested.end;
+				continue;
 			}
-			default:
-				value = "";
-				break;
 		}
-		if (stack.length === 0) return value;
-		values.push(value);
+		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)
+				},
+				end: index + run
+			};
+			index += closeRun;
+			continue;
+		}
+		index += 1;
 	}
-	return "";
 }
 /**
-* Depth-first, pre-order, root-inclusive traversal of a {@link MarkdownNode} - yields
-* the node itself, then recurses into its children (block children, list items, table
-* header/row cells' inline nodes) in walk order.
-*
-* @remarks
-* Total: never throws. Descent stops at {@link MAX_DEPTH} (the node at the cap is
-* still yielded; its children are not) so pathologically deep input cannot exhaust
-* the call stack.
+* Scan the window `[from, to)` of `source` into inline nodes - the single recursive
+* engine the inline phase runs on (emphasis, link text, and image alternative
+* content recurse through it). Linear:
+* each character is consumed once; a failed construct emits its opening character as
+* text and advances by one, so there is no re-scan (no ReDoS).
 *
-* @param node - The AST node to walk (a full document, or any sub-node)
-* @returns A generator yielding every visited node, pre-order
+* @param source - The inline source text
+* @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.
+* @returns The parsed inline nodes (NOT yet coalesced)
 *
 * @example
 * ```ts
-* const doc = { element: 'document', children: [{ element: 'thematicBreak' }] } as const
-* [...walkNodes(doc)].map((node) => node.element) // ['document', 'thematicBreak']
+* scanInline('hi *there*', 0, 10) // [{ element: 'text', value: 'hi ' }, { element: 'emphasis', ... }]
 * ```
 */
-function* walkNodes(node) {
-	const stack = [{
-		node,
-		depth: 0
-	}];
-	while (stack.length > 0) {
-		const frame = stack.pop();
-		if (frame === void 0) continue;
-		yield frame.node;
-		if (frame.depth >= 64) continue;
-		const children = [];
-		switch (frame.node.element) {
-			case "document":
-			case "heading":
-			case "paragraph":
-			case "blockquote":
-			case "listItem":
-			case "emphasis":
-			case "link":
-				for (const child of frame.node.children) if (child !== void 0) children.push(child);
-				break;
-			case "list":
-				for (const child of frame.node.items) if (child !== void 0) children.push(child);
-				break;
-			case "table":
-				for (const cell of frame.node.header) if (cell !== void 0) {
-					for (const child of cell) if (child !== void 0) children.push(child);
-				}
-				for (const row of frame.node.rows) if (row !== void 0) {
-					for (const cell of row) if (cell !== void 0) {
-						for (const child of cell) if (child !== void 0) children.push(child);
-					}
+function scanInline(source, from, to, depth = 0) {
+	if (depth >= 64) return from < to ? [{
+		element: "text",
+		value: source.slice(from, to)
+	}] : [];
+	const nodes = [];
+	let index = from;
+	let pending = "";
+	while (index < to) {
+		const character = source[index] ?? "";
+		if (character === "\\" && index + 1 < to && isEscapable(source[index + 1] ?? "")) {
+			pending += source[index + 1] ?? "";
+			index += 2;
+			continue;
+		}
+		if (character === " ") {
+			let spaceEnd = index;
+			while (spaceEnd < to && source[spaceEnd] === " ") spaceEnd += 1;
+			if (spaceEnd - index >= 2 && source[spaceEnd] === "\n") {
+				if (pending.length > 0) {
+					nodes.push({
+						element: "text",
+						value: pending
+					});
+					pending = "";
 				}
-				break;
+				nodes.push({ element: "break" });
+				index = spaceEnd + 1;
+				continue;
+			}
 		}
-		for (let index = children.length - 1; index >= 0; index -= 1) {
-			const child = children[index];
-			if (child !== void 0) stack.push({
-				node: child,
-				depth: frame.depth + 1
-			});
+		let scanned;
+		let end = index;
+		if (character === "`") {
+			const span = scanCode(source, index, to);
+			if (span) {
+				scanned = {
+					element: "codeSpan",
+					value: span.value
+				};
+				end = span.end;
+			}
+		}
+		if (character === "!" && source[index + 1] === "[") {
+			const link = scanLink(source, index + 1, to, depth);
+			if (link) {
+				scanned = {
+					element: "image",
+					src: link.node.href,
+					children: link.node.children
+				};
+				end = link.end;
+			}
+		}
+		if (character === "[") {
+			const link = scanLink(source, index, to, depth);
+			if (link) {
+				scanned = link.node;
+				end = link.end;
+			}
+		}
+		if (character === "*" || character === "_") {
+			const emphasis = scanEmphasis(source, index, to, depth);
+			if (emphasis) {
+				scanned = emphasis.node;
+				end = emphasis.end;
+			}
+		}
+		if (scanned !== void 0) {
+			if (pending.length > 0) {
+				nodes.push({
+					element: "text",
+					value: pending
+				});
+				pending = "";
+			}
+			nodes.push(scanned);
+			index = end;
+			continue;
 		}
+		pending += character;
+		index += 1;
 	}
+	if (pending.length > 0) nodes.push({
+		element: "text",
+		value: pending
+	});
+	return nodes;
 }
 /**
-* Fold a {@link MarkdownNode} into a `T` via a total catamorphism - children are
-* folded first (post-order), then the node's own {@link MarkdownHandler} is invoked
-* with the already-folded children.
+* Project a {@link MarkdownNode} into an unsanitized {@link HTMLDocument}.
 *
 * @remarks
-* **Table contract.** A {@link TableNode} has no single `children` array - its cells
-* live in `header` (one inline-node list per column) and `rows` (a list of such
-* rows). The `table` handler receives ONE folded `T` per inline node, flattened in
-* walk order across ALL cells - every header cell's inline nodes (column order), then
-* every body row's cells' inline nodes (row order, then column order) - and reads
-* `node.header[c].length` / `node.rows[r][c].length` off the table node itself to
-* recover cell boundaries within the flat list.
-*
-* Total: never throws. At `depth >= {@link MAX_DEPTH}` the node's handler is invoked
-* with an empty children list instead of recursing further.
+* The projection is pure and iterative. Text and attribute values remain literal for
+* `@orkestrel/html` to encode, and URL values remain unsanitized so callers can choose
+* their own HTML policy. Projected HTML element depth, including generated `pre > code`
+* and table scaffolding, never exceeds {@link MAX_DEPTH}. At the cap a node carrying a
+* string `value` degrades to a text node and a structural node contributes nothing.
 *
-* @param node - The AST node to fold
-* @param handlers - The total {@link MarkdownHandlers} table, one handler per element
-* @param depth - The starting recursion depth (pass `0` at the entry point)
-* @returns The folded `T`
+* @param node - The markdown document or bare node to project
+* @returns An unsanitized HTML document wrapping the projected node or nodes
 *
 * @example
 * ```ts
-* const countHandlers: MarkdownHandlers<number> = {
-*   document: (_, children) => children.reduce((a, b) => a + b, 1),
-*   // ...one handler per element, each summing its folded children
-* }
-* foldNode(document, countHandlers, 0) // total node count
+* markdownToHTML({ element: 'text', value: 'a & b' })
+* // { category: 'document', children: [{ category: 'text', value: 'a & b' }] }
 * ```
 */
-function foldNode(node, handlers, depth) {
+function markdownToHTML(node) {
 	const stack = [{
 		node,
-		depth,
+		depth: 0,
 		expanded: false,
 		count: 0
 	}];
@@ -1487,31 +1672,62 @@ function foldNode(node, handlers, depth) {
 	while (stack.length > 0) {
 		const frame = stack.pop();
 		if (frame === void 0) continue;
+		const current = frame.node;
 		if (!frame.expanded) {
+			if (frame.depth >= 64) {
+				values.push("value" in current && typeof current.value === "string" ? {
+					category: "text",
+					value: current.value
+				} : void 0);
+				continue;
+			}
 			const children = [];
-			if (frame.depth < 64) switch (frame.node.element) {
+			let depth = frame.depth;
+			switch (current.element) {
 				case "document":
+					for (const child of current.children) if (child !== void 0) children.push(child);
+					break;
 				case "heading":
 				case "paragraph":
 				case "blockquote":
-				case "listItem":
+					for (const child of current.children) if (child !== void 0) children.push(child);
+					depth += 1;
+					break;
+				case "listItem": {
+					const only = current.children[0];
+					if (current.children.length === 1 && only !== void 0 && only.element === "paragraph") {
+						for (const child of only.children) if (child !== void 0) children.push(child);
+					} else for (const child of current.children) if (child !== void 0) children.push(child);
+					depth += 1;
+					break;
+				}
 				case "emphasis":
 				case "link":
-					for (const child of frame.node.children) if (child !== void 0) children.push(child);
+					for (const child of current.children) if (child !== void 0) children.push(child);
+					depth += 1;
 					break;
 				case "list":
-					for (const child of frame.node.items) if (child !== void 0) children.push(child);
+					for (const child of current.items) if (child !== void 0) children.push(child);
+					depth += 1;
 					break;
 				case "table":
-					for (const cell of frame.node.header) if (cell !== void 0) {
+					if (frame.depth + 4 > 64) {
+						values.push(void 0);
+						continue;
+					}
+					for (const cell of current.header) if (cell !== void 0) {
 						for (const child of cell) if (child !== void 0) children.push(child);
 					}
-					for (const row of frame.node.rows) if (row !== void 0) {
+					for (const row of current.rows) if (row !== void 0) {
 						for (const cell of row) if (cell !== void 0) {
 							for (const child of cell) if (child !== void 0) children.push(child);
 						}
 					}
-					break;
+					depth += 4;
+			}
+			if (current.element === "codeBlock" && frame.depth + 2 > 64) {
+				values.push(void 0);
+				continue;
 			}
 			stack.push({
 				...frame,
@@ -1522,7 +1738,7 @@ function foldNode(node, handlers, depth) {
 				const child = children[index];
 				if (child !== void 0) stack.push({
 					node: child,
-					depth: frame.depth + 1,
+					depth,
 					expanded: false,
 					count: 0
 				});
@@ -1530,105 +1746,291 @@ function foldNode(node, handlers, depth) {
 			continue;
 		}
 		const children = frame.count === 0 ? [] : values.splice(values.length - frame.count, frame.count);
+		const projected = [];
+		for (const child of children) if (child !== void 0) projected.push(child);
 		let value;
-		switch (frame.node.element) {
+		switch (current.element) {
 			case "document":
-				value = handlers.document(frame.node, children);
+				value = {
+					category: "document",
+					children: projected
+				};
 				break;
 			case "heading":
-				value = handlers.heading(frame.node, children);
+				value = {
+					category: "element",
+					name: `h${current.level}`,
+					attributes: [],
+					children: projected
+				};
 				break;
 			case "paragraph":
-				value = handlers.paragraph(frame.node, children);
+				value = {
+					category: "element",
+					name: "p",
+					attributes: [],
+					children: projected
+				};
 				break;
 			case "thematicBreak":
-				value = handlers.thematicBreak(frame.node, children);
+				value = {
+					category: "element",
+					name: "hr",
+					attributes: [],
+					children: []
+				};
 				break;
 			case "blockquote":
-				value = handlers.blockquote(frame.node, children);
+				value = {
+					category: "element",
+					name: "blockquote",
+					attributes: [],
+					children: projected
+				};
 				break;
 			case "codeBlock":
-				value = handlers.codeBlock(frame.node, children);
+				value = {
+					category: "element",
+					name: "pre",
+					attributes: [],
+					children: [{
+						category: "element",
+						name: "code",
+						attributes: current.lang === void 0 ? [] : [{
+							name: "class",
+							value: `language-${current.lang}`
+						}],
+						children: [{
+							category: "text",
+							value: current.code
+						}]
+					}]
+				};
 				break;
 			case "list":
-				value = handlers.list(frame.node, children);
+				value = {
+					category: "element",
+					name: current.ordered ? "ol" : "ul",
+					attributes: current.ordered && current.start !== 1 ? [{
+						name: "start",
+						value: String(current.start)
+					}] : [],
+					children: projected
+				};
 				break;
 			case "listItem":
-				value = handlers.listItem(frame.node, children);
+				value = {
+					category: "element",
+					name: "li",
+					attributes: [],
+					children: projected
+				};
 				break;
-			case "table":
-				value = handlers.table(frame.node, children);
+			case "table": {
+				let offset = 0;
+				const header = [];
+				for (const [column, cell] of current.header.entries()) {
+					if (cell === void 0) continue;
+					const align = current.align[column];
+					const attributes = align === "left" || align === "right" || align === "center" ? [{
+						name: "align",
+						value: align
+					}] : [];
+					let count = 0;
+					for (const child of cell) if (child !== void 0) count += 1;
+					const cellChildren = [];
+					for (const child of children.slice(offset, offset + count)) if (child !== void 0) cellChildren.push(child);
+					header.push({
+						category: "element",
+						name: "th",
+						attributes,
+						children: cellChildren
+					});
+					offset += count;
+				}
+				const rows = [];
+				for (const row of current.rows) {
+					const cells = [];
+					for (const [column, cell] of row.entries()) {
+						if (cell === void 0) continue;
+						const align = current.align[column];
+						const attributes = align === "left" || align === "right" || align === "center" ? [{
+							name: "align",
+							value: align
+						}] : [];
+						let count = 0;
+						for (const child of cell) if (child !== void 0) count += 1;
+						const cellChildren = [];
+						for (const child of children.slice(offset, offset + count)) if (child !== void 0) cellChildren.push(child);
+						cells.push({
+							category: "element",
+							name: "td",
+							attributes,
+							children: cellChildren
+						});
+						offset += count;
+					}
+					rows.push({
+						category: "element",
+						name: "tr",
+						attributes: [],
+						children: cells
+					});
+				}
+				const tableChildren = [{
+					category: "element",
+					name: "thead",
+					attributes: [],
+					children: [{
+						category: "element",
+						name: "tr",
+						attributes: [],
+						children: header
+					}]
+				}];
+				if (isNonEmptyArray(current.rows)) tableChildren.push({
+					category: "element",
+					name: "tbody",
+					attributes: [],
+					children: rows
+				});
+				value = {
+					category: "element",
+					name: "table",
+					attributes: [],
+					children: tableChildren
+				};
 				break;
+			}
 			case "text":
-				value = handlers.text(frame.node, children);
+				value = {
+					category: "text",
+					value: current.value
+				};
 				break;
 			case "emphasis":
-				value = handlers.emphasis(frame.node, children);
+				value = {
+					category: "element",
+					name: current.strong ? "strong" : "em",
+					attributes: [],
+					children: projected
+				};
 				break;
 			case "codeSpan":
-				value = handlers.codeSpan(frame.node, children);
+				value = {
+					category: "element",
+					name: "code",
+					attributes: [],
+					children: [{
+						category: "text",
+						value: current.value
+					}]
+				};
 				break;
 			case "link":
-				value = handlers.link(frame.node, children);
+				value = {
+					category: "element",
+					name: "a",
+					attributes: [{
+						name: "href",
+						value: current.href
+					}],
+					children: projected
+				};
+				break;
+			case "image":
+				value = {
+					category: "element",
+					name: "img",
+					attributes: [{
+						name: "src",
+						value: current.src
+					}, {
+						name: "alt",
+						value: flattenText(current)
+					}],
+					children: []
+				};
+				break;
+			case "break":
+				value = {
+					category: "element",
+					name: "br",
+					attributes: [],
+					children: []
+				};
 				break;
+			default: value = void 0;
 		}
-		if (stack.length === 0) return value;
 		values.push(value);
 	}
-	switch (node.element) {
-		case "document": return handlers.document(node, []);
-		case "heading": return handlers.heading(node, []);
-		case "paragraph": return handlers.paragraph(node, []);
-		case "thematicBreak": return handlers.thematicBreak(node, []);
-		case "blockquote": return handlers.blockquote(node, []);
-		case "codeBlock": return handlers.codeBlock(node, []);
-		case "list": return handlers.list(node, []);
-		case "listItem": return handlers.listItem(node, []);
-		case "table": return handlers.table(node, []);
-		case "text": return handlers.text(node, []);
-		case "emphasis": return handlers.emphasis(node, []);
-		case "codeSpan": return handlers.codeSpan(node, []);
-		case "link": return handlers.link(node, []);
-	}
+	const projected = values[0];
+	if (projected?.category === "document") return projected;
+	return {
+		category: "document",
+		children: projected === void 0 ? [] : [projected]
+	};
 }
 /**
-* Rewrite 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.
+* Render a {@link MarkdownNode} to sanitized canonical HTML.
 *
 * @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
-* 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.
+* 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.
 *
-* 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
-* UNCHANGED (by reference, not rebuilt, and `rewrite` is not invoked on it) instead of
-* recursing further, so a pathologically deep adopted document cannot exhaust the
-* call stack. {@link MarkdownInterface.map} inherits this cap since it delegates here.
+* @param node - The markdown document or bare node to render
+* @returns Sanitized canonical HTML
 *
-* @param document - The document AST to rewrite
-* @param rewrite - The bottom-up {@link MarkdownRewriteHandler}
-* @returns A new, rewritten {@link MarkdownDocument}
+* @example
+* ```ts
+* renderHTML({ element: 'paragraph', children: [{ element: 'text', value: 'a & b' }] })
+* // '<p>a &amp; b</p>'
+* ```
+*/
+function renderHTML(node) {
+	return renderHTML$1(new HTML(markdownToHTML(node)).sanitize({ attributes: [...SAFE_ATTRIBUTES, "src"] }).document);
+}
+/**
+* Render 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
+* ordinals (from the list's `start`), `---` thematic breaks, fenced code blocks
+* (backtick run widened past any 3+ backtick run inside the body), ATX headings,
+* `> `-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).
+*
+* @remarks
+* Total: never throws. At {@link MAX_DEPTH} a value-bearing node degrades to its
+* escaped `value`; any other node degrades to `''`. Blocks are joined by exactly one
+* blank line; a document with zero blocks renders `''`.
+*
+* @param node - The AST node to render (a full document, or any sub-node)
+* @returns The canonical markdown source
 *
 * @example
 * ```ts
-* rewriteDocument(document, (node) =>
-*   node.element === 'text' ? { element: 'text', value: node.value.toUpperCase() } : node,
-* )
+* renderMarkdown({ element: 'document', children: [
+*   { element: 'heading', level: 2, children: [{ element: 'text', value: 'Hi' }] },
+* ] })
+* // '## Hi'
 * ```
 */
-function rewriteDocument(document, rewrite) {
+function renderMarkdown(node) {
 	const stack = [{
-		node: document,
-		depth: -1,
+		node,
+		depth: 0,
 		expanded: false,
-		count: 0
+		count: 0,
+		escaped: "",
+		escapeBang: false,
+		nesting: 0
 	}];
 	const values = [];
 	while (stack.length > 0) {
@@ -1636,887 +2038,1461 @@ function rewriteDocument(document, rewrite) {
 		if (frame === void 0) continue;
 		const current = frame.node;
 		if (!frame.expanded) {
-			if (current.element !== "document" && frame.depth >= 64) {
-				values.push(current);
+			let escaped = "";
+			if ((frame.depth >= 64 || current.element === "text") && "value" in current && typeof current.value === "string") for (let index = 0; index < current.value.length; index += 1) {
+				const character = current.value[index] ?? "";
+				const atLineStart = index === 0 || current.value[index - 1] === "\n";
+				if (current.element === "text" && character === "!" && index === current.value.length - 1 && frame.escapeBang) {
+					escaped += "\\!";
+					continue;
+				}
+				if (character === "\\" || character === "*" || character === "_" || character === "`" || character === "[" || character === "]") {
+					escaped += `\\${character}`;
+					continue;
+				}
+				if (atLineStart) {
+					if (character === "#" || character === ">") {
+						escaped += `\\${character}`;
+						continue;
+					}
+					if ((character === "-" || character === "~") && current.value[index + 1] === character && current.value[index + 2] === character) {
+						escaped += `\\${character}`;
+						continue;
+					}
+					if ((character === "-" || character === "+") && (current.value[index + 1] ?? " ") === " ") {
+						escaped += `\\${character}`;
+						continue;
+					}
+					if (/[0-9]/.test(character)) {
+						let end = index;
+						while (end < current.value.length && /[0-9]/.test(current.value[end] ?? "")) end += 1;
+						const marker = current.value[end];
+						if ((marker === "." || marker === ")") && current.value[end + 1] === " ") {
+							escaped += `${current.value.slice(index, end)}\\${marker}`;
+							index = end;
+							continue;
+						}
+					}
+				}
+				escaped += character;
+			}
+			if (frame.depth >= 64) {
+				values.push(escaped);
 				continue;
 			}
-			const children = [];
+			const groups = [];
+			const adjacent = [];
+			let depth = frame.depth + 1;
 			switch (current.element) {
 				case "document":
-				case "heading":
-				case "paragraph":
 				case "blockquote":
 				case "listItem":
+					groups.push(current.children);
+					adjacent.push(false);
+					break;
+				case "heading":
+				case "paragraph":
 				case "emphasis":
 				case "link":
-					for (const child of current.children) if (child !== void 0) children.push(child);
+				case "image":
+					groups.push(current.children);
+					adjacent.push(true);
 					break;
 				case "list":
-					for (const child of current.items) if (child !== void 0) children.push(child);
+					groups.push(current.items);
+					adjacent.push(false);
 					break;
 				case "table":
 					for (const cell of current.header) if (cell !== void 0) {
-						for (const child of cell) if (child !== void 0) children.push(child);
+						groups.push(cell);
+						adjacent.push(true);
 					}
-					for (const row of current.rows) if (row !== void 0) {
-						for (const cell of row) if (cell !== void 0) {
-							for (const child of cell) if (child !== void 0) children.push(child);
+					for (const row of current.rows) {
+						if (row === void 0) continue;
+						for (let column = 0; column < current.header.length; column += 1) {
+							const cell = row[column];
+							if (cell !== void 0) {
+								groups.push(cell);
+								adjacent.push(true);
+							}
 						}
 					}
-					break;
+					depth += 1;
+			}
+			const children = [];
+			const escapeBangs = [];
+			for (let groupIndex = 0; groupIndex < groups.length; groupIndex += 1) {
+				const group = groups[groupIndex];
+				if (group === void 0) continue;
+				for (let position = 0; position < group.length; position += 1) {
+					const child = group[position];
+					if (child === void 0) continue;
+					let escapeBang = false;
+					if (adjacent[groupIndex] === true) {
+						let nextPosition = position + 1;
+						let next = group[nextPosition];
+						while (next === void 0 && nextPosition < group.length) {
+							nextPosition += 1;
+							next = group[nextPosition];
+						}
+						escapeBang = next?.element === "link";
+					}
+					children.push(child);
+					escapeBangs.push(escapeBang);
+				}
 			}
 			stack.push({
 				...frame,
 				expanded: true,
-				count: children.length
+				count: children.length,
+				escaped
 			});
-			const depth = current.element === "document" ? 0 : frame.depth + 1;
+			const nesting = current.element === "emphasis" ? frame.nesting + 1 : frame.nesting;
 			for (let index = children.length - 1; index >= 0; index -= 1) {
 				const child = children[index];
 				if (child !== void 0) stack.push({
 					node: child,
 					depth,
 					expanded: false,
-					count: 0
+					count: 0,
+					escaped: "",
+					escapeBang: escapeBangs[index] === true && depth < 64,
+					nesting
 				});
 			}
 			continue;
 		}
 		const children = frame.count === 0 ? [] : values.splice(values.length - frame.count, frame.count);
-		let rebuilt = current;
+		let value = "";
 		switch (current.element) {
-			case "document": {
-				const blocks = [];
-				let offset = 0;
-				for (const block of current.children) {
-					if (block === void 0) continue;
-					const child = children[offset];
-					blocks.push(child !== void 0 && isBlockNode(child) ? child : block);
-					offset += 1;
-				}
-				const result = {
-					element: "document",
-					children: blocks
-				};
-				if (stack.length === 0) return result;
-				values.push(result);
-				continue;
-			}
-			case "heading":
-			case "paragraph": {
-				const inlines = [];
-				let offset = 0;
-				for (const inline of current.children) {
-					if (inline === void 0) continue;
-					const child = children[offset];
-					inlines.push(child !== void 0 && isInlineNode(child) ? child : inline);
-					offset += 1;
-				}
-				rebuilt = {
-					...current,
-					children: inlines
-				};
-				break;
-			}
-			case "blockquote": {
-				const blocks = [];
-				let offset = 0;
-				for (const block of current.children) {
-					if (block === void 0) continue;
-					const child = children[offset];
-					blocks.push(child !== void 0 && isBlockNode(child) ? child : block);
-					offset += 1;
-				}
-				rebuilt = {
-					...current,
-					children: blocks
-				};
-				break;
-			}
-			case "listItem": {
-				const blocks = [];
-				let offset = 0;
-				for (const block of current.children) {
-					if (block === void 0) continue;
-					const child = children[offset];
-					blocks.push(child !== void 0 && isBlockNode(child) ? child : block);
-					offset += 1;
-				}
-				rebuilt = {
-					element: "listItem",
-					children: blocks
-				};
-				break;
-			}
-			case "emphasis":
-			case "link": {
-				const inlines = [];
-				let offset = 0;
-				for (const inline of current.children) {
-					if (inline === void 0) continue;
-					const child = children[offset];
-					inlines.push(child !== void 0 && isInlineNode(child) ? child : inline);
-					offset += 1;
+			case "codeBlock":
+			case "codeSpan": {
+				const body = current.element === "codeBlock" ? current.code : current.value;
+				let longest = 0;
+				let run = 0;
+				for (const character of body) if (character === "`") {
+					run += 1;
+					longest = Math.max(longest, run);
+				} else run = 0;
+				const fence = "`".repeat(Math.max(current.element === "codeBlock" ? 3 : 1, longest + 1));
+				if (current.element === "codeBlock") {
+					value = `${fence}${current.lang === void 0 ? "" : current.lang}\n${current.code}\n${fence}`;
+					break;
 				}
-				rebuilt = {
-					...current,
-					children: inlines
-				};
+				const pad = current.value.startsWith("`") || current.value.endsWith("`") ? " " : "";
+				value = `${fence}${pad}${current.value}${pad}${fence}`;
 				break;
 			}
+			case "break":
+				value = "  \n";
+				break;
+			case "document":
+				value = children.join("\n\n");
+				break;
+			case "heading": {
+				const escaped = children.join("").replace(/(^|[^\\])(#+)$/, (_match, before, hashes) => {
+					return `${before}\\${hashes[0] ?? ""}${hashes.slice(1)}`;
+				});
+				value = `${"#".repeat(current.level)} ${escaped}`;
+				break;
+			}
+			case "paragraph":
+				value = children.join("");
+				break;
+			case "thematicBreak":
+				value = "---";
+				break;
+			case "blockquote":
+				value = children.join("\n\n").split("\n").map((line) => line === "" ? ">" : `> ${line}`).join("\n");
+				break;
 			case "list": {
 				const items = [];
-				let offset = 0;
-				for (const item of current.items) {
-					if (item === void 0) continue;
-					const child = children[offset];
-					items.push(child?.element === "listItem" ? child : item);
-					offset += 1;
+				let ordinal = current.start;
+				for (const [position, body] of children.entries()) {
+					const marker = current.ordered ? `${ordinal}. ` : "- ";
+					ordinal += 1;
+					const pad = " ".repeat(marker.length);
+					if (current.items[position]?.children[0]?.element === "table") {
+						items.push(`${marker}\n${body.split("\n").map((line) => pad + line).join("\n")}`);
+						continue;
+					}
+					items.push(body.split("\n").map((line, index) => index === 0 ? marker + line : line === "" ? "" : pad + line).join("\n"));
 				}
-				rebuilt = {
-					...current,
-					items
-				};
+				value = items.join("\n");
 				break;
 			}
+			case "listItem":
+				value = children.join("\n\n");
+				break;
 			case "table": {
 				let offset = 0;
 				const header = [];
 				for (const cell of current.header) {
-					if (cell === void 0) continue;
-					const inlines = [];
-					for (const inline of cell) {
-						if (inline === void 0) continue;
-						const child = children[offset];
-						inlines.push(child !== void 0 && isInlineNode(child) ? child : inline);
-						offset += 1;
+					if (cell === void 0) {
+						header.push("");
+						continue;
 					}
-					header.push(inlines);
+					let count = 0;
+					for (const child of cell) if (child !== void 0) count += 1;
+					header.push(children.slice(offset, offset + count).join("").replace(/\|/g, "\\|"));
+					offset += count;
 				}
+				const delimiter = current.align.map((align) => {
+					if (align === null) return "---";
+					if (align === "left") return ":---";
+					if (align === "right") return "---:";
+					if (align === "center") return ":---:";
+					return "---";
+				});
 				const rows = [];
 				for (const row of current.rows) {
-					if (row === void 0) continue;
 					const cells = [];
-					for (const cell of row) {
-						if (cell === void 0) continue;
-						const inlines = [];
-						for (const inline of cell) {
-							if (inline === void 0) continue;
-							const child = children[offset];
-							inlines.push(child !== void 0 && isInlineNode(child) ? child : inline);
-							offset += 1;
+					for (let column = 0; column < current.header.length; column += 1) {
+						const cell = row[column];
+						if (cell === void 0) {
+							cells.push("");
+							continue;
 						}
-						cells.push(inlines);
+						let count = 0;
+						for (const child of cell) if (child !== void 0) count += 1;
+						cells.push(children.slice(offset, offset + count).join("").replace(/\|/g, "\\|"));
+						offset += count;
 					}
-					rows.push(cells);
+					rows.push(`| ${cells.join(" | ")} |`);
 				}
-				rebuilt = {
-					...current,
-					header,
-					rows
-				};
+				value = [
+					`| ${header.join(" | ")} |`,
+					`| ${delimiter.join(" | ")} |`,
+					...rows
+				].join("\n");
 				break;
 			}
-		}
-		const result = rewrite(rebuilt);
-		let accepted = rebuilt;
-		switch (current.element) {
 			case "text":
-			case "emphasis":
-			case "codeSpan":
-			case "link":
-				if (isInlineNode(result)) accepted = result;
+				value = frame.escaped;
 				break;
-			case "heading":
-			case "paragraph":
-			case "list":
-			case "table":
-			case "codeBlock":
-			case "blockquote":
-			case "thematicBreak":
-				if (isBlockNode(result)) accepted = result;
+			case "emphasis": {
+				const marker = frame.nesting % 2 === 0 ? current.strong ? "**" : "*" : current.strong ? "__" : "_";
+				value = `${marker}${children.join("")}${marker}`;
 				break;
-			case "listItem":
-				if (result.element === "listItem") accepted = result;
+			}
+			case "link":
+			case "image": {
+				const escaped = (current.element === "link" ? current.href : current.src).replace(/[\\()]/g, (character) => `\\${character}`);
+				value = `${current.element === "image" ? "!" : ""}[${children.join("")}](${escaped})`;
 				break;
+			}
+			default: value = "";
 		}
-		values.push(accepted);
+		if (stack.length === 0) return value;
+		values.push(value);
 	}
-	return {
-		element: "document",
-		children: [...document.children]
-	};
+	return "";
 }
 /**
-* Concatenate the `value` / `code` content of every descendant text / code-span /
-* code-block node under `node`, in walk order - the plain-text projection of an AST
-* (search indexing, word counts, a text-only preview).
+* 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.
 *
 * @remarks
-* Total: never throws. Descent stops at {@link MAX_DEPTH} (contributes `''` past the
-* cap instead of recursing further).
+* 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 node - The AST node to flatten (a full document, or any sub-node)
-* @returns The concatenated text content
+* @param nodes - The inline run to trim
+* @returns The run with its edge whitespace removed
 *
 * @example
 * ```ts
-* flattenText({ element: 'paragraph', children: [
-*   { element: 'text', value: 'a ' },
-*   { element: 'codeSpan', value: 'b' },
-* ] })
-* // 'a b'
+* trimInlines([{ element: 'text', value: ' a ' }]) // [{ element: 'text', value: 'a' }]
 * ```
 */
-function flattenText(node) {
-	const stack = [{
-		node,
-		depth: 0
-	}];
-	let value = "";
-	while (stack.length > 0) {
-		const frame = stack.pop();
-		if (frame === void 0 || frame.depth >= 64) continue;
-		const children = [];
-		switch (frame.node.element) {
-			case "text":
-			case "codeSpan":
-				value += frame.node.value;
-				break;
-			case "codeBlock":
-				value += frame.node.code;
-				break;
-			case "document":
-			case "heading":
-			case "paragraph":
-			case "blockquote":
-			case "listItem":
-			case "emphasis":
-			case "link":
-				for (const child of frame.node.children) if (child !== void 0) children.push(child);
-				break;
-			case "list":
-				for (const child of frame.node.items) if (child !== void 0) children.push(child);
-				break;
-			case "table":
-				for (const cell of frame.node.header) if (cell !== void 0) {
-					for (const child of cell) if (child !== void 0) children.push(child);
-				}
-				for (const row of frame.node.rows) if (row !== void 0) {
-					for (const cell of row) if (cell !== void 0) {
-						for (const child of cell) if (child !== void 0) children.push(child);
-					}
-				}
-				break;
-		}
-		for (let index = children.length - 1; index >= 0; index -= 1) {
-			const child = children[index];
-			if (child !== void 0) stack.push({
-				node: child,
-				depth: frame.depth + 1
-			});
-		}
+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 (isEmptyString(value)) out.shift();
+		else out[0] = {
+			element: "text",
+			value
+		};
 	}
-	return value;
+	const last = out[out.length - 1];
+	if (last !== void 0 && last.element === "text") {
+		const value = last.value.replace(/\s+$/, "");
+		if (isEmptyString(value)) out.pop();
+		else out[out.length - 1] = {
+			element: "text",
+			value
+		};
+	}
+	return out;
 }
-//#endregion
-//#region src/core/parsers.ts
 /**
-* Parses a run of markdown lines into a block AST, recursing into nested
-* blockquotes, list items, and depth-capped degrade paragraphs.
+* Reduce 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.
 *
-* @param lines - The markdown lines to parse.
-* @param depth - The current recursion depth (blockquotes/lists increment it).
-* @returns The parsed block nodes.
+* @remarks
+* A hard break is `  \n` in markdown source, so it survives a re-parse only BETWEEN
+* two lines of content and only with no whitespace touching it: a leading or trailing
+* break has no line to end, a run of breaks reads as one blank line (which would end
+* the paragraph), and a space beside one is eaten by the parser's line trimming. Where
+* a break cannot be written at all - a heading and a table cell are one line each - it
+* 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
+* @returns The normalized run
 *
 * @example
 * ```ts
-* parseBlocks(['# Hi'], 0) // [{ element: 'heading', level: 1, children: [...] }]
+* normalizeInlines([{ element: 'break' }, { element: 'text', value: 'a' }], true)
+* // [{ element: 'text', value: 'a' }] - a leading break has no line to end
 * ```
 */
-function parseBlocks(lines, depth) {
-	if (depth >= 64) return lines.length > 0 ? [{
-		element: "paragraph",
-		children: [{
+function normalizeInlines(nodes, breaks) {
+	const spent = [];
+	for (const node of nodes) {
+		if (node === void 0) continue;
+		if (node.element === "break" && !breaks) spent.push({
 			element: "text",
-			value: lines.join("\n")
-		}]
-	}] : [];
-	const blocks = [];
-	let index = 0;
-	while (index < lines.length) {
-		const line = lines[index] ?? "";
-		if (isBlankLine(line)) {
-			index += 1;
-			continue;
-		}
-		const fence = extractFence(line);
-		if (fence) {
-			const body = [];
-			index += 1;
-			while (index < lines.length && !isFenceClose(lines[index] ?? "", fence.marker)) {
-				body.push(lines[index] ?? "");
-				index += 1;
-			}
-			index += 1;
-			blocks.push({
-				element: "codeBlock",
-				...fence.lang === void 0 ? {} : { lang: fence.lang },
-				code: body.join("\n")
+			value: " "
+		});
+		else spent.push(node);
+	}
+	const out = [];
+	for (const node of coalesceText(spent)) {
+		if (node === void 0) continue;
+		const previous = out[out.length - 1];
+		if (node.element === "text") {
+			const value = previous?.element === "break" ? node.value.replace(/^\s+/, "") : node.value;
+			if (!isEmptyString(value)) out.push({
+				element: "text",
+				value
 			});
 			continue;
 		}
-		if (isThematicBreak(line)) {
-			blocks.push({ element: "thematicBreak" });
-			index += 1;
+		if (node.element === "break") {
+			if (previous === void 0 || previous.element === "break") continue;
+			if (previous.element === "text") {
+				const value = previous.value.replace(/\s+$/, "");
+				if (isEmptyString(value)) out.pop();
+				else out[out.length - 1] = {
+					element: "text",
+					value
+				};
+			}
+			if (out.length === 0) continue;
+			out.push(node);
 			continue;
 		}
-		const heading = extractHeading(line);
-		if (heading) {
-			blocks.push({
-				element: "heading",
-				level: heading.level,
-				children: parseInline(heading.text)
+		out.push(node);
+	}
+	while (out.length > 0 && out[out.length - 1]?.element === "break") out.pop();
+	return coalesceText(out);
+}
+/**
+* Combine 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.
+*
+* @remarks
+* A child is either inline or block, never both, so merging preserves source order
+* exactly: an inline run is held pending until a block arrives, then written out as a
+* paragraph BEFORE it. That is what keeps `<div>lead<p>a</p></div>` two paragraphs in
+* the order they were written rather than two lists that lost their interleaving. A
+* pending run carrying no text is dropped rather than becoming a blank paragraph.
+* Direct cells become one row before a later row, while cells/rows before a block
+* materialize as paragraphs at that exact source position.
+*
+* @param children - The children's projections, in source order
+* @returns Their combined projection
+*
+* @example
+* ```ts
+* mergeProjections([
+*   createProjection({ inlines: [{ element: 'text', value: 'a' }], text: 'a' }),
+*   createProjection({ blocks: [{ element: 'thematicBreak' }] }),
+* ]).blocks
+* // [{ element: 'paragraph', children: [...] }, { element: 'thematicBreak' }]
+* ```
+*/
+function mergeProjections(children) {
+	const blocks = [];
+	const cells = [];
+	const rows = [];
+	let pending = [];
+	let text = "";
+	for (const child of children) {
+		if (child === void 0) continue;
+		text += child.text;
+		if (isNonEmptyArray(child.blocks)) {
+			const flushed = trimInlines(normalizeInlines(pending, true));
+			if (isNonEmptyArray(flushed)) blocks.push({
+				element: "paragraph",
+				children: flushed
+			});
+			pending = [];
+			for (const row of rows) for (const cell of row) if (cell !== void 0 && isNonEmptyArray(cell.inlines)) blocks.push({
+				element: "paragraph",
+				children: cell.inlines
 			});
-			index += 1;
+			rows.length = 0;
+			for (const cell of cells) if (cell !== void 0 && isNonEmptyArray(cell.inlines)) blocks.push({
+				element: "paragraph",
+				children: cell.inlines
+			});
+			cells.length = 0;
+			for (const block of projectionToBlocks(child)) blocks.push(block);
 			continue;
 		}
-		if (isQuote(line)) {
-			const quoted = [];
-			while (index < lines.length && isQuote(lines[index] ?? "")) {
-				quoted.push(stripQuote(lines[index] ?? ""));
-				index += 1;
+		if (isNonEmptyArray(child.rows)) {
+			if (isNonEmptyArray(cells)) {
+				rows.push([...cells]);
+				cells.length = 0;
 			}
+			for (const row of child.rows) if (row !== void 0) rows.push(row);
+		}
+		for (const cell of child.cells) if (cell !== void 0) cells.push(cell);
+		for (const inline of child.inlines) if (inline !== void 0) pending.push(inline);
+	}
+	if (isNonEmptyArray(rows) && isNonEmptyArray(cells)) {
+		rows.push([...cells]);
+		cells.length = 0;
+	}
+	if (!isNonEmptyArray(blocks)) return createProjection({
+		inlines: coalesceText(pending),
+		text,
+		cells,
+		rows
+	});
+	const flushed = trimInlines(normalizeInlines(pending, true));
+	if (isNonEmptyArray(flushed)) blocks.push({
+		element: "paragraph",
+		children: flushed
+	});
+	return createProjection({
+		blocks,
+		text,
+		cells,
+		rows
+	});
+}
+/**
+* Read a projection as BLOCK content - the view a document, a blockquote, and a list
+* item each need.
+*
+* @remarks
+* A bare inline run becomes one paragraph, and a run carrying no text becomes nothing
+* at all, because a blank paragraph is unwritable in markdown. A cell or a row that
+* never reached a table is unwrapped here rather than dropped: a stray `<td>` is still
+* someone's content.
+*
+* @param projection - The projection to read
+* @returns Its block content
+*
+* @example
+* ```ts
+* projectionToBlocks(createProjection({ inlines: [{ element: 'text', value: 'a' }], text: 'a' }))
+* // [{ element: 'paragraph', children: [{ element: 'text', value: 'a' }] }]
+* ```
+*/
+function projectionToBlocks(projection) {
+	const blocks = [];
+	for (const block of projection.blocks) if (block !== void 0) blocks.push(block);
+	for (const row of projection.rows) {
+		if (row === void 0) continue;
+		for (const cell of row) {
+			if (cell === void 0 || !isNonEmptyArray(cell.inlines)) continue;
 			blocks.push({
-				element: "blockquote",
-				children: parseBlocks(quoted, depth + 1)
+				element: "paragraph",
+				children: cell.inlines
 			});
-			continue;
-		}
-		if (isTableStart(line, lines[index + 1])) {
-			const table = collectTable(lines, index);
-			blocks.push(table.node);
-			index = table.next;
-			continue;
-		}
-		if (extractListItem(line)) {
-			const list = collectList(lines, index, depth);
-			blocks.push(list.node);
-			index = list.next;
-			continue;
-		}
-		const paragraph = [];
-		while (index < lines.length && !isBlankLine(lines[index] ?? "") && !(isNonEmptyArray(paragraph) && startsBlock(lines, index))) {
-			paragraph.push((lines[index] ?? "").trim());
-			index += 1;
 		}
+	}
+	for (const cell of projection.cells) {
+		if (cell === void 0 || !isNonEmptyArray(cell.inlines)) continue;
 		blocks.push({
 			element: "paragraph",
-			children: parseInline(paragraph.join("\n"))
+			children: cell.inlines
 		});
 	}
+	const paragraph = trimInlines(normalizeInlines(projection.inlines, true));
+	if (isNonEmptyArray(paragraph)) blocks.push({
+		element: "paragraph",
+		children: paragraph
+	});
 	return blocks;
 }
 /**
-* Collects a GFM table starting at a header row, parsing the header, the
-* alignment row, and every contiguous body row that follows.
+* Read a projection as INLINE content - the view a link, an emphasis, and a table cell
+* each need.
 *
-* @param lines - The markdown lines to scan.
-* @param start - The index of the header row.
-* @returns The parsed table node and the index of the first line after it.
+* @remarks
+* Inline content passes through as itself. Block content cannot: markdown has no way to
+* put a paragraph inside a table cell, so it flattens to one text node of its own words,
+* joined and whitespace-collapsed. Content that carries no text flattens to nothing
+* rather than to an empty text node, which is a shape the parser never produces.
+*
+* @param projection - The projection to read
+* @returns Its inline content
 *
 * @example
 * ```ts
-* collectTable(['| a |', '| - |'], 0) // { node: { element: 'table', ... }, next: 2 }
+* projectionToInlines(createProjection({ inlines: [{ element: 'break' }] }))
+* // [{ element: 'break' }]
 * ```
 */
-function collectTable(lines, start) {
-	const headerCells = splitTableRow(lines[start] ?? "");
-	const columns = headerCells.length;
-	const header = headerCells.map((cell) => parseInline(cell.trim()));
-	const align = tableAlignments(lines[start + 1] ?? "");
-	const padded = [];
-	for (let column = 0; column < columns; column += 1) padded.push(align[column] ?? "none");
-	const rows = [];
-	let index = start + 2;
-	while (index < lines.length && !isBlankLine(lines[index] ?? "") && (lines[index] ?? "").includes("|")) {
-		const cells = splitTableRow(lines[index] ?? "");
-		const row = [];
-		for (let column = 0; column < columns; column += 1) row.push(parseInline((cells[column] ?? "").trim()));
-		rows.push(row);
-		index += 1;
-	}
-	return {
-		node: {
-			element: "table",
-			header,
-			rows,
-			align: padded
-		},
-		next: index
-	};
+function projectionToInlines(projection) {
+	if (!isNonEmptyArray(projection.blocks) && !isNonEmptyArray(projection.cells) && !isNonEmptyArray(projection.rows)) return coalesceText(projection.inlines);
+	const value = projectionToBlocks(projection).map(flattenText).join(" ").replace(/\s+/g, " ").trim();
+	return isEmptyString(value) ? [] : [{
+		element: "text",
+		value
+	}];
 }
 /**
-* Collects a list starting at the first item, gathering sibling items at the
-* same indent/ordering and recursing into each item's own block content.
+* Project one HTML leaf - a text node, a comment, or a doctype - to its
+* {@link MarkdownProjection}.
 *
-* @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`).
-* @returns The parsed list node and the index of the first line after it.
+* @remarks
+* Text collapses each whitespace run to one space, which is both what HTML means by it
+* and all markdown can write back; the raw value travels on in `text` for the two
+* places that need it verbatim, a code span and a `pre > code` body. A comment and a
+* doctype carry nothing into markdown and project to nothing.
+*
+* @param leaf - The leaf node to project
+* @returns Its projection
 *
 * @example
 * ```ts
-* collectList(['- item'], 0, 0) // { node: { element: 'list', ... }, next: 1 }
+* projectHTMLLeaf({ category: 'text', value: 'a\n  b' }).inlines
+* // [{ element: 'text', value: 'a b' }]
 * ```
 */
-function collectList(lines, start, depth) {
-	const first = extractListItem(lines[start] ?? "");
-	const ordered = first?.ordered ?? false;
-	const startOrdinal = first?.start ?? 1;
-	const topIndent = first?.indent ?? 0;
-	const items = [];
-	const chain = [];
-	let nested = true;
-	for (let cursor = start; cursor < lines.length; cursor += 1) {
-		const parsed = extractListItem(lines[cursor] ?? "");
-		const previous = chain[chain.length - 1];
-		if (parsed === void 0 || previous !== void 0 && (previous.content.length > 0 || parsed.indent !== previous.marker)) {
-			nested = false;
-			break;
+function projectHTMLLeaf(leaf) {
+	if (leaf.category !== "text") return createProjection();
+	const value = leaf.value.replace(/\s+/g, " ");
+	return createProjection({
+		inlines: isEmptyString(value) ? [] : [{
+			element: "text",
+			value
+		}],
+		text: leaf.value
+	});
+}
+/**
+* Project 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.
+*
+* @remarks
+* `h1`-`h6` become headings; `p` a paragraph; `strong` / `b` and `em` / `i` emphasis;
+* `code` a code span; `pre` a code block, verbatim through a first `code` element child
+* (its `language-` class naming the language) and through `renderText` otherwise; `a`
+* and `img` a link and an image, each destination re-sanitized; `br` and `hr` a hard
+* break and a thematic break; `blockquote` and `li` their block content, with bare
+* inline runs wrapped in paragraphs; `ul` / `ol` a list, ordered from the tag and
+* numbered from `start`; `th` / `td`, `tr`, and `table` a GFM table whose column
+* alignment comes from each header-position cell's `align` attribute. Every
+* `UNSAFE_ELEMENTS` subtree contributes nothing at all, text included. Every OTHER
+* element unwraps to its children, so wrapper soup melts while its content keeps its
+* shape - `<div><p>a</p><p>b</p></div>` stays two paragraphs.
+*
+* Three mappings read their own node rather than only their children's projections,
+* because HTML puts the fact in a position rather than in a value: a `pre` takes its
+* body from its `code` child's raw text, and a list takes one item per `li` child - so
+* an empty `<li>` is still an item, while the whitespace between two of them is not.
+* A `tr` accepts only its own direct cells, and a table derives the first `th`-bearing
+* row from its own source structure.
+*
+* @param node - The document root or element to project
+* @param children - Its children's projections, in source order
+* @returns Its projection
+*
+* @example
+* ```ts
+* projectHTMLNode({ category: 'element', name: 'hr', attributes: [], children: [] }, []).blocks
+* // [{ element: 'thematicBreak' }]
+* ```
+*/
+function projectHTMLNode(node, children) {
+	if (node.category === "document") return mergeProjections(children);
+	if (UNSAFE_ELEMENTS.includes(node.name)) return createProjection();
+	const merged = mergeProjections(children);
+	const level = /^h([1-6])$/.exec(node.name);
+	if (level !== null) return createProjection({
+		blocks: [{
+			element: "heading",
+			level: parseInteger(level[1]) ?? 1,
+			children: trimInlines(normalizeInlines(projectionToInlines(merged), false))
+		}],
+		text: merged.text
+	});
+	switch (node.name) {
+		case "p":
+		case "li": return createProjection({
+			blocks: projectionToBlocks(merged),
+			text: merged.text
+		});
+		case "blockquote": return createProjection({
+			blocks: [{
+				element: "blockquote",
+				children: projectionToBlocks(merged)
+			}],
+			text: merged.text
+		});
+		case "hr": return createProjection({
+			blocks: [{ element: "thematicBreak" }],
+			text: ""
+		});
+		case "br": return createProjection({
+			inlines: [{ element: "break" }],
+			text: "\n"
+		});
+		case "strong":
+		case "b":
+		case "em":
+		case "i": {
+			const content = projectionToInlines(merged);
+			const inner = trimInlines(normalizeInlines(content, true));
+			if (!isNonEmptyArray(inner)) return createProjection({ text: merged.text });
+			const first = content[0];
+			const last = content[content.length - 1];
+			const inlines = [];
+			if (first?.element === "text" && /^\s/.test(first.value)) inlines.push({
+				element: "text",
+				value: " "
+			});
+			inlines.push({
+				element: "emphasis",
+				strong: node.name === "strong" || node.name === "b",
+				children: inner
+			});
+			if (last?.element === "text" && /\s$/.test(last.value)) inlines.push({
+				element: "text",
+				value: " "
+			});
+			return createProjection({
+				inlines,
+				text: merged.text
+			});
 		}
-		chain.push(parsed);
-	}
-	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 = [{
-				element: "paragraph",
-				children: [{
-					element: "text",
-					value: source.join("\n")
+		case "code": {
+			const body = merged.text.replace(/\r\n?/g, "\n").replace(/\s*\n\s*/g, " ");
+			const value = body.length > 2 && body.startsWith(" ") && body.endsWith(" ") && !isEmptyString(body.trim()) ? body.trim() : body;
+			return createProjection({
+				inlines: isEmptyString(value) ? [] : [{
+					element: "codeSpan",
+					value
+				}],
+				text: merged.text
+			});
+		}
+		case "pre": {
+			let position = -1;
+			for (const [index, child] of node.children.entries()) {
+				if (child?.category !== "element") continue;
+				position = index;
+				break;
+			}
+			const source = position === -1 ? void 0 : node.children[position];
+			const projected = position === -1 ? void 0 : children[position];
+			if (source?.category === "element" && source.name === "code" && projected !== void 0) {
+				let lang;
+				for (const token of (attributeOf(source, "class") ?? "").split(/\s+/)) {
+					if (!token.startsWith("language-") || token.length <= 9 || token.includes("`")) continue;
+					lang = token.slice(9);
+					break;
+				}
+				return createProjection({
+					blocks: [{
+						element: "codeBlock",
+						...lang === void 0 ? {} : { lang },
+						code: projected.text.replace(/\r\n?/g, "\n")
+					}],
+					text: merged.text
+				});
+			}
+			return createProjection({
+				blocks: [{
+					element: "codeBlock",
+					code: renderText(node).replace(/\r\n?/g, "\n")
+				}],
+				text: merged.text
+			});
+		}
+		case "a": return createProjection({
+			inlines: [{
+				element: "link",
+				href: sanitizeURL(attributeOf(node, "href") ?? "", SAFE_URL_SCHEMES),
+				children: normalizeInlines(projectionToInlines(merged), true)
+			}],
+			text: merged.text
+		});
+		case "img": {
+			const alt = (attributeOf(node, "alt") ?? "").replace(/\s+/g, " ").trim();
+			return createProjection({
+				inlines: [{
+					element: "image",
+					src: sanitizeURL(attributeOf(node, "src") ?? "", SAFE_URL_SCHEMES),
+					children: isEmptyString(alt) ? [] : [{
+						element: "text",
+						value: alt
+					}]
+				}],
+				text: ""
+			});
+		}
+		case "th":
+		case "td": {
+			const declared = (attributeOf(node, "align") ?? "").trim().toLowerCase();
+			const align = TABLE_ALIGNMENTS.includes(declared) && (declared === "left" || declared === "right" || declared === "center") ? declared : void 0;
+			return createProjection({
+				text: merged.text,
+				cells: [{
+					align,
+					inlines: trimInlines(normalizeInlines(projectionToInlines(merged), false))
 				}]
-			}];
-			let node;
-			for (let cursor = remaining - 1; cursor >= 0; cursor -= 1) {
-				const parsed = chain[cursor];
-				if (parsed === void 0) continue;
-				node = {
-					element: "list",
-					ordered: parsed.ordered,
-					start: parsed.start,
-					items: [{
+			});
+		}
+		case "tr": {
+			const cells = [];
+			for (const [index, child] of children.entries()) {
+				const source = node.children[index];
+				if (source?.category !== "element" || source.name !== "th" && source.name !== "td" || child === void 0) continue;
+				for (const cell of child.cells) if (cell !== void 0) cells.push(cell);
+			}
+			return createProjection({
+				text: merged.text,
+				rows: [cells]
+			});
+		}
+		case "ul":
+		case "ol": {
+			const items = [];
+			for (const [index, child] of children.entries()) {
+				if (child === void 0) continue;
+				const source = node.children[index];
+				const blocks = projectionToBlocks(child);
+				if (source?.category === "element" && source.name === "li") {
+					items.push({
 						element: "listItem",
-						children
-					}]
-				};
-				children = [node];
+						children: blocks
+					});
+					continue;
+				}
+				if (isNonEmptyArray(blocks)) items.push({
+					element: "listItem",
+					children: blocks
+				});
 			}
-			if (node !== void 0) return {
-				node,
-				next: lines.length
-			};
+			if (!isNonEmptyArray(items)) return createProjection({ text: merged.text });
+			const ordered = node.name === "ol";
+			const declared = parseInteger(attributeOf(node, "start"));
+			return createProjection({
+				blocks: [{
+					element: "list",
+					ordered,
+					start: ordered && declared !== void 0 && declared >= 0 && declared <= 999999999 ? declared : 1,
+					items
+				}],
+				text: merged.text
+			});
 		}
-	}
-	let index = start;
-	while (index < lines.length) {
-		const parsed = extractListItem(lines[index] ?? "");
-		if (!parsed || parsed.indent > topIndent || parsed.ordered !== ordered) break;
-		const itemLines = [parsed.content];
-		const continuation = parsed.marker;
-		index += 1;
-		while (index < lines.length) {
-			const next = lines[index] ?? "";
-			if (isBlankLine(next)) {
-				const after = lines[index + 1] ?? "";
-				if (index + 1 < lines.length && !isBlankLine(after) && leadingIndent(after) >= continuation) {
-					itemLines.push("");
-					index += 1;
+		case "table": {
+			const rows = [];
+			for (const row of merged.rows) if (row !== void 0) rows.push(row);
+			if (isNonEmptyArray(merged.cells)) rows.push(merged.cells);
+			const headings = [];
+			const rowed = [];
+			const sources = [{
+				children: node.children,
+				index: 0,
+				direct: false
+			}];
+			while (sources.length > 0) {
+				const source = sources.pop();
+				if (source === void 0) continue;
+				if (source.index >= source.children.length) continue;
+				const child = source.children[source.index];
+				source.index += 1;
+				sources.push(source);
+				if (child?.category !== "element") continue;
+				if (child.name === "th" || child.name === "td") {
+					if (!source.direct) {
+						headings.push(false);
+						rowed.push(false);
+					}
+					source.direct = true;
+					continue;
+				}
+				source.direct = false;
+				if (child.name === "tr") {
+					let heading = false;
+					for (const cell of child.children) if (cell?.category === "element" && cell.name === "th") {
+						heading = true;
+						break;
+					}
+					headings.push(heading);
+					rowed.push(true);
 					continue;
 				}
+				sources.push({
+					children: child.children,
+					index: 0,
+					direct: false
+				});
+			}
+			let position;
+			for (const [index, heading] of headings.entries()) {
+				if (!heading) continue;
+				position = index;
 				break;
 			}
-			if (leadingIndent(next) >= continuation) {
-				itemLines.push(next.slice(continuation));
-				index += 1;
-				continue;
+			if (position === void 0) for (const [index, structural] of rowed.entries()) {
+				if (!structural) continue;
+				position = index;
+				break;
 			}
-			if (extractListItem(next) || startsBlock(lines, index)) break;
-			itemLines.push(next.trim());
-			index += 1;
+			const headerRow = position === void 0 ? void 0 : rows[position];
+			const columns = headerRow?.length ?? rows[0]?.length ?? 0;
+			if (columns === 0) return createProjection({
+				blocks: projectionToBlocks(merged),
+				text: merged.text
+			});
+			const header = [];
+			const align = [];
+			for (let column = 0; column < columns; column += 1) {
+				const cell = headerRow?.[column];
+				header.push(cell?.inlines ?? []);
+				align.push(cell?.align ?? null);
+			}
+			const body = [];
+			for (const [index, row] of rows.entries()) {
+				if (row === void 0 || index === position) continue;
+				const cells = [];
+				for (let column = 0; column < header.length; column += 1) cells.push(row[column]?.inlines ?? []);
+				body.push(cells);
+			}
+			return createProjection({
+				blocks: [{
+					element: "table",
+					header,
+					rows: body,
+					align
+				}],
+				text: merged.text
+			});
 		}
-		items.push({
-			element: "listItem",
-			children: parseBlocks(itemLines, depth + 1)
-		});
 	}
-	return {
-		node: {
-			element: "list",
-			ordered,
-			start: startOrdinal,
-			items
-		},
-		next: index
-	};
-}
-/**
-* Parses a markdown string into a typed {@link MarkdownDocument} AST via the
-* block phase.
-*
-* @param markdown - The markdown source to parse.
-* @returns The parsed document.
-*/
-function parseDocument(markdown) {
-	return {
-		element: "document",
-		children: parseBlocks(splitLines(markdown), 0)
-	};
+	return merged;
 }
 /**
-* Parses inline markdown text (emphasis, code spans, links) into inline AST
-* nodes, coalescing adjacent text runs.
+* Project an `@orkestrel/html` {@link HTMLNode} into a {@link MarkdownDocument} - the
+* HTML→markdown direction, and the inverse of {@link markdownToHTML}.
 *
-* @param text - The inline markdown text to parse.
-* @returns The parsed inline nodes.
-*/
-function parseInline(text) {
-	return coalesceText(scanInline(text, 0, text.length));
-}
-//#endregion
-//#region src/core/shapers.ts
-/**
-* The shape of a {@link TextNode} - a plain-text leaf inline run.
+* @remarks
+* **Engine.** One total handler table - {@link projectHTMLNode} for the containers,
+* {@link projectHTMLLeaf} for the leaves - folded by `@orkestrel/html`'s own `foldNode`, so
+* depth capping, cycle safety, and bottom-up ordering are inherited rather than
+* rebuilt. Total: hostile, cyclic, and pathologically deep input degrades instead of
+* throwing.
+*
+* **Composed depth.** Both packages cap recursion at 64, and html's cap is reached
+* first: a document nested past it projects to a chain bounded by THAT cap, with the
+* content below it truncated before markdown ever sees it. Since the projected chain
+* can be a level or two deeper than {@link MAX_DEPTH}, the serializer's own cap can
+* then truncate again - so the anchor law below is a law within the depth budget, and
+* beyond it only totality is promised.
+*
+* **Safety.** Every `href` and `src` is re-sanitized through
+* `sanitizeURL(value, SAFE_URL_SCHEMES)` whether or not the AST was ever sanitized,
+* because a hand-built one never was. A refused destination empties to `''` and the
+* link or image is KEPT - `[text]()` - since a bad URL is no reason to lose the words
+* around it. An `UNSAFE_ELEMENTS` subtree contributes nothing at all, text included, so
+* a `script` body can never resurface as prose.
+*
+* **The anchor law.** HTML→markdown is lossy, so the fixpoint that matters is the
+* PROJECTED AST, not the input bytes:
+* `parseDocument(renderMarkdown(htmlToMarkdown(x)))` deep-equals `htmlToMarkdown(x)`.
+* The projection therefore emits canonical markdown shapes rather than literal
+* translations - whitespace collapsed, edges trimmed, a blank paragraph dropped, a hard
+* break only where a line can end - because a shape markdown cannot write back is a
+* shape this projection has no business producing.
+*
+* @param node - The HTML document or bare node to project
+* @returns The projected markdown document
 *
 * @example
 * ```ts
-* import { createContract } from '@orkestrel/contract'
-* import { textShape } from '@src/core'
+* import { parseDocument } from '@orkestrel/html'
 *
-* const text = createContract(textShape)
-* text.is({ element: 'text', value: 'hi' }) // true
+* htmlToMarkdown(parseDocument('<h1>Title</h1>'))
+* // { element: 'document', children: [{ element: 'heading', level: 1, children: [...] }] }
 * ```
 */
-var textShape = objectShape({
-	element: literalShape(["text"]),
-	value: stringShape()
-});
+function htmlToMarkdown(node) {
+	return {
+		element: "document",
+		children: projectionToBlocks(foldNode$1(node, {
+			document: projectHTMLNode,
+			element: projectHTMLNode,
+			text: projectHTMLLeaf,
+			comment: projectHTMLLeaf,
+			doctype: projectHTMLLeaf
+		}))
+	};
+}
 /**
-* The shape of a {@link CodeSpanNode} - an inline code span (`` `code` ``).
+* Depth-first, pre-order, root-inclusive traversal of a {@link MarkdownNode} - 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.
 *
-* @example
-* ```ts
-* import { createContract } from '@orkestrel/contract'
-* import { codeSpanShape } from '@src/core'
+* @remarks
+* Total: never throws. Descent stops at {@link MAX_DEPTH} (the node at the cap is
+* still yielded; its children are not) so pathologically deep input cannot exhaust
+* the call stack.
 *
-* const codeSpan = createContract(codeSpanShape)
-* codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
-* ```
-*/
-var codeSpanShape = objectShape({
-	element: literalShape(["codeSpan"]),
-	value: stringShape()
-});
-/**
-* The shape of a {@link CodeBlockNode} - a fenced code block. `lang` is
-* optional (absent when the opening fence carries no info-string).
+* @param node - The AST node to walk (a full document, or any sub-node)
+* @returns A generator yielding every visited node, pre-order
 *
 * @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
+* const doc = { element: 'document', children: [{ element: 'thematicBreak' }] } as const
+* [...walkNodes(doc)].map((node) => node.element) // ['document', 'thematicBreak']
 * ```
 */
-var codeBlockShape = objectShape({
-	element: literalShape(["codeBlock"]),
-	lang: optionalShape(stringShape()),
-	code: stringShape()
-});
+function* walkNodes(node) {
+	const stack = [{
+		node,
+		depth: 0
+	}];
+	while (stack.length > 0) {
+		const frame = stack.pop();
+		if (frame === void 0) continue;
+		yield frame.node;
+		if (frame.depth >= 64) continue;
+		const children = [];
+		switch (frame.node.element) {
+			case "document":
+			case "heading":
+			case "paragraph":
+			case "blockquote":
+			case "listItem":
+			case "emphasis":
+			case "link":
+			case "image":
+				for (const child of frame.node.children) if (child !== void 0) children.push(child);
+				break;
+			case "list":
+				for (const child of frame.node.items) if (child !== void 0) children.push(child);
+				break;
+			case "table":
+				for (const cell of frame.node.header) if (cell !== void 0) {
+					for (const child of cell) if (child !== void 0) children.push(child);
+				}
+				for (const row of frame.node.rows) if (row !== void 0) {
+					for (const cell of row) if (cell !== void 0) {
+						for (const child of cell) if (child !== void 0) children.push(child);
+					}
+				}
+		}
+		for (let index = children.length - 1; index >= 0; index -= 1) {
+			const child = children[index];
+			if (child !== void 0) stack.push({
+				node: child,
+				depth: frame.depth + 1
+			});
+		}
+	}
+}
 /**
-* The shape of a {@link ThematicBreakNode} - a horizontal rule. Carries no
-* fields beyond its `element` discriminant.
+* Fold a {@link MarkdownNode} into a `T` via a total catamorphism - children are
+* folded first (post-order), then the node's own {@link MarkdownHandler} is invoked
+* with the already-folded children.
 *
-* @example
-* ```ts
-* import { createContract } from '@orkestrel/contract'
-* import { thematicBreakShape } from '@src/core'
+* @remarks
+* **Table contract.** A {@link TableNode} has no single `children` array - its cells
+* live in `header` (one inline-node list per column) and `rows` (a list of such
+* rows). The `table` handler receives ONE folded `T` per inline node, flattened in
+* walk order across ALL cells - every header cell's inline nodes (column order), then
+* every body row's cells' inline nodes (row order, then column order) - and reads
+* `node.header[c].length` / `node.rows[r][c].length` off the table node itself to
+* recover cell boundaries within the flat list.
 *
-* const thematicBreak = createContract(thematicBreakShape)
-* thematicBreak.is({ element: 'thematicBreak' }) // true
-* ```
-*/
-var thematicBreakShape = objectShape({ element: literalShape(["thematicBreak"]) });
-/**
-* The shape of a {@link TableAlign} - the per-column GFM table alignment
-* literal.
+* Total: never throws. At `depth >= {@link MAX_DEPTH}` the node's handler is invoked
+* 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 depth - The starting recursion depth (pass `0` at the entry point)
+* @returns The folded `T`
 *
 * @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
+* const countHandlers: MarkdownHandlers<number> = {
+*   document: (_, children) => children.reduce((a, b) => a + b, 1),
+*   // ...one handler per element, each summing its folded children
+* }
+* foldNode(document, countHandlers, 0) // total node count
 * ```
 */
-var tableAlignShape = literalShape([
-	"none",
-	"left",
-	"right",
-	"center"
-]);
+function foldNode(node, handlers, depth) {
+	const stack = [{
+		node,
+		depth,
+		expanded: false,
+		count: 0
+	}];
+	const values = [];
+	while (stack.length > 0) {
+		const frame = stack.pop();
+		if (frame === void 0) continue;
+		if (!frame.expanded) {
+			const children = [];
+			if (frame.depth < 64) switch (frame.node.element) {
+				case "document":
+				case "heading":
+				case "paragraph":
+				case "blockquote":
+				case "listItem":
+				case "emphasis":
+				case "link":
+				case "image":
+					for (const child of frame.node.children) if (child !== void 0) children.push(child);
+					break;
+				case "list":
+					for (const child of frame.node.items) if (child !== void 0) children.push(child);
+					break;
+				case "table":
+					for (const cell of frame.node.header) if (cell !== void 0) {
+						for (const child of cell) if (child !== void 0) children.push(child);
+					}
+					for (const row of frame.node.rows) if (row !== void 0) {
+						for (const cell of row) if (cell !== void 0) {
+							for (const child of cell) if (child !== void 0) children.push(child);
+						}
+					}
+			}
+			stack.push({
+				...frame,
+				expanded: true,
+				count: children.length
+			});
+			for (let index = children.length - 1; index >= 0; index -= 1) {
+				const child = children[index];
+				if (child !== void 0) stack.push({
+					node: child,
+					depth: frame.depth + 1,
+					expanded: false,
+					count: 0
+				});
+			}
+			continue;
+		}
+		const children = frame.count === 0 ? [] : values.splice(values.length - frame.count, frame.count);
+		let value;
+		switch (frame.node.element) {
+			case "document":
+				value = handlers.document(frame.node, children);
+				break;
+			case "heading":
+				value = handlers.heading(frame.node, children);
+				break;
+			case "paragraph":
+				value = handlers.paragraph(frame.node, children);
+				break;
+			case "thematicBreak":
+				value = handlers.thematicBreak(frame.node, children);
+				break;
+			case "blockquote":
+				value = handlers.blockquote(frame.node, children);
+				break;
+			case "codeBlock":
+				value = handlers.codeBlock(frame.node, children);
+				break;
+			case "list":
+				value = handlers.list(frame.node, children);
+				break;
+			case "listItem":
+				value = handlers.listItem(frame.node, children);
+				break;
+			case "table":
+				value = handlers.table(frame.node, children);
+				break;
+			case "text":
+				value = handlers.text(frame.node, children);
+				break;
+			case "emphasis":
+				value = handlers.emphasis(frame.node, children);
+				break;
+			case "codeSpan":
+				value = handlers.codeSpan(frame.node, children);
+				break;
+			case "break":
+				value = handlers.break(frame.node, children);
+				break;
+			case "link":
+				value = handlers.link(frame.node, children);
+				break;
+			case "image": value = handlers.image(frame.node, children);
+		}
+		if (stack.length === 0) return value;
+		values.push(value);
+	}
+	switch (node.element) {
+		case "document": return handlers.document(node, []);
+		case "heading": return handlers.heading(node, []);
+		case "paragraph": return handlers.paragraph(node, []);
+		case "thematicBreak": return handlers.thematicBreak(node, []);
+		case "blockquote": return handlers.blockquote(node, []);
+		case "codeBlock": return handlers.codeBlock(node, []);
+		case "list": return handlers.list(node, []);
+		case "listItem": return handlers.listItem(node, []);
+		case "table": return handlers.table(node, []);
+		case "text": return handlers.text(node, []);
+		case "emphasis": return handlers.emphasis(node, []);
+		case "codeSpan": return handlers.codeSpan(node, []);
+		case "break": return handlers.break(node, []);
+		case "link": return handlers.link(node, []);
+		case "image": return handlers.image(node, []);
+	}
+}
 /**
-* The shape of {@link ListItemParts} - 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.
+* Rewrite 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.
 *
-* @example
-* ```ts
-* import { createContract } from '@orkestrel/contract'
-* import { listItemPartsShape } from '@src/core'
+* @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
+* 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.
 *
-* const listItemParts = createContract(listItemPartsShape)
-* listItemParts.is({ ordered: false, start: 1, content: 'hi', indent: 0, marker: 2 }) // true
-* ```
-*/
-var listItemPartsShape = objectShape({
-	ordered: booleanShape(),
-	start: integerShape(),
-	content: stringShape(),
-	indent: integerShape(),
-	marker: integerShape()
-});
-//#endregion
-//#region src/core/Markdown.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.
+* 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
+* UNCHANGED (by reference, not rebuilt, and `rewrite` is not invoked on it) instead of
+* recursing further, so a pathologically deep adopted document cannot exhaust the
+* call stack. {@link MarkdownInterface.map} inherits this cap since it delegates here.
 *
-* @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 document - The document AST to rewrite
+* @param rewrite - The bottom-up {@link MarkdownRewriteHandler}
+* @returns A new, rewritten {@link MarkdownDocument}
 *
 * @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) =>
+* rewriteDocument(document, (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;
-	constructor(input) {
-		this.#document = typeof input === "string" ? parseDocument(input) : input;
-	}
-	/** The stored {@link MarkdownDocument} AST root. */
-	get document() {
-		return this.#document;
-	}
-	/**
-	* 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}. */
-	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;
+function rewriteDocument(document, rewrite) {
+	const stack = [{
+		node: document,
+		depth: -1,
+		expanded: false,
+		count: 0
+	}];
+	const values = [];
+	while (stack.length > 0) {
+		const frame = stack.pop();
+		if (frame === void 0) continue;
+		const current = frame.node;
+		if (!frame.expanded) {
+			if (current.element !== "document" && frame.depth >= 64) {
+				values.push(current);
+				continue;
+			}
+			const children = [];
+			switch (current.element) {
+				case "document":
+				case "heading":
+				case "paragraph":
+				case "blockquote":
+				case "listItem":
+				case "emphasis":
+				case "link":
+				case "image":
+					for (const child of current.children) if (child !== void 0) children.push(child);
+					break;
+				case "list":
+					for (const child of current.items) if (child !== void 0) children.push(child);
+					break;
+				case "table":
+					for (const cell of current.header) if (cell !== void 0) {
+						for (const child of cell) if (child !== void 0) children.push(child);
+					}
+					for (const row of current.rows) if (row !== void 0) {
+						for (const cell of row) if (cell !== void 0) {
+							for (const child of cell) if (child !== void 0) children.push(child);
+						}
+					}
+			}
+			stack.push({
+				...frame,
+				expanded: true,
+				count: children.length
+			});
+			const depth = current.element === "document" ? 0 : frame.depth + 1;
+			for (let index = children.length - 1; index >= 0; index -= 1) {
+				const child = children[index];
+				if (child !== void 0) stack.push({
+					node: child,
+					depth,
+					expanded: false,
+					count: 0
+				});
+			}
+			continue;
+		}
+		const children = frame.count === 0 ? [] : values.splice(values.length - frame.count, frame.count);
+		let rebuilt = current;
+		switch (current.element) {
+			case "document": {
+				const blocks = [];
+				let offset = 0;
+				for (const block of current.children) {
+					if (block === void 0) continue;
+					const child = children[offset];
+					blocks.push(child !== void 0 && isBlockNode(child) ? child : block);
+					offset += 1;
+				}
+				const result = {
+					element: "document",
+					children: blocks
+				};
+				if (stack.length === 0) return result;
+				values.push(result);
+				continue;
+			}
+			case "heading":
+			case "paragraph": {
+				const inlines = [];
+				let offset = 0;
+				for (const inline of current.children) {
+					if (inline === void 0) continue;
+					const child = children[offset];
+					inlines.push(child !== void 0 && isInlineNode(child) ? child : inline);
+					offset += 1;
+				}
+				rebuilt = {
+					...current,
+					children: inlines
+				};
+				break;
+			}
+			case "blockquote": {
+				const blocks = [];
+				let offset = 0;
+				for (const block of current.children) {
+					if (block === void 0) continue;
+					const child = children[offset];
+					blocks.push(child !== void 0 && isBlockNode(child) ? child : block);
+					offset += 1;
+				}
+				rebuilt = {
+					...current,
+					children: blocks
+				};
+				break;
+			}
+			case "listItem": {
+				const blocks = [];
+				let offset = 0;
+				for (const block of current.children) {
+					if (block === void 0) continue;
+					const child = children[offset];
+					blocks.push(child !== void 0 && isBlockNode(child) ? child : block);
+					offset += 1;
 				}
-				controller.enqueue(block);
-				index += 1;
-			} else controller.close();
-		} });
+				rebuilt = {
+					element: "listItem",
+					children: blocks
+				};
+				break;
+			}
+			case "emphasis":
+			case "link":
+			case "image": {
+				const inlines = [];
+				let offset = 0;
+				for (const inline of current.children) {
+					if (inline === void 0) continue;
+					const child = children[offset];
+					inlines.push(child !== void 0 && isInlineNode(child) ? child : inline);
+					offset += 1;
+				}
+				rebuilt = {
+					...current,
+					children: inlines
+				};
+				break;
+			}
+			case "list": {
+				const items = [];
+				let offset = 0;
+				for (const item of current.items) {
+					if (item === void 0) continue;
+					const child = children[offset];
+					items.push(child?.element === "listItem" ? child : item);
+					offset += 1;
+				}
+				rebuilt = {
+					...current,
+					items
+				};
+				break;
+			}
+			case "table": {
+				let offset = 0;
+				const header = [];
+				for (const cell of current.header) {
+					if (cell === void 0) continue;
+					const inlines = [];
+					for (const inline of cell) {
+						if (inline === void 0) continue;
+						const child = children[offset];
+						inlines.push(child !== void 0 && isInlineNode(child) ? child : inline);
+						offset += 1;
+					}
+					header.push(inlines);
+				}
+				const rows = [];
+				for (const row of current.rows) {
+					if (row === void 0) continue;
+					const cells = [];
+					for (const cell of row) {
+						if (cell === void 0) continue;
+						const inlines = [];
+						for (const inline of cell) {
+							if (inline === void 0) continue;
+							const child = children[offset];
+							inlines.push(child !== void 0 && isInlineNode(child) ? child : inline);
+							offset += 1;
+						}
+						cells.push(inlines);
+					}
+					rows.push(cells);
+				}
+				rebuilt = {
+					...current,
+					header,
+					rows
+				};
+				break;
+			}
+		}
+		const result = rewrite(rebuilt);
+		let accepted = rebuilt;
+		switch (current.element) {
+			case "text":
+			case "emphasis":
+			case "codeSpan":
+			case "break":
+			case "link":
+			case "image":
+				if (isInlineNode(result)) accepted = result;
+				break;
+			case "heading":
+			case "paragraph":
+			case "list":
+			case "table":
+			case "codeBlock":
+			case "blockquote":
+			case "thematicBreak":
+				if (isBlockNode(result)) accepted = result;
+				break;
+			case "listItem": if (result.element === "listItem") accepted = result;
+		}
+		values.push(accepted);
 	}
-};
-//#endregion
-//#region src/core/factories.ts
-/**
-* 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) 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);
-}
-/**
-* 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).
-*
-* @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 createContract(textShape);
-}
-/**
-* 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).
-*
-* @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 createContract(codeSpanShape);
+	return {
+		element: "document",
+		children: [...document.children]
+	};
 }
 /**
-* 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'
+* Concatenate 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).
 *
-* const codeBlock = createCodeBlockContract()
-* codeBlock.is({ element: 'codeBlock', code: 'x' }) // true
-* ```
-*/
-function createCodeBlockContract() {
-	return 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).
+* @remarks
+* Total: never throws. Descent stops at {@link MAX_DEPTH} (contributes `''` past the
+* cap instead of recursing further).
 *
-* @returns A `ThematicBreakNode` contract bundling `schema` / `is` / `parse` / `generate`
+* @param node - The AST node to flatten (a full document, or any sub-node)
+* @returns The concatenated text content
 *
 * @example
 * ```ts
-* import { createThematicBreakContract } from '@src/core'
-*
-* const thematicBreak = createThematicBreakContract()
-* thematicBreak.is({ element: 'thematicBreak' }) // true
+* flattenText({ element: 'paragraph', children: [
+*   { element: 'text', value: 'a ' },
+*   { element: 'codeSpan', value: 'b' },
+* ] })
+* // 'a b'
 * ```
 */
-function createThematicBreakContract() {
-	return createContract(thematicBreakShape);
+function flattenText(node) {
+	const stack = [{
+		node,
+		depth: 0
+	}];
+	let value = "";
+	while (stack.length > 0) {
+		const frame = stack.pop();
+		if (frame === void 0 || frame.depth >= 64) continue;
+		const children = [];
+		switch (frame.node.element) {
+			case "text":
+			case "codeSpan":
+				value += frame.node.value;
+				break;
+			case "codeBlock":
+				value += frame.node.code;
+				break;
+			case "document":
+			case "heading":
+			case "paragraph":
+			case "blockquote":
+			case "listItem":
+			case "emphasis":
+			case "link":
+			case "image":
+				for (const child of frame.node.children) if (child !== void 0) children.push(child);
+				break;
+			case "list":
+				for (const child of frame.node.items) if (child !== void 0) children.push(child);
+				break;
+			case "table":
+				for (const cell of frame.node.header) if (cell !== void 0) {
+					for (const child of cell) if (child !== void 0) children.push(child);
+				}
+				for (const row of frame.node.rows) if (row !== void 0) {
+					for (const cell of row) if (cell !== void 0) {
+						for (const child of cell) if (child !== void 0) children.push(child);
+					}
+				}
+		}
+		for (let index = children.length - 1; index >= 0; index -= 1) {
+			const child = children[index];
+			if (child !== void 0) stack.push({
+				node: child,
+				depth: frame.depth + 1
+			});
+		}
+	}
+	return value;
 }
 //#endregion
-export { MAX_DEPTH, Markdown, SAFE_URL_SCHEMES, coalesceText, codeBlockShape, codeSpanShape, collectList, collectTable, createCodeBlockContract, createCodeSpanContract, createMarkdown, createTextContract, createThematicBreakContract, escapeHtml, extractFence, extractHeading, extractListItem, flattenText, foldNode, isBlankLine, isBlockNode, isBlockquoteNode, isCodeBlockNode, isCodeSpanNode, isEmphasisNode, isEscapable, isFenceClose, isFenceWhitespace, isHeadingNode, isInlineNode, isLinkNode, isListNode, isMarkdownDocument, isMarkdownNode, isParagraphNode, isQuote, isTableNode, isTableStart, isTextNode, isThematicBreak, isThematicBreakNode, isWhitespace, leadingIndent, listItemPartsShape, parseBlocks, parseDocument, parseInline, renderHTML, renderMarkdown, rewriteDocument, sanitizeUrl, scanCode, scanEmphasis, scanInline, scanLink, splitLines, splitTableRow, startsBlock, stripQuote, tableAlignShape, tableAlignments, textShape, thematicBreakShape, unescapeText, walkNodes };
+export { EMPTY_PROJECTION, MAX_DEPTH, Markdown, coalesceText, codeBlockShape, codeSpanShape, collectList, collectTable, countIndent, createCodeBlockContract, createCodeSpanContract, createLineBreakContract, createMarkdown, createProjection, createTextContract, createThematicBreakContract, delimiterToAlignments, extractFence, extractHeading, extractListItem, flattenText, foldNode, htmlToMarkdown, isBlankLine, isBlockNode, isBlockquoteNode, isCodeBlockNode, isCodeSpanNode, isEmphasisNode, isEscapable, isFenceClose, isFenceWhitespace, isHeadingNode, isImageNode, isInlineNode, isLineBreakNode, isLinkNode, isListNode, isMarkdownDocument, isMarkdownNode, isParagraphNode, isQuote, isTableNode, isTableStart, isTextNode, isThematicBreak, isThematicBreakNode, isWhitespace, lineBreakShape, listItemMatchShape, markdownToHTML, mergeProjections, normalizeInlines, parseBlocks, parseDocument, parseInline, projectHTMLLeaf, projectHTMLNode, projectionToBlocks, projectionToInlines, renderHTML, renderMarkdown, rewriteDocument, scanCode, scanEmphasis, scanInline, scanLink, splitLines, splitTableRow, startsBlock, stripQuote, tableAlignShape, textShape, thematicBreakShape, trimInlines, unescapeText, walkNodes };
 
 //# sourceMappingURL=index.js.map