// Copyright 2026 The V Language. All rights reserved.
// Use of this source code is governed by an MIT license
// that can be found in the LICENSE file.
module markdown

import strings

// block_level_tags lists HTML tags that start an HTML block (type 6).
// vfmt off
const block_level_tags = [
	'address', 'article', 'aside', 'base', 'basefont', 'blockquote', 'body', 'caption',	'center',
	'col', 'colgroup', 'dd', 'details', 'dialog', 'dir', 'div', 'dl', 'dt', 'fieldset',
	'figcaption', 'figure', 'footer', 'form', 'frame', 'frameset', 'h1', 'h2', 'h3', 'h4', 'h5',
	'h6', 'head', 'header', 'hr', 'html', 'iframe', 'legend', 'li', 'link', 'main', 'menu',
	'menuitem', 'meta', 'nav', 'noframes', 'ol', 'optgroup', 'option', 'p', 'param', 'search',
	'section', 'summary', 'table', 'tbody', 'td', 'tfoot', 'th', 'thead', 'title', 'tr', 'track',
	'ul'
]!
// vfmt on

// BlockParser parses markdown block structure line by line into an AST.
// After block parsing, inline content is parsed for every leaf node.
struct BlockParser {
	opts Options
mut:
	lines   []string
	pos     int
	ref_map map[string]LinkRef
	fn_defs map[string]&Node
}

// BlockParser.new creates a BlockParser for the given source.
fn BlockParser.new(src string, opts Options, ref_map map[string]LinkRef) BlockParser {
	normalized := src.replace('\r\n', '\n').replace('\r', '\n')
	lines := normalized.split('\n')
	mut refs := map[string]LinkRef{}
	for k, v in ref_map {
		refs[k] = v
	}
	return BlockParser{
		opts:    opts
		lines:   lines
		ref_map: refs
		fn_defs: map[string]&Node{}
	}
}

// nested_block_parser creates a nested parser that inherits the current options
// and reference definitions.
fn (p &BlockParser) nested_block_parser(lines []string) BlockParser {
	mut refs := map[string]LinkRef{}
	for k, v in p.ref_map {
		refs[k] = v
	}
	return BlockParser{
		opts:    p.opts
		lines:   lines
		ref_map: refs
		fn_defs: map[string]&Node{}
	}
}

// merge_nested_state propagates nested parser state back to the parent parser.
fn (mut p BlockParser) merge_nested_state(inner BlockParser) {
	for k, v in inner.ref_map {
		p.ref_map[k] = v
	}
	if p.opts.footnotes {
		for k, v in inner.fn_defs {
			if k !in p.fn_defs {
				p.fn_defs[k] = v
			}
		}
	}
}

// parse parses the full document and returns the AST root node.
fn (mut p BlockParser) parse() &Node {
	mut doc := new_node(.document)
	p.parse_blocks(mut doc, 0)
	// Attach collected footnote definitions as children of the document.
	if p.opts.footnotes {
		for _, fn_node in p.fn_defs {
			doc.append_child(fn_node)
		}
	}
	return doc
}

