@leadertechie/md2html 0.1.0-alpha.17 → 0.1.0-alpha.19

package/README.md

@@ -189,9 +189,94 @@ Additional safety with `maxRecursionDepth` (default: 100) to prevent stack overf
 
 ## Architecture (v2)
 
-### Strategy Pattern Token Handlers
+The pipeline is built from modular stages, each with a clear design pattern and single responsibility:
 
-The parser uses a **strategy pattern** with a `TokenHandlerRegistry`. Each marked token type has its own handler class:
+```
+Markdown String
+      │
+      ▼
+┌──────────────────────────┐
+│ 1. Preprocessor Chain    │  Chain of Responsibility
+│    (preprocessor.ts)     │  Transforms raw markdown before lexing
+│    • ContainerBlock      │  (e.g., ::: containers → HTML comments)
+└──────────┬───────────────┘
+           │
+           ▼
+┌──────────────────────────┐
+│ 2. marked.lexer()        │  Third-party lexer
+└──────────┬───────────────┘
+           │
+           ▼
+┌──────────────────────────┐
+│ 3. Token Postprocessor   │  Chain of Responsibility
+│    (token-postprocessor  │  Restructures flat tokens → nested tree
+│    .ts)                  │  (e.g., comments → containerBlock)
+│    • ContainerBlock      │
+└──────────┬───────────────┘
+           │
+           ▼
+┌──────────────────────────┐
+│ 4. Token Handlers        │  Strategy Pattern
+│    (handlers/)           │  Each marked token type has a dedicated
+│    • TokenHandlerRegistry│  handler, registered by type name.
+│    • CatchAllHandler     │  Extensible at runtime via registry.
+└──────────┬───────────────┘
+           │
+           ▼
+      ContentNode[]
+      (AST)
+           │
+           ▼
+┌──────────────────────────┐
+│ 5. Renderer              │  Strategy Pattern
+│    (renderer-strategies  │  Each ContentNode type has its own
+│    .ts / lit-strategies  │  render strategy — choose between:
+│    .ts)                  │  • HTMLRenderer (plain HTML strings)
+│    • NodeRendererStrategy│  • LitRenderer (Lit TemplateResult)
+│    • LitNodeRendererStrat│
+└──────────────────────────┘
+```
+
+### 1. Preprocessing (`preprocessor.ts`)
+
+The `CompositePreprocessor` chains `Preprocessor` transforms that run on raw markdown **before** lexing. Built-in:
+
+- **`ContainerBlockPreprocessor`** — converts `:::tag#id.class` fences to `<!-- md-container:... -->` HTML comment markers, so `marked` preserves them without affecting inner markdown parsing
+
+The chain is extensible:
+
+```typescript
+import { MarkdownParser, Preprocessor } from '@leadertechie/md2html';
+
+class EmojiPreprocessor implements Preprocessor {
+  readonly name = 'emoji';
+  process(markdown: string): string {
+    return markdown.replace(':smile:', '😊');
+  }
+}
+
+const parser = new MarkdownParser();
+parser.preprocessors.add(new EmojiPreprocessor());
+```
+
+### 2. Token Postprocessing (`token-postprocessor.ts`)
+
+The `CompositeTokenPostprocessor` chains `TokenPostprocessor` transforms that run on the flat token array **after** lexing. Built-in:
+
+- **`ContainerBlockPostprocessor`** — collapses `<!-- md-container:... -->` / `<!-- /md-container -->` markers into nested `containerBlock` tokens with proper parent-child structure (handles arbitrary nesting depth)
+
+Custom postprocessors:
+
+```typescript
+parser.postprocessors.add({
+  name: 'filter-unwanted',
+  process: (tokens) => tokens.filter(t => (t as any).type !== 'html')
+});
+```
+
+### 3. Token Handling — Strategy Pattern (`handlers/`)
+
+Each marked token type has its own `TokenHandler` class, registered in the `TokenHandlerRegistry`:
 
 ```
 src/handlers/
@@ -205,6 +290,10 @@ src/handlers/
 ├── hr-handler.ts         # <hr>
 ├── blockquote-handler.ts # <blockquote>
 ├── html-handler.ts       # raw HTML passthrough
+├── link-handler.ts       # <a>
+├── frontmatter-handler.ts# YAML frontmatter metadata
+├── container-block-      # ::: container blocks
+│   handler.ts
 └── catchall-handler.ts   # fallback for unregistered types
 ```
 
