dataface 0.1.2__py3-none-any.whl

dataface/core/compile/models/style/merged.py

@@ -0,0 +1,1682 @@
+"""Style cascade-merge models — frozen dataclasses and merge logic.
+
+MergedXxx are frozen dataclasses (post-cascade, all fields required).
+resolve_style() merges a compiled Style with optional *Patch overlays and
+returns a MergedStyle for consumption by render/.
+"""
+
+from __future__ import annotations
+
+import copy
+import dataclasses
+import re
+import types
+from typing import Any, Literal, get_args, get_origin
+
+from pydantic import BaseModel
+
+from dataface.core.compile.models.primitives import (
+    BorderStyle,
+    FontStyle,
+    MergedFontStyle,
+    SpacingValues,
+    StrokeStyle,
+)
+from dataface.core.compile.models.style.compiled import (
+    AreaChartStyle,
+    AutosizeStyle,
+    AxisStyle,
+    AxisStylePatch,
+    BarChartStyle,
+    BoardStyle,
+    BoxplotChartStyle,
+    CalloutChartStyle,
+    ChartsStyle,
+    DataTableStyle,
+    ErrorbandChartStyle,
+    ErrorbarChartStyle,
+    GeoshapeChartStyle,
+    GlobalMarksStyle,
+    HeatmapChartStyle,
+    HistogramChartStyle,
+    InferenceStyle,
+    KpiChartStyle,
+    LayoutStyle,
+    LegendStyle,
+    LineChartStyle,
+    PaddingStyle,
+    PageStyle,
+    PaginationConfig,
+    PieChartStyle,
+    PlaceholderStyle,
+    PointMapChartStyle,
+    ScaleStyle,
+    ScatterChartStyle,
+    SeriesLabelStyle,
+    SparkBarChartStyle,
+    SparkStyle,
+    Style,
+    TableChartStyle,
+    TextStyle,
+    TitleStyle,
+    TooltipStyle,
+    VariablesStyle,
+    ViewStyle,
+)
+from dataface.core.fonts import NOTO_COLOR_EMOJI_FONT_FAMILY, NOTO_EMOJI_FONT_FAMILY
+
+_DEFAULT_ROOT_FONT = FontStyle(
+    family="Inter",
+    color="#222222",
+    size=14.0,
+    weight="400",
+    style="normal",
+    decoration="none",
+    case="none",
+)
+
+
+@dataclasses.dataclass(frozen=True)
+class MergedAxisElementStyle:
+    """Merged axis label or title — all fields required, no defaults.
+
+    Chart-local Patch fields (label.angle, label.padding, etc.) flow through
+    the typed ``axis_overrides_*`` sentinels on ``MergedChartsStyle`` and
+    are merged at emit time by ``resolved_axis_style``. They never land on a
+    Merged axis directly.
+    """
+
+    font: MergedFontStyle
+    padding: float
+    # Optional VL-passthrough fields — carried from theme through resolve boundary.
+    # None means "use VL default". Filled by _fill_axis cascade; passed through
+    # _build_resolved_axis. Mirrors AxisElementStyle passthrough fields.
+    max_width: float | None = None
+    angle: float | None = None
+    align: str | None = None
+    baseline: str | None = None
+    overlap: str | None = None
+    separation: float | None = None
+    visible: bool | None = None  # None = cascade-inherit from parent axis slot
+    time_unit: str | None = None
+    expr: str | None = None
+    bound: bool | float | None = None
+    flush: bool | float | None = None
+    offset: float | None = None
+    line_height: float | None = None
+    anchor: str | None = None
+    tilt_increments: list[float] | None = None
+
+
+@dataclasses.dataclass(frozen=True)
+class MergedAxisGridZeroStyle:
+    color: str
+    width: float
+
+
+@dataclasses.dataclass(frozen=True)
+class MergedAxisGridStyle:
+    """No defaults — must be explicitly constructed via resolve_style().
+
+    Same scope as MergedAxisElementStyle: chart-local grid overrides
+    (e.g. ``style.axis_y.grid.dash``) flow through ``axis_overrides_*``
+    and merge at emit time.
+    """
+
+    visible: bool
+    opacity: float
+    width: float
+    color: str
+    zero: MergedAxisGridZeroStyle
+
+
+@dataclasses.dataclass(frozen=True)
+class MergedAxisDomainStyle:
+    visible: bool
+    width: float
+    color: str
+
+
+@dataclasses.dataclass(frozen=True)
+class MergedAxisTicksStyle:
+    visible: bool
+    color: str
+    # None means "use VL default" — kept distinct from a numeric override.
+    width: float | None
+    size: float | None
+    # Target tick count for quantitative axes. None → VL picks automatically.
+    count: int | None
+
+
+@dataclasses.dataclass(frozen=True)
+class MergedAxisStyle:
+    """Merged per-axis style — theme-only.
+
+    All fields come through resolve_style(). Chart-local axis overrides
+    (style.axis_x, style.axis_y, etc.) are NOT merged onto these fields —
+    they flow through the typed ``axis_overrides_*`` sentinels on
+    ``MergedChartsStyle`` and merge at emit time via ``resolved_axis_style``.
+    Storing chart-local fields here would force the renderer to discriminate
+    authored vs theme values, which the cascade rename eliminates.
+    """
+
+    grid: MergedAxisGridStyle
+    domain: MergedAxisDomainStyle
+    ticks: MergedAxisTicksStyle
+    label: MergedAxisElementStyle
+    title: MergedAxisElementStyle
+    orient: str | None  # None is a valid concrete value ("use VL default")
+    categorical_orient: str | None
+    offset: float | None
+    scale: ScaleStyle | None  # per-axis scale override (board cascade only)
+    fill: Literal[
+        "null",
+        "zero",
+        "linear",
+        "step-after",
+        "step-before",
+        "step-center",
+        "curve",
+    ]  # only active on axis_x ordinal bucketed-time charts
+    format: str | None  # tick-label format string; None uses VL auto-format
+
+
+@dataclasses.dataclass(frozen=True)
+class MergedLegendElementStyle:
+    font: MergedFontStyle
+    padding: float
+
+
+@dataclasses.dataclass(frozen=True)
+class MergedLegendStyle:
+    """Merged legend style.
+
+    ``disable`` is a cascade-managed UX-default sentinel: None means
+    "legend visible" (neither theme nor chart suppressed it); True means
+    "explicitly suppressed" — set by the theme via _build_resolved_legend
+    or by a chart-local patch via build_resolved_style. The render layer
+    at _build_encoding_legend checks ``disable is True`` to emit VL
+    ``legend: null``.
+    """
+
+    orient: str
+    direction: str
+    label: MergedLegendElementStyle
+    title: MergedLegendElementStyle
+    interactive_legend: bool
+    disable: bool | None = None
+
+
+@dataclasses.dataclass(frozen=True)
+class MergedCalloutElementStyle:
+    font: MergedFontStyle
+    y_offset: float
+
+
+@dataclasses.dataclass(frozen=True)
+class MergedCalloutChartStyle:
+    tone: str | None
+    background: str
+    border: BorderStyle
+    padding: float
+    section_gap: float
+    title: MergedCalloutElementStyle
+    message: MergedCalloutElementStyle
+
+
+@dataclasses.dataclass(frozen=True)
+class MergedChartsStyle:
+    """Merged charts — all fields required, no defaults.
+
+    Board-level fields (title, pagination, font_family) are carried here for the
+    VL config mapper (n()) which takes MergedChartsStyle, not the full
+    MergedStyle. They are required (not defaulted) to enforce that every
+    MergedChartsStyle is constructed by _build_resolved_charts().
+    """
+
+    palette: list[str]
+    # Dash palette for line-family marks. None means "no strokeDash encoding";
+    # themes that want dash-based categorical distinction set this. The render
+    # layer reads None and skips emission. Cascade-managed sentinel.
+    dashes: list[list[int]] | None
+    # Theme-resolved axis layers (Layers 1+2+3 of the cascade). build_resolved_style
+    # does NOT merge chart-local axis Patches into these — they're stored on
+    # axis_overrides_* below so resolved_axis_style can apply them in the canonical
+    # cascade order at emit time. Renderer reads the merged AxisStyle that
+    # resolved_axis_style returns, never the override Patches directly.
+    axis: MergedAxisStyle
+    axis_x: MergedAxisStyle
+    axis_y: MergedAxisStyle
+    axis_quantitative: MergedAxisStyle
+    legend: MergedLegendStyle
+    # Remaining sections keep compiled types (skeleton — centralize task fills these)
+    inference: InferenceStyle
+    # Global mark defaults (tier 1 of three-tier cascade). Renderers read mark
+    # fields from per-family chart styles via resolve_mark(charts.marks.<mark>,
+    # family.marks.<mark>). This field is also read by style_to_vega_lite for
+    # the VL config emit (circle, square, tick, rule, etc.).
+    marks: GlobalMarksStyle
+    bar: BarChartStyle
+    line: LineChartStyle
+    area: AreaChartStyle
+    scatter: ScatterChartStyle
+    view: ViewStyle
+    # Series-label primitive — shared typography for endpoint labels,
+    # direct stack labels, and slice callouts.
+    series_label: SeriesLabelStyle
+    pie: PieChartStyle
+    geoshape: GeoshapeChartStyle
+    point_map: PointMapChartStyle
+    histogram: HistogramChartStyle
+    heatmap: HeatmapChartStyle
+    boxplot: BoxplotChartStyle
+    errorbar: ErrorbarChartStyle
+    errorband: ErrorbandChartStyle
+    autosize: AutosizeStyle
+    # Remaining chart dimensions (not yet resolved to concrete layout values)
+    aspect_ratio: float
+    min_height: float
+    max_height: float
+    padding: PaddingStyle
+    border: BorderStyle
+    animation_duration: float
+    kpi: KpiChartStyle
+    table: TableChartStyle
+    spark: SparkStyle
+    spark_bar: SparkBarChartStyle
+    data_table: DataTableStyle
+    # Callout chart-family style (type: callout and runtime chart-error fallback)
+    callout: MergedCalloutChartStyle
+    # Authorable chart rendering settings — migrated from chart_rendering config
+    tooltip: TooltipStyle
+    font_family: str | None  # root font.family; emitted as top-level VL `font`
+    title: TitleStyle
+    pagination: PaginationConfig | None
+
+    # Format alias vocabulary from the root Style.formats cascade.
+    # None = theme defines no format aliases. Render callsites pass this to
+    # resolve_format() so aliases resolve through the face→theme cascade.
+    formats: dict[str, str] | None = None
+
+    # Chart-local axis overrides (Layers 4/5/6) as typed AxisStylePatch
+    # sentinels — populated only by build_resolved_style from the chart's
+    # ChartStylePatch. None = no chart-local override on that axis variant.
+    # These are NOT exposed to chart emit code directly; resolved_axis_style is
+    # the single canonical reader, returning a fully-merged AxisStyle.
+    axis_overrides_global: AxisStylePatch | None = None
+    axis_overrides_x: AxisStylePatch | None = None
+    axis_overrides_y: AxisStylePatch | None = None
+    axis_overrides_quantitative: AxisStylePatch | None = None
+    axis_overrides_band: AxisStylePatch | None = None
+    # Chart-level scale override — populated only by build_resolved_style from
+    # style.scale. None = no chart-local global scale override.
+    scale: ScaleStyle | None = None
+    # Chart-local-only Vega passthroughs — populated by build_resolved_style
+    # from style.color / style.background / style.border. None = no chart-local
+    # override (renderer falls back to theme defaults).
+    color: str | None = None
+    # Chart-local background override — set by ChartStylePatch.background when
+    # a chart authors a per-chart background color. None = no chart-local override;
+    # standard_renderer._resolve_effective_background() falls back to face/theme.
+    background: str | None = None
+
+
+@dataclasses.dataclass(frozen=True)
+class MergedStyle:
+    """Final merged style — all fields required, no defaults.
+
+    The sole type accepted by the render/sizing layer. Every instance must
+    be produced by resolve_style() — never constructed directly.
+    """
+
+    background: str
+    accent: str
+    muted: str
+    font: MergedFontStyle
+    border: BorderStyle
+    box_shadow: str | None  # None = no shadow (valid concrete value)
+    opacity: float
+    board: BoardStyle
+    title: TitleStyle
+    text: TextStyle
+    placeholder: PlaceholderStyle
+    charts: MergedChartsStyle
+    layout: LayoutStyle
+    variables: VariablesStyle
+    page: PageStyle
+    # Per-face CSS-chrome. None = not authored; theme supplies no default.
+    padding: SpacingValues | None
+    margin: SpacingValues | None
+    gap: float | None
+    color: str | None
+
+
+def effective_padding(resolved: MergedStyle) -> SpacingValues:
+    """Return padding with border-occupancy added (half stroke inside the box)."""
+    pad = resolved.padding or SpacingValues()
+    bw = resolved.border.width
+    return SpacingValues(
+        top=pad.top + bw,
+        bottom=pad.bottom + bw,
+        left=pad.left + bw,
+        right=pad.right + bw,
+    )
+
+
+# =============================================================================
+# resolve_style
+# =============================================================================
+
+
+def _fill_font(target: FontStyle | None, source: FontStyle) -> FontStyle:
+    """Fill None fields in target from source (cascade inheritance).
+
+    If target is None (per-family font not authored), return source as-is.
+    """
+    if target is None:
+        return source
+    return FontStyle(
+        family=target.family if target.family is not None else source.family,
+        color=target.color if target.color is not None else source.color,
+        size=target.size if target.size is not None else source.size,
+        weight=target.weight if target.weight is not None else source.weight,
+        style=target.style if target.style is not None else source.style,
+        decoration=(
+            target.decoration if target.decoration is not None else source.decoration
+        ),
+        case=target.case if target.case is not None else source.case,
+    )
+
+
+def resolve_cascaded_font(font: FontStyle, path: str = "") -> MergedFontStyle:
+    """Convert FontStyle to MergedFontStyle, raising if any required field is None."""
+    if (
+        font.family is None
+        or font.color is None
+        or font.size is None
+        or font.weight is None
+        or font.style is None
+        or font.decoration is None
+        or font.case is None
+    ):
+        missing = [
+            f
+            for f, v in [
+                ("family", font.family),
+                ("color", font.color),
+                ("size", font.size),
+                ("weight", font.weight),
+                ("style", font.style),
+                ("decoration", font.decoration),
+                ("case", font.case),
+            ]
+            if v is None
+        ]
+        raise ValueError(
+            f"Cannot resolve font{' at ' + path if path else ''}: "
+            f"missing required fields after cascade: {missing}"
+        )
+    return MergedFontStyle(
+        family=font.family,
+        color=font.color,
+        size=font.size,
+        weight=font.weight,
+        style=font.style,
+        decoration=font.decoration,
+        case=font.case,
+    )
+
+
+# Dotted palette token: "<palette-name>.<slot>" — e.g. "dft-grays.gray-30",
+# "negative.solid", "category-10.0". The leading character must be a letter so
+# that hex literals (#abcdef), CSS rgb()/rgba() values, decimal numerics like
+# "0.5", and quoted font-family lists never match.
+#
+# Contract: any string anywhere in Style that matches this regex is
+# treated as a palette token. If a future non-color string field could match
+# (none today), it must be excluded from the walk or the field reshaped.
+_COLOR_TOKEN_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_-]*\.[A-Za-z0-9_-]+$")
+
+
+# Theme-self tokens: strings that name a value elsewhere in the same compiled
+# style tree, resolved against the root Style. The canonical use case
+# is canvas coupling — any field that should track the theme's background
+# color (knockout strokes, halos) sets the field to ``theme.background`` and
+# the resolver substitutes the theme's actual ``style.background`` value.
+#
+# Resolution runs BEFORE ``_resolve_color_tokens`` so the substituted value
+# (which may itself be a palette token like ``dft-creams.cream-025``) is
+# carried through the color-token pass. Each theme resolves against its own
+# ``style.background``, so cream's arc.stroke ends up at the cream
+# canvas color while stark's stays white — without per-theme
+# override duplication.
+#
+# Resolution runs at two points (mirroring _resolve_color_tokens): once at
+# theme-load time inside ``get_compiled_theme()`` so cached themes carry
+# concrete values, and again at the end of ``resolve_style()`` so face-level
+# patches that introduce self-tokens are also resolved. A face that authors
+# ``arc.stroke: theme.background`` in its own style block resolves the same
+# way as the theme YAML did — no asymmetric contract.
+_THEME_SELF_TOKENS = {"theme.background"}
+
+
+def _self_token_replacement(token: str, root: Style) -> str:
+    """Look up a theme-self token's replacement value on ``root``.
+
+    ``token`` is guaranteed to be a member of ``_THEME_SELF_TOKENS`` by the
+    caller; raises ``ValueError`` for any unknown token so a future
+    ``_THEME_SELF_TOKENS`` addition without a matching branch fails loudly
+    instead of silently leaking the literal sentinel into compiled output.
+    """
+    if token == "theme.background":
+        return root.background
+    raise ValueError(f"Unknown theme-self token: {token!r}")
+
+
+def _resolve_self_tokens(node: Any, root: Any | None = None) -> Any:
+    """Walk a Style subtree and substitute theme-self tokens.
+
+    ``root`` is the top-level Style the substitution looks values up
+    on; it defaults to ``node`` for the initial top-level call. The recursion
+    keeps the same root so deeply nested fields (e.g. ``charts.arc.stroke.color``)
+    resolve against the theme root, not against an enclosing sub-model.
+    """
+    if root is None:
+        root = node
+    if isinstance(node, BaseModel):
+        updates: dict[str, Any] = {}
+        for name, value in node:
+            new = _resolve_self_tokens(value, root)
+            if new is not value:
+                updates[name] = new
+        return node.model_copy(update=updates) if updates else node
+    if isinstance(node, str):
+        if node in _THEME_SELF_TOKENS:
+            return _self_token_replacement(node, root)
+        return node
+    if isinstance(node, list):
+        new_list = [_resolve_self_tokens(item, root) for item in node]
+        return (
+            new_list
+            if any(a is not b for a, b in zip(new_list, node, strict=True))
+            else node
+        )
+    return node
+
+
+def _resolve_one_color_token(
+    token: str,
+    palettes: dict[str, str] | None,
+    roles: dict[str, str] | None,
+) -> str:
+    """Resolve a single dotted color token to hex.
+
+    Tries the direct ``palette.slot`` path first.  If the left-hand side is not
+    a known palette name the token is a role-indirected address (e.g.
+    ``chrome.ink``); try ``color_from_theme()`` with the theme palettes/roles
+    context.  Raises ``UnknownColorError`` if both paths fail.
+    """
+    from dataface.core.compile.palette import (
+        UnknownColorError,
+        UnknownPaletteError,
+        color as resolve_palette_color,
+        color_from_theme,
+    )
+
+    try:
+        return resolve_palette_color(token)
+    except (UnknownColorError, UnknownPaletteError):
+        pass
+
+    if palettes is not None:
+        return color_from_theme(token, palettes=palettes, roles=roles)
+
+    raise UnknownColorError(
+        f"color token '{token}' is not a known palette.slot address and no "
+        "theme palettes context is available for role-indirection lookup"
+    )
+
+
+def _resolve_color_tokens(
+    node: Any,
+    palettes: dict[str, str] | None = None,
+    roles: dict[str, str] | None = None,
+) -> Any:
+    """Walk a Style subtree and resolve every dotted palette token to hex.
+
+    Strings that don't look like a palette token (literal hex, rgb()/rgba(),
+    CSS named colors, font-family lists, etc.) pass through unchanged. Lists
+    are walked element-by-element so ``charts.palette`` slots that happen to
+    be tokens (rare) are also resolved. Dicts are not walked — no
+    color-bearing dicts exist on Style today; if one is added it
+    needs to be handled here explicitly.
+
+    ``palettes`` and ``roles`` are extracted from the root Style at call time
+    and passed through the recursion so role-indirected tokens (e.g.
+    ``chrome.ink`` where ``chrome`` maps to a palette name via the theme's
+    ``palettes:`` block) resolve correctly alongside direct palette.slot tokens.
+
+    Run twice: once at theme-load time inside ``get_compiled_theme()`` so
+    cached themes carry hex, and again at the end of ``resolve_style()`` so
+    face-level patches that introduce tokens are also resolved.
+    """
+    from dataface.core.compile.models.style.compiled import Style
+
+    if isinstance(node, Style):
+        # Extract palettes/roles context from the root Style for this walk.
+        palettes = node.palettes
+        roles = node.roles
+    if isinstance(node, BaseModel):
+        updates: dict[str, Any] = {}
+        for name, value in node:
+            new = _resolve_color_tokens(value, palettes, roles)
+            if new is not value:
+                updates[name] = new
+        return node.model_copy(update=updates) if updates else node
+    if isinstance(node, str):
+        if _COLOR_TOKEN_RE.match(node):
+            return _resolve_one_color_token(node, palettes, roles)
+        return node
+    if isinstance(node, list):
+        new_list = [_resolve_color_tokens(item, palettes, roles) for item in node]
+        return (
+            new_list
+            if any(a is not b for a, b in zip(new_list, node, strict=True))
+            else node
+        )
+    return node
+
+
+_EMOJI_MODE_TO_FAMILY: dict[str, str] = {
+    "monochrome": NOTO_EMOJI_FONT_FAMILY,
+    "color": NOTO_COLOR_EMOJI_FONT_FAMILY,
+}
+
+
+def insert_emoji_family(family: str, emoji_family: str) -> str:
+    """Insert ``emoji_family`` after the primary font in a CSS font-family stack.
+
+    Idempotent: no-op if ``emoji_family`` is already present. Public so callers in
+    typography.py / sizing.py / render can append an emoji family to a raw
+    family string without the full resolve_style() cascade walk.
+    """
+    if emoji_family in family:
+        return family
+    # Assumes commas are CSS font-family stack separators, not quoted name characters.
+    first_comma = family.find(",")
+    if first_comma == -1:
+        return f"{family}, '{emoji_family}'"
+    return f"{family[:first_comma]}, '{emoji_family}'{family[first_comma:]}"
+
+
+def apply_emoji_to_family(
+    raw: str,
+    emoji_mode: str,
+) -> str:
+    """Conditionally insert the appropriate emoji family into a font-family stack.
+
+    Maps ``emoji_mode`` to a bundled emoji font family name and inserts it.
+    Returns ``raw`` unchanged for ``system-default`` and ``disabled``.
+    """
+    emoji_family = _EMOJI_MODE_TO_FAMILY.get(emoji_mode)
+    if emoji_family is None:
+        return raw
+    return insert_emoji_family(raw, emoji_family)
+
+
+def _append_emoji_family(node: Any, emoji_family: str) -> Any:
+    """Walk a style subtree and append ``emoji_family`` to every non-None FontStyle.family.
+
+    Mirrors _resolve_color_tokens in structure: walks BaseModel trees recursively,
+    returning a patched copy only when a field actually changes.
+    FontStyle never appears inside a list/dict field in this schema; if that
+    changes, add a list branch mirroring _resolve_color_tokens.
+    """
+    if isinstance(node, FontStyle):
+        if node.family is not None:
+            new_family = insert_emoji_family(node.family, emoji_family)
+            if new_family != node.family:
+                return node.model_copy(update={"family": new_family})
+        return node
+    if isinstance(node, BaseModel):
+        updates: dict[str, Any] = {}
+        for name, value in node:
+            new = _append_emoji_family(value, emoji_family)
+            if new is not value:
+                updates[name] = new
+        return node.model_copy(update=updates) if updates else node
+    return node
+
+
+def _non_none_model_type(annotation: Any) -> type[BaseModel] | None:
+    """From `T | None`, return T if T is a BaseModel subclass, else None."""
+    import typing
+
+    origin = get_origin(annotation)
+    if origin is types.UnionType or origin is typing.Union:
+        non_none = [a for a in get_args(annotation) if a is not type(None)]
+        if (
+            len(non_none) == 1
+            and isinstance(non_none[0], type)
+            and issubclass(non_none[0], BaseModel)
+        ):
+            return non_none[0]
+    return None
+
+
+def deep_merge(base: BaseModel, patch: Any | None) -> BaseModel:
+    """Recursively merge a patch (all-Optional) onto a compiled base.
+
+    - Non-None patch fields win over base.
+    - Nested BaseModel fields are merged recursively (field-by-field), so a
+      patch that sets only axis.label.font.color still inherits the rest of
+      axis.label and axis from base.
+    - dict fields are merged key-wise: patch keys win, base keys not in patch survive.
+      This allows face.style.formats to override individual theme aliases without
+      replacing the entire dict.
+    - Scalars, lists, and Any-typed fields are replaced wholesale when non-None.
+    - None patch fields inherit from base.
+    - Patch fields whose name does not exist on base are ignored (the base type
+      defines the field set; this lets a Merged* base accept a bare-noun *Patch
+      that carries extra fields the merged type chose not to model).
+
+    Returns a new instance of the same type as base.
+    """
+    if patch is None:
+        return base
+    result = {}
+    for field_name in type(base).model_fields:
+        base_val = getattr(base, field_name)
+        patch_val = getattr(patch, field_name, None)
+        if patch_val is None:
+            result[field_name] = base_val
+        elif isinstance(base_val, BaseModel) and isinstance(patch_val, BaseModel):
+            result[field_name] = deep_merge(base_val, patch_val)
+        elif isinstance(base_val, dict) and isinstance(patch_val, dict):
+            result[field_name] = {**base_val, **patch_val}
+        elif isinstance(patch_val, BaseModel):
+            # base_val is None — decide based on whether the compiled field type
+            # can be seeded from a partial patch dict (all fields have defaults).
+            # ScaleStyle and similar all-Optional compiled types: use the patch.
+            # TitleStyle and others with required fields: leave as None (callers
+            # like build_resolved_style extract those fields through a separate path).
+            ann = type(base).model_fields[field_name].annotation
+            target = _non_none_model_type(ann)
+            if target is not None and not any(
+                fi.is_required() for fi in target.model_fields.values()
+            ):
+                result[field_name] = patch_val.model_dump(exclude_none=True)
+            else:
+                result[field_name] = None
+        else:
+            result[field_name] = patch_val
+    return type(base).model_validate(result)
+
+
+_M = Any  # BaseModel subtype; TypeVar would require a bound import
+
+
+def resolve_mark(global_mark: _M, family_override: _M | None) -> _M:
+    """Merge the global mark default with an optional family-level override.
+
+    Implements tier-1 + tier-2 of the three-tier mark cascade (global → family).
+    Face-level overrides (tier 3) are applied by build_resolved_style if present.
+
+    Returns ``global_mark`` unchanged when ``family_override`` is None.
+    """
+    if family_override is None:
+        return global_mark
+    return deep_merge(global_mark, family_override)
+
+
+def _fill_none(model: _M, **tokens: Any) -> _M:
+    """Fill only None fields of model from tokens; explicit values are preserved."""
+    updates = {f: v for f, v in tokens.items() if getattr(model, f) is None}
+    return model.model_copy(update=updates) if updates else model
+
+
+def _fill_chart_base(family_style: _M, charts: ChartsStyle) -> _M:
+    """Fill _ChartStyleBaseAllOptional sentinels from ChartsStyle global defaults.
+
+    Called for every per-family style in _apply_cascade.  None sentinels on
+    the family style inherit the corresponding required value from ChartsStyle.
+
+    Only scalar fields are filled here.  Nested BaseModel fields (legend, padding,
+    border, inference, tooltip) are now patch types (LegendStylePatch | None etc.)
+    due to is_recursive=True on _ChartStyleBaseAllOptional.  Filling them with
+    compiled-type values (LegendStyle, PaddingStyle, etc.) would mix types.
+    Per-family legend/padding/etc. overrides authored in theme YAML are applied
+    in build_resolved_style via chart_type-aware patch application.
+    """
+    return _fill_none(
+        family_style,
+        aspect_ratio=charts.aspect_ratio,
+        min_height=charts.min_height,
+        max_height=charts.max_height,
+        animation_duration=charts.animation_duration,
+        palette=charts.palette,
+        dashes=charts.dashes,
+    )
+
+
+def _cascade_family_marks(family: _M, global_marks: Any) -> _M:
+    """Cascade global mark defaults into every mark slot of a family's marks container.
+
+    For each mark field shared between the family marks container and GlobalMarksStyle,
+    applies resolve_mark(global_val, family_val) so that:
+    - None family slots inherit the full global mark (including nested required fields).
+    - Non-None family slots are deep-merged on top of global, preserving fields the
+      family doesn't override (e.g. pie.marks.slice sets gap/stroke but not labels —
+      labels cascades from global so build_resolved_style always has a complete base).
+    """
+    family_marks = family.marks
+    updates = {}
+    for field_name in type(family_marks).model_fields:
+        global_val = getattr(global_marks, field_name, None)
+        if global_val is None:
+            continue
+        updates[field_name] = resolve_mark(
+            global_val, getattr(family_marks, field_name)
+        )
+    if not updates:
+        return family
+    return family.model_copy(update={"marks": family_marks.model_copy(update=updates)})
+
+
+def _fill_stroke_color(mark: Any, color: str) -> Any:
+    """Fill mark.stroke.color from root font color when not already set.
+
+    Used for TickMarkStyle/RuleMarkStyle whose stroke.color cascades from
+    root font.color via _apply_token_cascade.
+    """
+    if mark.stroke is None:
+        return mark.model_copy(update={"stroke": StrokeStyle(color=color)})
+    if mark.stroke.color is None:
+        return mark.model_copy(
+            update={"stroke": mark.stroke.model_copy(update={"color": color})}
+        )
+    return mark
+
+
+def _apply_token_cascade(merged: Style) -> Style:
+    """Fill None sub-fields from root semantic tokens (accent, muted, font.color).
+
+    Cascade invariant (ADR-009): token cascade runs ONLY inside resolve_style(),
+    after all face/chart patches have been merged. Running it earlier (e.g. at
+    theme load time) would fill sub-fields to concrete values, making them
+    invisible to _fill_none and silently dropping face-level token overrides.
+
+    Tokens: accent → spark.color, spark.bar.color, spark_bar.bar.color,
+            input.focus_color; muted → spark.bar.background,
+            spark_bar.bar_background; font.color → tick.stroke.color, rule.stroke.color.
+    """
+    accent = merged.accent
+    muted = merged.muted
+    # _DEFAULT_ROOT_FONT.color is FontStyle.color (str | None), so spell out
+    # the literal fallback to keep root_color: str for mypy.
+    root_color: str = merged.font.color if merged.font.color is not None else "#222222"
+
+    spark = merged.charts.table.spark
+    new_spark = _fill_none(spark, color=accent).model_copy(
+        update={"bar": _fill_none(spark.bar, color=accent, background=muted)}
+    )
+
+    cascaded_marks = merged.charts.marks.model_copy(
+        update={
+            "tick": _fill_stroke_color(merged.charts.marks.tick, root_color),
+            "rule": _fill_stroke_color(merged.charts.marks.rule, root_color),
+        }
+    )
+    cascaded_charts = merged.charts.model_copy(
+        update={
+            "table": merged.charts.table.model_copy(update={"spark": new_spark}),
+            "spark_bar": merged.charts.spark_bar.model_copy(
+                update={
+                    "bar": _fill_none(
+                        merged.charts.spark_bar.bar, color=accent, background=muted
+                    )
+                }
+            ),
+            "marks": cascaded_marks,
+        }
+    )
+    return merged.model_copy(
+        update={
+            "charts": cascaded_charts,
+            "variables": merged.variables.model_copy(
+                update={"input": _fill_none(merged.variables.input, focus_color=accent)}
+            ),
+        }
+    )
+
+
+def _cascade_variables(variables: VariablesStyle, root: FontStyle) -> VariablesStyle:
+    """Cascade root font → variables.font → variables.{label,value,placeholder}.font."""
+    variables_font = _fill_font(variables.font, root)
+    return variables.model_copy(
+        update={
+            "font": variables_font,
+            "label": variables.label.model_copy(
+                update={"font": _fill_font(variables.label.font, variables_font)}
+            ),
+            "value": variables.value.model_copy(
+                update={"font": _fill_font(variables.value.font, variables_font)}
+            ),
+            "placeholder": variables.placeholder.model_copy(
+                update={"font": _fill_font(variables.placeholder.font, variables_font)}
+            ),
+        }
+    )
+
+
+# Fields on AxisElementStyle that are optional VL passthroughs:
+# cascaded from parent axis to child (axis_x/y/etc.) in _fill_axis,
+# then carried through _build_resolved_axis to MergedAxisElementStyle.
+_ELEM_PASSTHROUGH = (
+    "max_width",
+    "angle",
+    "align",
+    "baseline",
+    "overlap",
+    "separation",
+    "visible",
+    "time_unit",
+    "expr",
+    "bound",
+    "flush",
+    "offset",
+    "line_height",
+    "anchor",
+    "tilt_increments",
+)
+
+
+def _apply_cascade(merged: Style) -> Style:
+    """Apply semantic token cascade + ADR-003 font cascade.
+
+    Two-phase cascade applied after all patches are merged:
+    1. Token cascade (_apply_token_cascade): accent/muted/font.color → spark,
+       spark_bar, tick, rule, focus_color.
+    2. Font cascade: root font fills unset font fields at all text-bearing levels.
+       Hierarchy: root → charts_font → axis/legend/kpi/spark_bar/text/table;
+       table_font → table.header/title/more_rows/empty_state;
+       board_font → board.title.
+
+    Font cascade is deferred here (not at theme load time) so face-level font
+    overrides can propagate through the hierarchy — _fill_font only fills None
+    fields, so pre-filling at load time would prevent face patches propagating.
+    """
+    # Phase 1: semantic token cascade
+    merged = _apply_token_cascade(merged)
+
+    # Phase 2: font cascade
+    # Fill the root font from the fallback, then put back a RootFontStyle
+    # so the emoji field (only present on the root, not on nested FontStyle) is
+    # preserved through the cascade for the emoji-injection gate in resolve_style.
+    _filled_root = _fill_font(merged.font, _DEFAULT_ROOT_FONT)
+    root = merged.font.model_copy(
+        update={
+            "family": _filled_root.family,
+            "color": _filled_root.color,
+            "size": _filled_root.size,
+            "weight": _filled_root.weight,
+            "style": _filled_root.style,
+            "decoration": _filled_root.decoration,
+            "case": _filled_root.case,
+        }
+    )
+    charts_font = _fill_font(merged.charts.font, root)
+
+    def _fill_axis(axis: AxisStyle, parent: AxisStyle | None = None) -> AxisStyle:
+        # When parent is supplied (axis_x/y/quantitative), every None field in
+        # grid / domain / ticks inherits from the canonical `axis` slot.  This
+        # lets the base theme write only intentional differences in the child
+        # axis types — everything else cascades from `axis`.
+        grid = axis.grid
+        domain = axis.domain
+        ticks = axis.ticks
+        if parent is not None:
+            grid_updates = {
+                f: getattr(parent.grid, f)
+                for f in ("visible", "opacity", "width", "color")
+                if getattr(grid, f) is None and getattr(parent.grid, f) is not None
+            }
+            if grid_updates:
+                grid = grid.model_copy(update=grid_updates)
+            # Cascade zero sub-object field-by-field from parent axis slot.
+            if parent.grid.zero is not None:
+                if grid.zero is None:
+                    grid = grid.model_copy(update={"zero": parent.grid.zero})
+                else:
+                    zero_updates = {
+                        f: getattr(parent.grid.zero, f)
+                        for f in ("color", "width")
+                        if getattr(grid.zero, f) is None
+                        and getattr(parent.grid.zero, f) is not None
+                    }
+                    if zero_updates:
+                        grid = grid.model_copy(
+                            update={"zero": grid.zero.model_copy(update=zero_updates)}
+                        )
+            domain_updates = {
+                f: getattr(parent.domain, f)
+                for f in ("visible", "width", "color")
+                if getattr(domain, f) is None and getattr(parent.domain, f) is not None
+            }
+            if domain_updates:
+                domain = domain.model_copy(update=domain_updates)
+            ticks_updates = {
+                f: getattr(parent.ticks, f)
+                for f in ("visible", "color", "size", "width")
+                if getattr(ticks, f) is None and getattr(parent.ticks, f) is not None
+            }
+            if ticks_updates:
+                ticks = ticks.model_copy(update=ticks_updates)
+        # label/title font cascade: per-axis font fills missing fields from the
+        # canonical `axis` parent first, then from charts_font.  Without the
+        # parent step, an override on `charts.axis.label.font.color` would only
+        # land on `config.axis` and be clobbered by `config.axisX/Y` defaults.
+        label_parent_font = parent.label.font if parent is not None else charts_font
+        title_parent_font = parent.title.font if parent is not None else charts_font
+        label_padding = axis.label.padding
+        if label_padding is None and parent is not None:
+            label_padding = parent.label.padding
+        title_padding = axis.title.padding
+        if title_padding is None and parent is not None:
+            title_padding = parent.title.padding
+        if parent is not None:
+            label_passthrough = {
+                f: getattr(parent.label, f)
+                for f in _ELEM_PASSTHROUGH
+                if getattr(axis.label, f) is None
+                and getattr(parent.label, f) is not None
+            }
+            title_passthrough = {
+                f: getattr(parent.title, f)
+                for f in _ELEM_PASSTHROUGH
+                if getattr(axis.title, f) is None
+                and getattr(parent.title, f) is not None
+            }
+        else:
+            label_passthrough = {}
+            title_passthrough = {}
+        return axis.model_copy(
+            update={
+                "grid": grid,
+                "domain": domain,
+                "ticks": ticks,
+                "label": axis.label.model_copy(
+                    update={
+                        "font": _fill_font(
+                            _fill_font(axis.label.font, label_parent_font),
+                            charts_font,
+                        ),
+                        "padding": label_padding,
+                        **label_passthrough,
+                    }
+                ),
+                "title": axis.title.model_copy(
+                    update={
+                        "font": _fill_font(
+                            _fill_font(axis.title.font, title_parent_font),
+                            charts_font,
+                        ),
+                        "padding": title_padding,
+                        **title_passthrough,
+                    }
+                ),
+            }
+        )
+
+    def _fill_legend(legend: LegendStyle) -> LegendStyle:
+        return legend.model_copy(
+            update={
+                "label": legend.label.model_copy(
+                    update={"font": _fill_font(legend.label.font, charts_font)}
+                ),
+                "title": legend.title.model_copy(
+                    update={"font": _fill_font(legend.title.font, charts_font)}
+                ),
+            }
+        )
+
+    def _fill_callout_chart(
+        callout: CalloutChartStyle,
+    ) -> CalloutChartStyle:
+        return callout.model_copy(
+            update={
+                "title": callout.title.model_copy(
+                    update={"font": _fill_font(callout.title.font, charts_font)}
+                ),
+                "message": callout.message.model_copy(
+                    update={"font": _fill_font(callout.message.font, charts_font)}
+                ),
+            }
+        )
+
+    kpi_font = _fill_font(merged.charts.kpi.font, charts_font)
+    cascaded_kpi = merged.charts.kpi.model_copy(
+        update={
+            "font": kpi_font,
+            "value": merged.charts.kpi.value.model_copy(
+                update={"font": _fill_font(merged.charts.kpi.value.font, kpi_font)}
+            ),
+            "label": merged.charts.kpi.label.model_copy(
+                update={"font": _fill_font(merged.charts.kpi.label.font, kpi_font)}
+            ),
+            "affix": merged.charts.kpi.affix.model_copy(
+                update={"font": _fill_font(merged.charts.kpi.affix.font, kpi_font)}
+            ),
+            "glyph": merged.charts.kpi.glyph.model_copy(
+                update={"font": _fill_font(merged.charts.kpi.glyph.font, kpi_font)}
+            ),
+        }
+    )
+
+    cascaded_spark_bar = merged.charts.spark_bar.model_copy(
+        update={"font": _fill_font(merged.charts.spark_bar.font, charts_font)}
+    )
+
+    table_font = _fill_font(merged.charts.table.font, charts_font)
+    cascaded_bar = merged.charts.table.spark.bar.model_copy(
+        update={"font": _fill_font(merged.charts.table.spark.bar.font, charts_font)}
+    )
+    cascaded_spark = merged.charts.table.spark.model_copy(update={"bar": cascaded_bar})
+    cascaded_table = merged.charts.table.model_copy(
+        update={
+            "font": table_font,
+            "header": merged.charts.table.header.model_copy(
+                update={"font": _fill_font(merged.charts.table.header.font, table_font)}
+            ),
+            "title_row": merged.charts.table.title_row.model_copy(
+                update={
+                    "font": _fill_font(merged.charts.table.title_row.font, table_font)
+                }
+            ),
+            "more_rows": merged.charts.table.more_rows.model_copy(
+                update={
+                    "font": _fill_font(merged.charts.table.more_rows.font, table_font)
+                }
+            ),
+            "empty_state": merged.charts.table.empty_state.model_copy(
+                update={
+                    "font": _fill_font(merged.charts.table.empty_state.font, table_font)
+                }
+            ),
+            "spark": cascaded_spark,
+        }
+    )
+
+    # data_table font cascade: charts_font → data_table.font,
+    # then data_table.font → divider-less leaves (label).
+    data_table_font = _fill_font(merged.charts.data_table.font, charts_font)
+    cascaded_data_table = merged.charts.data_table.model_copy(
+        update={
+            "font": data_table_font,
+            "label": merged.charts.data_table.label.model_copy(
+                update={
+                    "font": _fill_font(
+                        merged.charts.data_table.label.font, data_table_font
+                    )
+                }
+            ),
+        }
+    )
+
+    cascaded_axis = _fill_axis(merged.charts.axis)
+    cascaded_pie_total = merged.charts.pie.total.model_copy(
+        update={
+            "value": merged.charts.pie.total.value.model_copy(
+                update={
+                    "font": _fill_font(merged.charts.pie.total.value.font, charts_font)
+                }
+            ),
+            "label": merged.charts.pie.total.label.model_copy(
+                update={
+                    "font": _fill_font(merged.charts.pie.total.label.font, charts_font)
+                }
+            ),
+        }
+    )
+    # Pie slice labels: live under pie.marks.slice.labels after ADR-015 migration.
+    # PieChartMarksStyle.slice is Optional (None = no family-level override).
+    # When slice is set, cascade the font into its labels.
+    pie_marks = merged.charts.pie.marks
+    pie_marks_slice = pie_marks.slice
+    if pie_marks_slice is not None and pie_marks_slice.labels is not None:
+        cascaded_slice_labels = pie_marks_slice.labels.model_copy(
+            update={"font": _fill_font(pie_marks_slice.labels.font, charts_font)}
+        )
+        cascaded_pie_marks_slice = pie_marks_slice.model_copy(
+            update={"labels": cascaded_slice_labels}
+        )
+        cascaded_pie_marks = pie_marks.model_copy(
+            update={"slice": cascaded_pie_marks_slice}
+        )
+        cascaded_pie = merged.charts.pie.model_copy(
+            update={"total": cascaded_pie_total, "marks": cascaded_pie_marks}
+        )
+    else:
+        cascaded_pie = merged.charts.pie.model_copy(
+            update={"total": cascaded_pie_total}
+        )
+
+    # Global marks — font cascade: text (renamed label) + slice labels.
+    # tick/rule stroke.color already set by _apply_token_cascade (Phase 1).
+    marks_updates: dict[str, Any] = {
+        "text": merged.charts.marks.text.model_copy(
+            update={"font": _fill_font(merged.charts.marks.text.font, charts_font)}
+        ),
+    }
+    if merged.charts.marks.slice.labels is not None:
+        marks_updates["slice"] = merged.charts.marks.slice.model_copy(
+            update={
+                "labels": merged.charts.marks.slice.labels.model_copy(
+                    update={
+                        "font": _fill_font(
+                            merged.charts.marks.slice.labels.font, charts_font
+                        )
+                    }
+                )
+            }
+        )
+    cascaded_marks = merged.charts.marks.model_copy(update=marks_updates)
+
+    _c = merged.charts  # shorthand for the per-family fill calls below
+
+    cascaded_charts = merged.charts.model_copy(
+        update={
+            "font": charts_font,
+            "axis": cascaded_axis,
+            "axis_x": _fill_axis(merged.charts.axis_x, parent=cascaded_axis),
+            "axis_y": _fill_axis(merged.charts.axis_y, parent=cascaded_axis),
+            "axis_quantitative": _fill_axis(
+                merged.charts.axis_quantitative, parent=cascaded_axis
+            ),
+            "legend": _fill_legend(merged.charts.legend),
+            "marks": cascaded_marks,
+            "series_label": merged.charts.series_label.model_copy(
+                update={
+                    "font": _fill_font(merged.charts.series_label.font, charts_font)
+                }
+            ),
+            # Per-family cascade: fill _ChartStyleBase sentinel fields
+            # (height, width, aspect_ratio, min_height, max_height, padding,
+            # border, animation_duration, palette, dashes, inference, legend,
+            # tooltip) from ChartsStyle global defaults.
+            # _cascade_family_marks also runs here: it deep-merges global mark
+            # defaults into every slot of each family's marks container so that
+            # build_resolved_style always has a complete compiled mark as the base
+            # for face-level overrides (no base_val=None gaps in deep_merge).
+            "bar": _cascade_family_marks(_fill_chart_base(_c.bar, _c), cascaded_marks),
+            "line": _cascade_family_marks(
+                _fill_chart_base(_c.line, _c), cascaded_marks
+            ),
+            "area": _cascade_family_marks(
+                _fill_chart_base(_c.area, _c), cascaded_marks
+            ),
+            "scatter": _cascade_family_marks(
+                _fill_chart_base(_c.scatter, _c), cascaded_marks
+            ),
+            "histogram": _cascade_family_marks(
+                _fill_chart_base(_c.histogram, _c), cascaded_marks
+            ),
+            "heatmap": _cascade_family_marks(
+                _fill_chart_base(_c.heatmap, _c), cascaded_marks
+            ),
+            "boxplot": _cascade_family_marks(
+                _fill_chart_base(_c.boxplot, _c), cascaded_marks
+            ),
+            "errorbar": _cascade_family_marks(
+                _fill_chart_base(_c.errorbar, _c), cascaded_marks
+            ),
+            "errorband": _cascade_family_marks(
+                _fill_chart_base(_c.errorband, _c), cascaded_marks
+            ),
+            "geoshape": _cascade_family_marks(
+                _fill_chart_base(_c.geoshape, _c), cascaded_marks
+            ),
+            "point_map": _cascade_family_marks(
+                _fill_chart_base(_c.point_map, _c), cascaded_marks
+            ),
+            # For families with pre-existing font cascade, apply geometry fill
+            # to the already-cascaded version so both passes take effect.
+            "pie": _cascade_family_marks(
+                _fill_chart_base(cascaded_pie, _c), cascaded_marks
+            ),
+            "kpi": _fill_chart_base(cascaded_kpi, _c),
+            "table": _fill_chart_base(cascaded_table, _c),
+            "spark_bar": cascaded_spark_bar,
+            "data_table": cascaded_data_table,
+            "callout": _fill_callout_chart(merged.charts.callout),
+        }
+    )
+
+    return merged.model_copy(
+        update={
+            "font": root,
+            "title": merged.title.model_copy(
+                update={
+                    "font": _fill_font(merged.title.font, root),
+                    "subtitle": merged.title.subtitle.model_copy(
+                        update={"font": _fill_font(merged.title.subtitle.font, root)}
+                    ),
+                }
+            ),
+            "text": merged.text.model_copy(
+                update={"font": _fill_font(merged.text.font, root)}
+            ),
+            "placeholder": merged.placeholder.model_copy(
+                update={
+                    "overlay": merged.placeholder.overlay.model_copy(
+                        update={
+                            "font": _fill_font(merged.placeholder.overlay.font, root)
+                        }
+                    )
+                }
+            ),
+            "charts": cascaded_charts,
+            "layout": merged.layout.model_copy(
+                update={
+                    "tabs": merged.layout.tabs.model_copy(
+                        update={"font": _fill_font(merged.layout.tabs.font, root)}
+                    ),
+                    "details": merged.layout.details.model_copy(
+                        update={"font": _fill_font(merged.layout.details.font, root)}
+                    ),
+                }
+            ),
+            "variables": _cascade_variables(merged.variables, root),
+        }
+    )
+
+
+def _build_resolved_axis(axis: AxisStyle) -> MergedAxisStyle:
+    def _require(value: Any, path: str) -> Any:
+        if value is None:
+            raise ValueError(
+                f"{path} must be authored by the theme or cascade from axis"
+            )
+        return value
+
+    return MergedAxisStyle(
+        grid=MergedAxisGridStyle(
+            visible=_require(axis.grid.visible, "charts.axis.grid.visible"),
+            opacity=_require(axis.grid.opacity, "charts.axis.grid.opacity"),
+            width=_require(axis.grid.width, "charts.axis.grid.width"),
+            color=_require(axis.grid.color, "charts.axis.grid.color"),
+            zero=MergedAxisGridZeroStyle(
+                color=_require(
+                    axis.grid.zero.color if axis.grid.zero else None,
+                    "charts.axis.grid.zero.color",
+                ),
+                width=_require(
+                    axis.grid.zero.width if axis.grid.zero else None,
+                    "charts.axis.grid.zero.width",
+                ),
+            ),
+        ),
+        domain=MergedAxisDomainStyle(
+            visible=_require(axis.domain.visible, "charts.axis.domain.visible"),
+            width=_require(axis.domain.width, "charts.axis.domain.width"),
+            color=_require(axis.domain.color, "charts.axis.domain.color"),
+        ),
+        ticks=MergedAxisTicksStyle(
+            visible=_require(axis.ticks.visible, "charts.axis.ticks.visible"),
+            color=_require(axis.ticks.color, "charts.axis.ticks.color"),
+            width=axis.ticks.width,
+            size=axis.ticks.size,
+            count=axis.ticks.count,
+        ),
+        label=MergedAxisElementStyle(
+            font=resolve_cascaded_font(axis.label.font, "charts.axis.label.font"),
+            padding=_require(axis.label.padding, "charts.axis.label.padding"),
+            **{f: getattr(axis.label, f) for f in _ELEM_PASSTHROUGH},
+        ),
+        title=MergedAxisElementStyle(
+            font=resolve_cascaded_font(axis.title.font, "charts.axis.title.font"),
+            padding=_require(axis.title.padding, "charts.axis.title.padding"),
+            **{f: getattr(axis.title, f) for f in _ELEM_PASSTHROUGH},
+        ),
+        orient=axis.orient,
+        categorical_orient=axis.categorical_orient,
+        offset=axis.offset,
+        scale=axis.scale,
+        fill=axis.fill,
+        format=axis.format,
+    )
+
+
+def _build_resolved_legend(legend: LegendStyle) -> MergedLegendStyle:
+    return MergedLegendStyle(
+        orient=legend.orient,
+        direction=legend.direction,
+        disable=legend.disable,
+        interactive_legend=legend.interactive_legend,
+        label=MergedLegendElementStyle(
+            font=resolve_cascaded_font(legend.label.font, "charts.legend.label.font"),
+            padding=legend.label.padding,
+        ),
+        title=MergedLegendElementStyle(
+            font=resolve_cascaded_font(legend.title.font, "charts.legend.title.font"),
+            padding=legend.title.padding,
+        ),
+    )
+
+
+def _build_resolved_callout_chart(
+    callout: CalloutChartStyle,
+) -> MergedCalloutChartStyle:
+    return MergedCalloutChartStyle(
+        tone=callout.tone,
+        background=callout.background,
+        border=callout.border,
+        padding=callout.padding,
+        section_gap=callout.section_gap,
+        title=MergedCalloutElementStyle(
+            font=resolve_cascaded_font(callout.title.font, "charts.callout.title.font"),
+            y_offset=callout.title.y_offset,
+        ),
+        message=MergedCalloutElementStyle(
+            font=resolve_cascaded_font(
+                callout.message.font, "charts.callout.message.font"
+            ),
+            y_offset=callout.message.y_offset,
+        ),
+    )
+
+
+def _build_resolved_charts(
+    charts: ChartsStyle,
+    font_family: str | None,
+    title: TitleStyle,
+    spark: SparkStyle,
+    pagination: PaginationConfig | None,
+    formats: dict[str, str] | None = None,
+) -> MergedChartsStyle:
+    # Axis/legend/callout are type-transformed; the rest are supplied by params or
+    # copied directly from charts where the field name matches.
+    _AXIS_LEGEND_ERROR = {
+        "axis",
+        "axis_x",
+        "axis_y",
+        "axis_quantitative",
+        "legend",
+        "callout",
+    }
+    _FROM_PARAMS = {
+        "font_family",
+        "title",
+        "spark",
+        "pagination",
+        "formats",
+    }
+    # Chart-local-only fields that have no representation on ChartsStyle —
+    # they're populated only by build_resolved_style from a chart's ChartStylePatch.
+    # Default to None at theme-resolve time.
+    _CHART_LOCAL_ONLY = {
+        "scale",
+        "axis_overrides_global",
+        "axis_overrides_x",
+        "axis_overrides_y",
+        "axis_overrides_quantitative",
+        "axis_overrides_band",
+        "color",
+        "background",
+    }
+    passthrough = {
+        name: getattr(charts, name)
+        for name in (f.name for f in dataclasses.fields(MergedChartsStyle))
+        if name not in _AXIS_LEGEND_ERROR
+        and name not in _FROM_PARAMS
+        and name not in _CHART_LOCAL_ONLY
+    }
+    return MergedChartsStyle(
+        **passthrough,
+        axis=_build_resolved_axis(charts.axis),
+        axis_x=_build_resolved_axis(charts.axis_x),
+        axis_y=_build_resolved_axis(charts.axis_y),
+        axis_quantitative=_build_resolved_axis(charts.axis_quantitative),
+        legend=_build_resolved_legend(charts.legend),
+        callout=_build_resolved_callout_chart(charts.callout),
+        font_family=font_family,
+        title=title,
+        spark=spark,
+        pagination=pagination,
+        formats=formats,
+    )
+
+
+_RESOLVED_STYLE_CACHE: dict[int, tuple[Style, MergedStyle]] = {}
+
+
+def clear_resolve_style_cache() -> None:
+    """Clear cached no-patch resolved styles after config reloads."""
+    _RESOLVED_STYLE_CACHE.clear()
+
+
+def _resolve_style_uncached(base: Style, *patches: Any) -> MergedStyle:
+    """Merge compiled base with patches, apply cascade, return resolved style.
+
+    1. Deep-merge: for each patch, non-None fields override the base.
+    2. Cascade inheritance (ADR-003): font flows down from root.
+    3. Convert FontStyle → MergedFontStyle at each level (raises if any field None).
+    4. Return MergedStyle.
+    """
+    merged = base
+    for patch in patches:
+        merged = deep_merge(merged, patch)  # type: ignore[assignment]
+
+    cascaded = _apply_cascade(merged)
+    cascaded = _resolve_self_tokens(cascaded)
+    cascaded = _resolve_color_tokens(cascaded)
+
+    emoji_family = _EMOJI_MODE_TO_FAMILY.get(cascaded.font.emoji)
+    if emoji_family is not None:
+        cascaded = _append_emoji_family(cascaded, emoji_family)
+
+    pagination = cascaded.charts.table.pagination
+
+    # Fields that pass through unchanged from Style → MergedStyle.
+    # font/charts require type transformation.
+    _TRANSFORMED = {"font", "charts"}
+    passthrough = {
+        name: getattr(cascaded, name)
+        for name in (f.name for f in dataclasses.fields(MergedStyle))
+        if name not in _TRANSFORMED
+    }
+    resolved_root_font = resolve_cascaded_font(cascaded.font, "font")
+    return MergedStyle(
+        **passthrough,
+        font=resolved_root_font,
+        charts=_build_resolved_charts(
+            cascaded.charts,
+            font_family=resolved_root_font.family,
+            title=cascaded.title,
+            spark=cascaded.charts.table.spark,
+            pagination=pagination,
+            formats=cascaded.formats,
+        ),
+    )
+
+
+def resolve_style(base: Style, *patches: Any) -> MergedStyle:
+    """Merge compiled base with patches, apply cascade, return resolved style."""
+    if patches:
+        return _resolve_style_uncached(base, *patches)
+
+    cache_key = id(base)
+    cached = _RESOLVED_STYLE_CACHE.get(cache_key)
+    if cached is not None and cached[0] is base:
+        return copy.deepcopy(cached[1])
+
+    resolved = _resolve_style_uncached(base)
+    _RESOLVED_STYLE_CACHE[cache_key] = (base, resolved)
+    return copy.deepcopy(resolved)
+
+
+# =============================================================================
+# VEGA-LITE MAPPING (new nested → flat camelCase)
+# =============================================================================
+
+
+def style_to_vega_lite(
+    charts: MergedChartsStyle,
+) -> Any:  # -> vlc.VegaLiteConfig, avoid circular import
+    """Map MergedChartsStyle to VegaLiteConfig.
+
+    Translates nested Dataface field names to flat Vega-Lite camelCase.
+    This is the sole place that knows about Vega-Lite naming.
+
+    Sole VL mapper. The overloaded style_to_vega_lite(Style) signature was removed.
+    """
+    from dataface.core.compile.models.vega_lite import config as vlc
+
+    data: dict[str, Any] = {}
+
+    # Root font family → VL top-level `font` key
+    if charts.font_family is not None:
+        data["font"] = charts.font_family
+
+    # Color palette → range.category. (Dashes flow through encoding-level
+    # `scale.range` on the strokeDash channel, not config.range — vl_convert's
+    # Vega-Lite v6 ignores `range.dashPattern` even though the docs list it.)
+    if charts.palette:
+        data["range"] = {"category": charts.palette}
+
+    # Default mark color flows through config.range.category (palette[0]) and
+    # per-mark palette stanzas for generic marks below.
+    default_mark_color: str | None = charts.palette[0] if charts.palette else None
+
+    # axis/axisX/axisY/axisQuantitative/axisBand: all moved to encoding level.
+    # profile.py:_build_encoding_axis layers global + channel + type-conditional.
+    # No config.axis* keys emitted here.
+
+    # legend: moved to encoding.color.legend.* / encoding.size.legend.* etc.
+    # profile.py:_build_encoding_legend handles theme + chart-local merge.
+    # No config.legend key emitted here.
+
+    # bar/line/area/scatter: moved to spec.mark.{...} extended mark object.
+    # profile.py:_map_mark/_build_mark_style handles theme + chart-local merge.
+    # No config.bar/line/area/point keys emitted here.
+
+    # Generic mark types: map opacity/stroke/strokeWidth where set.
+    # After ADR-015, these live under charts.marks.* instead of charts.*.
+    def _mark_config(m: Any) -> dict[str, Any]:
+        d: dict[str, Any] = {}
+        if getattr(m, "opacity", None) is not None:
+            d["opacity"] = m.opacity
+        stroke = getattr(m, "stroke", None)
+        if stroke is not None:
+            if stroke.color is not None:
+                d["stroke"] = stroke.color
+            if stroke.width is not None:
+                d["strokeWidth"] = stroke.width
+        return d
+
+    # Solid marks (rect) take fill from palette[0]; line-shaped marks (rule,
+    # trail) take stroke. circle/square/tick keep stroke-only mapping; their
+    # default coloring flows through scale.range.category.
+    _SOLID_MARKS = {"rect"}
+    _LINE_MARKS = {"rule", "trail"}
+    for mark_name, mark in [
+        ("circle", charts.marks.circle),
+        ("square", charts.marks.square),
+        ("tick", charts.marks.tick),
+        ("rule", charts.marks.rule),
+        ("trail", charts.marks.trail),
+        ("rect", charts.marks.rect),
+    ]:
+        cfg = _mark_config(mark)
+        if default_mark_color is not None:
+            if mark_name in _SOLID_MARKS:
+                cfg["fill"] = default_mark_color
+            elif mark_name in _LINE_MARKS and "stroke" not in cfg:
+                cfg["stroke"] = default_mark_color
+        if cfg:
+            data[mark_name] = vlc.MarkConfig.model_validate(cfg)
+
+    # path/shape/symbol: VL marks not modeled in ChartsStyle. Emit
+    # the palette[0] default only — these marks are passed through to VL
+    # with no other Dataface-owned fields.
+    if default_mark_color is not None:
+        data["path"] = vlc.MarkConfig.model_validate({"stroke": default_mark_color})
+        data["shape"] = vlc.MarkConfig.model_validate({"stroke": default_mark_color})
+        data["symbol"] = vlc.MarkConfig.model_validate({"fill": default_mark_color})
+
+    # View
+    view = charts.view
+    view_data: dict[str, Any] = {
+        "continuousWidth": view.continuous_width,
+        "continuousHeight": view.continuous_height,
+        # Always emit stroke. ``None`` is meaningful here: VL's default view
+        # stroke is ``"#ddd"``, so an absent key draws a default border. To
+        # actually disable the bounding box, the spec must contain
+        # ``stroke: null``.
+        "stroke": view.stroke,
+    }
+    if view.discrete_width is not None:
+        view_data["discreteWidth"] = view.discrete_width
+    if view.discrete_height is not None:
+        view_data["discreteHeight"] = view.discrete_height
+    data["view"] = view_data
+
+    # Autosize
+    autosize = charts.autosize
+    data["autosize"] = {
+        "type": autosize.type,
+        "contains": autosize.contains,
+        "resize": autosize.resize,
+    }
+
+    # Text mark (data labels, annotations) — renamed from label to marks.text
+    text_mark = charts.marks.text
+    tf_text = text_mark.font
+    text_data: dict[str, Any] = {}
+    # All TextMarkStyle fields are cascade tier sentinels — only emit when set.
+    if text_mark.align is not None:
+        text_data["align"] = text_mark.align
+    if tf_text.family is not None:
+        text_data["font"] = tf_text.family
+    if tf_text.color is not None:
+        text_data["fill"] = tf_text.color  # VL text mark uses fill for color
+    if tf_text.size is not None:
+        text_data["fontSize"] = tf_text.size
+    if tf_text.weight is not None:
+        text_data["fontWeight"] = tf_text.weight
+    if text_data:
+        data["text"] = text_data
+
+    # Title (board/chart title styling)
+    title = charts.title
+    title_data: dict[str, Any] = {}
+    tf = title.font
+    # FontStyle fields are Optional — only emit when authored (not None)
+    if tf.color is not None:
+        title_data["color"] = tf.color
+    if tf.family is not None:
+        title_data["font"] = tf.family
+    if tf.size is not None:
+        title_data["fontSize"] = tf.size
+    if tf.weight is not None:
+        title_data["fontWeight"] = tf.weight
+    title_data["anchor"] = title.position.anchor
+    if title.position.angle is not None:
+        title_data["angle"] = title.position.angle
+    if title.position.offset is not None:
+        title_data["offset"] = title.position.offset
+    if title.position.baseline is not None:
+        title_data["baseline"] = title.position.baseline
+    sf = title.subtitle.font
+    if sf.color is not None:
+        title_data["subtitleColor"] = sf.color
+    if sf.family is not None:
+        title_data["subtitleFont"] = sf.family
+    if sf.size is not None:
+        title_data["subtitleFontSize"] = sf.size
+    if sf.weight is not None:
+        title_data["subtitleFontWeight"] = sf.weight
+    if title_data:
+        data["title"] = title_data
+
+    return vlc.VegaLiteConfig.model_validate(data)