@orkestrel/markdown 0.0.5 → 0.0.6

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

@@ -1,8 +1,1459 @@
-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 { ContractInterface } from '@orkestrel/contract';
+import { Guard } from '@orkestrel/contract';
+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';
+
+/** 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;
+};
+
+/**
+ * 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>;
+
+/**
+ * Create a stateful markdown handle from a markdown string or an already-parsed
+ * {@link MarkdownDocument} - a typed AST plus the query, rewrite, and fold operations
+ * {@link MarkdownInterface} exposes.
+ *
+ * @remarks
+ * Given a `string`, runs a block phase (headings / paragraphs / lists / GFM tables /
+ * fenced code / blockquotes / thematic breaks) then an inline phase (emphasis /
+ * inline code / links) to build a render-agnostic {@link MarkdownDocument}. Given a
+ * {@link MarkdownDocument}, adopts it AS-IS without re-validation - gate an untrusted
+ * value with `isMarkdownDocument` first. Pure + total parse (malformed markdown
+ * degrades to text, never throws) and zero-dependency - a hand-written scanner, no
+ * regex-only structural parse, linear-time (no ReDoS).
+ *
+ * @param input - A markdown string to parse, or an already-parsed {@link MarkdownDocument}
+ * @returns A working {@link MarkdownInterface}
+ *
+ * @example
+ * ```ts
+ * import { createMarkdown } from '@src/core'
+ *
+ * const markdown = createMarkdown('# Hi\n\nRead the [guide](./guide.md).')
+ * markdown.document.children[0] // { element: 'heading', ... }
+ * ```
+ */
+export declare function createMarkdown(input: string | MarkdownDocument): MarkdownInterface;
+
+/**
+ * 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>;
+
+/**
+ * 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[];
+}
+
+/**
+ * HTML-escape text content - `&` / `<` / `>` / `"` / `'` to their entities - so text
+ * from a markdown document can never inject markup. The renderer applies this to every
+ * text run, code body, and (escaped further) attribute value.
+ *
+ * @param text - The raw text
+ * @returns The HTML-escaped text
+ *
+ * @example
+ * ```ts
+ * escapeHtml('<a>&"\'') // '&lt;a&gt;&amp;&quot;&#39;'
+ * ```
+ */
+export declare function escapeHtml(text: string): string;
+
+/**
+ * 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 ListItemParts}, or `undefined` when `line` is not a list
+ * item. `content` is the text after the marker; `marker` is the full marker-plus-space
+ * width (for measuring a continuation's indent).
+ *
+ * @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): ListItemParts | undefined;
+
+/**
+ * Concatenate the `value` / `code` content of every descendant text / code-span /
+ * code-block node under `node`, in walk order - the plain-text projection of an AST
+ * (search indexing, word counts, a text-only preview).
+ *
+ * @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[];
+}
+
+/** A node that can appear inside inline content (a heading / paragraph / cell / list item / link text). */
+export declare type InlineNode = TextNode | EmphasisNode | CodeSpanNode | LinkNode;
+
+/**
+ * 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 an arbitrary value is a valid {@link InlineNode} - a text
+ * run, emphasis, code span, or link, 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 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;
+
+/**
+ * The count of leading space / tab characters on `line` (a tab counts as one) - the
+ * indent that decides whether a list item's continuation belongs to the item.
+ *
+ * @param line - The line to measure
+ * @returns The number of leading space / tab characters
+ *
+ * @example
+ * ```ts
+ * leadingIndent('  text') // 2
+ * ```
+ */
+export declare function leadingIndent(line: string): number;
+
+/**
+ * An inline link - `[text](href)`. `children` are the inline nodes of the link text;
+ * `href` is the destination, sanitized at render (a `javascript:` / other unsafe
+ * scheme is dropped to an empty `href`, and the value is HTML-attribute-escaped).
+ */
+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[];
+}
+
+/** 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[];
+}
+
+/**
+ * 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 ListItemParts {
+    /** `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 ListItemParts} - the parsed parts of a single list-item
+ * line the block phase's list detector returns. Fully non-recursive (no
+ * nested node fields), so every field shapes directly.
+ *
+ * @example
+ * ```ts
+ * import { createContract } from '@orkestrel/contract'
+ * import { listItemPartsShape } from '@src/core'
+ *
+ * const listItemParts = createContract(listItemPartsShape)
+ * listItemParts.is({ ordered: false, start: 1, content: 'hi', indent: 0, marker: 2 }) // true
+ * ```
+ */
+export declare const listItemPartsShape: ObjectShape<{
+    ordered: BooleanShape;
+    start: NumberShape;
+    content: StringShape;
+    indent: NumberShape;
+    marker: NumberShape;
+}, false>;
+
+/**
+ * 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>;
+}
+
+/**
+ * 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 LinkNode} from its already-folded inline children. */
+    readonly link: MarkdownHandler<LinkNode, 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 the renderer's
+ * `switch` covers.
+ */
+export declare type MarkdownNode = MarkdownDocument | BlockNode | ListItemNode | InlineNode;
+
+/**
+ * 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;
+
+/**
+ * The maximum recursion depth the parse pipeline (`parseDocument` and its
+ * `parsers.ts` helpers) and the `helpers.ts` traversal / render functions
+ * (`renderHTML`, `renderMarkdown`, `walkNodes`, `foldNode`) honor before degrading to
+ * literal text - bounds blockquote nesting, inline nesting (emphasis / links), and
+ * traversal/render recursion so pathological or hostile input (deeply nested
+ * blockquotes, runaway emphasis) cannot exhaust the call stack. Past this depth the
+ * parser treats the remaining content as literal text instead of recursing further.
+ */
+export declare const MAX_DEPTH = 64;
+
+/** 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) 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[];
+
+/**
+ * Render a {@link MarkdownNode} (typically a {@link MarkdownDocument}) to a safe HTML
+ * string - the recursive AST → HTML engine (headings, paragraphs, lists, GFM tables,
+ * fenced code, blockquotes, links, emphasis, inline code), escaping every text run and
+ * sanitizing every link `href`.
+ *
+ * @remarks
+ * Total: never throws. At {@link MAX_DEPTH} a value-bearing node (`text` / `codeSpan`)
+ * degrades to its escaped `value`; any other node degrades to `''` instead of
+ * recursing further, so pathologically deep input cannot exhaust the call stack.
+ *
+ * @param node - The AST node to render (a full document, or any sub-node)
+ * @returns The rendered, XSS-safe HTML string
+ *
+ * @example
+ * ```ts
+ * renderHTML({ element: 'document', children: [
+ *   { element: 'heading', level: 1, children: [{ element: 'text', value: 'Hi' }] },
+ * ] })
+ * // '<h1>Hi</h1>'
+ * ```
+ */
+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: `*em*` / `**strong**` (underscore emphasis
+ * normalizes to asterisks), `- ` bullets, `N. ` sequential ordinals (from the list's
+ * `start`), `---` thematic breaks, fenced code blocks (backtick run widened past any
+ * 3+ backtick run inside the body), ATX headings, `> `-prefixed blockquote lines, GFM
+ * tables (1-space-padded cells, `\|`-escaped pipes, an alignment delimiter row), and
+ * `[text](href)` links. A `text` node's literal content is backslash-escaped wherever
+ * it would otherwise re-parse as markup (AGENTS §14 parse↔render soundness).
+ *
+ * @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;
+
+/**
+ * The URL schemes `renderHTML` permits on a link `href` - anything else (notably
+ * `javascript:`, `data:`, `vbscript:`, `file:`) is dropped to an empty `href` so a
+ * hostile link can never execute. Frozen, lower-case; a relative / anchor /
+ * scheme-less `href` (no `scheme:` prefix) is always allowed.
+ */
+export declare const SAFE_URL_SCHEMES: ReadonlySet<string>;
+
+/**
+ * Sanitize + HTML-attribute-escape a link `href` - a destination whose scheme is not
+ * in {@link SAFE_URL_SCHEMES} (notably `javascript:` / `data:` / `vbscript:`), or that
+ * is protocol-relative (`//host/path`, or a backslash variant a browser normalizes to
+ * the same effect - `\\host`, `/\host`, `\/host` - inherits whatever scheme the
+ * embedding page is served over, including an unsafe one), is dropped to an empty
+ * string; a relative / anchor / scheme-less (and non-protocol-relative) destination
+ * (including a SINGLE leading `/` or `\`) is kept;
+ * the surviving value is then HTML-escaped. Defence-in-depth against an XSS `href`,
+ * even though the input is trusted.
+ *
+ * @param href - The raw link destination
+ * @returns A safe, escaped `href` (empty when the scheme is unsafe or protocol-relative)
+ *
+ * @example
+ * ```ts
+ * sanitizeUrl('javascript:alert(1)') // ''
+ * sanitizeUrl('/path')               // '/path'
+ * ```
+ */
+export declare function sanitizeUrl(href: string): string;
+
+/**
+ * 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, requiring non-space immediately
+ * inside both delimiters (the CommonMark flanking simplification that blocks `* x *`).
+ * Returns the emphasis node, or `undefined` when no valid closer exists (it then
+ * degrades to a literal marker).
+ *
+ * @param source - The inline source text
+ * @param start - The index of the opening marker
+ * @param to - The exclusive end of the scan window
+ * @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
+ *   at {@link MAX_DEPTH} the emphasis's children degrade to literal text instead of
+ *   recursing further
+ * @returns The parsed {@link EmphasisNode} + end index, or `undefined`
+ *
+ * @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 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) - `'none'` when the delimiter carries
+ * no alignment colon. One entry per column, in column order.
+ */
+export declare type TableAlign = 'none' | 'left' | 'right' | 'center';
+
+/**
+ * Derive the per-column {@link TableAlign} list from a GFM delimiter row - `:---`
+ * left, `---:` right, `:---:` center, `---` none.
+ *
+ * @param delimiter - The table's delimiter row
+ * @returns One alignment per column, in column order
+ *
+ * @example
+ * ```ts
+ * tableAlignments('| :--- | ---: |') // ['left', 'right']
+ * ```
+ */
+export declare function tableAlignments(delimiter: string): readonly TableAlign[];
+
+/**
+ * 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 ["none", "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. */
+    readonly align: readonly TableAlign[];
+}
+
+/**
+ * A run of plain text - the leaf inline node. `value` is the decoded text with
+ * markdown escapes (`\*`, `\_`, …) already resolved to their literal characters; the
+ * renderer HTML-escapes it (`<` / `>` / `&` / `"`) on the way out.
+ */
+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>;
+
+/**
+ * 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, 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 { }