dataface 0.1.2__py3-none-any.whl

dataface/core/render/chart/profile.py

@@ -0,0 +1,3438 @@
+"""Chart profile mapping: Dataface canonical → Vega-Lite-native concepts.
+
+This module is the single home for all Dataface/Vega-Lite divergence:
+- chart type renames (scatter→point, pie→arc, etc.)
+- channel encoding construction from resolved Dataface fields
+- structural transforms (horizontal bar orientation swap)
+- sort mapping to Vega-Lite sort properties
+- bar axis categorical defaults
+- per-family encoding mapping (histogram bin, boxplot composite, arc theta, etc.)
+
+Every Vega-Lite-native chart type is either:
+- **profiled**: enters through ``map_to_vega_lite`` which returns a ``MappedChart``
+- **exception**: geo/kpi families that bypass profile with documented reasons
+
+The standard_renderer consumes the MappedChart output and performs
+mechanical Vega-Lite spec assembly without further profile logic.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field, replace
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any, Literal
+
+from dataface.core.compile.channel import ResolvedStyleChannel, parse_style_channel
+from dataface.core.compile.chart_resolved import (
+    ResolvedChart,
+    effective_color_field,
+    is_grouped_bar,
+)
+from dataface.core.compile.models.chart.authored import ConditionalRule
+from dataface.core.compile.models.style.compiled import AxisStylePatch
+from dataface.core.compile.models.style.merged import MergedChartsStyle, resolve_mark
+from dataface.core.compile.palette import resolve_dark_companion_stops
+from dataface.core.compile.style_cascade import (
+    _chart_type_axis_patch,
+    resolved_axis_style,
+)
+from dataface.core.render.chart.tick_values import (
+    nice_tick_values,
+    stacked_bar_totals_max,
+)
+from dataface.core.render.chart.time_unit_detect import (
+    BUCKETED_CALENDAR_UNITS,
+    complete_ordinal_time_series,
+    default_label_expr_for,
+    detect_time_unit,
+    ordinal_axis_values,
+    resolve_label_time_unit,
+    vl_time_unit,
+)
+from dataface.core.render.chart.type_inference import infer_vega_type_from_data
+from dataface.core.render.chart.vl_field_maps import map_fields
+from dataface.core.render.errors import ChartDataError, UnknownChartType
+from dataface.core.render.format_utils import resolve_format
+from dataface.core.render.text.case import format_display_text
+
+if TYPE_CHECKING:
+    from dataface.core.compile.custom_chart_types import CustomChartTypeRegistry
+
+# Default band-scale padding for grouped bar charts (xOffset/yOffset mode).
+# Theme YAML has no grouped-vs-single granularity, so these live here.
+# paddingInner: gap between groups; paddingOuter: margin at both plot edges.
+_GROUPED_BAR_PADDING_INNER: float = 0.2
+_GROUPED_BAR_PADDING_OUTER: float = 0.2
+
+
+# Invisible per-datum point overlay added to line/area charts so the JS hover
+# layer resolves to individual data points instead of the single line/area path.
+# size=300 ≈ 9.7 px hit radius (VL size = area in sq px; sqrt(300/π) ≈ 9.77 px).
+# Returns a fresh dict each call — callers must not share the same mark dict
+# across layers (mutations in downstream spec assembly would corrupt all callers).
+def _hover_overlay_point() -> dict[str, Any]:
+    return {
+        "type": "point",
+        "filled": True,
+        "size": 300,
+        "opacity": 0,
+        "tooltip": True,
+    }
+
+
+_OP_MAP: dict[str, str] = {
+    "eq": "==",
+    "ne": "!=",
+    "lt": "<",
+    "lte": "<=",
+    "gt": ">",
+    "gte": ">=",
+}
+
+# Detect any d3-time-format directive (% optionally followed by a padding
+# modifier and a letter). %% is a literal-percent escape and is stripped first
+# so "%%Y" is treated as the four characters %%Y, not a directive.
+# d3-time-format supports padding modifiers between % and the directive letter:
+#   - "-" suppresses padding   (e.g. %-d → "9" not "09")
+#   - "_" pads with spaces      (e.g. %_d → " 9")
+#   - "0" pads with zeros       (e.g. %0H, the default)
+# Common real-world formats like "%-m/%-d/%-Y" contain no bare %<letter>, so
+# the regex must accept an optional padding modifier.
+_TIME_FORMAT_RE = re.compile(r"%[-_0]?[A-Za-z]")
+
+
+def _utc_time_label_expr(fmt: str) -> str:
+    """Build a Vega ``labelExpr`` that formats a date-string axis tick under UTC.
+
+    Axis-and-scale-agnostic: ``toDate(datum.value)`` parses ISO date strings
+    (ordinal domain) or accepts Date instances unchanged (temporal/quantitative
+    domain); ``utcFormat`` then emits the requested d3-time-format string in
+    UTC, so the spec renders identically under any runtime TZ.
+
+    Replaces both legacy paths that routed time-format strings through
+    ``formatType: "time"`` (d3-time-format under runtime-local TZ) — the
+    ordinal-temporal-inferred axis-x branch and the non-temporal y/x fallback.
+    """
+    fmt_escaped = fmt.replace("\\", "\\\\").replace("'", "\\'")
+    return f"utcFormat(toDate(datum.value), '{fmt_escaped}')"
+
+
+def _is_time_format(fmt: str) -> bool:
+    """Return True when fmt contains a d3-time-format directive (``%<letter>``).
+
+    Ordinal axes in Vega use d3-format (number formatting). When a time-format
+    string like ``"%b %Y"`` is applied to an ordinal axis, d3-format rejects it,
+    causing a Vega scene-graph failure. Callers use this to route the format
+    through ``_utc_time_label_expr`` instead.
+
+    ``%%`` is a literal-percent escape and is stripped before the search so
+    ``"%%Y"`` (the literal four-character sequence) does not trigger detection.
+    """
+    return bool(_TIME_FORMAT_RE.search(fmt.replace("%%", "")))
+
+
+def _rule_to_vl_test(rule: Any, field_ref: str) -> str:
+    """Build a Vega-Lite ``condition.test`` expression for one rule.
+
+    Binary ops map to ``_OP_MAP``. Extended predicates expand:
+      - ``between [a, b]``  → ``(field >= a) && (field <= b)``
+      - ``in [v1, v2, ...]``→ ``indexof([...], field) >= 0``
+      - ``is_null: true``   → ``field == null``
+      - ``is_null: false``  → ``field != null``
+      - ``default: true``   → ``true`` (always matches)
+    """
+    if rule.default is True:
+        return "true"
+    if rule.is_null is True:
+        return f"{field_ref} == null"
+    if rule.is_null is False:
+        return f"{field_ref} != null"
+    if rule.between is not None:
+        low, high = rule.between
+        return (
+            f"({field_ref} >= {json.dumps(low)}) && ({field_ref} <= {json.dumps(high)})"
+        )
+    if rule.in_ is not None:
+        return f"indexof({json.dumps(list(rule.in_))}, {field_ref}) >= 0"
+    pred_field, pred_val = rule.active_predicate()
+    return f"{field_ref} {_OP_MAP[pred_field]} {json.dumps(pred_val)}"
+
+
+# ── Chart type mapping ────────────────────────────────────────────────
+# Maps Dataface chart type names to Vega-Lite mark types.
+# Identity entries included for completeness — every supported type
+# should be listed so lookup never falls through silently.
+
+CHART_TYPE_MAP: dict[str, str] = {
+    "bar": "bar",
+    "line": "line",
+    "area": "area",
+    "circle": "circle",
+    "square": "square",
+    "text": "text",
+    "tick": "tick",
+    "rule": "rule",
+    "trail": "trail",
+    "rect": "rect",
+    "arc": "arc",
+    "boxplot": "boxplot",
+    "errorbar": "errorbar",
+    "errorband": "errorband",
+    "geoshape": "geoshape",
+    "image": "image",
+    "map": "geoshape",
+    "point_map": "circle",
+    "bubble_map": "circle",
+    "scatter": "point",
+    "heatmap": "rect",
+    "pie": "arc",
+    "histogram": "bar",
+    "kpi": "text",
+}
+
+# Data-series layer types that receive datum-color injection in layered charts.
+# Annotation/overlay marks (text, rule, tick, image) are excluded so they don't
+# appear as spurious legend entries.
+_DATA_SERIES_LAYER_TYPES: frozenset[str] = frozenset(
+    {"bar", "line", "area", "circle", "square", "scatter", "trail", "rect"}
+)
+
+# ── Profile routing classification ───────────────────────────────────
+# Every type in CHART_TYPE_MAP is classified into exactly one set.
+#
+# PROFILED types enter through map_to_vega_lite() which returns a
+# MappedChart with mark + encoding. The standard_renderer assembles
+# the final spec mechanically from the MappedChart.
+#
+# EXCEPTION types bypass profile for documented reasons:
+# - geo (map/geoshape/point_map/bubble_map): Dataface adds
+#   product value beyond Vega-Lite (built-in geo sources, data joins,
+#   projection defaults). The renderer needs geo-specific data plumbing
+#   that the cartesian profile seam cannot express.
+# - kpi: Non-Vega-Lite renderer. Produces a text mark with formatted
+#   single-number display logic that has no mapping analog.
+
+PROFILED_CHART_FAMILIES: frozenset[str] = frozenset(
+    {
+        # Standard cartesian single-series
+        "bar",
+        "line",
+        "area",
+        "circle",
+        "square",
+        "text",
+        "tick",
+        "rule",
+        "trail",
+        "image",
+        "scatter",
+        # Composite / statistical marks
+        "histogram",
+        "boxplot",
+        "errorbar",
+        "errorband",
+        # Non-cartesian marks
+        "arc",
+        "pie",
+        # Grid / matrix marks
+        "rect",
+        "heatmap",
+    }
+)
+
+EXCEPTION_CHART_FAMILIES: frozenset[str] = frozenset(
+    {
+        # Geo: built-in geo sources, data joins, projection defaults
+        "map",
+        "geoshape",
+        "point_map",
+        "bubble_map",
+        # KPI: non-Vega-Lite single-number renderer
+        "kpi",
+    }
+)
+
+
+@dataclass(frozen=True)
+class MappedLayer:
+    """A single layer in a profiled layered chart."""
+
+    mark: dict[str, Any]
+    encoding: dict[str, Any] = field(default_factory=dict)
+    data_name: str | None = None
+    transform: tuple[dict[str, Any], ...] = ()
+    # Inline data override for layers that must NOT inherit the spec's
+    # ``data.values``. Used by the zero/top-rule layers to emit one rule
+    # mark instead of one per parent data row.
+    data: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class MappedChart:
+    """Vega-Lite-native chart after profile mapping from Dataface canonical form.
+
+    Single-series charts use ``mark`` + ``encoding``.
+    Layered charts keep shared top-level ``encoding`` and a concrete ``layers`` list.
+
+    When layers use per-layer queries, ``datasets`` maps query names to their
+    row data.  The spec generator emits VL ``"datasets"`` and per-layer
+    ``"data": {"name": ...}`` references.
+
+    ``data_override`` lets a profile add synthetic columns onto the top-level
+    inline data (e.g. donut labels pre-render Jinja templates per row). The
+    spec generator substitutes this for the original data at the top-level
+    ``data.values`` key.
+    """
+
+    mark: dict[str, Any] | None = None
+    encoding: dict[str, Any] = field(default_factory=dict)
+    layers: tuple[MappedLayer, ...] = ()
+    datasets: dict[str, list[dict[str, Any]]] | None = None
+    data_override: list[dict[str, Any]] | None = None
+    transform: tuple[dict[str, Any], ...] = ()
+    # Resolve clauses derived from typed surface (e.g. per-layer axis_y.orient
+    # auto-promotes the chart to independent y scales).
+    derived_resolve: dict[str, Any] | None = None
+
+
+# ── Zero-baseline rule mark ──────────────────────────────────────────
+# Vega renders axis guides (grid lines) BELOW marks, so area/bar fills cover
+# the bold zero baseline produced by the conditional ``gridColor`` encoding.
+# A rule mark layer at the top of the layer stack renders above all fills.
+# Scoped to bar (vertical + horizontal), area, and line charts; skipped when
+# 0 isn't in the measure-axis domain or when that axis's grid is hidden.
+
+
+def _domain_includes_zero(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    field: str,
+    axis_name: str,
+) -> bool:
+    """True when 0 falls within the effective scale domain on ``axis_name``.
+
+    Precedence: explicit per-axis ``axis.scale.domain`` → chart-level
+    ``scale.domain`` → ``resolved_chart.zero`` (inferred or authored chart-level
+    zero override, written to the VL y-encoding by ``map_y_encoding``) →
+    per-axis / chart-level ``scale.zero`` from the style cascade → data range
+    fallback.
+
+    ``resolved_chart.zero`` must be checked before the style cascade because the
+    pipeline infers ``zero=False`` for all-positive-data line/area charts (the
+    inference writes it to the VL y-encoding as ``scale.zero: false``). The style
+    cascade holds the *theme* scale zero, which is almost always None; a plain
+    ``None is not False`` guard would therefore misidentify inferred-False as
+    "unset" and fire the zero rule even when the rendering scale excludes 0.
+    """
+    rs = resolved_chart.resolved_style
+    # Walk the cascade to get the per-axis scale (chart-local axis_y.scale wins
+    # over theme axis_y.scale via resolved_axis_style).
+    merged_axis = resolved_axis_style(rs, axis_name, "quantitative")  # type: ignore[arg-type]
+    per_axis_scale = merged_axis.scale
+    chart_level_scale = rs.scale
+    # 1. Explicit per-axis or chart-level scale.domain
+    for scale in (per_axis_scale, chart_level_scale):
+        domain = getattr(scale, "domain", None) if scale is not None else None
+        if isinstance(domain, list) and len(domain) == 2:
+            lo, hi = domain
+            if isinstance(lo, (int, float)) and isinstance(hi, (int, float)):
+                return lo <= 0 <= hi
+    # 2. Explicit scale.zero — resolved_chart.zero wins (written to the VL encoding
+    # by map_y_encoding), then per-axis style scale, then chart-level style scale.
+    zero_setting: bool | None = resolved_chart.zero
+    if zero_setting is None:
+        for scale in (per_axis_scale, chart_level_scale):
+            z = getattr(scale, "zero", None) if scale is not None else None
+            if z is not None:
+                zero_setting = z
+                break
+    # When scale.zero is unset, the rule layer's ``datum: 0`` enters the unified
+    # VL domain and pulls 0 in regardless of data dtype, so we don't need to scan
+    # rows. ``scale.zero=False`` is the only path that requires a per-row check.
+    if zero_setting is not False:
+        return True
+    # 3. scale.zero=False explicitly: emit the rule only when data straddles 0.
+    if not data:
+        return False
+    values: list[float] = []
+    for row in data:
+        v = row.get(field)
+        if isinstance(v, (int, float, Decimal)) and not isinstance(v, bool):
+            values.append(float(v))
+        elif isinstance(v, str):
+            try:
+                values.append(float(v))
+            except ValueError:
+                continue
+    if not values:
+        return False
+    return min(values) <= 0 <= max(values)
+
+
+_ZERO_RULE_CHART_TYPES: frozenset[str] = frozenset({"area", "bar", "layered", "line"})
+
+
+def _zero_rule_layer(
+    resolved_chart: ResolvedChart, data: list[dict[str, Any]]
+) -> MappedLayer | None:
+    """Build a zero-baseline rule layer for the chart, or ``None`` to skip.
+
+    Vertical bar / area / line charts emit a horizontal rule at y=0; horizontal
+    bars emit a vertical rule at x=0. Returns ``None`` when:
+    - chart type isn't in ``_ZERO_RULE_CHART_TYPES`` (bar, area, line), OR
+    - chart has no quantitative measure axis (``y`` is None / list), OR
+    - 0 is outside the effective measure-axis domain, OR
+    - the quantitative grid is hidden (theme or chart-local).
+    """
+    if resolved_chart.chart_type not in _ZERO_RULE_CHART_TYPES:
+        return None
+    measure_field = resolved_chart.y
+    if resolved_chart.chart_type == "layered" and not isinstance(measure_field, str):
+        measure_field = next(
+            (layer.y for layer in resolved_chart.layers if layer.y), None
+        )
+    if not isinstance(measure_field, str):
+        return None
+    if not _domain_includes_zero(
+        resolved_chart, data, field=measure_field, axis_name="axis_y"
+    ):
+        return None
+
+    is_horizontal = (
+        resolved_chart.chart_type == "bar"
+        and resolved_chart.orientation == "horizontal"
+    )
+    effective = resolved_chart.resolved_style
+    chart_type = resolved_chart.chart_type
+
+    # Quantitative-measure cascade: axis_x cascade = categorical axis, axis_y
+    # cascade = measure axis (VL y for vertical bar, VL x for horizontal bar).
+    # This cascade owns the rule's grid.zero.color / zero.width and the hidden
+    # gate. Chart-local patches are pre-merged into ``effective`` by
+    # build_resolved_style, so the axis cascade reads from a single resolved source.
+    measure = resolved_axis_style(
+        effective,
+        "axis_y",
+        "quantitative",
+        _chart_type_axis_patch(effective, chart_type, "axis_y"),
+    )
+    if not measure.grid.visible:
+        return None
+    grid = measure.grid
+    assert grid.zero is not None, "theme must supply axis.grid.zero"
+
+    # Tick / orient cascade for the rule's extension over rendered axis ticks.
+    # Vertical bar / area: same cascade as the measure (axis_y, quantitative).
+    # Horizontal bar: axis_x cascade (categorical axis = VL y for horizontal
+    # bar); the zero rule at x=0 extends over the categorical y-axis ticks.
+    tick_axis = (
+        resolved_axis_style(
+            effective,
+            "axis_x",
+            "nominal",
+            _chart_type_axis_patch(effective, chart_type, "axis_x"),
+        )
+        if is_horizontal
+        else measure
+    )
+    ticks = tick_axis.ticks
+    visible_tick_size = (
+        ticks.size
+        if ticks.visible and ticks.size is not None and ticks.size > 0
+        else None
+    )
+
+    mark: dict[str, Any] = {
+        "type": "rule",
+        "color": grid.zero.color,
+        "strokeWidth": grid.zero.width,
+        "opacity": 1,
+        "tooltip": False,
+    }
+
+    # Single-row data override: VL inherits the spec's ``data.values`` for
+    # layers that don't declare their own data, so a rule encoded with all
+    # constant channels still iterates once per parent row at identical
+    # pixel coords (4 categories → 4 stacked rules; 16 weeks → 16). One
+    # synthetic row halts the iteration without changing the geometry.
+    # The row must carry the measure field name with a finite value because
+    # VL appends a ``isValid(datum[measure]) && isFinite(+datum[measure])``
+    # filter derived from the inherited shared encoding — an empty row gets
+    # filtered out and the rule never reaches the SVG.
+    rule_data: dict[str, Any] = {"values": [{measure_field: 0}]}
+
+    if is_horizontal:
+        # Vertical rule at x=0 spanning y=0..height.  The x-axis renders ticks
+        # outward: below y=height (bottom) or above y=0 (top).
+        #
+        # Top-orient: encoding-level y is set to -tick_size (not mark.yOffset)
+        # because encoding.yOffset={value:0} (the grouped-bar neutralizer below)
+        # would override any mark.yOffset, silently dropping the extension.
+        # Bottom-orient: mark-level y2Offset extends the end past y=height.
+        # y2Offset is safe from neutralization: grouped horizontal bars emit a
+        # top-level yOffset encoding (for bar center shift) but never a y2Offset
+        # encoding, so the rule layer never inherits a conflicting y2Offset value.
+        # {expr: "height + N"} encoding is NOT an alternative — vl-convert renders
+        # it as 0 (expression evaluated in the wrong context).
+        y_start: int | float = 0
+        if visible_tick_size is not None:
+            if tick_axis.orient == "top":
+                y_start = -visible_tick_size  # shift encoding.y up to cover ticks
+            else:  # bottom (default)
+                mark["y2Offset"] = visible_tick_size  # extend below y=height
+            mark["clip"] = False
+        encoding_h: dict[str, Any] = {
+            "x": {"datum": 0, "type": "quantitative"},
+            # Span the full plot height as a vertical rule; explicit y/y2
+            # and color overrides prevent inheriting shared encoding.
+            "y": {"value": y_start},
+            "y2": {"value": "height"},
+            "color": {"value": grid.zero.color},
+            # Grouped horizontal bars emit a top-level yOffset encoding.
+            # The rule data has no offset field, so VegaLite would inherit
+            # an undefined offset, misplacing the rule. Neutralize it.
+            "yOffset": {"value": 0},
+        }
+        _neutralize_layer_channels(encoding_h, resolved_chart)
+        return MappedLayer(mark=mark, data=rule_data, encoding=encoding_h)
+
+    # Vertical bar / area: horizontal rule at y=0 spanning x=0..width.  The
+    # y-axis renders ticks outward: right of x=width (right-orient) or left of
+    # x=0 (left).
+    #
+    # Left-orient: encoding-level x is set to -tick_size (not mark.xOffset)
+    # because encoding.xOffset={value:0} (the grouped-bar neutralizer below)
+    # overrides any mark.xOffset, silently dropping the extension.
+    # Right-orient: mark-level x2Offset extends the end past x=width.
+    # x2Offset is safe from neutralization: grouped vertical bars emit a
+    # top-level xOffset encoding (for bar center shift) but never an x2Offset
+    # encoding, so the rule layer never inherits a conflicting x2Offset value.
+    # {expr: "width + N"} encoding is NOT an alternative — vl-convert renders
+    # it as 0 (expression evaluated in the wrong context).
+    x_start: int | float = 0
+    if visible_tick_size is not None:
+        y_orient = _resolve_orient_auto(tick_axis.orient, resolved_chart, effective)
+        if y_orient == "left":
+            x_start = -visible_tick_size  # shift encoding.x left to cover ticks
+        else:  # right (Dataface default)
+            mark["x2Offset"] = visible_tick_size  # extend right of x=width
+        mark["clip"] = False
+    encoding: dict[str, Any] = {
+        "y": {"datum": 0, "type": "quantitative"},
+        # Override every shared channel that would otherwise fragment the
+        # rule into per-datum / per-series rules: x→constant pixel, x2→full
+        # plot width, color→explicit value (else inherits series binding).
+        "x": {"value": x_start},
+        "x2": {"value": "width"},
+        "color": {"value": grid.zero.color},
+        # Grouped vertical bars emit a top-level xOffset encoding.
+        # The rule data has no offset field, so VegaLite would inherit
+        # an undefined offset, misplacing the rule. Neutralize it.
+        "xOffset": {"value": 0},
+    }
+    # Only neutralize channels when the chart actually emits them — otherwise
+    # the override leaks spurious attributes onto the rule for every chart on
+    # every theme, including ones with no dashes.
+    _neutralize_layer_channels(encoding, resolved_chart)
+    return MappedLayer(mark=mark, data=rule_data, encoding=encoding)
+
+
+def zero_rule_vl_layer(
+    resolved_chart: ResolvedChart, data: list[dict[str, Any]]
+) -> dict[str, Any] | None:
+    """Public-API form of the zero-baseline rule: a VL layer dict ready to drop
+    into ``spec["layer"]``.
+
+    Returns ``None`` when the rule should be skipped (chart type doesn't apply,
+    0 not in y-domain, grid hidden).  Used by the standard renderer to inject
+    the rule post-spec, so single-mark charts can keep their tooltip-at-spec-
+    encoding placement and only the structural change (mark → layer[0]) is
+    applied to the spec.
+    """
+    layer = _zero_rule_layer(resolved_chart, data)
+    if layer is None:
+        return None
+    out: dict[str, Any] = {"mark": dict(layer.mark), "encoding": dict(layer.encoding)}
+    if layer.data is not None:
+        out["data"] = dict(layer.data)
+    return out
+
+
+def _top_rule_layer(resolved_chart: ResolvedChart) -> MappedLayer | None:
+    """Build a 100%-baseline rule layer for normalize-stacked charts, or None.
+
+    Mirror of ``_zero_rule_layer`` for the y=1 (or x=1 on horizontal bar)
+    edge that every column reaches when ``stack: 'normalize'`` is in
+    effect. Same color/stroke contract as the zero rule — both anchor edges
+    of the normalized domain with the same visual emphasis.
+
+    Returns None when the chart isn't a normalize-stacked area or bar, or
+    when the cascade hides the quantitative grid.
+    """
+    if resolved_chart.chart_type not in _ZERO_RULE_CHART_TYPES:
+        return None
+    if resolved_chart.stack != "normalize":
+        return None
+    measure_field = resolved_chart.y
+    if not isinstance(measure_field, str):
+        return None
+
+    is_horizontal = (
+        resolved_chart.chart_type == "bar"
+        and resolved_chart.orientation == "horizontal"
+    )
+    effective = resolved_chart.resolved_style
+    chart_type = resolved_chart.chart_type
+
+    measure = resolved_axis_style(
+        effective,
+        "axis_y",
+        "quantitative",
+        _chart_type_axis_patch(effective, chart_type, "axis_y"),
+    )
+    if not measure.grid.visible:
+        return None
+    grid = measure.grid
+    assert grid.zero is not None, "theme must supply axis.grid.zero"
+
+    mark: dict[str, Any] = {
+        "type": "rule",
+        "color": grid.zero.color,
+        "strokeWidth": grid.zero.width,
+        "opacity": 1,
+        "tooltip": False,
+    }
+
+    # See _zero_rule_layer for the rationale on the measure-field synthetic row.
+    rule_data: dict[str, Any] = {"values": [{measure_field: 0}]}
+
+    if is_horizontal:
+        encoding_h: dict[str, Any] = {
+            "x": {"datum": 1, "type": "quantitative"},
+            "y": {"value": 0},
+            "y2": {"value": "height"},
+            "color": {"value": grid.zero.color},
+            "yOffset": {"value": 0},
+        }
+        _neutralize_layer_channels(encoding_h, resolved_chart)
+        return MappedLayer(mark=mark, data=rule_data, encoding=encoding_h)
+
+    # Vertical bar / area: horizontal rule at y=1 spanning x=0..width.
+    encoding_v: dict[str, Any] = {
+        "y": {"datum": 1, "type": "quantitative"},
+        "x": {"value": 0},
+        "x2": {"value": "width"},
+        "color": {"value": grid.zero.color},
+        "xOffset": {"value": 0},
+    }
+    _neutralize_layer_channels(encoding_v, resolved_chart)
+    return MappedLayer(mark=mark, data=rule_data, encoding=encoding_v)
+
+
+def top_rule_vl_layer(
+    resolved_chart: ResolvedChart, data: list[dict[str, Any]]
+) -> dict[str, Any] | None:
+    """Public-API form of the 100%-baseline rule. Mirror of
+    ``zero_rule_vl_layer`` for the normalize-stack ceiling.
+    """
+    layer = _top_rule_layer(resolved_chart)
+    if layer is None:
+        return None
+    out: dict[str, Any] = {"mark": dict(layer.mark), "encoding": dict(layer.encoding)}
+    if layer.data is not None:
+        out["data"] = dict(layer.data)
+    return out
+
+
+# ── Mark mapping ──────────────────────────────────────────────────────
+
+# Chart types whose default mark color comes from ``palette[0]`` as a fill
+# (vs. stroke for line). Arc/pie are intentionally excluded — VL gives
+# mark.fill precedence over encoding.color for arc marks, so palette[0]
+# would freeze every slice to the same colour; per-slice colours flow
+# through encoding.color → ``config.range.category`` instead.
+_PALETTE_FILL_CHART_TYPES: tuple[str, ...] = (
+    "bar",
+    "area",
+    "scatter",
+    "circle",
+    "point",
+)
+_PALETTE_STROKE_CHART_TYPES: tuple[str, ...] = ("line",)
+
+
+def _build_mark_style(
+    chart_type: str,
+    effective: Any,
+    orientation: Literal["vertical", "horizontal"],
+    has_color_encoding: bool,
+) -> dict[str, Any]:
+    """Build the mark-style dict from the resolved (chart-local-merged) chart-family style.
+
+    Chart-local mark patches (``style.bar`` / ``style.line`` / ``style.area`` /
+    ``style.scatter`` / ``style.arc``) are pre-merged into ``effective.bar`` /
+    ``effective.line`` / ``effective.area`` / ``effective.scatter`` / ``effective.arc``
+    by build_resolved_style — so this function reads from a single, fully-resolved
+    chart-family style.
+
+    ``orientation`` is forwarded to ``bar_mark_to_vl`` so the band-width
+    fraction lands on the correct dimension: ``mark.width`` for vertical bars,
+    ``mark.height`` for horizontal bars.
+
+    ``has_color_encoding`` is True whenever the chart has a color channel
+    bound to data (any mode — series, gradient, conditional, literal). In
+    that case the palette[0] mark-level fill/stroke default is suppressed
+    so VL's color scale (or literal/conditional encoding) wins. Required,
+    not defaulted — a default of ``False`` would silently re-shadow the
+    encoded color scale for any future caller that forgets the flag.
+    """
+    from dataface.core.render.chart.vl_field_maps import (
+        area_mark_to_vl,
+        bar_mark_to_vl,
+        line_mark_to_vl,
+        scatter_mark_to_vl,
+        slice_mark_to_vl,
+    )
+
+    d: dict[str, Any] = {}
+
+    if effective is not None:
+        # Palette[0] default color for single-series charts only. When a
+        # color encoding is present (multi-series), the encoded color scale
+        # owns mark colour; emitting ``mark.fill = palette[0]`` here would
+        # freeze every mark to the same colour despite the scale.
+        # arc/pie intentionally never get the palette[0] mark fill: VL
+        # gives mark.fill precedence over encoding.color for arc marks
+        # (the opposite of bar/line/area), so per-slice colours flow
+        # through encoding.color → ``config.range.category`` instead.
+        palette0 = effective.palette[0] if effective.palette else None
+        # style.color (string) overrides palette[0]; if neither is set, no fill.
+        color0 = effective.color if effective.color is not None else palette0
+        if color0 is not None and not has_color_encoding:
+            if chart_type in _PALETTE_FILL_CHART_TYPES:
+                d["fill"] = color0
+            elif chart_type in _PALETTE_STROKE_CHART_TYPES:
+                d["stroke"] = color0
+
+        if chart_type == "bar":
+            bar_mark = resolve_mark(effective.marks.bar, effective.bar.marks.bar)
+            d.update(bar_mark_to_vl(bar_mark, orientation))
+        elif chart_type == "histogram":
+            bar_mark = resolve_mark(effective.marks.bar, effective.histogram.marks.bar)
+            d.update(bar_mark_to_vl(bar_mark, orientation))
+        elif chart_type == "line":
+            line_marks = effective.line.marks
+            line_mark = resolve_mark(effective.marks.line, line_marks.line)
+            point_mark = resolve_mark(effective.marks.point, line_marks.point)
+            d.update(line_mark_to_vl(line_mark, point_mark))
+        elif chart_type == "area":
+            area_mark = resolve_mark(effective.marks.area, effective.area.marks.area)
+            d.update(area_mark_to_vl(area_mark))
+        elif chart_type in ("scatter", "circle", "point"):
+            point_mark = resolve_mark(
+                effective.marks.point, effective.scatter.marks.point
+            )
+            d.update(scatter_mark_to_vl(point_mark))
+        elif chart_type in ("arc", "pie"):
+            pie_marks = effective.pie.marks
+            slice_mark = resolve_mark(effective.marks.slice, pie_marks.slice)
+            d.update(slice_mark_to_vl(slice_mark))
+
+    return d
+
+
+def _map_mark(
+    resolved_chart: ResolvedChart,
+    custom_registry: CustomChartTypeRegistry | None = None,
+) -> dict[str, Any]:
+    """Map Dataface chart type to a Vega-Lite mark dict."""
+    chart_type = resolved_chart.chart_type
+    vl_type = CHART_TYPE_MAP.get(chart_type)
+    custom_defn = None
+
+    if vl_type is None and custom_registry:
+        custom_defn = custom_registry.get(chart_type)
+        if custom_defn:
+            vl_type = custom_defn.mark
+
+    if vl_type is None:
+        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())),
+        )
+
+    mark: dict[str, Any] = {"type": vl_type, "tooltip": True}
+    if custom_defn and custom_defn.mark_properties:
+        mark.update(custom_defn.mark_properties)
+
+    # When a color encoding drives per-mark colour (any mode — series,
+    # gradient, conditional, literal), the palette[0] default fill/stroke
+    # must NOT shadow it.
+    color_ch = resolved_chart.resolved_channels.get("color")
+    has_color_encoding = color_ch is not None
+    mark.update(
+        _build_mark_style(
+            chart_type,
+            resolved_chart.resolved_style,
+            resolved_chart.orientation,
+            has_color_encoding,
+        )
+    )
+
+    return mark
+
+
+# ── Helpers ───────────────────────────────────────────────────────────
+
+
+def _resolve_orient_auto(
+    orient: str | None,
+    resolved_chart: ResolvedChart,
+    resolved_style: MergedChartsStyle,
+) -> str | None:
+    """Resolve the 'auto' orient sentinel to a concrete VL value at emit time.
+
+    'auto' → 'left' when the endpoint-label pane will actually fire
+    (the right-edge hconcat pane would collide with a right-side y-axis).
+    'auto' → 'right' otherwise (Dataface convention; VL default is left).
+    Non-'auto' values pass through unchanged.
+
+    Firing condition is delegated to
+    ``standard_renderer.endpoint_label_pane_will_fire`` so this resolver
+    and the pane-emit code stay in sync. Mirroring the full predicate
+    means single-series charts that author ``endpoint_labels.visible:
+    true`` keep ``axis_y`` on the right — the pane never renders on
+    those, so there's nothing to collide with.
+
+    Horizontal stacked bars *do* fire the predicate (the top-row rail
+    is wrapped in vconcat, not hconcat) so this resolver returns
+    ``"left"`` for that case. ``map_y_encoding`` strips the ``"auto"``
+    sentinel from the VL x-axis after routing, so horizontal bars never
+    end up with a mis-oriented axis from this code path.
+    """
+    if orient != "auto":
+        return orient
+    # Local import to avoid a render-layer import cycle: profile.py is
+    # imported by standard_renderer.py earlier in module init.
+    from dataface.core.render.chart.standard_renderer import (
+        endpoint_label_pane_will_fire,
+    )
+
+    return (
+        "left"
+        if endpoint_label_pane_will_fire(resolved_chart, resolved_style)
+        else "right"
+    )
+
+
+def _inject_label_case(axis_dict: dict[str, Any], label_case: str | None) -> None:
+    """Apply font.case as a Vega labelExpr on a VL axis dict.
+
+    'upper'/'lower' wrap the existing labelExpr if present (so smart cadence
+    expressions stack correctly), else inject upper/lower of datum.label.
+    'title'/'sentence' are not applicable to data-bound tick labels — they
+    require pre-transforming the query-result domain values, which are not
+    available at spec-construction time. 'preserve'/None no-ops.
+    Mutates axis_dict in place.
+    """
+    if label_case not in ("upper", "lower"):
+        return
+    vl_fn = "upper" if label_case == "upper" else "lower"
+    existing = axis_dict.get("labelExpr")
+    axis_dict["labelExpr"] = (
+        f"{vl_fn}({existing})" if existing else f"{vl_fn}(datum.label)"
+    )
+
+
+def _build_encoding_axis(
+    effective: MergedChartsStyle,
+    axis_name: Literal["axis_x", "axis_y"],
+    channel_type: str,
+    chart_type_axis_patch: AxisStylePatch | None = None,
+    skip_case_inject: bool = False,
+) -> dict[str, Any]:
+    """Build encoding.{x,y}.axis dict from the merged axis cascade.
+
+    Chart-local axis patches are pre-merged into ``effective.axis_x`` /
+    ``effective.axis_y`` / ``effective.axis_quantitative`` / ``effective.axis_band``
+    by build_resolved_style — so the renderer reads from a single, fully-resolved
+    source. ``resolved_axis_style`` handles the channel-type dispatch
+    (axis_quantitative for quantitative, axis_band for ordinal/nominal) and
+    Layer 3.5 chart-type-specific overlay; the result is mapped to VL via
+    ``axis_to_vl``. The zero baseline is drawn by the dedicated zero-rule layer
+    (``_zero_rule_layer``) on top of the chart fills — so the grid does not
+    encode a zero highlight here.
+
+    Case transforms on axis tick labels:
+    - 'upper'/'lower': injected here via _inject_label_case for all call sites
+      except map_x_encoding (skip_case_inject=True), where the smart cadence
+      labelExpr block runs *after* _build_encoding_axis and must be wrapped.
+      map_x_encoding calls _inject_label_case itself at its tail.
+    - 'title'/'sentence': NOT applied to data-bound tick labels. These require
+      pre-transforming the actual domain values (strings from query results)
+      which are not available at spec-construction time. They apply only to
+      static text fields (chart title, axis title, KPI label, table header).
+      A 'preserve' label case (the default) emits no labelExpr.
+    """
+    from dataface.core.render.chart.vl_field_maps import axis_to_vl
+
+    merged = resolved_axis_style(
+        effective, axis_name, channel_type, chart_type_axis_patch
+    )
+    result = {k: v for k, v in axis_to_vl(merged).items() if v is not None}
+    if "format" in result:
+        result["format"] = resolve_format(result["format"], effective.formats)
+
+    if not skip_case_inject:
+        _inject_label_case(result, merged.label.font.case)
+
+    return result
+
+
+def _emit_band_size(scale: Any, out: dict[str, Any]) -> None:
+    """Write minBandSize/maxBandSize into *out* from a scale's band sub-object."""
+    if scale is None or scale.band is None:
+        return
+    if scale.band.min_size is not None:
+        out["minBandSize"] = scale.band.min_size
+    if scale.band.max_size is not None:
+        out["maxBandSize"] = scale.band.max_size
+
+
+def _build_channel_scale(
+    effective: MergedChartsStyle,
+    axis_name: Literal["axis_x", "axis_y"],
+    channel_type: str,
+    chart_type_axis_patch: AxisStylePatch | None = None,
+) -> dict[str, Any]:
+    """Build a VL ``encoding.<channel>.scale`` dict from the merged axis cascade.
+
+    The renderer reads scale state in two layers:
+      1. Chart-level global scale (``effective.scale``)
+      2. The merged per-axis scale from ``resolved_axis_style`` — which already
+         applies theme cascade + chart-type Layer 3.5 + chart-local overrides
+         in canonical order, so per-axis (most specific) wins.
+    """
+    from dataface.core.render.chart.vl_field_maps import (
+        SCALE_ENCODING_FIELD_MAP,
+        SCALE_FIELD_MAP,
+    )
+
+    out: dict[str, Any] = {}
+    # Layer 1: chart-level global scale (lower precedence — applies to all axes).
+    if effective.scale is not None:
+        out.update(map_fields(effective.scale, SCALE_FIELD_MAP))
+        out.update(map_fields(effective.scale, SCALE_ENCODING_FIELD_MAP))
+        _emit_band_size(effective.scale, out)
+    # Layer 2: per-axis scale via the canonical cascade reader.
+    merged_axis = resolved_axis_style(
+        effective, axis_name, channel_type, chart_type_axis_patch
+    )
+    if merged_axis.scale is not None:
+        out.update(map_fields(merged_axis.scale, SCALE_FIELD_MAP))
+        out.update(map_fields(merged_axis.scale, SCALE_ENCODING_FIELD_MAP))
+        _emit_band_size(merged_axis.scale, out)
+    return out
+
+
+# ── Channel encoding mapping ─────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class _AxisRouting:
+    """Upstream channel↔cascade routing for a single chart.
+
+    Horizontal bar swaps field assignment and axis-cascade names so that
+    mapping helpers build the right VL encoding from the start — no
+    post-hoc swap or cleanup needed.
+
+    ``vl_x_*``  describe the channel that lands in ``encoding["x"]``.
+    ``vl_y_*``  describe the channel that lands in ``encoding["y"]``.
+    ``vl_x_label_src`` / ``vl_y_label_src`` control which authored label
+    (x_label or y_label) titles each VL channel.  Under dataface semantics
+    axis_x = categorical, axis_y = measure regardless of orientation, so
+    for horizontal bar the labels travel with chart.x / chart.y rather than
+    with VL x / VL y.
+    ``vl_y_infer_type`` is True when the VL-y field should have its type
+    inferred from data (nominal/ordinal) instead of defaulting to quantitative.
+    """
+
+    vl_x_field: str | None
+    vl_y_field: str | None
+    vl_x_axis_cascade: Literal["axis_x", "axis_y"]
+    vl_y_axis_cascade: Literal["axis_x", "axis_y"]
+    vl_x_label_src: Literal["x_label", "y_label"]
+    vl_y_label_src: Literal["x_label", "y_label"]
+    vl_y_infer_type: bool
+
+
+def _build_axis_routing(resolved_chart: ResolvedChart) -> _AxisRouting:
+    """Build channel↔cascade routing for the given chart.
+
+    Horizontal bar routes the measure field to VL x (using the axis_y
+    cascade, since axis_y = measure axis under dataface semantics) and
+    the categorical field to VL y (using the axis_x cascade, since
+    axis_x = categorical axis).  All other charts use the identity routing.
+    """
+    if (
+        resolved_chart.orientation == "horizontal"
+        and resolved_chart.chart_type == "bar"
+    ):
+        return _AxisRouting(
+            vl_x_field=resolved_chart.y if isinstance(resolved_chart.y, str) else None,
+            vl_y_field=resolved_chart.x,
+            vl_x_axis_cascade="axis_y",
+            vl_y_axis_cascade="axis_x",
+            vl_x_label_src="y_label",
+            vl_y_label_src="x_label",
+            vl_y_infer_type=True,
+        )
+    return _AxisRouting(
+        vl_x_field=resolved_chart.x,
+        vl_y_field=resolved_chart.y if not isinstance(resolved_chart.y, list) else None,
+        vl_x_axis_cascade="axis_x",
+        vl_y_axis_cascade="axis_y",
+        vl_x_label_src="x_label",
+        vl_y_label_src="y_label",
+        vl_y_infer_type=(resolved_chart.chart_type == "scatter"),
+    )
+
+
+def map_x_encoding(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    *,
+    routing: _AxisRouting | None = None,
+) -> dict[str, Any] | None:
+    """Map the x channel from Dataface to Vega-Lite encoding."""
+    x_field = routing.vl_x_field if routing is not None else resolved_chart.x
+    if not x_field:
+        return None
+
+    axis_cascade: Literal["axis_x", "axis_y"] = (
+        routing.vl_x_axis_cascade if routing is not None else "axis_x"
+    )
+    columns = set(data[0].keys()) if data else set()
+    effective = resolved_chart.resolved_style
+    # Data-inferred type: "temporal" for date/datetime values, else "nominal" etc.
+    x_type_from_data = (
+        infer_vega_type_from_data(data, x_field) if x_field in columns else "nominal"
+    )
+    x_type = x_type_from_data
+
+    # Probe authored time_unit + axis type from the full cascade.
+    # Use the data-inferred channel type for the initial probe; axis_overrides_global
+    # and axis_overrides_x surface authored time_unit regardless of channel type.
+    _initial_channel_type = x_type
+    _ct_attr_x_for_tu = (
+        "arc" if resolved_chart.chart_type == "pie" else resolved_chart.chart_type
+    )
+    _ct_style_x_for_tu = getattr(effective, _ct_attr_x_for_tu, None)
+    _ct_axis_x_for_tu = (
+        getattr(_ct_style_x_for_tu, axis_cascade, None)
+        if _ct_style_x_for_tu is not None
+        else None
+    )
+    _merged_x = resolved_axis_style(
+        effective, axis_cascade, _initial_channel_type, _ct_axis_x_for_tu
+    )
+    authored_tu = _merged_x.time_unit
+    authored_axis_type = _merged_x.type  # None / "auto" / "ordinal" / "temporal"
+
+    # For explicitly authored time_unit (non-auto/none) on non-date data:
+    # validate the data is parseable as dates so a bad authored time_unit fails
+    # loudly rather than silently producing a nominal-typed axis.
+    if authored_tu and authored_tu not in ("auto", "none") and x_type != "temporal":
+        values = [row.get(x_field) for row in data if x_field in row]
+        if values:
+            detect_time_unit(values)  # raises ValueError on ≥10% unparseable
+
+    # Pre-resolve time_unit for the scale-type decision below.
+    # Resolve regardless of current x_type so we can decide ordinal vs temporal.
+    if authored_tu == "none":
+        time_unit: str | None = None
+    elif authored_tu and authored_tu not in ("auto",):
+        time_unit = authored_tu
+    elif x_type == "temporal":
+        time_unit = detect_time_unit(
+            [row.get(x_field) for row in data if x_field in row]
+        )
+    else:
+        time_unit = None
+
+    # Scale-type decision: bucketed-calendar grains default to ordinal.
+    # Author's axis_x.type always wins over the default.
+    if authored_axis_type == "temporal":
+        # Escape hatch: force temporal even for bucketed data.
+        if x_type != "temporal":
+            x_type = "temporal"
+    elif authored_axis_type == "ordinal":
+        x_type = "ordinal"
+    elif time_unit and time_unit in BUCKETED_CALENDAR_UNITS:
+        # Auto/explicit bucketed-calendar grain → ordinal by default.
+        x_type = "ordinal"
+    elif authored_tu and authored_tu not in ("auto", "none") and x_type != "temporal":
+        # Explicit time-part (monthofyear, dayofweek, etc.) on non-date data
+        # → force temporal (unchanged behaviour for time-part units).
+        x_type = "temporal"
+
+    underlying_temporal = x_type == "temporal"
+
+    authored_label = (
+        resolved_chart.x_label
+        if routing is None or routing.vl_x_label_src == "x_label"
+        else resolved_chart.y_label
+    )
+    encoding: dict[str, Any] = {
+        "field": x_field,
+        "type": x_type,
+        "title": (
+            authored_label
+            if authored_label
+            else format_display_text(
+                x_field, from_slug=True, font=effective.axis_x.title.font
+            )
+        ),
+        "axis": {},
+    }
+    # Unified axis emit: chart-local axis layer is pre-merged into effective by
+    # build_resolved_style; the cascade helper handles type-conditional dispatch
+    # and chart-type-specific Layer 3.5.
+    _ct_attr_x = (
+        "arc" if resolved_chart.chart_type == "pie" else resolved_chart.chart_type
+    )
+    _ct_style_x = getattr(effective, _ct_attr_x, None)
+    _ct_axis_x = (
+        getattr(_ct_style_x, axis_cascade, None) if _ct_style_x is not None else None
+    )
+    encoding["axis"].update(
+        _build_encoding_axis(
+            effective, axis_cascade, x_type, _ct_axis_x, skip_case_inject=True
+        )
+    )
+    # axis_y carries orient="auto" for the y-axis side. That sentinel is only
+    # meaningful for VL y; strip it when axis_y cascade drives VL x.
+    if axis_cascade == "axis_y" and encoding["axis"].get("orient") == "auto":
+        encoding["axis"].pop("orient")
+
+    # When a d3-time-format string (e.g. "%b %Y") is applied to a non-temporal
+    # axis, Vega defaults to d3-format (number formatting) which rejects
+    # time-format patterns. ``formatType: "time"`` would route through
+    # d3-time-format under the *runtime's* local TZ (D-003a leak). Emit a UTC
+    # labelExpr that is TZ-independent by construction.
+    axis_fmt = encoding["axis"].get("format")
+    if isinstance(axis_fmt, str) and x_type != "temporal" and _is_time_format(axis_fmt):
+        if "labelExpr" not in encoding["axis"]:
+            encoding["axis"]["labelExpr"] = _utc_time_label_expr(axis_fmt)
+        encoding["axis"].pop("format", None)
+
+    x_scale = _build_channel_scale(effective, axis_cascade, x_type, _ct_axis_x)
+    if x_type == "temporal":
+        x_scale = {"type": "utc", **x_scale}
+
+    # For horizontal bar, VL x is the measure axis. Apply chart.zero and domainMax
+    # here, symmetrically with map_y_encoding's quantitative-scale blocks.
+    if (
+        routing is not None
+        and routing.vl_x_axis_cascade == "axis_y"
+        and x_type == "quantitative"
+        and resolved_chart.zero is not None
+    ):
+        x_scale["zero"] = resolved_chart.zero
+
+    if (
+        routing is not None
+        and routing.vl_x_axis_cascade == "axis_y"
+        and resolved_chart.chart_type == "bar"
+        and x_type == "quantitative"
+        and resolved_chart.stack not in (False, "normalize")
+        and not is_grouped_bar(resolved_chart)
+        and isinstance(resolved_chart.x, str)
+        and "domain" not in x_scale
+    ):
+        stacked_max = stacked_bar_totals_max(data, resolved_chart.x, x_field)
+        if stacked_max is not None:
+            x_scale["domainMax"] = stacked_max
+
+    if x_scale:
+        encoding["scale"] = x_scale
+
+    if (
+        resolved_chart.chart_type in {"bar", "line", "area", "layered"}
+        and x_type != "quantitative"
+    ):
+        encoding["sort"] = None
+        if underlying_temporal:
+            # Temporal path (including escape-hatch): emit timeUnit + smart labelExpr.
+            if time_unit is not None:
+                encoding["timeUnit"] = vl_time_unit(time_unit)
+                if "labelExpr" not in encoding["axis"]:
+                    authored_label_tu = resolved_axis_style(
+                        effective, axis_cascade, x_type, _ct_axis_x
+                    ).label.time_unit
+                    label_time_unit = resolve_label_time_unit(
+                        time_unit, authored_label_tu
+                    )
+                    smart_expr = default_label_expr_for(time_unit, label_time_unit)
+                    if smart_expr is not None:
+                        encoding["axis"]["labelExpr"] = smart_expr
+        elif x_type == "ordinal" and time_unit and time_unit in BUCKETED_CALENDAR_UNITS:
+            # Ordinal bucketed-time path: no timeUnit, no labelExpr.
+            # Emit axis.values (precomputed sorted tick list) and a smart
+            # default format for date-like input columns.
+            authored_label_tu = resolved_axis_style(
+                effective, axis_cascade, x_type, _ct_axis_x
+            ).label.time_unit
+            label_tu = resolve_label_time_unit(time_unit, authored_label_tu)
+            tick_values = ordinal_axis_values(data, x_field, time_unit, label_tu)
+            if tick_values is not None and "values" not in encoding["axis"]:
+                encoding["axis"]["values"] = tick_values
+            # Reuse the temporal-path smart labelExpr builders in ordinal
+            # mode for date-like (temporal-inferred) inputs when the author
+            # has not set an explicit format string. ``toDate(datum.value)``
+            # parses the ISO date string back to a UTC instant; ``utcFormat``
+            # emits the d3-time-format string without TZ drift; the
+            # cadence-aware gate stamps the year only on label-period
+            # openers (under January for yearmonth, Q1 for yearquarter, W1
+            # of January for yearweek, etc.) — the same multi-line
+            # convention the temporal path produced before #2400.
+            # ``formatType: "time"`` would silently drop every label on a
+            # string-domain ordinal scale.
+            if (
+                x_type_from_data == "temporal"
+                and not axis_fmt
+                and "labelExpr" not in encoding["axis"]
+            ):
+                smart_expr = default_label_expr_for(time_unit, label_tu)
+                if smart_expr is not None:
+                    encoding["axis"]["labelExpr"] = smart_expr
+
+    # Inject upper/lower case after all smart temporal labelExpr blocks so case
+    # wraps the cadence expression (upper(<smart_expr>)) rather than replacing
+    # it with the naive upper(datum.label) form that the temporal block would
+    # then silently skip. _build_encoding_axis skips injection (skip_case_inject=True)
+    # so this is the only case-injection site for the x-axis path.
+    _label_case = resolved_axis_style(
+        effective, axis_cascade, x_type, _ct_axis_x
+    ).label.font.case
+    _inject_label_case(encoding["axis"], _label_case)
+
+    return encoding
+
+
+def map_y_encoding(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    *,
+    y_field: str | None = None,
+    routing: _AxisRouting | None = None,
+    skip_tick_values: bool = False,
+) -> dict[str, Any] | None:
+    """Map the y channel from Dataface to Vega-Lite encoding."""
+    assert (
+        routing is None or y_field is None
+    ), "routing and y_field are mutually exclusive"
+    resolved_y_field: str | list[str] | None
+    if routing is not None:
+        resolved_y_field = routing.vl_y_field
+    elif y_field is not None:
+        resolved_y_field = y_field
+    else:
+        resolved_y_field = resolved_chart.y
+    if not resolved_y_field or isinstance(resolved_y_field, list):
+        return None
+
+    axis_cascade: Literal["axis_x", "axis_y"] = (
+        routing.vl_y_axis_cascade if routing is not None else "axis_y"
+    )
+    columns = set(data[0].keys()) if data else set()
+    effective = resolved_chart.resolved_style
+    user_format = (
+        resolve_format(resolved_chart.format, effective.formats)
+        if resolved_chart.format
+        else ""
+    )
+
+    infer_from_data = resolved_chart.chart_type == "scatter" or (
+        routing is not None and routing.vl_y_infer_type
+    )
+    y_type = "quantitative"
+    if infer_from_data:
+        y_type = (
+            infer_vega_type_from_data(data, resolved_y_field)
+            if resolved_y_field in columns
+            else "nominal"
+        )
+
+    y_axis: dict[str, Any] = {}
+    # Unified axis emit: chart-local axis layer is pre-merged into effective by
+    # build_resolved_style; the helper handles type-conditional dispatch.
+    _ct_attr_y = (
+        "arc" if resolved_chart.chart_type == "pie" else resolved_chart.chart_type
+    )
+    _ct_style_y = getattr(effective, _ct_attr_y, None)
+    _ct_axis_y = (
+        getattr(_ct_style_y, axis_cascade, None) if _ct_style_y is not None else None
+    )
+    y_axis.update(_build_encoding_axis(effective, axis_cascade, y_type, _ct_axis_y))
+    # Resolve "auto" orient sentinel: right by default, left when the chart
+    # family emits right-edge series labels that would collide with the axis.
+    # axis_y carries orient="auto"; axis_x does not — only check when needed.
+    if axis_cascade == "axis_y" and y_axis.get("orient") == "auto":
+        y_axis["orient"] = _resolve_orient_auto("auto", resolved_chart, effective)
+    if user_format and y_type == "quantitative":
+        y_axis["format"] = user_format
+
+    # Enforce tick density for quantitative y-axes when ticks.count is set.
+    # VL's tickCount is advisory (d3 rounds to "nice" steps and ignores the
+    # target); emit explicit tickValues so VL respects the editorial intent.
+    # Only fires when data is available and the author hasn't pinned values.
+    # Skip for normalize-stacked bars: _apply_stack_encoding sets quartile
+    # ticks (0, 0.25, 0.5, 0.75, 1.0) after map_y_encoding; we must not
+    # pre-empt them since the raw data values are raw counts, not fractions.
+    # Skip for layered multi-metric charts: each layer calls map_y_encoding
+    # with its own metric range; per-layer axis.values conflict on the shared
+    # y-scale, so callers pass skip_tick_values=True for layered contexts.
+    _is_normalize_stack = resolved_chart.stack == "normalize"
+    # Stacked area (stack: "zero") and streamgraph (stack: "center") have
+    # complex y-domains VL must compute from stacked totals. Pinning domainMax
+    # to the individual-row maximum clips marks above that value → chart vanishes.
+    _is_stacked_area = (
+        resolved_chart.chart_type == "area"
+        and resolved_chart.stack not in (False, None)
+    )
+    # True only when the pipeline explicitly resolved zero:true — meaning the
+    # scale will extend to 0 with data living above it, creating a potential
+    # blank gap below the first gridline that domainMin must close.
+    _chart_uses_zero = resolved_chart.zero is True
+    _computed_tick_vals: list[float] | None = None
+    if (
+        y_type == "quantitative"
+        and "values" not in y_axis
+        and data
+        and not _is_normalize_stack
+        and not _is_stacked_area
+        and not skip_tick_values
+    ):
+        _merged_y = resolved_axis_style(effective, axis_cascade, y_type, _ct_axis_y)
+        tick_count = _merged_y.ticks.count
+        if tick_count is not None:
+            y_floats: list[float] = [
+                float(row[resolved_y_field])
+                for row in data
+                if isinstance(row.get(resolved_y_field), (int, float))
+            ]
+            if y_floats:
+                # For stacked bars the per-row values are individual category
+                # contributions; the visible axis spans the stacked column
+                # totals. Derive domain_max from stacked totals when applicable
+                # (same condition as the domainMax scale pin below).
+                _x_field = resolved_chart.x
+                _is_stacked_bar = (
+                    resolved_chart.chart_type == "bar"
+                    and resolved_chart.stack not in (False, "normalize", None)
+                    and not is_grouped_bar(resolved_chart)
+                    and isinstance(_x_field, str)
+                )
+                if _is_stacked_bar and isinstance(_x_field, str):
+                    _stacked_max = stacked_bar_totals_max(
+                        data, _x_field, resolved_y_field
+                    )
+                    domain_max = (
+                        _stacked_max if _stacked_max is not None else max(y_floats)
+                    )
+                else:
+                    domain_max = max(y_floats)
+                domain_min = (
+                    min(0.0, min(y_floats)) if _chart_uses_zero else min(y_floats)
+                )
+                _computed_tick_vals = nice_tick_values(
+                    domain_min, domain_max, tick_count
+                )
+                y_axis["values"] = _computed_tick_vals
+
+    # Mirror the x-axis guard: when a d3-time-format string is supplied for a
+    # non-temporal y-axis, Vega's default d3-format rejects the time directive
+    # and crashes with a scene-graph TypeError. ``formatType: "time"`` would
+    # route through d3-time-format under the *runtime's* local TZ (D-003a leak).
+    # Emit a UTC labelExpr that is TZ-independent by construction.
+    axis_y_fmt = y_axis.get("format")
+    if (
+        isinstance(axis_y_fmt, str)
+        and y_type != "temporal"
+        and _is_time_format(axis_y_fmt)
+    ):
+        if "labelExpr" not in y_axis:
+            y_axis["labelExpr"] = _utc_time_label_expr(axis_y_fmt)
+        y_axis.pop("format", None)
+
+    authored_y_label = (
+        resolved_chart.y_label
+        if routing is None or routing.vl_y_label_src == "y_label"
+        else resolved_chart.x_label
+    )
+    encoding: dict[str, Any] = {
+        "field": resolved_y_field,
+        "type": y_type,
+        "title": (
+            authored_y_label
+            if authored_y_label and y_field is None
+            else format_display_text(
+                resolved_y_field, from_slug=True, font=effective.axis_y.title.font
+            )
+        ),
+        "axis": y_axis,
+    }
+    if user_format and y_type == "quantitative":
+        encoding["format"] = user_format
+
+    y_scale = _build_channel_scale(effective, axis_cascade, y_type, _ct_axis_y)
+    if resolved_chart.zero is not None and y_type == "quantitative":
+        y_scale["zero"] = resolved_chart.zero
+
+    # Pin domainMax for stacked vertical bar charts so the scale spans the full
+    # stacked extent.  Horizontal bar's VL x (measure) handles its own domainMax
+    # in map_x_encoding.  Grouped bars skip this — each bar is independent.
+    if (
+        resolved_chart.chart_type == "bar"
+        and y_type == "quantitative"
+        and resolved_chart.stack not in (False, "normalize")
+        and not is_grouped_bar(resolved_chart)
+        and isinstance(resolved_chart.x, str)
+    ):
+        if "domain" not in y_scale:
+            stacked_max = stacked_bar_totals_max(
+                data, resolved_chart.x, resolved_y_field
+            )
+            if stacked_max is not None:
+                y_scale["domainMax"] = stacked_max
+
+    # Pin domainMin to the first tick for zero-baseline charts (bar, area) so
+    # VL's scale.zero=true cannot push the domain below the lowest gridline,
+    # leaving blank space (e.g. $0–$80K gap when ticks start at $80K on a
+    # $97K–$168K dataset).  Never pin domainMax — that boxes the top of the
+    # chart with a gridline at the edge, which looks wrong for all mark types.
+    # Author-set domain/domainMin takes precedence.
+    if _computed_tick_vals is not None and _chart_uses_zero and "domain" not in y_scale:
+        if "domainMin" not in y_scale:
+            y_scale["domainMin"] = _computed_tick_vals[0]
+
+    if y_scale:
+        encoding["scale"] = y_scale
+
+    return encoding
+
+
+def _build_encoding_legend(effective: MergedChartsStyle) -> dict[str, Any] | None:
+    """Build encoding.{color,size}.legend dict from the merged resolved legend.
+
+    Chart-local legend patches are pre-merged into ``effective.legend`` by
+    build_resolved_style, so the renderer reads from a single resolved value.
+    ``effective.legend.disable=True`` returns None (VL emits ``legend = null``);
+    any other state returns a dict.
+    """
+    from dataface.core.render.chart.vl_field_maps import legend_to_vl
+
+    if effective.legend.disable is True:
+        return None
+    d: dict[str, Any] = legend_to_vl(effective.legend) or {}
+    return d if d else None
+
+
+def map_other_encoding(
+    channel_name: str,
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+) -> dict[str, Any] | None:
+    """Map color/size/shape channels from Dataface to Vega-Lite encoding."""
+    effective = resolved_chart.resolved_style
+
+    if channel_name == "color":
+        color_ch = resolved_chart.resolved_channels.get("color")
+        if color_ch is None:
+            return None
+        if color_ch.mode == "series" and color_ch.data_field:
+            columns = set(data[0].keys()) if data else set()
+            inferred_type = (
+                infer_vega_type_from_data(data, color_ch.data_field)
+                if color_ch.data_field in columns
+                else "nominal"
+            )
+            enc: dict[str, Any] = {"field": color_ch.data_field, "type": inferred_type}
+        else:
+            vl_enc = _resolved_channel_to_vl(color_ch)
+            if vl_enc is None:
+                return None
+            enc = vl_enc
+
+        # Literal-mode encodings (``{value: "#hex"}``) are constants — Vega-Lite
+        # ignores the value if a legend object is attached, so the bars/lines
+        # silently revert to the theme default. Skip the legend injection.
+        if color_ch.mode == "literal":
+            return enc
+
+        # Set title so vl-convert emits the titled key in aria-labels — without
+        # it, channels collapse to the raw lowercase field name (e.g. "kind: task"
+        # instead of "Kind: task").
+        if enc.get("field"):
+            enc["title"] = format_display_text(
+                enc["field"], from_slug=True, font=effective.legend.title.font
+            )
+
+        # Inject unified legend at encoding.color.legend
+        legend = _build_encoding_legend(effective)
+        enc["legend"] = legend  # None → null disables, dict → legend config
+        return enc
+
+    other_field = getattr(resolved_chart, channel_name)
+    if not other_field or isinstance(other_field, list):
+        return None
+
+    columns = set(data[0].keys()) if data else set()
+    default_type = "quantitative" if channel_name == "size" else "nominal"
+    inferred_type = (
+        infer_vega_type_from_data(data, other_field)
+        if other_field in columns
+        else default_type
+    )
+    enc = {
+        "field": other_field,
+        "type": inferred_type,
+        "title": format_display_text(
+            other_field, from_slug=True, font=effective.legend.title.font
+        ),
+    }
+
+    # Inject unified legend for size/shape channels too
+    if channel_name in ("size", "shape"):
+        legend = _build_encoding_legend(effective)
+        enc["legend"] = legend
+    return enc
+
+
+def _cf_rules_to_vl_condition(
+    rules: Iterable[ConditionalRule],
+    field_ref: str,
+) -> dict[str, Any] | None:
+    """Build a VL conditional color encoding from CF rules for a single field.
+
+    Only rules with a ``background`` output are encoded; font-only rules
+    are silently skipped (marks have no text to style).
+    Returns None when no background conditions exist.
+    """
+    conditions = [
+        {"test": _rule_to_vl_test(rule, field_ref), "value": rule.background}
+        for rule in rules
+        if rule.background is not None
+    ]
+    if not conditions:
+        return None
+    # value: null is the VL no-match fallback — leaves the mark un-encoded.
+    return {"condition": conditions, "value": None}
+
+
+def _resolved_channel_to_vl(ch: ResolvedStyleChannel) -> dict[str, Any] | None:
+    """Convert a ResolvedStyleChannel to a Vega-Lite encoding dict."""
+    if ch.mode == "literal":
+        return {"value": ch.literal_value}
+
+    if ch.mode == "series":
+        return {"field": ch.data_field, "type": "nominal"}
+
+    if ch.mode == "gradient":
+        assert ch.scale is not None  # gradient mode always has a scale
+        scale = ch.scale
+        vl_scale: dict[str, Any] = {"range": list(scale.palette)}
+        if scale.min is not None and scale.max is not None:
+            vl_scale["domain"] = [scale.min, scale.max]
+        elif scale.min is not None:
+            vl_scale["domainMin"] = scale.min
+        elif scale.max is not None:
+            vl_scale["domainMax"] = scale.max
+        return {"field": ch.data_field, "type": "quantitative", "scale": vl_scale}
+
+    if ch.mode == "conditional":
+        field_ref = f"datum[{json.dumps(ch.data_field)}]"
+        return _cf_rules_to_vl_condition(ch.rules, field_ref)
+
+    raise ValueError(f"Unreachable: unknown channel mode {ch.mode!r}")
+
+
+# ── Structural transforms ────────────────────────────────────────────
+
+
+_SORT_ORDER_VL = {"asc": "ascending", "desc": "descending"}
+
+
+def chart_has_active_dashes(resolved_chart: ResolvedChart) -> bool:
+    """True when the chart should emit a ``strokeDash`` encoding.
+
+    Shared predicate used by ``_apply_dash_encoding`` (emits the encoding) and
+    the zero/top rule-layer constructors (must null out inheritance only when
+    the encoding is actually present). Gating these on the same predicate
+    keeps existing themes-without-dashes producing byte-identical SVG.
+
+    Fires only when (a) the chart mark is line-family (line/area), (b) the
+    merged theme has ``dashes`` set, and (c) the chart's resolved color
+    channel is a categorical series field. The render layer reads None on
+    ``MergedChartsStyle.dashes`` as "skip emission" — see the cascade-managed-
+    sentinel comment on the field.
+    """
+    if resolved_chart.chart_type not in {"line", "area"}:
+        return False
+    if resolved_chart.resolved_style.dashes is None:
+        return False
+    color_ch = resolved_chart.resolved_channels.get("color")
+    if color_ch is None:
+        return False
+    return color_ch.mode == "series" and bool(color_ch.data_field)
+
+
+# Per-channel registries for _neutralize_layer_channels.
+# Pattern fills will extend these two dicts; everything else stays the same.
+_CHANNEL_PREDICATES: dict[str, Callable[[ResolvedChart], bool]] = {
+    "strokeDash": chart_has_active_dashes,
+}
+# The "channel is off" VL value for each registered channel.
+# strokeDash: [] → VL interprets an empty array as a solid stroke.
+_NEUTRAL_VALUES: dict[str, Any] = {
+    "strokeDash": [],
+}
+
+
+def _neutralize_layer_channels(
+    encoding: dict[str, Any],
+    resolved_chart: ResolvedChart,
+    channels: list[str] | None = None,
+) -> None:
+    """Stamp neutral VL values onto ``encoding`` for channels that are active
+    at the chart level but whose data is not present in this layer.
+
+    Rule layers and other synthetic-data layers call this to prevent VL from
+    inheriting a top-level ``strokeDash`` (or future ``patternFill``) binding
+    onto a layer whose data row has no series field — which would pollute the
+    scale domain with ``undefined`` and stamp spurious attributes on the SVG.
+
+    Mutates ``encoding`` in place.  When ``channels`` is None, defaults to all
+    registered channels (``list(_CHANNEL_PREDICATES.keys())``).  Pass an
+    explicit ``channels=[]`` to suppress all neutralization.
+    """
+    active = list(_CHANNEL_PREDICATES.keys()) if channels is None else channels
+    for channel in active:
+        predicate = _CHANNEL_PREDICATES[channel]
+        if predicate(resolved_chart):
+            encoding[channel] = {"value": _NEUTRAL_VALUES[channel]}
+
+
+def _apply_dash_encoding(
+    resolved_chart: ResolvedChart, encoding: dict[str, Any]
+) -> None:
+    """Bind ``strokeDash`` to the categorical color field on line-family charts.
+
+    Fires only when ``chart_has_active_dashes`` returns True AND the color
+    encoding has already been emitted as a field-bound nominal/ordinal channel
+    (which is the same condition under the hood).
+
+    Bound to the same field as ``color`` so the default is redundant encoding
+    (color + dash on the same series). Monochrome theme will set ``dashes`` and
+    a single-color palette, making dash the primary distinguishing channel.
+    """
+    if not chart_has_active_dashes(resolved_chart):
+        return
+    color_enc = encoding.get("color")
+    if not isinstance(color_enc, dict):
+        return
+    field = color_enc.get("field")
+    color_type = color_enc.get("type")
+    if not field or color_type not in {"nominal", "ordinal"}:
+        return
+    # ``scale.range`` carries the actual dash arrays. vl_convert silently
+    # ignores ``config.range.dashPattern`` (documented in Vega-Lite, not
+    # honored by the renderer we use), so the range lives on the encoding
+    # instead.
+    #
+    # When color and strokeDash bind to the same field with matching titles
+    # and clean (un-polluted) scale domains, Vega-Lite merges the two legends
+    # into a single legend whose swatches show both channels together. The
+    # rule-layer strokeDash overrides keep the domain clean. Here we also flip
+    # the color legend's ``symbolType`` to ``stroke`` so the merged-legend
+    # symbol renders as a line sample with the dash pattern applied, rather
+    # than the default filled circle (which displays a dashed circle outline
+    # and is unreadable). ``symbolSize: 2000`` produces a ~45-px line sample —
+    # ≥ one full cycle of every entry in the shipped 5+1 palette (longest
+    # cycle: dash-dot-dot ``[12, 8, 0, 8, 0, 8]`` = 36 px). ``symbolStrokeWidth:
+    # 2`` is a notch below the default 3-px line stroke so the legend reads
+    # compact. Both intentionally override any upstream legend symbol config —
+    # the merged-legend swatch requires these specific values.
+    # The color legend may be explicitly None (theme- or chart-disabled). In
+    # that case the user has opted out of the color legend entirely — leave
+    # strokeDash without a legend rather than resurrecting one.
+    existing_legend = color_enc.get("legend")
+    if existing_legend is None and "legend" in color_enc:
+        # legend: None means "suppressed" — strokeDash gets the same treatment.
+        encoding["strokeDash"] = {
+            "field": field,
+            "type": color_type,
+            "scale": {"range": resolved_chart.resolved_style.dashes},
+            "legend": None,
+        }
+        if "title" in color_enc:
+            encoding["strokeDash"]["title"] = color_enc["title"]
+        return
+
+    color_enc["legend"] = {
+        **(existing_legend or {}),
+        "symbolType": "stroke",
+        "symbolStrokeWidth": 2,
+        "symbolSize": 2000,
+    }
+
+    encoding["strokeDash"] = {
+        "field": field,
+        "type": color_type,
+        "scale": {"range": resolved_chart.resolved_style.dashes},
+    }
+    if "title" in color_enc:
+        encoding["strokeDash"]["title"] = color_enc["title"]
+
+
+def _apply_chart_sort(resolved_chart: ResolvedChart, encoding: dict[str, Any]) -> None:
+    """Map Dataface sort to Vega-Lite sort on the categorical axis.
+
+    Dataface stores ``ChartSort.order`` as ``"asc" | "desc"`` (canonical
+    form). Vega-Lite's ``sort.order`` accepts only ``"ascending"`` or
+    ``"descending"``; passing the raw Dataface form makes VL silently
+    fall back to ascending, breaking the sort contract. Translate at the
+    emit boundary.
+    """
+    if not resolved_chart.sort:
+        return
+
+    sort_target = {
+        "field": resolved_chart.sort.by,
+        "order": _SORT_ORDER_VL[resolved_chart.sort.order],
+    }
+
+    for axis_name in ("x", "y"):
+        axis_encoding = encoding.get(axis_name)
+        if not isinstance(axis_encoding, dict):
+            continue
+        if axis_encoding.get("type") in ("nominal", "ordinal"):
+            axis_encoding["sort"] = sort_target
+            break
+
+
+_DF_STACK_ORDER_KEY = "__df_stack_order"
+"""Sort key field computed by the joinaggregate transform in _apply_stacked_bar_z_order.
+
+The joinaggregate transform computes the global sum of the measure field per color
+group inside VL's transform pipeline. encoding.order references this column without
+aggregate — VL evaluates it per-datum so the sort key is stable across all bars.
+"""
+
+_DF_DATA_ORDER_KEY = "__df_data_order"
+"""Sort key field computed by a VL calculate transform for stack_order='data'.
+
+The calculate transform uses indexof([first, second, ...], datum.color_field) to
+assign each datum its series' global first-encounter index. encoding.order references
+this column with sort: 'ascending' so VL stacks in data-row first-encounter order —
+consistent across all bars regardless of alphabetical order.
+"""
+
+
+def _apply_stacked_bar_z_order(
+    resolved_chart: ResolvedChart,
+    encoding: dict[str, Any],
+    data: list[dict[str, Any]] | None = None,
+) -> tuple[dict[str, Any], ...]:
+    """Set encoding.order for globally-stable stacking; return the required VL transforms.
+
+    'value' (default): emits a joinaggregate transform to compute the global sum per
+    color group. encoding.order references the computed field per-datum — stable across
+    all bars, largest series at baseline.
+
+    'alphabetical': sort by color field name ascending; no transform needed.
+
+    'data': VL without an explicit encoding.order uses alphabetical domain order for
+    nominal fields, not data row order. To force data-row first-encounter order, emits
+    a calculate transform that assigns each series its global first-encounter index and
+    references it via encoding.order.sort: ascending.
+
+    encoding.order with aggregate: sum is wrong — VL evaluates that aggregate per
+    stack-group (per bar), so each bar re-ranks its segments independently.
+
+    Skipped when stacking is disabled or no color field is present.
+    Returns an empty tuple when no transform is needed.
+    """
+    if resolved_chart.chart_type != "bar":
+        return ()
+    if resolved_chart.stack is False or is_grouped_bar(resolved_chart):
+        return ()
+    color_ch = resolved_chart.resolved_channels.get("color")
+    if color_ch is None or not color_ch.data_field:
+        return ()
+
+    stack_order = resolved_chart.resolved_style.bar.stack_order
+
+    if stack_order == "data":
+        # VL's default for nominal color without encoding.order is alphabetical,
+        # not data row order. Compute the global first-encounter order and emit a
+        # calculate transform so VL stacks in the order rows appear in the data.
+        if not data:
+            return ()
+        seen: dict[str, None] = {}
+        for row in data:
+            s = row.get(color_ch.data_field)
+            if s is not None:
+                seen[str(s)] = None
+        first_encounter = list(seen)
+        if not first_encounter:
+            return ()
+        field_expr = f"datum[{json.dumps(color_ch.data_field)}]"
+        domain_expr = json.dumps(first_encounter)
+        encoding["order"] = {
+            "field": _DF_DATA_ORDER_KEY,
+            "sort": "ascending",
+        }
+        return (
+            {
+                "calculate": f"indexof({domain_expr}, {field_expr})",
+                "as": _DF_DATA_ORDER_KEY,
+            },
+        )
+
+    if stack_order == "alphabetical":
+        color_enc = encoding.get("color", {})
+        encoding["order"] = {
+            "field": color_ch.data_field,
+            "sort": "ascending",
+            "title": color_enc.get(
+                "title",
+                format_display_text(
+                    color_ch.data_field,
+                    from_slug=True,
+                    font=resolved_chart.resolved_style.legend.title.font,
+                ),
+            ),
+            "type": color_enc.get("type", "nominal"),
+        }
+        return ()
+
+    # Default: stack_order is None or "value".
+    # Emit a joinaggregate transform to compute the global sum per color group.
+    # encoding.order references this field without aggregate so VL evaluates it
+    # per-datum — stable across all bars (no per-bar re-aggregation).
+    measure_field = resolved_chart.y
+    if not measure_field:
+        return ()
+    if isinstance(measure_field, list):
+        return ()
+
+    encoding["order"] = {"field": _DF_STACK_ORDER_KEY, "sort": "descending"}
+    return (
+        {
+            "joinaggregate": [
+                {"op": "sum", "field": measure_field, "as": _DF_STACK_ORDER_KEY}
+            ],
+            "groupby": [color_ch.data_field],
+        },
+    )
+
+
+def _measure_vl_channel(resolved_chart: ResolvedChart) -> Literal["x", "y"]:
+    """Return the VL channel name that carries the measure axis after routing.
+
+    Under dataface semantics axis_y = measure regardless of orientation, but the
+    VL channel that carries the measure flips with orientation: vertical bar
+    (and every other family) puts the measure on VL ``y``; horizontal bar
+    swaps it onto VL ``x``. Pin axis-mode properties (``stack``, ``domainMax``,
+    quantitative format) by the value this returns rather than by literal
+    ``"y"`` so the pin lands on the rendered measure axis after the swap.
+    """
+    if (
+        resolved_chart.chart_type == "bar"
+        and resolved_chart.orientation == "horizontal"
+    ):
+        return "x"
+    return "y"
+
+
+def _apply_stack_encoding(
+    resolved_chart: ResolvedChart,
+    encoding: dict[str, Any],
+) -> None:
+    """Pin the stack mode on the measure-axis encoding.
+
+    When stack=None and a color field is present on a bar chart, emits
+    xOffset/yOffset to produce side-by-side grouped columns (the default).
+
+    ``stack: false`` (or any falsy non-None) emits VL's ``stack: null`` which
+    disables stacking — overlapping layers instead of stacked. Literal modes
+    (``"zero"``, ``"normalize"``, ``"center"``) pass through verbatim.
+
+    Lands on encoding.x for horizontal bars and encoding.y otherwise: VL's
+    ``stack`` semantics are axis-bound, and putting the mode on the categorical
+    encoding does nothing (stack on a nominal scale is meaningless) while
+    leaving the measure unstacked.
+    """
+    stack = resolved_chart.stack
+    if is_grouped_bar(resolved_chart):
+        color_field = effective_color_field(resolved_chart)
+        assert color_field is not None  # is_grouped_bar guarantees this
+        offset_ch = (
+            "yOffset" if resolved_chart.orientation == "horizontal" else "xOffset"
+        )
+        color_enc = encoding.get("color", {})
+        encoding[offset_ch] = {
+            "field": color_field,
+            "type": color_enc.get("type", "nominal"),
+            "title": color_enc.get(
+                "title",
+                format_display_text(
+                    color_field,
+                    from_slug=True,
+                    font=resolved_chart.resolved_style.legend.title.font,
+                ),
+            ),
+        }
+        return
+    if stack is None:
+        return
+    measure_channel = _measure_vl_channel(resolved_chart)
+    target = encoding.get(measure_channel)
+    if not isinstance(target, dict):
+        return
+    if stack is False:
+        target["stack"] = None
+    elif isinstance(stack, str):
+        target["stack"] = stack
+        if stack == "normalize":
+            target.setdefault("axis", {}).setdefault(
+                "values", [0, 0.25, 0.5, 0.75, 1.0]
+            )
+
+
+def _apply_grouped_bar_scale_padding(enc: dict[str, Any]) -> None:
+    """Set paddingInner/paddingOuter on a grouped-bar categorical encoding scale."""
+    scale = enc.setdefault("scale", {})
+    # ScaleStylePatch has no `padding` field, so the only source of `padding` in the
+    # scale dict is the theme cascade (axis_x.scale.padding: 0 → {padding: 0.0}).
+    # VegaLite's spec says `padding` is ignored when explicit inner/outer are present,
+    # but Vega's band scale processes `padding` after them and overrides paddingOuter.
+    # Pop it unconditionally so the explicit values are unambiguous.
+    scale.pop("padding", None)
+    scale.setdefault("paddingInner", _GROUPED_BAR_PADDING_INNER)
+    scale.setdefault("paddingOuter", _GROUPED_BAR_PADDING_OUTER)
+
+
+def _apply_bar_axis_defaults(
+    resolved_chart: ResolvedChart,
+    encoding: dict[str, Any],
+) -> None:
+    """Apply categorical axis defaults for bar charts."""
+    if resolved_chart.chart_type != "bar" or "y" not in encoding:
+        return
+
+    y_enc = encoding["y"]
+    effective = resolved_chart.resolved_style
+    bar = effective.bar
+
+    y_type = y_enc.get("type")
+    # categorical_orient lives on axis_y in theme as a sentinel for the bar
+    # categorical axis orient. Only fires for horizontal bar (VL y is nominal/ordinal).
+    if y_type in ("nominal", "ordinal") and isinstance(y_enc.get("axis"), dict):
+        y_enc["axis"]["orient"] = effective.axis_y.categorical_orient
+    elif y_type in ("nominal", "ordinal"):
+        y_enc["axis"] = {"orient": effective.axis_y.categorical_orient}
+
+    # Resolve bar mark for the padding field (lives in BarMarkStyle, not BarChartStyle).
+    bar_mark = resolve_mark(effective.marks.bar, bar.marks.bar)
+
+    # Wire band padding on the categorical axis encoding scale.
+    # Chart-local ScaleStyle.band_padding_inner wins; bar_mark.padding is the fallback.
+    # Note: VL only honors ``paddingInner`` (not ``bandPaddingInner``) at the
+    # encoding-level scale — see SCALE_FIELD_MAP.
+    #
+    # For grouped bars (xOffset/yOffset): paddingInner creates a visible gap between
+    # groups; paddingOuter prevents the outermost groups from running to the plot edge
+    # and colliding with axis labels.
+    if resolved_chart.orientation == "horizontal":
+        if is_grouped_bar(resolved_chart):
+            _apply_grouped_bar_scale_padding(y_enc)
+        else:
+            y_enc.setdefault("scale", {}).setdefault("paddingInner", bar_mark.padding)
+    else:
+        x_enc = encoding.get("x")
+        if x_enc and x_enc.get("type") in ("nominal", "ordinal"):
+            if is_grouped_bar(resolved_chart):
+                _apply_grouped_bar_scale_padding(x_enc)
+            else:
+                x_enc.setdefault("scale", {}).setdefault(
+                    "paddingInner", bar_mark.padding
+                )
+
+
+def _first_field(value: str | list[str] | None) -> str | None:
+    """Return the first field from a possible multi-field definition."""
+    if isinstance(value, list):
+        return value[0] if value else None
+    return value
+
+
+def _map_secondary_channels(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    channels: tuple[str, ...] = ("color", "size", "shape"),
+) -> dict[str, Any]:
+    """Map secondary encoding channels (color, size, shape) through map_other_encoding."""
+    encoding: dict[str, Any] = {}
+    for channel in channels:
+        ch_enc = map_other_encoding(channel, resolved_chart, data)
+        if ch_enc:
+            encoding[channel] = ch_enc
+    return encoding
+
+
+def _build_standard_encoding(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    theme: str | None,
+    y_field: str | None = None,
+) -> dict[str, Any]:
+    """Build the canonical standard encoding for cartesian profiled charts."""
+    routing = _build_axis_routing(resolved_chart)
+    encoding: dict[str, Any] = {}
+    x_enc = map_x_encoding(resolved_chart, data, routing=routing)
+    if x_enc:
+        encoding["x"] = x_enc
+    y_enc = map_y_encoding(resolved_chart, data, y_field=y_field, routing=routing)
+    if y_enc:
+        encoding["y"] = y_enc
+    for channel in ("color", "size", "shape"):
+        ch_enc = map_other_encoding(channel, resolved_chart, data)
+        if ch_enc:
+            encoding[channel] = ch_enc
+
+    for src, dst in (
+        ("opacity", "opacity"),
+        ("stroke_color", "stroke"),
+        ("stroke_width", "strokeWidth"),
+    ):
+        ch = resolved_chart.resolved_channels.get(src)
+        if ch is not None and (vl_enc := _resolved_channel_to_vl(ch)):
+            encoding[dst] = vl_enc
+
+    _apply_dash_encoding(resolved_chart, encoding)
+    _apply_chart_sort(resolved_chart, encoding)
+    _apply_bar_axis_defaults(resolved_chart, encoding)
+    _apply_stack_encoding(resolved_chart, encoding)
+
+    # Ensure the measure channel carries the tooltip format so vl-convert renders
+    # formatted numbers in bar element aria-labels (e.g. "Count: 5.00" not "Count: 5").
+    # Do NOT touch axis.format — that drives the scale-domain description, which
+    # uses its own existing format (or default integer rendering).
+    measure_ch = _measure_vl_channel(resolved_chart)
+    menc = encoding.get(measure_ch, {})
+    if menc.get("type") == "quantitative":
+        fmt = resolve_format(
+            resolved_chart.resolved_style.tooltip.format,
+            resolved_chart.resolved_style.formats,
+        )
+        if fmt:
+            menc.setdefault("format", fmt)
+
+    return encoding
+
+
+# ── Per-family mapping ───────────────────────────────────────────────
+
+
+def _map_histogram(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+) -> MappedChart:
+    """Map histogram: bar mark with binned x and aggregate count y."""
+    mark = _map_mark(resolved_chart)
+    effective = resolved_chart.resolved_style
+    encoding: dict[str, Any] = {}
+    if resolved_chart.x:
+        encoding["x"] = {
+            "field": resolved_chart.x,
+            "type": "quantitative",
+            "bin": True,
+            "title": format_display_text(
+                resolved_chart.x, from_slug=True, font=effective.axis_x.title.font
+            ),
+        }
+    encoding["y"] = {"aggregate": "count", "type": "quantitative", "title": "Count"}
+    # Histogram only supports color grouping; size/shape not applicable for binned bars
+    encoding.update(_map_secondary_channels(resolved_chart, data, ("color",)))
+    return MappedChart(mark=mark, encoding=encoding)
+
+
+def _map_boxplot(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+) -> MappedChart:
+    """Map boxplot: composite mark with nominal x and quantitative y."""
+    mark = _map_mark(resolved_chart)
+    mark["extent"] = "min-max"
+    effective = resolved_chart.resolved_style
+    encoding: dict[str, Any] = {}
+    if resolved_chart.x:
+        encoding["x"] = {
+            "field": resolved_chart.x,
+            "type": "nominal",
+            "title": format_display_text(
+                resolved_chart.x, from_slug=True, font=effective.axis_x.title.font
+            ),
+            "axis": _build_encoding_axis(
+                effective,
+                "axis_x",
+                "nominal",
+                _chart_type_axis_patch(effective, "boxplot", "axis_x"),
+            ),
+        }
+    y_field = _first_field(resolved_chart.y)
+    if y_field:
+        encoding["y"] = {
+            "field": y_field,
+            "type": "quantitative",
+            "title": format_display_text(
+                y_field, from_slug=True, font=effective.axis_y.title.font
+            ),
+        }
+        fmt = resolve_format(
+            resolved_chart.resolved_style.tooltip.format,
+            resolved_chart.resolved_style.formats,
+        )
+        if fmt:
+            encoding["y"]["format"] = fmt
+    # Boxplot composite mark: only color grouping is meaningful
+    encoding.update(_map_secondary_channels(resolved_chart, data, ("color",)))
+    return MappedChart(mark=mark, encoding=encoding)
+
+
+def _map_error(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+) -> MappedChart:
+    """Map errorbar/errorband: composite mark with inferred x type and quantitative y."""
+    mark = _map_mark(resolved_chart)
+    effective = resolved_chart.resolved_style
+    encoding: dict[str, Any] = {}
+    if resolved_chart.x:
+        columns = set(data[0].keys()) if data else set()
+        x_type = (
+            infer_vega_type_from_data(data, resolved_chart.x)
+            if resolved_chart.x in columns
+            else "nominal"
+        )
+        encoding["x"] = {
+            "field": resolved_chart.x,
+            "type": x_type,
+            "title": format_display_text(
+                resolved_chart.x, from_slug=True, font=effective.axis_x.title.font
+            ),
+        }
+    y_field = _first_field(resolved_chart.y)
+    if y_field:
+        encoding["y"] = {
+            "field": y_field,
+            "type": "quantitative",
+            "title": format_display_text(
+                y_field, from_slug=True, font=effective.axis_y.title.font
+            ),
+        }
+        fmt = resolve_format(
+            resolved_chart.resolved_style.tooltip.format,
+            resolved_chart.resolved_style.formats,
+        )
+        if fmt:
+            encoding["y"]["format"] = fmt
+    # Error composite mark: only color grouping is meaningful
+    encoding.update(_map_secondary_channels(resolved_chart, data, ("color",)))
+    return MappedChart(mark=mark, encoding=encoding)
+
+
+def _map_slice(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+) -> MappedChart:
+    """Map arc/pie: arc mark with theta, optional color and inner_radius.
+
+    Layered emission triggers when ``resolved_chart.total`` (donut center
+    summary) is set.  Pixel positioning uses ``width/2`` / ``height/2``
+    expressions so the layout matches whatever size the renderer chooses.
+    """
+    chart_id = resolved_chart.id or "unknown"
+    if not resolved_chart.theta:
+        raise ChartDataError(
+            f"Arc chart '{chart_id}' requires a 'theta' field naming the numeric column",
+            chart_id=chart_id,
+        )
+    arc_mark = _map_mark(resolved_chart)
+    # Disk-size policy: the disk fills 90% of the plot area's shorter
+    # dimension, regardless of label presence. Disk size becomes a function
+    # of cell, not data — a row of donuts produces a row of uniformly
+    # sized disks regardless of sector count. The 10% margin is a visual-
+    # breathing-room gutter; it does NOT functionally contain wedge labels
+    # (those extend beyond the disk via VL plot-area auto-padding anyway).
+    outer_fraction = 0.9
+    arc_mark["outerRadius"] = {"expr": f"min(width, height) / 2 * {outer_fraction}"}
+    # ``inner_radius`` is the ratio of inner hole to outer disk (i.e. the
+    # rendered inner/outer ratio), NOT a fraction of cell-half. Multiply by
+    # ``outer_fraction`` so the rendered ring respects both the disk-size
+    # policy and the configured hole proportion independently.
+    inner_ratio = resolved_chart.resolved_style.pie.inner_radius
+    if inner_ratio is not None and inner_ratio > 0:
+        arc_mark["innerRadius"] = {
+            "expr": f"min(width, height) / 2 * {outer_fraction} * {inner_ratio}"
+        }
+    else:
+        # No author-set inner_radius → solid pie. Set explicitly so VL
+        # doesn't pick up any inherited innerRadius from a parent layer.
+        arc_mark["innerRadius"] = 0
+
+    arc_encoding: dict[str, Any] = {
+        "theta": {
+            "field": resolved_chart.theta,
+            "type": "quantitative",
+            "title": format_display_text(
+                resolved_chart.theta,
+                from_slug=True,
+                font=resolved_chart.resolved_style.legend.title.font,
+            ),
+        },
+    }
+    fmt = resolve_format(
+        resolved_chart.resolved_style.tooltip.format,
+        resolved_chart.resolved_style.formats,
+    )
+    if fmt:
+        arc_encoding["theta"]["format"] = fmt
+    # Arc marks: only color (category) is meaningful; size/shape don't apply
+    arc_encoding.update(_map_secondary_channels(resolved_chart, data, ("color",)))
+
+    # Always augment arc data with __dft_row_idx + __dft_pct + angle meta and
+    # pin the arc order encoding to data insertion sequence — even when this
+    # function early-returns below (no total, no labels). Without it, VL
+    # palette-assigns alphabetically over the color domain while drawing
+    # slices in data-row order, which silently desyncs the attached-table
+    # swatches (palette[idx] in data order) from the rendered wedges. The
+    # color.sort: false below is also necessary for the same reason; hoisted
+    # together so the early-return path gets both.
+    data_override = _augment_arc_label_data(resolved_chart, data)
+    arc_encoding["order"] = {"field": "__dft_row_idx", "type": "quantitative"}
+    if "color" in arc_encoding:
+        arc_encoding["color"]["sort"] = False
+
+    if resolved_chart.total is None and resolved_chart.labels is None:
+        return MappedChart(
+            mark=arc_mark, encoding=arc_encoding, data_override=data_override
+        )
+
+    pie_style = resolved_chart.resolved_style.pie
+    theta_field = resolved_chart.theta
+    sum_field = "__dft_arc_total"
+
+    layers: list[MappedLayer] = [MappedLayer(mark=arc_mark, encoding=arc_encoding)]
+
+    if resolved_chart.total is not None:
+        value_text_mark: dict[str, Any] = {
+            "type": "text",
+            "align": "center",
+            "baseline": "bottom",
+            "tooltip": False,
+        }
+        _apply_font_to_mark(value_text_mark, pie_style.total.value.font)
+        value_text_encoding: dict[str, Any] = {
+            "text": {"field": sum_field, "type": "quantitative"},
+            "x": {"value": {"expr": "width / 2"}},
+            "y": {"value": {"expr": "height / 2"}},
+        }
+        if resolved_chart.total.format is not None:
+            resolved_fmt = resolve_format(
+                resolved_chart.total.format,
+                resolved_chart.resolved_style.formats,
+            )
+            if resolved_fmt is not None:
+                value_text_encoding["text"]["format"] = resolved_fmt
+        layers.append(
+            MappedLayer(
+                mark=value_text_mark,
+                encoding=value_text_encoding,
+                transform=(
+                    {
+                        "joinaggregate": [
+                            {"op": "sum", "field": theta_field, "as": sum_field}
+                        ]
+                    },
+                    {"window": [{"op": "row_number", "as": "__dft_arc_row"}]},
+                    {"filter": "datum.__dft_arc_row === 1"},
+                ),
+            )
+        )
+        if resolved_chart.total.label is not None:
+            label_mark: dict[str, Any] = {
+                "type": "text",
+                "align": "center",
+                "baseline": "top",
+                "tooltip": False,
+            }
+            _apply_font_to_mark(label_mark, pie_style.total.label.font)
+            layers.append(
+                MappedLayer(
+                    mark=label_mark,
+                    encoding={
+                        "text": {"value": resolved_chart.total.label},
+                        "x": {"value": {"expr": "width / 2"}},
+                        "y": {"value": {"expr": "height / 2"}},
+                    },
+                    transform=(
+                        {"window": [{"op": "row_number", "as": "__dft_arc_row"}]},
+                        {"filter": "datum.__dft_arc_row === 1"},
+                    ),
+                )
+            )
+
+    # Resolved color channel: the `color:` channel mapped to a data field.
+    # ``data_field is not None`` (rather than just ``color_ch is not None``)
+    # is the per-series-color predicate — a color channel can exist with a
+    # literal stop and no field, in which case there are no series to bind.
+    color_ch = resolved_chart.resolved_channels.get("color")
+    series_color_field = (
+        color_ch.data_field
+        if color_ch is not None and color_ch.data_field is not None
+        else None
+    )
+
+    if resolved_chart.labels is not None:
+        slice_mark = resolve_mark(
+            resolved_chart.resolved_style.marks.slice, pie_style.marks.slice
+        )
+        labels_style = slice_mark.labels
+        offset = labels_style.offset
+        block_height = labels_style.block_height
+        label_mark_dict: dict[str, Any] = {
+            "type": "text",
+            "baseline": "top",
+            "lineHeight": labels_style.line_height,
+            "tooltip": False,
+            "align": {"expr": "datum.__dft_right ? 'left' : 'right'"},
+        }
+        # Apply font properties; whether ``font.color`` becomes ``mark.fill``
+        # depends on whether a per-series color encoding will drive label
+        # color (see below). A static ``fill`` on a text mark overrides any
+        # color channel encoding in VL, so we must skip it in the per-series
+        # case — same contract as ``series_label`` in theme YAML.
+        _apply_font_to_mark(
+            label_mark_dict,
+            labels_style.font,
+            skip_color=series_color_field is not None,
+        )
+        label_encoding: dict[str, Any] = {
+            "text": {"field": "__dft_label", "type": "nominal"},
+            "x": {
+                "field": "__dft_x",
+                "type": "quantitative",
+                "scale": None,
+                "axis": None,
+            },
+            "y": {
+                "field": "__dft_y_anchored",
+                "type": "quantitative",
+                "scale": None,
+                "axis": None,
+            },
+        }
+        if series_color_field is not None:
+            # Dark-companion ink: match each slice's bright palette stop to its
+            # readable darker counterpart so labels carry series identity at
+            # the same contrast level endpoint labels use on line/area charts.
+            # Domain order mirrors arc's data-insertion order (the arc encoding
+            # sets ``sort: false``); palette[:n] indexes that same order.
+            seen: list[str] = []
+            for row in data_override or data:
+                v = row.get(series_color_field)
+                if v is None:
+                    continue
+                s = str(v)
+                if s not in seen:
+                    seen.append(s)
+            palette = list(resolved_chart.resolved_style.palette)
+            dark_stops = resolve_dark_companion_stops(palette[: len(seen)])
+            label_encoding["color"] = {
+                "field": series_color_field,
+                "type": "nominal",
+                "scale": {"domain": seen, "range": dark_stops},
+                "sort": False,
+                "legend": None,
+            }
+        from dataface.core.render.chart.arc_attached_table import (
+            WEDGE_LABEL_MIN_SHARE,
+        )
+
+        label_transforms = (
+            # ``where:``-filtered rows have __dft_label = null. Drop them
+            # before computing positions so VL doesn't render an empty
+            # text mark at every filtered slice's anchor.
+            {"filter": "datum.__dft_label != null"},
+            # Suppress per-wedge labels for small wedges. Even with a clean
+            # tier+visible-count trigger above, individual slim wedges that
+            # squeak through (e.g. an 11% wedge next to a 50% wedge) shed
+            # their label here so callouts don't crowd at near-cardinal
+            # angles. Wedge still renders; hover tooltip carries the value.
+            {"filter": f"datum.__dft_pct > {WEDGE_LABEL_MIN_SHARE}"},
+            # Labels sit at (disk_outer_radius + offset). The disk fills the
+            # cell to ``outer_fraction``; labels live in the gutter just
+            # outside the disk, INSIDE the cell. Without the same
+            # ``outer_fraction`` factor here, VL would reserve plot-area room
+            # for labels beyond the cell edge and shrink the disk to fit.
+            {
+                "calculate": (
+                    f"width / 2 + sin(datum.__dft_mid) * "
+                    f"(min(width, height) / 2 * {outer_fraction} + {offset})"
+                ),
+                "as": "__dft_x",
+            },
+            {
+                "calculate": (
+                    f"height / 2 - cos(datum.__dft_mid) * "
+                    f"(min(width, height) / 2 * {outer_fraction} + {offset})"
+                ),
+                "as": "__dft_y",
+            },
+            {
+                "calculate": (
+                    f"datum.__dft_y + (datum.__dft_top ? -{block_height} : 0)"
+                ),
+                "as": "__dft_y_anchored",
+            },
+        )
+        layers.append(
+            MappedLayer(
+                mark=label_mark_dict,
+                encoding=label_encoding,
+                transform=label_transforms,
+            )
+        )
+
+    # VL layered specs share the color scale across layers by default. The
+    # label layer's dark-companion scale would otherwise reach back into the
+    # arc layer and dim the slices to label ink — declare the color scale
+    # independent when per-series label color is in play.
+    derived_resolve: dict[str, Any] | None = None
+    if resolved_chart.labels is not None and series_color_field is not None:
+        derived_resolve = {"scale": {"color": "independent"}}
+
+    return MappedChart(
+        layers=tuple(layers),
+        data_override=data_override,
+        derived_resolve=derived_resolve,
+    )
+
+
+def _coerce_numeric(value: Any) -> Any:
+    """Coerce a CSV-string number to int or float; pass everything else through.
+
+    CSV adapters return raw strings (``"60"``); we want ``int(60)`` so
+    ``{{ value }}`` renders as ``"60"`` rather than ``"60.0"``. Float-shaped
+    strings (``"60.5"``) become ``float``. Non-string / unparseable values
+    pass through unchanged so callers see the surface error rather than a
+    silently coerced value.
+    """
+    if not isinstance(value, str):
+        return value
+    s = value.strip()
+    if not s:
+        return value
+    try:
+        return int(s)
+    except ValueError:
+        pass
+    try:
+        return float(s)
+    except ValueError:
+        return value
+
+
+def _augment_arc_label_data(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Walk arc data; pre-compute angles + (optionally) render label templates.
+
+    Always emits the angle metadata fields the arc renderer relies on:
+    ``__dft_row_idx`` (for the arc ``order`` encoding — pins draw order to
+    data insertion sequence so swatch tables can match), ``__dft_pct``,
+    ``__dft_total``, ``__dft_mid``, ``__dft_top``, ``__dft_right``.
+
+    When ``resolved_chart.labels`` is set, additionally renders the Jinja
+    template per row and emits ``__dft_label``. When labels is None
+    (attached-table mode strips them), the label rendering step is
+    skipped so the donut still draws in the correct order without a
+    label layer.
+    """
+    import math
+
+    from dataface.core.render.chart.labels import prepare_label_data
+    from dataface.core.render.utils import normalize_data_types
+
+    data = normalize_data_types(data)
+    theta_field = resolved_chart.theta or ""
+    color_ch = resolved_chart.resolved_channels.get("color")
+    color_field = color_ch.data_field if color_ch is not None else None
+    total = sum(float(row.get(theta_field, 0) or 0) for row in data)
+    # Compute mid-angle per row using the arc's natural (data-order) draw.
+    running = 0.0
+    angle_meta: list[dict[str, float | bool]] = []
+    for row in data:
+        v = float(row.get(theta_field, 0) or 0)
+        share = v / total if total else 0.0
+        mid = 2 * math.pi * (running + v / 2.0) / total if total else 0.0
+        angle_meta.append(
+            {
+                "__dft_total": total,
+                "__dft_pct": share,
+                "__dft_mid": mid,
+                "__dft_top": math.cos(mid) >= 0,
+                "__dft_right": math.sin(mid) >= 0,
+                "__dft_row_idx": len(angle_meta),
+            }
+        )
+        running += v
+
+    if resolved_chart.labels is None:
+        # Attached-table mode: caller suppressed labels. Skip the Jinja
+        # template render and just return data augmented with the angle
+        # metadata (sufficient for the arc layer's order encoding).
+        return [{**row, **angle_meta[idx]} for idx, row in enumerate(data)]
+
+    def _extras(row: dict[str, Any], index: int) -> dict[str, Any]:
+        meta = angle_meta[index]
+        # Pass the raw row value through. CSV adapter strings are coerced to
+        # float only when arithmetic forces it (Jinja's ``{{ value / 1000 }}``
+        # still works on numeric strings via Python's int/float promotion);
+        # author-side ``{{ value }}`` keeps int → "60" rather than "60.0".
+        return {
+            "percent": meta["__dft_pct"],
+            "value": _coerce_numeric(row.get(theta_field)),
+            "total": total,
+            "color": row.get(color_field) if color_field else None,
+        }
+
+    rendered = prepare_label_data(data, resolved_chart.labels, context_extras=_extras)
+    out: list[dict[str, Any]] = []
+    for idx, row in enumerate(rendered):
+        merged = dict(row)
+        merged.update(angle_meta[idx])
+        out.append(merged)
+    return out
+
+
+def _apply_font_to_mark(
+    mark: dict[str, Any], font: Any, skip_color: bool = False
+) -> None:
+    """Copy non-None font fields onto a VL text mark dict.
+
+    When ``skip_color`` is True, ``font.color`` is NOT copied to ``mark.fill``
+    — caller intends to drive label color via an encoding instead. VL gives
+    ``mark.fill`` precedence over any ``color`` channel on text marks, so a
+    static fill would silently win and collapse per-series labels to one ink.
+    """
+    if font.family is not None:
+        mark["font"] = font.family
+    if font.size is not None:
+        mark["fontSize"] = font.size
+    if font.weight is not None:
+        mark["fontWeight"] = font.weight
+    if font.color is not None and not skip_color:
+        mark["fill"] = font.color
+
+
+def _map_rect(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+) -> MappedChart:
+    """Map rect/square/heatmap: grid mark with nominal x/y and quantitative color."""
+    mark = _map_mark(resolved_chart)
+    effective = resolved_chart.resolved_style
+    encoding: dict[str, Any] = {}
+    if resolved_chart.x:
+        encoding["x"] = {
+            "field": resolved_chart.x,
+            "type": "nominal",
+            "title": format_display_text(
+                resolved_chart.x, from_slug=True, font=effective.axis_x.title.font
+            ),
+            "axis": _build_encoding_axis(
+                effective,
+                "axis_x",
+                "nominal",
+                _chart_type_axis_patch(effective, resolved_chart.chart_type, "axis_x"),
+            ),
+        }
+    y_field = _first_field(resolved_chart.y)
+    if y_field:
+        encoding["y"] = {
+            "field": y_field,
+            "type": "nominal",
+            "title": format_display_text(
+                y_field, from_slug=True, font=effective.axis_y.title.font
+            ),
+        }
+    # Rect/heatmap: color and size are meaningful; shape doesn't apply
+    encoding.update(_map_secondary_channels(resolved_chart, data, ("color", "size")))
+    if "color" in encoding and resolved_chart.chart_type == "heatmap":
+        encoding["color"]["scale"] = {
+            "scheme": resolved_chart.resolved_style.heatmap.color_scheme
+        }
+    # Rect/heatmap color typically encodes a quantitative measure; carry the
+    # tooltip format so aria-labels render formatted numbers (e.g.
+    # "Value: 1,234.56" not "Value: 1234.56").
+    color_enc = encoding.get("color")
+    if color_enc and color_enc.get("type") == "quantitative":
+        fmt = resolve_format(
+            resolved_chart.resolved_style.tooltip.format,
+            resolved_chart.resolved_style.formats,
+        )
+        if fmt:
+            color_enc.setdefault("format", fmt)
+    return MappedChart(mark=mark, encoding=encoding)
+
+
+def _map_line(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    theme: str | None = None,
+    background: str | None = None,
+) -> MappedChart:
+    """Map a single-series line chart, emitting halo layers when configured.
+
+    A ``halo_multiplier`` of 0 or a missing background falls back to the plain
+    single-mark line; otherwise the chart is emitted as 2 line layers (halo +
+    foreground), and as 4 layers when points are enabled (knockout halo
+    points + foreground points). The halo's stroke is set to the chart's
+    effective background so crossings read cleanly against the canvas.
+    """
+    encoding = _build_standard_encoding(resolved_chart, data, theme)
+    charts = resolved_chart.resolved_style
+    line_style = charts.line
+    line_marks = line_style.marks
+    line_mark = resolve_mark(charts.marks.line, line_marks.line)
+    point_mark = resolve_mark(charts.marks.point, line_marks.point)
+
+    if line_mark.halo_multiplier <= 0 or background is None:
+        mark = {**_map_mark(resolved_chart), "aria": False}
+        return MappedChart(
+            encoding=encoding,
+            layers=(
+                MappedLayer(mark=mark),
+                MappedLayer(mark=_hover_overlay_point()),
+            ),
+        )
+
+    from dataface.core.render.chart.vl_field_maps import (
+        _emit_point_mark,
+        line_mark_to_vl,
+    )
+
+    # LineMarkStyle guarantees stroke.width is not None.
+    assert line_mark.stroke.width is not None
+    halo_width = line_mark.stroke.width * line_mark.halo_multiplier
+    # Canonical mapper covers all mark fields (stroke, interpolate, etc.).
+    # Halo overrides stroke/strokeWidth with background color and wider width;
+    # fg inherits them as-is. New StrokeStyle fields flow automatically.
+    mark_vl = line_mark_to_vl(line_mark)
+    # Force opacity to 1 on every halo channel. Some themes set per-mark
+    # opacity defaults (e.g. line.opacity, point.opacity for soft scatter
+    # styling) that would otherwise modulate the halo and let the colored
+    # foreground bleed through, which defeats the knockout effect.
+    halo_line = {
+        "type": "line",
+        **mark_vl,
+        # Override: halo uses background color and wider stroke.
+        "stroke": background,
+        "strokeWidth": halo_width,
+        "opacity": 1,
+        "strokeOpacity": 1,
+        "tooltip": False,
+        # Halo protrudes past the fg stroke — suppress its aria-label so the
+        # edge band between data points doesn't trigger a first-datum tooltip.
+        "aria": False,
+    }
+    # aria: False suppresses the single-path first-datum aria-label; the
+    # transparent point overlay below provides per-datum labels instead.
+    fg_line = {"type": "line", **mark_vl, "tooltip": True, "aria": False}
+
+    # Layer order: ALL halo layers first, then ALL foreground layers, so the
+    # foreground line is never occluded by a point halo at the data points.
+    # The invisible point overlay sits last so it captures mouse events.
+    layers: list[MappedLayer] = [MappedLayer(mark=halo_line)]
+
+    if point_mark.size > 0:
+        halo_size = point_mark.size * line_mark.halo_multiplier
+        layers.append(
+            MappedLayer(
+                mark={
+                    "type": "point",
+                    "filled": True,
+                    "fill": background,
+                    "stroke": background,
+                    "size": halo_size,
+                    "opacity": 1,
+                    "fillOpacity": 1,
+                    "strokeOpacity": 1,
+                    "tooltip": False,
+                }
+            )
+        )
+
+    layers.append(MappedLayer(mark=fg_line))
+
+    if point_mark.size > 0:
+        layers.append(
+            MappedLayer(
+                mark={
+                    "type": "point",
+                    **_emit_point_mark(point_mark),
+                    # Force opacity 1: theme circle/scatter configs default to 0.7,
+                    # and VL applies those to 'point' marks too. A semi-transparent
+                    # foreground point lets the halo bleed through.
+                    "opacity": 1,
+                    "fillOpacity": 1,
+                    "strokeOpacity": 1,
+                    "tooltip": True,
+                }
+            )
+        )
+
+    layers.append(MappedLayer(mark=_hover_overlay_point()))
+
+    return MappedChart(encoding=encoding, layers=tuple(layers))
+
+
+def _map_area(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    theme: str | None = None,
+    background: str | None = None,
+) -> MappedChart:
+    """Map an area chart, emitting a halo undercoat layer for multi-series.
+
+    Single-series area is a flat single mark. Multi-series area (series
+    color encoding) gets a cream-knockout undercoat per series so the
+    soft colored fills don't mix where they overlap; the colored areas
+    sit on top at the resolved area opacity. Mirrors the line family's
+    halo, but for area marks.
+
+    Fill and stroke are emitted as separate layers so that
+    ``_inject_zero_baseline_rule`` can insert the zero baseline between
+    the fg fill and the fg stroke:
+    [halo_fill, halo_stroke, fg_fill, zero_rule, fg_stroke, hover_overlay].
+    Halo layers precede their fg counterparts so the knockout undercoat
+    renders behind the colored fill; the fg stroke sits above the baseline rule.
+    """
+    encoding = _build_standard_encoding(resolved_chart, data, theme)
+    charts = resolved_chart.resolved_style
+    area_style = charts.area
+    area_marks = area_style.marks
+    area_mark = resolve_mark(charts.marks.area, area_marks.area)
+
+    # Apply the area family's stack default when the chart didn't author one.
+    # ``_apply_stack_encoding`` only fires for non-None ``chart.stack`` and
+    # leaves the encoding bare otherwise — VL would then default to
+    # ``stack: "zero"`` for area marks. Theme YAML's ``area.stack`` lets the
+    # area family default to overlapping (false) without each chart
+    # re-authoring it. Pin on the measure channel so the rule is symmetric
+    # with ``_apply_stack_encoding`` (area today never swaps orientation, so
+    # this resolves to ``"y"``; the helper keeps the contract explicit).
+    measure_channel = _measure_vl_channel(resolved_chart)
+    if resolved_chart.stack is None and "stack" not in encoding.get(
+        measure_channel, {}
+    ):
+        if area_style.stack is False:
+            encoding.setdefault(measure_channel, {})["stack"] = None
+        elif isinstance(area_style.stack, str):
+            encoding.setdefault(measure_channel, {})["stack"] = area_style.stack
+
+    color_ch = resolved_chart.resolved_channels.get("color")
+    is_multi_series = (
+        color_ch is not None and color_ch.mode == "series" and bool(color_ch.data_field)
+    )
+
+    from dataface.core.render.chart.vl_field_maps import _stroke_to_vl
+
+    if area_mark.halo_multiplier <= 0 or background is None:
+        # No halo: fill-only area + separate line mark for top-edge stroke.
+        # Suppress the area boundary stroke; the line mark carries it instead.
+        base = {**_map_mark(resolved_chart), "aria": False}
+        area_fill = {
+            k: v
+            for k, v in base.items()
+            if k
+            not in ("stroke", "strokeWidth", "strokeCap", "strokeJoin", "strokeDash")
+        }
+        area_fill["strokeOpacity"] = 0
+        fg_line = {
+            "type": "line",
+            "strokeCap": "round",
+            "strokeJoin": "round",
+            **_stroke_to_vl(area_mark.stroke),
+            "aria": False,
+            "tooltip": True,
+        }
+        return MappedChart(
+            encoding=encoding,
+            layers=(
+                MappedLayer(mark=area_fill),
+                # zero rule injected by _inject_zero_baseline_rule after the area layer
+                MappedLayer(mark=fg_line),
+                MappedLayer(mark=_hover_overlay_point()),
+            ),
+        )
+
+    # Halo stroke width mirrors the line halo pattern: wider background-color
+    # stroke drawn before the colored foreground so crossings read cleanly.
+    # AreaMarkStyle guarantees stroke.width is not None.
+    assert area_mark.stroke.width is not None
+    halo_stroke_width = area_mark.stroke.width * area_mark.halo_multiplier
+
+    # Fill-only area marks. strokeOpacity: 0 suppresses the area boundary
+    # stroke; separate line marks below carry the top-edge stroke so that
+    # _inject_zero_baseline_rule can place the zero rule between fill and stroke.
+    halo_area_fill = {
+        "type": "area",
+        "fill": background,
+        "opacity": 1,
+        "fillOpacity": 1,
+        "strokeOpacity": 0,
+        "tooltip": False,
+        # Halo protrudes past the fg stroke — suppress its aria-label for the
+        # same reason as halo_line: it carries a first-datum label on the
+        # single area path and would trigger in the edge bands.
+        "aria": False,
+    }
+    # Mark-level ``opacity`` multiplies fill/stroke opacities, so we keep
+    # it at 1 and push the soft tint into ``fillOpacity`` only — that way
+    # the colored stroke renders at full intensity over a soft fill.
+    # aria: False suppresses the single-path first-datum aria-label; the
+    # transparent point overlay below provides per-datum labels instead.
+    fg_area_fill = {
+        "type": "area",
+        "opacity": 1,
+        "tooltip": True,
+        "aria": False,
+        "fillOpacity": area_mark.opacity,
+        "strokeOpacity": 0,
+    }
+
+    # Separate stroke (line) layers. Previously these were embedded via
+    # ``area.line: {...}`` which bundled fill + stroke into one VL layer,
+    # making it impossible to insert the zero rule between them.
+    # Note: a VL ``line`` mark on the same encoding as the area mark traces
+    # the same data path as the area's top edge for non-stacked areas.
+    halo_line_mark = {
+        "type": "line",
+        "stroke": background,
+        "strokeWidth": halo_stroke_width,
+        "strokeCap": "round",
+        "strokeJoin": "round",
+        "tooltip": False,
+        "aria": False,
+    }
+    fg_line_mark = {
+        "type": "line",
+        # Aesthetic defaults for area top-edge line; model overrides win.
+        "strokeCap": "round",
+        "strokeJoin": "round",
+        **_stroke_to_vl(area_mark.stroke),
+        "aria": False,
+        "tooltip": True,
+    }
+
+    if is_multi_series:
+        # The halo layers override the inherited color encoding to a constant
+        # background fill/stroke, but keep series grouping via ``detail`` so
+        # each series gets its own silhouette beneath its colored counterpart.
+        assert (
+            color_ch is not None and color_ch.data_field
+        )  # narrowed by is_multi_series
+        halo_encoding: dict[str, Any] = {
+            "color": {"value": background},
+            "detail": {"field": color_ch.data_field, "type": "nominal"},
+        }
+        return MappedChart(
+            encoding=encoding,
+            layers=(
+                MappedLayer(mark=halo_area_fill, encoding=halo_encoding),
+                MappedLayer(mark=halo_line_mark, encoding=halo_encoding),
+                MappedLayer(mark=fg_area_fill),
+                # zero rule injected by _inject_zero_baseline_rule after last area layer
+                MappedLayer(mark=fg_line_mark),
+                MappedLayer(mark=_hover_overlay_point()),
+            ),
+        )
+
+    # Single-series: halo fill + halo stroke + fg fill + (zero rule) + fg stroke + hover overlay.
+    return MappedChart(
+        encoding=encoding,
+        layers=(
+            MappedLayer(mark=halo_area_fill),
+            MappedLayer(mark=halo_line_mark),
+            MappedLayer(mark=fg_area_fill),
+            # zero rule injected by _inject_zero_baseline_rule after last area layer
+            MappedLayer(mark=fg_line_mark),
+            MappedLayer(mark=_hover_overlay_point()),
+        ),
+    )
+
+
+def _map_layered_chart(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    theme: str | None = None,
+) -> MappedChart:
+    """Map a multi-metric profiled chart into a single layered profile contract."""
+    y_fields = resolved_chart.y
+    if not isinstance(y_fields, list):
+        raise TypeError("_map_layered_chart requires a multi-field y definition")
+
+    base_encoding = _build_standard_encoding(
+        resolved_chart,
+        data,
+        theme,
+        y_field=None,
+    )
+    base_encoding.pop("y", None)
+
+    layers: list[MappedLayer] = []
+    for metric in y_fields:
+        layer_encoding = dict(base_encoding)
+        # skip_tick_values: each layer maps its own metric range; per-layer
+        # axis.values conflict on the shared y-scale. Callers must compute
+        # tick values from the full union extent across all metrics separately.
+        y_encoding = map_y_encoding(
+            resolved_chart, data, y_field=metric, skip_tick_values=True
+        )
+        if y_encoding is None:
+            chart_id = resolved_chart.id or "unknown"
+            raise ChartDataError(
+                f"Layered chart '{chart_id}' could not map y field '{metric}'",
+                chart_id=chart_id,
+            )
+        layer_encoding["y"] = y_encoding
+        _apply_stack_encoding(resolved_chart, layer_encoding)
+
+        if (
+            resolved_chart.chart_type in {"line", "area"}
+            and "color" not in layer_encoding
+        ):
+            effective = resolved_chart.resolved_style
+            color_enc: dict[str, Any] = {
+                "datum": format_display_text(
+                    metric, from_slug=True, font=effective.legend.title.font
+                )
+            }
+            legend = _build_encoding_legend(effective)
+            if legend is not None or effective.legend.disable is True:
+                color_enc["legend"] = legend
+            layer_encoding["color"] = color_enc
+
+        mark = _map_mark(resolved_chart)
+        if resolved_chart.chart_type in {"line", "area"}:
+            # Suppress the single-path first-datum aria-label; the point overlay
+            # appended below provides per-datum labels for each metric.
+            mark = {**mark, "aria": False}
+        layers.append(MappedLayer(mark=mark, encoding=layer_encoding))
+
+        if resolved_chart.chart_type in {"line", "area"}:
+            # Each line/area metric gets its own invisible point overlay so the
+            # JS hover layer resolves to individual data points.
+            layers.append(
+                MappedLayer(mark=_hover_overlay_point(), encoding=layer_encoding)
+            )
+
+    return MappedChart(encoding=base_encoding, layers=tuple(layers))
+
+
+def _map_explicit_layered_chart(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    theme: str | None = None,
+    datasets: dict[str, list[dict[str, Any]]] | None = None,
+) -> MappedChart:
+    """Map an explicit ``type: layered`` chart into a layered profile contract.
+
+    Each authored layer specifies its own mark type and may override
+    parent-level channels.  Parent-level ``x``, ``color``, ``size``,
+    ``shape`` supply shared defaults; per-layer ``y``, ``color``, etc.
+    take precedence when present.
+
+    When layers carry per-layer ``query_name`` / ``x``, each layer is
+    tagged with a ``data_name`` and gets its own x encoding derived from
+    its own dataset.  The resulting ``MappedChart.datasets`` dict is used
+    by the spec generator to emit VL ``"datasets"`` + per-layer
+    ``"data": {"name": ...}`` references.
+    """
+    chart_layers = resolved_chart.layers
+    if not chart_layers:
+        raise ValueError(
+            f"Layered chart '{resolved_chart.id}' has no `layers`. "
+            "Each layered chart must define at least one layer."
+        )
+
+    root_cf = resolved_chart.source_chart.conditional_formatting
+
+    # Validate CF keys up front so bad input fails before any layer work.
+    if root_cf:
+        layer_y_fields = {cl.y for cl in chart_layers if cl.y}
+        orphaned = [col for col in root_cf if col not in layer_y_fields]
+        if orphaned:
+            raise ValueError(
+                f"conditional_formatting on layered chart '{resolved_chart.id}' targets "
+                f"column(s) {orphaned!r} which don't match any layer's y field. "
+                f"Layer y fields: {sorted(layer_y_fields)}"
+            )
+
+    has_per_layer_queries = datasets and any(
+        cl.query_name is not None for cl in chart_layers
+    )
+
+    # Build shared base encoding from parent-level channels (no y — layers own y)
+    base_encoding = _build_standard_encoding(resolved_chart, data, theme, y_field=None)
+    base_encoding.pop("y", None)
+
+    # Resolve per-layer axis_y.orient with auto-fill: if any layer pinned a side,
+    # unset layers default to the opposite side. All-same / all-unset → no fill.
+    explicit_orients = {
+        cl.axis_y.get("orient")
+        for cl in chart_layers
+        if cl.axis_y and cl.axis_y.get("orient") in ("left", "right")
+    }
+    if explicit_orients == {"right"}:
+        unset_default_orient: str | None = "left"
+    elif explicit_orients == {"left"}:
+        unset_default_orient = "right"
+    else:
+        unset_default_orient = None
+    derived_independent_y = len(explicit_orients) >= 2 or (
+        unset_default_orient is not None
+        and any(not (cl.axis_y and cl.axis_y.get("orient")) for cl in chart_layers)
+    )
+
+    layers: list[MappedLayer] = []
+    for chart_layer in chart_layers:
+        vl_mark_type = CHART_TYPE_MAP.get(chart_layer.chart_type)
+        if vl_mark_type is None:
+            from dataface.core.errors import DF_RENDER_UNKNOWN_CHART_TYPE
+
+            raise UnknownChartType.from_code(
+                DF_RENDER_UNKNOWN_CHART_TYPE,
+                chart_type=chart_layer.chart_type,
+                available=", ".join(sorted(CHART_TYPE_MAP.keys())),
+            )
+
+        mark: dict[str, Any] = {"type": vl_mark_type, "tooltip": True}
+        # Per-layer mark-style emission. The non-layered path runs through
+        # _build_mark_style → bar_mark_to_vl so authored bar.size /
+        # band_width / border etc. land on the mark. The explicit-layered
+        # path was emitting bare {"type": "bar"} only — bars on a temporal
+        # x-scale fell back to VL's continuousBandSize default of 5 px,
+        # producing the thin-bar look in interval-label-centering-lab. Run
+        # the same per-mark-type emit here.
+        from dataface.core.compile.models.style.merged import resolve_mark
+        from dataface.core.render.chart.vl_field_maps import (
+            area_mark_to_vl,
+            bar_mark_to_vl,
+            line_mark_to_vl,
+            scatter_mark_to_vl,
+        )
+
+        eff = resolved_chart.resolved_style
+        pm_separate = False  # set True only for line layers with explicit point.color
+        pm: Any = None
+        if chart_layer.chart_type == "bar":
+            bar_mark = resolve_mark(eff.marks.bar, eff.bar.marks.bar)
+            mark.update(bar_mark_to_vl(bar_mark, "vertical"))
+        elif chart_layer.chart_type == "line":
+            line_marks = eff.line.marks
+            lm = resolve_mark(eff.marks.line, line_marks.line)
+            pm = resolve_mark(eff.marks.point, line_marks.point)
+            # When point.color is explicitly set, don't embed mark.point — VL's
+            # encoding.color (datum-based) overrides mark.point.color but not a
+            # separate layer's encoding.color={value:…}. Emit points as a
+            # separate layer instead (handled below after layer_encoding is built).
+            pm_separate = pm.color is not None and pm.size > 0
+            mark.update(line_mark_to_vl(lm, None if pm_separate else pm))
+            # Suppress the single-path first-datum aria-label; the point overlay
+            # appended after this layer provides per-datum aria-labels instead.
+            mark["aria"] = False
+        elif chart_layer.chart_type == "area":
+            area_mark = resolve_mark(eff.marks.area, eff.area.marks.area)
+            mark.update(area_mark_to_vl(area_mark))
+            mark["aria"] = False
+        elif chart_layer.chart_type in ("scatter", "circle", "point"):
+            pm = resolve_mark(eff.marks.point, eff.scatter.marks.point)
+            mark.update(scatter_mark_to_vl(pm))
+        layer_encoding = dict(base_encoding)
+
+        # Determine which dataset this layer uses
+        layer_data_name: str | None = None
+        layer_data = data
+        if has_per_layer_queries:
+            layer_query = chart_layer.query_name or resolved_chart.query_name
+            if layer_query and datasets and layer_query in datasets:
+                layer_data_name = layer_query
+                layer_data = datasets[layer_query]
+
+        # Per-layer gap-fill: each layer's dataset is independently gap-filled.
+        # Use the layer's x field (if present) and parent style for trigger detection.
+        if has_per_layer_queries and chart_layer.x:
+            layer_chart_for_fill = replace(
+                resolved_chart, x=chart_layer.x, x_label=None
+            )
+            layer_data = _gap_fill(layer_chart_for_fill, layer_data)
+            if layer_data_name is not None and datasets is not None:
+                datasets[layer_data_name] = layer_data
+
+        # Per-layer x: build encoding for the layer's own x field through the
+        # full scale-type decision path. Use replace() so map_x_encoding sees
+        # the layer's field while inheriting all axis style (time_unit,
+        # axis_x.type).
+        if chart_layer.x and has_per_layer_queries:
+            layer_chart = replace(resolved_chart, x=chart_layer.x, x_label=None)
+            x_enc = map_x_encoding(layer_chart, layer_data)
+            if x_enc is not None:
+                layer_encoding["x"] = x_enc
+
+        y_field = chart_layer.y
+        if not y_field:
+            raise ChartDataError(
+                f"Layer '{chart_layer.chart_type}' in chart "
+                f"'{resolved_chart.id}' has no `y` field. "
+                "Each layer in a layered chart must specify a `y` field.",
+                chart_id=resolved_chart.id or "unknown",
+            )
+        # skip_tick_values: per-layer axis.values conflict on the shared y-scale.
+        y_enc = map_y_encoding(
+            resolved_chart, layer_data, y_field=y_field, skip_tick_values=True
+        )
+        if y_enc is None:
+            raise ChartDataError(
+                f"Layered chart '{resolved_chart.id}' could not map y field "
+                f"'{y_field}' for layer '{chart_layer.chart_type}'",
+                chart_id=resolved_chart.id or "unknown",
+            )
+        layer_encoding["y"] = y_enc
+        _apply_stack_encoding(resolved_chart, layer_encoding)
+
+        # Per-layer CF: if root conditional_formatting targets this layer's y field,
+        # inject a VL conditional color encoding. A typed layer color channel
+        # (below) replaces it if both are authored.
+        if (
+            root_cf
+            and y_field in root_cf
+            and chart_layer.chart_type in frozenset({"bar", "line", "area", "scatter"})
+        ):
+            cf_entry = root_cf[y_field]
+            field_ref = f"datum[{json.dumps(y_field)}]"
+            vl_condition = _cf_rules_to_vl_condition(cf_entry.when, field_ref)
+            if vl_condition:
+                layer_encoding["color"] = vl_condition
+
+        # Per-layer channel overrides
+        for channel, default_type in (
+            ("color", "nominal"),
+            ("size", "quantitative"),
+            ("shape", "nominal"),
+        ):
+            layer_field = getattr(chart_layer, channel, None)
+            if layer_field is None:
+                continue
+            if isinstance(layer_field, dict):
+                ch = parse_style_channel(layer_field, channel)
+                vl_enc = _resolved_channel_to_vl(ch)
+                if vl_enc is not None:
+                    layer_encoding[channel] = vl_enc
+            else:
+                columns = set(layer_data[0].keys()) if layer_data else set()
+                inferred = (
+                    infer_vega_type_from_data(layer_data, layer_field)
+                    if layer_field in columns
+                    else default_type
+                )
+                layer_encoding[channel] = {"field": layer_field, "type": inferred}
+
+        # Per-layer static fill color — bypasses encoding channel system.
+        # Datum injection is also suppressed below (fill is None guard).
+        if chart_layer.fill is not None:
+            mark["fill"] = chart_layer.fill
+
+        # Typed per-layer axis_y: orient + title.
+        layer_orient = (
+            chart_layer.axis_y.get("orient") if chart_layer.axis_y else None
+        ) or unset_default_orient
+        layer_title = chart_layer.axis_y.get("title") if chart_layer.axis_y else None
+        if layer_orient or layer_title:
+            y_enc_for_axis = dict(layer_encoding.get("y", {}))
+            axis_dict = dict(y_enc_for_axis.get("axis") or {})
+            if layer_orient:
+                axis_dict["orient"] = layer_orient
+            if layer_title:
+                axis_dict["title"] = layer_title
+            y_enc_for_axis["axis"] = axis_dict
+            layer_encoding["y"] = y_enc_for_axis
+
+        # Assign a constant-datum color so Vega-Lite walks the palette per layer.
+        # Only fires on data-series marks when no color was authored at parent or
+        # layer level. Annotation marks (text, rule, tick, image) are excluded so
+        # they don't appear as spurious entries in the auto-built legend.
+        # Skip when layer.fill is set — the mark is intentionally static-painted.
+        if (
+            "color" not in layer_encoding
+            and chart_layer.chart_type in _DATA_SERIES_LAYER_TYPES
+            and chart_layer.fill is None
+        ):
+            effective = resolved_chart.resolved_style
+            datum_label = chart_layer.label or format_display_text(
+                y_field, from_slug=True, font=effective.legend.title.font
+            )
+            color_enc: dict[str, Any] = {"datum": datum_label}
+            legend = _build_encoding_legend(effective)
+            if legend is not None or effective.legend.disable is True:
+                color_enc["legend"] = legend
+            layer_encoding["color"] = color_enc
+
+        layers.append(
+            MappedLayer(
+                mark=mark,
+                encoding=layer_encoding,
+                data_name=layer_data_name,
+            )
+        )
+
+        if chart_layer.chart_type == "line" and pm_separate:
+            # Separate visible point layer: encoding.color={value:…} pins the
+            # explicit color so VL's datum-based color encoding can't override it.
+            from dataface.core.render.chart.vl_field_maps import _emit_point_mark
+
+            pt_encoding = {**layer_encoding, "color": {"value": pm.color}}
+            layers.append(
+                MappedLayer(
+                    mark={"type": "point", **_emit_point_mark(pm), "aria": False},
+                    encoding=pt_encoding,
+                    data_name=layer_data_name,
+                )
+            )
+
+        if chart_layer.chart_type in ("line", "area"):
+            # Each line/area sub-layer gets its own invisible point overlay so the
+            # JS hover layer resolves to individual data points (not the single path).
+            layers.append(
+                MappedLayer(
+                    mark=_hover_overlay_point(),
+                    encoding=layer_encoding,
+                    data_name=layer_data_name,
+                )
+            )
+
+    return MappedChart(
+        encoding=base_encoding,
+        layers=tuple(layers),
+        datasets=datasets if has_per_layer_queries else None,
+        derived_resolve=(
+            {"scale": {"y": "independent"}} if derived_independent_y else None
+        ),
+    )
+
+
+# ── Gap filling for ordinal bucketed-time charts ──────────────────────
+
+
+def _resolve_ordinal_time_unit(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+) -> str | None:
+    """Return the time_unit if the bucketed-time ordinal trigger fires; else None.
+
+    Mirrors the time_unit and axis_type resolution in map_x_encoding without
+    mutating any encoding state. Returns None when the trigger does not fire
+    (temporal escape hatch, non-bucketed unit, or no temporal data).
+    """
+    x_field = resolved_chart.x
+    if not x_field or not data:
+        return None
+
+    effective = resolved_chart.resolved_style
+    ct_attr = "arc" if resolved_chart.chart_type == "pie" else resolved_chart.chart_type
+    ct_style = getattr(effective, ct_attr, None)
+    ct_axis = getattr(ct_style, "axis_x", None) if ct_style is not None else None
+    merged_x = resolved_axis_style(effective, "axis_x", "nominal", ct_axis)
+    authored_tu = merged_x.time_unit
+    authored_axis_type = merged_x.type  # None / "auto" / "ordinal" / "temporal"
+
+    # Temporal escape hatch: author forces temporal → trigger does not fire.
+    if authored_axis_type == "temporal":
+        return None
+
+    # time_unit: none → no bucketing, trigger does not fire
+    if authored_tu == "none":
+        return None
+
+    x_values = [row.get(x_field) for row in data if x_field in row]
+    x_type_from_data = (
+        infer_vega_type_from_data(data, x_field) if x_field in data[0] else "nominal"
+    )
+
+    if authored_tu and authored_tu not in ("auto",):
+        time_unit: str | None = authored_tu
+    elif x_type_from_data == "temporal":
+        time_unit = detect_time_unit(x_values)
+    else:
+        time_unit = None
+
+    if time_unit is None or time_unit not in BUCKETED_CALENDAR_UNITS:
+        return None
+
+    # Author forced ordinal, or bucketed-calendar default → ordinal
+    if authored_axis_type in (None, "auto", "ordinal"):
+        return time_unit
+
+    return None
+
+
+def _gap_fill(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Gap-fill data for ordinal bucketed-time charts when the trigger fires.
+
+    Returns the original data list unchanged when the trigger does not fire
+    (e.g. temporal escape hatch, non-bucketed unit, empty data).
+    """
+    if not data:
+        return data
+
+    x_field = resolved_chart.x
+    if not x_field:
+        return data
+
+    time_unit = _resolve_ordinal_time_unit(resolved_chart, data)
+    if time_unit is None:
+        return data
+
+    effective = resolved_chart.resolved_style
+    ct_attr = "arc" if resolved_chart.chart_type == "pie" else resolved_chart.chart_type
+    ct_style = getattr(effective, ct_attr, None)
+    ct_axis = getattr(ct_style, "axis_x", None) if ct_style is not None else None
+    axis_style = resolved_axis_style(effective, "axis_x", "nominal", ct_axis)
+    fill = axis_style.fill
+
+    color_field = effective_color_field(resolved_chart)
+    dim_fields = [color_field] if color_field else []
+
+    return complete_ordinal_time_series(data, x_field, time_unit, dim_fields, fill)
+
+
+# ── Public API ────────────────────────────────────────────────────────
+
+
+def map_to_vega_lite(
+    resolved_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    theme: str | None = None,
+    custom_registry: CustomChartTypeRegistry | None = None,
+    datasets: dict[str, list[dict[str, Any]]] | None = None,
+    background: str | None = None,
+) -> MappedChart:
+    """Map a resolved Dataface chart to Vega-Lite-native concepts.
+
+    This is the single boundary between Dataface canonical chart semantics
+    and Vega-Lite encoding. Every profiled chart family dispatches here;
+    exception families (geo, kpi) bypass this with documented reasons.
+
+    Custom chart types registered in ``custom_registry`` are resolved to
+    their underlying Vega-Lite mark and routed through the standard
+    cartesian path with optional encoding overrides from the definition.
+
+    The returned MappedChart can be assembled into a spec mechanically.
+    """
+    chart_type = resolved_chart.chart_type
+
+    if chart_type == "layered":
+        return _map_explicit_layered_chart(
+            resolved_chart,
+            data,
+            width,
+            theme,
+            datasets=datasets,
+        )
+
+    if isinstance(resolved_chart.y, list):
+        return _map_layered_chart(resolved_chart, data, width, theme)
+
+    # ── Per-family dispatch (built-in types only) ────────────────────
+    if chart_type == "histogram":
+        return _map_histogram(resolved_chart, data)
+    if chart_type == "boxplot":
+        return _map_boxplot(resolved_chart, data)
+    if chart_type in ("errorbar", "errorband"):
+        return _map_error(resolved_chart, data)
+    if chart_type in ("arc", "pie"):
+        return _map_slice(resolved_chart, data)
+    if chart_type in ("rect", "heatmap", "square"):
+        return _map_rect(resolved_chart, data)
+
+    # Gap-fill: synthesize missing time buckets before encoding; only fires when
+    # the ordinal bucketed-time trigger is active (see _gap_fill).
+    filled_data = _gap_fill(resolved_chart, data)
+    data_override = filled_data if filled_data is not data else None
+
+    if chart_type == "line":
+        mapped_line = _map_line(
+            resolved_chart, filled_data, width, theme, background=background
+        )
+        if data_override is not None:
+            return replace(mapped_line, data_override=data_override)
+        return mapped_line
+    if chart_type == "area":
+        mapped_area = _map_area(
+            resolved_chart, filled_data, width, theme, background=background
+        )
+        if data_override is not None:
+            return replace(mapped_area, data_override=data_override)
+        return mapped_area
+
+    # ── Standard cartesian path (built-in + custom types) ────────────
+    mark = _map_mark(resolved_chart, custom_registry)
+    encoding = _build_standard_encoding(resolved_chart, filled_data, theme)
+
+    # ── Custom type encoding overrides ───────────────────────────────
+    custom_defn = custom_registry.get(chart_type) if custom_registry else None
+    if custom_defn and custom_defn.encoding_overrides:
+        for channel, overrides in custom_defn.encoding_overrides.items():
+            if channel in encoding and isinstance(encoding[channel], dict):
+                encoding[channel].update(overrides)
+            else:
+                encoding[channel] = overrides
+
+    z_transforms = _apply_stacked_bar_z_order(resolved_chart, encoding, filled_data)
+    return MappedChart(
+        mark=mark,
+        encoding=encoding,
+        data_override=data_override,
+        transform=z_transforms,
+    )