dataface 0.1.2__py3-none-any.whl

dataface/core/compile/data_table_attachment.py

@@ -0,0 +1,1287 @@
+"""Vega-Lite attachment for the chart.data_table primitive.
+
+Post-pass on a chart-body Vega-Lite spec. Given a validated ChartDataTable
+and the chart's x-encoding, emit:
+- An optional strip-top divider rule (when divider.width > 0).
+- One text layer per row — source rows use a format() calculate transform;
+  aggregate rows add a Vega-Lite aggregate transform grouped by x.
+- N-1 inter-row rule layers when row.rule.width > 0.
+- One label text layer per row that carries label: — emitted at the
+  y-axis tick label's x-anchor (right gutter for right-oriented axes,
+  left gutter for left-oriented axes), derived from the resolved axis_y.orient.
+
+No new primitives: every output layer is standard Vega-Lite (mark: text,
+mark: rule).
+
+Y-positioning is pixel-literal (`{"y": {"value": <px>}}`), computed from
+the spec's explicit height plus per-row offsets. Vega-Lite treats
+`{"y": {"expr": "..."}}` as a SCALED data value (not a pixel literal),
+so the previous expr-based approach collapsed every row to one pixel
+position via the parent's quantitative y-scale. Spec.height must be set
+when data_table is non-None — auto-sized specs have no anchor.
+
+The caller owns the padding allocation. Compute the required height with
+``data_table_strip_height`` and add it to the appropriate padding side
+(``top`` for position=top, ``bottom`` for position=bottom) via
+``bump_padding_top`` / ``bump_padding_bottom``. The renderer's downstream
+finalize step respects the external padding kwarg when supplied.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Literal
+
+from dataface.core.compile.models.chart.authored import (
+    CHART_DATA_TABLE_MAX_X_TICKS,
+    ChartDataTable,
+    ChartDataTableAggregate,
+    ChartDataTableAggregateOp,
+    ChartDataTablePerSeries,
+)
+from dataface.core.compile.models.style.compiled import DataTableStyle
+from dataface.core.compile.models.style.merged import (
+    MergedChartsStyle,
+    deep_merge,
+)
+from dataface.core.compile.palette import resolve_dark_companion_stops
+from dataface.core.render.format_utils import resolve_format
+
+# Map authoring-surface aggregate names to Vega-Lite aggregate ops.
+# G4 (spec §2.4) keeps authoring exact; the compiler is free to translate.
+# Keys are the ChartDataTableAggregateOp Literal values; the test guard
+# test_agg_op_map_keys_are_all_authoring_surface_ops enforces coverage.
+_AGG_OP_TO_VL: dict[ChartDataTableAggregateOp, str] = {
+    "sum": "sum",
+    "avg": "mean",
+    "min": "min",
+    "max": "max",
+    "median": "median",
+    "count": "count",
+    "count_distinct": "distinct",
+}
+
+# Row geometry. These are the compiler's constants — they live here rather
+# than on the style model because they are emitter mechanics, not user-facing
+# theme tokens. If a theme wants denser rows, padding.vertical lets it.
+_ROW_HEIGHT_BASE = 14.0  # per-row pixel height before padding
+_DIVIDER_GAP = 4.0  # vertical gap between divider rule and first row
+# Row labels share the y-axis tick column (~50–70 px for typical numeric
+# formats). 80 px accommodates labels up to ~12 chars at 11 px Inter without
+# the label reaching visibly into the legend zone or over-shrinking the plot.
+_LABEL_STUB_LIMIT_PX = 80.0
+
+
+def _row_height(style: DataTableStyle) -> float:
+    padding = style.row.padding
+    return _ROW_HEIGHT_BASE + padding.vertical * 2.0
+
+
+def _strip_height(style: DataTableStyle, n_rows: int) -> float:
+    """Total pixel height for the attached strip (position-agnostic)."""
+    row_h = _row_height(style)
+    divider = (style.divider.width + _DIVIDER_GAP) if style.divider.width > 0 else 0.0
+    inter_row = (
+        style.row.rule.width * (n_rows - 1)
+        if style.row.rule.width > 0 and n_rows > 1
+        else 0.0
+    )
+    return (
+        style.padding_top + divider + row_h * n_rows + inter_row + style.padding_bottom
+    )
+
+
+def data_table_strip_height(
+    data_table: ChartDataTable | None,
+    style: DataTableStyle,
+    charts_style: MergedChartsStyle,
+    series_count: int = 0,
+) -> float:
+    """Pixel height to reserve on the appropriate padding side when attaching a strip.
+
+    For ``position: bottom``: includes the axis-label gap between the plot bottom
+    and the strip top; callers pass the result to ``padding.bottom``.
+
+    For ``position: top``: no axis gap (x-axis is below the plot); callers pass
+    the result to ``padding.top``.
+
+    Returns 0 when no strip is attached.
+
+    Args:
+        data_table: The data_table block, or None for no strip.
+        style: Resolved DataTableStyle (must carry ``position``).
+        charts_style: Resolved MergedChartsStyle for axis offset calculation.
+        series_count: How many series each ``per_series:`` entry expands to.
+            All per_series entries on the same chart share one color domain,
+            so one int suffices for the strip-height accounting. Required
+            (>0) when any entry is ``ChartDataTablePerSeries`` — leaving it
+            at 0 with a per_series entry present silently under-sizes the
+            strip and the expanded rows render below the reserved padding.
+            ValueError is raised in that case rather than guessing 1.
+    """
+    if data_table is None or not data_table.entries:
+        return 0.0
+    n_rows = 0
+    for entry in data_table.entries:
+        if isinstance(entry, ChartDataTablePerSeries):
+            if entry.by_measure:
+                n_rows += 1
+            else:
+                if series_count <= 0:
+                    raise ValueError(
+                        "data_table_strip_height needs series_count > 0 when any "
+                        "entry is `per_series:` — pass the number of color-domain "
+                        "series the chart expands to. Defaulting to 1 silently "
+                        "under-sizes the strip and the expanded rows render below "
+                        "the reserved padding."
+                    )
+                n_rows += series_count
+        else:
+            n_rows += 1
+    strip_h = _strip_height(style, n_rows)
+    if style.position == "bottom":
+        return _axis_offset(charts_style, style) + strip_h
+    # top: x-axis is below the plot — no axis gap above the strip.
+    return strip_h
+
+
+def _axis_offset(charts_style: MergedChartsStyle, style: DataTableStyle) -> float:
+    """Pixel offset from plot bottom edge to the bottom of the x-axis block.
+
+    Sums whichever axis components are actually visible: a chart with the
+    title shown but labels suppressed still needs the title's height to
+    sit above the strip, otherwise the strip's first row collides with it.
+
+    label_max_lines × label height is reserved so yearly boundary ticks that
+    emit a two-element array (e.g. ['Jan', '2024']) do not overlap the strip
+    top edge. style.label_max_lines = 2 is the universal default; themes with
+    a year-only cadence may set 1.
+    """
+    axis = charts_style.axis_x
+    label_h = (
+        axis.label.padding + axis.label.font.size * style.label_max_lines
+        if axis.label.font.size > 0
+        else 0.0
+    )
+    title_h = (
+        axis.title.padding + axis.title.font.size if axis.title.font.size > 0 else 0.0
+    )
+    return label_h + title_h
+
+
+def _row_y_pixel(
+    index: int,
+    style: DataTableStyle,
+    charts_style: MergedChartsStyle,
+    spec_height: float,
+) -> float:
+    """Pixel y of the centroid of the ith row in the attached strip.
+
+    For ``position: bottom``: y > spec_height (strip below the plot). Row 0 is
+    closest to the plot (first below the divider); row index increases downward.
+
+    For ``position: top``: y < 0 (strip above the plot, in padding.top zone).
+    Row 0 is closest to the plot top (y nearest 0); row index increases upward
+    (y becomes more negative). No axis-offset is needed since the x-axis is below.
+    """
+    divider_off = style.divider.width + _DIVIDER_GAP if style.divider.width > 0 else 0.0
+    row_h = _row_height(style)
+    inter_row = (
+        style.row.rule.width * index if style.row.rule.width > 0 and index > 0 else 0.0
+    )
+    if style.position == "bottom":
+        axis_off = _axis_offset(charts_style, style)
+        offset = (
+            style.padding_top
+            + axis_off
+            + divider_off
+            + index * row_h
+            + inter_row
+            + row_h / 2.0
+        )
+        return spec_height + offset
+    # top: measure from y=0 (plot top) going upward (negative y).
+    # Row 0 is closest to the plot; row N is furthest above.
+    # Layout (from y=0 upward): padding_bottom, then rows (0…N), then padding_top.
+    # Divider sits just above y=0, between padding_bottom and rows.
+    dist_from_plot_top = (
+        style.padding_bottom + divider_off + index * row_h + inter_row + row_h / 2.0
+    )
+    return -dist_from_plot_top
+
+
+def _divider_y_pixel(
+    style: DataTableStyle,
+    charts_style: MergedChartsStyle,
+    spec_height: float,
+) -> float:
+    """Pixel y of the divider rule.
+
+    For ``position: bottom``: divider sits between the axis and the strip rows
+    (just below axis labels), at spec_height + padding_top + axis_offset.
+
+    For ``position: top``: divider sits between the strip rows and the plot top
+    (just above y=0), at -(padding_bottom).
+    """
+    if style.position == "bottom":
+        axis_off = _axis_offset(charts_style, style)
+        return spec_height + style.padding_top + axis_off
+    # top: divider is the boundary between strip and plot.
+    return -style.padding_bottom
+
+
+def _inter_row_rule_y_pixel(
+    index: int,
+    style: DataTableStyle,
+    charts_style: MergedChartsStyle,
+    spec_height: float,
+) -> float:
+    """Pixel y of the inter-row rule between row `index` and row `index + 1`.
+
+    Centroid sits in the middle of the inter-row gap so the rule's stroke
+    splits evenly between the two adjacent rows; without the half-stroke
+    offset the rule biases visually toward the row above.
+
+    For ``position: bottom``: row y values increase downward, so the rule
+    between row 0 and row 1 is *below* row 0's centroid → add half-row +
+    half-stroke.
+
+    For ``position: top``: row y values are negative (above the plot) and
+    become *more negative* as index increases. The rule between row 0 and
+    row 1 must be *more negative* than row 0's centroid → subtract.
+    """
+    row_y = _row_y_pixel(index, style, charts_style, spec_height)
+    half_gap = _row_height(style) / 2.0 + style.row.rule.width / 2.0
+    if style.position == "bottom":
+        return row_y + half_gap
+    # top: "between rows" is more negative (further above plot)
+    return row_y - half_gap
+
+
+def _vl_format_calc(
+    source: str,
+    format_spec: str | None,
+    as_name: str,
+    formats: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """Build a Vega-Lite calculate transform that formats a source column."""
+    if format_spec is None:
+        # Pass-through: text layer binds directly to the source field.
+        return {"calculate": f"datum.{source}", "as": as_name}
+    # Resolve alias before emitting — format_spec may be a theme alias (e.g.
+    # "currency") rather than a raw d3 spec (e.g. "$,.2f").
+    resolved = resolve_format(format_spec, formats)
+    return {"calculate": f"format(datum.{source}, '{resolved}')", "as": as_name}
+
+
+def _wrap_base_as_layer(spec: dict[str, Any]) -> dict[str, Any]:
+    """Lift a single-mark spec into {layer: [base, ...]} form if needed."""
+    if "layer" in spec:
+        return dict(spec)
+    base_layer: dict[str, Any] = {}
+    for key in ("mark", "encoding", "transform"):
+        if key in spec:
+            base_layer[key] = spec[key]
+    new_spec = {k: v for k, v in spec.items() if k not in ("mark", "encoding")}
+    # `transform` stays on the base layer; the attached layers carry their own.
+    if "transform" in new_spec:
+        del new_spec["transform"]
+    # Promote tooltip to spec-level so strip layers inherit it (PR #1877).
+    # Strip text marks have only x + a calc text field; without an inherited
+    # tooltip, hover shows the raw channel field (e.g. ``revenue: 100.5``)
+    # instead of titled-and-formatted output.
+    #
+    # Two paths:
+    # - If the base encoding carries an explicit tooltip array (legacy callers,
+    #   unit tests that hand-feed one): promote it as-is.
+    # - Otherwise: synthesize from the base's x/y channels — the bar layer's
+    #   channels carry title + format after this PR, so the synthesized array
+    #   is the same content the legacy tooltip array used to carry.
+    #
+    # Dict comprehension (not .pop) — base_layer["encoding"] is a shared
+    # reference to spec["encoding"] and mutation would corrupt the input.
+    base_encoding = base_layer.get("encoding")
+    if isinstance(base_encoding, dict):
+        existing_tooltip = base_encoding.get("tooltip")
+        if existing_tooltip is not None:
+            base_layer["encoding"] = {
+                k: v for k, v in base_encoding.items() if k != "tooltip"
+            }
+            new_spec["encoding"] = {"tooltip": existing_tooltip}
+        else:
+            spec_tooltip = [
+                {k: enc[k] for k in ("field", "type", "title", "format") if k in enc}
+                for ch in ("x", "y")
+                if (enc := base_encoding.get(ch, {})) and enc.get("field")
+            ]
+            if spec_tooltip:
+                new_spec["encoding"] = {"tooltip": spec_tooltip}
+    new_spec["layer"] = [base_layer]
+    return new_spec
+
+
+def _shared_x_encoding(parent_x_enc: dict[str, Any]) -> dict[str, Any]:
+    """Shared x-encoding for all attached layers.
+
+    Copies field, type, and (when present) timeUnit from the parent chart's
+    x-encoding so strip layers share the same scale type. Mismatched types
+    (e.g. parent temporal vs strip ordinal) cause a vl-convert null-deref.
+
+    bandPosition rules:
+      - temporal + timeUnit  → 1.0  (right-edge anchor; pairs with align:right
+                                     so text's right edge lines up with the bar's
+                                     right wall — no dx centering for these).
+      - ordinal / nominal    → 0.5  (explicit band-centre anchor; pairs with a
+                                     per-entry dx from _compute_data_table_entry_dx
+                                     to implement table-parity column centering:
+                                     right edge at band_centre + max_w/2).
+      - quantitative / plain temporal → omitted (continuous scale, no bands).
+
+    No axis: null — setting axis to None crashes vl-convert with a TypeError
+    in parseAxesAndHeaders. Omitting the axis key entirely is correct; Vega-Lite
+    infers axis rendering from context and the text mark does not need axis ticks.
+    """
+    enc: dict[str, Any] = {"field": parent_x_enc["field"], "type": parent_x_enc["type"]}
+    if "timeUnit" in parent_x_enc:
+        enc["timeUnit"] = parent_x_enc["timeUnit"]
+        enc["bandPosition"] = 1.0
+    elif parent_x_enc["type"] in ("ordinal", "nominal"):
+        enc["bandPosition"] = 0.5
+    return enc
+
+
+def _text_mark_props(style: DataTableStyle, dx: float | None = None) -> dict[str, Any]:
+    """Common mark properties for row-text layers.
+
+    dx, when set, offsets the text mark so the number lane's centre aligns
+    with the band midpoint — the same centre-on-midpoint invariant as
+    _compute_lane_positions in table.py.  Caller passes
+    dx = max_formatted_width / 2 (always positive).
+
+    Sign convention (mirrors table lane geometry):
+      align=right  → +dx  (right edge at band_center + max_w/2 → column centred)
+      align=left   → -dx  (left  edge at band_center - max_w/2 → column centred)
+    """
+    align_map = {"left": "left", "right": "right", "decimal": "right"}
+    mark: dict[str, Any] = {
+        "type": "text",
+        "align": align_map[style.number_align],
+        "baseline": "middle",
+    }
+    if dx is not None:
+        # Left-aligned text anchors on its left edge; negate so the column
+        # centre sits at the band midpoint rather than shifting right.
+        mark["dx"] = -dx if style.number_align == "left" else dx
+    font = style.font
+    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:
+        mark["fill"] = font.color
+    return mark
+
+
+def _row_text_layer(
+    index: int,
+    entry: Any,
+    parent_x_enc: dict[str, Any],
+    style: DataTableStyle,
+    charts_style: MergedChartsStyle,
+    spec_height: float,
+    sampling_step: int = 1,
+    dx: float | None = None,
+    label_period_filter_expr: str | None = None,
+    formats: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """Emit a text layer for one data_table row (source or aggregate).
+
+    When sampling_step > 1, a Vega-Lite window+filter chain is inserted so
+    only every Nth x position renders a cell. Transform ordering matters:
+    - For aggregate entries: [aggregate, (period_filter), window, filter, format_calc]
+      The aggregate collapses multi-row-per-x data first; period filter then thins
+      to label-period openers; sampling then thins further if needed.
+    - For source entries (1 row per x, guaranteed by G1): [(period_filter), window, filter, format_calc]
+
+    When label_period_filter_expr is set, a filter transform is inserted to
+    keep only x-values that open a new label period (e.g. quarterly openers on
+    a monthly-band axis). This prevents the data_table strip from rendering one
+    cell per band when the axis labels are at a coarser cadence.
+    """
+    is_agg = isinstance(entry, ChartDataTableAggregate)
+    x_field = parent_x_enc["field"]
+    # Internal field name for the formatted cell value.
+    cell_name = f"__data_table_{index}"
+
+    transforms: list[dict[str, Any]] = []
+    if is_agg:
+        vl_op = _AGG_OP_TO_VL[entry.aggregate]
+        agg_name = f"{cell_name}_val"
+        transforms.append(
+            {
+                "aggregate": [{"op": vl_op, "field": entry.source, "as": agg_name}],
+                "groupby": [x_field],
+            }
+        )
+        # Period filter after aggregate: one row per x, filter to label-period openers.
+        if label_period_filter_expr is not None:
+            transforms.append({"filter": label_period_filter_expr})
+        # Sampling after period filter: thin further if still over the cap.
+        if sampling_step > 1:
+            transforms.extend(_sampling_transforms(x_field, sampling_step))
+        if entry.format is not None:
+            transforms.append(
+                _vl_format_calc(agg_name, entry.format, cell_name, formats)
+            )
+        else:
+            # pass raw aggregate value through as text
+            cell_name = agg_name
+    else:
+        # Source entry: G1 guarantees 1 row per x.
+        # Period filter before sampling: thin to label-period openers first.
+        if label_period_filter_expr is not None:
+            transforms.append({"filter": label_period_filter_expr})
+        if sampling_step > 1:
+            transforms.extend(_sampling_transforms(x_field, sampling_step))
+        if entry.format is not None:
+            transforms.append(
+                _vl_format_calc(entry.source, entry.format, cell_name, formats)
+            )
+        else:
+            cell_name = entry.source
+
+    y_pixel = _row_y_pixel(index, style, charts_style, spec_height)
+    encoding: dict[str, Any] = {
+        "x": _shared_x_encoding(parent_x_enc),
+        "y": {"value": y_pixel},
+        "text": {"field": cell_name},
+    }
+    layer: dict[str, Any] = {
+        "mark": _text_mark_props(style, dx=dx),
+        "encoding": encoding,
+    }
+    if transforms:
+        layer["transform"] = transforms
+    return layer
+
+
+def _per_series_row_layers(
+    row_start_index: int,
+    entry: ChartDataTablePerSeries,
+    *,
+    parent_x_enc: dict[str, Any],
+    color_field: str | None,
+    series_order: list[str],
+    series_palette: list[str] | None,
+    style: DataTableStyle,
+    charts_style: MergedChartsStyle,
+    spec_height: float,
+    spec_width: float | None,
+    sampling_step: int = 1,
+    dx: float | None = None,
+    label_period_filter_expr: str | None = None,
+    axis_y_orient: Literal["left", "right"],
+    label_limit: float | None = None,
+    formats: dict[str, str] | None = None,
+) -> list[dict[str, Any]]:
+    """Emit one text layer + one label layer per series for a per_series entry.
+
+    When ``entry.by_measure`` is True, emits a single row reading the named
+    measure field directly (no color groupby/filter).  Otherwise expands into
+    one text layer + one label layer per series name in series_order.
+
+    For the normal (non-by_measure) path:
+    - Each layer has an aggregate transform groupby [x, color_field].
+    - A filter transform selects the specific series.
+    - The label layer carries the series name with fill = dark companion ink.
+
+    Args:
+        row_start_index: The pixel-row index of the first series row.
+        entry: The ChartDataTablePerSeries entry to expand.
+        parent_x_enc: The parent chart's x-encoding dict.
+        color_field: The column name used for the color: channel.  Required for
+            normal mode; may be None when ``entry.by_measure`` is True.
+        series_order: Ordered series names (stack/scale order).
+        series_palette: The effective palette colours for each series in
+            series_order. When None, label fill is omitted (no companion resolution).
+        style: Resolved DataTableStyle.
+        charts_style: Resolved MergedChartsStyle.
+        spec_height: The chart spec's pixel height.
+        spec_width: The chart spec's pixel width. Required (non-None) when
+            ``axis_y_orient == "right"``; ignored for left-cap.
+        sampling_step: Sampling step for dense x axes (>1 thins cells).
+        dx: Optional band-centering dx for cell text marks.
+        axis_y_orient: Resolved y-axis orient — "right" or "left". Determines
+            which label emitter fires and the mark's x-anchor and text-anchor.
+        label_limit: mark.limit (pixels) applied to every label layer. When None,
+            no limit is set. Pass _LABEL_STUB_LIMIT_PX to prevent labels from
+            reaching into the legend zone.
+
+    Returns:
+        Flat list of Vega-Lite layer dicts (cell text + label text per series).
+
+    Raises:
+        ValueError when ``axis_y_orient == "right"`` but ``spec_width`` is None.
+    """
+    if axis_y_orient == "right" and spec_width is None:
+        raise ValueError(
+            "attach_data_table requires the spec to carry an explicit "
+            "width when right-cap labels are present on per_series rows — "
+            "pixel-literal label positioning has no anchor otherwise."
+        )
+
+    # by_measure mode: one row reading the named field directly.
+    if entry.by_measure:
+        row_idx = row_start_index
+        bm_cell_name = f"__data_table_{row_idx}"
+        bm_transforms: list[dict[str, Any]] = []
+        if label_period_filter_expr is not None:
+            bm_transforms.append({"filter": label_period_filter_expr})
+        if sampling_step > 1:
+            bm_transforms.extend(
+                _sampling_transforms(parent_x_enc["field"], sampling_step)
+            )
+        if entry.format is not None:
+            bm_transforms.append(
+                {
+                    "calculate": f"format(datum.{entry.per_series}, '{entry.format}')",
+                    "as": bm_cell_name,
+                }
+            )
+        else:
+            bm_cell_name = entry.per_series
+        bm_y_pixel = _row_y_pixel(row_idx, style, charts_style, spec_height)
+        bm_cell_layer: dict[str, Any] = {
+            "mark": _text_mark_props(style, dx=dx),
+            "encoding": {
+                "x": _shared_x_encoding(parent_x_enc),
+                "y": {"value": bm_y_pixel},
+                "text": {"field": bm_cell_name},
+            },
+        }
+        if bm_transforms:
+            bm_cell_layer["transform"] = bm_transforms
+        # Label stub: use entry.label when set, else fall back to the field name.
+        bm_label_text = entry.label if entry.label is not None else entry.per_series
+        if axis_y_orient == "right":
+            assert spec_width is not None  # pre-check above guarantees this
+            bm_label_layer = _label_stub_right_layer(
+                row_idx,
+                bm_label_text,
+                style=style,
+                charts_style=charts_style,
+                spec_height=spec_height,
+                spec_width=spec_width,
+                limit=label_limit,
+            )
+        else:
+            bm_label_layer = _label_stub_left_layer(
+                row_idx,
+                bm_label_text,
+                style=style,
+                charts_style=charts_style,
+                spec_height=spec_height,
+                limit=label_limit,
+            )
+        return [bm_cell_layer, bm_label_layer]
+
+    # Normal mode: one cell + label per series in series_order.
+    # color_field is guaranteed non-None here: attach_data_table raises ValueError
+    # before calling this function for normal-mode entries when color_field is None.
+    dark_fills: list[str | None]
+    if series_palette is not None:
+        dark_fills = list(resolve_dark_companion_stops(series_palette))
+    else:
+        dark_fills = [None] * len(series_order)
+
+    x_field = parent_x_enc["field"]
+    layers: list[dict[str, Any]] = []
+
+    for series_idx, series_value in enumerate(series_order):
+        row_idx = row_start_index + series_idx
+        cell_name = f"__data_table_{row_idx}"
+        agg_name = f"{cell_name}_val"
+
+        transforms: list[dict[str, Any]] = [
+            {
+                "aggregate": [{"op": "sum", "field": entry.per_series, "as": agg_name}],
+                "groupby": [x_field, color_field],
+            },
+        ]
+        # Filter to this series first, THEN apply period filter, THEN sample.
+        # Sampling after the aggregate but before the per-series filter would
+        # window over the (x, series) cross-product, where ties on x_field have
+        # unspecified row-number order — so series A might keep x1/x3/x5
+        # while series B keeps x2/x4/x6, with cells at inconsistent
+        # x positions across the strip's rows. Sampling AFTER the
+        # per-series filter gives each series an independent 1-row-per-x
+        # input that thins consistently. Period filter goes between the
+        # per-series filter and sampling: it operates on per-series 1-row-per-x
+        # data and further thins to label-period openers.
+        safe_val = str(series_value).replace("\\", "\\\\").replace("'", "\\'")
+        transforms.append({"filter": f"datum['{color_field}'] === '{safe_val}'"})
+        if label_period_filter_expr is not None:
+            transforms.append({"filter": label_period_filter_expr})
+        if sampling_step > 1:
+            transforms.extend(_sampling_transforms(x_field, sampling_step))
+        if entry.format is not None:
+            transforms.append(
+                _vl_format_calc(agg_name, entry.format, cell_name, formats)
+            )
+        else:
+            cell_name = agg_name
+
+        y_pixel = _row_y_pixel(row_idx, style, charts_style, spec_height)
+        cell_layer: dict[str, Any] = {
+            "mark": _text_mark_props(style, dx=dx),
+            "encoding": {
+                "x": _shared_x_encoding(parent_x_enc),
+                "y": {"value": y_pixel},
+                "text": {"field": cell_name},
+            },
+            "transform": transforms,
+        }
+        layers.append(cell_layer)
+
+        # Label layer — series name with companion-resolved fill ink.
+        # Delegates to _label_stub_right_layer / _label_stub_left_layer so
+        # the orient-derived geometry (x, align, limit) lives in one place.
+        dark_fill = dark_fills[series_idx] if series_idx < len(dark_fills) else None
+        if axis_y_orient == "right":
+            assert spec_width is not None  # pre-loop check guarantees this
+            label_layer = _label_stub_right_layer(
+                row_idx,
+                str(series_value),
+                style=style,
+                charts_style=charts_style,
+                spec_height=spec_height,
+                spec_width=spec_width,
+                limit=label_limit,
+            )
+        else:
+            label_layer = _label_stub_left_layer(
+                row_idx,
+                str(series_value),
+                style=style,
+                charts_style=charts_style,
+                spec_height=spec_height,
+                limit=label_limit,
+            )
+        if dark_fill is not None:
+            label_layer["mark"]["fill"] = dark_fill
+        layers.append(label_layer)
+
+    return layers
+
+
+def _divider_rule_layer(
+    style: DataTableStyle,
+    charts_style: MergedChartsStyle,
+    spec_height: float,
+) -> dict[str, Any]:
+    """Strip-top divider rule (ADR-006: rule-only, no header text)."""
+    mark: dict[str, Any] = {
+        "type": "rule",
+        "strokeWidth": style.divider.width,
+    }
+    if style.divider.color is not None:
+        mark["stroke"] = style.divider.color
+    return {
+        "data": {"values": [{}]},
+        "mark": mark,
+        "encoding": {
+            "y": {"value": _divider_y_pixel(style, charts_style, spec_height)}
+        },
+    }
+
+
+def _row_rule_layer(
+    index: int,
+    style: DataTableStyle,
+    charts_style: MergedChartsStyle,
+    spec_height: float,
+) -> dict[str, Any]:
+    """Inter-row rule between row `index` and row `index + 1` (spec §4.3)."""
+    mark: dict[str, Any] = {
+        "type": "rule",
+        "strokeWidth": style.row.rule.width,
+    }
+    if style.row.rule.color is not None:
+        mark["stroke"] = style.row.rule.color
+    return {
+        "data": {"values": [{}]},
+        "mark": mark,
+        "encoding": {
+            "y": {
+                "value": _inter_row_rule_y_pixel(
+                    index, style, charts_style, spec_height
+                )
+            }
+        },
+    }
+
+
+def _label_mark_props(style: DataTableStyle, align: str) -> dict[str, Any]:
+    """Common mark properties shared by left-stub and right-cap label layers.
+
+    `align` is derived from the chart's resolved axis_y.orient at the call site:
+    right-oriented → "left" (text-anchor start); left-oriented → "right" (text-anchor end).
+    """
+    mark: dict[str, Any] = {
+        "type": "text",
+        "align": align,
+        "baseline": "middle",
+    }
+    font = style.label.font
+    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:
+        mark["fill"] = font.color
+    return mark
+
+
+def _label_stub_left_layer(
+    index: int,
+    label_text: str,
+    style: DataTableStyle,
+    charts_style: MergedChartsStyle,
+    spec_height: float,
+    limit: float | None = None,
+) -> dict[str, Any]:
+    """Left-gutter label layer anchored to the left y-axis tick column.
+
+    x = -axis_y.label.padding (same column as left-oriented y-axis tick labels,
+    which extend leftward from x=0 with text-anchor end / align right).
+    mark.limit caps the text width so VL's autosize does not shrink the plot.
+    """
+    axis_label_padding = charts_style.axis_y.label.padding
+    x_pixel = -axis_label_padding
+    mark = _label_mark_props(style, align="right")
+    if limit is not None:
+        mark["limit"] = limit
+    return {
+        "data": {"values": [{"__label": label_text}]},
+        "mark": mark,
+        "encoding": {
+            "x": {"value": x_pixel},
+            "y": {"value": _row_y_pixel(index, style, charts_style, spec_height)},
+            "text": {"field": "__label"},
+            # Opt out of inherited color encoding. Without this, VL sees own data
+            # that lacks the series field, adds null to the categorical domain, and
+            # null sorts first — consuming palette[0] and shifting every series mark
+            # one slot up (the dark-companion off-by-one).
+            "color": None,
+        },
+    }
+
+
+def _label_stub_right_layer(
+    index: int,
+    label_text: str,
+    style: DataTableStyle,
+    charts_style: MergedChartsStyle,
+    spec_height: float,
+    spec_width: float,
+    limit: float | None = None,
+) -> dict[str, Any]:
+    """Right-cap label layer anchored to the right y-axis tick column.
+
+    x = spec_width + axis_y.label.padding (same column as right-oriented y-axis
+    tick labels, which extend rightward from that anchor with text-anchor start /
+    align left). mark.limit caps the text width so VL's autosize does not shrink
+    the plot.
+    """
+    axis_label_padding = charts_style.axis_y.label.padding
+    x_pixel = spec_width + axis_label_padding
+    mark = _label_mark_props(style, align="left")
+    if limit is not None:
+        mark["limit"] = limit
+    return {
+        "data": {"values": [{"__label": label_text}]},
+        "mark": mark,
+        "encoding": {
+            "x": {"value": x_pixel},
+            "y": {"value": _row_y_pixel(index, style, charts_style, spec_height)},
+            "text": {"field": "__label"},
+            # Opt out of inherited color encoding — same fix as _label_stub_left_layer.
+            "color": None,
+        },
+    }
+
+
+def validate_data_table_against_data(
+    data_table: ChartDataTable,
+    x_field: str | None,
+    data: list[dict[str, Any]],
+    x_type: str | None = None,
+) -> int:
+    """Data-aware validation of a data_table block (spec §3.1, §3.2).
+
+    Runs at render time where the actual query output is available.
+    Complements the data-free checks in AuthoredChart.validate_data_table
+    (duplicate entries, chart-type, multi-y).
+
+    For temporal/quantitative x axes with more than CHART_DATA_TABLE_MAX_X_TICKS
+    rows, sampling is applied instead of failing. Returns the sampling step
+    (>= 1); step=1 means no sampling is needed.
+
+    For ordinal/nominal/unknown x_type exceeding the cap, raises ValueError
+    (fail-closed: dropping categories silently would be wrong).
+
+    Raises:
+        ValueError on violation. Messages are explicit — they name the
+        offending field and point at the resolution (e.g., "Add
+        'aggregate: <op>'...").
+    """
+    # Spec §3.1 — x-axis must exist.
+    if not x_field:
+        raise ValueError(
+            "chart.data_table requires an x-encoding; the chart has no "
+            "`x:` field. Add `x: <column>` or remove the data_table block."
+        )
+
+    # Spec §3.1 — x-axis cardinality cap.
+    x_values = {row.get(x_field) for row in data if x_field in row}
+    n = len(x_values)
+    sampling_step = 1
+    if n > CHART_DATA_TABLE_MAX_X_TICKS:
+        if x_type in ("temporal", "quantitative"):
+            # Temporal/quantitative: thin the strip labels via Vega-Lite
+            # window+filter transforms. The chart data layers are unaffected.
+            # Continue validating §3.2 below — the early-return pattern would
+            # silently skip source-column existence and G1 multi-row checks.
+            sampling_step = math.ceil(n / CHART_DATA_TABLE_MAX_X_TICKS)
+        else:
+            raise ValueError(
+                f"chart.data_table supports at most "
+                f"{CHART_DATA_TABLE_MAX_X_TICKS} x-axis ticks; got "
+                f"{n}. Aggregate or filter in the query before "
+                "rendering an attached table."
+            )
+
+    # Spec §3.2 — every referenced column must be present in the query output.
+    # Use the first row as the schema sample (mirrors how the rest of the
+    # render pipeline reads row shape).
+    if data:
+        available = set(data[0].keys())
+        for entry in data_table.entries:
+            if isinstance(entry, ChartDataTablePerSeries):
+                source_col = entry.per_series
+            else:
+                source_col = entry.source
+            if source_col not in available:
+                cols = ", ".join(sorted(available))
+                raise ValueError(
+                    f"chart.data_table entry references source column "
+                    f"{source_col!r} which is not in the query output. "
+                    f"Available columns: {cols}."
+                )
+
+    # Spec §3.2 G1 — a bare `source:` entry is ambiguous if the query
+    # returns multiple rows per x. Point the author at `aggregate:`.
+    # Normal per_series entries (by_measure=False) are exempt — they aggregate
+    # groupby [x, color] and expect multiple rows per x.
+    # by_measure entries are NOT exempt — they read datum[field] directly with
+    # no aggregation transform, so multiple rows per x produce a wrong result.
+    if data and x_field:
+        from collections import Counter
+
+        counts = Counter(row.get(x_field) for row in data)
+        multi_row = any(c > 1 for c in counts.values())
+        if multi_row:
+            for entry in data_table.entries:
+                is_aggregate = isinstance(entry, ChartDataTableAggregate)
+                is_normal_per_series = (
+                    isinstance(entry, ChartDataTablePerSeries) and not entry.by_measure
+                )
+                if not is_aggregate and not is_normal_per_series:
+                    source_col = (
+                        entry.per_series
+                        if isinstance(entry, ChartDataTablePerSeries)
+                        else entry.source
+                    )
+                    raise ValueError(
+                        f"chart.data_table entry references column {source_col!r} "
+                        f"which is ambiguous on this chart — {x_field!r} "
+                        "returns multiple rows per x. Add "
+                        f"'aggregate: <op>' (e.g. 'aggregate: sum, "
+                        f"source: {source_col}') to resolve."
+                    )
+
+    return sampling_step
+
+
+def _sampling_transforms(x_field: str, step: int) -> list[dict[str, Any]]:
+    """Vega-Lite window + filter transforms for strip-cell sampling.
+
+    Assigns a 1-indexed row_number sorted ascending by x_field, then filters
+    to rows where (row_number - 1) % step == 0, keeping the first row and
+    every step-th row after it.
+    """
+    return [
+        {
+            "window": [{"op": "row_number", "as": "__data_table_row_index"}],
+            "sort": [{"field": x_field, "order": "ascending"}],
+        },
+        {"filter": f"(datum.__data_table_row_index - 1) % {step} === 0"},
+    ]
+
+
+def resolve_effective_data_table_style(
+    charts_style: MergedChartsStyle, chart_type: str
+) -> DataTableStyle:
+    """Resolve the effective data_table style for a chart.
+
+    Applies the per-chart-type override (tier 2, spec §4.1) on top of the
+    universal style.charts.data_table (tier 1). Tier 3 (chart-local patch)
+    is already merged into charts_style.data_table via pipeline.py before
+    this function is called.
+    """
+    base: DataTableStyle = charts_style.data_table
+    per_type = getattr(charts_style, chart_type, None)
+    if per_type is None:
+        return base
+    override = getattr(per_type, "data_table", None)
+    if override is None:
+        return base
+    return deep_merge(base, override)  # type: ignore[return-value]
+
+
+def attach_data_table(
+    spec: dict[str, Any],
+    *,
+    data_table: ChartDataTable | None,
+    style: DataTableStyle,
+    charts_style: MergedChartsStyle | None = None,
+    sampling_step: int = 1,
+    entry_dx: list[float] | None = None,
+    series_order: list[str] | None = None,
+    series_palette: list[str] | None = None,
+    label_period_filter_expr: str | None = None,
+    axis_y_orient: Literal["left", "right"],
+    formats: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """Append attached-data-table layers to a Vega-Lite chart spec.
+
+    Y-positioning is pixel-literal (`{"y": {"value": <px>}}`), anchored to
+    the spec's explicit height. Vega-Lite scales `{"y": {"expr": ...}}`
+    through the parent's y-scale rather than treating it as a pixel
+    literal, so the spec must carry an explicit height (Dataface's
+    standard renderer always sets one).
+
+    Args:
+        spec: Base Vega-Lite chart spec (mark + encoding, or already layered).
+        data_table: Parsed ChartDataTable block, or None for no-op.
+        style: Resolved DataTableStyle (already cascade-resolved).
+        charts_style: Resolved ChartsStyle for x-axis label offset computation.
+            Required when data_table is non-None.
+        sampling_step: When > 1, prepend a Vega-Lite window+filter transform
+            chain to each text-mark layer so only every Nth row renders a
+            cell. The chart's bar/line/area base layer is not affected.
+            Computed by validate_data_table_against_data for temporal/
+            quantitative x axes that exceed CHART_DATA_TABLE_MAX_X_TICKS.
+        entry_dx: Per-entry dx offsets (pixels) for band-centering. When
+            set, entry_dx[i] is applied as VL mark ``dx`` on the text layer
+            for entry i, shifting right-aligned text so the number lane's
+            centre aligns with the band midpoint (same invariant as
+            _compute_lane_positions in table.py: column centred, decimals
+            aligned within). Computed by the render layer from measured
+            max formatted widths; None means no centering (e.g. widths all zero).
+        series_order: For per_series entries — ordered list of series names
+            in the chart's stack/scale order. Required when any entry is a
+            ChartDataTablePerSeries. Callers resolve this from the parent
+            chart's color encoding domain.
+        series_palette: For per_series entries — the effective palette colours
+            for each series in series_order, used to resolve dark companion
+            label ink. When None, label fill is omitted.
+        label_period_filter_expr: Vega filter expression that restricts strip
+            cells to label-period openers. When set, each text-mark layer
+            receives a ``{"filter": label_period_filter_expr}`` transform so
+            only x-values that open a new label period (e.g. quarterly openers
+            on a monthly-band axis) emit a cell. Computed by the render layer
+            from the chart's encoding_time_unit / label_time_unit pair.
+        axis_y_orient: Resolved y-axis orient — ``"right"`` or ``"left"``
+            (line charts with right-edge endpoint labels). Determines which label
+            emitter fires: right-oriented → label at ``spec_width +
+            axis_y.label.padding`` with ``align: left``; left-oriented → label at
+            ``-axis_y.label.padding`` with ``align: right``. Required — callers must
+            resolve this from the chart's axis_y.orient before calling.
+
+    Returns:
+        New spec dict with attached layers appended and ``autosize`` set
+        to ``pad`` so the outer SVG expands to include the strip rather
+        than shrinking the plot. Padding is NOT touched — callers must
+        reserve the strip's height themselves via
+        ``data_table_strip_height``. Input spec not mutated.
+    """
+    if data_table is None or not data_table.entries:
+        return spec
+
+    if charts_style is None:
+        raise ValueError(
+            "attach_data_table requires charts_style when data_table is "
+            "non-None — x-axis label offset computation needs it."
+        )
+
+    spec_height = spec.get("height")
+    if not isinstance(spec_height, (int, float)) or spec_height <= 0:
+        raise ValueError(
+            "attach_data_table requires the spec to carry an explicit height "
+            "when data_table is non-None — pixel-literal strip positioning "
+            "has no anchor otherwise."
+        )
+
+    raw_width = spec.get("width")
+    spec_width = (
+        float(raw_width)
+        if isinstance(raw_width, (int, float)) and raw_width > 0
+        else None
+    )
+
+    # Compute the total number of visual rows.
+    # by_measure entries each expand to 1 row; normal per_series entries expand
+    # to N rows (one per series); source/aggregate entries are 1 row each.
+    n_visual_rows = 0
+    for entry in data_table.entries:
+        if isinstance(entry, ChartDataTablePerSeries):
+            if entry.by_measure:
+                n_visual_rows += 1
+            else:
+                n_visual_rows += len(series_order) if series_order else 1
+        else:
+            n_visual_rows += 1
+
+    # Extract parent x-encoding before wrapping (wrap moves encoding into the base layer).
+    #
+    # Three shapes are accepted:
+    #
+    # 1. Standard top-level encoding — `spec["encoding"]["x"]` is set. The bulk
+    #    of charts arrive here.
+    # 2. Layered VL spec with x per-layer only (no top-level encoding.x) — the
+    #    migrator's `type: layered` emission with multiple bar layers + chart-level
+    #    x + data_table renders into this shape: top-level `spec["encoding"]` is
+    #    empty/absent and every `spec["layer"][i]["encoding"]` carries the same
+    #    x. We anchor against `layer[0]`'s x.
+    # 3. Any other shape — raise ChartDataError. The strip needs an unambiguous
+    #    anchor; silently picking layer-0's x when other layers disagree (or when
+    #    resolve.scale.x is independent) would misalign the strip against the
+    #    other layers' x-buckets, which is the "wrong result that looks right"
+    #    failure mode the repo non-negotiables forbid.
+    _raw_top_encoding = spec.get("encoding")
+    top_encoding: dict[str, Any] = (
+        _raw_top_encoding if isinstance(_raw_top_encoding, dict) else {}
+    )
+    if "x" in top_encoding:
+        parent_x_enc = top_encoding["x"]
+    else:
+        from dataface.core.render.errors import ChartDataError
+
+        layers_inline = spec.get("layer")
+        if not isinstance(layers_inline, list) or not layers_inline:
+            raise ChartDataError(
+                "data_table attachment requires an x-encoding on the chart spec "
+                "or its layers; none found."
+            )
+        if spec.get("resolve", {}).get("scale", {}).get("x") == "independent":
+            raise ChartDataError(
+                "data_table strip cannot anchor to a layered spec with "
+                "resolve.scale.x == 'independent'; the layers have per-dataset "
+                "x scales and the strip cannot anchor coherently."
+            )
+        layer_x_encs = [
+            layer.get("encoding", {}).get("x")
+            for layer in layers_inline
+            if isinstance(layer, dict)
+        ]
+        non_null_x_encs = [enc for enc in layer_x_encs if isinstance(enc, dict)]
+        if not non_null_x_encs:
+            raise ChartDataError(
+                "data_table attachment requires an x-encoding on the chart spec "
+                "or its layers; none found."
+            )
+        first_x_field = non_null_x_encs[0].get("field")
+        for enc in non_null_x_encs[1:]:
+            if enc.get("field") != first_x_field:
+                raise ChartDataError(
+                    "data_table strip cannot anchor to a layered spec whose "
+                    "per-layer x-encodings disagree on field; lift x to chart "
+                    "level or remove data_table."
+                )
+        parent_x_enc = non_null_x_encs[0]
+    # Resolve the color field from the parent spec's top-level encoding for
+    # per_series entries. In the layered fallback case top-level encoding has
+    # no color (color lives per-layer); return None and let the per_series
+    # caller require an explicit series_order/series_palette.
+    parent_color_enc = top_encoding.get("color")
+    color_field: str | None = None
+    if isinstance(parent_color_enc, dict):
+        color_field = parent_color_enc.get("field")
+
+    out = _wrap_base_as_layer(spec)
+    layers: list[dict[str, Any]] = list(out["layer"])
+
+    if style.divider.width > 0:
+        layers.append(_divider_rule_layer(style, charts_style, spec_height))
+
+    _label_stub_limit: float = _LABEL_STUB_LIMIT_PX
+
+    # Track the current visual row index as we iterate entries. Source and
+    # aggregate entries each consume 1 row; per_series entries consume N rows.
+    visual_row_idx = 0
+    for i, entry in enumerate(data_table.entries):
+        row_dx = entry_dx[i] if entry_dx is not None else None
+        if isinstance(entry, ChartDataTablePerSeries):
+            if entry.by_measure:
+                # by_measure: one row per entry, no series expansion needed.
+                bm_layers = _per_series_row_layers(
+                    visual_row_idx,
+                    entry,
+                    parent_x_enc=parent_x_enc,
+                    color_field=None,
+                    series_order=[],
+                    series_palette=None,
+                    style=style,
+                    charts_style=charts_style,
+                    spec_height=spec_height,
+                    spec_width=spec_width,
+                    sampling_step=sampling_step,
+                    dx=row_dx,
+                    label_period_filter_expr=label_period_filter_expr,
+                    axis_y_orient=axis_y_orient,
+                    label_limit=_label_stub_limit,
+                )
+                layers.extend(bm_layers)
+                if style.row.rule.width > 0 and visual_row_idx < n_visual_rows - 1:
+                    layers.append(
+                        _row_rule_layer(
+                            visual_row_idx, style, charts_style, spec_height
+                        )
+                    )
+                visual_row_idx += 1
+            else:
+                if not series_order:
+                    raise ValueError(
+                        "attach_data_table requires series_order when per_series "
+                        "entries are present — callers must supply the ordered series "
+                        "list resolved from the parent chart's color encoding domain."
+                    )
+                if color_field is None:
+                    raise ValueError(
+                        "attach_data_table requires the spec to carry a color "
+                        "encoding when per_series entries are present."
+                    )
+                per_series_layers = _per_series_row_layers(
+                    visual_row_idx,
+                    entry,
+                    parent_x_enc=parent_x_enc,
+                    color_field=color_field,
+                    series_order=series_order,
+                    series_palette=series_palette,
+                    style=style,
+                    charts_style=charts_style,
+                    spec_height=spec_height,
+                    spec_width=spec_width,
+                    sampling_step=sampling_step,
+                    dx=row_dx,
+                    label_period_filter_expr=label_period_filter_expr,
+                    axis_y_orient=axis_y_orient,
+                    label_limit=_label_stub_limit,
+                    formats=formats,
+                )
+                layers.extend(per_series_layers)
+                n_series = len(series_order)
+                # Inter-row rules: emit ONE per pair of adjacent visual rows
+                # within the per_series block (n_series - 1 rules) plus one
+                # trailing rule between this block and the next entry — same
+                # cadence as source/aggregate rows, where every adjacent visual
+                # pair gets a rule. Without the within-block rules, the strip
+                # height accounting (which includes inter-row spacing for every
+                # visual row) reserves gaps where no rules are drawn.
+                if style.row.rule.width > 0:
+                    last_in_block = visual_row_idx + n_series - 1
+                    # Within-block rules: between each pair of adjacent series.
+                    for inner_idx in range(visual_row_idx, last_in_block):
+                        layers.append(
+                            _row_rule_layer(inner_idx, style, charts_style, spec_height)
+                        )
+                    # Trailing rule: between this block and the next entry.
+                    if last_in_block < n_visual_rows - 1:
+                        layers.append(
+                            _row_rule_layer(
+                                last_in_block, style, charts_style, spec_height
+                            )
+                        )
+                visual_row_idx += n_series
+        else:
+            row_layer = _row_text_layer(
+                visual_row_idx,
+                entry,
+                parent_x_enc=parent_x_enc,
+                style=style,
+                charts_style=charts_style,
+                spec_height=spec_height,
+                sampling_step=sampling_step,
+                dx=row_dx,
+                label_period_filter_expr=label_period_filter_expr,
+                formats=formats,
+            )
+            layers.append(row_layer)
+            label = getattr(entry, "label", None)
+            if label:
+                if axis_y_orient == "right":
+                    if spec_width is None:
+                        raise ValueError(
+                            "attach_data_table requires the spec to carry an explicit "
+                            "width when right-cap labels are present — pixel-literal "
+                            "label positioning has no anchor otherwise."
+                        )
+                    layers.append(
+                        _label_stub_right_layer(
+                            visual_row_idx,
+                            label,
+                            style=style,
+                            charts_style=charts_style,
+                            spec_height=spec_height,
+                            spec_width=spec_width,
+                            limit=_label_stub_limit,
+                        )
+                    )
+                else:
+                    layers.append(
+                        _label_stub_left_layer(
+                            visual_row_idx,
+                            label,
+                            style=style,
+                            charts_style=charts_style,
+                            spec_height=spec_height,
+                            limit=_label_stub_limit,
+                        )
+                    )
+            if style.row.rule.width > 0 and visual_row_idx < n_visual_rows - 1:
+                layers.append(
+                    _row_rule_layer(visual_row_idx, style, charts_style, spec_height)
+                )
+            visual_row_idx += 1
+
+    out["layer"] = layers
+    # Strip rows live outside the plot area (pixel y > spec.height for bottom;
+    # pixel y < 0 for top). Override the chart-wide `autosize: fit` default with
+    # `pad` so the outer SVG grows to include the strip rather than shrinking the plot. Trade-off: under
+    # `pad`, spec.width refers to the inner plot, so the outer SVG is wider
+    # than the requested width by axis-y label + padding overhead (constant
+    # regardless of requested width — see
+    # test_render_pipeline_svg_width_overhead_independent_of_requested_width).
+    # layout_sizing.py compensates symmetrically on both axes. The initial
+    # render-first sizing pass (_make_data_aware_height_provider) renders once
+    # to measure the width overhead, then re-renders with spec.width pre-shrunk.
+    # Cols alignment (_align_cols_heights) has a hard target_height, so after
+    # its alignment re-render it measures any height overhead and re-renders
+    # with spec.height pre-shrunk too. Both axes fit the slot.
+    out["autosize"] = {"type": "pad", "contains": "padding"}
+    return out