dataface 0.1.6.dev260__py3-none-any.whl → 0.1.6.dev321__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -797,58 +797,6 @@ Dataface composes charts in three ways:
 
 Non-goals (not part of the authored chart surface): Vega-Lite `encoding`, `mark`, `spec`, `config`, `transform`, `params`, `resolve`, `hconcat`, `vconcat`, `concat`, `repeat`. These keys are rejected at compile time. Use the typed channels (`x`, `y`, `color`, …) and `style:` instead; use the layout primitives for visual composition.
 
-### Custom chart plugins
-
-Project-local chart types can extend the engine. Drop a `chart_types/<name>.yml` file next to the face files and reference the name in `type:`.
-
-```yaml
-# chart_types/funnel.yml
-name: funnel
-description: Funnel chart for conversion visualization
-mark: bar                              # Underlying Vega-Lite mark
-fields:
-  stage:
-    required: true
-    description: Stage field
-  value:
-    required: true
-    description: Value field
-encoding_overrides:
-  y:
-    type: nominal
-    sort: null
-  x:
-    type: quantitative
-mark_properties:
-  cornerRadius: 4
-```
-
-Then in a face:
-
-```yaml-schema
-charts:
-  conversion_funnel:
-    query: stages
-    type: funnel                       # The plugin name; no `custom:` prefix
-    # The plugin's required fields must be present in the data.
-```
-
-Plugin file fields:
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | yes | Lowercase identifier (regex `[a-z][a-z0-9_]*`) — must not shadow a built-in |
-| `mark` | yes | Vega-Lite mark name (must be a valid VL mark) |
-| `description` | no | Used in docs and AI prompts |
-| `fields` | no | `{<name>: {required: bool, description: string}}` |
-| `encoding_overrides` | no | Per-channel Vega-Lite encoding properties merged on top of standard mapping |
-| `mark_properties` | no | Extra properties merged into the mark dict |
-
-Constraints:
-- A plugin cannot shadow a built-in chart type name.
-- The `mark` value must be a valid Vega-Lite mark (validated at load time).
-- Unknown YAML keys in the plugin file are rejected — typos are caught up front.
-
 **See also:** `dft docs queries` (charts reference queries by name),
 `dft docs variables` (use `{{ var }}` in chart queries),
 `dft docs layout` (compose charts on the page),

dataface/agent_api/docs/yaml-reference.md

@@ -575,7 +575,7 @@ Authored overlay for BarChartStyle. Bar chart style: chart-level fields + marks
 | `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
-| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. The follow-up rhythm pass cycles slots across single-series charts; until then slot 0 is used for all. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
+| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
 | `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
