dataface 0.1.2__py3-none-any.whl

dataface/core/render/chart/table.py

@@ -0,0 +1,2957 @@
+"""Table SVG rendering for Dataface dashboards.
+
+Chart-level color and background channels are lowered to style.columns by
+pipeline._lower_channels_to_table before this renderer runs. Opacity and
+stroke_* are not meaningful on table charts and are rejected at normalize time.
+"""
+
+from __future__ import annotations
+
+import html as html_module
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from dataface.core.compile.models.primitives import FontStyle
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.chart.authored import (
+        SparkConfig,
+        TableColumnConfig,
+    )
+    from dataface.core.compile.models.style.compiled import (
+        PaginationConfig,
+        TableRowRoleStyle,
+    )
+    from dataface.core.compile.models.style.merged import MergedChartsStyle, MergedStyle
+from dataface.core.compile.colors import is_dark_color, sanitize_color
+from dataface.core.compile.config import get_markdown_config
+from dataface.core.compile.models.chart.authored import coerce_numeric
+from dataface.core.compile.models.style.compiled import (
+    VALID_FONT_WEIGHTS,
+    PaginatorStyle,
+    TableChartStyle,
+    TableChartStylePatch,
+    TableColumnDefaultsConfig,
+    TitleStyle,
+    font_weight_as_css,
+)
+from dataface.core.compile.typography import chart_title_spec
+from dataface.core.render.chart.table_support import (
+    _WORD_SUFFIXES,
+    calculate_column_layout,
+    format_table_cell_value,
+    is_date_like,
+    is_summary_role,
+    is_total_role,
+    measure_column_demands,
+    measure_column_word_floors,
+    parse_table_column_configs,
+    resolve_cell_conditional_styles,
+    resolve_cell_glyph,
+    resolve_cell_glyph_from_overrides,
+    resolve_cell_link_with_board,
+    resolve_conditional_styles,
+    resolve_header_overflow,
+    resolve_row_role,
+    resolve_table_style_value,
+    resolve_wrapped_headers,
+)
+from dataface.core.render.chart.title_overflow import (
+    compute_title_limit,
+    prepare_title_text,
+    resolve_title_overflow,
+)
+from dataface.core.render.errors import ChartDataError
+from dataface.core.render.font_measurement import get_font_measurer
+from dataface.core.render.font_support import DFT_SANS_TABULAR_FONT_FAMILY
+from dataface.core.render.format_utils import format_kpi_parts, resolve_format
+from dataface.core.render.svg_utils import _px
+from dataface.core.render.text.case import apply_case
+from dataface.core.render.utils import (
+    normalize_data_types,
+    slug_to_text,
+)
+from mdsvg.fonts import truncate_text_precise, wrap_text_precise
+
+# Height of the pagination control bar (chevrons + page numbers).
+_PAGINATION_CONTROL_HEIGHT = 28
+
+# Anti-dangle: collapse a small trailing page by squeezing row_height.
+# Only fire when the overflow is 1-2 rows (not a "real" second page).
+_ANTI_DANGLE_MAX_OVERFLOW = 2
+# Maximum row_height reduction ratio (15%): 32px → 27px still reads fine.
+_ANTI_DANGLE_MAX_SQUEEZE = 0.15
+# Hard pixel floor: below 20px text clips descenders at our smallest body size.
+_ANTI_DANGLE_MIN_ROW_H = 20
+
+# Sentinel column key for the synthetic row-number column. The key uses a
+# private-use character that YAML-authored column names cannot reach, so
+# style.columns lookups and conditional_formatting dicts keyed by column name
+# never match it. It is transparent to column_configs and when_rules.
+_ROW_NUMBER_COL = "\u0001__row_number__"
+
+
+# Fallback chart width when neither layout nor sizer supplies one. Used for
+# title-block sizing math; both `_get_table_height_from_data` and the renderer
+# read this so the two stay in lockstep.
+TABLE_DEFAULT_WIDTH: float = 800.0
+
+
+def _subtitle_baseline_below_title(
+    title_bottom: float,
+    title_subtitle_gap: float,
+    subtitle_font_size: float,
+) -> float:
+    """Place the subtitle baseline safely below the title block."""
+    subtitle_top = title_bottom + title_subtitle_gap
+    return subtitle_top + (subtitle_font_size * 0.8)
+
+
+@dataclass(frozen=True)
+class TableTitleBlockLayout:
+    """Resolved title-block geometry shared between sizer and renderer.
+
+    The renderer consumes every field; the sizer only reads ``height``. Both
+    paths run through ``compute_table_title_block_layout`` so the height the
+    sizer reserves matches what the renderer actually paints.
+    """
+
+    height: int
+    rendered_title: str = ""
+    title_lines: tuple[str, ...] = ()
+    subtitle_font_size: float = 0.0
+
+
+def compute_table_title_block_layout(
+    *,
+    chart_title: str,
+    chart_subtitle: str,
+    table_width: float,
+    tc: TableChartStyle,
+    padding: int,
+    title_style: TitleStyle,
+    resolved_chart_style: MergedChartsStyle,
+    face_level: int = 1,
+) -> TableTitleBlockLayout:
+    """Resolve the title-block layout used by both renderer and sizer.
+
+    Single source of truth — runs ``prepare_title_text`` once, computes
+    subtitle font size once. The renderer reads every field for SVG
+    emission; the sizer reads only ``height``.
+
+    Args:
+        resolved_chart_style: Active ``MergedChartsStyle`` for the face. Threaded
+            into ``chart_title_spec`` so the title font family reflects the
+            active theme, not the global default config.
+        face_level: Heading level of the parent face (root=1, nested=2, …).
+            Chart title uses face_level + 1 so titles are one level below their
+            containing face header.
+
+    Returns a zero-height layout when ``chart_title`` is empty.
+    """
+    if not chart_title:
+        return TableTitleBlockLayout(height=0)
+    title_font_size, _, title_font_family = chart_title_spec(
+        table_width, level=face_level + 1, resolved_chart_style=resolved_chart_style
+    )
+    title_line_height = title_font_size + 2
+    rendered_title = prepare_title_text(
+        chart_title,
+        overflow=resolve_title_overflow(title_style),
+        limit=compute_title_limit(table_width, {"left": padding, "right": padding}),
+        font_size=title_font_size,
+        font_family=title_font_family,
+    )
+    title_lines = tuple(rendered_title.splitlines() or [chart_title])
+    title_baseline = padding + tc.title_baseline_offset
+    last_title_baseline = title_baseline + ((len(title_lines) - 1) * title_line_height)
+    title_bottom = last_title_baseline + (title_font_size * 0.5)
+    height = max(int(tc.title_row.height), int(title_bottom - padding + 8))
+    subtitle_font_size = 0.0
+    if chart_subtitle:
+        assert (
+            tc.subtitle.font.size is not None
+        ), "theme must supply table.subtitle.font.size"
+        subtitle_font_size = float(tc.subtitle.font.size)
+        subtitle_baseline = _subtitle_baseline_below_title(
+            title_bottom=title_bottom,
+            title_subtitle_gap=tc.title_subtitle_gap,
+            subtitle_font_size=subtitle_font_size,
+        )
+        subtitle_bottom = subtitle_baseline + (subtitle_font_size * 0.5)
+        height = max(height, int(subtitle_bottom - padding + 8))
+    return TableTitleBlockLayout(
+        height=height,
+        rendered_title=rendered_title,
+        title_lines=title_lines,
+        subtitle_font_size=subtitle_font_size,
+    )
+
+
+def _row_number_column_width(
+    row_numbers: Any,
+    total_row_count: int,
+    table_config: Any,
+    font: FontStyle,
+    measurer: Any,
+) -> float:
+    """Compute the synthetic row-number column width.
+
+    Sized from ``total_row_count`` digit count — not per-page count — so the
+    column width is the same on every page of a paginated table.
+    """
+    font_size = float(font.size) if font.size is not None else 13.0
+    digits = max(len(str(max(total_row_count, 1))), len(row_numbers.header))
+    text_w = max(
+        measurer.measure("9" * digits, font_size),
+        measurer.measure(row_numbers.header, font_size),
+    )
+    cell_pad = int(table_config.column_layout.cell_padding)
+    return float(text_w + cell_pad * 2)
+
+
+# CSS font stack for numeric table cells — matches Vega axisQuantitative config
+_SANS_NUMERIC_FONT_STACK = (
+    f"'{DFT_SANS_TABULAR_FONT_FAMILY}', Inter, system-ui, sans-serif"
+)
+
+
+def _is_numeric_cell(value: Any, col_config: Any) -> bool:
+    """Determine if a cell should receive numeric styling (tabular font, three-lane layout).
+
+    Checks the Python type first, then falls back to probing string values.
+    A column with an explicit numeric format config (currency, percent, etc.)
+    is always treated as numeric regardless of the runtime value type — CSV
+    adapters deliver everything as strings.
+    """
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, (int, float)):
+        return True
+
+    # If the column has a format config, treat it as numeric — the author
+    # declared intent by attaching a number format.
+    if col_config and col_config.format is not None:
+        return True
+
+    # Probe string values that look like numbers (from CSV adapters)
+    if isinstance(value, str) and value:
+        stripped = value.strip()
+        if stripped:
+            try:
+                float(stripped)
+                return True
+            except ValueError:
+                pass
+    return False
+
+
+def _wants_tabular_font(value: Any, col_config: Any) -> bool:
+    """Return True if the cell should use tabular (monospaced-digit) font.
+
+    Covers numbers AND date-like strings — anything where digits need to
+    align vertically across rows.
+    """
+    return _is_numeric_cell(value, col_config) or is_date_like(value)
+
+
+# Swatch column constants. Swatch cells render a small rounded color square
+# instead of text — used for series-keyed tables (e.g. donut-attached tables
+# where each row carries the parent chart's palette color). The square sits
+# inside the cell with the standard cell-x padding (4) and is vertically
+# centered against the row's effective band by the caller.
+_SWATCH_SIZE = 14
+_SWATCH_CORNER_RADIUS = 3
+
+
+def _render_swatch_cell(value: Any, col: str, row_idx: int, chart_id: str) -> str:
+    """Render a small rounded color square for a swatch-typed cell.
+
+    Cell value must be a hex color string (e.g. ``#3164a3``) or one of the
+    sanitizer-accepted keywords (``transparent`` / ``none``). Raises
+    ``ChartDataError`` on any non-color value — a column declared
+    ``swatch: true`` whose cell content is empty or non-color is a misconfig,
+    not paint. Failing fast points the author at the wrong column / wrong
+    data rather than silently shipping a half-broken table.
+    """
+    from dataface.core.render.errors import ChartDataError
+
+    color = sanitize_color(value, None) if isinstance(value, str) else None
+    if not color:
+        raise ChartDataError(
+            f"Column {col!r} declares swatch: true but row {row_idx} value "
+            f"{value!r} is not a CSS color. Swatch cells must be hex "
+            f"(e.g. '#3164a3') or 'transparent'. Either point swatch: true "
+            f"at a different column, or fix the data.",
+            chart_id=chart_id,
+        )
+    return (
+        f'<rect width="{_SWATCH_SIZE}" height="{_SWATCH_SIZE}" '
+        f'rx="{_SWATCH_CORNER_RADIUS}" fill="{color}"/>'
+    )
+
+
+def _render_spark_cell(
+    value: Any,
+    spark_config: SparkConfig,
+    cell_width: float,
+    row_height: float,
+    cell_font: FontStyle | None = None,
+    resolved_style: MergedChartsStyle | None = None,
+    column_max: float | None = None,
+) -> tuple[str, int]:
+    """Render a spark chart for a table cell.
+
+    Args:
+        value: Cell value (array for line/area/columns; scalar for bar/bar-normalize).
+        spark_config: SparkConfig instance with typed configuration
+        cell_width: Available cell width
+        row_height: Nominal row height used to size the spark mark. The mark's
+            visual size stays pinned to the nominal row height so wrapped
+            rows don't grow their spark vertically — the caller centers the
+            mark within the row's effective (possibly grown) height instead.
+        cell_font: Table FontStyle to inherit for bar/bar-normalize value labels.
+        column_max: Pre-computed column max for `bar` auto-max (None = use default).
+
+    Returns:
+        ``(svg_content, spark_height)``. ``svg_content`` is the inner SVG
+        (sans wrapper) for embedding under a translate-wrapped `<g>`; the
+        height is reported so the caller can vertical-center the mark
+        against the row's effective height. Empty string + 0 when the
+        value can't be rendered (e.g. non-numeric for bar variants).
+    """
+    from dataface.core.render.chart.spark import render_spark
+
+    if resolved_style is None:
+        raise ValueError(
+            "_render_spark_cell requires a resolved charts style (resolved_style)"
+        )
+    spark_type = spark_config.type
+
+    # Calculate spark dimensions to fit in cell
+    padding = 8
+    spark_width = spark_config.width or int(cell_width - (padding * 2))
+    spark_height = spark_config.height or int(row_height - 8)
+
+    # Cap dimensions
+    spark_width = min(spark_width, int(cell_width - padding))
+    spark_height = min(spark_height, int(row_height - 4))
+
+    # Build options dict from SparkConfig (exclude type/width/height, drop None values)
+    options = spark_config.model_dump(
+        exclude={"type", "width", "height"},
+        exclude_none=True,
+    )
+
+    # Auto-max: `bar` (no explicit ceiling) auto-scales width to the column
+    # data max. `bar-normalize` always uses an explicit `max:` (or the theme
+    # `default_max`) — the whole point of the variant is "% of ceiling," so
+    # silently rescaling to the data max would defeat the contract.
+    if spark_type == "bar" and spark_config.max is None and column_max is not None:
+        options["max"] = column_max
+
+    # For single-bar sparklines, only render when value is numeric.
+    # This lets mixed tables (text + numeric rows) use one spark config without
+    # replacing text cells with zero-width bars.
+    if spark_type in ("bar", "bar-normalize"):
+        if isinstance(value, bool):
+            return "", 0
+        if not isinstance(value, (int, float)):
+            try:
+                float(str(value))
+            except (TypeError, ValueError):
+                return "", 0
+
+    # Render the spark SVG
+    spark_svg = render_spark(
+        value,
+        spark_type,
+        width=spark_width,
+        height=spark_height,
+        font=cell_font,
+        resolved_style=resolved_style,
+        **options,
+    )
+
+    # Extract inner content from SVG (remove wrapper)
+    inner_match = re.search(r"<svg[^>]*>(.*?)</svg>", spark_svg, re.DOTALL)
+    if inner_match is None:
+        raise ValueError(f"render_spark returned invalid SVG: {spark_svg[:100]}")
+    return inner_match.group(1), spark_height
+
+
+def _count_rows_fitting_height(row_heights: list[int], available: float) -> int:
+    """Count leading rows whose cumulative height fits within ``available``.
+
+    Returns at least 1 (so the table renders at least one row even when the
+    first row is taller than the budget).
+    """
+    cumulative = 0.0
+    count = 0
+    for h in row_heights:
+        if cumulative + h > available and count >= 1:
+            break
+        cumulative += h
+        count += 1
+    return max(1, count)
+
+
+def _largest_safe_page_size(
+    row_heights: list[int], available: float, max_page_size: int
+) -> int:
+    """Largest ``size <= max_page_size`` such that every contiguous
+    ``size``-row window sums to ≤ ``available``.
+
+    Safe under mixed row heights: page 1 fitting doesn't imply page 2 fits.
+    Returns 1 at minimum so the table always renders something.
+    """
+    n = len(row_heights)
+    if n == 0:
+        return 1
+    for size in range(min(max_page_size, n), 0, -1):
+        if all(sum(row_heights[s : s + size]) <= available for s in range(0, n, size)):
+            return size
+    return 1
+
+
+def _max_page_sum(row_heights: list[int], page_size: int) -> int:
+    """Max over every contiguous page-sized window of ``row_heights``.
+
+    Shared between ``_resolve_visible_rows`` (table_height for paginated
+    auto-height tables) and the more-rows indicator placement so both sit
+    at the same y-coordinate across pages.
+    """
+    if not row_heights or page_size <= 0:
+        return 0
+    return max(
+        sum(row_heights[s : s + page_size])
+        for s in range(0, len(row_heights), page_size)
+    )
+
+
+def _resolve_visible_rows(
+    data: list[dict[str, Any]],
+    height: float | None,
+    title_height: float,
+    header_height: float,
+    padding: int,
+    row_height: int,
+    bottom_padding: int,
+    pagination: PaginationConfig | None = None,
+    page: int = 1,
+    row_heights: list[int] | None = None,
+    header_visible: bool = True,
+) -> tuple[float, list[dict[str, Any]], int, int, list[int] | None, int, int]:
+    """Resolve table height, visible rows, total page count, page offset, and rows-height.
+
+    Returns ``(table_height, visible_data, total_pages, page_offset,
+    visible_row_heights, rows_height, effective_row_height)``.
+    ``rows_height`` is the vertical extent used for the data-row section
+    (tallest page when paginated + multi-page, else this page's own rows) —
+    callers place pagination indicators off this value so controls sit at a
+    consistent y across pages.
+
+    ``effective_row_height`` equals ``row_height`` unless the anti-dangle
+    heuristic fired and squeezed it to collapse a 1-2 row trailing page.
+    The caller must use this value for all per-row drawing so the squeezed
+    geometry is consistent end-to-end.
+
+    When ``row_heights`` is provided, pagination splitting and fixed-height
+    row-count calculations operate on real cumulative heights; otherwise
+    the uniform ``row_height`` is used.
+    """
+    # Chart-local pagination is pre-merged into ``pagination`` by the cascade —
+    # read the resolved page_size off the merged value. When pagination is
+    # enabled but no page_size is set, default to ``len(data)`` so the bounded
+    # auto-shrink branch still fires: a small cell will then split into pages
+    # rather than silently dropping rows into the "+ N more rows" footer, which
+    # is reserved for the explicit pagination-disabled case.
+    if pagination is not None and pagination.enabled:
+        page_size = (
+            pagination.page_size
+            if pagination.page_size is not None
+            else (len(data) if data else 1)
+        )
+    else:
+        page_size = None
+    page = max(1, page)
+
+    # Header-body gap is the visual buffer between the header rule and the first
+    # data row. When the header is hidden, this gap must collapse to zero so the
+    # sizer (layout_sizing._get_table_height_from_data) and the renderer's final
+    # placement (current_y bump after the header section, ~line 2762) agree on
+    # total height. The squeezed-row path below mirrors the same conditional.
+    header_body_gap = int(row_height * 0.25) if header_visible else 0
+
+    def _slice_heights(start: int, count: int) -> list[int] | None:
+        if row_heights is None:
+            return None
+        return row_heights[start : start + count]
+
+    def _rows_height(visible_heights: list[int] | None, visible_n: int) -> int:
+        if visible_heights is not None:
+            return sum(visible_heights)
+        return visible_n * row_height
+
+    if height and height > 0:
+        table_height = height
+        available_height = (
+            table_height
+            - title_height
+            - header_height
+            - header_body_gap
+            - padding
+            - bottom_padding
+        )
+        if page_size is not None:
+            # Reserve pagination control height whenever pagination will
+            # fire — either because page_size splits the data, or because
+            # the allotted height fits fewer rows than the data.
+            #
+            # With variable row heights, the probe must check every page's
+            # window, not just the leading rows — otherwise a short page 1
+            # leads to a picked `effective` that overflows page 2.
+            def _safe_page_size(avail: float) -> int:
+                if row_heights is not None:
+                    return _largest_safe_page_size(row_heights, avail, page_size)
+                return min(max(1, int(avail / row_height)), page_size)
+
+            probe_effective = _safe_page_size(available_height)
+            if len(data) > probe_effective:
+                overflow = len(data) - probe_effective
+                # Anti-dangle: if the overflow is ≤ 2 rows, try squeezing
+                # row_height to fit all rows in available_height.  Only fire
+                # when row_heights is None (uniform rows); variable-height
+                # tables have row-specific measurements that can't be rescaled.
+                #
+                # Known pre-existing limitation: when row_role_spec inserts
+                # summary gaps (~0.4 * row_height per summary transition),
+                # available_height here does not subtract that reservation,
+                # so the squeezed layout can exceed the bounded card height
+                # by ~13px per gap. The non-squeeze bounded path below has
+                # the same blind spot. Fixing requires plumbing
+                # row_role_spec into pick_table_layout so we can count gaps
+                # over the visible slice; deferred pre-launch.
+                if row_heights is None and 0 < overflow <= _ANTI_DANGLE_MAX_OVERFLOW:
+                    squeezed = max(
+                        _ANTI_DANGLE_MIN_ROW_H, int(available_height // len(data))
+                    )
+                    squeeze_ratio = squeezed / row_height
+                    if (
+                        squeeze_ratio >= (1.0 - _ANTI_DANGLE_MAX_SQUEEZE)
+                        and squeezed * len(data) <= available_height
+                    ):
+                        squeezed_rh = len(data) * squeezed
+                        return (
+                            table_height,
+                            data,
+                            1,
+                            0,
+                            None,
+                            squeezed_rh,
+                            squeezed,
+                        )
+                # Pagination controls will render — re-pick effective with
+                # the reduced budget so rows leave room for the controls.
+                effective = _safe_page_size(
+                    available_height - _PAGINATION_CONTROL_HEIGHT
+                )
+            else:
+                effective = probe_effective
+            total_pages = max(1, -(-len(data) // effective)) if data else 1
+            page = min(page, total_pages)
+            start = (page - 1) * effective
+            visible_heights = _slice_heights(start, effective)
+            # Use the tallest page's rows_height so pagination controls sit
+            # at the same y across pages (otherwise they wobble as the user
+            # clicks prev/next on mixed-height data).
+            if row_heights is not None and total_pages > 1:
+                rows_height_out = _max_page_sum(row_heights, effective)
+            else:
+                rows_height_out = _rows_height(visible_heights, effective)
+            return (
+                table_height,
+                data[start : start + effective],
+                total_pages,
+                start,
+                visible_heights,
+                rows_height_out,
+                row_height,
+            )
+        if row_heights is not None:
+            max_rows = _count_rows_fitting_height(row_heights, available_height)
+        else:
+            max_rows = max(1, int(available_height / row_height))
+        visible_heights = _slice_heights(0, max_rows)
+        return (
+            table_height,
+            data[:max_rows],
+            1,
+            0,
+            visible_heights,
+            _rows_height(visible_heights, max_rows),
+            row_height,
+        )
+
+    if page_size is not None:
+        n_data = len(data)
+        overflow = n_data - page_size
+        # Anti-dangle (unbounded path): if a 1-2 row tail would create a
+        # second page, squeeze row_height to fit all rows on one page.
+        # Only fire for uniform-height rows (row_heights is None).
+        if (
+            row_heights is None
+            and n_data > 0
+            and 0 < overflow <= _ANTI_DANGLE_MAX_OVERFLOW
+        ):
+            squeeze_ratio = page_size / n_data
+            if squeeze_ratio >= (1.0 - _ANTI_DANGLE_MAX_SQUEEZE):
+                squeezed = max(
+                    _ANTI_DANGLE_MIN_ROW_H, int(round(row_height * squeeze_ratio))
+                )
+                squeezed_rows_height = squeezed * n_data
+                squeezed_header_body_gap = int(squeezed * 0.25) if header_visible else 0
+                squeezed_table_height = (
+                    title_height
+                    + header_height
+                    + squeezed_header_body_gap
+                    + squeezed_rows_height
+                    + padding
+                    + bottom_padding
+                )
+                return (
+                    squeezed_table_height,
+                    data,
+                    1,
+                    0,
+                    None,
+                    squeezed_rows_height,
+                    squeezed,
+                )
+        total_pages = max(1, -(-n_data // page_size)) if data else 1
+        page = min(page, total_pages)
+        start = (page - 1) * page_size
+        visible_data = data[start : start + page_size]
+        visible_heights = _slice_heights(start, page_size)
+        # Size to the tallest page so every page renders at the same height.
+        if row_heights is not None and total_pages > 1:
+            rows_height = _max_page_sum(row_heights, page_size)
+        else:
+            # Use page_size (not len(visible_data)) for uniform height across
+            # pages when paginating uniform-height rows; the last page may
+            # have fewer rows but keeps the same table height.
+            row_slots = page_size if total_pages > 1 else len(visible_data)
+            rows_height = _rows_height(visible_heights, row_slots)
+        table_height = (
+            title_height
+            + header_height
+            + header_body_gap
+            + rows_height
+            + padding
+            + bottom_padding
+        )
+        return (
+            table_height,
+            visible_data,
+            total_pages,
+            start,
+            visible_heights,
+            rows_height,
+            row_height,
+        )
+
+    num_rows = len(data)
+    rows_height = sum(row_heights) if row_heights is not None else num_rows * row_height
+    table_height = (
+        title_height
+        + header_height
+        + header_body_gap
+        + rows_height
+        + padding
+        + bottom_padding
+    )
+    return table_height, data, 1, 0, row_heights, rows_height, row_height
+
+
+def _compute_content_span(
+    columns: list[str],
+    col_widths: dict[str, float],
+    col_x_offsets: list[float],
+    padding_x: int,
+    cell_pad: int,
+    table_width: float,
+) -> tuple[float, float]:
+    """Compute (x1, x2) for horizontal elements spanning all columns.
+
+    Returns the cell-content edge: from the first column's content start
+    to the last column's content end. Used for header background, header
+    rules (continuous), row stripes, row rules, and summary/total rules
+    — all horizontal spans use this one function so they share a visible
+    right edge.
+
+    The cell-content edge sits cell_pad inside the outer cell bounds,
+    matching where text is already laid out. That gives text and rects
+    a shared visible edge.
+    """
+    if not columns or not col_x_offsets:
+        return 0, table_width
+    first_cell_x = padding_x + col_x_offsets[0]
+    last_col = columns[-1]
+    last_cell_x = padding_x + col_x_offsets[-1]
+    last_cw = col_widths.get(last_col, 100)
+    x1 = first_cell_x + cell_pad
+    x2 = last_cell_x + last_cw - cell_pad
+    return x1, x2
+
+
+def _render_header_section(
+    svg_parts: list[str],
+    markdown_config: Any,
+    columns: list[str],
+    column_configs: dict[str, TableColumnConfig],
+    colors: dict[str, str],
+    table_config: Any,
+    table_width: float,
+    header_height: float,
+    current_y: float,
+    padding_x: int,
+    col_x_offsets: list[float],
+    col_widths: dict[str, float],
+    col_lane_positions: dict[str, tuple[float, float, float, float, float]],
+    header_font: FontStyle,
+    wrapped_headers: dict[str, list[str]] | None = None,
+    cell_pad: int | None = None,
+    header_rule_width: float = 1.0,
+    rule_color: str | None = None,
+    header_rule_continuous: bool = False,
+    row_numbers: Any = None,
+) -> None:
+    """Render header background, border, and labels."""
+    header_font_size = int(header_font.size) if header_font.size is not None else 12
+    header_font_weight = (
+        str(header_font.weight) if header_font.weight is not None else "600"
+    )
+    effective_font_family = header_font.family
+    # Header background paints edge-to-edge across the full column span.
+    bg_x1, bg_x2 = _compute_content_span(
+        columns=columns,
+        col_widths=col_widths,
+        col_x_offsets=col_x_offsets,
+        padding_x=padding_x,
+        cell_pad=0,
+        table_width=table_width,
+    )
+    # Skip the header background rect when transparent — no point emitting
+    # invisible paint.
+    _hdr_bg = colors["header_background"]
+    if _hdr_bg and _hdr_bg.lower() != "transparent":
+        svg_parts.append(
+            f'<rect x="{bg_x1}" y="{current_y}" width="{bg_x2 - bg_x1}" '
+            f'height="{header_height}" '
+            f'fill="{_hdr_bg}"/>',
+        )
+    effective_rule_color = rule_color or colors["color"]
+    if header_rule_width > 0:
+        # Rules rendered as <rect> for consistent thickness at any browser
+        # scale. Integer y + integer height = exact pixel coverage.
+        rule_y = int(current_y + header_height - header_rule_width)
+        effective_pad = (
+            cell_pad
+            if cell_pad is not None
+            else table_config.column_layout.cell_padding
+        )
+        if header_rule_continuous and columns and col_x_offsets:
+            # Single unbroken rule spanning the cell-content edge — same
+            # extent as stripes and row rules so all right edges align.
+            x1, x2 = _compute_content_span(
+                columns=columns,
+                col_widths=col_widths,
+                col_x_offsets=col_x_offsets,
+                padding_x=padding_x,
+                cell_pad=effective_pad,
+                table_width=table_width,
+            )
+            svg_parts.append(
+                f'<rect x="{x1}" y="{rule_y}" width="{x2 - x1}" '
+                f'height="{header_rule_width}" fill="{effective_rule_color}" '
+                f'shape-rendering="crispEdges"/>',
+            )
+        else:
+            # Per-column rules: EVERY rule centers on the cell midpoint,
+            # matching where the header text and number tspan center.
+            # Rule width = max(widest wrapped header line, value lane
+            # extent) so the rule always covers whatever is visually
+            # anchored above it.  Text columns (no lane) use the widest
+            # header line plus minimal breathing.
+            _RULE_GAP = 4  # min px gap between adjacent per-column rules
+            measurer = get_font_measurer(effective_font_family)
+            resolved_wrapped = wrapped_headers or {}
+            for i, col in enumerate(columns):
+                cw = col_widths.get(col, 100)
+                cell_x = padding_x + col_x_offsets[i]
+                cell_left_bound = cell_x + _RULE_GAP
+                cell_right_bound = cell_x + cw - _RULE_GAP
+
+                col_config = column_configs.get(col)
+                display_name = (
+                    col_config.label if col_config and col_config.label else col
+                )
+                if display_name == col:
+                    display_name = slug_to_text(display_name)
+                # Use the WIDEST WRAPPED LINE (what's actually rendered),
+                # not the full unwrapped name.
+                lines = resolved_wrapped.get(col) or [display_name]
+                widest_line = max(lines, key=len)
+                label_w = measurer.measure(widest_line, header_font_size)
+
+                if col in col_lane_positions:
+                    # Numeric column: center rule on cell midpoint.
+                    # Rule width covers the widest content element — the
+                    # header line or the value lane, whichever is wider.
+                    _, _, _, content_left, content_right = col_lane_positions[col]
+                    lane_w = content_right - content_left
+                    rule_w = max(label_w, lane_w)
+                    center = cell_x + cw / 2
+                    x1 = center - rule_w / 2
+                    x2 = center + rule_w / 2
+                else:
+                    # Text column: header is left-aligned, so the rule is
+                    # too.  Width at least spans the label.
+                    x1 = cell_x + effective_pad
+                    x2 = x1 + max(label_w, cw - 2 * effective_pad)
+
+                # Clamp to cell + gap so adjacent column rules don't touch.
+                x1 = max(x1, cell_left_bound)
+                x2 = min(x2, cell_right_bound)
+                if x2 > x1:
+                    svg_parts.append(
+                        f'<rect x="{x1}" y="{rule_y}" width="{x2 - x1}" '
+                        f'height="{header_rule_width}" fill="{effective_rule_color}" '
+                        f'shape-rendering="crispEdges"/>',
+                    )
+
+    markdown_colors = (
+        markdown_config.dark
+        if is_dark_color(colors["background"])
+        else markdown_config.light
+    )
+    link_color = markdown_colors.link_color
+    header_line_height = header_font_size + table_config.text_baseline_offset
+    resolved_wrapped_headers = wrapped_headers or {}
+
+    # Bottom-align all headers: position every header so its last line
+    # sits at the same baseline, creating a firm line before values start.
+    bottom_baseline = current_y + header_height - table_config.text_baseline_offset
+
+    for i, col in enumerate(columns):
+        cell_x = padding_x + col_x_offsets[i]
+
+        effective_pad = (
+            cell_pad
+            if cell_pad is not None
+            else table_config.column_layout.cell_padding
+        )
+        cw = col_widths.get(col, 100)
+
+        # Synthetic row-number column: render row_numbers.header with the
+        # author-selected alignment. Skip all column-config lookups.
+        if col == _ROW_NUMBER_COL and row_numbers is not None:
+            display_name = row_numbers.header
+            text_fill = colors["label_color"]
+            if row_numbers.align == "right":
+                x = cell_x + cw - effective_pad
+                anchor = "end"
+            else:
+                x = cell_x + effective_pad
+                anchor = "start"
+            y = bottom_baseline
+            escaped_name = html_module.escape(display_name)
+            svg_parts.append(
+                f'<text x="{x}" y="{y}" '
+                f'font-size="{header_font_size}" font-weight="{header_font_weight}" fill="{text_fill}" '
+                f'text-anchor="{anchor}" '
+                f'font-family="{effective_font_family}">'
+                f"{escaped_name}</text>",
+            )
+            continue
+
+        col_config = column_configs.get(col)
+        display_name = (col_config.label if col_config else None) or slug_to_text(col)
+        _header_case = header_font.case or "none"
+        display_name = apply_case(display_name, _header_case)
+        display_lines = resolved_wrapped_headers.get(col) or [display_name]
+        header_link = col_config.header_link if col_config else None
+        text_fill = link_color if header_link else colors["label_color"]
+
+        # STRONG CENTER-ON-MIDPOINT INVARIANT:
+        #   - Numeric columns: header centers on cell midpoint (same point
+        #     where the number tspan centers and the per-column rule
+        #     centers).
+        #   - Text columns: header left-aligns at cell_x + pad.
+        # No fallbacks, no conditional right-alignment, no centered_fit
+        # calculations. If the header would overflow, the wrap path shrinks
+        # or token-splits it in ``resolve_wrapped_headers``.
+        if col in col_lane_positions:
+            x = cell_x + cw / 2
+            anchor = "middle"
+        else:
+            x = cell_x + effective_pad
+            anchor = "start"
+
+        if header_link:
+            escaped_href = html_module.escape(header_link, quote=True)
+            svg_parts.append(f'<a href="{escaped_href}">')
+
+        if len(display_lines) > 1:
+            lines = display_lines
+            start_y = bottom_baseline - (len(lines) - 1) * header_line_height
+            # Emit <title> only when wrap-two/truncate adds ellipsis — the
+            # visible lines don't fully represent the original display_name.
+            is_truncated = any("…" in ln for ln in lines)
+            multi_title = (
+                f"<title>{html_module.escape(display_name)}</title>"
+                if is_truncated
+                else ""
+            )
+            svg_parts.append(
+                f'<text x="{x}" '
+                f'font-size="{header_font_size}" font-weight="{header_font_weight}" fill="{text_fill}" '
+                f'text-anchor="{anchor}" '
+                f'font-family="{effective_font_family}">'
+                f"{multi_title}",
+            )
+            for li, line in enumerate(lines):
+                ly = start_y + li * header_line_height
+                escaped_line = html_module.escape(line)
+                svg_parts.append(f'<tspan x="{x}" y="{ly}">{escaped_line}</tspan>')
+            svg_parts.append("</text>")
+        else:
+            y = bottom_baseline
+            visible = display_lines[0]
+            escaped_name = html_module.escape(visible)
+            # Emit <title> only when clip/truncate shortened the label — the
+            # title carries the full text so AT is accessible while the visual
+            # text is abbreviated.  Skip when visible == full name (no tooltip needed).
+            title_attr = (
+                f"<title>{html_module.escape(display_name)}</title>"
+                if visible != display_name
+                else ""
+            )
+            svg_parts.append(
+                f'<text x="{x}" y="{y}" '
+                f'font-size="{header_font_size}" font-weight="{header_font_weight}" fill="{text_fill}" '
+                f'text-anchor="{anchor}" '
+                f'font-family="{effective_font_family}">'
+                f"{title_attr}{escaped_name}</text>",
+            )
+
+        if header_link:
+            svg_parts.append("</a>")
+
+
+_FIT_BREATH = 4  # px breathing room — content shouldn't kiss cell edges
+
+
+def _has_overflow(
+    columns: list[str],
+    data: list[dict[str, Any]],
+    column_configs: dict[str, TableColumnConfig],
+    col_widths: dict[str, float],
+    cell_pad: int,
+    cell_font: FontStyle,
+    *,
+    header_font: FontStyle | None = None,
+    wrap: bool,
+    formats: dict[str, str] | None = None,
+    header_visible: bool = True,
+) -> bool:
+    """Return True if any column's widest value OR header exceeds its content area.
+
+    When *header_font* is given, also checks whether the column label
+    (display name) fits in a single line.  Headers that would need to wrap
+    count as overflow so the fit cascade can shrink fonts to avoid awkward
+    line breaks.
+
+    When *wrap* is True, text cells are skipped — they'll wrap rather than
+    overflow, so only numeric/date columns drive the cascade.
+
+    When *header_visible* is False, the header label is excluded from the
+    overflow check — a hidden header can't drive the fit cascade.
+    """
+    font_size = float(cell_font.size) if cell_font.size is not None else 12.0
+    measurer = get_font_measurer(cell_font.family)
+    for col in columns:
+        col_config = column_configs.get(col)
+        # Swatch columns render a fixed 14×14 <rect>, not the cell text. A 7-char
+        # hex string in a 24px-wide swatch column would otherwise trip the
+        # text-overflow check and kick off the table-wide fit cascade.
+        if col_config and col_config.swatch:
+            continue
+        fmt = col_config.format if col_config else None
+        cw = col_widths.get(col, 100)
+        content_area = cw - cell_pad * 2 - _FIT_BREATH
+
+        # Check header label overflow (single-line fit) — only for short
+        # labels in multi-column layouts where wrapping looks awkward.
+        # Long headers in single-column tables should wrap gracefully.
+        # Skipped when header.visible: false — a hidden label can't overflow.
+        if header_font is not None and header_visible and len(columns) > 1:
+            _hfs = (
+                float(header_font.size) if header_font.size is not None else font_size
+            )
+            display_name = col_config.label if col_config and col_config.label else col
+            display_name = (
+                slug_to_text(display_name) if display_name == col else display_name
+            )
+            _header_case = header_font.case or "none"
+            display_name = apply_case(display_name, _header_case)
+            # Only flag short labels (≤12 chars) as overflow candidates —
+            # "Growth", "Margin" shouldn't wrap, but "Opportunities
+            # Subscription Start Date" is fine to wrap.
+            if len(display_name) <= 12:
+                header_w = measurer.measure(display_name, _hfs)
+                if header_w > content_area:
+                    return True
+
+        for row in data[:50]:
+            val = row.get(col, "")
+            # In wrap mode, text cells wrap instead of overflow — skip them.
+            if wrap and not (_is_numeric_cell(val, col_config) or is_date_like(val)):
+                continue
+            rendered = format_table_cell_value(val, fmt, formats)
+            text_w = measurer.measure(rendered, font_size)
+            if text_w > content_area:
+                return True
+    return False
+
+
+def _compute_lane_positions(
+    rows: list[dict[str, Any]],
+    columns: list[str],
+    column_configs: dict[str, TableColumnConfig],
+    col_widths: dict[str, float],
+    col_x_offsets: list[float],
+    padding_x: int,
+    cell_pad: int,
+    cell_font: FontStyle,
+    column_when_rules: dict[str, tuple[Any, ...]] | None = None,
+    formats: dict[str, str] | None = None,
+) -> dict[str, tuple[float, float, float, float, float]]:
+    """Compute fixed (prefix_x, number_x, suffix_x, content_left, content_right) per numeric column.
+
+    Positions are constant across all rows so currency symbols, magnitude
+    letters, and percent signs form clean vertical columns.
+
+    **Center-on-midpoint invariant** (see ``DESIGN.md``): the number tspan
+    is anchored so its horizontal center sits at the cell's content
+    midpoint. Because the tspan renders with ``text-anchor="end"``, that
+    means its right edge (``number_x``) sits at
+    ``cell_midpoint + max_number_w / 2``. Header and per-column rule both
+    center on the same midpoint — everything reads as one column.
+
+    ``content_left`` and ``content_right`` mark the extent of the full
+    content including prefix and suffix; they're what the header rule
+    uses to size itself.
+    """
+    # numeric=True critical here: numeric cells render with the DFT Sans
+    # Tabular stack (tabular digit widths), which are noticeably wider
+    # than Inter's proportional digits.  Measuring with Inter would
+    # under-estimate content width by ~4px per number at 11px, pushing
+    # the prefix right on top of the value.
+    font_size = float(cell_font.size) if cell_font.size is not None else 12.0
+    measurer = get_font_measurer(cell_font.family, numeric=True)
+    positions: dict[str, tuple[float, float, float, float, float]] = {}
+    for i, col in enumerate(columns):
+        col_config = column_configs.get(col)
+        fmt = col_config.format if col_config else None
+        cw = col_widths.get(col, 100)
+        cell_x = padding_x + col_x_offsets[i]
+        # Content midpoint respects horizontal padding on both sides so
+        # that if a caller configures asymmetric padding, the midpoint
+        # still sits in the middle of the *visible content area*.
+        content_area_left = cell_x + cell_pad
+        content_area_right = cell_x + cw - cell_pad
+        cell_midpoint = (content_area_left + content_area_right) / 2
+
+        max_content_w = 0.0
+        max_prefix_w = 0.0
+        max_suffix_w = 0.0
+        col_suffix = ""
+        is_date_col = False
+        when_rules = (
+            column_when_rules.get(col) if column_when_rules is not None else None
+        )
+        glyph_possible = bool(when_rules) or (
+            col_config is not None and col_config.glyph is not None
+        )
+        for row in rows:
+            raw = row.get(col, "")
+            if _is_numeric_cell(raw, col_config):
+                try:
+                    num_val = float(raw) if isinstance(raw, str) else raw
+                except (ValueError, TypeError):
+                    continue
+                if not isinstance(num_val, (int, float)) or isinstance(num_val, bool):
+                    continue
+                _p, num_str, _s = format_kpi_parts(num_val, fmt, formats)
+                if not col_suffix and _s:
+                    col_suffix = _s
+                num_str = num_str.removeprefix("-")
+                w = measurer.measure(num_str, font_size)
+                # Glyph replaces the format prefix in the prefix lane,
+                # so measure whichever the cell will render.
+                cell_glyph: str | None = None
+                if glyph_possible:
+                    cell_glyph, _ = resolve_cell_glyph(col_config, raw, when_rules)
+                effective_prefix = cell_glyph or _p
+                if effective_prefix:
+                    max_prefix_w = max(
+                        max_prefix_w,
+                        measurer.measure(effective_prefix, font_size),
+                    )
+                if _s:
+                    max_suffix_w = max(
+                        max_suffix_w,
+                        measurer.measure(_s, font_size),
+                    )
+                max_content_w = max(max_content_w, w)
+            elif is_date_like(raw):
+                is_date_col = True
+                w = measurer.measure(str(raw).strip(), font_size)
+                max_content_w = max(max_content_w, w)
+
+        if max_content_w > 0:
+            # CORE INVARIANT: number tspan center == cell midpoint.
+            # tspan is right-anchored at number_x, so its left edge is at
+            # (number_x - max_content_w). Setting the center to midpoint
+            # gives number_x = cell_midpoint + max_content_w / 2.
+            number_x = cell_midpoint + max_content_w / 2
+            if is_date_col:
+                suffix_gap = 0
+            else:
+                suffix_gap = 3 if col_suffix.strip() in _WORD_SUFFIXES else 0
+            suffix_x = number_x + suffix_gap
+            # Prefix sits 3px left of the widest number so the two never
+            # visually kiss.  Matches suffix_gap above.  Rows narrower
+            # than the widest get a larger gap naturally.  Restores the
+            # 2px gap from the original three-lane rendering (PR #1186)
+            # that #1244 removed on the premise that measured tabular
+            # widths were accurate enough for zero-gap to read as
+            # "touching, not overlapping" — in practice it reads as a
+            # kiss, not a separator.
+            prefix_gap = 3 if max_prefix_w > 0 else 0
+            prefix_x = number_x - max_content_w - prefix_gap
+            # Content extent: from prefix's left edge to suffix's right
+            # edge — what per-column rules and header rules reference.
+            content_left = prefix_x - max_prefix_w
+            content_right = suffix_x + max_suffix_w
+            # Defensive clamp: if prefix or suffix would sit outside the
+            # cell's content area (asymmetric value — e.g. "$" prefix but
+            # no suffix), shift the whole band toward the side that has
+            # headroom. The shift amount is capped by the available
+            # headroom so we never trade one overflow for another. The
+            # fit cascade should have already shrunk font size to prevent
+            # real overflow; this clamp handles the subtler asymmetric
+            # padding case.
+            overflow_left = content_area_left - content_left
+            overflow_right = content_right - content_area_right
+            if overflow_left > 0 and overflow_right < 0:
+                # Content is too far left; shift right up to the right
+                # headroom (-overflow_right).
+                shift = min(overflow_left, -overflow_right)
+                prefix_x += shift
+                number_x += shift
+                suffix_x += shift
+                content_left += shift
+                content_right += shift
+            elif overflow_right > 0 and overflow_left < 0:
+                # Content is too far right; shift left up to the left
+                # headroom (-overflow_left).
+                shift = min(overflow_right, -overflow_left)
+                prefix_x -= shift
+                number_x -= shift
+                suffix_x -= shift
+                content_left -= shift
+                content_right -= shift
+            positions[col] = (
+                prefix_x,
+                number_x,
+                suffix_x,
+                content_left,
+                content_right,
+            )
+    return positions
+
+
+def _compute_wrap_layout(
+    rows: list[dict[str, Any]],
+    text_columns: list[str],
+    column_configs: dict[str, Any],
+    col_widths: dict[str, float],
+    cell_pad: int,
+    font_size: int,
+    row_height: int,
+    text_baseline_offset: float,
+    measurer: Any,
+    formats: dict[str, str] | None = None,
+) -> tuple[list[int], list[dict[str, list[str]]]]:
+    """Pre-compute per-row heights and cached wrapped lines for text cells.
+
+    Returns ``(heights, wrapped_lines_per_row)``. ``wrapped_lines_per_row[i]``
+    maps a text column to its wrapped line list for row ``i``. Cells that
+    need no wrapping (single-line fit, empty value, or the column has no
+    measurable width) are absent from the map — render path falls back to
+    the single-line path for those.
+
+    Rows whose cells all fit on one line keep the configured ``row_height``
+    verbatim; wrapped rows grow by
+    ``max_lines * line_height - text_baseline_offset + 2*cell_pad`` (the
+    offset subtraction keeps top/bottom margins symmetric).
+    We never shrink below ``row_height`` (``max(row_height, grown)``) so a
+    user who set a generous ``row.height`` keeps their spacing.
+    ``text_columns`` must already exclude the row-number synthetic column.
+    """
+    line_height = font_size + text_baseline_offset
+    heights: list[int] = []
+    wrapped_by_row: list[dict[str, list[str]]] = []
+    for row in rows:
+        max_lines = 1
+        row_wraps: dict[str, list[str]] = {}
+        for col in text_columns:
+            col_config = column_configs.get(col)
+            value = row.get(col, "")
+            # Swatch columns render a fixed-size <rect>, not text — the cell's
+            # value (a hex color) is paint, not content. Excluding them keeps
+            # narrow swatch columns from inflating row height by "wrapping"
+            # the hex string into one-character-per-line.
+            if col_config and col_config.swatch:
+                continue
+            if _is_numeric_cell(value, col_config) or is_date_like(value):
+                continue
+            fmt = col_config.format if col_config else None
+            display = format_table_cell_value(value, fmt, formats)
+            if not display:
+                continue
+            content_w = col_widths.get(col, 100) - cell_pad * 2
+            if content_w <= 0:
+                continue
+            # Fast path: if the cell already fits on one line, skip the
+            # (much more expensive) word-boundary wrap search. Saves the
+            # bulk of wrap_text_precise calls on wide columns / short text.
+            if measurer.measure(display, float(font_size)) <= content_w:
+                continue
+            lines = wrap_text_precise(display, content_w, float(font_size), measurer)
+            if lines:
+                row_wraps[col] = lines
+                max_lines = max(max_lines, len(lines))
+        wrapped_by_row.append(row_wraps)
+        if max_lines <= 1:
+            heights.append(row_height)
+        else:
+            # Subtract one text_baseline_offset so the bottom margin equals
+            # the top margin (cell_pad on each side). Without this the last
+            # baseline sits too close to the bottom edge and wrapped cells
+            # read as top-weighted.
+            grown = int(
+                round(max_lines * line_height - text_baseline_offset + 2 * cell_pad)
+            )
+            heights.append(max(row_height, grown))
+    return heights, wrapped_by_row
+
+
+def _render_data_rows(
+    svg_parts: list[str],
+    *,
+    markdown_config: Any,
+    table_config: Any,
+    rows: list[dict[str, Any]],
+    columns: list[str],
+    column_configs: dict[str, TableColumnConfig],
+    column_when_rules: dict[str, tuple[Any, ...]],
+    colors: dict[str, str],
+    col_widths: dict[str, float],
+    col_x_offsets: list[float],
+    col_lane_positions: dict[str, tuple[float, float, float, float, float]],
+    padding_x: int,
+    current_y: float,
+    row_height: int,
+    cell_font: FontStyle,
+    table_width: float,
+    cell_pad: int | None = None,
+    symbol_mode: str = "all",
+    row_rule_width: float = 0.0,
+    summary_rule_width: float = 0.0,
+    rule_color: str | None = None,
+    row_role_spec: str | None = None,
+    summary_font_weight: str | None = None,
+    role_summary: TableRowRoleStyle | None = None,
+    role_total: TableRowRoleStyle | None = None,
+    resolved_style: MergedChartsStyle | None = None,
+    row_numbers: Any = None,
+    page_offset: int = 0,
+    row_heights: list[int] | None = None,
+    wrapped_lines_by_row: list[dict[str, list[str]]] | None = None,
+    wrap: bool,
+    chart_root_link: str | None = None,
+    chart_id: str = "",
+) -> None:
+    """Render all visible table rows.
+
+    symbol_mode controls prefix/suffix rendering:
+      "all"      — every row shows full formatted value (default)
+      "anchors"  — first data row and summary/total rows show full value;
+                   plain middle data rows strip currency prefix and
+                   magnitude/unit suffix. The "anchor" rows structurally
+                   guide the reader at the top and bottom of the value field.
+    """
+    from dataface.core.compile.models.chart.authored import SparkConfig
+
+    effective_font_family: str = cell_font.family  # type: ignore[assignment]
+    assert (
+        effective_font_family is not None
+    ), "_render_data_rows requires cell_font.family"
+    font_size = int(cell_font.size) if cell_font.size is not None else 12
+    if cell_pad is None:
+        cell_pad = int(table_config.column_layout.cell_padding)
+    text_offset = table_config.text_baseline_offset
+    truncation_measurer = get_font_measurer(cell_font.family)
+
+    # Pre-compute column max for `bar` sparks (absolute magnitude, no
+    # explicit ceiling). `bar-normalize` deliberately does NOT auto-max —
+    # see _render_spark_cell for the rationale.
+    bar_auto_max: dict[str, float | None] = {}
+    for col in columns:
+        col_cfg = column_configs.get(col)
+        if (
+            col_cfg
+            and isinstance(col_cfg.spark, SparkConfig)
+            and col_cfg.spark.type == "bar"
+            and col_cfg.spark.max is None
+        ):
+            non_null = [
+                n for row in rows if (n := coerce_numeric(row.get(col))) is not None
+            ]
+            bar_auto_max[col] = max(non_null) if non_null else None
+
+    # Column names for link resolution (stable across rows)
+    all_data_columns = list(rows[0].keys()) if rows else []
+
+    # Extra breathing room before summary/total rows so the double rule
+    # doesn't crowd the last data row. Roughly half a row_height.
+    _SUMMARY_GAP = int(row_height * 0.4)
+    summary_gap_accum = 0
+    # Running y-offset from variable per-row heights (used when row_heights provided)
+    cumulative_row_height = 0.0
+
+    # Row rules are deferred here and flushed AFTER the loop so they paint on
+    # top of all fill rects. SVG document order = z-order: later = higher.
+    row_rule_parts: list[str] = []
+
+    # Scale domain is computed from detail rows only. Including summary/total rows
+    # would skew min/max — a grand-total cell is often 10-100x any single detail
+    # value, which crushes the detail-row gradient toward the low end of the palette.
+    scale_rows = [
+        r for r in rows if not is_summary_role(resolve_row_role(row_role_spec, r))
+    ]
+
+    for row_idx, row in enumerate(rows):
+        # Resolve per-row semantic role (value/summary/total)
+        role = resolve_row_role(row_role_spec, row)
+        row_is_summary = is_summary_role(role)
+        row_is_total = is_total_role(role)
+
+        # Add breathing room before the first summary/total row.
+        if row_is_summary and row_idx > 0:
+            prev_role = resolve_row_role(row_role_spec, rows[row_idx - 1])
+            if not is_summary_role(prev_role):
+                summary_gap_accum += _SUMMARY_GAP
+
+        per_row_height = row_heights[row_idx] if row_heights is not None else row_height
+        # Snap row_y to integer: cumulative float additions (row_height, padding)
+        # can drift sub-pixel and push 1px rules onto fractional rows, causing them to
+        # rasterize across two rows at reduced opacity. Round at the emit boundary so
+        # the sizing pipeline retains float precision while SVG coordinates stay crisp.
+        if row_heights is not None:
+            row_y = int(round(current_y + cumulative_row_height + summary_gap_accum))
+        else:
+            row_y = int(round(current_y + (row_idx * row_height) + summary_gap_accum))
+
+        # Compute row-rule draw condition and reserve at the TOP of the loop —
+        # before any fill rects are emitted. Every fill in this iteration uses
+        # fill_height (= per_row_height - rule_reserve_px) so the rule band
+        # at the bottom of the row stays clear and fills can't bleed past it.
+        is_last_row = row_idx == len(rows) - 1
+        next_is_summary = False
+        if not is_last_row:
+            next_role = resolve_row_role(row_role_spec, rows[row_idx + 1])
+            next_is_summary = is_summary_role(next_role)
+        will_draw_row_rule = (
+            row_rule_width > 0
+            and not is_last_row
+            and not next_is_summary
+            and not row_is_summary
+        )
+        # Promote sub-pixel rule widths to 1px: a 0.5px rule is invisible on
+        # every display we ship to. Zero means "no rule" and is never rounded up.
+        rule_reserve_px = (
+            max(1, int(round(row_rule_width))) if will_draw_row_rule else 0
+        )
+        fill_height = per_row_height - rule_reserve_px
+
+        # Stripe: suppress on summary rows (they stand out against clean bg).
+        # Also skip when the stripe color is transparent — no point emitting
+        # invisible rects, and some SVG renderers still treat "transparent"
+        # as a paint operation that interacts with other elements.
+        stripe_fill = colors["row_stripe"]
+        stripes_enabled = stripe_fill and stripe_fill.lower() != "transparent"
+        if row_idx % 2 == 1 and not row_is_summary and stripes_enabled:
+            stripe_x1, stripe_x2 = _compute_content_span(
+                columns=columns,
+                col_widths=col_widths,
+                col_x_offsets=col_x_offsets,
+                padding_x=padding_x,
+                cell_pad=0,
+                table_width=table_width,
+            )
+            svg_parts.append(
+                f'<rect x="{stripe_x1}" y="{row_y}" '
+                f'width="{stripe_x2 - stripe_x1}" height="{fill_height}" '
+                f'fill="{stripe_fill}"/>',
+            )
+
+        # Per-role background fill from row.roles.summary / row.roles.total.
+        role_bg_raw = None
+        if row_is_total and role_total and role_total.background:
+            role_bg_raw = role_total.background
+        elif row_is_summary and role_summary and role_summary.background:
+            role_bg_raw = role_summary.background
+        role_bg = sanitize_color(role_bg_raw, None) if role_bg_raw else None
+        if role_bg:
+            bg_x1, bg_x2 = _compute_content_span(
+                columns=columns,
+                col_widths=col_widths,
+                col_x_offsets=col_x_offsets,
+                padding_x=padding_x,
+                cell_pad=0,
+                table_width=table_width,
+            )
+            svg_parts.append(
+                f'<rect x="{bg_x1}" y="{row_y}" '
+                f'width="{bg_x2 - bg_x1}" height="{fill_height}" '
+                f'fill="{role_bg}"/>',
+            )
+
+        # Summary rule ABOVE the summary row. Decoupled from row_rule_width:
+        # summary_rule_width defaults to row_rule_width (backward compat) but
+        # can be set independently so BI/Classic variants get summary rules
+        # without body row rules.
+        # Single rule for "summary"; double rule (two rects + 1px gap) for "total".
+        if row_is_summary and summary_rule_width > 0:
+            effective_rule_color = rule_color or colors["color"]
+            rule_x1, rule_x2 = _compute_content_span(
+                columns=columns,
+                col_widths=col_widths,
+                col_x_offsets=col_x_offsets,
+                padding_x=padding_x,
+                cell_pad=cell_pad,
+                table_width=table_width,
+            )
+            line_h = max(1, int(summary_rule_width))
+            if row_is_total:
+                gap = 1
+                y_upper = row_y - line_h - gap - line_h
+                y_lower = row_y - line_h
+                svg_parts.append(
+                    f'<rect x="{rule_x1}" y="{y_upper}" '
+                    f'width="{rule_x2 - rule_x1}" height="{line_h}" '
+                    f'fill="{effective_rule_color}" '
+                    f'shape-rendering="crispEdges"/>',
+                )
+                svg_parts.append(
+                    f'<rect x="{rule_x1}" y="{y_lower}" '
+                    f'width="{rule_x2 - rule_x1}" height="{line_h}" '
+                    f'fill="{effective_rule_color}" '
+                    f'shape-rendering="crispEdges"/>',
+                )
+            else:
+                y_single = row_y - line_h
+                svg_parts.append(
+                    f'<rect x="{rule_x1}" y="{y_single}" '
+                    f'width="{rule_x2 - rule_x1}" height="{line_h}" '
+                    f'fill="{effective_rule_color}" '
+                    f'shape-rendering="crispEdges"/>',
+                )
+
+        # Row rule BELOW each row — deferred into row_rule_parts so it paints
+        # on top of all fill rects. Draw condition and reserve were computed at
+        # the top of this iteration; will_draw_row_rule / rule_reserve_px drive
+        # both the fill geometry and the rule geometry from the same values.
+        if will_draw_row_rule:
+            effective_rule_color = rule_color or colors["color"]
+            # rule_y sits at the bottom of the fill band. row_y is integer
+            # (pixel-snapped); per_row_height may be float (anti-dangle
+            # squeeze), so rule_y may be fractional — SVG renders it fine.
+            rule_y = row_y + per_row_height - rule_reserve_px
+            rule_x1, rule_x2 = _compute_content_span(
+                columns=columns,
+                col_widths=col_widths,
+                col_x_offsets=col_x_offsets,
+                padding_x=padding_x,
+                cell_pad=cell_pad,
+                table_width=table_width,
+            )
+            row_rule_parts.append(
+                f'<rect x="{rule_x1}" y="{rule_y}" width="{rule_x2 - rule_x1}" '
+                f'height="{rule_reserve_px}" fill="{effective_rule_color}" '
+                f'shape-rendering="crispEdges"/>',
+            )
+
+        cumulative_row_height += per_row_height
+
+        for i, col in enumerate(columns):
+            cw = col_widths.get(col, 100)
+            value = row.get(col, "")
+            cell_x = padding_x + col_x_offsets[i]
+            y = row_y + (per_row_height / 2) + text_offset
+
+            # Synthetic row-number cell — absolute 1-based index across pages.
+            # Summary/total rows render blank (the sequence is for data rows).
+            if col == _ROW_NUMBER_COL and row_numbers is not None:
+                if not (row_is_summary or row_is_total):
+                    absolute_index = page_offset + row_idx + 1
+                    if row_numbers.align == "right":
+                        rn_x = cell_x + cw - cell_pad
+                        rn_anchor = "end"
+                    else:
+                        rn_x = cell_x + cell_pad
+                        rn_anchor = "start"
+                    svg_parts.append(
+                        f'<text x="{rn_x}" y="{y}" '
+                        f'font-size="{font_size}" fill="{colors["muted"]}" '
+                        f'text-anchor="{rn_anchor}" '
+                        f'font-family="{_SANS_NUMERIC_FONT_STACK}">'
+                        f"{absolute_index}</text>",
+                    )
+                continue
+
+            col_config = column_configs.get(col)
+            spark_config = col_config.spark if col_config else None
+
+            if col_config and col_config.swatch:
+                # _render_swatch_cell raises ChartDataError on a non-color
+                # value — a swatch column with a bad cell is a misconfig,
+                # not a rendering choice. The error names column + row index
+                # so the author can find the cell that broke.
+                swatch_content = _render_swatch_cell(
+                    value, col=col, row_idx=page_offset + row_idx, chart_id=chart_id
+                )
+                swatch_x = _px(cell_x + 4)
+                swatch_y = row_y + (per_row_height - _SWATCH_SIZE) / 2
+                svg_parts.append(
+                    f'<g transform="translate({swatch_x}, {swatch_y})">{swatch_content}</g>',
+                )
+                continue
+
+            if isinstance(spark_config, SparkConfig) and value is not None:
+                spark_content, spark_height = _render_spark_cell(
+                    value,
+                    spark_config,
+                    cw,
+                    row_height,
+                    cell_font=cell_font,
+                    resolved_style=resolved_style,
+                    column_max=bar_auto_max.get(col),
+                )
+                if spark_content:
+                    spark_x = _px(cell_x + 4)
+                    # Center the spark mark within the row's effective band.
+                    # per_row_height >= nominal row_height; wrapped rows grow
+                    # to fit their tallest text column, so a fixed top-of-row
+                    # offset would leave the spark hugging the top.
+                    spark_y = row_y + (per_row_height - spark_height) / 2
+                    svg_parts.append(
+                        f'<g transform="translate({spark_x}, {spark_y})">{spark_content}</g>',
+                    )
+                    continue
+
+            # Resolve base styles (may be field refs resolved per-row)
+            cell_background = None
+            if col_config and col_config.background:
+                cell_background = sanitize_color(
+                    resolve_table_style_value(col_config.background, row),
+                    None,
+                )
+
+            # Overlay scale + when conditional formatting
+            has_scale = col_config and col_config.scale
+            when_rules = column_when_rules.get(col)
+            overrides: dict[str, Any] = (
+                resolve_conditional_styles(when_rules, value) if when_rules else {}
+            )
+            cond_color: str | None = None
+            cond_fw: str | float | None = None
+            cond_style: str | None = None
+            cond_decoration: str | None = None
+
+            if has_scale:
+                assert col_config is not None
+                col_format = (
+                    resolve_format(
+                        col_config.format,
+                        resolved_style.formats if resolved_style else None,
+                    )
+                    or None
+                )
+                cond_bg, cond_clr, cond_fw, cond_style, cond_decoration = (
+                    resolve_cell_conditional_styles(
+                        col_config,
+                        value,
+                        scale_rows,
+                        when_rules=when_rules,
+                        col_format=col_format,
+                        row_role=role,
+                        col_name=col,
+                    )
+                )
+                if cond_bg is not None:
+                    cell_background = sanitize_color(cond_bg, None)
+                if cond_clr is not None:
+                    cond_color = cond_clr
+            elif when_rules:
+                if "background" in overrides:
+                    cell_background = sanitize_color(overrides["background"], None)
+                cond_color = overrides.get("color")
+                cond_fw = overrides.get("weight")
+                cond_style = overrides.get("style")
+                cond_decoration = overrides.get("decoration")
+
+            if cell_background:
+                svg_parts.append(
+                    f'<rect x="{cell_x}" y="{row_y}" width="{cw}" height="{fill_height}" '
+                    f'fill="{cell_background}"/>',
+                )
+
+            cell_glyph, cell_glyph_color = resolve_cell_glyph_from_overrides(
+                col_config, overrides
+            )
+
+            is_numeric = _is_numeric_cell(value, col_config)
+            fmt = col_config.format if col_config else None
+
+            # Resolve cell link: column link takes priority; chart-root link is the fallback.
+            link_raw = col_config.link if col_config else None
+            if link_raw is None:
+                link_raw = chart_root_link
+            cell_link: str | None = None
+            if link_raw:
+                cell_link = resolve_cell_link_with_board(
+                    link_raw, row, all_data_columns
+                )
+
+            fill_color = colors["color"]
+            if cell_link:
+                _md_colors = (
+                    markdown_config.dark
+                    if is_dark_color(colors["background"])
+                    else markdown_config.light
+                )
+                fill_color = _md_colors.link_color
+            elif cond_color:
+                fill_color = sanitize_color(cond_color, fill_color)
+            elif col_config and col_config.font and col_config.font.color:
+                fill_color = sanitize_color(
+                    resolve_table_style_value(col_config.font.color, row),
+                    fill_color,
+                )
+
+            font_weight_attr = ""
+            if cond_fw and cond_fw in VALID_FONT_WEIGHTS:
+                font_weight_attr = f' font-weight="{cond_fw}"'
+            elif col_config and col_config.font and col_config.font.weight:
+                resolved_weight = resolve_table_style_value(
+                    font_weight_as_css(col_config.font.weight), row
+                )
+                if resolved_weight in VALID_FONT_WEIGHTS:
+                    font_weight_attr = f' font-weight="{resolved_weight}"'
+            # Summary/total rows: per-role font.weight from row.roles
+            # takes precedence, then flat summary_font_weight, then
+            # default medium (500). All values validated against
+            # VALID_FONT_WEIGHTS before interpolation into SVG.
+            if not font_weight_attr and row_is_summary:
+                _rw = None
+                _role_total_weight = (
+                    role_total.font.weight if role_total and role_total.font else None
+                )
+                _role_summary_weight = (
+                    role_summary.font.weight
+                    if role_summary and role_summary.font
+                    else None
+                )
+                if row_is_total and _role_total_weight:
+                    _candidate = font_weight_as_css(_role_total_weight)
+                    if _candidate in VALID_FONT_WEIGHTS:
+                        _rw = _candidate
+                if not _rw and _role_summary_weight:
+                    _candidate = font_weight_as_css(_role_summary_weight)
+                    if _candidate in VALID_FONT_WEIGHTS:
+                        _rw = _candidate
+                if not _rw:
+                    _rw = summary_font_weight or "500"
+                font_weight_attr = f' font-weight="{_rw}"'
+
+            font_style_attr = ""
+            if cond_style is not None:
+                font_style_attr = f' font-style="{cond_style}"'
+
+            font_decoration_attr = ""
+            if cond_decoration is not None:
+                font_decoration_attr = f' text-decoration="{cond_decoration}"'
+
+            use_tabular = _wants_tabular_font(value, col_config)
+            if use_tabular:
+                # Source Serif tables use the serif font for numeric cells
+                # (CSS tabular-nums handles digit alignment); all other fonts
+                # use the DFT Sans Tabular stack for tabular digit widths.
+                if effective_font_family and "Source Serif" in effective_font_family:
+                    cell_font_family = effective_font_family
+                else:
+                    cell_font_family = _SANS_NUMERIC_FONT_STACK
+            else:
+                cell_font_family = effective_font_family or ""
+            # tabular-nums + lining-nums ensures consistent column alignment.
+            # font-feature-settings is the OpenType belt-and-suspenders for
+            # renderers that don't support font-variant-numeric.
+            numeric_style = (
+                ' style="font-variant-numeric: tabular-nums lining-nums;'
+                " font-feature-settings: 'tnum' 1, 'lnum' 1;\""
+                if use_tabular
+                else ""
+            )
+
+            if cell_link:
+                escaped_href = html_module.escape(cell_link, quote=True)
+                svg_parts.append(f'<a href="{escaped_href}">')
+
+            # Three-lane rendering for numeric cells (not date-like strings
+            # which happen to parse as numbers, e.g. "2024")
+            if is_numeric and col in col_lane_positions and not is_date_like(value):
+                # Coerce string values from CSV adapter
+                try:
+                    num_value = float(value) if isinstance(value, str) else value
+                except (ValueError, TypeError):
+                    num_value = value
+
+                if isinstance(num_value, (int, float)) and not isinstance(
+                    num_value,
+                    bool,
+                ):
+                    prefix, number_str, suffix = format_kpi_parts(
+                        num_value,
+                        fmt,
+                        resolved_style.formats if resolved_style else None,
+                    )
+                else:
+                    prefix, number_str, suffix = (
+                        "",
+                        format_table_cell_value(
+                            value,
+                            fmt,
+                            resolved_style.formats if resolved_style else None,
+                        ),
+                        "",
+                    )
+
+                # Anchors: only the first row + summary rows show prefix/suffix
+                if symbol_mode == "anchors" and row_idx != 0 and not row_is_summary:
+                    prefix = ""
+                    suffix = ""
+
+                # Replace ASCII hyphen-minus with proper minus sign
+                if number_str.startswith("-"):
+                    number_str = "\u2212" + number_str[1:]
+                # When a glyph is active for this cell, it replaces the
+                # format prefix (currency etc.) so the prefix lane carries
+                # one colored indicator instead of two stacked symbols.
+                full_prefix = cell_glyph or prefix
+
+                # Use pre-computed fixed lane positions for this column
+                prefix_x, number_x, suffix_x, *_ = col_lane_positions[col]
+                escaped_number = html_module.escape(number_str)
+
+                svg_parts.append(
+                    f'<text y="{y}" font-size="{font_size}" '
+                    f'fill="{fill_color}" '
+                    f'font-family="{cell_font_family}"{numeric_style}{font_weight_attr}{font_style_attr}{font_decoration_attr}>',
+                )
+
+                # Prefix tspan: end-anchored at prefix_x (left of number).
+                # A glyph carries its own fill so it can stand out against
+                # the cell's default text color.
+                if full_prefix:
+                    escaped_prefix = html_module.escape(full_prefix)
+                    glyph_fill_attr = (
+                        f' fill="{sanitize_color(cell_glyph_color, fill_color)}"'
+                        if cell_glyph and cell_glyph_color
+                        else ""
+                    )
+                    svg_parts.append(
+                        f'<tspan x="{prefix_x}" text-anchor="end"{glyph_fill_attr}>'
+                        f"{escaped_prefix}</tspan>",
+                    )
+
+                # Number tspan: end-anchored so its center sits at cell
+                # midpoint (number_x = midpoint + max_number_w / 2).
+                svg_parts.append(
+                    f'<tspan x="{number_x}" text-anchor="end">{escaped_number}</tspan>',
+                )
+
+                # Suffix tspan: left-aligned at fixed position
+                if suffix:
+                    escaped_suffix = html_module.escape(suffix)
+                    svg_parts.append(
+                        f'<tspan x="{suffix_x}" text-anchor="start">'
+                        f"{escaped_suffix}</tspan>",
+                    )
+
+                svg_parts.append("</text>")
+            else:
+                display_value = format_table_cell_value(
+                    value, fmt, resolved_style.formats if resolved_style else None
+                )
+                content_area = cw - cell_pad * 2
+
+                align = col_config.align if col_config and col_config.align else None
+                if align == "center":
+                    x = cell_x + (cw / 2)
+                    anchor = "middle"
+                elif (
+                    align == "right" or is_date_like(value)
+                ) and col in col_lane_positions:
+                    # Route through the column's number_x so date cells
+                    # center under the (centered) header, matching the
+                    # numeric three-lane invariant. See _compute_lane_positions
+                    # docstring.
+                    _prefix_x, number_x, *_ = col_lane_positions[col]
+                    x = number_x
+                    anchor = "end"
+                elif align == "right" or is_date_like(value):
+                    x = cell_x + cw - cell_pad
+                    anchor = "end"
+                else:  # "left" or unset
+                    x = cell_x + cell_pad
+                    anchor = "start"
+
+                if wrap and not is_date_like(value) and not is_numeric:
+                    # _compute_wrap_layout ran upstream; missing-cache means
+                    # the cell was skipped (empty display or content_w <= 0).
+                    # Render those as a single line — no need to re-measure.
+                    # Numeric cells that fall through here (no lane position)
+                    # take the else-branch so they keep tabular-nums CSS and
+                    # a hard ellipsis rather than word-wrap.
+                    cached = (
+                        wrapped_lines_by_row[row_idx].get(col)
+                        if wrapped_lines_by_row is not None
+                        else None
+                    )
+                    lines = cached if cached is not None else [display_value]
+                else:
+                    display_value = truncate_text_precise(
+                        display_value,
+                        content_area,
+                        font_size,
+                        truncation_measurer,
+                        ellipsis=True,
+                    )
+                    lines = [display_value]
+
+                # Glyph for non-three-lane cells (text columns, dates, nulls).
+                # Inlined as a leading colored tspan; multi-line cells carry
+                # the glyph on the first line only.
+                glyph_prefix_inline = ""
+                if cell_glyph:
+                    escaped_glyph = html_module.escape(cell_glyph)
+                    glyph_fill_attr = (
+                        f' fill="{sanitize_color(cell_glyph_color, fill_color)}"'
+                        if cell_glyph_color
+                        else ""
+                    )
+                    glyph_prefix_inline = (
+                        f"<tspan{glyph_fill_attr}>{escaped_glyph} </tspan>"
+                    )
+
+                if len(lines) > 1:
+                    line_height = font_size + text_offset
+                    total_text_h = len(lines) * line_height
+                    first_y = row_y + (per_row_height - total_text_h) / 2 + font_size
+                    svg_parts.append(
+                        f'<text x="{x}" '
+                        f'font-size="{font_size}" fill="{fill_color}" '
+                        f'text-anchor="{anchor}" '
+                        f'font-family="{cell_font_family}"{font_weight_attr}{font_style_attr}{font_decoration_attr}>'
+                    )
+                    for li, line in enumerate(lines):
+                        ly = first_y + li * line_height
+                        prefix = glyph_prefix_inline if li == 0 else ""
+                        svg_parts.append(
+                            f'<tspan x="{x}" y="{ly}">{prefix}{html_module.escape(line)}</tspan>'
+                        )
+                    svg_parts.append("</text>")
+                else:
+                    svg_parts.append(
+                        f'<text x="{x}" y="{y}" '
+                        f'font-size="{font_size}" fill="{fill_color}" '
+                        f'text-anchor="{anchor}" '
+                        f'font-family="{cell_font_family}"{numeric_style}{font_weight_attr}{font_style_attr}{font_decoration_attr}>'
+                        f"{glyph_prefix_inline}{html_module.escape(lines[0])}</text>",
+                    )
+
+            if cell_link:
+                svg_parts.append("</a>")
+
+    # Flush deferred row rules last so they paint above all fill rects.
+    # SVG z-order is document order: later = higher.
+    svg_parts.extend(row_rule_parts)
+
+
+def _extract_page_from_variables(
+    chart_id: str,
+    variables: dict[str, Any] | None,
+) -> int:
+    """Extract the current page number from the variables dict.
+
+    The page variable is named ``{chart_id}_page`` and is 1-based.
+    Returns 1 if no page variable is present or the value is invalid.
+    """
+    if not variables:
+        return 1
+    raw = variables.get(f"{chart_id}_page")
+    if raw is None:
+        return 1
+    try:
+        return max(1, int(raw))
+    except (ValueError, TypeError):
+        return 1
+
+
+_PAGINATOR_PREV_CHEVRON = "\u2039"  # \u2039
+_PAGINATOR_NEXT_CHEVRON = "\u203a"  # \u203a
+_PAGINATOR_ELLIPSIS = "\u2026"  # \u2026
+# siblingCount=1 shows ±1 around the current page (e.g. `4 5 6` mid-window)
+# so the paginator carries some context, not just the single current digit.
+# The aux-slot squeeze keeps total width modest; the MUI small-gap
+# expansion fills in single hidden pages instead of ellipsizing them.
+_PAGINATOR_SIBLING_COUNT = 1
+_PAGINATOR_BOUNDARY_COUNT = 1
+
+# Chevrons and ellipses sit in narrower slots than digits so they read as
+# pairs with their adjacent page numbers rather than floating a full slot
+# away. 0.66 keeps the pairing tight without overlapping glyph bounds.
+_PAGINATOR_AUX_SLOT_RATIO = 0.66
+
+
+def _paginator_window(
+    page: int,
+    total: int,
+    sibling: int = _PAGINATOR_SIBLING_COUNT,
+    boundary: int = _PAGINATOR_BOUNDARY_COUNT,
+) -> list[int | str]:
+    """Build the windowed page sequence: numeric pages with ``"\u2026"`` for gaps.
+
+    Always-show set:
+      * ``[1 .. boundary]`` and ``[total-boundary+1 .. total]`` (the
+        boundary pages)
+      * ``[page-sibling .. page+sibling]`` (siblings around current)
+
+    Gaps between consecutive must-show pages become a single ``"\u2026"``
+    sentinel, regardless of gap size. We deliberately do NOT expand
+    single-page gaps into the hidden page \u2014 that produces "5-in-a-row"
+    runs near the edges (e.g. page 1 of 8 \u2192 ``1 2 3 4 5 \u2026 8``) which
+    overweight the start/end states. Siblings carry the local context;
+    ellipsis carries the "more here" signal.
+    """
+    if total <= 0:
+        return []
+    if total == 1:
+        return [1]
+
+    must_show: set[int] = set()
+    must_show.update(range(1, min(boundary, total) + 1))
+    must_show.update(range(max(total - boundary + 1, 1), total + 1))
+    must_show.update(range(max(page - sibling, 1), min(page + sibling, total) + 1))
+
+    sorted_pages = sorted(must_show)
+    items: list[int | str] = []
+    prev = 0
+    for p in sorted_pages:
+        if p > prev + 1:
+            items.append(_PAGINATOR_ELLIPSIS)
+        items.append(p)
+        prev = p
+    return items
+
+
+def _render_pagination_controls(
+    page: int,
+    total_pages: int,
+    page_var_name: str,
+    table_width: float,
+    y: float,
+    font_family: str,
+    paginator: PaginatorStyle,
+) -> str:
+    """Render a right-aligned paginator: ``\u2039 1 \u2026 4 5 6 \u2026 12 \u203a``.
+
+    Layout: each item occupies a fixed ``item_width`` slot; the rightmost
+    slot's right edge sits at ``table_width``. Clickable items (live
+    chevrons and inactive page numbers) get an invisible ``<rect>`` with an
+    ``onclick=updateVariable(...)`` handler \u2014 this is the hit target.
+    Disabled chevrons, the active page, and the ellipsis are non-interactive.
+    Disabled state is signalled by colour (``color_disabled``), not opacity.
+    """
+    window = _paginator_window(page=page, total=total_pages)
+
+    # Build the full visual sequence: leading chevron, page items, trailing
+    # chevron. Each entry is (role, glyph, target_page).
+    sequence: list[tuple[str, str, int]] = []
+    prev_target = page - 1 if page > 1 else 0
+    next_target = page + 1 if page < total_pages else 0
+    sequence.append(("prev", _PAGINATOR_PREV_CHEVRON, prev_target))
+    for item in window:
+        if isinstance(item, str):
+            sequence.append(("ellipsis", item, 0))
+        else:
+            sequence.append(("page", str(item), int(item)))
+    sequence.append(("next", _PAGINATOR_NEXT_CHEVRON, next_target))
+
+    font_size = int(paginator.font.size) if paginator.font.size is not None else 11
+    item_width = paginator.item_width
+    text_y = y + 18  # baseline within the reserved control band
+    # Hit rect hugs the glyph tightly so cursor:pointer matches the visible
+    # character. We don't want adjacent rects to butt up against each other —
+    # that makes the gap between items feel clickable when it isn't.
+    rect_w = float(font_size) + 6.0
+    rect_h = max(font_size * 1.8, 18.0)
+    rect_y = y + 4
+
+    safe_var = html_module.escape(page_var_name, quote=True)
+    safe_font = html_module.escape(font_family or "", quote=True)
+    safe_active = html_module.escape(paginator.color_active, quote=True)
+    safe_inactive = html_module.escape(paginator.color_inactive, quote=True)
+    safe_disabled = html_module.escape(paginator.color_disabled, quote=True)
+
+    # Right-anchored layout: walk slot widths so chevrons and ellipses
+    # get narrower slots than digits, sitting closer to their boundary
+    # neighbours. Total width is the sum of slot widths; the rightmost
+    # slot's right edge sits at ``table_width``.
+    aux_slot_w = item_width * _PAGINATOR_AUX_SLOT_RATIO
+    slot_widths = [
+        aux_slot_w if role in ("prev", "next", "ellipsis") else item_width
+        for role, _, _ in sequence
+    ]
+    total_width = sum(slot_widths)
+    cursor_left = table_width - total_width
+
+    parts: list[str] = [f'<g class="dft-paginator" data-paginator="{safe_var}">']
+    for i, (role, glyph, target) in enumerate(sequence):
+        slot_w = slot_widths[i]
+        slot_left = cursor_left
+        center_x = slot_left + slot_w / 2
+        cursor_left += slot_w
+
+        is_active_page = role == "page" and target == page
+        is_disabled_chevron = role in ("prev", "next") and target == 0
+        is_ellipsis = role == "ellipsis"
+
+        if is_active_page:
+            color = safe_active
+            weight = paginator.weight_active
+            clickable = False
+        elif is_disabled_chevron:
+            color = safe_disabled
+            weight = (
+                paginator.weight_chevron
+            )  # silhouette stays heavy; tone signals disabled
+            clickable = False
+        elif role in ("prev", "next"):
+            color = safe_active
+            weight = paginator.weight_chevron
+            clickable = True
+        elif is_ellipsis:
+            color = safe_inactive
+            weight = paginator.weight_inactive
+            clickable = False
+        else:  # inactive page number
+            color = safe_inactive
+            weight = paginator.weight_inactive
+            clickable = True
+
+        if clickable:
+            # Rect is centred on the glyph and narrower than the slot so
+            # cursor:pointer doesn't extend into the gap between items.
+            rect_x = center_x - rect_w / 2
+            parts.append(
+                f'<rect x="{rect_x:.1f}" y="{rect_y:.1f}" '
+                f'width="{rect_w:.1f}" height="{rect_h:.1f}" '
+                f'fill="transparent" pointer-events="all" '
+                f'style="cursor: pointer;" '
+                f"onclick=\"updateVariable('{safe_var}', '{target}')\"/>"
+            )
+
+        text_style = "font-variant-numeric: tabular-nums; user-select: none;"
+        data_attrs = f' data-paginator-role="{role}"'
+        if is_active_page:
+            data_attrs += f' data-pagination-current="{safe_var}"'
+        # pointer-events="none" so the underlying <rect> catches hover/click
+        # over the painted glyph — without this, SVG's default visiblePainted
+        # behaviour makes the text capture events but no cursor:pointer or
+        # onclick lives there, so the hit feels broken.
+        parts.append(
+            f'<text x="{center_x:.1f}" y="{text_y:.1f}" '
+            f'font-size="{font_size}" fill="{color}" text-anchor="middle" '
+            f'font-family="{safe_font}" font-weight="{weight}" '
+            f'pointer-events="none" '
+            f'style="{text_style}"{data_attrs}>{glyph}</text>'
+        )
+
+    parts.append("</g>")
+    return "\n".join(parts)
+
+
+def render_table_svg(
+    chart: Any,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    height: float | None = None,
+    is_placeholder: bool = False,
+    resolved_style: MergedChartsStyle | None = None,
+    variables: dict[str, Any] | None = None,
+    face_level: int = 1,
+    *,
+    board_style: MergedStyle,
+) -> str:
+    """Render a data table as SVG.
+
+    Creates a clean, modern table visualization with:
+    - Header row with column names
+    - Alternating row backgrounds
+    - Auto-calculated column widths
+    - Proper text truncation
+    - Spark charts (sparklines) in columns with spark config
+    - Interactive pagination controls when data exceeds page_size
+
+    Args:
+        chart: Chart definition with title and optional columns config
+        data: List of dicts containing table data
+        width: Optional explicit width in pixels
+        height: Optional explicit height in pixels
+        is_placeholder: If True, render with placeholder styling (reduced opacity,
+                        "add data" overlay). Used when table has no query/data.
+        variables: Current variable values (used to read pagination page state).
+        face_level: Heading level of the parent face (root=1, nested=2, …).
+            Chart title uses face_level + 1.
+
+    Returns:
+        SVG string representing the table
+
+    """
+    data = normalize_data_types(data)
+
+    # Apply cross-tab pivot transformation when the chart's query has pivot: set.
+    # ResolvedChart.query delegates to source_chart.query via property; Chart
+    # has .query directly. Both paths return None for blank/placeholder charts.
+    # The Pivot model guarantees column/value are non-empty strings, so the isinstance
+    # check distinguishes a real Pivot from an unset query attribute.
+    chart_pivot = getattr(getattr(chart, "query", None), "pivot", None)
+    if chart_pivot is not None and isinstance(chart_pivot.column, str) and data:
+        data = pivot_long_to_wide(
+            data, column=chart_pivot.column, value=chart_pivot.value
+        )
+
+    # --- Resolve chart-level style (presentation fields) ------------------
+    # Body operates on MergedChartsStyle (chart-level merged). When the
+    # caller didn't pass one, build it now from the chart's authored style
+    # so chart-local pagination/wrap/columns flow without each caller having
+    # to plumb a MergedChartsStyle through.
+    from dataface.core.compile.style_cascade import build_resolved_style
+
+    _ms = board_style
+
+    if resolved_style is None:
+        resolved_style = build_resolved_style(
+            _ms,
+            getattr(chart, "style", None),
+        )
+    tc: TableChartStyle = resolved_style.table
+
+    # markdown colors — narrow engine-config getter
+    _markdown = get_markdown_config()
+
+    # Build colors dict from board-level MergedStyle, then apply chart-level
+    # TableChartStyle overrides. Keeps all downstream helper-function call sites
+    # unchanged (they accept colors: dict[str, str]).
+    colors: dict[str, str] = {
+        "background": _ms.background,
+        "header_background": _ms.charts.table.header.background or "",
+        "label_color": _ms.variables.label.font.color or "",
+        "border": _ms.border.color,
+        "row_stripe": (
+            _ms.charts.table.row.stripe.color if _ms.charts.table.row.stripe else None
+        )
+        or "",
+        "color": _ms.font.color,
+        "title_color": _ms.title.font.color or "",
+        "muted": _ms.variables.font.color or "",
+    }
+    colors["background"] = sanitize_color(tc.background, colors["background"])
+    colors["header_background"] = sanitize_color(
+        tc.header.background,
+        colors["header_background"],
+    )
+    colors["label_color"] = sanitize_color(
+        tc.header.font.color,
+        colors["label_color"],
+    )
+    colors["border"] = sanitize_color(tc.border.color, colors["border"])
+    colors["row_stripe"] = sanitize_color(
+        tc.row.stripe.color if tc.row.stripe else None, colors["row_stripe"]
+    )
+    colors["color"] = sanitize_color(tc.color, colors["color"])  # type: ignore[arg-type]  # StyleColorConfig resolved to str by cascade before render
+
+    # tc IS both the style and the layout constants (TableChartStyle has all fields)
+    table_config = tc
+
+    row_height = int(tc.row.height)
+    padding = int(tc.outer_padding)
+    assert (
+        tc.font.size is not None
+    ), "TableChartStyle.font.size must be set after cascade"
+    font_size = int(tc.font.size)
+    # Header font size: when not explicitly set, MATCH the body font and
+    # track it through the fit cascade.  BI's apparatus tier (11px) is
+    # an explicit override that does NOT track body — header stays at 11
+    # even when body shrinks to 8.  Minimal and Classic leave it unset
+    # so headers travel with body 14 → 11 → 8.
+    _header_inherits_body = tc.header.font.size is None
+    header_font_size = (
+        int(tc.header.font.size) if tc.header.font.size is not None else font_size
+    )
+    # Header weight: compact tier (body ≤11px) may use font_compact.weight to
+    # apply a lighter weight when body text shrinks — e.g. BI theme uses 500 at
+    # 11px vs. 600 at the default 14px body size.
+    _default_header_weight = (
+        str(tc.header.font.weight) if tc.header.font.weight else "600"
+    )
+    if (
+        font_size <= 11
+        and tc.header.font_compact is not None
+        and tc.header.font_compact.weight is not None
+    ):
+        header_font_weight = str(tc.header.font_compact.weight)
+    else:
+        header_font_weight = _default_header_weight
+    symbol_mode = tc.symbol_mode or "all"
+    wrap_cells = tc.wrap
+    # Row role: TableRowStyle.role is never None after cascade (has default)
+    row_role_spec = tc.row.role
+    header_rule_width = float(tc.header.rule.width)
+    # Header height: when not explicitly set, scale with header font size
+    # plus padding for breathing room and the rule (if any).  Roughly
+    # 2 × font_size gives a comfortable text band; add the rule height.
+    # When the header is disabled, collapse to 0 so the layout assigns
+    # all vertical room to data rows.
+    if not tc.header.visible:
+        header_height = 0
+    elif tc.header.height is not None:
+        header_height = int(tc.header.height)
+    else:
+        header_height = int(header_font_size * 2 + header_rule_width + 4)
+    row_rule_width = float(tc.row.rule.width)
+    # Summary rule: falls back to row_rule_width when not explicitly set.
+    summary_rule_width = float(
+        tc.row.roles.summary.rule_width or row_rule_width,
+    )
+    _summary_role_font = tc.row.roles.summary.font
+    summary_font_weight = (
+        font_weight_as_css(_summary_role_font.weight)
+        if _summary_role_font is not None and _summary_role_font.weight is not None
+        else None
+    )
+    # Per-role presentation from row.roles (summary / total).
+    _role_summary = tc.row.roles.summary
+    _role_total = tc.row.roles.total
+    # Table font family can be overridden at the table level (e.g. Classic
+    # variant uses Source Serif), falling back to the global body font.
+    # Strip CSS-style quotes from font names for SVG compatibility — SVG
+    # font-family attributes treat single quotes as literal characters, not
+    # CSS string delimiters.  'Source Serif 4' → Source Serif 4.
+    # Also prepend "Source Serif 4 Web" alias so the browser prefers our
+    # bundled woff2 over a locally installed system font.
+    # tc.font.family is always filled by _apply_cascade in production paths
+    table_font_family = tc.font.family
+    assert table_font_family is not None, "style.font.family must be configured"
+    # Remove CSS quoting: 'Font Name' → Font Name (SVG presentation attrs
+    # use space-separated identifiers for multi-word family names, not quotes)
+    table_font_family = table_font_family.replace("'", "").replace('"', "")
+    if (
+        "Source Serif 4" in table_font_family
+        and "Source Serif 4 Web" not in table_font_family
+    ):
+        table_font_family = table_font_family.replace(
+            "Source Serif 4",
+            "Source Serif 4 Web, Source Serif 4",
+        )
+    header_rule_continuous = bool(tc.header.rule.continuous or False)
+    # Rules default to the body text color for strong visibility.
+    # Row-level rule color takes precedence over table-level rule color.
+    # Sanitize all user-provided colors; fall back to theme text color.
+    _raw_rule_color = tc.row.rule.color or (tc.rule.color if tc.rule else None)
+    rule_color = sanitize_color(_raw_rule_color, colors["color"])
+    bottom_padding = int(tc.bottom_padding)
+    title_text = chart.title
+    subtitle_text = chart.subtitle
+
+    # Use width/height if provided; TableChartStyle has no default_width.
+    table_width: float = width or TABLE_DEFAULT_WIDTH
+    title_font_size, title_font_weight, title_font_family_str = chart_title_spec(
+        table_width, level=face_level + 1, resolved_chart_style=resolved_style
+    )
+    title_style = resolved_style.title
+    title_line_height = title_font_size + 2
+    title_block = compute_table_title_block_layout(
+        chart_title=str(title_text or ""),
+        chart_subtitle=str(subtitle_text or ""),
+        table_width=table_width,
+        tc=tc,
+        padding=padding,
+        title_style=title_style,
+        resolved_chart_style=resolved_style,
+        face_level=face_level,
+    )
+    title_height = title_block.height
+    rendered_title = title_block.rendered_title
+    title_lines = list(title_block.title_lines)
+    subtitle_font_size = title_block.subtitle_font_size
+
+    # Authored chart-local style entry boundary. ``chart`` is Any here
+    # (ResolvedChart, Chart, or MockChart in tests). For ResolvedChart
+    # the chart-local Patch is consumed by the cascade and not stored on the
+    # ResolvedChart itself — column configs live on resolved.columns and the
+    # rest is in resolved_style. For Chart/MockChart we still
+    # read the authored Patch directly so column configs and table.wrap flow.
+    # ``wrap_cells`` already has the merged value: tc = resolved_style.table,
+    # and build_resolved_style merges any chart-local style.table onto
+    # base.table — so tc.wrap reflects both layers without further
+    # discrimination.
+    # Get the table family sub-patch for column configs and header overflow.
+    # ResolvedChart: column configs and defaults are promoted to resolved fields;
+    # the ChartStylePatch is consumed by the cascade and not stored on ResolvedChart.
+    # Chart/MockChart: read the authored table sub-patch directly.
+    raw_style = getattr(chart, "style", None)
+    if isinstance(raw_style, TableChartStylePatch):
+        table_patch: TableChartStylePatch = raw_style
+    elif raw_style is not None and hasattr(raw_style, "table"):
+        table_patch = raw_style.table or TableChartStylePatch()  # type: ignore[call-arg]
+    elif isinstance(raw_style, dict):
+        # Plain dict style — coerce to TableChartStylePatch (handles both
+        # flat {"columns": {...}} and nested {"table": {"columns": {...}}} shapes).
+        _style_dict = (
+            raw_style.get("table", raw_style) if "table" in raw_style else raw_style
+        )
+        table_patch = TableChartStylePatch.model_validate(_style_dict)
+    else:
+        table_patch = TableChartStylePatch()  # type: ignore[call-arg]
+    # Column configs: prefer ResolvedChart.columns and ResolvedChart.column_defaults
+    # (set by the table-channel lowering in pipeline.resolve_chart), fall back
+    # to authored style for direct Chart/MockChart calls.
+    resolved_columns = getattr(chart, "columns", None)
+    resolved_column_defaults = getattr(chart, "column_defaults", None)
+    patch_updates: dict[str, object] = {}
+    if resolved_columns:
+        patch_updates["columns"] = dict(resolved_columns)
+    if isinstance(resolved_column_defaults, TableColumnDefaultsConfig):
+        patch_updates["column_defaults"] = resolved_column_defaults
+    if patch_updates:
+        table_patch = table_patch.model_copy(update=patch_updates)
+    # Pass query column names so column_defaults can apply to all inferred columns
+    # when no explicit style.columns is provided (the "no columns" authoring shape).
+    query_columns = list(data[0].keys()) if data else None
+    column_configs = parse_table_column_configs(
+        table_patch, query_columns=query_columns
+    )
+
+    # Chart-level conditional_formatting block, indexed by column. Tables read
+    # rules directly at render time — no internal lowering into column configs.
+    # ResolvedChart stashes the block on ``source_chart``; Chart /
+    # MockChart expose it directly.
+    cf_block = getattr(chart, "conditional_formatting", None)
+    if cf_block is None:
+        source = getattr(chart, "source_chart", None)
+        if source is not None:
+            cf_block = getattr(source, "conditional_formatting", None)
+    column_when_rules: dict[str, tuple[Any, ...]] = {
+        col: tuple(entry.when) for col, entry in (cf_block or {}).items()
+    }
+
+    # ResolvedChart.header_overflow is the promoted authored value (see
+    # resolve_chart); for Chart/MockChart inputs we fall
+    # back to the authored Patch.
+    promoted_header_overflow = getattr(chart, "header_overflow", None)
+    header_overflow = resolve_header_overflow(
+        table_patch,
+        inherited_title_style=resolved_style.title,
+        table_config=table_config,
+        promoted=promoted_header_overflow,
+    )
+
+    # Prefer explicit configured columns so helper/style columns can stay hidden.
+    # Dict keys preserve insertion order, so authored column order is honored.
+    if table_patch.columns:
+        columns = list(table_patch.columns.keys())
+    else:
+        columns = list(data[0].keys()) if data else []
+
+    available_width = table_width - (padding * 2)
+    cell_pad = int(table_config.column_layout.cell_padding)
+
+    # Fit cascade: if content overflows, progressively reduce padding then
+    # font sizes.  11px is the floor — below that, truncation handles what
+    # can't fit.  8px is unreadable and visually worse than ellipsis.
+    _COMPACT_PAD = max(cell_pad // 2, 6)  # reduced padding floor
+    _COMPACT_FONT = 11  # stepped-down body size (also the floor)
+    _COMPACT_HEADER_FONT = 11  # header floor matches body
+
+    _cell_font = FontStyle(size=float(font_size), family=table_font_family)
+    _header_font = FontStyle(
+        size=float(header_font_size),
+        family=table_font_family,
+        weight=header_font_weight,
+        case=tc.header.font.case,
+    )
+
+    # Row-number column: compute its width NOW, before calculate_column_layout,
+    # so the data-column layout pass gets a budget already reduced by the
+    # synthetic column. This prevents the SVG widening when row_numbers is
+    # toggled on for a table whose real columns already fill available_width.
+    # Width is stable across pages (uses total row count, not per-page count).
+    row_numbers = tc.row_numbers
+    row_number_width = 0.0
+    if row_numbers.visible:
+        row_number_width = _row_number_column_width(
+            row_numbers=row_numbers,
+            total_row_count=len(data),
+            table_config=table_config,
+            font=_cell_font,
+            measurer=get_font_measurer(table_font_family),
+        )
+    data_column_budget = available_width - row_number_width
+
+    col_demands = measure_column_demands(
+        columns,
+        column_configs,
+        data,
+        get_font_measurer(table_font_family),
+        font_size=float(font_size),
+        header_font_size=float(header_font_size),
+        header_case=_header_font.case or "none",
+        cell_pad=cell_pad,
+        formats=resolved_style.formats,
+        header_visible=tc.header.visible,
+    )
+    col_word_floors = measure_column_word_floors(
+        columns,
+        column_configs,
+        data,
+        get_font_measurer(table_font_family),
+        font_size=float(font_size),
+        header_case=_header_font.case or "none",
+        cell_pad=cell_pad,
+        header_visible=tc.header.visible,
+    )
+    col_widths, col_x_offsets, actual_content_width = calculate_column_layout(
+        columns,
+        column_configs,
+        data_column_budget,
+        demands=col_demands,
+        width_similarity_threshold=table_config.column_layout.width_similarity_threshold,
+        word_floors=col_word_floors,
+    )
+
+    _formats = resolved_style.formats
+    if _has_overflow(
+        columns,
+        data,
+        column_configs,
+        col_widths,
+        cell_pad,
+        _cell_font,
+        header_font=_header_font,
+        wrap=wrap_cells,
+        formats=_formats,
+        header_visible=tc.header.visible,
+    ):
+        # Step 1: reduce cell padding (table-wide)
+        cell_pad = _COMPACT_PAD
+        if _has_overflow(
+            columns,
+            data,
+            column_configs,
+            col_widths,
+            cell_pad,
+            _cell_font,
+            header_font=_header_font,
+            wrap=wrap_cells,
+            formats=_formats,
+            header_visible=tc.header.visible,
+        ):
+            # Step 2: step down font size to 11px (table-wide, cascade stops here)
+            font_size = _COMPACT_FONT
+            row_height = max(row_height - 4, 16)
+            if _header_inherits_body:
+                header_font_size = font_size  # Minimal/Classic: track body
+            else:
+                header_font_size = _COMPACT_HEADER_FONT
+            # Rebuild FontStyle after cascade changes font sizes.
+            _cell_font = FontStyle(size=float(font_size), family=table_font_family)
+            _header_font = FontStyle(
+                size=float(header_font_size),
+                family=table_font_family,
+                weight=header_font_weight,
+                case=tc.header.font.case,
+            )
+            # Remaining overflow is handled by per-cell truncation (ellipsis).
+
+    # After the cascade, body font size may have shrunk. When row numbers are
+    # shown, row_number_width is font-dependent and must be recomputed so the
+    # data-column budget reflects the final synthetic column width.
+    _initial_font_size = float(int(tc.font.size))  # asserted non-None above
+    if font_size < _initial_font_size and row_numbers.visible:
+        row_number_width = _row_number_column_width(
+            row_numbers=row_numbers,
+            total_row_count=len(data),
+            table_config=table_config,
+            font=_cell_font,
+            measurer=get_font_measurer(table_font_family),
+        )
+        data_column_budget = available_width - row_number_width
+        col_demands = measure_column_demands(
+            columns,
+            column_configs,
+            data,
+            get_font_measurer(table_font_family),
+            font_size=float(font_size),
+            header_font_size=float(header_font_size),
+            header_case=_header_font.case or "none",
+            cell_pad=cell_pad,
+            formats=resolved_style.formats,
+            header_visible=tc.header.visible,
+        )
+        col_word_floors = measure_column_word_floors(
+            columns,
+            column_configs,
+            data,
+            get_font_measurer(table_font_family),
+            font_size=float(font_size),
+            header_case=_header_font.case or "none",
+            cell_pad=cell_pad,
+            header_visible=tc.header.visible,
+        )
+        col_widths, col_x_offsets, actual_content_width = calculate_column_layout(
+            columns,
+            column_configs,
+            data_column_budget,
+            demands=col_demands,
+            width_similarity_threshold=table_config.column_layout.width_similarity_threshold,
+            word_floors=col_word_floors,
+        )
+
+    # Now stitch the synthetic column into the layout: prepend at x=0 and
+    # shift all data-column x_offsets right by row_number_width.
+    if row_numbers.visible:
+        columns = [_ROW_NUMBER_COL, *columns]
+        col_widths = {_ROW_NUMBER_COL: row_number_width, **col_widths}
+        col_x_offsets = [0.0, *[off + row_number_width for off in col_x_offsets]]
+        actual_content_width += row_number_width
+
+    # When explicit column widths sum past available_width, the table widens.
+    if actual_content_width > available_width:
+        table_width = actual_content_width + padding * 2
+
+    # Extract the data-only column/offset views once; reused by lane_positions
+    # and resolve_wrapped_headers (both must skip the synthetic column).
+    real_columns = [c for c in columns if c != _ROW_NUMBER_COL]
+    real_col_x_offsets = [
+        col_x_offsets[i] for i, c in enumerate(columns) if c != _ROW_NUMBER_COL
+    ]
+
+    # Compute lane positions FIRST (before wrap decisions) so the wrap
+    # logic knows where the value lane sits in each column.  Use full
+    # `data` here (not visible_data which depends on header_height that
+    # we haven't determined yet — chicken-and-egg).  Lane positions are
+    # max widths across rows; using all data is a slight over-estimate
+    # but avoids the dependency cycle.
+    lane_positions = _compute_lane_positions(
+        rows=data,
+        columns=real_columns,
+        column_configs=column_configs,
+        col_widths=col_widths,
+        col_x_offsets=real_col_x_offsets,
+        padding_x=padding,
+        cell_pad=cell_pad,
+        cell_font=_cell_font,
+        column_when_rules=column_when_rules,
+        formats=resolved_style.formats,
+    )
+
+    # When the header row is hidden, skip header wrapping/sizing entirely —
+    # the resolver would otherwise re-compute a non-zero header_height even
+    # though no header text will render. Keep header_height at 0 so layout
+    # gives every pixel to data rows.
+    wrapped_headers: dict[str, list[str]]
+    if not tc.header.visible:
+        wrapped_headers = {}
+    else:
+        wrapped_headers, header_height_resolved = resolve_wrapped_headers(
+            real_columns,
+            column_configs,
+            col_widths,
+            header_overflow=header_overflow,
+            header_height=header_height,
+            header_font=_header_font,
+            padding=padding,
+            table_config=table_config,
+            cell_pad=cell_pad,
+            measurer=get_font_measurer(table_font_family),
+        )
+        header_height = int(header_height_resolved)
+
+    # Pagination: extract current page from variables using chart ID
+    chart_id = getattr(chart, "id", "") or ""
+    current_page = _extract_page_from_variables(chart_id, variables) if chart_id else 1
+
+    # Pre-compute per-row heights AND cache wrapped lines for the full
+    # dataset. Heights flow into pagination/height-constrained slicing;
+    # cached lines skip the re-wrap work in _render_data_rows.
+    all_row_heights: list[int] | None = None
+    all_wrapped_lines: list[dict[str, list[str]]] | None = None
+    if wrap_cells and data:
+        all_row_heights, all_wrapped_lines = _compute_wrap_layout(
+            data,
+            real_columns,
+            column_configs,
+            col_widths,
+            cell_pad,
+            font_size,
+            row_height,
+            table_config.text_baseline_offset,
+            get_font_measurer(table_font_family),
+            formats=_formats,
+        )
+
+    (
+        table_height,
+        visible_data,
+        total_pages,
+        page_offset,
+        per_row_heights,
+        rows_height,
+        row_height,
+    ) = _resolve_visible_rows(
+        data,
+        height=height,
+        title_height=title_height,
+        header_height=header_height,
+        padding=padding,
+        row_height=row_height,
+        bottom_padding=bottom_padding,
+        pagination=resolved_style.pagination,
+        page=current_page,
+        row_heights=all_row_heights,
+        header_visible=tc.header.visible,
+    )
+    # Slice cached wrapped-lines to align with visible_data.
+    visible_wrapped_lines: list[dict[str, list[str]]] | None = None
+    if all_wrapped_lines is not None:
+        visible_wrapped_lines = all_wrapped_lines[
+            page_offset : page_offset + len(visible_data)
+        ]
+
+    # Add breathing room before summary/total rows so double rules don't
+    # crowd the last data row. Compute here to adjust total SVG height.
+    _SUMMARY_GAP = int(row_height * 0.4)
+    summary_gap_total = 0
+    if row_role_spec and visible_data:
+        for i, row in enumerate(visible_data):
+            if i == 0:
+                continue
+            role = resolve_row_role(row_role_spec, row)
+            prev_role = resolve_row_role(row_role_spec, visible_data[i - 1])
+            if is_summary_role(role) and not is_summary_role(prev_role):
+                summary_gap_total += _SUMMARY_GAP
+    if summary_gap_total and not (height and height > 0):
+        table_height += summary_gap_total
+
+    # Reserve space for pagination controls when needed.
+    # When height is explicit (from sizing), it already includes the control
+    # height — only add it for auto-sized tables.
+    pagination_active = total_pages > 1
+    pagination_control_height = _PAGINATION_CONTROL_HEIGHT if pagination_active else 0
+    if pagination_active and not (height and height > 0):
+        table_height += pagination_control_height
+
+    # Start building SVG
+    svg_parts: list[str] = []
+
+    # Background
+    svg_parts.append(
+        f'<rect x="0" y="0" width="{table_width}" height="{table_height}" '
+        f'fill="{colors["background"]}" rx="4"/>',
+    )
+
+    current_y = padding
+
+    # Title
+    if title_text:
+        title_baseline = current_y + table_config.title_baseline_offset
+        # Emit inner <title> when the rendered text differs from the original —
+        # catches all overflow modes (clip, truncate, wrap-two). The old "…" sniff
+        # missed clip mode which shortens without an ellipsis.
+        is_title_truncated = rendered_title != str(title_text)
+        inner_title = (
+            f"<title>{html_module.escape(str(title_text))}</title>"
+            if is_title_truncated
+            else ""
+        )
+        svg_parts.append(
+            f'<text x="{padding}" y="{title_baseline}" '
+            f'font-size="{title_font_size}" font-weight="{title_font_weight}" fill="{colors["title_color"]}" '
+            f'font-family="{title_font_family_str}">{inner_title}',
+        )
+        for line_index, line in enumerate(title_lines):
+            line_y = title_baseline + (line_index * title_line_height)
+            svg_parts.append(
+                f'<tspan x="{padding}" y="{line_y}">{html_module.escape(line)}</tspan>',
+            )
+        svg_parts.append("</text>")
+        if subtitle_text:
+            last_title_baseline = title_baseline + (
+                (len(title_lines) - 1) * title_line_height
+            )
+            subtitle_y = _subtitle_baseline_below_title(
+                title_bottom=last_title_baseline + (title_font_size * 0.5),
+                title_subtitle_gap=table_config.title_subtitle_gap,
+                subtitle_font_size=subtitle_font_size,
+            )
+            escaped_subtitle = html_module.escape(subtitle_text)
+            svg_parts.append(
+                f'<text x="{padding}" y="{subtitle_y}" '
+                f'font-size="{subtitle_font_size}" fill="{colors["muted"]}" '
+                f'font-family="{table_font_family}">'
+                f"{escaped_subtitle}</text>",
+            )
+        current_y += title_height
+
+    # lane_positions already computed above (before resolve_wrapped_headers)
+
+    # Skip header rendering when style.header.visible is False. Header
+    # contributes 0 to layout (header_height has been zeroed above) so
+    # data rows start immediately after the title (or at the table top
+    # when no title). The header-body gap is also skipped.
+    if tc.header.visible:
+        _render_header_section(
+            svg_parts,
+            markdown_config=_markdown,
+            columns=columns,
+            column_configs=column_configs,
+            colors=colors,
+            table_config=table_config,
+            table_width=table_width,
+            header_height=header_height,
+            current_y=current_y,
+            padding_x=padding,
+            col_x_offsets=col_x_offsets,
+            col_widths=col_widths,
+            col_lane_positions=lane_positions,
+            header_font=_header_font,
+            wrapped_headers=wrapped_headers,
+            cell_pad=cell_pad,
+            header_rule_width=header_rule_width,
+            rule_color=rule_color,
+            header_rule_continuous=header_rule_continuous,
+            row_numbers=row_numbers if row_numbers.visible else None,
+        )
+
+    current_y += header_height
+    # Small whitespace gap between header and first data row for visual
+    # hierarchy. Scales with row height. Skipped when header is disabled —
+    # data rows start at the table top (after the title, if any).
+    header_body_gap = int(row_height * 0.25) if tc.header.visible else 0
+    current_y += header_body_gap
+
+    _render_data_rows(
+        svg_parts,
+        markdown_config=_markdown,
+        table_config=table_config,
+        rows=visible_data,
+        columns=columns,
+        column_configs=column_configs,
+        column_when_rules=column_when_rules,
+        colors=colors,
+        col_widths=col_widths,
+        col_x_offsets=col_x_offsets,
+        col_lane_positions=lane_positions,
+        padding_x=padding,
+        current_y=current_y,
+        row_height=row_height,
+        cell_font=_cell_font,
+        table_width=table_width,
+        cell_pad=cell_pad,
+        symbol_mode=symbol_mode,
+        row_rule_width=row_rule_width,
+        summary_rule_width=summary_rule_width,
+        rule_color=rule_color,
+        row_role_spec=row_role_spec,
+        summary_font_weight=summary_font_weight,
+        role_summary=_role_summary,
+        role_total=_role_total,
+        resolved_style=resolved_style,
+        row_numbers=row_numbers if row_numbers.visible else None,
+        page_offset=page_offset,
+        row_heights=per_row_heights,
+        wrapped_lines_by_row=visible_wrapped_lines,
+        wrap=wrap_cells,
+        chart_root_link=chart.link,
+        chart_id=chart_id,
+    )
+
+    # Show pagination controls or "more rows" indicator if data was truncated.
+    # rows_height comes from _resolve_visible_rows so indicator_y can't desync
+    # from table_height (both use the tallest-page sum when paginated).
+    if len(data) > len(visible_data):
+        indicator_y = current_y + rows_height + bottom_padding
+
+        if pagination_active and chart_id:
+            # Interactive pagination controls
+            page_var_name = f"{chart_id}_page"
+            controls_svg = _render_pagination_controls(
+                page=current_page,
+                total_pages=total_pages,
+                page_var_name=page_var_name,
+                table_width=table_width,
+                y=indicator_y,
+                font_family=table_font_family,
+                paginator=table_config.paginator,
+            )
+            svg_parts.append(controls_svg)
+        else:
+            more_count = len(data) - len(visible_data)
+            svg_parts.append(
+                f'<text x="{table_width / 2}" y="{indicator_y}" '
+                f'font-size="{table_config.more_rows.font.size}" fill="{colors["muted"]}" text-anchor="middle" font-style="italic" '
+                f'font-family="{table_font_family}">'
+                f"+ {more_count} more rows</text>",
+            )
+
+    # Empty state (only show if not placeholder - placeholder has data)
+    if not data and not is_placeholder:
+        svg_parts.append(
+            f'<text x="{table_width / 2}" y="{table_height / 2}" '
+            f'font-size="{table_config.empty_state.font.size}" fill="{colors["muted"]}" text-anchor="middle" '
+            f'font-family="{table_font_family}">'
+            f"No data</text>",
+        )
+
+    # Wrap in SVG
+    svg_result = f"""<svg xmlns="http://www.w3.org/2000/svg" width="{table_width}" height="{table_height}" viewBox="0 0 {table_width} {table_height}">
+{"".join(svg_parts)}
+</svg>"""
+
+    # Apply placeholder styling if needed
+    if is_placeholder:
+        from dataface.core.render.placeholder import (
+            add_placeholder_overlay,
+            apply_placeholder_opacity,
+        )
+
+        svg_result = apply_placeholder_opacity(svg_result)
+        svg_result = add_placeholder_overlay(
+            svg_result,
+            table_width,
+            table_height,
+            font=FontStyle(family=table_font_family),
+        )
+
+    return svg_result
+
+
+# ---------------------------------------------------------------------------
+# Pivot helper — long-form → wide-form (cross-tab) transformation
+# ---------------------------------------------------------------------------
+
+
+def pivot_long_to_wide(
+    data: list[dict[str, Any]],
+    *,
+    column: str,
+    value: str,
+) -> list[dict[str, Any]]:
+    """Transform long-form rows into a wide (cross-tab) matrix.
+
+    Given long-form rows where `column` field values become column headers
+    and `value` field fills each cell, returns wide-form rows keyed by the
+    remaining row-dim fields.
+
+    Example:
+        data = [{"region":"US","month":"Jan","amount":100}, ...]
+        pivot_long_to_wide(data, column="month", value="amount")
+        → [{"region":"US","Jan":100,"Feb":200}, {"region":"EU","Jan":150,"Feb":250}]
+
+    Missing (row, col) combinations produce None values in the output.
+    """
+    # Validate that both pivot fields are present before processing.
+    if data:
+        first_row = data[0]
+        observed = sorted(first_row.keys())
+        if column not in first_row:
+            raise ChartDataError(
+                f"pivot.column {column!r} not in data rows; observed keys: {observed}"
+            )
+        if value not in first_row:
+            raise ChartDataError(
+                f"pivot.value {value!r} not in data rows; observed keys: {observed}"
+            )
+    else:
+        return []
+
+    # Collect ordered column header values (preserve first-seen order)
+    col_headers: list[str] = list(dict.fromkeys(str(r[column]) for r in data))
+
+    # Identify row-dim fields (everything except column and value)
+    row_dim_keys = [k for k in data[0] if k != column and k != value]
+
+    # Build composite row key → dict of col_header → cell value.
+    # Track filled slots separately so None measure values don't bypass duplicate detection.
+    row_map: dict[tuple, dict[str, Any]] = {}
+    filled: dict[tuple, set[str]] = {}
+    for row in data:
+        key = tuple(row.get(k) for k in row_dim_keys)
+        if key not in row_map:
+            row_map[key] = {k: row.get(k) for k in row_dim_keys}
+            for h in col_headers:
+                row_map[key][h] = None
+            filled[key] = set()
+        col_val = str(row[column]) if column in row else None
+        if col_val is not None:
+            if col_val in filled[key]:
+                row_key_repr = ", ".join(
+                    f"{k}={row_map[key][k]!r}" for k in row_dim_keys
+                )
+                raise ChartDataError(
+                    f"pivot_long_to_wide: duplicate value for row ({row_key_repr})"
+                    f" and column {col_val!r} — data is not uniquely keyed by"
+                    f" ({', '.join(row_dim_keys)}, {column!r})"
+                )
+            row_map[key][col_val] = row.get(value)
+            filled[key].add(col_val)
+
+    return list(row_map.values())