merman_render/

class.rs

use crate::entities::decode_entities_minimal;
use crate::model::{
    Bounds, ClassDiagramV2Layout, ClassNodeRowMetrics, LayoutCluster, LayoutEdge, LayoutLabel,
    LayoutNode, LayoutPoint,
};
use crate::text::{TextMeasurer, TextStyle, WrapMode};
use crate::{Error, Result};
use dugong::graphlib::{Graph, GraphOptions};
use dugong::{EdgeLabel, GraphLabel, LabelPos, NodeLabel, RankDir};
use indexmap::IndexMap;
use rustc_hash::FxHashMap;
use serde_json::Value;
use std::collections::{BTreeMap, HashMap, HashSet};
use std::sync::Arc;

type ClassDiagramModel = merman_core::models::class_diagram::ClassDiagram;
type ClassNode = merman_core::models::class_diagram::ClassNode;

fn json_f64(v: &Value) -> Option<f64> {
    v.as_f64()
        .or_else(|| v.as_i64().map(|n| n as f64))
        .or_else(|| v.as_u64().map(|n| n as f64))
}

fn config_f64(cfg: &Value, path: &[&str]) -> Option<f64> {
    let mut cur = cfg;
    for key in path {
        cur = cur.get(*key)?;
    }
    json_f64(cur)
}

fn config_bool(cfg: &Value, path: &[&str]) -> Option<bool> {
    let mut cur = cfg;
    for key in path {
        cur = cur.get(*key)?;
    }
    cur.as_bool()
}

fn config_string(cfg: &Value, path: &[&str]) -> Option<String> {
    let mut cur = cfg;
    for key in path {
        cur = cur.get(*key)?;
    }
    cur.as_str().map(|s| s.to_string())
}

fn normalize_dir(direction: &str) -> String {
    match direction.trim().to_uppercase().as_str() {
        "TB" | "TD" => "TB".to_string(),
        "BT" => "BT".to_string(),
        "LR" => "LR".to_string(),
        "RL" => "RL".to_string(),
        other => other.to_string(),
    }
}

fn rank_dir_from(direction: &str) -> RankDir {
    match normalize_dir(direction).as_str() {
        "TB" => RankDir::TB,
        "BT" => RankDir::BT,
        "LR" => RankDir::LR,
        "RL" => RankDir::RL,
        _ => RankDir::TB,
    }
}

type Rect = merman_core::geom::Box2;

struct PreparedGraph {
    graph: Graph<NodeLabel, EdgeLabel, GraphLabel>,
    extracted: BTreeMap<String, PreparedGraph>,
    prefer_dagreish_disconnected: bool,
}

fn extract_descendants(
    graph: &Graph<NodeLabel, EdgeLabel, GraphLabel>,
    id: &str,
    out: &mut Vec<String>,
) {
    for child in graph.children(id) {
        out.push(child.to_string());
        extract_descendants(graph, child, out);
    }
}

fn is_descendant(descendants: &HashMap<String, HashSet<String>>, id: &str, ancestor: &str) -> bool {
    descendants
        .get(ancestor)
        .is_some_and(|set| set.contains(id))
}

fn prepare_graph(
    mut graph: Graph<NodeLabel, EdgeLabel, GraphLabel>,
    depth: usize,
    prefer_dagreish_disconnected: bool,
) -> Result<PreparedGraph> {
    if depth > 10 {
        return Ok(PreparedGraph {
            graph,
            extracted: BTreeMap::new(),
            prefer_dagreish_disconnected,
        });
    }

    // Mermaid's dagre-wrapper performs a pre-pass that extracts clusters *without* external
    // connections into their own subgraphs, toggles their rankdir (TB <-> LR), and renders them
    // recursively to obtain concrete cluster geometry before laying out the parent graph.
    //
    // Reference: Mermaid@11.12.2 `mermaid-graphlib.js` extractor + `recursiveRender`:
    // - eligible cluster: has children, and no edge crosses its descendant boundary
    // - extracted subgraph gets `rankdir = parent.rankdir === 'TB' ? 'LR' : 'TB'`
    // - subgraph rank spacing uses `ranksep = parent.ranksep + 25`
    // - margins are fixed at 8

    let cluster_ids: Vec<String> = graph
        .node_ids()
        .into_iter()
        .filter(|id| !graph.children(id).is_empty())
        .collect();

    let mut descendants: HashMap<String, HashSet<String>> = HashMap::new();
    for id in &cluster_ids {
        let mut vec: Vec<String> = Vec::new();
        extract_descendants(&graph, id, &mut vec);
        descendants.insert(id.clone(), vec.into_iter().collect());
    }

    let mut external: HashMap<String, bool> =
        cluster_ids.iter().map(|id| (id.clone(), false)).collect();
    for id in &cluster_ids {
        for e in graph.edge_keys() {
            // Mermaid's `edgeInCluster` treats edges incident on the cluster node itself as
            // non-descendant edges. Class diagrams do not normally connect edges to namespaces,
            // but keep the guard to mirror upstream behavior.
            if e.v == *id || e.w == *id {
                continue;
            }
            let d1 = is_descendant(&descendants, &e.v, id);
            let d2 = is_descendant(&descendants, &e.w, id);
            if d1 ^ d2 {
                external.insert(id.clone(), true);
                break;
            }
        }
    }

    let mut extracted: BTreeMap<String, PreparedGraph> = BTreeMap::new();
    let candidate_clusters: Vec<String> = graph
        .node_ids()
        .into_iter()
        .filter(|id| !graph.children(id).is_empty() && !external.get(id).copied().unwrap_or(false))
        .collect();

    for cluster_id in candidate_clusters {
        if graph.children(&cluster_id).is_empty() {
            continue;
        }
        let parent_dir = graph.graph().rankdir;
        let dir = if parent_dir == RankDir::TB {
            RankDir::LR
        } else {
            RankDir::TB
        };

        let nodesep = graph.graph().nodesep;
        let ranksep = graph.graph().ranksep;

        let mut subgraph = extract_cluster_graph(&cluster_id, &mut graph)?;
        subgraph.graph_mut().rankdir = dir;
        subgraph.graph_mut().nodesep = nodesep;
        subgraph.graph_mut().ranksep = ranksep + 25.0;
        subgraph.graph_mut().marginx = 8.0;
        subgraph.graph_mut().marginy = 8.0;

        let prepared = prepare_graph(subgraph, depth + 1, prefer_dagreish_disconnected)?;
        extracted.insert(cluster_id, prepared);
    }

    Ok(PreparedGraph {
        graph,
        extracted,
        prefer_dagreish_disconnected,
    })
}