@@ -591,7 +591,7 @@ Authored overlay for BarChartStyle. Bar chart style: chart-level fields + marks
 | `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
 | `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
 | `range` | [RangeStyle](#rangestyle) | ✓ | Color range/palette overrides for this chart type; None means no override. |
-| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override. Unset fields fall back to [`style.charts.data_table`](#chartsstyle). |
 | `orientation` | enum: "horizontal", "vertical", "auto" | ✓ | Preferred bar orientation; None uses the renderer default (vertical). |
 | `stack` | enum: "zero", "normalize", "center" | ✓ | Default stack mode for bar charts; None uses the renderer default (VL stacks by default). |
 | `stack_order` | enum: "value", "data", "alphabetical" | ✓ | Z-order of stacked segments. None/'value' puts the largest aggregate at baseline. 'data' follows SQL row order (orientation-stable not guaranteed). 'alphabetical' sorts by color field name. Ignored when stacking is off or no color. |
@@ -612,7 +612,7 @@ Authored overlay for LineChartStyle. Line chart style: chart-level fields + mark
 | `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
-| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. The follow-up rhythm pass cycles slots across single-series charts; until then slot 0 is used for all. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
+| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
 | `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
@@ -628,7 +628,7 @@ Authored overlay for LineChartStyle. Line chart style: chart-level fields + mark
 | `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
 | `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
 | `range` | [RangeStyle](#rangestyle) | ✓ | Color range/palette overrides for this chart type; None means no override. |
-| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override. Unset fields fall back to [`style.charts.data_table`](#chartsstyle). |
 | `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | ✓ | Endpoint label pane configuration for line charts. |
 | `marks` | [LineChartMarksStyle](#linechartmarksstyle) | ✓ | Line-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |
 
@@ -646,7 +646,7 @@ Authored overlay for AreaChartStyle. Area chart style: chart-level fields + mark
 | `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
-| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. The follow-up rhythm pass cycles slots across single-series charts; until then slot 0 is used for all. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
+| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
 | `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
@@ -662,7 +662,7 @@ Authored overlay for AreaChartStyle. Area chart style: chart-level fields + mark
 | `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
 | `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
 | `range` | [RangeStyle](#rangestyle) | ✓ | Color range/palette overrides for this chart type; None means no override. |
-| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override. Unset fields fall back to [`style.charts.data_table`](#chartsstyle). |
 | `stack` | enum: "zero", "normalize", "center" | ✓ | Default stack mode for area charts; False overlaps silhouettes. |
 | `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | ✓ | Endpoint label pane configuration for area charts. |
 | `marks` | [AreaChartMarksStyle](#areachartmarksstyle) | ✓ | Area-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |
@@ -681,7 +681,7 @@ Authored overlay for ScatterChartStyle. Scatter chart style: chart-level fields
 | `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
-| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. The follow-up rhythm pass cycles slots across single-series charts; until then slot 0 is used for all. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
+| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
 | `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
@@ -697,7 +697,7 @@ Authored overlay for ScatterChartStyle. Scatter chart style: chart-level fields
 | `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
 | `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
 | `range` | [RangeStyle](#rangestyle) | ✓ | Color range/palette overrides for this chart type; None means no override. |
-| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override. Unset fields fall back to [`style.charts.data_table`](#chartsstyle). |
 | `marks` | [ScatterChartMarksStyle](#scatterchartmarksstyle) | ✓ | Scatter-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |
 
 <a id="heatmapchartstyle"></a>
@@ -714,7 +714,7 @@ Authored overlay for HeatmapChartStyle. Heatmap chart style.
 | `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
-| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. The follow-up rhythm pass cycles slots across single-series charts; until then slot 0 is used for all. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
+| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
 | `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
@@ -730,7 +730,7 @@ Authored overlay for HeatmapChartStyle. Heatmap chart style.
 | `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
 | `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
 | `range` | [RangeStyle](#rangestyle) | ✓ | Color range/palette overrides for this chart type; None means no override. |
-| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override. Unset fields fall back to [`style.charts.data_table`](#chartsstyle). |
 | `cell_padding` | float | ✓ | Padding between heatmap cells in pixels. |
 | `color_scheme` | str | ✓ | Color scheme name for heatmap gradient (e.g. 'blues', 'viridis'). |
 | `marks` | [HeatmapChartMarksStyle](#heatmapchartmarksstyle) | ✓ | Heatmap-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |
@@ -759,7 +759,7 @@ Authored overlay for PieChartStyle. Pie/donut chart style: geometry + total (fla
 | `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
-| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. The follow-up rhythm pass cycles slots across single-series charts; until then slot 0 is used for all. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
+| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
 | `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
@@ -793,7 +793,7 @@ Authored overlay for KpiChartStyle. Produced by cascade from theme YAML.
 | `border` | [BorderStyle](#borderstyle) | ✓ | KPI card border style. |
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
-| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. The follow-up rhythm pass cycles slots across single-series charts; until then slot 0 is used for all. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
+| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
 | `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
@@ -822,7 +822,7 @@ Authored overlay for TableChartStyle. Table chart style overrides layered on top
 | `border` | [BorderStyle](#borderstyle) | ✓ | Table outer border style. |
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
-| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. The follow-up rhythm pass cycles slots across single-series charts; until then slot 0 is used for all. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
+| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
 | `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
@@ -879,7 +879,7 @@ Authored overlay for PointMapChartStyle. Point map chart style.
 | `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
-| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. The follow-up rhythm pass cycles slots across single-series charts; until then slot 0 is used for all. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
+| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
 | `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
@@ -904,7 +904,7 @@ Authored overlay for GeoshapeChartStyle. Geoshape (choropleth) chart style.
 | `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
-| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. The follow-up rhythm pass cycles slots across single-series charts; until then slot 0 is used for all. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
+| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
 | `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
@@ -955,7 +955,7 @@ Flat style patch for layered multi-mark charts.
 | `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
-| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. The follow-up rhythm pass cycles slots across single-series charts; until then slot 0 is used for all. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
+| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
 | `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style overrides. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style overrides. |
@@ -971,7 +971,7 @@ Flat style patch for layered multi-mark charts.
 | `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
 | `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
 | `range` | [RangeStyle](#rangestyle) | ✓ | Color range/palette overrides for this chart type; None means no override. |
-| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override. Unset fields fall back to [`style.charts.data_table`](#chartsstyle). |
 | `orientation` | enum: "horizontal", "vertical", "auto" | ✓ | Preferred bar orientation; None uses the renderer default (vertical). |
 | `stack` | enum: "zero", "normalize", "center" | ✓ | Default stack mode for bar/area charts. |
 | `stack_order` | enum: "value", "data", "alphabetical" | ✓ | Z-order of stacked segments. |
@@ -1138,7 +1138,7 @@ Authored overlay for ChartsStyle. Registry of all chart-type styles plus shared
 | `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
-| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. The follow-up rhythm pass cycles slots across single-series charts; until then slot 0 is used for all. |
+| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. |
 | `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
@@ -1687,7 +1687,7 @@ Authored overlay for SparkStyle. Inline sparkline defaults (inside table cells).
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `color` | str | ✓ | Sparkline line/point color; cascade-managed (inherits from style.accent). |
+| `color` | str | ✓ | Sparkline line/point color; None seeds from style.charts.single_series_palette[0]. |
 | `padding` | [SpacingValues](#spacingvalues) | ✓ | Cell padding around the sparkline in pixels. |
 | `empty` | [SparkEmptyStyle](#sparkemptystyle) | ✓ | Style for empty/no-data sparklines. |
 | `single_value` | [SparkSingleValueStyle](#sparksinglevaluestyle) | ✓ | Style for single-data-point sparklines. |
@@ -1772,8 +1772,8 @@ Authored overlay for SparkBarBarStyle. Bar geometry sub-block for SparkBarChartS
 |-------|------|:--------:|-------------|
 | `height` | float | ✓ | Height of each bar in pixels. |
 | `padding` | float | ✓ | Vertical padding between bars in pixels. |
-| `color` | str | ✓ | Bar fill color; cascade-managed (inherits from style.accent). |
-| `background` | str | ✓ | Bar track background color; cascade-managed (inherits from style.muted). |
+| `color` | str | ✓ | Bar fill color; None seeds from style.charts.single_series_palette[0]. |
+| `background` | str | ✓ | Bar track background color. Falls back to [`style.muted`](#style). |
 
 <a id="sparkbarchartlabelstyle"></a>
 ## SparkBarChartLabelStyle
@@ -1933,7 +1933,7 @@ Authored overlay for HistogramChartStyle. Histogram chart style.
 | `border` | [BorderStyle](#borderstyle) | ✓ | Chart card border style. |
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
-| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. The follow-up rhythm pass cycles slots across single-series charts; until then slot 0 is used for all. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
+| `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
 | `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
@@ -1949,7 +1949,7 @@ Authored overlay for HistogramChartStyle. Histogram chart style.
 | `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
 | `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
 | `range` | [RangeStyle](#rangestyle) | ✓ | Color range/palette overrides for this chart type; None means no override. |
-| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override. Unset fields fall back to [`style.charts.data_table`](#chartsstyle). |
 | `bin_maxbins` | int | ✓ | Maximum number of bins for auto-binning. |
 | `marks` | [HistogramChartMarksStyle](#histogramchartmarksstyle) | ✓ | Histogram-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |
 
@@ -2038,7 +2038,7 @@ Authored overlay for InputStyle.
 |-------|------|:--------:|-------------|
 | `height` | float | ✓ | Input control height in pixels. |
 | `border` | [BorderStyle](#borderstyle) | ✓ | Input border style. |
-| `focus_color` | str | ✓ | Input focus ring color; cascade-managed (inherits from style.accent). |
+| `focus_color` | str | ✓ | Input focus ring color. Falls back to [`style.accent`](#style). |
 | `background` | str | ✓ | Input background color. |
 | `padding` | [SpacingValues](#spacingvalues) | ✓ | Input inner padding in pixels. |
 | `widths` | [InputWidths](#inputwidths) | ✓ | Per-input-type default widths. |
@@ -2240,6 +2240,7 @@ Authored overlay for PointMarkStyle. Point mark style (data-point markers on lin
 | `opacity` | float | ✓ | Point opacity 0–1; None uses VL default. |
 | `filled` | bool | ✓ | Whether points are filled; None uses VL default. |
 | `fill` | str | ✓ | Point interior fill color; only applied when filled=false. |
+| `stroke_width` | float | ✓ | Stroke width in pixels for hollow point rings; None uses VL default. |
 
 <a id="rulemarkstyle"></a>
 ## RuleMarkStyle
@@ -2248,7 +2249,7 @@ Authored overlay for RuleMarkStyle. Rule (reference line) mark opacity and strok
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `opacity` | float | ✓ | Mark opacity (0–1); None means not overridden at this level. |
-| `stroke` | [StrokeStyle](#strokestyle) | ✓ | Mark stroke style; None means not overridden at this level. |
+| `stroke` | [FontColorStrokeStyle](#fontcolorstrokestyle) | ✓ | Mark stroke style. |
 
 <a id="areamarkstyle"></a>
 ## AreaMarkStyle
@@ -2369,8 +2370,8 @@ Authored overlay for SparkBarCellStyle. Inline `spark.type: bar` and `bar-normal
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `background` | str | ✓ | Track background color; cascade-managed (inherits from style.muted). |
-| `color` | str | ✓ | Bar fill color; cascade-managed (inherits from style.accent). |
+| `background` | str | ✓ | Track background color. Falls back to [`style.muted`](#style). |
+| `color` | str | ✓ | Bar fill color; None seeds from style.charts.single_series_palette[0]. |
 | `default_max` | float | ✓ | Default maximum value for bar scale when no explicit max is authored. |
 | `border` | [BorderStyle](#borderstyle) | ✓ | Spark bar border style. |
 | `font` | [FontStyle](#fontstyle) | ✓ | Spark bar cell font style overrides. Unset fields fall back to [`style.charts.font`](#chartsstyle). |
@@ -2418,7 +2419,7 @@ Authored overlay for TickMarkStyle. Tick mark opacity and stroke.
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `opacity` | float | ✓ | Mark opacity (0–1); None means not overridden at this level. |
-| `stroke` | [StrokeStyle](#strokestyle) | ✓ | Mark stroke style; None means not overridden at this level. |
+| `stroke` | [FontColorStrokeStyle](#fontcolorstrokestyle) | ✓ | Mark stroke style. |
 
 <a id="trailmarkstyle"></a>
 ## TrailMarkStyle
@@ -2532,6 +2533,18 @@ Authored overlay for StrokeStyle. Stroke appearance sub-block shared across mark
 | `join` | enum: "miter", "round", "bevel" | ✓ | Stroke line join style (miter, round, or bevel). |
 | `dasharray` | str | ✓ | SVG stroke-dasharray pattern (e.g. '4 2'). |
 
+<a id="fontcolorstrokestyle"></a>
+## FontColorStrokeStyle
+Authored overlay for FontColorStrokeStyle. Stroke for tick/rule marks whose color defaults to the root font color.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `color` | str | ✓ | Stroke color. Falls back to [`style.font.color`](#rootfontstyle). |
+| `width` | float | ✓ | Stroke width in pixels. |
+| `cap` | enum: "butt", "round", "square" | ✓ | Stroke line cap style (butt, round, or square). |
+| `join` | enum: "miter", "round", "bevel" | ✓ | Stroke line join style (miter, round, or bevel). |
+| `dasharray` | str | ✓ | SVG stroke-dasharray pattern (e.g. '4 2'). |
+
 <a id="slicelabelsstyle"></a>
 ## SliceLabelsStyle
 Authored overlay for SliceLabelsStyle. Pie labels: typography + positioning offsets for per-slice text.
@@ -2539,9 +2552,9 @@ Authored overlay for SliceLabelsStyle. Pie labels: typography + positioning offs
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `offset` | float | ✓ | Radial offset of slice labels from the arc in pixels. |
-| `block_height` | float | ✓ | Reserved height per label block in pixels. |
-| `line_height` | float | ✓ | Line height for multi-line slice labels 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). |
+| `default_template` | [LabelsDefaultTemplate](#labelsdefaulttemplate) | ✓ | Default Jinja templates for per-slice labels when the chart author omits ``labels:`` on a pie/donut. |
 
 <a id="tablerowrolestyle"></a>
 ## TableRowRoleStyle
@@ -2573,6 +2586,15 @@ Authored overlay for DetailsArrowFontStyle. Font style for the expand/collapse a
 |-------|------|:--------:|-------------|
 | `size` | float | ✓ | Font size of the arrow glyph in pixels. |
 
+<a id="labelsdefaulttemplate"></a>
+## LabelsDefaultTemplate
+Authored overlay for LabelsDefaultTemplate. Default Jinja templates for per-slice pie/donut labels.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `with_color` | str | ✓ | Default per-slice label template when the chart has a color binding. |
+| `no_color` | str | ✓ | Default per-slice label template when the chart has no color binding. |
+
 <a id="postgressourceconfig"></a>
 ## PostgresSourceConfig
 Postgres source configuration.

dataface/agent_api/project_session.py

@@ -36,6 +36,7 @@ from dataface.core.execute.adapters.adapter_registry import (
     build_adapter_registry,
 )
 from dataface.core.execute.duckdb_cache import DuckDBCache
+from dataface.core.execute.observability import WarehouseObserver
 from dataface.core.inspect.query_validator import (
     QueryDiagnostic,
     validate_query as _core_validate_query,
@@ -76,6 +77,7 @@ class ProjectSession:
     _duckdb_config: dict[str, Any] | None
     _allow_external_access_in_readonly: bool
     _resolver: SourceResolver | None
+    _observers: list[WarehouseObserver]
 
     def __init__(
         self,
@@ -83,6 +85,7 @@ class ProjectSession:
         cache: DuckDBCache | None = None,
         adapter_registry: AdapterRegistry | None = None,
         read_only: bool = True,
+        observers: list[WarehouseObserver] | None = None,
     ) -> None:
         self.project = project
         self.cache = cache
@@ -100,6 +103,7 @@ class ProjectSession:
         self._duckdb_config = None
         self._allow_external_access_in_readonly = False
         self._resolver = None
+        self._observers = list(observers) if observers else []
 
     @classmethod
     def open(
@@ -114,6 +118,7 @@ class ProjectSession:
         duckdb_config: dict[str, Any] | None = None,
         allow_external_access_in_readonly: bool = False,
         resolver: SourceResolver | None = None,
+        observers: list[WarehouseObserver] | None = None,
     ) -> Self:
         """Construct a ProjectSession rooted at *project_dir*.
 
@@ -130,6 +135,7 @@ class ProjectSession:
             project=Project(Path(project_dir).resolve()),
             cache=cache,
             read_only=read_only,
+            observers=observers,
         )
         session._connection_string = connection_string
         session._dialect = dialect
@@ -152,6 +158,7 @@ class ProjectSession:
         duckdb_config: dict[str, Any] | None = None,
         allow_external_access_in_readonly: bool = False,
         resolver: SourceResolver | None = None,
+        observers: list[WarehouseObserver] | None = None,
     ) -> Self:
         """Construct a ProjectSession from a pre-built Project.
 
@@ -159,7 +166,9 @@ class ProjectSession:
         not want to re-resolve the path.  The caller owns the Project lifecycle;
         this method stores it directly without re-wrapping.
         """
-        session = cls(project=project, cache=cache, read_only=read_only)
+        session = cls(
+            project=project, cache=cache, read_only=read_only, observers=observers
+        )
         session._connection_string = connection_string
         session._dialect = dialect
         session._target = target
@@ -204,6 +213,7 @@ class ProjectSession:
             duckdb_config=self._duckdb_config,
             allow_external_access_in_readonly=self._allow_external_access_in_readonly,
             resolver=self._resolver,
+            observers=self._observers,
         )
 
     def refresh(self) -> None:

dataface/ai/prompts/sql-guidance.md

@@ -1,5 +1,17 @@
 ## SQL Generation Rules
 
+Before writing SQL, write a short query plan:
+
+- **OUTPUT**: the columns to return, with clear aliases that describe the value
+- **FROM/JOIN**: the tables and the join keys between them
+- **GRAIN**: what one row represents after the joins; guard against fan-out / double-counting on the non-unique side of a join — if a join multiplies rows, aggregate before joining or add a GROUP BY
+- **FILTERS**: each WHERE condition; verify the exact stored value before filtering (stored values may differ from display labels — e.g. `'LA'` not `'Los Angeles'`)
+- **SORT/LIMIT**: include if the question asks to rank, sort, or return a top-N
+
+Then translate the plan faithfully into SQL. Verify by executing the query and checking that shape and values match the plan.
+
+Additional rules:
+
 - Write SQL that matches the database dialect in the schema context.
 - Use real table and column names from the provided schema context.
 - Use clear column aliases so results are self-describing.

dataface/cli/commands/schema.py

@@ -363,6 +363,8 @@ def _print_rich(
                         meta.append(f"rows={rc}")
                     if grain := summary.get("grain"):
                         meta.append(grain)
+                    if joins := summary.get("joins"):
+                        meta.append(f"joins={len(joins)}")
                     line = f"    {tname.ljust(name_w)}  {'  '.join(meta)}"
                     typer.echo(line.rstrip())
         return
@@ -516,6 +518,10 @@ def _echo_joins(name: str, data: dict[str, Any], columns: dict[str, Any]) -> Non
             entry["multiplicity"] = mult
         if (conf := rel.get("confidence")) is not None:
             entry["confidence"] = conf
+        # A super_schema edge sourced from a declared FK is authoritative — mark
+        # it declared so it renders without a misleading ~confidence guess.
+        if str(rel.get("source", "")).startswith("declared"):
+            entry["declared"] = True
 
     lines: list[str] = []
     for (fc, tt, tc), info in outbound.items():

dataface/core/compile/config.py

@@ -636,11 +636,11 @@ def _absolutize_source_paths(
                 and path_value != ":memory:"
                 and not Path(path_value).is_absolute()
             ):
-                cfg["path"] = str((project.root / path_value).resolve())
+                cfg["path"] = str(project.data_path(path_value))
         elif source_type in {"csv", "parquet", "json"}:
             file_value = cfg.get("file")
             if isinstance(file_value, str) and not Path(file_value).is_absolute():
-                cfg["file"] = str((project.root / file_value).resolve())
+                cfg["file"] = str(project.data_path(file_value))
         resolved[name] = cfg
     return resolved
 

dataface/core/compile/data_table_attachment.py

@@ -952,19 +952,15 @@ def resolve_effective_data_table_style(
 ) -> DataTableStyle:
     """Resolve the effective data_table style for a chart.
 
-    Applies the per-chart-type override (tier 2, spec §4.1) on top of the
-    universal style.charts.data_table (tier 1). Tier 3 (chart-local patch)
-    is already merged into charts_style.data_table via pipeline.py before
-    this function is called.
+    charts_style.data_table carries the global theme value merged with any
+    chart-local face override.  apply_inherit pre-fills per-family data_table
+    fields from charts.data_table, so this function only needs to apply the
+    per-family theme values (tier-2) on top.
     """
-    base: DataTableStyle = charts_style.data_table
     per_type = getattr(charts_style, chart_type, None)
-    if per_type is None:
-        return base
-    override = getattr(per_type, "data_table", None)
-    if override is None:
-        return base
-    return deep_merge(base, override)
+    if per_type is None or not hasattr(per_type, "data_table"):
+        return charts_style.data_table
+    return deep_merge(charts_style.data_table, per_type.data_table)
 
 
 def attach_data_table(

dataface/core/compile/inherit_graph.py

@@ -184,6 +184,14 @@ def _build_graph(
                         raise ValueError(
                             f"InheritSlot from_path {from_path!r} does not match any path in the model"
                         )
+                    # 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
+                    # None intermediates, so leaf links alone cannot fill a None
+                    # container.  After the copy, leaf links fill any remaining None
+                    # sub-fields when the field was partially set.
+                    if type(None) in typing.get_args(field_info.annotation):
+                        graph[_path_str(current)] = from_path
                     _build_graph(
                         nested,
                         current,

dataface/core/compile/inherit_registry.yaml

@@ -32,6 +32,8 @@ Style.charts.area.axis_y.label.font:
 Style.charts.area.axis_y.title.font:
 - Style.charts.font
 - Style.font
+Style.charts.area.data_table:
+- Style.charts.data_table
 Style.charts.area.legend.label.font:
 - Style.charts.font
 - Style.font
@@ -96,6 +98,8 @@ Style.charts.bar.axis_y.label.font:
 Style.charts.bar.axis_y.title.font:
 - Style.charts.font
 - Style.font
+Style.charts.bar.data_table:
+- Style.charts.data_table
 Style.charts.bar.legend.label.font:
 - Style.charts.font
 - Style.font
@@ -181,6 +185,8 @@ Style.charts.heatmap.axis_y.label.font:
 Style.charts.heatmap.axis_y.title.font:
 - Style.charts.font
 - Style.font
+Style.charts.heatmap.data_table:
+- Style.charts.data_table
 Style.charts.heatmap.legend.label.font:
 - Style.charts.font
 - Style.font
@@ -231,6 +237,8 @@ Style.charts.histogram.axis_y.label.font:
 Style.charts.histogram.axis_y.title.font:
 - Style.charts.font
 - Style.font
+Style.charts.histogram.data_table:
+- Style.charts.data_table
 Style.charts.histogram.legend.label.font:
 - Style.charts.font
 - Style.font
@@ -324,6 +332,8 @@ Style.charts.line.axis_y.label.font:
 Style.charts.line.axis_y.title.font:
 - Style.charts.font
 - Style.font
+Style.charts.line.data_table:
+- Style.charts.data_table
 Style.charts.line.legend.label.font:
 - Style.charts.font
 - Style.font
@@ -340,9 +350,13 @@ Style.charts.line.palette:
 - Style.charts.palette
 Style.charts.line.single_series_palette:
 - Style.charts.single_series_palette
+Style.charts.marks.rule.stroke.color:
+- Style.font.color
 Style.charts.marks.text.font:
 - Style.charts.font
 - Style.font
+Style.charts.marks.tick.stroke.color:
+- Style.font.color
 Style.charts.pie.animation_duration:
 - Style.charts.animation_duration
 Style.charts.pie.legend.label.font:
@@ -421,6 +435,8 @@ Style.charts.scatter.axis_y.label.font:
 Style.charts.scatter.axis_y.title.font:
 - Style.charts.font
 - Style.font
+Style.charts.scatter.data_table:
+- Style.charts.data_table
 Style.charts.scatter.legend.label.font:
 - Style.charts.font
 - Style.font
@@ -440,6 +456,8 @@ Style.charts.scatter.single_series_palette:
 Style.charts.series_label.font:
 - Style.charts.font
 - Style.font
+Style.charts.spark_bar.bar.background:
+- Style.muted
 Style.charts.spark_bar.font:
 - Style.charts.font
 - Style.font
@@ -476,6 +494,8 @@ Style.charts.table.palette:
 - Style.charts.palette
 Style.charts.table.single_series_palette:
 - Style.charts.single_series_palette
+Style.charts.table.spark.bar.background:
+- Style.muted
 Style.charts.table.spark.bar.font:
 - Style.charts.font
 - Style.font
@@ -506,6 +526,8 @@ Style.title.subtitle.font:
 - Style.font
 Style.variables.font:
 - Style.font
+Style.variables.input.focus_color:
+- Style.accent
 Style.variables.label.font:
 - Style.variables.font
 - Style.font

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 deep_merge, replacing the former hard-coded push loop approach.
 
-Not in scope: _apply_token_cascade, _build_resolved_style, resolved_axis_style.
+Not in scope: _build_resolved_style, resolved_axis_style.
 """
 
 from __future__ import annotations