@@ -253,6 +342,67 @@ const parser = new MarkdownParser({
 });
 ```
 
+### 4. Rendering — Strategy Pattern (`renderer-strategies.ts`, `lit-strategies.ts`)
+
+The AST renderers use the same Strategy + Registry pattern as the token handlers:
+
+- **`HTMLRenderer`** — produces plain HTML strings. Uses `NodeRendererStrategy` / `RendererStrategyRegistry` for each node type. Supports `classPrefix`, `addHeadingIds`, and `emitScopeAnchors` styling.
+- **`LitRenderer`** — produces Lit `TemplateResult` objects. Uses `LitNodeRendererStrategy` / `LitStrategyRegistry`. Perfect for Lit web components.
+
+Both registries are publicly accessible for customization:
+
+```typescript
+import { HTMLRenderer, NodeRendererStrategy } from '@leadertechie/md2html';
+
+const renderer = new HTMLRenderer({ classPrefix: 'my-' });
+
+// Register a custom strategy
+renderer.strategies.register({
+  type: 'custom',
+  render: (node, renderChild, ctx) => `<my-el>${node.content}</my-el>`
+});
+```
+
+The `LitRenderer.renderToHTMLString()` delegates to `HTMLRenderer` to avoid duplicating string rendering logic.
+
+### 5. Context Factory (`context-factory.ts`)
+
+The `createParseContext()` pure function separates context construction from the parser class. It bridges parser services (image processing, slot resolution, HTML sanitization) to token handlers via the `ParserServices` interface. This makes the context testable in isolation and decouples handler logic from parser internals.
+
+### Source Map
+
+```
+src/
+├── parser.ts              # Orchestrator: coordinates pre/post-processing + token handling
+├── preprocessor.ts        # Chain of Responsibility: markdown transforms before lexing
+├── token-postprocessor.ts # Chain of Responsibility: token transforms after lexing
+├── context-factory.ts     # Factory: creates ParseContext for token handlers
+├── handlers/              # Strategy: per-token-type ContentNode producers
+│   ├── types.ts
+│   ├── registry.ts
+│   ├── heading-handler.ts
+│   ├── paragraph-handler.ts
+│   ├── list-handler.ts
+│   ├── image-handler.ts
+│   ├── code-handler.ts
+│   ├── hr-handler.ts
+│   ├── blockquote-handler.ts
+│   ├── html-handler.ts
+│   ├── link-handler.ts
+│   ├── frontmatter-handler.ts
+│   ├── container-block-handler.ts
+│   └── catchall-handler.ts
+├── renderer.ts            # HTMLRenderer: transforms ContentNodes to plain HTML
+├── renderer-strategies.ts # Strategy: per-node-type HTML string renderers
+├── lit-renderer.ts        # LitRenderer: transforms ContentNodes to Lit TemplateResult
+├── lit-strategies.ts      # Strategy: per-node-type Lit TemplateResult renderers
+├── visitor.ts             # Visitor: tree traversal utilities
+├── factory.ts             # NodeFactory: ContentNode builder API
+├── pipeline.ts            # Facade: high-level MarkdownPipeline API
+├── types.ts               # Core types: ContentNode, MarkdownContent, configs
+└── telemetry-init.ts      # Shared logger initialization
+```
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { LoggerInterface } from '@leadertechie/telemetry';
+import { TemplateResult } from 'lit';
+
 /**
  * Handles 'blockquote' tokens.
  */
@@ -71,6 +74,42 @@ export declare function collectImages(root: ContentNode): Array<{
     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.
  *
@@ -88,6 +127,39 @@ export declare class ContainerBlockHandler implements TokenHandler {
     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;
@@ -105,6 +177,23 @@ export declare interface ContentNode {
 
 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[];
 
@@ -208,6 +297,22 @@ export declare class ImageHandler implements TokenHandler {
     };
 }
 
+/**
+ * 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).
  */
@@ -223,6 +328,118 @@ export declare class ListHandler implements TokenHandler {
     };
 }
 
+export declare class LitCodeStrategy implements LitNodeRendererStrategy {
+    readonly type = "code";
+    render(node: ContentNode, _renderChild: (child: ContentNode) => TemplateResult): TemplateResult;
+}
+
+export declare class LitContainerStrategy implements LitNodeRendererStrategy {
+    readonly type = "container";
+    render(node: ContentNode, renderChild: (child: ContentNode) => TemplateResult): TemplateResult;
+}
+
+export declare class LitEmphasisStrategy implements LitNodeRendererStrategy {
+    readonly type = "emphasis";
+    render(node: ContentNode, _renderChild: (child: ContentNode) => TemplateResult): TemplateResult;
+}
+
+export declare class LitFallbackStrategy implements LitNodeRendererStrategy {
+    readonly type = "*";
+    render(_node: ContentNode, _renderChild: (child: ContentNode) => TemplateResult): TemplateResult;
+}
+
+export declare class LitHeadingStrategy implements LitNodeRendererStrategy {
+    readonly type = "heading";
+    render(node: ContentNode, _renderChild: (child: ContentNode) => TemplateResult): TemplateResult;
+}
+
+export declare class LitImageStrategy implements LitNodeRendererStrategy {
+    readonly type = "image";
+    render(node: ContentNode, _renderChild: (child: ContentNode) => TemplateResult): TemplateResult;
+}
+
+export declare class LitLinkStrategy implements LitNodeRendererStrategy {
+    readonly type = "link";
+    render(node: ContentNode, _renderChild: (child: ContentNode) => TemplateResult): TemplateResult;
+}
+
+export declare class LitListItemStrategy implements LitNodeRendererStrategy {
+    readonly type = "list-item";
+    render(node: ContentNode, _renderChild: (child: ContentNode) => TemplateResult): TemplateResult;
+}
+
+export declare class LitListStrategy implements LitNodeRendererStrategy {
+    readonly type = "list";
+    render(node: ContentNode, renderChild: (child: ContentNode) => TemplateResult): TemplateResult;
+}
+
+export declare interface LitNodeRendererStrategy {
+    /** The ContentNode type this strategy handles */
+    readonly type: string;
+    /** Render a node to a Lit TemplateResult */
+    render(node: ContentNode, renderChild: (child: ContentNode) => TemplateResult): TemplateResult;
+}
+
+export declare class LitParagraphStrategy implements LitNodeRendererStrategy {
+    readonly type = "paragraph";
+    render(node: ContentNode, renderChild: (child: ContentNode) => TemplateResult): TemplateResult;
+}
+
+export declare class LitRenderer {
+    private strategyRegistry;
+    /** Lazily created HTMLRenderer for string output, sharing the same config */
+    private htmlRenderer?;
+    constructor();
+    /** Access the strategy registry for customization. */
+    get strategies(): LitStrategyRegistry;
+    /**
+     * Render a single node to a Lit TemplateResult.
+     */
+    renderNode(node: ContentNode): TemplateResult;
+    /**
+     * Render an array of nodes to a single Lit TemplateResult.
+     */
+    renderNodes(nodes: ContentNode[]): TemplateResult;
+    /**
+     * Render nodes to a plain HTML string.
+     * Delegates to HTMLRenderer to avoid duplicating string rendering logic.
+     *
+     * Note: Uses default HTMLRenderer config (no classPrefix, scope anchors,
+     * or heading IDs). For full HTML rendering with those features,
+     * use HTMLRenderer directly.
+     */
+    renderToHTMLString(nodes: ContentNode[]): string;
+}
+
+/**
+ * Registry of Lit renderer strategies.
+ *
+ * Two-tier lookup:
+ * 1. Dedicated strategy by node type
+ * 2. Fallback to a catch-all strategy (default: renders empty)
+ */
+export declare class LitStrategyRegistry {
+    private strategies;
+    private fallback;
+    constructor();
+    register(strategy: LitNodeRendererStrategy): void;
+    unregister(type: string): void;
+    get(type: string): LitNodeRendererStrategy;
+    has(type: string): boolean;
+    get types(): string[];
+    setFallback(strategy: LitNodeRendererStrategy): void;
+}
+
+export declare class LitStrongStrategy implements LitNodeRendererStrategy {
+    readonly type = "strong";
+    render(node: ContentNode, _renderChild: (child: ContentNode) => TemplateResult): TemplateResult;
+}
+
+export declare class LitTextStrategy implements LitNodeRendererStrategy {
+    readonly type = "text";
+    render(node: ContentNode, _renderChild: (child: ContentNode) => TemplateResult): TemplateResult;
+}
+
 export declare interface MarkdownContent {
     title: string;
     metadata?: Record<string, unknown>;
@@ -241,9 +458,16 @@ export declare class MarkdownParser {
     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;
@@ -263,41 +487,16 @@ export declare class MarkdownParser {
     private filterTagAttributes;
     private processRawHTML;
     /**
-     * Build the ParseContext that is passed to every token handler.
-     * This is the bridge between the parser's private services and the handlers.
+     * Build a ParserServices object that bridges the parser's private methods
+     * to the ParseContext factory. This keeps context creation decoupled.
      */
-    private createContext;
+    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;
-    /**
-     * Pre-process markdown: convert `:::tag#id.class` container syntax
-     * into HTML comment markers that marked will preserve as html tokens,
-     * but won't affect 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 -->
-     */
-    private preprocessContainerBlocks;
-    /**
-     * Post-process marked tokens to collapse container block markers
-     * into structured containerBlock tokens with proper nesting.
-     *
-     * This handles nesting depth up to maxRecursionDepth.
-     */
-    private postprocessTokens;
     parse(markdown: string, options?: ParseOptions): MarkdownContent;
     parseToNodes(markdown: string, options?: ParseOptions): ContentNode[];
 }
