dataface 0.1.2__py3-none-any.whl

dataface/core/compile/sizing.py

@@ -0,0 +1,2126 @@
+"""Layout sizing calculation module.
+
+Purpose: Calculate dimensions for layout items using static/compile-time defaults.
+
+Entry Points:
+    - calculate_layout(face) -> Face
+      Compile-time sizing — uses aspect ratios and config defaults for all heights.
+
+Data-aware sizing (render-first Vega sizing, table row counts) lives in
+render/layout_sizing.py and injects a HeightProvider callback into these
+algorithms at render time.
+
+Inputs:
+    - Face with layout but no dimensions
+
+Outputs:
+    - Face with calculated width/height on all layout items
+
+Key Principles:
+    1. Height is determined by layout AND content type
+       - KPIs get smaller heights (100px default)
+       - Charts get standard heights (300px default)
+       - Titles/content heights are estimated based on text/font
+       - In cols: all items have the SAME height (max of required heights)
+       - In rows: each item gets its content-appropriate height
+
+    2. Width is determined by layout type
+       - In cols: width is divided among items equally (by default)
+       - In rows: all items get full width
+
+    3. Padding philosophy
+       - Charts have internal padding (handled by Vega-Lite config)
+       - Boards have NO padding unless explicitly set in style
+       - Root dashboard has page padding (handled in renderer)
+
+    4. Nested layouts follow these rules recursively
+       - A nested rows layout inside a cols item gets the full height of that item
+       - Items within that nested layout then divide that height
+
+Example:
+    cols:
+      - chart1           # Gets 50% width, 100% height
+      - rows:            # Gets 50% width, 100% height
+          - chart2       # Gets 100% width of parent, 50% of parent height
+          - chart3       # Gets 100% width of parent, 50% of parent height
+
+    Result with 800x400 container:
+    ┌────────────────────┬────────────────────┐
+    │                    │      chart2        │
+    │      chart1        │   400x200px        │
+    │    400x400px       ├────────────────────┤
+    │                    │      chart3        │
+    │                    │   400x200px        │
+    └────────────────────┴────────────────────┘
+
+Dependencies:
+    - .models.face.compiled (Face, Layout, LayoutItem)
+    - .config (CompileConfig)
+
+See also:
+    - compile/normalizer.py: Previous step
+    - compile/compiler.py: Orchestrates all steps
+
+Cross-module API:
+    render/layout_sizing.py imports the following functions as part of the
+    HeightProvider injection pattern.  They are sizing algorithm internals
+    intentionally exported for use by the data-aware render-time sizing pass:
+        calculate_layout_height, calculate_layout_items,
+        get_item_content_height
+"""
+
+from __future__ import annotations
+
+import functools
+import re
+from typing import TYPE_CHECKING, Any, Literal, Protocol
+
+from PIL import ImageFont
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.face.compiled import ResolvedLayoutItem
+    from dataface.core.compile.models.style.compiled import TextStyle
+
+from dataface.core.compile.colors import is_dark_color
+from dataface.core.compile.config import get_chart_rendering, get_config
+from dataface.core.compile.jinja import resolve_jinja_template
+from dataface.core.compile.models.chart.compiled import (
+    Chart,
+)
+from dataface.core.compile.models.face.compiled import (
+    Face,
+    Layout,
+    LayoutItem,
+)
+from dataface.core.compile.models.style.compiled import (
+    VariablesStyle,
+    compute_text_column_count,
+)
+from dataface.core.compile.models.style.merged import (
+    MergedStyle,
+    apply_emoji_to_family,
+    effective_padding as _effective_padding,
+    resolve_style,
+)
+from dataface.core.fonts import get_inter_font_path
+
+# ============================================================================
+# CONTENT-AWARE HEIGHT DEFAULTS
+# ============================================================================
+
+# Default heights for different content types
+# WHY: compile-time static fallback used when no width for aspect-ratio sizing
+# and no specific chart type match; real sizes come from width-driven aspect-ratio path.
+DEFAULT_CHART_HEIGHT = 300.0
+# WHY: compile-time placeholder only — replaced by data-aware row-count sizing at
+# render time via HeightProvider; no cascade equivalent exists because table height
+# is always data-driven.
+DEFAULT_TABLE_HEIGHT = 250.0
+# WHY: engine-intrinsic display floor — every layout item must be at least this tall
+# to remain navigable. Not a theme value; it is a display-correctness invariant.
+MIN_CONTENT_HEIGHT = 60.0
+
+# Bottom breathing room under the title-inline header band before the first
+# row of layout content. The band's natural height (max of title-block vs
+# variable-controls heights) butts directly against the first card row, and
+# the theme's effective inter-section gap (face.layout.gap, ~8px default) is
+# too tight for a face title to read as a header rather than a column label.
+# 24 px lands between the "8 px + theme gap reads tight" and "32 px reads
+# disconnected" endpoints picked in the design exploration.
+TITLE_INLINE_BAND_BOTTOM_PAD = 24.0
+
+
+# ============================================================================
+# HEIGHT PROVIDER PROTOCOL
+# ============================================================================
+
+
+class HeightProvider(Protocol):
+    """Callback that returns the content height for a layout item.
+
+    The compile-time path uses the built-in get_item_content_height (static,
+    aspect-ratio-based). The render-time path injects a data-aware provider
+    from render/layout_sizing.py that renders Vega charts and queries data.
+    """
+
+    def __call__(
+        self,
+        item: LayoutItem,
+        card_gap: float,
+        gap: float,
+        width: float,
+        variable_defaults: dict[str, Any] | None,
+    ) -> float: ...
+
+
+def _resolve_height(
+    item: LayoutItem,
+    card_gap: float,
+    gap: float,
+    width: float,
+    variable_defaults: dict[str, Any] | None,
+    height_provider: HeightProvider | None,
+    resolved_style: MergedStyle,
+) -> float:
+    """Dispatch to height_provider if set, else use static get_item_content_height."""
+    if height_provider is not None:
+        return height_provider(item, card_gap, gap, width, variable_defaults)
+    return get_item_content_height(
+        item,
+        card_gap,
+        gap,
+        width,
+        variable_defaults,
+        height_provider=None,
+        resolved_style=resolved_style,
+    )
+
+
+def _get_root_content_width(config: Any) -> float:
+    """Return the root face content width after page padding is removed."""
+    return max(
+        float(config.style.board.width) - (2 * float(config.style.board.margin)), 0.0
+    )
+
+
+def get_chart_content_height(
+    chart: Chart | None,
+    *,
+    width: float | None = None,
+    resolved_style: MergedStyle,
+) -> float:
+    """Get the appropriate content height for a chart based on its type.
+
+    Resolution order for plot-style charts (bar, line, area, scatter, …):
+      1. chart.height — explicit chart-root override; returned as-is (no clamping).
+      2. chart.aspect_ratio — chart-root fallback; height = width / aspect_ratio,
+         clamped to theme min_height / max_height.
+      3. Per-family theme aspect_ratio (e.g. style.charts.bar.aspect_ratio).
+      4. Global theme aspect_ratio (style.charts.aspect_ratio).
+      5. DEFAULT_CHART_HEIGHT when no width is available.
+
+    SVG-family renderers own their own sizing contract:
+      - kpi    → resolved_style.charts.kpi.default_height (theme cascade)
+      - table  → DEFAULT_TABLE_HEIGHT (replaced by row-count sizing at render)
+      - callout → MIN_CONTENT_HEIGHT (replaced by natural render-first sizing)
+      - spark_bar → config-derived upper bound from max_bars/bar.height
+
+    This is the compile-time (static) height calculator. It uses aspect ratios
+    and config defaults only — no executor, no data, no rendering.
+    Layout slot height (``LayoutItem.layout_height``) wins at render time when
+    authored; the render-first pass in ``render/layout_sizing.py`` uses this
+    value as a fallback when no explicit slot height is declared.
+
+    Args:
+        chart: The compiled chart to get height for
+        width: Available width in pixels; enables aspect-ratio-driven sizing
+        resolved_style: Face-resolved style; KPI height reads from
+            resolved_style.charts.kpi.default_height.
+
+    Returns:
+        Appropriate height in pixels for this chart type
+    """
+    if chart is None:
+        return DEFAULT_CHART_HEIGHT
+
+    chart_type = chart.type
+    if chart_type == "kpi":
+        return float(resolved_style.charts.kpi.default_height)
+    elif chart_type == "table":
+        return DEFAULT_TABLE_HEIGHT
+    elif chart_type == "callout":
+        # Render-first natural sizing overrides this at render time.
+        return MIN_CONTENT_HEIGHT
+    elif chart_type == "spark_bar":
+        # Compile-time upper bound using max_bars. Render-first data-aware sizing
+        # in layout_sizing.py overrides this with the actual natural height.
+        # Includes title_height when chart.title is set to match the renderer's
+        # body + title addition (spark_bar.py:265-269).
+        sb = get_config().style.charts.spark_bar
+        body = sb.max_bars * (sb.bar.height + sb.bar.padding) + sb.bar.padding
+        return (
+            body + get_chart_rendering().spark_bar.title_height if chart.title else body
+        )
+
+    # Step 1: explicit chart-root height wins everything (no clamping).
+    if chart.height is not None:
+        return float(chart.height)
+
+    # Steps 2–4: aspect-ratio-driven sizing for plot-style charts.
+    if width is not None and width > 0:
+        config = get_config()
+        # Resolve clamps: start from face/theme resolved_style, override with
+        # chart-root min_height / max_height when explicitly set by the author.
+        min_h = (
+            float(chart.min_height)
+            if chart.min_height is not None
+            else float(resolved_style.charts.min_height)
+        )
+        max_h = (
+            float(chart.max_height)
+            if chart.max_height is not None
+            else float(resolved_style.charts.max_height)
+        )
+        # Step 2: chart-root aspect_ratio (validated gt=0 at compile time).
+        if chart.aspect_ratio is not None:
+            h = width / chart.aspect_ratio
+            return max(min_h, min(max_h, h))
+        # Steps 3–4: per-family theme aspect_ratio, then global theme default.
+        style_key = chart_type
+        type_config = getattr(config.style.charts, style_key, None)
+        aspect = (
+            float(type_config.aspect_ratio)
+            if type_config
+            and hasattr(type_config, "aspect_ratio")
+            and type_config.aspect_ratio
+            else float(config.style.charts.aspect_ratio)
+        )
+        if aspect > 0:
+            h = width / aspect
+            return max(min_h, min(max_h, h))
+
+    return DEFAULT_CHART_HEIGHT
+
+
+def is_item_collapsed_summary(
+    item: LayoutItem,
+    variable_defaults: dict[str, Any] | None,
+) -> bool:
+    return bool(
+        item.details_variable
+        and item.details_summary
+        and not _is_details_item_expanded(item, variable_defaults)
+    )
+
+
+def _is_details_item_expanded(
+    item: LayoutItem, variables: dict[str, Any] | None
+) -> bool:
+    """Check if a details item is expanded based on variable value or default."""
+    if variables and item.details_variable in variables:
+        return str(variables[item.details_variable]).lower() == "true"
+    # Fall back to default from face meta
+    if item.face and item.face.meta:
+        return bool(item.face.meta.get("details_expanded_default", False))
+    return False
+
+
+def details_chrome_height(
+    item: LayoutItem | ResolvedLayoutItem, gap: float, card_gap: float
+) -> float:
+    """Vertical overhead the details chrome adds above the nested face content.
+
+    Returns summary_height + gap + card_gap for details items, 0 otherwise.
+    Both the sizing pass and render pass must use this so they stay in sync.
+    """
+    if not (item.details_variable and item.details_summary):
+        return 0.0
+    return float(get_config().style.layout.details.summary_height) + gap + card_gap
+
+
+def get_compact_style(
+    merged_style: MergedStyle | None = None,
+    text_align: Literal["left", "center", "right"] = "left",
+    heading_font_weight: int | str | None = None,
+    font_family: str | None = None,
+    h1_size: float | None = None,
+) -> Any:
+    """Get a compact mdsvg Style with reduced heading margins.
+
+    The default mdsvg style has large heading margins (1.5em top, 0.5em bottom)
+    which produces ~2x more vertical space than HTML. This compact style
+    reduces margins for tighter dashboard/UI layouts.
+
+    Heading sizes (h1–h6) are pinned to absolute pixel values from
+    ``style.title.sizes`` rather than computed as multiples of the body font
+    size. Heading weight defaults to ``style.title.font.weight``; heading
+    color comes from the markdown color set or ``style.title.font.color``.
+
+    Args:
+        merged_style: Optional MergedStyle for color resolution. Falls back to
+            the global config default when None.
+        heading_font_weight: Override the heading font weight. Face titles pass
+            the tier-specific weight (600 narrow, 500 medium/wide).
+        font_family: Override the body font family. Pass
+            ``config.style.title.font.family`` to render prose in serif.
+        h1_size: Override the h1 pixel size. Face titles pass the
+            width-resolved pixel size from ``face_title_spec`` so the rendered
+            h1 lands exactly on the responsive target. When ``None``, h1 uses
+            ``style.title.sizes[0]`` like the other levels.
+
+    Returns:
+        mdsvg Style object with compact margins and theme-appropriate colors
+    """
+    from dataface.core.compile.typography import _coerce_weight
+    from mdsvg import Style
+
+    config = get_config()
+    _ms = merged_style or resolve_style(config.style)
+    markdown_colors = (
+        config.markdown.dark if is_dark_color(_ms.background) else config.markdown.light
+    )
+    _text_font_size = config.style.text.font.size
+    assert _text_font_size is not None, "style.text.font.size must be configured"
+
+    _root_family = config.style.font.family
+    assert _root_family is not None, "style.font.family must be configured"
+    _default_family = apply_emoji_to_family(_root_family, config.style.font.emoji)
+
+    title_sizes = config.style.title.sizes
+    if len(title_sizes) != 6:
+        raise ValueError(
+            f"style.title.sizes must have 6 entries (H1-H6); got {len(title_sizes)}"
+        )
+
+    effective_weight = (
+        heading_font_weight
+        if heading_font_weight is not None
+        else _coerce_weight(config.style.title.font.weight or 500)
+    )
+
+    return Style(
+        font_family=font_family if font_family is not None else _default_family,
+        base_font_size=float(_text_font_size),
+        line_height=float(config.style.text.line_height),
+        heading_margin_top=0.3,
+        heading_margin_bottom=0.2,
+        paragraph_spacing=8.0,
+        text_color=getattr(markdown_colors, "text_color", _ms.font.color),
+        heading_color=(
+            getattr(markdown_colors, "heading_color", None) or _ms.title.font.color
+        ),
+        link_color=markdown_colors.link_color,
+        code_color=markdown_colors.code_color,
+        code_background=markdown_colors.code_background,
+        blockquote_color=markdown_colors.blockquote_color,
+        text_align=text_align,
+        # Top-align letterboxed markdown images (default xMidYMid centers them).
+        image_preserve_aspect_ratio="xMidYMin meet",
+        h1_size=float(h1_size) if h1_size is not None else float(title_sizes[0]),
+        h2_size=float(title_sizes[1]),
+        h3_size=float(title_sizes[2]),
+        h4_size=float(title_sizes[3]),
+        h5_size=float(title_sizes[4]),
+        h6_size=float(title_sizes[5]),
+        heading_font_weight=effective_weight,
+        heading_line_height=float(config.style.title.line_height),
+    )
+
+
+def greedy_column_fill(
+    block_heights: list[float],
+    n_cols: int,
+    para_gap: float,
+) -> tuple[list[tuple[int, float]], float]:
+    """Assign blocks to columns using a greedy balanced fill.
+
+    Returns (assignments, actual_col_height) where assignments[i] = (col_idx, y_within_col).
+    Never breaks from an empty column (current_y > 0 guard).
+    """
+    if not block_heights:
+        return [], 0.0
+    total_content = sum(block_heights)
+    total_gaps = para_gap * (len(block_heights) - 1) if len(block_heights) > 1 else 0
+    target_col_height = (total_content + total_gaps) / n_cols
+
+    assignments: list[tuple[int, float]] = []
+    col_max_y = [0.0] * n_cols
+    current_col = 0
+    current_y = 0.0
+    for i, bh in enumerate(block_heights):
+        gap_before = para_gap if i > 0 and current_y > 0 else 0.0
+        if (
+            current_y > 0
+            and current_y + gap_before + bh > target_col_height
+            and current_col < n_cols - 1
+        ):
+            current_col += 1
+            current_y = 0.0
+            gap_before = 0.0
+        y_in_col = current_y + gap_before
+        assignments.append((current_col, y_in_col))
+        col_max_y[current_col] = max(col_max_y[current_col], y_in_col + bh)
+        current_y = y_in_col + bh
+
+    return assignments, max(col_max_y)
+
+
+def columned_text_height_estimate(
+    resolved_text: str,
+    width: float,
+    text_style: TextStyle,
+    style: Any,
+    font_path: str,
+) -> float:
+    """Compute multi-column body-text height using the same greedy block-fill algorithm as the renderer."""
+    from dataface.core.fonts import get_mono_font_path
+    from mdsvg import measure as measure_markdown, parse as parse_markdown
+    from mdsvg.renderer import SVGRenderer
+
+    mono_font_path = str(get_mono_font_path())
+
+    col = text_style.column
+    column_gap = (
+        col.gap if col.gap is not None else float(get_config().style.layout.rows.gap)
+    )
+    n_cols = compute_text_column_count(col, width, column_gap)
+
+    if n_cols <= 1:
+        size = measure_markdown(
+            resolved_text,
+            width=width,
+            padding=0.0,
+            style=style,
+            font_path=font_path,
+            mono_font_path=mono_font_path,
+        )
+        return size.height
+
+    per_col_width = max(
+        (width - (n_cols - 1) * column_gap) / n_cols,
+        1.0,
+    )
+    renderer = SVGRenderer(
+        style=style,
+        font_path=font_path,
+        mono_font_path=mono_font_path,
+    )
+    blocks = list(parse_markdown(resolved_text))
+    block_heights = [
+        renderer.measure([block], width=per_col_width, padding=0.0).height
+        for block in blocks
+    ]
+    _, actual_col_height = greedy_column_fill(
+        block_heights, n_cols, style.paragraph_spacing
+    )
+    return actual_col_height
+
+
+def get_markdown_text_height(
+    text: str | None,
+    width: float,
+    variable_defaults: dict[str, Any] | None = None,
+    *,
+    text_style: TextStyle | None = None,
+) -> float:
+    """Get the actual height needed for markdown content by measuring it.
+
+    Uses mdsvg's measure() to calculate height, which accounts for
+    word-wrapping and all markdown features.
+
+    When text_style specifies multi-column layout (column.number > 1 or
+    column.width), delegates to columned_text_height_estimate for an accurate
+    per-column-width measurement.
+
+    Args:
+        text: The markdown text
+        width: Available width for the text
+        variable_defaults: Optional variable defaults for Jinja resolution
+        text_style: Optional face body-text style for multi-column layout
+
+    Returns:
+        Actual height in pixels for the rendered content
+    """
+    if not text:
+        return 0.0
+
+    from dataface.core.compile.jinja import resolve_jinja_template
+    from dataface.core.fonts import get_inter_font_path, get_mono_font_path
+    from mdsvg import measure as measure_markdown
+
+    resolved_content = resolve_jinja_template(
+        text, variable_defaults or {}, strict=False
+    )
+
+    font_path = str(get_inter_font_path())
+    style = get_compact_style(resolve_style(get_config().style))
+
+    if text_style is not None and text_style.column.has_overrides:
+        return columned_text_height_estimate(
+            resolved_content, width, text_style, style, font_path
+        )
+
+    # Measure the markdown to get actual dimensions (using compact style).
+    # text_align is intentionally omitted: mdsvg measure() only computes
+    # line-wrapped height, which is independent of horizontal alignment.
+    size = measure_markdown(
+        resolved_content,
+        width=width,
+        padding=0.0,
+        style=style,
+        font_path=font_path,
+        mono_font_path=str(get_mono_font_path()),
+    )
+    return size.height
+
+
+def get_title_height(
+    title: str | None,
+    width: float,
+    variable_defaults: dict[str, Any] | None = None,
+    level: int = 1,
+) -> float:
+    """Get the actual height needed for a title by measuring it.
+
+    Uses mdsvg's measure() to calculate height for the title rendered
+    as a markdown heading, accounting for word-wrapping and font sizing.
+    Font size is determined by card pixel width (width-based tier).
+
+    Args:
+        title: The title text
+        width: Available width for the title (drives tier selection)
+        variable_defaults: Optional variable defaults for Jinja resolution
+
+    Returns:
+        Actual height in pixels for the rendered title
+    """
+    if not title:
+        return 0.0
+
+    from dataface.core.compile.jinja import resolve_jinja_template
+    from dataface.core.fonts import get_inter_font_path, get_mono_font_path
+    from mdsvg import measure as measure_markdown
+
+    # Resolve any Jinja templates using variable defaults
+    resolved_title = resolve_jinja_template(
+        title, variable_defaults or {}, strict=False
+    )
+
+    from dataface.core.compile.typography import face_title_markdown
+
+    markdown_title, h1_size, heading_weight = face_title_markdown(
+        resolved_title, width, level=level
+    )
+
+    # Measure the markdown to get actual dimensions (using compact style).
+    # text_align is intentionally omitted: mdsvg measure() only computes
+    # line-wrapped height, which is independent of horizontal alignment.
+    font_path = str(get_inter_font_path())
+    size = measure_markdown(
+        markdown_title,
+        width=width,
+        padding=0.0,
+        style=get_compact_style(
+            h1_size=h1_size,
+            heading_font_weight=heading_weight,
+        ),
+        font_path=font_path,
+        mono_font_path=str(get_mono_font_path()),
+    )
+
+    return size.height
+
+
+def get_face_gap(face: Face) -> float:
+    """Return the row/col/grid gap for a face based on its layout type.
+
+    When card_gap is active the gap is always 0 — spacing is owned by the
+    margin, not the individual layout rows/cols/grid.  Otherwise the gap comes
+    from the layout-type-specific config key.
+    """
+    config = get_config()
+    if face.card_gap:
+        return 0.0
+    if face.layout.type == "rows":
+        return float(config.style.layout.rows.gap)
+    if face.layout.type == "cols":
+        return float(config.style.layout.cols.gap)
+    if face.layout.type == "grid":
+        return float(config.style.layout.grid.gap)
+    return 0.0
+
+
+# ============================================================================
+# VARIABLE CONTROLS HEIGHT (moved from render/variable_controls.py)
+# ============================================================================
+
+# Minimum title column width when sharing a row with variables so titles never
+# collapse to zero when the variable strip is very wide.
+_MIN_TITLE_INLINE_TITLE_COLUMN_PX = 48.0
+# Hard ceiling on title column width as a fraction of the band's inner width.
+# At 0.8, pathologically long titles wrap before they can eliminate the
+# variables column — the strip stays parseable even when authors give a face
+# a 60-character title and 7 filters.
+_TITLE_INLINE_TITLE_MAX_INNER_RATIO = 0.8
+
+# Strip a leading `#+\s+` markdown heading prefix without eating standalone
+# `#` characters or trailing punctuation — `lstrip("# ")` would mangle titles
+# like "#1 Product" or "## Q3 ##".
+_HEADING_PREFIX_RE = re.compile(r"^#+\s+")
+
+
+def _measure_title_single_line_width(
+    title: str | None,
+    variable_defaults: dict[str, Any] | None = None,
+) -> float:
+    """Width the title text needs to render on a single line at its natural size.
+
+    Uses PIL's freetype-backed ImageFont on the wheel-shipped Inter font at
+    the largest title-tier size — measuring at the widest tier gives the
+    worst-case natural width, which is what the title-inline band reserves
+    at full inner width. mdsvg's measure() can't be used here — it returns
+    the constraint width when passed an unbounded width, not the natural
+    content extent.
+    """
+    if not title:
+        return 0.0
+
+    resolved = resolve_jinja_template(title, variable_defaults or {}, strict=False)
+    # Strip a leading `#+\s+` markdown heading prefix without eating standalone
+    # `#` characters or trailing punctuation — `lstrip("# ")` would mangle
+    # titles like "#1 Product" or "## Q3 ##".
+    plain = _HEADING_PREFIX_RE.sub("", resolved).strip()
+
+    h1_size = float(get_config().style.title.sizes[0])
+    return float(_load_title_font(h1_size).getlength(plain))
+
+
+@functools.lru_cache(maxsize=8)
+def _load_title_font(size_px: float) -> ImageFont.FreeTypeFont:
+    """Load the Inter title font at the requested size, cached.
+
+    `_measure_title_single_line_width` is called per-face during both sizing
+    and render; without caching, ImageFont.truetype reparses the .ttf file
+    on every call. The cache is bounded — `size_px` comes from the title
+    tier ramp (6 entries) plus the level-driven offsets, so `maxsize=8`
+    covers every realistic call site.
+    """
+    return ImageFont.truetype(str(get_inter_font_path()), size_px)
+
+
+def resolve_title_variables_inline_widths(
+    inner: float,
+    variables_style: VariablesStyle,
+    visible_variables: dict[str, Any],
+    title: str | None = None,
+    variable_defaults: dict[str, Any] | None = None,
+) -> tuple[float, float]:
+    """Split inner title+variables width into (title_w, variables_w).
+
+    Title precedence: reserve the title's measured single-line width first,
+    give the rest to variables, and let the variables strip flex-wrap into
+    multiple rows when its share is too narrow for one row. ``compute_
+    variable_controls_height`` handles the multi-row height so the band
+    grows correctly.
+
+    ``title_inline_title_max_width`` (theme) still caps the title when > 0;
+    a hard ceiling of 80% of inner protects pathologically long titles from
+    eliminating the variables column entirely (title wraps before that).
+    """
+    col_gap = float(variables_style.gap)
+    if not visible_variables:
+        return max(inner, 1.0), 0.0
+
+    # Title's natural single-line width + a small breathing-room pad so the
+    # measured width doesn't wrap on sub-pixel rendering jitter.
+    natural = _measure_title_single_line_width(title, variable_defaults)
+    natural_with_pad = (
+        natural + 8.0 if natural > 0 else _MIN_TITLE_INLINE_TITLE_COLUMN_PX
+    )
+
+    # Hard ceiling: never let the title eat more than this fraction of inner,
+    # even when natural width is larger — keeps the variables column wide
+    # enough that authors see their filters before having to wrap.
+    title_w = min(natural_with_pad, inner * _TITLE_INLINE_TITLE_MAX_INNER_RATIO)
+    title_w = max(title_w, _MIN_TITLE_INLINE_TITLE_COLUMN_PX)
+
+    # Theme-level override still wins when set.
+    cap = float(variables_style.title_inline_title_max_width)
+    if cap > 0.0:
+        title_w = min(title_w, cap)
+
+    vars_w = max(inner - title_w - col_gap, 1.0)
+    return title_w, vars_w
+
+
+def _estimate_control_width(
+    var_name: str, var_def: Any, variables_style: VariablesStyle
+) -> float:
+    """Estimate the rendered pixel width of a single variable control."""
+    label = (var_def.label or var_name.replace("_", " ").title()) + ":"
+    assert variables_style.font.size is not None
+    label_w = len(label) * variables_style.font.size * 0.6
+    input_cfg = variables_style.input
+    input_type = var_def.input
+
+    if input_type in ("select", "multiselect", "radio"):
+        input_w = 120.0
+    elif input_type in ("text", "input", "textarea"):
+        input_w = float(input_cfg.widths.text)
+    elif input_type == "number":
+        input_w = float(input_cfg.widths.number)
+    elif input_type in ("slider", "range"):
+        input_w = (
+            float(input_cfg.widths.range)
+            + variables_style.control_gap
+            + float(input_cfg.widths.slider_value_min)
+        )
+    elif input_type == "checkbox":
+        return float(input_cfg.widths.checkbox) + variables_style.control_gap + label_w
+    elif input_type in ("date", "datepicker"):
+        input_w = 120.0
+    elif input_type == "daterange":
+        input_w = float(input_cfg.widths.daterange)
+    else:
+        input_w = float(input_cfg.widths.text)
+
+    return label_w + variables_style.control_gap + input_w
+
+
+def compute_title_variables_inline_baseline_layout(
+    title_h: float,
+    vars_h: float,
+    label_font_size: float,
+) -> tuple[float, float, float]:
+    """Baseline-aligned layout for the title-inline band.
+
+    Returns ``(title_dy, vars_dy, band_h)`` — the y-translation each column
+    needs to land its first text baseline at the same shared baseline, plus
+    the total band height that results.
+
+    The ratios below are empirical, measured against the actual mdsvg /
+    foreignObject output for face titles at the default Inter weight:
+
+    - **Title baseline at 81.25% of title-block height.** mdsvg renders heading
+      text with a 1.3-line-height box plus its own block padding, putting the
+      first baseline at ``font_size * 1.3`` from the title-block top. Divided
+      by the block height (``font_size * 1.6`` for the default tier), that's
+      ``0.8125``. Pinned to the measured ratio so the rendered title and the
+      variable-label baseline land within sub-pixel of each other across font
+      tiers; do not "guess" with a rounded 0.85.
+    - **Label baseline ≈ container vertical center + 35% of label font size.**
+      Variable controls use ``align-items: center`` inside a ``container_height``
+      flex row; the centered label's baseline lands roughly half a label-em
+      below the container's vertical center.
+
+    Both columns are then shifted so the deeper baseline becomes the shared
+    target, which guarantees neither column extends above the band's top edge.
+    """
+    title_baseline = title_h * 0.8125
+    vars_baseline = vars_h / 2.0 + label_font_size * 0.35
+    target = max(title_baseline, vars_baseline)
+    title_dy = target - title_baseline
+    vars_dy = target - vars_baseline
+    band_h = max(title_dy + title_h, vars_dy + vars_h) + TITLE_INLINE_BAND_BOTTOM_PAD
+    return title_dy, vars_dy, band_h
+
+
+def compute_title_variables_inline_band_height(
+    face: Face,
+    content_width: float,
+    variable_defaults: dict[str, Any] | None = None,
+) -> float:
+    """Band height for ``variables.position: title-inline``.
+
+    Computes the height the baseline-aligned band needs to fit both columns.
+    Delegates to :func:`compute_title_variables_inline_baseline_layout` so the
+    sizing pass and the render pass share one source of truth.
+    """
+    vs = face.resolved_style.variables
+    card_pad = float(face.resolved_style.board.card_padding)
+    inner = max(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=variable_defaults,
+    )
+    if not face.title:
+        return 0.0
+    title_h = max(
+        get_title_height(face.title, title_w, variable_defaults),
+        float(face.resolved_style.title.min_height),
+    )
+    if not face.visible_variables:
+        return title_h
+    var_h = compute_variable_controls_height(
+        face.visible_variables,
+        vars_w,
+        variables_style=vs,
+    )
+    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, var_h, float(vs.font.size)
+    )
+    return band_h
+
+
+def compute_variable_controls_height(
+    variable_defs: dict[str, Any],
+    width: float,
+    *,
+    variables_style: VariablesStyle,
+) -> float:
+    """Compute the height needed for variable controls rendered at the given width.
+
+    Simulates flex-wrap layout to determine how many rows the controls occupy,
+    then returns the total foreignObject height including container padding.
+    Returns the single-row config height when all controls fit on one row.
+
+    Args:
+        variable_defs: Variable definitions dict
+        width: Available container width
+        variables_style: Variables style from the face's resolved style.
+    """
+    if not variable_defs:
+        return 0.0
+
+    container_height = float(variables_style.container_height)
+    padding_x = float(variables_style.container_padding)
+    gap = float(variables_style.gap)
+
+    available = max(width - 2 * padding_x, 1.0)
+    widths = [
+        _estimate_control_width(name, v, variables_style)
+        for name, v in variable_defs.items()
+    ]
+
+    # Simulate flex-wrap: first item always starts row 1. The strict ">"
+    # comparison is float-precision-sensitive: a row that fits exactly in
+    # CSS at integer pixel widths can read as overflow in Python after the
+    # vars_w / available subtractions accumulate ~1e-14 of drift. A 0.5px
+    # tolerance gives sub-pixel slop the benefit of the doubt and matches
+    # the browser's own pixel-snapping behaviour.
+    epsilon = 0.5
+    n_rows = 1
+    current_row_w = widths[0] if widths else 0.0
+    for w in widths[1:]:
+        if current_row_w + gap + w > available + epsilon:
+            n_rows += 1
+            current_row_w = w
+        else:
+            current_row_w += gap + w
+
+    if n_rows == 1:
+        return container_height
+
+    # Multi-row: each row gets full container height plus gap between rows
+    return n_rows * container_height + (n_rows - 1) * gap
+
+
+def calculate_layout(face: Face) -> Face:
+    """Calculate dimensions for all layout items.
+
+    Stage: COMPILE (Step 4 of 4: Layout Calculation)
+
+    This is the final compilation step. It calculates pixel dimensions
+    for all charts and nested faces based on layout type and nesting.
+
+    The sizing is content-aware:
+    - KPIs get heights from resolved_style.charts.kpi.default_height
+    - Charts get standard heights (~300px)
+    - Titles are measured for text wrapping
+    - Nested faces accumulate their content heights
+
+    Args:
+        face: Face with layout structure
+
+    Returns:
+        Face with calculated dimensions on layout items
+
+    Example:
+        >>> face = normalize_face(parsed_face)
+        >>> face = calculate_layout(face)
+        >>> print(face.layout.width, face.layout.height)
+        1200.0 800.0
+    """
+    config = get_config()
+
+    container_width = float(config.style.board.width)
+    content_width = _get_root_content_width(config)
+    min_height = float(config.style.board.min_height)
+
+    card_gap = float(config.style.board.card_gap) if face.card_gap else 0.0
+    gap = get_face_gap(face)
+    effective_gap = gap + card_gap
+
+    # Use pre-computed variable defaults for Jinja resolution
+    # This allows markdown content with {{ variable }} to size correctly
+    variable_defaults = face.variable_defaults
+
+    # Calculate required height based on content (content-aware)
+    container_height = calculate_layout_height(
+        face.layout,
+        card_gap,
+        gap,
+        min_height,
+        available_width=content_width,
+        variable_defaults=variable_defaults,
+        resolved_style=face.resolved_style,
+    )
+
+    # Add height for root face title if present. title renders at
+    # content_width - 2*card_padding (matching the card_padding inset applied in render).
+    vs = face.resolved_style.variables
+    use_title_inline = (
+        vs.position == "title-inline"
+        and bool(face.title)
+        and bool(face.visible_variables)
+    )
+    if use_title_inline:
+        band_h = compute_title_variables_inline_band_height(
+            face, content_width, variable_defaults
+        )
+        container_height += band_h + effective_gap
+    elif face.title:
+        card_pad = float(config.style.board.card_padding)
+        title_measure_width = max(content_width - 2 * card_pad, 0.0)
+        title_height = get_title_height(
+            face.title, title_measure_width, variable_defaults
+        )
+        container_height += title_height + effective_gap
+
+    # Set root layout dimensions
+    face.layout.width = container_width
+    face.layout.height = container_height
+
+    # Root layout items should be sized against the root content box, not the
+    # full outer board width.
+    face.layout.content_width = content_width
+    # Vertical spacing is finalized during render after title/content/control
+    # placement, so root sizing preserves the outer height contract here.
+    face.layout.content_height = container_height
+
+    # Calculate all item dimensions in a single pass
+    calculate_layout_items(
+        face.layout,
+        content_width,
+        container_height,
+        card_gap,
+        gap,
+        variable_defaults,
+        resolved_style=face.resolved_style,
+    )
+
+    return face
+
+
+def get_item_content_height(
+    item: LayoutItem,
+    card_gap: float,
+    gap: float,
+    width: float = 400.0,
+    variable_defaults: dict[str, Any] | None = None,
+    height_provider: HeightProvider | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> float:
+    """Get the content-appropriate height for a single layout item (static/compile-time).
+
+    This is the compile-time height calculator using aspect ratios and config
+    defaults only. No executor, no data, no rendering. The render-time path
+    uses a HeightProvider callback instead.
+
+    Args:
+        item: The layout item
+        card_gap: Gap between cards (inter-item spacing, applied N-1 times)
+        gap: Gap between items (used for nested layouts)
+        width: Available width for the item (used for text wrapping estimates)
+        variable_defaults: Optional variable defaults for Jinja resolution
+        resolved_style: Face-resolved style for cascade-aware height calculations.
+
+    Returns:
+        Appropriate height for this item's content
+    """
+    if item.type == "chart" and item.chart:
+        card_pad = float(get_config().style.board.card_padding)
+        if item.chart.type == "callout":
+            return get_chart_content_height(
+                item.chart, width=width, resolved_style=resolved_style
+            )
+        # Vega-family charts render at full item width with card_pad as internal
+        # Vega padding; SVG-family types ignore the width parameter anyway.
+        # The + 2*card_pad accounts for Vega's top+bottom padding in its output height.
+        return (
+            get_chart_content_height(
+                item.chart, width=width, resolved_style=resolved_style
+            )
+            + 2 * card_pad
+        )
+
+    elif item.type == "face" and item.face:
+        # Details (collapsible section): collapsed = summary bar only
+        if is_item_collapsed_summary(item, variable_defaults):
+            return float(get_config().style.layout.details.summary_height)
+
+        # For nested faces, calculate their content height using the nested face's
+        # own resolved_style (each face can have its own theme cascade).
+        nested_face = item.face
+        nested_rs = nested_face.resolved_style
+
+        content_width, nested_non_layout_height, child_gap = nested_face_sizing_context(
+            nested_face, width, card_gap, variable_defaults
+        )
+
+        nested_height = nested_non_layout_height
+        # Add layout content height (only if there are items)
+        if nested_face.layout.items:
+            nested_height += calculate_layout_height(
+                nested_face.layout,
+                card_gap,
+                gap=child_gap,
+                min_height=0,
+                available_width=content_width,
+                variable_defaults=variable_defaults,
+                height_provider=height_provider,
+                resolved_style=nested_rs,
+            )
+
+        # Add effective padding and margin to total height
+        nested_height += _effective_padding(nested_rs).vertical + (
+            nested_rs.margin.vertical if nested_rs.margin else 0.0
+        )
+
+        content_h = max(nested_height, MIN_CONTENT_HEIGHT)
+
+        # Expanded details: add chrome (summary bar + gap) above content
+        if item.details_variable and item.details_summary:
+            return details_chrome_height(item, gap, card_gap) + content_h
+
+        return content_h
+
+    # Fallback (leaf item — treat as card)
+    return DEFAULT_CHART_HEIGHT + 2 * float(get_config().style.board.card_padding)
+
+
+def calculate_layout_height(
+    layout: Layout,
+    card_gap: float,
+    gap: float,
+    min_height: float,
+    available_width: float = 400.0,
+    variable_defaults: dict[str, Any] | None = None,
+    height_provider: HeightProvider | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> float:
+    """Calculate required height for a layout.
+
+    Uses mdsvg to render and measure actual content heights:
+    - KPI charts get smaller heights
+    - Standard charts get normal heights
+    - Tables use default height (data-aware sizing via HeightProvider at render time)
+    - Nested boards accumulate their content heights
+    - Titles are rendered and measured
+    - Markdown content with word-wrapping is rendered and measured
+
+    For rows layout: sum of each item's height + gaps
+    For cols layout: max of item heights (all items share same height)
+    For grid layout: based on rows and content types
+    For tabs layout: max of tab content heights + tab bar
+
+    Args:
+        layout: The layout to calculate height for
+        card_gap: Gap between cards (inter-item spacing)
+        gap: Gap between items
+        min_height: Minimum height to return
+        available_width: Available width for text wrapping calculations
+        variable_defaults: Optional variable defaults for Jinja resolution
+
+    Returns:
+        Required height in pixels
+    """
+    if not layout.items:
+        return min_height
+
+    if layout.type == "rows":
+        measured_height = _measure_rows_layout_height(
+            layout.items,
+            card_gap,
+            gap,
+            available_width,
+            variable_defaults,
+            height_provider,
+            resolved_style=resolved_style,
+        )
+    elif layout.type == "cols":
+        measured_height = _measure_cols_layout_height(
+            layout.items,
+            card_gap,
+            gap,
+            available_width,
+            variable_defaults,
+            height_provider,
+            resolved_style=resolved_style,
+        )
+    elif layout.type == "grid":
+        measured_height = _measure_grid_layout_height(
+            layout,
+            card_gap,
+            gap,
+            available_width,
+            variable_defaults,
+            height_provider,
+            resolved_style=resolved_style,
+        )
+    elif layout.type == "tabs":
+        measured_height = _measure_tabs_layout_height(
+            layout.items,
+            card_gap,
+            gap,
+            available_width,
+            variable_defaults,
+            height_provider,
+            resolved_style=resolved_style,
+        )
+    else:
+        return min_height
+    return max(measured_height, min_height)
+
+
+def _measure_rows_layout_height(
+    items: list[LayoutItem],
+    card_gap: float,
+    gap: float,
+    available_width: float,
+    variable_defaults: dict[str, Any] | None,
+    height_provider: HeightProvider | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> float:
+    """Measure total height for a rows layout."""
+    total_height = 0.0
+    for item in items:
+        # User-specified height takes precedence over content-aware height.
+        # Percentages resolve to 0 here (no available_height context) and
+        # fall through; _calculate_rows_dimensions resolves them later.
+        resolved = _resolve_layout_height(item, 0.0)
+        if resolved is not None:
+            total_height += resolved
+        else:
+            total_height += _resolve_height(
+                item,
+                card_gap,
+                gap,
+                available_width,
+                variable_defaults,
+                height_provider,
+                resolved_style=resolved_style,
+            )
+    if len(items) > 1:
+        total_height += (gap + card_gap) * (len(items) - 1)
+    return total_height
+
+
+def _measure_cols_layout_height(
+    items: list[LayoutItem],
+    card_gap: float,
+    gap: float,
+    available_width: float,
+    variable_defaults: dict[str, Any] | None,
+    height_provider: HeightProvider | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> float:
+    """Measure shared row height for a cols layout."""
+    max_height = MIN_CONTENT_HEIGHT
+    n_items = len(items)
+    total_gap = (gap + card_gap) * (n_items - 1) if n_items > 1 else 0
+    content_width = available_width - total_gap
+
+    specified_widths: list[float | None] = []
+    for item in items:
+        parsed_width = parse_dimension(item.user_width, content_width)
+        specified_widths.append(parsed_width)
+
+    assigned_widths = _resolve_cols_widths(
+        specified_widths, content_width=content_width, item_count=n_items
+    )
+    for i, item in enumerate(items):
+        # User-specified height takes precedence (px only here;
+        # percentages need available_height, resolved in _calculate_cols_dimensions)
+        resolved = _resolve_layout_height(item, 0.0)
+        if resolved is not None:
+            max_height = max(max_height, resolved)
+        else:
+            item_width = assigned_widths[i]
+            item_height = _resolve_height(
+                item,
+                card_gap,
+                gap,
+                item_width,
+                variable_defaults,
+                height_provider,
+                resolved_style=resolved_style,
+            )
+            max_height = max(max_height, item_height)
+    return max_height
+
+
+def _measure_grid_layout_height(
+    layout: Layout,
+    card_gap: float,
+    gap: float,
+    available_width: float,
+    variable_defaults: dict[str, Any] | None,
+    height_provider: HeightProvider | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> float:
+    """Measure required height for a grid layout."""
+    columns = layout.columns or 24
+    max_row_end = 1
+    for item in layout.items:
+        item_row = item.row or 0
+        item_rows = item.row_span or 1
+        max_row_end = max(max_row_end, item_row + item_rows)
+
+    effective_gap = gap + card_gap
+    total_gap_x = effective_gap * (columns - 1)
+    col_width = (available_width - total_gap_x) / columns
+
+    total_item_height = 0.0
+    for item in layout.items:
+        resolved = _resolve_layout_height(item, 0.0)
+        if resolved is not None:
+            total_item_height += resolved
+            continue
+        item_col_span = item.col_span or 1
+        item_width = col_width * item_col_span + effective_gap * (item_col_span - 1)
+        total_item_height += _resolve_height(
+            item,
+            card_gap,
+            gap,
+            item_width,
+            variable_defaults,
+            height_provider,
+            resolved_style=resolved_style,
+        )
+
+    avg_item_height = (
+        total_item_height / len(layout.items) if layout.items else DEFAULT_CHART_HEIGHT
+    )
+    total_gaps = effective_gap * (max_row_end - 1) if max_row_end > 1 else 0
+    return (max_row_end * avg_item_height) + total_gaps
+
+
+def _measure_tabs_layout_height(
+    items: list[LayoutItem],
+    card_gap: float,
+    gap: float,
+    available_width: float,
+    variable_defaults: dict[str, Any] | None,
+    height_provider: HeightProvider | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> float:
+    """Measure required height for a tabs layout."""
+    tab_bar_height = float(get_config().style.layout.tabs.bar_height)
+    max_content_height = MIN_CONTENT_HEIGHT
+    for item in items:
+        resolved = _resolve_layout_height(item, 0.0)
+        if resolved is not None:
+            max_content_height = max(max_content_height, resolved)
+        else:
+            item_height = _resolve_height(
+                item,
+                card_gap,
+                gap,
+                available_width,
+                variable_defaults,
+                height_provider,
+                resolved_style=resolved_style,
+            )
+            max_content_height = max(max_content_height, item_height)
+    return max_content_height + tab_bar_height
+
+
+def _set_render_ready_sizing(item: LayoutItem) -> None:
+    """Set render-ready sizing fields (calculated_width, calculated_height, aspect_ratio).
+
+    These fields preserve the calculated pixel dimensions for consistent rendering
+    across SVG and HTML outputs. The aspect_ratio is used for responsive CSS rendering.
+
+    Args:
+        item: LayoutItem to set sizing fields on
+    """
+    # Set calculated dimensions (same as width/height for now, but preserved separately)
+    item.calculated_width = item.width if item.width > 0 else None
+    item.calculated_height = item.height if item.height > 0 else None
+
+    # Calculate aspect ratio for responsive rendering
+    if item.calculated_width and item.calculated_height and item.calculated_height > 0:
+        item.aspect_ratio = item.calculated_width / item.calculated_height
+    else:
+        item.aspect_ratio = None
+
+
+def calculate_layout_items(
+    layout: Layout,
+    available_width: float,
+    available_height: float,
+    card_gap: float,
+    gap: float,
+    variable_defaults: dict[str, Any] | None = None,
+    height_provider: HeightProvider | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> None:
+    """Calculate dimensions for all items in a layout.
+
+    Modifies items in place, setting their dimensions and positions.
+
+    Args:
+        layout: Layout to calculate dimensions for
+        available_width: Available container width in pixels
+        available_height: Available container height in pixels
+        card_gap: Gap between cards (inter-item spacing)
+        gap: Gap between items in pixels
+        variable_defaults: Optional variable defaults for Jinja resolution
+        resolved_style: Face-resolved style for cascade-aware height calculations.
+    """
+    if not layout.items:
+        return
+
+    _apply_layout_dimensions(
+        layout,
+        available_width,
+        available_height,
+        card_gap,
+        gap,
+        variable_defaults,
+        height_provider,
+        resolved_style=resolved_style,
+    )
+
+    for item in layout.items:
+        _calculate_nested_face_layout(
+            item, card_gap, gap, variable_defaults, height_provider
+        )
+
+
+def _apply_layout_dimensions(
+    layout: Layout,
+    available_width: float,
+    available_height: float,
+    card_gap: float,
+    gap: float,
+    variable_defaults: dict[str, Any] | None,
+    height_provider: HeightProvider | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> None:
+    """Apply the correct layout dimension calculator based on layout type."""
+    if layout.type == "rows":
+        _calculate_rows_dimensions(
+            layout.items,
+            available_width,
+            available_height,
+            card_gap,
+            gap,
+            variable_defaults,
+            height_provider,
+            resolved_style=resolved_style,
+        )
+        return
+    if layout.type == "cols":
+        _calculate_cols_dimensions(
+            layout.items,
+            available_width,
+            available_height,
+            card_gap,
+            gap,
+            variable_defaults,
+            height_provider,
+            resolved_style=resolved_style,
+        )
+        return
+    if layout.type == "grid":
+        _calculate_grid_dimensions(
+            layout.items,
+            available_width,
+            available_height,
+            layout.columns or 24,
+            card_gap,
+            gap,
+            variable_defaults,
+            height_provider,
+            resolved_style=resolved_style,
+        )
+        return
+    if layout.type == "tabs":
+        _calculate_tabs_dimensions(
+            layout.items,
+            available_width,
+            available_height,
+            card_gap,
+            gap,
+            variable_defaults,
+            height_provider,
+            resolved_style=resolved_style,
+        )
+        return
+    _calculate_rows_dimensions(
+        layout.items,
+        available_width,
+        available_height,
+        card_gap,
+        gap,
+        variable_defaults,
+        height_provider,
+        resolved_style=resolved_style,
+    )
+
+
+def nested_face_sizing_context(
+    nested_face: Face,
+    width: float,
+    card_gap: float,
+    variable_defaults: dict[str, Any] | None,
+) -> tuple[float, float, float]:
+    """Return (content_width, non_layout_height, child_gap).
+
+    non_layout_height includes title + text + variables + gaps between them,
+    plus the gap before the layout block if layout items follow.
+    """
+    nrs = nested_face.resolved_style
+    ep = _effective_padding(nrs)
+    face_margin_horizontal = nrs.margin.horizontal if nrs.margin else 0.0
+    content_width = width - ep.horizontal - face_margin_horizontal
+    child_gap = nrs.gap if nrs.gap is not None else 0.0
+    effective_child_gap = child_gap + card_gap
+
+    vs = nested_face.resolved_style.variables
+    card_pad = float(nested_face.resolved_style.board.card_padding)
+    inner = max(content_width - 2 * card_pad, 1.0)
+
+    use_title_inline = (
+        vs.position == "title-inline"
+        and bool(nested_face.title)
+        and bool(nested_face.visible_variables)
+    )
+
+    non_layout_height = 0.0
+    if use_title_inline:
+        non_layout_height += compute_title_variables_inline_band_height(
+            nested_face, content_width, variable_defaults
+        )
+    elif nested_face.title:
+        title_height = max(
+            get_title_height(nested_face.title, inner, variable_defaults),
+            float(nested_face.resolved_style.title.min_height),
+        )
+        non_layout_height += title_height
+
+    if nested_face.text:
+        text_height = get_markdown_text_height(
+            nested_face.text,
+            content_width,
+            variable_defaults,
+            text_style=nested_face.resolved_style.text,
+        )
+        if non_layout_height > 0:
+            non_layout_height += effective_child_gap
+        non_layout_height += text_height
+
+    # Add variable controls height if this nested face has visible variables
+    if nested_face.visible_variables and not use_title_inline:
+        if non_layout_height > 0:
+            non_layout_height += effective_child_gap
+        non_layout_height += compute_variable_controls_height(
+            nested_face.visible_variables,
+            content_width,
+            variables_style=nested_face.resolved_style.variables,
+        )
+
+    if non_layout_height > 0 and nested_face.layout.items:
+        non_layout_height += effective_child_gap
+
+    return content_width, non_layout_height, child_gap
+
+
+def _calculate_nested_face_layout(
+    item: LayoutItem,
+    card_gap: float,
+    gap: float,
+    variable_defaults: dict[str, Any] | None,
+    height_provider: HeightProvider | None = None,
+) -> None:
+    """Recursively size a nested face once the parent item dimensions are known."""
+    if is_item_collapsed_summary(item, variable_defaults) or not item.face:
+        return
+
+    nested_face = item.face
+    nested_face.layout.width = item.width
+    nested_face.layout.height = item.height
+
+    content_width, non_layout_height, child_gap = nested_face_sizing_context(
+        nested_face, item.width, card_gap, variable_defaults
+    )
+
+    nrs2 = nested_face.resolved_style
+    layout_available_height = (
+        item.height
+        - details_chrome_height(item, gap, card_gap)
+        - _effective_padding(nrs2).vertical
+        - (nrs2.margin.vertical if nrs2.margin else 0.0)
+        - non_layout_height
+    )
+
+    nested_face.layout.content_width = content_width
+    nested_face.layout.content_height = max(layout_available_height, 0)
+
+    calculate_layout_items(
+        nested_face.layout,
+        content_width,
+        max(layout_available_height, 0),
+        card_gap,
+        gap=child_gap,
+        variable_defaults=variable_defaults,
+        height_provider=height_provider,
+        resolved_style=nested_face.resolved_style,
+    )
+
+
+def _calculate_rows_dimensions(
+    items: list[LayoutItem],
+    available_width: float,
+    available_height: float,
+    card_gap: float,
+    gap: float,
+    variable_defaults: dict[str, Any] | None = None,
+    height_provider: HeightProvider | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> None:
+    """Calculate dimensions for items in a rows layout.
+
+    In a rows layout:
+    - Items stack vertically
+    - All items get full width
+    - Height respects user-specified values (e.g., "200px", "50%")
+    - Remaining height is distributed among auto items based on content type
+    - If auto items exceed remaining space, they scale proportionally
+    - Specified items are never scaled; if they exceed available space the layout overflows
+
+    Args:
+        items: List of layout items
+        available_width: Available width in pixels
+        available_height: Available height in pixels
+        card_gap: Gap between cards (inter-item spacing)
+        gap: Gap between items in pixels
+        variable_defaults: Optional variable defaults for Jinja resolution
+    """
+    n = len(items)
+    if n == 0:
+        return
+
+    # Calculate total gap space
+    total_gap = (gap + card_gap) * (n - 1)
+    available_content_height = available_height - total_gap
+
+    # First pass: parse user-specified heights and get content heights for auto items
+    specified_heights: list[float | None] = []
+    content_heights: list[float] = []
+    total_specified = 0.0
+
+    for item in items:
+        parsed_height = _resolve_layout_height(item, available_content_height)
+        specified_heights.append(parsed_height)
+        if parsed_height is not None:
+            total_specified += parsed_height
+            content_heights.append(parsed_height)
+        else:
+            height = _resolve_height(
+                item,
+                card_gap,
+                gap,
+                available_width,
+                variable_defaults,
+                height_provider,
+                resolved_style=resolved_style,
+            )
+            content_heights.append(height)
+
+    # Distribute height: specified items keep their height, auto items share the rest
+    remaining = max(available_content_height - total_specified, 0.0)
+    auto_total = sum(
+        h for h, s in zip(content_heights, specified_heights, strict=True) if s is None
+    )
+
+    item_heights: list[float] = []
+    for i, _item in enumerate(items):
+        spec_h = specified_heights[i]
+        if spec_h is not None:
+            item_heights.append(spec_h)
+        elif auto_total > 0 and remaining < auto_total:
+            # Auto items need scaling to fit
+            item_heights.append(content_heights[i] * (remaining / auto_total))
+        else:
+            item_heights.append(content_heights[i])
+
+    # Second pass: assign dimensions
+    current_y = 0.0
+    for i, item in enumerate(items):
+        item.width_fraction = 1.0
+        item.width = available_width
+        item.height = item_heights[i]
+        item.x = 0.0
+        item.y = current_y
+        current_y += item.height + gap + card_gap
+        # Set render-ready sizing fields
+        _set_render_ready_sizing(item)
+
+
+def parse_dimension(value: str | None, total: float) -> float | None:
+    """Parse a dimension string to pixels.
+
+    Supports:
+    - Percentages: "30%", "70%" -> fraction of total
+    - Pixels: "200px", "200" -> exact pixels
+    - None -> returns None (auto-distribute)
+
+    Args:
+        value: Dimension string or None
+        total: Total available size for percentage calculations
+
+    Returns:
+        Pixel value or None if not specified
+    """
+    if value is None:
+        return None
+
+    value = str(value).strip()
+
+    if value.endswith("%"):
+        try:
+            percent = float(value[:-1])
+            return (percent / 100.0) * total
+        except ValueError:
+            return None
+
+    if value.endswith("px"):
+        try:
+            return float(value[:-2])
+        except ValueError:
+            return None
+
+    # Try as plain number (pixels)
+    try:
+        return float(value)
+    except ValueError:
+        return None
+
+
+def _resolve_layout_height(item: LayoutItem, available: float) -> float | None:
+    """Return resolved layout-wrapper height in px, or None for auto.
+
+    Percentages resolve against ``available``; measurement functions pass
+    ``available=0.0`` so percentages fall through to content-aware sizing
+    (``parse_dimension("50%", 0.0)`` returns 0.0, filtered by ``h > 0``).
+
+    Explicit ``height: 0`` is rejected at compile time in
+    ``normalize_layout._validate_dimension``.
+    """
+    h = parse_dimension(item.layout_height, available)
+    return h if h is not None and h > 0 else None
+
+
+def _resolve_cols_widths(
+    specified_widths: list[float | None], content_width: float, item_count: int
+) -> list[float]:
+    """Resolve column widths, avoiding zero-width auto items in mixed layouts.
+
+    Normal case:
+    - explicit widths keep their authored size
+    - auto items split the leftover width equally
+
+    Defensive overflow case:
+    - when explicit widths consume the full row and auto siblings exist,
+      reserve one equal-share slot per auto item
+    - scale explicit widths proportionally into the remaining space
+
+    This preserves authored ratios for explicit siblings while avoiding
+    unreadable 0px auto columns in over-constrained mixed layouts.
+    """
+    if item_count == 0:
+        return []
+
+    total_specified = sum(width for width in specified_widths if width is not None)
+    auto_count = sum(1 for width in specified_widths if width is None)
+
+    if auto_count == 0:
+        return [width if width is not None else 0.0 for width in specified_widths]
+
+    remaining_width = content_width - total_specified
+    if remaining_width > 0:
+        auto_width = remaining_width / auto_count
+        return [auto_width if width is None else width for width in specified_widths]
+
+    equal_share = content_width / item_count if item_count > 0 else 0.0
+    auto_width = equal_share
+    specified_budget = max(content_width - (auto_width * auto_count), 0.0)
+    scale = specified_budget / total_specified if total_specified > 0 else 0.0
+
+    return [
+        auto_width if width is None else width * scale for width in specified_widths
+    ]
+
+
+def _calculate_cols_dimensions(
+    items: list[LayoutItem],
+    available_width: float,
+    available_height: float,
+    card_gap: float,
+    gap: float,
+    variable_defaults: dict[str, Any] | None = None,
+    height_provider: HeightProvider | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> None:
+    """Calculate dimensions for items in a cols layout.
+
+    In a cols layout:
+    - Items arrange horizontally
+    - Width respects user-specified values (e.g., "30%", "200px")
+    - Remaining width is distributed equally among items without specified widths
+    - ALL items get the SAME height (max of content heights, capped at available)
+
+    This ensures alignment: all items in a row have the same height.
+    The height is the max of what each item needs, but won't exceed available.
+
+    Args:
+        items: List of layout items
+        available_width: Available width in pixels
+        available_height: Available height in pixels (upper bound)
+        card_gap: Gap between cards (inter-item spacing)
+        gap: Gap between items in pixels
+        variable_defaults: Optional variable defaults for Jinja resolution
+    """
+    n = len(items)
+    if n == 0:
+        return
+
+    # Calculate total gap space
+    effective_gap = gap + card_gap
+    total_gap = effective_gap * (n - 1)
+    content_width = available_width - total_gap
+
+    # First pass: parse user-specified widths and calculate remaining space
+    specified_widths: list[float | None] = []
+
+    for item in items:
+        parsed_width = parse_dimension(item.user_width, content_width)
+        specified_widths.append(parsed_width)
+
+    resolved_widths = _resolve_cols_widths(
+        specified_widths, content_width=content_width, item_count=n
+    )
+
+    # Find max content height (all items in cols share this height).
+    # Track specified and content maxima separately so overflow semantics
+    # are order-independent: if max_specified >= max_content, the user's
+    # explicit height wins and the row overflows rather than being capped.
+    max_specified = 0.0
+    max_auto = MIN_CONTENT_HEIGHT
+    for i, item in enumerate(items):
+        # Percentages resolve against available_height (no vertical gap in cols)
+        resolved = _resolve_layout_height(item, available_height)
+        if resolved is not None:
+            max_specified = max(max_specified, resolved)
+        else:
+            item_w = resolved_widths[i]
+            ch = _resolve_height(
+                item,
+                card_gap,
+                gap,
+                item_w,
+                variable_defaults,
+                height_provider,
+                resolved_style=resolved_style,
+            )
+            max_auto = max(max_auto, ch)
+
+    max_content_height = max(max_specified, max_auto)
+    # Cap to available height unless a user-specified height drove the max.
+    # >= so that a specified height equal to the content max still wins
+    # (the user explicitly asked for this height, so don't clamp it).
+    row_height = (
+        max_content_height
+        if max_specified >= max_auto
+        else min(max_content_height, available_height)
+    )
+
+    # Second pass: assign dimensions
+    current_x = 0.0
+    for i, item in enumerate(items):
+        item_width = resolved_widths[i]
+        item.width_fraction = (
+            item_width / content_width if content_width > 0 else 1.0 / n
+        )
+        item.width = item_width
+        item.height = row_height  # All items get same height
+        item.x = current_x
+        item.y = 0.0
+        # Add gap between items, but not after the last item
+        if i < n - 1:
+            current_x += item_width + effective_gap
+        else:
+            current_x += item_width
+        # Set render-ready sizing fields
+        _set_render_ready_sizing(item)
+
+
+def _calculate_grid_dimensions(
+    items: list[LayoutItem],
+    available_width: float,
+    available_height: float,
+    columns: int,
+    card_gap: float,
+    gap: float,
+    variable_defaults: dict[str, Any] | None = None,
+    height_provider: HeightProvider | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> None:
+    """Calculate dimensions for items in a grid layout.
+
+    In a grid layout:
+    - Items can have explicit row, col positions and row_span, col_span
+    - Items WITHOUT explicit positions are auto-flowed like CSS grid
+    - Width is based on column count
+    - Row height is calculated based on content types
+
+    Args:
+        items: List of layout items with grid positions
+        available_width: Available width in pixels
+        available_height: Available height in pixels
+        columns: Number of grid columns
+        card_gap: Gap between cards (inter-item spacing)
+        gap: Gap between items in pixels
+        variable_defaults: Optional variable defaults for Jinja resolution
+    """
+    if not items:
+        return
+
+    # Calculate column width
+    effective_gap = gap + card_gap
+    total_gap_x = effective_gap * (columns - 1)
+    col_width = (available_width - total_gap_x) / columns
+
+    # Auto-flow items without explicit positions
+    # Track occupied cells as a set of (col, row) tuples
+    occupied: set = set()
+
+    # First pass: mark cells occupied by items with explicit positions
+    for item in items:
+        if item.col is not None and item.row is not None:
+            item_col_span = item.col_span or 1
+            item_row_span = item.row_span or 1
+            for c in range(item.col, item.col + item_col_span):
+                for r in range(item.row, item.row + item_row_span):
+                    occupied.add((c, r))
+
+    # Second pass: auto-place items without explicit positions
+    current_col = 0
+    current_row = 0
+
+    for item in items:
+        if item.col is None or item.row is None:
+            item_col_span = item.col_span or 1
+            item_row_span = item.row_span or 1
+
+            # Find next available position that fits the item
+            placed = False
+            while not placed:
+                # Check if item fits at current position
+                fits = True
+                if current_col + item_col_span > columns:
+                    # Doesn't fit, move to next row
+                    current_col = 0
+                    current_row += 1
+                    continue
+
+                # Check if all cells are available
+                for c in range(current_col, current_col + item_col_span):
+                    for r in range(current_row, current_row + item_row_span):
+                        if (c, r) in occupied:
+                            fits = False
+                            break
+                    if not fits:
+                        break
+
+                if fits:
+                    # Place the item
+                    item.col = current_col
+                    item.row = current_row
+                    # Mark cells as occupied
+                    for c in range(current_col, current_col + item_col_span):
+                        for r in range(current_row, current_row + item_row_span):
+                            occupied.add((c, r))
+                    placed = True
+                    # Move to next column for next item
+                    current_col += item_col_span
+                else:
+                    # Try next column
+                    current_col += 1
+
+    # Calculate number of rows
+    max_row_end = 1
+    for item in items:
+        item_row = item.row or 0
+        item_rows = item.row_span or 1
+        row_end = item_row + item_rows
+        max_row_end = max(max_row_end, row_end)
+
+    # Calculate content-aware row height
+    # Find max content height per row, then average
+    row_content_heights: dict = {}  # row_index -> max_height
+
+    # Track which rows have heights driven by user-specified values.
+    # A row with any specified-height item is exempt from scaling,
+    # even if the row's max came from an auto item.  This is intentional:
+    # the user pinned at least one item in that row, so we respect the
+    # resulting row height rather than squashing it.
+    specified_rows: set[int] = set()
+
+    for item in items:
+        item_row = item.row or 0
+        item_row_span = item.row_span or 1
+
+        # User-specified height takes precedence
+        resolved = _resolve_layout_height(item, available_height)
+        if resolved is not None:
+            content_height = resolved
+            for r in range(item_row, item_row + item_row_span):
+                specified_rows.add(r)
+        else:
+            content_height = _resolve_height(
+                item,
+                card_gap,
+                gap,
+                col_width,
+                variable_defaults,
+                height_provider,
+                resolved_style=resolved_style,
+            )
+        # Distribute height across spanned rows
+        height_per_row = content_height / item_row_span
+
+        for r in range(item_row, item_row + item_row_span):
+            current_max = row_content_heights.get(r, MIN_CONTENT_HEIGHT)
+            row_content_heights[r] = max(current_max, height_per_row)
+
+    # Calculate total content height
+    total_content_height = sum(row_content_heights.values())
+    total_gap_y = effective_gap * (max_row_end - 1)
+
+    # Use content height if it fits, otherwise scale auto rows to fit.
+    # Rows with user-specified heights are exempt from scaling (overflow).
+    if total_content_height + total_gap_y <= available_height:
+        row_heights = row_content_heights
+    else:
+        specified_total = sum(
+            row_content_heights[r] for r in specified_rows if r in row_content_heights
+        )
+        auto_total = total_content_height - specified_total
+        auto_budget = max(available_height - total_gap_y - specified_total, 0.0)
+        auto_scale = auto_budget / auto_total if auto_total > 0 else 1.0
+        row_heights = {
+            r: h if r in specified_rows else h * auto_scale
+            for r, h in row_content_heights.items()
+        }
+
+    # Calculate row Y positions
+    row_y_positions: dict = {}
+    current_y = 0.0
+    for r in range(max_row_end):
+        row_y_positions[r] = current_y
+        row_h = row_heights.get(r, DEFAULT_CHART_HEIGHT)
+        current_y += row_h + effective_gap
+
+    # Position each item
+    for item in items:
+        item_col = item.col or 0
+        item_row = item.row or 0
+        item_col_span = item.col_span or 1
+        item_row_span = item.row_span or 1
+
+        # Calculate pixel position
+        item.x = item_col * (col_width + effective_gap)
+        item.y = row_y_positions.get(item_row, 0.0)
+
+        # Calculate pixel dimensions
+        item.width = item_col_span * col_width + (item_col_span - 1) * effective_gap
+
+        # Height spans multiple rows
+        item_height = 0.0
+        for r in range(item_row, item_row + item_row_span):
+            item_height += row_heights.get(r, DEFAULT_CHART_HEIGHT)
+        item_height += effective_gap * (item_row_span - 1)  # Internal gaps
+        item.height = item_height
+
+        # Calculate width fraction
+        item.width_fraction = item_col_span / columns
+
+        # Set render-ready sizing fields
+        _set_render_ready_sizing(item)
+
+
+def _calculate_tabs_dimensions(
+    items: list[LayoutItem],
+    available_width: float,
+    available_height: float,
+    card_gap: float,
+    gap: float,
+    variable_defaults: dict[str, Any] | None = None,
+    height_provider: HeightProvider | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> None:
+    """Calculate dimensions for items in a tabs layout.
+
+    In a tabs layout:
+    - Each tab gets the full container size (minus tab bar height)
+    - Only one tab is visible at a time
+    - Height is based on max content height of all tabs
+
+    Args:
+        items: List of layout items (one per tab)
+        available_width: Available width in pixels
+        available_height: Available height in pixels
+        card_gap: Gap between cards (inter-item spacing)
+        gap: Gap (unused for tabs)
+        variable_defaults: Optional variable defaults for Jinja resolution
+    """
+    # Reserve space for tab bar
+    tab_bar_height = float(get_config().style.layout.tabs.bar_height)
+
+    # Find max content height across all tabs.
+    # Track specified and content maxima separately (order-independent).
+    tab_available = available_height - tab_bar_height
+    max_specified = 0.0
+    max_auto = MIN_CONTENT_HEIGHT
+    for item in items:
+        resolved = _resolve_layout_height(item, tab_available)
+        if resolved is not None:
+            max_specified = max(max_specified, resolved)
+        else:
+            ch = _resolve_height(
+                item,
+                card_gap,
+                gap,
+                available_width,
+                variable_defaults,
+                height_provider,
+                resolved_style=resolved_style,
+            )
+            max_auto = max(max_auto, ch)
+
+    max_content_height = max(max_specified, max_auto)
+    # Cap to available height unless the max was driven by a user-specified height
+    content_height = (
+        max_content_height
+        if max_specified >= max_auto
+        else min(max_content_height, tab_available)
+    )
+
+    for item in items:
+        item.width_fraction = 1.0
+        item.width = available_width
+        item.height = content_height
+        item.x = 0.0
+        item.y = tab_bar_height
+        # Set render-ready sizing fields
+        _set_render_ready_sizing(item)