lex-babel 0.18.1

//! HTML serialization (Lex → HTML export)
//!
//! Converts Lex documents to semantic HTML5 with embedded CSS.
//! Pipeline: Lex AST → IR → Events → RcDom → HTML string

use crate::common::nested_to_flat::tree_to_events;
use crate::common::splice::{SentinelBuffer, SpliceState};
use crate::error::FormatError;
use crate::formats::html::HtmlTheme;
use crate::ir::events::Event;
use crate::ir::nodes::{DocNode, InlineContent, TableCellAlignment};
use html5ever::{
    ns, serialize, serialize::SerializeOpts, serialize::TraversalScope, Attribute, LocalName,
    QualName,
};
use lex_core::lex::ast::Document;
use markup5ever_rcdom::{Handle, Node, NodeData, RcDom, SerializableHandle};
use std::cell::{Cell, RefCell};
use std::default::Default;
use std::rc::Rc;

/// Options for HTML serialization
#[derive(Debug, Clone, Default)]
pub struct HtmlOptions {
    /// CSS theme to use
    pub theme: HtmlTheme,
    /// Optional custom CSS to append after the baseline and theme CSS
    pub custom_css: Option<String>,
}

impl HtmlOptions {
    pub fn new(theme: HtmlTheme) -> Self {
        Self {
            theme,
            custom_css: None,
        }
    }

    pub fn with_custom_css(mut self, css: String) -> Self {
        self.custom_css = Some(css);
        self
    }
}

/// Serialize a Lex document to HTML with the given theme
pub fn serialize_to_html(doc: &Document, theme: HtmlTheme) -> Result<String, FormatError> {
    serialize_to_html_with_options(doc, HtmlOptions::new(theme))
}

/// Serialize with an extension-system [`Registry`] in scope: every
/// labelled annotation / verbatim whose schema declares
/// `hooks.render: ["html"]` is dispatched to its handler. Handler
/// diagnostics (errors, format-shape mismatches, namespace disabled)
/// surface in the returned [`HtmlExportOutcome::diagnostics`].
///
/// For annotations whose handler returns `RenderOut::String`, the
/// handler's HTML is spliced into the output in place of the
/// annotation's default rendering (the `<!-- lex:label -->` ...
/// `<!-- /lex:label -->` comment pair plus any content events
/// between them). Handlers returning `RenderOut::WireAst` or
/// `Ok(None)` fall through to the default rendering — wire-AST →
/// HTML conversion is a follow-up.
///
/// Splice mechanism: post-#617 the splice state lives in
/// [`crate::common::splice::SpliceState`]; this entry point just
/// constructs one with the body slice of the plan and threads it
/// through the event walker. Markdown reuses the same helper.
///
/// Phase 3b of #614 made doc-scope annotations IR-only — they don't
/// flow through the event stream. To keep the body splice aligned,
/// this entry point slices `plan.doc_scope_count` entries off the
/// front before handing the plan to the splice walker. Doc-scope
/// handler outputs are therefore unspliced today; their diagnostics
/// still surface in the returned `HtmlExportOutcome`. Routing them
/// back into the rendered HTML is a separate follow-up.
pub fn serialize_to_html_with_registry(
    doc: &Document,
    options: HtmlOptions,
    registry: &lex_extension_host::Registry,
) -> Result<HtmlExportOutcome, FormatError> {
    // Build the IR through the caller's registry so third-party
    // `on_ir_build` hooks (verbatim-label hydration etc.) participate
    // in IR construction. Otherwise the IR `dispatch_render` walks
    // would diverge from what the same registry expects to see.
    let ir_doc = crate::to_ir_with_registry(doc, registry);
    let plan = crate::render_dispatch::dispatch_render(&ir_doc, registry, "html");
    // Phase 3b of #614: skip the doc-scope prefix of the plan when
    // feeding the event-indexed splice walker. The event stream
    // doesn't contain events for `document_annotations`, so doc-scope
    // plan entries would otherwise shift the index and route their
    // handler HTML into the wrong body-annotation slot.
    let body_plan = &plan.nodes[plan.doc_scope_count..];
    let html = serialize_to_html_with_splice_from_ir(ir_doc, options, Some(body_plan))?;
    let mut diagnostics = plan
        .nodes
        .iter()
        .filter_map(|n| n.diagnostic.clone())
        .collect::<Vec<_>>();
    diagnostics.extend(plan.root_diagnostics);
    Ok(HtmlExportOutcome { html, diagnostics })
}

/// Internal helper: serialize with an optional splice plan. When
/// `splice_plan` is `None` this is identical to
/// [`serialize_to_html_with_options`]; when `Some(&plan)` it threads
/// the plan through the DOM builder and the post-process replacement
/// step.
fn serialize_to_html_with_splice(
    doc: &Document,
    options: HtmlOptions,
    splice_plan: Option<&[crate::render_dispatch::RenderedNode]>,
) -> Result<String, FormatError> {
    let ir_doc = crate::to_ir(doc);
    serialize_to_html_with_splice_from_ir(ir_doc, options, splice_plan)
}