// parse_blocks fills parent with block-level children parsed from p.lines[p.pos..].
// indent is the minimum leading-space indent already consumed by a container.
fn (mut p BlockParser) parse_blocks(mut parent Node, indent int) {
	for p.pos < p.lines.len {
		line_raw := p.lines[p.pos]
		line := expand_tabs(line_raw)
		trimmed := line.trim_left(' \t')

		// --- blank line ---
		if is_blank(line) {
			p.pos++
			continue
		}

		stripped := trim_indent(line, indent)
		sp := leading_spaces(stripped)
		content := trim_indent(stripped, sp)

		// --- thematic break (---, ***, ___) ---
		if is_thematic_break(stripped) {
			node := new_node(.thematic_break)
			parent.append_child(node)
			p.pos++
			continue
		}

		// --- ATX heading (# ... ######) ---
		if heading := p.try_atx_heading(stripped) {
			parent.append_child(heading)
			p.pos++
			continue
		}

		// --- fenced code block (``` or ~~~) ---
		if fenced := p.try_fenced_code(stripped, indent) {
			parent.append_child(fenced)
			continue
		}

		// --- HTML block ---
		if html_blk := p.try_html_block(stripped, indent) {
			parent.append_child(html_blk)
			continue
		}

		// --- link reference definition ---
		// CommonMark allows 0-3 leading spaces after container indentation.
		if sp <= 3 && p.try_link_ref_def(content) {
			continue
		}

		// --- footnote definition (if footnotes extension enabled) ---
		if p.opts.footnotes {
			if p.try_footnote_def(stripped, indent) {
				continue
			}
		}

		// --- blockquote (>) ---
		if stripped.starts_with('>') {
			bq := p.parse_blockquote(indent)
			parent.append_child(bq)
			continue
		}

		// --- indented code block (4 spaces) ---
		if sp >= 4 && !is_blank(stripped) {
			cb := p.parse_indented_code(indent)
			parent.append_child(cb)
			continue
		}

		// --- list (bullet or ordered) ---
		if is_list_marker(stripped) {
			lst := p.parse_list(indent)
			parent.append_child(lst)
			continue
		}

		// --- GFM table (if tables extension enabled) ---
		if p.opts.tables {
			if tbl := p.try_table(indent) {
				parent.append_child(tbl)
				continue
			}
		}

		// --- definition list (if extension enabled) ---
		if p.opts.definition_list {
			if dl := p.try_definition_list(indent) {
				parent.append_child(dl)
				continue
			}
		}

		// --- paragraph (including setext headings) ---
		para := p.parse_paragraph(indent)
		if para.kind == .heading || para.kind == .paragraph {
			parent.append_child(para)
		}
		_ = trimmed
		_ = content
	}
}

// is_thematic_break returns true if line is a valid thematic break
// (three or more -, *, or _ with optional spaces).
fn is_thematic_break(line string) bool {
	trimmed := line.trim_space()
	if trimmed.len < 3 {
		return false
	}
	mut c := trimmed[0]
	if c != `-` && c != `*` && c != `_` {
		return false
	}
	mut count := 0
	for i := 0; i < trimmed.len; i++ {
		ch := trimmed[i]
		if ch == c {
			count++
		} else if ch != ` ` && ch != `\t` {
			return false
		}
	}
	return count >= 3
}

// try_atx_heading attempts to parse an ATX heading from line.
// Returns the heading node on success.
fn (mut p BlockParser) try_atx_heading(line string) ?&Node {
	if line.len == 0 || line[0] != `#` {
		return none
	}
	mut level := 0
	for level < line.len && line[level] == `#` {
		level++
	}
	if level > 6 {
		return none
	}
	if level < line.len && line[level] != ` ` && line[level] != `\t` {
		return none
	}
	mut content := line[level..].trim_space()
	// Strip trailing # sequence.
	for content.ends_with('#') {
		stripped := content.trim_right('#')
		if stripped.len == 0 || stripped.ends_with(' ') || stripped.ends_with('\t') {
			content = stripped.trim_right(' \t')
			break
		}
		break
	}
	mut node := new_node(.heading)
	node.level = level
	node.literal = content
	if p.opts.parser_opts.auto_heading_id {
		node.id = heading_id_from_text(content)
	}
	return node
}

// try_fenced_code attempts to parse a fenced code block starting at p.pos.
fn (mut p BlockParser) try_fenced_code(line string, indent int) ?&Node {
	fence_char, fence_len := detect_fence(line)
	if fence_len < 3 {
		return none
	}
	info := line[fence_len..].trim_space()
	// info string must not contain a backtick when using backtick fence.
	if fence_char == 96 && info.contains('`') {
		return none
	}
	p.pos++
	mut code_lines := []string{}
	for p.pos < p.lines.len {
		raw := expand_tabs(p.lines[p.pos])
		stripped := trim_indent(raw, indent)
		// Check for closing fence.
		close_char, close_len := detect_fence(stripped)
		if close_char == fence_char && close_len >= fence_len {
			rest := stripped[close_len..].trim_space()
			if rest.len == 0 {
				p.pos++
				break
			}
		}
		code_lines << trim_indent(raw, indent)
		p.pos++
	}
	mut node := new_node(.fenced_code)
	node.fence_info = info
	node.literal = code_lines.join('\n') + '\n'
	return node
}

// detect_fence returns (fence_char, fence_length) if line starts with a valid
// code-fence sequence, or (0, 0) if not.
fn detect_fence(line string) (u8, int) {
	if line.len < 3 {
		return 0, 0
	}
	c := line[0]
	if c != 96 && c != `~` {
		return 0, 0
	}
	mut n := 0
	for n < line.len && line[n] == c {
		n++
	}
	if n >= 3 {
		return c, n
	}
	return 0, 0
}

