@fuzdev/fuz_ui 0.169.0

package/dist/mdz.js

@@ -0,0 +1,1481 @@
+/**
+ * mdz - minimal markdown dialect for Fuz documentation.
+ *
+ * Parses an enhanced markdown dialect with:
+ * - inline formatting: `code`, **bold**, _italic_, ~strikethrough~
+ * - auto-detected links: external URLs (`https://...`) and internal paths (`/path`)
+ * - markdown links: `[text](url)` with custom display text
+ * - inline code in backticks (creates `Code` nodes; auto-linking to identifiers/modules
+ *   is handled by the rendering layer via `MdzNodeView.svelte`)
+ * - paragraph breaks (double newline)
+ * - block elements: headings, horizontal rules, code blocks
+ * - HTML elements and Svelte components (opt-in via context)
+ *
+ * Key constraint: preserves ALL whitespace exactly as authored,
+ * and is rendered with white-space pre or pre-wrap.
+ *
+ * ## Design philosophy
+ *
+ * - **False negatives over false positives**: Strict syntax prevents accidentally
+ *   interpreting plain text as formatting. When in doubt, treat as plain text.
+ * - **One way to do things**: Single unambiguous syntax per feature. No alternatives.
+ * - **Explicit over implicit**: Clear delimiters and column-0 requirements avoid ambiguity.
+ * - **Simple over complete**: Prefer simple parsing rules over complex edge case handling.
+ *
+ * ## Status
+ *
+ * This is an early proof of concept with missing features and edge cases.
+ */
+// TODO design incremental parsing or some system that preserves Svelte components across re-renders when possible
+/**
+ * Parses text to an array of `MdzNode`.
+ */
+export const mdz_parse = (text) => new MdzParser(text).parse();
+// Character codes for performance
+const BACKTICK = 96; // `
+const ASTERISK = 42; // *
+const UNDERSCORE = 95; // _
+const TILDE = 126; // ~
+const NEWLINE = 10; // \n
+const HYPHEN = 45; // -
+const HASH = 35; // #
+const SPACE = 32; // (space)
+const TAB = 9; // \t
+const LEFT_ANGLE = 60; // <
+const RIGHT_ANGLE = 62; // >
+const SLASH = 47; // /
+const LEFT_BRACKET = 91; // [
+const RIGHT_BRACKET = 93; // ]
+const LEFT_PAREN = 40; // (
+const RIGHT_PAREN = 41; // )
+const COLON = 58; // :
+const PERIOD = 46; // .
+const COMMA = 44; // ,
+const SEMICOLON = 59; // ;
+const EXCLAMATION = 33; // !
+const QUESTION = 63; // ?
+// RFC 3986 URI characters
+const DOLLAR = 36; // $
+const PERCENT = 37; // %
+const AMPERSAND = 38; // &
+const APOSTROPHE = 39; // '
+const PLUS = 43; // +
+const EQUALS = 61; // =
+const AT = 64; // @
+// Character ranges
+const A_UPPER = 65; // A
+const Z_UPPER = 90; // Z
+const A_LOWER = 97; // a
+const Z_LOWER = 122; // z
+const ZERO = 48; // 0
+const NINE = 57; // 9
+// mdz specification constants
+const HR_HYPHEN_COUNT = 3; // Horizontal rule requires exactly 3 hyphens
+const MIN_CODEBLOCK_BACKTICKS = 3; // Code blocks require minimum 3 backticks
+const MAX_HEADING_LEVEL = 6; // Headings support levels 1-6
+const HTTPS_PREFIX_LENGTH = 8; // Length of "https://"
+const HTTP_PREFIX_LENGTH = 7; // Length of "http://"
+/**
+ * Parser for mdz format.
+ * Single-pass lexer/parser with text accumulation for efficiency.
+ * Used by `mdz_parse`, which should be preferred for simple usage.
+ */
+export class MdzParser {
+    #index = 0;
+    #template;
+    #accumulated_text = '';
+    #accumulated_start = 0;
+    #nodes = [];
+    #max_search_index = Number.MAX_SAFE_INTEGER; // Boundary for delimiter searches
+    constructor(template) {
+        this.#template = template;
+    }
+    /**
+     * Main parse method. Returns flat array of nodes,
+     * with paragraph nodes wrapping content between double newlines.
+     */
+    parse() {
+        this.#nodes.length = 0;
+        const root_nodes = [];
+        const paragraph_children = [];
+        // Check for block element at document start
+        const start_block = this.#try_parse_block_element();
+        if (start_block) {
+            root_nodes.push(start_block);
+        }
+        while (this.#index < this.#template.length) {
+            // Check for paragraph break (double newline)
+            if (this.#is_at_paragraph_break()) {
+                this.#flush_text();
+                // Move flushed nodes to paragraph_children
+                if (this.#nodes.length > 0) {
+                    paragraph_children.push(...this.#nodes);
+                    this.#nodes.length = 0;
+                }
+                // Wrap accumulated nodes in paragraph (or add single tag directly)
+                if (paragraph_children.length > 0) {
+                    if (this.#is_single_tag(paragraph_children)) {
+                        // Single tag (component/element) - add directly without paragraph wrapper (MDX convention)
+                        const tag = paragraph_children.find((n) => n.type === 'Component' || n.type === 'Element');
+                        root_nodes.push(tag);
+                    }
+                    else {
+                        // Regular paragraph
+                        root_nodes.push({
+                            type: 'Paragraph',
+                            children: paragraph_children.slice(),
+                            start: paragraph_children[0].start,
+                            end: paragraph_children[paragraph_children.length - 1].end,
+                        });
+                    }
+                    paragraph_children.length = 0;
+                }
+                // Consume the paragraph break
+                this.#eat('\n\n');
+                // Check for block element after paragraph break
+                const block = this.#try_parse_block_element();
+                if (block) {
+                    root_nodes.push(block);
+                }
+            }
+            else {
+                const node = this.#parse_node();
+                if (node.type === 'Text') {
+                    this.#accumulate_text(node.content, node.start);
+                }
+                else {
+                    this.#flush_text();
+                    this.#nodes.push(node);
+                }
+                if (this.#nodes.length > 0) {
+                    paragraph_children.push(...this.#nodes);
+                    this.#nodes.length = 0;
+                }
+            }
+        }
+        this.#flush_text();
+        if (this.#nodes.length > 0) {
+            paragraph_children.push(...this.#nodes);
+        }
+        // Wrap remaining nodes in final paragraph if any (or add single tag directly)
+        if (paragraph_children.length > 0) {
+            if (this.#is_single_tag(paragraph_children)) {
+                // Single tag (component/element) - add directly without paragraph wrapper (MDX convention)
+                const tag = paragraph_children.find((n) => n.type === 'Component' || n.type === 'Element');
+                root_nodes.push(tag);
+            }
+            else {
+                // Regular paragraph
+                root_nodes.push({
+                    type: 'Paragraph',
+                    children: paragraph_children,
+                    start: paragraph_children[0].start,
+                    end: paragraph_children[paragraph_children.length - 1].end,
+                });
+            }
+        }
+        return root_nodes;
+    }
+    /**
+     * Accumulate text for later flushing (performance optimization).
+     */
+    #accumulate_text(text, start) {
+        if (this.#accumulated_text === '') {
+            this.#accumulated_start = start;
+        }
+        this.#accumulated_text += text;
+    }
+    #flush_text() {
+        if (this.#accumulated_text !== '') {
+            this.#nodes.push({
+                type: 'Text',
+                content: this.#accumulated_text,
+                start: this.#accumulated_start,
+                end: this.#accumulated_start + this.#accumulated_text.length,
+            });
+            this.#accumulated_text = '';
+        }
+    }
+    /**
+     * Create a text node and advance index past the content.
+     * Used when formatting delimiters fail to match and need to be treated as literal text.
+     */
+    #make_text_node(content, start) {
+        this.#index = start + content.length;
+        return {
+            type: 'Text',
+            content,
+            start,
+            end: this.#index,
+        };
+    }
+    /**
+     * Parse next node based on current character.
+     * Uses switch for performance (avoids regex in hot loop).
+     */
+    #parse_node() {
+        const char_code = this.#current_char();
+        // Use character codes for performance in hot path
+        switch (char_code) {
+            case BACKTICK:
+                return this.#parse_code();
+            case ASTERISK:
+                return this.#parse_bold();
+            case UNDERSCORE:
+                return this.#parse_italic();
+            case TILDE:
+                return this.#parse_strikethrough();
+            case LEFT_BRACKET:
+                return this.#parse_markdown_link();
+            case LEFT_ANGLE:
+                return this.#parse_tag();
+            default:
+                return this.#parse_text();
+        }
+    }
+    /**
+     * Parse backtick code: `code`
+     * Auto-links to identifiers/modules if match found.
+     * Falls back to text if unclosed, empty, or if newline encountered before closing backtick.
+     */
+    #parse_code() {
+        const start = this.#index;
+        this.#eat('`');
+        const content_start = this.#index;
+        // Find closing backtick, but stop at newline (respect boundary for greedy matching)
+        let content_end = -1;
+        const search_limit = Math.min(this.#max_search_index, this.#template.length);
+        for (let i = this.#index; i < search_limit; i++) {
+            const char_code = this.#template.charCodeAt(i);
+            if (char_code === BACKTICK) {
+                content_end = i;
+                break;
+            }
+            if (char_code === NEWLINE) {
+                // Newline before closing backtick - treat as unclosed
+                break;
+            }
+        }
+        if (content_end === -1) {
+            // Unclosed backtick or newline encountered, treat as text
+            return this.#make_text_node('`', start);
+        }
+        const content = this.#template.slice(content_start, content_end);
+        // Empty inline code has no semantic meaning, treat as literal text
+        if (content.length === 0) {
+            return this.#make_text_node('``', start);
+        }
+        this.#index = content_end + 1;
+        return {
+            type: 'Code',
+            content,
+            start,
+            end: this.#index,
+        };
+    }
+    /**
+     * Parse bold starting with double asterisk.
+     *
+     * - **bold** = Bold node
+     *
+     * Falls back to text if unclosed or single asterisk.
+     *
+     * Bold has no word boundary restrictions and works everywhere including intraword.
+     * Examples:
+     * - `foo**bar**baz` → foo<strong>bar</strong>baz (creates bold)
+     * - `word **bold** word` → word <strong>bold</strong> word (also works)
+     */
+    #parse_bold() {
+        const start = this.#index;
+        // Check for ** (bold)
+        if (this.#match('**')) {
+            // Bold (**) has no word boundary restrictions - works everywhere including intraword
+            this.#eat('**');
+            // Find closing ** (greedy matching - first occurrence within boundary)
+            const search_end = Math.min(this.#max_search_index, this.#template.length);
+            let close_index = this.#template.indexOf('**', this.#index);
+            // Check if close_index exceeds search boundary
+            if (close_index !== -1 && close_index >= search_end) {
+                close_index = -1;
+            }
+            if (close_index === -1) {
+                // Unclosed, treat as text
+                return this.#make_text_node('**', start);
+            }
+            // No word boundary check for closing ** - works everywhere
+            // Parse children up to closing delimiter (bounded parsing)
+            const children = this.#parse_nodes_until('**', close_index);
+            // Verify we're at the closing delimiter (could have stopped early due to paragraph break)
+            if (!this.#match('**')) {
+                // Interrupted before closing - treat as unclosed
+                return this.#make_text_node('**', start);
+            }
+            // Empty bold has no semantic meaning, treat as literal text
+            if (children.length === 0) {
+                this.#index = start;
+                return this.#make_text_node('****', start);
+            }
+            // Consume closing **
+            this.#eat('**');
+            return {
+                type: 'Bold',
+                children,
+                start,
+                end: this.#index,
+            };
+        }
+        // Single asterisk - treat as text
+        const content = this.#template[this.#index];
+        return this.#make_text_node(content, start);
+    }
+    #parse_single_delimiter_formatting(delimiter, node_type) {
+        const start = this.#index;
+        // Check if opening delimiter is at word boundary
+        if (!this.#is_at_word_boundary(this.#index, true, false)) {
+            // Intraword delimiter - treat as literal text
+            const content = this.#template[this.#index];
+            return this.#make_text_node(content, start);
+        }
+        this.#eat(delimiter);
+        // Find closing delimiter (greedy matching - first occurrence within boundary)
+        const search_end = Math.min(this.#max_search_index, this.#template.length);
+        let close_index = this.#template.indexOf(delimiter, this.#index);
+        // Check if close_index exceeds search boundary
+        if (close_index !== -1 && close_index >= search_end) {
+            close_index = -1;
+        }
+        if (close_index === -1) {
+            // Unclosed, treat as text
+            return this.#make_text_node(delimiter, start);
+        }
+        // Check if closing delimiter is at word boundary
+        if (!this.#is_at_word_boundary(close_index + 1, false, true)) {
+            // Closing delimiter not at boundary - treat whole thing as text
+            return this.#make_text_node(delimiter, start);
+        }
+        // Parse children up to closing delimiter (bounded parsing)
+        const children = this.#parse_nodes_until(delimiter, close_index);
+        // Verify we're at the closing delimiter (could have stopped early due to paragraph break)
+        if (!this.#match(delimiter)) {
+            // Interrupted before closing - treat as unclosed
+            return this.#make_text_node(delimiter, start);
+        }
+        // Empty formatting has no semantic meaning, treat as literal text
+        if (children.length === 0) {
+            this.#index = start;
+            return this.#make_text_node(delimiter + delimiter, start);
+        }
+        // Consume closing delimiter
+        this.#eat(delimiter);
+        return {
+            type: node_type,
+            children,
+            start,
+            end: this.#index,
+        };
+    }
+    /**
+     * Parse italic starting with underscore.
+     * _italic_ = Italic node
+     * Falls back to text if unclosed or not at word boundary.
+     *
+     * Following GFM spec: underscores cannot create emphasis in middle of words.
+     * Examples:
+     * - `foo_bar_baz` → literal text (intraword)
+     * - `word _emphasis_ word` → emphasis (at word boundaries)
+     */
+    #parse_italic() {
+        return this.#parse_single_delimiter_formatting('_', 'Italic');
+    }
+    /**
+     * Parse strikethrough starting with tilde.
+     * ~strikethrough~ = Strikethrough node
+     * Falls back to text if unclosed or not at word boundary.
+     *
+     * Following mdz philosophy (false negatives over false positives):
+     * Strikethrough requires word boundaries to prevent intraword formatting.
+     * Examples:
+     * - `foo~bar~baz` → literal text (intraword)
+     * - `word ~strike~ word` → strikethrough (at word boundaries)
+     */
+    #parse_strikethrough() {
+        return this.#parse_single_delimiter_formatting('~', 'Strikethrough');
+    }
+    /**
+     * Parse markdown link: `[text](url)`.
+     * Falls back to text if malformed.
+     */
+    #parse_markdown_link() {
+        const start = this.#index;
+        // Consume opening [
+        if (!this.#match('[')) {
+            const content = this.#template[this.#index];
+            this.#index++;
+            return {
+                type: 'Text',
+                content,
+                start,
+                end: this.#index,
+            };
+        }
+        this.#index++;
+        // Parse children nodes until closing ]
+        const children = this.#parse_nodes_until(']');
+        // Check if we found the closing ]
+        if (!this.#match(']')) {
+            // No closing ], treat as text
+            this.#index = start + 1;
+            return {
+                type: 'Text',
+                content: '[',
+                start,
+                end: this.#index,
+            };
+        }
+        this.#index++; // consume ]
+        // Check for opening (
+        if (this.#index >= this.#template.length ||
+            this.#template.charCodeAt(this.#index) !== LEFT_PAREN) {
+            // No opening (, treat as text
+            this.#index = start + 1;
+            return {
+                type: 'Text',
+                content: '[',
+                start,
+                end: this.#index,
+            };
+        }
+        this.#index++;
+        // Find closing )
+        const close_paren = this.#template.indexOf(')', this.#index);
+        if (close_paren === -1) {
+            // No closing ), treat as text
+            this.#index = start + 1;
+            return {
+                type: 'Text',
+                content: '[',
+                start,
+                end: this.#index,
+            };
+        }
+        // Extract URL/path
+        const reference = this.#template.slice(this.#index, close_paren);
+        // Validate reference is not empty or whitespace-only
+        if (!reference.trim()) {
+            // Empty reference, treat as text
+            this.#index = start + 1;
+            return {
+                type: 'Text',
+                content: '[',
+                start,
+                end: this.#index,
+            };
+        }
+        // Validate all characters in reference are valid URI characters per RFC 3986
+        // This prevents spaces and other invalid characters from being in markdown link URLs
+        // Follows GFM behavior: invalid chars cause fallback to text, then auto-detection
+        for (let i = 0; i < reference.length; i++) {
+            const char_code = reference.charCodeAt(i);
+            if (!this.#is_valid_path_char(char_code)) {
+                // Invalid character in URL, treat as text and let auto-detection handle it
+                this.#index = start + 1;
+                return {
+                    type: 'Text',
+                    content: '[',
+                    start,
+                    end: this.#index,
+                };
+            }
+        }
+        this.#index = close_paren + 1;
+        // Determine link type (external vs internal)
+        const link_type = reference.startsWith('https://') || reference.startsWith('http://') ? 'external' : 'internal';
+        return {
+            type: 'Link',
+            reference,
+            children,
+            link_type,
+            start,
+            end: this.#index,
+        };
+    }
+    /**
+     * Parse component/element tag: `<TagName>content</TagName>` or `<TagName />`
+     *
+     * Formats:
+     * - `<Alert>content</Alert>` - Svelte component with children (uppercase first letter)
+     * - `<div>content</div>` - HTML element with children (lowercase first letter)
+     * - `<Alert />` - self-closing component/element
+     *
+     * Tag names must start with a letter and can contain letters, numbers, hyphens, underscores.
+     *
+     * Falls back to text if malformed or unclosed.
+     *
+     * TODO: Add attribute support like `<Alert status="error">` or `<div class="container">`
+     */
+    #parse_tag() {
+        const start = this.#index;
+        // Save parent accumulation state to avoid polluting component children with parent's accumulated text
+        const saved_state = this.#save_accumulation_state();
+        // Clear accumulation state for parsing component children
+        this.#accumulated_text = '';
+        this.#nodes.length = 0;
+        // Consume <
+        if (!this.#match('<')) {
+            // Restore parent state before returning
+            this.#restore_accumulation_state(saved_state);
+            const content = this.#template[this.#index];
+            this.#index++;
+            return {
+                type: 'Text',
+                content,
+                start,
+                end: this.#index,
+            };
+        }
+        this.#index++;
+        // Parse tag name
+        const tag_name_start = this.#index;
+        let tag_name_end = this.#index;
+        // Tag name must start with a letter
+        if (this.#index >= this.#template.length) {
+            // Just a `<` at EOF - restore parent state
+            this.#restore_accumulation_state(saved_state);
+            return {
+                type: 'Text',
+                content: '<',
+                start,
+                end: this.#index,
+            };
+        }
+        const first_char = this.#template.charCodeAt(this.#index);
+        if (!this.#is_letter(first_char)) {
+            // Not a valid tag, treat as text - restore parent state
+            this.#restore_accumulation_state(saved_state);
+            return {
+                type: 'Text',
+                content: '<',
+                start,
+                end: start + 1,
+            };
+        }
+        // Collect tag name (letters, numbers, hyphens, underscores)
+        while (this.#index < this.#template.length) {
+            const char_code = this.#template.charCodeAt(this.#index);
+            if (this.#is_tag_name_char(char_code)) {
+                this.#index++;
+            }
+            else {
+                break;
+            }
+        }
+        tag_name_end = this.#index;
+        const tag_name = this.#template.slice(tag_name_start, tag_name_end);
+        if (tag_name.length === 0) {
+            // Empty tag name - restore parent state
+            this.#restore_accumulation_state(saved_state);
+            return {
+                type: 'Text',
+                content: '<',
+                start,
+                end: start + 1,
+            };
+        }
+        // Determine if this is a Component (uppercase) or Element (lowercase)
+        const first_char_code = tag_name.charCodeAt(0);
+        const is_component = first_char_code >= A_UPPER && first_char_code <= Z_UPPER;
+        const node_type = is_component ? 'Component' : 'Element';
+        // Skip whitespace after tag name (for future attribute support)
+        while (this.#index < this.#template.length &&
+            this.#template.charCodeAt(this.#index) === SPACE) {
+            this.#index++;
+        }
+        // TODO: Parse attributes here
+        // Check for self-closing />
+        if (this.#index + 1 < this.#template.length &&
+            this.#template.charCodeAt(this.#index) === SLASH &&
+            this.#template.charCodeAt(this.#index + 1) === RIGHT_ANGLE) {
+            this.#index += 2;
+            // Restore parent state before returning
+            this.#restore_accumulation_state(saved_state);
+            return {
+                type: node_type,
+                name: tag_name,
+                children: [],
+                start,
+                end: this.#index,
+            };
+        }
+        // Check for closing >
+        if (this.#index >= this.#template.length ||
+            this.#template.charCodeAt(this.#index) !== RIGHT_ANGLE) {
+            // Unclosed opening tag, treat as text - restore parent state
+            this.#restore_accumulation_state(saved_state);
+            this.#index = start + 1;
+            return {
+                type: 'Text',
+                content: '<',
+                start,
+                end: this.#index,
+            };
+        }
+        // Consume >
+        this.#index++;
+        // Parse children until closing tag
+        const closing_tag = `</${tag_name}>`;
+        const children = [];
+        while (this.#index < this.#template.length) {
+            // Check for closing tag
+            if (this.#match(closing_tag)) {
+                // Flush any accumulated text from children
+                this.#flush_text();
+                children.push(...this.#nodes);
+                this.#nodes.length = 0;
+                this.#index += closing_tag.length;
+                // Restore parent state before returning
+                this.#restore_accumulation_state(saved_state);
+                return {
+                    type: node_type,
+                    name: tag_name,
+                    children,
+                    start,
+                    end: this.#index,
+                };
+            }
+            const node = this.#parse_node();
+            if (node.type === 'Text') {
+                this.#accumulate_text(node.content, node.start);
+            }
+            else {
+                this.#flush_text();
+                children.push(...this.#nodes);
+                this.#nodes.length = 0;
+                children.push(node);
+            }
+        }
+        // Unclosed tag - reached EOF without finding closing tag
+        // Treat the opening tag as text - restore parent state
+        this.#restore_accumulation_state(saved_state);
+        this.#index = start + 1;
+        return {
+            type: 'Text',
+            content: '<',
+            start,
+            end: this.#index,
+        };
+    }
+    /**
+     * Check if nodes represent a single tag (component or element) with only whitespace text nodes.
+     * Used to determine if paragraph wrapping should be skipped (MDX convention).
+     * Returns true if there's exactly one Component/Element node and all other nodes are whitespace-only Text nodes.
+     */
+    #is_single_tag(nodes) {
+        let found_tag = false;
+        for (const node of nodes) {
+            if (node.type === 'Component' || node.type === 'Element') {
+                if (found_tag)
+                    return false; // Multiple tags
+                found_tag = true;
+            }
+            else if (node.type === 'Text') {
+                // Allow only whitespace-only text nodes
+                if (node.content.trim() !== '')
+                    return false;
+            }
+            else {
+                // Any other node type means not a single tag
+                return false;
+            }
+        }
+        return found_tag;
+    }
+    /**
+     * Try to parse a block element (heading, hr, or codeblock) at current position.
+     * Returns the parsed block node if a match is found, null otherwise.
+     *
+     * Block elements must:
+     * - Start at column 0 (no leading whitespace)
+     * - Be followed by blank line or EOF
+     *
+     * This helper eliminates duplication between document start and post-paragraph-break parsing.
+     */
+    #try_parse_block_element() {
+        if (this.#match_heading()) {
+            return this.#parse_heading();
+        }
+        else if (this.#match_hr()) {
+            return this.#parse_hr();
+        }
+        else if (this.#match_code_block()) {
+            return this.#parse_code_block();
+        }
+        return null;
+    }
+    /**
+     * Save current text accumulation state.
+     * Used when parsing nested structures (like components/elements) that need isolated accumulation.
+     * Returns state object that can be passed to `#restore_accumulation_state()`.
+     */
+    #save_accumulation_state() {
+        return {
+            accumulated_text: this.#accumulated_text,
+            accumulated_start: this.#accumulated_start,
+            nodes: this.#nodes.slice(),
+        };
+    }
+    /**
+     * Restore previously saved text accumulation state.
+     * Used to restore parent state when exiting nested structure parsing.
+     * @param state - State object returned from `#save_accumulation_state()`
+     */
+    #restore_accumulation_state(state) {
+        this.#accumulated_text = state.accumulated_text;
+        this.#accumulated_start = state.accumulated_start;
+        this.#nodes.length = 0;
+        this.#nodes.push(...state.nodes);
+    }
+    /**
+     * Check if character code is a letter (A-Z, a-z).
+     */
+    #is_letter(char_code) {
+        return ((char_code >= A_UPPER && char_code <= Z_UPPER) ||
+            (char_code >= A_LOWER && char_code <= Z_LOWER));
+    }
+    /**
+     * Check if character code is valid for tag name (letter, number, hyphen, underscore).
+     */
+    #is_tag_name_char(char_code) {
+        return (this.#is_letter(char_code) ||
+            (char_code >= ZERO && char_code <= NINE) ||
+            char_code === HYPHEN ||
+            char_code === UNDERSCORE);
+    }
+    /**
+     * Check if character is part of a word for word boundary detection.
+     * Used to prevent intraword emphasis with `_` and `~` delimiters.
+     *
+     * Formatting delimiters (`*`, `_`, `~`) are NOT word characters - they're transparent.
+     * Only alphanumeric characters (A-Z, a-z, 0-9) are considered word characters.
+     *
+     * This prevents false positives with snake_case identifiers while allowing
+     * adjacent formatting like `**bold**_italic_`.
+     *
+     * @param char_code - Character code to check
+     */
+    #is_word_char(char_code) {
+        // Formatting delimiters are never word chars (transparent for boundary checks)
+        if (char_code === ASTERISK || char_code === UNDERSCORE || char_code === TILDE) {
+            return false;
+        }
+        // Alphanumeric characters are word chars for all delimiters
+        return ((char_code >= A_UPPER && char_code <= Z_UPPER) ||
+            (char_code >= A_LOWER && char_code <= Z_LOWER) ||
+            (char_code >= ZERO && char_code <= NINE));
+    }
+    /**
+     * Check if position is at a word boundary.
+     * Word boundary = not surrounded by word characters (A-Z, a-z, 0-9).
+     * Used to prevent intraword emphasis for underscores and tildes.
+     *
+     * @param index - Position to check
+     * @param check_before - Whether to check the character before this position
+     * @param check_after - Whether to check the character after this position
+     */
+    #is_at_word_boundary(index, check_before, check_after) {
+        if (check_before && index > 0) {
+            const prev = this.#template.charCodeAt(index - 1);
+            // If preceded by word char, not at boundary
+            if (this.#is_word_char(prev)) {
+                return false;
+            }
+        }
+        if (check_after && index < this.#template.length) {
+            const next = this.#template.charCodeAt(index);
+            // If followed by word char, not at boundary
+            if (this.#is_word_char(next)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Check if character code is valid in URI path per RFC 3986.
+     * Validates against the `pchar` production plus path/query/fragment separators.
+     *
+     * Valid characters:
+     * - unreserved: A-Z a-z 0-9 - . _ ~
+     * - sub-delims: ! $ & ' ( ) * + , ; =
+     * - path allowed: : @
+     * - separators: / ? #
+     * - percent-encoding: %
+     */
+    #is_valid_path_char(char_code) {
+        return ((char_code >= A_UPPER && char_code <= Z_UPPER) ||
+            (char_code >= A_LOWER && char_code <= Z_LOWER) ||
+            (char_code >= ZERO && char_code <= NINE) ||
+            // unreserved: - . _ ~
+            char_code === HYPHEN ||
+            char_code === PERIOD ||
+            char_code === UNDERSCORE ||
+            char_code === TILDE ||
+            // sub-delims: ! $ & ' ( ) * + , ; =
+            char_code === EXCLAMATION ||
+            char_code === DOLLAR ||
+            char_code === AMPERSAND ||
+            char_code === APOSTROPHE ||
+            char_code === LEFT_PAREN ||
+            char_code === RIGHT_PAREN ||
+            char_code === ASTERISK ||
+            char_code === PLUS ||
+            char_code === COMMA ||
+            char_code === SEMICOLON ||
+            char_code === EQUALS ||
+            // path allowed: : @
+            char_code === COLON ||
+            char_code === AT ||
+            // separators: / ? #
+            char_code === SLASH ||
+            char_code === QUESTION ||
+            char_code === HASH ||
+            // percent-encoding: %
+            char_code === PERCENT);
+    }
+    /**
+     * Check if current position is the start of an external URL (https:// or http://).
+     */
+    #is_at_url() {
+        if (this.#match('https://')) {
+            // Check for protocol-only (e.g., just "https://")
+            // Must have at least one non-whitespace character after protocol
+            if (this.#index + HTTPS_PREFIX_LENGTH >= this.#template.length) {
+                return false;
+            }
+            const next_char = this.#template.charCodeAt(this.#index + HTTPS_PREFIX_LENGTH);
+            return next_char !== SPACE && next_char !== NEWLINE;
+        }
+        if (this.#match('http://')) {
+            // Check for protocol-only (e.g., just "http://")
+            // Must have at least one non-whitespace character after protocol
+            if (this.#index + HTTP_PREFIX_LENGTH >= this.#template.length) {
+                return false;
+            }
+            const next_char = this.#template.charCodeAt(this.#index + HTTP_PREFIX_LENGTH);
+            return next_char !== SPACE && next_char !== NEWLINE;
+        }
+        return false;
+    }
+    /**
+     * Check if current position is the start of an internal path (starts with /).
+     */
+    #is_at_internal_path() {
+        if (this.#template.charCodeAt(this.#index) !== SLASH) {
+            return false;
+        }
+        // Check previous character - must be whitespace or start of string
+        // (to avoid matching / within relative paths like ./a/b or ../a/b)
+        if (this.#index > 0) {
+            const prev_char = this.#template.charCodeAt(this.#index - 1);
+            if (prev_char !== SPACE && prev_char !== NEWLINE && prev_char !== TAB) {
+                return false;
+            }
+        }
+        // Must have at least one more character after /, and it must NOT be:
+        // - another / (to avoid matching // which is used for comments or protocol-relative URLs)
+        // - whitespace (a bare / followed by space is not a useful link)
+        if (this.#index + 1 >= this.#template.length) {
+            return false;
+        }
+        const next_char = this.#template.charCodeAt(this.#index + 1);
+        return next_char !== SLASH && next_char !== SPACE && next_char !== NEWLINE;
+    }
+    /**
+     * Parse auto-detected external URL (https:// or http://).
+     * Uses RFC 3986 whitelist validation for valid URI characters.
+     */
+    #parse_auto_link_url() {
+        const start = this.#index;
+        // Consume protocol
+        if (this.#match('https://')) {
+            this.#index += HTTPS_PREFIX_LENGTH;
+        }
+        else if (this.#match('http://')) {
+            this.#index += HTTP_PREFIX_LENGTH;
+        }
+        // Collect URL characters using RFC 3986 whitelist
+        // Stop at whitespace or any character invalid in URIs
+        while (this.#index < this.#template.length) {
+            const char_code = this.#current_char();
+            if (char_code === SPACE || char_code === NEWLINE || !this.#is_valid_path_char(char_code)) {
+                break;
+            }
+            this.#index++;
+        }
+        let reference = this.#template.slice(start, this.#index);
+        // Apply GFM trailing punctuation trimming with balanced parentheses
+        reference = this.#trim_trailing_punctuation(reference);
+        // Update index after trimming
+        this.#index = start + reference.length;
+        return {
+            type: 'Link',
+            reference,
+            children: [{ type: 'Text', content: reference, start, end: this.#index }],
+            link_type: 'external',
+            start,
+            end: this.#index,
+        };
+    }
+    /**
+     * Parse auto-detected internal path (starts with /).
+     * Uses RFC 3986 whitelist validation for valid URI characters.
+     */
+    #parse_auto_link_internal() {
+        const start = this.#index;
+        // Collect path characters using RFC 3986 whitelist
+        // Stop at whitespace or any character invalid in URIs
+        while (this.#index < this.#template.length) {
+            const char_code = this.#current_char();
+            if (char_code === SPACE || char_code === NEWLINE || !this.#is_valid_path_char(char_code)) {
+                break;
+            }
+            this.#index++;
+        }
+        let reference = this.#template.slice(start, this.#index);
+        // Apply GFM trailing punctuation trimming
+        reference = this.#trim_trailing_punctuation(reference);
+        // Update index after trimming
+        this.#index = start + reference.length;
+        return {
+            type: 'Link',
+            reference,
+            children: [{ type: 'Text', content: reference, start, end: this.#index }],
+            link_type: 'internal',
+            start,
+            end: this.#index,
+        };
+    }
+    /**
+     * Trim trailing punctuation from URL/path per RFC 3986 and GFM rules.
+     * - Trims simple trailing: .,;:!?]
+     * - Balanced logic for () only (valid in path components)
+     * - Invalid chars like [] {} are already stopped by whitelist, but ] trimmed as fallback
+     *
+     * Optimized to avoid O(n²) string slicing - tracks end index and slices once at the end.
+     */
+    #trim_trailing_punctuation(url) {
+        let end = url.length;
+        // Trim simple trailing punctuation (] as fallback - whitelist should prevent it)
+        while (end > 0) {
+            const last_char = url.charCodeAt(end - 1);
+            if (last_char === PERIOD ||
+                last_char === COMMA ||
+                last_char === SEMICOLON ||
+                last_char === COLON ||
+                last_char === EXCLAMATION ||
+                last_char === QUESTION ||
+                last_char === RIGHT_BRACKET) {
+                end--;
+            }
+            else {
+                break;
+            }
+        }
+        // Handle balanced parentheses ONLY (parens are valid in URI path components)
+        // Count parentheses in the trimmed portion
+        let open_count = 0;
+        let close_count = 0;
+        for (let i = 0; i < end; i++) {
+            const char = url.charCodeAt(i);
+            if (char === LEFT_PAREN)
+                open_count++;
+            if (char === RIGHT_PAREN)
+                close_count++;
+        }
+        // Trim unmatched trailing closing parens
+        while (end > 0 && close_count > open_count) {
+            const last_char = url.charCodeAt(end - 1);
+            if (last_char === RIGHT_PAREN) {
+                end--;
+                close_count--;
+            }
+            else {
+                break;
+            }
+        }
+        // Return original string if no trimming, otherwise slice once
+        return end === url.length ? url : url.slice(0, end);
+    }
+    /**
+     * Parse plain text until special character encountered.
+     * Preserves all whitespace (except paragraph breaks handled separately).
+     * Detects and delegates to URL/path parsing when encountered.
+     */
+    #parse_text() {
+        const start = this.#index;
+        // Check for URL or internal path at current position
+        if (this.#is_at_url()) {
+            return this.#parse_auto_link_url();
+        }
+        if (this.#is_at_internal_path()) {
+            return this.#parse_auto_link_internal();
+        }
+        while (this.#index < this.#template.length) {
+            const char_code = this.#current_char();
+            // Stop at special characters (but preserve single newlines)
+            if (char_code === BACKTICK ||
+                char_code === ASTERISK ||
+                char_code === UNDERSCORE ||
+                char_code === TILDE ||
+                char_code === LEFT_BRACKET ||
+                char_code === RIGHT_BRACKET ||
+                char_code === RIGHT_PAREN ||
+                char_code === LEFT_ANGLE) {
+                break;
+            }
+            // Check for paragraph break (double newline)
+            if (this.#is_at_paragraph_break()) {
+                break;
+            }
+            // Check for URL or internal path mid-text
+            if (this.#is_at_url() || this.#is_at_internal_path()) {
+                break;
+            }
+            this.#index++;
+        }
+        // Ensure we always consume at least one character to prevent infinite loops
+        if (this.#index === start && this.#index < this.#template.length) {
+            this.#index++;
+        }
+        // Use slice instead of concatenation for performance
+        const content = this.#template.slice(start, this.#index);
+        return {
+            type: 'Text',
+            content,
+            start,
+            end: this.#index,
+        };
+    }
+    /**
+     * Parse nodes until delimiter string is found.
+     * Used for parsing children of inline formatting (bold, italic, strikethrough) and markdown links.
+     *
+     * Implements greedy/bounded parsing to prevent nested formatters from consuming parent delimiters:
+     * - When parsing `**bold with _italic_**`, the outer `**` parser finds its closing delimiter at position Y
+     * - Sets `#max_search_index = Y` to create a boundary
+     * - Parses children only within range, preventing `_italic_` from finding delimiters beyond Y
+     * - This ensures proper nesting without backtracking
+     *
+     * Stops parsing when:
+     * - Delimiter string is found
+     * - Paragraph break (double newline) is encountered (allows block elements to interrupt inline formatting)
+     * - `end_index` boundary is reached
+     *
+     * @param delimiter - The delimiter string to stop at (e.g., '**', '_', ']')
+     * @param end_index - Optional maximum index to parse up to (for greedy/bounded parsing)
+     * @returns Array of parsed nodes (may be empty if delimiter found immediately)
+     */
+    #parse_nodes_until(delimiter, end_index) {
+        const nodes = [];
+        const max_index = end_index ?? this.#template.length;
+        // Save and set max search boundary for nested parsers
+        const saved_max_search_index = this.#max_search_index;
+        this.#max_search_index = max_index;
+        while (this.#index < max_index) {
+            if (this.#match(delimiter)) {
+                break;
+            }
+            // Check for paragraph break (block element interruption)
+            if (this.#is_at_paragraph_break()) {
+                // Paragraph break interrupts inline formatting
+                break;
+            }
+            const node = this.#parse_node();
+            nodes.push(node);
+        }
+        // Restore previous boundary
+        this.#max_search_index = saved_max_search_index;
+        return nodes;
+    }
+    /**
+     * Get character code at current index, or -1 if at EOF.
+     */
+    #current_char() {
+        return this.#index < this.#template.length ? this.#template.charCodeAt(this.#index) : -1;
+    }
+    /**
+     * Check if current position is at a paragraph break (double newline).
+     */
+    #is_at_paragraph_break() {
+        return (this.#current_char() === NEWLINE &&
+            this.#index + 1 < this.#template.length &&
+            this.#template.charCodeAt(this.#index + 1) === NEWLINE);
+    }
+    #match(str) {
+        return this.#template.startsWith(str, this.#index);
+    }
+    /**
+     * Consume string at current index, or throw error.
+     */
+    #eat(str) {
+        if (this.#match(str)) {
+            this.#index += str.length;
+        }
+        else {
+            throw Error(`Expected "${str}" at index ${this.#index}`);
+        }
+    }
+    /**
+     * Check if current position matches a horizontal rule.
+     * HR must be exactly `---` at column 0, followed by blank line or EOF.
+     *
+     * Blank line requirement rationale:
+     * Prevents block elements from accidentally consuming following content.
+     * Without this, `---` followed by regular text would create an hr and treat
+     * the next line as a new paragraph, which could be surprising. The blank line
+     * makes block element boundaries explicit and predictable.
+     */
+    #match_hr() {
+        let i = this.#index;
+        // Must start at column 0 (no leading whitespace)
+        if (i < this.#template.length && this.#template.charCodeAt(i) === SPACE) {
+            return false;
+        }
+        // Must have exactly three hyphens
+        if (i + HR_HYPHEN_COUNT > this.#template.length ||
+            this.#template.charCodeAt(i) !== HYPHEN ||
+            this.#template.charCodeAt(i + 1) !== HYPHEN ||
+            this.#template.charCodeAt(i + 2) !== HYPHEN) {
+            return false;
+        }
+        i += HR_HYPHEN_COUNT;
+        // After the three hyphens, only whitespace and newline (or EOF) allowed
+        while (i < this.#template.length) {
+            const char_code = this.#template.charCodeAt(i);
+            if (char_code === NEWLINE) {
+                // Found newline - check if followed by another newline (blank line) or EOF
+                const next_i = i + 1;
+                if (next_i >= this.#template.length) {
+                    return true; // hr followed by newline + EOF
+                }
+                if (this.#template.charCodeAt(next_i) === NEWLINE) {
+                    return true; // hr followed by blank line
+                }
+                return false; // hr followed by single newline + content
+            }
+            if (char_code !== SPACE) {
+                return false; // Non-whitespace after ---, not an hr
+            }
+            i++;
+        }
+        // Reached EOF after ---, valid hr
+        return true;
+    }
+    /**
+     * Parse horizontal rule: `---`
+     * Assumes #match_hr() already verified this is an hr.
+     */
+    #parse_hr() {
+        const start = this.#index;
+        // Consume the three hyphens (no leading whitespace - already verified)
+        this.#index += HR_HYPHEN_COUNT;
+        // Skip trailing whitespace
+        while (this.#index < this.#template.length &&
+            this.#template.charCodeAt(this.#index) === SPACE) {
+            this.#index++;
+        }
+        // Don't consume the newline - let the main parse loop handle it
+        return {
+            type: 'Hr',
+            start,
+            end: this.#index,
+        };
+    }
+    /**
+     * Check if current position matches a heading.
+     * Heading must be 1-6 hashes at column 0, followed by space and content,
+     * followed by blank line or EOF.
+     *
+     * Blank line requirement rationale:
+     * Ensures headings are visually and semantically separate from following content.
+     * Without this, `# Heading\nText` would be ambiguous - is the text part of the
+     * heading or a new paragraph? The blank line makes document structure explicit.
+     */
+    #match_heading() {
+        let i = this.#index;
+        // Must start at column 0 (no leading whitespace)
+        if (i < this.#template.length && this.#template.charCodeAt(i) === SPACE) {
+            return false;
+        }
+        // Count hashes (must be 1-6)
+        let hash_count = 0;
+        while (i < this.#template.length &&
+            this.#template.charCodeAt(i) === HASH &&
+            hash_count <= MAX_HEADING_LEVEL) {
+            hash_count++;
+            i++;
+        }
+        if (hash_count === 0 || hash_count > MAX_HEADING_LEVEL) {
+            return false;
+        }
+        // Must have space after hashes
+        if (i >= this.#template.length || this.#template.charCodeAt(i) !== SPACE) {
+            return false;
+        }
+        i++; // consume the space
+        // Must have non-whitespace content after the space (not just whitespace until newline)
+        let has_content = false;
+        while (i < this.#template.length && this.#template.charCodeAt(i) !== NEWLINE) {
+            const char_code = this.#template.charCodeAt(i);
+            if (char_code !== SPACE && char_code !== TAB) {
+                has_content = true;
+            }
+            i++;
+        }
+        if (!has_content) {
+            return false; // heading with only whitespace, treat as plain text
+        }
+        // At this point we're at newline or EOF
+        // Check for blank line after (newline + newline) or EOF
+        if (i >= this.#template.length) {
+            return true; // heading at EOF
+        }
+        // Must have newline
+        if (this.#template.charCodeAt(i) !== NEWLINE) {
+            return false;
+        }
+        const next_i = i + 1;
+        if (next_i >= this.#template.length) {
+            return true; // heading followed by newline + EOF
+        }
+        if (this.#template.charCodeAt(next_i) === NEWLINE) {
+            return true; // heading followed by blank line
+        }
+        return false; // heading followed by single newline + content
+    }
+    /**
+     * Parse heading: `# Heading text`
+     * Assumes #match_heading() already verified this is a heading.
+     */
+    #parse_heading() {
+        const start = this.#index;
+        // Count and consume hashes
+        let level = 0;
+        while (this.#index < this.#template.length && this.#template.charCodeAt(this.#index) === HASH) {
+            level++;
+            this.#index++;
+        }
+        // Consume the space after hashes (already verified to exist)
+        this.#index++;
+        // Parse inline content until newline
+        const content_nodes = [];
+        while (this.#index < this.#template.length) {
+            const char_code = this.#template.charCodeAt(this.#index);
+            if (char_code === NEWLINE) {
+                break;
+            }
+            const node = this.#parse_node();
+            if (node.type === 'Text') {
+                // Check if text node includes a newline (since #parse_text doesn't stop at single newlines)
+                // If so, trim it and move index back
+                const newline_index = node.content.indexOf('\n');
+                if (newline_index !== -1) {
+                    const trimmed_content = node.content.slice(0, newline_index);
+                    if (trimmed_content) {
+                        this.#accumulate_text(trimmed_content, node.start);
+                    }
+                    this.#index = node.start + newline_index;
+                    break;
+                }
+                else {
+                    this.#accumulate_text(node.content, node.start);
+                }
+            }
+            else {
+                this.#flush_text();
+                content_nodes.push(...this.#nodes);
+                this.#nodes.length = 0;
+                content_nodes.push(node);
+            }
+        }
+        this.#flush_text();
+        content_nodes.push(...this.#nodes);
+        this.#nodes.length = 0;
+        // Don't consume the newline - let the main parse loop handle it
+        return {
+            type: 'Heading',
+            level: level,
+            children: content_nodes,
+            start,
+            end: this.#index,
+        };
+    }
+    /**
+     * Check if current position matches a code block.
+     * Code block must be 3+ backticks at column 0, followed by blank line or EOF.
+     * Empty code blocks (no content) are treated as invalid.
+     *
+     * Blank line requirement rationale:
+     * Separates code blocks from following content to prevent ambiguity.
+     * Codeblocks are distinct semantic units that should be visually isolated.
+     * The blank line makes it explicit where the code block ends and regular
+     * content begins, following the "explicit over implicit" design principle.
+     */
+    #match_code_block() {
+        let i = this.#index;
+        // Must start at column 0 (no leading whitespace)
+        if (i < this.#template.length && this.#template.charCodeAt(i) === SPACE) {
+            return false;
+        }
+        // Must have at least three backticks
+        let backtick_count = 0;
+        while (i < this.#template.length && this.#template.charCodeAt(i) === BACKTICK) {
+            backtick_count++;
+            i++;
+        }
+        if (backtick_count < MIN_CODEBLOCK_BACKTICKS) {
+            return false;
+        }
+        // Skip optional language hint (consume until space or newline)
+        while (i < this.#template.length) {
+            const char_code = this.#template.charCodeAt(i);
+            if (char_code === SPACE || char_code === NEWLINE) {
+                break;
+            }
+            i++;
+        }
+        // Skip any trailing spaces on opening fence line
+        while (i < this.#template.length && this.#template.charCodeAt(i) === SPACE) {
+            i++;
+        }
+        // Must have newline after opening fence (or be at EOF)
+        if (i >= this.#template.length) {
+            return false; // No newline, can't be a valid code block
+        }
+        if (this.#template.charCodeAt(i) !== NEWLINE) {
+            return false;
+        }
+        i++; // consume the newline
+        // Mark content start position (after opening fence newline)
+        const content_start = i;
+        // Now search for closing fence
+        const closing_fence = '`'.repeat(backtick_count);
+        while (i < this.#template.length) {
+            // Check if we're at a potential closing fence (must be at start of line)
+            if (this.#template.startsWith(closing_fence, i)) {
+                // Verify it's at column 0 by checking previous character
+                const prev_char = i > 0 ? this.#template.charCodeAt(i - 1) : NEWLINE;
+                if (prev_char === NEWLINE || i === 0) {
+                    // Found closing fence - check for empty content first
+                    const content = this.#template.slice(content_start, i);
+                    const final_content = content.endsWith('\n') ? content.slice(0, -1) : content;
+                    if (final_content.length === 0) {
+                        return false; // Empty code block has no semantic meaning
+                    }
+                    // Now verify what comes after closing fence
+                    let j = i + backtick_count;
+                    // Skip trailing whitespace on closing fence line
+                    while (j < this.#template.length && this.#template.charCodeAt(j) === SPACE) {
+                        j++;
+                    }
+                    // Must have newline after closing fence (or be at EOF)
+                    if (j >= this.#template.length) {
+                        return true;
+                    }
+                    if (this.#template.charCodeAt(j) !== NEWLINE) {
+                        // closing fence has non-whitespace after it on same line - not a code block
+                        return false;
+                    }
+                    // Check if followed by blank line or EOF
+                    const next_j = j + 1;
+                    if (next_j >= this.#template.length) {
+                        return true; // code block followed by newline + EOF
+                    }
+                    if (this.#template.charCodeAt(next_j) === NEWLINE) {
+                        return true; // code block followed by blank line
+                    }
+                    return false; // code block followed by single newline + content
+                }
+            }
+            i++;
+        }
+        // No closing fence found - not a valid code block
+        return false;
+    }
+    /**
+     * Parse code block: ```lang\ncode\n```
+     * Assumes #match_code_block() already verified this is a code block.
+     */
+    #parse_code_block() {
+        const start = this.#index;
+        // Count and consume opening backticks
+        let backtick_count = 0;
+        while (this.#index < this.#template.length &&
+            this.#template.charCodeAt(this.#index) === BACKTICK) {
+            backtick_count++;
+            this.#index++;
+        }
+        // Parse optional language hint (consume until space or newline)
+        let lang = null;
+        const lang_start = this.#index;
+        while (this.#index < this.#template.length) {
+            const char_code = this.#template.charCodeAt(this.#index);
+            if (char_code === SPACE || char_code === NEWLINE) {
+                break;
+            }
+            this.#index++;
+        }
+        if (this.#index > lang_start) {
+            lang = this.#template.slice(lang_start, this.#index);
+        }
+        // Skip any trailing spaces on opening fence line
+        while (this.#index < this.#template.length &&
+            this.#template.charCodeAt(this.#index) === SPACE) {
+            this.#index++;
+        }
+        // Consume the newline after opening fence (first newline is consumed per spec)
+        if (this.#index < this.#template.length && this.#template.charCodeAt(this.#index) === NEWLINE) {
+            this.#index++;
+        }
+        // Collect content until closing fence
+        const content_start = this.#index;
+        const closing_fence = '`'.repeat(backtick_count);
+        while (this.#index < this.#template.length) {
+            // Check if we're at the closing fence (must be at start of line)
+            if (this.#template.startsWith(closing_fence, this.#index)) {
+                // Verify it's at column 0 by checking previous character
+                const prev_char = this.#index > 0 ? this.#template.charCodeAt(this.#index - 1) : NEWLINE;
+                if (prev_char === NEWLINE || this.#index === 0) {
+                    // Check if it's exactly the right number of backticks at line start
+                    let j = this.#index + backtick_count;
+                    // After closing fence, only whitespace and newline allowed
+                    while (j < this.#template.length && this.#template.charCodeAt(j) === SPACE) {
+                        j++;
+                    }
+                    if (j >= this.#template.length || this.#template.charCodeAt(j) === NEWLINE) {
+                        // Valid closing fence
+                        const content = this.#template.slice(content_start, this.#index);
+                        // Remove trailing newline if present (closing fence comes after a newline)
+                        const final_content = content.endsWith('\n') ? content.slice(0, -1) : content;
+                        // Consume closing fence
+                        this.#index += backtick_count;
+                        // Skip trailing whitespace on closing fence line
+                        while (this.#index < this.#template.length &&
+                            this.#template.charCodeAt(this.#index) === SPACE) {
+                            this.#index++;
+                        }
+                        // Don't consume the newline - let the main parse loop handle it
+                        return {
+                            type: 'Codeblock',
+                            lang,
+                            content: final_content,
+                            start,
+                            end: this.#index,
+                        };
+                    }
+                }
+            }
+            this.#index++;
+        }
+        // Should not reach here if #match_code_block() validated correctly
+        throw Error('Code block not properly closed');
+    }
+}