md2x 0.1.0

package/dist/types/src/core/markdown-document.d.ts

@@ -0,0 +1,286 @@
+/**
+ * Markdown Document - In-memory document structure for incremental updates
+ *
+ * This module provides a pure data structure for managing markdown documents
+ * without any DOM dependencies. It handles:
+ * - Block-level parsing and tracking with stable IDs
+ * - Content hashing for change detection
+ * - Incremental diff computation
+ * - Virtual DOM with precise DOM operation commands
+ * - Line number mapping for scroll sync
+ */
+/**
+ * Block metadata stored in memory
+ */
+export interface BlockMeta {
+    /** Unique block ID (stable across updates for same content position) */
+    id: string;
+    /** Block hash (content-based) */
+    hash: string;
+    /** Source line number (0-based) */
+    startLine: number;
+    /** Number of source lines */
+    lineCount: number;
+    /** Raw markdown content */
+    content: string;
+    /** Rendered HTML (if available) */
+    html?: string;
+    /** Whether this block contains async placeholder */
+    hasPlaceholder?: boolean;
+}
+/**
+ * Block attributes for DOM elements
+ */
+export interface BlockAttrs {
+    'data-block-id': string;
+    'data-block-hash': string;
+    'data-line': number;
+    'data-line-count': number;
+}
+/**
+ * DOM operation command - platform-agnostic instructions for updating the DOM
+ */
+export type DOMCommand = {
+    type: 'clear';
+} | {
+    type: 'append';
+    blockId: string;
+    html: string;
+    attrs: BlockAttrs;
+} | {
+    type: 'insertBefore';
+    blockId: string;
+    html: string;
+    refId: string;
+    attrs: BlockAttrs;
+} | {
+    type: 'remove';
+    blockId: string;
+} | {
+    type: 'replace';
+    blockId: string;
+    html: string;
+    attrs: BlockAttrs;
+} | {
+    type: 'updateAttrs';
+    blockId: string;
+    attrs: Partial<BlockAttrs>;
+};
+/**
+ * Result of computing DOM commands
+ */
+export interface DOMCommandResult {
+    commands: DOMCommand[];
+    stats: {
+        kept: number;
+        inserted: number;
+        removed: number;
+        replaced: number;
+    };
+}
+/**
+ * Normalize math blocks in markdown text
+ * Converts single-line $$...$$ to multi-line format for proper display math rendering
+ */
+export declare function normalizeMathBlocks(markdown: string): string;
+/**
+ * In-memory markdown document with virtual DOM support
+ */
+export declare class MarkdownDocument {
+    private blocks;
+    private blockIdMap;
+    private rawContent;
+    private normalizedContent;
+    private idCounter;
+    /**
+     * Create a new document (optionally with initial content)
+     */
+    constructor(markdown?: string);
+    /**
+     * Rebuild the blockId -> index map
+     */
+    private rebuildBlockIdMap;
+    /**
+     * Get all blocks
+     */
+    getBlocks(): readonly BlockMeta[];
+    /**
+     * Get block by index
+     */
+    getBlock(index: number): BlockMeta | undefined;
+    /**
+     * Get block by ID (O(1) lookup)
+     */
+    getBlockById(id: string): BlockMeta | undefined;
+    /**
+     * Get block index by ID (O(1) lookup)
+     */
+    getBlockIndexById(id: string): number;
+    /**
+     * Get block count
+     */
+    get blockCount(): number;
+    /**
+     * Get raw markdown content
+     */
+    getRawContent(): string;
+    /**
+     * Get normalized content (math blocks expanded)
+     */
+    getNormalizedContent(): string;
+    /**
+     * Find block by line number
+     */
+    findBlockByLine(line: number): {
+        block: BlockMeta;
+        index: number;
+    } | null;
+    /**
+     * Get total line count of the document
+     */
+    getTotalLineCount(): number;
+    /**
+     * Get line position info for scroll sync.
+     * Returns the block containing the line and progress within that block.
+     *
+     * @param line - Source line number (can be fractional for sub-line precision)
+     * @returns Object with block info and progress (0-1) within block, or null if out of range
+     */
+    getLinePosition(line: number): {
+        block: BlockMeta;
+        index: number;
+        progress: number;
+    } | null;
+    /**
+     * Calculate line number from block index and progress within block.
+     * Inverse of getLinePosition.
+     *
+     * @param index - Block index
+     * @param progress - Progress within block (0-1)
+     * @returns Line number (with fractional part)
+     */
+    getLineFromPosition(index: number, progress: number): number;
+    /**
+     * Find surrounding blocks for a given line (for interpolation).
+     * Returns previous and next blocks relative to the line.
+     */
+    getSurroundingBlocks(line: number): {
+        previous?: {
+            block: BlockMeta;
+            index: number;
+        };
+        next?: {
+            block: BlockMeta;
+            index: number;
+        };
+    };
+    /**
+     * Calculate source line number from block ID and progress within block.
+     * Used by scroll sync: DOM provides blockId + pixel progress, we compute line.
+     *
+     * @param blockId - Block ID from DOM element's data-block-id
+     * @param progress - Progress within block (0-1) based on pixel position
+     * @returns Line number (with fractional part), or null if block not found
+     */
+    getLineFromBlockId(blockId: string, progress?: number): number | null;
+    /**
+     * Get block position for a source line number.
+     * Used by scroll sync: editor provides line, we compute blockId + progress for DOM scroll.
+     *
+     * @param line - Source line number (can be fractional)
+     * @returns Object with blockId and progress (0-1) within block, or null if out of range
+     */
+    getBlockPositionFromLine(line: number): {
+        blockId: string;
+        progress: number;
+    } | null;
+    /**
+     * Update document content and return DOM commands for incremental update
+     */
+    update(markdown: string): DOMCommandResult;
+    /**
+     * Generate a new unique block ID
+     */
+    private generateNewId;
+    /**
+     * Compute diff between old and new block arrays using LCS-based algorithm
+     */
+    private computeDiff;
+    /**
+     * Generate DOM commands from diff operations
+     */
+    private generateDOMCommands;
+    /**
+     * Get block attributes for DOM element
+     */
+    private getBlockAttrs;
+    /**
+     * Set rendered HTML for a block by index
+     */
+    setBlockHtml(index: number, html: string): void;
+    /**
+     * Set rendered HTML for a block by ID
+     */
+    setBlockHtmlById(id: string, html: string): void;
+    /**
+     * Get blocks that need rendering (no cached HTML or has placeholder)
+     */
+    getBlocksNeedingRender(): {
+        block: BlockMeta;
+        index: number;
+    }[];
+    /**
+     * Get all block IDs in order
+     */
+    getBlockIds(): string[];
+    /**
+     * Clear all cached HTML
+     */
+    clearHtmlCache(): void;
+    /**
+     * Get full HTML content (all blocks concatenated)
+     */
+    getFullHtml(): string;
+    /**
+     * Wrap block HTML with container div and attributes
+     */
+    wrapBlockHtml(block: BlockMeta): string;
+    /**
+     * Export document state for serialization
+     */
+    toJSON(): {
+        blocks: Omit<BlockMeta, 'html' | 'hasPlaceholder'>[];
+        rawContent: string;
+        idCounter: number;
+    };
+    /**
+     * Create document from serialized state
+     */
+    static fromJSON(data: {
+        blocks: Omit<BlockMeta, 'html' | 'hasPlaceholder'>[];
+        rawContent: string;
+        idCounter: number;
+    }): MarkdownDocument;
+}
+/**
+ * Extract title from markdown content
+ */
+export declare function extractTitle(markdown: string): string | null;
+/**
+ * Heading info for TOC
+ */
+export interface HeadingInfo {
+    level: number;
+    text: string;
+    id: string;
+    line: number;
+}
+/**
+ * Extract headings from parsed blocks (without DOM)
+ */
+export declare function extractHeadingsFromBlocks(blocks: readonly BlockMeta[]): HeadingInfo[];
+/**
+ * Execute DOM commands on a container element
+ * This is the only function that touches the real DOM
+ */
+export declare function executeDOMCommands(container: HTMLElement, commands: DOMCommand[], document: Document): void;