/// Splice-aware HTML serialization driven by an already-built IR
/// document. Used by [`serialize_to_html_with_registry`] so the IR
/// isn't built twice — once for dispatch and once for serialization.
fn serialize_to_html_with_splice_from_ir(
    ir_doc: crate::ir::nodes::Document,
    options: HtmlOptions,
    splice_plan: Option<&[crate::render_dispatch::RenderedNode]>,
) -> Result<String, FormatError> {
    let title_text = ir_doc
        .title
        .as_ref()
        .map(|t| crate::ir::to_wire::inlines_to_text(t));
    let subtitle_text = ir_doc
        .subtitle
        .as_ref()
        .map(|s| crate::ir::to_wire::inlines_to_text(s));

    let head_title = match (&title_text, &subtitle_text) {
        (Some(t), Some(s)) => format!("{t}: {s}"),
        (Some(t), None) => t.clone(),
        (None, _) => "Lex Document".to_string(),
    };

    let events = tree_to_events(&DocNode::Document(ir_doc));

    // rcdom has no raw-HTML node, so the event walker plants sentinel
    // comments and `SentinelBuffer::replace` substitutes the
    // handler's raw HTML after `serialize_dom`. Markdown's path
    // doesn't need this — Comrak's `NodeValue::HtmlBlock` carries
    // raw passthrough natively.
    let mut sentinels = SentinelBuffer::new();
    let (dom, has_math) = build_html_dom_with_splice(&events, splice_plan, &mut sentinels)?;

    let html_string = serialize_dom(&dom)?;
    let html_string = sentinels.replace(&html_string);

    wrap_in_document(
        &html_string,
        &head_title,
        title_text.as_deref(),
        subtitle_text.as_deref(),
        has_math,
        &options,
    )
}

/// Result of [`serialize_to_html_with_registry`]: the rendered HTML
/// plus any handler-emitted diagnostic messages (renderer errors,
/// format-shape mismatches, namespace disabled).
#[derive(Debug, Clone, PartialEq)]
pub struct HtmlExportOutcome {
    pub html: String,
    pub diagnostics: Vec<String>,
}

/// Serialize a Lex document to HTML with full options
pub fn serialize_to_html_with_options(
    doc: &Document,
    options: HtmlOptions,
) -> Result<String, FormatError> {
    serialize_to_html_with_splice(doc, options, None)
}

