dataface 0.4.1.dev32__py3-none-any.whl → 0.4.1.dev134__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -307,9 +307,11 @@ style:
   text:
     align: left
     column:
-      number: 2
+      max_number: 2
       gap: 24
-      rule: "1px solid #cbd5e1"
+      rule:
+        width: 1
+        color: "#cbd5e1"
 ```
 
 CSS-only keys like `border-radius`, `border-left`, `margin-top` are not board-style fields and are rejected.

dataface/agent_api/board_artifact.py

@@ -22,6 +22,7 @@ from pydantic import BaseModel, ConfigDict
 
 from dataface.agent_api._paths import resolve_face_or_error
 from dataface.core.compile import compile_file
+from dataface.core.compile.models.face.resolved import ChartResolveFailure
 from dataface.core.compile.variables import normalize_multiselect_values
 from dataface.core.diagnostics import ERR_FILE_NOT_FOUND, Diagnostic
 from dataface.core.diagnostics.base import DatafaceError
@@ -133,14 +134,27 @@ def emit_board_artifact(
     set_filter_variables_context(
         frozenset(face.variable_registry) if face.variable_registry else frozenset()
     )
+    resolve_errors: dict[str, ChartResolveFailure] = {}
     try:
-        resolved, _render_cache = build_resolved_face(face, executor, merged_variables)
+        resolved, _render_cache = build_resolved_face(
+            face, executor, merged_variables, resolve_errors=resolve_errors
+        )
     except DatafaceError as exc:
         return EmitBoardArtifactResult(success=False, errors=[exc.to_diagnostic()])
     finally:
         set_auto_link_context(False)
         set_filter_variables_context(frozenset())
 
+    # A chart-level resolve failure no longer raises — it leaves a hole in the
+    # face instead. Publishing that hole silently would be worse than the fatal
+    # it replaced, since a live render at least draws an error tile where an
+    # artifact just has nothing. Artifacts stay all-or-nothing.
+    if resolve_errors:
+        return EmitBoardArtifactResult(
+            success=False,
+            errors=[failure.diagnostic for failure in resolve_errors.values()],
+        )
+
     recording = record_board(resolved, executor, merged_variables)
 
     artifact_path.parent.mkdir(parents=True, exist_ok=True)

dataface/agent_api/diagnostics.py

@@ -36,9 +36,10 @@ __all__ = [
     "DiagnosticCodeDetail",
     "DiagnosticCodesListResult",
     "DiagnosticCodeDetailResult",
+    "DiagnosticDisplay",
     "list_diagnostic_codes",
     "get_diagnostic_code",
-    "doc_url_map",
+    "display_map",
 ]
 
 # ----- Args types ------------------------------------------------------------
@@ -77,6 +78,20 @@ class DiagnosticCodeSummary(BaseModel):
     model_config = ConfigDict(extra="forbid", frozen=True)
 
 
+class DiagnosticDisplay(BaseModel):
+    """Registry-derived presentation data for one code, shipped per page.
+
+    Both fields are derived DiagnosticCode properties rather than serialized
+    Diagnostic fields, so a display surface resolves them from the code it
+    already has instead of receiving them on every payload.
+    """
+
+    title: str
+    doc_url: str
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
 class DiagnosticCodeDetail(BaseModel):
     """Full details for a single diagnostic code."""
 
@@ -207,11 +222,14 @@ def get_diagnostic_code(code: str) -> DiagnosticCodeDetailResult:
     )
 
 
-def doc_url_map() -> dict[str, str]:
-    """The registry's code -> doc_url map, built once for embedding alongside a page.
+def display_map() -> dict[str, DiagnosticDisplay]:
+    """The registry's code -> display map, built once for embedding alongside a page.
 
-    doc_url is a derived DiagnosticCode property, never an authored/serialized
-    field — Cloud and Playground each ship this map once rather than
-    re-deriving or hand-formatting a URL per diagnostic.
+    `title` and `doc_url` are derived DiagnosticCode properties, never
+    authored/serialized Diagnostic fields — Cloud and Playground each ship this
+    map once rather than re-deriving a URL or restating a title per diagnostic.
     """
-    return {dc.code: dc.doc_url for dc in REGISTRY.all()}
+    return {
+        dc.code: DiagnosticDisplay(title=dc.title, doc_url=dc.doc_url)
+        for dc in REGISTRY.all()
+    }

dataface/agent_api/docs/yaml-reference.md

@@ -11,7 +11,7 @@ AuthoredFace (dataface) definition from YAML.
 | `tags` | list[str] | ✓ | Tags for categorization and search. |
 | `aliases` | list[str] | ✓ | Additional URLs that redirect to this face's canonical file-path URL. Each entry must be absolute (leading /). Requests to these URLs are redirected (302) to the face's real path, query string preserved. Valid on .yml, .yaml, .md, and folder index.* faces. |
 | `text` | str | ✓ | Markdown text content for text-only sections. |
-| `allow_html` | bool | ✓ | Render the face's body text as raw HTML via foreignObject instead of markdown. TRUSTED-CONTENT ONLY: the HTML (including any Jinja-interpolated values) is rendered as-authored — this is NOT a security sandbox. mdsvg strips <script>/event-handlers as a best-effort guard, not a guarantee. Enable only on first-party faces you fully control. |
+| `html_policy` | enum: "none", "safe-subset", "trusted-raw" | ✓ | HTML rendering policy for the face's body text. One of: "none" (default) — HTML is escaped and rendered as plain markdown; "safe-subset" — reserved for a parser-checked allowlist (not yet enforced — currently renders as none); "trusted-raw" — raw HTML via foreignObject. TRUSTED-CONTENT ONLY: this is NOT a security sandbox. <script>/event-handlers are stripped as a best-effort guard, not a guarantee. Enable only on first-party faces you fully control. |
 | `source` | str | ✓ | Default source name for all queries in this face. Inheritable via meta.yaml cascade. |
 | `cache` | [Cache](#cache) | ✓ | Cache policy for every query in this dashboard, e.g. cache: 1h — queries inherit it and may refine it; cache: false opts the whole dashboard out. Inheritable via the meta.yaml cascade. |
 | `variables` | dict[str, [Variable](#variable) \| VariableRef] | ✓ | Variable definitions for dynamic filtering and UI controls. |
@@ -1894,14 +1894,14 @@ Authored overlay for BlockMarginStyle. Top and bottom margin for a prose block r
 
 <a id="textcolumnstyle"></a>
 ## TextColumnStyle
-Authored overlay for TextColumnStyle. Multi-column layout for face body text (CSS column-count/gap/rule/max_chars).
+Authored overlay for TextColumnStyle. Author overrides for the column layout of face body text.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `number` | int | ✓ | Fixed column count. None = single column. |
-| `gap` | float | ✓ | Gap between columns in pixels. None = use layout gap token. |
-| `rule` | str | ✓ | CSS column-rule shorthand, e.g. '1px solid #e5e7eb'. None = no rule. |
-| `max_chars` | int | ✓ | Target column width as a character count. The pixel width is derived at render time via fonttools OS/2.xAvgCharWidth × max_chars; column count auto-derives as ceil(available / col_width_px). |
+| `max_number` | int | ✓ | Ceiling on the column count. The renderer may choose fewer when there is not enough text to fill them. None = no ceiling. |
+| `gap` | float | ✓ | Gap between columns in pixels. None = 1.5 line boxes, so the gutter scales with the type it separates. |
+| `rule` | [ColumnRuleStyle](#columnrulestyle) | ✓ | Vertical rule drawn between columns. None = no rule. |
+| `max_chars` | int | ✓ | Column width as a character count, overriding the shipped measure. The width is used exactly and the column count follows from it. |
 
 <a id="textcodestyle"></a>
 ## TextCodeStyle
@@ -2335,7 +2335,6 @@ Authored overlay for ScaleContinuousStyle. Continuous-scale-only config: type, d
 | `zero` | bool \| enum: "auto" | ✓ | Force scale zero-baseline: True/False pins it; "auto" runs the Dataface smart-zero heuristic; None passes through to Vega-Lite. |
 | `type` | enum: "linear", "log", "pow", "sqrt", "symlog", "temporal" | ✓ | Scale type override. 'linear'/'log'/'pow'/'sqrt'/'symlog' pass straight through to Vega-Lite's quantitative scale.type. 'temporal' is a Dataface escape hatch for a cartesian x-axis: it forces a continuous temporal scale instead of the auto-inferred ordinal/nominal bucketed type, which is required before an authored ``domain`` of ISO dates can extend the visible range past the data extent. None lets Dataface/Vega-Lite infer from the field type. |
 | `domain` | list[Any] | ✓ | Explicit [low, high] scale domain; None lets Vega-Lite auto-determine from data. Must have exactly 2 elements — Dataface only wires a continuous range override through to Vega-Lite, not an explicit category enumeration. When ``type: temporal`` is set, both elements must be ISO-8601 date/datetime strings. |
-| `domain_strategy` | enum: "stable", "auto" | ✓ | How the numeric domain responds to filter-variable changes when no explicit `domain` is authored. 'stable' (the default when None) pins the domain to the chart query's full unfiltered extent — the same value lands at the same pixel across variable changes. 'auto' rescales the domain to the current filtered subset on every variable change. An explicit `domain` always wins over either strategy. |
 | `log` | [ScaleLogStyle](#scalelogstyle) | ✓ | Log-scale param (base); only meaningful with type: log. |
 | `pow` | [ScalePowStyle](#scalepowstyle) | ✓ | Power-scale param (exponent); only meaningful with type: pow. |
 | `symlog` | [ScaleSymlogStyle](#scalesymlogstyle) | ✓ | Symlog-scale param (constant); only meaningful with type: symlog. |
@@ -2621,6 +2620,16 @@ Authored overlay for GeoshapeMarkStyle. Geoshape (choropleth) mark fill and boun
 | `fill` | str | ✓ | Neutral geoshape fill color. |
 | `stroke` | [StrokeStyle](#strokestyle) | ✓ | Geoshape boundary stroke style. |
 
+<a id="columnrulestyle"></a>
+## ColumnRuleStyle
+Authored overlay for ColumnRuleStyle. Vertical rule drawn between prose columns, structured like BorderStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `width` | float | ✓ | Rule line width in pixels. |
+| `color` | str | ✓ | Rule color as a CSS color string. |
+| `style` | enum: "solid", "dashed", "dotted" | ✓ | Rule line style. |
+
 <a id="circlemarkstyle"></a>
 ## CircleMarkStyle
 Authored overlay for CircleMarkStyle. Circle mark opacity and stroke.
@@ -2848,7 +2857,7 @@ Authored overlay for SliceLabelsStyle. Pie labels: typography + positioning offs
 |-------|------|:--------:|-------------|
 | `offset` | float | ✓ | Radial offset of slice labels from the arc in pixels. |
 | `line_height` | float | ✓ | Line height for slice labels in pixels. Reserved vertical space above the disk is ``line_height × &lt;rendered lines&gt;`` per row, so the same value handles 1-line, 2-line, and multi-line templates. |
-| `font` | [FontStyle](#fontstyle) | ✓ | Slice label font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
+| `font` | [FontStyle](#fontstyle) | ✓ | Slice label font style overrides. ``color`` only takes effect on single-series pies (no ``color:`` channel authored); multi-series pies always paint each label the dark companion of its own wedge color and ignore an authored ``color`` here. Unset fields fall back to [`style.charts.font`](#chartsstyle) (except `color`). |
 | `default_template` | [LabelsDefaultTemplate](#labelsdefaulttemplate) | ✓ | Default Jinja templates for per-slice labels when template is not authored. |
 | `template` | str | ✓ | Jinja2 label template. Overrides default_template when authored. |
 | `where` | str | ✓ | Jinja2 boolean filter — labels only render on rows where this is truthy. |

dataface/agent_api/project_session.py

@@ -365,8 +365,11 @@ class ProjectSession:
         self,
         name: str,
         path: Path,
+        vars: dict[str, Any] | None = None,
     ) -> _query.FaceQueryLookupResult:
-        return _query.lookup_face_query_sql(name=name, path=path, project=self.project)
+        return _query.lookup_face_query_sql(
+            name=name, path=path, project=self.project, vars=vars
+        )
 
     def query_face(
         self,

dataface/agent_api/query.py

@@ -33,12 +33,17 @@ def lookup_face_query_sql(
     path: Path,
     *,
     project: Project,
+    vars: dict[str, Any] | None = None,
 ) -> FaceQueryLookupResult:
-    """Compile a face file and extract the SQL + source for one named SQL query.
+    """Compile a face file, render the SQL template, and return it for offline use.
 
-    Used by validate and describe paths that need the raw SQL text without
-    executing it against a warehouse.
+    Expands ``{{ queries.X }}`` and substitutes variables so callers receive
+    valid SQL rather than a raw Jinja template.  Used by validate and describe
+    paths that need the rendered SQL text without executing it against a
+    warehouse.
     """
+    from dataface.core.compile.parameterized import render_parameterized_with_queries
+
     try:
         file_path = resolve_face_path(path, project)
     except ValueError as e:
@@ -74,7 +79,18 @@ def lookup_face_query_sql(
             ],
         )
 
-    return FaceQueryLookupResult(success=True, sql=query.sql, source=query.source)
+    merged_vars = {**face.variable_defaults, **(vars or {})}
+    try:
+        rendered = render_parameterized_with_queries(
+            query.sql,
+            merged_vars,
+            queries=face.queries,
+            strict=not query.lenient_variables,
+        )
+    except (ValueError, KeyError, TypeError) as exc:
+        return FaceQueryLookupResult(success=False, errors=[str(exc)])
+
+    return FaceQueryLookupResult(success=True, sql=rendered.sql, source=query.source)
 
 
 class ExecuteQueryArgs(BaseModel):
@@ -93,6 +109,14 @@ class ExecuteQueryArgs(BaseModel):
         False,
         description="When True, undefined Jinja variables degrade gracefully (useful for iterative chart editing where not all variables are set).",
     )
+    # Display only — never reaches execute_query(). Ad-hoc SQL is the one query
+    # surface with no author to describe it: a named face query carries the
+    # `description:` its YAML already declares, and this is the equivalent for
+    # a query that exists only for the length of one tool call.
+    description: str | None = Field(
+        None,
+        description="Short phrase naming what this query is for (e.g. 'Leads by industry'), shown to the user in place of the raw SQL.",
+    )
 
 
 class ExecuteQueryResult(BaseModel):
@@ -236,6 +260,9 @@ class QueryFaceResult(BaseModel):
     path: PurePosixPath
     query_type: str | None = None
     sql: str | None = None
+    #: The query's authored `description:`, when its YAML declares one. Lets a
+    #: caller label the run with what it is for rather than its identifier.
+    description: str | None = None
     columns: list[str] = []
     data: list[dict[str, Any]] = []
     row_count: int = 0
@@ -249,11 +276,19 @@ def _fail(
     path: PurePosixPath,
     errors: list[str],
     available: list[str] | None = None,
+    sql: str | None = None,
+    description: str | None = None,
 ) -> QueryFaceResult:
+    """A failure reports the query it was running whenever it got far enough to
+    know it: an undefined-variable error is unreadable without the SQL holding
+    the `{{ }}` that went unbound. Failures before the query is looked up
+    (unresolvable path, compile error, unknown name) have neither to report."""
     return QueryFaceResult(
         success=False,
         name=name,
         path=path,
+        sql=sql,
+        description=description,
         errors=errors,
         available_queries=available or [],
     )
@@ -298,6 +333,8 @@ def query_face(
 
     merged_vars = {**face.variable_defaults, **(vars or {})}
     query = face.queries[name].model_copy(update={"limit": limit + 1})
+    sql = query.sql if isinstance(query, SqlQuery) else None
+    described = query.description
 
     # Detect file sources before dispatching — the adapter path has no materializer
     # and would fall through to SqlAdapter with a cryptic dbt error. File-source
@@ -324,6 +361,8 @@ def query_face(
                         "(dft render / dft serve). "
                         "Use dft render to preview this dashboard."
                     ],
+                    sql=sql,
+                    description=described,
                 )
 
     try:
@@ -331,10 +370,16 @@ def query_face(
             query, variables=merged_vars or None, face=face, query_name=name
         )
     except Exception as e:  # noqa: BLE001
-        return _fail(name, resolved_display, [str(e)])
+        return _fail(name, resolved_display, [str(e)], sql=sql, description=described)
 
     if exec_result.error:
-        return _fail(name, resolved_display, [exec_result.error])
+        return _fail(
+            name,
+            resolved_display,
+            [exec_result.error],
+            sql=sql,
+            description=described,
+        )
 
     data = normalize_data_for_json(exec_result.data)
     truncated = len(data) > limit
@@ -345,7 +390,8 @@ def query_face(
         name=name,
         path=resolved_display,
         query_type=query.query_type,
-        sql=query.sql if isinstance(query, SqlQuery) else None,
+        sql=sql,
+        description=described,
         columns=list(data[0].keys()) if data else [],
         data=data,
         row_count=len(data),

dataface/ai/skills/dashboard-build/SKILL.md

@@ -260,12 +260,14 @@ Named presets (prefer these over raw D3 strings):
 | Preset | Example output | Notes |
 |--------|---------------|-------|
 | `integer` | `1,234` | |
+| `year` | `2025` — no grouping, no SI scaling | an identifier, not a quantity |
 | `currency_whole` | `$1,234` | |
 | `currency_compact` | `$1.2M` | |
 | `percent` | `2.3%` — input is decimal fraction (0.023) | line/bar/area/scatter via `style.number_format` |
 | `percent_number` | `2.3%` — input is whole-number percent (2.3) | **KPI only** (`style.value.format`) |
 | `percent_delta` | `+2.3%` — input is decimal fraction | |
 | `percent_number_delta` | `+2.3%` — input is whole-number (2.3) | **KPI only** |
+| `percentage_points_delta` | `+3.2 pts` — the difference of two percentages | for a point delta, not a ratio delta |
 
 **`percent_number` and `percent_number_delta` only work on `type: kpi`.** Using them on line/bar/area/scatter causes a render error. For those chart types use `percent` or `percent_delta` (decimal-fraction input) or omit formatting and accept axis defaults.
 

dataface/ai/tools/__init__.py

@@ -206,9 +206,16 @@ def _handle_get_skill(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str,
         )
     except _skills.SkillNotFound as exc:
         return {"success": False, "errors": [str(exc)]}
-    return skill.model_dump(
-        mode="json", exclude_none=True, exclude=_skills.SKILL_WIRE_EXCLUDE_FIELDS
-    )
+    # `Skill` is a domain model, not a result envelope — it carries no verdict
+    # of its own, and it must not grow one (it nests inside `SkillList.skills`,
+    # where a per-item `success` means nothing). The envelope is added here, so
+    # this payload states its outcome like every other tool's.
+    return {
+        "success": True,
+        **skill.model_dump(
+            mode="json", exclude_none=True, exclude=_skills.SKILL_WIRE_EXCLUDE_FIELDS
+        ),
+    }
 
 
 def _handle_search_skills(

dataface/cli/commands/query.py

@@ -344,7 +344,7 @@ def query_command(
         if mode_is_named:
             assert query_name is not None
             assert face is not None
-            lr = project_session.lookup_face_query_sql(query_name, face)
+            lr = project_session.lookup_face_query_sql(query_name, face, vars=vars)
             if not lr.success:
                 _handle_lookup_failure(lr, query_name)
             sql_text = lr.sql

dataface/core/compile/chart_update.py

@@ -36,13 +36,10 @@ Usage:
     )
 """
 
-import logging
 from typing import Any
 
 import yaml
 
-logger = logging.getLogger(__name__)
-
 
 def update_chart_in_yaml(
     yaml_content: str,
@@ -147,6 +144,25 @@ def update_chart_in_yaml(
         if field in edits and edits[field]:
             chart_def[field] = edits[field]
 
+    # Validate rewritability before any mutation.
+    # A rows/cols source_path must be exactly two segments (layout_key.N) where N
+    # is a digit — that is the only shape _update_layout_reference can rewrite.
+    # Deeper paths (rows.0.cols.1) name a chart inside a nested face; the nested
+    # face's own file must name the chart instead.
+    if source_path and source_path.split(".")[0] in ("rows", "cols"):
+        _segs = source_path.split(".")
+        if len(_segs) != 2:
+            raise ValueError(
+                f"Cannot promote inline chart at '{source_path}': only top-level "
+                "layout positions (rows.N / cols.N) are supported; name the chart "
+                "in the nested face's own file instead"
+            )
+        if not _segs[1].isdigit():
+            raise ValueError(
+                f"Cannot promote inline chart at '{source_path}': "
+                f"'{_segs[1]}' is not a valid integer index"
+            )
+
     # Update the charts section
     # If chart already exists, merge with existing values
     if chart_id in data["charts"]:
@@ -171,31 +187,19 @@ def update_chart_in_yaml(
 def _update_layout_reference(
     data: dict[str, Any], source_path: str, chart_id: str
 ) -> None:
-    """Update a layout position to reference a named chart instead of inline.
+    """Replace an inline chart at a top-level layout position with a named reference.
 
     Args:
         data: Parsed YAML data (modified in place)
-        source_path: Path like "rows.0" or "rows.0.cols.1"
+        source_path: Validated path of the form "rows.N" or "cols.N".
+            Caller guarantees exactly two segments and a digit index.
         chart_id: ID of the chart to reference
     """
-    # Only a top-level position is rewritable here: this replaces an entry in
-    # `data[layout_key]`, and a deeper path (`rows.0.cols.1`) names an entry in a
-    # nested face's own list, which this function never walks into.
-    segments = source_path.split(".")
-    if len(segments) != 2 or segments[0] not in ("rows", "cols"):
-        logger.debug(f"Unrecognized source_path format: {source_path}")
-        return
-    layout_key, raw_index = segments
-    if not raw_index.isdigit():
-        logger.warning(f"Failed to parse index from source_path: {source_path}")
-        return
+    layout_key, raw_index = source_path.split(".")
     index = int(raw_index)
-
-    # Update the layout
     if (
         layout_key in data
         and isinstance(data[layout_key], list)
         and 0 <= index < len(data[layout_key])
     ):
-        # Replace inline chart with named reference
         data[layout_key][index] = chart_id

dataface/core/compile/data_table.py

@@ -16,7 +16,7 @@ helpers) live there too.
 from __future__ import annotations
 
 from dataface.core.compile.merge import merge_onto_base
-from dataface.core.compile.models.style.resolved import ResolvedChartsStyle
+from dataface.core.compile.models.style.context import ChartStyleContext
 from dataface.core.compile.models.style.theme import DataTableStyle
 from dataface.core.compile.style_cascade import resolved_axis_style
 
@@ -31,7 +31,7 @@ def row_height(style: DataTableStyle) -> float:
     return _ROW_HEIGHT_BASE + padding.vertical * 2.0
 
 
-def axis_offset(charts_style: ResolvedChartsStyle, style: DataTableStyle) -> float:
+def axis_offset(chart_style_context: ChartStyleContext, 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
@@ -45,14 +45,14 @@ def axis_offset(charts_style: ResolvedChartsStyle, style: DataTableStyle) -> flo
 
     MUST use the fully-merged axis (resolved_axis_style) rather than reading
     charts_style.axis_x directly. The authored x_label visibility flip is
-    stored on axis_overrides_x (Layer 6) by build_resolved_style; reading
+    stored on axis_overrides_x (Layer 6) by build_chart_style_context; reading
     the base axis_x (Layers 1+2) misses it, under-reserving title space and
     causing the strip to collide with the rendered axis title.
     """
     # Font metrics come from the base ResolvedAxisStyle (non-None guaranteed).
     # Visibility is read from the fully-merged cascade (includes Layer-6 authored-
     # label flips) so both label and title heights reflect the actual rendered state.
-    merged = resolved_axis_style(charts_style, "axis_x", "band")
+    merged = resolved_axis_style(chart_style_context, "axis_x", "band")
     # labels.padding is always required by build_resolved_axis (the shared
     # ResolvedAxisElementStyle dataclass types it Optional only to let title
     # leave it unset — see AxisTitleStyle).
@@ -72,7 +72,7 @@ def axis_offset(charts_style: ResolvedChartsStyle, style: DataTableStyle) -> flo
 
 
 def resolve_effective_data_table_style(
-    charts_style: ResolvedChartsStyle, chart_type: str
+    chart_style_context: ChartStyleContext, chart_type: str
 ) -> DataTableStyle:
     """Resolve the effective data_table style for a chart.
 
@@ -81,7 +81,7 @@ def resolve_effective_data_table_style(
     fields from charts.data_table, so this function only needs to apply the
     per-family theme values (tier-2) on top.
     """
-    per_type = getattr(charts_style, chart_type, None)
+    per_type = getattr(chart_style_context, chart_type, None)
     if per_type is None or not hasattr(per_type, "data_table"):
-        return charts_style.data_table
-    return merge_onto_base(charts_style.data_table, per_type.data_table)
+        return chart_style_context.data_table
+    return merge_onto_base(chart_style_context.data_table, per_type.data_table)

dataface/core/compile/format.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 from typing import Any
 
 from dataface.core.compile.models.primitives import FormatConfig
+from dataface.core.text.format_d3 import round_aware_format
 
 
 def resolve_format(
@@ -35,6 +36,15 @@ def resolve_format(
     rendering. That pass keys slots off field name, so it is not a guarantee
     for every value reaching this function.
 
+    The resolved spec also carries ``round_aware_format``'s ``~``-trim
+    injection (a no-op for a non-SI spec, a native-formatter key, or a
+    strftime directive). This is the single point nearly every consumer of a
+    resolved format string is baked from — axes and mark labels at compile,
+    KPI/table/tooltip at render — so every one of them, including a spec
+    handed straight to Vega-Lite (``axis.format``, a value label's
+    ``text.format``), agrees on digits by construction instead of each
+    render leaf re-applying the trim itself.
+
     Args:
         format_input: Format specification (string, FormatConfig, dict, or None)
         formats: The resolved format alias dict from the theme cascade
@@ -59,10 +69,10 @@ def resolve_format(
 
     # Theme/face alias lookup (case-sensitive, key-exact)
     if formats and format_str in formats:
-        return formats[format_str]
+        return round_aware_format(formats[format_str])
 
     # Raw d3 passthrough — let d3 parse or raise
-    return format_str
+    return round_aware_format(format_str)
 
 
 # d3's first SI prefix ("k") engages at 1000. Below it, ".2s" doesn't compact —

dataface/core/compile/inherit_graph.py

@@ -97,11 +97,16 @@ def _build_graph(
     slot_at: StylePath | None = None,
     slot_from: StylePath | None = None,
     skip_slots: bool = False,
+    slot_exclude: frozenset[str] = frozenset(),
 ) -> None:
     """Walk *model_cls* recursively and populate *graph* from Inherit/InheritSlot markers.
 
     ``skip_slots=True`` suppresses InheritSlot expansion for the entire subtree —
     used when a shared model's slot annotations must not apply at a particular path.
+
+    ``slot_exclude`` carries the active slot's ``InheritSlot.exclude`` leaf names
+    down through the recursion; a leaf whose field name is in this set gets no
+    graph entry, leaving it a genuine cascade-managed sentinel.
     """
     if model_cls in seen:
         return
@@ -160,6 +165,7 @@ def _build_graph(
                     slot_at=slot_at if skip_marker.cascade else None,
                     slot_from=slot_from if skip_marker.cascade else None,
                     skip_slots=not skip_marker.cascade,
+                    slot_exclude=slot_exclude if skip_marker.cascade else frozenset(),
                 )
             elif slot_marker is not None and not skip_slots:
                 if slot_at is not None:
@@ -176,6 +182,7 @@ def _build_graph(
                         graph,
                         slot_at=slot_at,
                         slot_from=slot_from,
+                        slot_exclude=slot_exclude,
                     )
                 else:
                     from_path = slot_marker.from_path
@@ -184,6 +191,12 @@ def _build_graph(
                         raise ValueError(
                             f"InheritSlot from_path {from_path!r} does not match any path in the model"
                         )
+                    unknown_exclude = slot_marker.exclude - nested.model_fields.keys()
+                    if unknown_exclude:
+                        raise ValueError(
+                            f"InheritSlot exclude {sorted(unknown_exclude)!r} on "
+                            f"{_path_str(current)!r} not a field of {nested.__name__}"
+                        )
                     # Nullable InheritSlot (T | None): emit a container-level copy
                     # link so apply_inherit can copy the whole parent object when
                     # this field is None.  apply_inherit._set() skips writes through
@@ -200,6 +213,7 @@ def _build_graph(
                         graph,
                         slot_at=current,
                         slot_from=from_tuple,
+                        slot_exclude=slot_marker.exclude,
                     )
             else:
                 _build_graph(
@@ -211,6 +225,7 @@ def _build_graph(
                     slot_at=slot_at,
                     slot_from=slot_from,
                     skip_slots=skip_slots,
+                    slot_exclude=slot_exclude,
                 )
         else:
             # Leaf node.
@@ -226,7 +241,13 @@ def _build_graph(
             #    slot (which authors may override independently).
             # 2. Explicit Inherit: fires at canonical (non-slot) positions only,
             #    establishing the "ultimate fallback" for the entire slot family.
-            if slot_at is not None and slot_from is not None and skip_marker is None:
+            #
+            # A leaf named in the active slot's exclude set gets no link at
+            # all: it stays a genuine cascade-managed sentinel (None unless
+            # some tier's raw YAML sets it) rather than being backfilled.
+            if field_name in slot_exclude:
+                pass
+            elif slot_at is not None and slot_from is not None and skip_marker is None:
                 leaf_suffix: StylePath = current[len(slot_at) :]
                 fallback_path = _path_str(slot_from + leaf_suffix)
                 if fallback_path not in valid_paths:

dataface/core/compile/inherit_resolver.py

@@ -4,7 +4,7 @@ apply_inherit fills None-sentinel leaves by walking the single-link
 parent chains declared via Inherit/InheritSlot markers on the compiled Style.
 It runs after merge_onto_base, replacing the former hard-coded push loop approach.
 
-Not in scope: _build_resolved_style, resolved_axis_style.
+Not in scope: _build_chart_style_context, resolved_axis_style.
 """
 
 from __future__ import annotations

dataface/core/compile/introspection.py

@@ -72,6 +72,9 @@ class SchemaField:
     )
     inherit_from: tuple[str, ...] = ()  # ordered fallback dot-paths (Inherit marker)
     inherit_slot: str | None = None  # source subtree path (InheritSlot marker)
+    inherit_slot_exclude: frozenset[str] = (
+        frozenset()
+    )  # leaf names InheritSlot excludes
 
 
 @dataclasses.dataclass
@@ -411,6 +414,9 @@ def _build_schema_field(
         container_mapping_models=_container_mapping_models(annotation),
         inherit_from=(inherit.from_path,) if inherit is not None else (),
         inherit_slot=inherit_slot.from_path if inherit_slot is not None else None,
+        inherit_slot_exclude=(
+            inherit_slot.exclude if inherit_slot is not None else frozenset()
+        ),
     )