lex-babel 0.19.2

//! Conversion from Lex AST to the format-agnostic IR.
//!
//! Pipeline: Lex AST (Document) → IR (ir::nodes::Document)
//!
//! This is the entry point for all outbound format conversions. The IR strips
//! source-level details (positions, blank line groups, token info) to produce
//! a clean semantic representation that any format serializer can consume.
//!
//! Level mapping: root session children start at heading level 2 (the document
//! title occupies level 1). Each nested session increments the level.
//!
//! Verbatim blocks with built-in labels (`lex.tabular.table`,
//! `lex.media.{image,video,audio}`) are hydrated into first-class IR
//! nodes (Table, Image, Video, Audio) via the extension registry's
//! `on_resolve` dispatch (#583) — see [`from_lex_verbatim`].

use lex_core::lex::ast::elements::{
    inlines::InlineNode, Annotation as LexAnnotation, ContentItem as LexContentItem,
    Definition as LexDefinition, Document as LexDocument, List as LexList, ListItem as LexListItem,
    Paragraph as LexParagraph, Session as LexSession, TextLine as LexTextLine,
    Verbatim as LexVerbatim, VerbatimLine as LexVerbatimLine,
};
use lex_core::lex::ast::TextContent;
use lex_core::lex::wire::{origin_string, range_to_wire};
use lex_extension::wire::{AnnotationBody, HostNodeKind, LabelCtx, NodeRef, WireNode};
use lex_extension_host::registry::Registry;

use super::anchoring::AnchorIndex;
use super::nodes::{
    Annotation, Audio, Definition, DocNode, Document, Heading, Image, InlineContent, List,
    ListForm, ListItem, ListStyle, Paragraph, Verbatim, Video,
};

/// Shared context threaded through IR construction.
///
/// Bundles the extension `registry` (for verbatim `on_ir_build` dispatch) with
/// the document's resolved reference-line [`AnchorIndex`] (for whole-element and
/// self-link anchoring, references-general.lex §2.3.2–§2.3.4), so every
/// converter has both without a long parameter list.
struct ConvCtx<'a> {
    registry: &'a Registry,
    anchors: &'a AnchorIndex,
}

/// Converts a lex document to the IR.
///
/// `registry` is the extension registry used to dispatch verbatim
/// labels through their `on_resolve` hooks (#583 — required for
/// `lex.tabular.table` to produce a typed `DocNode::Table` and for
/// `lex.media.{image,video,audio}` to participate in the IR
/// construction). Callers that only need the built-in `lex.*`
/// namespaces can pass [`default_registry()`]; CLI / LSP callers
/// that boot a registry with third-party namespaces pass theirs.
///
/// Post-refac/label cleanup: the legacy frontmatter promotion (which
/// scanned `children` for `lex.metadata.*` annotations and synthesized
/// a single `frontmatter` IR Annotation into `children[0]`) is retired.
/// Document-scope metadata now lives exclusively in
/// `Document::document_annotations`, populated from the lex-core
/// `doc.annotations` slot.
///
/// Phase 3b (#614): the IR slot is also the single source of truth
/// on the way back out. `to_lex_document` emits each entry into
/// `lex_doc.annotations` via `to_lex_annotation_raw`, and the
/// `frontmatter` event synthesis at the events-emission layer is
/// retired — format-specific serializers that need a packed YAML
/// preamble (currently just markdown) read `document_annotations`
/// from the IR directly.
///
/// **Behavioural break** (documented in CHANGELOG): an inline
/// `:: lex.metadata.title :: ...` in the document body is no longer
/// promoted to document metadata. Inline annotations stay inline;
/// document-scope metadata must be attached at the document level
/// (lex-core's `doc.annotations` slot).
pub fn from_lex_document(doc: &LexDocument, registry: &Registry) -> Document {
    let anchors = AnchorIndex::from_document(doc);
    let ctx = ConvCtx {
        registry,
        anchors: &anchors,
    };

    // Extract document title and subtitle
    let title = doc
        .title
        .as_ref()
        .map(|t| convert_inline_content(&t.content));
    let subtitle = doc
        .title
        .as_ref()
        .and_then(|t| t.subtitle.as_ref())
        .map(convert_inline_content);

    let mut children = convert_children(&doc.root.children, 2, &ctx);

    // Splice self-link reference lines (§2.3.2: a reference line with no element
    // directly above stands alone and links its own text) into the top-level
    // child stream in source order. They were removed from the structural stream
    // by lex-core, so they have no element to attach to and render as standalone
    // link paragraphs.
    splice_self_links(&mut children, &doc.root.children, &anchors);

    let document_annotations = doc
        .annotations
        .iter()
        .map(|a| ir_annotation_from_lex(a, &ctx))
        .collect();

    Document {
        title,
        subtitle,
        children,
        document_annotations,
    }
}

/// Insert standalone self-link paragraphs into the child stream at the position
/// their source reference falls, by source order, recursing into the nested
/// container that actually contains each self-link.
///
/// `lex_children` is the original lex-AST child list (carrying source spans);
/// `ir_children` is the already-converted IR list. A self-link reference line
/// can appear at the top level *or* nested inside a container (session body,
/// list item, definition description, annotation body). Each self-link is placed
/// relative to its own source span:
///
/// - If it falls inside a structural element's source span, recurse into that
///   element's IR child container and splice it there.
/// - Otherwise it is a sibling at this level: insert it just before the first
///   element whose source starts after the self-link.
///
/// The two lists are not index-aligned: attached annotations expand into extra
/// leading IR nodes (each structural element converts to
/// `attached_annotations(item).len() + 1` IR nodes). Sibling positioning maps the
/// structural-element slot to the real IR index by summing that expansion over
/// the preceding structural elements, so a self-link never lands between an
/// element and its own attached annotations.
fn splice_self_links(
    ir_children: &mut Vec<DocNode>,
    lex_children: &[LexContentItem],
    anchors: &AnchorIndex,
) {
    let self_links = anchors.self_links_in(0..usize::MAX);
    if self_links.is_empty() {
        return;
    }
    splice_self_links_into(ir_children, lex_children, &self_links);
}