/// Build an HTML DOM tree from IR events, optionally splicing
/// handler-rendered HTML in place of default annotation rendering.
///
/// When `splice_plan` is `Some(&plan)`, the splice state machine in
/// [`SpliceState`] tracks the alignment with the dispatch walker's
/// plan order; on entries with output, the walker registers a
/// sentinel comment in `sentinels` and the post-process step in
/// [`serialize_to_html_with_splice_from_ir`] substitutes it for the
/// handler's raw HTML.
///
/// When `splice_plan` is `None`, the builder behaves exactly as it
/// did before the splice landing.
///
/// Returns the constructed DOM and a `has_math` flag indicating whether any
/// `InlineContent::Math` was encountered during the walk. The caller uses
/// the flag to decide whether to inject the KaTeX renderer into the document
/// head — tracking it here is more reliable than scanning the serialized
/// HTML for the math class string, which can false-positive when a verbatim
/// code block happens to contain that text.
fn build_html_dom_with_splice(
    events: &[Event],
    splice_plan: Option<&[crate::render_dispatch::RenderedNode]>,
    sentinels: &mut SentinelBuffer,
) -> Result<(RcDom, bool), FormatError> {
    let dom = RcDom::default();

    // Create document container
    let doc_container = create_element("div", vec![("class", "lex-document")]);

    let mut current_parent: Handle = doc_container.clone();
    let mut parent_stack: Vec<Handle> = vec![];

    // State for collecting verbatim content
    let mut in_verbatim = false;
    let mut verbatim_language: Option<String> = None;
    let mut verbatim_content = String::new();

    // State for heading context
    let mut current_heading: Option<Handle> = None;

    // Splice state machine — counter + skip-depth — lives in the
    // shared helper. The HTML callback below converts the helper's
    // raw-passthrough string into a sentinel comment via `sentinels`,
    // and `serialize_to_html_with_splice_from_ir` substitutes after
    // DOM serialization.
    let mut splice = SpliceState::new(splice_plan);

    // Consecutive Definition siblings share one `<dl>`. After `EndDefinition`
    // we leave `current_parent` pointing at the open `<dl>` and set this
    // flag; the next event either reuses the dl (another Definition) or
    // closes it (anything else).
    let mut defer_close_dl: bool = false;

    // Set by `add_inline_to_node` whenever it processes an `InlineContent::Math`.
    // The outer serializer consults this to decide whether to inject KaTeX into
    // the document head; tracking it during construction avoids the fragility
    // of a substring scan over the serialized HTML (which can false-positive on
    // verbatim code blocks that happen to contain `class="lex-math"`).
    let mut has_math: bool = false;

    for event in events {
        // Inside a splice skip region, only Start/EndAnnotation
        // events are inspected — for nesting depth and counter
        // bookkeeping. All other events are suppressed so the
        // handler's output stands alone.
        if splice.should_skip()
            && !matches!(
                event,
                Event::StartAnnotation { .. } | Event::EndAnnotation { .. }
            )
        {
            continue;
        }
        // If we have a `<dl>` waiting to be closed and the next event
        // isn't another Definition, close it now before handling the event.
        if defer_close_dl && !matches!(event, Event::StartDefinition) {
            current_parent = parent_stack.pop().ok_or_else(|| {
                FormatError::SerializationError(
                    "Failed to close deferred definition list".to_string(),
                )
            })?;
            defer_close_dl = false;
        }
        match event {
            Event::StartDocument => {
                // Already created doc_container
            }

            Event::EndDocument => {
                // Done
            }

            Event::StartHeading(level) => {
                // Create section wrapper for this session
                let class = format!("lex-session lex-session-{level}");
                let section = create_element("section", vec![("class", &class)]);
                current_parent.children.borrow_mut().push(section.clone());
                parent_stack.push(current_parent.clone());
                current_parent = section;

                // Create heading element (h1-h6, max at h6)
                // For levels > 6, add class attribute to preserve true depth
                let clamped = (*level as u8).min(6);
                let heading_tag = format!("h{clamped}");
                let heading = if *level > 6 {
                    let class = format!("lex-level-{level}");
                    create_element(&heading_tag, vec![("class", &class)])
                } else {
                    create_element(&heading_tag, vec![])
                };
                current_parent.children.borrow_mut().push(heading.clone());
                current_heading = Some(heading);
            }

            Event::EndHeading(_) => {
                current_heading = None;
                // Close section
                current_parent = parent_stack.pop().ok_or_else(|| {
                    FormatError::SerializationError("Unbalanced heading end".to_string())
                })?;
            }

            Event::StartContent => {
                // Create content wrapper (mirrors AST container structure for indentation).
                //
                // Inside a parent element that is ALREADY a semantic content
                // area, the wrapper is pure DOM bloat — two stacked containers
                // carrying the same "this is content" cue. Skip it for those
                // parents and push the parent onto the stack so EndContent's
                // pop is balanced and leaves current_parent pointing back at
                // the same element.
                //
                // - `<dd>`      — #604: the dd is already the content holder
                //                 for a definition body.
                // - `<section>` — #610 (option 1): after a heading the section
                //                 is the semantic content container; the
                //                 wrapper is redundant.
                current_heading = None;
                let parent_is_content_area = is_element_with_tag(&current_parent, "dd")
                    || is_element_with_tag(&current_parent, "section");
                if parent_is_content_area {
                    parent_stack.push(current_parent.clone());
                } else {
                    let content = create_element("div", vec![("class", "lex-content")]);
                    current_parent.children.borrow_mut().push(content.clone());
                    parent_stack.push(current_parent.clone());
                    current_parent = content;
                }
            }

            Event::EndContent => {
                // Close content wrapper
                current_parent = parent_stack.pop().ok_or_else(|| {
                    FormatError::SerializationError("Unbalanced content end".to_string())
                })?;
            }

            Event::StartParagraph => {
                // Paragraphs directly inside `<dd>` drop the redundant
                // `class="lex-paragraph"` — CSS can target `dd > p` instead (#604).
                current_heading = None;
                let para = if is_element_with_tag(&current_parent, "dd") {
                    create_element("p", vec![])
                } else {
                    create_element("p", vec![("class", "lex-paragraph")])
                };
                current_parent.children.borrow_mut().push(para.clone());
                parent_stack.push(current_parent.clone());
                current_parent = para;
            }

            Event::EndParagraph => {
                current_parent = parent_stack.pop().ok_or_else(|| {
                    FormatError::SerializationError("Unbalanced paragraph end".to_string())
                })?;
            }

            Event::StartList { ordered, style, .. } => {
                current_heading = None;
                let tag = if *ordered { "ol" } else { "ul" };
                // For ordered lists, set the HTML type attribute to preserve decoration style
                let list = match style {
                    crate::ir::nodes::ListStyle::AlphaLower => {
                        create_element(tag, vec![("class", "lex-list"), ("type", "a")])
                    }
                    crate::ir::nodes::ListStyle::AlphaUpper => {
                        create_element(tag, vec![("class", "lex-list"), ("type", "A")])
                    }
                    crate::ir::nodes::ListStyle::RomanLower => {
                        create_element(tag, vec![("class", "lex-list"), ("type", "i")])
                    }
                    crate::ir::nodes::ListStyle::RomanUpper => {
                        create_element(tag, vec![("class", "lex-list"), ("type", "I")])
                    }
                    _ => create_element(tag, vec![("class", "lex-list")]),
                };
                current_parent.children.borrow_mut().push(list.clone());
                parent_stack.push(current_parent.clone());
                current_parent = list;
            }

            Event::EndList => {
                current_parent = parent_stack.pop().ok_or_else(|| {
                    FormatError::SerializationError("Unbalanced list end".to_string())
                })?;
            }

            Event::StartListItem => {
                current_heading = None;
                let item = create_element("li", vec![("class", "lex-list-item")]);
                current_parent.children.borrow_mut().push(item.clone());
                parent_stack.push(current_parent.clone());
                current_parent = item;
            }

            Event::EndListItem => {
                current_parent = parent_stack.pop().ok_or_else(|| {
                    FormatError::SerializationError("Unbalanced list item end".to_string())
                })?;
            }

            Event::StartVerbatim {
                language,
                subject,
                subject_href,
                parameters: _,
            } => {
                current_heading = None;
                in_verbatim = true;
                verbatim_language = language.clone();
                verbatim_content.clear();

                // Render subject as a caption before the code block. A reference
                // line can anchor the subject (references-general.lex §2.3.2):
                // when `subject_href` is set, the caption text is wrapped in a
                // link to that target.
                if let Some(subj) = subject {
                    let caption = create_element("div", vec![("class", "lex-verbatim-subject")]);
                    if let Some(href) = subject_href {
                        let anchor = create_element("a", vec![("href", href)]);
                        anchor.children.borrow_mut().push(create_text(subj));
                        caption.children.borrow_mut().push(anchor);
                    } else {
                        caption.children.borrow_mut().push(create_text(subj));
                    }
                    current_parent.children.borrow_mut().push(caption);
                }
            }

            Event::EndVerbatim => {
                // Check for special metadata comment format
                if let Some(ref lang) = verbatim_language {
                    if let Some(label) = lang.strip_prefix("lex-metadata:") {
                        // Render as comment
                        let comment_text = format!(" lex:{label}{verbatim_content}");
                        let comment_node = create_comment(&comment_text);
                        current_parent.children.borrow_mut().push(comment_node);

                        in_verbatim = false;
                        verbatim_language = None;
                        verbatim_content.clear();
                        continue; // Skip normal verbatim handling
                    }
                }

                // Create pre + code block with highlight.js-compatible classes
                let normalized_lang;
                let mut pre_attrs = vec![("class", "lex-verbatim")];
                let lang_string;
                if let Some(ref lang) = verbatim_language {
                    lang_string = lang.clone();
                    pre_attrs.push(("data-language", &lang_string));
                    normalized_lang = Some(format!("language-{}", normalize_language(lang)));
                } else {
                    normalized_lang = None;
                }

                let pre = create_element("pre", pre_attrs);
                let code_attrs = match normalized_lang {
                    Some(ref class) => vec![("class", class.as_str())],
                    None => vec![],
                };
                let code = create_element("code", code_attrs);
                let text = create_text(&verbatim_content);
                code.children.borrow_mut().push(text);
                pre.children.borrow_mut().push(code);
                current_parent.children.borrow_mut().push(pre);

                in_verbatim = false;
                verbatim_language = None;
                verbatim_content.clear();
            }

            Event::StartDefinition => {
                current_heading = None;
                if defer_close_dl {
                    // Previous Definition just ended at the same level; keep
                    // using its `<dl>` so sibling defs share one container.
                    defer_close_dl = false;
                } else {
                    let dl = create_element("dl", vec![("class", "lex-definition")]);
                    current_parent.children.borrow_mut().push(dl.clone());
                    parent_stack.push(current_parent.clone());
                    current_parent = dl;
                }
            }

            Event::EndDefinition => {
                // Defer the `<dl>` close so that an immediately-following
                // sibling Definition can reuse this container.
                defer_close_dl = true;
            }

            Event::StartDefinitionTerm => {
                let dt = create_element("dt", vec![]);
                current_parent.children.borrow_mut().push(dt.clone());
                parent_stack.push(current_parent.clone());
                current_parent = dt;
            }

            Event::EndDefinitionTerm => {
                current_parent = parent_stack.pop().ok_or_else(|| {
                    FormatError::SerializationError("Unbalanced definition term end".to_string())
                })?;
            }

            Event::StartDefinitionDescription => {
                let dd = create_element("dd", vec![]);
                current_parent.children.borrow_mut().push(dd.clone());
                parent_stack.push(current_parent.clone());
                current_parent = dd;
            }

            Event::EndDefinitionDescription => {
                current_parent = parent_stack.pop().ok_or_else(|| {
                    FormatError::SerializationError(
                        "Unbalanced definition description end".to_string(),
                    )
                })?;
            }

            Event::StartTable { caption, fullwidth } => {
                current_heading = None;
                let mut table_attrs = vec![("class", "lex-table")];
                let fullwidth_class;
                if *fullwidth {
                    fullwidth_class = "lex-table lex-table-fullwidth".to_string();
                    table_attrs = vec![("class", &fullwidth_class)];
                }
                let table = create_element("table", table_attrs);

                // Render caption if present
                if let Some(caption_inlines) = caption {
                    let caption_el = create_element("caption", vec![]);
                    for inline in caption_inlines {
                        add_inline_to_node(&caption_el, inline, &mut has_math)?;
                    }
                    table.children.borrow_mut().push(caption_el);
                }

                current_parent.children.borrow_mut().push(table.clone());
                parent_stack.push(current_parent.clone());
                current_parent = table;
            }

            Event::EndTable => {
                current_parent = parent_stack.pop().ok_or_else(|| {
                    FormatError::SerializationError("Unbalanced table end".to_string())
                })?;
            }

            Event::StartTableFootnotes => {
                let footer = create_element("tfoot", vec![("class", "lex-table-footnotes")]);
                current_parent.children.borrow_mut().push(footer.clone());
                parent_stack.push(current_parent.clone());
                current_parent = footer;
            }

            Event::EndTableFootnotes => {
                current_parent = parent_stack.pop().ok_or_else(|| {
                    FormatError::SerializationError("Unbalanced table footnotes end".to_string())
                })?;
            }

            Event::StartTableRow { header: _ } => {
                let tr = create_element("tr", vec![]);
                current_parent.children.borrow_mut().push(tr.clone());
                parent_stack.push(current_parent.clone());
                current_parent = tr;
            }

            Event::EndTableRow => {
                current_parent = parent_stack.pop().ok_or_else(|| {
                    FormatError::SerializationError("Unbalanced table row end".to_string())
                })?;
            }

            Event::StartTableCell {
                header,
                align,
                colspan,
                rowspan,
            } => {
                let tag = if *header { "th" } else { "td" };
                let mut attrs: Vec<(&str, String)> = vec![];
                match align {
                    TableCellAlignment::Left => {
                        attrs.push(("style", "text-align: left".to_string()))
                    }
                    TableCellAlignment::Right => {
                        attrs.push(("style", "text-align: right".to_string()))
                    }
                    TableCellAlignment::Center => {
                        attrs.push(("style", "text-align: center".to_string()))
                    }
                    TableCellAlignment::None => {}
                }
                if *colspan > 1 {
                    attrs.push(("colspan", colspan.to_string()));
                }
                if *rowspan > 1 {
                    attrs.push(("rowspan", rowspan.to_string()));
                }

                let str_attrs: Vec<(&str, &str)> =
                    attrs.iter().map(|(k, v)| (*k, v.as_str())).collect();
                let cell = create_element(tag, str_attrs);
                current_parent.children.borrow_mut().push(cell.clone());
                parent_stack.push(current_parent.clone());
                current_parent = cell;
            }

            Event::EndTableCell => {
                current_parent = parent_stack.pop().ok_or_else(|| {
                    FormatError::SerializationError("Unbalanced table cell end".to_string())
                })?;
            }

            Event::Inline(inline_content) => {
                if in_verbatim {
                    // Accumulate verbatim content
                    if let InlineContent::Text(text) = inline_content {
                        verbatim_content.push_str(text);
                    }
                } else if let Some(ref heading) = current_heading {
                    // Add to heading
                    add_inline_to_node(heading, inline_content, &mut has_math)?;
                } else {
                    // Add to current parent
                    add_inline_to_node(&current_parent, inline_content, &mut has_math)?;
                }
            }

            Event::StartAnnotation {
                label, parameters, ..
            } => {
                current_heading = None;
                if let Some(rendered_html) = splice.advance_at_start(label) {
                    // rcdom has no raw-HTML node; emit a sentinel
                    // comment that the post-process replacement
                    // expands. The skip-state is owned by `splice`.
                    let sentinel = sentinels.push(rendered_html.to_string());
                    let comment_node = create_comment(&sentinel);
                    current_parent.children.borrow_mut().push(comment_node);
                } else if !splice.should_skip() {
                    // No splice — emit the default lex:label start
                    // comment as before.
                    let mut comment = format!(" lex:{label}");
                    for (key, value) in parameters {
                        comment.push_str(&format!(" {key}={value}"));
                    }
                    comment.push(' ');
                    let comment_node = create_comment(&comment);
                    current_parent.children.borrow_mut().push(comment_node);
                }
            }

            Event::EndAnnotation { label } => {
                if splice.should_skip() {
                    splice.advance_at_end();
                    continue;
                }
                // Not in splice — emit the default lex:label end
                // comment as before.
                let comment = format!(" /lex:{label} ");
                let comment_node = create_comment(&comment);
                current_parent.children.borrow_mut().push(comment_node);
            }

            Event::Image(image) => {
                let figure = create_element("figure", vec![("class", "lex-image")]);
                current_parent.children.borrow_mut().push(figure.clone());

                let mut attrs = vec![("src", image.src.as_str()), ("alt", image.alt.as_str())];
                if let Some(title) = &image.title {
                    attrs.push(("title", title.as_str()));
                }
                let img = create_element("img", attrs);
                figure.children.borrow_mut().push(img);

                if !image.alt.is_empty() {
                    let caption = create_element("figcaption", vec![]);
                    let text = create_text(&image.alt);
                    caption.children.borrow_mut().push(text);
                    figure.children.borrow_mut().push(caption);
                }
            }

            Event::Video(video) => {
                let figure = create_element("figure", vec![("class", "lex-video")]);
                current_parent.children.borrow_mut().push(figure.clone());

                let mut attrs = vec![("src", video.src.as_str()), ("controls", "")];
                if let Some(poster) = &video.poster {
                    attrs.push(("poster", poster.as_str()));
                }
                if let Some(title) = &video.title {
                    attrs.push(("title", title.as_str()));
                }
                let vid = create_element("video", attrs);
                figure.children.borrow_mut().push(vid);
            }

            Event::Audio(audio) => {
                let figure = create_element("figure", vec![("class", "lex-audio")]);
                current_parent.children.borrow_mut().push(figure.clone());

                let mut attrs = vec![("src", audio.src.as_str()), ("controls", "")];
                if let Some(title) = &audio.title {
                    attrs.push(("title", title.as_str()));
                }
                let aud = create_element("audio", attrs);
                figure.children.borrow_mut().push(aud);
            }
        }
    }

    // Close any `<dl>` that was deferred at end-of-events.
    if defer_close_dl {
        current_parent = parent_stack.pop().ok_or_else(|| {
            FormatError::SerializationError(
                "Failed to close deferred definition list at end of events".to_string(),
            )
        })?;
    }
    let _ = current_parent;

    // Set the document container as the root
    dom.document.children.borrow_mut().push(doc_container);

    Ok((dom, has_math))
}