package/dist/types/src/core/markdown-processor.d.ts

@@ -0,0 +1,228 @@
+import { type Processor } from 'unified';
+import { type BlockWithLine } from './markdown-block-splitter';
+import type { TranslateFunction, TaskStatus, TaskData, PluginRenderer, AsyncTaskPlugin } from '../types/index';
+export type { TranslateFunction };
+/**
+ * Task context for cancellation
+ */
+interface TaskContext {
+    cancelled: boolean;
+}
+/**
+ * Plugin interface for async tasks
+ */
+type Plugin = AsyncTaskPlugin;
+/**
+ * Async task interface
+ */
+interface AsyncTask {
+    id: string;
+    callback: (data: TaskData) => Promise<void>;
+    data: TaskData;
+    type: string;
+    status: TaskStatus;
+    error: Error | null;
+    context: TaskContext;
+    setReady: () => void;
+    setError: (error: Error) => void;
+}
+/**
+ * Normalize math blocks in markdown text
+ * Converts single-line $$...$$ to multi-line format for proper display math rendering
+ * @param markdown - Raw markdown content
+ * @returns Normalized markdown
+ */
+export declare function normalizeMathBlocks(markdown: string): string;
+export type { BlockWithLine };
+/**
+ * Split markdown into semantic blocks (paragraphs, code blocks, tables, etc.)
+ * Each block is a complete markdown element that can be processed independently.
+ * @param markdown - Raw markdown content
+ * @returns Array of markdown blocks
+ */
+export declare function splitMarkdownIntoBlocks(markdown: string): string[];
+/**
+ * Split markdown into semantic blocks with source line numbers.
+ * Each block includes its starting line number for scroll sync.
+ * @param markdown - Raw markdown content
+ * @returns Array of blocks with line info
+ */
+export declare function splitMarkdownIntoBlocksWithLines(markdown: string): BlockWithLine[];
+/**
+ * Escape HTML special characters
+ * @param text - Text to escape
+ * @returns Escaped text
+ */
+export declare function escapeHtml(text: string): string;
+/**
+ * Check if a block is a frontmatter block
+ * Frontmatter must start and end with ---, and typically appears at line 0
+ */
+export declare function isFrontmatterBlock(block: string, startLine: number): boolean;
+/**
+ * Parse frontmatter YAML content (simple key: value parsing)
+ */
+export declare function parseFrontmatter(block: string): Record<string, string>;
+/**
+ * Render frontmatter as HTML table
+ */
+export declare function renderFrontmatterAsTable(data: Record<string, string>): string;
+/**
+ * Render frontmatter as pre block (raw format)
+ */
+export declare function renderFrontmatterAsRaw(block: string): string;
+/**
+ * Validate URL values and block javascript-style protocols
+ * @param url - URL to validate
+ * @returns True when URL is considered safe
+ */
+export declare function isSafeUrl(url: string | null | undefined): boolean;
+/**
+ * Validate that every URL candidate in a srcset attribute is safe
+ * @param value - Raw srcset value
+ * @returns True when every entry is safe
+ */
+export declare function isSafeSrcset(value: string | null | undefined): boolean;
+/**
+ * Sanitize rendered HTML to remove active content like scripts before injection
+ * @param html - Raw HTML string produced by the markdown pipeline
+ * @returns Sanitized HTML safe for innerHTML assignment
+ */
+export declare function sanitizeRenderedHtml(html: string): string;
+/**
+ * Process tables to add centering attributes for Word compatibility
+ * @param html - HTML content
+ * @returns HTML with centered tables
+ */
+export declare function processTablesForWordCompatibility(html: string): string;
+/**
+ * Async task manager for plugin rendering
+ */
+export interface AsyncTaskManagerOptions {
+    /** Callback triggered when abort() is called, for cleanup of downstream resources */
+    onAbort?: () => void;
+}
+export declare class AsyncTaskManager {
+    private queue;
+    private idCounter;
+    private translate;
+    private aborted;
+    private context;
+    private onAbort?;
+    constructor(translate?: TranslateFunction, options?: AsyncTaskManagerOptions);
+    /**
+     * Abort all pending tasks
+     * Called when starting a new render to cancel previous tasks
+     */
+    abort(): void;
+    /**
+     * Reset abort flag (call before starting new task collection)
+     */
+    reset(): void;
+    /**
+     * Check if manager has been aborted
+     */
+    isAborted(): boolean;
+    /**
+     * Get current context for callbacks to reference
+     */
+    getContext(): TaskContext;
+    /**
+     * Generate unique ID for async tasks
+     */
+    generateId(): string;
+    /**
+     * Register async task for later execution
+     * @param callback - The async callback function
+     * @param data - Data to pass to callback
+     * @param plugin - Plugin instance
+     * @param initialStatus - Initial task status
+     * @returns Task control and placeholder content
+     */
+    createTask(callback: (data: TaskData, context: TaskContext) => Promise<void>, data?: Record<string, unknown>, plugin?: Plugin | null, initialStatus?: TaskStatus): {
+        task: AsyncTask;
+        placeholder: {
+            type: 'html';
+            value: string;
+        };
+    };
+    /**
+     * Process all async tasks in parallel
+     * @param onProgress - Progress callback (completed, total)
+     * @param onError - Error handler for individual task
+     * @returns Returns true if completed, false if aborted
+     */
+    processAll(onProgress?: ((completed: number, total: number) => void) | null, onError?: ((error: Error, task: AsyncTask) => void) | null): Promise<boolean>;
+    /**
+     * Get pending task count
+     */
+    get pendingCount(): number;
+}
+/**
+ * Create the unified markdown processor pipeline
+ * @param renderer - Renderer instance for diagrams
+ * @param taskManager - Async task manager
+ * @param translate - Translation function
+ * @returns Configured unified processor
+ */
+export declare function createMarkdownProcessor(renderer: PluginRenderer, taskManager: AsyncTaskManager, translate?: TranslateFunction): Processor;
+/**
+ * Frontmatter display mode
+ */
+export type FrontmatterDisplay = 'hide' | 'table' | 'raw';
+/**
+ * Options for processing markdown to HTML
+ */
+interface ProcessMarkdownOptions {
+    renderer: PluginRenderer;
+    taskManager: AsyncTaskManager;
+    translate?: TranslateFunction;
+    frontmatterDisplay?: FrontmatterDisplay;
+}
+/**
+ * Clear the HTML result cache (call when settings change)
+ */
+export declare function clearHtmlResultCache(): void;
+/**
+ * Process markdown to HTML with block-level caching
+ * Each block's top-level elements are tagged with hash for efficient DOM diffing.
+ * @param markdown - Raw markdown content
+ * @param options - Processing options
+ * @returns Processed HTML
+ */
+export declare function processMarkdownToHtml(markdown: string, options: ProcessMarkdownOptions): Promise<string>;
+/**
+ * Extract title from markdown content
+ * @param markdown - Markdown content
+ * @returns Extracted title or null
+ */
+export declare function extractTitle(markdown: string): string | null;
+/**
+ * Heading information for TOC
+ */
+export interface HeadingInfo {
+    level: number;
+    text: string;
+    id: string;
+}
+/**
+ * Extract headings for TOC generation (from DOM)
+ * @param container - DOM container with rendered content
+ * @returns Array of heading objects
+ */
+export declare function extractHeadings(container: Element): HeadingInfo[];
+/**
+ * Options for incremental HTML rendering
+ */
+interface RenderHtmlOptions {
+    batchSize?: number;
+    yieldDelay?: number;
+}
+/**
+ * Render HTML content incrementally to avoid blocking the main thread.
+ * Parses HTML, then appends top-level nodes in batches with yields between them.
+ * @param container - Target container element
+ * @param html - Full HTML content to render
+ * @param options - Rendering options
+ */
+export declare function renderHtmlIncrementally(container: HTMLElement, html: string, options?: RenderHtmlOptions): Promise<void>;

