Skip to main content

carve/
render_markdown.rs

1use crate::ast::*;
2use crate::carrier_markers::{
3    carrier_line, carrier_line_at, spell_carrier_markers, CarrierMarkers,
4};
5use crate::extension::Options;
6use crate::parse::unwrap_nested_anchors;
7use crate::render_loss::{DeniedSink, MarkdownLoss, RawNodeType};
8use crate::render_text::{strip_high_controls as strip_control_chars, trim_non_nbsp};
9use std::collections::HashMap;
10use std::collections::HashSet;
11use std::fmt::Write as _;
12use std::rc::Rc;
13
14use crate::render::MAX_RENDER_DEPTH;
15
16/// A Markdown render refused by the depth guard or by a roundtrip carrier.
17#[derive(Debug, Clone, PartialEq, Eq)]
18pub enum MarkdownRenderError {
19    /// The document exceeded the renderer's depth ceiling.
20    Depth(crate::RenderDepthError),
21    /// The canonical writer cannot spell a carrier's inline source.
22    SourceUnspellable(crate::SourceUnspellable),
23}
24
25impl std::fmt::Display for MarkdownRenderError {
26    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
27        match self {
28            Self::Depth(error) => error.fmt(f),
29            Self::SourceUnspellable(error) => error.fmt(f),
30        }
31    }
32}
33
34impl std::error::Error for MarkdownRenderError {}
35
36impl From<crate::RenderDepthError> for MarkdownRenderError {
37    fn from(error: crate::RenderDepthError) -> Self {
38        Self::Depth(error)
39    }
40}
41
42impl From<crate::RenderCarveError> for MarkdownRenderError {
43    fn from(error: crate::RenderCarveError) -> Self {
44        match error {
45            crate::RenderCarveError::Depth(error) => Self::Depth(error),
46            crate::RenderCarveError::SourceUnspellable(error) => Self::SourceUnspellable(error),
47        }
48    }
49}
50
51impl From<MarkdownRenderError> for crate::RenderCarveError {
52    fn from(error: MarkdownRenderError) -> Self {
53        match error {
54            MarkdownRenderError::Depth(error) => Self::Depth(error),
55            MarkdownRenderError::SourceUnspellable(error) => Self::SourceUnspellable(error),
56        }
57    }
58}
59
60impl From<MarkdownRenderError> for crate::CarveWriteError {
61    fn from(error: MarkdownRenderError) -> Self {
62        Self::Render(error.into())
63    }
64}
65
66fn trim_block_output(s: &str) -> &str {
67    s.trim_matches(|c| c == '\n' || c == ' ')
68}
69
70thread_local! {
71    /// Mode for the current render. A thread-local keeps this off every
72    /// signature in the render tree; it is set once per render entry point
73    /// and read only by the smart-punctuation arms.
74    static SMART_TYPOGRAPHY: std::cell::Cell<crate::extension::SmartTypographyMode> =
75        const { std::cell::Cell::new(crate::extension::SmartTypographyMode::Glyph) };
76}
77
78fn smart_punctuation_text(node: &crate::ast::SmartPunctuation) -> &str {
79    if SMART_TYPOGRAPHY
80        .with(std::cell::Cell::get)
81        .uses_source(&node.kind)
82    {
83        return &node.value;
84    }
85
86    smart_punctuation_glyph(node)
87}
88
89/// Render a document to Markdown, honouring `Options::smart_typography`. The
90/// profile transform is applied to `doc` upstream (see `crate::prepare_doc`).
91/// Render a tree that did NOT come from the parser, refusing at the ceiling.
92///
93/// `Err` when the tree nests deeper than [`crate::MAX_RENDER_DEPTH`] (PART 9
94/// §25), or when a roundtrip carrier has no faithful Carve source spelling.
95pub fn render_markdown_with_options(
96    doc: &Document,
97    options: &Options<'_>,
98) -> Result<String, MarkdownRenderError> {
99    crate::render_depth::refuse_if_too_deep(doc, "markdown")?;
100    let watch = crate::render_depth::RenderDepthWatch::new();
101    let previous_error = CARRIER_WRITE_ERROR.with(|cell| cell.replace(None));
102    let output = render_markdown_inner(
103        doc,
104        options.smart_typography,
105        options.heading_id_options(),
106        options.roundtrip,
107    );
108    let carrier_error = CARRIER_WRITE_ERROR.with(|cell| cell.replace(previous_error));
109    let output = watch.into_result(output)?;
110    carrier_error.map_or(Ok(output), |error| Err(error.into()))
111}
112
113/// Render a document to Markdown with the default settings, so smart
114/// typography renders as its glyph.
115/// Render a tree that did NOT come from the parser, refusing at the ceiling.
116///
117/// `Err` when the tree nests deeper than [`crate::MAX_RENDER_DEPTH`] (PART 9
118/// §25).
119pub fn render_markdown(doc: &Document) -> Result<String, crate::RenderDepthError> {
120    crate::render_depth::refuse_if_too_deep(doc, "markdown")?;
121    let watch = crate::render_depth::RenderDepthWatch::new();
122    watch.into_result(render_markdown_inner(
123        doc,
124        crate::extension::SmartTypographyMode::Glyph,
125        Options::default().heading_id_options(),
126        false,
127    ))
128}
129
130/// One render, and a second one if the document turned out to hold a carrier.
131///
132/// The carriers are PICKED per document (see `CARRIER_DEFAULTS`), and what the
133/// pick has to be made against is the author's private-use characters - which
134/// this target only learns by rendering, because the tree it is handed is not
135/// the source. So the first pass renders with the preferred run and COUNTS: how
136/// many carriers it inserted, and how many stood in the assembled document. A
137/// document that holds none of them - every real one - leaves the two counts
138/// equal and returns after one pass, which is the shape `render_carve` already
139/// runs for the canonical writer's own five (`render_carve_unguarded`).
140///
141/// More seen than inserted means the author wrote one. The run is then re-picked
142/// against every private-use code point the assembled document holds - the
143/// author's and this pass's own, a superset, so the new run is free of both -
144/// and the whole render repeats with it. It cannot need a third pass, and
145/// nothing else changes: the retry runs the same code.
146fn render_markdown_inner(
147    doc: &Document,
148    smart_typography: crate::extension::SmartTypographyMode,
149    id_opts: crate::extension::HeadingIdOptions,
150    roundtrip: bool,
151) -> String {
152    let _carriers = CarrierGuard::install_defaults();
153    let losses = crate::render_loss::checkpoint();
154    let first = render_markdown_once(doc, smart_typography, id_opts, roundtrip);
155    let inserted = INSERTED.with(std::cell::Cell::get);
156    let seen = SEEN.with(std::cell::Cell::get);
157    if (0..CARRIER_COUNT).all(|slot| seen[slot] <= inserted[slot]) {
158        return first;
159    }
160
161    if OCCUPIED.with(|occupied| marker_pool_needs_tokens(&occupied.borrow())) {
162        OCCUPIED_TOKEN_NONCES.with(|nonces| {
163            crate::sentinel_run::collect_marker_nonce_cores(&first, &mut nonces.borrow_mut());
164        });
165    }
166    let picked = OCCUPIED.with(|occupied| {
167        let occupied = occupied.borrow();
168        let chars: [char; CARRIER_COUNT] =
169            crate::sentinel_run::pick_sentinel_run(&occupied, u32::from(CARRIER_DEFAULTS[0]));
170        if chars
171            .iter()
172            .all(|marker| !occupied.contains(&u32::from(*marker)))
173        {
174            return chars.map(|marker| Rc::new(marker.to_string()));
175        }
176        // Punctuation at both ends preserves delimiter flanking. Choose a
177        // nonce absent from every assembled token family, without growing the
178        // marker with an authored character run.
179        let nonce = OCCUPIED_TOKEN_NONCES.with(|nonces| {
180            let nonces = nonces.borrow();
181            (0..=nonces.len())
182                .find(|nonce| !nonces.contains(nonce))
183                .unwrap()
184        });
185        std::array::from_fn(|index| Rc::new(format!("§m{nonce}:{index}§")))
186    });
187    let _picked_carriers = CarrierGuard::install(picked);
188    losses.restore();
189    render_markdown_once(doc, smart_typography, id_opts, roundtrip)
190}
191
192fn render_markdown_once(
193    doc: &Document,
194    smart_typography: crate::extension::SmartTypographyMode,
195    id_opts: crate::extension::HeadingIdOptions,
196    roundtrip: bool,
197) -> String {
198    INLINE_CARRIER_PATTERN.with(|pattern| {
199        *pattern.borrow_mut() = None;
200    });
201    if roundtrip {
202        let authored = crate::ast_json::to_json(doc);
203        let mut nonce = 0;
204        let prefix = loop {
205            let prefix = format!("§carve-inline-{nonce}§");
206            if !authored.contains(&prefix) {
207                break prefix;
208            }
209            nonce += 1;
210        };
211        INLINE_CARRIER_PATTERN.with(|pattern| {
212            *pattern.borrow_mut() = Some(
213                regex::Regex::new(&format!(
214                    "{}(<!--[\\s\\S]*?-->){}",
215                    regex::escape(&prefix),
216                    regex::escape(&prefix)
217                ))
218                .unwrap(),
219            );
220        });
221        INLINE_CARRIER_PREFIX.with(|current| {
222            *current.borrow_mut() = prefix;
223        });
224    }
225    INSERTED.with(|counts| counts.set([0; CARRIER_COUNT]));
226    SEEN.with(|counts| counts.set([0; CARRIER_COUNT]));
227    IN_LINK_TEXT.with(|d| d.set(0));
228    OCCUPIED.with(|occupied| occupied.borrow_mut().clear());
229    OCCUPIED_TOKEN_NONCES.with(|nonces| nonces.borrow_mut().clear());
230    SMART_TYPOGRAPHY.with(|cell| cell.set(smart_typography));
231    let _abbr_guard = crate::abbr_budget::AbbrBudgetGuard::for_document(doc);
232    let crossref_index = crate::parse::crossref_index_for_document(doc, id_opts);
233    // PART 11 §11: a link to a heading is written with the heading's GFM slug.
234    // Every heading gets its Carve id here, in the core's order, so the ids
235    // match; only a heading this target writes as one takes a slug. Footnote
236    // bodies render as block content after the document, which is also the
237    // order a reader numbers their headings in.
238    let mut explicit_ids = HashSet::new();
239    let mut explicit_pass = |block: &BlockNode, _: Option<&[InlineNode]>| {
240        if let BlockNode::Heading(heading) = block {
241            if let Some(id) = heading.attrs.as_ref().and_then(|attrs| attrs.id.as_ref()) {
242                explicit_ids.insert(id.clone());
243            }
244        }
245    };
246    walk_blocks(&doc.children, 0, &mut explicit_pass);
247    for body in doc.footnote_defs.values() {
248        walk_blocks(body, 0, &mut explicit_pass);
249    }
250
251    let mut id_counts = std::collections::BTreeMap::new();
252    let mut slugger = GfmSlugger::default();
253    let mut heading_slugs: HashMap<String, String> = HashMap::new();
254    let mut heading_pass = |heading: &Heading, written: bool| {
255        let id = next_heading_id(heading, &mut id_counts, &explicit_ids);
256        if written {
257            let slug = slugger.slug(&gfm_heading_text(&heading.children));
258            heading_slugs.entry(id).or_insert(slug);
259        }
260    };
261    walk_headings(&doc.children, 0, true, &mut heading_pass);
262    for (_, body) in crate::ast_json::footnote_defs_in_source_order(doc) {
263        walk_headings(body, 0, true, &mut heading_pass);
264    }
265
266    let referenced_links = referenced_link_labels(doc);
267    let native_references = if roundtrip {
268        native_reference_definitions(doc)
269    } else {
270        HashMap::new()
271    };
272    let mut ctx = MarkdownContext {
273        referenced_links,
274        native_references,
275        suppress_automatic_abbreviation: false,
276        heading_slugs,
277        list_depth: 0,
278        thematic_glued: false,
279        in_footnote: false,
280        footnote_allowed_lists: HashSet::new(),
281        list_item_opening_list: None,
282        defined_footnotes: doc.footnote_defs.keys().cloned().collect(),
283        crossref_index,
284        link_depth: 0,
285        single_line_depth: 0,
286        previous_list: None,
287        roundtrip,
288        carrier_depth: 0,
289        definition_depth: 0,
290        delimiter_ancestors: Vec::new(),
291        rendered_children: HashMap::new(),
292    };
293    let out: String =
294        crate::render_text::blocks_with_link_definitions_in_source_order(&doc.children)
295            .into_iter()
296            .map(|block| render_block(block, &mut ctx, 0))
297            .collect();
298    let footnotes = render_footnote_defs(doc, &mut ctx);
299    let body = normalize(&format!("{out}{footnotes}"));
300    let body = INLINE_CARRIER_PATTERN.with(|pattern| {
301        pattern
302            .borrow()
303            .as_ref()
304            .map(|pattern| pattern.replace_all(&body, "$1").into_owned())
305            .unwrap_or(body)
306    });
307    match render_frontmatter(doc) {
308        None => body,
309        // A document that is only frontmatter has no body to separate it from,
310        // and `normalize` returns a bare newline for one.
311        Some(frontmatter) if body == "\n" => format!("{frontmatter}\n"),
312        Some(frontmatter) => format!("{frontmatter}\n\n{body}"),
313    }
314}
315
316/// PART 11 §10r: frontmatter is emitted first, with the format token wherever
317/// the format is not `yaml`, and the content verbatim.
318///
319/// Built outside `normalize`, whose blank-line collapse and escape resolution
320/// must not reach metadata the clause requires verbatim. Only the Trojan-Source
321/// overrides and isolates go, which every other byte on this target loses too.
322///
323/// The raw block first and the parsed map second, the precedence `render_carve`
324/// already uses: the map is the fallback for a document built through the API
325/// rather than parsed.
326fn render_frontmatter(doc: &Document) -> Option<String> {
327    let strip = |text: &str| -> String {
328        text.chars()
329            .filter(|c| !crate::escape::is_bidi_control(*c))
330            .collect()
331    };
332    if let Some(raw) = &doc.frontmatter_raw {
333        let format = if raw.format == "yaml" {
334            ""
335        } else {
336            raw.format.as_str()
337        };
338        return Some(format!("---{format}\n{}\n---", strip(&raw.content)));
339    }
340    if doc.frontmatter.is_empty() {
341        return None;
342    }
343    let mut out = String::from("---");
344    for (key, value) in &doc.frontmatter {
345        out.push('\n');
346        out.push_str(&strip(key));
347        out.push_str(": ");
348        out.push_str(&strip(value));
349    }
350    out.push_str("\n---");
351    Some(out)
352}
353
354pub(crate) fn referenced_link_labels(doc: &Document) -> HashSet<String> {
355    use crate::include_walk::{visit_block_children, visit_inline_children, SubtreeVisitor};
356    struct Labels(HashSet<String>);
357    impl SubtreeVisitor for Labels {
358        fn blocks(&mut self, blocks: &mut Vec<BlockNode>) {
359            for block in blocks {
360                visit_block_children(block, self);
361            }
362        }
363        fn inlines(&mut self, inlines: &mut Vec<InlineNode>) {
364            for inline in inlines {
365                if let InlineNode::Link(link) = inline {
366                    if !crate::parse::is_unresolved_reference(link) {
367                        if let Some(label) = &link.ref_label {
368                            self.0.insert(crate::parse::label_key(label));
369                        }
370                    }
371                }
372                visit_inline_children(inline, self);
373            }
374        }
375        fn image(&mut self, image: &mut Image) {
376            if !crate::parse::is_unresolved_image(image) {
377                if let Some(label) = &image.ref_label {
378                    self.0.insert(crate::parse::label_key(label));
379                }
380            }
381        }
382    }
383    if !doc
384        .children
385        .iter()
386        .any(|block| matches!(block, BlockNode::LinkReferenceDefinition(_)))
387    {
388        return HashSet::new();
389    }
390    let mut labels = Labels(HashSet::new());
391    let mut document = doc.clone();
392    labels.blocks(&mut document.children);
393    for body in document.footnote_defs.values_mut() {
394        labels.blocks(body);
395    }
396    labels.0
397}
398
399fn native_reference_definitions(
400    doc: &Document,
401) -> HashMap<String, crate::ast::LinkReferenceDefinition> {
402    let mut groups: HashMap<String, Vec<&crate::ast::LinkReferenceDefinition>> = HashMap::new();
403    for block in &doc.children {
404        if let BlockNode::LinkReferenceDefinition(def) = block {
405            groups
406                .entry(crate::parse::label_key(&def.label).to_uppercase())
407                .or_default()
408                .push(def);
409        }
410    }
411    groups
412        .into_values()
413        .filter_map(|group| {
414            let def = *group.first()?;
415            let label = &def.label;
416            (group.len() == 1
417                && label.chars().any(|ch| !ch.is_whitespace())
418                && label.len() <= 999
419                && !label.contains(['[', ']', '\\', '\n', '\r']))
420            .then(|| (crate::parse::label_key(label), def.clone()))
421        })
422        .collect()
423}
424
425struct MarkdownContext {
426    referenced_links: HashSet<String>,
427    native_references: HashMap<String, crate::ast::LinkReferenceDefinition>,
428    /// Set while rendering a span that carries an authored `abbr`.
429    ///
430    /// PART 9 section 10 and carve#1127: the authored value OUTRANKS automatic
431    /// expansion, and a resolved abbreviation inside such a span contributes only
432    /// its visible text. The HTML renderer already carried this flag on its state;
433    /// this target emitted the DEFINITION's text instead (carve#1176).
434    suppress_automatic_abbreviation: bool,
435    /// The GFM slug of every heading this target writes, by the Carve id the
436    /// document assigned it (PART 11 §11).
437    heading_slugs: HashMap<String, String>,
438    list_depth: usize,
439    thematic_glued: bool,
440    in_footnote: bool,
441    footnote_allowed_lists: HashSet<usize>,
442    list_item_opening_list: Option<usize>,
443    /// Labels that actually have a definition. A reference without one did not
444    /// form a footnote, so it is not a footnote marker. The HTML renderer decides
445    /// this on the node's `number`, which numbering assigns -- this target does no
446    /// numbering, so that field is always None here and there was nothing to
447    /// check (carve#352).
448    defined_footnotes: std::collections::BTreeSet<String>,
449    crossref_index: crate::parse::CrossrefIndex,
450    /// Nonzero while rendering a link's label. Links never nest, and the parser
451    /// enforces that -- but a cross-reference becomes a link only HERE, after
452    /// the parser has run, so this target has to apply the rule itself.
453    /// `[see </#H>](/outer)` must render as `[see H](/outer)`, not as a link
454    /// inside a link, which is not valid Markdown (carve-rs#436).
455    link_depth: usize,
456    /// Nonzero while rendering a table cell or heading.
457    single_line_depth: usize,
458    /// The kind and marker of the list last written in the current flow, when
459    /// nothing has been written after it (PART 11 §10o).
460    previous_list: Option<(bool, char)>,
461    /// PART 11 §10s: whether an element-less container is bracketed with a
462    /// carrier marker. OFF by default; the mode only ADDS comment lines.
463    roundtrip: bool,
464    /// How many carried containers enclose the block being written, which is
465    /// what decides the colon-fence width a marker payload carries.
466    carrier_depth: usize,
467    definition_depth: usize,
468    delimiter_ancestors: Vec<&'static str>,
469    rendered_children: HashMap<usize, Vec<String>>,
470}
471
472/// The marker payloads a container takes, or `None` when the mode is off or the
473/// container is not element-less on this target.
474fn carrier_markers(node: &BlockNode, ctx: &MarkdownContext) -> Option<CarrierMarkers> {
475    if !ctx.roundtrip || ctx.single_line_depth > 0 {
476        return None;
477    }
478    spell_carrier_markers(node, ctx.carrier_depth)
479}
480
481/// Render a carried container's children one fence width in.
482fn carried_children(
483    children: &[BlockNode],
484    markers: Option<&CarrierMarkers>,
485    ctx: &mut MarkdownContext,
486    depth: usize,
487) -> String {
488    if markers.is_none() {
489        return render_blocks(children, ctx, depth);
490    }
491    ctx.carrier_depth += 1;
492    let out = render_blocks(children, ctx, depth);
493    ctx.carrier_depth -= 1;
494
495    out
496}
497
498/// Bracket a container's output with its marker lines.
499///
500/// The body is emitted UNCHANGED, separator and all: the mode adds lines and
501/// moves none, which is what keeps the mode-off bytes the bytes of today.
502fn carried(markers: Option<&CarrierMarkers>, body: String) -> String {
503    let Some(markers) = markers else { return body };
504    let mut out = String::new();
505    for payload in markers
506        .prelude
507        .iter()
508        .chain(std::iter::once(&markers.opener))
509    {
510        out.push_str(&carrier_line(payload));
511        out.push('\n');
512    }
513    out.push_str(&body);
514    out.push_str(&carrier_line(&markers.closer));
515    out.push('\n');
516
517    out
518}
519
520fn render_block_inlines(nodes: &[InlineNode], ctx: &mut MarkdownContext) -> String {
521    render_inlines(nodes, ctx, 0)
522}
523
524fn render_wrapped_inlines(
525    nodes: &[InlineNode],
526    ctx: &mut MarkdownContext,
527    delimiter: &'static str,
528    open_tag: &str,
529    close_tag: &str,
530) -> String {
531    let owner = &nodes as *const &[InlineNode] as usize;
532    ctx.delimiter_ancestors.push(delimiter);
533    let inner = render_recorded_inlines(nodes, ctx, 0, Some(owner));
534    ctx.delimiter_ancestors.pop();
535    let parts = ctx.rendered_children.remove(&owner);
536    let (marked_lead, marked_core, marked_trail) = inline_padding(&inner, char::is_whitespace);
537    let visible_core = visible_inline(&marked_core);
538    let core = visible_core.as_ref();
539    let rendered =
540        if !core.is_empty() && nested_edge_is_invalid(core, delimiter, nodes, parts.as_ref()) {
541            format!("{marked_lead}{open_tag}{marked_core}{close_tag}{marked_trail}")
542        } else {
543            pad_outside(inner, delimiter, open_tag, close_tag)
544        };
545    trim_non_nbsp(&rendered).to_string()
546}
547
548fn render_title_inlines(nodes: &[InlineNode], ctx: &mut MarkdownContext) -> String {
549    let nodes = inline_nodes_without_strong(nodes);
550    render_wrapped_inlines(&nodes, ctx, "**", "<strong>", "</strong>")
551}
552
553fn render_blocks(blocks: &[BlockNode], ctx: &mut MarkdownContext, depth: usize) -> String {
554    if depth > MAX_RENDER_DEPTH {
555        crate::render_depth::record("markdown");
556        return String::new();
557    }
558    blocks
559        .iter()
560        .map(|block| render_block(block, ctx, depth))
561        .collect()
562}
563
564/// Renders one block and keeps `previous_list` current for the flow it is
565/// written into (PART 11 §10o). A wrapper this target writes transparently
566/// leaves the answer to its children.
567fn render_block(node: &BlockNode, ctx: &mut MarkdownContext, depth: usize) -> String {
568    if !ctx.roundtrip && markdown_dropped_attributes(node) {
569        crate::render_loss::record_markdown_loss(
570            MarkdownLoss::Attributes,
571            RawNodeType::Block,
572            crate::ast_json::block_pos(node),
573        );
574    }
575    let mut out = render_block_kind(node, ctx, depth);
576    if ctx.roundtrip && ctx.single_line_depth == 0 && !out.is_empty() {
577        if let Some(attributes) = dropped_attribute_line(node)
578            .filter(|_| !matches!(node, BlockNode::DefinitionList(_)) || ctx.definition_depth == 0)
579        {
580            out = format!("{}\n{out}", carrier_line(&attributes));
581        }
582    }
583    let transparent = matches!(
584        node,
585        BlockNode::List(_)
586            | BlockNode::Div(_)
587            | BlockNode::Section(_)
588            | BlockNode::LineBlock(_)
589            | BlockNode::Admonition(_)
590            | BlockNode::Directive(_)
591            | BlockNode::ExtensionCarrier(_)
592            | BlockNode::BlockExtension(_)
593            | BlockNode::DefinitionList(_)
594    );
595    if !transparent && !out.trim().is_empty() {
596        ctx.previous_list = None;
597    }
598    out
599}
600
601fn markdown_dropped_attributes(node: &BlockNode) -> bool {
602    let additional = match node {
603        BlockNode::CodeBlock(n) => {
604            return !crate::render::render_attrs_without_keys(&n.attrs, &["title"]).is_empty();
605        }
606        BlockNode::Admonition(n) if list_table_outer(n).is_some() => {
607            return !crate::render::render_attrs_without_keys(
608                &n.attrs,
609                &["header-rows", "header-cols", "aligns"],
610            )
611            .is_empty();
612        }
613        BlockNode::Admonition(n) => &n.attrs,
614        BlockNode::Directive(n) => &n.attrs,
615        BlockNode::Div(n) => &n.attrs,
616        BlockNode::LineBlock(n) => &n.attrs,
617        BlockNode::FigureGroup(n) => &n.attrs,
618        BlockNode::BlockExtension(n) => &n.attrs,
619        BlockNode::ExtensionCarrier(n) => &n.attrs,
620        BlockNode::LinkReferenceDefinition(n) => &n.attrs,
621        _ => return dropped_attribute_line(node).is_some(),
622    };
623    nonempty_attributes(additional).is_some()
624}
625
626fn dropped_attribute_line(node: &BlockNode) -> Option<String> {
627    let attrs = match node {
628        BlockNode::Heading(n) => {
629            let mut attrs = n.attrs.clone();
630            if let Some(attrs) = &mut attrs {
631                if !attrs.order.iter().any(|slot| matches!(slot, AttrSlot::Id)) {
632                    attrs.id = None;
633                }
634            }
635            return nonempty_attributes(&attrs);
636        }
637        BlockNode::Paragraph(n) => &n.attrs,
638        BlockNode::BlockQuote(n) => &n.attrs,
639        BlockNode::List(n) => &n.attrs,
640        BlockNode::DefinitionList(n) => &n.attrs,
641        BlockNode::Table(n) => &n.attrs,
642        BlockNode::CodeBlock(n) => {
643            let mut attrs = n.attrs.clone();
644            if let (Some(title), Some(attrs)) = (&n.title, &mut attrs) {
645                if attrs.key_values.get("title") == Some(title) {
646                    attrs.key_values.remove("title");
647                    attrs
648                        .order
649                        .retain(|slot| !matches!(slot, AttrSlot::Key(key) if key == "title"));
650                }
651            }
652            return nonempty_attributes(&attrs);
653        }
654        BlockNode::ThematicBreak(n) => &n.attrs,
655        BlockNode::Figure(n) => &n.attrs,
656        BlockNode::BlockImage(n) => &n.attrs,
657        _ => return None,
658    };
659    nonempty_attributes(attrs)
660}
661
662fn nonempty_attributes(attrs: &Option<Attrs>) -> Option<String> {
663    let line = crate::render_carve::render_attrs(attrs);
664    (!line.is_empty()).then_some(line)
665}
666
667fn inline_carrier(prefix: &str, nodes: &[InlineNode]) -> String {
668    inline_carrier_at(prefix, nodes, 1)
669}
670
671fn inline_carrier_at(prefix: &str, nodes: &[InlineNode], depth: usize) -> String {
672    let mut doc = crate::parse::parse("");
673    // A synthetic top-level paragraph drops leading layout. A definition
674    // term's tab is content after `:: `, so keep it behind a temporary text
675    // byte while the inline writer spells the carrier payload.
676    let protect_term_tab = prefix == "::"
677        && matches!(nodes.first(), Some(InlineNode::Text(text)) if text.value.starts_with('\t'));
678    let mut children = nodes.to_vec();
679    if protect_term_tab {
680        children.insert(0, InlineNode::Text(Text::from("a")));
681    }
682    doc.children.push(BlockNode::Paragraph(Paragraph {
683        children,
684        ..Paragraph::default()
685    }));
686    let text = match crate::render_carve::render_carve(&doc) {
687        Ok(text) => text,
688        Err(error) => {
689            CARRIER_WRITE_ERROR.with(|cell| {
690                let mut first = cell.borrow_mut();
691                if first.is_none() {
692                    *first = Some(error);
693                }
694            });
695            return String::new();
696        }
697    };
698    let text = if protect_term_tab {
699        text.strip_prefix('a').expect("temporary carrier prefix")
700    } else {
701        &text
702    };
703    carrier_line_at(&format!("{prefix} {}", text.trim_end()), depth)
704}
705
706fn caption_carrier(nodes: &[InlineNode], ctx: &MarkdownContext) -> String {
707    if ctx.roundtrip && ctx.single_line_depth == 0 {
708        format!("{}\n", inline_carrier("^", nodes))
709    } else {
710        String::new()
711    }
712}
713
714fn render_block_kind(node: &BlockNode, ctx: &mut MarkdownContext, depth: usize) -> String {
715    if depth > MAX_RENDER_DEPTH {
716        crate::render_depth::record("markdown");
717        return String::new();
718    }
719    match node {
720        // Renders nothing, same as carve-js and carve-php on this target.
721        BlockNode::LinkReferenceDefinition(definition) => {
722            if !ctx.roundtrip
723                && ctx
724                    .referenced_links
725                    .contains(&crate::parse::label_key(&definition.label))
726            {
727                return String::new();
728            }
729            let safe = crate::escape::sanitize_destination(
730                &definition.href,
731                definition.pos.as_ref(),
732                crate::render_loss::DeniedSink::Destination,
733            );
734            let destination = if safe.is_empty() {
735                "<>".to_string()
736            } else {
737                neutralize_char_refs(
738                    &strip_control_chars(&safe)
739                        .replace('\\', "\\\\")
740                        .replace('(', "\\(")
741                        .replace(')', "\\)")
742                        .replace('<', "\\<")
743                        .replace('>', "\\>"),
744                )
745            };
746            let title = definition
747                .title
748                .as_ref()
749                .map(|title| format!(" \"{}\"", escape_md_title(title)))
750                .unwrap_or_default();
751            format!("[{}]: {destination}{title}\n\n", definition.label)
752        }
753        BlockNode::CitationDefinition(_) => String::new(),
754        // No `{#id}` suffix: GFM has no heading-id syntax, and a link reaches
755        // the heading through its slug instead (PART 11 §11).
756        BlockNode::Heading(heading) => {
757            ctx.single_line_depth += 1;
758            let text = flatten_heading_text(&render_block_inlines(&heading.children, ctx));
759            ctx.single_line_depth -= 1;
760            format!("{} {text}\n\n", "#".repeat(heading.level as usize))
761        }
762        BlockNode::Paragraph(paragraph) => {
763            let text = protect_paragraph_list_markers(
764                &render_block_inlines(&paragraph.children, ctx),
765                ctx.definition_depth > 0,
766            );
767            if text.is_empty() {
768                String::new()
769            } else {
770                format!("{text}\n\n")
771            }
772        }
773        BlockNode::CodeBlock(code) => {
774            let content = resolve_nbsp(&strip_controls(&code.content));
775            let mut info = code
776                .lang
777                .as_deref()
778                .map(sanitize_code_lang)
779                .filter(|lang| !lang.is_empty())
780                .unwrap_or_default();
781            // The EFFECTIVE title, not the authored header. An attribute line above
782            // the fence overrides a title written in the header, and the HTML
783            // target uses the winner -- so emitting `code.title` here described the
784            // document differently in the two targets, announcing a title that had
785            // lost (carve#352, corpus 11-fenced-code-10). The parser resolves the
786            // override into `attrs`, so that is where the answer already is.
787            let effective_title = code
788                .attrs
789                .as_ref()
790                .and_then(|attrs| attrs.key_values.get("title"))
791                .or(code.title.as_ref());
792            if effective_title.is_some() && info.is_empty() && !ctx.roundtrip {
793                crate::render_loss::record_markdown_loss(
794                    MarkdownLoss::FenceTitle,
795                    RawNodeType::Block,
796                    code.pos.as_ref(),
797                );
798            }
799            // A title needs a LANGUAGE in front of it. In Markdown the info
800            // string's first token IS the language, so `` ``` "notes.txt" ``
801            // makes a CommonMark reader emit
802            // `class="language-&quot;notes.txt&quot;"` -- measured against
803            // commonmark.js. Markdown cannot express a fence title on its own, so
804            // dropping it beats emitting a bogus language; with a language present
805            // the title is ignored by every consumer and rides along safely.
806            // carve-php had this guard and was right about it (carve#352, corpus
807            // 11-fenced-code-8).
808            if let Some(title) = effective_title.filter(|_| !info.is_empty()) {
809                info.push_str(&format!(" \"{}\"", escape_code_title(title)));
810            }
811            // A grouping `[label]` rides along after the language and title.
812            // Dropping it was silent data loss: an info string is free-form
813            // after the first word, so every consumer ignores what it does not
814            // understand, and carve-php was already emitting it (carve#352).
815            if let Some(label) = &code.label {
816                if !label.is_empty() {
817                    let cleaned: String =
818                        label.chars().filter(|c| !matches!(c, '[' | ']')).collect();
819                    info.push_str(&format!(" [{cleaned}]"));
820                }
821            }
822            let fence =
823                safe_fence_with_marker(&content, 3, if info.contains('`') { '~' } else { '`' });
824            let ending = if !content.is_empty() && !content.ends_with('\n') {
825                "\n"
826            } else {
827                ""
828            };
829            let info_separator = if fence.starts_with('~') && info.starts_with('~') {
830                " "
831            } else {
832                ""
833            };
834            note_inserted(C_PAYLOAD_BOUNDARY);
835            note_inserted(C_PAYLOAD_BOUNDARY);
836            let boundary = carrier(C_PAYLOAD_BOUNDARY);
837            let body = format!(
838                "{fence}{info_separator}{info}{boundary}\n{content}{boundary}{ending}{fence}\n\n"
839            );
840            if ctx.roundtrip {
841                if let Some(marker) = crate::carrier_markers::code_fence_marker(code) {
842                    format!("{marker}\n{body}")
843                } else {
844                    body
845                }
846            } else {
847                body
848            }
849        }
850        BlockNode::BlockQuote(quote) => {
851            let outer = ctx.previous_list.take();
852            let lines = render_blocks(&quote.children, ctx, depth + 1);
853            ctx.previous_list = outer;
854            let body = trim_block_output(&lines).to_string();
855            let quoted = body
856                .split('\n')
857                .map(|line| {
858                    if line.is_empty() {
859                        ">".to_string()
860                    } else {
861                        format!("> {line}")
862                    }
863                })
864                .collect::<Vec<_>>()
865                .join("\n");
866            format!("{quoted}\n\n")
867        }
868        BlockNode::List(list) => {
869            let style_carrier = ctx.roundtrip
870                && list.ordered
871                && list.ol_type.is_some()
872                && ctx.list_item_opening_list != Some(list as *const List as usize)
873                && (!ctx.in_footnote
874                    || ctx
875                        .footnote_allowed_lists
876                        .contains(&(list as *const List as usize)));
877            if let Some(style) = list.ol_type.filter(|_| !style_carrier) {
878                crate::render_loss::record_list_style_dropped(style, list.pos.as_ref());
879            }
880            // The marker the list would take, switched when the list written
881            // just before it in this flow is of the same kind and used it.
882            let usual = if list.ordered {
883                if list.delim == Some(')') {
884                    ')'
885                } else {
886                    '.'
887                }
888            } else {
889                list.bullet_char.unwrap_or('-')
890            };
891            let marker = match ctx.previous_list.filter(|_| !style_carrier) {
892                Some((ordered, previous)) if ordered == list.ordered && previous == usual => {
893                    match usual {
894                        '.' => ')',
895                        ')' => '.',
896                        '-' => '*',
897                        _ => '-',
898                    }
899                }
900                _ => usual,
901            };
902            if list.ordered && marker != usual {
903                crate::render_loss::record_list_delimiter_changed(usual, marker, list.pos.as_ref());
904            }
905            let mut out = render_list(list, ctx, depth + 1, marker);
906            if style_carrier {
907                let start = list.start.unwrap_or(1);
908                let style = list.ol_type;
909                let first = crate::render_carve::ordered_marker(start, style);
910                let second = if first.len() == 1
911                    && first.bytes().all(|ch| b"ivxlcdmIVXLCDM".contains(&ch))
912                    && list.items.len() > 1
913                {
914                    format!(
915                        " {}{}",
916                        crate::render_carve::ordered_marker(start + 1, style),
917                        usual
918                    )
919                } else {
920                    String::new()
921                };
922                out = format!(
923                    "{}\n{out}",
924                    carrier_line(&format!("{first}{usual}{second}"))
925                );
926            }
927            if !out.trim().is_empty() {
928                ctx.previous_list = Some((list.ordered, marker));
929            }
930            out
931        }
932        BlockNode::ThematicBreak(_) => if ctx.thematic_glued {
933            "***\n\n"
934        } else {
935            "---\n\n"
936        }
937        .to_string(),
938        BlockNode::Table(table) => render_table(table, ctx),
939        BlockNode::Admonition(admonition) => {
940            if let Some(table) = list_table_as_table(admonition) {
941                let table = render_table(&table, ctx);
942                return match admonition.label.as_deref().filter(|l| !l.is_empty()) {
943                    Some(label) => {
944                        ctx.previous_list = None;
945                        prepend_label(table, Some(label))
946                    }
947                    None => table,
948                };
949            }
950            // Markdown has no admonition; preserve the title (otherwise lost)
951            // as a leading bold line, then the body. Both are written before
952            // the body, so they separate it from a list above (§10o).
953            let title = admonition
954                .title
955                .as_ref()
956                .map(|title| render_title_inlines(title, ctx));
957            if title.as_ref().is_some_and(|t| !t.is_empty())
958                || admonition.label.as_deref().is_some_and(|l| !l.is_empty())
959            {
960                ctx.previous_list = None;
961            }
962            let markers = carrier_markers(node, ctx);
963            let body = carried_children(&admonition.children, markers.as_ref(), ctx, depth + 1);
964            // The LABEL goes on first so the TITLE ends up above it, which is the
965            // order the source writes them (`::: tip "Pro Tip" [Build]`) and the
966            // order the HTML renderer emits (carve#352, corpus 42-admonitions-4).
967            let body = prepend_label(body, admonition.label.as_deref());
968            let body = match title {
969                Some(t) if !t.is_empty() => format!("{t}\n\n{body}"),
970                _ => body,
971            };
972            carried(markers.as_ref(), body)
973        }
974        BlockNode::LineBlock(lb) => {
975            let markers = carrier_markers(node, ctx);
976            let body = carried_children(&lb.children, markers.as_ref(), ctx, depth + 1);
977            carried(markers.as_ref(), body)
978        }
979        BlockNode::Directive(d) => {
980            let title = d
981                .title
982                .as_ref()
983                .map(|title| render_title_inlines(title, ctx));
984            if title.as_ref().is_some_and(|t| !t.is_empty())
985                || d.label.as_deref().is_some_and(|l| !l.is_empty())
986            {
987                ctx.previous_list = None;
988            }
989            let markers = carrier_markers(node, ctx);
990            let body = carried_children(&d.children, markers.as_ref(), ctx, depth + 1);
991            let body = prepend_label(body, d.label.as_deref());
992            let body = match title {
993                Some(t) if !t.is_empty() => format!("{t}\n\n{body}"),
994                _ => body,
995            };
996            carried(markers.as_ref(), body)
997        }
998        BlockNode::Div(div) => {
999            if !ctx.roundtrip {
1000                crate::render_loss::record_markdown_loss(
1001                    MarkdownLoss::Container,
1002                    RawNodeType::Block,
1003                    div.pos.as_ref(),
1004                );
1005            }
1006            if div.label.as_deref().is_some_and(|l| !l.is_empty()) {
1007                ctx.previous_list = None;
1008            }
1009            let markers = carrier_markers(node, ctx);
1010            let body = carried_children(&div.children, markers.as_ref(), ctx, depth + 1);
1011            carried(markers.as_ref(), prepend_label(body, div.label.as_deref()))
1012        }
1013        BlockNode::Section(section) => render_blocks(&section.children, ctx, depth + 1),
1014        BlockNode::DefinitionList(list) => {
1015            if ctx.roundtrip && ctx.single_line_depth > 0 {
1016                crate::render_loss::record_definition_list_flattened(list.pos.as_ref());
1017            }
1018            render_definition_list(&list.items, ctx, depth + 1)
1019        }
1020        BlockNode::Figure(figure) => render_figure(figure, ctx, depth + 1),
1021        BlockNode::FigureGroup(group) => render_figure_group(group, ctx, depth + 1),
1022        // A standalone block image is its own block: terminate it so the next
1023        // block is not glued onto the image (render_image stays newline-free
1024        // because it is shared with inline image rendering).
1025        BlockNode::BlockImage(image) => format!("{}\n\n", render_image(image)),
1026        BlockNode::RawBlock(raw) => {
1027            if raw.format == "html" {
1028                crate::render_loss::record_markdown_loss(
1029                    MarkdownLoss::RawHtml,
1030                    RawNodeType::Block,
1031                    raw.pos.as_ref(),
1032                );
1033                // Escape, not emit: raw HTML in Markdown would be live again
1034                // when the Markdown is rendered to HTML downstream.
1035                format!(
1036                    "{}\n\n",
1037                    escape_md_html(&strip_controls(raw.target_content()))
1038                )
1039            } else {
1040                crate::render_loss::record_raw_drop(
1041                    &raw.format,
1042                    crate::RawNodeType::Block,
1043                    raw.pos.clone(),
1044                );
1045                String::new()
1046            }
1047        }
1048        BlockNode::BlockExtension(n) => render_block(&n.fallback, ctx, depth),
1049        BlockNode::ExtensionCarrier(extension) => {
1050            render_blocks(&extension.children, ctx, depth + 1)
1051        }
1052        // PART 11 §10a: a definition NOTHING references still reaches this
1053        // target. HTML drops it because it has nowhere to put one; Markdown,
1054        // plain text and the terminal do not get to drop content the author
1055        // wrote, and dropping it made the output depend on whether a reference
1056        // exists elsewhere in the document (carve#589).
1057        // The definition line goes through `escape_md_html` for the same reason
1058        // the `<abbr>` built from it does: an expansion is author content, and
1059        // this target's contract is that embedded HTML cannot become live
1060        // markup downstream. Writing the occurrence escaped and the definition
1061        // raw made one output disagree with itself (carve-rs#807).
1062        BlockNode::AbbreviationDef(def) => format!(
1063            "*[{}]: {}\n\n",
1064            escape_md_html(&strip_controls(&def.abbr)),
1065            escape_md_html(&strip_controls(&def.expansion))
1066        ),
1067        BlockNode::Comment(_) => String::new(),
1068    }
1069}
1070
1071/// Keep a paragraph's lines reading as paragraph text in Markdown readers: no
1072/// edge whitespace (PART 11 §10m), no list, quote, thematic-break or setext
1073/// opener (§8a M1c, §8d, §8g). The paragraph is one string here, so a marker
1074/// split across inline nodes is seen whole.
1075fn protect_paragraph_list_markers(text: &str, in_definition: bool) -> String {
1076    if !inline_marker_ranges(text).is_empty() {
1077        let mut code_fence = 0;
1078        return text
1079            .split('\n')
1080            .map(|line| {
1081                let visible = visible_inline(line);
1082                let inside_code = code_fence != 0;
1083                code_fence = code_span_state_after(&visible, code_fence);
1084                if inside_code {
1085                    return line.to_owned();
1086                }
1087                let core = inline_padding(line, |ch| ch == ' ' || ch == '\t').1;
1088                let visible = visible_inline(&core);
1089                let protected = protect_paragraph_list_markers(&visible, in_definition);
1090                restore_inline_change(&core, &visible, &protected)
1091            })
1092            .collect::<Vec<_>>()
1093            .join("\n");
1094    }
1095    let lines: Vec<&str> = text.split('\n').collect();
1096    let last = lines.len() - 1;
1097    let mut output = String::with_capacity(text.len());
1098    let mut code_fence = 0usize;
1099    let mut written = 0usize;
1100    for (line_index, source_line) in lines.iter().enumerate() {
1101        let open_at_start = code_fence != 0;
1102        code_fence = code_span_state_after(source_line, code_fence);
1103        let mut line = if open_at_start {
1104            (*source_line).to_string()
1105        } else {
1106            source_line.trim_start_matches([' ', '\t']).to_string()
1107        };
1108        if code_fence == 0 {
1109            let backslashes = line.chars().rev().take_while(|c| *c == '\\').count();
1110            line = if backslashes % 2 == 1 && line_index < last {
1111                let body = &line[..line.len() - 1];
1112                format!("{}\\", body.trim_end_matches([' ', '\t']))
1113            } else {
1114                line.trim_end_matches([' ', '\t']).to_string()
1115            };
1116        }
1117        // A line trimming empties is not written: it would end the paragraph.
1118        if line.is_empty() {
1119            continue;
1120        }
1121        if !open_at_start {
1122            // The underscore still stands as its carrier here, so the test reads
1123            // it as `_` and an escape on it writes the character itself.
1124            // So does §8i's `.`, which can be an ordered marker's delimiter.
1125            let underscore = carrier(C_UNDERSCORE);
1126            let dot = carrier(C_WWW_DOT);
1127            let view = if line.contains(underscore.as_str()) || line.contains(dot.as_str()) {
1128                std::borrow::Cow::Owned(
1129                    line.replace(underscore.as_str(), "_")
1130                        .replace(dot.as_str(), "."),
1131                )
1132            } else {
1133                std::borrow::Cow::Borrowed(line.as_str())
1134            };
1135            if let Some(at) = paragraph_marker_escape(&view, written == 0, in_definition) {
1136                if line[at..].starts_with(underscore.as_str()) {
1137                    note_assembled(&line[at..at + underscore.len()]);
1138                    line.replace_range(at..at + underscore.len(), "\\_");
1139                } else if line[at..].starts_with(dot.as_str()) {
1140                    note_assembled(&line[at..at + dot.len()]);
1141                    line.replace_range(at..at + dot.len(), "\\.");
1142                } else {
1143                    line.insert(at, '\\');
1144                }
1145            }
1146        }
1147        if written > 0 {
1148            output.push('\n');
1149        }
1150        output.push_str(&line);
1151        written += 1;
1152    }
1153    output
1154}
1155
1156/// Where a paragraph line needs a backslash so a reader does not open a block
1157/// on it, if anywhere. The line carries no leading whitespace.
1158fn paragraph_marker_escape(line: &str, first: bool, in_definition: bool) -> Option<usize> {
1159    let bytes = line.as_bytes();
1160    let first_byte = *bytes.first()?;
1161    // M1c, and §8g T3 for a marker with nothing after it.
1162    if matches!(first_byte, b'-' | b'+')
1163        && (bytes.len() == 1 && first || matches!(bytes.get(1), Some(b' ' | b'\t')))
1164    {
1165        return Some(0);
1166    }
1167    // A literal marker line can open or attach to a definition after import.
1168    if first_byte == b':'
1169        && ((in_definition && matches!(bytes.get(1), None | Some(b' ' | b'\t')))
1170            || (bytes.get(1) == Some(&b':') && matches!(bytes.get(2), Some(b' ' | b'\t'))))
1171    {
1172        return Some(0);
1173    }
1174    let digits = bytes
1175        .iter()
1176        .take(10)
1177        .take_while(|b| b.is_ascii_digit())
1178        .count();
1179    if (1..=9).contains(&digits) && matches!(bytes.get(digits), Some(b'.' | b')')) {
1180        let after = bytes.get(digits + 1);
1181        if matches!(after, Some(b' ' | b'\t')) || after.is_none() && first {
1182            return Some(digits);
1183        }
1184    }
1185    // A `>` opens a block quote with or without a space after it.
1186    if first_byte == b'>' {
1187        return Some(0);
1188    }
1189    // §8g T2: a setext underline below the paragraph's first line.
1190    if !first && matches!(first_byte, b'=' | b'-') && bytes.iter().all(|b| *b == first_byte) {
1191        return Some(0);
1192    }
1193    // §8g T1: a thematic break.
1194    if matches!(first_byte, b'-' | b'_' | b'*')
1195        && bytes
1196            .iter()
1197            .all(|b| *b == first_byte || matches!(b, b' ' | b'\t'))
1198        && bytes.iter().filter(|b| **b == first_byte).count() >= 3
1199    {
1200        return Some(0);
1201    }
1202    None
1203}
1204
1205/// Whether a code span is still open after `line`, given the run length that
1206/// was open before it (0 for none).
1207fn code_span_state_after(line: &str, mut code_fence: usize) -> usize {
1208    let bytes = line.as_bytes();
1209    let mut i = 0usize;
1210    while i < bytes.len() {
1211        if bytes[i] != b'`' {
1212            i += 1;
1213            continue;
1214        }
1215        let mut backslashes = 0usize;
1216        let mut before = i;
1217        while before > 0 && bytes[before - 1] == b'\\' {
1218            backslashes += 1;
1219            before -= 1;
1220        }
1221        let mut run = 1usize;
1222        while i + run < bytes.len() && bytes[i + run] == b'`' {
1223            run += 1;
1224        }
1225        if backslashes % 2 == 0 {
1226            if code_fence == 0 {
1227                code_fence = run;
1228            } else if code_fence == run {
1229                code_fence = 0;
1230            }
1231        }
1232        i += run;
1233    }
1234    code_fence
1235}
1236
1237fn render_list(node: &List, ctx: &mut MarkdownContext, depth: usize, marker: char) -> String {
1238    if depth > MAX_RENDER_DEPTH {
1239        crate::render_depth::record("markdown");
1240        return String::new();
1241    }
1242    ctx.list_depth += 1;
1243    let tight = node.effective_tight();
1244    let mut out = String::new();
1245    let mut counter = node.start.unwrap_or(1);
1246    // The authored bullet and delimiter, not normalized ones: a change of
1247    // either is what SEPARATES two adjacent lists in CommonMark (carve#352),
1248    // switched by the caller where the list above used the same one (§10o).
1249    let bullet = marker;
1250    let delim = marker;
1251    let last = node.items.len().saturating_sub(1);
1252    for (index, item) in node.items.iter().enumerate() {
1253        // The pad is the item's CONTENT COLUMN, which is only the same as the
1254        // printed prefix where the whole prefix is the marker. A task item's
1255        // `[x] ` is the first inline of its first paragraph, so padding by it puts
1256        // every block below four columns past where a reader looks for them
1257        // (carve-rs#1912, carve-rs#1929).
1258        let (prefix, pad) = if node.ordered {
1259            let prefix = format!("{counter}{delim} ");
1260            counter += 1;
1261            let pad = prefix.len();
1262            (prefix, pad)
1263        } else if let Some(checked) = item.checked {
1264            let box_mark = if checked { 'x' } else { ' ' };
1265            (format!("{bullet} [{box_mark}] "), bullet.len_utf8() + 1)
1266        } else {
1267            let prefix = format!("{bullet} ");
1268            let pad = prefix.len();
1269            (prefix, pad)
1270        };
1271        let outer = ctx.previous_list.take();
1272        let content = trim_block_output(&render_list_item(item, tight, ctx, depth + 1)).to_string();
1273        ctx.previous_list = outer;
1274        let mut lines = content.split('\n');
1275        let first = lines.next().unwrap_or_default();
1276        if first.is_empty() {
1277            out.push_str(&format!("{}\n", prefix.trim_end()));
1278        } else {
1279            out.push_str(&format!("{prefix}{first}\n"));
1280        }
1281        render_continuation_lines(&mut out, lines, pad);
1282        // A loose list is spelled with a blank line between its items. Without
1283        // it a list whose looseness lives in the item BOUNDARY reads back tight
1284        // (carve#2281): `- a` / blank / `- b` came back as two glued markers.
1285        if !tight && index < last {
1286            out.push('\n');
1287        }
1288    }
1289    ctx.list_depth -= 1;
1290    if ctx.list_depth == 0 {
1291        out.push('\n');
1292    }
1293    out
1294}
1295
1296/// A tight item's blocks, with the separator blank dropped where the block
1297/// below can stand without it.
1298///
1299/// Every block leaves one blank line behind it, and inside a list item that
1300/// blank is what makes the item LOOSE in CommonMark - `<li><p>parent</p>` where
1301/// the document says `<li>parent`. The blank can only go where the following
1302/// opener interrupts a paragraph on its own, which is why this asks per child
1303/// instead of never writing it (carve#2281).
1304///
1305/// The block ABOVE has a say too: on some pairs the unseparated opener is
1306/// swallowed by the text above instead of interrupting it, and a block is lost
1307/// (carve-rs#1924).
1308fn render_list_item(
1309    item: &ListItem,
1310    tight: bool,
1311    ctx: &mut MarkdownContext,
1312    depth: usize,
1313) -> String {
1314    if depth > MAX_RENDER_DEPTH {
1315        crate::render_depth::record("markdown");
1316        return String::new();
1317    }
1318    let mut out = String::new();
1319    for (index, child) in item.children.iter().enumerate() {
1320        let outer_opening = ctx.list_item_opening_list;
1321        if out.is_empty() {
1322            ctx.list_item_opening_list = match child {
1323                BlockNode::List(list) => Some(list as *const List as usize),
1324                _ => None,
1325            };
1326        }
1327        let non_setext = tight
1328            && matches!(opening_block(child), BlockNode::ThematicBreak(_))
1329            && out.ends_with("\n\n");
1330        let previous_thematic = std::mem::replace(&mut ctx.thematic_glued, non_setext);
1331        let rendered = render_block(child, ctx, depth);
1332        ctx.thematic_glued = previous_thematic;
1333        ctx.list_item_opening_list = outer_opening;
1334        // Check the block that opens the rendered output through any div wrappers.
1335        let opener = opening_block(child);
1336        if tight
1337            && out.ends_with("\n\n")
1338            && (interrupts_a_paragraph(opener, &rendered)
1339                || matches!(opener, BlockNode::ThematicBreak(_))
1340                || matches!(opener, BlockNode::Paragraph(_))
1341                    && index > 0
1342                    && matches!(
1343                        closing_block(&item.children[index - 1]),
1344                        BlockNode::CodeBlock(_)
1345                    ))
1346            && !absorbs_below(&out, opener)
1347        {
1348            out.pop();
1349        } else if out.ends_with('\n')
1350            && !out.ends_with("\n\n")
1351            && swallowed_by_a_lazy_line(&out, &rendered)
1352        {
1353            out.push('\n');
1354        }
1355        out.push_str(&rendered);
1356    }
1357    out
1358}
1359
1360/// Whether the block below is read as more text of the block above because no
1361/// blank line separates them and its own spelling opens with plain text.
1362///
1363/// A nested list is the only block this target writes with no blank line behind
1364/// it, so this is the seam the tight-item predicate cannot reach: it decides
1365/// about a blank that was never written. A table is in the swallowed set even
1366/// though its delimiter row promotes a paragraph at the same level, because a
1367/// lazy continuation line cannot open one - the rows arrive as the last nested
1368/// item's text and the table does not reach the output (carve-rs#1930).
1369///
1370/// The tail has to be able to TAKE lazy text, which a bare marker and a heading
1371/// cannot, so those stay glued and the item stays tight.
1372///
1373/// `rendered` is the block's own output, so a div wrapper is judged by the
1374/// paragraph it opens with (carve-rs#2136).
1375fn swallowed_by_a_lazy_line(above_text: &str, rendered: &str) -> bool {
1376    // Decided from the emitted first line, so an image, a figure or a wrapper
1377    // that opens with text counts as well (carve-rs#2973). A setext underline
1378    // cannot be lazy text, so a thematic break leaves the item above it alone.
1379    let first = rendered.split('\n').next().unwrap_or_default();
1380    if first.trim().is_empty() || thematic_break_line(first) || opens_an_interrupter(first) {
1381        return false;
1382    }
1383    let tail = above_text
1384        .lines()
1385        .rev()
1386        .find(|line| !line.trim().is_empty())
1387        .unwrap_or_default()
1388        .trim_start_matches([' ', '\t']);
1389    let boundary = carrier(C_PAYLOAD_BOUNDARY);
1390    let tail = tail.strip_prefix(boundary.as_str()).unwrap_or(tail);
1391    if bare_marker_line(tail) || thematic_break_line(tail) {
1392        return false;
1393    }
1394    let text = marker_content(tail);
1395    !text.is_empty() && !text.starts_with(['#', '>', '|', '`', '~', '='])
1396}
1397
1398/// Whether `line` opens a block that interrupts a paragraph in CommonMark.
1399fn opens_an_interrupter(line: &str) -> bool {
1400    let hashes = line.len() - line.trim_start_matches('#').len();
1401    let bullet = line
1402        .strip_prefix(['-', '*', '+'])
1403        .or_else(|| line.strip_prefix("1.").or_else(|| line.strip_prefix("1)")));
1404    line.starts_with('>')
1405        || ((1..=6).contains(&hashes)
1406            && (line.len() == hashes || line[hashes..].starts_with([' ', '\t'])))
1407        || line.starts_with("```")
1408        || line.starts_with("~~~")
1409        || bullet.is_some_and(|rest| {
1410            rest.starts_with([' ', '\t']) && !rest.trim_start_matches([' ', '\t']).is_empty()
1411        })
1412        || (line.starts_with('*')
1413            && line.matches('*').count() >= 3
1414            && line.chars().all(|c| matches!(c, '*' | ' ' | '\t')))
1415}
1416
1417/// A line's content with one list marker removed, for the marker lines a nested
1418/// list ends on.
1419fn marker_content(line: &str) -> &str {
1420    if let Some(rest) = line.strip_prefix(['-', '*', '+']) {
1421        if let Some(rest) = rest.strip_prefix(' ') {
1422            return rest.trim_start_matches(' ');
1423        }
1424    }
1425    let digits = line.trim_start_matches(|c: char| c.is_ascii_digit());
1426    if digits.len() < line.len() {
1427        if let Some(rest) = digits.strip_prefix(['.', ')']) {
1428            if let Some(rest) = rest.strip_prefix(' ') {
1429                return rest.trim_start_matches(' ');
1430            }
1431        }
1432    }
1433    line
1434}
1435
1436/// A run of three or more of one break character, which closes everything above
1437/// it rather than continuing it.
1438fn thematic_break_line(line: &str) -> bool {
1439    let line = line.trim_end_matches([' ', '\t']);
1440    let Some(first) = line.chars().next() else {
1441        return false;
1442    };
1443    matches!(first, '-' | '*' | '_') && line.len() >= 3 && line.chars().all(|c| c == first)
1444}
1445
1446/// Whether removing the blank makes the text above swallow this block.
1447///
1448/// Measured against cmark-gfm 0.29.0.gfm.13 over every pair of the block kinds
1449/// that reach a tight item: a quote absorbs a following quote and a following
1450/// table, and a table absorbs a following table. Every other pair keeps both
1451/// blocks.
1452///
1453/// A list absorbs a following table too, and that pair is NOT here: a nested list
1454/// leaves no blank line behind it, so the separator this decides about was never
1455/// written and the table is glued whatever this answers (carve-rs#1930).
1456///
1457/// The WRITTEN tail answers it, not the sibling above. A wrapper this target
1458/// renders transparently - a div, a line block, an admonition - can end in a
1459/// quote or a table without being one, and a child it writes nothing for leaves
1460/// the seam where it already was.
1461fn absorbs_below(above_text: &str, below: &BlockNode) -> bool {
1462    let tail = above_text
1463        .lines()
1464        .rev()
1465        .find(|line| !line.trim().is_empty())
1466        .unwrap_or_default()
1467        .trim_start_matches([' ', '\t']);
1468    match below {
1469        BlockNode::BlockQuote(_) => tail.starts_with('>'),
1470        BlockNode::Table(_) => tail.starts_with(['>', '|']),
1471        BlockNode::Figure(figure) => match &*figure.target {
1472            FigureTarget::BlockQuote(_) => tail.starts_with('>'),
1473            FigureTarget::Table(_) => tail.starts_with(['>', '|']),
1474            _ => false,
1475        },
1476        _ => false,
1477    }
1478}
1479
1480/// Whether this block's Markdown spelling starts a block directly below a
1481/// paragraph line, with no blank line between them.
1482fn interrupts_a_paragraph(node: &BlockNode, rendered: &str) -> bool {
1483    // A roundtrip carrier is an HTML comment block, which interrupts a paragraph
1484    // whatever the block it carries opens with.
1485    if rendered.starts_with("<!--") {
1486        return true;
1487    }
1488    match node {
1489        // A quote marker always interrupts.
1490        BlockNode::BlockQuote(_) => true,
1491        // CARVE-P11-047 states a property and names two spellings as examples.
1492        // An ATX heading and a fence carry it too: both open below a paragraph
1493        // line in cmark-gfm 0.29.0.gfm.13 (carve-rs#1914). A thematic break does
1494        // NOT belong here - this target spells it `---`, which under a paragraph
1495        // is a setext underline and turns the paragraph into a heading instead of
1496        // interrupting it.
1497        BlockNode::Heading(_) | BlockNode::CodeBlock(_) => true,
1498        // A GFM table opens only where the delimiter row promotes the row above
1499        // it. A headerless table writes rows alone, and those are read as lazy
1500        // continuation of the paragraph, so its text would be swallowed into the
1501        // paragraph rather than gaining a table.
1502        BlockNode::Table(_) => has_delimiter_row(rendered),
1503        BlockNode::List(list) => {
1504            // An ordered marker that does not start at 1 cannot interrupt, and a
1505            // marker with nothing after it reads as a setext underline. Both
1506            // shapes need the blank to stay lists at all.
1507            if list.ordered && list.start.unwrap_or(1) != 1 {
1508                return false;
1509            }
1510            !bare_marker_line(rendered.split('\n').next().unwrap_or_default())
1511        }
1512        // A figure writes its target first, so the target's opener decides
1513        // (carve-rs#2968). Its first line is checked so a carrier written
1514        // ahead of the target keeps the blank.
1515        BlockNode::Figure(figure) => {
1516            let first = rendered.split('\n').next().unwrap_or_default();
1517            match &*figure.target {
1518                FigureTarget::BlockQuote(_) => first.starts_with('>'),
1519                FigureTarget::CodeBlock(_) => first.starts_with("```") || first.starts_with("~~~"),
1520                FigureTarget::Table(_) => first.starts_with('|') && has_delimiter_row(rendered),
1521                FigureTarget::Image(_) | FigureTarget::Paragraph(_) => false,
1522            }
1523        }
1524        _ => false,
1525    }
1526}
1527
1528/// The block whose own markup opens this child's Markdown output.
1529///
1530/// Unlabelled containers and line blocks write their first child's opener.
1531/// A label or title writes text before that child and opens as its own block.
1532fn opening_block(node: &BlockNode) -> &BlockNode {
1533    let mut node = node;
1534    loop {
1535        let children = match node {
1536            BlockNode::Div(div) if div.label.as_deref().unwrap_or_default().is_empty() => {
1537                &div.children
1538            }
1539            BlockNode::Admonition(admonition)
1540                if admonition.label.as_deref().unwrap_or_default().is_empty()
1541                    && admonition.title.as_ref().map_or(true, Vec::is_empty) =>
1542            {
1543                &admonition.children
1544            }
1545            BlockNode::LineBlock(line) => &line.children,
1546            _ => break,
1547        };
1548        match children.first() {
1549            Some(first) => node = first,
1550            None => break,
1551        }
1552    }
1553    node
1554}
1555
1556fn closing_block(mut node: &BlockNode) -> &BlockNode {
1557    while let BlockNode::Div(div) = node {
1558        match div.children.last() {
1559            Some(last) => node = last,
1560            None => break,
1561        }
1562    }
1563    node
1564}
1565
1566/// Whether a rendered table's second line is the delimiter row, which is what
1567/// makes a GFM reader see a table at all.
1568fn has_delimiter_row(rendered: &str) -> bool {
1569    let Some(second) = rendered.split('\n').nth(1) else {
1570        return false;
1571    };
1572    second.contains('-')
1573        && second
1574            .chars()
1575            .all(|c| matches!(c, '|' | '-' | ':' | ' ' | '\t'))
1576}
1577
1578/// A list marker with no content after it: `-`, `*`, `1.`, `1)`.
1579fn bare_marker_line(line: &str) -> bool {
1580    let line = line.trim_end_matches(' ');
1581    if let Some(rest) = line.strip_prefix(['-', '*', '+']) {
1582        return rest.is_empty();
1583    }
1584    let rest = line.trim_start_matches(|c: char| c.is_ascii_digit());
1585    rest.len() < line.len() && matches!(rest, "." | ")")
1586}
1587
1588/// PART 11 §10p: GFM has no definition list, and a `: ` marker is literal
1589/// there, so each term is written as a paragraph of strong text and each
1590/// description's blocks as ordinary blocks in the same flow.
1591fn render_definition_list(
1592    items: &[DefinitionItem],
1593    ctx: &mut MarkdownContext,
1594    depth: usize,
1595) -> String {
1596    if depth > MAX_RENDER_DEPTH {
1597        crate::render_depth::record("markdown");
1598        return String::new();
1599    }
1600    let carried = ctx.roundtrip && ctx.single_line_depth == 0;
1601    ctx.definition_depth += 1;
1602    let carrier_depth = ctx.definition_depth;
1603    let mut out = String::new();
1604    for item in items {
1605        for term in &item.terms {
1606            if carried {
1607                out.push_str(&inline_carrier_at("::", term, carrier_depth));
1608                out.push('\n');
1609            }
1610            let term = render_wrapped_inlines(term, ctx, "**", "<strong>", "</strong>");
1611            if !term.is_empty() {
1612                ctx.previous_list = None;
1613                out.push_str(&term);
1614                out.push_str("\n\n");
1615            }
1616        }
1617        for definition in &item.definitions {
1618            if carried {
1619                out.push_str(&carrier_line_at(":", carrier_depth));
1620                out.push('\n');
1621            }
1622            out.push_str(&render_blocks(definition, ctx, depth + 1));
1623        }
1624    }
1625    if carried {
1626        out.push_str(&carrier_line_at("", carrier_depth));
1627        out.push_str("\n\n");
1628    }
1629    ctx.definition_depth -= 1;
1630    out
1631}
1632
1633/// A `header-rows` / `header-cols` value as the ListTable extension reads it.
1634fn list_table_count(value: Option<&String>) -> usize {
1635    match value {
1636        None => 0,
1637        Some(v) if v.trim().is_empty() => 1,
1638        Some(v) => {
1639            let digits: String = v
1640                .trim_start()
1641                .chars()
1642                .enumerate()
1643                .take_while(|(i, c)| c.is_ascii_digit() || (*i == 0 && (*c == '-' || *c == '+')))
1644                .map(|(_, c)| c)
1645                .collect();
1646            digits.parse::<i64>().map_or(0, |n| n.max(0) as usize)
1647        }
1648    }
1649}
1650
1651/// The pipe table a `::: list-table` is equivalent to (PART 11 §10q,
1652/// CARVE-P11-059), or `None` when its body is not a grid.
1653fn list_table_outer(node: &Admonition) -> Option<&List> {
1654    if node.kind != "list-table" {
1655        return None;
1656    }
1657    let [BlockNode::List(outer)] = node.children.as_slice() else {
1658        return None;
1659    };
1660    if outer
1661        .items
1662        .iter()
1663        .any(|row| !matches!(row.children.first(), Some(BlockNode::List(_))))
1664    {
1665        return None;
1666    }
1667    Some(outer)
1668}
1669
1670fn list_table_as_table(node: &Admonition) -> Option<Table> {
1671    let outer = list_table_outer(node)?;
1672    let empty = std::collections::BTreeMap::new();
1673    let kv = node.attrs.as_ref().map_or(&empty, |a| &a.key_values);
1674    let header_rows = list_table_count(kv.get("header-rows"));
1675    let header_cols = list_table_count(kv.get("header-cols"));
1676    let aligns: Vec<&str> = kv
1677        .get("aligns")
1678        .map(|v| v.split(',').map(str::trim).collect())
1679        .unwrap_or_default();
1680    let align_of = |value: &str| match value {
1681        "left" => Some(TableAlign::Left),
1682        "right" => Some(TableAlign::Right),
1683        "center" => Some(TableAlign::Center),
1684        _ => None,
1685    };
1686    let cell = |header: bool, span: Option<TableCellSpan>, align: Option<TableAlign>| TableCell {
1687        header,
1688        span,
1689        colspan: None,
1690        rowspan: None,
1691        align,
1692        valign: None,
1693        attrs: None,
1694        children: Vec::new(),
1695        blocks: None,
1696        pos: None,
1697    };
1698    let mut rows = Vec::with_capacity(outer.items.len());
1699    for (r, row) in outer.items.iter().enumerate() {
1700        // Every list in the row gives cells; any other block joins the cell before it.
1701        let mut entries: Vec<(&ListItem, Vec<BlockNode>)> = Vec::new();
1702        for block in &row.children {
1703            match block {
1704                BlockNode::List(inner) => {
1705                    entries.extend(inner.items.iter().map(|item| (item, item.children.clone())))
1706                }
1707                other => entries.last_mut()?.1.push(other.clone()),
1708            }
1709        }
1710        let header_row = r < header_rows
1711            || entries
1712                .first()
1713                .and_then(|(item, _)| item.attrs.as_ref())
1714                .is_some_and(|a| a.key_values.contains_key("header-row"));
1715        let mut cells = Vec::with_capacity(entries.len());
1716        for (c, (item, blocks)) in entries.into_iter().enumerate() {
1717            if item.attrs.is_none() {
1718                if let [BlockNode::Paragraph(p)] = blocks.as_slice() {
1719                    if let (None, [InlineNode::Text(t)]) = (&p.attrs, p.children.as_slice()) {
1720                        match t.value.trim() {
1721                            "^" => {
1722                                cells.push(cell(false, Some(TableCellSpan::Rowspan), None));
1723                                continue;
1724                            }
1725                            "<" => {
1726                                cells.push(cell(false, Some(TableCellSpan::Colspan), None));
1727                                continue;
1728                            }
1729                            _ => {}
1730                        }
1731                    }
1732                }
1733            }
1734            let own = item.attrs.as_ref().map(|a| &a.key_values);
1735            let align = own
1736                .and_then(|kv| kv.get("align"))
1737                .and_then(|v| align_of(v))
1738                .or_else(|| aligns.get(c).and_then(|v| align_of(v)));
1739            let header =
1740                header_row || c < header_cols || own.is_some_and(|kv| kv.contains_key("header"));
1741            let mut built = cell(header, None, align);
1742            match blocks.as_slice() {
1743                [BlockNode::Paragraph(p)] => built.children = p.children.clone(),
1744                [] => {}
1745                _ => built.blocks = Some(blocks),
1746            }
1747            cells.push(built);
1748        }
1749        rows.push(TableRow {
1750            cells,
1751            attrs: None,
1752            continuation_lines: None,
1753            pos: None,
1754        });
1755    }
1756    Some(Table {
1757        source_format: None,
1758        attrs: None,
1759        caption: node.title.clone().filter(|t| !t.is_empty()),
1760        short_caption: None,
1761        columns: Vec::new(),
1762        rows,
1763        row_groups: None,
1764        separator_widths: None,
1765        pos: None,
1766    })
1767}
1768
1769fn render_table(node: &Table, ctx: &mut MarkdownContext) -> String {
1770    let mut header = None;
1771    let mut header_columns = 0usize;
1772    let mut rows = Vec::new();
1773    let mut aligns: Vec<Option<TableAlign>> = Vec::new();
1774    let take_aligns = |aligns: &mut Vec<Option<TableAlign>>, row: &TableRow| {
1775        for (i, cell) in row.cells.iter().enumerate() {
1776            if aligns.len() <= i {
1777                aligns.resize(i + 1, None);
1778            }
1779            if aligns[i].is_none() {
1780                aligns[i] = cell.align;
1781            }
1782        }
1783    };
1784    for (row_index, row) in node.rows.iter().enumerate() {
1785        let is_header = row
1786            .cells
1787            .iter()
1788            .all(|cell| cell.header || cell.span.is_some())
1789            && row.cells.iter().any(|cell| cell.header);
1790        if is_header && header.is_some() {
1791            crate::render_loss::record_table_header_row(row.pos.as_ref());
1792        } else if is_header && row_index > 0 {
1793            // CARVE-P11-031 writes the first header row above the body rows before it.
1794            crate::render_loss::record_table_header_row_hoisted(row.pos.as_ref());
1795        }
1796        let cells = row
1797            .cells
1798            .iter()
1799            .map(|cell| {
1800                if !is_header && cell.header && cell.span.is_none() {
1801                    crate::render_loss::record_table_header_cell(cell.pos.as_ref());
1802                }
1803                crate::render_loss::record_table_span(cell);
1804                let inlines = match &cell.blocks {
1805                    Some(blocks) => {
1806                        crate::render_plain::flatten_cell_block_inlines_with(blocks, true)
1807                    }
1808                    None => crate::render_plain::flatten_cell_inlines(
1809                        crate::ast::visible_table_cell_children(&cell.children),
1810                        true,
1811                    ),
1812                };
1813                ctx.single_line_depth += 1;
1814                let roundtrip = ctx.roundtrip;
1815                ctx.roundtrip = false;
1816                let content = trim_non_nbsp(&render_block_inlines(&inlines, ctx)).to_string();
1817                ctx.roundtrip = roundtrip;
1818                ctx.single_line_depth -= 1;
1819                escape_cell_pipes(&content)
1820            })
1821            .map(|content| content.replace(['\r', '\n'], " "))
1822            .collect::<Vec<_>>();
1823        let rendered = format!("| {} |", cells.join(" | "));
1824        // A span placeholder belongs to the cell that covers it (PART 11 §10n).
1825        if is_header {
1826            if header.is_none() {
1827                aligns.clear();
1828            }
1829            // Multiple header rows collapse to Markdown's one header row. The
1830            // last header that specifies a column alignment wins in Carve, so
1831            // the delimiter must use the same effective value.
1832            for (i, cell) in row.cells.iter().enumerate() {
1833                if aligns.len() <= i {
1834                    aligns.resize(i + 1, None);
1835                }
1836                if cell.align.is_some() {
1837                    aligns[i] = cell.align;
1838                }
1839            }
1840            if header.is_none() {
1841                header_columns = cells.len();
1842                header = Some(rendered);
1843            } else {
1844                // Markdown cannot retain another header row, but a
1845                // presentation target must retain its authored content.
1846                rows.push(rendered);
1847            }
1848        } else {
1849            rows.push(rendered);
1850            // A headerless table still declares its columns somewhere, so fall
1851            // back to the first row that carries an alignment.
1852            if header.is_none() {
1853                take_aligns(&mut aligns, row);
1854            }
1855        }
1856    }
1857    let mut out = String::new();
1858    // GFM drops every body cell past the header's width, so the header is as
1859    // wide as the widest row: an empty one where the table has none, and a
1860    // narrower one padded with empty cells (PART 11 §10n).
1861    let widest = node.rows.iter().map(|row| row.cells.len()).max();
1862    let header = header.or_else(|| {
1863        let width = widest?;
1864        header_columns = width;
1865        Some(format!("| {} |", vec![""; width].join(" | ")))
1866    });
1867    if let Some(mut header) = header {
1868        while header_columns < widest.unwrap_or(0) {
1869            header.push_str("  |");
1870            header_columns += 1;
1871        }
1872        out.push_str(&header);
1873        out.push('\n');
1874        // The delimiter matches the header row cell for cell; a padded column
1875        // takes no alignment, since only a header row sets one (§10d).
1876        let sep = (0..header_columns)
1877            .map(|i| match aligns.get(i).copied().flatten() {
1878                Some(TableAlign::Left) => ":---",
1879                Some(TableAlign::Center) => ":---:",
1880                Some(TableAlign::Right) => "---:",
1881                None => "---",
1882            })
1883            .collect::<Vec<_>>()
1884            .join(" | ");
1885        out.push_str(&format!("| {sep} |\n"));
1886    }
1887    out.push_str(&rows.join("\n"));
1888    out.push('\n');
1889    // PART 11 §10e T2. A caption is authored text, and Markdown has no
1890    // table-caption syntax, so it goes under the table as body text rather than
1891    // being dropped - the position an image caption and a listing caption
1892    // already take on this target.
1893    //
1894    // THE BLANK LINE IS LOAD-BEARING. Written directly after the last row, the
1895    // caption is read by a GFM reader as ANOTHER ROW: `| a |` then
1896    // `Fruit prices` yields `<td>a</td>` and `<td>Fruit prices</td>`. The words
1897    // survive as a fabricated data cell, which is worse than losing them,
1898    // because neither a reader nor a parser can tell it from an authored cell.
1899    // §10e states the general form: attachment by adjacency is available only on
1900    // a target where adjacency does not change what the adjacent block IS.
1901    if let Some(caption) = &node.caption {
1902        if !ctx.roundtrip && !caption.is_empty() {
1903            crate::render_loss::record_markdown_loss(
1904                MarkdownLoss::Caption,
1905                RawNodeType::Block,
1906                node.pos.as_ref(),
1907            );
1908        }
1909        let text = render_inlines(caption, ctx, 0);
1910        let text = text.trim();
1911        if !text.is_empty() {
1912            out.push('\n');
1913            out.push_str(&caption_carrier(caption, ctx));
1914            out.push_str(text);
1915            out.push('\n');
1916        }
1917    }
1918    out.push('\n');
1919    out
1920}
1921
1922/// PART 11 §10g T1: Markdown has no figure grouping, so the group degrades to
1923/// its content in order - each panel's host as it already degrades, each panel
1924/// caption as an emphasized `*...*` paragraph after its host, preserved stray
1925/// content in place, and the group caption LAST as a bold `**...**` paragraph
1926/// with its number resolved. Emphasis and bold rather than invented syntax:
1927/// the spelling the admonition title already uses for authored text with no
1928/// native slot.
1929/// PART 11 §8h: GFM splits a row on every unescaped `|` before it reads any
1930/// inline, so every content pipe in a cell is escaped, one already escaped
1931/// excepted.
1932fn escape_cell_pipes(content: &str) -> String {
1933    if !content.contains('|') {
1934        return content.to_owned();
1935    }
1936    let bytes = content.as_bytes();
1937    let mut runs = Vec::new();
1938    let mut at = 0;
1939    while at < bytes.len() {
1940        if bytes[at] != b'`' {
1941            at += 1;
1942            continue;
1943        }
1944        let start = at;
1945        while bytes.get(at) == Some(&b'`') {
1946            at += 1;
1947        }
1948        runs.push((start, at - start));
1949    }
1950    let mut ends = vec![usize::MAX; bytes.len()];
1951    let mut next = std::collections::HashMap::new();
1952    for (start, width) in runs.into_iter().rev() {
1953        for offset in 0..width {
1954            ends[start + offset] = next.get(&(width - offset)).copied().unwrap_or(usize::MAX);
1955        }
1956        next.insert(width, start + width);
1957    }
1958    let mut out = Vec::with_capacity(bytes.len());
1959    let mut i = 0;
1960    while i < bytes.len() {
1961        if bytes[i] == b'\\' {
1962            let begin = i;
1963            while bytes.get(i) == Some(&b'\\') {
1964                i += 1;
1965            }
1966            out.extend_from_slice(&bytes[begin..i]);
1967            if bytes.get(i) == Some(&b'|') {
1968                if (i - begin) % 2 == 0 {
1969                    out.push(b'\\');
1970                }
1971                out.push(b'|');
1972                i += 1;
1973                continue;
1974            }
1975            if (i - begin) % 2 != 0 && i < bytes.len() {
1976                out.push(bytes[i]);
1977                i += 1;
1978            }
1979            continue;
1980        }
1981        let end = if bytes[i] == b'`' {
1982            ends[i]
1983        } else {
1984            usize::MAX
1985        };
1986        if end != usize::MAX {
1987            out.extend_from_slice(content[i..end].replace('|', "\\|").as_bytes());
1988            i = end;
1989            continue;
1990        }
1991        if bytes[i..].starts_with(b"[^") {
1992            let mut close = i + 2;
1993            while close < bytes.len() && !matches!(bytes[close], b'[' | b']' | b'\n') {
1994                close += 1;
1995            }
1996            if bytes.get(close) == Some(&b']') {
1997                out.extend_from_slice(content[i..=close].replace('|', "\\|").as_bytes());
1998                i = close + 1;
1999                continue;
2000            }
2001        }
2002        if bytes[i] == b'|' {
2003            out.push(b'\\');
2004        }
2005        out.push(bytes[i]);
2006        i += 1;
2007    }
2008    String::from_utf8(out).expect("pipe escapes preserve UTF-8")
2009}
2010
2011fn render_figure_group(node: &FigureGroup, ctx: &mut MarkdownContext, depth: usize) -> String {
2012    if depth > MAX_RENDER_DEPTH {
2013        crate::render_depth::record("markdown");
2014        return String::new();
2015    }
2016    let markers = carrier_markers(&BlockNode::FigureGroup(node.clone()), ctx);
2017    if markers.is_some() {
2018        ctx.carrier_depth += 1;
2019    }
2020    let mut out = String::new();
2021    for child in &node.children {
2022        match child {
2023            BlockNode::Figure(figure) => {
2024                if !ctx.roundtrip {
2025                    crate::render_loss::record_markdown_loss(
2026                        MarkdownLoss::Caption,
2027                        RawNodeType::Block,
2028                        figure.pos.as_ref(),
2029                    );
2030                }
2031                let target = render_figure_target(figure, ctx, depth);
2032                let caption = render_wrapped_inlines(&figure.caption, ctx, "*", "<em>", "</em>");
2033                out.push_str(&format!(
2034                    "{target}\n\n{}{caption}\n\n",
2035                    caption_carrier(&figure.caption, ctx)
2036                ));
2037            }
2038            other => out.push_str(&render_block(other, ctx, depth)),
2039        }
2040    }
2041    if markers.is_some() {
2042        ctx.carrier_depth -= 1;
2043    }
2044    out = carried(markers.as_ref(), out);
2045    // The group's caption slot follows the closing fence in Carve.
2046    if let Some(caption) = &node.caption {
2047        if !ctx.roundtrip {
2048            crate::render_loss::record_markdown_loss(
2049                MarkdownLoss::Caption,
2050                RawNodeType::Block,
2051                node.pos.as_ref(),
2052            );
2053        }
2054        out.push_str(&caption_carrier(caption, ctx));
2055        let caption = render_wrapped_inlines(caption, ctx, "**", "<strong>", "</strong>");
2056        out.push_str(&caption);
2057        out.push_str("\n\n");
2058    }
2059    out
2060}
2061
2062fn render_figure(node: &Figure, ctx: &mut MarkdownContext, depth: usize) -> String {
2063    if depth > MAX_RENDER_DEPTH {
2064        crate::render_depth::record("markdown");
2065        return String::new();
2066    }
2067    if !ctx.roundtrip {
2068        crate::render_loss::record_markdown_loss(
2069            MarkdownLoss::Caption,
2070            RawNodeType::Block,
2071            node.pos.as_ref(),
2072        );
2073    }
2074    let target = render_figure_target(node, ctx, depth);
2075    let sep = match &*node.target {
2076        FigureTarget::BlockQuote(_) | FigureTarget::Table(_) => "\n\n",
2077        _ => "\n",
2078    };
2079    // End with the block separator so a following block is not glued to the
2080    // caption (matching every other block renderer and carve-php).
2081    format!(
2082        "{target}{sep}{}{}\n\n",
2083        caption_carrier(&node.caption, ctx),
2084        render_block_inlines(&node.caption, ctx)
2085    )
2086}
2087
2088/// A figure's TARGET degraded on its own, without the caption - shared by the
2089/// plain figure (which glues its caption under it) and the figure group
2090/// (whose panel captions take the §10g T1 emphasized-paragraph form instead).
2091fn render_figure_target(node: &Figure, ctx: &mut MarkdownContext, depth: usize) -> String {
2092    match &*node.target {
2093        FigureTarget::Image(image) => render_image(image),
2094        FigureTarget::Table(table) => render_table(table, ctx).trim().to_string(),
2095        FigureTarget::BlockQuote(quote) => {
2096            render_block(&BlockNode::BlockQuote(quote.clone()), ctx, depth + 1)
2097                .trim()
2098                .to_string()
2099        }
2100        FigureTarget::CodeBlock(cb) => {
2101            render_block(&BlockNode::CodeBlock(cb.clone()), ctx, depth + 1)
2102                .trim()
2103                .to_string()
2104        }
2105        FigureTarget::Paragraph(p) => {
2106            render_block(&BlockNode::Paragraph(p.clone()), ctx, depth + 1)
2107                .trim()
2108                .to_string()
2109        }
2110    }
2111}
2112
2113fn render_continuation_lines<'a>(
2114    out: &mut String,
2115    lines: impl Iterator<Item = &'a str>,
2116    pad: usize,
2117) {
2118    let continuation = " ".repeat(pad);
2119    for line in lines {
2120        // Empty lines carry no structural indent (PART 11 section 7).
2121        if !line.is_empty() {
2122            out.push_str(&continuation);
2123            out.push_str(line);
2124        }
2125        out.push('\n');
2126    }
2127}
2128
2129fn render_footnote_defs(doc: &Document, ctx: &mut MarkdownContext) -> String {
2130    let mut out = String::new();
2131    // SOURCE ORDER, not label order (§7; carve-rs#686). The map is a BTreeMap.
2132    for (label, blocks) in crate::ast_json::footnote_defs_in_source_order(doc) {
2133        let outer = ctx.previous_list.take();
2134        ctx.in_footnote = true;
2135        ctx.footnote_allowed_lists = blocks
2136            .iter()
2137            .skip(1)
2138            .filter_map(|block| match block {
2139                BlockNode::List(list) => Some(list as *const List as usize),
2140                _ => None,
2141            })
2142            .collect();
2143        let body = render_blocks(blocks, ctx, 0);
2144        ctx.in_footnote = false;
2145        ctx.footnote_allowed_lists.clear();
2146        ctx.previous_list = outer;
2147        let mut lines = trim_non_nbsp(&body).split('\n');
2148        let first = lines.next().unwrap_or_default();
2149        out.push_str(&format!("[^{}]:", escape_md_html(&strip_controls(label))));
2150        if !first.is_empty() {
2151            out.push(' ');
2152            out.push_str(first);
2153        }
2154        out.push('\n');
2155        render_continuation_lines(&mut out, lines, 4);
2156    }
2157    out
2158}
2159
2160/// Whether a closing delimiter placed here would be eaten by the content's own
2161/// trailing escape. An odd run of backslashes leaves one unpaired, and the
2162/// character behind it is the first of the delimiter.
2163fn ends_escaped(core: &str) -> bool {
2164    core.chars().rev().take_while(|c| *c == '\\').count() % 2 == 1
2165}
2166
2167/// Trim outer ASCII padding after building a wrapper on its own line.
2168fn pad_outside_on_its_own_line(
2169    inner: String,
2170    delimiter: &str,
2171    open_tag: &str,
2172    close_tag: &str,
2173) -> String {
2174    trim_non_nbsp(&pad_outside(inner, delimiter, open_tag, close_tag)).to_string()
2175}
2176
2177/// A delimiter run only opens emphasis while it is left-flanking, which a run
2178/// followed by whitespace never is (CommonMark 6.2), so `** x**` reads back as
2179/// literal text. The padding is content, so it moves outside the delimiters
2180/// rather than being trimmed away. Content that has no safe delimiter form at
2181/// all - only padding, or a trailing escape that would swallow the closing run,
2182/// which is how a hard break at the edge arrives - falls back to inline HTML,
2183/// the way this renderer already spells underline, sub, super and highlight.
2184fn pad_outside(inner: String, delimiter: &str, open_tag: &str, close_tag: &str) -> String {
2185    if inline_marker_ranges(&inner).is_empty() {
2186        return pad_outside_plain(inner, delimiter, open_tag, close_tag);
2187    }
2188    let (lead, core, trail) = inline_padding(&inner, char::is_whitespace);
2189    let visible = visible_inline(&core);
2190    if visible.is_empty() {
2191        return core;
2192    }
2193    if ends_escaped(&visible) || content_grows_the_run(&visible, delimiter) {
2194        return format!("{open_tag}{inner}{close_tag}");
2195    }
2196    format!("{lead}{delimiter}{core}{delimiter}{trail}")
2197}
2198
2199fn pad_outside_plain(inner: String, delimiter: &str, open_tag: &str, close_tag: &str) -> String {
2200    // The class stays Rust's `White_Space` rather than narrowing to
2201    // CommonMark 2.1. carve-js and carve-php can state the narrow class
2202    // because they strip U+000B, U+2028 and U+2029 as controls; this engine
2203    // does not, and `**<U+2028>x**` reads back as literal text through
2204    // pulldown-cmark, whose flanking test counts the wider class.
2205    let core = inner.trim();
2206    if core.is_empty() || ends_escaped(core) || content_grows_the_run(core, delimiter) {
2207        if inner.is_empty() {
2208            return String::new();
2209        }
2210        let lead = &inner[..inner.len() - inner.trim_start().len()];
2211        if ends_escaped(core) && lead.contains('\n') {
2212            return format!("{lead}{open_tag}{}{close_tag}", &inner[lead.len()..]);
2213        }
2214        return format!("{open_tag}{inner}{close_tag}");
2215    }
2216    let lead = &inner[..inner.len() - inner.trim_start().len()];
2217    let trail = &inner[inner.trim_end().len()..];
2218    format!("{lead}{delimiter}{core}{delimiter}{trail}")
2219}
2220
2221fn nested_edge_is_invalid(
2222    core: &str,
2223    delimiter: &str,
2224    children: &[InlineNode],
2225    parts: Option<&Vec<String>>,
2226) -> bool {
2227    let ch = delimiter.chars().next().unwrap();
2228    let lead = core.chars().take_while(|c| *c == ch).count();
2229    let mut invalid_edge = ch == '*' && lead > 0 && delimiter.len() + lead != 3;
2230    if ch == '*' && live_run_at_end(core, ch) > 0 {
2231        if let Some(parts) = parts {
2232            if let Some(i) = parts.iter().rposition(|part| !part.is_empty()) {
2233                if let Some((child_delimiter, _, _)) = delimiter_run(&children[i]) {
2234                    if child_delimiter.starts_with(ch) {
2235                        invalid_edge |= child_delimiter == delimiter;
2236                        if let Some(child) = split_run(&parts[i], child_delimiter) {
2237                            let before = child
2238                                .lead
2239                                .chars()
2240                                .next_back()
2241                                .or_else(|| neighbour_before(parts, i));
2242                            let inside = child.core.chars().find(|c| *c != ch);
2243                            let closes = before.is_some_and(|c| !flank_space(flank_character(c)))
2244                                && flanks(before, inside);
2245                            let opening = child_delimiter.len()
2246                                + child.core.chars().take_while(|c| *c == ch).count();
2247                            let closing = delimiter.len() + live_run_at_end(core, ch);
2248                            invalid_edge |= closes && !rule_of_three_allows(opening, closing);
2249                        }
2250                    }
2251                }
2252            }
2253        }
2254    }
2255    invalid_edge
2256}
2257
2258fn pad_nested_outside(
2259    body: String,
2260    delimiter: &str,
2261    open_tag: &str,
2262    close_tag: &str,
2263    node: &InlineNode,
2264    ctx: &MarkdownContext,
2265) -> String {
2266    let core = body.trim();
2267    let children = match node {
2268        InlineNode::Emphasis(emphasis) => emphasis.children.as_slice(),
2269        _ => &[],
2270    };
2271    let invalid_edge = nested_edge_is_invalid(
2272        core,
2273        delimiter,
2274        children,
2275        ctx.rendered_children
2276            .get(&(node as *const InlineNode as usize)),
2277    );
2278    if invalid_edge && !core.is_empty() {
2279        let piece = RunPiece {
2280            lead: body[..body.len() - body.trim_start().len()].to_string(),
2281            core: core.to_string(),
2282            trail: body[body.trim_end().len()..].to_string(),
2283        };
2284        return spell_nested_html(node, piece, open_tag, close_tag, ctx);
2285    }
2286    pad_outside(body, delimiter, open_tag, close_tag)
2287}
2288
2289/// Whether the content's own edge would lengthen the delimiter run past what
2290/// the reader can read.
2291///
2292/// GFM strikethrough is a matching pair of ONE OR TWO tildes; three is not a
2293/// longer delimiter, it is no delimiter at all - and at the start of a line it
2294/// is a FENCED CODE BLOCK opener that swallows the rest of the document. So a
2295/// strike whose content begins or ends with a tilde takes the inline-HTML form.
2296///
2297/// CommonMark emphasis has no such cap: `***x***` is how a strong holding an
2298/// italic is spelled and every reader reads it back, so the asterisk runs are
2299/// left alone. They could not reach here in any case - `escape_text` escapes a
2300/// literal asterisk, and `~` is deliberately not escaped because GFM reads
2301/// `~x~` as strikethrough.
2302fn content_grows_the_run(core: &str, delimiter: &str) -> bool {
2303    let Some(ch) = delimiter.chars().next() else {
2304        return false;
2305    };
2306    if ch == '~' {
2307        return core.starts_with('~') || live_run_at_end(core, '~') > 0;
2308    }
2309    // Two joined single markers form a strong and lose the nested italic.
2310    let lead = core.chars().take_while(|c| *c == ch).count();
2311    let trail = live_run_at_end(core, ch);
2312    (lead > 0 && delimiter.len() + lead == 2) || (trail > 0 && delimiter.len() + trail == 2)
2313}
2314
2315/// The trailing run of `ch`, minus one where a backslash covers its last
2316/// character: an escaped marker is a literal and breaks a run.
2317fn live_run_at_end(core: &str, ch: char) -> usize {
2318    let run = core.chars().rev().take_while(|c| *c == ch).count();
2319    if run == 0 {
2320        return 0;
2321    }
2322    let slashes = core
2323        .chars()
2324        .rev()
2325        .skip(run)
2326        .take_while(|c| *c == '\\')
2327        .count();
2328    if slashes % 2 == 1 {
2329        run - 1
2330    } else {
2331        run
2332    }
2333}
2334
2335fn render_inlines(nodes: &[InlineNode], ctx: &mut MarkdownContext, depth: usize) -> String {
2336    render_recorded_inlines(nodes, ctx, depth, None)
2337}
2338
2339fn render_recorded_inlines(
2340    nodes: &[InlineNode],
2341    ctx: &mut MarkdownContext,
2342    depth: usize,
2343    owner: Option<usize>,
2344) -> String {
2345    if depth > MAX_RENDER_DEPTH {
2346        crate::render_depth::record("markdown");
2347        return String::new();
2348    }
2349    let mut parts: Vec<String> = Vec::with_capacity(nodes.len());
2350    for node in nodes {
2351        parts.push(render_inline(node, ctx, depth));
2352    }
2353    let has_content = |part: &str| {
2354        visible_inline(part)
2355            .bytes()
2356            .any(|byte| !matches!(byte, b' ' | b'\t' | b'\r' | b'\n'))
2357    };
2358    for i in (0..parts.len()).rev() {
2359        if matches!(nodes[i], InlineNode::HardBreak(_)) && parts[i] == "\\\n" {
2360            let preceding_content = parts[..i].iter().any(|part| has_content(part));
2361            parts[i] = if preceding_content {
2362                "<br>"
2363            } else {
2364                "<br><!---->"
2365            }
2366            .to_owned();
2367            break;
2368        }
2369        if has_content(&parts[i]) {
2370            break;
2371        }
2372    }
2373    repair_nested_runs(nodes, &mut parts, ctx, owner.is_some());
2374    if nodes.len() > 1 {
2375        reflank_runs(nodes, &mut parts, ctx);
2376        unmerge_runs(nodes, &mut parts, ctx);
2377    }
2378    let result = parts.concat();
2379    if !ctx.rendered_children.is_empty() {
2380        for child in nodes {
2381            ctx.rendered_children
2382                .remove(&(child as *const InlineNode as usize));
2383        }
2384    }
2385    if let Some(owner) = owner {
2386        if nodes.iter().any(|node| delimiter_run(node).is_some()) {
2387            ctx.rendered_children.insert(owner, parts);
2388        }
2389    }
2390    result
2391}
2392
2393/// The four inlines this writer spells with a delimiter run, and the inline-HTML
2394/// form each falls back to. Everything else is inline HTML already and carries
2395/// no flanking question.
2396fn delimiter_run(node: &InlineNode) -> Option<(&'static str, &'static str, &'static str)> {
2397    let InlineNode::Emphasis(emphasis) = node else {
2398        return None;
2399    };
2400    match emphasis.kind {
2401        EmphasisKind::Italic => Some(("*", "<em>", "</em>")),
2402        EmphasisKind::Strong => Some(("**", "<strong>", "</strong>")),
2403        EmphasisKind::Strike => Some(("~~", "<del>", "</del>")),
2404        EmphasisKind::BoldItalic => Some(("***", "<strong><em>", "</em></strong>")),
2405        _ => None,
2406    }
2407}
2408
2409/// CommonMark 0.31 punctuation: ASCII punctuation plus the Unicode P* and S*
2410/// categories. The S* half is the reason to spell it rather than reuse
2411/// `is_ascii_punctuation` - 0.30 left the symbol categories out, so a reader on
2412/// either version agrees about `!` and disagrees about `©`, and taking the WIDER
2413/// class is the answer that is right under both: it can only move a construct to
2414/// inline HTML, which every reader reads the same way.
2415fn flank_punct(ch: char) -> bool {
2416    static PUNCT: std::sync::OnceLock<regex::Regex> = std::sync::OnceLock::new();
2417    PUNCT
2418        .get_or_init(|| regex::Regex::new(r"^[\p{P}\p{S}]$").expect("the flanking class is valid"))
2419        .is_match(ch.encode_utf8(&mut [0u8; 4]))
2420}
2421
2422/// The space half of the same test. `NBSP_PLACEHOLDER` is this writer's own
2423/// carrier for a no-break space and stands for whitespace wherever it survives
2424/// into an emitted part.
2425fn flank_space(ch: char) -> bool {
2426    ch.is_whitespace() || ch == crate::NBSP_PLACEHOLDER
2427}
2428
2429/// A carrier stands for `_`, `#` or `[`, all three of them punctuation, and it
2430/// is a private-use code point that no punctuation property matches. The
2431/// flanking test therefore has to ask about the character the reader will see,
2432/// not the carrier standing in for it until `resolve_narrowed_escapes` runs.
2433fn flank_character(ch: char) -> char {
2434    CARRIERS.with(|slot| match carrier_slot(&slot.borrow(), ch) {
2435        Some(index) => carried_character(index),
2436        None => ch,
2437    })
2438}
2439
2440/// One side of CommonMark 6.2, and it really is ONE side: left-flanking and
2441/// right-flanking are the same test read in opposite directions. A run is
2442/// left-flanking if the character INSIDE it is not whitespace and, when that
2443/// character is punctuation, the character OUTSIDE is whitespace or punctuation;
2444/// right-flanking swaps which end is inside. `pad_outside` has already moved
2445/// every space out of the run, so the inside character is never whitespace and
2446/// only the punctuation clause is left to decide.
2447///
2448/// No neighbour at all counts as whitespace: the enclosing text either starts or
2449/// ends the line, or it is a delimiter, a bracket or a tag belonging to whatever
2450/// encloses the run - punctuation in every case this writer can produce.
2451fn flanks(inside: Option<char>, outside: Option<char>) -> bool {
2452    let Some(inner) = inside else {
2453        return true;
2454    };
2455    if !flank_punct(flank_character(inner)) {
2456        return true;
2457    }
2458    let Some(outer) = outside else {
2459        return true;
2460    };
2461    let outer = flank_character(outer);
2462
2463    flank_space(outer) || flank_punct(outer)
2464}
2465
2466/// A rendered part taken back apart into the pieces `pad_outside` built it from.
2467struct RunPiece {
2468    lead: String,
2469    core: String,
2470    trail: String,
2471}
2472
2473/// Take a rendered part apart, or `None` when it is not a delimiter run - an
2474/// empty render, or the inline-HTML form `pad_outside` falls back to for
2475/// whitespace-only content and for a trailing escape.
2476fn split_run(part: &str, delimiter: &str) -> Option<RunPiece> {
2477    let body = part.trim();
2478    if body.len() <= delimiter.len() * 2 {
2479        return None;
2480    }
2481    if !body.starts_with(delimiter) || !body.ends_with(delimiter) {
2482        return None;
2483    }
2484
2485    Some(RunPiece {
2486        lead: part[..part.len() - part.trim_start().len()].to_string(),
2487        core: body[delimiter.len()..body.len() - delimiter.len()].to_string(),
2488        trail: part[part.trim_end().len()..].to_string(),
2489    })
2490}
2491
2492fn spell_nested_html(
2493    node: &InlineNode,
2494    piece: RunPiece,
2495    open_tag: &str,
2496    close_tag: &str,
2497    ctx: &MarkdownContext,
2498) -> String {
2499    let mut core = piece.core;
2500    let parent = ctx.delimiter_ancestors.last().copied();
2501    if matches!(parent, Some("**" | "***")) {
2502        if let (InlineNode::Emphasis(emphasis), Some(parts)) = (
2503            node,
2504            ctx.rendered_children
2505                .get(&(node as *const InlineNode as usize)),
2506        ) {
2507            let body = parts.concat();
2508            if body.trim() == core && parts.len() == emphasis.children.len() {
2509                let repaired = parts
2510                    .iter()
2511                    .zip(&emphasis.children)
2512                    .map(|(part, child)| {
2513                        if let InlineNode::Emphasis(child) = child {
2514                            if child.kind == EmphasisKind::Strong {
2515                                if let Some(nested) = split_run(part, "**") {
2516                                    return format!(
2517                                        "{}<strong>{}</strong>{}",
2518                                        nested.lead, nested.core, nested.trail
2519                                    );
2520                                }
2521                            }
2522                        }
2523                        part.clone()
2524                    })
2525                    .collect::<Vec<_>>()
2526                    .concat();
2527                let lead = body.len() - body.trim_start().len();
2528                let trail = body.len() - body.trim_end().len();
2529                core = repaired[lead..repaired.len() - trail].to_string();
2530            }
2531        }
2532    }
2533    format!("{}{open_tag}{core}{close_tag}{}", piece.lead, piece.trail)
2534}
2535
2536fn repair_nested_runs(
2537    nodes: &[InlineNode],
2538    parts: &mut [String],
2539    ctx: &MarkdownContext,
2540    direct_parent: bool,
2541) {
2542    let ancestors = &ctx.delimiter_ancestors;
2543    if ancestors.is_empty() {
2544        return;
2545    }
2546    let parent = ancestors.last().copied();
2547    for i in 0..parts.len() {
2548        let Some((delimiter, open_tag, close_tag)) = delimiter_run(&nodes[i]) else {
2549            continue;
2550        };
2551        let Some(piece) = split_run(&parts[i], delimiter) else {
2552            continue;
2553        };
2554        let edge_separated = direct_parent
2555            && parent == Some(delimiter)
2556            && ancestors.iter().filter(|run| Some(**run) == parent).count() == 1
2557            && !ancestors.contains(&"***")
2558            && (neighbour_before(parts, i).is_none() || neighbour_after(parts, i).is_none());
2559        if edge_separated {
2560            continue;
2561        }
2562        let ch = delimiter.chars().next().unwrap();
2563        let before = piece
2564            .lead
2565            .chars()
2566            .next_back()
2567            .or_else(|| neighbour_before(parts, i));
2568        let inside = piece.core.chars().find(|c| *c != ch);
2569        let closes =
2570            before.is_some_and(|c| !flank_space(flank_character(c))) && flanks(before, inside);
2571        let opening = delimiter.len() + piece.core.chars().take_while(|c| *c == ch).count();
2572        let repeated_strong =
2573            delimiter == "**" && (parent == Some("**") || ancestors.contains(&"***"));
2574        let steals = closes
2575            && ancestors.iter().any(|run| {
2576                run.starts_with(ch) && (ch == '~' || rule_of_three_allows(run.len(), opening))
2577            });
2578        if repeated_strong || steals {
2579            parts[i] = spell_nested_html(&nodes[i], piece, open_tag, close_tag, ctx);
2580        }
2581    }
2582}
2583
2584/// Whether a run can flank is a property of the SEAM, not of the emphasis node,
2585/// so it cannot be answered where the run is built: the character that decides
2586/// it belongs to the sibling on the other side. Here is the one place both
2587/// neighbours are known, so a run that cannot open or cannot close where it
2588/// stands is re-spelled as inline HTML - the same fallback every inline this
2589/// writer cannot spell with delimiters already takes (carve-rs#1615).
2590///
2591/// The neighbour is read off the parts as they stand, so a part already
2592/// re-spelled on this pass contributes its `>` or `<` rather than its delimiter.
2593/// That only ever makes a later run MORE able to flank, so the pass needs no
2594/// second round; a run decided against an earlier neighbour can at worst take
2595/// inline HTML it would not have needed.
2596fn reflank_runs(nodes: &[InlineNode], parts: &mut [String], ctx: &MarkdownContext) {
2597    for i in 0..parts.len() {
2598        let Some((delimiter, open_tag, close_tag)) = delimiter_run(&nodes[i]) else {
2599            continue;
2600        };
2601        let Some(piece) = split_run(&parts[i], delimiter) else {
2602            continue;
2603        };
2604        let before = piece
2605            .lead
2606            .chars()
2607            .next_back()
2608            .or_else(|| neighbour_before(parts, i));
2609        let after = piece
2610            .trail
2611            .chars()
2612            .next()
2613            .or_else(|| neighbour_after(parts, i));
2614        // An italic around a single strong node, or a strong around a single
2615        // italic, joins into a triple-star run. Check the content beyond all
2616        // three stars against the neighbours.
2617        let (outer_kind, inner_kind, nested) = if delimiter == "*" {
2618            (EmphasisKind::Italic, EmphasisKind::Strong, "**")
2619        } else {
2620            (EmphasisKind::Strong, EmphasisKind::Italic, "*")
2621        };
2622        if (delimiter == "*" || delimiter == "**")
2623            && ctx.delimiter_ancestors.is_empty()
2624            && matches!(&nodes[i], InlineNode::Emphasis(emphasis)
2625                if emphasis.kind == outer_kind
2626                    && emphasis.children.len() == 1
2627                    && matches!(&emphasis.children[0], InlineNode::Emphasis(child)
2628                        if child.kind == inner_kind))
2629            && piece.core.len() > nested.len() * 2
2630            && piece.core.starts_with(nested)
2631            && piece.core.ends_with(nested)
2632        {
2633            let inner = &piece.core[nested.len()..piece.core.len() - nested.len()];
2634            if flanks(inner.chars().next(), before) && flanks(inner.chars().next_back(), after) {
2635                continue;
2636            }
2637        }
2638        if flanks(piece.core.chars().next(), before)
2639            && flanks(piece.core.chars().next_back(), after)
2640        {
2641            continue;
2642        }
2643        parts[i] = spell_nested_html(&nodes[i], piece, open_tag, close_tag, ctx);
2644    }
2645}
2646
2647fn neighbour_before(parts: &[String], i: usize) -> Option<char> {
2648    parts[..i]
2649        .iter()
2650        .rev()
2651        .find_map(|p| visible_inline(p).chars().next_back())
2652}
2653
2654fn neighbour_after(parts: &[String], i: usize) -> Option<char> {
2655    parts[i + 1..]
2656        .iter()
2657        .find_map(|p| visible_inline(p).chars().next())
2658}
2659
2660/// The characters this writer spells a delimiter run with. A run of anything
2661/// else cannot merge with a neighbouring run, because there is no neighbouring
2662/// run to merge with.
2663fn is_run_character(ch: char) -> bool {
2664    ch == '*' || ch == '~'
2665}
2666
2667/// CommonMark's rule of three. When a delimiter run can both open and close, a
2668/// closer may only match an opener if the sum of the two run lengths is not a
2669/// multiple of three, or if both lengths are.
2670fn rule_of_three_allows(opener: usize, closer: usize) -> bool {
2671    (opener + closer) % 3 != 0 || (opener % 3 == 0 && closer % 3 == 0)
2672}
2673
2674/// Whether the reader still gets both constructs back out of a run that spans a
2675/// seam.
2676///
2677/// `m` is what the part on the left contributed and `n` what the part on the
2678/// right did, so the reader sees ONE run of `m + n` with the first construct's
2679/// content on its left and the second's on its right. Every question is asked
2680/// about that summed run, which is why no flanking test on either piece can see
2681/// this: each piece flanks perfectly well against the other's delimiter.
2682///
2683/// A TILDE seam never survives. GFM strikethrough reads one or two tildes, and
2684/// the two readers disagree about a longer run - markdown-it splits `~~~~` into
2685/// two pairs, pulldown-cmark reads the whole thing as text. Inline HTML is the
2686/// answer both of them agree on.
2687fn merged_run_reads_back(
2688    ch: char,
2689    m: usize,
2690    n: usize,
2691    inner_left: Option<char>,
2692    inner_right: Option<char>,
2693) -> bool {
2694    if !flanks(inner_left, inner_right) || !flanks(inner_right, inner_left) {
2695        return false;
2696    }
2697    if ch != '*' {
2698        return false;
2699    }
2700    let summed = m + n;
2701
2702    rule_of_three_allows(m, summed) && rule_of_three_allows(summed, n)
2703}
2704
2705/// The run of `ch` that ends `part`, and the character in front of it.
2706fn trailing_run(part: &str, ch: char) -> (usize, Option<char>) {
2707    let head = part.trim_end_matches(ch);
2708    let run = part.chars().count() - head.chars().count();
2709    // A delimiter the writer ESCAPED is text, so the reader counts one less
2710    // than the characters do (markup-carve/carve-rs#1654). The one caller asks
2711    // only about a part that ends in `ch`, so the run is never empty here.
2712    let escaped = head.chars().rev().take_while(|c| *c == '\\').count() % 2 == 1;
2713    (run - usize::from(escaped), head.chars().next_back())
2714}
2715
2716/// The run of `ch` that begins `part`, and the character behind it.
2717fn leading_run(part: &str, ch: char) -> (usize, Option<char>) {
2718    let tail = part.trim_start_matches(ch);
2719
2720    (
2721        part.chars().count() - tail.chars().count(),
2722        tail.chars().next(),
2723    )
2724}
2725
2726/// Re-spell one part as inline HTML, if it is a delimiter run at all.
2727fn respell(nodes: &[InlineNode], parts: &mut [String], at: usize, ctx: &MarkdownContext) -> bool {
2728    let Some((delimiter, open_tag, close_tag)) = delimiter_run(&nodes[at]) else {
2729        return false;
2730    };
2731    let Some(piece) = split_run(&parts[at], delimiter) else {
2732        return false;
2733    };
2734    parts[at] = spell_nested_html(&nodes[at], piece, open_tag, close_tag, ctx);
2735
2736    true
2737}
2738
2739/// Two adjacent parts whose runs are made of the same character do not reach
2740/// the reader as two runs: they reach it as ONE, of the summed length. The
2741/// damaging shape is a strike next to a strike, which writes four tildes that
2742/// one reader splits and the other does not; the ordinary shape is two
2743/// emphases that collapse into a single `<em>` holding the delimiters of the
2744/// second (carve-rs#1619).
2745///
2746/// The seam is the only place the summed length is known, and it is a different
2747/// question from `reflank_runs`: each piece IS well-flanked, against the other
2748/// piece's delimiter. So this runs after the flanking pass and asks its
2749/// questions about the run the reader will actually see.
2750///
2751/// The later part is the one re-spelled, so the merge is gone before the seam
2752/// behind it is reached. Where that part is not a delimiter run at all - a text
2753/// node opening with a literal tilde - the earlier part takes the inline HTML
2754/// instead.
2755fn unmerge_runs(nodes: &[InlineNode], parts: &mut [String], ctx: &MarkdownContext) {
2756    let filled: Vec<usize> = (0..parts.len()).filter(|i| !parts[*i].is_empty()).collect();
2757    for pair in filled.windows(2) {
2758        let (left, right) = (pair[0], pair[1]);
2759        let Some(ch) = parts[left].chars().next_back() else {
2760            continue;
2761        };
2762        if !is_run_character(ch) || !parts[right].starts_with(ch) {
2763            continue;
2764        }
2765        let (m, before) = trailing_run(&parts[left], ch);
2766        // The marker that ends the left part is ESCAPED, so it is text and the
2767        // live run is empty (markup-carve/carve-rs#1654). Nothing merges across
2768        // the seam, so there is no summed run to ask about and nothing to
2769        // unmerge (markup-carve/carve-rs#1831).
2770        if m == 0 {
2771            continue;
2772        }
2773        let (n, after) = leading_run(&parts[right], ch);
2774        let inner_left = before.or_else(|| neighbour_before(parts, left));
2775        let inner_right = after.or_else(|| neighbour_after(parts, right));
2776        if merged_run_reads_back(ch, m, n, inner_left, inner_right) {
2777            continue;
2778        }
2779        if !respell(nodes, parts, right, ctx) {
2780            respell(nodes, parts, left, ctx);
2781        }
2782    }
2783}
2784
2785fn render_attributed_emphasis(
2786    emphasis: &Emphasis,
2787    ctx: &mut MarkdownContext,
2788    depth: usize,
2789) -> Option<String> {
2790    let (open, close) = match emphasis.kind {
2791        EmphasisKind::Italic => ("<em", "</em>"),
2792        EmphasisKind::Strong | EmphasisKind::BoldItalic => ("<strong", "</strong>"),
2793        EmphasisKind::Strike => ("<del", "</del>"),
2794        _ => return None,
2795    };
2796    emphasis.attrs.as_ref()?;
2797    let attrs = crate::render::render_attrs(&emphasis.attrs);
2798    if attrs.is_empty() {
2799        return None;
2800    }
2801    // The attributes sit on the outer `<strong>`, so the inner emphasis is an
2802    // ordinary child and takes the `*` spelling where it reads back (CARVE-P11-045).
2803    let inner = if emphasis.kind == EmphasisKind::BoldItalic {
2804        let italic = InlineNode::Emphasis(Emphasis {
2805            attrs: None,
2806            kind: EmphasisKind::Italic,
2807            children: emphasis.children.clone(),
2808            pos: None,
2809        });
2810        render_inlines(std::slice::from_ref(&italic), ctx, depth + 1)
2811    } else {
2812        render_inlines(&emphasis.children, ctx, depth + 1)
2813    };
2814    Some(format!("{open}{attrs}>{inner}{close}"))
2815}
2816
2817thread_local! {
2818    static CARRIER_WRITE_ERROR: std::cell::RefCell<Option<crate::RenderCarveError>> = const { std::cell::RefCell::new(None) };
2819    static INLINE_CARRIER_PATTERN: std::cell::RefCell<Option<regex::Regex>> = const { std::cell::RefCell::new(None) };
2820    static INLINE_CARRIER_PREFIX: std::cell::RefCell<String> = const { std::cell::RefCell::new(String::new()) };
2821}
2822
2823fn inline_carrier_line(payload: &str) -> String {
2824    INLINE_CARRIER_PREFIX.with(|prefix| {
2825        let prefix = prefix.borrow();
2826        format!("{prefix}{}{prefix}", carrier_line(payload))
2827    })
2828}
2829
2830fn inline_marker_ranges(text: &str) -> Vec<std::ops::Range<usize>> {
2831    INLINE_CARRIER_PATTERN.with(|pattern| {
2832        pattern
2833            .borrow()
2834            .as_ref()
2835            .map(|pattern| pattern.find_iter(text).map(|found| found.range()).collect())
2836            .unwrap_or_default()
2837    })
2838}
2839
2840fn visible_inline(text: &str) -> std::borrow::Cow<'_, str> {
2841    INLINE_CARRIER_PATTERN.with(|pattern| match pattern.borrow().as_ref() {
2842        Some(pattern) => pattern.replace_all(text, ""),
2843        None => std::borrow::Cow::Borrowed(text),
2844    })
2845}
2846
2847fn inline_padding(text: &str, space: impl Fn(char) -> bool) -> (String, String, String) {
2848    let visible = visible_inline(text);
2849    let start = visible.len() - visible.trim_start_matches(&space).len();
2850    let end = visible.trim_end_matches(&space).len().max(start);
2851    let mut core = String::new();
2852    let mut cursor = 0;
2853    let mut position = 0;
2854    for range in inline_marker_ranges(text) {
2855        let chunk = &text[cursor..range.start];
2856        let from = start.saturating_sub(position).min(chunk.len());
2857        let to = end.saturating_sub(position).min(chunk.len()).max(from);
2858        core.push_str(&chunk[from..to]);
2859        core.push_str(&text[range.clone()]);
2860        position += chunk.len();
2861        cursor = range.end;
2862    }
2863    let chunk = &text[cursor..];
2864    let from = start.saturating_sub(position).min(chunk.len());
2865    let to = end.saturating_sub(position).min(chunk.len()).max(from);
2866    core.push_str(&chunk[from..to]);
2867    (visible[..start].to_owned(), core, visible[end..].to_owned())
2868}
2869
2870fn restore_inline_change(marked: &str, before: &str, after: &str) -> String {
2871    if before == after {
2872        return marked.to_owned();
2873    }
2874    let start = before
2875        .chars()
2876        .zip(after.chars())
2877        .take_while(|(a, b)| a == b)
2878        .map(|(ch, _)| ch.len_utf8())
2879        .sum::<usize>();
2880    let suffix = before[start..]
2881        .chars()
2882        .rev()
2883        .zip(after[start..].chars().rev())
2884        .take_while(|(a, b)| a == b)
2885        .map(|(ch, _)| ch.len_utf8())
2886        .sum::<usize>();
2887    let end = before.len() - suffix;
2888    let ranges = inline_marker_ranges(marked);
2889    let offset = |position: usize| {
2890        let mut at = position;
2891        let mut removed = 0;
2892        for range in &ranges {
2893            if range.start - removed > position {
2894                break;
2895            }
2896            at += range.len();
2897            removed += range.len();
2898        }
2899        at
2900    };
2901    let from = offset(start);
2902    let to = offset(end);
2903    let mut out = marked[..from].to_owned();
2904    for range in ranges
2905        .iter()
2906        .filter(|range| range.start >= from && range.end <= to)
2907    {
2908        out.push_str(&marked[range.clone()]);
2909    }
2910    out.push_str(&after[start..after.len() - suffix]);
2911    out.push_str(&marked[to..]);
2912    out
2913}
2914
2915fn render_inline(node: &InlineNode, ctx: &mut MarkdownContext, depth: usize) -> String {
2916    let body = render_inline_body(node, ctx, depth);
2917    if !ctx.roundtrip {
2918        return body;
2919    }
2920    let attributes = |attrs: &Option<Attrs>| {
2921        let spelled = crate::render_carve::render_carrier_attrs(attrs);
2922        if spelled.is_empty() {
2923            "{}".to_owned()
2924        } else {
2925            spelled
2926        }
2927    };
2928    match node {
2929        InlineNode::Link(link)
2930            if ctx.link_depth == 0 && !crate::parse::is_unresolved_reference(link) =>
2931        {
2932            let attrs = attributes(&link.attrs);
2933            if attrs == "{}" {
2934                body
2935            } else {
2936                format!("{body}{}", inline_carrier_line(&attrs))
2937            }
2938        }
2939        InlineNode::Image(image) if !crate::parse::is_unresolved_image(image) => {
2940            let attrs = attributes(&image.attrs);
2941            if attrs == "{}" {
2942                body
2943            } else {
2944                format!("{body}{}", inline_carrier_line(&attrs))
2945            }
2946        }
2947        InlineNode::Span(span) => format!(
2948            "{}{body}{}",
2949            inline_carrier_line("["),
2950            inline_carrier_line(&format!("]{}", attributes(&span.attrs)))
2951        ),
2952        InlineNode::CrossRef(reference) if ctx.link_depth == 0 && body.starts_with('[') => {
2953            let mut document = crate::parse::parse("x");
2954            if let BlockNode::Paragraph(paragraph) = &mut document.children[0] {
2955                paragraph.children = vec![InlineNode::CrossRef(CrossRef {
2956                    target: reference.target.clone(),
2957                    href: None,
2958                    pos: None,
2959                })];
2960            }
2961            let payload = crate::render_carve::render_carve(&document).unwrap_or_default();
2962            format!(
2963                "{}{body}",
2964                inline_carrier_line(payload.trim_end_matches('\n'))
2965            )
2966        }
2967        _ => body,
2968    }
2969}
2970
2971fn render_inline_body(node: &InlineNode, ctx: &mut MarkdownContext, depth: usize) -> String {
2972    if depth > MAX_RENDER_DEPTH {
2973        crate::render_depth::record("markdown");
2974        return String::new();
2975    }
2976    match node {
2977        // Reproduce the author's escape where it protects something ON THIS
2978        // TARGET. `\-\-` was written precisely so a downstream processor with
2979        // smart punctuation on would not read an en dash; emitting the
2980        // character bare loses exactly that (carve issue 350), so the triggers
2981        // §8 names are kept whatever their position.
2982        //
2983        // PART 11 §8b narrows the rest, on the finding §8a already states.
2984        // M2a: a character this target's readers never read as markup is
2985        // emitted BARE, which is Carve's own delimiters. M2b: the hash is read
2986        // as markup only where it would open an ATX heading, so it takes a
2987        // sentinel and is decided on the line like M1b's candidates.
2988        //
2989        // Every character Markdown CAN read keeps M2 as written. The bracket
2990        // in particular keeps its escape at every position, which is what
2991        // leaves §8a's argument about the two link grammars standing: an
2992        // author who meant `[a](b)` as text still gets it back.
2993        InlineNode::EscapedText(text) => {
2994            let mut chars = text.value.chars();
2995            match (chars.next(), chars.next()) {
2996                (Some(ch), None) if AUTHORED_INERT.contains(&ch) => ch.to_string(),
2997                (Some(ch), None) if authored_defers_to_the_line(ch) => {
2998                    positional_sentinel().to_string()
2999                }
3000                _ => format!("\\{}", text.value),
3001            }
3002        }
3003        InlineNode::Text(text) => {
3004            if is_literal_crossref(&text.value) {
3005                strip_controls(&text.value)
3006            } else {
3007                escape_text(&resolve_nbsp(&strip_controls(&text.value)))
3008            }
3009        }
3010        // Not escaped: a smart-typography run is either a glyph (nothing to
3011        // escape) or the author's source run, which must survive verbatim so a
3012        // reader searching for what was typed finds it. carve-php and carve-js
3013        // emit it unescaped for the same reason; escaping here turned `->`
3014        // into `-&gt;` in source mode.
3015        InlineNode::SmartPunctuation(s) => strip_controls(smart_punctuation_text(s)),
3016        InlineNode::Emphasis(emphasis) => {
3017            if let Some(rendered) = render_attributed_emphasis(emphasis, ctx, depth) {
3018                return rendered;
3019            }
3020            match emphasis.kind {
3021                EmphasisKind::Italic => {
3022                    ctx.delimiter_ancestors.push("*");
3023                    let body = render_recorded_inlines(
3024                        &emphasis.children,
3025                        ctx,
3026                        depth + 1,
3027                        Some(node as *const InlineNode as usize),
3028                    );
3029                    ctx.delimiter_ancestors.pop();
3030                    pad_nested_outside(body, "*", "<em>", "</em>", node, ctx)
3031                }
3032                EmphasisKind::Strong => {
3033                    ctx.delimiter_ancestors.push(if emphasis.children.len() == 1 && matches!(&emphasis.children[0], InlineNode::Emphasis(child) if child.kind == EmphasisKind::Italic) { "***" } else { "**" });
3034                    let body = render_recorded_inlines(
3035                        &emphasis.children,
3036                        ctx,
3037                        depth + 1,
3038                        Some(node as *const InlineNode as usize),
3039                    );
3040                    ctx.delimiter_ancestors.pop();
3041                    pad_nested_outside(body, "**", "<strong>", "</strong>", node, ctx)
3042                }
3043                EmphasisKind::Underline => {
3044                    format!(
3045                        "<u{}>{}</u>",
3046                        crate::render::render_attrs(&emphasis.attrs),
3047                        render_inlines(&emphasis.children, ctx, depth + 1)
3048                    )
3049                }
3050                // PART 11 section 8c: no Markdown delimiter spelling exists, so the
3051                // target uses inline HTML, carrying the construct's attribute set
3052                // onto the element the way ruby already does. `smallcaps` is a BASE
3053                // class merged into the author's class slot, as on the HTML target.
3054                EmphasisKind::SmallCaps => {
3055                    format!(
3056                        "<span{}>{}</span>",
3057                        crate::render::render_attrs_with_base_class(&emphasis.attrs, "smallcaps"),
3058                        render_inlines(&emphasis.children, ctx, depth + 1)
3059                    )
3060                }
3061                EmphasisKind::Strike => {
3062                    ctx.delimiter_ancestors.push("~~");
3063                    let body = render_recorded_inlines(
3064                        &emphasis.children,
3065                        ctx,
3066                        depth + 1,
3067                        Some(node as *const InlineNode as usize),
3068                    );
3069                    ctx.delimiter_ancestors.pop();
3070                    pad_nested_outside(body, "~~", "<del>", "</del>", node, ctx)
3071                }
3072                EmphasisKind::Sub => {
3073                    format!(
3074                        "<sub{}>{}</sub>",
3075                        crate::render::render_attrs(&emphasis.attrs),
3076                        render_inlines(&emphasis.children, ctx, depth + 1)
3077                    )
3078                }
3079                EmphasisKind::Super => {
3080                    format!(
3081                        "<sup{}>{}</sup>",
3082                        crate::render::render_attrs(&emphasis.attrs),
3083                        render_inlines(&emphasis.children, ctx, depth + 1)
3084                    )
3085                }
3086                EmphasisKind::Highlight => {
3087                    format!(
3088                        "<mark{}>{}</mark>",
3089                        crate::render::render_attrs(&emphasis.attrs),
3090                        render_inlines(&emphasis.children, ctx, depth + 1)
3091                    )
3092                }
3093                EmphasisKind::BoldItalic => {
3094                    ctx.delimiter_ancestors.push("***");
3095                    let body = render_recorded_inlines(
3096                        &emphasis.children,
3097                        ctx,
3098                        depth + 1,
3099                        Some(node as *const InlineNode as usize),
3100                    );
3101                    ctx.delimiter_ancestors.pop();
3102                    pad_nested_outside(body, "***", "<strong><em>", "</em></strong>", node, ctx)
3103                }
3104            }
3105        }
3106        InlineNode::Code(code) => render_code(&resolve_nbsp(&strip_controls(&code.value))),
3107        InlineNode::Link(link) => render_link(link, ctx, depth + 1),
3108        InlineNode::Image(image) => render_image(image),
3109        InlineNode::Span(span) => {
3110            // A span has no Markdown spelling, so its content is rendered bare -
3111            // EXCEPT for an authored `abbr`, which outranks the document
3112            // definition (carve#1127). This target can carry a title, since it
3113            // already emits an `<abbr>` for an ordinary expansion, so it carries
3114            // the AUTHORED one (carve#1176).
3115            let authored = span
3116                .attrs
3117                .as_ref()
3118                .and_then(|a| a.key_values.get("abbr"))
3119                .cloned();
3120            let Some(authored) = authored else {
3121                return render_inlines(&span.children, ctx, depth + 1);
3122            };
3123            let previous = ctx.suppress_automatic_abbreviation;
3124            ctx.suppress_automatic_abbreviation = true;
3125            let inner = render_inlines(&span.children, ctx, depth + 1);
3126            ctx.suppress_automatic_abbreviation = previous;
3127            if authored.is_empty() || !crate::abbr_budget::try_spend(authored.len()) {
3128                return inner;
3129            }
3130            let title = escape_md_html(&strip_controls(&authored)).replace('"', "&quot;");
3131            format!("<abbr title=\"{title}\">{inner}</abbr>")
3132        }
3133        InlineNode::Ruby(r) => {
3134            let mut out = format!("<ruby{}>", crate::render::render_attrs(&r.attrs));
3135            for pair in &r.pairs {
3136                out.push_str(&render_inlines(&pair.base, ctx, depth + 1));
3137                out.push_str("<rp>(</rp><rt>");
3138                out.push_str(&render_inlines(&pair.annotation, ctx, depth + 1));
3139                out.push_str("</rt><rp>)</rp>");
3140            }
3141            out.push_str("</ruby>");
3142            out
3143        }
3144        InlineNode::Math(math) => {
3145            // Escaped, exactly as the HTML target escapes the same content: a
3146            // consumer decodes the entity back to the character before its math
3147            // renderer sees it, so `a < b` still reaches KaTeX as `a < b` while
3148            // `<script>` cannot become a tag (carve-rs#807).
3149            let content = escape_md_html(&strip_controls(&math.content));
3150            let spelled = if math.display {
3151                format!("$${content}$$")
3152            } else {
3153                format!("${content}$")
3154            };
3155            // PART 9 §19: the same ` LABEL NUMBER` the HTML target appends,
3156            // without the wrapping span and under this target's escaping.
3157            match (&math.label, math.number) {
3158                (Some(label), Some(number)) => format!(
3159                    "{spelled} {} {number}",
3160                    escape_md_html(&strip_controls(label))
3161                ),
3162                _ => spelled,
3163            }
3164        }
3165        InlineNode::RawInline(raw) => {
3166            if raw.format == "html" {
3167                crate::render_loss::record_markdown_loss(
3168                    MarkdownLoss::RawHtml,
3169                    RawNodeType::Inline,
3170                    raw.pos.as_ref(),
3171                );
3172                escape_md_html(&strip_controls(&raw.content))
3173            } else {
3174                crate::render_loss::record_raw_drop(
3175                    &raw.format,
3176                    crate::RawNodeType::Inline,
3177                    raw.pos.clone(),
3178                );
3179                String::new()
3180            }
3181        }
3182        InlineNode::LiteralInline(lit) => {
3183            // §27: emitted by EVERY renderer, never dropped. It is prose, not
3184            // code, so no code fence -- the content becomes literal text with
3185            // Markdown metacharacters escaped so `*not bold*` stays visible.
3186            escape_text(&resolve_nbsp(&strip_controls(&lit.content)))
3187        }
3188        InlineNode::Symbol(symbol) => format!(":{}:", symbol.name),
3189        InlineNode::AutoLink(link) => {
3190            let raw_label = strip_controls(&link.text);
3191            let destination =
3192                encode_markdown_destination(&link.href, link.pos.as_ref(), DeniedSink::Destination);
3193            let title_value = link
3194                .attrs
3195                .as_ref()
3196                .and_then(|attrs| attrs.key_values.get("title"));
3197            if title_value.is_none()
3198                && markdown_angle_autolink(&raw_label, &link.href, &destination)
3199            {
3200                return format!("<{raw_label}>");
3201            }
3202            IN_LINK_TEXT.with(|d| d.set(d.get() + 1));
3203
3204            let label = escape_text(&raw_label);
3205
3206            IN_LINK_TEXT.with(|d| d.set(d.get() - 1));
3207            let title = title_value
3208                .map(|title| format!(" \"{}\"", escape_md_title(&strip_controls(title))))
3209                .unwrap_or_default();
3210            format!("[{label}]({destination}{title})")
3211        }
3212        InlineNode::Mention(mention) => format!("@{}", strip_controls(&mention.user)),
3213        InlineNode::Tag(tag) => escape_text(&format!("#{}", strip_controls(&tag.name))),
3214        InlineNode::Extension(extension) => render_inlines(&extension.children, ctx, depth + 1),
3215        InlineNode::Abbreviation(abbr) => {
3216            // Markdown has no abbreviation syntax; emit an HTML <abbr> so the
3217            // title survives (markdown allows inline HTML), matching carve-php.
3218            // Dropping it to plain text would lose the expansion.
3219            let text = escape_md_html(&strip_controls(&abbr.abbr));
3220            // Inside a span carrying its own `abbr`, only the visible text
3221            // (carve#1127).
3222            if ctx.suppress_automatic_abbreviation {
3223                return text;
3224            }
3225            // Bound cumulative expansion bytes (memory-amplification DoS): once
3226            // the budget is exhausted, degrade to plain key text with no title.
3227            if crate::abbr_budget::try_spend(abbr.expansion.len()) {
3228                // The attribute context needs the quote too; the other three
3229                // characters come from the one helper.
3230                let title = escape_md_html(&strip_controls(&abbr.expansion)).replace('"', "&quot;");
3231                format!("<abbr title=\"{title}\">{text}</abbr>")
3232            } else {
3233                text
3234            }
3235        }
3236        InlineNode::Footnote(footnote) => {
3237            if let Some(inline) = &footnote.inline {
3238                // A footnote body is an aside, not part of the label it sits in
3239                // -- the HTML target renders it outside the anchor entirely. So
3240                // a reference inside one is not nested and still links.
3241                // Its Markdown body still sits inside the outer label brackets.
3242                let outer = std::mem::replace(&mut ctx.link_depth, 0);
3243                let rendered = render_inlines(inline, ctx, depth + 1);
3244                ctx.link_depth = outer;
3245                format!("^[{rendered}]")
3246            } else {
3247                let id = strip_controls(footnote.id.as_deref().unwrap_or(""));
3248                if ctx.defined_footnotes.contains(&id) {
3249                    // Escaped like the definition above, so the pair still
3250                    // matches, and like the unresolved branch below, which
3251                    // already escapes -- that one was deciding the question for
3252                    // brackets and skipping it for HTML (carve-rs#807).
3253                    format!("[^{}]", escape_md_html(&id))
3254                } else {
3255                    // UNRESOLVED: ordinary text, and its brackets are Markdown
3256                    // metacharacters that PART 11 section 8 M1 escapes
3257                    // UNCONDITIONALLY. Bare, they hand the re-parser markup the
3258                    // document never had. The label between them is author
3259                    // content and gets the HTML pass for the same reason: this
3260                    // branch was deciding the question for brackets and
3261                    // skipping it for `<`.
3262                    format!("\\[^{}\\]", escape_md_html(&id).replace("\\", "\\\\"))
3263                }
3264            }
3265        }
3266        InlineNode::NonBreakingSpace(_) => "\u{00a0}".to_string(),
3267        InlineNode::SoftBreak(_) => "\n".to_string(),
3268        InlineNode::CellWrap(_) => " ".to_string(),
3269        // A BACKSLASH, not two trailing spaces (PART 11 section 9). Both mean
3270        // `<br />` to a CommonMark reader, but trailing whitespace is removed by
3271        // editors that strip on save, by `git apply --whitespace=fix` and by CI
3272        // whitespace checks -- and losing ONE of the two spaces is enough for the
3273        // break to vanish rather than degrade, silently, in a file nobody edited.
3274        // In a table cell the newline would end the GFM row (PART 11 section 9a).
3275        InlineNode::HardBreak(_) if ctx.single_line_depth > 0 => "<br>".to_string(),
3276        InlineNode::HardBreak(_) => "\\\n".to_string(),
3277        InlineNode::CriticInsert(insert) => {
3278            format!(
3279                "<ins>{}</ins>",
3280                render_inlines(&insert.children, ctx, depth + 1)
3281            )
3282        }
3283        InlineNode::CriticDelete(delete) => {
3284            // PART 11 section 8c: the class is what tells a deletion from the
3285            // bare `<del>` a `strike` falls back to, which otherwise reads back
3286            // as a strike (markup-carve/carve#2845).
3287            format!(
3288                "<del class=\"critic-delete\">{}</del>",
3289                render_inlines(&delete.children, ctx, depth + 1)
3290            )
3291        }
3292        InlineNode::CriticSubstitute(sub) => format!(
3293            "<del class=\"critic-delete\">{}</del><ins>{}</ins>",
3294            render_inlines(&sub.old, ctx, depth + 1),
3295            render_inlines(&sub.new, ctx, depth + 1)
3296        ),
3297        // Visible content: the HTML target renders it as
3298        // `<span class="critic-comment"> note </span>`, so dropping it here made two
3299        // targets of one engine disagree about whether the document says it. Markdown
3300        // has no critic syntax, so it carries the same span (markup-carve/carve#2791)
3301        // around the text, escaped like any other text, since a comment carrying
3302        // Markdown metacharacters must not become live markup when the output is
3303        // re-rendered. carve-php kept it
3304        // (carve#352, corpus 33-editorial-markup); plain and ANSI were fixed in
3305        // carve-rs#322.
3306        InlineNode::Comment(_) => String::new(),
3307        InlineNode::CriticComment(c) => format!(
3308            "<span class=\"critic-comment\">{}</span>",
3309            escape_text(&strip_controls(&c.text))
3310        ),
3311        // A RESOLVED cross-reference is a link to that target, so it renders as
3312        // one - `[Title](#id)` - under exactly the condition `render_link` uses:
3313        // only when this target will EMIT that id. A Markdown heading carries
3314        // `{#id}`; an image or a table does not, so a reference to a numbered
3315        // figure would produce a link to a fragment that is not in the output.
3316        // There the title alone is the honest rendering, which is what the
3317        // `numbered-figure-crossref` fixture pins.
3318        //
3319        // Emitting only the title in BOTH cases would silently drop every
3320        // heading link from the Markdown export - the mistake this arm was first
3321        // written with.
3322        InlineNode::CrossRef(crossref) => {
3323            // The label is the target's cloned inline NODES (PART 9R R4), so it
3324            // is written back out as Markdown markup rather than as flattened
3325            // text, and the source run reaches this renderer's typography mode.
3326            // A caption target has no nodes - its label is LABEL + NUMBER - so
3327            // that one is still a string.
3328            let resolved = ctx
3329                .crossref_index
3330                .resolve(&crossref.target)
3331                .map(|(id, title)| {
3332                    (
3333                        id.to_string(),
3334                        if crate::abbr_budget::label_rejected(&crossref.target) {
3335                            String::new()
3336                        } else {
3337                            title.to_string()
3338                        },
3339                    )
3340                });
3341            match resolved {
3342                // UNRESOLVED: the authored marker, kept readable rather than
3343                // escaped into noise - a reader can still act on `</#nope>`.
3344                // The TARGET inside it is author content and can hold a `<`,
3345                // and `</#a<script>` is a complete opening tag once this
3346                // Markdown is rendered, so the target takes the HTML pass while
3347                // the writer's own delimiters stay literal (carve-rs#807).
3348                None => {
3349                    let target = escape_md_html(&strip_controls(&crossref.target));
3350                    // An angle run in a Markdown link label is still label text.
3351                    // Its closing bracket must not end the surrounding link.
3352                    let target = if ctx.link_depth > 0 {
3353                        target.replace(']', "\\]")
3354                    } else {
3355                        target
3356                    };
3357                    format!("</#{target}>")
3358                }
3359                Some((id, title)) => {
3360                    let rejected = crate::abbr_budget::label_rejected(&crossref.target);
3361                    let label = if rejected {
3362                        None
3363                    } else {
3364                        ctx.crossref_index.label(&id)
3365                    };
3366                    // Written as link text below, where §8i escapes nothing.
3367                    let links = ctx.link_depth == 0 && ctx.heading_slugs.contains_key(&id);
3368                    if links {
3369                        IN_LINK_TEXT.with(|d| d.set(d.get() + 1));
3370                    }
3371                    let text = match &label {
3372                        Some(nodes) => render_inlines(nodes, ctx, depth + 1),
3373                        None => escape_text(&strip_controls(if rejected {
3374                            &crossref.target
3375                        } else {
3376                            &title
3377                        })),
3378                    };
3379                    // Same expansion budget the abbreviation arm below spends,
3380                    // degrading to the authored target (carve-rs#805). See
3381                    // `crate::abbr_budget`.
3382                    let text = if crate::abbr_budget::try_spend_label(
3383                        resolved_len(&text),
3384                        &crossref.target,
3385                    ) {
3386                        text
3387                    } else {
3388                        escape_text(&strip_controls(&crossref.target))
3389                    };
3390                    if links {
3391                        IN_LINK_TEXT.with(|d| d.set(d.get() - 1));
3392                    }
3393                    // Inside a link label the reference is already surrounded by
3394                    // an anchor, so it degrades to its display text -- the same
3395                    // rule the parser applies to every link it produces itself,
3396                    // and the HTML target applies to this node (carve-rs#436).
3397                    match ctx.heading_slugs.get(&id) {
3398                        Some(slug) if ctx.link_depth == 0 => format!("[{text}](#{slug})"),
3399                        _ => text,
3400                    }
3401                }
3402            }
3403        }
3404        // Tier-2 ext node; the core renderer has no numbering, so emit the source.
3405        InlineNode::CitationGroup(group) => strip_controls(&group.raw),
3406        InlineNode::CaptionNumber(number) => number
3407            .number
3408            .map(|n| n.to_string())
3409            .unwrap_or_else(|| "#".to_string()),
3410    }
3411}
3412
3413fn render_link(node: &Link, ctx: &mut MarkdownContext, depth: usize) -> String {
3414    if crate::parse::is_unresolved_reference(node) {
3415        return escape_text(&strip_controls(node.raw_ref.as_deref().unwrap_or_default()));
3416    }
3417    ctx.link_depth += 1;
3418    IN_LINK_TEXT.with(|d| d.set(d.get() + 1));
3419
3420    // Render the label through the anchor-unwrapping view.
3421    let children = unwrap_nested_anchors(&node.children);
3422    let ancestors = std::mem::take(&mut ctx.delimiter_ancestors);
3423    let text = render_inlines(children.as_ref(), ctx, depth);
3424    ctx.delimiter_ancestors = ancestors;
3425    IN_LINK_TEXT.with(|d| d.set(d.get() - 1));
3426
3427    ctx.link_depth -= 1;
3428    if ctx.roundtrip
3429        && node.attrs.is_none()
3430        && ctx.single_line_depth == 0
3431        && !fragment_id(&node.href).is_some_and(|id| ctx.heading_slugs.contains_key(id))
3432    {
3433        if let Some(label) = &node.ref_label {
3434            if let Some(def) = ctx.native_references.get(&crate::parse::label_key(label)) {
3435                if def.href == node.href && def.title == node.title {
3436                    if node
3437                        .raw_ref
3438                        .as_deref()
3439                        .is_some_and(|raw| raw.ends_with("[]"))
3440                        && text == def.label
3441                    {
3442                        return format!("[{text}][]");
3443                    }
3444                    return format!("[{text}][{}]", def.label);
3445                }
3446            }
3447        }
3448    }
3449    // A fragment naming a heading is written as that heading's GFM slug, which
3450    // needs no encoding; any other fragment is still the author's destination
3451    // (PART 11 sections 11 and 11a).
3452    if let Some(slug) = fragment_id(&node.href).and_then(|id| ctx.heading_slugs.get(id)) {
3453        let destination = format!("#{slug}");
3454        if let Some(title) = node.title.as_ref().or_else(|| {
3455            node.attrs
3456                .as_ref()
3457                .and_then(|attrs| attrs.key_values.get("title"))
3458        }) {
3459            format!(
3460                "[{text}]({destination} \"{}\")",
3461                escape_md_title(&strip_controls(title))
3462            )
3463        } else {
3464            format!("[{text}]({destination})")
3465        }
3466    } else {
3467        let mut href =
3468            encode_markdown_destination(&node.href, node.pos.as_ref(), DeniedSink::Destination);
3469        if node.href.is_empty() {
3470            href = "<>".to_owned();
3471        }
3472        if let Some(title) = node.title.as_ref().or_else(|| {
3473            node.attrs
3474                .as_ref()
3475                .and_then(|attrs| attrs.key_values.get("title"))
3476        }) {
3477            format!(
3478                "[{text}]({href} \"{}\")",
3479                escape_md_title(&strip_controls(title))
3480            )
3481        } else {
3482            format!("[{text}]({href})")
3483        }
3484    }
3485}
3486
3487fn render_image(node: &Image) -> String {
3488    if crate::parse::is_unresolved_image(node) {
3489        return escape_text(&strip_controls(node.raw_ref.as_deref().unwrap_or_default()));
3490    }
3491    let mut src =
3492        encode_markdown_destination(&node.src, node.pos.as_ref(), DeniedSink::ImageSource);
3493    if node.src.is_empty() {
3494        src = "<>".to_owned();
3495    }
3496    let alt = escape_md_label(&strip_controls(&node.alt));
3497    if let Some(title) = node.title.as_ref().or_else(|| {
3498        node.attrs
3499            .as_ref()
3500            .and_then(|attrs| attrs.key_values.get("title"))
3501    }) {
3502        format!(
3503            "![{}]({} \"{}\")",
3504            alt,
3505            src,
3506            escape_md_title(&strip_controls(title))
3507        )
3508    } else {
3509        format!("![{}]({})", alt, src)
3510    }
3511}
3512
3513fn escape_md_title(title: &str) -> String {
3514    neutralize_char_refs(&title.replace('\\', "\\\\").replace('"', "\\\""))
3515}
3516
3517fn escape_md_label(label: &str) -> String {
3518    IN_LINK_TEXT.with(|depth| depth.set(depth.get() + 1));
3519    let escaped = escape_text(label);
3520    IN_LINK_TEXT.with(|depth| depth.set(depth.get() - 1));
3521    escaped
3522}
3523
3524fn sanitize_code_lang(lang: &str) -> String {
3525    // Keep only the first whitespace-delimited token (the language word); drop
3526    // it if it still contains a backtick (would break the fence).
3527    let token = strip_controls(lang)
3528        .split_whitespace()
3529        .next()
3530        .unwrap_or("")
3531        .to_string();
3532    if token.contains('`') {
3533        String::new()
3534    } else {
3535        token
3536    }
3537}
3538
3539fn escape_code_title(title: &str) -> String {
3540    strip_controls(title)
3541        .replace('\\', "\\\\")
3542        .replace('"', "\\\"")
3543}
3544
3545fn safe_fence(content: &str, min: usize) -> String {
3546    safe_fence_with_marker(content, min, '`')
3547}
3548
3549fn safe_fence_with_marker(content: &str, min: usize, marker: char) -> String {
3550    let mut longest = 0usize;
3551    let mut current = 0usize;
3552    for ch in content.chars() {
3553        if ch == marker {
3554            current += 1;
3555            longest = longest.max(current);
3556        } else {
3557            current = 0;
3558        }
3559    }
3560    marker.to_string().repeat(min.max(longest + 1))
3561}
3562
3563fn render_code(content: &str) -> String {
3564    if content.is_empty() {
3565        return "<code></code>".to_owned();
3566    }
3567    if content.contains('\n') || content.contains('\t') {
3568        let mut escaped = String::with_capacity(content.len());
3569        for character in content.chars() {
3570            if character == '\n' {
3571                escaped.push_str("<!---->&#10;<!---->");
3572            } else if matches!(character, ' ' | '\t') || character.is_ascii_punctuation() {
3573                write!(&mut escaped, "&#{};", u32::from(character)).expect("writing to a String");
3574                if character == '@' {
3575                    escaped.push_str("<!---->");
3576                }
3577            } else {
3578                escaped.push(character);
3579            }
3580        }
3581        return format!("<code>{escaped}</code>");
3582    }
3583    let fence = safe_fence(content, 1);
3584    let needs_padding = content.starts_with('`')
3585        || content.ends_with('`')
3586        || (content.starts_with(' ')
3587            && content.ends_with(' ')
3588            && content.chars().any(|ch| ch != ' '));
3589    if needs_padding {
3590        format!("{fence} {content} {fence}")
3591    } else {
3592        format!("{fence}{content}{fence}")
3593    }
3594}
3595
3596fn fragment_id(href: &str) -> Option<&str> {
3597    href.strip_prefix('#')
3598}
3599
3600/// Graceful degradation: when no extension consumed the grouping `[label]`,
3601/// surface it as a leading bold line (mirroring how an admonition title
3602/// renders) so the authored label is never silently dropped in Markdown.
3603fn prepend_label(body: String, label: Option<&str>) -> String {
3604    match label {
3605        Some(label) if !label.is_empty() => {
3606            let l = pad_outside_on_its_own_line(escape_text(label), "**", "<strong>", "</strong>");
3607            if body.is_empty() {
3608                format!("{l}\n\n")
3609            } else {
3610                format!("{l}\n\n{body}")
3611            }
3612        }
3613        _ => body,
3614    }
3615}
3616
3617fn escape_text(text: &str) -> String {
3618    CARRIERS.with(|slot| {
3619        let mut out = String::with_capacity(text.len());
3620        // The carriers are read once and the inserts counted here, because a
3621        // carried character can be most of a long text and the thread-locals are
3622        // not free per character.
3623        let carriers = slot.borrow();
3624        let mut inserted = [0usize; CARRIER_COUNT];
3625        let mut carry = |slot: usize, out: &mut String| {
3626            inserted[slot] += 1;
3627            out.push_str(&carriers[slot]);
3628        };
3629        let autolinks = IN_LINK_TEXT.with(std::cell::Cell::get) == 0;
3630        // Both forms start on an ASCII byte and are decided from ASCII bytes, so
3631        // the scans read `text` in place: a 50k label is escaped once per
3632        // reference, and collecting it first cost more than the whole render.
3633        let bytes = text.as_bytes();
3634        for (at, ch) in text.char_indices() {
3635            // PART 11 §8i: a `:` or `.` that may start an autolink is decided on the
3636            // line, since the rest of the form can come from another node.
3637            if autolinks && ch == ':' && may_be_scheme_colon(bytes, at) {
3638                carry(C_SCHEME_COLON, &mut out);
3639                continue;
3640            }
3641            if autolinks && ch == '.' && may_be_www_dot(bytes, at) {
3642                carry(C_WWW_DOT, &mut out);
3643                continue;
3644            }
3645            // E1's local part can start the text, so there is no cheap prefilter the
3646            // way `://` and `www` give the other two: every text `@` is carried and
3647            // the line decides.
3648            if autolinks && ch == '@' {
3649                carry(C_EMAIL_AT, &mut out);
3650                continue;
3651            }
3652            match ch {
3653                // Neutralize embedded HTML so Markdown re-rendered to HTML cannot
3654                // execute it (carve's "HTML is text" guarantee for the Markdown
3655                // target too): a literal `<img onerror=…>` becomes inert.
3656                //
3657                // ONLY `<` AND `>` DO THAT WORK. A bare `&` cannot open a tag: an
3658                // entity in Markdown TEXT decodes to a CHARACTER, and a character in
3659                // text content is escaped again by whatever writes the HTML.
3660                // Measured against pandoc 3.5, commonmark.js and marked with raw
3661                // HTML ALLOWED - the entity and bare forms came out byte-identical
3662                // and inert, while a bare `<` was live in all three. Escaping every
3663                // ampersand cost every document its spelling for nothing
3664                // (carve#1071).
3665                //
3666                // NO EXCEPTION FOR A CHARACTER-REFERENCE OPENER, deliberately: text
3667                // authored as `&#65;` is emitted as itself. Whether an `&` opens a
3668                // reference depends on the EMITTED LINE, and Carve parses `#65` as a
3669                // tag, so this renderer sees two separate text nodes - answering it
3670                // here would be one node too early, the mistake section 8a
3671                // documents for `_`, `#` and `[`.
3672                // PART 11 section 8a M1e: a `<` is escaped only where the emitted
3673                // line would read it as markup - before an ASCII letter, `/`, `!`
3674                // or `?`, the four things that open raw HTML. Everything else is
3675                // inert, and so is `>` mid-line; at line start `>` is a block quote
3676                // marker M1 already covers.
3677                //
3678                // A BACKSLASH, not an entity. Both entities were written
3679                // unconditionally with no clause behind them (carve#1148), and that
3680                // is precisely because an entity is not the operation this section
3681                // describes: M2 and M3 protect a character so it survives as
3682                // itself, and an entity replaces it instead. Escaping the `<` alone
3683                // suffices - a tag that cannot open cannot be closed.
3684                // `<`, `&` and `!` are decided on the EMITTED LINE too, across node
3685                // boundaries (PART 11 §8d to §8f): a highlighter puts `<`, the tag
3686                // name and `>` in three spans, so the next character is often in
3687                // another node.
3688                '<' => {
3689                    carry(C_ANGLE, &mut out);
3690                    continue;
3691                }
3692                '&' => {
3693                    carry(C_AMPERSAND, &mut out);
3694                    continue;
3695                }
3696                '!' => {
3697                    carry(C_BANG, &mut out);
3698                    continue;
3699                }
3700                // `_`, `#` and `[` are emitted as SENTINELS rather than as
3701                // backslashes: PART 11 §8a decides those three on the EMITTED LINE,
3702                // which only `resolve_narrowed_escapes` can see.
3703                '_' => {
3704                    carry(C_UNDERSCORE, &mut out);
3705                    continue;
3706                }
3707                '#' => {
3708                    carry(C_POSITIONAL_HASH, &mut out);
3709                    continue;
3710                }
3711                '[' => {
3712                    if !autolinks {
3713                        out.push_str("\\[");
3714                    } else {
3715                        carry(C_BRACKET, &mut out);
3716                    }
3717                    continue;
3718                }
3719                // Markdown metacharacters. The ASTERISK keeps M1 unconditionally
3720                // (§8a M1a): this writer spells emphasis with `*`, so a literal
3721                // asterisk is not a character that MIGHT meet markup on the line -
3722                // it is the character the line's markup is made of. `*\*\**`
3723                // unescaped to `****`, which a CommonMark reader publishes as a
3724                // thematic break rather than as emphasis holding two asterisks.
3725                // `]` and the rest are M1c: nothing else narrows.
3726                // The TILDE is M1 unconditionally too: GFM strikethrough pairs a
3727                // run of one or two, so two literal tildes in a paragraph close
3728                // over whatever markup stands between them.
3729                '\\' | '`' | '*' | '~' | ']' => out.push('\\'),
3730                _ => {}
3731            }
3732            out.push(ch);
3733        }
3734        INSERTED.with(|counts| {
3735            let mut current = counts.get();
3736            for (slot, count) in inserted.iter().enumerate() {
3737                current[slot] += count;
3738            }
3739            counts.set(current);
3740        });
3741        out
3742    })
3743}
3744
3745/// Whether the `:` at `at` could be a scheme's, given only its own node: a
3746/// `//` (or the end of the value) after it, and a letter run before it that is
3747/// a scheme or reaches the start of the value.
3748fn may_be_scheme_colon(bytes: &[u8], at: usize) -> bool {
3749    let rest = &bytes[at + 1..];
3750    let slashes = rest.iter().take(2).take_while(|b| **b == b'/').count();
3751    if slashes < rest.len().min(2) {
3752        return false;
3753    }
3754    let run = bytes[..at]
3755        .iter()
3756        .rev()
3757        .take_while(|b| b.is_ascii_alphabetic())
3758        .count();
3759    run == at || scheme_ends_at(at, |k| bytes.get(k).map(|b| *b as char))
3760}
3761
3762/// Whether the `.` at `at` could end a `www`: three `w` before it, or a run of
3763/// them reaching the start of the value.
3764fn may_be_www_dot(bytes: &[u8], at: usize) -> bool {
3765    let run = bytes[..at].iter().rev().take_while(|b| **b == b'w').count();
3766    run >= 3 || run == at
3767}
3768
3769/// Whether `http`, `https` or `ftp` ends at `at` and no ASCII letter precedes it
3770/// (§8i U1).
3771/// Read through `char_at` so both passes can ask: the escape pass indexes one
3772/// text node's bytes, the resolve pass the whole line's chars.
3773fn scheme_ends_at(at: usize, char_at: impl Fn(usize) -> Option<char>) -> bool {
3774    ["https", "http", "ftp"].iter().any(|scheme| {
3775        let len = scheme.len();
3776        at >= len
3777            && scheme
3778                .chars()
3779                .enumerate()
3780                .all(|(k, s)| char_at(at - len + k).is_some_and(|c| c.eq_ignore_ascii_case(&s)))
3781            && !(at > len && char_at(at - len - 1).is_some_and(|c| c.is_ascii_alphabetic()))
3782    })
3783}
3784
3785/// Carriers standing in for the escapes PART 11 §8a and §8b decide on the LINE,
3786/// CHOSEN PER DOCUMENT from code points it does not contain.
3787const CARRIER_DEFAULTS: [char; 10] = [
3788    '\u{E004}', '\u{E005}', '\u{E006}', '\u{E007}', '\u{E008}', '\u{E009}', '\u{E00A}', '\u{E00B}',
3789    '\u{E00C}', '\u{E00D}',
3790];
3791const CARRIER_COUNT: usize = CARRIER_DEFAULTS.len();
3792
3793/// Slot indices into [`CARRIER_DEFAULTS`] / [`CARRIERS`].
3794///
3795/// ONE HASH SLOT SERVES BOTH CLAUSES. §8a M1f and §8b M2b ask the same
3796/// positional question, so a `#` from a text node and one from an
3797/// `escaped_text` node are decided alike and need no slot of their own.
3798const C_UNDERSCORE: usize = 0;
3799const C_BRACKET: usize = 1;
3800const C_POSITIONAL_HASH: usize = 2;
3801const C_ANGLE: usize = 3;
3802const C_AMPERSAND: usize = 4;
3803const C_BANG: usize = 5;
3804/// The `:` and `.` that may start a GFM autolink (PART 11 §8i).
3805const C_SCHEME_COLON: usize = 6;
3806const C_WWW_DOT: usize = 7;
3807/// The `@` of an address GFM's email extension would match (§8i E1). Its own
3808/// slot because it is the one form in §8i spelled with an empty comment rather
3809/// than a backslash, and the emit site reads the slot to know that.
3810const C_EMAIL_AT: usize = 8;
3811const C_PAYLOAD_BOUNDARY: usize = 9;
3812
3813thread_local! {
3814    /// The carriers in force for the render running on this thread.
3815    ///
3816    /// A thread-local for the same reason as `SMART_TYPOGRAPHY` above: they are
3817    /// written by two escape sites and read by the resolve pass, and threading
3818    /// them through every signature in the render tree buys nothing.
3819    static DEFAULT_CARRIER_TOKENS: [Rc<String>; CARRIER_COUNT] =
3820        CARRIER_DEFAULTS.map(|marker| Rc::new(marker.to_string()));
3821    static CARRIERS: std::cell::RefCell<[Rc<String>; CARRIER_COUNT]> =
3822        std::cell::RefCell::new(DEFAULT_CARRIER_TOKENS.with(Clone::clone));
3823    static OCCUPIED_TOKEN_NONCES: std::cell::RefCell<std::collections::BTreeSet<usize>> =
3824        const { std::cell::RefCell::new(std::collections::BTreeSet::new()) };
3825    /// How many of each this render INSERTED.
3826    static INSERTED: std::cell::Cell<[usize; CARRIER_COUNT]> =
3827        const { std::cell::Cell::new([0; CARRIER_COUNT]) };
3828    /// How many of each stood in the assembled document, counted where the
3829    /// resolve pass reads it - which is the last moment an authored one is still
3830    /// visible, because resolving is what consumes them.
3831    static SEEN: std::cell::Cell<[usize; CARRIER_COUNT]> =
3832        const { std::cell::Cell::new([0; CARRIER_COUNT]) };
3833    /// Every private-use code point the assembled document holds, so a re-pick
3834    /// is made against a SET rather than against a second copy of the document.
3835    static OCCUPIED: std::cell::RefCell<std::collections::BTreeSet<u32>> =
3836        const { std::cell::RefCell::new(std::collections::BTreeSet::new()) };
3837    /// Mirrors `MarkdownContext::link_depth` for `escape_text`: GFM builds no
3838    /// autolink inside a link's text, so §8i escapes nothing there.
3839    static IN_LINK_TEXT: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
3840}
3841
3842/// Install `chars` for the duration of one render, restoring the previous run on
3843/// drop (panic unwind included).
3844struct CarrierGuard(Option<[Rc<String>; CARRIER_COUNT]>);
3845
3846impl CarrierGuard {
3847    fn install_defaults() -> CarrierGuard {
3848        DEFAULT_CARRIER_TOKENS.with(|defaults| {
3849            let installed = CARRIERS.with(|slot| {
3850                slot.borrow()
3851                    .iter()
3852                    .zip(defaults)
3853                    .all(|(current, default)| Rc::ptr_eq(current, default))
3854            });
3855            if installed {
3856                CarrierGuard(None)
3857            } else {
3858                CarrierGuard::install(defaults.clone())
3859            }
3860        })
3861    }
3862
3863    fn install(chars: [Rc<String>; CARRIER_COUNT]) -> CarrierGuard {
3864        CarrierGuard(Some(CARRIERS.with(|slot| slot.replace(chars))))
3865    }
3866}
3867
3868impl Drop for CarrierGuard {
3869    fn drop(&mut self) {
3870        if let Some(markers) = self.0.take() {
3871            CARRIERS.with(|slot| *slot.borrow_mut() = markers);
3872        }
3873    }
3874}
3875
3876/// Byte length of `text` with every carrier counted as the ASCII character it
3877/// stands for, so the label budget is charged alike in every engine.
3878fn resolved_len(text: &str) -> usize {
3879    CARRIERS.with(|slot| {
3880        carrier_tokens(text, &slot.borrow())
3881            .map(|token| {
3882                if token.slot == Some(C_PAYLOAD_BOUNDARY) {
3883                    0
3884                } else if token.slot.is_some() {
3885                    1
3886                } else {
3887                    token.character.len_utf8()
3888                }
3889            })
3890            .sum()
3891    })
3892}
3893
3894struct CarrierToken<'a> {
3895    raw: &'a str,
3896    character: char,
3897    slot: Option<usize>,
3898}
3899
3900fn carrier_tokens<'a>(
3901    text: &'a str,
3902    markers: &'a [Rc<String>; CARRIER_COUNT],
3903) -> impl Iterator<Item = CarrierToken<'a>> + 'a {
3904    let mut offset = 0;
3905    let first_characters: [char; CARRIER_COUNT] =
3906        std::array::from_fn(|index| markers[index].chars().next().unwrap());
3907    let single_characters = markers
3908        .iter()
3909        .zip(first_characters)
3910        .all(|(marker, character)| marker.len() == character.len_utf8());
3911    debug_assert!(first_characters
3912        .iter()
3913        .all(|character| !character.is_ascii()));
3914    std::iter::from_fn(move || {
3915        if offset == text.len() {
3916            return None;
3917        }
3918        let rest = &text[offset..];
3919        let authored = rest.chars().next().unwrap();
3920        let slot = if authored.is_ascii() {
3921            None
3922        } else if single_characters {
3923            first_characters
3924                .iter()
3925                .position(|character| *character == authored)
3926        } else {
3927            markers
3928                .iter()
3929                .position(|marker| rest.starts_with(marker.as_str()))
3930        };
3931        let (character, width) = match slot {
3932            Some(index) => (carried_character(index), markers[index].len()),
3933            None => (authored, authored.len_utf8()),
3934        };
3935        let raw = &text[offset..offset + width];
3936        offset += width;
3937        Some(CarrierToken {
3938            raw,
3939            character,
3940            slot,
3941        })
3942    })
3943}
3944
3945fn carrier(which: usize) -> Rc<String> {
3946    CARRIERS.with(|slot| slot.borrow()[which].clone())
3947}
3948
3949/// Record one carrier this render put into the text. The count is what tells an
3950/// authored occurrence from one of ours; see `render_markdown_inner`.
3951fn note_inserted(which: usize) {
3952    INSERTED.with(|counts| {
3953        let mut current = counts.get();
3954        current[which] += 1;
3955        counts.set(current);
3956    });
3957}
3958
3959fn marker_pool_needs_tokens(occupied: &std::collections::BTreeSet<u32>) -> bool {
3960    let pool_size = (crate::sentinel_run::POOL_LAST - crate::sentinel_run::POOL_FIRST + 1) as usize;
3961    if occupied.len() < pool_size / CARRIER_COUNT {
3962        return false;
3963    }
3964    let picked: [char; CARRIER_COUNT] =
3965        crate::sentinel_run::pick_sentinel_run(occupied, u32::from(CARRIER_DEFAULTS[0]));
3966    picked
3967        .iter()
3968        .any(|marker| occupied.contains(&u32::from(*marker)))
3969}
3970
3971/// Count the carriers standing in the assembled document, and record which
3972/// private-use code points it occupies.
3973///
3974/// One pass over the text the resolve pass is about to read, and the occupancy
3975/// answer is a SET bounded by the private-use area - not the document's text
3976/// joined, which would be a second full copy of it.
3977fn note_assembled(text: &str) {
3978    if text.is_ascii() {
3979        return;
3980    }
3981    let mut seen = SEEN.with(std::cell::Cell::get);
3982    let needs_nonces = OCCUPIED.with(|occupied| {
3983        let mut occupied = occupied.borrow_mut();
3984        crate::sentinel_run::collect_private_use(text, &mut occupied);
3985        marker_pool_needs_tokens(&occupied)
3986    });
3987    if needs_nonces {
3988        OCCUPIED_TOKEN_NONCES.with(|nonces| {
3989            crate::sentinel_run::collect_marker_nonce_cores(text, &mut nonces.borrow_mut());
3990        });
3991    }
3992    CARRIERS.with(|slot| {
3993        let markers = slot.borrow();
3994        let characters: [char; CARRIER_COUNT] =
3995            std::array::from_fn(|index| markers[index].chars().next().unwrap());
3996        if markers
3997            .iter()
3998            .zip(characters)
3999            .all(|(marker, character)| marker.len() == character.len_utf8())
4000        {
4001            for character in text.chars().filter(|character| !character.is_ascii()) {
4002                if let Some(index) = characters.iter().position(|marker| *marker == character) {
4003                    seen[index] += 1;
4004                }
4005            }
4006        } else {
4007            for token in carrier_tokens(text, &markers) {
4008                if let Some(index) = token.slot {
4009                    seen[index] += 1;
4010                }
4011            }
4012        }
4013    });
4014    SEEN.with(|counts| counts.set(seen));
4015}
4016
4017/// PART 11 §8b M2a: characters this target's readers never read as markup, at
4018/// ANY position on the line.
4019///
4020/// An `escaped_text` node holding one of these is emitted BARE. They are
4021/// Carve's own delimiters and Markdown has no reading for them, so the escape
4022/// protects nothing and lands inside an identifier.
4023///
4024/// `~` is NOT here: GFM reads `~x~` as strikethrough. Nor are the
4025/// smart-punctuation triggers `"`, `'`, `-` and `.`, which §8b keeps whatever
4026/// their position, because a processor with substitution on rewrites the TEXT
4027/// rather than reading markup.
4028const AUTHORED_INERT: [char; 8] = ['{', '}', '^', ',', '%', ':', '/', '@'];
4029
4030/// Whether §8b M2b defers an AUTHORED escape of `ch` to the line.
4031///
4032/// A second family rather than a wider first one, because the two are decided
4033/// by DIFFERENT tests: M1b asks about an adjacent delimiter of the same
4034/// character, M1f and M2b ask where on the line the character stands.
4035fn authored_defers_to_the_line(ch: char) -> bool {
4036    ch == '#'
4037}
4038
4039/// The carrier for an escape the position test decides, counted as inserted.
4040fn positional_sentinel() -> Rc<String> {
4041    note_inserted(C_POSITIONAL_HASH);
4042    carrier(C_POSITIONAL_HASH)
4043}
4044
4045/// Which slot `ch` is, if it is a carrier at all.
4046///
4047/// Takes the run rather than reading the thread-local, because both callers ask
4048/// once per character of the assembled document and the run cannot move under
4049/// them mid-pass.
4050fn carrier_slot(carriers: &[Rc<String>; CARRIER_COUNT], ch: char) -> Option<usize> {
4051    carriers.iter().position(|current| current.chars().eq([ch]))
4052}
4053
4054/// The character a carrier stands for: M1b's two, and the positional hash.
4055fn carried_character(slot: usize) -> char {
4056    match slot {
4057        C_UNDERSCORE => '_',
4058        C_BRACKET => '[',
4059        C_ANGLE => '<',
4060        C_AMPERSAND => '&',
4061        C_BANG => '!',
4062        C_SCHEME_COLON => ':',
4063        C_WWW_DOT => '.',
4064        C_EMAIL_AT => '@',
4065        _ => '#',
4066    }
4067}
4068
4069/// Drop control characters from author content.
4070///
4071/// THE §8a CARRIERS ARE NOT DROPPED HERE, and that is markup-carve/carve-rs#1216.
4072/// They are this renderer's own markers, and deleting the range they occupied was
4073/// how author content was kept off them - at the cost of the author's character,
4074/// in every context including a fenced code block. They are picked per document
4075/// now (see `CARRIER_DEFAULTS`), so no authored character can be one and nothing
4076/// has to be deleted to keep it that way.
4077///
4078/// THE CONTROL HALF STAYS AS BROAD AS IT WAS. It is `strip_control_chars`, which
4079/// is every `Cc` character bar tab and newline, NOT the non-whitespace C0 class:
4080/// DEL (U+007F) and the C1 controls have to keep going, because CSI (U+009B) and
4081/// OSC (U+009D) are single-character forms of the sequences PART 9 §25's terminal
4082/// rule exists to stop. Narrowing this guard is a security regression, and the
4083/// test suite pins it rather than leaving it to this comment.
4084fn strip_controls(input: &str) -> String {
4085    strip_control_chars(input)
4086}
4087
4088/// Resolve the internal staging marker to Markdown's literal no-break space.
4089fn resolve_nbsp(text: &str) -> String {
4090    text.replace(crate::NBSP_PLACEHOLDER, "\u{00a0}")
4091}
4092
4093/// Escape `<>&` so embedded raw HTML cannot become live markup downstream.
4094fn escape_md_html(text: &str) -> String {
4095    text.replace('&', "&amp;")
4096        .replace('<', "&lt;")
4097        .replace('>', "&gt;")
4098}
4099
4100/// Blank a URL whose (normalized) scheme is on the dangerous denylist, so it does
4101/// not survive into Markdown output and from there into whatever renders it.
4102///
4103/// The set and the probe filter come from `escape`, not restated here. A local copy
4104/// listed only `javascript`, `vbscript`, `data` and `file`, and filtered with an
4105/// ASCII-only test -- so the twenty OS protocol-handler schemes (`ms-msdt`,
4106/// `search-ms`, `shell`, `vscode`, `jar`, ...) reached the output while the HTML
4107/// renderer blanked them. A Markdown destination is resolved by the renderer
4108/// downstream, so that is the same sink one step removed (PART 9 section 25,
4109/// markup-carve/carve#385).
4110fn sanitize_md_url(url: &str, pos: Option<&Pos>, sink: DeniedSink) -> String {
4111    // The PROBE comes from `escape` too, not only the scheme set. The body used
4112    // to be restated here and had already drifted: it dropped the non-empty
4113    // prefix guard its original has, so `:x` was read as a scheme with an empty
4114    // name. One copy cannot drift from itself.
4115    crate::escape::sanitize_destination(url, pos, sink).into_owned()
4116}
4117
4118fn markdown_angle_autolink(label: &str, href: &str, destination: &str) -> bool {
4119    if destination == label {
4120        if let Some((scheme, body)) = label.split_once(':') {
4121            let scheme = scheme.as_bytes();
4122            if (2..=32).contains(&scheme.len())
4123                && scheme[0].is_ascii_alphabetic()
4124                && scheme[1..]
4125                    .iter()
4126                    .all(|b| b.is_ascii_alphanumeric() || matches!(*b, b'+' | b'.' | b'-'))
4127                && !body.is_empty()
4128                && body.chars().all(|ch| {
4129                    !ch.is_whitespace() && !ch.is_control() && !matches!(ch, '<' | '>' | '\\')
4130                })
4131            {
4132                return true;
4133            }
4134        }
4135    }
4136    if href.strip_prefix("mailto:") != Some(label) || destination != href {
4137        return false;
4138    }
4139    let Some((local, domain)) = label.split_once('@') else {
4140        return false;
4141    };
4142    let local_valid = !local.is_empty()
4143        && local
4144            .chars()
4145            .all(|ch| ch.is_ascii_alphanumeric() || ".!#$%&'*+/=?^_`{|}~-".contains(ch));
4146    let labels: Vec<&str> = domain.split('.').collect();
4147    local_valid
4148        && labels.len() >= 2
4149        && labels.iter().all(|part| {
4150            let bytes = part.as_bytes();
4151            (1..=63).contains(&bytes.len())
4152                && bytes[0].is_ascii_alphanumeric()
4153                && bytes[bytes.len() - 1].is_ascii_alphanumeric()
4154                && bytes
4155                    .iter()
4156                    .all(|b| b.is_ascii_alphanumeric() || *b == b'-')
4157        })
4158}
4159
4160/// Encode a destination for the Markdown output, refusing a denied scheme.
4161///
4162/// The order is the whole point. This writer NORMALIZES the destination before
4163/// it emits it - it drops control characters, and its consumer decodes character
4164/// references - so the probe has to run on the normalized form. Probing the
4165/// authored form and normalizing afterwards means the writer itself
4166/// manufactures the live URL out of one the probe had already dismissed
4167/// (`markup-carve/carve-rs#806`).
4168fn encode_markdown_destination(url: &str, pos: Option<&Pos>, sink: DeniedSink) -> String {
4169    // 1. Strip first, probe second. The strip drops all of `\p{Cc}`, the probe
4170    //    skips only up to U+0020 plus whitespace, so `java<DEL>script:` and the
4171    //    C1 range walked straight through and came out clean on the far side.
4172    //    The ANSI target of this same engine already strips before it probes
4173    //    (`render_ansi.rs`), and carve-php strips inside its probe.
4174    let sanitized = sanitize_md_url(&strip_controls(url), pos, sink);
4175    let mut out = String::new();
4176    let pipe_destination = sanitized.contains('|');
4177    for ch in sanitized.chars() {
4178        match ch {
4179            '\\' if pipe_destination => out.push_str("%5C"),
4180            '|' => out.push_str("%7C"),
4181            ' ' => out.push_str("%20"),
4182            '(' => out.push_str("\\("),
4183            ')' => out.push_str("\\)"),
4184            '<' => out.push_str("%3C"),
4185            '>' => out.push_str("%3E"),
4186            _ => out.push(ch),
4187        }
4188    }
4189    // 2. Neutralize character references, so the bytes the consumer resolves are
4190    //    the bytes probed in step 1.
4191    neutralize_char_refs(&out)
4192}
4193
4194/// Escape every ampersand that OPENS an HTML character reference.
4195///
4196/// A CommonMark consumer decodes character references inside a link
4197/// destination, so `&#106;avascript:alert1` reaches the browser as
4198/// `javascript:alert1` - a scheme the probe never saw, because the probe reads
4199/// the authored bytes. `&#x6A;` and `javascript&colon;alert1` are the same trick
4200/// (the second hides the colon, so there is no scheme to find at all).
4201///
4202/// Escaping the ampersand rather than percent-encoding it is what keeps this
4203/// honest: percent-encoding `&` would corrupt every legitimate query string,
4204/// while `&amp;` decodes back to `&` in the consumer, so the URL it resolves is
4205/// byte-for-byte the one probed here. It also stops the consumer from silently
4206/// rewriting an authored `&#106;` into `j`. An ampersand that opens nothing
4207/// (`?a=1&b=2`) is left exactly as authored.
4208fn neutralize_char_refs(url: &str) -> String {
4209    if !url.contains('&') {
4210        return url.to_string();
4211    }
4212    let mut out = String::with_capacity(url.len() + 8);
4213    for (i, ch) in url.char_indices() {
4214        if ch == '&' && opens_char_ref(&url[i + ch.len_utf8()..]) {
4215            out.push_str("&amp;");
4216        } else {
4217            out.push(ch);
4218        }
4219    }
4220    out
4221}
4222
4223/// Does the text after an `&` spell a character reference?
4224///
4225/// The three forms a consumer decodes: `#DIGITS;`, `#xHEXDIGITS;` and `NAME;`.
4226/// An unknown NAME counts too - a consumer leaves it alone either way, so
4227/// escaping it changes nothing a reader sees, and guessing which names are known
4228/// would be a second denylist to keep in step with three engines.
4229fn opens_char_ref(rest: &str) -> bool {
4230    let mut chars = rest.chars();
4231    match chars.next() {
4232        Some('#') => {
4233            let digits = chars.as_str();
4234            let (digits, hex) = match digits.strip_prefix(['x', 'X']) {
4235                Some(after) => (after, true),
4236                None => (digits, false),
4237            };
4238            for (seen, c) in digits.chars().enumerate() {
4239                if c == ';' {
4240                    return seen > 0;
4241                }
4242                let is_digit = if hex {
4243                    c.is_ascii_hexdigit()
4244                } else {
4245                    c.is_ascii_digit()
4246                };
4247                if !is_digit || seen >= 8 {
4248                    return false;
4249                }
4250            }
4251            false
4252        }
4253        Some(c) if c.is_ascii_alphabetic() => {
4254            for (seen, c) in (1usize..).zip(chars) {
4255                if c == ';' {
4256                    return true;
4257                }
4258                if !c.is_ascii_alphanumeric() || seen >= 32 {
4259                    return false;
4260                }
4261            }
4262            false
4263        }
4264        _ => false,
4265    }
4266}
4267
4268fn normalize(text: &str) -> String {
4269    let carriers = CARRIERS.with(|slot| slot.borrow().clone());
4270    let mut out = String::with_capacity(text.len());
4271    let mut newlines = 0usize;
4272    for (index, chunk) in text
4273        .split(carriers[C_PAYLOAD_BOUNDARY].as_str())
4274        .enumerate()
4275    {
4276        if index > 0 {
4277            out.push_str(&carriers[C_PAYLOAD_BOUNDARY]);
4278        }
4279        if index % 2 == 1 {
4280            out.push_str(chunk);
4281            let trailing = chunk
4282                .bytes()
4283                .rev()
4284                .take_while(|byte| *byte == b'\n')
4285                .count();
4286            newlines = if trailing == chunk.len() {
4287                newlines + trailing
4288            } else {
4289                trailing
4290            };
4291            continue;
4292        }
4293        let mut cursor = 0;
4294        for (at, _) in chunk.match_indices('\n') {
4295            if at > cursor {
4296                out.push_str(&chunk[cursor..at]);
4297                newlines = 0;
4298            }
4299            newlines += 1;
4300            if newlines <= 2 {
4301                out.push('\n');
4302            }
4303            cursor = at + 1;
4304        }
4305        if cursor < chunk.len() {
4306            out.push_str(&chunk[cursor..]);
4307            newlines = 0;
4308        }
4309    }
4310    let collapsed = format!("{}\n", out.trim_matches(|c| c == '\n' || c == ' '));
4311
4312    // COUNTED HERE and not at the end of the render, because resolving is what
4313    // consumes a carrier: by the time the render returns, an authored one has
4314    // already been read as an escape and is indistinguishable from never having
4315    // been there. Same place `render_carve` counts its own.
4316    note_assembled(&collapsed);
4317    resolve_narrowed_escapes(&collapsed)
4318}
4319
4320/// Whether the candidate at `i` is ADJACENT to an unescaped delimiter of the
4321/// same character, on the line the writer is building (PART 11 §8a M1b).
4322///
4323/// `line` is the assembled output with every candidate resolved to its BARE
4324/// character, so it is the line as it reads if nothing is escaped, and an index
4325/// into it is an index into the text being rewritten. "On the emitted line"
4326/// needs no line splitting: a neighbour across a newline IS a newline, which is
4327/// never the same character.
4328///
4329/// A neighbour BEFORE the candidate counts only if it is not itself behind a
4330/// backslash - the clause's "not behind a backslash" - so the run of backslashes
4331/// in front of it is counted and an odd run disqualifies it. A neighbour AFTER
4332/// never can be: the character in front of it is the candidate itself.
4333fn adjacent_to_live_delimiter(line: &[char], i: usize, ch: char) -> bool {
4334    if line.get(i + 1) == Some(&ch) {
4335        return true;
4336    }
4337    if i == 0 || line[i - 1] != ch {
4338        return false;
4339    }
4340    let mut backslashes = 0usize;
4341    let mut j = i.checked_sub(2);
4342    while let Some(k) = j {
4343        if line[k] != '\\' {
4344            break;
4345        }
4346        backslashes += 1;
4347        j = k.checked_sub(1);
4348    }
4349    backslashes % 2 == 0
4350}
4351
4352/// M1b's second condition for `_`: which `_` from text could pair with
4353/// another in its paragraph, heading or table cell, by CommonMark 6.2 read for
4354/// the underscore.
4355///
4356/// One scan per block: an opener pairs with any closer after it, a closer with
4357/// any opener before it. Only a `_` from text is a candidate, so one the
4358/// author escaped is never half of a pair.
4359fn underscores_that_could_pair(text: &[char], slots: &[u8]) -> Vec<bool> {
4360    let mut escape = vec![false; text.len()];
4361    for block in inline_blocks(text) {
4362        let flags: Vec<(usize, bool, bool)> = block
4363            .iter()
4364            .flat_map(|&(start, end)| (start..end).map(move |i| (start, end, i)))
4365            .filter(|&(_, _, i)| slots[i] == C_UNDERSCORE as u8)
4366            .map(|(start, end, i)| {
4367                // A line or cell boundary is whitespace to the reader.
4368                let before = if i == start { ' ' } else { text[i - 1] };
4369                let after = if i + 1 < end { text[i + 1] } else { ' ' };
4370                let left = !flank_space(after)
4371                    && (!flank_punct(after) || flank_space(before) || flank_punct(before));
4372                let right = !flank_space(before)
4373                    && (!flank_punct(before) || flank_space(after) || flank_punct(after));
4374                let opens = left && (!right || flank_punct(before));
4375                let closes = right && (!left || flank_punct(after));
4376                (i, opens, closes)
4377            })
4378            .collect();
4379        let mut opener_before = false;
4380        for &(i, opens, closes) in &flags {
4381            if closes && opener_before {
4382                escape[i] = true;
4383            }
4384            opener_before |= opens;
4385        }
4386        let mut closer_after = false;
4387        for &(i, opens, closes) in flags.iter().rev() {
4388            if opens && closer_after {
4389                escape[i] = true;
4390            }
4391            closer_after |= closes;
4392        }
4393    }
4394    escape
4395}
4396
4397/// The emitted document cut into the blocks M1b reads, each as the content
4398/// ranges of its lines: a blank line ends a block, a heading and a new list
4399/// item start one, and every table cell is one of its own. `raw` still holds
4400/// the carriers, so a `#` the writer will escape is not taken for a heading.
4401fn inline_blocks(text: &[char]) -> Vec<Vec<(usize, usize)>> {
4402    let mut blocks = Vec::new();
4403    let mut current: Vec<(usize, usize)> = Vec::new();
4404    let mut line_start = 0usize;
4405    while line_start <= text.len() {
4406        let line_end = text[line_start..]
4407            .iter()
4408            .position(|c| *c == '\n')
4409            .map_or(text.len(), |at| line_start + at);
4410        let content = content_position(text, line_start).min(line_end);
4411        let body = &text[content..line_end];
4412        if body.iter().all(|c| *c == ' ') {
4413            if !current.is_empty() {
4414                blocks.push(std::mem::take(&mut current));
4415            }
4416        } else if body[0] == '|' {
4417            if !current.is_empty() {
4418                blocks.push(std::mem::take(&mut current));
4419            }
4420            let mut cell = content + 1;
4421            let mut i = cell;
4422            while i < line_end {
4423                if text[i] == '\\' {
4424                    i += 2;
4425                    continue;
4426                }
4427                if text[i] == '|' {
4428                    blocks.push(vec![(cell, i)]);
4429                    cell = i + 1;
4430                }
4431                i += 1;
4432            }
4433            if cell < line_end {
4434                blocks.push(vec![(cell, line_end)]);
4435            }
4436        } else if starts_a_list_item(text, line_start) {
4437            if !current.is_empty() {
4438                blocks.push(std::mem::take(&mut current));
4439            }
4440            current.push((content, line_end));
4441        } else {
4442            current.push((content, line_end));
4443        }
4444        line_start = line_end + 1;
4445    }
4446    if !current.is_empty() {
4447        blocks.push(current);
4448    }
4449    blocks
4450}
4451
4452/// Whether the line opens a list item, past any quote markers in front of it.
4453fn starts_a_list_item(text: &[char], line_start: usize) -> bool {
4454    let mut at = line_start;
4455    loop {
4456        while text.get(at) == Some(&' ') {
4457            at += 1;
4458        }
4459        match text.get(at) {
4460            Some('>') => match container_prefix_end(text, at) {
4461                Some(end) => at = end,
4462                None => return false,
4463            },
4464            Some(_) => return container_prefix_end(text, at).is_some(),
4465            None => return false,
4466        }
4467    }
4468}
4469
4470/// Resolve the narrowed escapes: PART 11 §8a, M1b.
4471fn resolve_narrowed_escapes(text: &str) -> String {
4472    if text.is_ascii() {
4473        return text.to_string();
4474    }
4475    // READ ONCE. The carriers are a property of the render, not of the
4476    // character, and this pass asks about every character of the assembled
4477    // document - twice before the loop even starts.
4478    let carriers = CARRIERS.with(|slot| slot.borrow().clone());
4479    if !carriers[..C_PAYLOAD_BOUNDARY]
4480        .iter()
4481        .any(|marker| text.contains(marker.as_str()))
4482    {
4483        return text.replace(carriers[C_PAYLOAD_BOUNDARY].as_str(), "");
4484    }
4485    let mut line = Vec::new();
4486    let mut raw_chars = Vec::new();
4487    let mut slots = Vec::new();
4488    const NO_SLOT: u8 = u8::MAX;
4489    const _: () = assert!(CARRIER_COUNT < u8::MAX as usize);
4490    let mut markers = std::collections::BTreeMap::<usize, String>::new();
4491    let mut cursor = 0;
4492    for range in inline_marker_ranges(text)
4493        .into_iter()
4494        .chain(std::iter::once(text.len()..text.len()))
4495    {
4496        for token in carrier_tokens(&text[cursor..range.start], &carriers)
4497            .filter(|token| token.slot != Some(C_PAYLOAD_BOUNDARY))
4498        {
4499            line.push(token.character);
4500            raw_chars.push(token.raw.chars().next().unwrap());
4501            slots.push(token.slot.map_or(NO_SLOT, |slot| slot as u8));
4502        }
4503        if !range.is_empty() {
4504            markers
4505                .entry(line.len())
4506                .or_default()
4507                .push_str(&text[range.clone()]);
4508        }
4509        cursor = range.end;
4510    }
4511    let pairs = underscores_that_could_pair(&line, &slots);
4512    let mut out = String::with_capacity(text.len());
4513    // WHERE THE CURRENT LINE'S CONTENT BEGINS, carried rather than re-derived.
4514    //
4515    // M2b's position test used to answer by scanning BACKWARD from the
4516    // candidate to the line's newline, once per candidate - so a line whose
4517    // every character is a candidate paid an O(n) scan n times over, which is
4518    // quadratic behavior on lines dense with candidates.
4519    // The position is a property of the LINE, not of the candidate, so it is
4520    // computed once when a line opens and read in O(1) after that.
4521    let mut content_start = content_position(&line, 0);
4522    for (i, (&raw, &slot)) in raw_chars.iter().zip(&slots).enumerate() {
4523        if let Some(marker) = markers.get(&i) {
4524            out.push_str(marker);
4525        }
4526        if raw == '\n' {
4527            content_start = content_position(&line, i + 1);
4528            out.push(raw);
4529            continue;
4530        }
4531        // TWO FAMILIES, TWO TESTS. M1b asks whether a delimiter of the same
4532        // character stands beside the candidate; M1f and M2b ask whether the
4533        // candidate stands where an ATX heading could open.
4534        let keep = (slot != NO_SLOT).then(|| {
4535            let slot = usize::from(slot);
4536            let ch = carried_character(slot);
4537            if slot == C_POSITIONAL_HASH {
4538                (
4539                    ch,
4540                    opens_an_atx_heading(&line, i, content_start)
4541                        || closes_an_atx_heading(&line, &raw_chars, i, content_start),
4542                )
4543            } else if slot == C_ANGLE {
4544                // §8a M1e, read across nodes (§8d).
4545                let next = line.get(i + 1).copied().unwrap_or('\n');
4546                (
4547                    ch,
4548                    next.is_ascii_alphabetic() || matches!(next, '/' | '!' | '?'),
4549                )
4550            } else if slot == C_AMPERSAND {
4551                let rest: String = line[i + 1..].iter().take(40).collect();
4552                (ch, opens_char_ref(&rest))
4553            } else if slot == C_BANG {
4554                // §8f: a live `[` is the writer's own, never a text carrier.
4555                (ch, raw_chars.get(i + 1) == Some(&'['))
4556            } else if slot == C_SCHEME_COLON {
4557                let slashes = line.get(i + 1) == Some(&'/') && line.get(i + 2) == Some(&'/');
4558                (ch, slashes && scheme_ends_at(i, |k| line.get(k).copied()))
4559            } else if slot == C_WWW_DOT {
4560                let www = i >= 3 && line[i - 3..i] == ['w', 'w', 'w'];
4561                (ch, www && !(i > 3 && line[i - 4].is_ascii_alphanumeric()))
4562            } else if slot == C_EMAIL_AT {
4563                (ch, gfm_email_at(&line, i))
4564            } else {
4565                (ch, adjacent_to_live_delimiter(&line, i, ch) || pairs[i])
4566            }
4567        });
4568
4569        match keep {
4570            Some(('@', true)) => {
4571                // §8i E1: both readers link the address whichever character
4572                // carries a backslash, so the empty comment is what holds it.
4573                out.push_str("<!---->@");
4574            }
4575            Some((ch, true)) => {
4576                out.push('\\');
4577                out.push(ch);
4578            }
4579            Some((ch, false)) => out.push(ch),
4580            None => out.push(raw),
4581        }
4582    }
4583    if let Some(marker) = markers.get(&line.len()) {
4584        out.push_str(marker);
4585    }
4586    out
4587}
4588
4589/// Does GFM's email extension match an address at the `@` on `line[at]` (§8i E1)?
4590///
4591/// A port of carve-php's `gfmEmailAt`, character for character, so the two
4592/// engines answer the shared fixture alike by construction rather than by two
4593/// independent readings of the extension. Read on the EMITTED line, so an
4594/// address a highlighter split across spans is still one form.
4595fn gfm_email_at(line: &[char], at: usize) -> bool {
4596    let mut start = at;
4597    let mut xmpp = false;
4598    while start > 0 {
4599        let ch = line[start - 1];
4600        if ch.is_ascii_alphanumeric() || matches!(ch, '.' | '+' | '-' | '_') {
4601            start -= 1;
4602            continue;
4603        }
4604        if ch == ':' {
4605            let mut took_protocol = false;
4606            for protocol in ["mailto:", "xmpp:"] {
4607                let spelled: Vec<char> = protocol.chars().collect();
4608                if start < spelled.len() || line[start - spelled.len()..start] != spelled[..] {
4609                    continue;
4610                }
4611                let before = start - spelled.len();
4612                if before > 0 && line[before - 1].is_ascii_alphanumeric() {
4613                    continue;
4614                }
4615                xmpp = xmpp || protocol == "xmpp:";
4616                start -= 1;
4617                took_protocol = true;
4618                break;
4619            }
4620            if took_protocol {
4621                continue;
4622            }
4623        }
4624        break;
4625    }
4626    if start == at {
4627        return false;
4628    }
4629    let mut dots = 0usize;
4630    let mut end = at + 1;
4631    while end < line.len() {
4632        let ch = line[end];
4633        if ch.is_ascii_alphanumeric() || ch == '-' || ch == '_' || (xmpp && ch == '/') {
4634            end += 1;
4635            continue;
4636        }
4637        // A second `@` means the run is not one address.
4638        if ch == '@' {
4639            return false;
4640        }
4641        if ch == '.' && line.get(end + 1).is_some_and(char::is_ascii_alphanumeric) {
4642            dots += 1;
4643            end += 1;
4644            continue;
4645        }
4646        break;
4647    }
4648    // A domain with no dot is not matched by either reader, and a trailing `-`
4649    // or `_` ends no label. With no domain at all `line[end - 1]` is the `@`
4650    // itself, which is not alphabetic, so the same test refuses it.
4651    dots > 0 && line[end - 1].is_ascii_alphabetic()
4652}
4653
4654/// Whether the `#` at `index` opens the TRAILING run of a line emitted as a
4655/// heading, which a CommonMark reader takes for the ATX closing sequence and
4656/// drops (§8a M1f, amended in markup-carve/carve#2056).
4657///
4658/// Only the run's FIRST hash: the rest no longer follow a space, so the escape
4659/// on the first is what keeps the whole run. `raw` rather than `line` decides
4660/// that the line IS a heading, because the marker is emitted bare while every
4661/// hash from the document's text arrives as a carrier.
4662fn closes_an_atx_heading(line: &[char], raw: &[char], index: usize, content_start: usize) -> bool {
4663    if index == 0 || !matches!(line.get(index - 1), Some(' ' | '\t')) {
4664        return false;
4665    }
4666    if !emitted_as_a_heading(raw, content_start) {
4667        return false;
4668    }
4669    line[index..]
4670        .iter()
4671        .take_while(|c| **c != '\n')
4672        .all(|c| *c == '#')
4673}
4674
4675/// Whether the line beginning at `content_start` is one this writer emitted as
4676/// an ATX heading: a bare run of one to six hashes and a space.
4677fn emitted_as_a_heading(raw: &[char], content_start: usize) -> bool {
4678    let run = raw[content_start..]
4679        .iter()
4680        .take_while(|c| **c == '#')
4681        .take(7)
4682        .count();
4683    (1..=6).contains(&run) && matches!(raw.get(content_start + run), Some(' '))
4684}
4685
4686/// Whether the `#` at `index` would open an ATX heading (§8a M1f, §8b M2b).
4687fn opens_an_atx_heading(line: &[char], index: usize, content_start: usize) -> bool {
4688    if index != content_start {
4689        return false;
4690    }
4691
4692    let run = line[index..]
4693        .iter()
4694        .take_while(|c| **c == '#')
4695        .take(7)
4696        .count();
4697    if run > 6 {
4698        return false;
4699    }
4700
4701    match line.get(index + run) {
4702        Some(' ' | '\t' | '\n') | None => true,
4703        Some(_) => false,
4704    }
4705}
4706
4707/// Where the CONTENT of the line beginning at `line_start` begins, which is
4708/// after every container prefix the writer put in front of it (PART 11 §8b,
4709/// markup-carve/carve#1332).
4710fn content_position(line: &[char], line_start: usize) -> usize {
4711    let mut at = line_start;
4712    loop {
4713        while line.get(at) == Some(&' ') {
4714            at += 1;
4715        }
4716        match container_prefix_end(line, at) {
4717            Some(end) => at = end,
4718            None => return at,
4719        }
4720    }
4721}
4722
4723/// One container prefix at `at`, and where it ends. See [`content_position`].
4724fn container_prefix_end(line: &[char], at: usize) -> Option<usize> {
4725    let ch = *line.get(at)?;
4726
4727    // A quote marker takes ONE following space, the separator this writer emits.
4728    // A blank quote line is written bare (`>`), so the space is optional.
4729    if ch == '>' {
4730        return Some(if line.get(at + 1) == Some(&' ') {
4731            at + 2
4732        } else {
4733            at + 1
4734        });
4735    }
4736
4737    // A BULLET ENDS AT ITS SEPARATOR, task box included. The box is content:
4738    // a reader takes a `#` after it for text, not a heading opener, so
4739    // reaching past it escaped a hash no reader reads (markup-carve/carve-rs#1674).
4740    if matches!(ch, '-' | '*' | '+') && line.get(at + 1) == Some(&' ') {
4741        return Some(at + 2);
4742    }
4743
4744    // An ordered marker: digits, then the authored delimiter, then the
4745    // separator. The digit run is bounded the way `protect_paragraph_list_markers`
4746    // bounds its own - a number no writer emits is not a marker.
4747    if ch.is_ascii_digit() {
4748        let mut end = at;
4749        while end - at < 9 && line.get(end).is_some_and(char::is_ascii_digit) {
4750            end += 1;
4751        }
4752        if matches!(line.get(end), Some('.' | ')')) && line.get(end + 1) == Some(&' ') {
4753            return Some(end + 2);
4754        }
4755        return None;
4756    }
4757
4758    // A footnote definition's label, which this writer emits as `[^id]: `. An
4759    // abbreviation definition (`*[X]: `) is NOT one: its body is not a container
4760    // and holds no block content for a hash to open.
4761    if ch == '[' && line.get(at + 1) == Some(&'^') {
4762        let mut end = at + 2;
4763        while !matches!(line.get(end), None | Some('\n') | Some(']')) {
4764            end += 1;
4765        }
4766        if line.get(end) == Some(&']')
4767            && line.get(end + 1) == Some(&':')
4768            && line.get(end + 2) == Some(&' ')
4769        {
4770            return Some(end + 3);
4771        }
4772    }
4773
4774    None
4775}
4776
4777fn flatten_heading_text(text: &str) -> String {
4778    // ASCII layout whitespace only. `str::trim` uses `char::is_whitespace`, which
4779    // includes U+00A0 - so a heading whose text began with a NO-BREAK SPACE lost
4780    // it here, on the Markdown target alone, while every other target in this
4781    // engine and both other engines kept it (carve-rs#614). A no-break space is
4782    // CONTENT: the author typed a character, not indentation.
4783    //
4784    // Mid-text was never affected, because only the ends are trimmed; this is
4785    // specifically the leading and trailing position.
4786    let layout = |c: char| c == ' ' || c == '\t' || c == '\r';
4787
4788    text.split('\n')
4789        .map(|part| inline_padding(part, layout).1)
4790        .filter(|part| !part.is_empty())
4791        .collect::<Vec<_>>()
4792        .join(" ")
4793}
4794
4795/// The id this heading gets, with duplicate disambiguation.
4796///
4797/// Mirrors `render::next_heading_id`: an explicit `{#id}` wins verbatim, an auto
4798/// slug takes a `-N` suffix on repeat, and an auto slug never lands on an id an
4799/// explicit one already claims. Called once per heading per pass, in document
4800/// order, so the prepass and the render agree on every id.
4801fn next_heading_id(
4802    heading: &Heading,
4803    counts: &mut std::collections::BTreeMap<String, usize>,
4804    explicit_ids: &HashSet<String>,
4805) -> String {
4806    let explicit = heading.attrs.as_ref().and_then(|attrs| attrs.id.clone());
4807    let has_explicit = explicit.is_some();
4808    let base = explicit.unwrap_or_else(|| slugify(&plain_inlines(&heading.children)));
4809
4810    crate::document_ids::allocate_heading_id(base, has_explicit, counts, |id| {
4811        explicit_ids.contains(id)
4812    })
4813}
4814
4815// Markdown-specific flattening. Node coverage is kept in lockstep with the
4816// core, including `CitationGroup` -> `raw`, so a citation heading's id is
4817// consistent here too.
4818fn plain_inlines(nodes: &[InlineNode]) -> String {
4819    plain_inlines_with(nodes, ' ', " ")
4820}
4821
4822/// `plain_inlines`, spelling the staged no-break space as `nbsp`.
4823fn plain_inlines_with(nodes: &[InlineNode], nbsp: char, hard_break_text: &str) -> String {
4824    let mut out = String::new();
4825    for node in nodes {
4826        match node {
4827            InlineNode::NonBreakingSpace(_) => out.push('\u{00a0}'),
4828            InlineNode::Text(text) => out.push_str(
4829                &text
4830                    .value
4831                    .replace(crate::NBSP_PLACEHOLDER, nbsp.encode_utf8(&mut [0u8; 4])),
4832            ),
4833            // Visible prose, so it feeds this slug exactly as it feeds the core's
4834            // (carve-rs#800). This is the THIRD spelling of one derivation - the
4835            // parse-time index, the HTML renderer and this one - and the reason
4836            // the arm goes in all three at once is that a heading id derived two
4837            // ways has to be one id.
4838            InlineNode::EscapedText(escaped) => out.push_str(&escaped.value),
4839            InlineNode::SmartPunctuation(s) => out.push_str(smart_punctuation_text(s)),
4840            InlineNode::Emphasis(emphasis) => out.push_str(&plain_inlines_with(
4841                &emphasis.children,
4842                nbsp,
4843                hard_break_text,
4844            )),
4845            InlineNode::Span(span) if !span.injected => {
4846                out.push_str(&plain_inlines_with(&span.children, nbsp, hard_break_text))
4847            }
4848            InlineNode::Code(code) => out.push_str(&code.value),
4849            // An inline literal renders as visible prose (§27), so it feeds a
4850            // Markdown heading slug like a code span does.
4851            InlineNode::LiteralInline(lit) => out.push_str(&lit.content),
4852            // Math is verbatim visible text, so it feeds this slug like a code
4853            // span does. The THIRD spelling of the derivation carve#1283 moves;
4854            // the arm goes in all three at once because a heading id derived
4855            // three ways has to be one id.
4856            InlineNode::Math(math) => out.push_str(&math.content),
4857            // A cross-reference contributes NOTHING to the slug, exactly as in
4858            // `render::plain_inlines`. By this point resolution has turned it
4859            // into a Link carrying the target heading's text, so counting it
4860            // would slug `# A </#a>` as `A-A` and every id derived here would
4861            // disagree with the one the core assigned before resolution.
4862            InlineNode::Link(link) if link.from_crossref => {}
4863            InlineNode::Link(link) => {
4864                out.push_str(&plain_inlines_with(&link.children, nbsp, hard_break_text))
4865            }
4866            InlineNode::Ruby(r) => {
4867                out.push_str(&plain_inlines_with(&r.flattened(), nbsp, hard_break_text))
4868            }
4869            InlineNode::Image(image) => out.push_str(&image.alt),
4870            InlineNode::AutoLink(autolink) => out.push_str(&autolink.text),
4871            InlineNode::Extension(extension) => out.push_str(&plain_inlines_with(
4872                &extension.children,
4873                nbsp,
4874                hard_break_text,
4875            )),
4876            InlineNode::CitationGroup(group) => out.push_str(&group.raw),
4877            InlineNode::Abbreviation(abbr) => out.push_str(&abbr.abbr),
4878            InlineNode::Mention(mention) => out.push_str(&mention.user),
4879            InlineNode::Tag(tag) => out.push_str(&tag.name),
4880            InlineNode::CaptionNumber(number) => {
4881                if let Some(number) = number.number {
4882                    out.push_str(&number.to_string());
4883                }
4884            }
4885            InlineNode::SoftBreak(_) => out.push(' '),
4886            InlineNode::HardBreak(_) => out.push_str(hard_break_text),
4887            _ => {}
4888        }
4889    }
4890    out
4891}
4892
4893fn slugify(text: &str) -> String {
4894    // Delegate to the single canonical implementation so HTML, Markdown, and
4895    // the parser's id index never drift apart (or from carve-js / carve-php).
4896    // The Markdown renderer has no Options, so it always uses the case-preserving
4897    // default (lowercase = false), matching the parser's default id index.
4898    crate::parse::slugify_parse(text, crate::extension::HeadingIdOptions::PLAIN)
4899}
4900
4901/// GitHub's heading slugger (github-slugger), which `pandoc -f gfm` follows:
4902/// PART 11 §11 G2 to G5.
4903#[derive(Default)]
4904struct GfmSlugger {
4905    counts: HashMap<String, usize>,
4906}
4907
4908impl GfmSlugger {
4909    fn slug(&mut self, text: &str) -> String {
4910        static DROP: std::sync::OnceLock<regex::Regex> = std::sync::OnceLock::new();
4911        let drop = DROP.get_or_init(|| {
4912            regex::Regex::new(r"[^\p{L}\p{M}\p{N}\p{Pc} \-]").expect("the slug class is valid")
4913        });
4914        let base = drop.replace_all(&text.to_lowercase(), "").replace(' ', "-");
4915        let mut slug = base.clone();
4916        while self.counts.contains_key(&slug) {
4917            let count = self.counts.entry(base.clone()).or_insert(0);
4918            *count += 1;
4919            slug = format!("{base}-{count}");
4920        }
4921        self.counts.insert(slug.clone(), 0);
4922        slug
4923    }
4924}
4925
4926/// §11 G1: the heading's text content as this target writes it, a no-break
4927/// space included as itself.
4928fn gfm_heading_text(nodes: &[InlineNode]) -> String {
4929    use unicode_normalization::UnicodeNormalization;
4930    let text = plain_inlines_with(nodes, '\u{00a0}', "");
4931    text.trim_matches(|c: char| c.is_ascii_whitespace())
4932        .nfc()
4933        .collect()
4934}
4935
4936/// Every heading in document order, and whether this target writes it as a
4937/// heading: one inside a table cell is flattened into the cell.
4938fn walk_headings<F>(blocks: &[BlockNode], depth: usize, written: bool, visit: &mut F)
4939where
4940    F: FnMut(&Heading, bool),
4941{
4942    if depth > MAX_RENDER_DEPTH {
4943        return;
4944    }
4945    let next = depth + 1;
4946    for block in blocks {
4947        match block {
4948            BlockNode::Heading(heading) => visit(heading, written),
4949            BlockNode::BlockQuote(quote) => walk_headings(&quote.children, next, written, visit),
4950            BlockNode::Admonition(admonition) => match list_table_as_table(admonition) {
4951                Some(table) => walk_headings(&[BlockNode::Table(table)], depth, written, visit),
4952                None => walk_headings(&admonition.children, next, written, visit),
4953            },
4954            BlockNode::Directive(directive) => {
4955                walk_headings(&directive.children, next, written, visit)
4956            }
4957            BlockNode::Div(div) => walk_headings(&div.children, next, written, visit),
4958            BlockNode::Section(section) => walk_headings(&section.children, next, written, visit),
4959            BlockNode::LineBlock(lb) => walk_headings(&lb.children, next, written, visit),
4960            BlockNode::List(list) => {
4961                for item in &list.items {
4962                    walk_headings(&item.children, next, written, visit);
4963                }
4964            }
4965            BlockNode::DefinitionList(list) => {
4966                for item in &list.items {
4967                    for definition in &item.definitions {
4968                        walk_headings(definition, next, written, visit);
4969                    }
4970                }
4971            }
4972            BlockNode::Table(table) => {
4973                for row in &table.rows {
4974                    for cell in &row.cells {
4975                        if let Some(blocks) = &cell.blocks {
4976                            walk_headings(blocks, next, false, visit);
4977                        }
4978                    }
4979                }
4980            }
4981            BlockNode::Figure(figure) => {
4982                if let FigureTarget::BlockQuote(quote) = &*figure.target {
4983                    walk_headings(&quote.children, next, written, visit);
4984                }
4985            }
4986            BlockNode::FigureGroup(group) => walk_headings(&group.children, next, written, visit),
4987            BlockNode::ExtensionCarrier(extension) => {
4988                walk_headings(&extension.children, next, written, visit)
4989            }
4990            BlockNode::BlockExtension(extension) => walk_headings(
4991                std::slice::from_ref(extension.fallback.as_ref()),
4992                next,
4993                written,
4994                visit,
4995            ),
4996            _ => {}
4997        }
4998    }
4999}
5000
5001fn is_literal_crossref(text: &str) -> bool {
5002    text.starts_with("</#") && text.ends_with('>') && !text[3..text.len() - 1].contains('>')
5003}
5004
5005fn walk_blocks<F>(blocks: &[BlockNode], depth: usize, visit: &mut F)
5006where
5007    F: FnMut(&BlockNode, Option<&[InlineNode]>),
5008{
5009    if depth > MAX_RENDER_DEPTH {
5010        crate::render_depth::record("markdown");
5011        return;
5012    }
5013    for block in blocks {
5014        visit(block, None);
5015        match block {
5016            BlockNode::Heading(heading) => visit(block, Some(&heading.children)),
5017            BlockNode::Paragraph(paragraph) => visit(block, Some(&paragraph.children)),
5018            BlockNode::BlockQuote(quote) => walk_blocks(&quote.children, depth + 1, visit),
5019            BlockNode::Admonition(admonition) if list_table_as_table(admonition).is_some() => {
5020                if let Some(table) = list_table_as_table(admonition) {
5021                    walk_blocks(&[BlockNode::Table(table)], depth, visit);
5022                }
5023            }
5024            BlockNode::Admonition(admonition) => {
5025                // The title is now rendered, so a crossref link in it must be
5026                // seen by the prepass that collects referenced heading ids.
5027                if let Some(title) = &admonition.title {
5028                    visit(block, Some(title));
5029                }
5030                walk_blocks(&admonition.children, depth + 1, visit);
5031            }
5032            BlockNode::Directive(directive) => {
5033                if let Some(title) = &directive.title {
5034                    visit(block, Some(title));
5035                }
5036                walk_blocks(&directive.children, depth + 1, visit);
5037            }
5038            BlockNode::Div(div) => walk_blocks(&div.children, depth + 1, visit),
5039            BlockNode::Section(section) => walk_blocks(&section.children, depth + 1, visit),
5040            BlockNode::LineBlock(lb) => walk_blocks(&lb.children, depth + 1, visit),
5041            BlockNode::List(list) => {
5042                for item in &list.items {
5043                    walk_blocks(&item.children, depth + 1, visit);
5044                }
5045            }
5046            BlockNode::DefinitionList(list) => {
5047                for item in &list.items {
5048                    for term in &item.terms {
5049                        visit(block, Some(term));
5050                    }
5051                    for definition in &item.definitions {
5052                        walk_blocks(definition, depth + 1, visit);
5053                    }
5054                }
5055            }
5056            BlockNode::Table(table) => {
5057                if let Some(caption) = &table.caption {
5058                    visit(block, Some(caption));
5059                }
5060                for row in &table.rows {
5061                    for cell in &row.cells {
5062                        visit(block, Some(&cell.children));
5063                        if let Some(blocks) = &cell.blocks {
5064                            walk_blocks(blocks, depth + 1, visit);
5065                        }
5066                    }
5067                }
5068            }
5069            BlockNode::Figure(figure) => {
5070                visit(block, Some(&figure.caption));
5071                match &*figure.target {
5072                    FigureTarget::BlockQuote(quote) => {
5073                        walk_blocks(&quote.children, depth + 1, visit)
5074                    }
5075                    FigureTarget::Table(table) => {
5076                        walk_blocks(&[BlockNode::Table(table.clone())], depth + 1, visit);
5077                    }
5078                    FigureTarget::Paragraph(p) => {
5079                        walk_blocks(&[BlockNode::Paragraph(p.clone())], depth + 1, visit);
5080                    }
5081                    FigureTarget::Image(_) | FigureTarget::CodeBlock(_) => {}
5082                }
5083            }
5084            BlockNode::FigureGroup(group) => {
5085                if let Some(caption) = &group.caption {
5086                    visit(block, Some(caption));
5087                }
5088                walk_blocks(&group.children, depth + 1, visit);
5089            }
5090            BlockNode::ExtensionCarrier(extension) => {
5091                walk_blocks(&extension.children, depth + 1, visit)
5092            }
5093            _ => {}
5094        }
5095    }
5096}