quikdown 1.2.7 → 1.2.9

package/dist/quikdown_edit.umd.js

@@ -1,6 +1,6 @@
 /**
  * Quikdown Editor - Drop-in Markdown Parser
- * @version 1.2.7
+ * @version 1.2.9
  * @license BSD-2-Clause
  * @copyright DeftIO 2025
  */
@@ -11,30 +11,245 @@
 })(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';
+    /**
+     * Full CommonMark HR check: three or more identical characters from
+     * {-, *, _} with optional interspersed whitespace.
+     *
+     * Examples that return true:  ---, ***, ___, ----, - - -, * * *, _  _  _
+     * Examples that return false: --, - text, ---text, mixed -_*, empty
+     *
+     * Algorithm (O(n), single pass, no backtracking):
+     *   1. Strip all whitespace
+     *   2. Verify length >= 3
+     *   3. First char must be -, *, or _
+     *   4. Every remaining char must equal the first
+     *
+     * @param {string} trimmed  The line, already trimmed
+     * @returns {boolean}
+     */
+    function isHRLine(trimmed) {
+        if (trimmed.length < 3) return false;
+
+        // Strip whitespace via linear scan
+        let stripped = '';
+        for (let i = 0; i < trimmed.length; i++) {
+            const ch = trimmed[i];
+            if (ch !== ' ' && ch !== '\t') stripped += ch;
+        }
+
+        if (stripped.length < 3) return false;
+
+        const ch = stripped[0];
+        if (ch !== '-' && ch !== '*' && ch !== '_') return false;
+
+        for (let i = 1; i < stripped.length; i++) {
+            if (stripped[i] !== ch) return false;
+        }
+        return true;
+    }
+
+    /**
+     * 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
+    }
+
+    /**
+     * Check if a trimmed line opens a code fence.
+     * Returns { char, len, lang } if it does, or null otherwise.
+     *
+     * A fence opener is 3+ identical backticks or tildes at the start of a line,
+     * optionally followed by a language tag.
+     *
+     * @param {string} trimmed  The line, already trimmed
+     * @returns {{ char: string, len: number, lang: string } | null}
+     */
+    function fenceOpen(trimmed) {
+        if (trimmed.length < 3) return null;
+        const ch = trimmed[0];
+        if (ch !== '`' && ch !== '~') return null;
 
-    // Constants for reuse
+        let len = 1;
+        while (len < trimmed.length && trimmed[len] === ch) len++;
+        if (len < 3) return null;
+
+        const lang = trimmed.slice(len).trim();
+        return { char: ch, len, lang };
+    }
+
+    /**
+     * Check if a trimmed line closes an open fence.
+     * The closing fence must use the same character, be at least as long,
+     * and have no content after (optional trailing whitespace only).
+     *
+     * @param {string} trimmed   The line, already trimmed
+     * @param {string} openChar  The fence character ('`' or '~')
+     * @param {number} openLen   Length of the opening fence marker
+     * @returns {boolean}
+     */
+    function isFenceClose(trimmed, openChar, openLen) {
+        if (trimmed.length < openLen) return false;
+
+        let len = 0;
+        while (len < trimmed.length && trimmed[len] === openChar) len++;
+        if (len < openLen) return false;
+
+        // Rest must be whitespace only
+        for (let i = len; i < trimmed.length; i++) {
+            if (trimmed[i] !== ' ' && trimmed[i] !== '\t') return false;
+        }
+        return true;
+    }
+
+    /**
+     * Classify a content line into a category string.
+     * Order matters: HR before list-ul (since `- - -` looks like a list start).
+     *
+     * @param {string} trimmed  The line, already trimmed
+     * @returns {string}  One of: 'heading', 'hr', 'list-ol', 'list-ul',
+     *                    'blockquote', 'table', 'paragraph'
+     */
+    function classifyLine(trimmed) {
+        if (/^#{1,6}\s/.test(trimmed))         return 'heading';
+        if (isHRLine(trimmed))                 return 'hr';
+        if (/^\d+\.\s/.test(trimmed))          return 'list-ol';
+        if (/^[-*+]\s/.test(trimmed))          return 'list-ul';
+        if (/^>/.test(trimmed))                return 'blockquote';
+        if (/^\|/.test(trimmed))               return 'table';
+        return 'paragraph';
+    }
+
+    /**
+     * Heuristic: does a line look like a markdown table row?
+     * @param {string} line  The line (trimmed or untrimmed)
+     * @returns {boolean}
+     */
+    function looksLikeTableRow(line) {
+        return line.includes('|');
+    }
+
+    /**
+     * 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 +272,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 +315,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 +401,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 +411,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 +506,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 +578,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 +732,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 +765,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 +778,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 +788,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 +824,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 +856,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 +939,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 +951,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 +1028,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;
@@ -2158,8 +2521,8 @@
                             if (w > 0 && h > 0 && overlaps && style.display !== 'none' && style.visibility !== 'hidden') {
                                 ctx.drawImage(tile, x, y, w + 1, h + 1);
                             }
-                        } catch (e) {
-                            console.warn('Failed to draw tile:', e);
+                        } catch (_e) {
+                            console.warn('Failed to draw tile:', _e);
                         }
                     }
 
@@ -2178,8 +2541,8 @@
                             const h = Math.round(r.height);
                             const overlaps = !(r.right <= leafRect.left || r.left >= leafRect.right || r.bottom <= leafRect.top || r.top >= leafRect.bottom);
                             if (w > 0 && h > 0 && overlaps) ctx.drawImage(img, x, y, w, h);
-                        } catch (e) {
-                            console.warn('Failed to draw overlay SVG:', e);
+                        } catch (_e) {
+                            console.warn('Failed to draw overlay SVG:', _e);
                         }
                     }
 
@@ -2197,8 +2560,8 @@
                             if (w > 0 && h > 0 && overlaps && style.display !== 'none' && style.visibility !== 'hidden') {
                                 ctx.drawImage(icon, x, y, w, h);
                             }
-                        } catch (e) {
-                            console.warn('Failed to draw marker icon:', e);
+                        } catch (_e) {
+                            console.warn('Failed to draw marker icon:', _e);
                         }
                     }
 
@@ -2626,13 +2989,28 @@
         },
         math: {
             check: () => typeof window.MathJax !== 'undefined',
-            script: 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js',
+            script: 'https://cdn.jsdelivr.net/npm/mathjax@3.2.2/es5/tex-svg.js',
             beforeLoad: () => {
                 // Configure MathJax before loading (must be set on window before script runs)
+                // Must match the config in ensureMathJaxLoaded() for consistent behavior
                 if (!window.MathJax) {
                     window.MathJax = {
-                        tex: { inlineMath: [['$', '$'], ['\\(', '\\)']], displayMath: [['$$', '$$'], ['\\[', '\\]']] },
-                        svg: { fontCache: 'global' },
+                        loader: { load: ['input/tex', 'output/svg'] },
+                        tex: {
+                            packages: { '[+]': ['ams'] },
+                            inlineMath: [['$', '$'], ['\\(', '\\)']],
+                            displayMath: [['$$', '$$'], ['\\[', '\\]']],
+                            processEscapes: true,
+                            processEnvironments: true
+                        },
+                        options: {
+                            renderActions: { addMenu: [] },
+                            ignoreHtmlClass: 'tex2jax_ignore',
+                            processHtmlClass: 'tex2jax_process'
+                        },
+                        svg: {
+                            fontCache: 'none'  // self-contained SVGs (required for copy-rendered)
+                        },
                         startup: { typeset: false }
                     };
                 }
@@ -2769,7 +3147,14 @@
                 btn.title = `Switch to ${modeLabels[mode]} view`;
                 toolbar.appendChild(btn);
             });
-            
+
+            // Mobile split toggle (hidden by default, shown via CSS on narrow viewports)
+            const splitToggle = document.createElement('button');
+            splitToggle.className = 'qde-btn qde-split-toggle';
+            splitToggle.textContent = 'Preview';
+            splitToggle.title = 'Toggle between source and preview in split mode';
+            toolbar.appendChild(splitToggle);
+
             // Undo/Redo buttons (if enabled)
             if (this.options.showUndoRedo) {
                 const undoBtn = document.createElement('button');
@@ -2854,6 +3239,7 @@
             .qde-toolbar {
                 display: flex;
                 align-items: center;
+                flex-wrap: wrap;
                 padding: 8px;
                 background: #f5f5f5;
                 border-bottom: 1px solid #ddd;
@@ -3239,19 +3625,45 @@
                 background: #252525;
             }
             
-            /* Mobile responsive */
-            @media (max-width: 768px) {
-                .qde-mode-split .qde-editor {
-                    flex-direction: column;
-                }
+            /* Mobile split toggle — hidden by default */
+            .qde-split-toggle { display: none; }
 
-                .qde-mode-split .qde-source {
-                    border-right: none;
-                    border-bottom: 1px solid #ddd;
+            /* Mobile responsive — compact toolbar for all small screens */
+            @media (max-width: 720px) {
+                .qde-toolbar {
+                    padding: 6px;
+                    gap: 3px;
                 }
-                .qde-dark.qde-mode-split .qde-source {
-                    border-bottom-color: #444;
+                .qde-btn {
+                    padding: 5px 8px;
+                    font-size: 12px;
                 }
+                .qde-source, .qde-preview {
+                    padding: 10px;
+                }
+                .qde-textarea {
+                    padding: 10px;
+                }
+                /* Undo/Redo: show circular arrows instead of text */
+                .qde-btn[data-action="undo"] { font-size: 0; }
+                .qde-btn[data-action="undo"]::after { content: "\\21B6"; font-size: 14px; }
+                .qde-btn[data-action="redo"] { font-size: 0; }
+                .qde-btn[data-action="redo"]::after { content: "\\21B7"; font-size: 14px; }
+                /* Hide secondary utility buttons to reduce clutter */
+                .qde-btn[data-action="remove-hr"],
+                .qde-btn[data-action="lazy-linefeeds"],
+                .qde-btn[data-action="copy-rendered"] { display: none; }
+            }
+
+            /* Portrait mobile: drop split mode entirely */
+            @media (max-width: 720px) and (orientation: portrait) {
+                .qde-btn[data-mode="split"] { display: none; }
+                .qde-split-toggle { display: none !important; }
+                /* Fallback: if still in split mode, show source only */
+                .qde-mode-split .qde-source { border-right: none; }
+                .qde-mode-split .qde-preview { display: none; }
+                .qde-mode-split.qde-split-preview .qde-source { display: none; }
+                .qde-mode-split.qde-split-preview .qde-preview { display: block; }
             }
         `;
             
@@ -3277,7 +3689,15 @@
                 this.toolbar.addEventListener('click', (e) => {
                     const btn = e.target.closest('.qde-btn');
                     if (!btn) return;
-                    
+
+                    // Mobile split-toggle button
+                    if (btn.classList.contains('qde-split-toggle')) {
+                        this.container.classList.toggle('qde-split-preview');
+                        const showingPreview = this.container.classList.contains('qde-split-preview');
+                        btn.textContent = showingPreview ? 'Source' : 'Preview';
+                        return;
+                    }
+
                     if (btn.dataset.mode) {
                         this.setMode(btn.dataset.mode);
                     } else if (btn.dataset.action) {
@@ -3320,8 +3740,22 @@
                     }
                 }
             });
+
+            // On narrow portrait viewports, auto-switch out of split mode to source.
+            // Split is kept available on landscape where there is enough width.
+            if (typeof window.matchMedia === 'function') {
+                const portraitQuery = window.matchMedia('(max-width: 720px) and (orientation: portrait)');
+                const switchIfPortrait = () => {
+                    if (portraitQuery.matches && this.currentMode === 'split') {
+                        this.setMode('source');
+                    }
+                };
+                // Check after init's setMode() has run (microtask fires after sync code).
+                Promise.resolve().then(switchIfPortrait);
+                portraitQuery.addEventListener('change', switchIfPortrait);
+            }
         }
-        
+
         /**
          * Handle source textarea input
          */
@@ -4428,6 +4862,7 @@
             // below would otherwise wipe it out — this used to be a no-op bug
             // where dark mode was lost on every setMode call).
             const wasDark = this.container.classList.contains('qde-dark');
+            const previousMode = this.currentMode;
 
             this.currentMode = mode;
             this.container.className = `qde-container qde-mode-${mode}`;
@@ -4435,18 +4870,37 @@
                 this.container.classList.add('qde-dark');
             }
 
+            // Reset mobile split-toggle button text
+            if (this.toolbar) {
+                const splitToggle = this.toolbar.querySelector('.qde-split-toggle');
+                if (splitToggle) {
+                    splitToggle.textContent = 'Preview';
+                }
+            }
+
             // Update toolbar buttons
             if (this.toolbar) {
                 this.toolbar.querySelectorAll('.qde-btn[data-mode]').forEach(btn => {
                     btn.classList.toggle('active', btn.dataset.mode === mode);
                 });
             }
-            
-            // Make fence blocks non-editable when showing preview
-            if (mode !== 'source') {
+
+            // If the preview was hidden (source-only) it may have missed content
+            // updates. Re-render it now, including MathJax typesetting.
+            // Do NOT re-render if the preview was already visible — that would
+            // destroy MathJax-typeset SVG output with raw pre-typeset HTML.
+            if (mode !== 'source' && previousMode === 'source' && this._html) {
+                this.previewPanel.innerHTML = this._html;
                 setTimeout(() => this.makeFencesNonEditable(), 0);
+                if (typeof window !== 'undefined' && window.MathJax && window.MathJax.typesetPromise) {
+                    const mathElements = this.previewPanel.querySelectorAll('.math-display');
+                    if (mathElements.length > 0) {
+                        window.MathJax.typesetPromise(Array.from(mathElements))
+                            .catch(() => {});
+                    }
+                }
             }
-            
+
             // Trigger mode change event
             if (this.options.onModeChange) {
                 this.options.onModeChange(mode);
@@ -4694,36 +5148,29 @@
             const lines = (markdown || '').split('\n');
             const result = [];
             let inFence = false;
-            let fenceChar = null;  // '`' or '~'
-            let fenceLen = 0;      // length of opening fence marker
+            let openChar = null;
+            let openLen = 0;
 
             for (let i = 0; i < lines.length; i++) {
                 const line = lines[i];
                 const trimmed = line.trim();
 
-                // Track fence open/close (``` or ~~~, 3+ chars)
-                const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
-                if (fenceMatch) {
-                    const matchChar = fenceMatch[1][0];
-                    const matchLen = fenceMatch[1].length;
-                    if (!inFence) {
+                // Track fence open/close
+                if (!inFence) {
+                    const fo = fenceOpen(trimmed);
+                    if (fo) {
                         inFence = true;
-                        fenceChar = matchChar;
-                        fenceLen = matchLen;
+                        openChar = fo.char;
+                        openLen = fo.len;
                         result.push(line);
                         continue;
-                    } else if (matchChar === fenceChar && matchLen >= fenceLen && /^(`{3,}|~{3,})\s*$/.test(trimmed)) {
-                        // Closing fence: same char, at least as many chars, no trailing content
+                    }
+                } else {
+                    if (isFenceClose(trimmed, openChar, openLen)) {
                         inFence = false;
-                        fenceChar = null;
-                        fenceLen = 0;
-                        result.push(line);
-                        continue;
+                        openChar = null;
+                        openLen = 0;
                     }
-                }
-
-                // Inside a fence — keep everything
-                if (inFence) {
                     result.push(line);
                     continue;
                 }
@@ -4734,14 +5181,13 @@
                     continue;
                 }
 
-                // Check if this line is a standalone HR
-                const isHR = /^[-_*](\s*[-_*]){2,}\s*$/.test(trimmed);
-                if (isHR) {
+                // Check if this line is a standalone HR (no ReDoS — linear scan)
+                if (isHRLine(trimmed)) {
                     // Table separator heuristic: immediately adjacent lines (no blank
                     // lines between) that look like table rows protect this HR-like line
                     const prevLine = i > 0 ? lines[i - 1].trim() : '';
                     const nextLine = i < lines.length - 1 ? lines[i + 1].trim() : '';
-                    if (_looksLikeTableRow(prevLine) || _looksLikeTableRow(nextLine)) {
+                    if (looksLikeTableRow(prevLine) || looksLikeTableRow(nextLine)) {
                         result.push(line);
                         continue;
                     }
@@ -4820,30 +5266,28 @@
             //   'blockquote', 'table', 'heading', 'hr', 'paragraph'
             const items = [];
             let inFence = false;
-            let fenceChar = null;
-            let fenceLen = 0;
+            let openChar = null;
+            let openLen = 0;
 
             for (const rawLine of inputLines) {
                 const line = rawLine;
                 const trimmed = line.trim();
 
-                // Fence tracking
-                const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
-                if (fenceMatch && !inFence) {
-                    inFence = true;
-                    fenceChar = fenceMatch[1][0];
-                    fenceLen  = fenceMatch[1].length;
-                    items.push({ line, kind: 'fence-open' });
-                    continue;
-                }
-                if (inFence) {
-                    if (fenceMatch &&
-                        fenceMatch[1][0] === fenceChar &&
-                        fenceMatch[1].length >= fenceLen &&
-                        /^(`{3,}|~{3,})\s*$/.test(trimmed)) {
+                // Fence tracking via shared utilities
+                if (!inFence) {
+                    const fo = fenceOpen(trimmed);
+                    if (fo) {
+                        inFence = true;
+                        openChar = fo.char;
+                        openLen  = fo.len;
+                        items.push({ line, kind: 'fence-open' });
+                        continue;
+                    }
+                } else {
+                    if (isFenceClose(trimmed, openChar, openLen)) {
                         inFence = false;
-                        fenceChar = null;
-                        fenceLen = 0;
+                        openChar = null;
+                        openLen = 0;
                         items.push({ line, kind: 'fence-close' });
                     } else {
                         items.push({ line, kind: 'fence-body' });
@@ -4857,16 +5301,12 @@
                     continue;
                 }
 
-                // Categorize content lines so we can recognize adjacent same-kind blocks
-                let category = 'paragraph';
-                if (/^#{1,6}\s/.test(trimmed))                    category = 'heading';
-                else if (/^[-_*](\s*[-_*]){2,}\s*$/.test(trimmed)) category = 'hr';
-                else if (/^(\d+\.)\s/.test(trimmed))              category = 'list-ol';
-                else if (/^[-*+]\s/.test(trimmed))                category = 'list-ul';
-                else if (/^>/.test(trimmed))                      category = 'blockquote';
-                else if (/^\|/.test(trimmed))                     category = 'table';
+                // Categorize content lines (no ReDoS — classifyLine uses linear scan for HR)
+                let category = classifyLine(trimmed);
                 // Indented continuation of a list (2+ leading spaces or tab)
-                else if (/^(?: {4}|\t| {2,}[-*+]| {2,}\d+\.)/.test(line)) category = 'list-cont';
+                if (category === 'paragraph' && /^(?: {4}|\t| {2,}[-*+]| {2,}\d+\.)/.test(line)) {
+                    category = 'list-cont';
+                }
 
                 items.push({ line, kind: 'content', category });
             }
@@ -4966,13 +5406,6 @@
         }
     }
 
-    // --- Internal helpers for removeHR fence/table awareness ---
-
-    /** Heuristic: does this line look like a markdown table row? */
-    function _looksLikeTableRow(line) {
-        return line.includes('|');
-    }
-
     // Export for CommonJS (needed for bundled ESM to work with Jest)
     if (typeof module !== 'undefined' && module.exports) {
         module.exports = QuikdownEditor;