@orkestrel/markdown 0.0.13 → 0.0.15

package/dist/src/core/index.d.ts

@@ -1,22 +1,22 @@
 import { BooleanShape } from '@orkestrel/contract';
-import { CommentNode } from '@orkestrel/html';
-import { ContractInterface } from '@orkestrel/contract';
-import { DoctypeNode } from '@orkestrel/html';
-import { ElementNode } from '@orkestrel/html';
-import { Guard } from '@orkestrel/contract';
-import { HTMLDocument } from '@orkestrel/html';
-import { HTMLNode } from '@orkestrel/html';
+import type { CommentNode } from '@orkestrel/html';
+import type { ContractInterface } from '@orkestrel/contract';
+import type { DoctypeNode } from '@orkestrel/html';
+import type { ElementNode } from '@orkestrel/html';
+import type { Guard } from '@orkestrel/contract';
+import type { HTMLDocument } from '@orkestrel/html';
+import type { HTMLNode } from '@orkestrel/html';
 import { LiteralShape } from '@orkestrel/contract';
 import { NumberShape } from '@orkestrel/contract';
 import { ObjectShape } from '@orkestrel/contract';
 import { OptionalShape } from '@orkestrel/contract';
 import { StringShape } from '@orkestrel/contract';
-import { TextNode as TextNode_2 } from '@orkestrel/html';
+import type { TextNode as TextNode_2 } from '@orkestrel/html';
 
 /** Represents a node that can appear at the block level of a document (or inside a list item / blockquote). */
 export declare type BlockNode = HeadingNode | ParagraphNode | ListNode | TableNode | CodeBlockNode | BlockquoteNode | ThematicBreakNode;
 