/// Add inline content to an HTML node, handling references → anchors conversion.
///
/// `has_math` is set to true if any `InlineContent::Math` is encountered
/// (transitively, through nested Bold/Italic/Link children). The caller
/// uses this to decide whether to inject KaTeX into the document head.
fn add_inline_to_node(
    parent: &Handle,
    inline: &InlineContent,
    has_math: &mut bool,
) -> Result<(), FormatError> {
    match inline {
        InlineContent::Text(text) => {
            let text_node = create_text(text);
            parent.children.borrow_mut().push(text_node);
        }

        InlineContent::Bold(children) => {
            let strong = create_element("strong", vec![]);
            parent.children.borrow_mut().push(strong.clone());
            for child in children {
                add_inline_to_node(&strong, child, has_math)?;
            }
        }

        InlineContent::Italic(children) => {
            let em = create_element("em", vec![]);
            parent.children.borrow_mut().push(em.clone());
            for child in children {
                add_inline_to_node(&em, child, has_math)?;
            }
        }

        InlineContent::Code(code_text) => {
            let code = create_element("code", vec![]);
            let text = create_text(code_text);
            code.children.borrow_mut().push(text);
            parent.children.borrow_mut().push(code);
        }

        InlineContent::Math(math_text) => {
            *has_math = true;
            let math_span = create_element("span", vec![("class", "lex-math")]);
            let dollar_open = create_text("$");
            let math_content = create_text(math_text);
            let dollar_close = create_text("$");
            math_span.children.borrow_mut().push(dollar_open);
            math_span.children.borrow_mut().push(math_content);
            math_span.children.borrow_mut().push(dollar_close);
            parent.children.borrow_mut().push(math_span);
        }

        InlineContent::Reference {
            raw: ref_text,
            kind,
        } => {
            // Unresolved reference (non-linkable types like citations,
            // footnotes, etc.). Dispatch on the typed kind preserved
            // from lex-core; fall back to raw-string heuristic only for
            // `NotSure` (markdown / rfc-xml import paths that didn't
            // classify against lex's reference grammar).
            use crate::ir::nodes::ReferenceType;
            let href = match kind {
                ReferenceType::Citation(data) => {
                    // Anchor on the citation KEY only (`#ref-spec2025`); the raw
                    // literal includes the locator (`@spec2025, pp. 45-46`) which
                    // must not leak into the href. See the markdown serializer.
                    let key = data.keys.first().cloned().unwrap_or_else(|| {
                        ref_text.strip_prefix('@').unwrap_or(ref_text).to_string()
                    });
                    format!("#ref-{key}")
                }
                ReferenceType::NotSure => {
                    if let Some(citation) = ref_text.strip_prefix('@') {
                        format!("#ref-{citation}")
                    } else {
                        ref_text.clone()
                    }
                }
                _ => ref_text.clone(),
            };

            let anchor = create_element("a", vec![("href", &href)]);
            let anchor_text = create_text(ref_text);
            anchor.children.borrow_mut().push(anchor_text);
            parent.children.borrow_mut().push(anchor);
        }

        InlineContent::Link { text, href } => {
            let anchor = create_element("a", vec![("href", href)]);
            let anchor_text = create_text(text);
            anchor.children.borrow_mut().push(anchor_text);
            parent.children.borrow_mut().push(anchor);
        }

        InlineContent::Image(image) => {
            let mut attrs = vec![("src", image.src.as_str()), ("alt", image.alt.as_str())];
            if let Some(title) = &image.title {
                attrs.push(("title", title.as_str()));
            }
            let img = create_element("img", attrs);
            parent.children.borrow_mut().push(img);
        }
    }

    Ok(())
}