// parse_indented_code collects lines that are indented by at least (indent+4)
// spaces (or blank) into an indented code block.
fn (mut p BlockParser) parse_indented_code(indent int) &Node {
	mut lines := []string{}
	for p.pos < p.lines.len {
		raw := expand_tabs(p.lines[p.pos])
		if is_blank(raw) {
			// Blank line may be included, but only if followed by more indented code.
			lines << ''
			p.pos++
			continue
		}
		stripped := trim_indent(raw, indent)
		sp := leading_spaces(stripped)
		if sp < 4 {
			break
		}
		lines << trim_indent(stripped, 4)
		p.pos++
	}
	// Trim trailing blank lines.
	for lines.len > 0 && lines[lines.len - 1] == '' {
		lines = unsafe { lines[..lines.len - 1] }
	}
	mut node := new_node(.code_block)
	node.literal = lines.join('\n') + '\n'
	return node
}

// try_html_block attempts to parse an HTML block starting at p.pos.
fn (mut p BlockParser) try_html_block(line string, indent int) ?&Node {
	html_type := detect_html_block_type(line)
	if html_type == 0 {
		return none
	}
	mut raw_lines := []string{}
	raw_lines << p.lines[p.pos]
	p.pos++
	// Types 1-5 end at specific end patterns; type 6-7 end at blank line.
	for p.pos < p.lines.len {
		raw := p.lines[p.pos]
		expanded := expand_tabs(raw)
		stripped := trim_indent(expanded, indent)
		match html_type {
			1 {
				raw_lines << raw
				p.pos++
				low := stripped.to_lower()
				if low.contains('</script>') || low.contains('</pre>') || low.contains('</style>')
					|| low.contains('</textarea>') {
					break
				}
			}
			2 {
				raw_lines << raw
				p.pos++
				if stripped.contains('-->') {
					break
				}
			}
			3 {
				raw_lines << raw
				p.pos++
				if stripped.contains('?>') {
					break
				}
			}
			4 {
				raw_lines << raw
				p.pos++
				if stripped.contains('>') {
					break
				}
			}
			5 {
				raw_lines << raw
				p.pos++
				if stripped.contains(']]>') {
					break
				}
			}
			6, 7 {
				if is_blank(stripped) {
					break
				}
				raw_lines << raw
				p.pos++
			}
			else {}
		}
	}
	mut node := new_node(.html_block)
	node.literal = raw_lines.join('\n') + '\n'
	return node
}

// detect_html_block_type returns the HTML block type (1-7) or 0 if the line
// does not start an HTML block.
fn detect_html_block_type(line string) int {
	stripped := line.trim_left(' \t')
	if stripped.len == 0 || stripped[0] != `<` {
		return 0
	}
	low := stripped.to_lower()
	// Type 2: HTML comment
	if low.starts_with('<!--') {
		return 2
	}
	// Type 3: processing instruction
	if low.starts_with('<?') {
		return 3
	}
	// Type 5: CDATA
	if low.starts_with('<![cdata[') {
		return 5
	}
	// Type 4: <!X
	if low.len > 2 && low[1] == `!` && low[2] >= `a` && low[2] <= `z` {
		return 4
	}
	// Type 1: script/pre/style/textarea
	for _, tag in ['<script', '<pre', '<style', '<textarea'] {
		if low.starts_with(tag) {
			rest := low[tag.len..]
			if rest.len == 0 || rest[0] == ` ` || rest[0] == `\t` || rest[0] == `>`
				|| rest[0] == `\n` {
				return 1
			}
		}
	}
	// Type 6: block-level tag
	tag_name := extract_tag_name(low[1..])
	if tag_name.len > 0 {
		for bt in block_level_tags {
			if tag_name == bt {
				return 6
			}
		}
	}
	// Type 7: complete open/close tag not in type 6
	if is_complete_html_tag(stripped) {
		return 7
	}
	return 0
}

// extract_tag_name extracts the tag name from the beginning of s.
fn extract_tag_name(s string) string {
	mut end := 0
	for end < s.len && (is_alnum(s[end]) || s[end] == `-`) {
		end++
	}
	return s[..end].to_lower()
}

