dataface 0.1.2__py3-none-any.whl

dataface/core/render/faces.py

@@ -0,0 +1,1194 @@
+"""Face rendering functions.
+
+Stage: RENDER
+Purpose: Render face structures (root and nested) to SVG.
+
+This module handles:
+- Root face SVG rendering (render_face_svg)
+- Nested face SVG rendering (render_nested_face)
+
+Dependencies:
+    - .layouts (for layout rendering)
+    - .variable_controls (for variable rendering)
+    - .svg_utils (for SVG utilities)
+    - .themes (for theme colors)
+"""
+
+import hashlib
+import html
+import re
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Literal
+
+from dataface.core.errors import StructuredError
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.primitives import FontStyle
+    from dataface.core.compile.models.style.compiled import TextStyle
+    from dataface.core.compile.models.style.merged import MergedStyle
+
+from dataface.core.compile.models.face.compiled import (
+    MergedFace,
+    VariableValues,
+)
+from dataface.core.compile.models.style.compiled import compute_text_column_count
+from dataface.core.compile.models.style.merged import (
+    effective_padding as _effective_padding,
+)
+from dataface.core.execute.executor import Executor
+from dataface.core.render.chart_interactivity import (
+    generate_svg_chart_interactivity_script,
+)
+from dataface.core.render.svg_utils import _px, extract_svg_inner_content
+
+# Named constant for SVG ID hash length
+SVG_ID_HASH_LENGTH = 8
+
+# Vertical gap between the page footer text and the hairline rule above it.
+# Used by both the height-reservation math and the rule-position math so the
+# two never drift.
+FOOTER_RULE_GAP_PX = 2
+
+__all__ = [
+    "render_face_svg",
+    "render_nested_face",
+    "SVG_ID_HASH_LENGTH",
+]
+
+# -----------------------------------------------------------------------------
+# Shared rendering helpers (DRY - single source of truth)
+# -----------------------------------------------------------------------------
+
+
+def _format_svg_numeric(value: float) -> str:
+    """Render integer-valued floats without a trailing .0."""
+    numeric = float(value)
+    return str(int(numeric)) if numeric.is_integer() else str(numeric)
+
+
+def _resolve_jinja(template: str, variables: VariableValues) -> str:
+    """Resolve Jinja templates in a string (lenient mode).
+
+    Returns the original string if no Jinja syntax is present.
+    """
+    if "{{" not in template and "{%" not in template:
+        return template
+    from dataface.core.compile.jinja import resolve_jinja_template
+
+    return resolve_jinja_template(template, variables, strict=False)
+
+
+def _render_title_svg(
+    title: str,
+    variables: VariableValues,
+    width: float,
+    text_align: Literal["left", "center", "right"] = "left",
+    level: int = 1,
+    prose: bool = False,
+    resolved_style: "MergedStyle | None" = None,
+) -> str:
+    """Render a title with Jinja resolution and case transform."""
+    from dataface.core.render.svg_utils import render_title
+    from dataface.core.render.text.case import apply_case
+
+    resolved = _resolve_jinja(title, variables)
+    # Apply the case transform from style.title.font.case (cascaded from root).
+    # Face body markdown (TextStyle.font.case) is explicitly excluded — case
+    # transforms on prose blocks would corrupt code spans, links, and emphasis.
+    _title_case = resolved_style.title.font.case if resolved_style is not None else None
+    if _title_case is not None and _title_case != "none":
+        resolved = apply_case(resolved, _title_case)
+    return render_title(
+        resolved,
+        width,
+        text_align=text_align,
+        level=level,
+        prose=prose,
+        resolved_style=resolved_style,
+    )
+
+
+def _face_uses_title_inline_band(face: MergedFace) -> bool:
+    return (
+        face.style.variables.position == "title-inline"
+        and bool(face.title)
+        and bool(face.visible_variables)
+    )
+
+
+def _paint_title_svg_fill(title_svg: str, color: str) -> str:
+    r"""Apply a solid fill to every ``<text>`` element in the title SVG.
+
+    Uses inline ``style="fill: ..."`` rather than the ``fill="..."`` presentation
+    attribute. The title text carries ``class="md-heading"`` (mdsvg), and SVG/CSS
+    specificity rules let class-rule properties beat presentation attributes —
+    so a bare ``fill="…"`` override is silently swallowed by the class's fill.
+    An inline style attribute trumps the class rule and the override sticks.
+
+    Two independent passes (both run unconditionally):
+
+    1. **Inject** ``style="fill: …"`` on every ``<text>`` element that does
+       not already carry a style attribute. mdsvg emits plain-heading text
+       as ``<text class="md-heading">…</text>``; that text gets the new
+       inline style here.
+    2. **Rewrite** any existing ``fill:`` declaration inside any ``style="…"``
+       attribute. mdsvg wraps code-styled or link-styled runs inside a
+       title in ``<tspan style="…; fill: …">…</tspan>``; those tspans get
+       their existing fill rewritten in place so a mixed-content title
+       like ``Sales \`Q3\``` paints uniformly in the override color.
+
+    The rewrite is scoped to the attribute value (not the whole document)
+    so CSS rules inside any ``<style>`` block — ``.md-text { fill: ... }``
+    etc. — are untouched. Other declarations in the same ``style="..."``
+    attribute (e.g. ``font-weight: 500``) are preserved.
+    """
+    color_escaped = html.escape(str(color))
+
+    # Pass 1 — inject inline style on every <text> that doesn't already carry
+    # one. Inserting before any attribute means subsequent attributes survive.
+    no_style_re = re.compile(r"<text(?![^>]*\bstyle=)")
+    title_svg = no_style_re.sub(f'<text style="fill: {color_escaped}"', title_svg)
+
+    # Pass 2 — rewrite any existing fill: declaration inside a style attribute.
+    attr_with_fill_re = re.compile(r'(style=")([^"]*\bfill\s*:\s*)[^;"]*([^"]*)(")')
+    title_svg = attr_with_fill_re.sub(
+        rf"\g<1>\g<2>{color_escaped}\g<3>\g<4>", title_svg
+    )
+
+    return title_svg
+
+
+def _render_title_variables_inline_band(
+    face: MergedFace,
+    variables: VariableValues,
+    layout_content_width: float,
+    card_pad: float,
+    interactive: bool,
+    executor: Executor,
+    text_align: Literal["left", "center", "right"],
+    prose: bool,
+) -> tuple[str, float]:
+    """One horizontal band: face title (left column) + variable controls (right)."""
+    from dataface.core.compile.sizing import (
+        compute_title_variables_inline_baseline_layout,
+        get_title_height,
+        resolve_title_variables_inline_widths,
+    )
+    from dataface.core.render.variable_controls import (
+        render_interactive_variables_svg,
+        render_variables_svg,
+    )
+
+    vs = face.style.variables
+    inner = max(layout_content_width - 2 * card_pad, 1.0)
+    title_w, vars_w = resolve_title_variables_inline_widths(
+        inner,
+        vs,
+        face.visible_variables,
+        title=face.title,
+        variable_defaults=face.variable_defaults,
+    )
+    col_gap = float(vs.gap)
+
+    # Size the title against the board's inner width, not the title column.
+    # face_title_spec selects a width tier (narrow/medium/wide) that drives the
+    # heading-level offset. Passing the cramped title-inline column (~262px on
+    # the default board with a daterange filter) lands in the narrow tier and
+    # bumps the title from H1 (24px) to H2 (18px) the moment a filter is added.
+    # The title still wraps/measures inside title_w at the layout step — only
+    # tier selection sees the board inner width.
+    title_svg_raw = _render_title_svg(
+        face.title,
+        variables,
+        inner,
+        text_align,
+        prose=prose,
+        resolved_style=face.style,
+    )
+    # Paint the title fill from cascade-resolved face style so user overrides
+    # win over mdsvg's CSS-baked class fill. Same precedence as the non-inline
+    # path further down (style.title.font.color → style.color); both render
+    # paths produce identical title colors for the same face.
+    # TODO(audit-variable-controls-css-for-off-stack-font-sizes follow-up):
+    # this is a post-render painter sitting on top of mdsvg's heading-color
+    # path; the proper cascade fix in get_compact_style (style.title.font.color
+    # vs markdown_colors layer) is deferred to that task to bound blast radius.
+    title_color = face.style.title.font.color or face.style.color
+    if title_color:
+        title_svg_raw = _paint_title_svg_fill(title_svg_raw, str(title_color))
+    title_inner = extract_svg_inner_content(title_svg_raw)
+    title_h = max(
+        get_title_height(face.title, title_w, face.variable_defaults),
+        float(face.style.title.min_height),
+    )
+
+    if interactive:
+        vars_svg, vars_h = render_interactive_variables_svg(
+            face.visible_variables,
+            variables,
+            vars_w,
+            executor,
+            resolved_style=face.style,
+        )
+    else:
+        vars_svg, vars_h = render_variables_svg(
+            face.visible_variables,
+            variables,
+            vars_w,
+            resolved_style=face.style,
+        )
+    assert vs.font.size is not None, "style.variables.font.size must be configured"
+    title_dy, vars_dy, band_h = compute_title_variables_inline_baseline_layout(
+        title_h, vars_h, float(vs.font.size)
+    )
+    band = (
+        "<g>"
+        f'<g transform="translate({_px(card_pad)}, {_px(title_dy)})">{title_inner}</g>'
+        f'<g transform="translate({_px(card_pad + title_w + col_gap)}, {_px(vars_dy)})">{vars_svg}</g>'
+        "</g>"
+    )
+    return band, band_h
+
+
+def _render_text_svg(
+    text: str,
+    variables: VariableValues,
+    width: float,
+    text_align: Literal["left", "center", "right"] = "left",
+    prose: bool = False,
+    resolved_style: "MergedStyle | None" = None,
+    text_style: "TextStyle | None" = None,
+) -> tuple[str, float]:
+    """Render markdown text with Jinja resolution and board-link rewriting.
+
+    Returns (svg_string, height).
+    """
+    from dataface.core.compile.config import get_config
+    from dataface.core.compile.models.primitives import FontStyle
+    from dataface.core.compile.models.style.merged import resolve_style
+    from dataface.core.compile.sizing import get_compact_style
+    from dataface.core.fonts import get_inter_font_path, get_mono_font_path
+    from dataface.core.render.board_links import get_link_context, rewrite_board_links
+    from mdsvg import parse as parse_markdown
+    from mdsvg.renderer import SVGRenderer
+
+    resolved = _resolve_jinja(text, variables)
+    resolved = rewrite_board_links(resolved, get_link_context())
+    if prose:
+        assert resolved_style is not None
+        prose_font: FontStyle | None = resolved_style.title.font
+    else:
+        prose_font = None
+
+    if text_style is not None and text_style.column.has_overrides:
+        return _render_columned_text_svg(
+            resolved, width, text_style, font=prose_font, resolved_style=resolved_style
+        )
+
+    font_family = prose_font.family if prose_font is not None else None
+    _ms = (
+        resolved_style
+        if resolved_style is not None
+        else resolve_style(get_config().style)
+    )
+    style = get_compact_style(_ms, text_align=text_align, font_family=font_family)
+    font_path = str(get_inter_font_path())
+    mono_font_path = str(get_mono_font_path())
+    # fetch_image_sizes=False: http:// image URLs in text blocks must not make
+    # synchronous network calls (10s urlopen timeout × N images blocks the
+    # asyncio event loop in dft serve). Pages that need accurate per-image
+    # sizing must embed dimensions in the markdown source via mdsvg's explicit
+    # ``![alt](url){width=X height=Y}`` syntax — pre-compute and inject at
+    # YAML-staging time, not at render time.
+    renderer = SVGRenderer(
+        style=style,
+        font_path=font_path,
+        mono_font_path=mono_font_path,
+        fetch_image_sizes=False,
+    )
+    blocks = list(parse_markdown(resolved))
+    size = renderer.measure(blocks, width=width, padding=0.0)
+    svg = renderer.render(blocks, width=width, padding=0.0)
+    return svg, size.height
+
+
+def _render_columned_text_svg(
+    markdown_text: str,
+    width: float,
+    text_style: "TextStyle",
+    font: "FontStyle | None" = None,
+    resolved_style: "MergedStyle | None" = None,
+) -> tuple[str, float]:
+    """Render body-text markdown as pure SVG with column/align overrides.
+
+    Handles align and multi-column flow entirely in SVG —
+    no foreignObject, no browser HTML layout dependency.
+
+    Returns (svg_string, height).
+    """
+    from dataface.core.compile.config import get_config
+    from dataface.core.compile.models.style.merged import (
+        apply_emoji_to_family,
+        resolve_style,
+    )
+    from dataface.core.compile.sizing import get_compact_style, greedy_column_fill
+    from dataface.core.fonts import get_inter_font_path, get_mono_font_path
+    from mdsvg import parse as parse_markdown
+    from mdsvg.renderer import SVGRenderer
+
+    config = get_config()
+    col = text_style.column
+    column_gap = col.gap if col.gap is not None else float(config.style.layout.rows.gap)
+
+    _align: Literal["left", "center", "right"] = text_style.align
+    _root_family = config.style.font.family
+    assert _root_family is not None, "style.font.family must be configured"
+    _base_family = apply_emoji_to_family(_root_family, config.style.font.emoji)
+    effective_family = (font.family if font is not None else None) or _base_family
+
+    _ms = (
+        resolved_style
+        if resolved_style is not None
+        else resolve_style(get_config().style)
+    )
+    style = get_compact_style(_ms, text_align=_align, font_family=effective_family)
+    font_path = str(get_inter_font_path())
+    mono_font_path = str(get_mono_font_path())
+
+    n_cols = compute_text_column_count(col, width, column_gap)
+
+    # fetch_image_sizes=False: see comment in _render_text_svg.
+    renderer = SVGRenderer(
+        style=style,
+        font_path=font_path,
+        mono_font_path=mono_font_path,
+        fetch_image_sizes=False,
+    )
+
+    blocks = list(parse_markdown(markdown_text))
+
+    if n_cols <= 1:
+        result = renderer.render_content(blocks, width=width, padding=0.0)
+        w = _format_svg_numeric(width)
+        h = _format_svg_numeric(result.height)
+        svg = (
+            f'<svg xmlns="http://www.w3.org/2000/svg" width="{w}" height="{h}">'
+            f"{result.content}</svg>"
+        )
+        return svg, result.height
+
+    per_col_width = max((width - (n_cols - 1) * column_gap) / n_cols, 1.0)
+
+    block_results = [
+        renderer.render_content([block], width=per_col_width, padding=0.0)
+        for block in blocks
+    ]
+
+    assignments, actual_col_height = greedy_column_fill(
+        [r.height for r in block_results], n_cols, style.paragraph_spacing
+    )
+
+    style_block = block_results[0].style_block if block_results else ""
+    svg_parts = [style_block]
+    for ci in range(n_cols):
+        col_x = ci * (per_col_width + column_gap)
+        col_elements = [
+            f'<g transform="translate(0, {_px(y)})">{r.elements}</g>'
+            for (c, y), r in zip(assignments, block_results, strict=True)
+            if c == ci
+        ]
+        if col_elements:
+            svg_parts.append(
+                f'<g transform="translate({_px(col_x)}, 0)">'
+                f'{"".join(col_elements)}</g>'
+            )
+        if col.rule and ci < n_cols - 1:
+            svg_parts.append(
+                _column_rule_line(
+                    col_x + per_col_width + column_gap / 2, actual_col_height, col.rule
+                )
+            )
+
+    total_width = n_cols * per_col_width + (n_cols - 1) * column_gap
+    w = _format_svg_numeric(total_width)
+    h = _format_svg_numeric(actual_col_height)
+    svg = f'<svg xmlns="http://www.w3.org/2000/svg" width="{w}" height="{h}">{"".join(svg_parts)}</svg>'
+    return svg, actual_col_height
+
+
+_COLUMN_RULE_DASHARRAY = {"dotted": "2,2", "dashed": "6,3"}
+
+
+def _column_rule_line(x: float, height: float, rule: str) -> str:
+    """Generate a vertical SVG line from a validated column-rule string (e.g. '1px solid #e5e7eb').
+
+    Input must have been validated by TextColumnStyle._validate_rule_parseable:
+    exactly one px width, exactly one hex color, at most one of solid/dashed/dotted.
+    """
+    parts = rule.strip().split()
+    stroke_width = next(float(p[:-2]) for p in parts if p.endswith("px"))
+    stroke_color = next(p for p in parts if p.startswith("#"))
+    stroke_style = next((p for p in parts if p in _COLUMN_RULE_DASHARRAY), "solid")
+    # Snap x to integer: a 1px structural mark at fractional x blurs horizontally.
+    x_snapped = _px(x)
+    h_s = _format_svg_numeric(height)
+    sw_s = _format_svg_numeric(stroke_width)
+    extra = (
+        f' stroke-dasharray="{_COLUMN_RULE_DASHARRAY[stroke_style]}"'
+        if stroke_style in _COLUMN_RULE_DASHARRAY
+        else ""
+    )
+    return (
+        f'<line x1="{x_snapped}" y1="0" x2="{x_snapped}" y2="{h_s}"'
+        f' stroke="{html.escape(stroke_color)}" stroke-width="{sw_s}"{extra}/>'
+    )
+
+
+def _build_face_content_items(
+    x_offset: float,
+    y_offset: float,
+    gap: float,
+    title_svg: str,
+    title_height: float,
+    text_svg: str,
+    text_height: float,
+    variables_svg: str,
+    variables_height: float,
+    layout_content: str,
+    layout_content_height: float,
+    card_padding: float,
+    inline_header_svg: str = "",
+    inline_header_height: float = 0.0,
+) -> tuple[list[str], float]:
+    """Build inner content item list; return (items, items_height).
+
+    Applies gap between adjacent elements only — no trailing gap after the
+    last non-layout element when no layout items follow.  This matches the
+    sizing pass formula: gap * (n - 1).
+
+    card_padding: when nonzero, title, text, and variables are inset by this
+    amount on the x-axis, matching the card_padding inset applied to chart
+    leaf items. Layout content keeps the base x_offset.
+    """
+    items: list[str] = []
+    items_height = y_offset
+    has_prev = False
+    content_x = x_offset + card_padding  # title and text align with chart content
+
+    if inline_header_svg:
+        items.append(
+            f'<g transform="translate({_px(x_offset)}, {_px(items_height)})">{inline_header_svg}</g>'
+        )
+        items_height += inline_header_height
+        has_prev = True
+    elif title_svg:
+        items.append(
+            f'<g transform="translate({_px(content_x)}, {_px(items_height)})">{title_svg}</g>'
+        )
+        items_height += title_height
+        has_prev = True
+
+    if text_svg:
+        if has_prev:
+            items_height += gap
+        md = extract_svg_inner_content(text_svg)
+        if md:
+            items.append(
+                f'<g transform="translate({_px(content_x)}, {_px(items_height)})">{md}</g>'
+            )
+        items_height += text_height
+        has_prev = True
+
+    if variables_svg and not inline_header_svg:
+        if has_prev:
+            items_height += gap
+        items.append(
+            f'<g transform="translate({_px(content_x)}, {_px(items_height)})">{variables_svg}</g>'
+        )
+        items_height += variables_height
+        has_prev = True
+
+    if layout_content:
+        if has_prev:
+            items_height += gap
+        items.append(
+            f'<g transform="translate({_px(x_offset)}, {_px(items_height)})">{layout_content}</g>'
+        )
+
+    # Advance by the remaining layout space so the face fills its allocated slot.
+    # For nested faces: sizing deducted all non-layout heights to compute this value,
+    # so adding it back fills the slot exactly. For the root face: if non-layout
+    # content overflows (available goes negative), clamp to 0 — the SVG will grow
+    # via max(height, ...) in total_height.
+    items_height += max(layout_content_height, 0)
+
+    return items, items_height - y_offset
+
+
+def _render_layout(
+    face: MergedFace,
+    executor: Executor,
+    variables: VariableValues,
+    layout_content_width: float,
+    layout_content_height: float,
+    card_gap: float,
+    gap: float,
+    background: str | None,
+    interactive: bool = True,
+    render_cache: dict[tuple[str, float, float], tuple[str, float]] | None = None,
+    error_collector: list[StructuredError] | None = None,
+) -> tuple[str, float]:
+    """Render layout based on type (single dispatch point).
+
+    This is the single source of truth for layout type dispatch.
+
+    Returns:
+        (svg_elements_string, actual_layout_height)
+    """
+    from dataface.core.render.layouts import (
+        render_cols_layout,
+        render_grid_layout,
+        render_rows_layout,
+        render_tabs_layout,
+    )
+
+    if not face.layout.items:
+        return "", 0.0
+
+    layout = face.layout
+    items = layout.items
+    # vega_config is baked by resolve_face/_build_resolved_nested_face — always non-empty.
+    _vega_config = face.vega_config
+    resolved_style = face.style  # MergedFace.style is the MergedStyle
+
+    if layout.type == "cols":
+        result = render_cols_layout(
+            items,
+            executor,
+            variables,
+            layout_content_width,
+            layout_content_height,
+            card_gap,
+            gap,
+            background,
+            resolved_style,
+            interactive,
+            render_cache,
+            error_collector=error_collector,
+            face_level=face.level,
+            vega_config=_vega_config,
+        )
+    elif layout.type == "grid":
+        columns = layout.columns or resolved_style.layout.grid.columns
+        result = render_grid_layout(
+            items,
+            executor,
+            variables,
+            layout_content_width,
+            layout_content_height,
+            columns,
+            card_gap,
+            gap,
+            background,
+            resolved_style,
+            interactive,
+            render_cache,
+            error_collector=error_collector,
+            face_level=face.level,
+            vega_config=_vega_config,
+        )
+    elif layout.type == "tabs":
+        result = render_tabs_layout(
+            items,
+            executor,
+            variables,
+            layout_content_width,
+            layout_content_height,
+            card_gap,
+            list(layout.tab_titles),
+            list(layout.tab_slugs),
+            layout.tab_variable,
+            layout.default_tab or 0,
+            layout.tab_position or "top",
+            background,
+            resolved_style=resolved_style,
+            interactive=interactive,
+            render_cache=render_cache,
+            error_collector=error_collector,
+            face_level=face.level,
+            vega_config=_vega_config,
+        )
+    else:
+        # Default to rows (handles "rows" and any unknown type)
+        result = render_rows_layout(
+            items,
+            executor,
+            variables,
+            layout_content_width,
+            layout_content_height,
+            card_gap,
+            gap,
+            background,
+            resolved_style,
+            interactive,
+            render_cache,
+            error_collector=error_collector,
+            face_level=face.level,
+            vega_config=_vega_config,
+        )
+
+    return result
+
+
+def render_face_svg(
+    face: MergedFace,
+    executor: Executor,
+    variables: VariableValues,
+    background: str | None,
+    grid: bool = False,
+    interactive: bool = True,
+    render_cache: dict[tuple[str, float, float], tuple[str, float]] | None = None,
+    margins: bool = False,
+    error_collector: list[StructuredError] | None = None,
+) -> str:
+    """Render face to SVG.
+
+    Walks the layout structure and renders each item based on layout type.
+
+    Args:
+        face: MergedFace with baked board config — no get_config() needed.
+        executor: Executor for query execution
+        variables: Variable values for queries
+        background: Background color or pattern URL
+        grid: Whether to show grid overlay pattern
+        interactive: Whether to render interactive variable controls using foreignObject.
+                     Set to False for PNG/PDF export (svglib doesn't support foreignObject).
+        margins: Whether to show vertical margin guide lines
+
+    Returns:
+        Complete SVG string for the face
+    """
+    from dataface.core.compile.sizing import get_title_height
+    from dataface.core.render.svg_utils import create_grid_pattern, generate_svg_styles
+    from dataface.core.render.variable_controls import (
+        generate_svg_variable_script,
+        render_interactive_variables_svg,
+        render_variables_svg,
+    )
+
+    resolved_style = face.style  # MergedFace.style is the MergedStyle
+    # Board config baked into MergedFace — no get_config() needed.
+    page_padding = face.page_padding or 0.0
+    card_pad = face.card_padding or 0.0
+    card_gap = face.card_gap or 0.0
+    # gap between layout items: MergedFace.layout.gap (set during resolve_face).
+    gap = face.layout.gap or 0.0
+    effective_gap = gap + card_gap
+
+    width = face.width
+    height = face.height
+
+    # Root content width should match the sizing pass exactly.
+    layout_content_width = face.layout.content_width
+    # Title and text render within a narrower width (inset by card_padding on both sides).
+    title_text_width = max((layout_content_width or 0.0) - 2 * card_pad, 0.0)
+    # Width is container-driven and precomputed during sizing; height remains
+    # content-driven and is finalized here after title/content/controls render.
+    layout_content_height = height - (2 * page_padding)
+    # Track whether any element has been placed so we only insert a gap *between*
+    # adjacent elements — matching the sizing pass's gap*(n-1) formula exactly.
+    # Note: the root face renders title/content/variable heights dynamically here
+    # (rather than reading pre-computed values from sizing) because the root face
+    # is the source of truth for its own height — it has no pre-allocated slot.
+    # Nested faces follow the opposite contract (see render_nested_face).
+    has_prev = False
+
+    text_align = resolved_style.text.align
+
+    from dataface.core.compile.typography import is_prose
+
+    prose = is_prose(face.text) if face.text else False
+
+    inline_header_svg = ""
+    inline_header_height = 0.0
+    title_svg = ""
+    title_height = 0.0
+
+    if _face_uses_title_inline_band(face):
+        inline_header_svg, inline_header_height = _render_title_variables_inline_band(
+            face,
+            variables,
+            layout_content_width,
+            card_pad,
+            interactive,
+            executor,
+            text_align=text_align,
+            prose=prose,
+        )
+        layout_content_height -= inline_header_height
+        has_prev = True
+    elif face.title:
+        title_svg = _render_title_svg(
+            face.title,
+            variables,
+            title_text_width or layout_content_width,
+            text_align=text_align,
+            level=face.level,
+            prose=prose,
+            resolved_style=resolved_style,
+        )
+        # Same paint precedence as the inline-band path (style.title.font.color
+        # → style.color); both render paths produce identical title colors for
+        # the same face style, regardless of variables.position.
+        title_color = resolved_style.title.font.color or resolved_style.color
+        if title_color:
+            title_svg = _paint_title_svg_fill(title_svg, str(title_color))
+        title_height = get_title_height(
+            face.title,
+            title_text_width or layout_content_width,
+            face.variable_defaults,
+            level=face.level,
+        )
+        title_height = max(title_height, float(face.style.title.min_height))
+        layout_content_height -= title_height
+        has_prev = True
+
+    # Render text (markdown) if present (using shared helper)
+    text_svg = ""
+    text_height = 0.0
+    if face.text:
+        text_svg, text_height = _render_text_svg(
+            face.text,
+            variables,
+            title_text_width or layout_content_width,
+            text_align=text_align,
+            prose=prose,
+            resolved_style=resolved_style,
+            text_style=resolved_style.text,
+        )
+        if has_prev:
+            layout_content_height -= effective_gap
+        layout_content_height -= text_height
+        has_prev = True
+
+    # Render variable controls for root-level variables only (skip when merged into title band).
+    variables_svg = ""
+    variables_height = 0.0
+    variables_script = ""
+    chart_interactivity_script = ""
+    # Variable controls are inset by card_pad on the left (aligned with chart
+    # content); reduce width by the same amount so the right edge is unchanged.
+    variables_width = max(layout_content_width - card_pad, 0.0)
+    if face.visible_variables and variables and not inline_header_svg:
+        if interactive:
+            variables_svg, variables_height = render_interactive_variables_svg(
+                face.visible_variables,
+                variables,
+                variables_width,
+                executor,
+                resolved_style=resolved_style,
+            )
+        else:
+            variables_svg, variables_height = render_variables_svg(
+                face.visible_variables,
+                variables,
+                variables_width,
+                resolved_style=resolved_style,
+            )
+        if variables_height > 0:
+            if has_prev:
+                layout_content_height -= effective_gap
+            layout_content_height -= variables_height
+            has_prev = True
+
+    # Gap before layout items (only when something precedes them)
+    if face.layout.items and has_prev:
+        layout_content_height -= effective_gap
+
+    if interactive:
+        # Always embed variables.js for interactive SVG: it handles both
+        # variable control updates and SVG <a href="?..."> tab navigation.
+        # The tab click interception is required even when no variable controls
+        # are declared (blob-URL iframes can't navigate to query-string URLs).
+        variables_script = generate_svg_variable_script()
+        chart_interactivity_script = generate_svg_chart_interactivity_script(
+            resolved_style=resolved_style
+        )
+
+    # Render layout (using shared helper)
+    layout_content, actual_layout_height = _render_layout(
+        face,
+        executor,
+        variables,
+        layout_content_width,
+        layout_content_height,
+        card_gap,
+        gap,
+        resolved_style.background,
+        interactive,
+        render_cache,
+        error_collector=error_collector,
+    )
+
+    # Combine title, content, variables, and layout into positioned groups.
+    # Gap is added only between adjacent elements (matches sizing's gap*(n-1) formula).
+    # Use actual_layout_height (from rendered content) rather than the pre-computed
+    # layout_content_height so the root face SVG grows to fit Vega charts.
+    content_items, content_items_height = _build_face_content_items(
+        x_offset=page_padding,
+        y_offset=page_padding,
+        gap=effective_gap,
+        title_svg=title_svg,
+        title_height=title_height,
+        text_svg=text_svg,
+        text_height=text_height,
+        variables_svg=variables_svg,
+        variables_height=variables_height,
+        layout_content=layout_content,
+        layout_content_height=actual_layout_height,
+        card_padding=card_pad,
+        inline_header_svg=inline_header_svg,
+        inline_header_height=inline_header_height,
+    )
+
+    from dataface.core.compile.config import get_rendering_config
+
+    rendering_cfg = get_rendering_config()
+
+    # Calculate final dimensions
+    total_width = max(width, layout_content_width + (2 * page_padding))
+    total_height = max(height, content_items_height + (2 * page_padding))
+
+    # Reserve vertical space for the page footer (right-aligned text, optional
+    # hairline rule above) so it doesn't overlap the bottom card.
+    if rendering_cfg.footer_text:
+        # FooterConfig._require_font_size_and_color guarantees non-None.
+        assert rendering_cfg.footer.font.size is not None
+        footer_font_size = float(rendering_cfg.footer.font.size)
+        rule_gap = FOOTER_RULE_GAP_PX if rendering_cfg.footer.rule is not None else 0
+        total_height += rendering_cfg.footer.y_offset + footer_font_size + rule_gap
+
+    # Grid pattern if enabled
+    grid_defs = ""
+    if grid:
+        grid_defs = create_grid_pattern()
+        background = "url(#grid-pattern)"
+
+    # Background rect
+    bg_rect = ""
+    if background:
+        bg_rect = f'<rect x="0" y="0" width="{total_width}" height="{total_height}" fill="{html.escape(background)}"/>'
+
+    # Margin guide lines (print-media style alignment guides)
+    margin_lines = ""
+    if margins:
+        margin_color = "rgba(219, 112, 147, 0.45)"
+        inset = 16
+        left = page_padding
+        right = total_width - page_padding
+        lines = [
+            f'<line x1="{_format_svg_numeric(left)}" y1="0" x2="{_format_svg_numeric(left)}" y2="{total_height}" stroke="{margin_color}" stroke-width="1"/>',
+            f'<line x1="{_format_svg_numeric(left + inset)}" y1="0" x2="{_format_svg_numeric(left + inset)}" y2="{total_height}" stroke="{margin_color}" stroke-width="1"/>',
+            f'<line x1="{_format_svg_numeric(right)}" y1="0" x2="{_format_svg_numeric(right)}" y2="{total_height}" stroke="{margin_color}" stroke-width="1"/>',
+            f'<line x1="{_format_svg_numeric(right - inset)}" y1="0" x2="{_format_svg_numeric(right - inset)}" y2="{total_height}" stroke="{margin_color}" stroke-width="1"/>',
+        ]
+        margin_lines = "\n".join(lines)
+
+    from dataface.core.compile.config import get_config
+
+    svg_styles = generate_svg_styles(emoji_mode=get_config().style.font.emoji)
+
+    svg_id_hash = hashlib.md5(f"{total_width}x{total_height}".encode()).hexdigest()[
+        :SVG_ID_HASH_LENGTH
+    ]
+    svg_id = f"dataface-svg-{svg_id_hash}"
+
+    render_time = datetime.now(timezone.utc)
+    render_timestamp_iso = render_time.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    timestamp_element = ""
+    if rendering_cfg.timestamp_visible:
+        timestamp_format = rendering_cfg.timestamp_format
+        timestamp_config = rendering_cfg.timestamp
+        # TimestampConfig's _require_font_size_and_color model validator
+        # guarantees both are non-None at config load; narrow for mypy.
+        assert timestamp_config.font.size is not None
+        assert timestamp_config.font.color is not None
+        display_timestamp = render_time.strftime(timestamp_format)
+        timestamp_x = total_width - page_padding
+        timestamp_y = timestamp_config.y
+        timestamp_element = (
+            f'<text data-role="render-timestamp" x="{_format_svg_numeric(timestamp_x)}" y="{_format_svg_numeric(timestamp_y)}" text-anchor="end" '
+            f'font-size="{_format_svg_numeric(float(timestamp_config.font.size))}" fill="{timestamp_config.font.color}" font-family="{face.style.font.family}" '
+            f'style="font-variant-numeric: tabular-nums lining-nums;">'
+            f"{html.escape(display_timestamp)}</text>"
+        )
+
+    footer_element = ""
+    if rendering_cfg.footer_text:
+        footer_cfg = rendering_cfg.footer
+        # FooterConfig._require_font_size_and_color guarantees both non-None.
+        assert footer_cfg.font.size is not None
+        assert footer_cfg.font.color is not None
+        footer_x = total_width - page_padding
+        footer_y = total_height - footer_cfg.y_offset
+        footer_parts = []
+        if footer_cfg.rule is not None:
+            rule_y = footer_y - float(footer_cfg.font.size) - FOOTER_RULE_GAP_PX
+            footer_parts.append(
+                f'<line x1="{_format_svg_numeric(page_padding)}" y1="{_format_svg_numeric(rule_y)}" '
+                f'x2="{_format_svg_numeric(footer_x)}" y2="{_format_svg_numeric(rule_y)}" '
+                f'stroke="{footer_cfg.rule.color}" stroke-width="{_format_svg_numeric(footer_cfg.rule.stroke_width)}"/>'
+            )
+        footer_parts.append(
+            f'<text x="{_format_svg_numeric(footer_x)}" y="{_format_svg_numeric(footer_y)}" text-anchor="end" '
+            f'font-size="{_format_svg_numeric(float(footer_cfg.font.size))}" fill="{footer_cfg.font.color}" font-family="{face.style.font.family}">'
+            f"{html.escape(rendering_cfg.footer_text)}</text>"
+        )
+        footer_element = "\n".join(footer_parts)
+
+    return f"""<svg id="{svg_id}" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {total_width} {total_height}" width="100%" preserveAspectRatio="xMinYMin meet" style="display: block;" data-rendered-at="{render_timestamp_iso}">
+<defs>
+{grid_defs}
+{svg_styles}
+</defs>
+{bg_rect}
+{"".join(content_items)}
+{margin_lines}
+{timestamp_element}
+{footer_element}
+{variables_script}
+{chart_interactivity_script}
+</svg>"""
+
+
+def render_nested_face(
+    face: MergedFace,
+    executor: Executor,
+    variables: VariableValues,
+    available_width: float,
+    available_height: float,
+    card_gap: float,
+    interactive: bool = True,
+    render_cache: dict[tuple[str, float, float], tuple[str, float]] | None = None,
+    error_collector: list[StructuredError] | None = None,
+) -> tuple[str, float]:
+    """Render a nested face.
+
+    Args:
+        face: MergedFace for the nested face (board config fields are None).
+        executor: Executor for query execution
+        variables: Variable values for queries
+        available_width: Width in pixels for the face
+        card_gap: Gap between cards (inter-item spacing)
+        interactive: Whether to render interactive variable controls (foreignObject).
+                     Set to False for PNG/PDF export.
+        available_height: Pre-allocated slot height from parent layout (e.g. cols max
+                          height). When provided, the face renders at least this tall so
+                          all siblings in a cols row share the same height.
+
+    Returns:
+        (svg_string, actual_height) — actual_height is derived from rendered content.
+    """
+
+    resolved_style = face.style  # MergedFace.style is the MergedStyle
+
+    gap = resolved_style.gap if resolved_style.gap is not None else 0.0
+    ep = _effective_padding(resolved_style)
+
+    # Trust the normalizer - content dimensions are always set by sizing.py
+    layout_content_width = face.layout.content_width
+    layout_content_height = face.layout.content_height
+
+    card_pad = float(resolved_style.board.card_padding)
+    title_text_width = max(layout_content_width - 2 * card_pad, 0.0)
+
+    face_width = available_width - (
+        resolved_style.margin.horizontal if resolved_style.margin else 0.0
+    )
+    text_align = resolved_style.text.align
+
+    from dataface.core.compile.typography import is_prose
+
+    prose = is_prose(face.text) if face.text else False
+
+    inline_header_svg = ""
+    inline_header_height = 0.0
+    title_svg = ""
+    title_height = 0.0
+    if _face_uses_title_inline_band(face):
+        inline_header_svg, inline_header_height = _render_title_variables_inline_band(
+            face,
+            variables,
+            layout_content_width,
+            card_pad,
+            interactive,
+            executor,
+            text_align=text_align,
+            prose=prose,
+        )
+    elif face.title:
+        from dataface.core.compile.sizing import get_title_height
+
+        title_svg = _render_title_svg(
+            face.title,
+            variables,
+            title_text_width or layout_content_width,
+            text_align,
+            level=face.level,
+            prose=prose,
+            resolved_style=resolved_style,
+        )
+        title_height = max(
+            get_title_height(
+                face.title,
+                title_text_width or layout_content_width,
+                face.variable_defaults,
+                level=face.level,
+            ),
+            float(face.style.title.min_height),
+        )
+
+    # Render text (markdown) if present (using shared helper)
+    text_svg = ""
+    text_height = 0.0
+    if face.text:
+        text_svg, text_height = _render_text_svg(
+            face.text,
+            variables,
+            title_text_width or layout_content_width,
+            text_align=text_align,
+            prose=prose,
+            resolved_style=resolved_style,
+            text_style=resolved_style.text,
+        )
+
+    # Render variable controls for this nested face's local variables.
+    # Interactive: foreignObject HTML controls (variables.js in the root SVG exposes
+    # window.updateVariable globally, accessible from all foreignObject contexts).
+    # Non-interactive (PNG/PDF): plain SVG text labels showing current values.
+    nested_variables_svg = ""
+    nested_variables_height = 0.0
+    # Variable controls are inset by card_pad on the left (aligned with chart
+    # content); reduce width by the same amount so the right edge is unchanged.
+    nested_variables_width = max(layout_content_width - card_pad, 0.0)
+    if face.visible_variables and variables and not inline_header_svg:
+        from dataface.core.render.variable_controls import (
+            render_interactive_variables_svg,
+            render_variables_svg,
+        )
+
+        if interactive:
+            nested_variables_svg, nested_variables_height = (
+                render_interactive_variables_svg(
+                    face.visible_variables,
+                    variables,
+                    nested_variables_width,
+                    executor,
+                    resolved_style=resolved_style,
+                )
+            )
+        else:
+            nested_variables_svg, nested_variables_height = render_variables_svg(
+                face.visible_variables,
+                variables,
+                nested_variables_width,
+                resolved_style=resolved_style,
+            )
+
+    # _calculate_nested_face_layout deducted variable controls height from
+    # face.layout.content_height. Pass that as the layout slot hint. The actual
+    # rendered height is read back from the layout renderer below.
+    authored_bg = resolved_style.background
+    layout_content, actual_layout_height = _render_layout(
+        face,
+        executor,
+        variables,
+        layout_content_width,
+        layout_content_height,
+        card_gap,
+        gap,
+        authored_bg,
+        interactive,
+        render_cache,
+        error_collector=error_collector,
+    )
+
+    # Apply face-level title color overrides before building items. Same
+    # precedence as the inline-band path: `style.title.font.color` first
+    # (the canonical "face title color" knob), `style.color` as a face-wide
+    # ink fallback. Painting happens AFTER mdsvg renders so the override
+    # wins over mdsvg's CSS-baked class fill regardless of upstream cascade
+    # quirks in get_compact_style.
+    title_color = resolved_style.title.font.color or resolved_style.color
+    if title_color and title_svg:
+        title_svg = _paint_title_svg_fill(title_svg, str(title_color))
+
+    # Combine title, text, variables, and layout into positioned groups.
+    # Gap is added only between adjacent elements (matches sizing's gap*(n-1) formula).
+    # Title positioning: mdsvg handles x position and text-anchor from text_align.
+    # Use actual_layout_height (from rendered content) so Vega charts that render
+    # taller than their pre-computed slot expand the face rather than being clipped.
+    inner_items, inner_items_height = _build_face_content_items(
+        x_offset=ep.left,
+        y_offset=ep.top,
+        gap=gap,
+        title_svg=title_svg,
+        title_height=title_height,
+        text_svg=text_svg,
+        text_height=text_height,
+        variables_svg=nested_variables_svg,
+        variables_height=nested_variables_height,
+        layout_content=layout_content,
+        layout_content_height=actual_layout_height,
+        card_padding=card_pad,
+        inline_header_svg=inline_header_svg,
+        inline_header_height=inline_header_height,
+    )
+
+    # Compute face dimensions from actual rendered content, floored at the pre-allocated
+    # slot height from the parent layout (e.g. cols max height) so all siblings share
+    # the same height.  Content overflow still expands beyond the slot.
+    natural_face_height = ep.top + inner_items_height + ep.bottom
+    face_margin_vertical = (
+        resolved_style.margin.vertical if resolved_style.margin else 0.0
+    )
+    face_margin_left = resolved_style.margin.left if resolved_style.margin else 0.0
+    face_margin_top = resolved_style.margin.top if resolved_style.margin else 0.0
+    allocated_face_height = max(available_height - face_margin_vertical, 0.0)
+    face_height = max(natural_face_height, allocated_face_height)
+    total_svg_width = available_width
+    total_svg_height = face_height + face_margin_vertical
+
+    bg_rect = ""
+    border_rect = ""
+    border_radius = resolved_style.border.radius
+
+    if authored_bg:
+        bg = html.escape(str(authored_bg))
+        bg_rect = f'<rect x="0" y="0" width="{face_width}" height="{face_height}" fill="{bg}" rx="{border_radius}"/>'
+
+    border_width = resolved_style.border.width
+    border_color = resolved_style.border.color
+    if border_width > 0 and border_color:
+        stroke_width = border_width
+        stroke_color = html.escape(border_color)
+        stroke_inset = stroke_width / 2.0
+        border_rect = (
+            f'<rect x="{stroke_inset}" y="{stroke_inset}" '
+            f'width="{max(face_width - stroke_width, 0)}" '
+            f'height="{max(face_height - stroke_width, 0)}" '
+            f'fill="none" stroke="{stroke_color}" stroke-width="{stroke_width}" '
+            f'rx="{max(border_radius - stroke_inset, 0)}"/>'
+        )
+
+    face_group = f"""<g transform="translate({_px(face_margin_left)}, {_px(face_margin_top)})">
+{bg_rect}
+{border_rect}
+{"".join(inner_items)}
+</g>"""
+
+    svg = f"""<svg width="{total_svg_width}" height="{total_svg_height}" viewBox="0 0 {total_svg_width} {total_svg_height}">
+{face_group}
+</svg>"""
+    return svg, total_svg_height