@orkestrel/markdown 0.0.17 → 0.0.18

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

@@ -13,6 +13,17 @@ import { OptionalShape } from '@orkestrel/contract';
 import { StringShape } from '@orkestrel/contract';
 import type { TextNode as TextNode_2 } from '@orkestrel/html';
 
+/**
+ * Accepts a rewritten node only when it fits the original node slot.
+ *
+ * @example
+ * ```ts
+ * const original: TextNode = { element: 'text', value: 'hi' }
+ * acceptMarkdownNode(original, original, { element: 'thematicBreak' }) === original // true
+ * ```
+ */
+export declare function acceptMarkdownNode(current: MarkdownNode, rebuilt: MarkdownNode, result: MarkdownNode): MarkdownNode;
+
 /** Represents a node that can appear at the block level of a document (or inside a list item / blockquote). */
 export declare type BlockNode = HeadingNode | ParagraphNode | ListNode | TableNode | CodeBlockNode | BlockquoteNode | ThematicBreakNode;
 
@@ -28,7 +39,8 @@ export declare interface BlockquoteNode {
  * unrecognized character, so coalescing keeps the AST clean and assertion-friendly.
  *
  * @param nodes - The inline nodes (possibly with adjacent text runs)
- * @param spans - The optional operation-owned node span recorder
+ * @param spans - The optional operation-owned span memo; inserts merged-node entries
+ *   without deleting or replacing constituent entries
  * @returns The nodes with consecutive text nodes concatenated
  *
  * @example
@@ -160,6 +172,16 @@ export declare function collectTable(lines: readonly MarkdownSource[], start: nu
  */
 export declare function countIndent(line: string): number;
 
+/**
+ * Counts consecutive copies of the character at the start of a scan window.
+ *
+ * @example
+ * ```ts
+ * countMarkdownRun('***x', 0, 4) // 3
+ * ```
+ */
+export declare function countMarkdownRun(source: string, start: number, to: number): number;
+
 /**
  * Compiles the {@link codeBlockShape} into a {@link ContractInterface} for
  * {@link CodeBlockNode} — a guard, coercing parser, JSON Schema, and seeded
@@ -360,6 +382,16 @@ export declare interface EmphasisScan {
  */
 export declare const EMPTY_PROJECTION: MarkdownProjection;
 
+/**
+ * Escapes literal text so markdown syntax remains literal when rendered.
+ *
+ * @example
+ * ```ts
+ * escapeMarkdownText('*hi*', false) // '\\*hi\\*'
+ * ```
+ */
+export declare function escapeMarkdownText(value: string, bang: boolean): string;
+
 /**
  * Extracts a fenced-code opening line (```` ``` ```` or `~~~`, optionally with an info
  * string) into its `{ marker, lang }`, or `undefined` when `line` is not a fence
@@ -419,6 +451,16 @@ export declare interface FenceMatch {
     readonly lang: string | undefined;
 }
 
+/**
+ * Finds the next defined markdown node at or after an array offset.
+ *
+ * @example
+ * ```ts
+ * findFollowingNode([], 0) // undefined
+ * ```
+ */
+export declare function findFollowingNode(nodes: readonly MarkdownNode[], start: number): MarkdownNode | undefined;
+
 /**
  * Concatenates the `value` / `code` content of every descendant text / code-span /
  * code-block node under `node`, including image alternative content, in walk order —
@@ -443,6 +485,16 @@ export declare interface FenceMatch {
  */
 export declare function flattenText(node: MarkdownNode): string;
 
+/**
+ * Dispatches one markdown node and its folded children to the matching handler.
+ *
+ * @example
+ * ```ts
+ * foldMarkdownNode({ element: 'text', value: 'hi' }, countHandlers, []) // 1
+ * ```
+ */
+export declare function foldMarkdownNode<T>(node: MarkdownNode, handlers: MarkdownHandlerMap<T>, children: readonly T[]): T;
+
 /**
  * Folds a {@link MarkdownNode} into a `T` through a total catamorphism — children are
  * folded first (post-order), then the node's own {@link MarkdownHandler} is invoked
@@ -1025,6 +1077,19 @@ export declare interface LinkScan {
     readonly end: number;
 }
 
+/**
+ * Lists the direct children of a markdown node in traversal order.
+ *
+ * @param node - The node whose direct children to list
+ * @returns The children, with table cells flattened in header then body order
+ *
+ * @example
+ * ```ts
+ * listChildren({ element: 'document', children: [] }) // []
+ * ```
+ */
+export declare function listChildren(node: MarkdownNode): readonly MarkdownNode[];
+
 /**
  * Represents the result of collecting one list — the node the construct scanner built and where
  * the block phase resumes.
@@ -1136,6 +1201,16 @@ export declare function locateEmphasis(source: string, start: number, to: number
  */
 export declare function locateLink(source: string, start: number, to: number): LinkBounds | undefined;
 
+/**
+ * Locates a balanced closing delimiter while skipping backslash escapes.
+ *
+ * @example
+ * ```ts
+ * locateMarkdownDelimiter('[a]', 0, 3, '[', ']') // 2
+ * ```
+ */
+export declare function locateMarkdownDelimiter(source: string, start: number, to: number, open: string, close: string): number | undefined;
+
 /**
  * Wraps a typed {@link MarkdownDocument} AST as a stateful, parsed markdown document
  * with the query (`find` / `filter` / `reduce` / iteration), rewrite (`map`), fold, and
@@ -1246,7 +1321,9 @@ export declare class Markdown implements MarkdownInterface {
      * ```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()) {
+     * for (;;) {
+     *   const result = await reader.read()
+     *   if (result.done) break
      *   console.log(result.value) // one BlockNode
      * }
      *
@@ -1365,6 +1442,12 @@ export declare interface MarkdownHandlerMap<T> {
     readonly image: MarkdownHandler<ImageNode, T>;
 }
 
+/** Represents an inline construct and the source offset where scanning resumes. */
+export declare interface MarkdownInlineScan {
+    readonly node: InlineNode;
+    readonly end: number;
+}
+
 /**
  * Represents a stateful, parsed markdown document: the typed {@link MarkdownDocument} AST plus
  * the query, rewrite, and fold operations over it.
@@ -1763,6 +1846,10 @@ export declare function parseInline(text: string): readonly InlineNode[];
  * @param markdown - The markdown source to parse.
  * @returns The parsed document and its node-identity span map.
  *
+ * @remarks
+ * Parsing inserts into a scratch memo. The returned map contains only nodes of the
+ * final document, enumerated without the public walk's depth cap.
+ *
  * @example
  * ```ts
  * const [document, spans] = parseProvenance('# Hi')
@@ -1871,6 +1958,16 @@ export declare function projectionToBlocks(projection: MarkdownProjection): read
  */
 export declare function projectionToInlines(projection: MarkdownProjection): readonly InlineNode[];
 
+/**
+ * Projects one markdown node from its already projected children.
+ *
+ * @example
+ * ```ts
+ * projectMarkdownNode({ element: 'text', value: 'hi' }, []) // { category: 'text', value: 'hi' }
+ * ```
+ */
+export declare function projectMarkdownNode(current: MarkdownNode, children: ReadonlyArray<HTMLNode | undefined>): HTMLNode | undefined;
+
 /**
  * Projects a derived text range through its segments to a half-open region of the
  * original markdown string.
@@ -1888,6 +1985,39 @@ export declare function projectionToInlines(projection: MarkdownProjection): rea
  */
 export declare function projectSpan(source: MarkdownSource, from: number, to: number): MarkdownSpan | undefined;
 
+/**
+ * Rebuilds a table cell and records each input and accepted output pair.
+ *
+ * @example
+ * ```ts
+ * rebuildMarkdownCell([], [].values(), []) // []
+ * ```
+ */
+export declare function rebuildMarkdownCell(cell: readonly InlineNode[], outputs: Iterator<MarkdownNode, undefined>, pairs: Array<readonly [InlineNode, InlineNode]>): readonly InlineNode[];
+
+/**
+ * Rebuilds one markdown node when accepted child replacements change its identity.
+ *
+ * @example
+ * ```ts
+ * const original: ParagraphNode = { element: 'paragraph', children: [] }
+ * rebuildMarkdownNode(original, []) === original // true
+ * ```
+ */
+export declare function rebuildMarkdownNode(current: MarkdownNode, children: readonly MarkdownNode[]): MarkdownNode;
+
+/**
+ * Appends a nonempty text node and records its original source span.
+ *
+ * @example
+ * ```ts
+ * const nodes: InlineNode[] = []
+ * recordMarkdownText({ text: 'a', segments: [] }, 'a', 0, 1, new Map(), nodes)
+ * nodes // [{ element: 'text', value: 'a' }]
+ * ```
+ */
+export declare function recordMarkdownText(source: MarkdownSource, value: string, start: number, end: number, spans: Map<MarkdownNode, MarkdownSpan>, nodes: InlineNode[]): void;
+
 /**
  * Renders a {@link MarkdownNode} to sanitized canonical HTML.
  *
@@ -1943,6 +2073,16 @@ export declare function renderHTML(node: MarkdownNode): string;
  */
 export declare function renderMarkdown(node: MarkdownNode): string;
 
+/**
+ * Renders one markdown node from its rendered children and escaped literal text.
+ *
+ * @example
+ * ```ts
+ * renderMarkdownNode({ element: 'thematicBreak' }, [], '', 0) // '---'
+ * ```
+ */
+export declare function renderMarkdownNode(current: MarkdownNode, children: readonly string[], literal: string, emphasis: number): string;
+
 /**
  * Rewrites a {@link MarkdownDocument} bottom-up (copy-on-write) — each node's children
  * are rewritten first (post-order), then `rewrite` is applied to the node itself; the
@@ -2094,6 +2234,16 @@ export declare function scanInlineSource(source: MarkdownSource, from: number, t
  */
 export declare function scanLink(source: string, start: number, to: number, depth?: number): LinkScan | undefined;
 
+/**
+ * Scans one inline construct and records the spans of its nested children.
+ *
+ * @example
+ * ```ts
+ * scanMarkdownInline({ text: '`x`', segments: [] }, 0, 3, new Map(), 0)?.end // 3
+ * ```
+ */
+export declare function scanMarkdownInline(source: MarkdownSource, index: number, to: number, spans: Map<MarkdownNode, MarkdownSpan>, depth: number): MarkdownInlineScan | undefined;
+
 /**
  * Slices derived markdown text and narrows each intersecting source segment to the
  * same text-relative range.
@@ -2157,6 +2307,19 @@ export declare function splitTableRow(row: string): readonly string[];
  */
 export declare function splitTableSources(row: MarkdownSource): readonly MarkdownSource[];
 
+/**
+ * Splits inline nodes into adjacent text runs and singleton non-text runs.
+ *
+ * @param nodes - The inline nodes in source order
+ * @returns The runs with their original node identities
+ *
+ * @example
+ * ```ts
+ * splitTextRuns([{ element: 'text', value: 'a' }]).length // 1
+ * ```
+ */
+export declare function splitTextRuns(nodes: readonly InlineNode[]): ReadonlyArray<readonly InlineNode[]>;
+
 /**
  * Checks whether the line at `index` starts a new block kind (heading / fence / thematic
  * break / blockquote / list / table) — the paragraph collector stops at such a line
@@ -2327,6 +2490,19 @@ element: LiteralShape<readonly ["thematicBreak"]>;
  */
 export declare function trimInlines(nodes: readonly InlineNode[]): readonly InlineNode[];
 
+/**
+ * Trims leading whitespace when an inline run starts with a text node.
+ *
+ * @param nodes - The inline run to trim
+ * @returns The run with its leading text trimmed or removed when empty
+ *
+ * @example
+ * ```ts
+ * trimLeading([{ element: 'text', value: ' a ' }]) // [{ element: 'text', value: 'a ' }]
+ * ```
+ */
+export declare function trimLeading(nodes: readonly InlineNode[]): readonly InlineNode[];
+
 /**
  * Trims an offset-bearing source without losing the coordinates of its retained text.
  *
@@ -2341,6 +2517,19 @@ export declare function trimInlines(nodes: readonly InlineNode[]): readonly Inli
  */
 export declare function trimSource(source: MarkdownSource): MarkdownSource;
 
+/**
+ * Trims trailing whitespace when an inline run ends with a text node.
+ *
+ * @param nodes - The inline run to trim
+ * @returns The run with its trailing text trimmed or removed when empty
+ *
+ * @example
+ * ```ts
+ * trimTrailing([{ element: 'text', value: ' a ' }]) // [{ element: 'text', value: ' a' }]
+ * ```
+ */
+export declare function trimTrailing(nodes: readonly InlineNode[]): readonly InlineNode[];
+
 /**
  * Resolves backslash escapes in a raw string to their literal characters — used for a
  * link `href` (which is not otherwise inline-parsed) and any plain text run.
@@ -2355,6 +2544,26 @@ export declare function trimSource(source: MarkdownSource): MarkdownSource;
  */
 export declare function unescapeText(text: string): string;
 
+/**
+ * Yields UTF-16 offsets and characters within a markdown scan window.
+ *
+ * @example
+ * ```ts
+ * Array.from(walkMarkdownCharacters('ab', 0, 2)) // [[0, 'a'], [1, 'b']]
+ * ```
+ */
+export declare function walkMarkdownCharacters(source: string, from: number, to: number): Generator<readonly [number, string], void, unknown>;
+
+/**
+ * Yields line offsets through a closable markdown scan iterator.
+ *
+ * @example
+ * ```ts
+ * Array.from(walkMarkdownLines(splitLines('a\nb'), 1)) // [1]
+ * ```
+ */
+export declare function walkMarkdownLines(lines: readonly MarkdownSource[], start: number): Generator<number, void, unknown>;
+
 /**
  * Walks a {@link MarkdownNode} depth-first, pre-order, root-inclusive — yields
  * the node itself, then recurses into its children (block children, list items,

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

@@ -13,6 +13,17 @@ import { OptionalShape } from '@orkestrel/contract';
 import { StringShape } from '@orkestrel/contract';
 import type { TextNode as TextNode_2 } from '@orkestrel/html';
 
+/**
+ * Accepts a rewritten node only when it fits the original node slot.
+ *
+ * @example
+ * ```ts
+ * const original: TextNode = { element: 'text', value: 'hi' }
+ * acceptMarkdownNode(original, original, { element: 'thematicBreak' }) === original // true
+ * ```
+ */
+export declare function acceptMarkdownNode(current: MarkdownNode, rebuilt: MarkdownNode, result: MarkdownNode): MarkdownNode;
+
 /** Represents a node that can appear at the block level of a document (or inside a list item / blockquote). */
 export declare type BlockNode = HeadingNode | ParagraphNode | ListNode | TableNode | CodeBlockNode | BlockquoteNode | ThematicBreakNode;
 
@@ -28,7 +39,8 @@ export declare interface BlockquoteNode {
  * unrecognized character, so coalescing keeps the AST clean and assertion-friendly.
  *
  * @param nodes - The inline nodes (possibly with adjacent text runs)
- * @param spans - The optional operation-owned node span recorder
+ * @param spans - The optional operation-owned span memo; inserts merged-node entries
+ *   without deleting or replacing constituent entries
  * @returns The nodes with consecutive text nodes concatenated
  *
  * @example
@@ -160,6 +172,16 @@ export declare function collectTable(lines: readonly MarkdownSource[], start: nu
  */
 export declare function countIndent(line: string): number;
 
+/**
+ * Counts consecutive copies of the character at the start of a scan window.
+ *
+ * @example
+ * ```ts
+ * countMarkdownRun('***x', 0, 4) // 3
+ * ```
+ */
+export declare function countMarkdownRun(source: string, start: number, to: number): number;
+
 /**
  * Compiles the {@link codeBlockShape} into a {@link ContractInterface} for
  * {@link CodeBlockNode} — a guard, coercing parser, JSON Schema, and seeded
@@ -360,6 +382,16 @@ export declare interface EmphasisScan {
  */
 export declare const EMPTY_PROJECTION: MarkdownProjection;
 
+/**
+ * Escapes literal text so markdown syntax remains literal when rendered.
+ *
+ * @example
+ * ```ts
+ * escapeMarkdownText('*hi*', false) // '\\*hi\\*'
+ * ```
+ */
+export declare function escapeMarkdownText(value: string, bang: boolean): string;
+
 /**
  * Extracts a fenced-code opening line (```` ``` ```` or `~~~`, optionally with an info
  * string) into its `{ marker, lang }`, or `undefined` when `line` is not a fence
@@ -419,6 +451,16 @@ export declare interface FenceMatch {
     readonly lang: string | undefined;
 }
 
+/**
+ * Finds the next defined markdown node at or after an array offset.
+ *
+ * @example
+ * ```ts
+ * findFollowingNode([], 0) // undefined
+ * ```
+ */
+export declare function findFollowingNode(nodes: readonly MarkdownNode[], start: number): MarkdownNode | undefined;
+
 /**
  * Concatenates the `value` / `code` content of every descendant text / code-span /
  * code-block node under `node`, including image alternative content, in walk order —
@@ -443,6 +485,16 @@ export declare interface FenceMatch {
  */
 export declare function flattenText(node: MarkdownNode): string;
 
+/**
+ * Dispatches one markdown node and its folded children to the matching handler.
+ *
+ * @example
+ * ```ts
+ * foldMarkdownNode({ element: 'text', value: 'hi' }, countHandlers, []) // 1
+ * ```
+ */
+export declare function foldMarkdownNode<T>(node: MarkdownNode, handlers: MarkdownHandlerMap<T>, children: readonly T[]): T;
+
 /**
  * Folds a {@link MarkdownNode} into a `T` through a total catamorphism — children are
  * folded first (post-order), then the node's own {@link MarkdownHandler} is invoked
@@ -1025,6 +1077,19 @@ export declare interface LinkScan {
     readonly end: number;
 }
 
+/**
+ * Lists the direct children of a markdown node in traversal order.
+ *
+ * @param node - The node whose direct children to list
+ * @returns The children, with table cells flattened in header then body order
+ *
+ * @example
+ * ```ts
+ * listChildren({ element: 'document', children: [] }) // []
+ * ```
+ */
+export declare function listChildren(node: MarkdownNode): readonly MarkdownNode[];
+
 /**
  * Represents the result of collecting one list — the node the construct scanner built and where
  * the block phase resumes.
@@ -1136,6 +1201,16 @@ export declare function locateEmphasis(source: string, start: number, to: number
  */
 export declare function locateLink(source: string, start: number, to: number): LinkBounds | undefined;
 
+/**
+ * Locates a balanced closing delimiter while skipping backslash escapes.
+ *
+ * @example
+ * ```ts
+ * locateMarkdownDelimiter('[a]', 0, 3, '[', ']') // 2
+ * ```
+ */
+export declare function locateMarkdownDelimiter(source: string, start: number, to: number, open: string, close: string): number | undefined;
+
 /**
  * Wraps a typed {@link MarkdownDocument} AST as a stateful, parsed markdown document
  * with the query (`find` / `filter` / `reduce` / iteration), rewrite (`map`), fold, and
@@ -1246,7 +1321,9 @@ export declare class Markdown implements MarkdownInterface {
      * ```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()) {
+     * for (;;) {
+     *   const result = await reader.read()
+     *   if (result.done) break
      *   console.log(result.value) // one BlockNode
      * }
      *
@@ -1365,6 +1442,12 @@ export declare interface MarkdownHandlerMap<T> {
     readonly image: MarkdownHandler<ImageNode, T>;
 }
 
+/** Represents an inline construct and the source offset where scanning resumes. */
+export declare interface MarkdownInlineScan {
+    readonly node: InlineNode;
+    readonly end: number;
+}
+
 /**
  * Represents a stateful, parsed markdown document: the typed {@link MarkdownDocument} AST plus
  * the query, rewrite, and fold operations over it.
@@ -1763,6 +1846,10 @@ export declare function parseInline(text: string): readonly InlineNode[];
  * @param markdown - The markdown source to parse.
  * @returns The parsed document and its node-identity span map.
  *
+ * @remarks
+ * Parsing inserts into a scratch memo. The returned map contains only nodes of the
+ * final document, enumerated without the public walk's depth cap.
+ *
  * @example
  * ```ts
  * const [document, spans] = parseProvenance('# Hi')
@@ -1871,6 +1958,16 @@ export declare function projectionToBlocks(projection: MarkdownProjection): read
  */
 export declare function projectionToInlines(projection: MarkdownProjection): readonly InlineNode[];
 
+/**
+ * Projects one markdown node from its already projected children.
+ *
+ * @example
+ * ```ts
+ * projectMarkdownNode({ element: 'text', value: 'hi' }, []) // { category: 'text', value: 'hi' }
+ * ```
+ */
+export declare function projectMarkdownNode(current: MarkdownNode, children: ReadonlyArray<HTMLNode | undefined>): HTMLNode | undefined;
+
 /**
  * Projects a derived text range through its segments to a half-open region of the
  * original markdown string.
@@ -1888,6 +1985,39 @@ export declare function projectionToInlines(projection: MarkdownProjection): rea
  */
 export declare function projectSpan(source: MarkdownSource, from: number, to: number): MarkdownSpan | undefined;
 
+/**
+ * Rebuilds a table cell and records each input and accepted output pair.
+ *
+ * @example
+ * ```ts
+ * rebuildMarkdownCell([], [].values(), []) // []
+ * ```
+ */
+export declare function rebuildMarkdownCell(cell: readonly InlineNode[], outputs: Iterator<MarkdownNode, undefined>, pairs: Array<readonly [InlineNode, InlineNode]>): readonly InlineNode[];
+
+/**
+ * Rebuilds one markdown node when accepted child replacements change its identity.
+ *
+ * @example
+ * ```ts
+ * const original: ParagraphNode = { element: 'paragraph', children: [] }
+ * rebuildMarkdownNode(original, []) === original // true
+ * ```
+ */
+export declare function rebuildMarkdownNode(current: MarkdownNode, children: readonly MarkdownNode[]): MarkdownNode;
+
+/**
+ * Appends a nonempty text node and records its original source span.
+ *
+ * @example
+ * ```ts
+ * const nodes: InlineNode[] = []
+ * recordMarkdownText({ text: 'a', segments: [] }, 'a', 0, 1, new Map(), nodes)
+ * nodes // [{ element: 'text', value: 'a' }]
+ * ```
+ */
+export declare function recordMarkdownText(source: MarkdownSource, value: string, start: number, end: number, spans: Map<MarkdownNode, MarkdownSpan>, nodes: InlineNode[]): void;
+
 /**
  * Renders a {@link MarkdownNode} to sanitized canonical HTML.
  *
@@ -1943,6 +2073,16 @@ export declare function renderHTML(node: MarkdownNode): string;
  */
 export declare function renderMarkdown(node: MarkdownNode): string;
 
+/**
+ * Renders one markdown node from its rendered children and escaped literal text.
+ *
+ * @example
+ * ```ts
+ * renderMarkdownNode({ element: 'thematicBreak' }, [], '', 0) // '---'
+ * ```
+ */
+export declare function renderMarkdownNode(current: MarkdownNode, children: readonly string[], literal: string, emphasis: number): string;
+
 /**
  * Rewrites a {@link MarkdownDocument} bottom-up (copy-on-write) — each node's children
  * are rewritten first (post-order), then `rewrite` is applied to the node itself; the
@@ -2094,6 +2234,16 @@ export declare function scanInlineSource(source: MarkdownSource, from: number, t
  */
 export declare function scanLink(source: string, start: number, to: number, depth?: number): LinkScan | undefined;
 
+/**
+ * Scans one inline construct and records the spans of its nested children.
+ *
+ * @example
+ * ```ts
+ * scanMarkdownInline({ text: '`x`', segments: [] }, 0, 3, new Map(), 0)?.end // 3
+ * ```
+ */
+export declare function scanMarkdownInline(source: MarkdownSource, index: number, to: number, spans: Map<MarkdownNode, MarkdownSpan>, depth: number): MarkdownInlineScan | undefined;
+
 /**
  * Slices derived markdown text and narrows each intersecting source segment to the
  * same text-relative range.
@@ -2157,6 +2307,19 @@ export declare function splitTableRow(row: string): readonly string[];
  */
 export declare function splitTableSources(row: MarkdownSource): readonly MarkdownSource[];
 
+/**
+ * Splits inline nodes into adjacent text runs and singleton non-text runs.
+ *
+ * @param nodes - The inline nodes in source order
+ * @returns The runs with their original node identities
+ *
+ * @example
+ * ```ts
+ * splitTextRuns([{ element: 'text', value: 'a' }]).length // 1
+ * ```
+ */
+export declare function splitTextRuns(nodes: readonly InlineNode[]): ReadonlyArray<readonly InlineNode[]>;
+
 /**
  * Checks whether the line at `index` starts a new block kind (heading / fence / thematic
  * break / blockquote / list / table) — the paragraph collector stops at such a line
@@ -2327,6 +2490,19 @@ element: LiteralShape<readonly ["thematicBreak"]>;
  */
 export declare function trimInlines(nodes: readonly InlineNode[]): readonly InlineNode[];
 
+/**
+ * Trims leading whitespace when an inline run starts with a text node.
+ *
+ * @param nodes - The inline run to trim
+ * @returns The run with its leading text trimmed or removed when empty
+ *
+ * @example
+ * ```ts
+ * trimLeading([{ element: 'text', value: ' a ' }]) // [{ element: 'text', value: 'a ' }]
+ * ```
+ */
+export declare function trimLeading(nodes: readonly InlineNode[]): readonly InlineNode[];
+
 /**
  * Trims an offset-bearing source without losing the coordinates of its retained text.
  *
@@ -2341,6 +2517,19 @@ export declare function trimInlines(nodes: readonly InlineNode[]): readonly Inli
  */
 export declare function trimSource(source: MarkdownSource): MarkdownSource;
 
+/**
+ * Trims trailing whitespace when an inline run ends with a text node.
+ *
+ * @param nodes - The inline run to trim
+ * @returns The run with its trailing text trimmed or removed when empty
+ *
+ * @example
+ * ```ts
+ * trimTrailing([{ element: 'text', value: ' a ' }]) // [{ element: 'text', value: ' a' }]
+ * ```
+ */
+export declare function trimTrailing(nodes: readonly InlineNode[]): readonly InlineNode[];
+
 /**
  * Resolves backslash escapes in a raw string to their literal characters — used for a
  * link `href` (which is not otherwise inline-parsed) and any plain text run.
@@ -2355,6 +2544,26 @@ export declare function trimSource(source: MarkdownSource): MarkdownSource;
  */
 export declare function unescapeText(text: string): string;
 
+/**
+ * Yields UTF-16 offsets and characters within a markdown scan window.
+ *
+ * @example
+ * ```ts
+ * Array.from(walkMarkdownCharacters('ab', 0, 2)) // [[0, 'a'], [1, 'b']]
+ * ```
+ */
+export declare function walkMarkdownCharacters(source: string, from: number, to: number): Generator<readonly [number, string], void, unknown>;
+
+/**
+ * Yields line offsets through a closable markdown scan iterator.
+ *
+ * @example
+ * ```ts
+ * Array.from(walkMarkdownLines(splitLines('a\nb'), 1)) // [1]
+ * ```
+ */
+export declare function walkMarkdownLines(lines: readonly MarkdownSource[], start: number): Generator<number, void, unknown>;
+
 /**
  * Walks a {@link MarkdownNode} depth-first, pre-order, root-inclusive — yields
  * the node itself, then recurses into its children (block children, list items,