// is_complete_html_tag returns true if s looks like a complete open or close tag.
fn is_complete_html_tag(s string) bool {
	if s.len < 3 {
		return false
	}
	// Must start with < and end with >
	if s[0] != `<` {
		return false
	}
	end := s.index('>') or { return false }
	return end == s.len - 1 || s[end + 1..].trim_space().len == 0
}

// try_link_ref_def attempts to parse a link reference definition at p.pos.
// CommonMark allows the title to appear on the next line when the destination
// is alone on the first line.  Returns true and advances p.pos if successful.
fn (mut p BlockParser) try_link_ref_def(line string) bool {
	if !line.starts_with('[') {
		return false
	}
	// Find closing bracket.
	mut i := 1
	for i < line.len && line[i] != `]` {
		if line[i] == `\\` {
			i++
		}
		i++
	}
	if i >= line.len || line[i] != `]` || i + 1 >= line.len || line[i + 1] != `:` {
		return false
	}
	label := normalize_label(line[1..i])
	rest := line[i + 2..].trim_left(' \t')
	if label.len == 0 {
		return false
	}
	// Parse destination.
	dest, after_dest := parse_link_dest(rest)
	if after_dest == rest {
		return false
	}
	// Parse optional title.  The title may appear on the same line or, if the
	// destination is the only content on the first line, on the very next line.
	mut title := ''
	mut extra_lines := 0 // number of additional lines consumed for the title
	title_str := after_dest.trim_left(' \t')
	if title_str.len > 0 {
		// Title (or unwanted content) is on the same line as the destination.
		parsed_title, title_rest := parse_link_title(title_str)
		if title_rest == title_str {
			// Not a valid title; reject the whole definition.
			return false
		}
		if title_rest.trim_space().len > 0 {
			// Trailing content after the title – invalid.
			return false
		}
		title = parsed_title
	} else {
		// Destination was alone on its line; look for a title on the next line.
		next_idx := p.pos + 1
		if next_idx < p.lines.len {
			next_line := expand_tabs(p.lines[next_idx]).trim_left(' \t')
			if next_line.len > 0 {
				parsed_title, title_rest := parse_link_title(next_line)
				if title_rest != next_line && title_rest.trim_space().len == 0 {
					// Valid title on the next line; consume it.
					title = parsed_title
					extra_lines = 1
				}
			}
		}
	}
	if label !in p.ref_map {
		p.ref_map[label] = LinkRef{
			dest:  dest
			title: title
		}
	}
	p.pos += 1 + extra_lines
	return true
}

// parse_link_dest parses a link destination from s and returns (dest, rest).
fn parse_link_dest(s string) (string, string) {
	if s.len == 0 {
		return '', s
	}
	if s[0] == `<` {
		// Angle-bracket form: <url>
		end := s.index_after_('>', 1)
		if end < 0 {
			return '', s
		}
		return s[1..end], s[end + 1..]
	}
	// Regular form: no spaces, no control characters, balanced parentheses.
	mut parens := 0
	mut i := 0
	for i < s.len {
		c := s[i]
		if c == ` ` || c == `\t` || c == `\n` {
			break
		}
		if c == `(` {
			parens++
		} else if c == `)` {
			if parens == 0 {
				break
			}
			parens--
		} else if c == `\\` && i + 1 < s.len {
			i += 2
			continue
		}
		i++
	}
	if i == 0 {
		return '', s
	}
	if parens != 0 {
		return '', s
	}
	return s[..i], s[i..]
}

// parse_link_title parses an optional link title from s and returns (title, rest).
// Returns empty string if no valid title is found.
fn parse_link_title(s string) (string, string) {
	if s.len == 0 {
		return '', s
	}
	open := s[0]
	mut close := u8(0)
	match open {
		`"` { close = `"` }
		`'` { close = `'` }
		`(` { close = `)` }
		else { return '', s }
	}

	mut i := 1
	for i < s.len {
		c := s[i]
		if c == close {
			return unescape_string(s[1..i]), s[i + 1..]
		}
		if c == `\\` && i + 1 < s.len {
			i += 2
			continue
		}
		i++
	}
	return '', s
}