fn extract_cluster_graph(
    cluster_id: &str,
    graph: &mut Graph<NodeLabel, EdgeLabel, GraphLabel>,
) -> Result<Graph<NodeLabel, EdgeLabel, GraphLabel>> {
    if graph.children(cluster_id).is_empty() {
        return Err(Error::InvalidModel {
            message: format!("cluster has no children: {cluster_id}"),
        });
    }

    let mut descendants: Vec<String> = Vec::new();
    extract_descendants(graph, cluster_id, &mut descendants);
    descendants.sort();
    descendants.dedup();

    let moved_set: HashSet<String> = descendants.iter().cloned().collect();

    let mut sub = Graph::<NodeLabel, EdgeLabel, GraphLabel>::new(GraphOptions {
        directed: true,
        multigraph: true,
        compound: true,
    });

    // Preserve parent graph settings as a base.
    sub.set_graph(graph.graph().clone());

    for id in &descendants {
        let Some(label) = graph.node(id).cloned() else {
            continue;
        };
        sub.set_node(id.clone(), label);
    }

    for key in graph.edge_keys() {
        if moved_set.contains(&key.v) && moved_set.contains(&key.w) {
            if let Some(label) = graph.edge_by_key(&key).cloned() {
                sub.set_edge_named(key.v.clone(), key.w.clone(), key.name.clone(), Some(label));
            }
        }
    }

    for id in &descendants {
        let Some(parent) = graph.parent(id) else {
            continue;
        };
        if moved_set.contains(parent) {
            sub.set_parent(id.clone(), parent.to_string());
        }
    }

    for id in &descendants {
        let _ = graph.remove_node(id);
    }

    Ok(sub)
}

#[derive(Debug, Clone)]
struct EdgeTerminalMetrics {
    start_left: Option<(f64, f64)>,
    start_right: Option<(f64, f64)>,
    end_left: Option<(f64, f64)>,
    end_right: Option<(f64, f64)>,
    start_marker: f64,
    end_marker: f64,
}

fn edge_terminal_metrics_from_extras(e: &EdgeLabel) -> EdgeTerminalMetrics {
    let get_pair = |key: &str| -> Option<(f64, f64)> {
        let obj = e.extras.get(key)?;
        let w = obj.get("width").and_then(|v| v.as_f64()).unwrap_or(0.0);
        let h = obj.get("height").and_then(|v| v.as_f64()).unwrap_or(0.0);
        if w > 0.0 && h > 0.0 {
            Some((w, h))
        } else {
            None
        }
    };
    let start_marker = e
        .extras
        .get("startMarker")
        .and_then(|v| v.as_f64())
        .unwrap_or(0.0);
    let end_marker = e
        .extras
        .get("endMarker")
        .and_then(|v| v.as_f64())
        .unwrap_or(0.0);
    EdgeTerminalMetrics {
        start_left: get_pair("startLeft"),
        start_right: get_pair("startRight"),
        end_left: get_pair("endLeft"),
        end_right: get_pair("endRight"),
        start_marker,
        end_marker,
    }
}

#[derive(Debug, Clone)]
struct LayoutFragments {
    nodes: IndexMap<String, LayoutNode>,
    edges: Vec<(LayoutEdge, Option<EdgeTerminalMetrics>)>,
}

fn round_number(num: f64, precision: i32) -> f64 {
    if !num.is_finite() {
        return 0.0;
    }
    let factor = 10_f64.powi(precision);
    (num * factor).round() / factor
}

fn distance(a: &LayoutPoint, b: Option<&LayoutPoint>) -> f64 {
    let Some(b) = b else {
        return 0.0;
    };
    let dx = a.x - b.x;
    let dy = a.y - b.y;
    (dx * dx + dy * dy).sqrt()
}

fn calculate_point(points: &[LayoutPoint], distance_to_traverse: f64) -> Option<LayoutPoint> {
    if points.is_empty() {
        return None;
    }
    let mut prev: Option<&LayoutPoint> = None;
    let mut remaining = distance_to_traverse.max(0.0);
    for p in points {
        if let Some(prev_p) = prev {
            let vector_distance = distance(p, Some(prev_p));
            if vector_distance == 0.0 {
                return Some(prev_p.clone());
            }
            if vector_distance < remaining {
                remaining -= vector_distance;
            } else {
                let ratio = remaining / vector_distance;
                if ratio <= 0.0 {
                    return Some(prev_p.clone());
                }
                if ratio >= 1.0 {
                    return Some(p.clone());
                }
                return Some(LayoutPoint {
                    x: round_number((1.0 - ratio) * prev_p.x + ratio * p.x, 5),
                    y: round_number((1.0 - ratio) * prev_p.y + ratio * p.y, 5),
                });
            }
        }
        prev = Some(p);
    }
    None
}

#[derive(Debug, Clone, Copy)]
enum TerminalPos {
    StartLeft,
    StartRight,
    EndLeft,
    EndRight,
}

fn point_inside_rect(rect: Rect, x: f64, y: f64, eps: f64) -> bool {
    x > rect.min_x() + eps
        && x < rect.max_x() - eps
        && y > rect.min_y() + eps
        && y < rect.max_y() - eps
}

fn nudge_point_outside_rect(mut x: f64, mut y: f64, rect: Rect) -> (f64, f64) {
    let eps = 0.01;
    if !point_inside_rect(rect, x, y, eps) {
        return (x, y);
    }

    let (cx, cy) = rect.center();
    let mut dx = x - cx;
    let mut dy = y - cy;
    let len = (dx * dx + dy * dy).sqrt();
    if len < 1e-9 {
        dx = 1.0;
        dy = 0.0;
    } else {
        dx /= len;
        dy /= len;
    }

    let mut t_exit = f64::INFINITY;
    if dx > 1e-9 {
        t_exit = t_exit.min((rect.max_x() - x) / dx);
    } else if dx < -1e-9 {
        t_exit = t_exit.min((rect.min_x() - x) / dx);
    }
    if dy > 1e-9 {
        t_exit = t_exit.min((rect.max_y() - y) / dy);
    } else if dy < -1e-9 {
        t_exit = t_exit.min((rect.min_y() - y) / dy);
    }

    if t_exit.is_finite() && t_exit >= 0.0 {
        let margin = 0.5;
        x += dx * (t_exit + margin);
        y += dy * (t_exit + margin);
    }

    (x, y)
}