/// Create an HTML element with attributes
fn create_element(tag: &str, attrs: Vec<(&str, &str)>) -> Handle {
    let qual_name = QualName::new(None, ns!(html), LocalName::from(tag));
    let attributes = attrs
        .into_iter()
        .map(|(name, value)| Attribute {
            name: QualName::new(None, ns!(), LocalName::from(name)),
            value: value.to_string().into(),
        })
        .collect();

    Rc::new(Node {
        parent: Cell::new(None),
        children: RefCell::new(Vec::new()),
        data: NodeData::Element {
            name: qual_name,
            attrs: RefCell::new(attributes),
            template_contents: Default::default(),
            mathml_annotation_xml_integration_point: false,
        },
    })
}

/// Return true if `handle` is an element with the given tag name.
fn is_element_with_tag(handle: &Handle, tag: &str) -> bool {
    if let NodeData::Element { name, .. } = &handle.data {
        name.local.as_ref() == tag
    } else {
        false
    }
}

/// Create a text node
fn create_text(text: &str) -> Handle {
    Rc::new(Node {
        parent: Cell::new(None),
        children: RefCell::new(Vec::new()),
        data: NodeData::Text {
            contents: RefCell::new(text.to_string().into()),
        },
    })
}

/// Create a comment node
fn create_comment(text: &str) -> Handle {
    Rc::new(Node {
        parent: Cell::new(None),
        children: RefCell::new(Vec::new()),
        data: NodeData::Comment {
            contents: text.to_string().into(),
        },
    })
}