package/dist/types/src/core/viewer/viewer-controller.d.ts

@@ -0,0 +1,85 @@
+/**
+ * ViewerController - Shared, platform-agnostic markdown rendering orchestration.
+ *
+ * This version uses MarkdownDocument for block-ID based virtual DOM,
+ * providing precise incremental updates without morphdom.
+ */
+import { AsyncTaskManager, type HeadingInfo } from '../markdown-processor';
+import { MarkdownDocument } from '../markdown-document';
+import type { PluginRenderer, TranslateFunction } from '../../types/index';
+export type { HeadingInfo };
+export type ViewerRenderResult = {
+    title: string | null;
+    headings: HeadingInfo[];
+    taskManager: AsyncTaskManager;
+};
+/**
+ * Frontmatter display mode
+ */
+export type FrontmatterDisplay = 'hide' | 'table' | 'raw';
+export type RenderMarkdownOptions = {
+    markdown: string;
+    container: HTMLElement;
+    renderer: PluginRenderer;
+    translate: TranslateFunction;
+    /**
+     * Optional external task manager, useful for cancellation.
+     * If not provided, a new AsyncTaskManager will be created.
+     */
+    taskManager?: AsyncTaskManager;
+    /**
+     * When true, container.innerHTML will be cleared before rendering.
+     * Keep false if the caller wants to clear before applying theme to avoid flicker.
+     */
+    clearContainer?: boolean;
+    /**
+     * When true, use incremental DOM diffing instead of full re-render.
+     * This preserves already-rendered plugin content when possible.
+     * @deprecated Now always uses block-ID based incremental update
+     */
+    incrementalUpdate?: boolean;
+    /** Called when headings are extracted (may be called multiple times during streaming) */
+    onHeadings?: (headings: HeadingInfo[]) => void;
+    /** Called when initial DOM streaming is complete (before async tasks) */
+    onStreamingComplete?: () => void;
+    /** Frontmatter display mode: 'hide', 'table', or 'raw' */
+    frontmatterDisplay?: FrontmatterDisplay;
+};
+/**
+ * Get or create the markdown document instance
+ */
+export declare function getDocument(): MarkdownDocument;
+/**
+ * Reset the document instance (call when switching files)
+ */
+export declare function resetDocument(): void;
+/**
+ * Clear HTML cache (for backward compatibility)
+ * @deprecated Use resetDocument() instead
+ */
+export declare function clearHtmlCache(): void;
+/**
+ * Sync block HTML from DOM after async rendering completes.
+ * Called when a placeholder is replaced with rendered content.
+ * This ensures the in-memory cache matches the actual DOM state.
+ *
+ * @param placeholderId - The ID of the placeholder element that was replaced
+ */
+export declare function syncBlockHtmlFromDOM(placeholderId: string): void;
+/**
+ * Main render function using MarkdownDocument architecture
+ */
+export declare function renderMarkdownDocument(options: RenderMarkdownOptions): Promise<ViewerRenderResult>;
+/**
+ * Find block element by ID
+ */
+export declare function findBlockElement(container: HTMLElement, blockId: string): HTMLElement | null;
+/**
+ * Get all block elements in order
+ */
+export declare function getBlockElements(container: HTMLElement): HTMLElement[];
+/**
+ * Check if incremental update is possible (for backward compatibility)
+ * @deprecated Always returns true now since we use block-ID based updates
+ */
+export declare function canIncrementalUpdate(container: HTMLElement): boolean;