@@ -306,6 +505,7 @@ export declare class MarkdownPipeline {
     private parser;
     private renderer;
     private config;
+    private log;
     constructor(config?: PipelineConfigV2);
     parse(markdown: string): ContentNode[];
     parseWithMetadata(markdown: string): MarkdownContent;
@@ -389,7 +589,7 @@ export declare interface NodeVisitor {
 }
 
 /**
- * Handles 'paragraph' tokens, including inline images and raw HTML.
+ * Handles 'paragraph' tokens, including inline images, links, and raw HTML.
  */
 export declare class ParagraphHandler implements TokenHandler {
     readonly type = "paragraph";
@@ -432,6 +632,8 @@ export declare interface ParseOptions {
 }
 
 export declare interface ParserOptions {
+    /** Optional telemetry logger */
+    logger?: LoggerInterface;
     imagePathPrefix?: string;
     imageBaseUrl?: string;
     preserveRawHTML?: boolean;
@@ -458,6 +660,22 @@ export declare interface ParserOptions {
     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;
@@ -469,6 +687,8 @@ export declare interface PipelineConfig {
  * 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;
@@ -491,6 +711,24 @@ export declare interface PipelineConfigV2 extends PipelineConfig {
     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.
@@ -596,6 +834,22 @@ export declare class TokenHandlerRegistry {
     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.