fn calc_terminal_label_position(
    terminal_marker_size: f64,
    position: TerminalPos,
    points: &[LayoutPoint],
) -> Option<(f64, f64)> {
    if points.len() < 2 {
        return None;
    }

    let mut pts = points.to_vec();
    match position {
        TerminalPos::StartLeft | TerminalPos::StartRight => {}
        TerminalPos::EndLeft | TerminalPos::EndRight => pts.reverse(),
    }

    let distance_to_cardinality_point = 25.0 + terminal_marker_size;
    let center = calculate_point(&pts, distance_to_cardinality_point)?;
    let d = 10.0 + terminal_marker_size * 0.5;
    let angle = (pts[0].y - center.y).atan2(pts[0].x - center.x);

    let (x, y) = match position {
        TerminalPos::StartLeft => {
            let a = angle + std::f64::consts::PI;
            (
                a.sin() * d + (pts[0].x + center.x) / 2.0,
                -a.cos() * d + (pts[0].y + center.y) / 2.0,
            )
        }
        TerminalPos::StartRight => (
            angle.sin() * d + (pts[0].x + center.x) / 2.0,
            -angle.cos() * d + (pts[0].y + center.y) / 2.0,
        ),
        TerminalPos::EndLeft => (
            angle.sin() * d + (pts[0].x + center.x) / 2.0 - 5.0,
            -angle.cos() * d + (pts[0].y + center.y) / 2.0 - 5.0,
        ),
        TerminalPos::EndRight => {
            let a = angle - std::f64::consts::PI;
            (
                a.sin() * d + (pts[0].x + center.x) / 2.0 - 5.0,
                -a.cos() * d + (pts[0].y + center.y) / 2.0 - 5.0,
            )
        }
    };
    Some((x, y))
}

fn intersect_segment_with_rect(
    p0: &LayoutPoint,
    p1: &LayoutPoint,
    rect: Rect,
) -> Option<LayoutPoint> {
    let dx = p1.x - p0.x;
    let dy = p1.y - p0.y;
    if dx == 0.0 && dy == 0.0 {
        return None;
    }

    let mut candidates: Vec<(f64, LayoutPoint)> = Vec::new();
    let eps = 1e-9;
    let min_x = rect.min_x();
    let max_x = rect.max_x();
    let min_y = rect.min_y();
    let max_y = rect.max_y();

    if dx.abs() > eps {
        for x_edge in [min_x, max_x] {
            let t = (x_edge - p0.x) / dx;
            if t < -eps || t > 1.0 + eps {
                continue;
            }
            let y = p0.y + t * dy;
            if y + eps >= min_y && y <= max_y + eps {
                candidates.push((t, LayoutPoint { x: x_edge, y }));
            }
        }
    }

    if dy.abs() > eps {
        for y_edge in [min_y, max_y] {
            let t = (y_edge - p0.y) / dy;
            if t < -eps || t > 1.0 + eps {
                continue;
            }
            let x = p0.x + t * dx;
            if x + eps >= min_x && x <= max_x + eps {
                candidates.push((t, LayoutPoint { x, y: y_edge }));
            }
        }
    }

    candidates.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap_or(std::cmp::Ordering::Equal));
    candidates
        .into_iter()
        .find(|(t, _)| *t >= 0.0)
        .map(|(_, p)| p)
}

fn terminal_path_for_edge(
    points: &[LayoutPoint],
    from_rect: Rect,
    to_rect: Rect,
) -> Vec<LayoutPoint> {
    if points.len() < 2 {
        return points.to_vec();
    }
    let mut out = points.to_vec();

    if let Some(p) = intersect_segment_with_rect(&out[0], &out[1], from_rect) {
        out[0] = p;
    }
    let last = out.len() - 1;
    if let Some(p) = intersect_segment_with_rect(&out[last], &out[last - 1], to_rect) {
        out[last] = p;
    }

    out
}