/// Recursive worker for [`splice_self_links`]. Distributes `self_links` (those
/// whose span falls inside a nested container recurse into it; the rest splice
/// at this level) against the `(lex_children, ir_children)` pair produced by
/// [`convert_children`].
fn splice_self_links_into(
    ir_children: &mut Vec<DocNode>,
    lex_children: &[LexContentItem],
    self_links: &[&super::anchoring::SelfLink],
) {
    use lex_core::lex::ast::traits::AstNode;

    // Walk the structural (non-blank) lex children in order, tracking the IR
    // index of each element's *own* node (after its leading annotation nodes).
    // Record, per structural element, its source span and IR node index, so we
    // can both recurse into containers and map sibling slots to IR indices.
    struct Slot {
        span: std::ops::Range<usize>,
        ir_index: usize,
    }
    let mut slots: Vec<Slot> = Vec::new();
    let mut ir_cursor = 0usize;
    for item in lex_children
        .iter()
        .filter(|c| !matches!(c, LexContentItem::BlankLineGroup(_)))
    {
        let anno_count = attached_annotations(item).len();
        let ir_index = ir_cursor + anno_count;
        slots.push(Slot {
            span: item.range().span.clone(),
            ir_index,
        });
        // A lex item usually maps to exactly one IR node, but a multi-group
        // verbatim block expands to one node per group (see `convert_children`
        // / `from_lex_verbatim_groups`, #769). Advance the cursor by the actual
        // node count so every subsequent slot's `ir_index` — and the recursion /
        // sibling-splice indices derived from it — stay aligned with the IR list.
        ir_cursor = ir_index + ir_node_count(item);
    }

    // Iterate structural items in parallel with `slots` for recursion.
    let structural: Vec<&LexContentItem> = lex_children
        .iter()
        .filter(|c| !matches!(c, LexContentItem::BlankLineGroup(_)))
        .collect();

    // Partition the self-links: those contained in a structural element recurse
    // into it; the rest stay as siblings at this level. `nested[si]` collects
    // the self-links that fall inside the `si`-th structural element.
    let mut siblings: Vec<&super::anchoring::SelfLink> = Vec::new();
    let mut nested: Vec<Vec<&super::anchoring::SelfLink>> = vec![Vec::new(); structural.len()];

    for &sl in self_links {
        // Find the structural element whose span strictly contains the self-link
        // (start < sl.start AND sl.start < end) and that has a recursable child
        // stream. A self-link sits *inside* a container when its bracket falls
        // within that container's source span.
        let container = structural.iter().enumerate().find(|(_, item)| {
            let span = item.range().span.clone();
            span.start < sl.span.start && sl.span.start < span.end && has_recursable_children(item)
        });
        match container {
            Some((si, _item)) => nested[si].push(sl),
            None => siblings.push(sl),
        }
    }

    // Recurse into each container that received nested self-links.
    for (si, links) in nested.iter().enumerate() {
        if links.is_empty() {
            continue;
        }
        let item = structural[si];
        let ir_index = slots[si].ir_index;
        recurse_into_container(&mut ir_children[ir_index], item, links);
    }

    // Splice the sibling self-links at this level (descending source order so
    // earlier inserts don't shift later indices).
    let mut siblings_sorted = siblings;
    siblings_sorted.sort_by_key(|s| std::cmp::Reverse(s.span.start));
    for sl in siblings_sorted {
        // Map the sibling to the IR index just after the last structural element
        // that starts before it. `slots` is in source order, so count the
        // elements before the self-link and take the IR index following the last
        // one (or 0 when the self-link precedes every element).
        let preceding = slots
            .iter()
            .filter(|s| s.span.start < sl.span.start)
            .count();
        let ir_index = if preceding == 0 {
            0
        } else {
            // Land just past the preceding element's *last* IR node. That
            // element may expand to several nodes (a multi-group verbatim,
            // #769), so step over all of them — not a fixed `+ 1` — or the
            // sibling self-link would be spliced between the groups.
            slots[preceding - 1].ir_index + ir_node_count(structural[preceding - 1])
        };
        let node = self_link_node(sl);
        if ir_index <= ir_children.len() {
            ir_children.insert(ir_index, node);
        } else {
            ir_children.push(node);
        }
    }
}

/// Number of IR `DocNode`s the item's *own* content expands to (excluding its
/// leading attached-annotation nodes, which are counted separately). One for
/// every item except a multi-group verbatim block, which `convert_children`
/// expands into one node per group (#769) — the self-link index mapping must
/// advance by that count to stay aligned with the IR list.
fn ir_node_count(item: &LexContentItem) -> usize {
    if let LexContentItem::VerbatimBlock(verbatim) = item {
        let groups = verbatim.group_len();
        if groups > 1 {
            return groups;
        }
    }
    1
}

/// True when `item` is a container whose IR counterpart holds a child `DocNode`
/// stream a nested self-link could be spliced into.
fn has_recursable_children(item: &LexContentItem) -> bool {
    matches!(
        item,
        LexContentItem::Session(_)
            | LexContentItem::List(_)
            | LexContentItem::ListItem(_)
            | LexContentItem::Definition(_)
            | LexContentItem::Annotation(_)
    )
}

/// Recurse into a container IR node, splicing the `links` that fall within it.
///
/// Pairs the lex container's child list with the matching IR child `Vec` and
/// recurses through [`splice_self_links_into`]. A `List` has no direct child
/// stream of its own — its self-links live inside one of its `ListItem`s — so it
/// dispatches to the list item whose span contains each link.
fn recurse_into_container(
    ir_node: &mut DocNode,
    lex_item: &LexContentItem,
    links: &[&super::anchoring::SelfLink],
) {
    use lex_core::lex::ast::traits::AstNode;

    match (ir_node, lex_item) {
        (DocNode::Heading(h), LexContentItem::Session(s)) => {
            splice_self_links_into(&mut h.children, &s.children, links);
        }
        (DocNode::ListItem(li), LexContentItem::ListItem(lex_li)) => {
            splice_self_links_into(&mut li.children, &lex_li.children, links);
        }
        (DocNode::Definition(d), LexContentItem::Definition(lex_d)) => {
            splice_self_links_into(&mut d.description, &lex_d.children, links);
        }
        (DocNode::Annotation(a), LexContentItem::Annotation(lex_a)) => {
            splice_self_links_into(&mut a.content, &lex_a.children, links);
        }
        (DocNode::List(list), LexContentItem::List(lex_list)) => {
            // A list has no direct child stream — its self-links live inside one
            // of its items. A reference line indented under an item is removed
            // from the source, so its byte offset can land *past* that item's
            // recorded span end (the span reflects only the surviving tokens) yet
            // before the next item. Strict containment would miss it, so assign
            // each link to the item it *trails*: the item with the greatest start
            // offset still less than the link's. Items are in source order.
            let lex_items: Vec<&LexContentItem> = lex_list
                .items
                .iter()
                .filter(|c| matches!(c, LexContentItem::ListItem(_)))
                .collect();
            let item_starts: Vec<usize> = lex_items.iter().map(|c| c.range().span.start).collect();
            // Bucket links by trailing-item index.
            let mut buckets: Vec<Vec<&super::anchoring::SelfLink>> =
                vec![Vec::new(); lex_items.len()];
            for &sl in links {
                let target = item_starts.iter().rposition(|&start| start < sl.span.start);
                if let Some(ti) = target {
                    buckets[ti].push(sl);
                }
                // A link before the first item is unexpected (it would not be
                // inside the list span); drop-free fallback: it stays unplaced,
                // which can't happen given the outer containment check.
            }
            for (ir_li, (lex_li, bucket)) in list
                .items
                .iter_mut()
                .zip(lex_items.iter().zip(buckets.iter()))
            {
                if bucket.is_empty() {
                    continue;
                }
                if let LexContentItem::ListItem(lex_li) = lex_li {
                    splice_self_links_into(&mut ir_li.children, &lex_li.children, bucket);
                }
            }
        }
        _ => {
            // Shape mismatch (should not happen given has_recursable_children).
            // Leave the links unplaced rather than panic; correctness-preserving
            // fallback per the PR's nested-placement note.
        }
    }
}

/// A standalone self-link reference line: a paragraph holding a single `Link`
/// whose text and href are both the reference's own raw content.
fn self_link_node(sl: &super::anchoring::SelfLink) -> DocNode {
    DocNode::Paragraph(Paragraph {
        content: vec![InlineContent::Link {
            text: sl.raw.clone(),
            href: super::anchoring::reference_href(&sl.raw),
        }],
    })
}

/// Build an IR `Annotation` directly from a lex-core annotation, without
/// the `DocNode` enum wrapper that [`from_lex_annotation`] returns. Used
/// by [`from_lex_document`] to populate `Document::document_annotations`.
fn ir_annotation_from_lex(annotation: &LexAnnotation, ctx: &ConvCtx) -> Annotation {
    let label = annotation.data.label.value.clone();
    let form = annotation.data.label.form;
    let parameters = annotation
        .data
        .parameters
        .iter()
        .map(|p| (p.key.clone(), p.value.clone()))
        .collect();
    let content = convert_children(&annotation.children, 2, ctx);
    Annotation {
        label,
        parameters,
        content,
        form,
    }
}

