satteri-pulldown-cmark 0.6.3

//! Direct arena builder: walks the pulldown-cmark internal tree and builds
//! a `satteri_arena::Arena` without going through the Event iterator.

use alloc::borrow::Cow;

use satteri_arena::{Arena, ArenaBuilder, LineIndex, Mdast, StringRef, line_ending_iter};
use satteri_ast::mdast::{
    CodeData, ColumnAlign, DefinitionData, DescriptionDetailsData, FootnoteDefinitionData,
    ImageData, LinkData, ListData, ListItemData, MathData, MdastNodeType, ReferenceData,
    encode_directive_data, encode_image_reference_data, encode_reference_data, encode_table_data,
};
#[cfg(feature = "mdx")]
use satteri_ast::mdast::{ExpressionData, encode_mdx_jsx_element_data};
#[cfg(feature = "mdx")]
use satteri_ast::shared::{
    MDX_ATTR_BOOLEAN_PROP, MDX_ATTR_EXPRESSION_PROP, MDX_ATTR_LITERAL_PROP, MDX_ATTR_SPREAD,
};

use crate::linklabel::LinkLabel;
#[cfg(feature = "mdx")]
use crate::parse::JsxAttr;
use crate::parse::{DefaultParserCallbacks, HeadingAttributes, ItemBody, LinkDef, ParserInner};
use crate::{Alignment, HeadingLevel, LinkType, Options};

#[cfg(feature = "mdx")]
use crate::post_passes::MDX_EXPLICIT_JSX_DATA;

/// Default options: GFM (tables, strikethrough, task lists, autolink-literal),
/// footnotes, math, YAML metadata.
/// Note: heading attributes (`# Title {#id .cls}`) are intentionally NOT enabled
/// here — remark doesn't parse them and stripping them breaks conformance for
/// headings that incidentally contain `{…}` text.
pub const DEFAULT_OPTIONS: Options = Options::from_bits_truncate(
    Options::ENABLE_GFM.bits()
        | Options::ENABLE_TABLES.bits()
        | Options::ENABLE_FOOTNOTES.bits()
        | Options::ENABLE_STRIKETHROUGH.bits()
        | Options::ENABLE_TASKLISTS.bits()
        | Options::ENABLE_MATH.bits()
        | Options::ENABLE_YAML_STYLE_METADATA_BLOCKS.bits(),
);

/// MDX options: default options plus JSX, expressions, and ESM.
#[cfg(feature = "mdx")]
pub const MDX_OPTIONS: Options =
    Options::from_bits_truncate(DEFAULT_OPTIONS.bits() | Options::ENABLE_MDX.bits());

/// Parse markdown source into an Arena.
///
/// Offsets and the arena's source are relative to [`crate::strip_leading_bom`].
///
/// Returns `(arena, mdx_errors)` where `mdx_errors` contains any MDX
/// validation errors collected during parsing (empty for non-MDX input).
pub fn parse(source: &str, options: Options) -> (Arena<Mdast>, Vec<(usize, String)>) {
    parse_inner(source, options, true, None, false)
}

/// Skip-positions variant: leaves per-node line/column fields at the zero
/// sentinel, skipping the `LineIndex` build, the per-node cursor lookups, and
/// the cp-offset post-pass. Byte offsets are still filled. Use when the
/// consumer (HTML/JS codegen) never reads positions.
pub fn parse_no_positions(source: &str, options: Options) -> (Arena<Mdast>, Vec<(usize, String)>) {
    parse_inner(source, options, false, None, false)
}

/// Same as `parse_no_positions` but recycles a caller-pooled arena (via
/// `reset()`), reusing its `Vec` / `String` capacity to save the per-compile
/// mallocs that dominate tiny inputs.
pub fn parse_no_positions_into(
    source: &str,
    options: Options,
    reuse: Arena<Mdast>,
) -> (Arena<Mdast>, Vec<(usize, String)>) {
    parse_inner(source, options, false, Some(reuse), false)
}

/// Same as [`parse`] but recycles a caller-pooled arena; see [`parse_no_positions_into`].
pub fn parse_into(
    source: &str,
    options: Options,
    reuse: Arena<Mdast>,
) -> (Arena<Mdast>, Vec<(usize, String)>) {
    parse_inner(source, options, true, Some(reuse), false)
}