fn layout_prepared(
    prepared: &mut PreparedGraph,
    node_label_metrics_by_id: &HashMap<String, (f64, f64)>,
) -> Result<(LayoutFragments, Rect)> {
    let mut fragments = LayoutFragments {
        nodes: IndexMap::new(),
        edges: Vec::new(),
    };

    let extracted_ids: Vec<String> = prepared.extracted.keys().cloned().collect();
    let mut extracted_fragments: BTreeMap<String, (LayoutFragments, Rect)> = BTreeMap::new();
    for id in extracted_ids {
        let sub = prepared.extracted.get_mut(&id).expect("exists");
        let (sub_frag, sub_bounds) = layout_prepared(sub, node_label_metrics_by_id)?;

        // Mermaid sizes extracted cluster placeholders using the rendered SVG bbox of the
        // recursively rendered cluster (`updateNodeBounds`). That bbox includes Dagre's implicit
        // "cluster padding" around the laid out content. In Dagre, this padding is effectively
        // `ranksep` (after `makeSpaceForEdgeLabels`), split across both sides.
        //
        // Our headless pipeline does not render extracted clusters as a separate SVG subtree, so
        // inflate the computed bounds to match the padding that Mermaid's renderer bakes into the
        // placeholder node size.
        let pad = sub.graph.graph().ranksep.max(0.0);
        let sub_bounds = Rect::from_min_max(
            sub_bounds.min_x() - pad,
            sub_bounds.min_y() - pad,
            sub_bounds.max_x() + pad,
            sub_bounds.max_y() + pad,
        );

        extracted_fragments.insert(id, (sub_frag, sub_bounds));
    }

    for (id, (_sub_frag, bounds)) in &extracted_fragments {
        let Some(n) = prepared.graph.node_mut(id) else {
            return Err(Error::InvalidModel {
                message: format!("missing cluster placeholder node: {id}"),
            });
        };
        n.width = bounds.width().max(1.0);
        n.height = bounds.height().max(1.0);
    }

    // Mermaid's dagre wrapper always sets `compound: true`, and Dagre's ranker expects a connected
    // graph. `dugong::layout_dagreish` mirrors Dagre's full pipeline (including `nestingGraph`)
    // and should be used for class diagrams even when there are no explicit clusters.
    dugong::layout_dagreish(&mut prepared.graph);

    // Mermaid does not render Dagre's internal dummy nodes/edges (border nodes, edge label nodes,
    // nesting artifacts). Filter them out before computing bounds and before merging extracted
    // layouts back into the parent.
    let mut dummy_nodes: HashSet<String> = HashSet::new();
    for id in prepared.graph.node_ids() {
        let Some(n) = prepared.graph.node(&id) else {
            continue;
        };
        if n.dummy.is_some() {
            dummy_nodes.insert(id);
            continue;
        }
        let is_cluster =
            !prepared.graph.children(&id).is_empty() || prepared.extracted.contains_key(&id);
        let (label_width, label_height) = node_label_metrics_by_id
            .get(id.as_str())
            .copied()
            .map(|(w, h)| (Some(w), Some(h)))
            .unwrap_or((None, None));
        fragments.nodes.insert(
            id.clone(),
            LayoutNode {
                id: id.clone(),
                x: n.x.unwrap_or(0.0),
                y: n.y.unwrap_or(0.0),
                width: n.width,
                height: n.height,
                is_cluster,
                label_width,
                label_height,
            },
        );
    }

    for key in prepared.graph.edge_keys() {
        let Some(e) = prepared.graph.edge_by_key(&key) else {
            continue;
        };
        if e.nesting_edge {
            continue;
        }
        if dummy_nodes.contains(&key.v) || dummy_nodes.contains(&key.w) {
            continue;
        }
        if !fragments.nodes.contains_key(&key.v) || !fragments.nodes.contains_key(&key.w) {
            continue;
        }
        let id = key
            .name
            .clone()
            .unwrap_or_else(|| format!("edge:{}:{}", key.v, key.w));

        let label = if e.width > 0.0 && e.height > 0.0 {
            Some(LayoutLabel {
                x: e.x.unwrap_or(0.0),
                y: e.y.unwrap_or(0.0),
                width: e.width,
                height: e.height,
            })
        } else {
            None
        };

        let points = e
            .points
            .iter()
            .map(|p| LayoutPoint { x: p.x, y: p.y })
            .collect::<Vec<_>>();

        let edge = LayoutEdge {
            id,
            from: key.v.clone(),
            to: key.w.clone(),
            from_cluster: None,
            to_cluster: None,
            points,
            label,
            start_label_left: None,
            start_label_right: None,
            end_label_left: None,
            end_label_right: None,
            start_marker: None,
            end_marker: None,
            stroke_dasharray: None,
        };

        let terminals = edge_terminal_metrics_from_extras(e);
        let has_terminals = terminals.start_left.is_some()
            || terminals.start_right.is_some()
            || terminals.end_left.is_some()
            || terminals.end_right.is_some();
        let terminal_meta = if has_terminals { Some(terminals) } else { None };

        fragments.edges.push((edge, terminal_meta));
    }

    for (cluster_id, (mut sub_frag, sub_bounds)) in extracted_fragments {
        let Some(cluster_node) = fragments.nodes.get(&cluster_id).cloned() else {
            return Err(Error::InvalidModel {
                message: format!("missing cluster placeholder layout: {cluster_id}"),
            });
        };
        let (sub_cx, sub_cy) = sub_bounds.center();
        let dx = cluster_node.x - sub_cx;
        let dy = cluster_node.y - sub_cy;

        for n in sub_frag.nodes.values_mut() {
            n.x += dx;
            n.y += dy;
        }
        for (e, _t) in &mut sub_frag.edges {
            for p in &mut e.points {
                p.x += dx;
                p.y += dy;
            }
            if let Some(l) = e.label.as_mut() {
                l.x += dx;
                l.y += dy;
            }
        }

        // The extracted subgraph includes its own copy of the cluster root node so bounds match
        // Mermaid's `updateNodeBounds(...)`. Do not merge that node back into the parent layout,
        // otherwise we'd overwrite the placeholder position computed by the parent graph layout.
        let _ = sub_frag.nodes.swap_remove(&cluster_id);

        fragments.nodes.extend(sub_frag.nodes);
        fragments.edges.extend(sub_frag.edges);
    }

    let mut points: Vec<(f64, f64)> = Vec::new();
    for n in fragments.nodes.values() {
        let r = Rect::from_center(n.x, n.y, n.width, n.height);
        points.push((r.min_x(), r.min_y()));
        points.push((r.max_x(), r.max_y()));
    }
    for (e, _t) in &fragments.edges {
        for p in &e.points {
            points.push((p.x, p.y));
        }
        if let Some(l) = &e.label {
            let r = Rect::from_center(l.x, l.y, l.width, l.height);
            points.push((r.min_x(), r.min_y()));
            points.push((r.max_x(), r.max_y()));
        }
    }
    let bounds = Bounds::from_points(points)
        .map(|b| Rect::from_min_max(b.min_x, b.min_y, b.max_x, b.max_y))
        .unwrap_or_else(|| Rect::from_min_max(0.0, 0.0, 0.0, 0.0));

    Ok((fragments, bounds))
}

fn class_text_style(effective_config: &Value) -> TextStyle {
    // Mermaid defaults to `"trebuchet ms", verdana, arial, sans-serif`. Class diagram labels are
    // rendered via HTML `<foreignObject>` and inherit the global font family.
    let font_family = config_string(effective_config, &["fontFamily"])
        .or_else(|| config_string(effective_config, &["themeVariables", "fontFamily"]))
        .or_else(|| Some("\"trebuchet ms\", verdana, arial, sans-serif".to_string()));
    // Mermaid class diagram node labels inherit the global `fontSize` (via the root `#id{font-size}` rule)
    // and render via HTML labels (`foreignObject`). Prefer the global value for sizing/layout parity.
    let font_size = config_f64(effective_config, &["fontSize"])
        .or_else(|| config_f64(effective_config, &["class", "fontSize"]))
        .unwrap_or(16.0)
        .max(1.0);
    TextStyle {
        font_family,
        font_size,
        font_weight: None,
    }
}

