dataface 0.1.6.dev360__py3-none-any.whl → 0.1.6.dev476__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -253,6 +253,32 @@ Rules:
 - Each alias must be unique across the project — two faces claiming the same alias is a startup error.
 - Aliasing a generated system route (data or inspector view) is allowed: the redirect takes precedence, letting you override what that URL serves.
 
+#### Parameterized aliases (capture a path segment into a variable)
+
+An alias may contain `<name>` capture segments.  A request matching the pattern
+302-redirects to the face's canonical URL with each captured segment appended as a
+query param of the same name — which the face then reads as its variable.  This
+gives a single detail face a clean per-entity URL:
+
+```yaml
+# faces/milestone.yml  (canonical URL: /milestone)
+aliases:
+  - /milestones/<name>
+variables:
+  name: { input: select, options: { query: milestone_options, column: slug } }
+```
+
+Now `/milestones/m3-public-launch` redirects to `/milestone/?name=m3-public-launch`,
+and `milestone.yml` renders with `name` bound to `m3-public-launch`.
+
+- Capture names use the same grammar as built-in routes: `<name>` matches exactly
+  one non-empty path segment (no `/`).  Use a capture name that matches the
+  variable you want it to fill.
+- A real face file always wins over a pattern alias, so `/milestones/` (the list
+  face) and `/milestones/<name>` (the detail redirect) coexist without conflict.
+- Plain aliases (no `<...>`) redirect as before; only aliases with a capture are
+  treated as patterns.
+
 There are two ways to override a data/inspector route for a given path:
 - **Face file at that path** — create `faces/data/warehouse/schema/table.yml` and the server renders it directly (no redirect).
 - **`aliases:` entry** — any face can declare `/data/…/` as an alias; the server issues a 302 to the declaring face's canonical URL.

dataface/agent_api/dashboards.py

@@ -244,7 +244,7 @@ def get_dashboard(
             ],
         )
 
-    result = compile_file(file_path, project=project)
+    result = compile_file(project.file_for_path(file_path), project=project)
     return CompiledDashboard(
         success=result.success,
         dashboard=result.face if result.success else None,

dataface/agent_api/describe.py

@@ -224,7 +224,7 @@ def describe_face(path: Path, *, project: Project) -> DescribeFaceResult:
         )
 
     try:
-        result = compile_file(resolved, project=project)
+        result = compile_file(project.file_for_path(resolved), project=project)
     except OSError as exc:
         return DescribeFaceResult(
             success=False,
@@ -350,13 +350,15 @@ def _describe_one_path(
     if not resolved.is_dir():
         return [describe_face(resolved, project=project)]
 
-    template_dirs = {m.parent for m in resolved.glob(f"**/{INSPECT_TEMPLATE_MANIFEST}")}
-    yaml_files = sorted(
-        f
-        for f in (list(resolved.glob("**/*.yml")) + list(resolved.glob("**/*.yaml")))
-        if not f.name.startswith("_") and f.parent not in template_dirs
+    under = str(resolved.relative_to(project.root))
+    faces = sorted(
+        project.root / pf.relpath
+        for pf in project.iter_faces(under=under, recursive=True)
+        if pf.is_yaml
+        and not pf.is_private
+        and not pf.sibling(INSPECT_TEMPLATE_MANIFEST).exists()
     )
-    if not yaml_files:
+    if not faces:
         return [
             DescribeFaceResult(
                 success=False,
@@ -369,4 +371,4 @@ def _describe_one_path(
                 ],
             )
         ]
-    return [describe_face(f, project=project) for f in yaml_files]
+    return [describe_face(f, project=project) for f in faces]

dataface/agent_api/docs/yaml-reference.md

@@ -287,6 +287,7 @@ Authored patch for KPI (key performance indicator) charts.
 | `label` | str | ✓ | KPI label rendered above the headline value. |
 | `support` | [KpiSupportConfig](#kpisupportconfig) | ✓ | Optional support line beneath the KPI value. |
 | `style` | [KpiChartStyle](#kpichartstyle) | ✓ | Chart-local style overrides. |
+| `background` | str \| dict[str, Any] | ✓ | Gradient background channel — {column, scale} shape. Paints the card background by the value's position in the scale. See channel.py parse_style_channel for the full grammar. |
 
 <a id="tablechart"></a>
 ## TableChart
@@ -848,6 +849,7 @@ Authored overlay for TableChartStyle. Table chart style overrides layered on top
 | `more_rows` | [TableEdgeStyle](#tableedgestyle) | ✓ | Style for the 'more rows' edge-case indicator. |
 | `empty_state` | [TableEdgeStyle](#tableedgestyle) | ✓ | Style for the empty-state (no data) indicator. |
 | `spark` | [SparkStyle](#sparkstyle) | ✓ | Inline sparkline defaults for table cells. |
+| `transpose` | bool | ✓ | When True, render a single wide data row as N (label, value) rows — one per column. Raises ChartDataError when data has more than one row. Used for Looker single-value summary tiles with multiple measures. |
 | `text_baseline_offset` | float | ✓ | Vertical offset to align SVG text baseline with cell grid in pixels. |
 | `title_baseline_offset` | float | ✓ | Vertical offset to align SVG title baseline in pixels. |
 | `title_subtitle_gap` | float | ✓ | Gap between table title and subtitle lines in pixels. |
@@ -1348,6 +1350,7 @@ Authored overlay for LegendStyle.
 | `title` | [LegendElementStyle](#legendelementstyle) | ✓ | Legend title style. |
 | `visible` | bool | ✓ | Show the legend. None = legend visible; False = explicitly suppressed. |
 | `interactive_legend` | bool | ✓ | Emit a dft_legend point-selection param for single-click series toggle. |
+| `symbol_limit` | int | ✓ | Maximum number of legend entries to display; maps to VL symbolLimit. None uses Vega-Lite's default (no cap). Set to a positive integer to prevent legend overflow on high-cardinality series. |
 
 <a id="tooltipstyle"></a>
 ## TooltipStyle
@@ -1569,6 +1572,7 @@ Authored overlay for TableColumnsStyle.
 | `default_width` | float | ✓ | Default column width in pixels. |
 | `cell_padding` | float | ✓ | Horizontal padding inside table cells in pixels. |
 | `width_similarity_threshold` | float | ✓ | Auto-width columns whose min/max ratio &gt;= this threshold are snapped to a shared width before budget allocation. 1.0 disables clustering; 0.0 forces all auto-columns to equal width. |
+| `content_headroom` | float | ✓ | Fractional breathing room added above the raw p95 column demand when pinning compact columns in mixed (compact + text) tables.  0.10 means each compact column is pinned at 10 % above its measured demand; the extra width is funded by the text-column budget.  Has no effect on all-compact tables (proportional scaling already fills the budget).  0.0 disables headroom. |
 
 <a id="tableheaderstyle"></a>
 ## TableHeaderStyle
@@ -2209,6 +2213,7 @@ Authored overlay for BarMarkStyle. Bar mark geometry and stroke. Chart-level bar
 | `padding` | float | ✓ | Padding around bar marks in pixels. |
 | `size` | float | ✓ | Bar width in pixels (fixed-width mode). |
 | `band_width` | float | ✓ | Bar width as a fraction of the band step (0–1). |
+| `labels` | [BarLabelsStyle](#barlabelsstyle) | ✓ | Value label style for bar marks. |
 
 <a id="textmarkstyle"></a>
 ## TextMarkStyle
@@ -2228,6 +2233,7 @@ Authored overlay for LineMarkStyle. Line mark stroke, interpolation, and halo. P
 | `stroke` | [StrokeStyle](#strokestyle) | ✓ | Line stroke style. |
 | `curve` | str | ✓ | Line interpolation curve (e.g. 'linear', 'monotone'). |
 | `halo_multiplier` | float | ✓ | Halo stroke width multiplier relative to stroke.width; 0 disables the halo. |
+| `labels` | [PointLabelsStyle](#pointlabelsstyle) | ✓ | Value label style for line marks. |
 
 <a id="pointmarkstyle"></a>
 ## PointMarkStyle
@@ -2242,6 +2248,7 @@ Authored overlay for PointMarkStyle. Point mark style (data-point markers on lin
 | `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. |
+| `labels` | [PointLabelsStyle](#pointlabelsstyle) | ✓ | Value label style for point marks. |
 
 <a id="rulemarkstyle"></a>
 ## RuleMarkStyle
@@ -2522,6 +2529,19 @@ Authored overlay for DataTableRowPaddingStyle.
 | `vertical` | float | ✓ | Vertical (top/bottom) padding inside data_table rows in pixels. |
 | `horizontal` | float | ✓ | Horizontal (left/right) padding inside data_table rows in pixels. |
 
+<a id="barlabelsstyle"></a>
+## BarLabelsStyle
+Authored overlay for BarLabelsStyle. Bar mark value-label config. Extends MarkLabelsStyle with bar-specific positions.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show numeric value labels on each mark; False by default. |
+| `format` | str | ✓ | Number format string for value labels. None inherits from style.charts.axis_quantitative.format at render time (the same format string used for measure-axis tick labels, e.g. '~s'). |
+| `dx` | int | ✓ | Horizontal pixel offset for value labels; overrides the position default. |
+| `dy` | int | ✓ | Vertical pixel offset for value labels; overrides the position default. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Value label font style (color, size, family, etc.). |
+| `position` | enum: "top", "inside_top", "middle" | ✓ | Label position relative to the bar. 'top' places labels above the bar top (outside). 'inside_top' places labels just inside the top edge. 'middle' centers labels vertically in the bar. |
+
 <a id="strokestyle"></a>
 ## StrokeStyle
 Authored overlay for StrokeStyle. Stroke appearance sub-block shared across mark families.
@@ -2534,6 +2554,19 @@ 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="pointlabelsstyle"></a>
+## PointLabelsStyle
+Authored overlay for PointLabelsStyle. Point/line mark value-label config. Used by both LineMarkStyle and PointMarkStyle.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `visible` | bool | ✓ | Show numeric value labels on each mark; False by default. |
+| `format` | str | ✓ | Number format string for value labels. None inherits from style.charts.axis_quantitative.format at render time (the same format string used for measure-axis tick labels, e.g. '~s'). |
+| `dx` | int | ✓ | Horizontal pixel offset for value labels; overrides the position default. |
+| `dy` | int | ✓ | Vertical pixel offset for value labels; overrides the position default. |
+| `font` | [FontStyle](#fontstyle) | ✓ | Value label font style (color, size, family, etc.). |
+| `position` | enum: "top", "bottom", "left", "right", "middle" | ✓ | Label position relative to the point. 'top' places labels above the point. 'bottom' places labels below. 'left' to the left. 'right' to the right. 'middle' centers on the point. |
+
 <a id="fontcolorstrokestyle"></a>
 ## FontColorStrokeStyle
 Authored overlay for FontColorStrokeStyle. Stroke for tick/rule marks whose color defaults to the root font color.

dataface/agent_api/project_session.py

@@ -35,7 +35,7 @@ from dataface.core.execute.adapters.adapter_registry import (
     AdapterRegistry,
     build_adapter_registry,
 )
-from dataface.core.execute.duckdb_cache import DuckDBCache
+from dataface.core.execute.cache_backend import QueryResultCache
 from dataface.core.execute.observability import WarehouseObserver
 from dataface.core.inspect.query_validator import (
     QueryDiagnostic,
@@ -68,7 +68,7 @@ class ProjectSession:
     """
 
     project: Project
-    cache: DuckDBCache | None
+    cache: QueryResultCache | None
     _owns_registry: bool
     _read_only: bool
     _connection_string: str | None
@@ -82,7 +82,7 @@ class ProjectSession:
     def __init__(
         self,
         project: Project,
-        cache: DuckDBCache | None = None,
+        cache: QueryResultCache | None = None,
         adapter_registry: AdapterRegistry | None = None,
         read_only: bool = True,
         observers: list[WarehouseObserver] | None = None,
@@ -110,7 +110,7 @@ class ProjectSession:
         cls,
         project_dir: Path | str,
         *,
-        cache: DuckDBCache | None = None,
+        cache: QueryResultCache | None = None,
         read_only: bool = True,
         connection_string: str | None = None,
         dialect: str = "duckdb",
@@ -150,7 +150,7 @@ class ProjectSession:
         cls,
         project: Project,
         *,
-        cache: DuckDBCache | None = None,
+        cache: QueryResultCache | None = None,
         read_only: bool = True,
         connection_string: str | None = None,
         dialect: str = "duckdb",
@@ -183,7 +183,7 @@ class ProjectSession:
         face_file: Path | str,
         *,
         read_only: bool = True,
-        cache: DuckDBCache | None = None,
+        cache: QueryResultCache | None = None,
     ) -> Self:
         """Open a ProjectSession rooted at the project directory discovered upward from face_file."""
         resolved = Path(face_file).resolve()

dataface/agent_api/query.py

@@ -47,7 +47,7 @@ def lookup_face_query_sql(
             success=False, errors=[f"File not found: {file_path}"]
         )
 
-    compile_result = compile_file(file_path, project=project)
+    compile_result = compile_file(project.file_for_path(file_path), project=project)
     if not compile_result.success:
         return FaceQueryLookupResult(
             success=False, errors=[e.message for e in compile_result.errors]
@@ -275,7 +275,7 @@ def query_face(
         hint = no_project_hint(project.root)
         return _fail(name, file_path, [f"File not found: {file_path}{hint}"])
 
-    compile_result = compile_file(file_path, project=project)
+    compile_result = compile_file(project.file_for_path(file_path), project=project)
     if not compile_result.success:
         return _fail(name, file_path, [e.message for e in compile_result.errors])
 

dataface/agent_api/render_face.py

@@ -13,8 +13,8 @@ from dataface.core.compile.markdown import (
     is_markdown_face,
     markdown_to_yaml,
 )
-from dataface.core.execute.duckdb_cache import DuckDBCache
-from dataface.core.project import Project
+from dataface.core.execute.cache_backend import QueryResultCache
+from dataface.core.project import Project, ProjectFile
 from dataface.core.render.face_api import compile_and_render
 
 
@@ -26,7 +26,7 @@ def render_face(
     project: Project | None = None,
     variables: dict[str, str] | None = None,
     use_cache: bool = True,
-    cache: DuckDBCache | None = None,
+    cache: QueryResultCache | None = None,
     **options: Any,
 ) -> str | bytes:
     """Render a Dataface face file (.yml or .md) to embeddable output.
@@ -70,7 +70,15 @@ def render_face(
         project_session = ProjectSession.from_face(face_file, cache=cache)
     try:
         p = project_session.project
-        base_file = p.file_for_path(face_file)
+        # The face may live outside an explicitly-supplied project root — e.g.
+        # the looker_migrate eval renders faces under evals/runs/ against a
+        # project rooted at runtime/ for its sources/schema. Such a face has no
+        # project-relative handle; nested sub-file refs are unsupported in that
+        # mode (relative reads still resolve via face_dir below).
+        try:
+            base_file: ProjectFile | None = p.file_for_path(face_file)
+        except ValueError:
+            base_file = None
         return compile_and_render(
             yaml_content,
             p,

dataface/agent_api/validate.py

@@ -110,13 +110,15 @@ def _validate_one_path(
     if not resolved.is_dir():
         return [validate(resolved, project=project)]
 
-    template_dirs = {m.parent for m in resolved.glob(f"**/{INSPECT_TEMPLATE_MANIFEST}")}
-    yaml_files = sorted(
-        f
-        for f in (list(resolved.glob("**/*.yml")) + list(resolved.glob("**/*.yaml")))
-        if not f.name.startswith("_") and f.parent not in template_dirs
+    under = str(resolved.relative_to(project.root))
+    faces = sorted(
+        project.root / pf.relpath
+        for pf in project.iter_faces(under=under, recursive=True)
+        if pf.is_yaml
+        and not pf.is_private
+        and not pf.sibling(INSPECT_TEMPLATE_MANIFEST).exists()
     )
-    if not yaml_files:
+    if not faces:
         return [
             ValidateResult(
                 success=False,
@@ -129,7 +131,7 @@ def _validate_one_path(
                 ],
             )
         ]
-    return [validate(f, project=project) for f in yaml_files]
+    return [validate(f, project=project) for f in faces]
 
 
 def validate(path: Path, *, project: Project) -> ValidateResult:
@@ -163,7 +165,7 @@ def validate(path: Path, *, project: Project) -> ValidateResult:
         )
 
     try:
-        result = compile_file(resolved, project=project)
+        result = compile_file(project.file_for_path(resolved), project=project)
     except OSError as exc:
         return ValidateResult(
             success=False,

dataface/ai/agent.py

@@ -120,7 +120,7 @@ DASHBOARD_PROFILE = AgentProfile(
 
 
 def run_agent(
-    prompt: str,
+    prompt: str | list[dict[str, Any]],
     *,
     client: LLMClient,
     context: DatafaceAIContext,

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

@@ -129,6 +129,8 @@ Skip this step when you are previewing ephemerally — see "Previewing vs. savin
 
 Fix any errors `{{ s_validate_dashboard }}` reports, then re-run until it passes.
 
+**YAML style:** write block style — one key per line. Avoid JSON-like inline flow maps (`{ type: bar, x: month }`); they read and diff worse than indented blocks. Inline arrays (`y: [revenue, cost]`) are fine.
+
 ## Parameterized Queries — Use From the Start
 
 Use `{{ variable_name }}` syntax for any configurable values, even during exploration:

dataface/core/compile/__init__.py

@@ -6,7 +6,7 @@ ready for execution and rendering.
 
 Entry Points:
     - compile(yaml_content: str) -> CompileResult
-    - compile_file(file_path: Path, *, project: Project) -> CompileResult
+    - compile_file(face_file: ProjectFile, *, project: Project) -> CompileResult
 
 Outputs:
     - Face: Fully normalized face with all references resolved

dataface/core/compile/channel.py

@@ -130,7 +130,7 @@ def validate_channel_fields(
             )
 
 
-_COLOR_CHANNELS = frozenset({"color"})
+_COLOR_CHANNELS = frozenset({"color", "background"})
 _NUMERIC_CHANNELS: frozenset[str] = frozenset()
 
 
@@ -165,8 +165,10 @@ def normalize_chart_channels(
 ) -> dict[str, ResolvedStyleChannel]:
     """Parse and validate chart-level style channels.
 
-    Only ``color`` is a data channel at chart root. background/opacity/stroke
-    were removed as data channels (they are paint fields, not data bindings).
+    ``color`` is a data channel at chart root for all chart types.
+    ``background`` is a data channel at chart root for KPI charts only
+    (gradient background painted by value position in scale).
+    Other paint fields (opacity, stroke) are not data channels.
 
     ``style_color``: when a ``StyleColorConfig`` with a scale is provided, the
     series color channel is upgraded to gradient mode.  A plain string value
@@ -182,6 +184,11 @@ def normalize_chart_channels(
     if color_raw is not None:
         channels["color"] = parse_style_channel(color_raw, "color")
 
+    if chart_type == "kpi":
+        background_raw = chart.background
+        if background_raw is not None:
+            channels["background"] = parse_style_channel(background_raw, "background")
+
     # Upgrade series channel to gradient when style.color carries a scale.
     if isinstance(style_color, StyleColorConfig):
         if "color" not in channels:

dataface/core/compile/compiler.py

@@ -7,7 +7,7 @@ ready for execution and rendering.
 Entry Points:
     - compile(yaml_content: str) -> CompileResult
     - compile_authored_face(authored: AuthoredFace) -> CompileResult
-    - compile_file(file_path: Path, *, project: Project) -> CompileResult
+    - compile_file(face_file: ProjectFile, *, project: Project) -> CompileResult
 
 This is the main orchestrator for compilation. It:
 1. Parses YAML to AuthoredFace (parser.py)
@@ -32,7 +32,6 @@ from __future__ import annotations
 
 import logging
 from dataclasses import dataclass, field
-from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 import yaml
@@ -462,7 +461,7 @@ def validate_compiled_queries(
 
 
 def compile_file(
-    file_path: str | Path,
+    face_file: ProjectFile,
     apply_meta: bool = True,
     *,
     project: Project,
@@ -474,34 +473,30 @@ def compile_file(
     applies meta.yaml cascading configuration from parent directories.
 
     Args:
-        file_path: Path to YAML file
+        face_file: ProjectFile handle for the YAML (or Markdown) face file
         apply_meta: If True, resolve and apply meta.yaml chain (default: True)
         project: Project for meta resolution and source loading
-        markdown_metadata_table: When True and file_path is a .md, prepend
+        markdown_metadata_table: When True and face_file is a .md, prepend
             non-face frontmatter keys as a metadata table before the body.
 
     Returns:
         CompileResult with compiled face or errors
 
-    Raises:
-        FileNotFoundError: If file doesn't exist
-
     Example:
-        >>> result = compile_file(Path("face.yml"), project=project)
+        >>> result = compile_file(project.file("face.yml"), project=project)
         >>> if result.success:
         ...     print(result.face.title)
     """
-    file_path = Path(file_path)
-
-    if not file_path.exists():
+    if not face_file.exists():
         return CompileResult(
-            errors=[CompilationError(f"File not found: {file_path}").to_structured()]
+            errors=[
+                CompilationError(f"File not found: {face_file.relpath}").to_structured()
+            ]
         )
 
-    face_file = project.file_for_path(file_path)
-
     # Markdown report files: translate to YAML before compiling.
-    # is_markdown_face stays path-based (upward directory walk, out of scope).
+    # is_markdown_face and resolve_meta_chain stay path-based (disk-coupled helpers,
+    # out of scope for this task); reconstruct the absolute path for them.
     from dataface.core.compile.markdown import (
         MARKDOWN_NOT_FACE_MESSAGE,
         MARKDOWN_SUFFIXES,
@@ -509,14 +504,16 @@ def compile_file(
         markdown_to_yaml,
     )
 
-    if file_path.suffix.lower() in MARKDOWN_SUFFIXES:
-        if not is_markdown_face(file_path):
+    abs_path = project.root / face_file.relpath
+
+    if abs_path.suffix.lower() in MARKDOWN_SUFFIXES:
+        if not is_markdown_face(abs_path):
             return CompileResult(
                 errors=[CompilationError(MARKDOWN_NOT_FACE_MESSAGE).to_structured()]
             )
 
         try:
-            raw_text = file_path.read_text(encoding="utf-8")
+            raw_text = face_file.read_text()
             yaml_content = markdown_to_yaml(
                 raw_text, metadata_table=markdown_metadata_table
             )
@@ -532,8 +529,6 @@ def compile_file(
                 errors=[CompilationError(f"Failed to read file: {e}").to_structured()]
             )
 
-    file_str = str(file_path)
-
     # Parse the face text to a mapping. Meta is deep-merged under it (when
     # enabled) and the merged mapping is validated once as an AuthoredFace —
     # no YAML round-trip. A malformed meta.yaml raises CompilationError immediately.
@@ -541,7 +536,7 @@ def compile_file(
     try:
         face_data = load_yaml_mapping(yaml_content)
         if apply_meta:
-            meta_dict, lint = resolve_meta_chain(file_path, root_path=project.root)
+            meta_dict, lint = resolve_meta_chain(abs_path, root_path=project.root)
             if lint.ignore or lint.ignore_queries:
                 meta_lint = lint
             face_data = apply_meta_to_face(meta_dict, face_data)
@@ -549,12 +544,14 @@ def compile_file(
     except ParseError as e:
         return CompileResult(
             errors=[
-                _stamp_error_file(err, file_str)
+                _stamp_error_file(err, face_file.relpath)
                 for err in _parse_error_to_structured(e, yaml_content)
             ]
         )
     except CompilationError as e:
-        return CompileResult(errors=[_stamp_error_file(e.to_structured(), file_str)])
+        return CompileResult(
+            errors=[_stamp_error_file(e.to_structured(), face_file.relpath)]
+        )
 
     result = _compile_with_text(
         face,
@@ -566,7 +563,7 @@ def compile_file(
     # Stamp file path and add validate next_command on each compile error so
     # UI surfaces and CLI can surface "dft validate <file>" without re-deriving the path.
     if result.errors:
-        result.errors = [_stamp_error_file(e, file_str) for e in result.errors]
+        result.errors = [_stamp_error_file(e, face_file.relpath) for e in result.errors]
     return result
 
 

dataface/core/compile/data_table_attachment.py

@@ -40,6 +40,7 @@ from dataface.core.compile.models.chart.authored import (
     ChartDataTablePerSeries,
     ChartDataTableSource,
 )
+from dataface.core.compile.models.chart.resolved import FormatState
 from dataface.core.compile.models.style.resolved import (
     ResolvedChartsStyle,
     deep_merge,
@@ -274,7 +275,7 @@ def _inter_row_rule_y_pixel(
 
 def _vl_format_calc(
     source: str,
-    format_spec: str | None,
+    format_spec: FormatState,
     as_name: str,
     formats: dict[str, str] | None = None,
 ) -> dict[str, Any]:
@@ -417,6 +418,7 @@ def _row_text_layer(
     style: DataTableStyle,
     charts_style: ResolvedChartsStyle,
     spec_height: float,
+    value_format: FormatState = None,
     sampling_step: int = 1,
     dx: float | None = None,
     label_period_filter_expr: str | None = None,
@@ -457,12 +459,7 @@ def _row_text_layer(
         # Sampling after period filter: thin further if still over the cap.
         if sampling_step > 1:
             transforms.extend(_sampling_transforms(x_field, sampling_step))
-        if entry.format is not None:
-            transforms.append(
-                _vl_format_calc(agg_name, entry.format, cell_name, formats)
-            )
-        else:
-            transforms.append(_vl_format_calc(agg_name, None, cell_name, formats))
+        transforms.append(_vl_format_calc(agg_name, value_format, cell_name, formats))
     else:
         # Source entry: G1 guarantees 1 row per x.
         # Period filter before sampling: thin to label-period openers first.
@@ -470,18 +467,21 @@ def _row_text_layer(
             transforms.append({"filter": label_period_filter_expr})
         if sampling_step > 1:
             transforms.extend(_sampling_transforms(x_field, sampling_step))
-        if entry.format is not None:
-            transforms.append(
-                _vl_format_calc(entry.source, entry.format, cell_name, formats)
-            )
-        else:
-            transforms.append(_vl_format_calc(entry.source, None, cell_name, formats))
+        transforms.append(
+            _vl_format_calc(entry.source, value_format, cell_name, formats)
+        )
 
     y_pixel = _row_y_pixel(index, style, charts_style, spec_height)
     encoding: dict[str, Any] = {
         "x": _shared_x_encoding(parent_x_enc),
         "y": {"value": y_pixel},
         "text": {"field": cell_name},
+        # Opt out of inherited color encoding. Without this, VL sees own data
+        # that lacks the series field after aggregation (groupby omits the color
+        # field), adds null to the categorical domain, and null sorts first —
+        # consuming palette[0] and shifting every series mark one slot up (the
+        # dark-companion / endpoint-label off-by-one).
+        "color": None,
     }
     layer: dict[str, Any] = {
         "mark": _text_mark_props(style, dx=dx),
@@ -504,6 +504,7 @@ def _per_series_row_layers(
     charts_style: ResolvedChartsStyle,
     spec_height: float,
     spec_width: float | None,
+    value_format: FormatState = None,
     sampling_step: int = 1,
     dx: float | None = None,
     label_period_filter_expr: str | None = None,
@@ -569,7 +570,7 @@ def _per_series_row_layers(
                 _sampling_transforms(parent_x_enc["field"], sampling_step)
             )
         bm_transforms.append(
-            _vl_format_calc(entry.per_series, entry.format, bm_cell_name, formats)
+            _vl_format_calc(entry.per_series, value_format, bm_cell_name, formats)
         )
         bm_y_pixel = _row_y_pixel(row_idx, style, charts_style, spec_height)
         bm_cell_layer: dict[str, Any] = {
@@ -645,7 +646,7 @@ def _per_series_row_layers(
             transforms.append({"filter": label_period_filter_expr})
         if sampling_step > 1:
             transforms.extend(_sampling_transforms(x_field, sampling_step))
-        transforms.append(_vl_format_calc(agg_name, entry.format, cell_name, formats))
+        transforms.append(_vl_format_calc(agg_name, value_format, cell_name, formats))
 
         y_pixel = _row_y_pixel(row_idx, style, charts_style, spec_height)
         cell_layer: dict[str, Any] = {
@@ -975,6 +976,7 @@ def attach_data_table(
     series_palette: list[str] | None = None,
     label_period_filter_expr: str | None = None,
     axis_y_orient: Literal["left", "right"],
+    entry_formats: list[FormatState] | None = None,
     formats: dict[str, str] | None = None,
 ) -> dict[str, Any]:
     """Append attached-data-table layers to a Vega-Lite chart spec.
@@ -1160,6 +1162,7 @@ def attach_data_table(
     visual_row_idx = 0
     for i, entry in enumerate(data_table.entries):
         row_dx = entry_dx[i] if entry_dx is not None else None
+        row_format = entry_formats[i] if entry_formats is not None else entry.format
         if isinstance(entry, ChartDataTablePerSeries):
             if entry.by_measure:
                 # by_measure: one row per entry, no series expansion needed.
@@ -1174,11 +1177,13 @@ def attach_data_table(
                     charts_style=charts_style,
                     spec_height=spec_height,
                     spec_width=spec_width,
+                    value_format=row_format,
                     sampling_step=sampling_step,
                     dx=row_dx,
                     label_period_filter_expr=label_period_filter_expr,
                     axis_y_orient=axis_y_orient,
                     label_limit=_label_stub_limit,
+                    formats=formats,
                 )
                 layers.extend(bm_layers)
                 if style.row.rule.width > 0 and visual_row_idx < n_visual_rows - 1:
@@ -1211,6 +1216,7 @@ def attach_data_table(
                     charts_style=charts_style,
                     spec_height=spec_height,
                     spec_width=spec_width,
+                    value_format=row_format,
                     sampling_step=sampling_step,
                     dx=row_dx,
                     label_period_filter_expr=label_period_filter_expr,
@@ -1250,6 +1256,7 @@ def attach_data_table(
                 style=style,
                 charts_style=charts_style,
                 spec_height=spec_height,
+                value_format=row_format,
                 sampling_step=sampling_step,
                 dx=row_dx,
                 label_period_filter_expr=label_period_filter_expr,