/// `skip_fnr_autolink` is the path-selection probe's lever: every entry point
/// above passes `false`, so only `#[cfg(test)]` code can turn it on.
fn parse_inner(
    source: &str,
    options: Options,
    track_positions: bool,
    reuse: Option<Arena<Mdast>>,
    skip_fnr_autolink: bool,
) -> (Arena<Mdast>, Vec<(usize, String)>) {
    let source = crate::strip_leading_bom(source);

    // ENABLE_GFM is the umbrella flag for the GitHub Flavored Markdown
    // feature set. Expand it into the granular flags the parser checks so
    // callers don't have to remember which sub-flags GFM implies.
    let options = if options.contains(Options::ENABLE_GFM) {
        options | Options::ENABLE_TABLES | Options::ENABLE_STRIKETHROUGH | Options::ENABLE_TASKLISTS
    } else {
        options
    };

    // ENABLE_MATH is the umbrella for math, mirroring ENABLE_GFM above:
    // expand it into the single- and multi-dollar flags the parser checks.
    let options = if options.contains(Options::ENABLE_MATH) {
        options | Options::ENABLE_MATH_SINGLE_DOLLAR | Options::ENABLE_MATH_MULTI_DOLLAR
    } else {
        options
    };

    let line_index = if track_positions {
        LineIndex::from_source(source)
    } else {
        LineIndex::disabled_for(source)
    };
    let mut cursor = line_index.cursor();

    // Measured: ~1 node/16 bytes, ~11 type-data bytes/node, pool up to ~2.5x source.
    let estimated_nodes = source.len() / 16 + 16;
    let source_extra = source.len() * 2;
    let arena = if let Some(mut a) = reuse {
        // Recycle: clear all per-document state but keep the already-grown
        // `Vec` / `String` allocations. For tiny inputs the saved `malloc`s
        // are the dominant cost, since the actual parse and convert work is
        // already sub-microsecond.
        a.reset();
        a.string_pool.reserve(source.len() + source_extra);
        a.string_pool.push_str(source);
        a.source_len = source.len() as u32;
        a.nodes.reserve(estimated_nodes);
        a.children.reserve(estimated_nodes);
        a.type_data.reserve(estimated_nodes * 12);
        a
    } else {
        let mut source_buf = String::with_capacity(source.len() + source_extra);
        source_buf.push_str(source);
        Arena::<Mdast>::with_capacity(
            source_buf,
            estimated_nodes,
            estimated_nodes,
            estimated_nodes * 12,
        )
    };
    let mut builder: ArenaBuilder<Mdast> = ArenaBuilder::from_arena(arena);

    // Build the pulldown-cmark parser (runs first pass).
    let mut inner = ParserInner::new(source, options);
    let mut callbacks = DefaultParserCallbacks;

    // Open root node. In skip-positions mode the cursor returns the zero
    // sentinel; mirror it in the root's hardcoded 1:1 start so every node
    // carries a consistent "no position" marker (byte offsets stay filled).
    builder.open_node(MdastNodeType::Root as u8);
    let (end_line, end_col) = cursor.offset_to_line_col(source.len() as u32);
    let (start_line, start_col) = if track_positions { (1, 1) } else { (0, 0) };
    builder.set_position_current(
        0,
        source.len() as u32,
        start_line,
        start_col,
        end_line,
        end_col,
    );

    // Accumulation buffers for special container→leaf conversions.
    let mut html_block_buf: Option<String> = None;
    let mut code_block_buf: Option<String> = None;
    let mut image_alt_buf: Option<String> = None;
    let mut image_depth: usize = 0;

    // JSX tag pairing state. The third element is `is_flow` — true if the
    // open tag was on its own block line (MdxJsxFlowElement), false if it
    // was inline (MdxJsxTextElement). mdx-js requires the closing tag to
    // match in mode: a flow open can't be paired with an inline close, so
    // `<Foo>\n</Foo>X` (close has trailing text → inline mode) errors.
    let mut jsx_stack: Vec<(String, u32, bool)> = Vec::new();
    let mut mdx_errors: Vec<(usize, String)> = Vec::new();
    let mut paragraph_open_depth: Vec<usize> = Vec::new();
    // jsx_stack length snapshot taken when a structural container
    // (blockquote, list item, container directive) opens. When the
    // container closes, any JSX entry pushed inside it that's still on
    // the stack is unclosed-within-the-container and triggers an
    // mdx-js-style "Expected a closing tag … before the end of `…`"
    // error — see §B in plans/mdx-conformance.md.
    let mut container_jsx_snapshot: Vec<(MdastNodeType, usize)> = Vec::new();

    // Refdefs in source order. Each container close pass claims the defs whose
    // source range lies inside it; the rest get emitted at root.
    //
    // We take ownership of `refdefs_all` instead of cloning each field; the
    // parser doesn't read it again after this point. Saves up to 3 heap allocs
    // per refdef on the parse hot path.
    let mut refdefs_owned: Vec<(LinkLabel<'_>, LinkDef<'_>)> =
        core::mem::take(&mut inner.allocs.refdefs_all);
    refdefs_owned.sort_by_key(|(_, def)| def.span.start);
    let refdef_starts: Vec<usize> = refdefs_owned.iter().map(|(_, d)| d.span.start).collect();
    let mut refdef_emitted: Vec<bool> = vec![false; refdefs_owned.len()];

    let mdx = options.contains(Options::ENABLE_MDX);
    // An unclosed MDX JSX tag can leave a container's node open past its own tree pop, so its end never gets fixed up.
    let defer_container_end = track_positions && !mdx;

    // Walk the tree iteratively.
    loop {
        match inner.tree.cur() {
            None => {
                // Backing out of a container, emit close.
                let ix = match inner.tree.pop() {
                    Some(ix) => ix,
                    None => break, // Done: popped past root.
                };

                // TightParagraph: close it like a regular paragraph.
                // MDAST spec requires listItem > paragraph > text even for
                // tight lists.

                // Inside an image: skip closing non-Image containers
                // (they were never opened in the MDAST builder).
                if image_alt_buf.is_some()
                    && !matches!(inner.tree[ix].item.body, ItemBody::Image(_))
                {
                    image_depth = image_depth.saturating_sub(1);
                    inner.tree.next_sibling(ix);
                    continue;
                }

                let item = inner.tree[ix].item;
                // Every branch of `mdast_position_end` hands back `item.end` untouched unless a line terminator precedes it.
                let end = if item.end > 0
                    && matches!(source.as_bytes().get(item.end - 1), Some(b'\n' | b'\r'))
                {
                    let parent_body = inner.tree.peek_up().map(|p| inner.tree[p].item.body);
                    crate::firstpass::mdast_position_end(
                        &item,
                        source.as_bytes(),
                        parent_body.as_ref(),
                    )
                } else {
                    item.end as u32
                };
                let (end_line, end_col) = cursor.offset_to_line_col(end);

                match &inner.tree[ix].item.body {
                    // Math block close: write accumulated content.
                    ItemBody::MathBlock(_) => {
                        if let Some(mut content) = code_block_buf.take() {
                            // Drop the trailing line terminator (remark keeps
                            // CRLF inside the value but strips the one right
                            // before the closing fence).
                            if content.ends_with("\r\n") {
                                content.truncate(content.len() - 2);
                            } else if content.ends_with('\n') || content.ends_with('\r') {
                                content.pop();
                            }
                            let meta_str = match &inner.tree[ix].item.body {
                                ItemBody::MathBlock(cow_ix) => {
                                    let cow = inner.allocs.take_cow(*cow_ix);
                                    cow.to_string()
                                }
                                _ => String::new(),
                            };
                            let meta_ref = if meta_str.is_empty() {
                                StringRef::empty()
                            } else {
                                builder.alloc_string(&meta_str)
                            };
                            let value_ref = builder.alloc_string(&content);

                            builder.set_data_current(
                                &MathData {
                                    meta: meta_ref,
                                    value: value_ref,
                                }
                                .to_bytes(),
                            );
                            let id = builder.current_node_id();
                            let node = builder.arena_ref().get_node(id);
                            let orig_start = node.start_offset;
                            let orig_start_line = node.start_line;
                            let orig_start_col = node.start_column;
                            builder.set_position_current(
                                orig_start,
                                end,
                                orig_start_line,
                                orig_start_col,
                                end_line,
                                end_col,
                            );
                            builder.close_node();
                        }
                    }
                    // Code block close: write accumulated content.
                    ItemBody::FencedCodeBlock(..) | ItemBody::IndentCodeBlock(_) => {
                        if let Some(mut content) = code_block_buf.take() {
                            // Drop the trailing line terminator (remark keeps
                            // CRLF inside the value but strips the one right
                            // before the closing fence).
                            if content.ends_with("\r\n") {
                                content.truncate(content.len() - 2);
                            } else if content.ends_with('\n') || content.ends_with('\r') {
                                content.pop();
                            }
                            let sr = builder.alloc_string(&content);
                            let id = builder.current_node_id();
                            let data = builder.arena_mut().get_type_data_mut(id);
                            if data.len() >= 24 {
                                data[16..24].copy_from_slice(&sr.as_bytes());
                            }
                            let mut code_end = end;
                            let mut code_end_line = end_line;
                            let mut code_end_col = end_col;
                            let code_start_column = builder.arena_ref().get_node(id).start_column;
                            let parent_body =
                                inner.tree.peek_up().map(|p| &inner.tree[p].item.body);
                            if let Some(ext) = crate::firstpass::extend_indented_code_block(
                                &inner.tree[ix].item,
                                source.as_bytes(),
                                parent_body,
                                code_start_column,
                                end,
                            ) {
                                code_end = ext.end_offset;
                                let (el, ec) = cursor.offset_to_line_col(code_end);
                                code_end_line = el;
                                code_end_col = ec;
                                if ext.extra_blank_lines > 0
                                    && builder.arena_ref().get_type_data(id).len() >= 24
                                {
                                    let mut extended = String::with_capacity(
                                        content.len() + ext.extra_blank_lines,
                                    );
                                    extended.push_str(&content);
                                    for _ in 0..ext.extra_blank_lines {
                                        extended.push('\n');
                                    }
                                    let sr2 = builder.alloc_string(&extended);
                                    builder.arena_mut().get_type_data_mut(id)[16..24]
                                        .copy_from_slice(&sr2.as_bytes());
                                }
                            }
                            let node = builder.arena_ref().get_node(id);
                            let orig_start = node.start_offset;
                            let orig_start_line = node.start_line;
                            let orig_start_col = node.start_column;
                            builder.set_position_current(
                                orig_start,
                                code_end,
                                orig_start_line,
                                orig_start_col,
                                code_end_line,
                                code_end_col,
                            );
                            builder.close_node();
                        }
                    }
                    // HTML block close: write accumulated content. The bool
                    // says whether to trim a trailing newline — true for
                    // type 6/7 (always) and for type 1-5 that hit their
                    // closer pattern; false for type 1-5 that ran to EOF
                    // without a closer (then the trailing `\n` is content).
                    ItemBody::HtmlBlock(trim_trailing) => {
                        if let Some(content) = html_block_buf.take() {
                            let trimmed = if *trim_trailing {
                                let s = content.trim_end_matches('\n');
                                // CRLF source: the final `\r\n` is just the
                                // newline; without dropping the `\r` too the
                                // block value would end in a stray CR.
                                s.trim_end_matches('\r')
                            } else {
                                content.as_str()
                            };
                            let sr = builder.alloc_string(trimmed);
                            let id = builder.current_node_id();
                            let node = builder.arena_ref().get_node(id);
                            let orig_start = node.start_offset;
                            let orig_start_line = node.start_line;
                            let orig_start_col = node.start_column;
                            let trimmed_len = content.len() - trimmed.len();
                            let raw_end = (item.end as u32).saturating_sub(trimmed_len as u32);
                            let (raw_end_line, raw_end_col) = cursor.offset_to_line_col(raw_end);
                            builder.set_position_current(
                                orig_start,
                                raw_end,
                                orig_start_line,
                                orig_start_col,
                                raw_end_line,
                                raw_end_col,
                            );
                            builder.set_data_current(&sr.as_bytes());
                            builder.close_node();
                        }
                    }
                    // Metadata block close: strip exactly one trailing line
                    // terminator (the newline before the closing fence).
                    // Any earlier blank line inside the block is content and
                    // must be preserved — matching remark-frontmatter.
                    ItemBody::MetadataBlock(_) => {
                        if let Some(mut content) = html_block_buf.take() {
                            if content.ends_with("\r\n") {
                                content.truncate(content.len() - 2);
                            } else if content.ends_with('\n') || content.ends_with('\r') {
                                content.pop();
                            }
                            let sr = builder.alloc_string(&content);
                            let id = builder.current_node_id();
                            let node = builder.arena_ref().get_node(id);
                            let orig_start = node.start_offset;
                            let orig_start_line = node.start_line;
                            let orig_start_col = node.start_column;
                            builder.set_position_current(
                                orig_start,
                                end,
                                orig_start_line,
                                orig_start_col,
                                end_line,
                                end_col,
                            );
                            builder.set_data_current(&sr.as_bytes());
                            builder.close_node();
                        }
                    }
                    // Image close: finalize alt text.
                    ItemBody::Image(_) => {
                        if image_depth > 0 {
                            image_depth -= 1;
                            inner.tree.next_sibling(ix);
                            continue;
                        }
                        if let Some(alt_text) = image_alt_buf.take() {
                            let alt_ref = builder.alloc_string(&alt_text);
                            let id = builder.current_node_id();
                            let node_type = builder.arena_ref().get_node(id).node_type;
                            let is_image_ref = node_type == MdastNodeType::ImageReference as u8;
                            let data = builder.arena_mut().get_type_data_mut(id);
                            if is_image_ref {
                                if data.len() >= 28 {
                                    data[20..28].copy_from_slice(&alt_ref.as_bytes());
                                }
                            } else if data.len() >= 24 {
                                data[8..16].copy_from_slice(&alt_ref.as_bytes());
                            }
                        }
                        let id = builder.current_node_id();
                        let node = builder.arena_ref().get_node(id);
                        let orig_start = node.start_offset;
                        let orig_start_line = node.start_line;
                        let orig_start_col = node.start_column;
                        builder.set_position_current(
                            orig_start,
                            end,
                            orig_start_line,
                            orig_start_col,
                            end_line,
                            end_col,
                        );
                        builder.close_node();
                    }
                    ItemBody::ListItem(_, item_spread) => {
                        // Drain unclosed JSX opens before refdef pull and
                        // spread computation — mirrors the regular-close
                        // arm's blockquote handling but inline here since
                        // ListItem close has its own arm. See §B.
                        if let Some(&(snap_kind, snap_len)) = container_jsx_snapshot.last()
                            && snap_kind == MdastNodeType::ListItem
                        {
                            container_jsx_snapshot.pop();
                            while jsx_stack.len() > snap_len {
                                let (name, offset, _is_flow) = jsx_stack.pop().unwrap();
                                let loc = byte_offset_to_line_col(source, offset as usize);
                                mdx_errors.push((
                                        offset as usize,
                                        format!(
                                            "Expected a closing tag for `<{name}>` ({loc}) before the end of `listItem`"
                                        ),
                                    ));
                                builder.close_node();
                            }
                        }
                        let id = builder.current_node_id();
                        let node = builder.arena_ref().get_node(id);
                        let orig_start_offset = node.start_offset;
                        // Pull in any refdefs whose source range falls inside
                        // this list item before we evaluate spread / position.
                        if container_may_hold_refdef(
                            &refdef_starts,
                            orig_start_offset as usize,
                            item.end,
                        ) && emit_refdefs_in_container(
                            &mut builder,
                            &mut cursor,
                            source,
                            &refdefs_owned,
                            &refdef_starts,
                            &mut refdef_emitted,
                            orig_start_offset as usize,
                            item.end,
                        ) {
                            builder.sort_current_pending_children_by_source_order();
                        }
                        let is_spread = *item_spread || {
                            // Loose-list detection: a blank line between
                            // consecutive children means two line endings in the
                            // source gap. Counted on byte offsets, not lines, because
                            // skip-positions mode leaves `start_line` zero but
                            // offsets are always recorded.
                            let source_bytes = source.as_bytes();
                            let mut found = false;
                            let mut prev_end_offset: Option<u32> = None;
                            for &child_id in builder.current_pending_children() {
                                let child_node = builder.arena_ref().get_node(child_id);
                                if let Some(peo) = prev_end_offset {
                                    let start = peo as usize;
                                    let end = child_node.start_offset as usize;
                                    if start <= end && end <= source_bytes.len() {
                                        let gap = &source_bytes[start..end];
                                        if line_ending_iter(gap).take(2).count() >= 2 {
                                            found = true;
                                            break;
                                        }
                                    }
                                }
                                prev_end_offset = Some(child_node.end_offset);
                            }
                            found
                        };
                        if is_spread {
                            let data = builder.arena_mut().get_type_data_mut(id);
                            if data.len() >= 2 {
                                data[1] = 1;
                            }
                        }
                        let node = builder.arena_ref().get_node(id);
                        let orig_start = node.start_offset;
                        let orig_start_line = node.start_line;
                        let orig_start_col = node.start_column;
                        let (mut cont_end, mut cont_end_line, mut cont_end_col) =
                            if let Some(last_child) = builder.last_sibling_id() {
                                let lc = builder.arena_ref().get_node(last_child);
                                (lc.end_offset, lc.end_line, lc.end_column)
                            } else {
                                let src = source.as_bytes();
                                let start_usize = orig_start as usize;
                                let end_usize = end as usize;
                                let first_nl = src[start_usize..end_usize]
                                    .iter()
                                    .position(|&b| b == b'\n' || b == b'\r')
                                    .map(|p| (start_usize + p) as u32)
                                    .unwrap_or(end);
                                let (el, ec) = cursor.offset_to_line_col(first_nl);
                                (first_nl, el, ec)
                            };
                        if let Some(extended) =
                            crate::firstpass::extend_list_item_to_next_sibling_content(
                                &inner.tree,
                                ix,
                                source.as_bytes(),
                                cont_end,
                            )
                        {
                            cont_end = extended;
                            let (el, ec) = cursor.offset_to_line_col(cont_end);
                            cont_end_line = el;
                            cont_end_col = ec;
                        }
                        builder.set_position_current(
                            orig_start,
                            cont_end,
                            orig_start_line,
                            orig_start_col,
                            cont_end_line,
                            cont_end_col,
                        );
                        builder.close_node();
                    }
                    ItemBody::List(_is_tight, _, _) => {
                        let id = builder.current_node_id();
                        let node = builder.arena_ref().get_node(id);
                        let orig_start = node.start_offset;
                        let orig_start_line = node.start_line;
                        let orig_start_col = node.start_column;
                        let (mut cont_end, mut cont_end_line, mut cont_end_col) =
                            if let Some(last_child) = builder.last_sibling_id() {
                                let lc = builder.arena_ref().get_node(last_child);
                                (lc.end_offset, lc.end_line, lc.end_column)
                            } else {
                                (end, end_line, end_col)
                            };
                        if let Some(extended) =
                            crate::firstpass::extend_list_in_blockquote_through_marker_lines(
                                &inner.tree,
                                ix,
                                source.as_bytes(),
                                cont_end,
                            )
                        {
                            cont_end = extended;
                            let (el, ec) = cursor.offset_to_line_col(cont_end);
                            cont_end_line = el;
                            cont_end_col = ec;
                        }
                        builder.set_position_current(
                            orig_start,
                            cont_end,
                            orig_start_line,
                            orig_start_col,
                            cont_end_line,
                            cont_end_col,
                        );
                        builder.close_node();
                        let children = builder.arena_ref().get_children(id).to_vec();
                        let has_blank_between_items = {
                            // Same byte-offset-based blank-line detection as
                            // the inner ListItem case above. Independent of
                            // line tracking.
                            let source_bytes = source.as_bytes();
                            let mut found = false;
                            let mut prev_end_offset: Option<u32> = None;
                            for &child_id in &children {
                                let child_node = builder.arena_ref().get_node(child_id);
                                if let Some(peo) = prev_end_offset {
                                    let start = peo as usize;
                                    let end = child_node.start_offset as usize;
                                    if start <= end && end <= source_bytes.len() {
                                        let gap = &source_bytes[start..end];
                                        if line_ending_iter(gap).take(2).count() >= 2 {
                                            found = true;
                                            break;
                                        }
                                    }
                                }
                                prev_end_offset = Some(child_node.end_offset);
                            }
                            found
                        };
                        if has_blank_between_items {
                            let data = builder.arena_mut().get_type_data_mut(id);
                            if data.len() >= 8 {
                                data[5] = 1;
                            }
                        }
                        // Already closed above; skip the common close_node path.
                        inner.tree.next_sibling(ix);
                        continue;
                    }
                    // dl/dt/dd: extend the end to span the last child, like List.
                    ItemBody::DefinitionList(..)
                    | ItemBody::DefinitionListTitle
                    | ItemBody::DefinitionListDefinition(..) => {
                        let id = builder.current_node_id();
                        let node = builder.arena_ref().get_node(id);
                        let orig_start = node.start_offset;
                        let orig_start_line = node.start_line;
                        let orig_start_col = node.start_column;
                        let (cont_end, cont_end_line, cont_end_col) =
                            if let Some(last_child) = builder.last_sibling_id() {
                                let lc = builder.arena_ref().get_node(last_child);
                                (lc.end_offset, lc.end_line, lc.end_column)
                            } else {
                                (end, end_line, end_col)
                            };
                        builder.set_position_current(
                            orig_start,
                            cont_end,
                            orig_start_line,
                            orig_start_col,
                            cont_end_line,
                            cont_end_col,
                        );
                        builder.close_node();
                    }
                    // Regular container close.
                    _ => {
                        // If this is a Paragraph close, drain any inline JSX
                        // that was opened inside the paragraph but never
                        // matched. micromark-mdx errors in this situation
                        // ("Expected a closing tag for `<X>` … before the
                        // end of `paragraph`"); we mirror the error rather
                        // than silently produce an invalid tree where the
                        // would-be paragraph-close ends up closing the
                        // dangling JSX node.
                        if matches!(
                            item.body,
                            ItemBody::Paragraph
                                | ItemBody::TightParagraph
                                | ItemBody::DirectiveLabel
                        ) && let Some(opened_at) = paragraph_open_depth.pop()
                        {
                            while builder.stack_depth() > opened_at {
                                if let Some((name, offset, _is_flow)) = jsx_stack.pop() {
                                    let loc = byte_offset_to_line_col(source, offset as usize);
                                    mdx_errors.push((
                                            offset as usize,
                                            format!(
                                                "Expected a closing tag for `<{name}>` ({loc}) before the end of `paragraph`"
                                            ),
                                        ));
                                }
                                builder.close_node();
                            }
                        }
                        // Drain unclosed JSX opens that were pushed inside a
                        // structural container (blockquote, list item) when
                        // that container closes. mdx-js errors structurally
                        // — see §B.
                        let container_kind_for_drain = match item.body {
                            ItemBody::BlockQuote(_) => Some(MdastNodeType::Blockquote),
                            ItemBody::ListItem(..) => Some(MdastNodeType::ListItem),
                            _ => None,
                        };
                        if let Some(kind) = container_kind_for_drain
                            && let Some(&(snap_kind, snap_len)) = container_jsx_snapshot.last()
                            && snap_kind == kind
                        {
                            container_jsx_snapshot.pop();
                            while jsx_stack.len() > snap_len {
                                let (name, offset, _is_flow) = jsx_stack.pop().unwrap();
                                let loc = byte_offset_to_line_col(source, offset as usize);
                                let container_label = match kind {
                                    MdastNodeType::Blockquote => "blockQuote",
                                    MdastNodeType::ListItem => "listItem",
                                    _ => "container",
                                };
                                mdx_errors.push((
                                            offset as usize,
                                            format!(
                                                "Expected a closing tag for `<{name}>` ({loc}) before the end of `{container_label}`"
                                            ),
                                        ));
                                builder.close_node();
                            }
                        }
                        let id = builder.current_node_id();
                        let node = builder.arena_ref().get_node(id);
                        let orig_start = node.start_offset;
                        let orig_start_line = node.start_line;
                        let orig_start_col = node.start_column;
                        // Claim refdefs nested in this container before its
                        // children are finalized.
                        if matches!(
                            item.body,
                            ItemBody::BlockQuote(..)
                                | ItemBody::ContainerDirective(..)
                                | ItemBody::FootnoteDefinition(..)
                        ) && container_may_hold_refdef(
                            &refdef_starts,
                            orig_start as usize,
                            item.end,
                        ) && emit_refdefs_in_container(
                            &mut builder,
                            &mut cursor,
                            source,
                            &refdefs_owned,
                            &refdef_starts,
                            &mut refdef_emitted,
                            orig_start as usize,
                            item.end,
                        ) {
                            builder.sort_current_pending_children_by_source_order();
                        }
                        let use_last_child = matches!(
                            item.body,
                            ItemBody::BlockQuote(..) | ItemBody::ContainerDirective(..)
                        );
                        let use_last_child_strict =
                            matches!(item.body, ItemBody::FootnoteDefinition(..));
                        let (mut cont_end, mut cont_end_line, mut cont_end_col) = if use_last_child
                        {
                            if let Some(last_child) = builder.last_sibling_id() {
                                let lc = builder.arena_ref().get_node(last_child);
                                if lc.end_offset >= end {
                                    (lc.end_offset, lc.end_line, lc.end_column)
                                } else {
                                    (end, end_line, end_col)
                                }
                            } else {
                                (end, end_line, end_col)
                            }
                        } else if use_last_child_strict {
                            // FootnoteDefinition: end at the last child's end
                            // (don't absorb trailing blank lines / whitespace
                            // beyond the content — matches remark, which
                            // trims trailing source-whitespace from the
                            // definition's span).
                            if let Some(last_child) = builder.last_sibling_id() {
                                let lc = builder.arena_ref().get_node(last_child);
                                (lc.end_offset, lc.end_line, lc.end_column)
                            } else {
                                (end, end_line, end_col)
                            }
                        } else {
                            (end, end_line, end_col)
                        };

                        if let Some(extended) =
                            crate::firstpass::extend_inner_blockquote_through_outer_markers(
                                &inner.tree,
                                ix,
                                source.as_bytes(),
                                cont_end,
                            )
                        {
                            cont_end = extended;
                            let (el, ec) = cursor.offset_to_line_col(cont_end);
                            cont_end_line = el;
                            cont_end_col = ec;
                        }
                        builder.set_position_current(
                            orig_start,
                            cont_end,
                            orig_start_line,
                            orig_start_col,
                            cont_end_line,
                            cont_end_col,
                        );
                        builder.close_node();
                    }
                }

                inner.tree.next_sibling(ix);
            }
            Some(cur_ix) => {
                // TightParagraph: emit as a regular paragraph node.
                // MDAST spec requires listItem > paragraph > text even for
                // tight lists.

                // Resolve inline markup if needed.
                if inner.tree[cur_ix].item.body.is_maybe_inline() {
                    inner.handle_inline(&mut callbacks);
                }

                let item = inner.tree[cur_ix].item;
                let start = item.start as u32;
                let end = item.end as u32;
                let (start_line, start_col) = cursor.offset_to_line_col(start);
                let (end_line, end_col) =
                    if defer_container_end && opens_repositioned_node(&item.body) {
                        (0, 0)
                    } else {
                        cursor.offset_to_line_col(end)
                    };

                // If we're accumulating content for an HTML/code block, handle it.
                if let Some(buf) = html_block_buf.as_mut() {
                    match &item.body {
                        ItemBody::Text { .. } | ItemBody::Html | ItemBody::SoftBreak => {
                            let text = if matches!(item.body, ItemBody::SoftBreak) {
                                "\n"
                            } else {
                                &source[item.start..item.end]
                            };
                            buf.push_str(text);
                            inner.tree.next_sibling(cur_ix);
                            continue;
                        }
                        ItemBody::SynthesizeText(cow_ix) => {
                            // Tab-expansion leftover spaces have no raw-byte
                            // representation (e.g. inside `>\t<div>` the 2
                            // synthesized spaces are the part of the tab past
                            // the blockquote marker).
                            let cow = inner.allocs.take_cow(*cow_ix);
                            buf.push_str(&cow);
                            inner.tree.next_sibling(cur_ix);
                            continue;
                        }
                        _ => {}
                    }
                }

                if let Some(buf) = code_block_buf.as_mut() {
                    match &item.body {
                        ItemBody::Text { .. } => {
                            buf.push_str(&source[item.start..item.end]);
                            inner.tree.next_sibling(cur_ix);
                            continue;
                        }
                        ItemBody::SynthesizeText(cow_ix) => {
                            let cow = inner.allocs.take_cow(*cow_ix);
                            buf.push_str(&cow);
                            inner.tree.next_sibling(cur_ix);
                            continue;
                        }
                        _ => {}
                    }
                }

                // Inside an image: accumulate alt text but skip MDAST
                // node emission. Image is a void node in the MDAST spec.
                if let Some(buf) = image_alt_buf.as_mut() {
                    match &item.body {
                        ItemBody::Text { .. } => {
                            buf.push_str(&source[item.start..item.end]);
                        }
                        ItemBody::Code(cow_ix) => {
                            let cow = inner.allocs.take_cow(*cow_ix);
                            buf.push_str(&cow);
                        }
                        ItemBody::SoftBreak => {
                            // Alt text keeps the break rather than collapsing it
                            // to a space, and keeps the source's own line ending.
                            let s = &source[item.start..item.end];
                            match s.find(['\r', '\n']) {
                                Some(eol) => buf.push_str(&s[eol..]),
                                None => buf.push('\n'),
                            }
                        }
                        // A hard break carries no visible content, so it adds
                        // nothing to the alt text.
                        ItemBody::HardBreak(_) => {}
                        ItemBody::SynthesizeText(cow_ix) => {
                            let cow = inner.allocs.take_cow(*cow_ix);
                            buf.push_str(&cow);
                        }
                        ItemBody::SynthesizeChar(c) => {
                            buf.push(*c);
                        }
                        // mdx-js extends CommonMark's "alt = stripped visible
                        // content" rule by also concatenating the literal
                        // body of `{...}` expressions. e.g. `![{1+2}](u)` →
                        // alt = "1+2".
                        #[cfg(feature = "mdx")]
                        ItemBody::MdxTextExpression(cow_ix)
                        | ItemBody::MdxFlowExpression(cow_ix) => {
                            let cow = inner.allocs.take_cow(*cow_ix);
                            buf.push_str(&cow);
                        }
                        // Inline HTML appears verbatim in the alt text —
                        // remark preserves `![foo<div>bar](u)` → alt
                        // = `foo<div>bar`. This includes raw and
                        // normalized-wrap forms.
                        ItemBody::InlineHtml => {
                            buf.push_str(&source[item.start..item.end]);
                        }
                        ItemBody::OwnedInlineHtml(cow_ix) => {
                            let cow = inner.allocs.take_cow(*cow_ix);
                            buf.push_str(&cow);
                        }
                        ItemBody::Image(_) => {
                            image_depth += 1;
                            inner.tree.push();
                            continue;
                        }
                        _ => {
                            if inner.tree[cur_ix].child.is_some() {
                                image_depth += 1;
                                inner.tree.push();
                                continue;
                            }
                        }
                    }
                    // Leaf node: advance past it.
                    inner.tree.next_sibling(cur_ix);
                    continue;
                }

                // Map ItemBody to arena node.
                match item.body {
                    ItemBody::Paragraph | ItemBody::TightParagraph => {
                        builder.open_node(MdastNodeType::Paragraph as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        if mdx {
                            paragraph_open_depth.push(builder.stack_depth());
                        }
                        inner.tree.push();
                    }
                    ItemBody::DirectiveLabel => {
                        // A container directive label: a `paragraph` tagged with
                        // `directiveLabel`, whose inline children were tokenized
                        // by the normal inline pass.
                        builder.open_node(MdastNodeType::Paragraph as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        let para_id = builder.current_node_id();
                        builder
                            .arena_mut()
                            .set_node_data(para_id, b"{\"directiveLabel\":true}".to_vec());
                        if mdx {
                            paragraph_open_depth.push(builder.stack_depth());
                        }
                        inner.tree.push();
                    }
                    ItemBody::Heading(level, heading_ix) => {
                        let depth = heading_level_to_u8(level);
                        builder.open_node(MdastNodeType::Heading as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        builder.set_data_current(&[depth]);
                        // Conveyed as `data.hProperties`, which the mdast->hast
                        // pass emits as `id`/`class`/custom attributes.
                        if let Some(heading_ix) = heading_ix
                            && let Some(json) =
                                encode_heading_h_properties(&inner.allocs[heading_ix])
                        {
                            let heading_id = builder.current_node_id();
                            builder.arena_mut().set_node_data(heading_id, json);
                        }
                        inner.tree.push();
                    }
                    ItemBody::BlockQuote(_) => {
                        builder.open_node(MdastNodeType::Blockquote as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        if mdx {
                            container_jsx_snapshot
                                .push((MdastNodeType::Blockquote, jsx_stack.len()));
                        }
                        inner.tree.push();
                    }
                    ItemBody::MathBlock(_) => {
                        builder.open_node(MdastNodeType::Math as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        code_block_buf = Some(String::with_capacity(256));
                        inner.tree.push();
                    }
                    ItemBody::FencedCodeBlock(info_ix) => {
                        let (info_cow, lang_len) = inner.allocs.take_fenced_info(info_ix);
                        let info_str = info_cow.as_ref();
                        // The boundary was taken on raw source; whitespace a
                        // character reference decodes to stays in the language.
                        let split = (lang_len as usize).min(info_str.len());
                        let (lang_str, meta_str) = info_str.split_at(split);
                        let meta_str = meta_str.trim_start();
                        let lang_ref = if lang_str.is_empty() {
                            StringRef::empty()
                        } else {
                            builder.alloc_string(lang_str)
                        };
                        let meta_ref = if meta_str.is_empty() {
                            StringRef::empty()
                        } else {
                            builder.alloc_string(meta_str)
                        };
                        builder.open_node(MdastNodeType::Code as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        let cd = CodeData {
                            lang: lang_ref,
                            meta: meta_ref,
                            value: StringRef::empty(),
                            fence_char: b'`',
                            _pad: [0; 3],
                        };
                        builder.set_data_current(&cd.to_bytes());
                        code_block_buf = Some(String::with_capacity(256));
                        inner.tree.push();
                    }
                    ItemBody::IndentCodeBlock(_) => {
                        builder.open_node(MdastNodeType::Code as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        let cd = CodeData {
                            lang: StringRef::empty(),
                            meta: StringRef::empty(),
                            value: StringRef::empty(),
                            fence_char: b' ',
                            _pad: [0; 3],
                        };
                        builder.set_data_current(&cd.to_bytes());
                        code_block_buf = Some(String::with_capacity(256));
                        inner.tree.push();
                    }
                    ItemBody::List(_is_tight, c, listitem_start) => {
                        let ordered = c == b'.' || c == b')';
                        let start_num = if ordered { listitem_start } else { 0 };
                        builder.open_node(MdastNodeType::List as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        let ld = ListData {
                            start: start_num,
                            ordered,
                            spread: false,
                            _pad: [0; 2],
                        };
                        builder.set_data_current(&ld.to_bytes());
                        inner.tree.push();
                    }
                    ItemBody::ListItem(_, spread) => {
                        builder.open_node(MdastNodeType::ListItem as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        builder.set_data_current(&ListItemData { checked: 2, spread }.to_bytes());
                        if mdx {
                            container_jsx_snapshot.push((MdastNodeType::ListItem, jsx_stack.len()));
                        }
                        inner.tree.push();
                    }
                    ItemBody::Table(align_ix) => {
                        let alignments = inner.allocs.take_alignment(align_ix);
                        let aligns: Vec<ColumnAlign> = alignments
                            .iter()
                            .map(|a| match a {
                                Alignment::None => ColumnAlign::None,
                                Alignment::Left => ColumnAlign::Left,
                                Alignment::Center => ColumnAlign::Center,
                                Alignment::Right => ColumnAlign::Right,
                            })
                            .collect();
                        builder.open_node(MdastNodeType::Table as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        builder.set_data_current(&encode_table_data(&aligns));
                        inner.tree.push();
                    }
                    ItemBody::TableHead | ItemBody::TableRow => {
                        builder.open_node(MdastNodeType::TableRow as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        inner.tree.push();
                    }
                    ItemBody::TableCell => {
                        builder.open_node(MdastNodeType::TableCell as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        inner.tree.push();
                    }
                    ItemBody::Emphasis => {
                        builder.open_node(MdastNodeType::Emphasis as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        inner.tree.push();
                    }
                    ItemBody::Strong => {
                        builder.open_node(MdastNodeType::Strong as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        inner.tree.push();
                    }
                    ItemBody::Strikethrough => {
                        builder.open_node(MdastNodeType::Delete as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        inner.tree.push();
                    }
                    ItemBody::Link(link_ix) => {
                        let (link_type, dest_url, title, id) = inner.allocs.take_link(link_ix);
                        if let Some(kind) = reference_kind(link_type) {
                            let (ref_end, ref_end_line, ref_end_col) =
                                reference_end(source, &mut cursor, end, kind);
                            let label_src =
                                extract_reference_label(source, start, ref_end, kind, false);
                            let label_ref = match unescape_label_backslashes(label_src) {
                                Some(unescaped) => builder.alloc_string(&unescaped),
                                None => builder.alloc_string(label_src),
                            };
                            let identifier_ref = builder.alloc_string(&normalize_identifier(&id));
                            builder.open_node(MdastNodeType::LinkReference as u8);
                            builder.set_position_current(
                                start,
                                ref_end,
                                start_line,
                                start_col,
                                ref_end_line,
                                ref_end_col,
                            );
                            builder.set_data_current(&encode_reference_data(
                                identifier_ref,
                                label_ref,
                                kind,
                            ));
                            // The generic container-close path reads
                            // `item.end` and overrides the position we just
                            // set. For Collapsed references we need the span
                            // to cover the trailing `[]`, so sync the tree
                            // node's end up front.
                            inner.tree[cur_ix].item.end = ref_end as usize;
                        } else {
                            let url_ref = if matches!(link_type, LinkType::Email) {
                                let mailto = format!("mailto:{}", &*dest_url);
                                builder.alloc_string(&mailto)
                            } else {
                                builder.alloc_string(&dest_url)
                            };
                            let title_ref = if title.is_empty() {
                                StringRef::empty()
                            } else {
                                builder.alloc_string(&title)
                            };
                            builder.open_node(MdastNodeType::Link as u8);
                            builder.set_position_current(
                                start, end, start_line, start_col, end_line, end_col,
                            );
                            builder.set_data_current(
                                &LinkData {
                                    url: url_ref,
                                    title: title_ref,
                                }
                                .to_bytes(),
                            );
                        }
                        inner.tree.push();
                    }
                    ItemBody::Image(link_ix) => {
                        let (link_type, dest_url, title, id) = inner.allocs.take_link(link_ix);
                        if let Some(kind) = reference_kind(link_type) {
                            let (ref_end, ref_end_line, ref_end_col) =
                                reference_end(source, &mut cursor, end, kind);
                            let label_src =
                                extract_reference_label(source, start, ref_end, kind, true);
                            let label_ref = match unescape_label_backslashes(label_src) {
                                Some(unescaped) => builder.alloc_string(&unescaped),
                                None => builder.alloc_string(label_src),
                            };
                            let identifier_ref = builder.alloc_string(&normalize_identifier(&id));
                            builder.open_node(MdastNodeType::ImageReference as u8);
                            builder.set_position_current(
                                start,
                                ref_end,
                                start_line,
                                start_col,
                                ref_end_line,
                                ref_end_col,
                            );
                            builder.set_data_current(&encode_image_reference_data(
                                identifier_ref,
                                label_ref,
                                kind,
                                StringRef::empty(),
                            ));
                            // Same fix as LinkReference: the generic close
                            // path reads `item.end`, which ignores the
                            // trailing `[]` for Collapsed refs. Sync it.
                            inner.tree[cur_ix].item.end = ref_end as usize;
                        } else {
                            let url_ref = builder.alloc_string(&dest_url);
                            let title_ref = if title.is_empty() {
                                StringRef::empty()
                            } else {
                                builder.alloc_string(&title)
                            };
                            let alt_ref = StringRef::empty();
                            builder.open_node(MdastNodeType::Image as u8);
                            builder.set_position_current(
                                start, end, start_line, start_col, end_line, end_col,
                            );
                            builder.set_data_current(
                                &ImageData {
                                    url: url_ref,
                                    alt: alt_ref,
                                    title: title_ref,
                                }
                                .to_bytes(),
                            );
                        }
                        if image_alt_buf.is_none() {
                            image_alt_buf = Some(String::with_capacity(64));
                        }
                        inner.tree.push();
                    }
                    ItemBody::FootnoteDefinition(cow_ix) => {
                        let label_cow = inner.allocs.take_cow(cow_ix);
                        // `identifier` is the normalized form (case-folded,
                        // whitespace-collapsed); `label` is the human-
                        // readable form with backslash escapes resolved.
                        // Mirrors mdast-util-from-markdown's
                        // footnoteDefinition handler (and our Definition
                        // emission in `emit_pending_refdef`).
                        let id_sr = builder.alloc_string(&normalize_identifier(&label_cow));
                        let label_sr = match unescape_label_backslashes(&label_cow) {
                            Some(unescaped) => builder.alloc_string(&unescaped),
                            None => builder.alloc_string(&label_cow),
                        };
                        builder.open_node(MdastNodeType::FootnoteDefinition as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        builder.set_data_current(
                            &FootnoteDefinitionData {
                                identifier: id_sr,
                                label: label_sr,
                            }
                            .to_bytes(),
                        );
                        inner.tree.push();
                    }
                    ItemBody::HtmlBlock(_) => {
                        builder.open_node(MdastNodeType::Html as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        html_block_buf = Some(String::with_capacity(128));
                        inner.tree.push();
                    }
                    ItemBody::MetadataBlock(kind) => {
                        let node_type = match kind {
                            crate::MetadataBlockKind::YamlStyle => MdastNodeType::Yaml,
                            crate::MetadataBlockKind::PlusesStyle => MdastNodeType::Toml,
                        };
                        builder.open_node(node_type as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        html_block_buf = Some(String::with_capacity(128));
                        inner.tree.push();
                    }
                    // MDX JSX elements.
                    #[cfg(feature = "mdx")]
                    ItemBody::MdxJsxFlowElement(jsx_ix) | ItemBody::MdxJsxTextElement(jsx_ix) => {
                        let is_flow = matches!(item.body, ItemBody::MdxJsxFlowElement(_));
                        let jsx = inner.allocs.take_jsx_element(jsx_ix);

                        if jsx.is_closing {
                            let close_name = jsx.name.as_ref();
                            if let Some((open_name, open_offset, open_is_flow)) = jsx_stack.pop() {
                                if close_name != open_name {
                                    let open_loc =
                                        byte_offset_to_line_col(source, open_offset as usize);
                                    mdx_errors.push((
                                        start as usize,
                                        format!(
                                            "Unexpected closing tag `</{close_name}>`, expected \
                                             corresponding closing tag for `<{open_name}>` ({open_loc})"
                                        ),
                                    ));
                                } else if open_is_flow != is_flow {
                                    // mdx-js: a flow-mode open (`<Foo>` alone on its
                                    // line) cannot be closed by an inline close
                                    // (`</Foo>` followed by content on its line)
                                    // and vice versa. The mismatch indicates the
                                    // open's block context didn't actually close
                                    // structurally.
                                    let open_loc =
                                        byte_offset_to_line_col(source, open_offset as usize);
                                    mdx_errors.push((
                                        start as usize,
                                        format!(
                                            "Expected the closing tag `</{close_name}>` either after \
                                             the end of `paragraph` or another opening tag after the \
                                             start of `paragraph` (`<{open_name}>` opened at {open_loc})"
                                        ),
                                    ));
                                }
                                let id = builder.current_node_id();
                                let node = builder.arena_ref().get_node(id);
                                let orig_start = node.start_offset;
                                let orig_start_line = node.start_line;
                                let orig_start_col = node.start_column;
                                builder.set_position_current(
                                    orig_start,
                                    end,
                                    orig_start_line,
                                    orig_start_col,
                                    end_line,
                                    end_col,
                                );
                                builder.close_node();
                            } else {
                                mdx_errors.push((
                                    start as usize,
                                    format!("Unexpected closing tag `</{close_name}>`, expected an open tag first"),
                                ));
                            }
                        } else {
                            let node_type = if is_flow {
                                MdastNodeType::MdxJsxFlowElement
                            } else {
                                MdastNodeType::MdxJsxTextElement
                            };
                            let data = encode_jsx_element_data(&jsx, &mut builder);
                            builder.open_node(node_type as u8);
                            builder.set_position_current(
                                start, end, start_line, start_col, end_line, end_col,
                            );
                            builder.set_data_current(&data);
                            let id = builder.current_node_id();
                            builder
                                .arena_mut()
                                .set_node_data(id, MDX_EXPLICIT_JSX_DATA.to_vec());
                            if jsx.is_self_closing {
                                builder.close_node();
                            } else {
                                jsx_stack.push((jsx.name.to_string(), start, is_flow));
                            }
                        }
                        inner.tree.next_sibling(cur_ix);
                        continue;
                    }

                    ItemBody::DefinitionList(_) => {
                        builder.open_node(MdastNodeType::DescriptionList as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        inner.tree.push();
                    }
                    ItemBody::DefinitionListTitle => {
                        builder.open_node(MdastNodeType::DescriptionTerm as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        inner.tree.push();
                    }
                    ItemBody::DefinitionListDefinition(_, loose) => {
                        builder.open_node(MdastNodeType::DescriptionDetails as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        // `loose` is per-dd (firstpass sets it when a blank line
                        // precedes this definition's `:` marker).
                        builder
                            .set_data_current(&DescriptionDetailsData { spread: loose }.to_bytes());
                        inner.tree.push();
                    }
                    ItemBody::Superscript => {
                        builder.open_node(MdastNodeType::Superscript as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        inner.tree.push();
                    }
                    ItemBody::Subscript => {
                        builder.open_node(MdastNodeType::Subscript as u8);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        inner.tree.push();
                    }
                    ItemBody::ContainerDirective(_, dir_ix) => {
                        let dir = inner.allocs.directive_ref(dir_ix);
                        let name_sr = builder.alloc_string(&dir.name);
                        let attr_pairs: Vec<(StringRef, StringRef)> = dir
                            .attributes
                            .iter()
                            .map(|(k, v)| (builder.alloc_string(k), builder.alloc_string(v)))
                            .collect();
                        let type_data = encode_directive_data(name_sr, &attr_pairs);
                        builder.open_node(MdastNodeType::ContainerDirective as u8);
                        builder.set_data_current(&type_data);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        // The `[label]`, when present, is a `DirectiveLabel`
                        // child in the first-pass tree (emitted as a tagged
                        // paragraph), so nothing to synthesize here.
                        inner.tree.push();
                    }
                    ItemBody::LeafDirective(dir_ix) => {
                        let dir = inner.allocs.directive_ref(dir_ix);
                        let name_sr = builder.alloc_string(&dir.name);
                        let attr_pairs: Vec<(StringRef, StringRef)> = dir
                            .attributes
                            .iter()
                            .map(|(k, v)| (builder.alloc_string(k), builder.alloc_string(v)))
                            .collect();
                        let type_data = encode_directive_data(name_sr, &attr_pairs);
                        builder.open_node(MdastNodeType::LeafDirective as u8);
                        builder.set_data_current(&type_data);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        // The label is the directive's inline children in the
                        // first-pass tree; descend so the walk emits them.
                        inner.tree.push();
                    }

                    ItemBody::TextDirective(dir_ix) => {
                        let dir = inner.allocs.directive_ref(dir_ix);
                        let name_sr = builder.alloc_string(&dir.name);
                        let attr_pairs: Vec<(StringRef, StringRef)> = dir
                            .attributes
                            .iter()
                            .map(|(k, v)| (builder.alloc_string(k), builder.alloc_string(v)))
                            .collect();
                        let type_data = encode_directive_data(name_sr, &attr_pairs);
                        builder.open_node(MdastNodeType::TextDirective as u8);
                        builder.set_data_current(&type_data);
                        builder.set_position_current(
                            start, end, start_line, start_col, end_line, end_col,
                        );
                        inner.tree.push();
                    }

                    // A blocked autolink marker leaves a zero-width `Text`. The
                    // escaped form is not empty: it reaches back over the `\`.
                    ItemBody::Text {
                        backslash_escaped: false,
                    } if item.start == item.end => {
                        inner.tree.next_sibling(cur_ix);
                    }

                    ItemBody::Text { backslash_escaped } => {
                        let text_value: &str = &source[item.start..item.end];

                        // Merge with previous sibling text node when
                        // adjacent or separated by a gap (backslash escape).
                        let prev_id = builder.last_sibling_id();
                        let merged = if let Some(pid) = prev_id {
                            let prev = builder.arena_ref().get_node(pid);
                            if prev.node_type == MdastNodeType::Text as u8 {
                                let prev_data = builder.arena_ref().get_type_data(pid);
                                if prev_data.len() >= 8 {
                                    let prev_sr = StringRef::from_bytes(prev_data);
                                    let new_sr =
                                        builder.arena_mut().append_string(prev_sr, text_value);
                                    let pn = builder.arena_ref().get_node(pid);
                                    builder.update_leaf_full(
                                        pid,
                                        pn.start_offset,
                                        end,
                                        pn.start_line,
                                        pn.start_column,
                                        end_line,
                                        end_col,
                                        &new_sr.as_bytes(),
                                    );
                                    true
                                } else {
                                    false
                                }
                            } else {
                                false
                            }
                        } else {
                            false
                        };
                        if !merged {
                            let (sr, pos_start, pos_start_col) = if backslash_escaped && start > 0 {
                                (
                                    builder.alloc_string(text_value),
                                    start - 1,
                                    start_col.saturating_sub(1),
                                )
                            } else {
                                (StringRef::new(start, end - start), start, start_col)
                            };
                            let pos_start_line = if backslash_escaped && start > 0 {
                                cursor.offset_to_line_col(start - 1).0
                            } else {
                                start_line
                            };
                            builder.add_leaf_full(
                                MdastNodeType::Text as u8,
                                pos_start,
                                end,
                                pos_start_line,
                                pos_start_col,
                                end_line,
                                end_col,
                                &sr.as_bytes(),
                            );
                        }
                        inner.tree.next_sibling(cur_ix);
                    }
                    ItemBody::Code(cow_ix) => {
                        let cow = inner.allocs.take_cow(cow_ix);
                        let sr = builder.alloc_string(&cow);
                        builder.add_leaf_full(
                            MdastNodeType::InlineCode as u8,
                            start,
                            end,
                            start_line,
                            start_col,
                            end_line,
                            end_col,
                            &sr.as_bytes(),
                        );
                        inner.tree.next_sibling(cur_ix);
                    }
                    ItemBody::SynthesizeText(cow_ix) => {
                        let cow = inner.allocs.take_cow(cow_ix);
                        crate::post_passes::emit_text_merging(
                            &mut builder,
                            &cow,
                            start,
                            end,
                            start_line,
                            start_col,
                            end_line,
                            end_col,
                        );
                        inner.tree.next_sibling(cur_ix);
                    }
                    ItemBody::SynthesizeChar(c) => {
                        let s = String::from(c);
                        crate::post_passes::emit_text_merging(
                            &mut builder,
                            &s,
                            start,
                            end,
                            start_line,
                            start_col,
                            end_line,
                            end_col,
                        );
                        inner.tree.next_sibling(cur_ix);
                    }
                    ItemBody::Html => {
                        let sr = StringRef::new(start, end - start);
                        builder.add_leaf_full(
                            MdastNodeType::Html as u8,
                            start,
                            end,
                            start_line,
                            start_col,
                            end_line,
                            end_col,
                            &sr.as_bytes(),
                        );
                        inner.tree.next_sibling(cur_ix);
                    }
                    ItemBody::InlineHtml => {
                        let slice = &source[start as usize..end as usize];
                        let sr = match normalize_inline_html_wrap(slice) {
                            Some(normalized) => builder.alloc_string(&normalized),
                            None => StringRef::new(start, end - start),
                        };
                        builder.add_leaf_full(
                            MdastNodeType::Html as u8,
                            start,
                            end,
                            start_line,
                            start_col,
                            end_line,
                            end_col,
                            &sr.as_bytes(),
                        );
                        inner.tree.next_sibling(cur_ix);
                    }
                    ItemBody::OwnedInlineHtml(cow_ix) => {
                        let cow = inner.allocs.take_cow(cow_ix);
                        let sr = builder.alloc_string(&cow);
                        builder.add_leaf_full(
                            MdastNodeType::Html as u8,
                            start,
                            end,
                            start_line,
                            start_col,
                            end_line,
                            end_col,
                            &sr.as_bytes(),
                        );
                        inner.tree.next_sibling(cur_ix);
                    }
                    ItemBody::SoftBreak => {
                        let src_bytes = source.as_bytes();
                        let break_text = {
                            let span = &src_bytes[item.start..item.end];
                            let has_cr = span.contains(&b'\r');
                            let has_lf = span.contains(&b'\n');
                            if has_cr && has_lf {
                                "\r\n"
                            } else if has_cr {
                                "\r"
                            } else {
                                "\n"
                            }
                        };
                        let prev_id = builder.last_sibling_id();
                        let merged = if let Some(pid) = prev_id {
                            let prev = builder.arena_ref().get_node(pid);
                            if prev.node_type == MdastNodeType::Text as u8 {
                                let prev_data = builder.arena_ref().get_type_data(pid);
                                if prev_data.len() >= 8 {
                                    let prev_sr = StringRef::from_bytes(prev_data);
                                    let new_sr =
                                        builder.arena_mut().append_string(prev_sr, break_text);
                                    let pn = builder.arena_ref().get_node(pid);
                                    builder.update_leaf_full(
                                        pid,
                                        pn.start_offset,
                                        end,
                                        pn.start_line,
                                        pn.start_column,
                                        end_line,
                                        end_col,
                                        &new_sr.as_bytes(),
                                    );
                                    true
                                } else {
                                    false
                                }
                            } else {
                                false
                            }
                        } else {
                            false
                        };
                        if !merged {
                            let sr = builder.alloc_string(break_text);
                            builder.add_leaf_full(
                                MdastNodeType::Text as u8,
                                start,
                                end,
                                start_line,
                                start_col,
                                end_line,
                                end_col,
                                &sr.as_bytes(),
                            );
                        }
                        inner.tree.next_sibling(cur_ix);
                    }
                    ItemBody::HardBreak(_) => {
                        builder.add_leaf_full(
                            MdastNodeType::Break as u8,
                            start,
                            end,
                            start_line,
                            start_col,
                            end_line,
                            end_col,
                            &[],
                        );
                        inner.tree.next_sibling(cur_ix);
                    }
                    ItemBody::Rule => {
                        let mut rule_end = end;
                        let src = source.as_bytes();
                        while rule_end > start
                            && matches!(src.get(rule_end as usize - 1), Some(b'\n' | b'\r'))
                        {
                            rule_end -= 1;
                        }
                        let (rule_end_line, rule_end_col) = cursor.offset_to_line_col(rule_end);
                        builder.add_leaf_full(
                            MdastNodeType::ThematicBreak as u8,
                            start,
                            rule_end,
                            start_line,
                            start_col,
                            rule_end_line,
                            rule_end_col,
                            &[],
                        );
                        inner.tree.next_sibling(cur_ix);
                    }
                    ItemBody::TaskListMarker(checked) => {
                        let checked_val = if checked { 1 } else { 0 };
                        let depth = builder.stack_depth();
                        for i in (0..depth).rev() {
                            if let Some(node_id) = builder.stack_node_id(i)
                                && builder.arena_ref().get_node(node_id).node_type
                                    == MdastNodeType::ListItem as u8
                            {
                                let data = builder.arena_mut().get_type_data_mut(node_id);
                                if data.len() >= 2 {
                                    data[0] = checked_val;
                                } else {
                                    let fresh = ListItemData {
                                        checked: checked_val,
                                        spread: false,
                                    }
                                    .to_bytes();
                                    builder.arena_mut().set_type_data(node_id, &fresh);
                                }
                                break;
                            }
                        }
                        inner.tree.next_sibling(cur_ix);
                    }
                    ItemBody::FootnoteReference(cow_ix) => {
                        let cow = inner.allocs.take_cow(cow_ix);
                        // Identifier is normalized (case-folded + whitespace-
                        // collapsed); label keeps the raw source form. Same
                        // pattern as FootnoteDefinition.
                        let id_sr = builder.alloc_string(&normalize_identifier(&cow));
                        let label_sr = builder.alloc_string(&cow);
                        let data = ReferenceData {
                            identifier: id_sr,
                            label: label_sr,
                            reference_kind: 0,
                            _pad: [0; 3],
                        }
                        .to_bytes();
                        builder.add_leaf_full(
                            MdastNodeType::FootnoteReference as u8,
                            start,
                            end,
                            start_line,
                            start_col,
                            end_line,
                            end_col,
                            &data,
                        );
                        inner.tree.next_sibling(cur_ix);
                    }
                    ItemBody::Math(cow_ix, is_display) => {
                        let cow = inner.allocs.take_cow(cow_ix);
                        let sr = builder.alloc_string(&cow);
                        let node_type = if is_display {
                            MdastNodeType::Math
                        } else {
                            MdastNodeType::InlineMath
                        };
                        builder.add_leaf_full(
                            node_type as u8,
                            start,
                            end,
                            start_line,
                            start_col,
                            end_line,
                            end_col,
                            &MathData {
                                meta: StringRef::empty(),
                                value: sr,
                            }
                            .to_bytes(),
                        );
                        inner.tree.next_sibling(cur_ix);
                    }
                    #[cfg(feature = "mdx")]
                    ItemBody::MdxFlowExpression(cow_ix) => {
                        let cow = inner.allocs.take_cow(cow_ix);
                        let sr = builder.alloc_string(&cow);
                        builder.add_leaf_full(
                            MdastNodeType::MdxFlowExpression as u8,
                            start,
                            end,
                            start_line,
                            start_col,
                            end_line,
                            end_col,
                            &ExpressionData { value: sr }.to_bytes(),
                        );
                        inner.tree.next_sibling(cur_ix);
                    }
                    #[cfg(feature = "mdx")]
                    ItemBody::MdxTextExpression(cow_ix) => {
                        let cow = inner.allocs.take_cow(cow_ix);
                        let sr = builder.alloc_string(&cow);
                        builder.add_leaf_full(
                            MdastNodeType::MdxTextExpression as u8,
                            start,
                            end,
                            start_line,
                            start_col,
                            end_line,
                            end_col,
                            &ExpressionData { value: sr }.to_bytes(),
                        );
                        inner.tree.next_sibling(cur_ix);
                    }
                    #[cfg(feature = "mdx")]
                    ItemBody::MdxEsm(cow_ix) => {
                        let cow = inner.allocs.take_cow(cow_ix);
                        let sr = builder.alloc_string(&cow);
                        builder.add_leaf_full(
                            MdastNodeType::MdxjsEsm as u8,
                            start,
                            end,
                            start_line,
                            start_col,
                            end_line,
                            end_col,
                            &ExpressionData { value: sr }.to_bytes(),
                        );
                        inner.tree.next_sibling(cur_ix);
                    }

                    // Unresolved inline markers, should have been resolved by handle_inline.
                    ItemBody::MaybeEmphasis(..)
                    | ItemBody::MaybeEmphasisEscaped(..)
                    | ItemBody::MaybeMath(..)
                    | ItemBody::MaybeSmartQuote(..)
                    | ItemBody::MaybeCode(..)
                    | ItemBody::MaybeHtml(..)
                    | ItemBody::MaybeLinkOpen
                    | ItemBody::MaybeLinkClose(..)
                    | ItemBody::MaybeImage => {
                        let text_value: &str = &source[item.start..item.end];
                        let prev_id = builder.last_sibling_id();
                        let merged = if let Some(pid) = prev_id {
                            let prev = builder.arena_ref().get_node(pid);
                            if prev.node_type == MdastNodeType::Text as u8 {
                                let prev_data = builder.arena_ref().get_type_data(pid);
                                if prev_data.len() >= 8 {
                                    let prev_sr = StringRef::from_bytes(prev_data);
                                    let new_sr =
                                        builder.arena_mut().append_string(prev_sr, text_value);
                                    let pn = builder.arena_ref().get_node(pid);
                                    builder.update_leaf_full(
                                        pid,
                                        pn.start_offset,
                                        end,
                                        pn.start_line,
                                        pn.start_column,
                                        end_line,
                                        end_col,
                                        &new_sr.as_bytes(),
                                    );
                                    true
                                } else {
                                    false
                                }
                            } else {
                                false
                            }
                        } else {
                            false
                        };
                        if !merged {
                            let sr = StringRef::new(start, end - start);
                            builder.add_leaf_full(
                                MdastNodeType::Text as u8,
                                start,
                                end,
                                start_line,
                                start_col,
                                end_line,
                                end_col,
                                &sr.as_bytes(),
                            );
                        }
                        inner.tree.next_sibling(cur_ix);
                    }

                    // `handle_inline_pass1` fires or unlinks every marker, and a
                    // consumed item range drops the markers inside it.
                    ItemBody::MaybeAutolink(..) => {
                        debug_assert!(false, "unresolved autolink marker reached arena_build");
                        inner.tree.next_sibling(cur_ix);
                    }

                    // Skip these silently.
                    ItemBody::Root => {
                        inner.tree.push();
                    }

                    // Catch-all for anything unexpected.
                    _ => {
                        inner.tree.next_sibling(cur_ix);
                    }
                }
            }
        }
    }

    // Check for unclosed JSX tags.
    for (name, offset, _is_flow) in &jsx_stack {
        let loc = byte_offset_to_line_col(source, *offset as usize);
        mdx_errors.push((
            *offset as usize,
            format!("Expected a closing tag for `<{name}>` ({loc})"),
        ));
    }

    // Merge parser-level MDX errors.
    if !inner.mdx_errors.is_empty() {
        mdx_errors.extend_from_slice(&inner.mdx_errors);
        mdx_errors.sort_by_key(|(offset, _)| *offset);
    }

    // Root-level refdefs: anything not already emitted inside a container.
    // Interleaved with the other root children in source order.
    let mut emitted_any_at_root = false;
    for (i, (label, def)) in refdefs_owned.iter().enumerate() {
        if refdef_emitted[i] {
            continue;
        }
        emit_pending_refdef(&mut builder, &mut cursor, source, label, def);
        emitted_any_at_root = true;
    }
    if emitted_any_at_root {
        builder.sort_current_pending_children_by_source_order();
    }

    // Close root.
    builder.close_node();
    let mut arena = builder.finish();
    arena.parse_options = options.bits();

    // Source-level early exits: post-passes scan the arena to find
    // candidate nodes, but if the construct's trigger char(s) don't
    // appear in the source at all, no candidate can exist. The memchr
    // probes are conservative supersets (e.g. `@` matches both emails
    // and unrelated literal text); the actual passes still validate.
    let source_bytes = source.as_bytes();

    #[cfg(feature = "mdx")]
    if options.contains(Options::ENABLE_MDX) && memchr::memchr2(b'<', b'{', source_bytes).is_some()
    {
        crate::post_passes::mdx_mark_and_unravel(&mut arena);
    }

    // GFM extension: promote bare URLs (http://…, https://…, www.…) inside
    // Text nodes to `link` nodes. Matches remark-gfm / mdast-util-gfm-autolink-literal.
    if options.contains(Options::ENABLE_GFM) {
        // When directives are also on, a URL with a port (`http://host:4321`)
        // gets split by the directive parser into
        // `text("…http://host") + textDirective("4321") + text("/…")`.
        // remark handles this cleanly because its autolink tokenizer runs
        // before the directive check; we're a post-pass, so we re-merge the
        // split first and then run the autolink scan.
        if options.contains(Options::ENABLE_DIRECTIVE)
            && memchr::memmem::find(source_bytes, b"://").is_some()
        {
            crate::post_passes::merge_directive_port_splits(&mut arena);
        }
        if !skip_fnr_autolink && crate::post_passes::gfm_autolink_literal_may_apply(source_bytes) {
            crate::post_passes::gfm_autolink_literal_pass(
                &mut arena,
                source_bytes,
                options,
                track_positions.then_some(&mut cursor),
            );
        }
    }

    // Precompute per-node UTF-16 offsets so `to_raw_buffer` skips a
    // second `LineIndex` build + per-node `byte_to_utf16_offset` lookup.
    // ASCII sources skip: UTF-16 offsets equal byte offsets and downstream
    // serializers won't touch the cache. The cursor is already warm from the
    // arena walk.
    // Skip-positions mode skips too: downstream paths don't read utf16_offsets.
    if track_positions && !source.is_ascii() {
        let mut utf16_offsets = Vec::with_capacity(arena.nodes.len());
        for node in &arena.nodes {
            let pair = if node.start_line == 0 && node.start_offset == 0 {
                (0u32, 0u32)
            } else {
                (
                    line_index.utf16_offset_at(node.start_line, node.start_column),
                    line_index.utf16_offset_at(node.end_line, node.end_column),
                )
            };
            utf16_offsets.push(pair);
        }
        arena.utf16_offsets = utf16_offsets;
    }

    (arena, mdx_errors)
}

/// Nodes the walk opens and descends into: the tree pop rewrites their end, so an open-time end line/column is dead.
fn opens_repositioned_node(body: &ItemBody) -> bool {
    use ItemBody::*;
    matches!(
        body,
        Paragraph
            | TightParagraph
            | DirectiveLabel
            | Heading(..)
            | BlockQuote(_)
            | MathBlock(_)
            | FencedCodeBlock(_)
            | IndentCodeBlock(_)
            | List(..)
            | ListItem(..)
            | Table(_)
            | TableHead
            | TableRow
            | TableCell
            | Emphasis
            | Strong
            | Strikethrough
            | Superscript
            | Subscript
            | Link(_)
            | Image(_)
            | FootnoteDefinition(_)
            | HtmlBlock(_)
            | MetadataBlock(_)
            | DefinitionList(_)
            | DefinitionListTitle
            | DefinitionListDefinition(..)
            | ContainerDirective(..)
            | LeafDirective(_)
            | TextDirective(_)
    )
}

fn emit_pending_refdef(
    builder: &mut ArenaBuilder<Mdast>,
    cursor: &mut satteri_arena::LineIndexCursor<'_, '_>,
    source: &str,
    label: &LinkLabel<'_>,
    def: &LinkDef<'_>,
) {
    let start = def.span.start as u32;
    let end = def.span.end as u32;
    let (sl, sc) = cursor.offset_to_line_col(start);
    let (el, ec) = cursor.offset_to_line_col(end);
    let url_ref = builder.alloc_string(def.dest.as_ref());
    let title_ref = match &def.title {
        Some(t) => builder.alloc_string(t.as_ref()),
        None => StringRef::empty(),
    };
    let label_str: &str = label.as_ref();
    let raw_label = extract_definition_label(source, start).unwrap_or(label_str);
    // remark decodes HTML entities AND backslash escapes in the refdef label.
    // `&amp;` → `&`, `&AElig;` → `Æ`, etc. Invalid entities pass through.
    let unescaped = crate::scanners::unescape(raw_label, false);
    let label_ref = if unescaped.as_ref() == raw_label {
        builder.alloc_string(raw_label)
    } else {
        builder.alloc_string(&unescaped)
    };
    let identifier_ref = builder.alloc_string(&normalize_identifier(label_str));
    let data = DefinitionData {
        url: url_ref,
        title: title_ref,
        identifier: identifier_ref,
        label: label_ref,
    }
    .to_bytes();
    builder.add_leaf_full(
        MdastNodeType::Definition as u8,
        start,
        end,
        sl,
        sc,
        el,
        ec,
        &data,
    );
}

/// Emit any not-yet-emitted refdefs whose source range falls inside the
/// container span `[container_start, container_end)`. Returns true if at
/// least one was emitted, so the caller knows it should re-sort the
/// container's pending children to keep source order.
#[allow(clippy::too_many_arguments)]
fn emit_refdefs_in_container(
    builder: &mut ArenaBuilder<Mdast>,
    cursor: &mut satteri_arena::LineIndexCursor<'_, '_>,
    source: &str,
    refdefs: &[(LinkLabel<'_>, LinkDef<'_>)],
    starts: &[usize],
    emitted: &mut [bool],
    container_start: usize,
    container_end: usize,
) -> bool {
    let mut any = false;
    // `starts` is sorted, so the container's refdefs are one slice.
    let lo = starts.partition_point(|&s| s < container_start);
    let hi = starts.partition_point(|&s| s < container_end);
    for i in lo..hi {
        if emitted[i] {
            continue;
        }
        let (label, def) = &refdefs[i];
        emit_pending_refdef(builder, cursor, source, label, def);
        emitted[i] = true;
        any = true;
    }
    any
}

/// Cheap reject before the claim scan: most containers close nowhere near a refdef.
fn container_may_hold_refdef(
    starts: &[usize],
    container_start: usize,
    container_end: usize,
) -> bool {
    match (starts.first(), starts.last()) {
        (Some(&lo), Some(&hi)) => container_end > lo && container_start <= hi,
        _ => false,
    }
}

/// Normalize wrapped-line leading whitespace inside an inline HTML span:
/// micromark drops up to 3 columns of indent at the start of each continuation
/// line (tabs counted as 4-column stops, with any overflow re-emitted as
/// spaces). Returns `None` when the slice has no continuation line that would
/// change.
fn normalize_inline_html_wrap(src: &str) -> Option<String> {
    let bytes = src.as_bytes();
    let first_nl = bytes.iter().position(|&b| b == b'\n' || b == b'\r')?;
    let mut out = String::with_capacity(src.len());
    out.push_str(&src[..first_nl]);
    let mut i = first_nl;
    while i < bytes.len() {
        if bytes[i] == b'\r' {
            out.push('\r');
            i += 1;
            if i < bytes.len() && bytes[i] == b'\n' {
                out.push('\n');
                i += 1;
            }
        } else if bytes[i] == b'\n' {
            out.push('\n');
            i += 1;
        }
        let mut col = 0usize;
        while col < 3 && i < bytes.len() {
            match bytes[i] {
                b' ' => {
                    col += 1;
                    i += 1;
                }
                b'\t' => {
                    let tab_cols = 4 - (col % 4);
                    if col + tab_cols <= 3 {
                        col += tab_cols;
                        i += 1;
                    } else {
                        let leftover = col + tab_cols - 3;
                        for _ in 0..leftover {
                            out.push(' ');
                        }
                        i += 1;
                        col = 3;
                    }
                }
                _ => break,
            }
        }
        let line_start = i;
        while i < bytes.len() && bytes[i] != b'\n' && bytes[i] != b'\r' {
            i += 1;
        }
        out.push_str(&src[line_start..i]);
    }
    if out == src { None } else { Some(out) }
}

fn reference_end(
    source: &str,
    cursor: &mut satteri_arena::LineIndexCursor<'_, '_>,
    end: u32,
    kind: u8,
) -> (u32, u32, u32) {
    let bytes = source.as_bytes();
    let mut out_end = end;
    if kind == 1 {
        let i = end as usize;
        if i + 1 < bytes.len() && bytes[i] == b'[' && bytes[i + 1] == b']' {
            out_end = end + 2;
        }
    }
    let (line, col) = cursor.offset_to_line_col(out_end);
    (out_end, line, col)
}

/// Extract the source text of the reference label — the bit between the
/// brackets that names the definition. Pulldown-cmark normalizes whitespace
/// when it stores `id` on the link, so using that clobbers the `label` field
/// remark preserves verbatim. Shortcut/Collapsed take the text from the
/// displayed brackets; Full takes the second pair (`[text][a  b]`).
///
/// `end` must already be the adjusted end from `reference_end` (so Collapsed
/// extends past `[]`).
/// Extract the verbatim text between `[` and the matching `]` for a link
/// reference definition, treating `\X` as a 2-byte escape (so an escaped `]`
/// inside the label doesn't terminate the scan).
/// Resolve `\X` escape sequences for ASCII punctuation in a definition or
/// reference label, matching remark's behaviour. Returns `None` when there's
/// nothing to change so the caller can keep using the source slice directly.
fn unescape_label_backslashes(s: &str) -> Option<String> {
    let bytes = s.as_bytes();
    if !bytes.contains(&b'\\') {
        return None;
    }
    let mut out = String::with_capacity(s.len());
    let mut last = 0;
    let mut i = 0;
    let mut changed = false;
    while i < bytes.len() {
        if bytes[i] == b'\\'
            && i + 1 < bytes.len()
            && crate::puncttable::is_ascii_punctuation(bytes[i + 1])
        {
            out.push_str(&s[last..i]);
            out.push(bytes[i + 1] as char);
            i += 2;
            last = i;
            changed = true;
        } else {
            i += 1;
        }
    }
    if !changed {
        return None;
    }
    out.push_str(&s[last..]);
    Some(out)
}

fn extract_definition_label(source: &str, start: u32) -> Option<&str> {
    let bytes = source.as_bytes();
    let open = start as usize;
    if open >= bytes.len() || bytes[open] != b'[' {
        return None;
    }
    let mut i = open + 1;
    while i < bytes.len() {
        match bytes[i] {
            b'\\' if i + 1 < bytes.len() => i += 2,
            b']' => return Some(&source[open + 1..i]),
            _ => i += 1,
        }
    }
    None
}

fn extract_reference_label(source: &str, start: u32, end: u32, kind: u8, is_image: bool) -> &str {
    let bytes = source.as_bytes();
    let inner_start = if is_image {
        start as usize + 2
    } else {
        start as usize + 1
    };
    if kind == 2 {
        // Full `[text][label]`: walk back from `end` (past closing `]`) to
        // find the matching `[`. Skip escaped `\[` — a bracket is escaped
        // when preceded by an odd number of backslashes.
        let close2 = end as usize - 1; // position of the second `]`
        let mut open2 = close2;
        while open2 > inner_start {
            if bytes[open2 - 1] == b'[' {
                let mut bs = 0usize;
                let mut k = open2 - 1;
                while k > inner_start && bytes[k - 1] == b'\\' {
                    bs += 1;
                    k -= 1;
                }
                if bs.is_multiple_of(2) {
                    break;
                }
            }
            open2 -= 1;
        }
        return &source[open2..close2];
    }
    if kind == 1 {
        // Collapsed `[label][]`: `end` is past the trailing `]`, so drop the
        // last three bytes (`][]`) to get to the closing `]` of the label.
        let close1 = end as usize - 3;
        return &source[inner_start..close1];
    }
    // Shortcut `[label]`: `end` sits past the closing `]`.
    &source[inner_start..end as usize - 1]
}

/// Map a pulldown-cmark `LinkType` to an MDAST reference kind
/// (0 = shortcut, 1 = collapsed, 2 = full). Returns `None` for link types
/// that resolve to an inline `link`/`image` (Inline, Autolink, Email, WikiLink).
fn reference_kind(link_type: LinkType) -> Option<u8> {
    match link_type {
        LinkType::Reference | LinkType::ReferenceUnknown => Some(2),
        LinkType::Collapsed | LinkType::CollapsedUnknown => Some(1),
        LinkType::Shortcut | LinkType::ShortcutUnknown => Some(0),
        _ => None,
    }
}

/// mdast identifier normalization. Matches remark's pipeline exactly:
/// `micromark-util-normalize-identifier` collapses `[\t\n\r ]` runs, trims,
/// then case-folds via `toLowerCase().toUpperCase()` (Unicode-approximate);
/// `mdast-util-from-markdown` then lowercases. The triple-case dance
/// matters for chars like `ẞ` → `ss`, where a single lowercase would give
/// `ß` and break cross-references to a `[SS]` definition.
fn normalize_identifier(s: &str) -> Cow<'_, str> {
    if s.is_ascii() {
        // Fast path: most refdef/footnote labels are already lowercase, no
        // tabs/newlines, no leading/trailing/consecutive whitespace. Pre-scan
        // for any of those and skip the per-char rebuild entirely.
        let bytes = s.as_bytes();
        let mut needs_work = false;
        let mut last_was_space = true; // treat string start as "after ws" to detect leading ws
        for &b in bytes {
            if matches!(b, b'\t' | b'\n' | b'\r') {
                needs_work = true;
                break;
            }
            if b == b' ' {
                if last_was_space {
                    needs_work = true;
                    break;
                }
                last_was_space = true;
            } else {
                if b.is_ascii_uppercase() {
                    needs_work = true;
                    break;
                }
                last_was_space = false;
            }
        }
        if !needs_work && last_was_space && !bytes.is_empty() {
            needs_work = true;
        }
        if !needs_work {
            return Cow::Borrowed(s);
        }
        // ASCII case folding is round-trip stable, so the
        // lower→upper→lower dance collapses to a single in-place lowercase.
        let mut out = String::with_capacity(s.len());
        let mut last_was_ws = false;
        for &b in bytes {
            if matches!(b, b' ' | b'\t' | b'\n' | b'\r') {
                if !last_was_ws && !out.is_empty() {
                    out.push(' ');
                    last_was_ws = true;
                }
            } else {
                out.push(b.to_ascii_lowercase() as char);
                last_was_ws = false;
            }
        }
        if out.ends_with(' ') {
            out.pop();
        }
        return Cow::Owned(out);
    }
    let mut collapsed = String::with_capacity(s.len());
    let mut last_was_ws = false;
    for ch in s.chars() {
        if matches!(ch, ' ' | '\t' | '\n' | '\r') {
            if !last_was_ws {
                collapsed.push(' ');
                last_was_ws = true;
            }
        } else {
            collapsed.push(ch);
            last_was_ws = false;
        }
    }
    Cow::Owned(
        collapsed
            .trim()
            .to_lowercase()
            .to_uppercase()
            .to_lowercase(),
    )
}

fn heading_level_to_u8(level: HeadingLevel) -> u8 {
    match level {
        HeadingLevel::H1 => 1,
        HeadingLevel::H2 => 2,
        HeadingLevel::H3 => 3,
        HeadingLevel::H4 => 4,
        HeadingLevel::H5 => 5,
        HeadingLevel::H6 => 6,
    }
}

/// JSON is hand-built to keep serde_json out of this crate's runtime deps
/// (mirroring satteri-ast's code node_data encoder); values are source-derived,
/// so quotes, backslashes and control chars are escaped.
fn encode_heading_h_properties(attrs: &HeadingAttributes<'_>) -> Option<Vec<u8>> {
    if attrs.id.is_none() && attrs.classes.is_empty() && attrs.attrs.is_empty() {
        return None;
    }

    fn json_string(s: &str, out: &mut Vec<u8>) {
        out.push(b'"');
        for ch in s.bytes() {
            match ch {
                b'"' => out.extend_from_slice(b"\\\""),
                b'\\' => out.extend_from_slice(b"\\\\"),
                b'\n' => out.extend_from_slice(b"\\n"),
                b'\r' => out.extend_from_slice(b"\\r"),
                b'\t' => out.extend_from_slice(b"\\t"),
                c if c < 0x20 => {
                    out.extend_from_slice(b"\\u00");
                    out.push(b"0123456789abcdef"[(c >> 4) as usize]);
                    out.push(b"0123456789abcdef"[(c & 0xf) as usize]);
                }
                c => out.push(c),
            }
        }
        out.push(b'"');
    }

    fn separator(out: &mut Vec<u8>, first: &mut bool) {
        if *first {
            *first = false;
        } else {
            out.push(b',');
        }
    }

    let mut buf = Vec::with_capacity(64);
    buf.extend_from_slice(b"{\"hProperties\":{");
    let mut first = true;

    if let Some(id) = &attrs.id {
        separator(&mut buf, &mut first);
        buf.extend_from_slice(b"\"id\":");
        json_string(id, &mut buf);
    }
    if !attrs.classes.is_empty() {
        separator(&mut buf, &mut first);
        buf.extend_from_slice(b"\"className\":[");
        for (i, class) in attrs.classes.iter().enumerate() {
            if i > 0 {
                buf.push(b',');
            }
            json_string(class, &mut buf);
        }
        buf.push(b']');
    }
    for (key, value) in &attrs.attrs {
        separator(&mut buf, &mut first);
        json_string(key, &mut buf);
        buf.push(b':');
        // Value-less (`{myattr}`) renders as `myattr=""`; a JSON `true` would
        // surface as `myattr="true"` through a real rehype pipeline.
        json_string(value.as_deref().unwrap_or(""), &mut buf);
    }

    buf.extend_from_slice(b"}}");
    Some(buf)
}

fn byte_offset_to_line_col(source: &str, offset: usize) -> String {
    let index = LineIndex::from_source(source);
    let (line, col) = index
        .cursor()
        .offset_to_line_col(offset.min(source.len()) as u32);
    format!("{line}:{col}")
}

#[cfg(feature = "mdx")]
use crate::parse::JsxElementData;

#[cfg(feature = "mdx")]
fn encode_jsx_element_data(jsx: &JsxElementData<'_>, builder: &mut ArenaBuilder<Mdast>) -> Vec<u8> {
    let name_ref = if jsx.name.is_empty() {
        StringRef::empty()
    } else {
        builder.alloc_string(&jsx.name)
    };

    let attr_tuples: Vec<(u8, StringRef, StringRef)> = jsx
        .attrs
        .iter()
        .map(|attr| match attr {
            JsxAttr::Boolean(n) => {
                let n = builder.alloc_string(n);
                (MDX_ATTR_BOOLEAN_PROP, n, StringRef::empty())
            }
            JsxAttr::Literal(n, v) => {
                let n = builder.alloc_string(n);
                let v = builder.alloc_string(v);
                (MDX_ATTR_LITERAL_PROP, n, v)
            }
            JsxAttr::Expression(n, v, _, _) => {
                let n = builder.alloc_string(n);
                let v = builder.alloc_string(v);
                (MDX_ATTR_EXPRESSION_PROP, n, v)
            }
            JsxAttr::Spread(v, _, _) => {
                let v = builder.alloc_string(v);
                (MDX_ATTR_SPREAD, StringRef::empty(), v)
            }
        })
        .collect();

    encode_mdx_jsx_element_data(name_ref, &attr_tuples, true)
}

/// Which of the two autolink routes produced each link. They disagree on
/// decoding, accepted domains, and link extent, so rendered-output conformance
/// can't pin the choice. Expected values are remark's classification;
/// `test/conformance/autolink-path.test.ts` holds remark to the same tables.
#[cfg(test)]
mod autolink_path_probe {
    use super::{Arena, Mdast, MdastNodeType, Options, parse_inner};
    use satteri_ast::mdast::decode_link_data;

    /// The JS conformance features: GFM, no frontmatter, no math.
    const PROBE_OPTIONS: Options = Options::from_bits_truncate(
        Options::ENABLE_GFM.bits()
            | Options::ENABLE_TABLES.bits()
            | Options::ENABLE_STRIKETHROUGH.bits()
            | Options::ENABLE_TASKLISTS.bits()
            | Options::ENABLE_FOOTNOTES.bits(),
    );

    #[derive(Debug, Clone, Copy, PartialEq)]
    enum Path {
        Construct,
        Fnr,
        None,
    }
    use Path::{Construct as C, Fnr as F, None as N};

    /// Unique per link within a parse, so it survives the diff between parses.
    type LinkKey = (u32, u32, String);

    fn links(source: &str, skip_fnr_autolink: bool) -> Vec<LinkKey> {
        let (arena, _) = parse_inner(source, PROBE_OPTIONS, true, None, skip_fnr_autolink);
        let mut out = Vec::new();
        if !arena.is_empty() {
            collect(&arena, 0, &mut out);
        }
        out
    }

    fn collect(arena: &Arena<Mdast>, id: u32, out: &mut Vec<LinkKey>) {
        let node = arena.get_node(id);
        if matches!(
            MdastNodeType::from_u8(node.node_type),
            Some(MdastNodeType::Link)
        ) {
            let url = decode_link_data(arena.get_type_data(id)).url;
            out.push((
                node.start_offset,
                node.end_offset,
                arena.get_str(url).to_string(),
            ));
        }
        let start = node.children_start as usize;
        for i in start..start + node.children_count as usize {
            collect(arena, arena.children[i], out);
        }
    }

    /// Every link in document order, by route.
    fn paths(source: &str) -> Vec<Path> {
        let mut construct = links(source, true);
        links(source, false)
            .into_iter()
            .map(|link| match construct.iter().position(|c| *c == link) {
                Some(ix) => {
                    construct.remove(ix);
                    C
                }
                None => F,
            })
            .collect()
    }

    /// The single path a lone trigger takes.
    fn path(source: &str) -> Path {
        paths(source).first().copied().unwrap_or(N)
    }

    /// Every shape where the three opener states (still open, closed-and-failed,
    /// closed-and-resolved) differ, plus every construct that can swallow a
    /// bracket before the trigger sees it.
    #[test]
    fn each_autolink_takes_the_same_path_as_in_remark() {
        let cases: &[(&str, &[Path])] = &[
            // Bracket-opener states.
            ("[a](/b) www.x.y", &[C, C]),
            ("[a [b](/c) www.x.y", &[C, F]),
            ("[a] www.x.y", &[C]),
            ("![a] www.x.y", &[C]),
            ("[a www.x.y", &[F]),
            ("[a\nwww.x.y", &[F]),
            ("[a\n\nwww.x.y", &[C]),
            ("# [a www.x.y", &[F]),
            // Brackets consumed by an enclosing construct before the trigger.
            ("[a `]` www.x.y", &[F]),
            ("`[` www.x.y", &[C]),
            ("[a ``]`` www.x.y", &[F]),
            ("``[`` www.x.y", &[C]),
            ("<span a='['> www.x.y", &[C]),
            ("[a <http://q.r/]> www.x.y", &[C, F]),
            // A trigger inside a link destination the parser has already resolved.
            ("[a](https://x.y)x", &[C]),
            ("[a](www.x.y)x", &[C]),
            // …and inside one it never resolves, so the trigger sees ordinary bytes.
            ("[[x]](https://x.y)x\n\n[x]: /", &[C]),
            ("[[x]](www.a.com)y\n\n[x]: /", &[C]),
            ("[foo][bar](https://x.y)x\n\n[bar]: /", &[C]),
            ("[[a](/b)](https://x.y)x", &[C, C]),
            // Unclosed or non-resolving brackets around a trigger.
            ("[www.a.com", &[F]),
            ("[www.a.com]", &[F]),
            ("[www.a.com](", &[F]),
            ("![www.a.com", &[F]),
            ("[foo][www.a.com]", &[F]),
            ("[https://a.com](", &[F]),
            // A `]` balances its opener even when nothing resolves, so a
            // trigger past it is no longer blocked and the URL before it
            // can't run on.
            ("[www.a.com]www.b.com", &[F, C]),
            ("[www.a.com]]www.b.com", &[F, C]),
            ("[www.a.com]http://b.com", &[F, C]),
            ("[www.a.com]u@b.com", &[F, C]),
            ("[www.a.com]_u@b.com", &[F, C]),
            ("[http://a.com]www.b.com", &[F, C]),
            ("a[www.a.com]www.b.com", &[F, C]),
            // The opener is still unbalanced, so both triggers stay blocked.
            ("[[www.a.com]www.b.com", &[F]),
            // No opener at all: `]` is an ordinary URL byte.
            ("www.a.com]www.b.com", &[C]),
            // Preceding-character rules. `www.` takes a fixed whitelist,
            // `http://` rejects only ASCII letters, and email rejects `/` and atext.
            ("www.x.y", &[C]),
            (".www.x.y", &[F]),
            (".http://x.y", &[C]),
            ("awww.x.y", &[]),
            ("5http://x.y", &[C]),
            ("/a@b.cd", &[]),
            ("(www.x.y)", &[C]),
            ("_www.x.y_", &[C]),
            ("x\u{85}www.x.y", &[]),
        ];

        assert_eq!(cases.len(), 44, "the probe lost inputs");
        let mismatches: Vec<String> = cases
            .iter()
            .filter(|(input, expected)| paths(input) != **expected)
            .map(|(input, expected)| format!("{input:?} want {expected:?} got {:?}", paths(input)))
            .collect();
        assert!(mismatches.is_empty(), "{}", mismatches.join("\n"));
    }

    /// The triggers have disagreeing preceding-character rules, and what the
    /// construct path blocks falls through to find-and-replace, which wants
    /// whitespace or punctuation. The fourth is a `www.` literal and an email
    /// at the same offset, so it also pins which construct is tried first.
    #[test]
    fn a_preceding_character_selects_the_path_per_trigger() {
        const TRIGGERS: [&str; 4] = ["www.x.y", "http://x.y", "a@b.cd", "www.x@y.zz"];
        let rules: &[(&str, [Path; 4])] = &[
            ("", [C, C, C, C]),
            (" ", [C, C, C, C]),
            ("(", [C, C, C, C]),
            ("*", [C, C, C, C]),
            ("_", [C, C, C, C]),
            ("]", [C, C, C, C]),
            ("~", [C, C, C, C]),
            ("[", [F, F, F, F]),
            (".", [F, C, C, C]),
            ("/", [F, C, N, F]),
            ("+", [F, C, C, C]),
            (")", [F, C, C, C]),
            ("!", [F, C, C, C]),
            (":", [F, C, C, C]),
            ("¥", [F, C, C, C]),
            ("→", [F, C, C, C]),
            ("a", [N, N, C, C]),
            ("5", [N, C, C, C]),
            ("é", [N, C, C, C]),
            ("你", [N, C, C, C]),
            ("你好", [N, C, C, C]),
            ("\u{200b}", [N, C, C, C]),
            // U+FEFF is not `White_Space`, yet find-and-replace takes it as a
            // boundary. Prefixed with a letter to keep leading-BOM handling out.
            ("a\u{feff}", [F, C, C, C]),
            // U+0085 is `White_Space`, but find-and-replace does not take it
            // as a boundary.
            ("\u{85}", [N, C, C, C]),
        ];

        for (prefix, expected) in rules {
            for (trigger, want) in TRIGGERS.iter().zip(expected) {
                let input = format!("{prefix}{trigger}");
                assert_eq!(path(&input), *want, "{input:?}");
            }
        }
    }

    /// Deliberate divergence: the preceding character is classified as a whole
    /// scalar, so astral punctuation and symbols open an autolink.
    /// See website/content/docs/divergences.md.
    #[test]
    fn an_astral_punctuation_or_symbol_starts_an_autolink() {
        for prefix in ["\u{10101}", "\u{1f600}", "\u{1d6db}"] {
            // Unbracketed, only `www.` shows it: the other two take the construct path.
            assert_eq!(path(&format!("{prefix}www.x.y")), F);
            // An unclosed `[` blocks the construct, so all three fall through.
            for trigger in ["www.x.y", "http://x.y", "a@b.cd"] {
                assert_eq!(path(&format!("[{prefix}{trigger}")), F, "{trigger}");
            }
        }
    }

    /// `Nd`: the control for the divergence above.
    #[test]
    fn an_astral_digit_starts_nothing() {
        let prefix = "\u{1fbf0}";
        assert_eq!(path(&format!("{prefix}www.x.y")), N);
        for trigger in ["www.x.y", "http://x.y", "a@b.cd"] {
            assert_eq!(path(&format!("[{prefix}{trigger}")), N, "{trigger}");
        }
    }

    /// The differential signal holds only while the skip is the sole difference.
    #[test]
    fn skipping_the_pass_changes_nothing_that_has_no_autolink() {
        for input in ["[a](/b) x", "`[` x", "# [a", "text **bold** and `code`"] {
            let (skipped, _) = parse_inner(input, PROBE_OPTIONS, true, None, true);
            let (full, _) = parse_inner(input, PROBE_OPTIONS, true, None, false);
            assert_eq!(
                satteri_ast::mdast_to_html(&skipped),
                satteri_ast::mdast_to_html(&full),
                "{input:?}"
            );
        }
    }

    const NO_POSSIBLE_TRIGGER: &[&str] = &[
        "how the wind howls",
        "Web WWW rows, HTTP verbs: what, where, why",
        "**how** *what* ~~where~~ `hth` w.x ww.x.y wwww http:x.y https:/x.y",
        "[a w.x](http:foo) ![b](w:x)",
        "| head h | w col |\n| --- | --- |\n| ha | wo |",
        "- [ ] winter\n- [x] home\n\n> quote how\n\n# heading with words",
    ];

    const CONSTRUCT_PATH_LINKS: &[&str] = &[
        "www.x.y http://x.y a@b.cd",
        "HTTP://X.Y WWW.X.Y",
        "*www.x.y* _a@b.cd_",
    ];

    const FNR_PATH_LINKS: &[&str] = &[
        "[a www.x.y",
        ".www.x.y",
        "[a <http://q.r/]> www.x.y",
        "<www.x.y> b",
        "[a] www.a.b x\\* www.c.d",
        "> [a www.x.y\n> more",
    ];

    const DECODE_SYNTHESIZED_TRIGGERS: &[&str] = &[
        "www\\.x.y",
        "http:\\//x.y",
        "ww&#119;.x.y",
        "w&#119;w.x.y",
        "x&#64;y.zz",
        "&#104;ttp&#58;//x.y",
        "w\\ww.x.y",
    ];

    const IGNORED_OR_TRUNCATED_SHAPES: &[&str] = &[
        "`www.x.y` [www.x.y](/u) ![w](www.x.y)",
        "```\nwww.x.y\n```",
        "www.",
        "www.x",
        "a@",
        "htt",
        "x@y.zz",
        "| www.x.y |\n| --- |\n| a@b.cd |",
        "a[^1]\n\n[^1]: www.x.y ok",
    ];

    /// A wrong document-level skip is silent; this is the check that catches it.
    #[test]
    fn force_running_the_fnr_pass_after_a_parse_changes_nothing() {
        let smart = PROBE_OPTIONS.union(Options::ENABLE_SMART_PUNCTUATION);
        for options in [PROBE_OPTIONS, smart] {
            for input in NO_POSSIBLE_TRIGGER
                .iter()
                .chain(CONSTRUCT_PATH_LINKS)
                .chain(FNR_PATH_LINKS)
                .chain(DECODE_SYNTHESIZED_TRIGGERS)
                .chain(IGNORED_OR_TRUNCATED_SHAPES)
            {
                let (mut arena, _) = parse_inner(input, options, true, None, false);
                let before = satteri_ast::mdast_to_html(&arena);
                crate::post_passes::gfm_autolink_literal_pass(
                    &mut arena,
                    input.as_bytes(),
                    options,
                    None,
                );
                assert_eq!(before, satteri_ast::mdast_to_html(&arena), "{input:?}");
            }
        }
    }

    /// Keeps the corpus honest: an entry drifting to the wrong verdict would void the proof above.
    #[test]
    fn the_gate_corpus_exercises_both_verdicts() {
        for input in NO_POSSIBLE_TRIGGER {
            assert!(
                !crate::post_passes::gfm_autolink_literal_may_apply(input.as_bytes()),
                "{input:?}"
            );
        }
        for input in DECODE_SYNTHESIZED_TRIGGERS
            .iter()
            .chain(CONSTRUCT_PATH_LINKS)
            .chain(FNR_PATH_LINKS)
        {
            assert!(
                crate::post_passes::gfm_autolink_literal_may_apply(input.as_bytes()),
                "{input:?}"
            );
        }
    }
}