/// Serialize the DOM to an HTML string (just the inner content)
fn serialize_dom(dom: &RcDom) -> Result<String, FormatError> {
    let mut output = Vec::new();

    // Get the document container (first child of document root)
    let doc_container = dom
        .document
        .children
        .borrow()
        .first()
        .ok_or_else(|| FormatError::SerializationError("Empty document".to_string()))?
        .clone();

    // Serialize each child of the doc_container
    // Use TraversalScope::IncludeNode to serialize the element AND its children
    let opts = SerializeOpts {
        traversal_scope: TraversalScope::IncludeNode,
        ..Default::default()
    };

    for child in doc_container.children.borrow().iter() {
        let serializable = SerializableHandle::from(child.clone());
        serialize(&mut output, &serializable, opts.clone()).map_err(|e| {
            FormatError::SerializationError(format!("HTML serialization failed: {e}"))
        })?;
    }

    String::from_utf8(output)
        .map_err(|e| FormatError::SerializationError(format!("UTF-8 conversion failed: {e}")))
}

/// Wrap the content in a complete HTML document with embedded CSS
fn wrap_in_document(
    body_html: &str,
    head_title: &str,
    body_title: Option<&str>,
    body_subtitle: Option<&str>,
    has_math: bool,
    options: &HtmlOptions,
) -> Result<String, FormatError> {
    let baseline_css = include_str!("../../../css/baseline.css");
    let theme_css = match options.theme {
        HtmlTheme::FancySerif => include_str!("../../../css/themes/theme-fancy-serif.css"),
        HtmlTheme::Modern => include_str!("../../../css/themes/theme-modern.css"),
    };

    // Custom CSS is appended after baseline and theme
    let custom_css = options.custom_css.as_deref().unwrap_or("");

    let escaped_head_title = html_escape(head_title);

    let header_html = match body_title {
        Some(t) => {
            let escaped_t = html_escape(t);
            match body_subtitle {
                Some(s) => format!(
                    "<header class=\"lex-doc-header\"><h1 class=\"lex-doc-title\">{escaped_t}</h1><p class=\"lex-doc-subtitle\">{}</p></header>\n",
                    html_escape(s)
                ),
                None => format!(
                    "<header class=\"lex-doc-header\"><h1 class=\"lex-doc-title\">{escaped_t}</h1></header>\n"
                ),
            }
        }
        None => String::new(),
    };

    // KaTeX is only included when the document contains math spans — saves
    // ~290 KB on the wire for math-free documents. SRI hashes are pinned to
    // KaTeX 0.16.11; bumping the version requires re-computing them from the
    // release tarball (github.com/KaTeX/KaTeX/releases) with
    // `openssl dgst -sha384 -binary <file> | openssl base64 -A`.
    let katex_html = if has_math {
        r#"  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" integrity="sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+" crossorigin="anonymous">
  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js" integrity="sha384-7zkQWkzuo3B5mTepMUcHkMB5jZaolc2xDwL6VFqjFALcbeS9Ggm/Yr2r3Dy4lfFg" crossorigin="anonymous"></script>
  <script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js" integrity="sha384-43gviWU0YVjaDtb/GhzOouOXtZMP/7XUzwPTstBeZFe/+rCMvRwr4yROQP43s0Xk" crossorigin="anonymous" onload="renderMathInElement(document.body, {delimiters: [{left: '$', right: '$', display: false}, {left: '$$', right: '$$', display: true}], throwOnError: false});"></script>
"#
    } else {
        ""
    };

    let html = format!(
        r#"<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="generator" content="lex-babel">
  <title>{escaped_head_title}</title>
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/styles/github.min.css" integrity="sha384-eFTL69TLRZTkNfYZOLM+G04821K1qZao/4QLJbet1pP4tcF+fdXq/9CdqAbWRl/L" crossorigin="anonymous">
{katex_html}  <style>
{baseline_css}
{theme_css}
{custom_css}
  </style>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/highlight.min.js" integrity="sha384-RH2xi4eIQ/gjtbs9fUXM68sLSi99C7ZWBRX1vDrVv6GQXRibxXLbwO2NGZB74MbU" crossorigin="anonymous"></script>
  <script>hljs.highlightAll();</script>
</head>
<body>
<div class="lex-document">
{header_html}{body_html}
</div>
</body>
</html>"#
    );

    Ok(html)
}