// parse_blockquote parses a blockquote block and returns a blockquote node.
fn (mut p BlockParser) parse_blockquote(indent int) &Node {
	mut bq_lines := []string{}
	for p.pos < p.lines.len {
		raw := expand_tabs(p.lines[p.pos])
		stripped := trim_indent(raw, indent)
		if is_blank(stripped) {
			// Lazy continuation stops at blank.
			p.pos++
			break
		}
		if stripped.starts_with('> ') {
			bq_lines << stripped[2..]
			p.pos++
		} else if stripped.starts_with('>') {
			bq_lines << stripped[1..]
			p.pos++
		} else {
			// Lazy continuation line.
			bq_lines << stripped
			p.pos++
		}
	}
	mut node := new_node(.blockquote)
	// Recursively parse the blockquote content.
	mut inner := p.nested_block_parser(bq_lines)
	inner.parse_blocks(mut node, 0)
	p.merge_nested_state(inner)
	return node
}

// ListMarker holds parsed list marker information.
struct ListMarker {
	is_ordered  bool
	bullet_char u8
	start       int
	indent      int // total indent of content after marker
}

// is_list_marker returns true if line starts with a bullet or ordered list marker.
fn is_list_marker(line string) bool {
	if line.len == 0 {
		return false
	}
	_, ok := parse_list_marker(line)
	return ok
}

// parse_list_marker parses a list marker from the beginning of line.
fn parse_list_marker(line string) (ListMarker, bool) {
	sp := leading_spaces(line)
	rest := line[sp..]
	if rest.len == 0 {
		return ListMarker{}, false
	}
	// Bullet list: -, *, +
	if rest[0] == `-` || rest[0] == `*` || rest[0] == `+` {
		if rest.len < 2 || (rest[1] != ` ` && rest[1] != `\t`) {
			// Only a bare marker with no space is not valid (except empty item for -)
			if rest.len == 1 {
				return ListMarker{
					is_ordered:  false
					bullet_char: rest[0]
					indent:      sp + 2
				}, true
			}
			return ListMarker{}, false
		}
		content_indent := sp + 1 + (if rest.len > 1 && rest[1] == `\t` { 3 } else { 1 })
		return ListMarker{
			is_ordered:  false
			bullet_char: rest[0]
			indent:      content_indent
		}, true
	}
	// Ordered list: 1. or 1)
	mut num_end := 0
	for num_end < rest.len && is_digit(rest[num_end]) {
		num_end++
	}
	if num_end > 0 && num_end < rest.len && (rest[num_end] == `.` || rest[num_end] == `)`) {
		marker_end := num_end + 1
		if marker_end < rest.len && rest[marker_end] != ` ` && rest[marker_end] != `\t` {
			return ListMarker{}, false
		}
		num_str := rest[..num_end]
		start := num_str.int()
		mut content_indent := sp + marker_end + 1
		if marker_end < rest.len && rest[marker_end] == `\t` {
			content_indent = sp + marker_end + (4 - ((sp + marker_end) % 4))
		}
		return ListMarker{
			is_ordered:  true
			start:       start
			bullet_char: rest[num_end]
			indent:      content_indent
		}, true
	}
	return ListMarker{}, false
}

// parse_list parses a list (bullet or ordered) and returns a list node.
fn (mut p BlockParser) parse_list(indent int) &Node {
	// Determine list type from the first item's marker.
	if p.pos >= p.lines.len {
		return new_node(.list)
	}

	first_raw := expand_tabs(p.lines[p.pos])
	first_line := trim_indent(first_raw, indent)
	marker, ok := parse_list_marker(first_line)
	if !ok {
		return new_node(.list)
	}

	mut list := new_node(.list)
	list.is_ordered = marker.is_ordered
	list.list_start = if marker.is_ordered { marker.start } else { 1 }
	list.is_tight = true

	mut had_blank := false

	for p.pos < p.lines.len {
		raw := expand_tabs(p.lines[p.pos])
		stripped := trim_indent(raw, indent)

		if is_blank(stripped) {
			had_blank = true
			p.pos++
			continue
		}

		cur_marker, marker_ok := parse_list_marker(stripped)
		if !marker_ok {
			break
		}
		// Different list type → stop.
		if cur_marker.is_ordered != marker.is_ordered {
			break
		}
		if !cur_marker.is_ordered && cur_marker.bullet_char != marker.bullet_char {
			break
		}

		if had_blank {
			list.is_tight = false
		}
		had_blank = false

		item := p.parse_list_item(indent)
		list.append_child(item)
	}

	return list
}