/// Helper: Converts a list of content items, filtering out blank lines
/// Also extracts annotations attached to each element
fn convert_children(items: &[LexContentItem], level: usize, ctx: &ConvCtx) -> Vec<DocNode> {
    items
        .iter()
        .filter(|item| !matches!(item, LexContentItem::BlankLineGroup(_)))
        .flat_map(|item| {
            let mut nodes = extract_attached_annotations(item, level, ctx);
            // A multi-group verbatim block (multiple subject/content pairs
            // sharing one closing marker, e.g. `verbatim-11-group-shell.lex`)
            // is flattened into one IR `DocNode::Verbatim` per group: the IR
            // verbatim node carries a single subject + content, so without this
            // every group after the first would be dropped (#769).
            if let LexContentItem::VerbatimBlock(verbatim) = item {
                if verbatim.group_len() > 1 {
                    nodes.extend(from_lex_verbatim_groups(verbatim, ctx));
                    return nodes;
                }
            }
            nodes.push(from_lex_content_item_with_level(item, level, ctx));
            nodes
        })
        .collect()
}

/// Annotations attached to a content item (the same set
/// [`extract_attached_annotations`] converts to leading IR nodes).
fn attached_annotations(item: &LexContentItem) -> &[LexAnnotation] {
    match item {
        LexContentItem::Session(session) => session.annotations(),
        LexContentItem::Paragraph(paragraph) => paragraph.annotations(),
        LexContentItem::List(list) => list.annotations(),
        LexContentItem::ListItem(list_item) => list_item.annotations(),
        LexContentItem::Definition(definition) => definition.annotations(),
        LexContentItem::VerbatimBlock(verbatim) => verbatim.annotations(),
        LexContentItem::Table(table) => table.annotations(),
        _ => &[],
    }
}

/// Extracts annotations attached to a content item and converts them to IR nodes
fn extract_attached_annotations(
    item: &LexContentItem,
    level: usize,
    ctx: &ConvCtx,
) -> Vec<DocNode> {
    attached_annotations(item)
        .iter()
        .map(|anno| from_lex_annotation(anno, level, ctx))
        .collect()
}

/// Converts TextContent to IR InlineContent, applying §2.3.1 word anchors.
///
/// lex-core resolves each inline reference's word anchor during parsing and
/// stores it on the `ReferenceInline`. [`apply_word_anchors`] reads that
/// resolved data: a link-like reference with an adjacent word becomes a `Link`
/// wrapping that word (the bracketed reference itself renders nothing), while
/// marker-style references and references with no adjacent word pass through
/// unchanged for the serializer to render.
fn convert_inline_content(text: &TextContent) -> Vec<InlineContent> {
    use crate::ir::anchoring::apply_word_anchors;

    // Get inline items from TextContent.
    let inline_items = text.inline_items();

    if inline_items.is_empty() {
        // If no inline items, use raw string.
        return vec![InlineContent::Text(text.as_string().to_string())];
    }

    apply_word_anchors(&inline_items, &convert_inline_node)
}

/// Converts a single InlineNode to IR InlineContent
fn convert_inline_node(node: &InlineNode) -> InlineContent {
    match node {
        InlineNode::Plain { text, .. } => InlineContent::Text(text.clone()),
        InlineNode::Strong { content, .. } => {
            InlineContent::Bold(content.iter().map(convert_inline_node).collect())
        }
        InlineNode::Emphasis { content, .. } => {
            InlineContent::Italic(content.iter().map(convert_inline_node).collect())
        }
        InlineNode::Code { text, .. } => InlineContent::Code(text.clone()),
        InlineNode::Math { text, .. } => InlineContent::Math(text.clone()),
        InlineNode::Reference { data, .. } => InlineContent::Reference {
            raw: data.raw.clone(),
            kind: data.reference_type.clone(),
        },
    }
}

/// Converts a head-line `TextContent` to IR inline content, applying a
/// whole-element anchor (references-general.lex §2.3.2) when a reference line
/// targets this head line.
///
/// When the head line's source span contains a resolved whole-element anchor,
/// the entire head line is rendered as a single `Link` of the anchor's text;
/// the reference line itself emits no separate output (it was removed from the
/// structural stream by lex-core). Otherwise the head line converts normally,
/// including any §2.3.1 inline word anchors.
fn convert_head_line(text: &TextContent, ctx: &ConvCtx) -> Vec<InlineContent> {
    if !ctx.anchors.is_empty() {
        if let Some(anchor) = ctx.anchors.match_head_line(text) {
            return super::anchoring::wrap_head_line(anchor);
        }
    }
    convert_inline_content(text)
}

/// Converts a lex content item to an IR node with a given level.
fn from_lex_content_item_with_level(item: &LexContentItem, level: usize, ctx: &ConvCtx) -> DocNode {
    match item {
        LexContentItem::Session(session) => from_lex_session(session, level, ctx),
        LexContentItem::Paragraph(paragraph) => from_lex_paragraph(paragraph, ctx),
        LexContentItem::List(list) => from_lex_list(list, level, ctx),
        LexContentItem::ListItem(list_item) => from_lex_list_item(list_item, level, ctx),
        LexContentItem::Definition(definition) => from_lex_definition(definition, level, ctx),
        LexContentItem::VerbatimBlock(verbatim) => from_lex_verbatim(verbatim, ctx),
        LexContentItem::Table(table) => from_lex_table(table, ctx),
        LexContentItem::Annotation(annotation) => from_lex_annotation(annotation, level, ctx),
        LexContentItem::TextLine(text_line) => from_lex_text_line(text_line),
        LexContentItem::VerbatimLine(verbatim_line) => from_lex_verbatim_line(verbatim_line),
        LexContentItem::BlankLineGroup(_) => {
            // Blank lines are filtered out by convert_children, but handle gracefully if encountered
            DocNode::Paragraph(Paragraph { content: vec![] })
        }
    }
}

/// Converts a lex session to an IR heading.
///
/// Session markers (e.g. "1." in "1. Introduction") are part of the author's
/// title text and are preserved as regular `InlineContent::Text` — not as a
/// separate structural variant. The full title text (including any numbering
/// prefix) is kept in `Heading.content`.
fn from_lex_session(session: &LexSession, level: usize, ctx: &ConvCtx) -> DocNode {
    let content = convert_head_line(&session.title, ctx);

    let children = convert_children(&session.children, level + 1, ctx);
    DocNode::Heading(Heading {
        level,
        content,
        children,
    })
}

/// Converts a lex paragraph to an IR paragraph.
///
/// Each paragraph line is a head-line candidate for a whole-element anchor
/// (§2.3.2: a reference line on a paragraph anchors the single line directly
/// above it), so lines convert through [`convert_head_line`].
fn from_lex_paragraph(paragraph: &LexParagraph, ctx: &ConvCtx) -> DocNode {
    // Paragraphs have multiple lines, each is a TextLine with TextContent
    let mut content = Vec::new();
    for line_item in &paragraph.lines {
        if let LexContentItem::TextLine(text_line) = line_item {
            content.extend(convert_head_line(&text_line.content, ctx));
            // Add newline between lines except for the last line
            if line_item != paragraph.lines.last().unwrap() {
                content.push(InlineContent::Text("\n".to_string()));
            }
        }
    }
    DocNode::Paragraph(Paragraph { content })
}

/// Converts a lex list to an IR list.
fn from_lex_list(list: &LexList, level: usize, ctx: &ConvCtx) -> DocNode {
    let items: Vec<ListItem> = list
        .items
        .iter()
        .filter_map(|item| {
            if let LexContentItem::ListItem(li) = item {
                Some(convert_list_item(li, level, ctx))
            } else {
                None
            }
        })
        .collect();

    // Detect list style from the first item's marker
    let style = if let Some(LexContentItem::ListItem(li)) = list.items.first() {
        detect_list_style(&li.marker)
    } else {
        ListStyle::Bullet
    };
    let ordered = style.is_ordered();

    // Detect form from the list's SequenceMarker
    let form = list
        .marker
        .as_ref()
        .map(|m| match m.form {
            lex_core::lex::ast::elements::sequence_marker::Form::Extended => ListForm::Extended,
            lex_core::lex::ast::elements::sequence_marker::Form::Short => ListForm::Short,
        })
        .unwrap_or(ListForm::Short);

    DocNode::List(List {
        items,
        ordered,
        style,
        form,
    })
}

