dataface 0.1.4.dev6__py3-none-any.whl → 0.1.5.dev88__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -461,7 +461,6 @@ charts:
 
     # Style + behavior
     sort: { by: total, order: desc }
-    stack: zero               # false | zero | normalize | center
     format: integer           # named alias or raw D3 spec (e.g. ",.0f")
     x_label: "Month"
     y_label: "Revenue (USD)"
@@ -470,7 +469,7 @@ charts:
 
     style:                    # Chart-local style patch (typed; not raw CSS) — paint only
       orientation: vertical   # style: does NOT accept height or aspect_ratio
-      stack: true
+      stack: zero               # false | true | zero | normalize | center
 ```
 
 ### Chart types (29 total)
@@ -523,7 +522,6 @@ All chart types accept the channels and style fields below — but each type rej
 | `longitude` | string | Longitude field (point/bubble map) |
 | `background` | string \| object | Background channel — color, `{value}`, `{field, scale/when}`, or map layer |
 | `sort` | object | `{by, order}` — categorical sort |
-| `stack` | bool \| enum | `false`, `zero`, `normalize`, or `center` |
 | `link` | string | Click-through URL template for drill-down links |
 | `filters` | object | Post-execution row filters: `{col: var_name}` (implicit `eq`) or `{col: {op: var}}` where op is one of `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`, `in`, `not_in`, `between`. Implicit-eq values may also be Jinja templates (e.g. `"{{ region }}"`) resolved at execute time. A filter is skipped when the variable is `None`, `""`, or renders to `"none"`. |
 | `layers` | list | Layer definitions for `type: layered` (see [Composition](#composition)) |
@@ -561,7 +559,8 @@ color: segment         # Optional: one line per segment
 type: area
 x: date
 y: value
-stack: normalize       # 100% stacked
+style:
+  stack: normalize     # 100% stacked
 
 # scatter — x and y numeric
 type: scatter
@@ -1113,17 +1112,30 @@ Active code categories (see `dataface/core/errors/codes_*.py` for the authoritat
 
 | Prefix | Meaning |
 |--------|---------|
+| `DF-COMPILE-*` | Compile-time errors (missing fields, unknown references, malformed YAML) |
 | `DF-RENDER-*` | Chart rendering errors (wrong row counts, unknown chart types, format issues) |
 | `DF-EXECUTE-*` | Query execution errors (missing sources, inline-source policy, source typing) |
 | `DF-UNKNOWN-*` | Fallback codes for legacy string-message errors not yet migrated |
 
-The registry is being filled out incrementally — many compile-time and variable-resolution errors still raise as plain `DatafaceError` without a structured code. Today's typed codes:
+The registry is being filled out incrementally — some compile-time and variable-resolution errors still raise as plain `DatafaceError` without a structured code. Today's typed codes:
+
+### Compile errors
+
+- **`DF-COMPILE-SOURCE-REQUIRED`** — a SQL query has no `source:` and no default is configured. Set the source on the query (`source: my_db`), at the face level (`source:` or `sources.default`), or project-wide via `sources.default` in `dataface.yml`.
+- **`DF-COMPILE-UNKNOWN-QUERY`** — a chart's `query:` references a name that does not appear under `queries:`. Check for a typo or add the missing query.
+- **`DF-COMPILE-EXTRA-FIELD`** — the face YAML contains a field not recognised by the schema. Remove it or check the schema for supported keys.
+- **`DF-COMPILE-SQL-LITERAL-NEWLINES`** — a SQL field contains a literal `\n` (backslash + n) from single-quoted YAML. Use a YAML block scalar (`sql: |`) to write multiline SQL.
+
+### Render errors
 
 - **`DF-RENDER-KPI-MULTIROW`** — a KPI chart's query returned more than one row but `value` is a column reference. Add `LIMIT 1` or aggregate down to one row.
 - **`DF-RENDER-UNKNOWN-CHART-TYPE`** — `type:` is not a recognized chart type. See the [Charts](#charts) section for the list.
 - **`DF-RENDER-FORMAT-UNSUPPORTED`** — the render `format` argument is not one of `svg`/`html`/`png`.
 - **`DF-RENDER-NO-LAYOUT`** — the face has no `rows`/`cols`/`grid`/`tabs` and nothing to render.
 - **`DF-RENDER-INPUT-INVALID`** — the render call received structurally invalid input (e.g. both `path` and `yaml_content`).
+
+### Execute errors
+
 - **`DF-EXECUTE-SOURCE-NOT-FOUND`** / **`-NOT-FOUND-EMPTY`** — the query's `source:` (or default source) is not configured in `dataface.yml`.
 - **`DF-EXECUTE-NO-DEFAULT-SOURCE`** — multiple sources are defined and no `default_source` was set.
 - **`DF-EXECUTE-SOURCE-INLINE-FORBIDDEN`** / **`-CROSS-FILE-FORBIDDEN`** — inline source definitions are restricted by project policy.

dataface/agent_api/_init_templates/{index.md → README.md}

@@ -11,14 +11,14 @@ for your data project.
 ## Authoring modes
 
 **YAML (`.yml`)** — structured dashboards with queries, charts, and layout.
-See the [dataface guide](dataface) for a working example covering queries, charts, and variables.
+See the [dataface guide](guide) for a working example covering queries, charts, and variables.
 
 **Markdown (`.md`)** — prose pages like this one. Add YAML frontmatter for
 queries and charts, then embed them inline with `{% raw %}{{ chart my_chart }}{% endraw %}`.
 
 ## Next steps
 
-1. Open `faces/dataface.yml` and tweak the content.
+1. Open `faces/guide.yml` and tweak the content.
 2. Run `dft serve` and open the URL it prints.
 3. Add new `.yml` or `.md` files under `faces/` — they appear automatically.
 4. Run `dft validate` to validate your face YAML for errors.

dataface/agent_api/_project_agents_md.py

@@ -15,7 +15,7 @@ _TEMPLATES = importlib.resources.files("dataface.agent_api._init_templates")
 
 def load_agents_snippet() -> str:
     """Return the packaged markdown blurb (includes marker comments)."""
-    return _TEMPLATES.joinpath("agents_dft_snippet.md").read_text()
+    return _TEMPLATES.joinpath("agents_dft_snippet.md").read_text(encoding="utf-8")
 
 
 def has_dataface_markers(text: str) -> bool:

dataface/agent_api/_session_store.py

@@ -198,7 +198,7 @@ class SessionIndex:
     def _load(self) -> dict[str, list[SessionMeta]]:
         if self._path.exists():
             try:
-                raw = json.loads(self._path.read_text())
+                raw = json.loads(self._path.read_text(encoding="utf-8"))
                 if isinstance(raw, dict):
                     return raw
                 logger.warning("sessions/index.json has unexpected shape; rebuilding")
@@ -208,7 +208,7 @@ class SessionIndex:
 
     def _save(self) -> None:
         self._path.parent.mkdir(parents=True, exist_ok=True)
-        self._path.write_text(json.dumps(self._data, indent=2))
+        self._path.write_text(json.dumps(self._data, indent=2), encoding="utf-8")
 
     def _rebuild(self) -> dict[str, list[SessionMeta]]:
         """Scan all JSONL files under ~/.dft/sessions/ and reconstruct the index."""
@@ -234,7 +234,7 @@ class SessionIndex:
             data.setdefault(cwd, []).append(entry)
         # Persist the rebuilt index
         self._path.parent.mkdir(parents=True, exist_ok=True)
-        self._path.write_text(json.dumps(data, indent=2))
+        self._path.write_text(json.dumps(data, indent=2), encoding="utf-8")
         return data
 
 

dataface/agent_api/dashboards.py

@@ -148,7 +148,7 @@ def list_dashboards(
         if yaml_file.name.startswith("_"):
             continue
         try:
-            content = yaml.safe_load(yaml_file.read_text())
+            content = yaml.safe_load(yaml_file.read_text(encoding="utf-8"))
             if not isinstance(content, dict):
                 skipped.append(
                     SkippedFile(
@@ -235,7 +235,7 @@ def get_dashboard(
         )
 
     try:
-        raw_yaml = file_path.read_text()
+        raw_yaml = file_path.read_text(encoding="utf-8")
     except OSError as e:
         return CompiledDashboard(
             success=False,

dataface/agent_api/describe.py

@@ -7,11 +7,11 @@ from typing import Any
 
 from pydantic import BaseModel, Field
 
-from dataface.core.compile.models.chart.compiled import (
+from dataface.core.compile.models.chart.normalized import (
     Chart,
 )
-from dataface.core.compile.models.face.compiled import Layout
-from dataface.core.compile.models.query.compiled import (
+from dataface.core.compile.models.face.normalized import Layout
+from dataface.core.compile.models.query.normalized import (
     CsvQuery,
     DbtModelQuery,
     HttpQuery,

dataface/agent_api/describe_query.py

@@ -109,7 +109,7 @@ def _duckdb_describe(
     sql: str, source: str | None, adapter_registry: AdapterRegistry
 ) -> list[DescribeQueryColumn]:
     """Run DESCRIBE ({sql}) via the registry's read-only SqlAdapter."""
-    from dataface.core.compile.models.query.compiled import SqlQuery
+    from dataface.core.compile.models.query.normalized import SqlQuery
 
     result = adapter_registry.execute(SqlQuery(sql=f"DESCRIBE ({sql})", source=source))
     if result.error:

dataface/agent_api/docs/yaml-reference.md

@@ -15,7 +15,7 @@ AuthoredFace (dataface) definition from YAML.
 | `source` | str | ✓ | Default source name shorthand (equivalent to sources.default). Sets the connection for all queries. |
 | `variables` | dict[str, [Variable](#variable) \| VariableRef] | ✓ | Variable definitions for dynamic filtering and UI controls. |
 | `queries` | dict[str, [Query](#query) \| QueryRef] | ✓ | Named query definitions (SQL, CSV, MetricFlow, HTTP, etc.). |
-| `charts` | dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| ChartRef] | ✓ | Named chart definitions referenced in the layout. |
+| `charts` | dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| ChartRef] | ✓ | Named chart definitions. When no explicit layout is present, charts render as an implicit row layout in authored order. |
 | `rows` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Vertical stack layout: list of chart names or inline chart/face definitions. |
 | `cols` | list[str \| [Face](#face) \| [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart) \| [ForeachItem](#foreachitem) \| dict[str, [BarChart](#barchart) \| [LineChart](#linechart) \| [AreaChart](#areachart) \| [ScatterChart](#scatterchart) \| [HeatmapChart](#heatmapchart) \| [PieChart](#piechart) \| [KpiChart](#kpichart) \| [TableChart](#tablechart) \| [PointMapChart](#pointmapchart) \| [GeoshapeChart](#geoshapechart) \| [LayeredChart](#layeredchart) \| [CalloutChart](#calloutchart) \| [SparkBarChart](#sparkbarchart)]] | ✓ | Horizontal layout: list of chart names or inline chart/face definitions. |
 | `grid` | [GridLayout](#gridlayout) | ✓ | CSS-grid style layout with explicit row/column placement. |
@@ -646,13 +646,14 @@ HTTP/REST API source configuration.
 
 <a id="dbtprofilesourceconfig"></a>
 ## DbtProfileSourceConfig
-Reference to a dbt profile (for backward compatibility).
+Reference to a dbt profile.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `type` | enum: "dbt_profile" |  | Source type identifier. |
 | `profile` | str |  | dbt profile name from profiles.yml. |
 | `target` | str | ✓ | dbt target to use; defaults to the profile's default target. |
+| `profiles_dir` | str | ✓ | Directory containing profiles.yml, relative to the dataface project root. Use when profiles.yml is in a subdirectory (e.g. services/dbt). Resolution order: profiles_dir → $DBT_PROFILES_DIR → project root → ~/.dbt. |
 
 <a id="variableoptions"></a>
 ## VariableOptions
@@ -758,7 +759,7 @@ Authored overlay for BarChartStyle. Bar chart style: chart-level fields + marks
 | `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
 | `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` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; 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. |
 | `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). |
@@ -795,7 +796,7 @@ Authored overlay for LineChartStyle. Line chart style: chart-level fields + mark
 | `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
 | `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` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; 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. |
 | `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | ✓ | Endpoint label pane configuration for line charts. |
 | `marks` | [LineChartMarksStyle](#linechartmarksstyle) | ✓ | Line-family mark overrides. |
@@ -829,7 +830,7 @@ Authored overlay for AreaChartStyle. Area chart style: chart-level fields + mark
 | `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
 | `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` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; 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. |
 | `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. |
@@ -864,7 +865,7 @@ Authored overlay for ScatterChartStyle. Scatter chart style: chart-level fields
 | `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
 | `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` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; 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. |
 | `marks` | [ScatterChartMarksStyle](#scatterchartmarksstyle) | ✓ | Scatter-family mark overrides. |
 
@@ -897,7 +898,7 @@ Authored overlay for HeatmapChartStyle. Heatmap chart style.
 | `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
 | `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` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; 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. |
 | `cell_padding` | float | ✓ | Padding between heatmap cells in pixels. |
 | `color_scheme` | str | ✓ | Color scheme name for heatmap gradient (e.g. 'blues', 'viridis'). |
@@ -1129,7 +1130,7 @@ Flat style patch for layered multi-mark charts.
 | `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
 | `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
 | `scale` | ScaleStyle | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
-| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; 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. |
 | `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. |
@@ -1485,11 +1486,21 @@ Authored overlay for LegendStyle.
 
 <a id="tooltipstyle"></a>
 ## TooltipStyle
-Authored overlay for TooltipStyle. Tooltip rendering defaults.
+Authored overlay for TooltipStyle. Tooltip box style — all cascade keys for the hover bubble.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
 | `format` | str | ✓ | Default tooltip value format string; theme always provides this. |
+| `background` | str | ✓ | Tooltip background color (CSS color string); theme always provides this. |
+| `line_height` | float | ✓ | Tooltip line-height multiplier; theme always provides this. |
+| `max_width` | float | ✓ | Maximum tooltip width in pixels; theme always provides this. |
+| `gap` | float | ✓ | Gap in pixels between label and value columns; theme always provides this. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Tooltip font overrides (size etc.); cascade fills missing fields. |
+| `padding` | [PaddingStyle](#paddingstyle) | ✓ | Tooltip inner padding (4 sides in pixels); theme always provides this. |
+| `label` | [TooltipSlotStyle](#tooltipslotstyle) | ✓ | Label-column font overrides (color, weight). |
+| `value` | [TooltipSlotStyle](#tooltipslotstyle) | ✓ | Value-column font overrides (color, weight). |
+| `border` | [TooltipBorderStyle](#tooltipborderstyle) | ✓ | Tooltip border style; theme always provides this. |
+| `shadow` | [TooltipShadowStyle](#tooltipshadowstyle) | ✓ | Tooltip drop-shadow config; theme always provides this. |
 
 <a id="stylecolorconfig"></a>
 ## StyleColorConfig
@@ -1545,6 +1556,17 @@ Authored overlay for ScaleStyle. Scale configuration primitive.
 | `nice` | bool | ✓ | Round scale domain to nice values; None uses Vega-Lite's default. |
 | `padding` | float | ✓ | Unified scale padding shortcut; dispatches to band, point, or continuous padding per scale type. |
 
+<a id="rangestyle"></a>
+## RangeStyle
+Chart-local palette/range overlay — no theme cascade.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `category` | list[str] | ✓ | Per-chart categorical color palette (list of CSS color strings). |
+| `diverging` | list[str] | ✓ | Per-chart diverging color scale colors. |
+| `heatmap` | list[str] | ✓ | Per-chart heatmap color scale colors. |
+| `ramp` | list[str] | ✓ | Per-chart sequential color ramp colors. |
+
 <a id="datatablestyle"></a>
 ## DataTableStyle
 Authored overlay for DataTableStyle. Attached data_table style. Lives at style.charts.data_table.*.
@@ -1729,7 +1751,7 @@ Authored overlay for TableTitleStyle.
 
 <a id="paginationconfig"></a>
 ## PaginationConfig
-Authored overlay for PaginationConfig. Table pagination configuration.
+Table pagination configuration.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
@@ -1738,7 +1760,7 @@ Authored overlay for PaginationConfig. Table pagination configuration.
 
 <a id="tablecolumndefaultsconfig"></a>
 ## TableColumnDefaultsConfig
-Authored overlay for TableColumnDefaultsConfig. Table-level defaults applied to every column unless overridden per-column.
+Table-level defaults applied to every column unless overridden per-column.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
@@ -2019,8 +2041,8 @@ Scatter chart style: chart-level fields + marks sub-block.
 | `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
 | `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
 | `scale` | ScaleStyle | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
-| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
-| `data_table` | DataTableStylePatch | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `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. |
 | `marks` | ScatterChartMarksStyle | ✓ | Scatter-family mark overrides. |
 
 <a id="histogramchartstyle"></a>
@@ -2052,7 +2074,7 @@ Authored overlay for HistogramChartStyle. Histogram chart style.
 | `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
 | `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` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; 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. |
 | `bin_maxbins` | int | ✓ | Maximum number of bins for auto-binning. |
 | `marks` | [HistogramChartMarksStyle](#histogramchartmarksstyle) | ✓ | Histogram-family mark overrides. |
@@ -2086,8 +2108,8 @@ Boxplot chart style.
 | `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
 | `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
 | `scale` | ScaleStyle | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
-| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
-| `data_table` | DataTableStylePatch | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `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. |
 | `marks` | BoxplotChartMarksStyle | ✓ | Boxplot-family mark overrides. |
 
 <a id="errorbarchartstyle"></a>
@@ -2119,8 +2141,8 @@ Error bar chart style.
 | `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
 | `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
 | `scale` | ScaleStyle | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
-| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
-| `data_table` | DataTableStylePatch | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `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. |
 | `marks` | ErrorbarChartMarksStyle | ✓ | Errorbar-family mark overrides. |
 
 <a id="errorbandchartstyle"></a>
@@ -2152,8 +2174,8 @@ Error band chart style.
 | `number_format` | str | ✓ | Default number format for axes and tooltips (D3 format string); None inherits from theme. |
 | `time_format` | str | ✓ | Default time format for temporal axes (D3 time format string); None inherits from theme. |
 | `scale` | ScaleStyle | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
-| `range` | RangeStylePatch | ✓ | Color range/palette overrides for this chart type; None means no override. |
-| `data_table` | DataTableStylePatch | ✓ | Per-chart-type data_table style override; None uses the universal style.charts.data_table. |
+| `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. |
 | `marks` | ErrorbandChartMarksStyle | ✓ | Errorband-family mark overrides. |
 
 <a id="serieslabelstyle"></a>
@@ -2266,6 +2288,32 @@ Authored overlay for LegendElementStyle.
 | `font` | [FontStyle](#fontstyle) | ✓ | Legend element font style overrides. |
 | `padding` | float | ✓ | Padding between legend symbol and element text in pixels. |
 
+<a id="tooltipslotstyle"></a>
+## TooltipSlotStyle
+Authored overlay for TooltipSlotStyle. Typography for a single tooltip slot (label or value).
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `font` | [FontStyle](#fontstyle) | ✓ | Font overrides for this tooltip slot (color, weight). |
+
+<a id="tooltipborderstyle"></a>
+## TooltipBorderStyle
+Authored overlay for TooltipBorderStyle. Tooltip box border — all fields required; theme YAML supplies defaults.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `color` | str | ✓ | Border color as a CSS color string. |
+| `width` | float | ✓ | Border width in pixels. |
+| `radius` | float | ✓ | Border corner radius in pixels. |
+
+<a id="tooltipshadowstyle"></a>
+## TooltipShadowStyle
+Authored overlay for TooltipShadowStyle. Tooltip drop-shadow toggle. JS applies the shadow expression when visible=true.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show a drop-shadow on the tooltip box; theme always provides this. |
+
 <a id="scaletargetconfig"></a>
 ## ScaleTargetConfig
 Scale configuration for a single style target (background or color).
@@ -2765,12 +2813,3 @@ Discriminated union of per-family chart patches. type: is mandatory; missing or
 | `longitude` | str | ✓ | Field containing longitude values for point/bubble maps. |
 | `basemap` | [BasemapConfig](#basemapconfig) | ✓ | Tile-layer configuration for the map background. |
 | `x_domain` | enum: "union", "primary" | ✓ | Controls how x-values from multiple layer queries are combined. |
-
-<a id="paginationconfig"></a>
-## PaginationConfig
-Table pagination configuration.
-
-| Field | Type | Optional | Description |
-|-------|------|:--------:|-------------|
-| `enabled` | bool | ✓ | Enable client-side pagination for table charts. |
-| `page_size` | int | ✓ | Rows per page. When enabled and None, the renderer auto-fits page size to the cell — set explicitly to pin the page size. |

dataface/agent_api/init.py

@@ -51,9 +51,18 @@ def init_project(
     (root / "faces" / "partials").mkdir(exist_ok=True)
 
     scaffolds: list[tuple[str, str]] = [
-        ("dataface.yml", _TEMPLATES.joinpath("dataface.yml").read_text()),
-        ("faces/index.md", _TEMPLATES.joinpath("index.md").read_text()),
-        ("faces/dataface.yml", _TEMPLATES.joinpath("faces-dataface.yml").read_text()),
+        (
+            "dataface.yml",
+            _TEMPLATES.joinpath("dataface.yml").read_text(encoding="utf-8"),
+        ),
+        (
+            "faces/README.md",
+            _TEMPLATES.joinpath("README.md").read_text(encoding="utf-8"),
+        ),
+        (
+            "faces/guide.yml",
+            _TEMPLATES.joinpath("guide.yml").read_text(encoding="utf-8"),
+        ),
         ("faces/partials/.gitkeep", ""),
     ]
 
@@ -62,10 +71,10 @@ def init_project(
         if target.exists() and not force:
             result.skipped_files.append(Path(rel))
         elif target.exists():
-            target.write_text(content)
+            target.write_text(content, encoding="utf-8")
             result.refreshed_files.append(Path(rel))
         else:
-            target.write_text(content)
+            target.write_text(content, encoding="utf-8")
             result.created_files.append(Path(rel))
 
     _ensure_gitignore_entries(root, result)
@@ -74,10 +83,12 @@ def init_project(
         snippet = load_agents_snippet()
         agents_md_path = root / "AGENTS.md"
         existing: str | None = (
-            agents_md_path.read_text() if agents_md_path.exists() else None
+            agents_md_path.read_text(encoding="utf-8")
+            if agents_md_path.exists()
+            else None
         )
         final_text, action = merge_agents_snippet(existing, snippet)
-        agents_md_path.write_text(final_text)
+        agents_md_path.write_text(final_text, encoding="utf-8")
         if action == "created":
             result.created_files.append(Path("AGENTS.md"))
         elif action == "refreshed":
@@ -88,7 +99,7 @@ def init_project(
     if write_claude_md:
         claude_md_path = root / "CLAUDE.md"
         if not claude_md_path.exists():
-            claude_md_path.write_text("@AGENTS.md\n")
+            claude_md_path.write_text("@AGENTS.md\n", encoding="utf-8")
             result.created_files.append(Path("CLAUDE.md"))
 
     if eject_inspect:
@@ -111,16 +122,18 @@ def init_project(
 def _ensure_gitignore_entries(root: Path, result: InitResult) -> None:
     gitignore = root / ".gitignore"
     if not gitignore.exists():
-        gitignore.write_text("\n".join(GITIGNORE_ENTRIES) + "\n")
+        gitignore.write_text("\n".join(GITIGNORE_ENTRIES) + "\n", encoding="utf-8")
         result.created_files.append(Path(".gitignore"))
         return
 
-    text = gitignore.read_text()
+    text = gitignore.read_text(encoding="utf-8")
     existing = set(text.splitlines())
     missing = [e for e in GITIGNORE_ENTRIES if e not in existing]
     if not missing:
         return
 
     separator = "" if not text or text.endswith("\n") else "\n"
-    gitignore.write_text(f"{text}{separator}" + "\n".join(missing) + "\n")
+    gitignore.write_text(
+        f"{text}{separator}" + "\n".join(missing) + "\n", encoding="utf-8"
+    )
     result.refreshed_files.append(Path(".gitignore"))

dataface/agent_api/inspect.py

@@ -78,9 +78,9 @@ def eject_templates(
         if target_file.exists() and not force:
             continue
 
-        content = source_file.read_text()
+        content = source_file.read_text(encoding="utf-8")
         source_hash = sha256(content.encode("utf-8")).hexdigest()
-        target_file.write_text(content)
+        target_file.write_text(content, encoding="utf-8")
 
         manifest_templates[name] = {
             "filename": f"{name}.yml",

dataface/agent_api/mcp_install.py

@@ -126,7 +126,7 @@ def _upsert_mcp_config(
     existing: dict[str, Any] = {}
     if config_path.exists():
         try:
-            existing = json.loads(config_path.read_text())
+            existing = json.loads(config_path.read_text(encoding="utf-8"))
             if not isinstance(existing, dict):
                 existing = {}
         except (json.JSONDecodeError, OSError):
@@ -140,7 +140,7 @@ def _upsert_mcp_config(
 
     existing.setdefault(servers_key, {})
     existing[servers_key]["dataface"] = server_entry
-    config_path.write_text(json.dumps(existing, indent=2) + "\n")
+    config_path.write_text(json.dumps(existing, indent=2) + "\n", encoding="utf-8")
     return f"  {'Updated' if already_has else 'Added dataface to'} {config_path}"
 
 
@@ -158,7 +158,7 @@ def _upsert_toml_mcp_config(
 
     existing: dict[str, Any] = {}
     if config_path.exists():
-        existing = tomllib.loads(config_path.read_text())
+        existing = tomllib.loads(config_path.read_text(encoding="utf-8"))
 
     already_has = "dataface" in existing.get(servers_key, {})
     if already_has and not force:
@@ -166,5 +166,5 @@ def _upsert_toml_mcp_config(
 
     existing.setdefault(servers_key, {})
     existing[servers_key]["dataface"] = server_entry
-    config_path.write_text(tomli_w.dumps(existing))
+    config_path.write_text(tomli_w.dumps(existing), encoding="utf-8")
     return f"  {'Updated' if already_has else 'Added dataface to'} {config_path}"

dataface/agent_api/pack.py

@@ -291,7 +291,8 @@ def _write_face(path: Path, face_dict: dict) -> None:
     path.write_text(
         yaml.dump(
             face_dict, default_flow_style=False, sort_keys=False, allow_unicode=True
-        )
+        ),
+        encoding="utf-8",
     )
 
 
@@ -417,7 +418,8 @@ def apply_proposal(
         # Write a minimal partial YAML comment block
         partial_path.write_text(
             f"# Shared partial: {partial_filename}\n"
-            f"# Add shared query fragments, variables, or chart definitions here.\n"
+            f"# Add shared query fragments, variables, or chart definitions here.\n",
+            encoding="utf-8",
         )
         result.created_files.append(rel)
 

dataface/agent_api/query.py

@@ -7,7 +7,7 @@ from pydantic import BaseModel, ConfigDict, Field
 
 from dataface.agent_api._paths import resolve_scoped_path
 from dataface.core.compile import compile_file
-from dataface.core.compile.models.query.compiled import SqlQuery
+from dataface.core.compile.models.query.normalized import SqlQuery
 from dataface.core.execute.adapters import AdapterRegistry
 from dataface.core.validate import normalize_data_for_json
 

dataface/agent_api/schema.py

@@ -646,7 +646,7 @@ def _project_uses_direct_file_queries(project_root: Path) -> bool:
 
     for dashboard in list_dashboards(directory=project_root, recursive=True).dashboards:
         try:
-            content = dashboard.absolute_path.read_text()
+            content = dashboard.absolute_path.read_text(encoding="utf-8")
         except OSError:
             continue
         if (

dataface/agent_api/search.py

@@ -124,7 +124,7 @@ def _build_index(directory: Path) -> list[dict[str, Any]]:
     for dash in listing.dashboards:
         abs_path = dash.absolute_path
         try:
-            content = yaml.safe_load(abs_path.read_text())
+            content = yaml.safe_load(abs_path.read_text(encoding="utf-8"))
         except (yaml.YAMLError, OSError):
             continue
 

dataface/agent_api/surface_aliases.yaml

@@ -39,7 +39,7 @@ render_dashboard:
 
 query_face:
   tool: "query_face"
-  dft: "dft query --face"
+  dft: "dft query --in"
 
 describe_query:
   tool: "describe_query"

dataface/ai/external_mcp.py

@@ -234,7 +234,7 @@ def _parse_json_config(
     if not path.exists():
         return
     try:
-        data = json.loads(path.read_text())
+        data = json.loads(path.read_text(encoding="utf-8"))
     except json.JSONDecodeError:
         _console.print(f"[yellow]MCP: {path} has invalid JSON; skipping[/yellow]")
         return
@@ -271,7 +271,7 @@ def _parse_toml_config(
     if not path.exists():
         return
     try:
-        data = tomllib.loads(path.read_text())
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
     except (tomllib.TOMLDecodeError, OSError) as exc:
         _console.print(
             f"[yellow]MCP: {path} has invalid TOML: {exc}; skipping[/yellow]"

dataface/ai/memories.py

@@ -17,7 +17,7 @@ def load_memories(base_dir: Path | None = None) -> list[dict[str, Any]]:
     if not path.exists():
         return []
 
-    payload = yaml.safe_load(path.read_text()) or {}
+    payload = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
     rows = payload.get("memories") if isinstance(payload, dict) else None
     if not isinstance(rows, list):
         return []