// parse_list_item parses a single list item and returns a list_item node.
fn (mut p BlockParser) parse_list_item(base_indent int) &Node {
	if p.pos >= p.lines.len {
		return new_node(.list_item)
	}

	mut item := new_node(.list_item)

	// Get first line of the item
	first_raw := expand_tabs(p.lines[p.pos])
	first_stripped := trim_indent(first_raw, base_indent)

	// Extract content after marker
	marker_line := first_stripped
	mut marker_idx := 0

	// Find where marker ends in stripped line
	if marker_line.len > 0
		&& (marker_line[0] == `-` || marker_line[0] == `*` || marker_line[0] == `+`) {
		// Bullet marker: skip marker and whitespace
		marker_idx = 1
		for marker_idx < marker_line.len
			&& (marker_line[marker_idx] == ` ` || marker_line[marker_idx] == `\t`) {
			marker_idx++
		}
	} else {
		// Ordered marker: skip number and . or )
		for marker_idx < marker_line.len && is_digit(marker_line[marker_idx]) {
			marker_idx++
		}
		if marker_idx < marker_line.len
			&& (marker_line[marker_idx] == `.` || marker_line[marker_idx] == `)`) {
			marker_idx++
		}
		// Skip whitespace after marker
		for marker_idx < marker_line.len
			&& (marker_line[marker_idx] == ` ` || marker_line[marker_idx] == `\t`) {
			marker_idx++
		}
	}

	// Get content after marker
	first_content := if marker_idx < marker_line.len {
		marker_line[marker_idx..]
	} else {
		''
	}

	// Detect task list checkbox: [ ] or [x] or [X] at the start of content.
	mut task_checked := false
	mut has_task := false
	mut task_content_start := 0
	if p.opts.task_list && first_content.len >= 3 && first_content[0] == `[` {
		if (first_content[1] == ` ` || first_content[1] == `x` || first_content[1] == `X`)
			&& first_content[2] == `]` {
			if first_content.len == 3 || first_content[3] == ` ` || first_content[3] == `\t` {
				has_task = true
				task_checked = first_content[1] != ` `
				// Skip the checkbox and one optional following whitespace char.
				task_content_start = if first_content.len > 3 { 4 } else { 3 }
			}
		}
	}
	actual_first_content := if has_task {
		first_content[task_content_start..]
	} else {
		first_content
	}

	// Collect lines belonging to this item
	mut item_lines := [actual_first_content]
	p.pos++

	// Content indent is where subsequent lines must be indented to
	first_leading := leading_spaces(first_stripped)
	content_indent := first_leading + marker_idx

	for p.pos < p.lines.len {
		raw := expand_tabs(p.lines[p.pos])
		stripped_base := trim_indent(raw, base_indent)

		if is_blank(stripped_base) {
			item_lines << ''
			p.pos++
			continue
		}

		sp := leading_spaces(stripped_base)

		// If line has enough indent, include it
		if sp >= content_indent {
			// Remove the content indent
			item_lines << trim_indent(stripped_base, content_indent)
			p.pos++
			continue
		}

		// If line starts a new list item at base indent level, stop
		if sp < 2 {
			_, mk := parse_list_marker(stripped_base)
			if mk {
				break
			}
		}

		// Check if it might be a sub-block (less indented but meaningful)
		if is_thematic_break(stripped_base) || stripped_base.starts_with('#') {
			break
		}

		item_lines << stripped_base
		p.pos++
	}

	// Trim trailing blank lines
	for item_lines.len > 0 && item_lines[item_lines.len - 1] == '' {
		item_lines = unsafe { item_lines[..item_lines.len - 1] }
	}

	// Recursively parse the item's content with fresh parser
	mut inner := p.nested_block_parser(item_lines)
	inner.parse_blocks(mut item, 0)

	// Merge back any new link references and footnote definitions.
	p.merge_nested_state(inner)

	// Prepend task checkbox node if detected (must be first child).
	if has_task {
		mut chk := new_node(.task_checkbox)
		chk.checked = task_checked
		mut new_children := [chk]
		for child in item.children {
			new_children << child
		}
		item.children = new_children
	}

	return item
}