fn class_box_dimensions(
    node: &ClassNode,
    measurer: &dyn TextMeasurer,
    text_style: &TextStyle,
    wrap_mode: WrapMode,
    padding: f64,
    hide_empty_members_box: bool,
    capture_row_metrics: bool,
) -> (f64, f64, Option<ClassNodeRowMetrics>) {
    // Mermaid class nodes are sized by rendering the label groups (`textHelper(...)`) and taking
    // the resulting SVG bbox (`getBBox()`), then expanding by class padding (see upstream:
    // `rendering-elements/shapes/classBox.ts` + `diagrams/class/shapeUtil.ts`).
    //
    // Emulate that sizing logic deterministically using the same text measurer.
    let use_html_labels = matches!(wrap_mode, WrapMode::HtmlLike);
    let padding = padding.max(0.0);
    let gap = padding;
    let text_padding = if use_html_labels { 0.0 } else { 3.0 };

    fn measure_label(
        measurer: &dyn TextMeasurer,
        text: &str,
        style: &TextStyle,
        wrap_mode: WrapMode,
    ) -> crate::text::TextMetrics {
        // Mermaid class diagram text uses `createText(..., { classes: 'markdown-node-label' })`,
        // which applies Markdown formatting for both SVG-label and HTML-label modes.
        //
        // The common case is plain text; keep the fast path for labels that do not appear to use
        // Markdown markers.
        if text.contains('*') || text.contains('_') || text.contains('`') {
            crate::text::measure_markdown_with_flowchart_bold_deltas(
                measurer, text, style, None, wrap_mode,
            )
        } else {
            measurer.measure_wrapped(text, style, None, wrap_mode)
        }
    }

    fn label_rect(m: crate::text::TextMetrics, y_offset: f64) -> Option<Rect> {
        if !(m.width.is_finite() && m.height.is_finite()) {
            return None;
        }
        let w = m.width.max(0.0);
        let h = m.height.max(0.0);
        if w <= 0.0 || h <= 0.0 {
            return None;
        }
        let lines = m.line_count.max(1) as f64;
        let y = y_offset - (h / (2.0 * lines));
        Some(Rect::from_min_max(0.0, y, w, y + h))
    }

    // Annotation group: Mermaid only renders the first annotation.
    let mut annotation_rect: Option<Rect> = None;
    let mut annotation_group_height = 0.0;
    if let Some(a) = node.annotations.first() {
        let t = format!("\u{00AB}{}\u{00BB}", decode_entities_minimal(a.trim()));
        let m = measure_label(measurer, &t, text_style, wrap_mode);
        annotation_rect = label_rect(m, 0.0);
        if let Some(r) = annotation_rect {
            annotation_group_height = r.height().max(0.0);
        }
    }

    // Title label group (bold).
    let mut title_text = decode_entities_minimal(&node.text);
    if !use_html_labels && title_text.starts_with('\\') {
        title_text = title_text.trim_start_matches('\\').to_string();
    }
    // Mermaid renders class titles as bold (`font-weight: bolder`) and sizes boxes via SVG bbox.
    // The vendored text measurer does not model bold glyph widths, so apply the same flowchart
    // bold deltas used for Markdown `<strong>` spans.
    let title_md = format!("**{title_text}**");
    let title_metrics = crate::text::measure_markdown_with_flowchart_bold_deltas(
        measurer, &title_md, text_style, None, wrap_mode,
    );
    let title_rect = label_rect(title_metrics, 0.0);
    let title_group_height = title_rect.map(|r| r.height()).unwrap_or(0.0);

    // Members group.
    let mut members_rect: Option<Rect> = None;
    let mut members_metrics_out: Option<Vec<crate::text::TextMetrics>> =
        capture_row_metrics.then(|| Vec::with_capacity(node.members.len()));
    {
        let mut y_offset = 0.0;
        for m in &node.members {
            let mut t = decode_entities_minimal(m.display_text.trim());
            if !use_html_labels && t.starts_with('\\') {
                t = t.trim_start_matches('\\').to_string();
            }
            let metrics = measure_label(measurer, &t, text_style, wrap_mode);
            if let Some(out) = members_metrics_out.as_mut() {
                out.push(metrics);
            }
            if let Some(r) = label_rect(metrics, y_offset) {
                if let Some(ref mut cur) = members_rect {
                    cur.union(r);
                } else {
                    members_rect = Some(r);
                }
            }
            y_offset += metrics.height.max(0.0) + text_padding;
        }
    }
    let mut members_group_height = members_rect.map(|r| r.height()).unwrap_or(0.0);
    if members_group_height <= 0.0 {
        // Mermaid reserves half a gap when the members group is empty.
        members_group_height = (gap / 2.0).max(0.0);
    }

    // Methods group.
    let mut methods_rect: Option<Rect> = None;
    let mut methods_metrics_out: Option<Vec<crate::text::TextMetrics>> =
        capture_row_metrics.then(|| Vec::with_capacity(node.methods.len()));
    {
        let mut y_offset = 0.0;
        for m in &node.methods {
            let mut t = decode_entities_minimal(m.display_text.trim());
            if !use_html_labels && t.starts_with('\\') {
                t = t.trim_start_matches('\\').to_string();
            }
            let metrics = measure_label(measurer, &t, text_style, wrap_mode);
            if let Some(out) = methods_metrics_out.as_mut() {
                out.push(metrics);
            }
            if let Some(r) = label_rect(metrics, y_offset) {
                if let Some(ref mut cur) = methods_rect {
                    cur.union(r);
                } else {
                    methods_rect = Some(r);
                }
            }
            y_offset += metrics.height.max(0.0) + text_padding;
        }
    }

    // Combine into the bbox returned by `textHelper(...)`.
    let mut bbox_opt: Option<Rect> = None;

    // annotation-group: centered horizontally (`translate(-w/2, 0)`).
    if let Some(mut r) = annotation_rect {
        let w = r.width();
        r.translate(-w / 2.0, 0.0);
        bbox_opt = Some(if let Some(mut cur) = bbox_opt {
            cur.union(r);
            cur
        } else {
            r
        });
    }

    // label-group: centered and shifted down by annotation height.
    if let Some(mut r) = title_rect {
        let w = r.width();
        r.translate(-w / 2.0, annotation_group_height);
        bbox_opt = Some(if let Some(mut cur) = bbox_opt {
            cur.union(r);
            cur
        } else {
            r
        });
    }

    // members-group: left-aligned, shifted down by label height + gap*2.
    if let Some(mut r) = members_rect {
        let dy = annotation_group_height + title_group_height + gap * 2.0;
        r.translate(0.0, dy);
        bbox_opt = Some(if let Some(mut cur) = bbox_opt {
            cur.union(r);
            cur
        } else {
            r
        });
    }

    // methods-group: left-aligned, shifted down by label height + members height + gap*4.
    if let Some(mut r) = methods_rect {
        let dy = annotation_group_height + title_group_height + (members_group_height + gap * 4.0);
        r.translate(0.0, dy);
        bbox_opt = Some(if let Some(mut cur) = bbox_opt {
            cur.union(r);
            cur
        } else {
            r
        });
    }

    let bbox = bbox_opt.unwrap_or_else(|| Rect::from_min_max(0.0, 0.0, 0.0, 0.0));
    let w = bbox.width().max(0.0);
    let mut h = bbox.height().max(0.0);

    // Mermaid adjusts bbox height depending on which compartments exist.
    if node.members.is_empty() && node.methods.is_empty() {
        h += gap;
    } else if !node.members.is_empty() && node.methods.is_empty() {
        h += gap * 2.0;
    }

    let render_extra_box =
        node.members.is_empty() && node.methods.is_empty() && !hide_empty_members_box;

    // The Dagre node bounds come from the rectangle passed to `updateNodeBounds`.
    let mut rect_w = w + 2.0 * padding;
    let mut rect_h = h + 2.0 * padding;
    if render_extra_box {
        rect_h += padding * 2.0;
    } else if node.members.is_empty() && node.methods.is_empty() {
        rect_h -= padding;
    }

    if node.type_param == "group" {
        rect_w = rect_w.max(500.0);
    }

    let row_metrics = capture_row_metrics.then(|| ClassNodeRowMetrics {
        members: members_metrics_out.unwrap_or_default(),
        methods: methods_metrics_out.unwrap_or_default(),
    });

    (rect_w.max(1.0), rect_h.max(1.0), row_metrics)
}