package/dist/types/src/exporters/docx-blockquote-converter.d.ts

@@ -0,0 +1,24 @@
+import { Table, type FileChild } from 'docx';
+import type { DOCXThemeStyles, DOCXBlockquoteNode, DOCXASTNode } from '../types/docx';
+import type { InlineResult, InlineNode } from './docx-inline-converter';
+type ConvertInlineNodesFunction = (children: InlineNode[], options?: {
+    color?: string;
+}) => Promise<InlineResult[]>;
+type ConvertChildNodeFunction = (node: DOCXASTNode, blockquoteNestLevel?: number) => Promise<FileChild | FileChild[] | null>;
+interface BlockquoteConverterOptions {
+    themeStyles: DOCXThemeStyles;
+    convertInlineNodes: ConvertInlineNodesFunction;
+    convertChildNode?: ConvertChildNodeFunction;
+}
+export interface BlockquoteConverter {
+    convertBlockquote(node: DOCXBlockquoteNode, listLevel?: number): Promise<Table>;
+    setConvertChildNode(fn: ConvertChildNodeFunction): void;
+}
+/**
+ * Create a blockquote converter using table-based approach
+ * This allows true nesting and supports any content type inside blockquotes
+ * @param options - Configuration options
+ * @returns Blockquote converter
+ */
+export declare function createBlockquoteConverter({ themeStyles, convertInlineNodes, convertChildNode: initialConvertChildNode }: BlockquoteConverterOptions): BlockquoteConverter;
+export {};