/// Converts a lex list item to an IR list item node.
fn from_lex_list_item(list_item: &LexListItem, level: usize, ctx: &ConvCtx) -> DocNode {
    DocNode::ListItem(convert_list_item(list_item, level, ctx))
}

/// Converts a lex list item to an IR list item struct.
///
/// List markers are structural (captured by `List.style` and `List.form` on the
/// parent) and are not included in the item's inline content. The item's own
/// line is a head-line candidate for a whole-element anchor (§2.3.2), so it
/// converts through [`convert_head_line`].
fn convert_list_item(list_item: &LexListItem, level: usize, ctx: &ConvCtx) -> ListItem {
    let mut content = Vec::new();
    for text_content in &list_item.text {
        content.extend(convert_head_line(text_content, ctx));
    }
    let children = convert_children(&list_item.children, level, ctx);
    ListItem { content, children }
}

/// Converts a lex definition to an IR definition.
///
/// The subject term is a head-line candidate for a whole-element anchor
/// (§2.3.2; the trailing colon is excluded, matching the resolved anchor text),
/// so it converts through [`convert_head_line`].
fn from_lex_definition(definition: &LexDefinition, level: usize, ctx: &ConvCtx) -> DocNode {
    let term = convert_head_line(&definition.subject, ctx);
    let description = convert_children(&definition.children, level, ctx);
    DocNode::Definition(Definition { term, description })
}

/// Converts a lex verbatim block to an IR verbatim block.
///
/// #615 unified registry surface: dispatches through
/// [`Registry::dispatch_ir_build`] (the IR-construction lifecycle hook)
/// rather than the pre-#615 `dispatch_resolve` path. The built-in
/// `lex.tabular.table` and `lex.media.{image,video,audio}` handlers
/// parse the verbatim into a typed `WireNode` (`Table` / `Image` /
/// `Video` / `Audio` per `wire_version: 2`); the typed wire output
/// converts to IR directly via [`from_wire_typed`], without a
/// wire-→-lex-core-AST round-trip and without dispatching on the
/// label string a second time. Third-party namespaces that register
/// a verbatim handler with `on_ir_build` participate the same way.
///
/// Falls back to a generic `DocNode::Verbatim` when no handler is
/// registered for the label, when the handler returns `Ok(None)`, or
/// when the returned wire kind isn't one this builder knows how to
/// type (third-party verbatim labels without an IR-build hook,
/// unrecognised labels, future wire variants).
fn from_lex_verbatim(verbatim: &LexVerbatim, ctx: &ConvCtx) -> DocNode {
    let subject_str = verbatim.subject.as_string();
    let subject = if subject_str.is_empty() {
        None
    } else {
        Some(subject_str.to_string())
    };
    // A reference line can anchor the verbatim subject (§2.3.2; trailing colon
    // excluded). The subject renders as a plain-text caption, so the resolved
    // link travels alongside it as `subject_href` for the serializers to wrap.
    let subject_href = ctx
        .anchors
        .match_head_line(&verbatim.subject)
        .map(|a| a.href.clone());
    let language = Some(verbatim.closing_data.label.value.clone());
    let content = verbatim
        .children
        .iter()
        .map(|item| {
            if let LexContentItem::VerbatimLine(vl) = item {
                vl.content.as_string().to_string()
            } else {
                "".to_string()
            }
        })
        .collect::<Vec<_>>()
        .join("\n");

    // Build a LabelCtx from the parsed-verbatim payload (label + params
    // + body) and fire the IR-build hook. The handler returns a typed
    // WireNode directly; we convert to IR by switching on the wire
    // variant — no re-dispatch on the label string.
    let label = verbatim.closing_data.label.value.clone();
    // Pass semantic param values to handlers (outer quotes stripped,
    // escapes resolved) — matches the policy lex-core uses for
    // annotation dispatch (see `includes::annotation_to_wire`). The
    // raw value with quotes is preserved on the IR `Verbatim`
    // fallback below for round-trip serialisation.
    let params_object = serde_json::Value::Object(
        verbatim
            .closing_data
            .parameters
            .iter()
            .map(|p| (p.key.clone(), serde_json::Value::String(p.unquoted_value())))
            .collect(),
    );
    let label_ctx = LabelCtx {
        label,
        params: params_object,
        body: AnnotationBody::Text(content.clone()),
        node: NodeRef {
            kind: HostNodeKind::Verbatim.as_str().into(),
            range: range_to_wire(&verbatim.location),
            origin: origin_string(&verbatim.location),
        },
    };
    if let Ok(Some(mut wire_node)) = ctx.registry.dispatch_ir_build(&label_ctx) {
        // The subject line on a verbatim is part of the host's context,
        // not the hydrated wire payload — built-in IR-build handlers
        // (and well-behaved third-party ones) read params + body only.
        // Restore it host-side so downstream renderers have a default
        // caption / title / alt when the source carried a subject but
        // the handler emitted an empty value.
        if let Some(s) = subject.as_deref() {
            if !s.is_empty() {
                inject_subject_into_wire_node(&mut wire_node, s);
            }
        }
        if let Some(node) = from_wire_typed(&wire_node, ctx, &content) {
            return node;
        }
    }

    let parameters = verbatim
        .closing_data
        .parameters
        .iter()
        .map(|p| (p.key.clone(), p.value.clone()))
        .collect();
    DocNode::Verbatim(Verbatim {
        subject,
        subject_href,
        language,
        content,
        parameters,
    })
}

/// Expand a multi-group verbatim block into one IR `DocNode::Verbatim` per
/// group. A multi-group verbatim is always a plain code/text block (the typed
/// media/tabular hydration in [`from_lex_verbatim`] only ever applies to a
/// single-group block), so each group becomes a generic verbatim sharing the
/// block's single closing label + parameters. Without this, only the first
/// group survived the lex → IR conversion and later groups vanished from every
/// serializer's output (#769).
fn from_lex_verbatim_groups(verbatim: &LexVerbatim, ctx: &ConvCtx) -> Vec<DocNode> {
    let language = Some(verbatim.closing_data.label.value.clone());
    let parameters: Vec<(String, String)> = verbatim
        .closing_data
        .parameters
        .iter()
        .map(|p| (p.key.clone(), p.value.clone()))
        .collect();

    verbatim
        .group()
        .map(|group| {
            let subject_str = group.subject.as_string();
            let subject = if subject_str.is_empty() {
                None
            } else {
                Some(subject_str.to_string())
            };
            // A reference line can anchor each group's subject (§2.3.2), exactly
            // as for a single-group verbatim subject.
            let subject_href = ctx
                .anchors
                .match_head_line(group.subject)
                .map(|a| a.href.clone());
            let content = group
                .children
                .iter()
                .map(|item| {
                    if let LexContentItem::VerbatimLine(vl) = item {
                        vl.content.as_string().to_string()
                    } else {
                        String::new()
                    }
                })
                .collect::<Vec<_>>()
                .join("\n");
            DocNode::Verbatim(Verbatim {
                subject,
                subject_href,
                language: language.clone(),
                content,
                parameters: parameters.clone(),
            })
        })
        .collect()
}