// try_table attempts to parse a GFM table starting at p.pos.
// A table requires a header row, an alignment row (|---|), then data rows.
fn (mut p BlockParser) try_table(indent int) ?&Node {
	if p.pos + 1 >= p.lines.len {
		return none
	}
	header_raw := expand_tabs(p.lines[p.pos])
	header_line := trim_indent(header_raw, indent)
	sep_raw := expand_tabs(p.lines[p.pos + 1])
	sep_line := trim_indent(sep_raw, indent)

	if !is_table_separator(sep_line) {
		return none
	}
	if !header_line.contains('|') {
		return none
	}

	aligns := parse_table_alignments(sep_line)
	if aligns.len == 0 {
		return none
	}

	mut tbl := new_node(.table)

	// Header row.
	mut head := new_node(.table_head)
	header_row := parse_table_row(header_line, aligns)
	head.append_child(header_row)
	tbl.append_child(head)

	p.pos += 2

	// Body rows.
	mut body := new_node(.table_body)
	for p.pos < p.lines.len {
		raw := expand_tabs(p.lines[p.pos])
		stripped := trim_indent(raw, indent)
		if is_blank(stripped) || !stripped.contains('|') {
			break
		}
		body.append_child(parse_table_row(stripped, aligns))
		p.pos++
	}
	if body.children.len > 0 {
		tbl.append_child(body)
	}
	return tbl
}

// is_table_separator returns true if line is a table alignment separator row.
fn is_table_separator(line string) bool {
	trimmed := line.trim('| \t')
	if trimmed.len == 0 {
		return false
	}
	cells := split_table_cells(line)
	if cells.len == 0 {
		return false
	}
	for cell in cells {
		c := cell.trim_space()
		if c.len == 0 {
			continue
		}
		inner := if c.starts_with(':') && c.ends_with(':') {
			c[1..c.len - 1]
		} else if c.starts_with(':') {
			c[1..]
		} else if c.ends_with(':') {
			c[..c.len - 1]
		} else {
			c
		}
		for ch in inner.runes() {
			if ch != `-` {
				return false
			}
		}
		if inner.len == 0 {
			return false
		}
	}
	return true
}

// parse_table_alignments returns the alignment for each column from a separator line.
fn parse_table_alignments(line string) []Alignment {
	cells := split_table_cells(line)
	mut aligns := []Alignment{}
	for cell in cells {
		c := cell.trim_space()
		if c.len == 0 {
			continue
		}
		left := c.starts_with(':')
		right := c.ends_with(':')
		if left && right {
			aligns << .center
		} else if left {
			aligns << .left
		} else if right {
			aligns << .right
		} else {
			aligns << .none_
		}
	}
	return aligns
}

// parse_table_row parses a table row line into a table_row node.
fn parse_table_row(line string, aligns []Alignment) &Node {
	cells := split_table_cells(line)
	mut row := new_node(.table_row)
	for i, cell_text in cells {
		mut cell := new_node(.table_cell)
		cell.align = if i < aligns.len { aligns[i] } else { .none_ }
		cell.literal = cell_text.trim_space()
		row.append_child(cell)
	}
	return row
}

// split_table_cells splits a table row line by pipe characters.
fn split_table_cells(line string) []string {
	trimmed := line.trim_space()
	// Strip leading/trailing pipe.
	inner := if trimmed.starts_with('|') && trimmed.ends_with('|') && trimmed.len > 1 {
		trimmed[1..trimmed.len - 1]
	} else if trimmed.starts_with('|') {
		trimmed[1..]
	} else if trimmed.ends_with('|') {
		trimmed[..trimmed.len - 1]
	} else {
		trimmed
	}
	mut cells := []string{}
	mut current := strings.new_builder(32)
	for i := 0; i < inner.len; i++ {
		if inner[i] == `\\` && i + 1 < inner.len && inner[i + 1] == `|` {
			current.write_u8(`|`)
			i++
		} else if inner[i] == `|` {
			cells << current.str()
			current = strings.new_builder(32)
		} else {
			current.write_u8(inner[i])
		}
	}
	last := current.str()
	cells << last
	return cells
}

