@orkestrel/markdown 0.0.6 → 0.0.7

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

@@ -1,11 +1,17 @@
 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;
@@ -131,6 +137,20 @@ export declare function collectTable(lines: readonly string[], start: number): {
     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
@@ -165,6 +185,21 @@ export declare function createCodeBlockContract(): ContractInterface<CodeBlockNo
  */
 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
@@ -173,7 +208,8 @@ export declare function createCodeSpanContract(): ContractInterface<CodeSpanNode
  * @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
+ * 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
@@ -192,6 +228,28 @@ export declare function createCodeSpanContract(): ContractInterface<CodeSpanNode
  */
 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
@@ -226,6 +284,21 @@ export declare function createTextContract(): ContractInterface<TextNode>;
  */
 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,
@@ -241,19 +314,16 @@ export declare interface EmphasisNode {
 }
 
 /**
- * HTML-escape text content - `&` / `<` / `>` / `"` / `'` to their entities - so text
- * from a markdown document can never inject markup. The renderer applies this to every
- * text run, code body, and (escaped further) attribute value.
- *
- * @param text - The raw text
- * @returns The HTML-escaped text
+ * The frozen empty HTML-to-markdown projection from which projection factories
+ * default every absent field.
  *
  * @example
  * ```ts
- * escapeHtml('<a>&"\'') // '&lt;a&gt;&amp;&quot;&#39;'
+ * EMPTY_PROJECTION.blocks // []
+ * Object.isFrozen(EMPTY_PROJECTION) // true
  * ```
  */
-export declare function escapeHtml(text: string): string;
+export declare const EMPTY_PROJECTION: MarkdownProjection;
 
 /**
  * Extract a fenced-code opening line (```` ``` ```` or `~~~`, optionally with an info
@@ -295,7 +365,7 @@ export declare function extractHeading(line: string): {
 
 /**
  * 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
+ * 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).
  *
@@ -307,12 +377,13 @@ export declare function extractHeading(line: string): {
  * extractListItem('- item') // { ordered: false, start: 1, content: 'item', indent: 0, marker: 2 }
  * ```
  */
-export declare function extractListItem(line: string): ListItemParts | undefined;
+export declare function extractListItem(line: string): ListItemMatch | 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).
+ * 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
@@ -377,8 +448,66 @@ export declare interface HeadingNode {
     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 | LinkNode;
+export declare type InlineNode = TextNode | EmphasisNode | CodeSpanNode | LineBreakNode | LinkNode | ImageNode;
 
 /**
  * Whether `line` is blank - empty, or containing only whitespace - the markdown
@@ -512,9 +641,19 @@ export declare function isFenceWhitespace(character: string | undefined): boolea
 /** 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, or link, recursively validated.
+ * run, emphasis, code span, hard break, link, or image, recursively validated.
  *
  * @remarks
  * Total: never throws, even on cyclic or pathologically deep input - every
@@ -534,6 +673,16 @@ export declare function isHeadingNode(node: MarkdownNode): node is HeadingNode;
  */
 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;
 
@@ -688,24 +837,31 @@ export declare function isThematicBreakNode(node: MarkdownNode): node is Themati
  */
 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 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
+ * The shape of a {@link LineBreakNode} - a GFM hard line-break leaf.
  *
  * @example
  * ```ts
- * leadingIndent('  text') // 2
+ * import { createContract } from '@orkestrel/contract'
+ * import { lineBreakShape } from '@src/core'
+ *
+ * const lineBreak = createContract(lineBreakShape)
+ * lineBreak.is({ element: 'break' }) // true
  * ```
  */
-export declare function leadingIndent(line: string): number;
+export declare const lineBreakShape: ObjectShape<{
+    element: LiteralShape<readonly ["break"]>;
+}, false>;
 
 /**
- * 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).
+ * 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';
@@ -715,18 +871,11 @@ export declare interface LinkNode {
     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 {
+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. */
@@ -740,20 +889,20 @@ export declare interface ListItemParts {
 }
 
 /**
- * The shape of {@link ListItemParts} - the parsed parts of a single list-item
+ * 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 { listItemPartsShape } from '@src/core'
+ * import { listItemMatchShape } from '@src/core'
  *
- * const listItemParts = createContract(listItemPartsShape)
+ * const listItemParts = createContract(listItemMatchShape)
  * listItemParts.is({ ordered: false, start: 1, content: 'hi', indent: 0, marker: 2 }) // true
  * ```
  */
-export declare const listItemPartsShape: ObjectShape<{
+export declare const listItemMatchShape: ObjectShape<{
     ordered: BooleanShape;
     start: NumberShape;
     content: StringShape;
@@ -761,6 +910,13 @@ export declare const listItemPartsShape: ObjectShape<{
     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`).
@@ -863,6 +1019,14 @@ export declare class Markdown implements MarkdownInterface {
     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.
@@ -916,8 +1080,12 @@ export declare interface MarkdownHandlers<T> {
     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>;
 }
 
 /**
@@ -979,11 +1147,46 @@ export declare interface MarkdownInterface {
 
 /**
  * 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.
+ * 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
@@ -991,17 +1194,92 @@ export declare type MarkdownNode = MarkdownDocument | BlockNode | ListItemNode |
  */
 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 / render functions
- * (`renderHTML`, `renderMarkdown`, `walkNodes`, `foldNode`) honor before degrading to
- * literal text - bounds blockquote nesting, inline nesting (emphasis / links), and
- * traversal/render recursion so pathological or hostile input (deeply nested
- * blockquotes, runaway emphasis) cannot exhaust the call stack. Past this depth the
- * parser treats the remaining content as literal text instead of recursing further.
+ * `parsers.ts` helpers) and the `helpers.ts` traversal / projection functions
+ * (`markdownToHTML`, `renderHTML`, `renderMarkdown`, `walkNodes`, `foldNode`,
+ * `rewriteDocument`) honor before degrading. It bounds blockquote nesting, inline
+ * nesting (emphasis / links), and traversal / projection recursion so pathological
+ * or hostile input cannot exhaust the call stack. {@link htmlToMarkdown} is the
+ * inherited exception: its fold and depth cap belong to `@orkestrel/html`.
  */
 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';
@@ -1034,8 +1312,8 @@ export declare function parseBlocks(lines: readonly string[], depth: number): re
 export declare function parseDocument(markdown: string): MarkdownDocument;
 
 /**
- * Parses inline markdown text (emphasis, code spans, links) into inline AST
- * nodes, coalescing adjacent text runs.
+ * 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.
@@ -1043,25 +1321,122 @@ export declare function parseDocument(markdown: string): MarkdownDocument;
 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`.
+ * Project one HTML leaf - a text node, a comment, or a doctype - to its
+ * {@link MarkdownProjection}.
  *
  * @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.
+ * 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 node - The AST node to render (a full document, or any sub-node)
- * @returns The rendered, XSS-safe HTML string
+ * @param leaf - The leaf node to project
+ * @returns Its projection
  *
  * @example
  * ```ts
- * renderHTML({ element: 'document', children: [
- *   { element: 'heading', level: 1, children: [{ element: 'text', value: 'Hi' }] },
- * ] })
- * // '<h1>Hi</h1>'
+ * 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;
@@ -1069,13 +1444,15 @@ 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).
+ * 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
@@ -1129,36 +1506,6 @@ export declare function renderMarkdown(node: MarkdownNode): string;
  */
 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
@@ -1182,10 +1529,11 @@ export declare function scanCode(source: string, start: number, to: number): {
 
 /**
  * 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).
+ * 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
@@ -1208,7 +1556,8 @@ export declare function scanEmphasis(source: string, start: number, to: number,
 
 /**
  * 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:
+ * 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).
  *
@@ -1319,24 +1668,12 @@ 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']
- * ```
+ * (`:---` 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 function tableAlignments(delimiter: string): readonly TableAlign[];
+export declare type TableAlign = 'left' | 'right' | 'center';
 
 /**
  * The shape of a {@link TableAlign} - the per-column GFM table alignment
@@ -1353,7 +1690,7 @@ export declare function tableAlignments(delimiter: string): readonly TableAlign[
  * tableAlign.is('top')    // false
  * ```
  */
-export declare const tableAlignShape: LiteralShape<readonly ["none", "left", "right", "center"]>;
+export declare const tableAlignShape: LiteralShape<readonly ["left", "right", "center"]>;
 
 /**
  * A GFM table - `header` the inline content of each header cell, `rows` the body
@@ -1367,14 +1704,20 @@ export declare interface TableNode {
     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[];
+    /**
+     * 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; the
- * renderer HTML-escapes it (`<` / `>` / `&` / `"`) on the way out.
+ * 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';
@@ -1421,6 +1764,26 @@ 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.
@@ -1437,8 +1800,8 @@ 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.
+ * 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