/// Restore the verbatim subject as a default caption / title / alt on
/// hydrated media + tabular wire nodes when the handler emitted an
/// empty field. Built-in IR-build handlers read `ctx.params` + body
/// only and have no visibility into the subject line — without this
/// injection a `.lex` source like
///
/// ```text
/// Sunset Photo:
///     ...
/// :: image src=sunset.jpg ::
/// ```
///
/// loses `"Sunset Photo"` in the resulting `WireNode::Image`. Issue #595.
fn inject_subject_into_wire_node(wire_node: &mut WireNode, subject: &str) {
    match wire_node {
        WireNode::Table { caption, .. } if caption.is_empty() => {
            *caption = subject.to_string();
        }
        WireNode::Image { title, alt, .. } => {
            if title.is_none() {
                *title = Some(subject.to_string());
            }
            if alt.is_empty() {
                *alt = subject.to_string();
            }
        }
        WireNode::Video { title, .. } if title.is_none() => {
            *title = Some(subject.to_string());
        }
        WireNode::Audio { title, .. } if title.is_none() => {
            *title = Some(subject.to_string());
        }
        _ => {}
    }
}

/// Convert a typed [`WireNode`] returned from `dispatch_ir_build`
/// directly into a typed IR `DocNode`, switching on the wire variant
/// (not on the label string).
///
/// Pre-#615 this path went wire → lex-core AST (via `from_wire_node`)
/// → IR (via `from_lex_table` / `from_lex_media_verbatim`), and the
/// media branch re-dispatched on the label string to pick the right
/// hydration helper. The unified registry surface (#615) eliminates
/// both detours: a `WireNode::Image` becomes a `DocNode::Image`
/// directly, no label-string switch needed.
///
/// Returns `None` when the wire variant isn't one this builder knows
/// how to type — the caller falls back to a generic `DocNode::Verbatim`.
fn from_wire_typed(wire_node: &WireNode, ctx: &ConvCtx, fallback_content: &str) -> Option<DocNode> {
    match wire_node {
        WireNode::Table { .. } => {
            // Tables hydrate via the lex-core AST round-trip — IR's
            // Table mirrors the AST shape exactly (cells, alignment,
            // headers), and the existing `from_lex_table` converter
            // is the canonical place that knows how to consume it.
            // Switching on `WireNode::Table` (not on the label string)
            // keeps third-party `Table`-shaped wire kinds aligned with
            // the built-in path automatically.
            let items = lex_core::lex::wire::from_wire_node(wire_node).ok()?;
            let LexContentItem::Table(table) = items.into_iter().next()? else {
                return None;
            };
            Some(from_lex_table(&table, ctx))
        }
        WireNode::Image {
            src, alt, title, ..
        } => Some(DocNode::Image(Image {
            src: src.clone(),
            alt: if alt.is_empty() {
                fallback_content.trim().to_string()
            } else {
                alt.clone()
            },
            title: title.clone(),
        })),
        WireNode::Video {
            src, title, poster, ..
        } => Some(DocNode::Video(Video {
            src: src.clone(),
            title: title.clone(),
            poster: poster.clone(),
        })),
        WireNode::Audio { src, title, .. } => Some(DocNode::Audio(Audio {
            src: src.clone(),
            title: title.clone(),
        })),
        _ => None,
    }
}

/// Converts a lex annotation to an IR annotation.
fn from_lex_annotation(annotation: &LexAnnotation, level: usize, ctx: &ConvCtx) -> DocNode {
    let label = annotation.data.label.value.clone();
    let form = annotation.data.label.form;
    let parameters = annotation
        .data
        .parameters
        .iter()
        .map(|p| (p.key.clone(), p.value.clone()))
        .collect();
    let content = convert_children(&annotation.children, level, ctx);
    DocNode::Annotation(Annotation {
        label,
        parameters,
        content,
        form,
    })
}

/// Converts a standalone TextLine to an IR paragraph.
/// TextLines are typically parts of paragraphs, but can appear standalone.
fn from_lex_text_line(text_line: &LexTextLine) -> DocNode {
    let content = convert_inline_content(&text_line.content);
    DocNode::Paragraph(Paragraph { content })
}

/// Converts a VerbatimLine to an IR verbatim block.
/// VerbatimLines are typically parts of VerbatimBlocks, but can appear standalone.
/// Converts a native lex Table AST node to an IR Table node.
fn from_lex_table(table: &lex_core::lex::ast::Table, ctx: &ConvCtx) -> DocNode {
    use crate::ir::nodes::{
        Table as IrTable, TableCell as IrTableCell, TableCellAlignment as IrAlign,
        TableRow as IrTableRow,
    };

    let convert_align = |a: lex_core::lex::ast::TableCellAlignment| -> IrAlign {
        match a {
            lex_core::lex::ast::TableCellAlignment::Left => IrAlign::Left,
            lex_core::lex::ast::TableCellAlignment::Center => IrAlign::Center,
            lex_core::lex::ast::TableCellAlignment::Right => IrAlign::Right,
            lex_core::lex::ast::TableCellAlignment::None => IrAlign::None,
        }
    };

    let convert_row = |row: &lex_core::lex::ast::TableRow| -> IrTableRow {
        IrTableRow {
            cells: row
                .cells
                .iter()
                .map(|cell| {
                    let content = if cell.has_block_content() {
                        convert_children(&cell.children, 2, ctx)
                    } else {
                        vec![DocNode::Paragraph(Paragraph {
                            content: convert_inline_content(&cell.content),
                        })]
                    };
                    IrTableCell {
                        content,
                        header: cell.header,
                        align: convert_align(cell.align),
                        colspan: cell.colspan,
                        rowspan: cell.rowspan,
                    }
                })
                .collect(),
        }
    };

    let header: Vec<IrTableRow> = table.header_rows.iter().map(convert_row).collect();
    let rows: Vec<IrTableRow> = table.body_rows.iter().map(convert_row).collect();
    let caption = if table.subject.as_string().is_empty() {
        None
    } else {
        Some(convert_inline_content(&table.subject))
    };

    let footnotes = table
        .footnotes
        .as_ref()
        .map(|list| vec![from_lex_list(list, 2, ctx)])
        .unwrap_or_default();

    let fullwidth = matches!(
        table.mode,
        lex_core::lex::ast::elements::verbatim::VerbatimBlockMode::Fullwidth
    );

    DocNode::Table(IrTable {
        rows,
        header,
        caption,
        footnotes,
        fullwidth,
    })
}

fn from_lex_verbatim_line(verbatim_line: &LexVerbatimLine) -> DocNode {
    let content = verbatim_line.content.as_string().to_string();
    DocNode::Verbatim(Verbatim {
        subject: None,
        subject_href: None,
        language: None,
        content,
        parameters: Vec::new(),
    })
}

