@orkestrel/markdown 0.0.5 → 0.0.7

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

@@ -1,8 +1,1822 @@
-export type * from './types.js';
-export * from './constants.js';
-export * from './helpers.js';
-export * from './parsers.js';
-export * from './shapers.js';
-export * from './validators.js';
-export * from './Markdown.js';
-export * from './factories.js';
+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 { 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';
+
+/** 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;
+
+/** A blockquote - `>`-prefixed lines; `children` the block content parsed from the de-quoted lines (so quotes nest). */
+export declare interface BlockquoteNode {
+    readonly element: 'blockquote';
+    /** The block content of the quote (the `>`-stripped lines, re-parsed as blocks). */
+    readonly children: readonly BlockNode[];
+}
+
+/**
+ * Merge adjacent text nodes into one - the inline scanner emits a text node per
+ * unrecognized character, so coalescing keeps the AST clean and assertion-friendly.
+ *
+ * @param nodes - The inline nodes (possibly with adjacent text runs)
+ * @returns The nodes with consecutive text nodes concatenated
+ *
+ * @example
+ * ```ts
+ * coalesceText([{ element: 'text', value: 'a' }, { element: 'text', value: 'b' }])
+ * // [{ element: 'text', value: 'ab' }]
+ * ```
+ */
+export declare function coalesceText(nodes: readonly InlineNode[]): readonly InlineNode[];
+
+/**
+ * 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.
+ */
+export declare interface CodeBlockNode {
+    readonly element: 'codeBlock';
+    /** The info-string language tag (first word after the opening fence), if any. */
+    readonly lang?: string;
+    /** The verbatim code content (no inner markdown; HTML-escaped at render). */
+    readonly code: string;
+}
+
+/**
+ * The shape of a {@link CodeBlockNode} - a fenced code block. `lang` is
+ * optional (absent when the opening fence carries no info-string).
+ *
+ * @example
+ * ```ts
+ * import { createContract } from '@orkestrel/contract'
+ * import { codeBlockShape } from '@src/core'
+ *
+ * const codeBlock = createContract(codeBlockShape)
+ * codeBlock.is({ element: 'codeBlock', code: 'x' })                    // true
+ * codeBlock.is({ element: 'codeBlock', code: 'x', lang: 'ts' })        // true
+ * ```
+ */
+export declare const codeBlockShape: ObjectShape<{
+    element: LiteralShape<readonly ["codeBlock"]>;
+    lang: OptionalShape<StringShape>;
+    code: StringShape;
+}, false>;
+
+/**
+ * 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.
+ */
+export declare interface CodeSpanNode {
+    readonly element: 'codeSpan';
+    /** The verbatim code text (no inner markdown; HTML-escaped at render). */
+    readonly value: string;
+}
+
+/**
+ * The shape of a {@link CodeSpanNode} - an inline code span (`` `code` ``).
+ *
+ * @example
+ * ```ts
+ * import { createContract } from '@orkestrel/contract'
+ * import { codeSpanShape } from '@src/core'
+ *
+ * const codeSpan = createContract(codeSpanShape)
+ * codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
+ * ```
+ */
+export declare const codeSpanShape: ObjectShape<{
+    element: LiteralShape<readonly ["codeSpan"]>;
+    value: StringShape;
+}, false>;
+
+/**
+ * Collects a list starting at the first item, gathering sibling items at the
+ * same indent/ordering and recursing into each item's own block content.
+ *
+ * @param lines - The markdown lines to scan.
+ * @param start - The index of the first list item.
+ * @param depth - The current recursion depth (each item recurses at `depth + 1`).
+ * @returns The parsed list node and the index of the first line after it.
+ *
+ * @example
+ * ```ts
+ * collectList(['- item'], 0, 0) // { node: { element: 'list', ... }, next: 1 }
+ * ```
+ */
+export declare function collectList(lines: readonly string[], start: number, depth: number): {
+    readonly node: ListNode;
+    readonly next: number;
+};
+
+/**
+ * Collects a GFM table starting at a header row, parsing the header, the
+ * alignment row, and every contiguous body row that follows.
+ *
+ * @param lines - The markdown lines to scan.
+ * @param start - The index of the header row.
+ * @returns The parsed table node and the index of the first line after it.
+ *
+ * @example
+ * ```ts
+ * collectTable(['| a |', '| - |'], 0) // { node: { element: 'table', ... }, next: 2 }
+ * ```
+ */
+export declare function collectTable(lines: readonly string[], start: number): {
+    readonly node: TableNode;
+    readonly next: number;
+};
+
+/**
+ * The count of leading space / tab characters on `line` (a tab counts as one) - the
+ * indent that decides whether a list item's continuation belongs to the item.
+ *
+ * @param line - The line to measure
+ * @returns The number of leading space / tab characters
+ *
+ * @example
+ * ```ts
+ * countIndent('  text') // 2
+ * ```
+ */
+export declare function countIndent(line: string): number;
+
+/**
+ * Compile the {@link codeBlockShape} into a {@link ContractInterface} for
+ * {@link CodeBlockNode} - a guard, coercing parser, JSON Schema, and seeded
+ * generator from one shape declaration (AGENTS §14).
+ *
+ * @returns A `CodeBlockNode` contract bundling `schema` / `is` / `parse` / `generate`
+ *
+ * @example
+ * ```ts
+ * import { createCodeBlockContract } from '@src/core'
+ *
+ * const codeBlock = createCodeBlockContract()
+ * codeBlock.is({ element: 'codeBlock', code: 'x' }) // true
+ * ```
+ */
+export declare function createCodeBlockContract(): ContractInterface<CodeBlockNode>;
+
+/**
+ * Compile the {@link codeSpanShape} into a {@link ContractInterface} for
+ * {@link CodeSpanNode} - a guard, coercing parser, JSON Schema, and seeded
+ * generator from one shape declaration (AGENTS §14).
+ *
+ * @returns A `CodeSpanNode` contract bundling `schema` / `is` / `parse` / `generate`
+ *
+ * @example
+ * ```ts
+ * import { createCodeSpanContract } from '@src/core'
+ *
+ * const codeSpan = createCodeSpanContract()
+ * codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
+ * ```
+ */
+export declare function createCodeSpanContract(): ContractInterface<CodeSpanNode>;
+
+/**
+ * Compile the {@link lineBreakShape} into a {@link ContractInterface} for
+ * {@link LineBreakNode}.
+ *
+ * @returns A `LineBreakNode` contract bundling `schema` / `is` / `parse` / `generate`
+ *
+ * @example
+ * ```ts
+ * import { createLineBreakContract } from '@src/core'
+ *
+ * createLineBreakContract().is({ element: 'break' }) // true
+ * ```
+ */
+export declare function createLineBreakContract(): ContractInterface<LineBreakNode>;
+
+/**
+ * Create a stateful markdown handle from a markdown string or an already-parsed
+ * {@link MarkdownDocument} - a typed AST plus the query, rewrite, and fold operations
+ * {@link MarkdownInterface} exposes.
+ *
+ * @remarks
+ * Given a `string`, runs a block phase (headings / paragraphs / lists / GFM tables /
+ * fenced code / blockquotes / thematic breaks) then an inline phase (emphasis /
+ * inline code / links / images / hard breaks) to build a render-agnostic
+ * {@link MarkdownDocument}. Given a
+ * {@link MarkdownDocument}, adopts it AS-IS without re-validation - gate an untrusted
+ * value with `isMarkdownDocument` first. Pure + total parse (malformed markdown
+ * degrades to text, never throws) and zero-dependency - a hand-written scanner, no
+ * regex-only structural parse, linear-time (no ReDoS).
+ *
+ * @param input - A markdown string to parse, or an already-parsed {@link MarkdownDocument}
+ * @returns A working {@link MarkdownInterface}
+ *
+ * @example
+ * ```ts
+ * import { createMarkdown } from '@src/core'
+ *
+ * const markdown = createMarkdown('# Hi\n\nRead the [guide](./guide.md).')
+ * markdown.document.children[0] // { element: 'heading', ... }
+ * ```
+ */
+export declare function createMarkdown(input: string | MarkdownDocument): MarkdownInterface;
+
+/**
+ * Create an HTML-to-markdown projection with absent fields defaulted from
+ * {@link EMPTY_PROJECTION} and the block/inline exclusivity invariant enforced.
+ *
+ * @remarks
+ * A block-bearing projection cannot also expose inline content. Callers may provide
+ * both views, but `inlines` is flushed whenever `blocks` is non-empty.
+ *
+ * @param parts - The projection fields to provide
+ * @returns A complete invariant-preserving projection
+ *
+ * @example
+ * ```ts
+ * createProjection({
+ *   blocks: [{ element: 'thematicBreak' }],
+ *   inlines: [{ element: 'text', value: 'discarded' }],
+ * })
+ * // { blocks: [{ element: 'thematicBreak' }], inlines: [], text: '', cells: [], rows: [] }
+ * ```
+ */
+export declare function createProjection(parts?: Partial<MarkdownProjection>): MarkdownProjection;
+
+/**
+ * Compile the {@link textShape} into a {@link ContractInterface} for
+ * {@link TextNode} - a guard, coercing parser, JSON Schema, and seeded
+ * generator from one shape declaration (AGENTS §14).
+ *
+ * @returns A `TextNode` contract bundling `schema` / `is` / `parse` / `generate`
+ *
+ * @example
+ * ```ts
+ * import { createTextContract } from '@src/core'
+ *
+ * const text = createTextContract()
+ * text.is({ element: 'text', value: 'hi' }) // true
+ * ```
+ */
+export declare function createTextContract(): ContractInterface<TextNode>;
+
+/**
+ * Compile the {@link thematicBreakShape} into a {@link ContractInterface} for
+ * {@link ThematicBreakNode} - a guard, coercing parser, JSON Schema, and
+ * seeded generator from one shape declaration (AGENTS §14).
+ *
+ * @returns A `ThematicBreakNode` contract bundling `schema` / `is` / `parse` / `generate`
+ *
+ * @example
+ * ```ts
+ * import { createThematicBreakContract } from '@src/core'
+ *
+ * const thematicBreak = createThematicBreakContract()
+ * thematicBreak.is({ element: 'thematicBreak' }) // true
+ * ```
+ */
+export declare function createThematicBreakContract(): ContractInterface<ThematicBreakNode>;
+
+/**
+ * Derive the per-column {@link TableAlign} list from a GFM delimiter row - `:---`
+ * left, `---:` right, `:---:` center, and `---` as the explicit no-alignment
+ * marker represented by `null`.
+ *
+ * @param delimiter - The table's delimiter row
+ * @returns One alignment per column, in column order
+ *
+ * @example
+ * ```ts
+ * delimiterToAlignments('| :--- | ---: |') // ['left', 'right']
+ * ```
+ */
+export declare function delimiterToAlignments(delimiter: string): readonly (TableAlign | null)[];
+
+/**
+ * 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).
+ */
+export declare interface EmphasisNode {
+    readonly element: 'emphasis';
+    /** `true` for strong (`**` / `__`, → `<strong>`); `false` for ordinary emphasis (`*` / `_`, → `<em>`). */
+    readonly strong: boolean;
+    /** The emphasized inline content. */
+    readonly children: readonly InlineNode[];
+}
+
+/**
+ * The frozen empty HTML-to-markdown projection from which projection factories
+ * default every absent field.
+ *
+ * @example
+ * ```ts
+ * EMPTY_PROJECTION.blocks // []
+ * Object.isFrozen(EMPTY_PROJECTION) // true
+ * ```
+ */
+export declare const EMPTY_PROJECTION: MarkdownProjection;
+
+/**
+ * Extract a fenced-code opening line (```` ``` ```` or `~~~`, optionally with an info
+ * string) into its `{ marker, lang }`, or `undefined` when `line` is not a fence
+ * opener. `marker` is the exact fence run (the closer must match the same character +
+ * at least the same length); `lang` is the first word of the info string.
+ *
+ * @param line - The candidate line
+ * @returns The fence marker run and its language tag, or `undefined`
+ *
+ * @example
+ * ```ts
+ * extractFence('```ts') // { marker: '```', lang: 'ts' }
+ * ```
+ */
+export declare function extractFence(line: string): {
+    readonly marker: string;
+    readonly lang: string | undefined;
+} | undefined;
+
+/**
+ * Extract an ATX heading line (`#` … `######` followed by text) into its
+ * `{ level, text }`, or `undefined` when `line` is not a heading. A run of more than 6
+ * `#`s, or `#`s not followed by whitespace + text, is not a
+ * heading; an optional closing `###` run is stripped.
+ *
+ * @param line - The candidate line
+ * @returns The heading level (1–6) and its raw inline text, or `undefined`
+ *
+ * @example
+ * ```ts
+ * extractHeading('## Title') // { level: 2, text: 'Title' }
+ * ```
+ */
+export declare function extractHeading(line: string): {
+    readonly level: number;
+    readonly text: string;
+} | undefined;
+
+/**
+ * Extract a list-item line (`-` / `*` / `+` bullet, or `1.` / `1)` ordinal, followed by
+ * a space) into its {@link ListItemMatch}, or `undefined` when `line` is not a list
+ * item. `content` is the text after the marker; `marker` is the full marker-plus-space
+ * width (for measuring a continuation's indent).
+ *
+ * @param line - The candidate line
+ * @returns The list-item parts, or `undefined` when not a list item
+ *
+ * @example
+ * ```ts
+ * extractListItem('- item') // { ordered: false, start: 1, content: 'item', indent: 0, marker: 2 }
+ * ```
+ */
+export declare function extractListItem(line: string): ListItemMatch | undefined;
+
+/**
+ * Concatenate the `value` / `code` content of every descendant text / code-span /
+ * code-block node under `node`, including image alternative content, in walk order -
+ * the plain-text projection of an AST (search indexing, word counts, a text-only
+ * preview).
+ *
+ * @remarks
+ * Total: never throws. Descent stops at {@link MAX_DEPTH} (contributes `''` past the
+ * cap instead of recursing further).
+ *
+ * @param node - The AST node to flatten (a full document, or any sub-node)
+ * @returns The concatenated text content
+ *
+ * @example
+ * ```ts
+ * flattenText({ element: 'paragraph', children: [
+ *   { element: 'text', value: 'a ' },
+ *   { element: 'codeSpan', value: 'b' },
+ * ] })
+ * // 'a b'
+ * ```
+ */
+export declare function flattenText(node: MarkdownNode): string;
+
+/**
+ * Fold a {@link MarkdownNode} into a `T` via a total catamorphism - children are
+ * folded first (post-order), then the node's own {@link MarkdownHandler} is invoked
+ * with the already-folded children.
+ *
+ * @remarks
+ * **Table contract.** A {@link TableNode} has no single `children` array - its cells
+ * live in `header` (one inline-node list per column) and `rows` (a list of such
+ * rows). The `table` handler receives ONE folded `T` per inline node, flattened in
+ * walk order across ALL cells - every header cell's inline nodes (column order), then
+ * every body row's cells' inline nodes (row order, then column order) - and reads
+ * `node.header[c].length` / `node.rows[r][c].length` off the table node itself to
+ * recover cell boundaries within the flat list.
+ *
+ * Total: never throws. At `depth >= {@link MAX_DEPTH}` the node's handler is invoked
+ * with an empty children list instead of recursing further.
+ *
+ * @param node - The AST node to fold
+ * @param handlers - The total {@link MarkdownHandlers} table, one handler per element
+ * @param depth - The starting recursion depth (pass `0` at the entry point)
+ * @returns The folded `T`
+ *
+ * @example
+ * ```ts
+ * const countHandlers: MarkdownHandlers<number> = {
+ *   document: (_, children) => children.reduce((a, b) => a + b, 1),
+ *   // ...one handler per element, each summing its folded children
+ * }
+ * foldNode(document, countHandlers, 0) // total node count
+ * ```
+ */
+export declare function foldNode<T>(node: MarkdownNode, handlers: MarkdownHandlers<T>, depth: number): T;
+
+/**
+ * An ATX heading - `#` … `######`. `level` is 1–6 (the number of leading `#`),
+ * `children` the inline content of the heading text.
+ */
+export declare interface HeadingNode {
+    readonly element: 'heading';
+    /** The heading level, 1 (`#`) through 6 (`######`). */
+    readonly level: number;
+    /** The inline content of the heading text. */
+    readonly children: readonly InlineNode[];
+}
+
+/**
+ * Project 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
+ * depth capping, cycle safety, and bottom-up ordering are inherited rather than
+ * rebuilt. Total: hostile, cyclic, and pathologically deep input degrades instead of
+ * throwing.
+ *
+ * **Composed depth.** Both packages cap recursion at 64, and html's cap is reached
+ * first: a document nested past it projects to a chain bounded by THAT cap, with the
+ * content below it truncated before markdown ever sees it. Since the projected chain
+ * can be a level or two deeper than {@link MAX_DEPTH}, the serializer's own cap can
+ * then truncate again - so the anchor law below is a law within the depth budget, and
+ * beyond it only totality is promised.
+ *
+ * **Safety.** Every `href` and `src` is re-sanitized through
+ * `sanitizeURL(value, SAFE_URL_SCHEMES)` whether or not the AST was ever sanitized,
+ * because a hand-built one never was. A refused destination empties to `''` and the
+ * link or image is KEPT - `[text]()` - since a bad URL is no reason to lose the words
+ * around it. An `UNSAFE_ELEMENTS` subtree contributes nothing at all, text included, so
+ * a `script` body can never resurface as prose.
+ *
+ * **The anchor law.** HTML→markdown is lossy, so the fixpoint that matters is the
+ * PROJECTED AST, not the input bytes:
+ * `parseDocument(renderMarkdown(htmlToMarkdown(x)))` deep-equals `htmlToMarkdown(x)`.
+ * The projection therefore emits canonical markdown shapes rather than literal
+ * translations - whitespace collapsed, edges trimmed, a blank paragraph dropped, a hard
+ * break only where a line can end - because a shape markdown cannot write back is a
+ * shape this projection has no business producing.
+ *
+ * @param node - The HTML document or bare node to project
+ * @returns The projected markdown document
+ *
+ * @example
+ * ```ts
+ * import { parseDocument } from '@orkestrel/html'
+ *
+ * htmlToMarkdown(parseDocument('<h1>Title</h1>'))
+ * // { element: 'document', children: [{ element: 'heading', level: 1, children: [...] }] }
+ * ```
+ */
+export declare function htmlToMarkdown(node: HTMLNode): MarkdownDocument;
+
+/**
+ * An inline image - `![alt](src)`. `children` are the inline nodes of the
+ * alternative content and `src` is the image destination.
+ */
+export declare interface ImageNode {
+    readonly element: 'image';
+    /** The image destination. */
+    readonly src: string;
+    /** The inline alternative content. */
+    readonly children: readonly InlineNode[];
+}
+
+/** A node that can appear inside inline content (a heading / paragraph / cell / list item / link text). */
+export declare type InlineNode = TextNode | EmphasisNode | CodeSpanNode | LineBreakNode | LinkNode | ImageNode;
+
+/**
+ * Whether `line` is blank - empty, or containing only whitespace - the markdown
+ * definition of a blank line that block parsing uses to separate paragraphs, skip
+ * gaps, and end list continuations.
+ *
+ * @param line - The candidate line
+ * @returns `true` when the line is blank
+ *
+ * @example
+ * ```ts
+ * isBlankLine('   ') // true
+ * ```
+ */
+export declare function isBlankLine(line: string): boolean;
+
+/**
+ * Determine whether an arbitrary value is a valid {@link BlockNode} - a
+ * heading, paragraph, list, table, code block, blockquote, or thematic break,
+ * recursively validated.
+ *
+ * @remarks
+ * Total: never throws, even on cyclic or pathologically deep input - every
+ * combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
+ * throw-contained per the `@orkestrel/contract` guard contract (AGENTS §14).
+ * A list item's shape is inlined here (and in {@link isMarkdownNode}) rather
+ * than named separately - it is used at exactly these two sites.
+ *
+ * @param value - The value to test
+ * @returns `true` when `value` is a well-formed {@link BlockNode}
+ *
+ * @example
+ * ```ts
+ * import { isBlockNode } from '@orkestrel/markdown'
+ *
+ * isBlockNode({ element: 'thematicBreak' }) // true
+ * isBlockNode({ element: 'heading' })       // false - missing `level` / `children`
+ * ```
+ */
+export declare const isBlockNode: Guard<BlockNode>;
+
+/**
+ * Determine whether a node is a blockquote block.
+ *
+ * @example
+ * ```ts
+ * isBlockquoteNode({ element: 'blockquote', children: [] }) // true
+ * ```
+ */
+export declare function isBlockquoteNode(node: MarkdownNode): node is BlockquoteNode;
+
+/**
+ * Determine whether a node is a fenced code block.
+ *
+ * @example
+ * ```ts
+ * isCodeBlockNode({ element: 'codeBlock', code: 'x' }) // true
+ * ```
+ */
+export declare function isCodeBlockNode(node: MarkdownNode): node is CodeBlockNode;
+
+/**
+ * Determine whether a node is an inline code span.
+ *
+ * @remarks
+ * Narrows to {@link CodeSpanNode} - the node whose `element` discriminant is
+ * `'codeSpan'`.
+ *
+ * @example
+ * ```ts
+ * isCodeSpanNode({ element: 'codeSpan', value: 'x' }) // true
+ * ```
+ */
+export declare function isCodeSpanNode(node: MarkdownNode): node is CodeSpanNode;
+
+/**
+ * Determine whether a node is an emphasis run (`*em*` / `**strong**`).
+ *
+ * @example
+ * ```ts
+ * isEmphasisNode({ element: 'emphasis', strong: false, children: [] }) // true
+ * ```
+ */
+export declare function isEmphasisNode(node: MarkdownNode): node is EmphasisNode;
+
+/**
+ * Whether `character` is escapable by a leading backslash - the ASCII punctuation
+ * markdown gives meaning to (so `\*` becomes `*` but `\.` stays `\.`).
+ *
+ * @param character - The single character after a backslash
+ * @returns `true` when a backslash before it is an escape
+ *
+ * @example
+ * ```ts
+ * isEscapable('*') // true
+ * isEscapable('a') // false
+ * ```
+ */
+export declare function isEscapable(character: string): boolean;
+
+/**
+ * Whether `line` closes a fence opened by `marker` - the same fence character, a run
+ * at least as long, and nothing else but surrounding whitespace.
+ *
+ * @param line - The candidate closing line
+ * @param marker - The opening fence's marker run (from {@link extractFence})
+ * @returns `true` when `line` closes the fence
+ *
+ * @example
+ * ```ts
+ * isFenceClose('```', '```') // true
+ * ```
+ */
+export declare function isFenceClose(line: string, marker: string): boolean;
+
+/**
+ * Whether `character` is a regex-`\s`-equivalent whitespace character - the
+ * character class {@link isFenceClose}'s scan treats as surrounding padding.
+ *
+ * @param character - The single character to test, or `undefined` past the end of a line
+ * @returns `true` when it is whitespace
+ *
+ * @example
+ * ```ts
+ * isFenceWhitespace(' ')         // true
+ * isFenceWhitespace(undefined)   // false
+ * ```
+ */
+export declare function isFenceWhitespace(character: string | undefined): boolean;
+
+/** Determine whether a node is a heading block. */
+export declare function isHeadingNode(node: MarkdownNode): node is HeadingNode;
+
+/**
+ * Determine whether a node is an image.
+ *
+ * @example
+ * ```ts
+ * isImageNode({ element: 'image', src: 'x.png', children: [] }) // true
+ * ```
+ */
+export declare function isImageNode(node: MarkdownNode): node is ImageNode;
+
+/**
+ * Determine whether an arbitrary value is a valid {@link InlineNode} - a text
+ * run, emphasis, code span, hard break, link, or image, recursively validated.
+ *
+ * @remarks
+ * Total: never throws, even on cyclic or pathologically deep input - every
+ * combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
+ * throw-contained per the `@orkestrel/contract` guard contract (AGENTS §14).
+ *
+ * @param value - The value to test
+ * @returns `true` when `value` is a well-formed {@link InlineNode}
+ *
+ * @example
+ * ```ts
+ * import { isInlineNode } from '@orkestrel/markdown'
+ *
+ * isInlineNode({ element: 'text', value: 'hi' }) // true
+ * isInlineNode({ element: 'text' })               // false - missing `value`
+ * ```
+ */
+export declare const isInlineNode: Guard<InlineNode>;
+
+/**
+ * Determine whether a node is a GFM hard line break.
+ *
+ * @example
+ * ```ts
+ * isLineBreakNode({ element: 'break' }) // true
+ * ```
+ */
+export declare function isLineBreakNode(node: MarkdownNode): node is LineBreakNode;
+
+/** Determine whether a node is a link. */
+export declare function isLinkNode(node: MarkdownNode): node is LinkNode;
+
+/**
+ * Determine whether a node is a list block.
+ *
+ * @example
+ * ```ts
+ * isListNode({ element: 'list', ordered: false, start: 1, items: [] }) // true
+ * ```
+ */
+export declare function isListNode(node: MarkdownNode): node is ListNode;
+
+/**
+ * Determine whether an arbitrary value is a valid {@link MarkdownDocument} -
+ * the parsed-AST root {@link parseDocument} returns, recursively
+ * validated.
+ *
+ * @remarks
+ * Total: never throws, even on cyclic or pathologically deep input - every
+ * combinator involved (`recordOf`, `arrayOf`) is throw-contained per the
+ * `@orkestrel/contract` guard contract (AGENTS §14).
+ *
+ * @param value - The value to test
+ * @returns `true` when `value` is a well-formed {@link MarkdownDocument}
+ *
+ * @example
+ * ```ts
+ * import { isMarkdownDocument } from '@orkestrel/markdown'
+ *
+ * isMarkdownDocument({ element: 'document', children: [] }) // true
+ * isMarkdownDocument({ element: 'document' })                 // false - missing `children`
+ * ```
+ */
+export declare const isMarkdownDocument: Guard<MarkdownDocument>;
+
+/**
+ * Determine whether an arbitrary value is a valid {@link MarkdownNode} - the
+ * {@link MarkdownDocument} root, a {@link BlockNode}, a {@link ListItemNode}, or
+ * an {@link InlineNode}, recursively validated.
+ *
+ * @remarks
+ * Total: never throws, even on cyclic or pathologically deep input - every
+ * combinator involved (`unionOf`, `recordOf`, `arrayOf`, `lazyOf`) is
+ * throw-contained per the `@orkestrel/contract` guard contract (AGENTS §14).
+ * A list item's shape is inlined here (and in {@link isBlockNode}) rather than
+ * named separately - it is used at exactly these two sites.
+ *
+ * @param value - The value to test
+ * @returns `true` when `value` is a well-formed {@link MarkdownNode}
+ *
+ * @example
+ * ```ts
+ * import { isMarkdownNode } from '@orkestrel/markdown'
+ *
+ * isMarkdownNode({ element: 'text', value: 'hi' }) // true
+ * isMarkdownNode({ element: 'bogus' })              // false
+ * ```
+ */
+export declare const isMarkdownNode: Guard<MarkdownNode>;
+
+/**
+ * Determine whether a node is a paragraph block.
+ *
+ * @example
+ * ```ts
+ * isParagraphNode({ element: 'paragraph', children: [] }) // true
+ * ```
+ */
+export declare function isParagraphNode(node: MarkdownNode): node is ParagraphNode;
+
+/**
+ * Whether `line` is a blockquote line (`>` optionally indented up to three spaces) -
+ * its content is de-quoted by {@link stripQuote}.
+ *
+ * @param line - The candidate line
+ * @returns `true` when the line begins a blockquote
+ *
+ * @example
+ * ```ts
+ * isQuote('> quoted') // true
+ * ```
+ */
+export declare function isQuote(line: string): boolean;
+
+/** Determine whether a node is a GFM table block. */
+export declare function isTableNode(node: MarkdownNode): node is TableNode;
+
+/**
+ * Whether the pair (`header`, `delimiter`) opens a GFM table - `delimiter` is a row of
+ * `|`-separated cells each matching `:?-+:?`, the GFM rule that a table requires a
+ * header row IMMEDIATELY followed by a delimiter row.
+ *
+ * @param header - The candidate header line
+ * @param delimiter - The line after it (the candidate delimiter)
+ * @returns `true` when the two lines open a table
+ *
+ * @example
+ * ```ts
+ * isTableStart('| a |', '| - |') // true
+ * ```
+ */
+export declare function isTableStart(header: string, delimiter: string | undefined): boolean;
+
+/**
+ * Determine whether a node is a plain text run.
+ *
+ * @example
+ * ```ts
+ * isTextNode({ element: 'text', value: 'hi' }) // true
+ * ```
+ */
+export declare function isTextNode(node: MarkdownNode): node is TextNode;
+
+/**
+ * Whether `line` is a thematic break (horizontal rule) - three or more of the SAME
+ * marker `-`, `*`, or `_` (optionally space-separated) and nothing else (`---`,
+ * `***`, `___`, `- - -`).
+ *
+ * @param line - The candidate line
+ * @returns `true` when the line is a thematic break
+ *
+ * @example
+ * ```ts
+ * isThematicBreak('---') // true
+ * ```
+ */
+export declare function isThematicBreak(line: string): boolean;
+
+/**
+ * Determine whether a node is a thematic break (horizontal rule) block.
+ *
+ * @example
+ * ```ts
+ * isThematicBreakNode({ element: 'thematicBreak' }) // true
+ * ```
+ */
+export declare function isThematicBreakNode(node: MarkdownNode): node is ThematicBreakNode;
+
+/**
+ * Whether `character` is an inline whitespace character (space / tab / newline) - the
+ * emphasis flanking rule's space test.
+ *
+ * @param character - The character to test
+ * @returns `true` when it is inline whitespace
+ *
+ * @example
+ * ```ts
+ * isWhitespace(' ') // true
+ * isWhitespace('a') // false
+ * ```
+ */
+export declare function isWhitespace(character: string): boolean;
+
+/** A GFM hard line break - two or more trailing spaces before a newline. */
+export declare interface LineBreakNode {
+    readonly element: 'break';
+}
+
+/**
+ * The shape of a {@link LineBreakNode} - a GFM hard line-break leaf.
+ *
+ * @example
+ * ```ts
+ * import { createContract } from '@orkestrel/contract'
+ * import { lineBreakShape } from '@src/core'
+ *
+ * const lineBreak = createContract(lineBreakShape)
+ * lineBreak.is({ element: 'break' }) // true
+ * ```
+ */
+export declare const lineBreakShape: ObjectShape<{
+    element: LiteralShape<readonly ["break"]>;
+}, false>;
+
+/**
+ * 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 `''`.
+ */
+export declare interface LinkNode {
+    readonly element: 'link';
+    /** The link destination (sanitized + attribute-escaped at render). */
+    readonly href: string;
+    /** The inline content of the link text. */
+    readonly children: readonly InlineNode[];
+}
+
+/**
+ * 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 {
+    /** `true` for an ordered (`1.` / `1)`) item, `false` for a bullet (`-` / `*` / `+`). */
+    readonly ordered: boolean;
+    /** The ordinal of an ordered item (its number); `1` for a bullet. */
+    readonly start: number;
+    /** The item's text after the marker. */
+    readonly content: string;
+    /** The leading-space indent of the marker. */
+    readonly indent: number;
+    /** The full marker width (indent + bullet/ordinal + the following space) - the continuation indent. */
+    readonly marker: number;
+}
+
+/**
+ * The shape of {@link ListItemMatch} - the parsed parts of a single list-item
+ * line the block phase's list detector returns. Fully non-recursive (no
+ * nested node fields), so every field shapes directly.
+ *
+ * @example
+ * ```ts
+ * import { createContract } from '@orkestrel/contract'
+ * import { listItemMatchShape } from '@src/core'
+ *
+ * const listItemParts = createContract(listItemMatchShape)
+ * listItemParts.is({ ordered: false, start: 1, content: 'hi', indent: 0, marker: 2 }) // true
+ * ```
+ */
+export declare const listItemMatchShape: ObjectShape<{
+    ordered: BooleanShape;
+    start: NumberShape;
+    content: StringShape;
+    indent: NumberShape;
+    marker: NumberShape;
+}, false>;
+
+/** 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';
+    /** The block content of the list item (its text as a paragraph, plus any nested list). */
+    readonly children: readonly BlockNode[];
+}
+
+/**
+ * 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`.
+ */
+export declare interface ListNode {
+    readonly element: 'list';
+    /** `true` for an ordered (numbered) list (→ `<ol>`); `false` for a bulleted list (→ `<ul>`). */
+    readonly ordered: boolean;
+    /** The starting ordinal of an ordered list (the first item's number); `1` for a bulleted list. */
+    readonly start: number;
+    /** The list's items, in order. */
+    readonly items: readonly ListItemNode[];
+}
+
+/**
+ * A stateful, parsed markdown document - wraps a typed {@link MarkdownDocument} AST
+ * with the query (`find` / `filter` / `reduce` / iteration), rewrite (`map`), fold, and
+ * streaming operations {@link MarkdownInterface} declares.
+ *
+ * @remarks
+ * - **Construction.** Given a `string`, the constructor runs {@link parseDocument} (the
+ *   block phase then the inline phase) to build the AST. Given a {@link MarkdownDocument},
+ *   the document is adopted AS-IS and is NOT re-validated - a caller adopting an
+ *   untrusted value should gate it with `isMarkdownDocument` first.
+ * - **Immutable.** {@link map} never mutates the stored AST - it returns a NEW `Markdown`
+ *   instance; the document root invariant (`element: 'document'`) always holds.
+ * - **Traversal order.** {@link walk} and the `find` / `filter` / `reduce` queries built
+ *   on it walk the AST depth-first, pre-order, root-inclusive (via {@link walkNodes});
+ *   `stream` is shallow - only the document's direct block children.
+ *
+ * @example
+ * ```ts
+ * import { Markdown, isHeadingNode, renderMarkdown } from '@src/core'
+ *
+ * const markdown = new Markdown('# Title\n\nA **bold** [link](https://x.dev).')
+ * const heading = markdown.find(isHeadingNode) // the HeadingNode, or undefined
+ * const shouted = markdown.map((node) =>
+ *   node.element === 'text' ? { element: 'text', value: node.value.toUpperCase() } : node,
+ * )
+ * renderMarkdown(shouted.document) // '# TITLE\n\nA **BOLD** [LINK](https://x.dev).'
+ * ```
+ */
+export declare class Markdown implements MarkdownInterface {
+    #private;
+    constructor(input: string | MarkdownDocument);
+    /** The stored {@link MarkdownDocument} AST root. */
+    get document(): MarkdownDocument;
+    /**
+     * THE deep traversal - a lazy, depth-first, pre-order, root-inclusive generator
+     * over every {@link MarkdownNode} in the document. `find` / `filter` / `reduce`
+     * all iterate this single traversal.
+     *
+     * @example
+     * ```ts
+     * for (const node of markdown.walk()) {
+     *   // every node, depth-first, pre-order, root-inclusive
+     * }
+     *
+     * // also consumable by for-await - JS accepts a sync iterable in for-await
+     * for await (const node of markdown.walk()) {
+     *   // same sequence, no separate async iterator needed
+     * }
+     * ```
+     */
+    walk(): Generator<MarkdownNode>;
+    find<T extends MarkdownNode>(guard: (node: MarkdownNode) => node is T): T | undefined;
+    find(predicate: (node: MarkdownNode) => boolean): MarkdownNode | undefined;
+    filter<T extends MarkdownNode>(guard: (node: MarkdownNode) => node is T): readonly T[];
+    filter(predicate: (node: MarkdownNode) => boolean): readonly MarkdownNode[];
+    /** Rewrites the AST bottom-up (copy-on-write) and returns a new {@link Markdown}. */
+    map(rewrite: MarkdownRewriteHandler): MarkdownInterface;
+    /** Folds the AST depth-first, pre-order into an accumulator. */
+    reduce<T>(callback: (accumulator: T, node: MarkdownNode) => T, initial: T): T;
+    /** Runs a total catamorphism over the document using a {@link MarkdownHandlers} table. */
+    fold<T>(handlers: MarkdownHandlers<T>): T;
+    /**
+     * A web-standard {@link ReadableStream} over the document's top-level block nodes
+     * (shallow, source order) - a fresh, pull-based source per call: one block is
+     * enqueued per `pull`, so a slow reader's backpressure is respected. Cancellable,
+     * async-iterable wherever the platform supports it (Node, Deno), and pipeable
+     * through any {@link TransformStream} / {@link WritableStream}.
+     *
+     * @example
+     * ```ts
+     * // universal - works in every ReadableStream-supporting environment
+     * const reader = markdown.stream().getReader()
+     * for (let result = await reader.read(); !result.done; result = await reader.read()) {
+     *   console.log(result.value) // one BlockNode
+     * }
+     *
+     * // Node / Deno / Firefox support async iteration of ReadableStream natively;
+     * // other environments should use the reader loop above instead.
+     * for await (const block of markdown.stream()) {
+     *   console.log(block)
+     * }
+     * ```
+     */
+    stream(): ReadableStream<BlockNode>;
+}
+
+/** One projected table cell - the inline content and alignment of a `th` / `td`. */
+export declare interface MarkdownCell {
+    /** The alignment the cell's `align` attribute declared; `undefined` when it declared none. */
+    readonly align: TableAlign | undefined;
+    /** The cell's inline content - a table cell is inline-only, so block content flattens to text. */
+    readonly inlines: readonly InlineNode[];
+}
+
+/**
+ * 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 {
+    readonly element: 'document';
+    /** The document's top-level block nodes, in source order. */
+    readonly children: readonly BlockNode[];
+}
+
+/**
+ * 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 MarkdownHandlers} catamorphism table.
+ */
+export declare type MarkdownHandler<TNode, T> = (node: TNode, children: readonly T[]) => T;
+
+/**
+ * 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.
+ */
+export declare interface MarkdownHandlers<T> {
+    /** Folds a {@link MarkdownDocument} root from its already-folded block children. */
+    readonly document: MarkdownHandler<MarkdownDocument, T>;
+    /** Folds a {@link HeadingNode} from its already-folded inline children. */
+    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). */
+    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). */
+    readonly codeBlock: MarkdownHandler<CodeBlockNode, T>;
+    /** Folds a {@link ListNode} from its already-folded item children. */
+    readonly list: MarkdownHandler<ListNode, T>;
+    /** Folds a {@link ListItemNode} from its already-folded block children. */
+    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
+     * 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). */
+    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). */
+    readonly codeSpan: MarkdownHandler<CodeSpanNode, T>;
+    /** 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>;
+    /** Folds an {@link ImageNode} from its already-folded alternative content. */
+    readonly image: MarkdownHandler<ImageNode, T>;
+}
+
+/**
+ * A stateful, parsed markdown document: the typed {@link MarkdownDocument} AST plus
+ * 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
+ *   (`element: 'document'`) always holds.
+ * - **Traversal order.** `walk` / `find` / `filter` / `reduce` walk the AST
+ *   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
+ *   `pull`, so a slow consumer's backpressure is respected and no work happens ahead
+ *   of demand. Cancellable via the returned stream's own `cancel()`, async-iterable
+ *   wherever the platform supports it (Node, Deno, and browsers that ship the
+ *   proposal), and pipeable through any {@link TransformStream} / {@link WritableStream}.
+ * - **The seven-method surface.** `document` (the AST root), `walk` (the deep
+ *   traversal), `find` / `filter` / `reduce` (queries built on `walk`), `map` (the
+ *   bottom-up rewrite), `fold` (the total catamorphism), and `stream` (the shallow,
+ *   backpressured top-level source).
+ */
+export declare interface MarkdownInterface {
+    /** The stored {@link MarkdownDocument} AST root. */
+    readonly document: MarkdownDocument;
+    /**
+     * 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
+     * iterable in a `for await`), so async pipelines need no separate iterator.
+     * Contrast with {@link stream}: `walk` is deep, every-node, and sync; `stream`
+     * 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. */
+    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. */
+    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[];
+    /** 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. */
+    reduce<T>(callback: (accumulator: T, node: MarkdownNode) => T, initial: T): T;
+    /** Runs a total catamorphism over the document using a {@link MarkdownHandlers} table. */
+    fold<T>(handlers: MarkdownHandlers<T>): T;
+    /**
+     * A web-standard {@link ReadableStream} over the document's top-level block nodes
+     * (shallow, source order) - a lazy, pull-based, backpressure-respecting source. A
+     * fresh, independently-replayable stream every call; never mutates the document.
+     */
+    stream(): ReadableStream<BlockNode>;
+}
+
+/**
+ * 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;
+
+/**
+ * What one HTML node projects to on the way to markdown - the fold value
+ * `htmlToMarkdown` carries up the AST.
+ *
+ * @remarks
+ * A node projects to several things at once because markdown decides late what a
+ * given HTML subtree becomes: a `td`'s content is inline in a table and a paragraph
+ * outside one, and a `code` body is a code span in prose and a verbatim code block
+ * 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
+ *   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
+ *   `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
+ *   row up to its `table`, passing through the `thead` / `tbody` wrappers between
+ *   them untouched; whatever never reaches a table degrades to paragraphs.
+ */
+export declare interface MarkdownProjection {
+    /** The node's block content, with any surrounding inline runs already wrapped into paragraphs. */
+    readonly blocks: readonly BlockNode[];
+    /** The node's inline content; empty whenever `blocks` is not. */
+    readonly inlines: readonly InlineNode[];
+    /** The raw subtree text, whitespace uncollapsed and escapes unresolved. */
+    readonly text: string;
+    /** The cells this node contributes to an enclosing row. */
+    readonly cells: readonly MarkdownCell[];
+    /** The rows this node contributes to an enclosing table - each its cells, in column order. */
+    readonly rows: readonly (readonly MarkdownCell[])[];
+}
+
+/**
+ * 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;
+
+/**
+ * Project a {@link MarkdownNode} into an unsanitized {@link HTMLDocument}.
+ *
+ * @remarks
+ * The projection is pure and iterative. Text and attribute values remain literal for
+ * `@orkestrel/html` to encode, and URL values remain unsanitized so callers can choose
+ * their own HTML policy. Projected HTML element depth, including generated `pre > code`
+ * and table scaffolding, never exceeds {@link MAX_DEPTH}. At the cap a node carrying a
+ * string `value` degrades to a text node and a structural node contributes nothing.
+ *
+ * @param node - The markdown document or bare node to project
+ * @returns An unsanitized HTML document wrapping the projected node or nodes
+ *
+ * @example
+ * ```ts
+ * markdownToHTML({ element: 'text', value: 'a & b' })
+ * // { category: 'document', children: [{ category: 'text', value: 'a & b' }] }
+ * ```
+ */
+export declare function markdownToHTML(node: MarkdownNode): HTMLDocument;
+
+/**
+ * The maximum recursion depth the parse pipeline (`parseDocument` and its
+ * `parsers.ts` helpers) and the `helpers.ts` traversal / projection functions
+ * (`markdownToHTML`, `renderHTML`, `renderMarkdown`, `walkNodes`, `foldNode`,
+ * `rewriteDocument`) honor before degrading. It bounds blockquote nesting, inline
+ * 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`.
+ */
+export declare const MAX_DEPTH = 64;
+
+/**
+ * Combine the projections of one node's children into the projection of that node -
+ * the single place inline runs become paragraphs, so no ancestor has to decide it
+ * twice.
+ *
+ * @remarks
+ * A child is either inline or block, never both, so merging preserves source order
+ * exactly: an inline run is held pending until a block arrives, then written out as a
+ * paragraph BEFORE it. That is what keeps `<div>lead<p>a</p></div>` two paragraphs in
+ * the order they were written rather than two lists that lost their interleaving. A
+ * pending run carrying no text is dropped rather than becoming a blank paragraph.
+ * Direct cells become one row before a later row, while cells/rows before a block
+ * materialize as paragraphs at that exact source position.
+ *
+ * @param children - The children's projections, in source order
+ * @returns Their combined projection
+ *
+ * @example
+ * ```ts
+ * mergeProjections([
+ *   createProjection({ inlines: [{ element: 'text', value: 'a' }], text: 'a' }),
+ *   createProjection({ blocks: [{ element: 'thematicBreak' }] }),
+ * ]).blocks
+ * // [{ element: 'paragraph', children: [...] }, { element: 'thematicBreak' }]
+ * ```
+ */
+export declare function mergeProjections(children: readonly MarkdownProjection[]): MarkdownProjection;
+
+/**
+ * Reduce an inline run to the shape markdown can actually write back: adjacent text
+ * coalesced, empty text dropped, and every hard break either kept as a real line
+ * ending or spent as a space.
+ *
+ * @remarks
+ * A hard break is `  \n` in markdown source, so it survives a re-parse only BETWEEN
+ * two lines of content and only with no whitespace touching it: a leading or trailing
+ * break has no line to end, a run of breaks reads as one blank line (which would end
+ * the paragraph), and a space beside one is eaten by the parser's line trimming. Where
+ * a break cannot be written at all - a heading and a table cell are one line each - it
+ * becomes the space it stood for.
+ *
+ * @param nodes - The inline run to normalize
+ * @param breaks - Whether the target context can carry a hard break at all; `false` for
+ *   a heading or a table cell, where every break becomes a space
+ * @returns The normalized run
+ *
+ * @example
+ * ```ts
+ * normalizeInlines([{ element: 'break' }, { element: 'text', value: 'a' }], true)
+ * // [{ element: 'text', value: 'a' }] - a leading break has no line to end
+ * ```
+ */
+export declare function normalizeInlines(nodes: readonly InlineNode[], breaks: boolean): readonly InlineNode[];
+
+/** A paragraph - a run of non-blank lines that is not another block; `children` its inline content. */
+export declare interface ParagraphNode {
+    readonly element: 'paragraph';
+    /** The inline content of the paragraph. */
+    readonly children: readonly InlineNode[];
+}
+
+/**
+ * Parses a run of markdown lines into a block AST, recursing into nested
+ * blockquotes, list items, and depth-capped degrade paragraphs.
+ *
+ * @param lines - The markdown lines to parse.
+ * @param depth - The current recursion depth (blockquotes/lists increment it).
+ * @returns The parsed block nodes.
+ *
+ * @example
+ * ```ts
+ * parseBlocks(['# Hi'], 0) // [{ element: 'heading', level: 1, children: [...] }]
+ * ```
+ */
+export declare function parseBlocks(lines: readonly string[], depth: number): readonly BlockNode[];
+
+/**
+ * Parses a markdown string into a typed {@link MarkdownDocument} AST via the
+ * block phase.
+ *
+ * @param markdown - The markdown source to parse.
+ * @returns The parsed document.
+ */
+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.
+ *
+ * @param text - The inline markdown text to parse.
+ * @returns The parsed inline nodes.
+ */
+export declare function parseInline(text: string): readonly InlineNode[];
+
+/**
+ * Project one HTML leaf - a text node, a comment, or a doctype - to its
+ * {@link MarkdownProjection}.
+ *
+ * @remarks
+ * Text collapses each whitespace run to one space, which is both what HTML means by it
+ * and all markdown can write back; the raw value travels on in `text` for the two
+ * places that need it verbatim, a code span and a `pre > code` body. A comment and a
+ * doctype carry nothing into markdown and project to nothing.
+ *
+ * @param leaf - The leaf node to project
+ * @returns Its projection
+ *
+ * @example
+ * ```ts
+ * projectHTMLLeaf({ category: 'text', value: 'a\n  b' }).inlines
+ * // [{ element: 'text', value: 'a b' }]
+ * ```
+ */
+export declare function projectHTMLLeaf(leaf: CommentNode | DoctypeNode | TextNode_2): MarkdownProjection;
+
+/**
+ * Project one HTML container - the document root or an element - from its children's
+ * already-computed projections. THE element mapping, and the only place that decides
+ * what an HTML tag becomes in markdown.
+ *
+ * @remarks
+ * `h1`-`h6` become headings; `p` a paragraph; `strong` / `b` and `em` / `i` emphasis;
+ * `code` a code span; `pre` a code block, verbatim through a first `code` element child
+ * (its `language-` class naming the language) and through `renderText` otherwise; `a`
+ * and `img` a link and an image, each destination re-sanitized; `br` and `hr` a hard
+ * break and a thematic break; `blockquote` and `li` their block content, with bare
+ * inline runs wrapped in paragraphs; `ul` / `ol` a list, ordered from the tag and
+ * numbered from `start`; `th` / `td`, `tr`, and `table` a GFM table whose column
+ * alignment comes from each header-position cell's `align` attribute. Every
+ * `UNSAFE_ELEMENTS` subtree contributes nothing at all, text included. Every OTHER
+ * element unwraps to its children, so wrapper soup melts while its content keeps its
+ * shape - `<div><p>a</p><p>b</p></div>` stays two paragraphs.
+ *
+ * Three mappings read their own node rather than only their children's projections,
+ * because HTML puts the fact in a position rather than in a value: a `pre` takes its
+ * body from its `code` child's raw text, and a list takes one item per `li` child - so
+ * an empty `<li>` is still an item, while the whitespace between two of them is not.
+ * A `tr` accepts only its own direct cells, and a table derives the first `th`-bearing
+ * row from its own source structure.
+ *
+ * @param node - The document root or element to project
+ * @param children - Its children's projections, in source order
+ * @returns Its projection
+ *
+ * @example
+ * ```ts
+ * projectHTMLNode({ category: 'element', name: 'hr', attributes: [], children: [] }, []).blocks
+ * // [{ element: 'thematicBreak' }]
+ * ```
+ */
+export declare function projectHTMLNode(node: ElementNode | HTMLDocument, children: readonly MarkdownProjection[]): MarkdownProjection;
+
+/**
+ * Read a projection as BLOCK content - the view a document, a blockquote, and a list
+ * item each need.
+ *
+ * @remarks
+ * A bare inline run becomes one paragraph, and a run carrying no text becomes nothing
+ * at all, because a blank paragraph is unwritable in markdown. A cell or a row that
+ * never reached a table is unwrapped here rather than dropped: a stray `<td>` is still
+ * someone's content.
+ *
+ * @param projection - The projection to read
+ * @returns Its block content
+ *
+ * @example
+ * ```ts
+ * projectionToBlocks(createProjection({ inlines: [{ element: 'text', value: 'a' }], text: 'a' }))
+ * // [{ element: 'paragraph', children: [{ element: 'text', value: 'a' }] }]
+ * ```
+ */
+export declare function projectionToBlocks(projection: MarkdownProjection): readonly BlockNode[];
+
+/**
+ * Read a projection as INLINE content - the view a link, an emphasis, and a table cell
+ * each need.
+ *
+ * @remarks
+ * Inline content passes through as itself. Block content cannot: markdown has no way to
+ * put a paragraph inside a table cell, so it flattens to one text node of its own words,
+ * joined and whitespace-collapsed. Content that carries no text flattens to nothing
+ * rather than to an empty text node, which is a shape the parser never produces.
+ *
+ * @param projection - The projection to read
+ * @returns Its inline content
+ *
+ * @example
+ * ```ts
+ * projectionToInlines(createProjection({ inlines: [{ element: 'break' }] }))
+ * // [{ element: 'break' }]
+ * ```
+ */
+export declare function projectionToInlines(projection: MarkdownProjection): readonly InlineNode[];
+
+/**
+ * Render a {@link MarkdownNode} to sanitized canonical HTML.
+ *
+ * @remarks
+ * Markdown widens `@orkestrel/html`'s attribute floor by exactly `src`, because image
+ * syntax is meaningless without its source. `src` is still a URL attribute, so the
+ * floor refuses `javascript:`, `data:`, `vbscript:`, and `file:` values. A stricter
+ * consumer can compose {@link markdownToHTML} with `@orkestrel/html`'s `HTML` class
+ * directly.
+ *
+ * @param node - The markdown document or bare node to render
+ * @returns Sanitized canonical HTML
+ *
+ * @example
+ * ```ts
+ * renderHTML({ element: 'paragraph', children: [{ element: 'text', value: 'a & b' }] })
+ * // '<p>a &amp; b</p>'
+ * ```
+ */
+export declare function renderHTML(node: MarkdownNode): string;
+
+/**
+ * Render a {@link MarkdownNode} to its CANONICAL markdown source - the inverse
+ * projection of `renderHTML`, and the serializer a `parse(renderMarkdown(doc))`
+ * round-trip is built on. Canonical forms: `*` / `**` emphasis at even emphasis
+ * nesting depths and `_` / `__` at odd depths, `- ` bullets, `N. ` sequential
+ * ordinals (from the list's `start`), `---` thematic breaks, fenced code blocks
+ * (backtick run widened past any 3+ backtick run inside the body), ATX headings,
+ * `> `-prefixed blockquote lines, GFM tables (1-space-padded cells, `\|`-escaped
+ * pipes, an alignment delimiter row), `[text](href)` links, `![alt](src)` images,
+ * and two-space hard breaks. A `text` node's literal content is backslash-escaped
+ * wherever it would otherwise re-parse as markup (AGENTS §14 parse↔render
+ * soundness).
+ *
+ * @remarks
+ * Total: never throws. At {@link MAX_DEPTH} a value-bearing node degrades to its
+ * escaped `value`; any other node degrades to `''`. Blocks are joined by exactly one
+ * blank line; a document with zero blocks renders `''`.
+ *
+ * @param node - The AST node to render (a full document, or any sub-node)
+ * @returns The canonical markdown source
+ *
+ * @example
+ * ```ts
+ * renderMarkdown({ element: 'document', children: [
+ *   { element: 'heading', level: 2, children: [{ element: 'text', value: 'Hi' }] },
+ * ] })
+ * // '## Hi'
+ * ```
+ */
+export declare function renderMarkdown(node: MarkdownNode): string;
+
+/**
+ * Rewrite a {@link MarkdownDocument} bottom-up (copy-on-write) - each node's children
+ * are rewritten first (post-order), then `rewrite` is applied to the node itself; the
+ * document ROOT is never passed to `rewrite` (the `element: 'document'` invariant
+ * always holds). A table's inline cells and a list's items ARE rewritten.
+ *
+ * @remarks
+ * Never mutates `document` - every level is rebuilt into a fresh object/array, even
+ * when `rewrite` returns its input unchanged. When `rewrite` returns a node whose
+ * `element` does not fit the slot it was called for (a block slot handed a
+ * non-{@link BlockNode}, an inline slot handed a non-{@link InlineNode}, a list-item
+ * slot handed a non-`listItem`), the ill-fitting result is discarded and the
+ * freshly-rebuilt (unrewritten-at-this-level) node is kept instead - `rewriteDocument`
+ * stays total and never produces a structurally invalid document.
+ *
+ * Descent is capped at {@link MAX_DEPTH}, the same cap {@link walkNodes} and
+ * {@link foldNode} observe: at `depth >= MAX_DEPTH` the subtree is passed through
+ * UNCHANGED (by reference, not rebuilt, and `rewrite` is not invoked on it) instead of
+ * recursing further, so a pathologically deep adopted document cannot exhaust the
+ * call stack. {@link MarkdownInterface.map} inherits this cap since it delegates here.
+ *
+ * @param document - The document AST to rewrite
+ * @param rewrite - The bottom-up {@link MarkdownRewriteHandler}
+ * @returns A new, rewritten {@link MarkdownDocument}
+ *
+ * @example
+ * ```ts
+ * rewriteDocument(document, (node) =>
+ *   node.element === 'text' ? { element: 'text', value: node.value.toUpperCase() } : node,
+ * )
+ * ```
+ */
+export declare function rewriteDocument(document: MarkdownDocument, rewrite: MarkdownRewriteHandler): MarkdownDocument;
+
+/**
+ * Scan an inline code span at `start` (a `` ` ``-run … a matching `` ` ``-run of the
+ * SAME length, the CommonMark rule that lets a span contain backticks). Returns the
+ * span's literal text + end index, or `undefined` when no matching closer exists (it
+ * then degrades to literal backticks).
+ *
+ * @param source - The inline source text
+ * @param start - The index of the opening backtick
+ * @param to - The exclusive end of the scan window
+ * @returns The span text + end index, or `undefined`
+ *
+ * @example
+ * ```ts
+ * scanCode('`code`', 0, 6) // { value: 'code', end: 6 }
+ * ```
+ */
+export declare function scanCode(source: string, start: number, to: number): {
+    readonly value: string;
+    readonly end: number;
+} | undefined;
+
+/**
+ * Scan an emphasis run at `start` (`*` / `_`, doubled for strong) - finds the nearest
+ * matching closing run of the same marker + width while skipping complete nested
+ * runs from the other marker family, and requires non-space immediately inside both
+ * delimiters (the CommonMark flanking simplification that blocks `* x *`). Returns
+ * the emphasis node, or `undefined` when no valid closer exists (it then degrades to
+ * a literal marker).
+ *
+ * @param source - The inline source text
+ * @param start - The index of the opening marker
+ * @param to - The exclusive end of the scan window
+ * @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
+ *   at {@link MAX_DEPTH} the emphasis's children degrade to literal text instead of
+ *   recursing further
+ * @returns The parsed {@link EmphasisNode} + end index, or `undefined`
+ *
+ * @example
+ * ```ts
+ * scanEmphasis('*em*', 0, 4)
+ * // { node: { element: 'emphasis', strong: false, children: [...] }, end: 4 }
+ * ```
+ */
+export declare function scanEmphasis(source: string, start: number, to: number, depth?: number): {
+    readonly node: EmphasisNode;
+    readonly end: number;
+} | undefined;
+
+/**
+ * Scan the window `[from, to)` of `source` into inline nodes - the single recursive
+ * engine the inline phase runs on (emphasis, link text, and image alternative
+ * content recurse through it). Linear:
+ * each character is consumed once; a failed construct emits its opening character as
+ * text and advances by one, so there is no re-scan (no ReDoS).
+ *
+ * @param source - The inline source text
+ * @param from - The inclusive start of the scan window
+ * @param to - The exclusive end of the scan window
+ * @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
+ *   incremented by one on every recursive descent through {@link scanLink} /
+ *   {@link scanEmphasis}. At {@link MAX_DEPTH} the window is never scanned for markup -
+ *   it emits as a single literal text node - so pathological nesting (`[[[[…`,
+ *   `****…`) cannot exhaust the call stack.
+ * @returns The parsed inline nodes (NOT yet coalesced)
+ *
+ * @example
+ * ```ts
+ * scanInline('hi *there*', 0, 10) // [{ element: 'text', value: 'hi ' }, { element: 'emphasis', ... }]
+ * ```
+ */
+export declare function scanInline(source: string, from: number, to: number, depth?: number): readonly InlineNode[];
+
+/**
+ * Scan a link `[text](href)` at `start` - the text runs to a BALANCED `]`, then `(`
+ * must immediately follow and the destination runs to the matching `)` (both respect
+ * nested delimiters + escapes). Returns the link node, or `undefined` when the shape
+ * does not hold (it then degrades to a literal `[`).
+ *
+ * @param source - The inline source text
+ * @param start - The index of the opening `[`
+ * @param to - The exclusive end of the scan window
+ * @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
+ *   at {@link MAX_DEPTH} the link's text children degrade to literal text instead of
+ *   recursing further
+ * @returns The parsed {@link LinkNode} + end index, or `undefined`
+ *
+ * @example
+ * ```ts
+ * scanLink('[text](url)', 0, 11)
+ * // { node: { element: 'link', href: 'url', children: [...] }, end: 11 }
+ * ```
+ */
+export declare function scanLink(source: string, start: number, to: number, depth?: number): {
+    readonly node: LinkNode;
+    readonly end: number;
+} | undefined;
+
+/**
+ * Normalize line endings to `\n` and split a markdown document into its lines - CRLF
+ * (`\r\n`) and bare CR (`\r`) both collapse to `\n` first, so a Windows-origin
+ * document parses identically. A single trailing newline does not yield a final
+ * empty line.
+ *
+ * @param markdown - The raw markdown source
+ * @returns The document's lines, line-terminators stripped
+ *
+ * @example
+ * ```ts
+ * splitLines('a\r\nb\nc') // ['a', 'b', 'c']
+ * ```
+ */
+export declare function splitLines(markdown: string): readonly string[];
+
+/**
+ * Split one GFM table row into its cell strings - outer pipes are optional, an escaped
+ * pipe (`\|`) inside a cell is NOT a separator (it becomes a literal `|`), and the
+ * empty leading / trailing cell produced by an outer `|` is dropped.
+ *
+ * @param row - The raw table row line
+ * @returns The row's cells, in column order
+ *
+ * @example
+ * ```ts
+ * splitTableRow('|a|b|') // ['a', 'b']
+ * ```
+ */
+export declare function splitTableRow(row: string): readonly string[];
+
+/**
+ * Whether the line at `index` starts a NEW block kind (heading / fence / thematic
+ * break / blockquote / list / table) - the paragraph collector stops at such a line
+ * so a block following a paragraph without a blank line still parses (a trusted-input
+ * caller writing a `##` heading directly under a paragraph, with no intervening blank
+ * line).
+ *
+ * @param lines - The document's lines
+ * @param index - The line index to test
+ * @returns `true` when the line begins a different block
+ *
+ * @example
+ * ```ts
+ * startsBlock(['text', '## Heading'], 1) // true
+ * ```
+ */
+export declare function startsBlock(lines: readonly string[], index: number): boolean;
+
+/**
+ * Strip one level of blockquote marker (`>` plus one optional following space) from a
+ * blockquote line, so the de-quoted lines re-parse as nested blocks.
+ *
+ * @param line - A blockquote line (per {@link isQuote})
+ * @returns The line with its leading `>` (and one space) removed
+ *
+ * @example
+ * ```ts
+ * stripQuote('> text') // 'text'
+ * ```
+ */
+export declare function stripQuote(line: string): string;
+
+/**
+ * The horizontal alignment of a GFM table column, as declared by its delimiter row
+ * (`:---` left, `---:` right, `:---:` center). A bare `---` delimiter is represented
+ * 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.
+ */
+export declare type TableAlign = 'left' | 'right' | 'center';
+
+/**
+ * The shape of a {@link TableAlign} - the per-column GFM table alignment
+ * literal.
+ *
+ * @example
+ * ```ts
+ * import { createContract } from '@orkestrel/contract'
+ * import { tableAlignShape } from '@src/core'
+ *
+ * const tableAlign = createContract(tableAlignShape)
+ * tableAlign.is('left')   // true
+ * tableAlign.is('center') // true
+ * tableAlign.is('top')    // false
+ * ```
+ */
+export declare const tableAlignShape: LiteralShape<readonly ["left", "right", "center"]>;
+
+/**
+ * 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';
+    /** The header row - one cell of inline content per column. */
+    readonly header: readonly (readonly InlineNode[])[];
+    /** The body rows - each a list of cells, each cell inline content. */
+    readonly rows: readonly (readonly (readonly InlineNode[])[])[];
+    /**
+     * The per-column alignment from the delimiter row, in column order. `null`
+     * represents a bare `---` delimiter because this positional array requires one
+     * entry per column, JSON cannot carry `undefined` in an array, and the delimiter
+     * is an explicit no-alignment marker rather than an omitted value.
+     */
+    readonly align: readonly (TableAlign | null)[];
+}
+
+/**
+ * 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';
+    /** The literal text content (escapes resolved, NOT yet HTML-escaped). */
+    readonly value: string;
+}
+
+/**
+ * The shape of a {@link TextNode} - a plain-text leaf inline run.
+ *
+ * @example
+ * ```ts
+ * import { createContract } from '@orkestrel/contract'
+ * import { textShape } from '@src/core'
+ *
+ * const text = createContract(textShape)
+ * text.is({ element: 'text', value: 'hi' }) // true
+ * ```
+ */
+export declare const textShape: ObjectShape<{
+    element: LiteralShape<readonly ["text"]>;
+    value: StringShape;
+}, false>;
+
+/** A thematic break - a horizontal rule (`---` / `***` / `___` on its own line). */
+export declare interface ThematicBreakNode {
+    readonly element: 'thematicBreak';
+}
+
+/**
+ * The shape of a {@link ThematicBreakNode} - a horizontal rule. Carries no
+ * fields beyond its `element` discriminant.
+ *
+ * @example
+ * ```ts
+ * import { createContract } from '@orkestrel/contract'
+ * import { thematicBreakShape } from '@src/core'
+ *
+ * const thematicBreak = createContract(thematicBreakShape)
+ * thematicBreak.is({ element: 'thematicBreak' }) // true
+ * ```
+ */
+export declare const thematicBreakShape: ObjectShape<{
+    element: LiteralShape<readonly ["thematicBreak"]>;
+}, false>;
+
+/**
+ * Trim the whitespace at the two ends of an inline run - the leading whitespace of a
+ * leading text node and the trailing whitespace of a trailing one - dropping either
+ * node when nothing survives.
+ *
+ * @remarks
+ * Markdown trims every line of a paragraph, a heading's text, and a table cell, so an
+ * untrimmed run would come back from a re-parse a different AST. Expects a coalesced
+ * run (see {@link coalesceText}): only the outermost node on each side is examined.
+ *
+ * @param nodes - The inline run to trim
+ * @returns The run with its edge whitespace removed
+ *
+ * @example
+ * ```ts
+ * trimInlines([{ element: 'text', value: ' a ' }]) // [{ element: 'text', value: 'a' }]
+ * ```
+ */
+export declare function trimInlines(nodes: readonly InlineNode[]): readonly InlineNode[];
+
+/**
+ * Resolve backslash escapes in a raw string to their literal characters - used for a
+ * link `href` (which is not otherwise inline-parsed) and any plain text run.
+ *
+ * @param text - The raw text possibly carrying `\x` escapes
+ * @returns The text with escapable `\x` reduced to `x`
+ *
+ * @example
+ * ```ts
+ * unescapeText('\\*hi\\*') // '*hi*'
+ * ```
+ */
+export declare function unescapeText(text: string): string;
+
+/**
+ * Depth-first, pre-order, root-inclusive traversal of a {@link MarkdownNode} - yields
+ * the node itself, then recurses into its children (block children, list items,
+ * image/link inline children, table header/row cells' inline nodes) in walk order.
+ *
+ * @remarks
+ * Total: never throws. Descent stops at {@link MAX_DEPTH} (the node at the cap is
+ * still yielded; its children are not) so pathologically deep input cannot exhaust
+ * the call stack.
+ *
+ * @param node - The AST node to walk (a full document, or any sub-node)
+ * @returns A generator yielding every visited node, pre-order
+ *
+ * @example
+ * ```ts
+ * const doc = { element: 'document', children: [{ element: 'thematicBreak' }] } as const
+ * [...walkNodes(doc)].map((node) => node.element) // ['document', 'thematicBreak']
+ * ```
+ */
+export declare function walkNodes(node: MarkdownNode): Generator<MarkdownNode>;
+
+export { }