dataface 0.4.1.dev53__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/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. |
@@ -1898,9 +1898,9 @@ Authored overlay for TextColumnStyle. Author overrides for the column layout of
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `number` | int | ✓ | Ceiling on the column count. The renderer may choose fewer when there is not enough text to fill them. None = no ceiling. |
+| `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` | str | ✓ | CSS column-rule shorthand, e.g. '1px solid #e5e7eb'. None = no rule. |
+| `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>
@@ -2620,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.
@@ -2847,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/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()
+        ),
     )
 
 

dataface/core/compile/models/chart/normalized/callout.py

@@ -44,6 +44,13 @@ class CalloutChart(BaseModel):
         description="Always None — callout has no query. Present so build_resolved_face "
         "can access compiled.query_name directly without isinstance guards.",
     )
+    description: str = Field(
+        default="",
+        description="Always empty — callout has no description. Present so generic "
+        "chart-iteration code (ChartIdentity.from_normalized) can access "
+        "chart.description without isinstance guards, mirroring the same "
+        "structural-parity field on ResolvedCalloutChart.",
+    )
     query_is_inline: bool = Field(
         default=False,
         description="True when query is defined inline; False for named reference.",

dataface/core/compile/models/chart/resolved/_base.py

@@ -30,6 +30,7 @@ from dataface.core.compile.models.style.resolved import (
     ResolvedLegendStyle,
 )
 from dataface.core.compile.models.style.theme.board import PaddingStyle, TitleStyle
+from dataface.core.compile.models.style.theme.table import DataTableStyle
 from dataface.core.compile.models.vega_lite.contracts import Projection
 
 
@@ -189,6 +190,18 @@ class _CartesianResolvedChartFields(_SharedResolvedChartFields):
     )
     min_height: float | None = Field(default=None, description="Minimum chart height.")
     max_height: float | None = Field(default=None, description="Maximum chart height.")
+    # Baked at resolve time so render never re-runs the axis cascade to
+    # compute data_table strip geometry — see compile/data_table.py's
+    # axis_offset()/resolve_effective_data_table_style(), the per-chart
+    # cascade steps this projects. None when data_table is None.
+    data_table_axis_offset: float | None = Field(
+        default=None,
+        description="Pixel offset from plot bottom to the x-axis block bottom, for data_table strip placement.",
+    )
+    effective_data_table_style: DataTableStyle | None = Field(
+        default=None,
+        description="Final per-chart data_table style (board theme merged with the family override).",
+    )
 
 
 class _GeoResolvedChartFields(_SharedResolvedChartFields):

dataface/core/compile/models/config.py

@@ -162,22 +162,6 @@ class ChartRenderingConfig(ConfigNode):
         footer_rule_gap_px: int
         footer_timestamp_gap_px: int
 
-    class ProseConfig(ConfigNode):
-        target_chars: int
-        single_column_chars: int
-        min_chars: int
-        max_chars: int
-        min_lines_per_column: int
-        max_columns: int
-        gutter_line_boxes: float
-        orphan_penalty: float
-        widow_penalty: float
-        interior_break_penalty: float
-        block_break_penalty: float
-        balance_weight: float
-        balance_scale: float
-        balance_undershoot: float
-
     class DataTableConfig(ConfigNode):
         divider_gap: float
         chart_data_table_max_x_ticks: int
@@ -190,7 +174,6 @@ class ChartRenderingConfig(ConfigNode):
     bar: BarConfig
     type_inference: TypeInferenceConfig
     board: BoardConfig
-    prose: ProseConfig
     data_table: DataTableConfig
     stroke: StrokeConfig
     axis: AxisConfig

dataface/core/compile/models/face/authored.py

@@ -441,14 +441,19 @@ class AuthoredFace(_FaceDesugarMixin):
     text: Annotated[str | None, Merge(Strategy.OVERRIDE)] = Field(
         default=None, description="Markdown text content for text-only sections."
     )
-    allow_html: Annotated[bool, Merge(Strategy.OVERRIDE)] = Field(
-        default=False,
+    html_policy: Annotated[
+        Literal["none", "safe-subset", "trusted-raw"], Merge(Strategy.OVERRIDE)
+    ] = Field(
+        default="none",
         description=(
-            "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 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."
         ),
     )
 

dataface/core/compile/models/face/normalized.py

@@ -12,6 +12,7 @@ from dataface.core.compile.models.chart.normalized import Chart
 from dataface.core.compile.models.face.authored import LayoutType
 from dataface.core.compile.models.query.normalized import AnyQuery
 from dataface.core.compile.models.style.authored import StylePatch
+from dataface.core.compile.models.style.context import ChartStyleContext
 from dataface.core.compile.models.style.resolved import ResolvedStyle
 from dataface.core.compile.models.variable.authored import SingleRowBoolProbe, Variable
 
@@ -317,14 +318,11 @@ class Face(BaseModel):
     text: str = Field(
         default="", description="Markdown text content for text-only faces."
     )
-    allow_html: bool = Field(
-        default=False,
+    html_policy: Literal["none", "safe-subset", "trusted-raw"] = Field(
+        default="none",
         description=(
-            "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 rendering policy for the face's body text. "
+            "See docs/contributing/markdown-html-policy.md for tier definitions."
         ),
     )
 
@@ -379,6 +377,15 @@ class Face(BaseModel):
     resolved_style: ResolvedStyle = Field(
         description="Board-scoped resolved style; produced at compile time. Render reads this instead of re-merging patches.",
     )
+    # Board-scoped chart style cascade context — compiler working state
+    # (sparse axis overlays, patch sentinels, palette/role token bindings, the
+    # pre-inherit tree), produced alongside resolved_style by the same
+    # cascade. Used only by runtime chart resolution (execute orchestration,
+    # sizing, the data_table-attachment axis-offset step) — never by
+    # ResolvedFace or any mechanical render API.
+    chart_style_context: ChartStyleContext = Field(
+        description="Board-scoped chart style cascade context for runtime chart resolution.",
+    )
 
     @property
     def visible_variables(self) -> "dict[str, Variable]":