fn note_dimensions(
    text: &str,
    measurer: &dyn TextMeasurer,
    text_style: &TextStyle,
    wrap_mode: WrapMode,
    padding: f64,
) -> (f64, f64, crate::text::TextMetrics) {
    let p = padding.max(0.0);
    let label = decode_entities_minimal(text);
    let m = measurer.measure_wrapped(&label, text_style, None, wrap_mode);
    (m.width + p, m.height + p, m)
}

fn label_metrics(
    text: &str,
    measurer: &dyn TextMeasurer,
    text_style: &TextStyle,
    wrap_mode: WrapMode,
) -> (f64, f64) {
    if text.trim().is_empty() {
        return (0.0, 0.0);
    }
    let t = decode_entities_minimal(text);
    let m = measurer.measure_wrapped(&t, text_style, None, wrap_mode);
    (m.width.max(0.0), m.height.max(0.0))
}

fn set_extras_label_metrics(extras: &mut BTreeMap<String, Value>, key: &str, w: f64, h: f64) {
    let obj = Value::Object(
        [
            ("width".to_string(), Value::from(w)),
            ("height".to_string(), Value::from(h)),
        ]
        .into_iter()
        .collect(),
    );
    extras.insert(key.to_string(), obj);
}

pub fn layout_class_diagram_v2(
    semantic: &Value,
    effective_config: &Value,
    measurer: &dyn TextMeasurer,
) -> Result<ClassDiagramV2Layout> {
    let model: ClassDiagramModel = crate::json::from_value_ref(semantic)?;
    layout_class_diagram_v2_typed(&model, effective_config, measurer)
}