package/dist/types/src/exporters/docx-code-highlighter.d.ts

@@ -0,0 +1,14 @@
+import { TextRun } from 'docx';
+import type { DOCXThemeStyles } from '../types/docx';
+export interface CodeHighlighter {
+    getHighlightColor(classList: string | string[] | DOMTokenList | null): string | null;
+    appendCodeTextRuns(text: string, runs: TextRun[], color: string | null): void;
+    collectHighlightedRuns(node: Node, runs: TextRun[], inheritedColor?: string | null): void;
+    getHighlightedRunsForCode(code: string, language: string | null | undefined): TextRun[];
+}
+/**
+ * Create a code highlighter for DOCX export
+ * @param themeStyles - Theme configuration with code colors
+ * @returns Highlighter instance with methods
+ */
+export declare function createCodeHighlighter(themeStyles: DOCXThemeStyles | null): CodeHighlighter;

package/dist/types/src/exporters/docx-download.d.ts

@@ -0,0 +1,27 @@
+/**
+ * DOCX Download Utilities
+ * Functions for downloading DOCX files
+ */
+/**
+ * Convert byte array chunk to base64 without exceeding call stack limits
+ * @param bytes - Binary chunk
+ * @returns Base64 encoded chunk
+ */
+export declare function encodeBytesToBase64(bytes: Uint8Array): string;
+/**
+ * Fallback download method using <a> element
+ * @param blob - File blob
+ * @param filename - Output filename
+ */
+export declare function fallbackDownload(blob: Blob, filename: string): void;
+/**
+ * Progress callback for upload phase
+ */
+export type UploadProgressCallback = (uploaded: number, total: number) => void;
+/**
+ * Download blob as file using platform file service
+ * @param blob - File blob
+ * @param filename - Output filename
+ * @param onProgress - Optional progress callback for upload phase
+ */
+export declare function downloadBlob(blob: Blob, filename: string, onProgress?: UploadProgressCallback): Promise<void>;