// try_definition_list attempts to parse a definition list starting at p.pos.
fn (mut p BlockParser) try_definition_list(indent int) ?&Node {
	if p.pos + 1 >= p.lines.len {
		return none
	}
	next_raw := expand_tabs(p.lines[p.pos + 1])
	next_stripped := trim_indent(next_raw, indent)
	if !next_stripped.starts_with(':') {
		return none
	}
	mut dl := new_node(.definition_list)
	for p.pos < p.lines.len {
		raw := expand_tabs(p.lines[p.pos])
		stripped := trim_indent(raw, indent)
		if is_blank(stripped) {
			p.pos++
			break
		}
		// Collect term line.
		mut term := new_node(.definition_term)
		term.literal = stripped
		p.pos++
		// Collect one or more definitions (:).
		for p.pos < p.lines.len {
			def_raw := expand_tabs(p.lines[p.pos])
			def_stripped := trim_indent(def_raw, indent)
			if def_stripped.starts_with(':') {
				mut desc := new_node(.definition_desc)
				desc.literal = def_stripped[1..].trim_left(' \t')
				term.append_child(desc)
				p.pos++
			} else {
				break
			}
		}
		dl.append_child(term)
	}
	if dl.children.len == 0 {
		return none
	}
	return dl
}

// try_footnote_def attempts to parse a footnote definition starting at p.pos.
fn (mut p BlockParser) try_footnote_def(line string, indent int) bool {
	if !line.starts_with('[^') {
		return false
	}
	end := line.index_after_(']', 2)
	if end < 0 || end + 1 >= line.len || line[end + 1] != `:` {
		return false
	}
	label := line[2..end]
	if label.len == 0 {
		return false
	}
	content := line[end + 2..].trim_left(' \t')
	mut fn_node := new_node(.footnote_def)
	fn_node.fn_label = label
	fn_node.literal = content
	p.pos++
	// Collect continuation lines (indented by at least 4 spaces).
	for p.pos < p.lines.len {
		raw := expand_tabs(p.lines[p.pos])
		stripped := trim_indent(raw, indent)
		if is_blank(stripped) || leading_spaces(stripped) >= 4 {
			fn_node.literal += '\n' + stripped.trim_left('    ')
			p.pos++
		} else {
			break
		}
	}
	if label !in p.fn_defs {
		p.fn_defs[label] = fn_node
	}
	return true
}

// parse_paragraph parses a paragraph block, upgrading it to a setext heading
// if the immediately following line is a setext underline (=== or ---).
fn (mut p BlockParser) parse_paragraph(indent int) &Node {
	mut para_lines := []string{}
	for p.pos < p.lines.len {
		raw := expand_tabs(p.lines[p.pos])
		stripped := trim_indent(raw, indent)

		if is_blank(stripped) {
			p.pos++
			break
		}
		// Check for setext underline on the next line while para_lines is non-empty.
		if para_lines.len > 0 {
			if is_setext_underline(stripped) {
				level := if stripped.trim_left(' \t')[0] == `=` { 1 } else { 2 }
				content := para_lines.join('\n').trim_space()
				mut node := new_node(.heading)
				node.level = level
				node.literal = content
				if p.opts.parser_opts.auto_heading_id {
					node.id = heading_id_from_text(content)
				}
				p.pos++
				return node
			}
		}
		// Other block starters interrupt a paragraph.
		if para_lines.len > 0 {
			if is_thematic_break(stripped) || stripped.starts_with('#') || stripped.starts_with('>')
				|| stripped.starts_with('```') || stripped.starts_with('~~~') {
				break
			}
			if is_list_marker(stripped) {
				break
			}
		}
		para_lines << stripped
		p.pos++
	}
	mut node := new_node(.paragraph)
	node.literal = para_lines.join('\n').trim_space()
	return node
}

// is_setext_underline returns true if line is a setext heading underline
// (0-3 leading spaces, then one or more = or - with optional trailing spaces).
fn is_setext_underline(line string) bool {
	if line.len == 0 {
		return false
	}
	// Allow up to 3 leading spaces (CommonMark spec rule 80).
	mut start := 0
	for start < 3 && start < line.len && line[start] == ` ` {
		start++
	}
	if start >= line.len {
		return false
	}
	c := line[start]
	if c != `=` && c != `-` {
		return false
	}
	for i := start; i < line.len; i++ {
		if line[i] != c && line[i] != ` ` && line[i] != `\t` {
			return false
		}
	}
	return true
}

// unescape_string decodes CommonMark backslash escapes in s.
fn unescape_string(s string) string {
	if !s.contains('\\') {
		return s
	}
	mut out := strings.new_builder(s.len)
	mut i := 0
	for i < s.len {
		if s[i] == `\\` && i + 1 < s.len && is_ascii_punct(s[i + 1]) {
			out.write_u8(s[i + 1])
			i += 2
		} else {
			out.write_u8(s[i])
			i++
		}
	}
	return out.str()
}