pub fn layout_class_diagram_v2_typed(
    model: &ClassDiagramModel,
    effective_config: &Value,
    measurer: &dyn TextMeasurer,
) -> Result<ClassDiagramV2Layout> {
    let diagram_dir = rank_dir_from(&model.direction);
    let conf = effective_config
        .get("flowchart")
        .or_else(|| effective_config.get("class"))
        .unwrap_or(effective_config);
    let nodesep = config_f64(conf, &["nodeSpacing"]).unwrap_or(50.0);
    let ranksep = config_f64(conf, &["rankSpacing"]).unwrap_or(50.0);

    let global_html_labels = config_bool(effective_config, &["htmlLabels"]).unwrap_or(true);
    let flowchart_html_labels =
        config_bool(effective_config, &["flowchart", "htmlLabels"]).unwrap_or(true);
    let wrap_mode_node = if global_html_labels {
        WrapMode::HtmlLike
    } else {
        WrapMode::SvgLike
    };
    let wrap_mode_label = if flowchart_html_labels {
        WrapMode::HtmlLike
    } else {
        WrapMode::SvgLike
    };

    // Mermaid defaults `config.class.padding` to 12.
    let class_padding = config_f64(effective_config, &["class", "padding"]).unwrap_or(12.0);
    let namespace_padding = config_f64(effective_config, &["flowchart", "padding"]).unwrap_or(15.0);
    let hide_empty_members_box =
        config_bool(effective_config, &["class", "hideEmptyMembersBox"]).unwrap_or(false);

    let text_style = class_text_style(effective_config);
    let capture_row_metrics = matches!(wrap_mode_node, WrapMode::HtmlLike);
    let capture_label_metrics = matches!(wrap_mode_label, WrapMode::HtmlLike);
    let mut class_row_metrics_by_id: FxHashMap<String, Arc<ClassNodeRowMetrics>> =
        FxHashMap::default();
    let mut node_label_metrics_by_id: HashMap<String, (f64, f64)> = HashMap::new();

    let mut g = Graph::<NodeLabel, EdgeLabel, GraphLabel>::new(GraphOptions {
        directed: true,
        multigraph: true,
        compound: true,
    });
    g.set_graph(GraphLabel {
        rankdir: diagram_dir,
        nodesep,
        ranksep,
        // Mermaid uses fixed graph margins in its Dagre wrapper for class diagrams, but our SVG
        // renderer re-introduces that margin when computing the viewport. Keep layout coordinates
        // margin-free here to avoid double counting.
        marginx: 0.0,
        marginy: 0.0,
        ..Default::default()
    });

    for id in model.namespaces.keys() {
        // Mermaid's dagre-wrapper assigns a concrete size to namespace nodes (cluster placeholders)
        // based on the rendered label bbox plus padding. Doing the same here helps compound
        // constraints match upstream (especially for LR layouts).
        let title = id.clone();
        let (tw, th) = label_metrics(&title, measurer, &text_style, wrap_mode_label);
        let w = (tw + 2.0 * namespace_padding).max(1.0);
        let h = (th + 2.0 * namespace_padding).max(1.0);
        g.set_node(
            id.clone(),
            NodeLabel {
                width: w,
                height: h,
                ..Default::default()
            },
        );
    }

    for c in model.classes.values() {
        let (w, h, row_metrics) = class_box_dimensions(
            c,
            measurer,
            &text_style,
            wrap_mode_node,
            class_padding,
            hide_empty_members_box,
            capture_row_metrics,
        );
        if let Some(rm) = row_metrics {
            class_row_metrics_by_id.insert(c.id.clone(), Arc::new(rm));
        }
        g.set_node(
            c.id.clone(),
            NodeLabel {
                width: w,
                height: h,
                ..Default::default()
            },
        );
    }

    // Interface nodes (lollipop syntax).
    for iface in &model.interfaces {
        let label = decode_entities_minimal(iface.label.trim());
        let (tw, th) = label_metrics(&label, measurer, &text_style, wrap_mode_label);
        if capture_label_metrics {
            node_label_metrics_by_id.insert(iface.id.clone(), (tw, th));
        }
        g.set_node(
            iface.id.clone(),
            NodeLabel {
                width: tw.max(1.0),
                height: th.max(1.0),
                ..Default::default()
            },
        );
    }

    for n in &model.notes {
        let (w, h, metrics) = note_dimensions(
            &n.text,
            measurer,
            &text_style,
            wrap_mode_label,
            namespace_padding,
        );
        if capture_label_metrics {
            node_label_metrics_by_id.insert(
                n.id.clone(),
                (metrics.width.max(0.0), metrics.height.max(0.0)),
            );
        }
        g.set_node(
            n.id.clone(),
            NodeLabel {
                width: w.max(1.0),
                height: h.max(1.0),
                ..Default::default()
            },
        );
    }

    if g.options().compound {
        // Mermaid assigns parents based on the class' `parent` field (see upstream
        // `addClasses(..., parent)` + `g.setParent(vertex.id, parent)`).
        for c in model.classes.values() {
            if let Some(parent) = c
                .parent
                .as_ref()
                .map(|s| s.trim())
                .filter(|s| !s.is_empty())
            {
                if model.namespaces.contains_key(parent) {
                    g.set_parent(c.id.clone(), parent.to_string());
                }
            }
        }

        // Keep interface nodes inside the same namespace cluster as their owning class.
        for iface in &model.interfaces {
            let Some(cls) = model.classes.get(iface.class_id.as_str()) else {
                continue;
            };
            let Some(parent) = cls
                .parent
                .as_ref()
                .map(|s| s.trim())
                .filter(|s| !s.is_empty())
            else {
                continue;
            };
            if model.namespaces.contains_key(parent) {
                g.set_parent(iface.id.clone(), parent.to_string());
            }
        }
    }

    for rel in &model.relations {
        let (lw, lh) = label_metrics(&rel.title, measurer, &text_style, wrap_mode_label);
        let start_text = if rel.relation_title_1 == "none" {
            String::new()
        } else {
            rel.relation_title_1.clone()
        };
        let end_text = if rel.relation_title_2 == "none" {
            String::new()
        } else {
            rel.relation_title_2.clone()
        };

        let (srw, srh) = label_metrics(&start_text, measurer, &text_style, wrap_mode_label);
        let (elw, elh) = label_metrics(&end_text, measurer, &text_style, wrap_mode_label);

        let start_marker = if rel.relation.type1 == -1 { 0.0 } else { 10.0 };
        let end_marker = if rel.relation.type2 == -1 { 0.0 } else { 10.0 };

        let mut el = EdgeLabel {
            width: lw,
            height: lh,
            labelpos: LabelPos::C,
            labeloffset: 10.0,
            minlen: 1,
            weight: 1.0,
            ..Default::default()
        };
        if srw > 0.0 && srh > 0.0 {
            set_extras_label_metrics(&mut el.extras, "startRight", srw, srh);
        }
        if elw > 0.0 && elh > 0.0 {
            set_extras_label_metrics(&mut el.extras, "endLeft", elw, elh);
        }
        el.extras
            .insert("startMarker".to_string(), Value::from(start_marker));
        el.extras
            .insert("endMarker".to_string(), Value::from(end_marker));

        g.set_edge_named(
            rel.id1.clone(),
            rel.id2.clone(),
            Some(rel.id.clone()),
            Some(el),
        );
    }

    let start_note_edge_id = model.relations.len() + 1;
    for (i, note) in model.notes.iter().enumerate() {
        let Some(class_id) = note.class_id.as_ref() else {
            continue;
        };
        if !model.classes.contains_key(class_id) {
            continue;
        }
        let edge_id = format!("edgeNote{}", start_note_edge_id + i);
        let el = EdgeLabel {
            width: 0.0,
            height: 0.0,
            labelpos: LabelPos::C,
            labeloffset: 10.0,
            minlen: 1,
            weight: 1.0,
            ..Default::default()
        };
        g.set_edge_named(note.id.clone(), class_id.clone(), Some(edge_id), Some(el));
    }

    let prefer_dagreish_disconnected = !model.interfaces.is_empty();
    let mut prepared = prepare_graph(g, 0, prefer_dagreish_disconnected)?;
    let (mut fragments, _bounds) = layout_prepared(&mut prepared, &node_label_metrics_by_id)?;

    let mut node_rect_by_id: HashMap<String, Rect> = HashMap::new();
    for n in fragments.nodes.values() {
        node_rect_by_id.insert(n.id.clone(), Rect::from_center(n.x, n.y, n.width, n.height));
    }

    for (edge, terminal_meta) in fragments.edges.iter_mut() {
        let Some(meta) = terminal_meta.clone() else {
            continue;
        };
        let (from_rect, to_rect, points) = if let (Some(from), Some(to)) = (
            node_rect_by_id.get(edge.from.as_str()).copied(),
            node_rect_by_id.get(edge.to.as_str()).copied(),
        ) {
            (
                Some(from),
                Some(to),
                terminal_path_for_edge(&edge.points, from, to),
            )
        } else {
            (None, None, edge.points.clone())
        };

        if let Some((w, h)) = meta.start_left {
            if let Some((x, y)) =
                calc_terminal_label_position(meta.start_marker, TerminalPos::StartLeft, &points)
            {
                let (x, y) = from_rect
                    .map(|r| nudge_point_outside_rect(x, y, r))
                    .unwrap_or((x, y));
                edge.start_label_left = Some(LayoutLabel {
                    x,
                    y,
                    width: w,
                    height: h,
                });
            }
        }
        if let Some((w, h)) = meta.start_right {
            if let Some((x, y)) =
                calc_terminal_label_position(meta.start_marker, TerminalPos::StartRight, &points)
            {
                let (x, y) = from_rect
                    .map(|r| nudge_point_outside_rect(x, y, r))
                    .unwrap_or((x, y));
                edge.start_label_right = Some(LayoutLabel {
                    x,
                    y,
                    width: w,
                    height: h,
                });
            }
        }
        if let Some((w, h)) = meta.end_left {
            if let Some((x, y)) =
                calc_terminal_label_position(meta.end_marker, TerminalPos::EndLeft, &points)
            {
                let (x, y) = to_rect
                    .map(|r| nudge_point_outside_rect(x, y, r))
                    .unwrap_or((x, y));
                edge.end_label_left = Some(LayoutLabel {
                    x,
                    y,
                    width: w,
                    height: h,
                });
            }
        }
        if let Some((w, h)) = meta.end_right {
            if let Some((x, y)) =
                calc_terminal_label_position(meta.end_marker, TerminalPos::EndRight, &points)
            {
                let (x, y) = to_rect
                    .map(|r| nudge_point_outside_rect(x, y, r))
                    .unwrap_or((x, y));
                edge.end_label_right = Some(LayoutLabel {
                    x,
                    y,
                    width: w,
                    height: h,
                });
            }
        }
    }

    let title_margin_top = config_f64(
        effective_config,
        &["flowchart", "subGraphTitleMargin", "top"],
    )
    .unwrap_or(0.0);
    let title_margin_bottom = config_f64(
        effective_config,
        &["flowchart", "subGraphTitleMargin", "bottom"],
    )
    .unwrap_or(0.0);

    let mut clusters: Vec<LayoutCluster> = Vec::new();
    // Mermaid renders namespaces as Dagre clusters. The cluster geometry comes from the Dagre
    // compound layout (not a post-hoc union of class-node bboxes). Use the computed namespace
    // node x/y/width/height and mirror `clusters.js` sizing tweaks for title width.
    for id in model.namespaces.keys() {
        let Some(ns_node) = fragments.nodes.get(id.as_str()) else {
            continue;
        };
        let cx = ns_node.x;
        let cy = ns_node.y;
        let base_w = ns_node.width.max(1.0);
        let base_h = ns_node.height.max(1.0);

        let title = id.clone();
        let (tw, th) = label_metrics(&title, measurer, &text_style, wrap_mode_label);
        let min_title_w = (tw + namespace_padding).max(1.0);
        let width = if base_w <= min_title_w {
            min_title_w
        } else {
            base_w
        };
        let diff = if base_w <= min_title_w {
            (width - base_w) / 2.0 - namespace_padding
        } else {
            -namespace_padding
        };
        let offset_y = th - namespace_padding / 2.0;
        let title_label = LayoutLabel {
            x: cx,
            y: (cy - base_h / 2.0) + title_margin_top + th / 2.0,
            width: tw,
            height: th,
        };

        clusters.push(LayoutCluster {
            id: id.clone(),
            x: cx,
            y: cy,
            width,
            height: base_h,
            diff,
            offset_y,
            title: title.clone(),
            title_label,
            requested_dir: None,
            effective_dir: normalize_dir(&model.direction),
            padding: namespace_padding,
            title_margin_top,
            title_margin_bottom,
        });
    }

    // Keep snapshots deterministic. The Dagre-ish pipeline may insert dummy nodes/edges in
    // iteration-dependent order, so sort the emitted layout lists by stable identifiers.
    let mut nodes: Vec<LayoutNode> = fragments.nodes.into_values().collect();
    nodes.sort_by(|a, b| a.id.cmp(&b.id));

    let mut edges: Vec<LayoutEdge> = fragments.edges.into_iter().map(|(e, _)| e).collect();
    edges.sort_by(|a, b| a.id.cmp(&b.id));

    clusters.sort_by(|a, b| a.id.cmp(&b.id));

    let bounds = compute_bounds(&nodes, &edges, &clusters);

    Ok(ClassDiagramV2Layout {
        nodes,
        edges,
        clusters,
        bounds,
        class_row_metrics_by_id,
    })
}