/// Detects the list decoration style from a marker.
fn detect_list_style(marker: &TextContent) -> ListStyle {
    let marker_text = marker.as_string().trim();
    if marker_text.is_empty() {
        return ListStyle::Bullet;
    }

    // Strip trailing `.` or `)` to get the label part
    let label = marker_text.trim_end_matches(['.', ')']);

    if label.is_empty() {
        return ListStyle::Bullet;
    }

    // Check for bullet markers
    if matches!(label, "-" | "*" | "+" | "–" | "—") {
        return ListStyle::Bullet;
    }

    // Check for numeric: all digits
    if label.chars().all(|c| c.is_ascii_digit()) {
        return ListStyle::Numeric;
    }

    // Check for roman numerals (uppercase)
    if label
        .chars()
        .all(|c| matches!(c, 'I' | 'V' | 'X' | 'L' | 'C' | 'D' | 'M'))
    {
        return ListStyle::RomanUpper;
    }

    // Check for roman numerals (lowercase)
    if label
        .chars()
        .all(|c| matches!(c, 'i' | 'v' | 'x' | 'l' | 'c' | 'd' | 'm'))
    {
        return ListStyle::RomanLower;
    }

    // Check for alpha (single or multi char)
    if label.chars().all(|c| c.is_ascii_uppercase()) {
        return ListStyle::AlphaUpper;
    }

    if label.chars().all(|c| c.is_ascii_lowercase()) {
        return ListStyle::AlphaLower;
    }

    // Fallback: if it has a period/paren, treat as numeric ordered
    if marker_text.contains('.') || marker_text.contains(')') {
        ListStyle::Numeric
    } else {
        ListStyle::Bullet
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use lex_core::lex::ast::elements::{
        List as LexList, ListItem as LexListItem, Paragraph as LexParagraph, Session as LexSession,
        VerbatimContent,
    };
    use lex_core::lex::ast::{ContentItem, Document as LexDocument, TextContent};

    /// Test-scope shorthand for the lex-babel default registry —
    /// every test that calls `from_lex_document` directly needs one.
    fn test_registry() -> &'static Registry {
        crate::default_registry()
    }

    /// Test-scope `ConvCtx` with an empty anchor index, for unit tests that
    /// call the internal `from_lex_*` converters directly (the public
    /// `from_lex_document` builds its own context). The leaked empty index is a
    /// `'static` borrow so the returned context can be passed by reference.
    fn test_ctx() -> ConvCtx<'static> {
        static ANCHORS: std::sync::OnceLock<AnchorIndex> = std::sync::OnceLock::new();
        ConvCtx {
            registry: test_registry(),
            anchors: ANCHORS.get_or_init(AnchorIndex::default),
        }
    }

    #[test]
    fn test_simple_paragraph_conversion() {
        let lex_para = LexParagraph::from_line("Hello world".to_string());
        let ir_node = from_lex_paragraph(&lex_para, &test_ctx());

        match ir_node {
            DocNode::Paragraph(para) => {
                assert_eq!(para.content.len(), 1);
                assert!(
                    matches!(&para.content[0], InlineContent::Text(text) if text == "Hello world")
                );
            }
            _ => panic!("Expected Paragraph node"),
        }
    }

    #[test]
    fn test_session_to_heading() {
        let session = LexSession::with_title("Test Section".to_string());
        let ir_node = from_lex_session(&session, 1, &test_ctx());

        match ir_node {
            DocNode::Heading(heading) => {
                assert_eq!(heading.level, 1);
                assert_eq!(heading.content.len(), 1);
                assert!(heading.children.is_empty());
            }
            _ => panic!("Expected Heading node"),
        }
    }

    #[test]
    fn test_list_conversion() {
        let item1 = LexListItem::new("-".to_string(), "Item 1".to_string());
        let item2 = LexListItem::new("-".to_string(), "Item 2".to_string());
        let list = LexList::new(vec![item1, item2]);

        let ir_node = from_lex_list(&list, 1, &test_ctx());

        match ir_node {
            DocNode::List(list) => {
                assert_eq!(list.items.len(), 2);
            }
            _ => panic!("Expected List node"),
        }
    }

    #[test]
    fn test_verbatim_language_extraction() {
        let subject = TextContent::from_string("".to_string(), None);
        let content = vec![VerbatimContent::VerbatimLine(LexVerbatimLine::new(
            "code here".to_string(),
        ))];
        let closing_data = lex_core::lex::ast::Data::new(
            lex_core::lex::ast::elements::Label::new("rust".to_string()),
            Vec::new(),
        );
        let verb = LexVerbatim::new(
            subject,
            content,
            closing_data,
            lex_core::lex::ast::elements::verbatim::VerbatimBlockMode::Inflow,
        );

        let ir_node = from_lex_verbatim(&verb, &test_ctx());

        match ir_node {
            DocNode::Verbatim(verb) => {
                assert_eq!(verb.language, Some("rust".to_string()));
                assert_eq!(verb.content, "code here");
            }
            _ => panic!("Expected Verbatim node"),
        }
    }

    #[test]
    fn test_blank_lines_filtered() {
        let para = ContentItem::Paragraph(LexParagraph::from_line("Test".to_string()));
        let blank = ContentItem::BlankLineGroup(lex_core::lex::ast::elements::BlankLineGroup::new(
            1,
            Vec::new(),
        ));

        let children = convert_children(&[para, blank], 1, &test_ctx());

        assert_eq!(children.len(), 1);
    }

    #[test]
    fn test_full_document_conversion() {
        let doc = LexDocument::with_content(vec![ContentItem::Paragraph(LexParagraph::from_line(
            "Test paragraph".to_string(),
        ))]);

        let ir_doc = from_lex_document(&doc, test_registry());

        assert_eq!(ir_doc.children.len(), 1);
        assert!(matches!(ir_doc.children[0], DocNode::Paragraph(_)));
    }

    /// Build a lex-core document with one document-scope annotation
    /// attached. Used by Phase 3a tests for the new
    /// `Document::document_annotations` slot.
    fn doc_with_one_annotation(label: &str, value: &str) -> LexDocument {
        use lex_core::lex::ast::elements::annotation::Annotation as LexAnnotation;
        use lex_core::lex::ast::elements::label::Label;
        use lex_core::lex::ast::elements::paragraph::Paragraph;
        use lex_core::lex::ast::elements::typed_content::ContentElement;

        let body = ContentElement::Paragraph(Paragraph::from_line(value.to_string()));
        let ann = LexAnnotation::new(Label::from_string(label), Vec::new(), vec![body]);
        let mut doc = LexDocument::new();
        doc.annotations.push(ann);
        doc
    }

    #[test]
    fn document_annotations_field_is_populated_from_lex_document() {
        // Phase 3a contract: `from_lex_document` must populate the new
        // `document_annotations: Vec<Annotation>` slot from every
        // annotation in `doc.annotations` (the lex-core
        // document-scope slot). The synthetic `frontmatter`
        // annotation that the legacy promotion inserts into
        // `children` is *additive* in Phase 3a — Phase 3b removes it.
        let doc = doc_with_one_annotation("acme.custom", "Body text.");
        let ir_doc = from_lex_document(&doc, test_registry());

        assert_eq!(
            ir_doc.document_annotations.len(),
            1,
            "one document-scope annotation must populate document_annotations"
        );
        let ann = &ir_doc.document_annotations[0];
        assert_eq!(ann.label, "acme.custom");
        assert_eq!(ann.content.len(), 1);
    }

    #[test]
    fn document_annotations_empty_when_no_document_scope_annotations() {
        // No document-scope annotations → empty slot. Phase 3a must
        // not synthesize anything here on its own.
        let doc = LexDocument::with_content(vec![ContentItem::Paragraph(LexParagraph::from_line(
            "Body only.".to_string(),
        ))]);
        let ir_doc = from_lex_document(&doc, test_registry());
        assert!(
            ir_doc.document_annotations.is_empty(),
            "empty input must produce empty document_annotations"
        );
    }

    #[test]
    fn normalize_labels_pipeline_writes_canonical_labels_into_ast() {
        // Confirm the activated `NormalizeLabels` pass produces a
        // Document whose annotations carry canonical `lex.metadata.*`
        // labels by the time `from_lex_document` sees them.
        use lex_core::lex::transforms::standard::STRING_TO_AST;

        let lex_doc = STRING_TO_AST
            .run(":: title :: My Doc\n\nBody.\n".to_string())
            .expect("parse ok");
        let title_in_ast = lex_doc
            .annotations
            .first()
            .or_else(|| {
                lex_doc.root.children.iter().find_map(|item| match item {
                    lex_core::lex::ast::ContentItem::Annotation(a) => Some(a),
                    _ => None,
                })
            })
            .expect("title annotation parsed");
        assert_eq!(title_in_ast.data.label.value, "lex.metadata.title");

        // Post-refac/label cleanup: `from_lex_document` no longer
        // synthesizes a `frontmatter` annotation in children. The
        // canonical-labelled annotation lands in
        // `document_annotations` instead; the `frontmatter` event is
        // synthesized at the events-emission layer.
        let ir = from_lex_document(&lex_doc, test_registry());
        let frontmatter_in_children = ir
            .children
            .iter()
            .any(|c| matches!(c, DocNode::Annotation(a) if a.label == "frontmatter"));
        assert!(
            !frontmatter_in_children,
            "frontmatter must no longer be synthesized in children"
        );
    }

    /// Issue #595 regression: the subject line on a media / tabular
    /// verbatim must survive the `on_resolve` dispatch as a default
    /// caption / title / alt. Built-in resolve handlers don't read
    /// `ctx.subject` (it isn't on the ctx), so the host has to inject
    /// it after the wire roundtrip.
    #[test]
    fn verbatim_subject_becomes_image_title_when_handler_left_it_empty() {
        let subject = TextContent::from_string("Sunset Photo".to_string(), None);
        let label = lex_core::lex::ast::elements::Label::new("lex.media.image".to_string());
        let parameters = vec![lex_core::lex::ast::Parameter {
            key: "src".to_string(),
            value: "sunset.jpg".to_string(),
            location: lex_core::lex::ast::Range::default(),
        }];
        let closing_data = lex_core::lex::ast::Data::new(label, parameters);
        let verb = LexVerbatim::new(
            subject,
            Vec::new(),
            closing_data,
            lex_core::lex::ast::elements::verbatim::VerbatimBlockMode::Inflow,
        );
        let ir_node = from_lex_verbatim(&verb, &test_ctx());
        match ir_node {
            DocNode::Image(image) => {
                assert_eq!(image.src, "sunset.jpg");
                assert_eq!(
                    image.title.as_deref(),
                    Some("Sunset Photo"),
                    "subject must be restored as the image title"
                );
            }
            other => panic!("expected DocNode::Image, got {other:?}"),
        }
    }

    #[test]
    fn verbatim_subject_becomes_table_caption_when_handler_left_it_empty() {
        let subject = TextContent::from_string("Quarterly results".to_string(), None);
        let content = vec![
            VerbatimContent::VerbatimLine(LexVerbatimLine::new("| Q1 | Q2 |".to_string())),
            VerbatimContent::VerbatimLine(LexVerbatimLine::new("| -- | -- |".to_string())),
            VerbatimContent::VerbatimLine(LexVerbatimLine::new("| 10 | 20 |".to_string())),
        ];
        let closing_data = lex_core::lex::ast::Data::new(
            lex_core::lex::ast::elements::Label::new("lex.tabular.table".to_string()),
            Vec::new(),
        );
        let verb = LexVerbatim::new(
            subject,
            content,
            closing_data,
            lex_core::lex::ast::elements::verbatim::VerbatimBlockMode::Inflow,
        );
        let ir_node = from_lex_verbatim(&verb, &test_ctx());
        match ir_node {
            DocNode::Table(table) => {
                let caption = table
                    .caption
                    .as_ref()
                    .map(|inlines| {
                        inlines
                            .iter()
                            .filter_map(|inline| match inline {
                                crate::ir::nodes::InlineContent::Text(t) => Some(t.as_str()),
                                _ => None,
                            })
                            .collect::<String>()
                    })
                    .unwrap_or_default();
                assert_eq!(
                    caption, "Quarterly results",
                    "subject must be restored as the table caption"
                );
            }
            other => panic!("expected DocNode::Table, got {other:?}"),
        }
    }

    #[test]
    fn verbatim_subject_does_not_overwrite_handler_set_image_title() {
        // When the user wrote both a subject AND an explicit `title=`
        // parameter, the param wins — the subject is only a fallback
        // for empty fields.
        let subject = TextContent::from_string("Subject Wins?".to_string(), None);
        let label = lex_core::lex::ast::elements::Label::new("lex.media.image".to_string());
        let parameters = vec![
            lex_core::lex::ast::Parameter {
                key: "src".to_string(),
                value: "x.jpg".to_string(),
                location: lex_core::lex::ast::Range::default(),
            },
            lex_core::lex::ast::Parameter {
                key: "title".to_string(),
                value: "Param Wins".to_string(),
                location: lex_core::lex::ast::Range::default(),
            },
        ];
        let closing_data = lex_core::lex::ast::Data::new(label, parameters);
        let verb = LexVerbatim::new(
            subject,
            Vec::new(),
            closing_data,
            lex_core::lex::ast::elements::verbatim::VerbatimBlockMode::Inflow,
        );
        let ir_node = from_lex_verbatim(&verb, &test_ctx());
        match ir_node {
            DocNode::Image(image) => {
                assert_eq!(image.title.as_deref(), Some("Param Wins"));
            }
            other => panic!("expected DocNode::Image, got {other:?}"),
        }
    }

    #[test]
    fn document_annotations_is_source_of_truth_for_doc_metadata() {
        // Post-refac/label cleanup: document-scope metadata flows
        // through `document_annotations` only — the legacy
        // `frontmatter` synthesis in children is gone.
        let doc = doc_with_one_annotation("author", "Alice");
        let ir_doc = from_lex_document(&doc, test_registry());

        // The new slot carries the annotation.
        assert_eq!(ir_doc.document_annotations.len(), 1);
        assert_eq!(ir_doc.document_annotations[0].label, "author");

        // Children no longer carry a synthetic frontmatter annotation.
        let frontmatter_in_children = ir_doc
            .children
            .iter()
            .any(|c| matches!(c, DocNode::Annotation(a) if a.label == "frontmatter"));
        assert!(
            !frontmatter_in_children,
            "synthetic frontmatter must not appear in children after cleanup"
        );
    }

    /// #615: `from_lex_verbatim` migrated from `dispatch_resolve` to
    /// `dispatch_ir_build`. The end-to-end behaviour for built-in
    /// verbatim labels (table, image, video, audio) must be unchanged
    /// — same typed IR nodes produced from the same Lex source.
    #[test]
    fn ir_build_dispatch_hydrates_table_verbatim_to_typed_table() {
        let subject = TextContent::from_string("Sales".to_string(), None);
        let body = vec![
            VerbatimContent::VerbatimLine(LexVerbatimLine::new("| q | r |".to_string())),
            VerbatimContent::VerbatimLine(LexVerbatimLine::new("|---|---|".to_string())),
            VerbatimContent::VerbatimLine(LexVerbatimLine::new("| 7 | 9 |".to_string())),
        ];
        let closing_data = lex_core::lex::ast::Data::new(
            lex_core::lex::ast::elements::Label::new("lex.tabular.table".to_string()),
            Vec::new(),
        );
        let verb = LexVerbatim::new(
            subject,
            body,
            closing_data,
            lex_core::lex::ast::elements::verbatim::VerbatimBlockMode::Inflow,
        );
        match from_lex_verbatim(&verb, &test_ctx()) {
            DocNode::Table(_) => {}
            other => panic!(
                "table verbatim must hydrate via dispatch_ir_build to DocNode::Table; got {other:?}"
            ),
        }
    }

    /// #615: `from_wire_typed` switches on the WireNode kind directly
    /// instead of re-dispatching on the label string. A `lex.media.video`
    /// hydration produces a typed `DocNode::Video`, populated from the
    /// wire node's typed fields (no params HashMap detour).
    #[test]
    fn ir_build_dispatch_hydrates_video_via_wire_kind_switch() {
        let subject = TextContent::from_string("".to_string(), None);
        let label = lex_core::lex::ast::elements::Label::new("lex.media.video".to_string());
        let parameters = vec![
            lex_core::lex::ast::Parameter {
                key: "src".to_string(),
                value: "intro.mp4".to_string(),
                location: lex_core::lex::ast::Range::default(),
            },
            lex_core::lex::ast::Parameter {
                key: "poster".to_string(),
                value: "intro.png".to_string(),
                location: lex_core::lex::ast::Range::default(),
            },
        ];
        let closing_data = lex_core::lex::ast::Data::new(label, parameters);
        let verb = LexVerbatim::new(
            subject,
            Vec::new(),
            closing_data,
            lex_core::lex::ast::elements::verbatim::VerbatimBlockMode::Inflow,
        );
        match from_lex_verbatim(&verb, &test_ctx()) {
            DocNode::Video(video) => {
                assert_eq!(video.src, "intro.mp4");
                assert_eq!(video.poster.as_deref(), Some("intro.png"));
            }
            other => panic!("expected DocNode::Video, got {other:?}"),
        }
    }

    /// #615: `from_wire_typed` returns `None` for wire variants it
    /// doesn't know how to type (third-party verbatim labels with no
    /// IR-build hook, or hooks returning non-media/non-table wire
    /// kinds), and the caller falls back to a generic `DocNode::Verbatim`.
    /// This pins the fallback path so a future wire-spec addition
    /// can't silently produce `Verbatim`-with-empty-content.
    #[test]
    fn unhandled_label_falls_back_to_generic_verbatim() {
        let subject = TextContent::from_string("".to_string(), None);
        let body = vec![VerbatimContent::VerbatimLine(LexVerbatimLine::new(
            "raw body".to_string(),
        ))];
        let closing_data = lex_core::lex::ast::Data::new(
            // Community-shape label — no built-in handler, no IR-build
            // dispatch. The from_lex_verbatim path falls through to
            // the generic Verbatim IR node.
            lex_core::lex::ast::elements::Label::new("acme.unknown".to_string()),
            Vec::new(),
        );
        let verb = LexVerbatim::new(
            subject,
            body,
            closing_data,
            lex_core::lex::ast::elements::verbatim::VerbatimBlockMode::Inflow,
        );
        match from_lex_verbatim(&verb, &test_ctx()) {
            DocNode::Verbatim(v) => {
                assert_eq!(v.content, "raw body");
                assert_eq!(v.language.as_deref(), Some("acme.unknown"));
            }
            other => {
                panic!("unrouted verbatim label must fall back to generic Verbatim; got {other:?}")
            }
        }
    }

    /// #615: `doc.*` schemas are registered in the default registry
    /// and accessible via `schema_for`. End-to-end check that the
    /// six built-in canonicals all surface via `Registry::schema_for`
    /// from the lex-babel default registry (the one most callers use).
    #[test]
    fn default_registry_carries_doc_metadata_schemas() {
        let r = test_registry();
        for label in [
            "doc.title",
            "doc.author",
            "doc.date",
            "doc.tags",
            "doc.category",
            "doc.template",
        ] {
            let schema = r
                .schema_for(label)
                .unwrap_or_else(|| panic!("default registry must carry {label}"));
            assert_eq!(schema.label, label);
            // Each doc.* declares both markdown + html render hooks
            // so the unified surface can fire them at serialisation
            // time (Sub D wires the consumer side).
            let formats: Vec<&str> = schema.hooks.render.iter().map(|h| h.0.as_str()).collect();
            assert!(
                formats.contains(&"markdown") && formats.contains(&"html"),
                "{label} must declare markdown + html render hooks; got {formats:?}"
            );
        }
    }

    /// #615: the `doc.*` namespace dispatches through the unified
    /// render surface and produces format-specific text.
    #[test]
    fn doc_render_dispatch_emits_markdown_yaml_line_via_unified_surface() {
        use lex_extension::wire::{AnnotationBody, Format, NodeRef, Position, Range, RenderOut};
        let r = test_registry();
        let ctx = lex_extension::wire::LabelCtx {
            label: "doc.author".into(),
            params: serde_json::Value::Null,
            body: AnnotationBody::Text("Alice".into()),
            node: NodeRef {
                kind: "document".into(),
                range: Range {
                    start: Position(0, 0),
                    end: Position(0, 0),
                },
                origin: None,
            },
        };
        let out = r
            .dispatch_render(&ctx, Format::Markdown)
            .expect("dispatch_render ok")
            .expect("doc.author must produce a rendered output");
        match out {
            RenderOut::String { string } => assert_eq!(string, "author: \"Alice\"\n"),
            other => panic!("expected String, got {other:?}"),
        }
    }

    // ========================================================================
    // SELF-LINK SPLICING (references-general.lex §2.3.2 — #720 fixups #5)
    // ========================================================================

    use lex_core::lex::transforms::standard::STRING_TO_AST;

    /// Flatten an IR paragraph's first inline into its link href, if any.
    fn paragraph_link_href(node: &DocNode) -> Option<&str> {
        if let DocNode::Paragraph(p) = node {
            if let Some(InlineContent::Link { href, .. }) = p.content.first() {
                return Some(href.as_str());
            }
        }
        None
    }

    /// #5(a): a self-link after a paragraph that itself carries an attached
    /// annotation must splice *after* the paragraph (and its expanded annotation
    /// IR node), not between them. With the old structural-slot indexing the
    /// self-link landed one slot too early and split the paragraph from its
    /// annotation.
    #[test]
    fn self_link_after_paragraph_with_attached_annotation_lands_after_it() {
        // The annotation `:: note ::` attaches to "Anchored paragraph." (no blank
        // line between them); the self-link follows after a blank line.
        let src = "First paragraph.\n\n:: note ::\n    A side note.\nAnchored paragraph.\n\n[https://after.example]\n\nTrailing paragraph.\n";
        let doc = STRING_TO_AST.run(src.to_string()).expect("parse ok");
        let ir = from_lex_document(&doc, test_registry());

        // Locate the self-link paragraph.
        let sl_pos = ir
            .children
            .iter()
            .position(|c| paragraph_link_href(c) == Some("https://after.example"))
            .expect("self-link paragraph must be present");

        // The node immediately before the self-link must be the anchored
        // paragraph's own content ("Anchored paragraph."), proving the link did
        // not slip between the annotation and the paragraph it annotates.
        let before = &ir.children[sl_pos - 1];
        let before_is_anchored_para = matches!(
            before,
            DocNode::Paragraph(p) if p.content.iter().any(|c| matches!(c, InlineContent::Text(t) if t.contains("Anchored paragraph")))
        );
        assert!(
            before_is_anchored_para,
            "self-link must follow the annotated paragraph, not split it from its annotation; got {before:?}"
        );

        // And the annotation IR node still precedes that paragraph.
        let annotation_before_para = ir.children[..sl_pos]
            .iter()
            .any(|c| matches!(c, DocNode::Annotation(a) if a.label == "note"));
        assert!(
            annotation_before_para,
            "the attached annotation must remain ahead of its paragraph"
        );
    }

    /// #5(b): a self-link nested inside a list item's body must be spliced into
    /// that list item's children, not at the document top level.
    #[test]
    fn self_link_nested_in_list_item_lands_in_that_item() {
        let src =
            "Intro.\n\n- First item\n    Nested body.\n\n    [https://nested.example]\n- Second item\n\nDone.\n";
        let doc = STRING_TO_AST.run(src.to_string()).expect("parse ok");
        let ir = from_lex_document(&doc, test_registry());

        // The self-link must NOT appear at the document top level.
        let at_top = ir
            .children
            .iter()
            .any(|c| paragraph_link_href(c) == Some("https://nested.example"));
        assert!(
            !at_top,
            "nested self-link must not be spliced at the document top level"
        );

        // It must appear inside the first list item's children.
        let list = ir
            .children
            .iter()
            .find_map(|c| match c {
                DocNode::List(l) => Some(l),
                _ => None,
            })
            .expect("a list must be present");
        let first_item = list.items.first().expect("list has a first item");
        let nested = first_item
            .children
            .iter()
            .any(|c| paragraph_link_href(c) == Some("https://nested.example"));
        assert!(
            nested,
            "nested self-link must be spliced into the first list item's children; got {:?}",
            first_item.children
        );
    }
}