/// Map common language aliases to highlight.js class names
fn normalize_language(lang: &str) -> &str {
    match lang {
        "js" => "javascript",
        "ts" => "typescript",
        "py" => "python",
        "sh" => "bash",
        "c++" | "cpp" => "cpp",
        "c#" | "csharp" => "csharp",
        "yml" => "yaml",
        "rb" => "ruby",
        "rs" => "rust",
        "kt" => "kotlin",
        "md" => "markdown",
        "objc" | "obj-c" => "objectivec",
        other => other,
    }
}

/// Escape HTML special characters in text
fn html_escape(s: &str) -> String {
    s.replace('&', "&amp;")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
        .replace('"', "&quot;")
}

#[cfg(test)]
mod tests {
    use super::*;
    use lex_core::lex::transforms::standard::STRING_TO_AST;

    #[test]
    fn test_simple_paragraph() {
        let lex_src = "This is a simple paragraph.\n";
        let lex_doc = STRING_TO_AST.run(lex_src.to_string()).unwrap();

        let html = serialize_to_html(&lex_doc, HtmlTheme::Modern).unwrap();

        assert!(html.contains("<!DOCTYPE html>"));
        assert!(html.contains("<p class=\"lex-paragraph\">"));
        assert!(html.contains("This is a simple paragraph."));
    }