fn compute_bounds(
    nodes: &[LayoutNode],
    edges: &[LayoutEdge],
    clusters: &[LayoutCluster],
) -> Option<Bounds> {
    let mut points: Vec<(f64, f64)> = Vec::new();

    for c in clusters {
        let r = Rect::from_center(c.x, c.y, c.width, c.height);
        points.push((r.min_x(), r.min_y()));
        points.push((r.max_x(), r.max_y()));
        let lr = Rect::from_center(
            c.title_label.x,
            c.title_label.y,
            c.title_label.width,
            c.title_label.height,
        );
        points.push((lr.min_x(), lr.min_y()));
        points.push((lr.max_x(), lr.max_y()));
    }

    for n in nodes {
        let r = Rect::from_center(n.x, n.y, n.width, n.height);
        points.push((r.min_x(), r.min_y()));
        points.push((r.max_x(), r.max_y()));
    }

    for e in edges {
        for p in &e.points {
            points.push((p.x, p.y));
        }
        for l in [
            e.label.as_ref(),
            e.start_label_left.as_ref(),
            e.start_label_right.as_ref(),
            e.end_label_left.as_ref(),
            e.end_label_right.as_ref(),
        ]
        .into_iter()
        .flatten()
        {
            let r = Rect::from_center(l.x, l.y, l.width, l.height);
            points.push((r.min_x(), r.min_y()));
            points.push((r.max_x(), r.max_y()));
        }
    }

    Bounds::from_points(points)
}