dataface 0.1.2__py3-none-any.whl

dataface/core/render/chart/standard_renderer.py

@@ -0,0 +1,2645 @@
+"""Mechanical Vega-Lite assembly for resolved charts.
+
+This module is the thin emitter layer. It consumes profile-mapped chart
+state from ``profile.py`` and assembles the final Vega-Lite spec dict.
+All Dataface/Vega-Lite divergence logic (type renames, channel encoding
+construction, orientation transforms, sort mapping, bar axis defaults)
+lives in ``profile.py``, not here.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import copy
+import functools
+import json
+import logging
+import re
+import statistics
+from collections import defaultdict
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from dataface.core.compile.chart_resolved import (
+    ResolvedChart,
+    effective_color_field,
+    is_grouped_bar,
+)
+from dataface.core.compile.config import (
+    get_config,
+    get_default_theme_name,
+    get_theme_dict,
+)
+from dataface.core.compile.data_table_attachment import (
+    attach_data_table,
+    data_table_strip_height,
+    resolve_effective_data_table_style,
+    validate_data_table_against_data,
+)
+from dataface.core.compile.models.chart.authored import (
+    ChartDataTableAggregate,
+    ChartDataTablePerSeries,
+)
+from dataface.core.compile.models.style.compiled import (
+    EndpointLabelsConfig,
+    font_weight_as_css,
+)
+from dataface.core.compile.models.style.merged import (
+    MergedChartsStyle,
+    style_to_vega_lite,
+)
+from dataface.core.compile.palette import resolve_dark_companion_stops
+from dataface.core.compile.vega_config import compile_effective_vega_config
+from dataface.core.compile.vega_lite.validation import (
+    validate_top_level_spec,
+)
+from dataface.core.render.chart.geo import _generate_map_spec, _generate_point_map_spec
+from dataface.core.render.chart.pipeline import (
+    count_horizontal_bar_categories,
+    min_height_for_horizontal_bar_categories,
+)
+from dataface.core.render.chart.presentation import (
+    overlay_merge,
+    to_plain_dict,
+)
+from dataface.core.render.chart.profile import (
+    CHART_TYPE_MAP,
+    _resolve_orient_auto,
+    map_to_vega_lite,
+)
+from dataface.core.render.chart.spec_builders import (
+    bump_padding_bottom,
+    bump_padding_top,
+    new_chart_spec,
+    set_chart_title,
+)
+from dataface.core.render.chart.tick_values import stacked_bar_totals_max
+from dataface.core.render.chart.time_unit_detect import (
+    normalize_labeled_temporal,
+    opens_label_period,
+    resolve_label_time_unit,
+)
+from dataface.core.render.chart.title_overflow import apply_title_overflow_to_spec
+from dataface.core.render.chart.type_inference import is_lex_sortable_date_like
+from dataface.core.render.chart.validation import validate_preaggregated_data
+from dataface.core.render.chart.vega_lite_types import (
+    _generate_arc_spec,
+    _generate_boxplot_spec,
+    _generate_error_spec,
+    _generate_histogram_spec,
+    _generate_layered_spec,
+    _generate_rect_spec,
+)
+from dataface.core.render.errors import ChartDataError, UnknownChartType
+from dataface.core.render.font_measurement import get_font_measurer
+from dataface.core.render.format_utils import format_value
+from dataface.core.render.utils import normalize_data_types
+
+if TYPE_CHECKING:
+    from dataface.core.compile.custom_chart_types import CustomChartTypeRegistry
+    from dataface.core.compile.models.chart.authored import ChartDataTable
+    from dataface.core.compile.models.style.compiled import DataTableStyle
+    from dataface.core.compile.models.style.merged import MergedStyle
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Click interactivity helpers
+# ---------------------------------------------------------------------------
+
+_HREF_PLACEHOLDER = re.compile(r"\{\{\s*(x|y|color|theta)\s*\}\}")
+
+# Sentinel prefix used so vl_convert doesn't mangle relative/query-string URLs.
+# vl_convert resolves relative URLs against its own base URL, so we use an
+# absolute URL with a known prefix that we strip in SVG post-processing.
+# ".invalid" is an IANA-reserved TLD that will never resolve (RFC 6761).
+_HREF_SENTINEL = "http://dft.invalid"
+
+# Internal field name used for the calculate transform output
+_HREF_FIELD = "__df_href__"
+
+
+def _channel_field(resolved: ResolvedChart, channel: str) -> str | None:
+    """Return the data field name for a given encoding channel."""
+    if channel == "x":
+        return resolved.x
+    if channel == "y":
+        y = resolved.y
+        return y[0] if isinstance(y, list) else y
+    if channel == "color":
+        return effective_color_field(resolved)
+    if channel == "theta":
+        return resolved.theta
+    return None
+
+
+def _build_href_calc_expr(
+    template: str, resolved: ResolvedChart, spec: dict[str, Any]
+) -> str:
+    """Build a Vega calculate expression for the href template.
+
+    ``{{ x }}`` → ``'' + datum['month']``
+
+    For temporal fields, Vega coerces datum values to millisecond timestamps
+    before calculate expressions run.  ``'' + datum['day']`` therefore
+    produces a number like ``1775088000000`` rather than ``'2026-04-23'``.
+    When *spec* is provided we inspect the compiled encoding to detect
+    temporal fields and use ``timeFormat(datum['field'], '%Y-%m-%d')``
+    instead so the resulting URL params are ISO date strings.
+
+    Relative URLs (starting with ``?`` or ``/``) are prefixed with the
+    sentinel so vl_convert doesn't mangle them during SVG rendering.
+    The sentinel is stripped during SVG post-processing.
+    """
+    # Build a set of field names whose Vega-Lite encoding type is "temporal"
+    temporal_fields: set[str] = set()
+    for enc_val in spec.get("encoding", {}).values():
+        if isinstance(enc_val, dict) and enc_val.get("type") == "temporal":
+            field_name = enc_val.get("field")
+            if field_name:
+                temporal_fields.add(field_name)
+
+    parts = _HREF_PLACEHOLDER.split(template)
+    channels_found = _HREF_PLACEHOLDER.findall(template)
+
+    # parts alternates: literal, channel, literal, channel, ...
+    expr_parts: list[str] = []
+    for i, part in enumerate(parts):
+        if i % 2 == 0:
+            if part:
+                expr_parts.append(
+                    "'" + part.replace("\\", "\\\\").replace("'", "\\'") + "'"
+                )
+        else:
+            channel = channels_found[i // 2]
+            field = _channel_field(resolved, channel)
+            if field is None:
+                raise ValueError(
+                    f"link template references channel '{{{{ {channel} }}}}' but chart "
+                    f"has no '{channel}' encoding assigned"
+                )
+            safe = field.replace("\\", "\\\\").replace("'", "\\'")
+            if field in temporal_fields:
+                # Vega coerces temporal datum values to ms timestamps; use
+                # timeFormat to get a URL-safe ISO date string instead.
+                expr_parts.append(f"timeFormat(datum['{safe}'], '%Y-%m-%d')")
+            else:
+                expr_parts.append(f"'' + datum['{safe}']")
+
+    expr = " + ".join(expr_parts) if expr_parts else "''"
+
+    # Prefix relative/query-string URLs with sentinel to prevent vl_convert mangling
+    if template.startswith("?") or template.startswith("/"):
+        return f"'{_HREF_SENTINEL}' + {expr}"
+    return expr
+
+
+def _apply_click_interactivity(
+    spec: dict[str, Any], resolved: ResolvedChart
+) -> dict[str, Any]:
+    """Add href encoding to a Vega-Lite spec for href interactivity.
+
+    Uses a calculate transform + field encoding so vl_convert renders real
+    SVG ``<a>`` elements. The sentinel prefix on relative URLs is stripped
+    during SVG post-processing (see converters/chart.py).
+    """
+    if not resolved.link:
+        return spec
+
+    calc_expr = _build_href_calc_expr(resolved.link, resolved, spec=spec)
+    result = dict(spec)
+
+    transforms = list(result.get("transform") or [])
+    transforms.append({"calculate": calc_expr, "as": _HREF_FIELD})
+    result["transform"] = transforms
+
+    enc = dict(result.get("encoding", {}))
+    enc["href"] = {
+        "field": _HREF_FIELD,
+        "type": "nominal",
+    }  # Vega-Lite wire name; unrelated to Dataface's authored `link:`
+    result["encoding"] = enc
+    return result
+
+
+def _inject_legend_toggle_param(
+    spec: dict[str, Any],
+    resolved_chart: ResolvedChart,
+    resolved_chart_style: MergedChartsStyle,
+) -> dict[str, Any]:
+    """Inject a Vega-Lite point-selection param bound to the legend for click-to-mute.
+
+    Skipped when the spec has no top-level encoding (hconcat/vconcat wrappers from the
+    endpoint-label path) or no visible color legend.
+    """
+    if not resolved_chart_style.legend.interactive_legend:
+        return spec
+    color_field = effective_color_field(resolved_chart)
+    if color_field is None:
+        return spec
+    enc = spec.get("encoding")
+    if not isinstance(enc, dict):
+        return spec
+    color_enc = enc.get("color")
+    if not isinstance(color_enc, dict):
+        return spec
+    if "legend" in color_enc and color_enc["legend"] is None:
+        return spec
+
+    field_lit = json.dumps(color_field)
+    toggle_expr = (
+        f"event.shiftKey"
+        f" || indata('dft_legend_store', {field_lit}, datum[{field_lit}])"
+    )
+    opacity_cond = {
+        "condition": {"param": "dft_legend", "value": 1},
+        "value": 0.2,
+    }
+    dft_param = {
+        "name": "dft_legend",
+        "select": {"type": "point", "fields": [color_field], "toggle": toggle_expr},
+        "bind": "legend",
+    }
+
+    def _has_dft(params: list[Any] | None) -> bool:
+        return any(
+            isinstance(p, dict) and p.get("name") == "dft_legend"
+            for p in (params or [])
+        )
+
+    result = dict(spec)
+    layers = result.get("layer")
+    # In a layered spec, ``params`` at the top level produces a duplicate
+    # ``dft_legend_tuple`` Vega signal during compile (one per layer that
+    # inherits the param). Anchor the param inside the first data-bearing
+    # layer instead — opacity conditions in sibling layers reference it by
+    # name and Vega only registers one signal.
+    if isinstance(layers, list):
+        new_layers: list[dict[str, Any]] = []
+        param_anchored = False
+        for layer in layers:
+            if not isinstance(layer, dict) or "data" in layer:
+                new_layers.append(layer)
+                continue
+            mark = layer.get("mark") or {}
+            if isinstance(mark, dict) and mark.get("opacity") == 0:
+                # Invisible overlay layers (tooltip hit-target points) must not
+                # receive encoding-level opacity: it overrides mark.opacity=0 and
+                # makes the points visible when the legend selection is empty.
+                new_layers.append(layer)
+                continue
+            layer_enc = layer.get("encoding") or {}
+            updated = dict(layer)
+            if "opacity" not in layer_enc:
+                updated["encoding"] = {**layer_enc, "opacity": opacity_cond}
+            if not param_anchored:
+                if _has_dft(layer.get("params")):
+                    return spec  # idempotent
+                updated["params"] = [*(layer.get("params") or []), dft_param]
+                param_anchored = True
+            new_layers.append(updated)
+        if not param_anchored:
+            return spec  # only special layers — nothing to bind opacity to
+        result["layer"] = new_layers
+    else:
+        if _has_dft(result.get("params")):
+            return spec  # idempotent
+        result["params"] = [*(result.get("params") or []), dft_param]
+        if "opacity" not in enc:
+            result["encoding"] = {**enc, "opacity": opacity_cond}
+    return result
+
+
+def build_base_spec(
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    height: float | None = None,
+) -> dict[str, Any]:
+    """Create the base Vega-Lite shell for resolved standard charts."""
+    spec = new_chart_spec(data)
+    if width is not None and width > 0:
+        spec["width"] = width
+    if height is not None and height > 0:
+        spec["height"] = height
+    return spec
+
+
+def _vl_dict_subtract_equal(
+    full: dict[str, Any], default: dict[str, Any]
+) -> dict[str, Any]:
+    """Return only the keys in `full` that differ from `default` (nested)."""
+    result: dict[str, Any] = {}
+    for k, v in full.items():
+        if k not in default:
+            result[k] = v
+        elif isinstance(v, dict) and isinstance(default[k], dict):
+            diff = _vl_dict_subtract_equal(v, default[k])
+            if diff:
+                result[k] = diff
+        elif v != default[k]:
+            result[k] = v
+    return result
+
+
+@functools.lru_cache(maxsize=1)
+def _default_vl_overlay() -> dict[str, Any]:
+    """VL config dict for the theme-applied YAML baseline style.
+
+    Used as baseline in _resolved_style_vega_overlay to emit only
+    non-default values — so cascade-filled defaults don't clobber the
+    VL theme colors already baked into compile_effective_vega_config.
+    The baseline matches what rendered charts see, so only genuine
+    per-chart overrides are emitted as deltas.
+    """
+    from dataface.core.compile.models.style.merged import resolve_style
+
+    return style_to_vega_lite(resolve_style(get_config().style).charts).model_dump(
+        exclude_none=True
+    )
+
+
+def _resolved_style_vega_overlay(style: MergedChartsStyle) -> dict[str, Any]:
+    """Convert a MergedChartsStyle to a Vega-Lite config dict for overlay.
+
+    Only emits values that DIFFER from the bare cascade default so that
+    VL theme colors (from compile_effective_vega_config) are not clobbered
+    by cascade-filled root defaults.
+    """
+    vlc = style_to_vega_lite(style)
+    full = vlc.model_dump(exclude_none=True)
+    return _vl_dict_subtract_equal(full, _default_vl_overlay())
+
+
+def apply_presentation_defaults(
+    spec: dict[str, Any],
+    theme_name: str | None,
+    resolved_chart_style: MergedChartsStyle,
+    *,
+    effective_vega_config: dict[str, Any] | None = None,
+    width_aware_title: dict[str, Any] | None = None,
+    face_background_overlay: str | None = None,
+) -> dict[str, Any]:
+    """Apply compiled presentation defaults to an emitted Vega-Lite spec once.
+
+    When callers provide ``effective_vega_config``, render uses that compiled
+    base config directly and only overlays authored chart config plus the
+    effective chart style view.
+
+    When omitted, render falls back to compiling defaults from the unified theme.
+
+    ``width_aware_title`` splits across two priority tiers: its width-driven
+    ``font`` (family) applies *after* the style overlay so the
+    narrow→body / wide→title family choice wins over the editorial title-slot
+    delta; its ``fontSize`` / ``fontWeight`` apply *before* the style overlay
+    so an authored ``style.title.font.size`` or ``font.weight`` still wins.
+    The width-aware family itself already incorporates face-local and
+    chart-local family patches (via ``chart_title_spec`` reading the
+    resolved chart style), so authored family flows through at medium/wide
+    tiers; only narrow-tier legibility demotion bypasses it.
+    """
+    result_spec = copy.deepcopy(spec)
+    if "config" not in result_spec:
+        result_spec["config"] = {}
+    elif not isinstance(result_spec["config"], dict):
+        raise TypeError("Chart config must be a dictionary")
+    authored_config = copy.deepcopy(result_spec["config"])
+
+    if effective_vega_config:  # falsy (None or {}) → compile from theme defaults
+        compiled = copy.deepcopy(effective_vega_config)
+    else:
+        compiled = compile_effective_vega_config(theme=theme_name)
+
+    # width_aware_title carries three keys: font (family), fontSize, fontWeight.
+    # They split between two priority tiers because they answer different
+    # questions:
+    #   - fontSize / fontWeight are width-aware defaults. The style overlay
+    #     must win when a chart author writes `style.title.font.size: 30` or
+    #     `style.title.font.weight: 700` — apply them BEFORE the overlay.
+    #   - font (family) is a width-driven decision that wins by design:
+    #     narrow widths demote to the body family for legibility, regardless
+    #     of theme. The width-aware family already incorporates any authored
+    #     `style.title.font.family` (via chart_title_spec reading resolved_-
+    #     chart_style at medium/wide tiers), so authored family flows through
+    #     too. Apply font AFTER the overlay so the editorial title-slot delta
+    #     can't clobber the narrow→body demotion.
+    if width_aware_title:
+        compiled.setdefault("title", {})
+        title_defaults = {k: v for k, v in width_aware_title.items() if k != "font"}
+        if title_defaults:
+            compiled["title"] = overlay_merge(compiled["title"], title_defaults)
+
+    style_overlay = _resolved_style_vega_overlay(resolved_chart_style)
+    if style_overlay:
+        compiled = overlay_merge(compiled, style_overlay)
+
+    if width_aware_title and "font" in width_aware_title:
+        compiled.setdefault("title", {})
+        compiled["title"] = overlay_merge(
+            compiled["title"], {"font": width_aware_title["font"]}
+        )
+
+    result_spec["config"] = compiled
+
+    effective_theme_name = (
+        get_default_theme_name() if theme_name in (None, "default") else theme_name
+    )
+    vega_theme_config = get_theme_dict(effective_theme_name)
+    preserve_transparent_background = (
+        result_spec.get("background") is None and "projection" in result_spec
+    )
+    if not preserve_transparent_background:
+        # Spec root background precedence: face's resolved background (when
+        # threaded through) > unified compiled theme > old-format VL theme.
+        # The face background is the source of truth — it already accounts for
+        # theme + face-local style overrides, so charts inside a face never
+        # disagree with the face's actual paper colour.
+        root_bg = (
+            face_background_overlay
+            if face_background_overlay is not None
+            else (
+                compiled.get("background")
+                if not vega_theme_config
+                else vega_theme_config.get("background")
+            )
+        )
+        if root_bg is not None:
+            result_spec["background"] = root_bg
+
+    # Chart-local background override takes priority over theme at spec root level.
+    # Only non-None when set by ChartStylePatch.background (chart-local override).
+    if resolved_chart_style.background is not None:
+        result_spec["background"] = resolved_chart_style.background
+
+    result_spec["config"] = overlay_merge(result_spec["config"], authored_config)
+    return result_spec
+
+
+def build_layered_series_spec(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    height: float | None = None,
+    theme: str | None = None,
+    datasets: dict[str, list[dict[str, Any]]] | None = None,
+) -> dict[str, Any]:
+    """Build the explicit layered-series path for multi-metric charts.
+
+    Layered profiled charts use the same ``MappedChart`` contract as single-series
+    profiled charts so the renderer never re-derives chart semantics.
+    """
+    mapped = map_to_vega_lite(resolved_chart, data, width, theme, datasets=datasets)
+    return _generate_layered_spec(mapped, resolved_chart, data, width, height)
+
+
+def _apply_projection_override(
+    spec: dict[str, Any], resolved_chart: ResolvedChart
+) -> dict[str, Any]:
+    """Apply the authored projection field onto the emitted spec."""
+    authored_projection = to_plain_dict(resolved_chart.projection)
+    if isinstance(authored_projection, str):
+        authored_projection = {"type": authored_projection}
+    if not authored_projection:
+        return spec
+
+    result = copy.deepcopy(spec)
+    existing_projection = result.get("projection")
+    if isinstance(existing_projection, dict) and isinstance(authored_projection, dict):
+        result["projection"] = overlay_merge(existing_projection, authored_projection)
+    else:
+        result["projection"] = authored_projection
+    return result
+
+
+def _finalize_standard_spec(
+    spec: dict[str, Any],
+    theme: str | None,
+    resolved_chart_style: MergedChartsStyle,
+    width: float | None = None,
+    face_background_overlay: str | None = None,
+    face_level: int = 1,
+    effective_vega_config: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Apply presentation defaults and validate the emitted Vega-Lite spec.
+
+    Presentation defaults are applied first so that the compiled Vega config
+    (including ``config.title.fontSize`` from the theme) is available when
+    ``apply_title_overflow_to_spec`` computes character-level line breaks.
+
+    Args:
+        face_level: Heading level of the parent face (root=1, nested=2, …).
+            Chart title uses face_level + 1.
+    """
+    from dataface.core.compile.typography import chart_title_spec
+    from dataface.core.render.font_support import (
+        INTER_FONT_FAMILY,
+        INTER_VARIABLE_FONT_FAMILY,
+    )
+
+    width_aware_title: dict[str, Any] | None = None
+    title_font_size: float | None = None
+    title_font_family: str | None = None
+    if width is not None and width > 0:
+        font_size, font_weight, font_family = chart_title_spec(
+            width, level=face_level + 1, resolved_chart_style=resolved_chart_style
+        )
+        title_font_size = float(font_size)
+        # vl-convert registers InterVariable.ttf as "Inter Variable", not "Inter".
+        # Use the registered name so Vega renders with the correct font instead of
+        # falling back to a system sans-serif. The measurer resolves both names to
+        # the same TTF (see get_font_measurer), so pass the vl name on both sides to
+        # keep the measurer/renderer font identity tight.
+        title_font_family = (
+            INTER_VARIABLE_FONT_FAMILY
+            if font_family == INTER_FONT_FAMILY
+            else font_family
+        )
+        width_aware_title = {
+            "font": title_font_family,
+            "fontSize": font_size,
+            "fontWeight": font_weight,
+        }
+    spec_with_config = apply_presentation_defaults(
+        spec,
+        theme,
+        resolved_chart_style,
+        effective_vega_config=effective_vega_config,
+        width_aware_title=width_aware_title,
+        face_background_overlay=face_background_overlay,
+    )
+    apply_title_overflow_to_spec(
+        spec_with_config,
+        resolved_chart_style.title,
+        title_font_size=title_font_size,
+        title_font_family=title_font_family,
+    )
+    return validate_top_level_spec(spec_with_config)
+
+
+_LABEL_Y_ALIAS = "__label_y"
+_LABEL_X_ALIAS = "__label_x"
+_LABEL_DODGE_ALIAS = "__dodge_row"
+
+# Horizontal stacked bar label rail: maximum number of times a colliding
+# label may be lifted above the base row. The leftmost label always sits
+# at row 0; each rightward neighbor that would intersect a previously
+# placed label's bbox lifts by one line-height. If the cap is hit, the
+# next collision is placed at the cap row anyway — the alternative
+# (dropping labels or raising) makes the chart misread silently.
+_HORIZONTAL_LABEL_RAIL_MAX_DODGE = 3
+
+# Pixel padding between adjacent label bounding boxes, used by the
+# horizontal-rail dodge resolver to decide whether two labels can sit at
+# the same dodge row. Mirrors the line/area pane's pixel-gap design;
+# tuned so labels visually clear at body-font sizes.
+_HORIZONTAL_LABEL_RAIL_X_GAP_PX = 4.0
+
+
+def _dark_companion_stops(
+    data: list[dict[str, Any]],
+    series_field: str,
+    palette: list[str],
+) -> tuple[list[str], list[str]]:
+    """Endpoint-label helper: derive the color-domain order + dark companions.
+
+    Wraps :func:`resolve_dark_companion_stops` for the endpoint-label path,
+    which needs the alphabetised color domain alongside the resolved dark
+    stops. Vega-lite sorts nominal scale domains alphabetically, so the
+    chart pane maps ``palette[i]`` to the i-th series in that order — the
+    label pane must mirror it.
+
+    Returns ``(color_domain_order, dark_stops)`` indexed in lockstep.
+    """
+    distinct: set[str] = set()
+    for row in data:
+        s = row.get(series_field)
+        if s is not None:
+            distinct.add(str(s))
+    color_domain_order = sorted(distinct)
+    n = len(color_domain_order) or 1
+    emitted_colors = palette[:n]
+    dark_stops = resolve_dark_companion_stops(emitted_colors)
+    return color_domain_order, dark_stops
+
+
+def _label_mark_font(
+    resolved_chart_style: MergedChartsStyle,
+) -> tuple[dict[str, Any], str, float]:
+    """Resolve the series-label font triple for a label-pane text mark.
+
+    Returns ``(mark_props, font_family, font_size)``: ``mark_props`` is a
+    dict ready to splice into a ``mark`` (carries ``fontSize``, ``font``,
+    and ``fontWeight`` mapped through ``font_weight_as_css``);
+    ``font_family`` and ``font_size`` are surfaced so callers can also use
+    them with the font measurer to size the pane.
+
+    All three font fields assert non-None — the cascade fills family/
+    weight from ``charts.font`` and size from the explicit theme value.
+    Silent fallback would mask the same "cascade dropped my override"
+    class of bug the font primitive is built to prevent.
+    """
+    label_font_size = resolved_chart_style.series_label.font.size
+    assert label_font_size is not None, (
+        "MergedChartsStyle.series_label.font.size is None — theme cascade did "
+        "not fill it; fix the theme rather than defaulting in the renderer"
+    )
+    label_font_family = resolved_chart_style.series_label.font.family
+    assert label_font_family is not None, (
+        "MergedChartsStyle.series_label.font.family is None — _apply_cascade "
+        "did not fill it from charts.font; fix the theme rather than "
+        "defaulting in the renderer"
+    )
+    label_font_weight = resolved_chart_style.series_label.font.weight
+    assert label_font_weight is not None, (
+        "MergedChartsStyle.series_label.font.weight is None — _apply_cascade "
+        "did not fill it from charts.font; fix the theme rather than "
+        "defaulting in the renderer"
+    )
+    return (
+        {
+            "fontSize": label_font_size,
+            "font": label_font_family,
+            "fontWeight": font_weight_as_css(label_font_weight),
+        },
+        label_font_family,
+        float(label_font_size),
+    )
+
+
+# Font-size multiplier matching standard line-height for body text. The
+# value applies as the minimum-gap between adjacent label y-centers, in
+# pixels-per-point-of-font-size. At 1.0 two 14pt labels sit 14px apart
+# — bounding rects just touch, but lowercase letters (which mostly live
+# in the x-height, ~0.5× font size) have clear visual separation. 1.4
+# was tried earlier and read as too airy for tight series clusters; 0.7
+# let descender-on-ascender pairs visually overlap. 1.0 is the middle
+# call: bounding rects kiss, lowercase reads cleanly, descenders on the
+# rare ascender pair touch but don't cross.
+_LABEL_LINE_HEIGHT_MULTIPLIER = 1.3
+
+# Plot area is smaller than the chart's outer height (title + subtitle +
+# axis labels + padding eat into it). 0.85 is a coarse approximation that
+# errs on the safe side — slightly under-estimating plot height inflates
+# the data-units gap, so labels end up a bit further apart than the pure
+# math would call for, never closer.
+_PLOT_AREA_FRACTION = 0.85
+
+
+def _extract_y_domain(
+    spec: dict[str, Any],
+    data: list[dict[str, Any]],
+    y_field: str,
+) -> tuple[float, float]:
+    """Return (y_min, y_max) for the chart's y scale.
+
+    Prefer explicit bounds from the finalized spec (what vega-lite actually
+    maps to pixels) in this order:
+      1. ``encoding.y.scale.domain`` list — exact two-element bound.
+      2. ``encoding.y.scale.domainMin`` + ``domainMax`` both present — stacked
+         bars set domainMax; bar/area charts set domainMin via tick pinning.
+    Falls back to raw data range when the chart leaves all bounds implicit.
+    """
+    enc = spec.get("encoding")
+    if isinstance(enc, dict):
+        y_enc = enc.get("y")
+        if isinstance(y_enc, dict):
+            scale = y_enc.get("scale")
+            if isinstance(scale, dict):
+                domain = scale.get("domain")
+                if isinstance(domain, list) and len(domain) == 2:
+                    try:
+                        lo, hi = float(domain[0]), float(domain[1])
+                        if hi >= lo:
+                            return lo, hi
+                    except (TypeError, ValueError):
+                        pass
+                d_min = scale.get("domainMin")
+                d_max = scale.get("domainMax")
+                if d_min is not None and d_max is not None:
+                    try:
+                        lo, hi = float(d_min), float(d_max)
+                        if hi >= lo:
+                            return lo, hi
+                    except (TypeError, ValueError):
+                        pass
+    ys = [
+        float(row[y_field])
+        for row in data
+        if y_field in row and row[y_field] is not None
+    ]
+    if ys:
+        return float(min(ys)), float(max(ys))
+    return 0.0, 1.0
+
+
+def _resolve_endpoint_label_positions(
+    data: list[dict[str, Any]],
+    x_field: str,
+    y_field: str,
+    series_field: str,
+    min_data_gap: float,
+    y_domain_min: float,
+    y_domain_max: float,
+) -> list[tuple[str, float]]:
+    """Compute (series, label_y) pairs anchored to line endpoints with
+    bidirectional greedy collision avoidance.
+
+    Algorithm:
+        1. For each series take the row at the largest x — its y value is
+           the natural anchor.
+        2. Compute the cluster centroid (mean of anchor y's). If the
+           centroid sits in the upper half of the y domain, cascade
+           *downward*: walk anchors top-to-bottom and push each one down
+           to ``previous − min_data_gap`` if it's too close. If the
+           centroid is in the lower half, cascade *upward* instead: walk
+           anchors bottom-to-top and push each one up by ``min_data_gap``.
+
+    The direction flip prevents labels from being shoved off the chart's
+    bottom (resp. top) when several series cluster against one edge of
+    the plot — the anchored end of the cascade is whichever one is
+    closer to its bound, so displacement always grows *into* the empty
+    half of the plot.
+
+    `min_data_gap` and the domain bounds are computed by the caller so
+    spacing stays fixed in *pixels* across charts of different y ranges.
+    Returns a list ordered top-to-bottom (descending y) regardless of
+    which cascade direction was used.
+    """
+    last_x: Any = None
+    for row in data:
+        v = row.get(x_field)
+        if v is None:
+            continue
+        if last_x is None or v > last_x:
+            last_x = v
+
+    last_per_series: dict[str, float] = {}
+    for row in data:
+        if row.get(x_field) != last_x:
+            continue
+        s = row.get(series_field)
+        y = row.get(y_field)
+        if s is None or y is None:
+            continue
+        last_per_series[str(s)] = float(y)
+
+    return _apply_label_cascade(
+        last_per_series,
+        min_data_gap=min_data_gap,
+        y_domain_min=y_domain_min,
+        y_domain_max=y_domain_max,
+    )
+
+
+def _apply_label_cascade(
+    anchors: dict[str, float],
+    min_data_gap: float,
+    y_domain_min: float,
+    y_domain_max: float,
+) -> list[tuple[str, float]]:
+    """Bidirectional greedy collision-avoidance over an anchor map.
+
+    Shared by the line/area and bar resolvers — both produce a
+    ``{series: anchor_y}`` map and want the same nudge-on-collision pass.
+    Output is ordered top-to-bottom (descending y).
+    """
+    if not anchors:
+        return []
+
+    domain_mid = (y_domain_min + y_domain_max) / 2.0
+    anchor_mean = sum(anchors.values()) / len(anchors)
+
+    if anchor_mean >= domain_mid:
+        # Cluster sits in the upper half → pin the topmost anchor and
+        # cascade downward into the empty lower half.
+        items = sorted(anchors.items(), key=lambda kv: kv[1], reverse=True)
+        adjusted: list[tuple[str, float]] = []
+        for series, y in items:
+            if adjusted and adjusted[-1][1] - y < min_data_gap:
+                y = adjusted[-1][1] - min_data_gap
+            # Clamp before storing so subsequent iterations use the clamped
+            # position and out-of-domain values never reach the label pane
+            # data (which would expand the shared hconcat y-scale).
+            y = max(y_domain_min, y)
+            adjusted.append((series, y))
+        return adjusted
+
+    # Cluster sits in the lower half → pin the bottommost anchor and
+    # cascade upward into the empty upper half.
+    items = sorted(anchors.items(), key=lambda kv: kv[1])
+    upward: list[tuple[str, float]] = []
+    for series, y in items:
+        if upward and y - upward[-1][1] < min_data_gap:
+            y = upward[-1][1] + min_data_gap
+        y = min(y_domain_max, y)
+        upward.append((series, y))
+    # Caller expects descending-y order (top of plot first).
+    return list(reversed(upward))
+
+
+def _resolve_bar_endpoint_label_positions(
+    data: list[dict[str, Any]],
+    x_field: str,
+    y_field: str,
+    series_field: str,
+    stack_mode: str | bool | None,
+    min_data_gap: float,
+    y_domain_min: float,
+    y_domain_max: float,
+    stack_order: str | None = None,
+) -> list[tuple[str, float]]:
+    """Compute (series, label_y) anchors for the bar family.
+
+    Per-stack-mode anchor:
+        - ``"zero"`` (or ``None`` — VL's bar default): segment midpoint of
+          each series in the rightmost x column. Cumulative bottom-up sum
+          in the order determined by ``stack_order``, matching
+          ``_apply_stacked_bar_z_order``'s pin so labels anchor over their
+          actual rendered segments.
+        - ``"normalize"``: same midpoint, expressed as a share of the
+          column's total so anchors land on the 0..1 normalized scale.
+        - ``False``: grouped/overlapping bars — anchor sits at each
+          series' bar top (the value itself).
+
+    ``stack_order`` mirrors the same knob as ``_apply_stacked_bar_z_order``:
+        - ``None`` / ``"value"``: largest-sum series at baseline (default).
+        - ``"alphabetical"``: alpha-ascending series at baseline.
+        - ``"data"``: caller should not be computing midpoints for data order;
+          treated as value order here (SQL order is not reproduced at render time).
+
+    Cascade pass shared with the line/area resolver via
+    ``_apply_label_cascade``.
+
+    Raises ``ChartDataError`` when the chart's stack mode falls outside the
+    supported set (``"center"``) or when values are negative — both produce
+    silently wrong anchor positions on top of correctly-rendered bars and
+    violate the validate-and-error-fast non-negotiable. The caller in
+    ``_build_endpoint_label_pane`` already collapses ``stack: True`` to
+    ``"zero"``, so this resolver sees one canonical mode per call.
+    """
+    if stack_mode not in (None, False, "zero", "normalize"):
+        raise ChartDataError(
+            f"endpoint_labels: stack mode {stack_mode!r} is not supported on "
+            "the bar family — use 'zero', 'normalize', or stack: false. "
+            "(Diverging 'center' stacks would need signed segment-midpoint "
+            "anchors against a (-Σ/2, +Σ/2) domain; not yet implemented.)"
+        )
+
+    last_x: Any = None
+    for row in data:
+        v = row.get(x_field)
+        if v is None:
+            continue
+        if last_x is None or v > last_x:
+            last_x = v
+
+    values_at_last: dict[str, float] = {}
+    for row in data:
+        if row.get(x_field) != last_x:
+            continue
+        s = row.get(series_field)
+        y = row.get(y_field)
+        if s is None or y is None:
+            continue
+        values_at_last[str(s)] = float(y)
+    if not values_at_last:
+        return []
+
+    if stack_mode is not False and any(v < 0 for v in values_at_last.values()):
+        raise ChartDataError(
+            "endpoint_labels: negative values in the trailing x column are "
+            "not supported on stacked bar charts — VL's stacked domain spans "
+            "both signs and the cumulative-midpoint computation would land "
+            "labels off the segments. Set ``stack: false`` (grouped bars), "
+            "or filter/transform the data upstream."
+        )
+
+    # Series iteration order must match _apply_stacked_bar_z_order so label
+    # anchors land on the actual rendered segments. The first series in the
+    # iteration sits at cum_lower=0 (baseline); subsequent ones stack above.
+    # VL stacks by the global sum (joinaggregate transform on encoding.order),
+    # so we sort by global sum here too (not local per-bar values).
+    # Grouped bars (stack=False) overlap, no stacking order needed.
+    if stack_order == "alphabetical":
+        # Alpha-ascending: alphabetically-first series at baseline.
+        series_order = sorted(values_at_last)
+    elif stack_order == "data":
+        # VL builds its ordinal color domain in global first-encounter order across
+        # all data rows — not the order at last_x. Use the same traversal so label
+        # midpoints land on the right segments even when row order varies by x-group.
+        seen: dict[str, None] = {}
+        for row in data:
+            s = row.get(series_field)
+            if s is not None:
+                seen[str(s)] = None
+        series_order = [s for s in seen if s in values_at_last]
+    else:
+        # Default (None or "value"): globally-largest series at baseline.
+        # Stable secondary sort by name so ties are deterministic.
+        global_sums: dict[str, float] = {}
+        for row in data:
+            s = row.get(series_field)
+            y = row.get(y_field)
+            if s is None or y is None:
+                continue
+            key = str(s)
+            global_sums[key] = global_sums.get(key, 0.0) + float(y)
+        series_order = sorted(
+            values_at_last, key=lambda s: (-global_sums.get(s, 0.0), s)
+        )
+
+    if stack_mode is False:
+        anchors = {s: values_at_last[s] for s in series_order}
+    else:
+        total = sum(values_at_last[s] for s in series_order)
+        anchors = {}
+        cum_lower = 0.0
+        for s in series_order:
+            v = values_at_last[s]
+            mid = cum_lower + v / 2.0
+            if stack_mode == "normalize" and total > 0:
+                mid = mid / total
+            anchors[s] = mid
+            cum_lower += v
+
+    return _apply_label_cascade(
+        anchors,
+        min_data_gap=min_data_gap,
+        y_domain_min=y_domain_min,
+        y_domain_max=y_domain_max,
+    )
+
+
+def _bar_stack_y_domain(
+    data: list[dict[str, Any]],
+    x_field: str,
+    y_field: str,
+    stack_mode: str | bool | None,
+) -> tuple[float, float]:
+    """Return the (min, max) y-domain that the bar chart actually renders.
+
+    ``_extract_y_domain`` reads the spec's explicit y-scale domain when
+    set; for stacked bar charts vega-lite computes the stacked domain at
+    render time and the spec leaves ``scale.domain`` unset, so falling
+    back to raw value min/max would put cascade decisions in the wrong
+    half of the chart. Compute the correct rendered domain here.
+    """
+    if stack_mode == "normalize":
+        return 0.0, 1.0
+    if stack_mode is False:
+        ys = [
+            float(row[y_field])
+            for row in data
+            if y_field in row and row[y_field] is not None
+        ]
+        if not ys:
+            return 0.0, 1.0
+        # Grouped/overlapping bars: VL's quantitative y-scale always
+        # includes 0; with negative values the domain spans both signs.
+        return min(0.0, min(ys)), max(0.0, max(ys))
+    # Stacked at zero (default for bar with color encoding).
+    totals_max = stacked_bar_totals_max(data, x_field, y_field)
+    return (0.0, totals_max) if totals_max is not None else (0.0, 1.0)
+
+
+def _label_pane_min_data_gap(
+    resolved_chart_style: MergedChartsStyle,
+    y_domain_min: float,
+    y_domain_max: float,
+    spec_height: float | None = None,
+) -> float:
+    """Convert the desired pixel gap between labels into data units.
+
+    The gap target is fixed in pixels — `series_label.font.size × line-height` —
+    so a chart with a tall y range gets the same visual spacing as a short one.
+    We scale that target into data units using the chart's y-domain range and pixel
+    height, because the resolver works in data units (the label pane shares
+    pane[0]'s y scale).
+
+    The label pane is pinned to ``spec_height`` (see ``_build_endpoint_label_pane``),
+    so the shared hconcat y-scale always uses ``spec_height`` as its pixel range.
+    When ``spec_height`` is unknown (None or 0) both panes default to
+    ``view.continuousHeight``.
+    """
+    font_size = resolved_chart_style.series_label.font.size
+    assert font_size is not None, (
+        "MergedChartsStyle.series_label.font.size is None — theme cascade "
+        "did not fill it; fix the theme rather than defaulting in the renderer"
+    )
+    y_range = (y_domain_max - y_domain_min) if y_domain_max > y_domain_min else 1.0
+    continuous = resolved_chart_style.view.continuous_height
+    # Label pane carries explicit height=spec_height (see _build_endpoint_label_pane),
+    # so the shared hconcat y-scale always uses spec_height as its pixel range.
+    # When spec_height is unknown, both panes default to view.continuousHeight.
+    chart_height = (
+        float(spec_height)
+        if spec_height is not None and spec_height > 0
+        else continuous
+    )
+    plot_height = chart_height * _PLOT_AREA_FRACTION
+    min_pixel_gap = font_size * _LABEL_LINE_HEIGHT_MULTIPLIER
+    return min_pixel_gap * (y_range / plot_height)
+
+
+def _resolve_horizontal_top_row_label_anchors(
+    data: list[dict[str, Any]],
+    x_field: str,
+    y_field: str,
+    series_field: str,
+    stack_mode: str | bool | None,
+    stack_order: str | None = None,
+) -> dict[str, float]:
+    """Return ``{series: x_midpoint}`` for the alphabetical-first row of a
+    horizontal stacked bar chart.
+
+    The horizontal label rail names color segments inside a single
+    "label-bearing" row at the top of the chart. The top row is the
+    alphabetical-first value of the *post-swap-y* axis (which is the
+    authored ``x_field`` — VL renders nominal-domain[0] at the top of a
+    left-oriented categorical axis). Within that row, segments stack
+    along the measure axis with ``_apply_stacked_bar_z_order``'s order pin
+    (value-descending by default, or alphabetical when stack_order='alphabetical').
+    Midpoints are computed cumulatively in the same order so each label
+    anchors over its actual rendered segment.
+
+    For ``stack: normalize`` midpoints are expressed as shares of the
+    top row's total (the chart pane is pinned to the [0, 1] x-domain
+    elsewhere in the wrap helper).
+
+    ``stack: True`` / ``None`` are accepted and collapsed to ``"zero"``
+    (VL's implicit default for bar marks); ``False`` and ``"center"``
+    raise — grouped bars don't stack and diverging stacks would need
+    signed-midpoint anchors not yet implemented.
+    """
+    if stack_mode is True or stack_mode is None:
+        stack_mode = "zero"
+    if stack_mode not in ("zero", "normalize"):
+        raise ChartDataError(
+            f"endpoint_labels: stack mode {stack_mode!r} is not supported on "
+            "horizontal bars — use 'zero' (the default) or 'normalize'. "
+            "Grouped horizontal bars (stack: false) don't form stacks to "
+            "label; diverging 'center' stacks would need signed midpoint "
+            "anchors not yet implemented."
+        )
+
+    distinct_rows = sorted(
+        {str(r[x_field]) for r in data if x_field in r and r[x_field] is not None}
+    )
+    if not distinct_rows:
+        return {}
+    top_row = distinct_rows[0]
+
+    values_at_top: dict[str, float] = {}
+    for row in data:
+        if x_field not in row or row[x_field] is None:
+            continue
+        if str(row[x_field]) != top_row:
+            continue
+        s = row.get(series_field)
+        v = row.get(y_field)
+        if s is None or v is None:
+            continue
+        values_at_top[str(s)] = float(v)
+    if not values_at_top:
+        return {}
+
+    if any(v < 0 for v in values_at_top.values()):
+        raise ChartDataError(
+            "endpoint_labels: negative values in the top row of a horizontal "
+            "stacked bar chart are not supported — VL's stacked domain spans "
+            "both signs and the cumulative-midpoint computation would land "
+            "labels off the segments. Set ``stack: false`` (grouped bars) or "
+            "filter/transform the data upstream."
+        )
+
+    # Series iteration order must match _apply_stacked_bar_z_order: the first
+    # series in the iteration sits at the baseline (left, x=0 for horizontal).
+    # VL stacks by the global sum (joinaggregate transform on encoding.order),
+    # so we sort by global sum here too (not just the top-row values).
+    if stack_order == "alphabetical":
+        series_order = sorted(values_at_top)
+    elif stack_order == "data":
+        # VL builds its ordinal color domain in global first-encounter order across
+        # all data rows — not the order at the reference row. Use the same traversal.
+        seen: dict[str, None] = {}
+        for row in data:
+            s = row.get(series_field)
+            if s is not None:
+                seen[str(s)] = None
+        series_order = [s for s in seen if s in values_at_top]
+    else:
+        # Default (None or "value"): globally-largest series at baseline.
+        global_sums: dict[str, float] = {}
+        for row in data:
+            s = row.get(series_field)
+            v = row.get(y_field)
+            if s is None or v is None:
+                continue
+            key = str(s)
+            global_sums[key] = global_sums.get(key, 0.0) + float(v)
+        series_order = sorted(
+            values_at_top, key=lambda s: (-global_sums.get(s, 0.0), s)
+        )
+
+    total = sum(values_at_top[s] for s in series_order)
+
+    cum_lower = 0.0
+    midpoints: dict[str, float] = {}
+    for s in series_order:
+        v = values_at_top[s]
+        mid = cum_lower + v / 2.0
+        if stack_mode == "normalize" and total > 0:
+            mid = mid / total
+        midpoints[s] = mid
+        cum_lower += v
+    return midpoints
+
+
+def _resolve_horizontal_label_dodge(
+    midpoints: dict[str, float],
+    label_widths_px: dict[str, float],
+    chart_x_min: float,
+    chart_x_max: float,
+    chart_pane_width: float,
+    gap_px: float,
+    max_dodge: int,
+) -> list[tuple[str, float, int]]:
+    """Walk left-to-right; right-hand neighbor lifts on collision.
+
+    Returns ``[(series, x_mid, dodge_row)]`` ordered by ``x_mid`` ascending.
+    The leftmost label always sits at ``dodge_row=0`` (the resolver's
+    determinism contract — pinned in tests). Each subsequent label tries
+    rows 0..``max_dodge``; if it collides at every row, it's placed at
+    ``max_dodge`` anyway. We never raise: the alternative (dropping a
+    label) makes the chart misread silently.
+    """
+    items = sorted(midpoints.items(), key=lambda kv: kv[1])
+    if chart_x_max <= chart_x_min or chart_pane_width <= 0 or not items:
+        return [(s, x, 0) for s, x in items]
+
+    domain_to_px = chart_pane_width / (chart_x_max - chart_x_min)
+    placed: list[tuple[str, float, float, float, int]] = []
+
+    for series, x_mid in items:
+        center_px = (x_mid - chart_x_min) * domain_to_px
+        # Trust the caller: ``label_widths_px`` is built from the same
+        # series keys that drive ``midpoints``. KeyError here would surface
+        # a real cascade bug — defaulting to 0 would silently collapse the
+        # bbox and make every collision check trivially pass, dropping
+        # every right-hand label onto the base row.
+        w_px = label_widths_px[series]
+        x_lo = center_px - w_px / 2.0
+        x_hi = center_px + w_px / 2.0
+
+        chosen = max_dodge
+        for dodge in range(max_dodge + 1):
+            collides = False
+            for _, _, p_lo, p_hi, p_dodge in placed:
+                if p_dodge != dodge:
+                    continue
+                # Two intervals overlap iff each starts before the other's
+                # gap-padded end. The negation: one ends before the other's
+                # gap-padded start.
+                if x_hi + gap_px <= p_lo or x_lo >= p_hi + gap_px:
+                    continue
+                collides = True
+                break
+            if not collides:
+                chosen = dodge
+                break
+
+        placed.append((series, x_mid, x_lo, x_hi, chosen))
+
+    return [(s, x, d) for s, x, _, _, d in placed]
+
+
+def _build_horizontal_top_row_rail_pane(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    resolved_chart_style: MergedChartsStyle,
+    main_spec: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the top-row series-label rail for horizontal stacked bars.
+
+    Layout: a separate pane that stacks above the chart in a ``vconcat``
+    with ``resolve.scale.x = shared``. Each series gets one text mark at
+    the segment midpoint of the top categorical row (alphabetical-first
+    y-domain value). When neighboring midpoints' label bboxes would
+    overlap, the right-hand label lifts by ``__dodge_row`` line-heights
+    (cap = ``_HORIZONTAL_LABEL_RAIL_MAX_DODGE``). The pane's ``height``
+    is sized to the actual stacking depth before being returned.
+    """
+    # In horizontal bar specs the user-authored ``x`` is the categorical
+    # axis (post-swap → emitted as encoding.y) and authored ``y`` is the
+    # quantitative measure (post-swap → emitted as encoding.x). The
+    # ResolvedChart still carries the AUTHORED field names; the rail
+    # resolver works in authored space.
+    x_field = resolved_chart.x or "x"
+    y_field = (
+        resolved_chart.y[0]
+        if isinstance(resolved_chart.y, list)
+        else (resolved_chart.y or "y")
+    )
+    color_ch = resolved_chart.resolved_channels["color"]
+    series_field = color_ch.data_field
+    assert series_field, (
+        "horizontal endpoint-label rail invoked without a color/series field — "
+        "endpoint_label_pane_will_fire should have gated this; cascade is broken"
+    )
+
+    # The rail anchors at the *alphabetical-first* y-domain value (VL's
+    # default sort for nominal scales). When the chart authors a non-default
+    # sort, the rendered top row is whatever that sort puts first — likely
+    # not alphabetical-first. Honoring an arbitrary sort here would require
+    # mirroring VL's full sort-resolution machinery (sort-by-measure,
+    # sort-array, sort-by-encoding); raising is the validate-and-error-fast
+    # response so labels never silently anchor on the wrong row.
+    if resolved_chart.sort is not None:
+        raise ChartDataError(
+            "endpoint_labels: a chart.sort on a horizontal stacked bar with "
+            "endpoint_labels.visible is not supported — the rail anchors at "
+            "the alphabetical-first row, but a custom sort would put a "
+            "different row at the top of the chart and the labels would "
+            "land on the wrong row's segments. Drop the sort, or disable "
+            "endpoint_labels on this chart."
+        )
+
+    midpoints = _resolve_horizontal_top_row_label_anchors(
+        data,
+        x_field,
+        y_field,
+        series_field,
+        stack_mode=resolved_chart.stack,
+        stack_order=resolved_chart.resolved_style.bar.stack_order,
+    )
+
+    color_domain_order, dark_stops = _dark_companion_stops(
+        data, series_field, list(resolved_chart_style.palette)
+    )
+
+    mark_font_props, label_font_family, label_font_size = _label_mark_font(
+        resolved_chart_style
+    )
+
+    # Measure label widths once so the dodge resolver can decide whether two
+    # adjacent labels' bboxes intersect.
+    measurer = get_font_measurer(label_font_family)
+    widths_px = {s: measurer.measure(s, label_font_size) for s in midpoints}
+
+    chart_pane_width_raw = main_spec.get("width")
+    assert (
+        isinstance(chart_pane_width_raw, (int, float)) and chart_pane_width_raw > 0
+    ), (
+        "horizontal endpoint-label rail invoked without a positive chart width; "
+        f"got {chart_pane_width_raw!r}. The standard render path always supplies "
+        "width — fix the caller rather than defaulting here."
+    )
+    chart_pane_width = float(chart_pane_width_raw)
+
+    if resolved_chart.stack == "normalize":
+        x_min, x_max = 0.0, 1.0
+    else:
+        # Top-row's stacked total is the chart's x-domain max (the longest
+        # bar in the chart sets the scale; for stack-zero VL extends the
+        # quantitative axis to max-of-totals across rows). We measure
+        # collision in pixel space relative to that scale.
+        x_min = 0.0
+        totals: dict[Any, float] = {}
+        for row in data:
+            xv = row.get(x_field)
+            yv = row.get(y_field)
+            if xv is None or yv is None:
+                continue
+            totals[xv] = totals.get(xv, 0.0) + float(yv)
+        x_max = max(totals.values()) if totals else 1.0
+
+    positions = _resolve_horizontal_label_dodge(
+        midpoints,
+        widths_px,
+        chart_x_min=x_min,
+        chart_x_max=x_max,
+        chart_pane_width=chart_pane_width,
+        gap_px=_HORIZONTAL_LABEL_RAIL_X_GAP_PX,
+        max_dodge=_HORIZONTAL_LABEL_RAIL_MAX_DODGE,
+    )
+
+    label_pane_data = [
+        {
+            series_field: s,
+            _LABEL_X_ALIAS: x,
+            _LABEL_DODGE_ALIAS: d,
+        }
+        for s, x, d in positions
+    ]
+    max_dodge_used = max((d for _, _, d in positions), default=0)
+
+    line_height_px = float(label_font_size) * _LABEL_LINE_HEIGHT_MULTIPLIER
+    rail_height = (max_dodge_used + 1) * line_height_px + line_height_px / 2.0
+
+    pane_spec: dict[str, Any] = {
+        "width": chart_pane_width,
+        "height": rail_height,
+        "view": {"stroke": None},
+        "data": {"values": label_pane_data},
+        "mark": {
+            "type": "text",
+            "align": "center",
+            "baseline": "bottom",
+            **mark_font_props,
+        },
+        "encoding": {
+            "x": {
+                "field": _LABEL_X_ALIAS,
+                "type": "quantitative",
+                "axis": None,
+            },
+            "y": {
+                "field": _LABEL_DODGE_ALIAS,
+                "type": "quantitative",
+                "axis": None,
+                # Pin the y-domain so dodge_row=0 lands at the bottom of the
+                # rail pane (closest to the chart), max_dodge_used at the
+                # top — independent of the actual values present in the
+                # data so a chart that doesn't trigger dodge still places
+                # all labels just above the bar (not centered in the pane).
+                "scale": {"domain": [0, max(max_dodge_used, 1)]},
+            },
+            "color": {
+                "field": series_field,
+                "type": "nominal",
+                "scale": {
+                    "domain": color_domain_order,
+                    "range": dark_stops,
+                },
+                "legend": None,
+            },
+            "text": {"field": series_field},
+        },
+    }
+    return pane_spec
+
+
+def _build_endpoint_label_pane(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    resolved_chart_style: MergedChartsStyle,
+    main_spec: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the right-side label pane for multi-series line/area endpoint labels.
+
+    Each label anchors to its series' last data point via a shared y scale
+    with the main pane; when several series cluster at similar y values
+    a bidirectional greedy nudging pass (`_resolve_endpoint_label_positions`)
+    spreads colliding labels apart by a fixed pixel gap derived from
+    `series_label.font.size`. Label text is the series name only — the coloured
+    stroke/fill carries series identity.
+    """
+    x_field = resolved_chart.x or "x"
+    series_field = (
+        resolved_chart.resolved_channels["color"].data_field or "series"
+        if resolved_chart.resolved_channels.get("color")
+        else "series"
+    )
+    y_field = (
+        resolved_chart.y[0]
+        if isinstance(resolved_chart.y, list)
+        else (resolved_chart.y or "y")
+    )
+
+    # The sizing pass sets spec["height"] to width/aspect_ratio (the VL plot
+    # area in pixels). Use it so min_data_gap scales correctly when the chart
+    # is shorter than DEFAULT_CHART_HEIGHT. Fall back to None
+    # so _label_pane_min_data_gap uses view.continuous_height instead.
+    raw_spec_height = main_spec.get("height")
+    spec_height: float | None = (
+        float(raw_spec_height)
+        if isinstance(raw_spec_height, (int, float)) and raw_spec_height > 0
+        else None
+    )
+
+    if resolved_chart.chart_type == "bar":
+        # Bar's effective y-domain is the stacked-total range (or [0,1] for
+        # normalize) — vega-lite computes it at render time and the spec
+        # carries no explicit ``scale.domain`` to extract.
+        stack_mode: str | bool | None = resolved_chart.stack
+        # ``stack: True`` is VL's implicit default ("zero" for bars); collapse
+        # so downstream resolver/domain helpers see one canonical mode.
+        # Grouped-by-default bars anchor at bar top, not at stacked midpoints.
+        if stack_mode is True:
+            stack_mode = "zero"
+        elif is_grouped_bar(resolved_chart):
+            stack_mode = False
+        y_domain_min, y_domain_max = _bar_stack_y_domain(
+            data, x_field, y_field, stack_mode
+        )
+        min_data_gap = _label_pane_min_data_gap(
+            resolved_chart_style, y_domain_min, y_domain_max, spec_height=spec_height
+        )
+        positions = _resolve_bar_endpoint_label_positions(
+            data,
+            x_field,
+            y_field,
+            series_field,
+            stack_mode=stack_mode,
+            min_data_gap=min_data_gap,
+            y_domain_min=y_domain_min,
+            y_domain_max=y_domain_max,
+            stack_order=resolved_chart.resolved_style.bar.stack_order,
+        )
+    else:
+        y_domain_min, y_domain_max = _extract_y_domain(main_spec, data, y_field)
+        min_data_gap = _label_pane_min_data_gap(
+            resolved_chart_style, y_domain_min, y_domain_max, spec_height=spec_height
+        )
+        positions = _resolve_endpoint_label_positions(
+            data,
+            x_field,
+            y_field,
+            series_field,
+            min_data_gap=min_data_gap,
+            y_domain_min=y_domain_min,
+            y_domain_max=y_domain_max,
+        )
+
+    color_domain_order, dark_stops = _dark_companion_stops(
+        data, series_field, list(resolved_chart_style.palette)
+    )
+
+    label_pane_data = [{series_field: s, _LABEL_Y_ALIAS: y} for s, y in positions]
+
+    mark_font_props, label_font_family, label_font_size = _label_mark_font(
+        resolved_chart_style
+    )
+    measurer = get_font_measurer(label_font_family)
+    _GAP_PX = 4.0
+    max_label_px = max(
+        (measurer.measure(str(s), label_font_size) for s in color_domain_order),
+        default=0.0,
+    )
+    label_width = max_label_px + _GAP_PX
+    chart_width_raw = main_spec.get("width")
+    if isinstance(chart_width_raw, (int, float)) and chart_width_raw > 0:
+        # Cap the pane at 1/3 of the chart width. Labels wider than the cap
+        # are truncated by Vega via the mark's limit property below. The chart
+        # grows rightward to accommodate the pane, so no error is raised.
+        label_width = min(label_width, chart_width_raw / 3.0)
+
+    label_mark = {
+        "type": "text",
+        "align": "left",
+        "baseline": "middle",
+        **mark_font_props,
+        # Truncate labels that exceed the pane width with an ellipsis.
+        # Kicks in when label_width was capped at chart_width/3 above.
+        "limit": label_width,
+    }
+
+    pane: dict[str, Any] = {
+        "width": label_width,
+        "view": {"stroke": None},
+        "data": {"values": label_pane_data},
+        "mark": label_mark,
+        "encoding": {
+            "x": {"value": 0},
+            "y": {
+                "field": _LABEL_Y_ALIAS,
+                "type": "quantitative",
+                "axis": None,
+            },
+            "color": {
+                "field": series_field,
+                "type": "nominal",
+                "scale": {
+                    "domain": color_domain_order,
+                    "range": dark_stops,
+                },
+                "legend": None,
+            },
+            "text": {"field": series_field},
+        },
+    }
+    # Pin the label pane to the same height as pane[0]. Without this, VL
+    # defaults the label pane to view.continuousHeight (300px), which is taller
+    # than pane[0] when the sizing pass renders at a smaller spec_height. The
+    # taller pane then governs the hconcat total height, making the chart with
+    # endpoint labels taller than the same chart without labels.
+    if spec_height is not None and spec_height > 0:
+        pane["height"] = spec_height
+    return pane
+
+
+def endpoint_label_pane_will_fire(
+    resolved_chart: ResolvedChart,
+    resolved_chart_style: MergedChartsStyle,
+) -> bool:
+    """Return True iff the endpoint-label pane will actually render.
+
+    Used by both ``_maybe_wrap_endpoint_label_pane`` (decides whether to
+    emit the hconcat label pane) and ``_resolve_orient_auto`` in
+    ``profile.py`` (decides whether to flip ``axis_y`` to the left
+    because the right-edge label pane would collide with a right-side
+    y-axis). Centralizing the predicate keeps the two helpers from
+    diverging — divergence meant single-series and horizontal-bar
+    charts authoring ``endpoint_labels.visible: true`` got their
+    y-axis silently flipped without a pane to justify the flip.
+
+    Firing conditions, in order:
+
+    1. Chart type is ``line``, ``area``, or ``bar`` (the only families
+       with a typed ``endpoint_labels`` field).
+    2. The family's compiled style has ``endpoint_labels.visible``.
+    3. For horizontal bar: stack mode must be truthy (``zero`` /
+       ``normalize`` / VL's implicit default). The rail labels color
+       segments inside a single row; grouped horizontal bars (``stack:
+       false``) sit side-by-side and
+       don't form stacks to label.
+    4. The color channel is in ``"series"`` mode with a data field
+       (multi-series only — single-series charts don't need direct
+       labels at series endpoints because there's only one series).
+    """
+    if resolved_chart.chart_type not in ("line", "area", "bar"):
+        return False
+    # Direct attribute access: every family in the allowlist owns a typed
+    # ``endpoint_labels: EndpointLabelsConfig`` field on its compiled
+    # style. ``getattr(..., None)`` here would mask the same cascade-dropped-
+    # my-override class of bug the font_size assert below catches.
+    chart_family_style = getattr(resolved_chart_style, resolved_chart.chart_type)
+    if not chart_family_style.endpoint_labels.visible:
+        return False
+    if (
+        resolved_chart.chart_type == "bar"
+        and resolved_chart.orientation == "horizontal"
+    ):
+        # Top-row series rail only applies to stacked horizontals.
+        # Grouped bars — explicit ``stack: false`` or grouped-by-default — don't
+        # form stacks to label.
+        if resolved_chart.stack is False or is_grouped_bar(resolved_chart):
+            return False
+    color_ch = resolved_chart.resolved_channels.get("color")
+    return not (
+        color_ch is None or color_ch.mode != "series" or not color_ch.data_field
+    )
+
+
+def _maybe_wrap_endpoint_label_pane(
+    spec: dict[str, Any],
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    resolved_chart_style: MergedChartsStyle,
+) -> dict[str, Any]:
+    """Wrap the main spec in hconcat with a label pane if endpoint labels are enabled.
+
+    Firing condition delegated to ``endpoint_label_pane_will_fire``;
+    see that function for the full predicate.
+    """
+    if not endpoint_label_pane_will_fire(resolved_chart, resolved_chart_style):
+        return spec
+
+    chart_family_style = getattr(resolved_chart_style, resolved_chart.chart_type)
+    endpoint_labels_cfg = chart_family_style.endpoint_labels
+
+    if (
+        resolved_chart.chart_type == "bar"
+        and resolved_chart.orientation == "horizontal"
+    ):
+        return _wrap_horizontal_top_row_rail(
+            spec, resolved_chart, data, resolved_chart_style, endpoint_labels_cfg
+        )
+
+    label_pane = _build_endpoint_label_pane(
+        resolved_chart, data, resolved_chart_style, spec
+    )
+
+    # Auto-disable the categorical legend on pane[0]. A right-edge label pane
+    # and a side legend encode the same series→colour mapping; rendering both
+    # is double-encoding (Cleveland on direct labels), and the legend's right-
+    # side overhang blows past the wrap helper's pane[0] width budget, so the
+    # label pane clips out of the canvas.
+    color_enc = spec.get("encoding", {}).get("color")
+    if isinstance(color_enc, dict):
+        color_enc["legend"] = None
+
+    # Pin pane[0]'s y-scale domain to [0, 1] when stack=normalize. VL's auto-
+    # scale on the raw value field would yield [0, max(value)], and the
+    # wrapper's resolve.scale.y=shared then propagates that raw-domain scale
+    # to the label pane — squashing every label near zero on 100% stacks.
+    # The label-position resolver already works in [0, 1] for normalize
+    # (_bar_stack_y_domain), so this pin makes pane[0]'s rendered scale agree
+    # with the label-pane domain. Resolved in endpoint-labels.md.
+    if resolved_chart.chart_type == "bar" and resolved_chart.stack == "normalize":
+        y_enc = spec.get("encoding", {}).get("y")
+        if isinstance(y_enc, dict):
+            scale = y_enc.setdefault("scale", {})
+            if isinstance(scale, dict):
+                scale["domain"] = [0, 1]
+
+    # vl-convert ignores autosize:fit on hconcat children
+    # (https://vega.github.io/vega-lite/docs/size.html#limitations).
+    # Stamp the intended total SVG width on the wrapper; render_vega_spec
+    # does a two-pass render: first to measure the actual SVG width, then
+    # shrinks pane[0].width by the overshoot before the real render.
+    spacing = endpoint_labels_cfg.label_offset
+    pane0_width = spec.get("width")
+    pane0_height = spec.get("height")
+
+    # Lift spec-level properties from the main spec to the hconcat root.
+    # vl-convert treats $schema/config/background/data as top-level-only:
+    # when they sit inside a concat child, theme config is silently dropped
+    # (default vega palette + default tick chrome) and pane[1] cannot resolve
+    # the dataset (renders as an empty <g>). `title`, `padding`, and `autosize`
+    # stay on pane[0] so vega-lite anchors the title over the chart body's
+    # visual bounds (not the full hconcat including the label pane — hoisting
+    # title to the wrapper shifts it ~20px rightward for wide label panes).
+    hoist_keys = (
+        "$schema",
+        "config",
+        "background",
+        "data",
+    )
+    hoisted = {k: spec.pop(k) for k in hoist_keys if k in spec}
+
+    wrapper: dict[str, Any] = {
+        **hoisted,
+        "spacing": spacing,
+        # y must be SHARED so labels align with each line's actual endpoint
+        # pixel y. hconcat's default is `independent` for position channels,
+        # which would let pane[1] derive its own y scale from the filtered
+        # last-x rows and float labels off the line endpoints. color stays
+        # independent so the label pane uses its own dark companion stops.
+        "resolve": {"scale": {"color": "independent", "y": "shared"}},
+        "hconcat": [spec, label_pane],
+        **(
+            {"$df_target_width": float(pane0_width)}
+            if isinstance(pane0_width, (int, float)) and pane0_width > 0
+            else {}
+        ),
+        **(
+            {"$df_target_height": float(pane0_height)}
+            if isinstance(pane0_height, (int, float)) and pane0_height > 0
+            else {}
+        ),
+    }
+    return wrapper
+
+
+def _wrap_horizontal_top_row_rail(
+    spec: dict[str, Any],
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    resolved_chart_style: MergedChartsStyle,
+    endpoint_labels_cfg: EndpointLabelsConfig,
+) -> dict[str, Any]:
+    """Compose a vconcat with the series-label rail above the horizontal chart.
+
+    Layout asymmetry is by design: vertical stacks read top-to-bottom along
+    the measure axis, so per-segment labels sit on the SIDE in an hconcat;
+    horizontal stacks read left-to-right inside one row, so a single rail
+    of one-label-per-series sits ABOVE the top categorical row. Both
+    follow from the same reading-direction principle (label rail runs
+    perpendicular to the measure axis).
+    """
+    rail_pane = _build_horizontal_top_row_rail_pane(
+        resolved_chart, data, resolved_chart_style, spec
+    )
+
+    # Direct labels and a side legend double-encode the same series→colour
+    # mapping; suppress the cascade-default legend when wrapping. Mirrors
+    # the hconcat path's auto-disable.
+    color_enc = spec.get("encoding", {}).get("color")
+    if isinstance(color_enc, dict):
+        color_enc["legend"] = None
+
+    # Pin the chart pane's x-scale (post-swap measure axis) to [0, 1] when
+    # stack=normalize. Without the pin VL's auto-scale on the raw value
+    # field would yield [0, max(value)] and ``resolve.scale.x = shared``
+    # propagates that raw-domain scale to the rail pane — squashing every
+    # label near the left edge. The rail resolver works on [0, 1] for
+    # normalize, so this keeps the shared scale agreeing with it.
+    if resolved_chart.stack == "normalize":
+        x_enc = spec.get("encoding", {}).get("x")
+        if isinstance(x_enc, dict):
+            scale = x_enc.setdefault("scale", {})
+            if isinstance(scale, dict):
+                scale["domain"] = [0, 1]
+
+    spacing = endpoint_labels_cfg.label_offset
+
+    # Reserve room for the rail pane inside the chart's allocated cell
+    # height. vl-convert ignores ``autosize: fit`` on vconcat the same way
+    # it ignores it on hconcat, so the outer SVG ends up as
+    # ``rail_pane.height + spacing + chart_pane.height + padding`` and
+    # overflows the configured cell height. Mirror the hconcat path's
+    # width-reduction by subtracting the rail's footprint from the chart
+    # pane's height.
+    rail_pane_height = float(rail_pane.get("height", 0) or 0)
+    pane_height = spec.get("height")
+    if isinstance(pane_height, (int, float)) and pane_height > 0:
+        reduced = float(pane_height) - rail_pane_height - spacing
+        if reduced > 0:
+            spec["height"] = reduced
+
+    # Hoist top-level keys (same set as hconcat) so vl-convert resolves
+    # theme config, $schema, the dataset, and chrome at the wrapper root
+    # rather than dropping them when they sit inside a concat child.
+    # Title hoists cleanly here — both panes are equal-width via
+    # ``resolve.scale.x = shared``, so the title centers correctly over
+    # both. The hconcat path keeps title on pane[0] for the opposite
+    # reason (uneven pane widths shift a hoisted title rightward).
+    hoist_keys = (
+        "$schema",
+        "config",
+        "background",
+        "title",
+        "data",
+    )
+    hoisted = {k: spec.pop(k) for k in hoist_keys if k in spec}
+
+    pane_target_width = spec.get("width")
+    wrapper: dict[str, Any] = {
+        **hoisted,
+        "spacing": spacing,
+        # x must be SHARED so each label centers on the actual segment's
+        # rendered pixel x — vconcat's default is `independent`, which
+        # would let the rail pane derive its own x-scale from the
+        # filtered top-row data and float labels off the segments.
+        "resolve": {"scale": {"color": "independent", "x": "shared"}},
+        "vconcat": [rail_pane, spec],
+        **(
+            {"$df_target_width": float(pane_target_width)}
+            if isinstance(pane_target_width, (int, float)) and pane_target_width > 0
+            else {}
+        ),
+    }
+    return wrapper
+
+
+def _inject_zero_baseline_rule(
+    spec: dict[str, Any],
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]] | None,
+) -> dict[str, Any]:
+    """Insert zero (and, for normalize-stacked, top) baseline rule layers.
+
+    Vega renders axis guides (grid lines) below marks, so area/bar fills cover
+    the bold zero baseline. Insertion position is chart-type-specific:
+
+    - bar/layered: append last — rule renders above all fills.
+    - line: insert first — rule renders below strokes so lines cross y=0
+      without being interrupted by the baseline.
+    - area: insert after the last ``type: "area"`` layer — rule renders above
+      the fg area fill but below the fg stroke (line mark). Layer order:
+      halo_fill, halo_stroke, fg_fill, zero_rule, fg_stroke, hover_overlay.
+
+    For ``stack: normalize`` charts, also insert a sibling rule at y=1 in the
+    same position as the zero rule.
+
+    Skipped when both rule helpers return None (wrong chart type, 0 not in
+    y-domain, horizontal bar, grid hidden, or non-normalize stack for the top
+    rule). Single-mark bar specs are converted to layered with the bar mark in
+    ``layer[0]`` and rules appended after.
+    """
+    from dataface.core.render.chart.profile import (
+        top_rule_vl_layer,
+        zero_rule_vl_layer,
+    )
+
+    if data is None:
+        data = []
+    zero_rule = zero_rule_vl_layer(resolved_chart, data)
+    top_rule = top_rule_vl_layer(resolved_chart, data)
+
+    rules = [r for r in (zero_rule, top_rule) if r is not None]
+    if not rules:
+        return spec
+    if "layer" in spec:
+        chart_type = resolved_chart.chart_type
+        if chart_type == "line":
+            spec["layer"] = [*rules, *spec["layer"]]
+        elif chart_type == "area":
+            # Insert after the last area-fill layer so the zero rule appears
+            # above fills but below the separate stroke (line) layers.
+            # _map_area emits fill layers (type: "area") before stroke layers
+            # (type: "line"), so scanning for the last area-type mark gives
+            # the correct insertion point.
+            layers = spec["layer"]
+            last_area_idx = -1
+            for i, layer in enumerate(layers):
+                mark = layer.get("mark", {})
+                mark_type = mark.get("type") if isinstance(mark, dict) else mark
+                if mark_type == "area":
+                    last_area_idx = i
+            if last_area_idx >= 0:
+                spec["layer"] = [
+                    *layers[: last_area_idx + 1],
+                    *rules,
+                    *layers[last_area_idx + 1 :],
+                ]
+            elif len(layers) >= 2:
+                spec["layer"] = [*layers[:-1], *rules, layers[-1]]
+            else:
+                spec["layer"].extend(rules)
+        else:
+            spec["layer"].extend(rules)
+        return spec
+    if "mark" not in spec:
+        return spec  # not a chart spec we can wrap
+    spec["layer"] = [{"mark": spec.pop("mark")}, *rules]
+    return spec
+
+
+def _finalize(
+    spec: dict[str, Any],
+    resolved_chart: ResolvedChart,
+    theme: str | None,
+    resolved_chart_style: MergedChartsStyle,
+    width: float | None = None,
+    padding: dict[str, Any] | None = None,
+    data: list[dict[str, Any]] | None = None,
+    face_background_overlay: str | None = None,
+    face_level: int = 1,
+    effective_vega_config: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Apply passthrough overrides, click interactivity, and finalize spec."""
+    spec = _apply_projection_override(spec, resolved_chart)
+    spec = _apply_click_interactivity(spec, resolved_chart)
+    # Apply card padding before finalize so apply_title_overflow_to_spec computes
+    # the title limit against the actual Vega padding, not the default spec padding.
+    if padding is not None:
+        spec["padding"] = padding
+    finalized = _finalize_standard_spec(
+        spec,
+        theme,
+        resolved_chart_style,
+        width=width,
+        face_background_overlay=face_background_overlay,
+        face_level=face_level,
+        effective_vega_config=effective_vega_config,
+    )
+    finalized = _inject_zero_baseline_rule(finalized, resolved_chart, data)
+    if data is not None:
+        finalized = _maybe_wrap_endpoint_label_pane(
+            finalized, resolved_chart, data, resolved_chart_style
+        )
+    # Inject after endpoint-label wrapping so legend suppression (color_enc["legend"]=None)
+    # is already applied and the check accurately reflects what's rendered.
+    finalized = _inject_legend_toggle_param(
+        finalized, resolved_chart, resolved_chart_style
+    )
+    return finalized
+
+
+def _resolve_effective_background(
+    resolved_chart_style: MergedChartsStyle,
+    theme: str | None,
+    face_background_overlay: str | None = None,
+) -> str | None:
+    """Return the chart's effective background colour.
+
+    Precedence:
+    1. Chart-local override (``resolved_chart_style.background``)
+    2. ``face_background_overlay`` — face-level background from ``MergedStyle.background``
+       (cascade: authored value or theme default); None when no MergedStyle is available.
+    3. Theme background looked up by name via ``compile_effective_vega_config``
+       — fallback path for callers that don't carry a MergedStyle.
+    """
+    if resolved_chart_style.background is not None:
+        return resolved_chart_style.background
+    if face_background_overlay is not None:
+        return face_background_overlay
+    compiled = compile_effective_vega_config(theme=theme)
+    bg = compiled.get("background")
+    return bg if isinstance(bg, str) else None
+
+
+def _aggregate_by_x(
+    data: list[dict[str, Any]],
+    source: str,
+    x_field: str,
+    op: str,
+) -> list[float]:
+    """Group data by x_field, apply aggregate op, return resulting values.
+
+    Mirrors the VL aggregate transform used in _row_text_layer so that width
+    measurements reflect the actual rendered strings.  op must be one of:
+    sum, avg, min, max, median, count, count_distinct.
+
+    count/count_distinct do not coerce source values to float — they count
+    rows / distinct raw values so non-numeric sources are first-class.
+    For sum/avg/min/max/median, float() is intentionally not suppressed:
+    a non-numeric source with a numeric aggregate is a query authoring error
+    and should surface as ValueError, not silently produce wrong dx.
+
+    Both ops share the _AGG_OP_TO_VL enum in data_table_attachment.py;
+    update that mapping when adding a new op here.
+    """
+    # count/count_distinct: key on raw values directly (no float coercion)
+    if op in ("count", "count_distinct"):
+        raw_groups: dict[Any, list[Any]] = defaultdict(list)
+        for row in data:
+            x_val = row.get(x_field)
+            raw = row.get(source)
+            if x_val is None:
+                continue
+            raw_groups[x_val].append(raw)
+        if op == "count":
+            return [float(len(vals)) for vals in raw_groups.values() if vals]
+        return [
+            float(len({v for v in vals if v is not None}))
+            for vals in raw_groups.values()
+            if vals
+        ]
+
+    # numeric ops: float() is intentionally not suppressed — non-numeric source
+    # values here mean a query authoring error, not an expected no-op.
+    groups: dict[Any, list[float]] = defaultdict(list)
+    for row in data:
+        x_val = row.get(x_field)
+        raw = row.get(source)
+        if x_val is None or raw is None:
+            continue
+        groups[x_val].append(float(raw))
+
+    results: list[float] = []
+    for vals in groups.values():
+        if not vals:
+            continue
+        if op == "sum":
+            results.append(sum(vals))
+        elif op == "avg":
+            results.append(sum(vals) / len(vals))
+        elif op == "min":
+            results.append(min(vals))
+        elif op == "max":
+            results.append(max(vals))
+        elif op == "median":
+            results.append(statistics.median(vals))
+        else:
+            raise ValueError(f"unknown aggregate op {op!r}")
+    return results
+
+
+def _aggregate_by_x_and_color(
+    data: list[dict[str, Any]],
+    source: str,
+    x_field: str,
+    color_field: str,
+) -> list[float]:
+    """Sum ``source`` grouped by (x, color), mirroring the per_series VL transform.
+
+    The per_series text layer in :mod:`data_table_attachment` emits a sum
+    aggregate keyed on ``[x_field, color_field]`` and a per-series filter,
+    so each rendered cell shows that one series' value at that x. This
+    helper produces the matching width-measurement input — sum-per-(x,
+    series) — so dx reflects the *actual* rendered cell widths rather
+    than the across-series sum.
+    """
+    groups: dict[tuple[Any, Any], list[float]] = defaultdict(list)
+    for row in data:
+        x_val = row.get(x_field)
+        c_val = row.get(color_field)
+        raw = row.get(source)
+        if x_val is None or c_val is None or raw is None:
+            continue
+        groups[(x_val, c_val)].append(float(raw))
+    return [sum(vals) for vals in groups.values() if vals]
+
+
+def _compute_data_table_entry_dx(
+    data_table: ChartDataTable,
+    data: list[dict[str, Any]],
+    dt_style: DataTableStyle,
+    has_time_unit: bool,
+    x_field: str | None = None,
+    x_type: str | None = None,
+    color_field: str | None = None,
+    formats: dict[str, str] | None = None,
+) -> list[float] | None:
+    """Compute per-entry dx offsets for band-centred number lanes.
+
+    Returns None when no offset is needed.  dx is only meaningful on band-scale
+    axes (ordinal/nominal) where bandPosition:0.5 pins the text anchor to the
+    band centre.  For continuous axes (temporal without timeUnit, quantitative)
+    there are no bands — a non-zero dx would shift the text away from the data
+    point rather than centering it.
+
+    When dx is applicable, returns a list of floats, one per entry:
+    dx = max_formatted_width / 2 so that right-aligned text's right edge sits
+    at band_center + max_w/2, centering the column over the bar.
+
+    For ChartDataTableAggregate entries, data is pre-aggregated per x_field
+    before measuring widths so the dx reflects the actual rendered values
+    (aggregates are typically wider than any individual raw row).
+
+    Mirrors the centre-on-midpoint invariant of _compute_lane_positions
+    (table.py): the number lane is centred; decimals still align within it.
+    """
+    # Temporal+timeUnit strips already use bandPosition:1.0 (right-edge anchor).
+    # Adding dx there would double-shift the text — skip centering.
+    if has_time_unit:
+        return None
+    # Continuous axes (quantitative, temporal without timeUnit) have no bands.
+    # dx on these would shift text off the data point rather than centering it.
+    if x_type not in ("ordinal", "nominal"):
+        return None
+
+    font_family = dt_style.font.family
+    font_size = dt_style.font.size
+    if font_size is None:
+        raise ValueError(
+            "data_table.font.size must be set by the theme cascade; "
+            "a missing value means the theme is misconfigured"
+        )
+    measurer = get_font_measurer(font_family, numeric=True)
+
+    entry_dx: list[float] = []
+    for entry in data_table.entries:
+        max_w = 0.0
+        fmt = entry.format
+
+        if isinstance(entry, ChartDataTablePerSeries):
+            # per_series entries render one cell per (x, series) — measure
+            # widths over the same (x, color) grouping the VL aggregate
+            # transform uses (data_table_attachment._per_series_row_layers).
+            # Grouping by x alone would sum across series and inflate dx.
+            source = entry.per_series
+            values: list[float] = []
+            if x_field is not None and color_field is not None:
+                values = _aggregate_by_x_and_color(data, source, x_field, color_field)
+            else:
+                for row in data:
+                    raw = row.get(source)
+                    if raw is None:
+                        continue
+                    with contextlib.suppress(ValueError, TypeError):
+                        values.append(float(raw))
+        elif isinstance(entry, ChartDataTableAggregate) and x_field is not None:
+            # Pre-aggregate to match the VL aggregate transform in _row_text_layer.
+            # Without this, dx is measured from raw per-row values which are
+            # typically narrower than the per-x aggregate.
+            source = entry.source
+            values = _aggregate_by_x(data, source, x_field, entry.aggregate)
+        else:
+            source = entry.source
+            # Bare source entries can point to string columns (Vega renders them
+            # directly as labels).  Non-numeric values simply contribute no width;
+            # dx falls to 0 and the column is not band-centred — which is correct
+            # because centering is only meaningful for a column of known numeric width.
+            values = []
+            for row in data:
+                raw = row.get(source)
+                if raw is None:
+                    continue
+                with contextlib.suppress(ValueError, TypeError):
+                    values.append(float(raw))
+
+        for num in values:
+            formatted = format_value(num, fmt, formats) if fmt else str(num)
+            w = measurer.measure(formatted, font_size)
+            if w > max_w:
+                max_w = w
+        entry_dx.append(max_w / 2.0)
+
+    return entry_dx if any(dx > 0 for dx in entry_dx) else None
+
+
+def _label_period_filter_expr(
+    spec: dict[str, Any],
+    resolved_chart_style: MergedChartsStyle,
+    data: list[dict[str, Any]],
+    x_field: str,
+    chart_type: str,
+) -> str | None:
+    """Return a Vega filter expression restricting data_table cells to label-period openers.
+
+    Returns None when no filtering is needed: label cadence equals band cadence,
+    no temporal axis, no coarser label cadence, or opens_label_period returns None
+    for an unsupported encoding/label-cadence pair.
+
+    Semantics for aggregate: entries — the filter shows the per-opener-band
+    aggregate, not a re-aggregated sum across all bands in the period. This is
+    correct for the primary case (one source row per band), and re-aggregating
+    across bands would require a different VL groupby granularity that changes
+    what the agg op operates on. The filter matches the opener list used by
+    labelExpr so every visible axis label has exactly one data_table cell.
+
+    For the temporal path (timeUnit in spec x encoding): uses opens_label_period
+    to build a UTC-month/date predicate on the raw x field.
+
+    For the ordinal bucketed-time path (axis.values present): builds an indexof
+    predicate against the precomputed tick-values list (the label-period openers
+    already computed by ordinal_axis_values in profile.py).
+    """
+    from dataface.core.compile.style_cascade import resolved_axis_style
+
+    enc_x = spec.get("encoding", {}).get("x", {})
+    x_type = enc_x.get("type")
+
+    # Resolve the chart-type-specific axis_x patch (Layer 3.5) so authored
+    # label.time_unit values that land on chart.style.<type>.axis_x via
+    # normalize_chart_local_style_dict are picked up.
+    ct_style = getattr(resolved_chart_style, chart_type, None)
+    ct_axis_x = getattr(ct_style, "axis_x", None) if ct_style is not None else None
+
+    # Temporal path: timeUnit present in spec x encoding.
+    enc_time_unit = enc_x.get("timeUnit")
+    if enc_time_unit:
+        # vl_time_unit emits "utc<grain>" (e.g. "utcyearmonth") in the spec.
+        # Strip that prefix so internal helpers that work with Dataface grain
+        # names ("yearmonth", "yearweek", …) receive the right string.
+        dft_time_unit = enc_time_unit.removeprefix("utc")
+        axis_st = resolved_axis_style(
+            resolved_chart_style, "axis_x", x_type or "temporal", ct_axis_x
+        )
+        label_tu = resolve_label_time_unit(dft_time_unit, axis_st.label.time_unit)
+        if not label_tu or label_tu == dft_time_unit:
+            return None
+        safe_field = x_field.replace("'", "\\'")
+        gate = opens_label_period(
+            dft_time_unit,
+            label_tu,
+            v=f"toDate(datum['{safe_field}'])",
+            month="utcmonth",
+            date="utcdate",
+        )
+        return gate
+
+    # Ordinal bucketed-time path: axis.values is the precomputed opener list.
+    if x_type == "ordinal":
+        axis_vals = enc_x.get("axis", {}).get("values")
+        if not axis_vals:
+            return None
+        x_distinct = {
+            row.get(x_field)
+            for row in data
+            if x_field in row and row.get(x_field) is not None
+        }
+        if len(axis_vals) >= len(x_distinct):
+            # No thinning needed: every band has a label.
+            return None
+        # Only filter when bands are too dense to show all cells without overlap.
+        # At >= 45 px per band a formatted number fits; sparser data shows all cells.
+        spec_width = spec.get("width")
+        if isinstance(spec_width, (int, float)) and spec_width > 0:
+            if spec_width / len(x_distinct) >= 45.0:
+                return None
+        safe_field = x_field.replace("'", "\\'")
+        safe_vals = [
+            str(v).replace("\\", "\\\\").replace("'", "\\'") for v in axis_vals
+        ]
+        quoted = ", ".join(f"'{v}'" for v in safe_vals)
+        return f"indexof([{quoted}], datum['{safe_field}']) >= 0"
+
+    return None
+
+
+def _maybe_attach_data_table(
+    spec: dict[str, Any],
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    resolved_chart_style: MergedChartsStyle,
+    padding: dict[str, Any] | None,
+    chart_type: str,
+) -> tuple[dict[str, Any], dict[str, Any] | None]:
+    """Post-pass: attach the data_table strip when the chart authors one.
+
+    Single source of truth for the validate → resolve-style → attach →
+    reserve-padding sequence. Called from every render branch that needs
+    to honor `chart.data_table` (single-mark, profile-driven layered,
+    author-layered). Returns the (possibly mutated) spec plus the
+    (possibly augmented) padding kwarg the caller forwards to _finalize.
+
+    Padding-bump destination depends on whether the caller supplied an
+    external padding kwarg (which _finalize overwrites wholesale) or
+    None (which leaves spec.padding alone).
+    """
+    data_table = resolved_chart.source_chart.data_table
+    if data_table is None:
+        return spec, padding
+    # Extract the x encoding type from the already-built spec.
+    x_type: str | None = spec.get("encoding", {}).get("x", {}).get("type")
+    # For the validator, lex-sortable date-like ordinal axes (e.g. "2024-01")
+    # behave like temporal — the window sort on the raw string field produces
+    # chronological order for year-leading patterns — so sampling is safe.
+    # Non-lex-sortable patterns (e.g. "Jan 2024", "01/2024") stay ordinal and
+    # continue to fail-closed at >40 distinct values.
+    # IMPORTANT: this reclassification is only for the validator.  x_type (the
+    # actual spec encoding type) is kept separate so centering still applies to
+    # lex-sortable ordinal axes — they render with bandPosition:0.5, so they
+    # need dx exactly like any other ordinal axis.
+    validator_x_type = x_type
+    if validator_x_type == "ordinal" and resolved_chart.x and data:
+        # Require ALL non-null values to be lex-sortable date-like — one stray
+        # "Unknown" mid-column must keep the axis ordinal (fail-closed).
+        field = resolved_chart.x
+        all_lex_sortable = True
+        for row in data:
+            v = row.get(field)
+            if v is None:
+                continue
+            if not (isinstance(v, str) and is_lex_sortable_date_like(v)):
+                all_lex_sortable = False
+                break
+        if all_lex_sortable:
+            validator_x_type = "temporal"
+    sampling_step = validate_data_table_against_data(
+        data_table, resolved_chart.x, data, x_type=validator_x_type
+    )
+    dt_style = resolve_effective_data_table_style(resolved_chart_style, chart_type)
+    has_time_unit = bool(spec.get("encoding", {}).get("x", {}).get("timeUnit"))
+    # color_field used by both the dx computation (per_series cells are
+    # measured per-(x, series) so dx reflects the actual rendered widths
+    # rather than the across-series sum) and the series_order/palette
+    # resolution below.
+    color_field = effective_color_field(resolved_chart)
+    # Compute per-entry dx so number-lane centres align with band midpoints.
+    # Uses x_type (the spec encoding type) NOT validator_x_type, so lex-sortable
+    # ordinal axes (which have bandPosition:0.5) still get the dx they need.
+    entry_dx = _compute_data_table_entry_dx(
+        data_table,
+        data,
+        dt_style,
+        has_time_unit,
+        x_field=resolved_chart.x,
+        x_type=x_type,
+        color_field=color_field,
+        formats=resolved_chart_style.formats,
+    )
+    # Resolve series_order and series_palette for per_series entries.
+    has_per_series = any(
+        isinstance(e, ChartDataTablePerSeries) for e in data_table.entries
+    )
+    series_order: list[str] | None = None
+    series_palette: list[str] | None = None
+    if has_per_series:
+        # Resolve series order so the strip row adjacent to the plot matches
+        # the chart's visual stack segment at that edge (adjacency invariant).
+        # The bar-vs-area distinction matters: Dataface emits
+        # ``order: {field, sort: ascending}`` on **bar** encodings only,
+        # which inverts VL's default and puts alpha-FIRST at the BOTTOM of
+        # a stacked bar (alpha-LAST at the TOP). Stacked **area** charts
+        # carry no such override, so VL's nominal default applies:
+        # alpha-FIRST at the TOP, alpha-LAST at the BOTTOM.
+        #
+        # Strip-row order is keyed off the actual rendered stack direction,
+        # not "is_stacked":
+        #   stacked bar       → reverse-alphabetical (top=alpha-LAST)
+        #   stacked area      → alphabetical (top=alpha-FIRST = VL default)
+        #   non-stacked, line → alphabetical (matches VL legend order)
+        #
+        # NOTE on position: this logic maintains the adjacency invariant
+        # regardless of position.  For position='bottom' the strip reads
+        # top-to-bottom in the same direction as the visual stack.  For
+        # position='top' the strip is above the plot: layer index 0 (the row
+        # adjacent to the plot top edge) carries alpha-LAST for a stacked
+        # bar, so reading the strip top-to-bottom produces alpha-FIRST →
+        # alpha-LAST — the reverse of the visual-stack direction.  Adjacency
+        # is preserved; top-to-bottom reading order is not (this is inherent
+        # to placing the strip above the chart).
+        if color_field and data:
+            distinct: set[str] = set()
+            for row in data:
+                s = row.get(color_field)
+                if s is not None:
+                    distinct.add(str(s))
+            # Only stacked BAR carries Dataface's order:ascending override.
+            # Grouped-by-default and explicit-false bars use alphabetical order.
+            # Stacked area and other chart types use VL's nominal default.
+            is_stacked_bar = (
+                resolved_chart.chart_type == "bar"
+                and resolved_chart.stack is not False
+                and not is_grouped_bar(resolved_chart)
+            )
+            if is_stacked_bar:
+                series_order = sorted(distinct, reverse=True)
+            else:
+                series_order = sorted(distinct)
+            palette = list(resolved_chart_style.palette)
+            # VL assigns palette[i] to the i-th series in alphabetical color
+            # domain. Map each entry in series_order to the palette index of
+            # its alphabetical position so reverse-alphabetical strips still
+            # render each series in its actual chart color.
+            alpha_index = {s: i for i, s in enumerate(sorted(series_order))}
+            series_palette = [
+                palette[alpha_index[s] % len(palette)] for s in series_order
+            ]
+    series_count = len(series_order) if series_order else 0
+    period_filter = (
+        _label_period_filter_expr(
+            spec, resolved_chart_style, data, resolved_chart.x, chart_type
+        )
+        if resolved_chart.x
+        else None
+    )
+    # When a period_filter is active it already restricts strip cells to
+    # label-period openers (e.g. one per month on a daily-data chart).
+    # Applying sampling on top would further thin the strip — e.g. daily
+    # data with 365 rows gives sampling_step=10, then the period filter
+    # keeps 12 monthly openers, and sampling reduces that to ~2 cells.
+    # The period filter is the correct thinning mechanism; suppress sampling.
+    if period_filter is not None:
+        sampling_step = 1
+    resolved_orient = _resolve_orient_auto(
+        resolved_chart_style.axis_y.orient, resolved_chart, resolved_chart_style
+    )
+    if resolved_orient not in ("left", "right"):
+        raise ValueError(
+            f"axis_y.orient resolved to unexpected value {resolved_orient!r}; "
+            "expected 'left' or 'right'"
+        )
+    axis_y_orient = cast(Literal["left", "right"], resolved_orient)
+    spec = attach_data_table(
+        spec,
+        data_table=data_table,
+        style=dt_style,
+        charts_style=resolved_chart_style,
+        sampling_step=sampling_step,
+        entry_dx=entry_dx,
+        series_order=series_order,
+        series_palette=series_palette,
+        label_period_filter_expr=period_filter,
+        axis_y_orient=axis_y_orient,
+        formats=resolved_chart_style.formats,
+    )
+    strip_h = data_table_strip_height(
+        data_table, dt_style, resolved_chart_style, series_count=series_count
+    )
+    if strip_h > 0:
+        if dt_style.position == "top":
+            if padding is not None:
+                padding = {
+                    **padding,
+                    "top": float(padding.get("top", 0)) + strip_h,
+                }
+            else:
+                bump_padding_top(spec, strip_h)
+        else:
+            if padding is not None:
+                padding = {
+                    **padding,
+                    "bottom": float(padding.get("bottom", 0)) + strip_h,
+                }
+            else:
+                bump_padding_bottom(spec, strip_h)
+    return spec, padding
+
+
+def render_standard_vega_spec(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    height: float | None = None,
+    theme: str | None = None,
+    custom_registry: CustomChartTypeRegistry | None = None,
+    datasets: dict[str, list[dict[str, Any]]] | None = None,
+    padding: dict[str, Any] | None = None,
+    resolved_style: MergedStyle | None = None,
+    face_level: int = 1,
+    effective_vega_config: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Render a resolved chart to a Vega-Lite spec.
+
+    Custom chart types registered in ``custom_registry`` are resolved to
+    their underlying Vega-Lite mark and rendered through the standard
+    cartesian path.
+
+    ``resolved_style`` carries the face's resolved background so the chart's
+    halo / knockout / spec-root background match the face's actual paper
+    colour, not whatever the theme name lookup would produce.
+
+    ``face_level`` is the heading level of the parent face (root=1, nested=2, …).
+    Chart title uses face_level + 1.
+    """
+    data = normalize_data_types(data)
+    if resolved_chart.x:
+        pre, x = data, resolved_chart.x
+        data = normalize_labeled_temporal(data, x)
+        if data is not pre:
+            # normalize_labeled_temporal rewrote labeled strings to ISO; sort by ISO
+            # so chronological order holds regardless of warehouse row order.
+            data = sorted(data, key=lambda r: (r.get(x) is None, r.get(x)))
+    validate_preaggregated_data(resolved_chart, data)
+    chart_type = resolved_chart.chart_type
+    resolved_chart_style = resolved_chart.resolved_style
+    face_background_overlay = (
+        resolved_style.background if resolved_style is not None else None
+    )
+
+    if chart_type == "histogram":
+        mapped = map_to_vega_lite(resolved_chart, data, width, theme)
+        return _finalize(
+            _generate_histogram_spec(mapped, resolved_chart, data, width, height),
+            resolved_chart,
+            theme,
+            resolved_chart_style,
+            width=width,
+            padding=padding,
+            face_background_overlay=face_background_overlay,
+            face_level=face_level,
+            effective_vega_config=effective_vega_config,
+        )
+    if chart_type == "boxplot":
+        mapped = map_to_vega_lite(resolved_chart, data, width, theme)
+        return _finalize(
+            _generate_boxplot_spec(mapped, resolved_chart, data, width, height),
+            resolved_chart,
+            theme,
+            resolved_chart_style,
+            width=width,
+            padding=padding,
+            face_background_overlay=face_background_overlay,
+            face_level=face_level,
+            effective_vega_config=effective_vega_config,
+        )
+    if chart_type in ("errorbar", "errorband"):
+        mapped = map_to_vega_lite(resolved_chart, data, width, theme)
+        return _finalize(
+            _generate_error_spec(mapped, resolved_chart, data, width, height),
+            resolved_chart,
+            theme,
+            resolved_chart_style,
+            width=width,
+            padding=padding,
+            face_background_overlay=face_background_overlay,
+            face_level=face_level,
+            effective_vega_config=effective_vega_config,
+        )
+    if chart_type in ("arc", "pie"):
+        mapped = map_to_vega_lite(resolved_chart, data, width, theme)
+        return _finalize(
+            _generate_arc_spec(mapped, resolved_chart, data, width, height),
+            resolved_chart,
+            theme,
+            resolved_chart_style,
+            width=width,
+            padding=padding,
+            face_background_overlay=face_background_overlay,
+            face_level=face_level,
+            effective_vega_config=effective_vega_config,
+        )
+    if chart_type in ("rect", "square", "heatmap"):
+        mapped = map_to_vega_lite(resolved_chart, data, width, theme)
+        return _finalize(
+            _generate_rect_spec(mapped, resolved_chart, data, width, height),
+            resolved_chart,
+            theme,
+            resolved_chart_style,
+            width=width,
+            padding=padding,
+            face_background_overlay=face_background_overlay,
+            face_level=face_level,
+            effective_vega_config=effective_vega_config,
+        )
+    if chart_type in ("map", "geoshape"):
+        if resolved_style is None:
+            raise ValueError(
+                f"render_standard_vega_spec requires resolved_style for chart type '{chart_type}'. "
+                "Thread the face's MergedStyle from the render pipeline."
+            )
+        return _finalize(
+            _generate_map_spec(
+                resolved_chart,
+                data,
+                chart_type,
+                width,
+                height,
+                board_style=resolved_style,
+            ),
+            resolved_chart,
+            theme,
+            resolved_chart_style,
+            width=width,
+            padding=padding,
+            face_background_overlay=face_background_overlay,
+            face_level=face_level,
+            effective_vega_config=effective_vega_config,
+        )
+    if chart_type in ("point_map", "bubble_map"):
+        if resolved_style is None:
+            raise ValueError(
+                f"render_standard_vega_spec requires resolved_style for chart type '{chart_type}'. "
+                "Thread the face's MergedStyle from the render pipeline."
+            )
+        return _finalize(
+            _generate_point_map_spec(
+                resolved_chart,
+                data,
+                chart_type,
+                width,
+                height,
+                board_style=resolved_style,
+            ),
+            resolved_chart,
+            theme,
+            resolved_chart_style,
+            width=width,
+            padding=padding,
+            face_background_overlay=face_background_overlay,
+            face_level=face_level,
+            effective_vega_config=effective_vega_config,
+        )
+
+    if chart_type == "layered" or isinstance(resolved_chart.y, list):
+        spec = build_layered_series_spec(
+            resolved_chart, data, width, height, theme, datasets=datasets
+        )
+        spec, padding = _maybe_attach_data_table(
+            spec, resolved_chart, data, resolved_chart_style, padding, chart_type
+        )
+        return _finalize(
+            spec,
+            resolved_chart,
+            theme,
+            resolved_chart_style,
+            width=width,
+            padding=padding,
+            face_background_overlay=face_background_overlay,
+            face_level=face_level,
+            effective_vega_config=effective_vega_config,
+        )
+
+    if chart_type not in CHART_TYPE_MAP and not (
+        custom_registry and custom_registry.get(chart_type)
+    ):
+        from dataface.core.errors import DF_RENDER_UNKNOWN_CHART_TYPE
+
+        raise UnknownChartType.from_code(
+            DF_RENDER_UNKNOWN_CHART_TYPE,
+            chart_type=chart_type,
+            available=", ".join(sorted(CHART_TYPE_MAP.keys())),
+        )
+
+    # ── Standard single-metric path: profile mapping → mechanical emit ──
+    background = _resolve_effective_background(
+        resolved_chart_style, theme, face_background_overlay=face_background_overlay
+    )
+    mapped = map_to_vega_lite(
+        resolved_chart,
+        data,
+        width,
+        theme,
+        custom_registry=custom_registry,
+        background=background,
+    )
+
+    if mapped.layers:
+        spec = _generate_layered_spec(mapped, resolved_chart, data, width, height)
+        spec, padding = _maybe_attach_data_table(
+            spec, resolved_chart, data, resolved_chart_style, padding, chart_type
+        )
+        return _finalize(
+            spec,
+            resolved_chart,
+            theme,
+            resolved_chart_style,
+            width=width,
+            padding=padding,
+            data=data,
+            face_background_overlay=face_background_overlay,
+            face_level=face_level,
+            effective_vega_config=effective_vega_config,
+        )
+
+    # Use gap-filled data when the profile synthesized missing time-bucket rows.
+    spec_data = mapped.data_override if mapped.data_override is not None else data
+    render_height = height
+    # Only grow within a layout-allocated slot. Omitting height keeps Vega
+    # autosize and preserves the data_table contract (explicit height required).
+    if (
+        chart_type == "bar"
+        and resolved_chart.orientation == "horizontal"
+        and spec_data
+        and height is not None
+        and height > 0
+    ):
+        n_categories = count_horizontal_bar_categories(resolved_chart.x, spec_data)
+        min_h = min_height_for_horizontal_bar_categories(
+            n_categories, resolved_chart_style
+        )
+        if min_h > 0:
+            render_height = max(height, min_h)
+    spec = build_base_spec(spec_data, width, render_height)
+    spec["mark"] = mapped.mark
+    spec["encoding"] = dict(mapped.encoding)
+    if mapped.transform:
+        spec["transform"] = [dict(t) for t in mapped.transform]
+    set_chart_title(
+        spec,
+        resolved_chart.title,
+        resolved_chart.subtitle,
+        style=resolved_chart_style,
+    )
+
+    spec, padding = _maybe_attach_data_table(
+        spec, resolved_chart, spec_data, resolved_chart_style, padding, chart_type
+    )
+    return _finalize(
+        spec,
+        resolved_chart,
+        theme,
+        resolved_chart_style,
+        width=width,
+        padding=padding,
+        data=spec_data,
+        face_background_overlay=face_background_overlay,
+        face_level=face_level,
+        effective_vega_config=effective_vega_config,
+    )