    #[test]
    fn test_heading() {
        let lex_src = "1. Introduction\n\n    Content here.\n";
        let lex_doc = STRING_TO_AST.run(lex_src.to_string()).unwrap();

        let html = serialize_to_html(&lex_doc, HtmlTheme::Modern).unwrap();

        assert!(html.contains("<section class=\"lex-session lex-session-2\">"));
        assert!(html.contains("<h2>"));
        assert!(html.contains("Introduction"));
    }

    #[test]
    fn test_css_embedded() {
        let lex_src = "Test document.\n";
        let lex_doc = STRING_TO_AST.run(lex_src.to_string()).unwrap();

        let html = serialize_to_html(&lex_doc, HtmlTheme::Modern).unwrap();

        assert!(html.contains("<style>"));
        assert!(html.contains(".lex-document"));
        assert!(html.contains("Helvetica")); // Modern theme uses Helvetica font
    }

    #[test]
    fn test_fancy_serif_theme() {
        let lex_src = "Test document.\n";
        let lex_doc = STRING_TO_AST.run(lex_src.to_string()).unwrap();

        let html = serialize_to_html(&lex_doc, HtmlTheme::FancySerif).unwrap();

        assert!(html.contains("Cormorant")); // Fancy serif theme uses Cormorant font
    }

    #[test]
    fn test_custom_css_appended() {
        let lex_src = "Test document.\n";
        let lex_doc = STRING_TO_AST.run(lex_src.to_string()).unwrap();

        let custom_css = ".my-custom-class { color: red; }";
        let options = HtmlOptions::new(HtmlTheme::Modern).with_custom_css(custom_css.to_string());
        let html = serialize_to_html_with_options(&lex_doc, options).unwrap();

        // Custom CSS should be present
        assert!(html.contains(".my-custom-class { color: red; }"));
        // Baseline CSS should still be present
        assert!(html.contains(".lex-document"));
    }

    #[test]
    fn test_html_options_default() {
        let options = HtmlOptions::default();
        assert_eq!(options.theme, HtmlTheme::Modern);
        assert!(options.custom_css.is_none());
    }
}