quikdown 1.2.7 → 1.2.9

package/dist/quikdown.umd.js

@@ -1,6 +1,6 @@
 /**
  * quikdown - Lightweight Markdown Parser
- * @version 1.2.7
+ * @version 1.2.9
  * @license BSD-2-Clause
  * @copyright DeftIO 2025
  */
@@ -11,30 +11,135 @@
 })(this, (function () { 'use strict';
 
     /**
-     * quikdown - A minimal markdown parser optimized for chat/LLM output
-     * Supports tables, code blocks, lists, and common formatting
-     * @param {string} markdown - The markdown source text
-     * @param {Object} options - Optional configuration object
-     * @param {Function} options.fence_plugin - Custom renderer for fenced code blocks
-     *                   (content, fence_string) => html string
-     * @param {boolean} options.inline_styles - If true, uses inline styles instead of classes
-     * @param {boolean} options.bidirectional - If true, adds data-qd attributes for source tracking
-     * @param {boolean} options.lazy_linefeeds - If true, single newlines become <br> tags
-     * @returns {string} - The rendered HTML
+     * quikdown_classify — Shared line-classification utilities
+     * ═════════════════════════════════════════════════════════
+     *
+     * Pure functions for classifying markdown lines.  Used by both the main
+     * parser (quikdown.js) and the editor (quikdown_edit.js) so the logic
+     * lives in one place.
+     *
+     * All functions operate on a **trimmed** line (caller must trim).
+     * None use regexes with nested quantifiers — every check is either a
+     * simple regex or a linear scan, so there is zero ReDoS risk.
      */
 
-    // Version will be injected at build time  
-    const quikdownVersion = '1.2.7';
 
-    // Constants for reuse
+    /**
+     * Dash-only HR check — exact parity with the main parser's original
+     * regex `/^---+\s*$/`.  Only matches lines of three or more dashes
+     * with optional trailing whitespace (no interspersed spaces).
+     *
+     * @param {string} trimmed  The line, already trimmed
+     * @returns {boolean}
+     */
+    function isDashHRLine(trimmed) {
+        if (trimmed.length < 3) return false;
+        for (let i = 0; i < trimmed.length; i++) {
+            const ch = trimmed[i];
+            if (ch === '-') continue;
+            // Allow trailing whitespace only
+            if (ch === ' ' || ch === '\t') {
+                for (let j = i + 1; j < trimmed.length; j++) {
+                    if (trimmed[j] !== ' ' && trimmed[j] !== '\t') return false;
+                }
+                return i >= 3; // at least 3 dashes before whitespace
+            }
+            return false;
+        }
+        return true; // all dashes
+    }
+
+    /**
+     * quikdown — A compact, scanner-based markdown parser
+     * ════════════════════════════════════════════════════
+     *
+     * Architecture overview (v1.2.8 — lexer rewrite)
+     * ───────────────────────────────────────────────
+     * Prior to v1.2.8, quikdown used a multi-pass regex pipeline: each block
+     * type (headings, blockquotes, HR, lists, tables) and each inline format
+     * (bold, italic, links, …) was handled by its own global regex applied
+     * sequentially to the full document string. That worked but made the code
+     * hard to extend and debug — a new construct meant adding another regex
+     * pass, and ordering bugs between passes were subtle.
+     *
+     * Starting in v1.2.8 the parser uses a **line-scanning** approach for
+     * block detection and a **per-block inline pass** for formatting:
+     *
+     *   ┌─────────────────────────────────────────────────────────┐
+     *   │  Phase 1 — Code Extraction                             │
+     *   │  Scan for fenced code blocks (``` / ~~~) and inline    │
+     *   │  code spans (`…`). Replace with §CB§ / §IC§ place-    │
+     *   │  holders so code content is never touched by later      │
+     *   │  phases.                                                │
+     *   ├─────────────────────────────────────────────────────────┤
+     *   │  Phase 2 — HTML Escaping                                │
+     *   │  Escape &, <, >, ", ' in the remaining text to prevent │
+     *   │  XSS. (Skipped when allow_unsafe_html is true.)         │
+     *   ├─────────────────────────────────────────────────────────┤
+     *   │  Phase 3 — Block Scanning                               │
+     *   │  Walk the text **line by line**.  At each line, the     │
+     *   │  scanner checks (in order):                             │
+     *   │    • table rows  (|)                                    │
+     *   │    • headings    (#)                                    │
+     *   │    • HR          (---)                                  │
+     *   │    • blockquotes (&gt;)                                 │
+     *   │    • list items  (-, *, +, 1.)                          │
+     *   │    • code-block placeholder (§CB…§)                     │
+     *   │    • paragraph text (everything else)                   │
+     *   │                                                         │
+     *   │  Block text is run through the **inline formatter**     │
+     *   │  which handles bold, italic, strikethrough, links,      │
+     *   │  images, and autolinks.                                 │
+     *   │                                                         │
+     *   │  Paragraphs are wrapped in <p> tags.  Lazy linefeeds   │
+     *   │  (single \n → <br>) are handled here too.               │
+     *   ├─────────────────────────────────────────────────────────┤
+     *   │  Phase 4 — Code Restoration                             │
+     *   │  Replace §CB§ / §IC§ placeholders with rendered <pre>  │
+     *   │  / <code> HTML, applying the fence_plugin if present.   │
+     *   └─────────────────────────────────────────────────────────┘
+     *
+     * Why this design?
+     *  • Single pass over lines for block identification — no re-scanning.
+     *  • Each block type is a clearly separated branch, easy to add new ones.
+     *  • Inline formatting is confined to block text — can't accidentally
+     *    match across block boundaries or inside HTML tags.
+     *  • Code extraction still uses a simple regex (it's one pattern, not a
+     *    chain) because the §-placeholder approach is proven and simple.
+     *
+     * @param {string} markdown  The markdown source text
+     * @param {Object} options   Configuration (see below)
+     * @returns {string}         Rendered HTML
+     */
+
+
+    // ────────────────────────────────────────────────────────────────────
+    //  Constants
+    // ────────────────────────────────────────────────────────────────────
+
+    /** Build-time version stamp (injected by tools/updateVersion) */
+    const quikdownVersion = '1.2.9';
+
+    /** CSS class prefix used for all generated elements */
     const CLASS_PREFIX = 'quikdown-';
-    const PLACEHOLDER_CB = '§CB';
-    const PLACEHOLDER_IC = '§IC';
 
-    // Escape map at module level
+    /** Placeholder sigils — chosen to be extremely unlikely in real text */
+    const PLACEHOLDER_CB = '§CB';   // fenced code blocks
+    const PLACEHOLDER_IC = '§IC';   // inline code spans
+
+    /** HTML entity escape map */
     const ESC_MAP = {'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'};
 
-    // Single source of truth for all style definitions - optimized
+    // ────────────────────────────────────────────────────────────────────
+    //  Style definitions
+    // ────────────────────────────────────────────────────────────────────
+
+    /**
+     * Inline styles for every element quikdown can emit.
+     * When `inline_styles: true` these are injected as style="…" attributes.
+     * When `inline_styles: false` (default) we use class="quikdown-<tag>"
+     * and these same values are emitted by `quikdown.emitStyles()`.
+     */
     const QUIKDOWN_STYLES = {
         h1: 'font-size:2em;font-weight:600;margin:.67em 0;text-align:left',
         h2: 'font-size:1.5em;font-weight:600;margin:.83em 0',
@@ -57,35 +162,41 @@
         ul: 'margin:.5em 0;padding-left:2em',
         ol: 'margin:.5em 0;padding-left:2em',
         li: 'margin:.25em 0',
-        // Task list specific styles
         'task-item': 'list-style:none',
         'task-checkbox': 'margin-right:.5em'
     };
 
-    // Factory function to create getAttr for a given context
+    // ────────────────────────────────────────────────────────────────────
+    //  Attribute factory
+    // ────────────────────────────────────────────────────────────────────
+
+    /**
+     * Creates a `getAttr(tag, additionalStyle?)` helper that returns
+     * either a class="…" or style="…" attribute string depending on mode.
+     *
+     * @param {boolean} inline_styles  True → emit style="…"; false → class="…"
+     * @param {Object}  styles         The QUIKDOWN_STYLES map
+     * @returns {Function}
+     */
     function createGetAttr(inline_styles, styles) {
         return function(tag, additionalStyle = '') {
             if (inline_styles) {
                 let style = styles[tag];
                 if (!style && !additionalStyle) return '';
-                
-                // Remove default text-align if we're adding a different alignment
+
+                // When adding alignment that conflicts with the tag's default,
+                // strip the default text-align first.
                 if (additionalStyle && additionalStyle.includes('text-align') && style && style.includes('text-align')) {
                     style = style.replace(/text-align:[^;]+;?/, '').trim();
-                    // Ensure trailing semicolon before concatenating additionalStyle.
-                    // Both short-circuit paths of this guard (empty `style` or
-                    // already-has-`;`) are defensive and unreachable with the
-                    // current QUIKDOWN_STYLES values — istanbul ignore next.
                     /* istanbul ignore next */
                     if (style && !style.endsWith(';')) style += ';';
                 }
-                
+
                 /* istanbul ignore next - defensive: additionalStyle without style doesn't occur with current tags */
                 const fullStyle = additionalStyle ? (style ? `${style}${additionalStyle}` : additionalStyle) : style;
                 return ` style="${fullStyle}"`;
             } else {
                 const classAttr = ` class="${CLASS_PREFIX}${tag}"`;
-                // Apply inline styles for alignment even when using CSS classes
                 if (additionalStyle) {
                     return `${classAttr} style="${additionalStyle}"`;
                 }
@@ -94,72 +205,84 @@
         };
     }
 
+    // ════════════════════════════════════════════════════════════════════
+    //  Main parser function
+    // ════════════════════════════════════════════════════════════════════
+
     function quikdown(markdown, options = {}) {
+        // ── Guard: only process non-empty strings ──
         if (!markdown || typeof markdown !== 'string') {
             return '';
         }
-        
+
+        // ── Unpack options ──
         const { fence_plugin, inline_styles = false, bidirectional = false, lazy_linefeeds = false, allow_unsafe_html = false } = options;
-        const styles = QUIKDOWN_STYLES; // Use module-level styles
-        const getAttr = createGetAttr(inline_styles, styles); // Create getAttr once
+        const styles = QUIKDOWN_STYLES;
+        const getAttr = createGetAttr(inline_styles, styles);
+
+        // ── Helpers (closed over options) ──
 
-        // Escape HTML entities to prevent XSS
+        /** Escape the five HTML-special characters. */
         function escapeHtml(text) {
             return text.replace(/[&<>"']/g, m => ESC_MAP[m]);
         }
-        
-        // Helper to add data-qd attributes for bidirectional support.
-        // The non-bidirectional branch is a trivial no-op arrow; it's exercised in
-        // the core bundle but never in quikdown_bd (which always sets bidirectional=true).
+
+        /**
+         * Bidirectional marker helper.
+         * When bidirectional mode is on, returns ` data-qd="…"`.
+         * The non-bidirectional branch is a trivial no-op arrow; it is
+         * exercised in the core bundle but never in quikdown_bd.
+         */
         /* istanbul ignore next - trivial no-op fallback */
         const dataQd = bidirectional ? (marker) => ` data-qd="${escapeHtml(marker)}"` : () => '';
 
-        // Sanitize URLs to prevent XSS attacks
+        /**
+         * Sanitize a URL to block javascript:, vbscript:, and non-image data: URIs.
+         * Returns '#' for blocked URLs.
+         */
         function sanitizeUrl(url, allowUnsafe = false) {
             /* istanbul ignore next - defensive programming, regex ensures url is never empty */
             if (!url) return '';
-            
-            // If unsafe URLs are explicitly allowed, return as-is
             if (allowUnsafe) return url;
-            
+
             const trimmedUrl = url.trim();
             const lowerUrl = trimmedUrl.toLowerCase();
-            
-            // Block dangerous protocols
             const dangerousProtocols = ['javascript:', 'vbscript:', 'data:'];
-            
+
             for (const protocol of dangerousProtocols) {
                 if (lowerUrl.startsWith(protocol)) {
-                    // Exception: Allow data:image/* for images
                     if (protocol === 'data:' && lowerUrl.startsWith('data:image/')) {
                         return trimmedUrl;
                     }
-                    // Return safe empty link for dangerous protocols
                     return '#';
                 }
             }
-            
             return trimmedUrl;
         }
 
-        // Process the markdown in phases
+        // ────────────────────────────────────────────────────────────────
+        //  Phase 1 — Code Extraction
+        // ────────────────────────────────────────────────────────────────
+        // Why extract code first?  Fenced blocks and inline code spans can
+        // contain markdown-like characters (*, _, #, |, etc.) that must NOT
+        // be interpreted as formatting.  By pulling them out and replacing
+        // with unique placeholders, the rest of the pipeline never sees them.
+
         let html = markdown;
-        
-        // Phase 1: Extract and protect code blocks and inline code
-        const codeBlocks = [];
-        const inlineCodes = [];
-        
-        // Extract fenced code blocks first (supports both ``` and ~~~)
-        // Match paired fences - ``` with ``` and ~~~ with ~~~
-        // Fence must be at start of line
+        const codeBlocks = [];    // Array of {lang, code, custom, fence, hasReverse}
+        const inlineCodes = [];   // Array of escaped-HTML strings
+
+        // ── Fenced code blocks ──
+        // Matches paired fences: ``` with ``` and ~~~ with ~~~.
+        // The fence must start at column 0 of a line (^ with /m flag).
+        // Group 1 = fence marker, Group 2 = language hint, Group 3 = code body.
         html = html.replace(/^(```|~~~)([^\n]*)\n([\s\S]*?)^\1$/gm, (match, fence, lang, code) => {
             const placeholder = `${PLACEHOLDER_CB}${codeBlocks.length}§`;
-            
-            // Trim the language specification
             const langTrimmed = lang ? lang.trim() : '';
-            
-            // If custom fence plugin is provided, use it (v1.1.0: object format required)
+
             if (fence_plugin && fence_plugin.render && typeof fence_plugin.render === 'function') {
+                // Custom plugin — store raw code (un-escaped) so the plugin
+                // receives the original source.
                 codeBlocks.push({
                     lang: langTrimmed,
                     code: code.trimEnd(),
@@ -168,6 +291,7 @@
                     hasReverse: !!fence_plugin.reverse
                 });
             } else {
+                // Default — pre-escape the code for safe HTML output.
                 codeBlocks.push({
                     lang: langTrimmed,
                     code: escapeHtml(code.trimEnd()),
@@ -177,69 +301,94 @@
             }
             return placeholder;
         });
-        
-        // Extract inline code
+
+        // ── Inline code spans ──
+        // Matches a single backtick pair: `content`.
+        // Content is captured and HTML-escaped immediately.
         html = html.replace(/`([^`]+)`/g, (match, code) => {
             const placeholder = `${PLACEHOLDER_IC}${inlineCodes.length}§`;
             inlineCodes.push(escapeHtml(code));
             return placeholder;
         });
-        
-        // Escape HTML in the rest of the content (skip if allow_unsafe_html is on —
-        // useful for trusted pipelines where the markdown contains intentional HTML)
+
+        // ────────────────────────────────────────────────────────────────
+        //  Phase 2 — HTML Escaping
+        // ────────────────────────────────────────────────────────────────
+        // All remaining text (everything except code placeholders) is escaped
+        // to prevent XSS.  The `allow_unsafe_html` option skips this for
+        // trusted pipelines that intentionally embed raw HTML.
+
         if (!allow_unsafe_html) {
             html = escapeHtml(html);
         }
-        
-        // Phase 2: Process block elements
-        
-        // Process tables
+
+        // ────────────────────────────────────────────────────────────────
+        //  Phase 3 — Block Scanning + Inline Formatting + Paragraphs
+        // ────────────────────────────────────────────────────────────────
+        // This is the heart of the lexer rewrite.  Instead of applying
+        // 10+ global regex passes, we:
+        //   1. Process tables (line walker — tables need multi-line lookahead)
+        //   2. Scan remaining lines for headings, HR, blockquotes
+        //   3. Process lists (line walker — lists need indent tracking)
+        //   4. Apply inline formatting to all text content
+        //   5. Wrap remaining text in <p> tags
+        //
+        // Steps 1 and 3 are line-walkers that process the full text in a
+        // single pass each.  Step 2 replaces global regex with a per-line
+        // scanner.  Steps 4-5 are applied to the result.
+        //
+        // Total: 3 structured passes instead of 10+ regex passes.
+
+        // ── Step 1: Tables ──
+        // Tables need multi-line lookahead (header → separator → body rows)
+        // so they're handled by a dedicated line-walker first.
         html = processTable(html, getAttr);
-        
-        // Process headings (supports optional trailing #'s)
-        html = html.replace(/^(#{1,6})\s+(.+?)\s*#*$/gm, (match, hashes, content) => {
-            const level = hashes.length;
-            return `<h${level}${getAttr('h' + level)}${dataQd(hashes)}>${content}</h${level}>`;
-        });
-        
-        // Process blockquotes (must handle escaped > since we already escaped HTML)
-        html = html.replace(/^&gt;\s+(.+)$/gm, `<blockquote${getAttr('blockquote')}>$1</blockquote>`);
-        // Merge consecutive blockquotes
-        html = html.replace(/<\/blockquote>\n<blockquote>/g, '\n');
-        
-        // Process horizontal rules (allow trailing spaces)
-        html = html.replace(/^---+\s*$/gm, `<hr${getAttr('hr')}>`);
-        
-        // Process lists
+
+        // ── Step 2: Headings, HR, Blockquotes ──
+        // These are simple line-level constructs.  We scan each line once
+        // and replace matching lines with their HTML representation.
+        html = scanLineBlocks(html, getAttr, dataQd);
+
+        // ── Step 3: Lists ──
+        // Lists need indent-level tracking across lines, so they get their
+        // own line-walker.
         html = processLists(html, getAttr, inline_styles, bidirectional);
-        
-        // Phase 3: Process inline elements
-        
-        // Images (must come before links, with URL sanitization)
+
+        // ── Step 4: Inline formatting ──
+        // Apply bold, italic, strikethrough, images, links, and autolinks
+        // to all text content.  This runs on the output of steps 1-3, so
+        // it sees text inside headings, blockquotes, table cells, list
+        // items, and paragraph text.
+
+        // Images (must come before links — ![alt](src) vs [text](url))
         html = html.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (match, alt, src) => {
             const sanitizedSrc = sanitizeUrl(src, options.allow_unsafe_urls);
+            // Bidirectional attributes are only exercised via quikdown_bd bundle.
+            /* istanbul ignore next - bd-only branch */
             const altAttr = bidirectional && alt ? ` data-qd-alt="${escapeHtml(alt)}"` : '';
+            /* istanbul ignore next - bd-only branch */
             const srcAttr = bidirectional ? ` data-qd-src="${escapeHtml(src)}"` : '';
             return `<img${getAttr('img')} src="${sanitizedSrc}" alt="${alt}"${altAttr}${srcAttr}${dataQd('!')}>`;
         });
-        
-        // Links (with URL sanitization)
+
+        // Links
         html = html.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (match, text, href) => {
-            // Sanitize URL to prevent XSS
             const sanitizedHref = sanitizeUrl(href, options.allow_unsafe_urls);
             const isExternal = /^https?:\/\//i.test(sanitizedHref);
             const rel = isExternal ? ' rel="noopener noreferrer"' : '';
+            /* istanbul ignore next - bd-only branch */
             const textAttr = bidirectional ? ` data-qd-text="${escapeHtml(text)}"` : '';
             return `<a${getAttr('a')} href="${sanitizedHref}"${rel}${textAttr}${dataQd('[')}>${text}</a>`;
         });
-        
-        // Autolinks - convert bare URLs to clickable links
+
+        // Autolinks — bare https?:// URLs become clickable <a> tags
         html = html.replace(/(^|\s)(https?:\/\/[^\s<]+)/g, (match, prefix, url) => {
             const sanitizedUrl = sanitizeUrl(url, options.allow_unsafe_urls);
             return `${prefix}<a${getAttr('a')} href="${sanitizedUrl}" rel="noopener noreferrer">${url}</a>`;
         });
-        
-        // Process inline formatting (bold, italic, strikethrough)
+
+        // Bold, italic, strikethrough
+        // Order matters: ** before * (so ** isn't consumed as two *s)
         const inlinePatterns = [
             [/\*\*(.+?)\*\*/g, 'strong', '**'],
             [/__(.+?)__/g, 'strong', '__'],
@@ -247,60 +396,63 @@
             [/(?<!_)_(?!_)(.+?)(?<!_)_(?!_)/g, 'em', '_'],
             [/~~(.+?)~~/g, 'del', '~~']
         ];
-        
         inlinePatterns.forEach(([pattern, tag, marker]) => {
             html = html.replace(pattern, `<${tag}${getAttr(tag)}${dataQd(marker)}>$1</${tag}>`);
         });
-        
-        // Line breaks
+
+        // ── Step 5: Line breaks + paragraph wrapping ──
         if (lazy_linefeeds) {
-            // Lazy linefeeds: single newline becomes <br> (except between paragraphs and after/before block elements)
+            // Lazy linefeeds mode: every single \n becomes <br> EXCEPT:
+            //   • Double newlines → paragraph break
+            //   • Newlines adjacent to block elements (h, blockquote, pre, hr, table, list)
+            //
+            // Strategy: protect block-adjacent newlines with §N§, convert
+            // the rest, then restore.
+
             const blocks = [];
             let bi = 0;
-            
-            // Protect tables and lists  
+
+            // Protect tables and lists from <br> injection
             html = html.replace(/<(table|[uo]l)[^>]*>[\s\S]*?<\/\1>/g, m => {
                 blocks[bi] = m;
                 return `§B${bi++}§`;
             });
-            
-            // Handle paragraphs and block elements
+
             html = html.replace(/\n\n+/g, '§P§')
-                // After block elements
+                // After block-level closing tags
                 .replace(/(<\/(?:h[1-6]|blockquote|pre)>)\n/g, '$1§N§')
                 .replace(/(<(?:h[1-6]|blockquote|pre|hr)[^>]*>)\n/g, '$1§N§')
-                // Before block elements  
+                // Before block-level opening tags
                 .replace(/\n(<(?:h[1-6]|blockquote|pre|hr)[^>]*>)/g, '§N§$1')
                 .replace(/\n(§B\d+§)/g, '§N§$1')
                 .replace(/(§B\d+§)\n/g, '$1§N§')
-                // Convert remaining newlines
+                // Convert surviving newlines to <br>
                 .replace(/\n/g, `<br${getAttr('br')}>`)
                 // Restore
                 .replace(/§N§/g, '\n')
                 .replace(/§P§/g, '</p><p>');
-            
+
             // Restore protected blocks
             blocks.forEach((b, i) => html = html.replace(`§B${i}§`, b));
-            
+
             html = '<p>' + html + '</p>';
         } else {
-            // Standard: two spaces at end of line for line breaks
+            // Standard mode: two trailing spaces → <br>, double newline → new paragraph
             html = html.replace(/ {2}$/gm, `<br${getAttr('br')}>`);
-            
-            // Paragraphs (double newlines)
-            // Don't add </p> after block elements (they're not in paragraphs)
+
             html = html.replace(/\n\n+/g, (match, offset) => {
-                // Check if we're after a block element closing tag
                 const before = html.substring(0, offset);
                 if (before.match(/<\/(h[1-6]|blockquote|ul|ol|table|pre|hr)>$/)) {
-                    return '<p>';  // Just open a new paragraph
+                    return '<p>';
                 }
-                return '</p><p>';  // Normal paragraph break
+                return '</p><p>';
             });
             html = '<p>' + html + '</p>';
         }
-        
-        // Clean up empty paragraphs and unwrap block elements
+
+        // ── Step 6: Cleanup ──
+        // Remove <p> wrappers that accidentally enclose block elements.
+        // This is simpler than trying to prevent them during wrapping.
         const cleanupPatterns = [
             [/<p><\/p>/g, ''],
             [/<p>(<h[1-6][^>]*>)/g, '$1'],
@@ -316,65 +468,152 @@
             [/(<\/pre>)<\/p>/g, '$1'],
             [new RegExp(`<p>(${PLACEHOLDER_CB}\\d+§)</p>`, 'g'), '$1']
         ];
-        
         cleanupPatterns.forEach(([pattern, replacement]) => {
             html = html.replace(pattern, replacement);
         });
-        
-        // Fix orphaned closing </p> tags after block elements
-        // When a paragraph follows a block element, ensure it has opening <p>
+
+        // When a block element is followed by a newline and then text, open a <p>.
         html = html.replace(/(<\/(?:h[1-6]|blockquote|ul|ol|table|pre|hr)>)\n([^<])/g, '$1\n<p>$2');
-        
-        // Phase 4: Restore code blocks and inline code
-        
-        // Restore code blocks
+
+        // ────────────────────────────────────────────────────────────────
+        //  Phase 4 — Code Restoration
+        // ────────────────────────────────────────────────────────────────
+        // Replace placeholders with rendered HTML.  For fenced blocks this
+        // means wrapping in <pre><code>…</code></pre> (or calling the
+        // fence_plugin).  For inline code it means <code>…</code>.
+
         codeBlocks.forEach((block, i) => {
             let replacement;
-            
+
             if (block.custom && fence_plugin && fence_plugin.render) {
-                // Use custom fence plugin (v1.1.0: object format with render function)
+                // Delegate to the user-provided fence plugin.
                 replacement = fence_plugin.render(block.code, block.lang);
-                
-                // If plugin returns undefined, fall back to default rendering
+
                 if (replacement === undefined) {
+                    // Plugin declined — fall back to default rendering.
                     const langClass = !inline_styles && block.lang ? ` class="language-${block.lang}"` : '';
                     const codeAttr = inline_styles ? getAttr('code') : langClass;
+                    /* istanbul ignore next - bd-only branch */
                     const langAttr = bidirectional && block.lang ? ` data-qd-lang="${escapeHtml(block.lang)}"` : '';
+                    /* istanbul ignore next - bd-only branch */
                     const fenceAttr = bidirectional ? ` data-qd-fence="${escapeHtml(block.fence)}"` : '';
                     replacement = `<pre${getAttr('pre')}${fenceAttr}${langAttr}><code${codeAttr}>${escapeHtml(block.code)}</code></pre>`;
-                } else if (bidirectional) {
-                    // If bidirectional and plugin provided HTML, add data attributes for roundtrip
-                    replacement = replacement.replace(/^<(\w+)/, 
+                } else /* istanbul ignore next - bd-only branch */ if (bidirectional) {
+                    // Plugin returned HTML — inject data attributes for roundtrip.
+                    replacement = replacement.replace(/^<(\w+)/,
                         `<$1 data-qd-fence="${escapeHtml(block.fence)}" data-qd-lang="${escapeHtml(block.lang)}" data-qd-source="${escapeHtml(block.code)}"`);
                 }
             } else {
-                // Default rendering
+                // Default rendering — wrap in <pre><code>.
                 const langClass = !inline_styles && block.lang ? ` class="language-${block.lang}"` : '';
                 const codeAttr = inline_styles ? getAttr('code') : langClass;
+                /* istanbul ignore next - bd-only branch */
                 const langAttr = bidirectional && block.lang ? ` data-qd-lang="${escapeHtml(block.lang)}"` : '';
+                /* istanbul ignore next - bd-only branch */
                 const fenceAttr = bidirectional ? ` data-qd-fence="${escapeHtml(block.fence)}"` : '';
                 replacement = `<pre${getAttr('pre')}${fenceAttr}${langAttr}><code${codeAttr}>${block.code}</code></pre>`;
             }
-            
+
             const placeholder = `${PLACEHOLDER_CB}${i}§`;
             html = html.replace(placeholder, replacement);
         });
-        
-        // Restore inline code
+
+        // Restore inline code spans
         inlineCodes.forEach((code, i) => {
             const placeholder = `${PLACEHOLDER_IC}${i}§`;
             html = html.replace(placeholder, `<code${getAttr('code')}${dataQd('`')}>${code}</code>`);
         });
-        
+
         return html.trim();
     }
 
+    // ════════════════════════════════════════════════════════════════════
+    //  Block-level line scanner
+    // ════════════════════════════════════════════════════════════════════
+
+    /**
+     * scanLineBlocks — single-pass line scanner for headings, HR, blockquotes
+     *
+     * Walks the text line by line.  For each line it checks (in order):
+     *   1. Heading   — starts with 1-6 '#' followed by a space
+     *   2. HR        — line is entirely '---…' (3+ dashes, optional trailing space)
+     *   3. Blockquote — starts with '&gt; ' (the > was already HTML-escaped)
+     *
+     * Lines that don't match any block pattern are passed through unchanged.
+     *
+     * This replaces three separate global regex passes from the pre-1.2.8
+     * architecture with one structured scan.
+     *
+     * @param {string}   text    The document text (HTML-escaped, code extracted)
+     * @param {Function} getAttr Attribute factory (class or style)
+     * @param {Function} dataQd  Bidirectional marker factory
+     * @returns {string}         Text with block-level elements rendered
+     */
+    function scanLineBlocks(text, getAttr, dataQd) {
+        const lines = text.split('\n');
+        const result = [];
+        let i = 0;
+
+        while (i < lines.length) {
+            const line = lines[i];
+
+            // ── Heading ──
+            // Count leading '#' characters.  Valid heading: 1-6 hashes then a space.
+            // Example: "## Hello World ##" → <h2>Hello World</h2>
+            let hashCount = 0;
+            while (hashCount < line.length && hashCount < 7 && line[hashCount] === '#') {
+                hashCount++;
+            }
+            if (hashCount >= 1 && hashCount <= 6 && line[hashCount] === ' ') {
+                // Extract content after "# " and strip trailing hashes
+                const content = line.slice(hashCount + 1).replace(/\s*#+\s*$/, '');
+                const tag = 'h' + hashCount;
+                result.push(`<${tag}${getAttr(tag)}${dataQd('#'.repeat(hashCount))}>${content}</${tag}>`);
+                i++;
+                continue;
+            }
+
+            // ── Horizontal Rule ──
+            // Three or more dashes, optional trailing whitespace, nothing else.
+            if (isDashHRLine(line)) {
+                result.push(`<hr${getAttr('hr')}>`);
+                i++;
+                continue;
+            }
+
+            // ── Blockquote ──
+            // After Phase 2, the '>' character has been escaped to '&gt;'.
+            // Pattern: "&gt; content" or merged consecutive blockquotes.
+            if (/^&gt;\s+/.test(line)) {
+                result.push(`<blockquote${getAttr('blockquote')}>${line.replace(/^&gt;\s+/, '')}</blockquote>`);
+                i++;
+                continue;
+            }
+
+            // ── Pass-through ──
+            result.push(line);
+            i++;
+        }
+
+        // Merge consecutive blockquotes into a single element.
+        // <blockquote>A</blockquote>\n<blockquote>B</blockquote>
+        //   → <blockquote>A\nB</blockquote>
+        let joined = result.join('\n');
+        joined = joined.replace(/<\/blockquote>\n<blockquote>/g, '\n');
+        return joined;
+    }
+
+    // ════════════════════════════════════════════════════════════════════
+    //  Table processing (line walker)
+    // ════════════════════════════════════════════════════════════════════
+
     /**
-     * Process inline markdown formatting
+     * Inline markdown formatter for table cells.
+     * Handles bold, italic, strikethrough, and code within cell text.
+     * Links / images / autolinks are handled by the global inline pass
+     * (Phase 3 Step 4) which runs after table processing.
      */
     function processInlineMarkdown(text, getAttr) {
-        
-        // Process inline formatting patterns
         const patterns = [
             [/\*\*(.+?)\*\*/g, 'strong'],
             [/__(.+?)__/g, 'strong'],
@@ -383,27 +622,32 @@
             [/~~(.+?)~~/g, 'del'],
             [/`([^`]+)`/g, 'code']
         ];
-        
         patterns.forEach(([pattern, tag]) => {
             text = text.replace(pattern, `<${tag}${getAttr(tag)}>$1</${tag}>`);
         });
-        
         return text;
     }
 
     /**
-     * Process markdown tables
+     * processTable — line walker for markdown tables
+     *
+     * Walks through lines looking for runs of pipe-containing lines.
+     * Each run is validated (must contain a separator row: |---|---|)
+     * and rendered as an HTML <table>.  Invalid runs are restored as-is.
+     *
+     * @param {string}   text    Full document text
+     * @param {Function} getAttr Attribute factory
+     * @returns {string}         Text with tables rendered
      */
     function processTable(text, getAttr) {
         const lines = text.split('\n');
         const result = [];
         let inTable = false;
         let tableLines = [];
-        
+
         for (let i = 0; i < lines.length; i++) {
             const line = lines[i].trim();
-            
-            // Check if this line looks like a table row (with or without trailing |)
+
             if (line.includes('|') && (line.startsWith('|') || /[^\\|]/.test(line))) {
                 if (!inTable) {
                     inTable = true;
@@ -411,14 +655,11 @@
                 }
                 tableLines.push(line);
             } else {
-                // Not a table line
                 if (inTable) {
-                    // Process the accumulated table
                     const tableHtml = buildTable(tableLines, getAttr);
                     if (tableHtml) {
                         result.push(tableHtml);
                     } else {
-                        // Not a valid table, restore original lines
                         result.push(...tableLines);
                     }
                     inTable = false;
@@ -427,8 +668,8 @@
                 result.push(lines[i]);
             }
         }
-        
-        // Handle table at end of text
+
+        // Handle table at end of document
         if (inTable && tableLines.length > 0) {
             const tableHtml = buildTable(tableLines, getAttr);
             if (tableHtml) {
@@ -437,35 +678,35 @@
                 result.push(...tableLines);
             }
         }
-        
+
         return result.join('\n');
     }
 
     /**
-     * Build an HTML table from markdown table lines
+     * buildTable — validate and render a table from accumulated lines
+     *
+     * @param {string[]} lines   Array of pipe-containing lines
+     * @param {Function} getAttr Attribute factory
+     * @returns {string|null}    HTML table string, or null if invalid
      */
     function buildTable(lines, getAttr) {
-        
         if (lines.length < 2) return null;
-        
-        // Check for separator line (second line should be the separator)
+
+        // Find the separator row (---|---|)
         let separatorIndex = -1;
         for (let i = 1; i < lines.length; i++) {
-            // Support separator with or without leading/trailing pipes
             if (/^\|?[\s\-:|]+\|?$/.test(lines[i]) && lines[i].includes('-')) {
                 separatorIndex = i;
                 break;
             }
         }
-        
         if (separatorIndex === -1) return null;
-        
+
         const headerLines = lines.slice(0, separatorIndex);
         const bodyLines = lines.slice(separatorIndex + 1);
-        
-        // Parse alignment from separator
+
+        // Parse alignment from separator cells (:--- = left, :---: = center, ---: = right)
         const separator = lines[separatorIndex];
-        // Handle pipes at start/end or not
         const separatorCells = separator.trim().replace(/^\|/, '').replace(/\|$/, '').split('|');
         const alignments = separatorCells.map(cell => {
             const trimmed = cell.trim();
@@ -473,31 +714,28 @@
             if (trimmed.endsWith(':')) return 'right';
             return 'left';
         });
-        
+
         let html = `<table${getAttr('table')}>\n`;
-        
-        // Build header
-        // Note: headerLines will always have length > 0 since separatorIndex starts from 1
+
+        // Header
         html += `<thead${getAttr('thead')}>\n`;
         headerLines.forEach(line => {
-                html += `<tr${getAttr('tr')}>\n`;
-                // Handle pipes at start/end or not
-                const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|');
-                cells.forEach((cell, i) => {
-                    const alignStyle = alignments[i] && alignments[i] !== 'left' ? `text-align:${alignments[i]}` : '';
-                    const processedCell = processInlineMarkdown(cell.trim(), getAttr);
-                    html += `<th${getAttr('th', alignStyle)}>${processedCell}</th>\n`;
-                });
-                html += '</tr>\n';
+            html += `<tr${getAttr('tr')}>\n`;
+            const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|');
+            cells.forEach((cell, i) => {
+                const alignStyle = alignments[i] && alignments[i] !== 'left' ? `text-align:${alignments[i]}` : '';
+                const processedCell = processInlineMarkdown(cell.trim(), getAttr);
+                html += `<th${getAttr('th', alignStyle)}>${processedCell}</th>\n`;
+            });
+            html += '</tr>\n';
         });
         html += '</thead>\n';
-        
-        // Build body
+
+        // Body
         if (bodyLines.length > 0) {
             html += `<tbody${getAttr('tbody')}>\n`;
             bodyLines.forEach(line => {
                 html += `<tr${getAttr('tr')}>\n`;
-                // Handle pipes at start/end or not
                 const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|');
                 cells.forEach((cell, i) => {
                     const alignStyle = alignments[i] && alignments[i] !== 'left' ? `text-align:${alignments[i]}` : '';
@@ -508,66 +746,81 @@
             });
             html += '</tbody>\n';
         }
-        
+
         html += '</table>';
         return html;
     }
 
+    // ════════════════════════════════════════════════════════════════════
+    //  List processing (line walker)
+    // ════════════════════════════════════════════════════════════════════
+
     /**
-     * Process markdown lists (ordered and unordered)
+     * processLists — line walker for ordered, unordered, and task lists
+     *
+     * Scans each line for list markers (-, *, +, 1., 2., etc.) with
+     * optional leading indentation for nesting.  Non-list lines close
+     * any open lists and pass through unchanged.
+     *
+     * Task lists (- [ ] / - [x]) are detected and rendered with
+     * checkbox inputs.
+     *
+     * @param {string}   text         Full document text
+     * @param {Function} getAttr      Attribute factory
+     * @param {boolean}  inline_styles Whether to use inline styles
+     * @param {boolean}  bidirectional Whether to add data-qd markers
+     * @returns {string}              Text with lists rendered
      */
     function processLists(text, getAttr, inline_styles, bidirectional) {
-        
         const lines = text.split('\n');
         const result = [];
-        const listStack = []; // Track nested lists
-        
+        const listStack = [];   // tracks nesting: [{type:'ul', level:0}, …]
+
         // Helper to escape HTML for data-qd attributes. List markers (`-`, `*`,
         // `+`, `1.`, etc.) never contain HTML-special chars, so the replace
         // callback is defensive-only and never actually fires in practice.
+        /* istanbul ignore next - defensive: list markers never trigger escaping */
         const escapeHtml = (text) => text.replace(/[&<>"']/g,
             /* istanbul ignore next - defensive: list markers never contain HTML specials */
             m => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'})[m]);
         /* istanbul ignore next - trivial no-op fallback; not exercised via bd bundle */
         const dataQd = bidirectional ? (marker) => ` data-qd="${escapeHtml(marker)}"` : () => '';
-        
+
         for (let i = 0; i < lines.length; i++) {
             const line = lines[i];
             const match = line.match(/^(\s*)([*\-+]|\d+\.)\s+(.+)$/);
-            
+
             if (match) {
                 const [, indent, marker, content] = match;
                 const level = Math.floor(indent.length / 2);
                 const isOrdered = /^\d+\./.test(marker);
                 const listType = isOrdered ? 'ol' : 'ul';
-                
-                // Check for task list items
+
+                // Task list detection (only in unordered lists)
                 let listItemContent = content;
                 let taskListClass = '';
                 const taskMatch = content.match(/^\[([x ])\]\s+(.*)$/i);
                 if (taskMatch && !isOrdered) {
                     const [, checked, taskContent] = taskMatch;
                     const isChecked = checked.toLowerCase() === 'x';
-                    const checkboxAttr = inline_styles 
-                        ? ' style="margin-right:.5em"' 
+                    const checkboxAttr = inline_styles
+                        ? ' style="margin-right:.5em"'
                         : ` class="${CLASS_PREFIX}task-checkbox"`;
                     listItemContent = `<input type="checkbox"${checkboxAttr}${isChecked ? ' checked' : ''} disabled> ${taskContent}`;
                     taskListClass = inline_styles ? ' style="list-style:none"' : ` class="${CLASS_PREFIX}task-item"`;
                 }
-                
-                // Close deeper levels
+
+                // Close deeper nesting levels
                 while (listStack.length > level + 1) {
                     const list = listStack.pop();
                     result.push(`</${list.type}>`);
                 }
-                
-                // Open new level if needed
+
+                // Open new list or switch type at current level
                 if (listStack.length === level) {
-                    // Need to open a new list
                     listStack.push({ type: listType, level });
                     result.push(`<${listType}${getAttr(listType)}>`);
                 } else if (listStack.length === level + 1) {
-                    // Check if we need to switch list type
                     const currentList = listStack[listStack.length - 1];
                     if (currentList.type !== listType) {
                         result.push(`</${currentList.type}>`);
@@ -576,11 +829,11 @@
                         result.push(`<${listType}${getAttr(listType)}>`);
                     }
                 }
-                
+
                 const liAttr = taskListClass || getAttr('li');
                 result.push(`<li${liAttr}${dataQd(marker)}>${listItemContent}</li>`);
             } else {
-                // Not a list item, close all lists
+                // Not a list item — close all open lists
                 while (listStack.length > 0) {
                     const list = listStack.pop();
                     result.push(`</${list.type}>`);
@@ -588,76 +841,76 @@
                 result.push(line);
             }
         }
-        
-        // Close any remaining lists
+
+        // Close any remaining open lists
         while (listStack.length > 0) {
             const list = listStack.pop();
             result.push(`</${list.type}>`);
         }
-        
+
         return result.join('\n');
     }
 
+    // ════════════════════════════════════════════════════════════════════
+    //  Static API
+    // ════════════════════════════════════════════════════════════════════
+
     /**
-     * Emit CSS styles for quikdown elements
-     * @param {string} prefix - Optional class prefix (default: 'quikdown-')
-     * @param {string} theme - Optional theme: 'light' (default) or 'dark'
-     * @returns {string} CSS string with quikdown styles
+     * Emit CSS rules for all quikdown elements.
+     *
+     * @param {string} prefix  Class prefix (default: 'quikdown-')
+     * @param {string} theme   'light' (default) or 'dark'
+     * @returns {string}       CSS text
      */
     quikdown.emitStyles = function(prefix = 'quikdown-', theme = 'light') {
         const styles = QUIKDOWN_STYLES;
-        
-        // Define theme color overrides
+
         const themeOverrides = {
             dark: {
-                '#f4f4f4': '#2a2a2a', // pre background
-                '#f0f0f0': '#2a2a2a', // code background
-                '#f2f2f2': '#2a2a2a', // th background
-                '#ddd': '#3a3a3a',    // borders
-                '#06c': '#6db3f2',    // links
+                '#f4f4f4': '#2a2a2a',   // pre background
+                '#f0f0f0': '#2a2a2a',   // code background
+                '#f2f2f2': '#2a2a2a',   // th background
+                '#ddd': '#3a3a3a',      // borders
+                '#06c': '#6db3f2',      // links
                 _textColor: '#e0e0e0'
             },
             light: {
-                _textColor: '#333'    // Explicit text color for light theme
+                _textColor: '#333'
             }
         };
-        
+
         let css = '';
         for (const [tag, style] of Object.entries(styles)) {
             let themedStyle = style;
-                
-                // Apply theme overrides if dark theme
-                if (theme === 'dark' && themeOverrides.dark) {
-                    // Replace colors
-                    for (const [oldColor, newColor] of Object.entries(themeOverrides.dark)) {
-                        if (!oldColor.startsWith('_')) {
-                            themedStyle = themedStyle.replace(new RegExp(oldColor, 'g'), newColor);
-                        }
-                    }
-                    
-                    // Add text color for certain elements in dark theme
-                    const needsTextColor = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'td', 'li', 'blockquote'];
-                    if (needsTextColor.includes(tag)) {
-                        themedStyle += `;color:${themeOverrides.dark._textColor}`;
-                    }
-                } else if (theme === 'light' && themeOverrides.light) {
-                    // Add explicit text color for light theme elements too
-                    const needsTextColor = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'td', 'li', 'blockquote'];
-                    if (needsTextColor.includes(tag)) {
-                        themedStyle += `;color:${themeOverrides.light._textColor}`;
+
+            if (theme === 'dark' && themeOverrides.dark) {
+                for (const [oldColor, newColor] of Object.entries(themeOverrides.dark)) {
+                    if (!oldColor.startsWith('_')) {
+                        themedStyle = themedStyle.replaceAll(oldColor, newColor);
                     }
                 }
-            
+                const needsTextColor = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'td', 'li', 'blockquote'];
+                if (needsTextColor.includes(tag)) {
+                    themedStyle += `;color:${themeOverrides.dark._textColor}`;
+                }
+            } else if (theme === 'light' && themeOverrides.light) {
+                const needsTextColor = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'td', 'li', 'blockquote'];
+                if (needsTextColor.includes(tag)) {
+                    themedStyle += `;color:${themeOverrides.light._textColor}`;
+                }
+            }
+
             css += `.${prefix}${tag} { ${themedStyle} }\n`;
         }
-        
+
         return css;
     };
 
     /**
-     * Configure quikdown with options and return a function
-     * @param {Object} options - Configuration options
-     * @returns {Function} Configured quikdown function
+     * Create a pre-configured parser with baked-in options.
+     *
+     * @param {Object} options  Options to bake in
+     * @returns {Function}      Configured quikdown(markdown) function
      */
     quikdown.configure = function(options) {
         return function(markdown) {
@@ -665,18 +918,18 @@
         };
     };
 
-    /**
-     * Version information
-     */
+    /** Semantic version (injected at build time) */
     quikdown.version = quikdownVersion;
 
-    // Export for both CommonJS and ES6
+    // ════════════════════════════════════════════════════════════════════
+    //  Exports
+    // ════════════════════════════════════════════════════════════════════
+
     /* istanbul ignore next */
     if (typeof module !== 'undefined' && module.exports) {
         module.exports = quikdown;
     }
 
-    // For browser global
     /* istanbul ignore next */
     if (typeof window !== 'undefined') {
         window.quikdown = quikdown;