-/** Represents a blockquote - `>`-prefixed lines; `children` the block content parsed from the de-quoted lines (so quotes nest). */
+/** Represents a blockquote — `>`-prefixed lines; `children` the block content parsed from the de-quoted lines (so quotes nest). */
 export declare interface BlockquoteNode {
     readonly element: 'blockquote';
     /** Holds the block content of the quote (the `>`-stripped lines, re-parsed as blocks). */
@@ -24,7 +24,7 @@ export declare interface BlockquoteNode {
 }
 
 /**
- * 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)
@@ -40,7 +40,7 @@ export declare interface BlockquoteNode {
 export declare function coalesceText(nodes: readonly InlineNode[], spans?: Map<MarkdownNode, MarkdownSpan>): readonly InlineNode[];
 
 /**
- * Represents a fenced code block - ```` ```lang ````. `code` is the verbatim block content (no
+ * Represents a fenced code block — ```` ```lang ````. `code` is the verbatim block content (no
  * inner markdown; the closing fence and the trailing newline are stripped), `lang`
  * the info-string language tag (the first word after the opening fence), absent when
  * none was given.
@@ -54,7 +54,7 @@ export declare interface CodeBlockNode {
 }
 
 /**
- * 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
@@ -67,14 +67,14 @@ export declare interface CodeBlockNode {
  * codeBlock.is({ element: 'codeBlock', code: 'x', lang: 'ts' })        // true
  * ```
  */
-export declare const codeBlockShape: ObjectShape<{
-    element: LiteralShape<readonly ["codeBlock"]>;
-    lang: OptionalShape<StringShape>;
-    code: StringShape;
+export declare const codeBlockShape: ObjectShape<    {
+element: LiteralShape<readonly ["codeBlock"]>;
+lang: OptionalShape<StringShape>;
+code: StringShape;
 }, false>;
 
 /**
- * Represents the located extent of one inline code span - the value the inline phase's code
+ * Represents the located extent of one inline code span — the value the inline phase's code
  * scanner returns for a matched backtick run.
  */
 export declare interface CodeSpanMatch {
@@ -85,7 +85,7 @@ export declare interface CodeSpanMatch {
 }
 
 /**
- * Represents an inline code span - `` `code` ``. `value` is the verbatim span text; no inner
+ * Represents an inline code span — `` `code` ``. `value` is the verbatim span text; no inner
  * markdown is parsed (code is literal), and the renderer HTML-escapes it inside a
  * `<code>` element.
  */
@@ -96,7 +96,7 @@ export declare interface CodeSpanNode {
 }
 
 /**
- * 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
@@ -107,9 +107,9 @@ export declare interface CodeSpanNode {
  * codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
  * ```
  */
-export declare const codeSpanShape: ObjectShape<{
-    element: LiteralShape<readonly ["codeSpan"]>;
-    value: StringShape;
+export declare const codeSpanShape: ObjectShape<    {
+element: LiteralShape<readonly ["codeSpan"]>;
+value: StringShape;
 }, false>;
 
 /**
@@ -147,7 +147,7 @@ export declare function collectList(lines: readonly MarkdownSource[], start: num
 export declare function collectTable(lines: readonly MarkdownSource[], start: number, spans?: Map<MarkdownNode, MarkdownSpan>): TableCollection;
 
 /**
- * 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
@@ -162,7 +162,7 @@ export declare function countIndent(line: string): number;
 
 /**
  * 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`
@@ -179,7 +179,7 @@ export declare function createCodeBlockContract(): ContractInterface<CodeBlockNo
 
 /**
  * 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`
@@ -211,7 +211,7 @@ export declare function createLineBreakContract(): ContractInterface<LineBreakNo
 
 /**
  * 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
@@ -219,9 +219,9 @@ export declare function createLineBreakContract(): ContractInterface<LineBreakNo
  * 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}
@@ -261,7 +261,7 @@ export declare function createProjection(parts?: Partial<MarkdownProjection>): M
 
 /**
  * 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`
@@ -278,7 +278,7 @@ export declare function createTextContract(): ContractInterface<TextNode>;
 
 /**
  * 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`
@@ -294,7 +294,7 @@ export declare function createTextContract(): ContractInterface<TextNode>;
 export declare function createThematicBreakContract(): ContractInterface<ThematicBreakNode>;
 
 /**
- * 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`.
  *
@@ -309,7 +309,7 @@ export declare function createThematicBreakContract(): ContractInterface<Themati
 export declare function delimiterToAlignments(delimiter: string): ReadonlyArray<TableAlign | null>;
 
 /**
- * Represents the located content and syntax bounds of one emphasis run - the value the inline
+ * Represents the located content and syntax bounds of one emphasis run — the value the inline
  * phase's emphasis locator returns for a matched marker run.
  */
 export declare interface EmphasisBounds {
@@ -324,7 +324,7 @@ export declare interface EmphasisBounds {
 }
 
 /**
- * Represents emphasized inline content - `*italic*` / `_italic_` (`strong: false`) or
+ * Represents emphasized inline content — `*italic*` / `_italic_` (`strong: false`) or
  * `**bold**` / `__bold__` (`strong: true`). `children` are the nested inline nodes,
  * so emphasis composes (a `**bold _and italic_**` is a strong node wrapping a text
  * node and an emphasis node).
@@ -338,7 +338,7 @@ export declare interface EmphasisNode {
 }
 
 /**
- * Represents the scanned result of one emphasis run - the node the inline phase's emphasis
+ * Represents the scanned result of one emphasis run — the node the inline phase's emphasis
  * scanner built from {@link EmphasisBounds} and where the scan resumes.
  */
 export declare interface EmphasisScan {
@@ -409,7 +409,7 @@ export declare function extractHeading(line: string): HeadingMatch | undefined;
 export declare function extractListItem(line: string): ListItemMatch | undefined;
 
 /**
- * Represents the parsed parts of a fenced-code opening line - the value the block phase's fence
+ * Represents the parsed parts of a fenced-code opening line — the value the block phase's fence
  * detector returns for a ```` ``` ```` or `~~~` opener.
  */
 export declare interface FenceMatch {
@@ -421,7 +421,7 @@ export declare interface FenceMatch {
 
 /**
  * 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).
  *
@@ -444,16 +444,16 @@ export declare interface FenceMatch {
 export declare function flattenText(node: MarkdownNode): string;
 
 /**
- * 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.
  *
@@ -477,7 +477,7 @@ export declare function flattenText(node: MarkdownNode): string;
 export declare function foldNode<T>(node: MarkdownNode, handlers: MarkdownHandlerMap<T>, depth: number): T;
 
 /**
- * Represents the parsed parts of a single ATX heading line - the value the block phase's heading
+ * Represents the parsed parts of a single ATX heading line — the value the block phase's heading
  * detector returns for a `#` … `######` line.
  */
 export declare interface HeadingMatch {
@@ -490,7 +490,7 @@ export declare interface HeadingMatch {
 }
 
 /**
- * Represents an ATX heading - `#` … `######`. `level` is 1–6 (the number of leading `#`),
+ * Represents an ATX heading — `#` … `######`. `level` is 1–6 (the number of leading `#`),
  * `children` the inline content of the heading text.
  */
 export declare interface HeadingNode {
@@ -502,36 +502,36 @@ export declare interface HeadingNode {
 }
 
 /**
- * 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
@@ -548,7 +548,7 @@ export declare interface HeadingNode {
 export declare function htmlToMarkdown(node: HTMLNode): MarkdownDocument;
 
 /**
- * Represents an inline image - `![alt](src)`. `children` are the inline nodes of the
+ * Represents an inline image — `![alt](src)`. `children` are the inline nodes of the
  * alternative content and `src` is the image destination.
  */
 export declare interface ImageNode {
@@ -563,7 +563,7 @@ export declare interface ImageNode {
 export declare type InlineNode = TextNode | EmphasisNode | CodeSpanNode | LineBreakNode | LinkNode | ImageNode;
 
 /**
- * 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.
  *
@@ -578,16 +578,16 @@ export declare type InlineNode = TextNode | EmphasisNode | CodeSpanNode | LineBr
 export declare function isBlankLine(line: string): boolean;
 
 /**
- * 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
@@ -632,7 +632,7 @@ export declare function isCodeBlockNode(node: MarkdownNode): node is CodeBlockNo
  * 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
@@ -659,7 +659,7 @@ export declare function isCodeSpanNode(node: MarkdownNode): node is CodeSpanNode
 export declare function isEmphasisNode(node: MarkdownNode): node is EmphasisNode;
 
 /**
- * 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
@@ -674,7 +674,7 @@ export declare function isEmphasisNode(node: MarkdownNode): node is EmphasisNode
 export declare function isEscapable(character: string): boolean;
 
 /**
- * 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
@@ -689,7 +689,7 @@ export declare function isEscapable(character: string): boolean;
 export declare function isFenceClose(line: string, marker: string): boolean;
 
 /**
- * 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
@@ -704,7 +704,7 @@ export declare function isFenceClose(line: string, marker: string): boolean;
 export declare function isFenceWhitespace(character: string | undefined): boolean;
 
 /**
- * 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
@@ -745,11 +745,11 @@ export declare function isHeadingNode(node: MarkdownNode): node is HeadingNode;
 export declare function isImageNode(node: MarkdownNode): node is ImageNode;
 
 /**
- * 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.
  *
@@ -806,12 +806,12 @@ export declare function isLinkNode(node: MarkdownNode): node is LinkNode;
 export declare function isListNode(node: MarkdownNode): node is ListNode;
 
 /**
- * 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.
  *
@@ -829,16 +829,16 @@ export declare function isListNode(node: MarkdownNode): node is ListNode;
 export declare const isMarkdownDocument: Guard<MarkdownDocument>;
 
 /**
- * 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
@@ -867,7 +867,7 @@ export declare const isMarkdownNode: Guard<MarkdownNode>;
 export declare function isParagraphNode(node: MarkdownNode): node is ParagraphNode;
 
 /**
- * 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
@@ -894,9 +894,9 @@ export declare function isQuote(line: string): boolean;
 export declare function isTableNode(node: MarkdownNode): node is TableNode;
 
 /**
- * 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)
@@ -923,7 +923,7 @@ export declare function isTableStart(header: string, delimiter: string | undefin
 export declare function isTextNode(node: MarkdownNode): node is TextNode;
 
 /**
- * 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 (`---`,
  * `***`, `___`, `- - -`).
  *
@@ -966,13 +966,16 @@ export declare function isThematicBreakNode(node: MarkdownNode): node is Themati
  */
 export declare function joinSources(sources: readonly MarkdownSource[], separator: string): MarkdownSource;
 
-/** Represents a GFM hard line break - two or more trailing spaces before a newline. */
+/**
+ * Represents a GFM hard line break — two or more trailing spaces before a newline in
+ * markdown source, a `br` element in HTML.
+ */
 export declare interface LineBreakNode {
     readonly element: 'break';
 }
 
 /**
- * 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
@@ -983,12 +986,12 @@ export declare interface LineBreakNode {
  * lineBreak.is({ element: 'break' }) // true
  * ```
  */
-export declare const lineBreakShape: ObjectShape<{
-    element: LiteralShape<readonly ["break"]>;
+export declare const lineBreakShape: ObjectShape<    {
+element: LiteralShape<readonly ["break"]>;
 }, false>;
 
 /**
- * Represents the located syntax bounds of one `[text](href)` link - the value the inline phase's
+ * Represents the located syntax bounds of one `[text](href)` link — the value the inline phase's
  * link locator returns for a balanced label followed by a destination.
  */
 export declare interface LinkBounds {
@@ -999,7 +1002,7 @@ export declare interface LinkBounds {
 }
 
 /**
- * Represents an inline link - `[text](href)`. `children` are the inline nodes of the link text.
+ * Represents an inline link — `[text](href)`. `children` are the inline nodes of the link text.
  * At render, html's floor removes a refused `href` attribute and the link keeps its
  * text; {@link htmlToMarkdown} instead stores a refused destination as `''`.
  */
@@ -1012,7 +1015,7 @@ export declare interface LinkNode {
 }
 
 /**
- * Represents the scanned result of one `[text](href)` link - the node the inline phase's link
+ * Represents the scanned result of one `[text](href)` link — the node the inline phase's link
  * scanner built from {@link LinkBounds} and where the scan resumes.
  */
 export declare interface LinkScan {
@@ -1023,7 +1026,7 @@ export declare interface LinkScan {
 }
 
 /**
- * Represents the result of collecting one list - the node the construct scanner built and where
+ * Represents the result of collecting one list — the node the construct scanner built and where
  * the block phase resumes.
  */
 export declare interface ListCollection {
@@ -1034,7 +1037,7 @@ export declare interface ListCollection {
 }
 
 /**
- * Represents the parsed parts of a single list-item line - the value the block phase's
+ * Represents the parsed parts of a single list-item line — the value the block phase's
  * list detector returns for a `-` / `*` / `+` bullet or a `1.` / `1)` ordinal line.
  */
 export declare interface ListItemMatch {
@@ -1046,12 +1049,12 @@ export declare interface ListItemMatch {
     readonly content: string;
     /** Holds the leading-space indent of the marker. */
     readonly indent: number;
-    /** Holds the full marker width (indent + bullet/ordinal + the following space) - the continuation indent. */
+    /** Holds the full marker width (indent + bullet/ordinal + the following space) — the continuation indent. */
     readonly marker: number;
 }
 
 /**
- * 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.
  *
@@ -1064,15 +1067,15 @@ export declare interface ListItemMatch {
  * listItemParts.is({ ordered: false, start: 1, content: 'hi', indent: 0, marker: 2 }) // true
  * ```
  */
-export declare const listItemMatchShape: ObjectShape<{
-    ordered: BooleanShape;
-    start: NumberShape;
-    content: StringShape;
-    indent: NumberShape;
-    marker: NumberShape;
+export declare const listItemMatchShape: ObjectShape<    {
+ordered: BooleanShape;
+start: NumberShape;
+content: StringShape;
+indent: NumberShape;
+marker: NumberShape;
 }, false>;
 
-/** Represents one item of a {@link ListNode} - `children` the block content of the item (typically one paragraph, plus any nested list). */
+/** Represents one item of a {@link ListNode} — `children` the block content of the item (typically one paragraph, plus any nested list). */
 export declare interface ListItemNode {
     readonly element: 'listItem';
     /** Holds the block content of the list item (its text as a paragraph, plus any nested list). */
@@ -1080,7 +1083,7 @@ export declare interface ListItemNode {
 }
 
 /**
- * Represents a list - bulleted (`-` / `*` / `+`, `ordered: false`) or numbered (`1.` / `1)`,
+ * Represents a list — bulleted (`-` / `*` / `+`, `ordered: false`) or numbered (`1.` / `1)`,
  * `ordered: true`). `start` is the first ordinal of an ordered list (usually `1`).
  * Nesting is expressed by a {@link ListNode} appearing in a {@link ListItemNode}'s
  * `children`.
@@ -1096,7 +1099,7 @@ export declare interface ListNode {
 }
 
 /**
- * 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
@@ -1116,7 +1119,7 @@ export declare interface ListNode {
 export declare function locateEmphasis(source: string, start: number, to: number): EmphasisBounds | undefined;
 
 /**
- * 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 `[`).
@@ -1140,14 +1143,14 @@ export declare function locateLink(source: string, start: number, to: number): L
  *
  * @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
@@ -1155,23 +1158,22 @@ export declare function locateLink(source: string, start: number, to: number): L
  *   {@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
  * ```
  */
 export declare class Markdown implements MarkdownInterface {
@@ -1198,7 +1200,7 @@ export declare class Markdown implements MarkdownInterface {
      */
     span(node: MarkdownNode): MarkdownSpan | undefined;
     /**
-     * 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.
      *
@@ -1235,7 +1237,7 @@ export declare class Markdown implements MarkdownInterface {
     fold<T>(handlers: MarkdownHandlerMap<T>): T;
     /**
      * 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}.
@@ -1258,28 +1260,35 @@ export declare class Markdown implements MarkdownInterface {
     stream(): ReadableStream<BlockNode>;
 }
 
-/** Represents one projected table cell - the inline content and alignment of a `th` / `td`. */
+/**
+ * Represents one projected table cell — the inline content and alignment of a `th` / `td`.
+ *
+ * @remarks
+ * {@link htmlToMarkdown} derives a projected table's header row from the source HTML
+ * structure rather than from any flag a cell carries: the header is the first
+ * `th`-bearing row, and every row after it becomes a body row.
+ */
 export declare interface MarkdownCell {
     /** Holds the alignment the cell's `align` attribute declared; `undefined` when it declared none. */
     readonly align: TableAlign | undefined;
-    /** Holds the cell's inline content - a table cell is inline-only, so block content flattens to text. */
+    /** Holds the cell's inline content — a table cell is inline-only, so block content flattens to text. */
     readonly inlines: readonly InlineNode[];
 }
 
 /**
- * Pairs a rewritten value with the input node each rewritten node was produced from -
+ * Pairs a rewritten value with the input node each rewritten node was produced from —
  * what `rewriteDocument` returns, so provenance survives a rewrite instead of ending at
  * it. `T` is the rewritten value: the document for a whole-document rewrite.
  *
  * @remarks
- * `derivations` is keyed by the nodes of the OUTPUT, and each entry names the DIRECT
+ * `derivations` is keyed by the nodes of the output, and each entry names the direct
  * input the rewrite drew that output from. {@link MarkdownInterface.map} resolves each
  * output node against the source handle's own spans in a fixed order, and follows no
  * second derivation edge:
  *
- * - the output identity's OWN span in the source handle wins, whatever the map says,
- *   so an identity the rewrite reused - one node returned for several inputs, or a
- *   node the handler moved elsewhere in the tree - keeps the region it already had;
+ * - the output identity's own span in the source handle wins, whatever the map says,
+ *   so an identity the rewrite reused — one node returned for several inputs, or a
+ *   node the handler moved elsewhere in the tree — keeps the region it already had;
  * - otherwise the span of the direct input the entry names, where that input has one;
  * - otherwise none. Where the output identity holds no region of its own, a node mapped
  *   to `undefined`, a node whose direct input has no span, and a node with no entry at
@@ -1296,7 +1305,7 @@ derivations: ReadonlyMap<MarkdownNode, MarkdownNode | undefined>
 ];
 
 /**
- * Represents the root of a parsed markdown AST - the ordered block children of the whole
+ * Represents the root of a parsed markdown AST — the ordered block children of the whole
  * document. The value {@link MarkdownInterface.document} holds.
  */
 export declare interface MarkdownDocument {
@@ -1306,14 +1315,14 @@ export declare interface MarkdownDocument {
 }
 
 /**
- * Represents a fold handler for one AST element - receives the node and its children
- * ALREADY folded to `T`, and produces the node's own `T`. The building block of a
+ * Represents a fold handler for one AST element — receives the node and its children
+ * already folded to `T`, and produces the node's own `T`. The building block of a
  * {@link MarkdownHandlerMap} catamorphism table.
  */
 export declare type MarkdownHandler<TNode, T> = (node: TNode, children: readonly T[]) => T;
 
 /**
- * Represents the total catamorphism table for {@link MarkdownInterface.fold} - one
+ * Represents the total catamorphism table for {@link MarkdownInterface.fold} — one
  * {@link MarkdownHandler} per AST element, keyed by its `element` discriminant. Every
  * key is required: a fold is total over the AST, so there is no element it can skip.
  */
@@ -1324,11 +1333,11 @@ export declare interface MarkdownHandlerMap<T> {
     readonly heading: MarkdownHandler<HeadingNode, T>;
     /** Folds a {@link ParagraphNode} from its already-folded inline children. */
     readonly paragraph: MarkdownHandler<ParagraphNode, T>;
-    /** Folds a {@link ThematicBreakNode} (leaf - always called with an empty children list). */
+    /** Folds a {@link ThematicBreakNode} (leaf — always called with an empty children list). */
     readonly thematicBreak: MarkdownHandler<ThematicBreakNode, T>;
     /** Folds a {@link BlockquoteNode} from its already-folded block children. */
     readonly blockquote: MarkdownHandler<BlockquoteNode, T>;
-    /** Folds a {@link CodeBlockNode} (leaf - always called with an empty children list). */
+    /** Folds a {@link CodeBlockNode} (leaf — always called with an empty children list). */
     readonly codeBlock: MarkdownHandler<CodeBlockNode, T>;
     /** Folds a {@link ListNode} from its already-folded item children. */
     readonly list: MarkdownHandler<ListNode, T>;
@@ -1336,19 +1345,19 @@ export declare interface MarkdownHandlerMap<T> {
     readonly listItem: MarkdownHandler<ListItemNode, T>;
     /**
      * Folds a {@link TableNode} from its cells' already-folded inline nodes, flattened
-     * to ONE folded `T` per inline node - header cells first (column order), then body
-     * rows' cells (row order, then column order). It is NOT a leaf: recover cell
+     * to one folded `T` per inline node — header cells first (column order), then body
+     * rows' cells (row order, then column order). It is not a leaf: recover cell
      * boundaries from `node.header[c].length` / `node.rows[r][c].length` against the
      * flat `children` list.
      */
     readonly table: MarkdownHandler<TableNode, T>;
-    /** Folds a {@link TextNode} (leaf - always called with an empty children list). */
+    /** Folds a {@link TextNode} (leaf — always called with an empty children list). */
     readonly text: MarkdownHandler<TextNode, T>;
     /** Folds an {@link EmphasisNode} from its already-folded inline children. */
     readonly emphasis: MarkdownHandler<EmphasisNode, T>;
-    /** Folds a {@link CodeSpanNode} (leaf - always called with an empty children list). */
+    /** Folds a {@link CodeSpanNode} (leaf — always called with an empty children list). */
     readonly codeSpan: MarkdownHandler<CodeSpanNode, T>;
-    /** Folds a {@link LineBreakNode} (leaf - always called with an empty children list). */
+    /** Folds a {@link LineBreakNode} (leaf — always called with an empty children list). */
     readonly break: MarkdownHandler<LineBreakNode, T>;
     /** Folds a {@link LinkNode} from its already-folded inline children. */
     readonly link: MarkdownHandler<LinkNode, T>;
@@ -1361,14 +1370,14 @@ export declare interface MarkdownHandlerMap<T> {
  * the query, rewrite, and fold operations over it.
  *
  * @remarks
- * - **Immutable.** {@link MarkdownInterface.map} never mutates the stored AST - it
- *   returns a NEW {@link MarkdownInterface} instance; the document root invariant
+ * - **Immutable.** {@link MarkdownInterface.map} never mutates the stored AST — it
+ *   returns a new {@link MarkdownInterface} instance; the document root invariant
  *   (`element: 'document'`) always holds.
  * - **Traversal order.** `walk` / `find` / `filter` / `reduce` walk the AST
- *   depth-first, pre-order, root-inclusive; `stream` is shallow - only the
+ *   depth-first, pre-order, root-inclusive; `stream` is shallow — only the
  *   document's direct block children.
  * - **`stream`.** Returns a web-standard {@link ReadableStream} over the top-level
- *   blocks - a fresh, pull-based source per call: exactly one block is enqueued per
+ *   blocks — a fresh, pull-based source per call: exactly one block is enqueued per
  *   `pull`, so a slow consumer's backpressure is respected and no work happens ahead
  *   of demand. Cancellable through the returned stream's own `cancel()`, async-iterable
  *   wherever the platform supports it (Node, Deno, and browsers that ship the
@@ -1382,7 +1391,7 @@ export declare interface MarkdownInterface {
     /** Holds the stored {@link MarkdownDocument} AST root. */
     readonly document: MarkdownDocument;
     /**
-     * Returns THE deep traversal - a lazy, depth-first, pre-order, root-inclusive
+     * Returns the deep traversal — a lazy, depth-first, pre-order, root-inclusive
      * {@link Generator} over every {@link MarkdownNode} in the document. The sync
      * `for (const node of markdown.walk())` surface is also consumable by
      * `for await (const node of markdown.walk())` (JavaScript accepts a sync
@@ -1391,11 +1400,17 @@ export declare interface MarkdownInterface {
      * is shallow (top-level blocks only) and backpressure-respecting.
      */
     walk(): Generator<MarkdownNode>;
-    /** Finds the first node (depth-first, pre-order) narrowed by a type guard. */
+    /**
+     * Finds the first node (depth-first, pre-order) narrowed by a type guard, and returns
+     * `undefined` when no node matches; a second overload takes a plain predicate.
+     */
     find<T extends MarkdownNode>(guard: (node: MarkdownNode) => node is T): T | undefined;
     /** Finds the first node (depth-first, pre-order) matching a predicate. */
     find(predicate: (node: MarkdownNode) => boolean): MarkdownNode | undefined;
-    /** Collects every node (depth-first, pre-order) narrowed by a type guard. */
+    /**
+     * Collects every node (depth-first, pre-order) narrowed by a type guard; a second
+     * overload takes a plain predicate.
+     */
     filter<T extends MarkdownNode>(guard: (node: MarkdownNode) => node is T): readonly T[];
     /** Collects every node (depth-first, pre-order) matching a predicate. */
     filter(predicate: (node: MarkdownNode) => boolean): readonly MarkdownNode[];
@@ -1408,11 +1423,11 @@ export declare interface MarkdownInterface {
      *
      * @remarks
      * Provenance is per handle and per node identity, so a node reports a region only
-     * where THIS handle holds coordinates for it. A handle constructed from an adopted
+     * where this handle holds coordinates for it. A handle constructed from an adopted
      * {@link MarkdownDocument} reports `undefined` for every node: it parsed no string,
-     * so no coordinates exist to report. A text run the PARSE joined from adjacent
+     * so no coordinates exist to report. A text run the parse joined from adjacent
      * scanner output reports the region enclosing its parts rather than `undefined`;
-     * only a REWRITE output that holds no region of its own and was assembled from
+     * only a rewrite output that holds no region of its own and was assembled from
      * separate source nodes reports `undefined`. The region a node does report is the
      * original source it was produced from, which can include syntax its value drops
      * and characters that normalization removed. Each call returns a fresh value rather
@@ -1421,33 +1436,33 @@ export declare interface MarkdownInterface {
     span(node: MarkdownNode): MarkdownSpan | undefined;
     /** Rewrites the AST bottom-up (copy-on-write) and returns a new {@link MarkdownInterface}. */
     map(rewrite: MarkdownRewriteHandler): MarkdownInterface;
-    /** Folds the AST depth-first, pre-order into an accumulator. */
+    /** Folds the AST depth-first, pre-order into an accumulator through a reducer callback. */
     reduce<T>(callback: (accumulator: T, node: MarkdownNode) => T, initial: T): T;
     /** Runs a total catamorphism over the document using a {@link MarkdownHandlerMap} table. */
     fold<T>(handlers: MarkdownHandlerMap<T>): T;
     /**
      * Returns a web-standard {@link ReadableStream} over the document's top-level block nodes
-     * (shallow, source order) - a lazy, pull-based, backpressure-respecting source. A
+     * (shallow, source order) — a lazy, pull-based, backpressure-respecting source. A
      * fresh, independently-replayable stream every call; never mutates the document.
      */
     stream(): ReadableStream<BlockNode>;
 }
 
 /**
- * Represents any node in a markdown AST - the {@link MarkdownDocument} root, a {@link BlockNode},
+ * Represents any node in a markdown AST — the {@link MarkdownDocument} root, a {@link BlockNode},
  * a {@link ListItemNode}, or an {@link InlineNode}. The exhaustive set every
  * projection's `switch` covers.
  */
 export declare type MarkdownNode = MarkdownDocument | BlockNode | ListItemNode | InlineNode;
 
 /**
- * Pairs a parsed document with the {@link MarkdownSpan} of each of its nodes - what
+ * Pairs a parsed document with the {@link MarkdownSpan} of each of its nodes — what
  * `parseProvenance` returns, and what `parseDocument` projects the document out of.
  *
  * @remarks
- * `spans` is keyed by node identity, so it addresses the nodes of THAT document and
- * no other. A node the parse merged from adjacent scanner output - the text run
- * `coalesceText` joins - is present and carries the region ENCLOSING its parts, from
+ * `spans` is keyed by node identity, so it addresses the nodes of that document and
+ * no other. A node the parse merged from adjacent scanner output — the text run
+ * `coalesceText` joins — is present and carries the region enclosing its parts, from
  * the first part's `start` to the last part's `end`, which can include original text
  * lying between them. Absence means the parse recorded no region for the node, not
  * that the node was assembled from more than one region. Destructure it as
@@ -1459,7 +1474,7 @@ spans: ReadonlyMap<MarkdownNode, MarkdownSpan>
 ];
 
 /**
- * Represents what one HTML node projects to on the way to markdown - the fold value
+ * Represents what one HTML node projects to on the way to markdown — the fold value
  * `htmlToMarkdown` carries up the AST.
  *
  * @remarks
@@ -1469,14 +1484,14 @@ spans: ReadonlyMap<MarkdownNode, MarkdownSpan>
  * under a `pre`. Rather than guess, each node reports every view its ancestors could
  * need, and the ancestor that knows the context takes the one it wants.
  *
- * - `blocks` / `inlines` - the block and inline views. They are exclusive by
+ * - `blocks` / `inlines` — the block and inline views. They are exclusive by
  *   construction: as soon as a node contributes a block, the inline runs around it
  *   are wrapped into paragraphs, so `blocks` being non-empty means `inlines` is
  *   empty and no interleaving is ever lost.
- * - `text` - the raw, uncollapsed, unescaped subtree text a code span and a
+ * - `text` — the raw, uncollapsed, unescaped subtree text a code span and a
  *   `pre > code` body need verbatim. An `UNSAFE_ELEMENTS` subtree contributes none
  *   of it, so a script body can never resurface as prose.
- * - `cells` / `rows` - table structure in flight. A cell travels up to its `tr` and a
+ * - `cells` / `rows` — table structure in flight. A cell travels up to its `tr` and a
  *   row up to its `table`, passing through the `thead` / `tbody` wrappers between
  *   them untouched; whatever never reaches a table degrades to paragraphs.
  */
@@ -1489,25 +1504,25 @@ export declare interface MarkdownProjection {
     readonly text: string;
     /** Holds the cells this node contributes to an enclosing row. */
     readonly cells: readonly MarkdownCell[];
-    /** Holds the rows this node contributes to an enclosing table - each its cells, in column order. */
+    /** Holds the rows this node contributes to an enclosing table — each its cells, in column order. */
     readonly rows: ReadonlyArray<readonly MarkdownCell[]>;
 }
 
 /**
- * Represents a copy-on-write node rewrite applied bottom-up by {@link MarkdownInterface.map} -
+ * Represents a copy-on-write node rewrite applied bottom-up by {@link MarkdownInterface.map} —
  * receives one node (its own children already rewritten) and returns its
  * replacement (the same node, unchanged, or a new node).
  */
 export declare type MarkdownRewriteHandler = (node: MarkdownNode) => MarkdownNode;
 
 /**
- * Maps one run of a {@link MarkdownSource} back to the region of the ORIGINAL
+ * Maps one run of a {@link MarkdownSource} back to the region of the original
  * markdown string it was taken from.
  *
  * @remarks
  * `offset` addresses {@link MarkdownSource.text}; `start` and `end` address the
  * original string. The run's original length derives from `end - start` rather than
- * being stored beside them, so no length member exists to drift. The run's DERIVED
+ * being stored beside them, so no length member exists to drift. The run's derived
  * extent ends where the next segment's `offset` begins, so a run may cover more of the
  * original than it holds derived: the separator run `joinSources` records over a
  * normalized `\r\n` terminator is one derived code unit over a two-unit original
@@ -1518,10 +1533,10 @@ export declare type MarkdownRewriteHandler = (node: MarkdownNode) => MarkdownNod
  *
  * - strictly inside the run, `p` projects to `start + (p - offset)`;
  * - at the run's derived end, `p` projects to `end`, so the boundary claims the run's
- *   whole original region instead of the prefix an affine step would reach - which is
+ *   whole original region instead of the prefix an affine step would reach — which is
  *   how the one-unit `\r\n` separator run above reports its two-unit region;
  * - a zero-width `p` that coincides with a later segment's `offset` resolves through the
- *   LAST segment whose `offset` equals `p`, skipping every earlier segment at that
+ *   last segment whose `offset` equals `p`, skipping every earlier segment at that
  *   position whatever its extent, so a discontinuous abutment reports that final run's
  *   `start` rather than the earlier run's `end`.
  *
@@ -1538,7 +1553,7 @@ export declare interface MarkdownSegment {
 
 /**
  * Pairs a piece of derived markdown text with the runs mapping it back to the
- * original string - what `splitLines` returns per line, so every phase downstream of
+ * original string — what `splitLines` returns per line, so every phase downstream of
  * it keeps original coordinates instead of reconstructing them from node values.
  *
  * @remarks
@@ -1563,14 +1578,14 @@ export declare interface MarkdownSource {
 }
 
 /**
- * Addresses a half-open region of the ORIGINAL markdown string, in UTF-16 code units -
+ * Addresses a half-open region of the original markdown string, in UTF-16 code units —
  * `start` inclusive, `end` exclusive. The provenance a parse records for a node and
  * {@link MarkdownInterface.span} reads back.
  *
  * @remarks
  * The coordinates address the string the handle was constructed from, never the line
  * text a later phase walks, so `markdown.slice(span.start, span.end)` returns the
- * ORIGINAL source region the node was produced from. That region is not the node's
+ * original source region the node was produced from. That region is not the node's
  * value: it carries the syntax the value drops, such as a `\` escape marker, and the
  * characters that normalization removed, such as a trailing space the paragraph phase
  * trimmed. The text node of `'a \nb'` has the `value` `a\nb` and reports
@@ -1610,7 +1625,7 @@ export declare function markdownToHTML(node: MarkdownNode): HTMLDocument;
  * 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`.
@@ -1618,14 +1633,14 @@ export declare function markdownToHTML(node: MarkdownNode): HTMLDocument;
 export declare const MAX_DEPTH = 64;
 
 /**
- * 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
@@ -1651,11 +1666,11 @@ export declare function mergeProjections(children: readonly MarkdownProjection[]
  * 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
@@ -1687,7 +1702,7 @@ export declare function normalizeInlines(nodes: readonly InlineNode[], breaks: b
  */
 export declare function normalizeParagraphLine(source: MarkdownSource, breaks: boolean): MarkdownSource;
 
-/** Represents a paragraph - a run of non-blank lines that is not another block; `children` its inline content. */
+/** Represents a paragraph — a run of non-blank lines that is not another block; `children` its inline content. */
 export declare interface ParagraphNode {
     readonly element: 'paragraph';
     /** Holds the inline content of the paragraph. */
@@ -1713,7 +1728,8 @@ export declare function parseBlocks(lines: readonly MarkdownSource[], depth: num
 
 /**
  * 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.
@@ -1727,7 +1743,8 @@ export declare function parseDocument(markdown: string): MarkdownDocument;
 
 /**
  * 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.
@@ -1740,7 +1757,8 @@ export declare function parseDocument(markdown: string): MarkdownDocument;
 export declare function parseInline(text: string): readonly InlineNode[];
 
 /**
- * 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.
@@ -1754,7 +1772,7 @@ export declare function parseInline(text: string): readonly InlineNode[];
 export declare function parseProvenance(markdown: string): MarkdownParseResult;
 
 /**
- * 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
@@ -1775,8 +1793,8 @@ export declare function parseProvenance(markdown: string): MarkdownParseResult;
 export declare function projectHTMLLeaf(leaf: CommentNode | DoctypeNode | TextNode_2): MarkdownProjection;
 
 /**
- * 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
@@ -1788,13 +1806,13 @@ export declare function projectHTMLLeaf(leaf: CommentNode | DoctypeNode | TextNo
  * 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.
@@ -1812,7 +1830,7 @@ export declare function projectHTMLLeaf(leaf: CommentNode | DoctypeNode | TextNo
 export declare function projectHTMLNode(node: ElementNode | HTMLDocument, children: readonly MarkdownProjection[]): MarkdownProjection;
 
 /**
- * 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
@@ -1833,7 +1851,7 @@ export declare function projectHTMLNode(node: ElementNode | HTMLDocument, childr
 export declare function projectionToBlocks(projection: MarkdownProjection): readonly BlockNode[];
 
 /**
- * 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
@@ -1874,6 +1892,9 @@ export declare function projectSpan(source: MarkdownSource, from: number, to: nu
  * 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
@@ -1892,15 +1913,15 @@ export declare function projectSpan(source: MarkdownSource, from: number, to: nu
 export declare function renderHTML(node: MarkdownNode): string;
 
 /**
- * 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.
  *
@@ -1923,10 +1944,10 @@ export declare function renderHTML(node: MarkdownNode): string;
 export declare function renderMarkdown(node: MarkdownNode): string;
 
 /**
- * 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
@@ -1935,12 +1956,12 @@ export declare function renderMarkdown(node: MarkdownNode): string;
  * 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.
  *
@@ -1959,7 +1980,7 @@ export declare function rewriteDocument(document: MarkdownDocument, rewrite: Mar
 
 /**
  * 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).
  *
@@ -1976,7 +1997,7 @@ export declare function rewriteDocument(document: MarkdownDocument, rewrite: Mar
 export declare function scanCode(source: string, start: number, to: number): CodeSpanMatch | undefined;
 
 /**
- * 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
@@ -2000,7 +2021,7 @@ export declare function scanCode(source: string, start: number, to: number): Cod
 export declare function scanEmphasis(source: string, start: number, to: number, depth?: number): EmphasisScan | undefined;
 
 /**
- * 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
@@ -2012,10 +2033,10 @@ export declare function scanEmphasis(source: string, start: number, to: number,
  * @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
@@ -2051,7 +2072,7 @@ export declare function scanInline(source: string, from: number, to: number, dep
 export declare function scanInlineSource(source: MarkdownSource, from: number, to: number, spans: Map<MarkdownNode, MarkdownSpan>, depth?: number): readonly InlineNode[];
 
 /**
- * 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
@@ -2106,10 +2127,11 @@ export declare function sliceSource(source: MarkdownSource, from: number, to: nu
 export declare function splitLines(markdown: string): readonly MarkdownSource[];
 
 /**
- * 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
@@ -2136,8 +2158,8 @@ export declare function splitTableRow(row: string): readonly string[];
 export declare function splitTableSources(row: MarkdownSource): readonly MarkdownSource[];
 
 /**
- * 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).
@@ -2175,12 +2197,19 @@ export declare function stripQuote(source: MarkdownSource): MarkdownSource;
  * by `null` in {@link TableNode.align}: the positional array requires one entry per
  * column, JSON cannot carry `undefined` in an array, and the bare delimiter is an
  * explicit no-alignment marker rather than an omitted value.
+ *
+ * @remarks
+ * The other place absence appears is {@link MarkdownCell.align}, which holds
+ * `undefined` when the projected cell declared no alignment. That member is a plain
+ * optional property on one cell rather than an entry in a positional array, so it
+ * takes the ordinary `undefined` instead of the in-band `null` marker.
  */
 export declare type TableAlign = 'left' | 'right' | 'center';
 
 /**
- * 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
@@ -2196,7 +2225,7 @@ export declare type TableAlign = 'left' | 'right' | 'center';
 export declare const tableAlignShape: LiteralShape<readonly ["left", "right", "center"]>;
 
 /**
- * Represents the result of collecting one GFM table - the node the construct scanner built and
+ * Represents the result of collecting one GFM table — the node the construct scanner built and
  * where the block phase resumes.
  */
 export declare interface TableCollection {
@@ -2207,16 +2236,16 @@ export declare interface TableCollection {
 }
 
 /**
- * Represents a GFM table - `header` the inline content of each header cell, `rows` the body
+ * Represents a GFM table — `header` the inline content of each header cell, `rows` the body
  * rows (each a list of cells, each cell inline content), `align` the per-column
  * alignment from the delimiter row. A short body row is padded with empty cells; an
  * over-long one is truncated to the header's column count.
  */
 export declare interface TableNode {
     readonly element: 'table';
-    /** Holds the header row - one cell of inline content per column. */
+    /** Holds the header row — one cell of inline content per column. */
     readonly header: ReadonlyArray<readonly InlineNode[]>;
-    /** Holds the body rows - each a list of cells, each cell inline content. */
+    /** Holds the body rows — each a list of cells, each cell inline content. */
     readonly rows: ReadonlyArray<ReadonlyArray<readonly InlineNode[]>>;
     /**
      * Holds the per-column alignment from the delimiter row, in column order. `null`
@@ -2228,19 +2257,19 @@ export declare interface TableNode {
 }
 
 /**
- * Represents a run of plain text - the leaf inline node. `value` is the decoded text with
+ * Represents a run of plain text — the leaf inline node. `value` is the decoded text with
  * markdown escapes (`\*`, `\_`, …) already resolved to their literal characters;
  * html's text encoder escapes `&`, `<`, `>` on the way out; `"` and `'` stay literal
  * in character data.
  */
 export declare interface TextNode {
     readonly element: 'text';
-    /** Holds the literal text content (escapes resolved, NOT yet HTML-escaped). */
+    /** Holds the literal text content (escapes resolved, not yet HTML-escaped). */
     readonly value: string;
 }
 
 /**
- * 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
@@ -2251,18 +2280,18 @@ export declare interface TextNode {
  * text.is({ element: 'text', value: 'hi' }) // true
  * ```
  */
-export declare const textShape: ObjectShape<{
-    element: LiteralShape<readonly ["text"]>;
-    value: StringShape;
+export declare const textShape: ObjectShape<    {
+element: LiteralShape<readonly ["text"]>;
+value: StringShape;
 }, false>;
 
-/** Represents a thematic break - a horizontal rule (`---` / `***` / `___` on its own line). */
+/** Represents a thematic break — a horizontal rule (`---` / `***` / `___` on its own line). */
 export declare interface ThematicBreakNode {
     readonly element: 'thematicBreak';
 }
 
 /**
- * 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
@@ -2274,13 +2303,13 @@ export declare interface ThematicBreakNode {
  * thematicBreak.is({ element: 'thematicBreak' }) // true
  * ```
  */
-export declare const thematicBreakShape: ObjectShape<{
-    element: LiteralShape<readonly ["thematicBreak"]>;
+export declare const thematicBreakShape: ObjectShape<    {
+element: LiteralShape<readonly ["thematicBreak"]>;
 }, false>;
 
 /**
- * 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
@@ -2313,7 +2342,7 @@ export declare function trimInlines(nodes: readonly InlineNode[]): readonly Inli
 export declare function trimSource(source: MarkdownSource): MarkdownSource;
 
 /**
- * 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
@@ -2327,7 +2356,7 @@ export declare function trimSource(source: MarkdownSource): MarkdownSource;
 export declare function unescapeText(text: string): string;
 
 /**
- * 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.
  *