@leadertechie/md2html 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/index.d.ts

@@ -1,7 +1,746 @@
-export * from './types';
-export * from './parser';
-export * from './renderer';
-export * from './lit-renderer';
-export * from './pipeline';
-export { LitRenderer as HTMLRenderer } from './lit-renderer';
-//# sourceMappingURL=index.d.ts.map
+import { LoggerInterface } from '@leadertechie/telemetry';
+
+/**
+ * Handles 'blockquote' tokens.
+ */
+export declare class BlockquoteHandler implements TokenHandler {
+    readonly type = "blockquote";
+    handle(token: Record<string, unknown>, ctx: ParseContext): {
+        type: "container";
+        attributes: {
+            tag: string;
+        };
+        children: ContentNode[];
+    };
+}
+
+/**
+ * Catch-all handler for any token type that doesn't have a dedicated handler.
+ * Wraps the raw token content in a container node so content is never silently lost.
+ * Reports the unhandled type via the context's reportUnhandled callback.
+ */
+export declare class CatchAllHandler implements TokenHandler {
+    readonly type = "*";
+    handle(token: Record<string, unknown>, ctx: ParseContext): {
+        type: "container";
+        content: string;
+        attributes: {
+            'data-unhandled': string;
+            tag: string;
+        };
+    };
+}
+
+/**
+ * Handles 'code' tokens (fenced code blocks).
+ */
+export declare class CodeHandler implements TokenHandler {
+    readonly type = "code";
+    handle(token: Record<string, unknown>, _ctx: ParseContext): {
+        type: "code";
+        content: string;
+        attributes: {
+            lang: string;
+        };
+    };
+}
+
+/**
+ * Built-in visitor: collect all nodes of a specific type.
+ */
+export declare function collectByType(root: ContentNode, type: string): ContentNode[];
+
+/**
+ * Walk a ContentNode tree and collect results from the visitor.
+ * The collector function is called for each node and returns a value or null.
+ */
+export declare function collectFromTree<T>(root: ContentNode, collector: (node: ContentNode, parent: ContentNode | null, depth: number) => T | null): T[];
+
+/**
+ * Built-in visitor: collect all headings with their levels.
+ */
+export declare function collectHeadings(root: ContentNode): Array<{
+    level: string;
+    text: string;
+    id?: string;
+}>;
+
+/**
+ * Built-in visitor: collect all images with their src/alt.
+ */
+export declare function collectImages(root: ContentNode): Array<{
+    src: string;
+    alt: string;
+}>;
+
+/**
+ * Sequentially applies multiple preprocessors to the markdown.
+ * Each preprocessor's output becomes the next one's input.
+ *
+ * This follows the Chain of Responsibility pattern — you can add
+ * new preprocessors without modifying existing code.
+ */
+export declare class CompositePreprocessor implements Preprocessor {
+    readonly name = "composite";
+    private processors;
+    constructor(processors?: Preprocessor[]);
+    /** Add a preprocessor to the chain. Returns `this` for fluent API. */
+    add(processor: Preprocessor): this;
+    /** Remove a preprocessor by name. */
+    remove(name: string): void;
+    /** Get the list of registered preprocessors. */
+    getProcessors(): ReadonlyArray<Preprocessor>;
+    process(markdown: string): string;
+}
+
+/**
+ * Sequentially applies multiple postprocessors to the token array.
+ */
+export declare class CompositeTokenPostprocessor implements TokenPostprocessor {
+    readonly name = "composite";
+    private processors;
+    constructor(processors?: TokenPostprocessor[]);
+    /** Add a postprocessor to the chain. Returns `this` for fluent API. */
+    add(processor: TokenPostprocessor): this;
+    /** Remove a postprocessor by name. */
+    remove(name: string): void;
+    /** Get the list of registered postprocessors. */
+    getProcessors(): ReadonlyArray<TokenPostprocessor>;
+    process(tokens: unknown[]): unknown[];
+}
+
+/**
+ * ContainerBlockHandler — handles custom :::tag#id.class container blocks.
+ *
+ * These are produced by the MarkdownParser's preprocessor which converts
+ * the ::: syntax into marked tokens before lexing, then reconstructs
+ * containerBlock tokens after lexing.
+ *
+ * The handler parses the specifier (e.g. "section#header.content") into
+ * tag name, id, and class(es), then recursively parses the inner tokens
+ * as normal markdown content, producing a container node with the
+ * specified HTML wrapper.
+ */
+export declare class ContainerBlockHandler implements TokenHandler {
+    readonly type = "containerBlock";
+    handle(token: Record<string, unknown>, ctx: ParseContext): ContentNode | null;
+}
+
+/**
+ * Collapses `<!-- md-container:... -->` and `<!-- /md-container -->` comment
+ * markers into nested `containerBlock` tokens with proper parent-child structure.
+ *
+ * Handles nesting depth up to any reasonable limit (depends on stack memory).
+ */
+export declare class ContainerBlockPostprocessor implements TokenPostprocessor {
+    readonly name = "container-blocks";
+    process(tokens: unknown[]): unknown[];
+}
+
+/**
+ * Converts `:::tag#id.class` container syntax into HTML comment markers
+ * that marked will preserve as HTML tokens, without affecting markdown parsing
+ * of the inner content.
+ *
+ * Example:
+ *   :::section#header
+ *   # Heading inside container
+ *   Some text
+ *   :::
+ *
+ * Becomes:
+ *   <!-- md-container:section#header -->
+ *   # Heading inside container
+ *   Some text
+ *   <!-- /md-container -->
+ */
+export declare class ContainerBlockPreprocessor implements Preprocessor {
+    readonly name = "container-blocks";
+    process(markdown: string): string;
+}
+
+export declare interface ContentNode {
+    type: ContentNodeType;
+    content?: string;
+    children?: ContentNode[];
+    attributes?: Record<string, unknown>;
+    className?: string;
+    src?: string;
+    alt?: string;
+    ordered?: boolean;
+    /** Raw HTML content for passthrough mode */
+    rawHTML?: string;
+    /** Scope anchor value for data-md-scope */
+    scope?: string;
+}
+
+export declare type ContentNodeType = 'text' | 'heading' | 'paragraph' | 'list' | 'list-item' | 'image' | 'code' | 'container' | 'strong' | 'emphasis' | 'link';
+
+/** Default postprocessor chain with the built-in container block support. */
+export declare function createDefaultPostprocessor(): CompositeTokenPostprocessor;
+
+/** Default preprocessor chain with the built-in container block support. */
+export declare function createDefaultPreprocessor(): CompositePreprocessor;
+
+/**
+ * Create a ParseContext from parser services.
+ *
+ * Each call creates a fresh context with its own metadata store,
+ * allowing for clean separation between recursive parse calls.
+ *
+ * The getters use closures to lazily access the parser's current state,
+ * so the context always reflects the latest configuration.
+ */
+export declare function createParseContext(services: ParserServices): ParseContext;
+
+/** Default allowed HTML tags for preserveRawHTML mode */
+export declare const defaultAllowedHTMLTags: string[];
+
+/**
+ * FrontmatterHandler — consumes YAML-ish frontmatter tokens produced by marked.lexer().
+ * Parses the raw YAML and stores key-value pairs onto ctx.metadata.
+ * Returns null so no HTML is emitted for frontmatter blocks.
+ *
+ * Handles both formats:
+ *   key: value
+ *   key:
+ *     - item1
+ *     - item2
+ */
+export declare class FrontmatterHandler implements TokenHandler {
+    readonly type = "frontmatter";
+    handle(token: Record<string, unknown>, ctx: ParseContext): null;
+}
+
+/**
+ * Handles 'heading' tokens (h1-h6).
+ */
+export declare class HeadingHandler implements TokenHandler {
+    readonly type = "heading";
+    handle(token: Record<string, unknown>, ctx: ParseContext): {
+        type: "heading";
+        content: string;
+        attributes: {
+            level: string;
+        };
+    };
+}
+
+/**
+ * Handles 'hr' tokens (horizontal rules).
+ */
+export declare class HrHandler implements TokenHandler {
+    readonly type = "hr";
+    handle(_token: Record<string, unknown>, _ctx: ParseContext): {
+        type: "container";
+        attributes: {
+            tag: string;
+        };
+    };
+}
+
+/**
+ * Handles 'html' tokens (inline or block-level raw HTML).
+ * In preserveRawHTML mode, passes through allowed HTML tags.
+ * Otherwise, stores the raw content as a container node.
+ */
+export declare class HtmlHandler implements TokenHandler {
+    readonly type = "html";
+    handle(token: Record<string, unknown>, ctx: ParseContext): {
+        type: "container";
+        rawHTML: string;
+        content?: undefined;
+    } | {
+        type: "container";
+        content: string;
+        rawHTML?: undefined;
+    } | null;
+}
+
+export declare class HTMLRenderer {
+    private config;
+    private strategyRegistry;
+    constructor(config?: StyleConfigV2);
+    /** Access the strategy registry for customization. */
+    get strategies(): RendererStrategyRegistry;
+    private hasClassConfig;
+    private getClass;
+    private generateHeadingId;
+    /**
+     * Get the scope attribute string for a node type.
+     * Returns empty string if emitScopeAnchors is disabled.
+     */
+    private getScopeAttr;
+    /**
+     * Get the CSS class for a container's tag-based rendering.
+     * Returns just the tag name since renderWithClass applies the prefix.
+     */
+    private getContainerClass;
+    private buildRenderContext;
+    renderNode(node: ContentNode): string;
+    renderNodes(nodes: ContentNode[]): string;
+    renderToHTMLString(nodes: ContentNode[]): string;
+    render(markdown: string): string;
+    getCustomCSS(): string;
+}
+
+/**
+ * Handles standalone 'image' tokens.
+ */
+export declare class ImageHandler implements TokenHandler {
+    readonly type = "image";
+    handle(token: Record<string, unknown>, ctx: ParseContext): {
+        type: "image";
+        src: string;
+        alt: string;
+    };
+}
+
+/**
+ * Handles standalone 'link' tokens (e.g., reference-style links, or links
+ * that appear outside paragraphs in certain edge cases).
+ */
+export declare class LinkHandler implements TokenHandler {
+    readonly type = "link";
+    handle(token: Record<string, unknown>, ctx: ParseContext): {
+        type: "link";
+        content: string;
+        attributes: {
+            title?: string | undefined;
+            href: string;
+        };
+    };
+}
+
+/**
+ * Handles 'list' tokens (ordered and unordered).
+ */
+export declare class ListHandler implements TokenHandler {
+    readonly type = "list";
+    handle(token: Record<string, unknown>, ctx: ParseContext): {
+        type: "list";
+        ordered: boolean;
+        children: {
+            type: "list-item";
+            content: string;
+        }[];
+    };
+}
+
+export declare interface MarkdownContent {
+    title: string;
+    metadata?: Record<string, unknown>;
+    content: ContentNode[];
+}
+
+export declare class MarkdownParser {
+    private imagePathPrefix;
+    private imageBaseUrl;
+    private preserveRawHTML;
+    private slotPattern;
+    private onSlot;
+    private errorRecovery;
+    private maxRecursionDepth;
+    private allowedHTMLTags;
+    private allowedAttributes;
+    private handlerRegistry;
+    private onUnhandledToken?;
+    private log;
+    private preprocessor;
+    private postprocessor;
+    constructor(options?: ParserOptions);
+    /** Access the handler registry for customization. */
+    get handlers(): TokenHandlerRegistry;
+    /** Access the preprocessor chain for customization. */
+    get preprocessors(): CompositePreprocessor;
+    /** Access the token postprocessor chain for customization. */
+    get postprocessors(): CompositeTokenPostprocessor;
+    private processImagePath;
+    private processInlineFormatting;
+    private processSlots;
+    /**
+     * Check if an attribute name is allowed for a given tag.
+     * Supports "data-*" wildcard prefix matching.
+     */
+    private isAttributeAllowed;
+    /**
+     * Check if an attribute name matches a list of allowed patterns.
+     * Supports "data-*" wildcard prefix matching.
+     */
+    private matchesAttributeList;
+    /**
+     * Filter attributes on an HTML tag, keeping only allowed ones.
+     */
+    private filterTagAttributes;
+    private processRawHTML;
+    /**
+     * Build a ParserServices object that bridges the parser's private methods
+     * to the ParseContext factory. This keeps context creation decoupled.
+     */
+    private buildServices;
+    /**
+     * Process an array of marked tokens into ContentNodes.
+     * When depth === 0 (root), creates a shared context that accumulates metadata.
+     * For recursive calls (depth > 0), creates a fresh context for each level.
+     */
+    private parseTokens;
+    parse(markdown: string, options?: ParseOptions): MarkdownContent;
+    parseToNodes(markdown: string, options?: ParseOptions): ContentNode[];
+}
+
+export declare class MarkdownPipeline {
+    private parser;
+    private renderer;
+    private config;
+    private log;
+    constructor(config?: PipelineConfigV2);
+    parse(markdown: string): ContentNode[];
+    parseWithMetadata(markdown: string): MarkdownContent;
+    render(nodes: ContentNode[]): string;
+    renderMarkdown(markdown: string): string;
+    renderPage(title: string, nodes: ContentNode[], options?: {
+        lang?: string;
+        charset?: string;
+    }): string;
+    getConfig(): Readonly<PipelineConfigV2>;
+    getCustomCSS(): string;
+}
+
+/**
+ * ContentNode factory — a builder API for creating ContentNode instances
+ * consistently across the codebase. Eliminates scattered object literals
+ * and provides type-safe construction with sensible defaults.
+ *
+ * Usage:
+ *   NodeFactory.heading('Hello', { level: '1' })
+ *   NodeFactory.paragraph('Some text')
+ *   NodeFactory.container({ tag: 'section', id: 'main' }, [children...])
+ */
+export declare class NodeFactory {
+    static heading(content: string, attributes?: Record<string, unknown>): ContentNode;
+    static paragraph(contentOrChildren: string | ContentNode[], children?: ContentNode[]): ContentNode;
+    static list(items: ContentNode[], ordered?: boolean, attributes?: Record<string, unknown>): ContentNode;
+    static listItem(content: string): ContentNode;
+    static image(src: string, alt?: string, className?: string): ContentNode;
+    static code(content: string, lang?: string): ContentNode;
+    static container(children?: ContentNode[], config?: {
+        tag?: string;
+        id?: string;
+        className?: string;
+        rawHTML?: string;
+        scope?: string;
+    }): ContentNode;
+    static text(content: string): ContentNode;
+    static strong(content: string): ContentNode;
+    static emphasis(content: string): ContentNode;
+    static link(href: string, content: string): ContentNode;
+}
+
+/**
+ * Strategy interface for rendering a specific ContentNode type to HTML.
+ * This is the renderer-side equivalent of TokenHandler — each node type
+ * gets its own strategy, eliminating the large switch statement.
+ *
+ * To add support for a new node type:
+ * 1. Create a class implementing NodeRendererStrategy
+ * 2. Register it with the RendererStrategyRegistry
+ */
+export declare interface NodeRendererStrategy {
+    /** The node type this strategy handles */
+    readonly type: string;
+    /** Render a node of this type to an HTML string */
+    render(node: ContentNode, renderChild: (child: ContentNode) => string, ctx: RenderContext): string;
+}
+
+/** Maps ContentNodeType to ScopeValue */
+export declare const nodeTypeToScope: Record<ContentNodeType, ScopeValue>;
+
+/**
+ * Visitor interface for traversing/walking a ContentNode AST.
+ *
+ * Implement this interface to inspect, collect, or transform nodes.
+ * Each method returns a ContentNode or null — returning null removes the node.
+ *
+ * Use cases:
+ *  - Collect all images for preloading
+ *  - Transform link URLs
+ *  - Validate AST structure
+ *  - Extract headings for ToC
+ *  - Inject attributes
+ */
+export declare interface NodeVisitor {
+    /** Called when entering a node, before visiting its children. */
+    enter?(node: ContentNode, parent: ContentNode | null, depth: number): ContentNode | null;
+    /** Called after visiting all children of the node. */
+    exit?(node: ContentNode, parent: ContentNode | null, depth: number): ContentNode | null;
+}
+
+/**
+ * Handles 'paragraph' tokens, including inline images, links, and raw HTML.
+ */
+export declare class ParagraphHandler implements TokenHandler {
+    readonly type = "paragraph";
+    handle(token: Record<string, unknown>, ctx: ParseContext): {
+        type: "paragraph";
+        children: ContentNode[];
+        content?: undefined;
+    } | {
+        type: "paragraph";
+        content: string;
+        children?: undefined;
+    } | null;
+}
+
+/**
+ * Context passed to every token handler, giving access to parser services.
+ */
+export declare interface ParseContext {
+    processImagePath(src: string): string;
+    processInlineFormatting(text: string): string;
+    processSlots(text: string): string;
+    processRawHTML(html: string): string;
+    parseTokens(tokens: unknown[], depth: number): ContentNode[];
+    preserveRawHTML: boolean;
+    errorRecovery: 'throw' | 'warn' | 'silent';
+    maxRecursionDepth: number;
+    /** Report an unhandled token type so callers can be notified */
+    reportUnhandled(type: string, token: Record<string, unknown>): void;
+    /**
+     * Shared metadata store populated by token handlers (e.g. FrontmatterHandler).
+     * After parsing, this object contains all frontmatter key-value pairs.
+     */
+    metadata: Record<string, unknown>;
+}
+
+export declare interface ParseOptions {
+    gfm?: boolean;
+    breaks?: boolean;
+    pedantic?: boolean;
+}
+
+export declare interface ParserOptions {
+    /** Optional telemetry logger */
+    logger?: LoggerInterface;
+    imagePathPrefix?: string;
+    imageBaseUrl?: string;
+    preserveRawHTML?: boolean;
+    slotPattern?: RegExp;
+    onSlot?: (name: string) => string;
+    errorRecovery?: 'throw' | 'warn' | 'silent';
+    maxRecursionDepth?: number;
+    allowedHTMLTags?: string[];
+    /**
+     * Allowed HTML attributes per tag for preserveRawHTML mode.
+     * Key "*" applies to all tags. Key "tag" applies to specific tags.
+     * Supports "data-*" wildcard prefix matching.
+     */
+    allowedAttributes?: Record<string, string[]>;
+    /**
+     * Callback invoked when a token type has no dedicated handler.
+
+     * The catch-all handler will still produce a container node for the content,
+     * but this callback allows callers to log, warn, or track unhandled types.
+     *
+     * @param type - The unhandled token type name (e.g. 'table', 'def')
+     * @param token - The raw marked token
+     */
+    onUnhandledToken?: (type: string, token: Record<string, unknown>) => void;
+}
+
+/**
+ * Services needed by the ParseContext factory.
+ * This is the interface the parser exposes to context creation.
+ */
+export declare interface ParserServices {
+    preserveRawHTML: boolean;
+    errorRecovery: 'throw' | 'warn' | 'silent';
+    maxRecursionDepth: number;
+    processImagePath(src: string): string;
+    processInlineFormatting(text: string): string;
+    processSlots(text: string): string;
+    processRawHTML(html: string): string;
+    parseTokens(tokens: unknown[], depth: number): ContentNode[];
+    onUnhandledToken?: (type: string, token: Record<string, unknown>) => void;
+}
+
+export declare interface PipelineConfig {
+    imagePathPrefix?: string;
+    imageBaseUrl?: string;
+    parseOptions?: ParseOptions;
+    styleOptions?: StyleConfig | StyleConfigV2;
+}
+
+/**
+ * v2: Extended PipelineConfig with raw HTML passthrough, slot hooks, and error recovery.
+ */
+export declare interface PipelineConfigV2 extends PipelineConfig {
+    /** Optional telemetry logger for observability. Pass your own or a default console logger is used. */
+    logger?: LoggerInterface;
+    styleOptions?: StyleConfigV2;
+    /** Preserve raw HTML tags in markdown (img, style, div, span, etc.) (default: false) */
+    preserveRawHTML?: boolean;
+    /** Regex pattern for slot placeholders like [[SLOT_NAME]] (default: /\[\[(.*?)\]\]/g) */
+    slotPattern?: RegExp;
+    /** Callback to resolve slot values. Called with the slot name, returns replacement string. */
+    onSlot?: (name: string) => string;
+    /** Error recovery mode (default: 'throw' — backward compatible) */
+    errorRecovery?: 'throw' | 'warn' | 'silent';
+    /** Max recursion depth to prevent stack overflow (default: 100) */
+    maxRecursionDepth?: number;
+    /** Additional allowed HTML tags for preserveRawHTML mode */
+    allowedHTMLTags?: string[];
+    /**
+     * Allowed HTML attributes per tag for preserveRawHTML mode.
+     * Key "*" applies to all tags. Key "tag" applies to specific tags.
+     * Supports "data-*" wildcard prefix matching.
+     * Example: { "*": ["id", "class"], "script": ["type", "src"] }
+     */
+    allowedAttributes?: Record<string, string[]>;
+}
+
+/**
+ * Markdown Preprocessor
+ *
+ * Single responsibility: Transform markdown text before it reaches the lexer.
+ * Currently handles `:::` container block syntax conversion to HTML comments.
+ *
+ * This is the first stage in the parsing pipeline.
+ *
+ * Extensibility: Additional preprocessors can be composed via the
+ * CompositePipeline pattern (see composite-pipeline.ts).
+ */
+export declare interface Preprocessor {
+    /** Name identifier for logging/debugging */
+    readonly name: string;
+    /** Transform the markdown before lexing */
+    process(markdown: string): string;
+}
+
+/**
+ * Context passed to every render strategy, providing access to
+ * shared rendering services and configuration.
+ */
+export declare interface RenderContext {
+    classPrefix: string;
+    addHeadingIds: boolean;
+    emitScopeAnchors: boolean;
+    customCSS: string;
+    getClass(baseClass: string, nodeClass?: string): string;
+    getScopeAttr(node: ContentNode): string;
+    generateHeadingId(content?: string): string;
+    getContainerClass(tag: string): string;
+    hasClassConfig(): boolean;
+}
+
+/**
+ * Registry of renderer strategies. Maps ContentNode types to their
+ * rendering strategy. This is the renderer-side equivalent of
+ * TokenHandlerRegistry.
+ *
+ * The registry uses a two-tier lookup:
+ * 1. Check for a dedicated strategy by node type
+ * 2. Fall back to the catch-all strategy (registered as '*')
+ */
+export declare class RendererStrategyRegistry {
+    private strategies;
+    private fallback;
+    constructor();
+    /** Register a strategy for a node type. Overrides any existing strategy. */
+    register(strategy: NodeRendererStrategy): void;
+    /** Unregister a strategy by node type. */
+    unregister(type: string): void;
+    /** Get a strategy for the given node type, falling back to catch-all. */
+    get(type: string): NodeRendererStrategy;
+    /** Check if a dedicated strategy exists for the given node type. */
+    has(type: string): boolean;
+    /** Get all registered dedicated strategy types. */
+    get types(): string[];
+    /** Replace the fallback strategy. */
+    setFallback(strategy: NodeRendererStrategy): void;
+}
+
+/** Scope hierarchy values for data-md-scope */
+export declare type ScopeValue = 'root' | 'heading' | 'paragraph' | 'list' | 'list-item' | 'image' | 'code' | 'strong' | 'emphasis' | 'link' | 'container';
+
+export declare interface StyleConfig {
+    classPrefix?: string;
+    customCSS?: string;
+    addHeadingIds?: boolean;
+}
+
+/**
+ * v2: Extended StyleConfig with scope anchor support.
+ */
+export declare interface StyleConfigV2 extends StyleConfig {
+    /** Emit data-md-scope attributes for CSS @scope anchoring (default: false) */
+    emitScopeAnchors?: boolean;
+}
+
+/**
+ * A token handler knows how to convert a single marked token into a ContentNode.
+ * Handlers are registered by token type name in the handler registry.
+ */
+export declare interface TokenHandler {
+    /** The marked token type this handler processes (e.g. 'heading', 'paragraph') */
+    readonly type: string;
+    /** Convert a marked token to a ContentNode (or null to skip) */
+    handle(token: Record<string, unknown>, ctx: ParseContext): ContentNode | null;
+}
+
+/**
+ * Registry of token handlers. Handlers can be added/overridden externally
+ * to extend the parser without modifying its internals.
+ *
+ * The registry uses a two-tier lookup:
+ * 1. First, check for a dedicated handler by token type name
+ * 2. If none found, fall back to the catch-all handler (registered as '*')
+ *
+ * The catch-all handler ensures no content is silently lost — unhandled
+ * token types are wrapped in a container node with `data-unhandled` attribute.
+ */
+export declare class TokenHandlerRegistry {
+    private handlers;
+    private catchAll;
+    constructor();
+    /** Register a handler. Overrides any existing handler for the same token type. */
+    register(handler: TokenHandler): void;
+    /** Unregister a handler by token type. */
+    unregister(type: string): void;
+    /**
+     * Get a handler for the given token type.
+     * Falls back to the catch-all handler if no dedicated handler is registered.
+     */
+    get(type: string): TokenHandler;
+    /** Check if a dedicated handler exists for the given token type (excludes catch-all). */
+    has(type: string): boolean;
+    /** Get all registered dedicated handler types. */
+    get types(): string[];
+    /** Replace the catch-all handler with a custom implementation. */
+    setCatchAll(handler: TokenHandler): void;
+    /** Get the current catch-all handler. */
+    getCatchAll(): TokenHandler;
+}
+
+/**
+ * Token Postprocessor
+ *
+ * Single responsibility: Transform the flat array of marked tokens into
+ * a structured tree. Currently handles collapsing HTML comment markers
+ * (from container block preprocessing) into structured `containerBlock` tokens.
+ *
+ * This is the third stage in the parsing pipeline (after lexing).
+ */
+export declare interface TokenPostprocessor {
+    /** Name identifier for logging/debugging */
+    readonly name: string;
+    /** Transform an array of tokens into an array of (possibly restructured) tokens */
+    process(tokens: unknown[]): unknown[];
+}
+
+/**
+ * Walk a ContentNode tree, applying a visitor at each node.
+ * Returns a new tree (immutable) — does not mutate the original.
+ */
+export declare function walkTree(root: ContentNode, visitor: NodeVisitor): ContentNode;
+
+export { }