@orkestrel/markdown 0.0.13 → 0.0.14

package/dist/src/core/index.js

@@ -5,7 +5,7 @@ import { HTML, SAFE_ATTRIBUTES, SAFE_URL_SCHEMES, TABLE_ALIGNMENTS, UNSAFE_ELEME
 * Caps the recursion depth the parse pipeline (`parseDocument` and its
 * `parsers.ts` helpers), the `helpers.ts` traversal / projection functions
 * (`markdownToHTML`, `renderMarkdown`, `walkNodes`, `foldNode`, `rewriteDocument`),
-* and the `compilers.ts` renderer (`renderHTML`) honor before degrading. It bounds blockquote nesting, inline
+* and the `compilers.ts` renderer (`renderHTML`) honor before degrading, at 64. 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`.
@@ -160,7 +160,7 @@ function isEmphasisNode(node) {
 * Determines whether a node is an inline code span.
 *
 * @remarks
-* Narrows to {@link CodeSpanNode} - the node whose `element` discriminant is
+* Narrows to {@link CodeSpanNode} — the node whose `element` discriminant is
 * `'codeSpan'`.
 *
 * @param node - The AST node to test
@@ -217,11 +217,11 @@ function isImageNode(node) {
 	return node.element === "image";
 }
 /**
-* Determines whether an arbitrary value is a valid {@link InlineNode} - a text
+* Determines whether an arbitrary value is a valid {@link InlineNode} — a text
 * run, emphasis, code span, hard break, link, or image, recursively validated.
 *
 * @remarks
-* Total: never throws, even on cyclic or pathologically deep input - every
+* Total: never throws, even on cyclic or pathologically deep input — every
 * combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
 * throw-contained per the `@orkestrel/contract` guard contract.
 *
@@ -256,16 +256,16 @@ var isInlineNode = unionOf(recordOf({
 	children: arrayOf(lazyOf(() => isInlineNode))
 }));
 /**
-* Determines whether an arbitrary value is a valid {@link BlockNode} - a
+* Determines whether an arbitrary value is a valid {@link BlockNode} — a
 * heading, paragraph, list, table, code block, blockquote, or thematic break,
 * recursively validated.
 *
 * @remarks
-* Total: never throws, even on cyclic or pathologically deep input - every
+* Total: never throws, even on cyclic or pathologically deep input — every
 * combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
 * throw-contained per the `@orkestrel/contract` guard contract.
 * A list item's shape is inlined here (and in {@link isMarkdownNode}) rather
-* than named separately - it is used at exactly these two sites.
+* than named separately — it is used at exactly these two sites.
 *
 * @param value - The value to test
 * @returns True if `value` is a well-formed {@link BlockNode}; false otherwise
@@ -307,16 +307,16 @@ var isBlockNode = unionOf(recordOf({
 	children: arrayOf(lazyOf(() => isBlockNode))
 }), recordOf({ element: literalOf("thematicBreak") }));
 /**
-* Determines whether an arbitrary value is a valid {@link MarkdownNode} - the
+* Determines whether an arbitrary value is a valid {@link MarkdownNode} — the
 * {@link MarkdownDocument} root, a {@link BlockNode}, a {@link ListItemNode}, or
 * an {@link InlineNode}, recursively validated.
 *
 * @remarks
-* Total: never throws, even on cyclic or pathologically deep input - every
+* Total: never throws, even on cyclic or pathologically deep input — every
 * combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
 * throw-contained per the `@orkestrel/contract` guard contract.
 * A list item's shape is inlined here (and in {@link isBlockNode}) rather than
-* named separately - it is used at exactly these two sites.
+* named separately — it is used at exactly these two sites.
 *
 * @param value - The value to test
 * @returns True if `value` is a well-formed {@link MarkdownNode}; false otherwise
@@ -334,12 +334,12 @@ var isMarkdownNode = unionOf(lazyOf(() => isMarkdownDocument), lazyOf(() => isBl
 	children: arrayOf(lazyOf(() => isBlockNode))
 }), lazyOf(() => isInlineNode));
 /**
-* Determines whether an arbitrary value is a valid {@link MarkdownDocument} -
+* Determines whether an arbitrary value is a valid {@link MarkdownDocument} —
 * the parsed-AST root {@link parseDocument} returns, recursively
 * validated.
 *
 * @remarks
-* Total: never throws, even on cyclic or pathologically deep input - every
+* Total: never throws, even on cyclic or pathologically deep input — every
 * combinator involved (`recordOf`, `arrayOf`) is throw-contained per the
 * `@orkestrel/contract` guard contract.
 *
@@ -511,7 +511,8 @@ function parseBlocks(lines, depth, spans = /* @__PURE__ */ new Map(), end) {
 }
 /**
 * Parses a markdown string into a typed {@link MarkdownDocument} AST through the
-* block phase.
+* block phase — the document half of what {@link parseProvenance} returns. Malformed
+* markdown degrades to literal text, so the parse never throws.
 *
 * @param markdown - The markdown source to parse.
 * @returns The parsed document.
@@ -526,7 +527,8 @@ function parseDocument(markdown) {
 	return document;
 }
 /**
-* Parses a markdown string into a document and its original-source spans.
+* Parses a markdown string into a document and its original-source spans. Malformed
+* markdown degrades to literal text, so the parse never throws.
 *
 * @param markdown - The markdown source to parse.
 * @returns The parsed document and its node-identity span map.
@@ -551,7 +553,8 @@ function parseProvenance(markdown) {
 }
 /**
 * Parses inline markdown text (emphasis, code spans, links, images, and hard
-* breaks) into inline AST nodes, coalescing adjacent text runs.
+* breaks) into inline AST nodes, coalescing adjacent text runs and reading no block
+* structure. Malformed markdown degrades to literal text, so the parse never throws.
 *
 * @param text - The inline markdown text to parse.
 * @returns The parsed inline nodes.
@@ -781,7 +784,7 @@ function normalizeParagraphLine(source, breaks) {
 	}], "");
 }
 /**
-* Counts the leading space / tab characters on `line` (a tab counts as one) - the
+* Counts the leading space / tab characters on `line` (a tab counts as one) — the
 * indent that decides whether a list item's continuation belongs to the item.
 *
 * @param line - The line to measure
@@ -799,7 +802,7 @@ function countIndent(line) {
 	return count;
 }
 /**
-* Checks whether `character` is whitespace under the emphasis flanking rule - a space, a
+* Checks whether `character` is whitespace under the emphasis flanking rule — a space, a
 * tab, or a newline.
 *
 * @param character - The character to test
@@ -815,7 +818,7 @@ function isFlankingWhitespace(character) {
 	return character === " " || character === "	" || character === "\n";
 }
 /**
-* Checks whether `character` is escapable by a leading backslash - the ASCII punctuation
+* Checks whether `character` is escapable by a leading backslash — the ASCII punctuation
 * markdown gives meaning to (so `\*` becomes `*` but `\.` stays `\.`).
 *
 * @param character - The single character after a backslash
@@ -831,7 +834,7 @@ function isEscapable(character) {
 	return /[\\`*_{}[\]()#+\-.!>~|]/.test(character);
 }
 /**
-* Checks whether `line` is blank - empty, or containing only whitespace - the markdown
+* Checks whether `line` is blank — empty, or containing only whitespace — the markdown
 * definition of a blank line that block parsing uses to separate paragraphs, skip
 * gaps, and end list continuations.
 *
@@ -847,7 +850,7 @@ function isBlankLine(line) {
 	return isEmptyString(line.trim());
 }
 /**
-* Checks whether `line` is a blockquote line (`>` optionally indented up to three spaces) -
+* Checks whether `line` is a blockquote line (`>` optionally indented up to three spaces) —
 * its content is de-quoted by {@link stripQuote}.
 *
 * @param line - The candidate line
@@ -862,7 +865,7 @@ function isQuote(line) {
 	return /^\s{0,3}>/.test(line);
 }
 /**
-* Checks whether `line` closes a fence opened by `marker` - the same fence character, a run
+* Checks whether `line` closes a fence opened by `marker` — the same fence character, a run
 * at least as long, and nothing else but surrounding whitespace.
 *
 * @param line - The candidate closing line
@@ -888,7 +891,7 @@ function isFenceClose(line, marker) {
 	return index === line.length;
 }
 /**
-* Checks whether `character` is a regex-`\s`-equivalent whitespace character - the
+* Checks whether `character` is a regex-`\s`-equivalent whitespace character — the
 * character class {@link isFenceClose}'s scan treats as surrounding padding.
 *
 * @param character - The single character to test, or `undefined` past the end of a line
@@ -904,7 +907,7 @@ function isFenceWhitespace(character) {
 	return character === " " || character === "	" || character === "\n" || character === "\r" || character === "\f" || character === "\v";
 }
 /**
-* Checks whether `line` is a thematic break (horizontal rule) - three or more of the SAME
+* Checks whether `line` is a thematic break (horizontal rule) — three or more of the same
 * marker `-`, `*`, or `_` (optionally space-separated) and nothing else (`---`,
 * `***`, `___`, `- - -`).
 *
@@ -924,9 +927,9 @@ function isThematicBreak(line) {
 	return [...stripped].every((character) => character === marker);
 }
 /**
-* Checks whether the pair (`header`, `delimiter`) opens a GFM table - `delimiter` is a row of
+* Checks whether the pair (`header`, `delimiter`) opens a GFM table — `delimiter` is a row of
 * `|`-separated cells each matching `:?-+:?`, the GFM rule that a table requires a
-* header row IMMEDIATELY followed by a delimiter row.
+* header row immediately followed by a delimiter row.
 *
 * @param header - The candidate header line
 * @param delimiter - The line after it (the candidate delimiter)
@@ -1056,10 +1059,11 @@ function stripQuote(source) {
 	return sliceSource(source, (/^\s{0,3}>\s?/.exec(source.text)?.[0] ?? "").length, source.text.length);
 }
 /**
-* Splits one GFM table row into its cell strings - outer pipes are optional, an escaped
-* pipe (`\|`) inside a cell is NOT a separator (it becomes a literal `|`), and the
-* empty leading / trailing cell produced by an outer `|` is dropped. Derives the string
-* form from {@link splitTableSources}, which owns the escaped-pipe splitting rule.
+* Splits one GFM table row into its cell strings — outer pipes are optional, a pipe
+* escaped by a leading backslash inside a cell is not a separator (it becomes a literal
+* pipe character), and the empty leading / trailing cell an outer pipe produces is
+* dropped. Derives the string form from {@link splitTableSources}, which owns the
+* escaped-pipe splitting rule.
 *
 * @param row - The raw table row line
 * @returns The row's cells, in column order
@@ -1122,7 +1126,7 @@ function splitTableSources(row) {
 	return cells;
 }
 /**
-* Derives the per-column {@link TableAlign} list from a GFM delimiter row - `:---`
+* Derives the per-column {@link TableAlign} list from a GFM delimiter row — `:---`
 * left, `---:` right, `:---:` center, and `---` as the explicit no-alignment
 * marker represented by `null`.
 *
@@ -1146,8 +1150,8 @@ function delimiterToAlignments(delimiter) {
 	});
 }
 /**
-* Checks whether the line at `index` starts a NEW block kind (heading / fence / thematic
-* break / blockquote / list / table) - the paragraph collector stops at such a line
+* Checks whether the line at `index` starts a new block kind (heading / fence / thematic
+* break / blockquote / list / table) — the paragraph collector stops at such a line
 * so a block following a paragraph without a blank line still parses (a trusted-input
 * caller writing a `##` heading directly under a paragraph, with no intervening blank
 * line).
@@ -1166,7 +1170,7 @@ function startsBlock(lines, index) {
 	return extractHeading(line) !== void 0 || extractFence(line) !== void 0 || isThematicBreak(line) || isQuote(line) || extractListItem(line) !== void 0 || isTableStart(line, lines[index + 1]);
 }
 /**
-* Resolves backslash escapes in a raw string to their literal characters - used for a
+* Resolves backslash escapes in a raw string to their literal characters — used for a
 * link `href` (which is not otherwise inline-parsed) and any plain text run.
 *
 * @param text - The raw text possibly carrying `\x` escapes
@@ -1189,7 +1193,7 @@ function unescapeText(text) {
 	return out;
 }
 /**
-* Merges adjacent text nodes into one - the inline scanner emits a text node per
+* Merges adjacent text nodes into one — the inline scanner emits a text node per
 * unrecognized character, so coalescing keeps the AST clean and assertion-friendly.
 *
 * @param nodes - The inline nodes (possibly with adjacent text runs)
@@ -1228,7 +1232,7 @@ function coalesceText(nodes, spans) {
 }
 /**
 * Scans an inline code span at `start` (a `` ` ``-run … a matching `` ` ``-run of the
-* SAME length, the CommonMark rule that lets a span contain backticks). Returns the
+* 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).
 *
@@ -1262,7 +1266,7 @@ function scanCode(source, start, to) {
 	}
 }
 /**
-* Locates a link `[text](href)` at `start` - the text runs to a BALANCED `]`, then `(`
+* Locates a link `[text](href)` at `start` — the text runs to a balanced `]`, then `(`
 * must immediately follow and the destination runs to the matching `)` (both respect
 * nested delimiters + escapes). Returns the label close and syntax end, or `undefined` when the shape
 * does not hold (it then degrades to a literal `[`).
@@ -1320,7 +1324,7 @@ function locateLink(source, start, to) {
 	};
 }
 /**
-* Scans a link `[text](href)` at `start` - the text runs to a BALANCED `]`, then `(`
+* Scans a link `[text](href)` at `start` — the text runs to a balanced `]`, then `(`
 * must immediately follow and the destination runs to the matching `)` (both respect
 * nested delimiters + escapes) through {@link locateLink}, and returns the parsed node
 * and end index. Returns `undefined` when the shape does not hold (it then degrades to
@@ -1353,7 +1357,7 @@ function scanLink(source, start, to, depth = 0) {
 	};
 }
 /**
-* Locates an emphasis run at `start` (`*` / `_`, doubled for strong) - finds the nearest
+* Locates an emphasis run at `start` (`*` / `_`, doubled for strong) — finds the nearest
 * matching closing run of the same marker + width while skipping complete nested
 * runs from the other marker family, and requires non-space immediately inside both
 * delimiters (the CommonMark flanking simplification that blocks `* x *`). Returns
@@ -1412,7 +1416,7 @@ function locateEmphasis(source, start, to) {
 	}
 }
 /**
-* Scans an emphasis run at `start` (`*` / `_`, doubled for strong) - finds the nearest
+* Scans an emphasis run at `start` (`*` / `_`, doubled for strong) — finds the nearest
 * matching closing run of the same marker + width while skipping complete nested runs
 * from the other marker family, and requires non-space immediately inside both
 * delimiters (the CommonMark flanking simplification that blocks `* x *`) through
@@ -1446,7 +1450,7 @@ function scanEmphasis(source, start, to, depth = 0) {
 	};
 }
 /**
-* Scans the window `[from, to)` of `source` into inline nodes - the single recursive
+* Scans the window `[from, to)` of `source` into inline nodes — the single recursive
 * engine the inline phase runs on (emphasis, link text, and image alternative
 * content recurse through it). Linear:
 * each character is consumed once; a failed construct emits its opening character as
@@ -1458,10 +1462,10 @@ function scanEmphasis(source, start, to, depth = 0) {
 * @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
 *   incremented by one on every recursive descent {@link scanInlineSource} makes into
 *   itself for a link's text, an image's alternative content, or an emphasis run's
-*   children. At {@link MAX_DEPTH} the window is never scanned for markup - it emits as
-*   a single literal text node - so pathological nesting (`[[[[…`, `****…`) cannot
+*   children. At {@link MAX_DEPTH} the window is never scanned for markup — it emits as
+*   a single literal text node — so pathological nesting (`[[[[…`, `****…`) cannot
 *   exhaust the call stack.
-* @returns The parsed inline nodes (NOT yet coalesced)
+* @returns The parsed inline nodes (not yet coalesced)
 *
 * @example
 * ```ts
@@ -2159,15 +2163,15 @@ function markdownToHTML(node) {
 	};
 }
 /**
-* Renders a {@link MarkdownNode} to its CANONICAL markdown source - the inverse
-* projection of `renderHTML`, and the serializer a `parse(renderMarkdown(doc))`
+* Renders a {@link MarkdownNode} to its canonical markdown source — the inverse
+* projection of `renderHTML`. It is 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
+* `> `-prefixed blockquote lines, GFM tables (1-space-padded cells, a backslash
+* before each literal pipe, 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, so parsing the rendered source
 * returns the node it was rendered from.
 *
@@ -2484,8 +2488,8 @@ function createProjection(parts = {}) {
 	};
 }
 /**
-* Trims the whitespace at the two ends of an inline run - the leading whitespace of a
-* leading text node and the trailing whitespace of a trailing one - dropping either
+* Trims the whitespace at the two ends of an inline run — the leading whitespace of a
+* leading text node and the trailing whitespace of a trailing one — dropping either
 * node when nothing survives.
 *
 * @remarks
@@ -2530,11 +2534,11 @@ function trimInlines(nodes) {
 * ending or spent as a space.
 *
 * @remarks
-* A hard break is `  \n` in markdown source, so it survives a re-parse only BETWEEN
+* 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
+* 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
@@ -2590,14 +2594,14 @@ function normalizeInlines(nodes, breaks) {
 	return coalesceText(out);
 }
 /**
-* Combines the projections of one node's children into the projection of that node -
+* Combines the projections of one node's children into the projection of that node —
 * the single place inline runs become paragraphs, so no ancestor has to decide it
 * twice.
 *
 * @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
+* 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
@@ -2677,7 +2681,7 @@ function mergeProjections(children) {
 	});
 }
 /**
-* Reads a projection as BLOCK content - the view a document, a blockquote, and a list
+* Reads a projection as block content — the view a document, a blockquote, and a list
 * item each need.
 *
 * @remarks
@@ -2723,7 +2727,7 @@ function projectionToBlocks(projection) {
 	return blocks;
 }
 /**
-* Reads a projection as INLINE content - the view a link, an emphasis, and a table cell
+* Reads a projection as inline content — the view a link, an emphasis, and a table cell
 * each need.
 *
 * @remarks
@@ -2750,7 +2754,7 @@ function projectionToInlines(projection) {
 	}];
 }
 /**
-* Projects one HTML leaf - a text node, a comment, or a doctype - to its
+* Projects one HTML leaf — a text node, a comment, or a doctype — to its
 * {@link MarkdownProjection}.
 *
 * @remarks
@@ -2780,8 +2784,8 @@ function projectHTMLLeaf(leaf) {
 	});
 }
 /**
-* Projects one HTML container - the document root or an element - from its children's
-* already-computed projections. THE element mapping, and the only place that decides
+* Projects one HTML container — the document root or an element — from its children's
+* already-computed projections. The element mapping, and the only place that decides
 * what an HTML tag becomes in markdown.
 *
 * @remarks
@@ -2793,13 +2797,13 @@ function projectHTMLLeaf(leaf) {
 * 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
+* `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.
+* 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
+* 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.
@@ -3087,36 +3091,36 @@ function projectHTMLNode(node, children) {
 	return merged;
 }
 /**
-* Projects an `@orkestrel/html` {@link HTMLNode} into a {@link MarkdownDocument} - the
+* Projects an `@orkestrel/html` {@link HTMLNode} into a {@link MarkdownDocument} — the
 * HTML→markdown direction, and the inverse of {@link markdownToHTML}.
 *
 * @remarks
-* **Engine.** One total handler table - {@link projectHTMLNode} for the containers,
-* {@link projectHTMLLeaf} for the leaves - folded by `@orkestrel/html`'s own `foldNode`, so
+* **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
+* 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
+* then truncate again — so the anchor law that follows 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
+* link or image is kept — `[text]()` — because 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:
+* 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
+* 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
@@ -3143,7 +3147,7 @@ function htmlToMarkdown(node) {
 	};
 }
 /**
-* Walks a {@link MarkdownNode} depth-first, pre-order, root-inclusive - yields
+* Walks a {@link MarkdownNode} depth-first, pre-order, root-inclusive — yields
 * the node itself, then recurses into its children (block children, list items,
 * image/link inline children, table header/row cells' inline nodes) in walk order.
 *
@@ -3206,16 +3210,16 @@ function* walkNodes(node) {
 	}
 }
 /**
-* Folds a {@link MarkdownNode} into a `T` through a total catamorphism - children are
+* Folds a {@link MarkdownNode} into a `T` through a total catamorphism — children are
 * folded first (post-order), then the node's own {@link MarkdownHandler} is invoked
 * with the already-folded children.
 *
 * @remarks
-* **Table contract.** A {@link TableNode} has no single `children` array - its cells
+* **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
+* 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.
 *
@@ -3358,10 +3362,10 @@ function foldNode(node, handlers, depth) {
 	}
 }
 /**
-* Rewrites a {@link MarkdownDocument} bottom-up (copy-on-write) - each node's children
+* Rewrites a {@link MarkdownDocument} bottom-up (copy-on-write) — each node's children
 * are rewritten first (post-order), then `rewrite` is applied to the node itself; the
-* document ROOT is never passed to `rewrite` (the `element: 'document'` invariant
-* always holds). A table's inline cells and a list's items ARE rewritten.
+* 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 too.
 *
 * @remarks
 * Never mutates `document`. An unchanged subtree keeps its input identity. A parent
@@ -3370,12 +3374,12 @@ function foldNode(node, handlers, depth) {
 * 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 accepted
-* input child is reused - `rewriteDocument` stays total and never produces a
+* input child is reused — `rewriteDocument` stays total and never produces a
 * structurally invalid document.
 *
 * Descent is capped at {@link MAX_DEPTH}, the same cap {@link walkNodes} and
 * {@link foldNode} observe: at `depth >= MAX_DEPTH` the subtree is passed through
-* UNCHANGED (by reference, not rebuilt, and `rewrite` is not invoked on it) instead of
+* 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.
 *
@@ -3642,7 +3646,7 @@ function rewriteDocument(document, rewrite) {
 }
 /**
 * Concatenates the `value` / `code` content of every descendant text / code-span /
-* code-block node under `node`, including image alternative content, in walk order -
+* 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).
 *
@@ -3719,6 +3723,9 @@ function flattenText(node) {
 * Renders a {@link MarkdownNode} to sanitized canonical HTML.
 *
 * @remarks
+* Sanitization is unconditional: the function takes one argument and declares no
+* options, so no call shape opts out of it.
+*
 * 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
@@ -3740,7 +3747,7 @@ function renderHTML(node) {
 //#endregion
 //#region src/core/shapers.ts
 /**
-* Describes the shape of a {@link TextNode} - a plain-text leaf inline run.
+* Describes the shape of a {@link TextNode} — a plain-text leaf inline run.
 *
 * @example
 * ```ts
@@ -3756,7 +3763,7 @@ var textShape = objectShape({
 	value: stringShape()
 });
 /**
-* Describes the shape of a {@link CodeSpanNode} - an inline code span (`` `code` ``).
+* Describes the shape of a {@link CodeSpanNode} — an inline code span (`` `code` ``).
 *
 * @example
 * ```ts
@@ -3772,7 +3779,7 @@ var codeSpanShape = objectShape({
 	value: stringShape()
 });
 /**
-* Describes the shape of a {@link LineBreakNode} - a GFM hard line-break leaf.
+* Describes the shape of a {@link LineBreakNode} — a GFM hard line-break leaf.
 *
 * @example
 * ```ts
@@ -3785,7 +3792,7 @@ var codeSpanShape = objectShape({
 */
 var lineBreakShape = objectShape({ element: literalShape(["break"]) });
 /**
-* Describes the shape of a {@link CodeBlockNode} - a fenced code block. `lang` is
+* Describes the shape of a {@link CodeBlockNode} — a fenced code block. `lang` is
 * optional (absent when the opening fence carries no info-string).
 *
 * @example
@@ -3804,7 +3811,7 @@ var codeBlockShape = objectShape({
 	code: stringShape()
 });
 /**
-* Describes the shape of a {@link ThematicBreakNode} - a horizontal rule. Carries no
+* Describes the shape of a {@link ThematicBreakNode} — a horizontal rule. Carries no
 * fields beyond its `element` discriminant.
 *
 * @example
@@ -3818,8 +3825,9 @@ var codeBlockShape = objectShape({
 */
 var thematicBreakShape = objectShape({ element: literalShape(["thematicBreak"]) });
 /**
-* Describes the shape of a {@link TableAlign} - the per-column GFM table alignment
-* literal.
+* Describes the shape of a {@link TableAlign} — the per-column GFM table alignment
+* literal. Absence is no member of it, so the shape refuses the `null` a bare `---`
+* delimiter takes in a `TableNode`'s `align` list.
 *
 * @example
 * ```ts
@@ -3838,7 +3846,7 @@ var tableAlignShape = literalShape([
 	"center"
 ]);
 /**
-* Describes the shape of {@link ListItemMatch} - the parsed parts of a single list-item
+* Describes the shape of {@link ListItemMatch} — the parsed parts of a single list-item
 * line the block phase's list detector returns. Fully non-recursive (no
 * nested node fields), so every field shapes directly.
 *
@@ -3867,14 +3875,14 @@ var listItemMatchShape = objectShape({
 *
 * @remarks
 * - **Construction.** Given a `string`, the constructor runs {@link parseProvenance} (the
-*   block phase then the inline phase) once, keeping the AST and a COPY of the span map
-*   that parse recorded. Given a {@link MarkdownDocument}, the document is adopted AS-IS
-*   and is NOT re-validated - gate an untrusted value with `isMarkdownDocument` first.
-* - **Provenance.** {@link span} reads the region of the ORIGINAL constructor string a
+*   block phase then the inline phase) once, keeping the AST and a copy of the span map
+*   that parse recorded. Given a {@link MarkdownDocument}, the document is adopted as-is
+*   and is not re-validated — gate an untrusted value with `isMarkdownDocument` first.
+* - **Provenance.** {@link span} reads the region of the original constructor string a
 *   node was produced from, and it is handle-relative: a string-constructed handle exposes
 *   the regions of the nodes it parsed, an adopted document exposes none, and a node from
 *   another handle reports `undefined` here whatever that handle reports. Each call
-*   returns a fresh value. A node reports the region THIS handle holds for its identity,
+*   returns a fresh value. A node reports the region this handle holds for its identity,
 *   else the region of the direct input a rewrite named for it, else `undefined`: a text
 *   run the parse joined from adjacent scanner output reports the region enclosing its
 *   parts, and only a rewrite output that holds no region of its own and was assembled
@@ -3882,23 +3890,22 @@ var listItemMatchShape = objectShape({
 *   {@link map} carries provenance across the rewrite: an unchanged node keeps its
 *   region, a one-source replacement takes the region of the node it replaced, and a
 *   rebuilt parent takes its original's.
-* - **Immutable.** {@link map} never mutates the stored AST - it returns a NEW `Markdown`
+* - **Immutable.** {@link map} never mutates the stored AST — it returns a new `Markdown`
 *   instance; the document root invariant (`element: 'document'`) always holds. An
 *   identity rewrite still returns a new handle, over the same document tree.
 * - **Traversal order.** {@link walk} and the `find` / `filter` / `reduce` queries built
 *   on it walk the AST depth-first, pre-order, root-inclusive (through {@link walkNodes});
-*   `stream` is shallow - only the document's direct block children.
+*   `stream` is shallow — only the document's direct block children.
 *
-* @example
+* @example Construct from a string and narrow with a guard
 * ```ts
-* import { Markdown, isHeadingNode, renderMarkdown } from '@src/core'
+* import { Markdown, isHeadingNode } from '@orkestrel/markdown'
 *
 * 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).'
+* markdown.document.children[0] // { element: 'heading', level: 1, children: [...] }
+*
+* const heading = markdown.find(isHeadingNode) // HeadingNode | undefined, narrowed
+* if (heading !== undefined) heading.level // number — narrowed to HeadingNode
 * ```
 */
 var Markdown = class Markdown {
@@ -3943,7 +3950,7 @@ var Markdown = class Markdown {
 		};
 	}
 	/**
-	* Returns THE deep traversal - a lazy, depth-first, pre-order, root-inclusive generator
+	* Returns the deep traversal — a lazy, depth-first, pre-order, root-inclusive generator
 	* over every {@link MarkdownNode} in the document. `find` / `filter` / `reduce`
 	* all iterate this single traversal.
 	*
@@ -3995,7 +4002,7 @@ var Markdown = class Markdown {
 	}
 	/**
 	* Returns a web-standard {@link ReadableStream} over the document's top-level block nodes
-	* (shallow, source order) - a fresh, pull-based source per call: one block is
+	* (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}.
@@ -4050,7 +4057,7 @@ var Markdown = class Markdown {
 //#region src/core/factories.ts
 /**
 * Creates a stateful markdown handle from a markdown string or an already-parsed
-* {@link MarkdownDocument} - a typed AST plus the query, rewrite, and fold operations
+* {@link MarkdownDocument} — a typed AST plus the query, rewrite, and fold operations
 * {@link MarkdownInterface} exposes.
 *
 * @remarks
@@ -4058,9 +4065,9 @@ var Markdown = class Markdown {
 * 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
+* {@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
+* 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}
@@ -4079,7 +4086,7 @@ function createMarkdown(input) {
 }
 /**
 * Compiles the {@link textShape} into a {@link ContractInterface} for
-* {@link TextNode} - a guard, coercing parser, JSON Schema, and seeded
+* {@link TextNode} — a guard, coercing parser, JSON Schema, and seeded
 * generator from one shape declaration.
 *
 * @returns A `TextNode` contract bundling `schema` / `is` / `parse` / `generate`
@@ -4097,7 +4104,7 @@ function createTextContract() {
 }
 /**
 * Compiles the {@link codeSpanShape} into a {@link ContractInterface} for
-* {@link CodeSpanNode} - a guard, coercing parser, JSON Schema, and seeded
+* {@link CodeSpanNode} — a guard, coercing parser, JSON Schema, and seeded
 * generator from one shape declaration.
 *
 * @returns A `CodeSpanNode` contract bundling `schema` / `is` / `parse` / `generate`
@@ -4131,7 +4138,7 @@ function createLineBreakContract() {
 }
 /**
 * Compiles the {@link codeBlockShape} into a {@link ContractInterface} for
-* {@link CodeBlockNode} - a guard, coercing parser, JSON Schema, and seeded
+* {@link CodeBlockNode} — a guard, coercing parser, JSON Schema, and seeded
 * generator from one shape declaration.
 *
 * @returns A `CodeBlockNode` contract bundling `schema` / `is` / `parse` / `generate`
@@ -4149,7 +4156,7 @@ function createCodeBlockContract() {
 }
 /**
 * Compiles the {@link thematicBreakShape} into a {@link ContractInterface} for
-* {@link ThematicBreakNode} - a guard, coercing parser, JSON Schema, and
+* {@link ThematicBreakNode} — a guard, coercing parser, JSON Schema, and
 * seeded generator from one shape declaration.
 *
 * @returns A `ThematicBreakNode` contract bundling `schema` / `is` / `parse` / `generate`