dataface 0.1.5.dev322__py3-none-any.whl → 0.1.5.dev384__py3-none-any.whl

d3_format/format.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 import math
 from collections.abc import Callable
 from decimal import ROUND_HALF_UP, Decimal
+from typing import overload
 
 from d3_format.spec import FormatSpec, parse
 
@@ -520,6 +521,14 @@ def _apply_spec(spec: FormatSpec, v: float | int | Decimal) -> str:
     return _assemble(spec, sign_char, body, suffix)
 
 
+@overload
+def format(spec_str: str) -> Callable[[float | int | Decimal], str]: ...  # noqa: A001
+
+
+@overload
+def format(spec_str: str, value: float | int | Decimal) -> str: ...  # noqa: A001
+
+
 def format(  # noqa: A001
     spec_str: str,
     value: float | int | Decimal | None = None,

dataface/DATAFACE_SYNTAX.md

@@ -427,6 +427,8 @@ WHERE {{ filter('plan', plans) }}
 
 The `filter()` macro handles `select` (single value → `=`) and `multiselect` (list → `IN (...)`) automatically and quotes all string literals correctly.
 
+Select and multiselect controls render only the options the face author provides. Dataface does not add an "All" option; author a real sentinel option and matching SQL/Jinja explicitly if a dashboard needs one.
+
 ### Inline query in a chart
 
 A chart can carry its own one-off query instead of referencing a named one. Three equivalent forms:
@@ -672,6 +674,7 @@ lookup: state
 value: revenue
 
 # map — generic choropleth (alias for geoshape with named source)
+# world-countries/world-50m join on numeric TopoJSON ids such as 840, not ISO alpha codes.
 type: map
 geo_source: us-states
 lookup: state

dataface/agent_api/docs/_loader.py

@@ -58,7 +58,7 @@ class DocsSearchHit(BaseModel):
 
 
 class DocsArgs(BaseModel):
-    """Input model for agent_api.docs — drives MCP inputSchema."""
+    """Browse the Dataface YAML reference offline. Modes: no args = topic index (slug + one-line description per H2), topic='<slug>' = one section, topic='all' = whole reference unsliced, search='<query>' = substring search across topics. Use this before writing YAML to learn field names, valid values, and examples. Call with no args first to see the available topics."""
 
     topic: str | None = Field(
         None,

dataface/agent_api/docs/yaml-reference.md

@@ -1457,8 +1457,8 @@ Authored overlay for BarChartMarksStyle. Bar-family mark overrides. Only bar and
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `bar` | [BarMarkStyle](#barmarkstyle) | ✓ | Bar mark overrides for bar charts; None inherits global. |
-| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides for bar endpoint labels; None inherits global. |
+| `bar` | [BarMarkStyle](#barmarkstyle) | ✓ | Bar mark overrides for bar charts; inherits from global. |
+| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides for bar endpoint labels; inherits from global. |
 
 <a id="linechartmarksstyle"></a>
 ## LineChartMarksStyle
@@ -1466,9 +1466,9 @@ Authored overlay for LineChartMarksStyle. Line-family mark overrides.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `line` | [LineMarkStyle](#linemarkstyle) | ✓ | Line mark overrides; None inherits global. |
-| `point` | [PointMarkStyle](#pointmarkstyle) | ✓ | Point mark overrides; None inherits global. |
-| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides; None inherits global. |
+| `line` | [LineMarkStyle](#linemarkstyle) | ✓ | Line mark overrides; inherits from global. |
+| `point` | [PointMarkStyle](#pointmarkstyle) | ✓ | Point mark overrides; inherits from global. |
+| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides; inherits from global. |
 | `rule` | [RuleMarkStyle](#rulemarkstyle) | ✓ | Rule mark overrides; None inherits global. |
 
 <a id="areachartmarksstyle"></a>
@@ -1477,10 +1477,10 @@ Authored overlay for AreaChartMarksStyle. Area-family mark overrides.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `area` | [AreaMarkStyle](#areamarkstyle) | ✓ | Area mark overrides; None inherits global. |
-| `line` | [LineMarkStyle](#linemarkstyle) | ✓ | Top-edge line mark overrides; None inherits global. |
-| `point` | [PointMarkStyle](#pointmarkstyle) | ✓ | Point mark overrides; None inherits global. |
-| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides; None inherits global. |
+| `area` | [AreaMarkStyle](#areamarkstyle) | ✓ | Area mark overrides; inherits from global. |
+| `line` | [LineMarkStyle](#linemarkstyle) | ✓ | Top-edge line mark overrides; inherits from global. |
+| `point` | [PointMarkStyle](#pointmarkstyle) | ✓ | Point mark overrides; inherits from global. |
+| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides; inherits from global. |
 
 <a id="scatterchartmarksstyle"></a>
 ## ScatterChartMarksStyle
@@ -1488,8 +1488,8 @@ Authored overlay for ScatterChartMarksStyle. Scatter-family mark overrides.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `point` | [PointMarkStyle](#pointmarkstyle) | ✓ | Point mark overrides; None inherits global. |
-| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides; None inherits global. |
+| `point` | [PointMarkStyle](#pointmarkstyle) | ✓ | Point mark overrides; inherits from global. |
+| `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides; inherits from global. |
 
 <a id="heatmapchartmarksstyle"></a>
 ## HeatmapChartMarksStyle
@@ -1497,7 +1497,7 @@ Authored overlay for HeatmapChartMarksStyle. Heatmap-family mark overrides.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `rect` | [RectMarkStyle](#rectmarkstyle) | ✓ | Rect mark overrides; None inherits global. |
+| `rect` | [RectMarkStyle](#rectmarkstyle) | ✓ | Rect mark overrides; inherits from global. |
 | `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides; None inherits global. |
 
 <a id="totalstyle"></a>
@@ -1515,7 +1515,7 @@ Authored overlay for PieChartMarksStyle. Pie/donut-family mark overrides.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `slice` | [SliceMarkStyle](#slicemarkstyle) | ✓ | Slice mark overrides; None inherits global. |
+| `slice` | [SliceMarkStyle](#slicemarkstyle) | ✓ | Slice mark overrides; inherits from global. |
 | `text` | [TextMarkStyle](#textmarkstyle) | ✓ | Text mark overrides; None inherits global. |
 
 <a id="kpivaluestyle"></a>
@@ -1720,7 +1720,7 @@ Authored overlay for PointMapChartMarksStyle. Point map-family mark overrides.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `point` | [PointMarkStyle](#pointmarkstyle) | ✓ | Point mark overrides; None inherits global. |
+| `point` | [PointMarkStyle](#pointmarkstyle) | ✓ | Point mark overrides; inherits from global. |
 
 <a id="geoshapechartmarksstyle"></a>
 ## GeoshapeChartMarksStyle
@@ -1728,7 +1728,7 @@ Authored overlay for GeoshapeChartMarksStyle. Geoshape-family mark overrides.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `geoshape` | [GeoshapeMarkStyle](#geoshapemarkstyle) | ✓ | Geoshape mark overrides; None inherits global. |
+| `geoshape` | [GeoshapeMarkStyle](#geoshapemarkstyle) | ✓ | Geoshape mark overrides; inherits from global. |
 
 <a id="layeraxisystyle"></a>
 ## LayerAxisYStyle
@@ -2441,7 +2441,7 @@ Authored overlay for HistogramChartMarksStyle. Histogram-family mark overrides.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `bar` | [BarMarkStyle](#barmarkstyle) | ✓ | Bar mark overrides; None inherits global. |
+| `bar` | [BarMarkStyle](#barmarkstyle) | ✓ | Bar mark overrides; inherits from global. |
 | `rule` | [RuleMarkStyle](#rulemarkstyle) | ✓ | Rule mark overrides; None inherits global. |
 
 <a id="detailsarrowstyle"></a>

dataface/agent_api/mcp_install.py

@@ -126,9 +126,8 @@ def _upsert_mcp_config(
     existing: dict[str, Any] = {}
     if config_path.exists():
         try:
-            existing = json.loads(config_path.read_text(encoding="utf-8"))
-            if not isinstance(existing, dict):
-                existing = {}
+            loaded = json.loads(config_path.read_text(encoding="utf-8"))
+            existing = loaded if isinstance(loaded, dict) else {}
         except (json.JSONDecodeError, OSError):
             existing = {}
 

dataface/ai/mcp/server.py

@@ -178,14 +178,14 @@ def create_server(context: DatafaceAIContext) -> Any:
     def _uri(value: str) -> AnyUrl:
         return TypeAdapter(AnyUrl).validate_python(value)
 
-    @server.list_resources()
+    @server.list_resources()  # type: ignore[no-untyped-call]
     async def handle_list_resources() -> list[Resource]:
         return [
             Resource(uri=_uri(u), mimeType=m, name=n, description=d)
             for u, m, n, d in (*_BASE_RESOURCES, *_docs_topic_resources())
         ]
 
-    @server.list_resource_templates()
+    @server.list_resource_templates()  # type: ignore[no-untyped-call]
     async def handle_list_resource_templates() -> list[ResourceTemplate]:
         return [
             ResourceTemplate(
@@ -202,11 +202,11 @@ def create_server(context: DatafaceAIContext) -> Any:
             ),
         ]
 
-    @server.read_resource()
-    async def handle_read_resource(uri: str) -> str:
+    @server.read_resource()  # type: ignore[no-untyped-call]
+    async def handle_read_resource(uri: AnyUrl) -> str:
         return _read_resource_content(str(uri), context=context)
 
-    @server.list_tools()
+    @server.list_tools()  # type: ignore[no-untyped-call]
     async def handle_list_tools() -> list[Tool]:
         return [
             Tool(

dataface/ai/tool_schemas.py

@@ -14,6 +14,7 @@ from pydantic import BaseModel
 from dataface.agent_api.dashboards import RenderDashboardArgs
 from dataface.agent_api.describe import DescribeFaceArgs
 from dataface.agent_api.describe_query import DescribeQueryArgs
+from dataface.agent_api.docs import DocsArgs
 from dataface.agent_api.docs.warnings import GetWarningCodeArgs
 from dataface.agent_api.files import (
     EditFileArgs,
@@ -47,34 +48,7 @@ SCHEMA = _ai_tool("schema", SchemaArgs)
 SCHEMA_SEARCH = _ai_tool("schema_search", SchemaSearchArgs)
 SEARCH_DASHBOARDS = _ai_tool("search_dashboards", SearchDashboardsArgs)
 
-DOCS = {
-    "name": "docs",
-    "description": (
-        "Browse the Dataface YAML reference offline. "
-        "Modes: no args = topic index (slug + one-line description per H2), "
-        "topic='<slug>' = one section, topic='all' = whole reference unsliced, "
-        "search='<query>' = substring search across topics. "
-        "Use this before writing YAML to learn field names, valid values, "
-        "and examples. Call with no args first to see the available topics."
-    ),
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "topic": {
-                "type": "string",
-                "description": "Topic slug (e.g. 'face', 'charts', 'cheatsheet') or 'all' for the whole file. Omit for the topic index.",
-            },
-            "search": {
-                "type": "string",
-                "description": "Substring query — scans all H2 sections and returns ranked hits",
-            },
-            "limit": {
-                "type": "integer",
-                "description": "Max search hits to return (default 5, max 50)",
-            },
-        },
-    },
-}
+DOCS = _ai_tool("docs", DocsArgs)
 
 LIST_WARNING_CODES = {
     "name": "list_warning_codes",

dataface/ai/tools/__init__.py

@@ -20,6 +20,7 @@ from dataface.agent_api import (
     search as _search,
     skills as _skills,
 )
+from dataface.agent_api.query import ExecuteQueryArgs as _ExecuteQueryArgs
 from dataface.agent_api.validate import (
     ValidateDashboardArgs as _ValidateDashboardArgs,
     annotate_with_data_lint as _annotate_with_data_lint,
@@ -120,11 +121,12 @@ def _handle_render(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str, An
 
 
 def _handle_query(args: dict[str, Any], ctx: DatafaceAIContext) -> dict[str, Any]:
+    parsed = _ExecuteQueryArgs.model_validate(args)
     return _query.execute_query(
-        sql=args.get("sql", ""),
-        variables=args.get("variables"),
-        source=args.get("source"),
-        limit=args.get("limit", 50),
+        sql=parsed.sql,
+        variables=parsed.variables,
+        source=parsed.source,
+        limit=parsed.limit or 50,
         adapter_registry=ctx.project.adapter_registry,
     ).model_dump(mode="json", exclude_none=True)
 

dataface/cli/commands/serve.py

@@ -20,6 +20,7 @@ def serve_command(
     dialect: str | None = None,
     target: str | None = None,
     max_workers: int | None = None,
+    no_cache: bool = False,
 ) -> None:
     """Start unified Dataface server.
 
@@ -46,21 +47,22 @@ def serve_command(
         None (exits with code 0 on success, 1 on errors)
     """
     from dataface.core.project_roots import find_dft_root, infer_dialect_from_dbt
-    from dataface.core.serve.bootstrap import apply_default_theme_from_env
+    from dataface.core.serve.bootstrap import apply_default_theme
     from dataface.core.serve.port import resolve_port
     from dataface.core.serve.server import create_server
 
     # Resolve the project root: --project-dir if given, else discover from cwd.
     project_dir = project_dir or find_dft_root() or Path.cwd()
 
-    # Apply DFT_DEFAULT_THEME before anything else — fails fast on invalid names.
+    # Resolve default theme (env var > dataface.yml theme: > built-in default).
+    # Fails fast on invalid values.
     try:
-        apply_default_theme_from_env()
+        apply_default_theme(project_dir)
     except DatafaceError as e:
         print_structured_errors([e.to_structured()])
         raise typer.Exit(1) from None
 
-    # Resolve port: --port > DFT_PORT > dataface.yml > hash(project_dir)
+    # Resolve port: --port > DFT_PORT > dataface.yml server.port > hash(project_dir)
     port = resolve_port(
         explicit_port=port,
         project_dir=project_dir,
@@ -85,6 +87,7 @@ def serve_command(
         dialect=effective_dialect,
         target=effective_target,
         max_workers=max_workers,
+        no_cache=no_cache,
     )
 
     # Start server

dataface/cli/main.py

@@ -911,6 +911,17 @@ def serve(
             ),
         ),
     ] = None,
+    no_cache: Annotated[
+        bool,
+        typer.Option(
+            "--no-cache",
+            help=(
+                "Disable the persistent query cache. By default dft serve caches "
+                "results in <project>/.dft/cache.duckdb across page loads. "
+                "Use --no-cache to disable (matches today's behavior)."
+            ),
+        ),
+    ] = False,
 ) -> None:
     """Start the dashboard server.
 
@@ -929,7 +940,7 @@ def serve(
       4. ~/.dbt/profiles.yml
 
     Port is auto-resolved: --port flag > DFT_PORT env var > dataface.yml
-    port field > deterministic hash of project directory. If the chosen port
+    server.port > deterministic hash of project directory. If the chosen port
     is occupied, the next available port is used automatically.
 
     \b
@@ -948,6 +959,7 @@ def serve(
         dialect=dialect,
         target=target,
         max_workers=max_workers,
+        no_cache=no_cache,
     )
 
 

dataface/core/compile/colors.py

@@ -1,7 +1,6 @@
 """Color utility functions for Dataface renderers.
 
-Provides is_dark_color, is_sanitizable_color, and sanitize_color for use across
-compile and render layers.
+Provides color helpers for use across compile and render layers.
 """
 
 from __future__ import annotations
@@ -9,9 +8,16 @@ from __future__ import annotations
 import re
 from typing import overload
 
+from PIL import ImageColor
+
 from dataface.core.compile.errors import CompilationError
 
 _CSS_HEX_COLOR_PATTERN = re.compile(r"^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$")
+_CSS_RGBA_COLOR_PATTERN = re.compile(
+    r"^rgba\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*"
+    r"((?:0(?:\.\d+)?)|(?:1(?:\.0+)?)|(?:\.\d+))\s*\)$",
+    re.IGNORECASE,
+)
 
 
 def is_sanitizable_color(color: str) -> bool:
@@ -22,31 +28,41 @@ def is_sanitizable_color(color: str) -> bool:
     }
 
 
-def is_dark_color(color: str) -> bool:
-    """Check if a color is dark based on luminance.
+def _color_channels(color: str) -> tuple[int, int, int]:
+    rgba_match = _CSS_RGBA_COLOR_PATTERN.match(color)
+    if rgba_match:
+        r, g, b = (int(value) for value in rgba_match.groups()[:3])
+        if all(0 <= value <= 255 for value in (r, g, b)):
+            return (r, g, b)
+        raise CompilationError(f"mix_colors expects CSS colors, got {color!r}")
 
-    Uses the relative luminance formula to determine if a color is
-    dark (luminance < 0.5) or light (luminance >= 0.5).
-    """
-    if not color or not color.startswith("#"):
-        return False
+    try:
+        parsed = ImageColor.getrgb(color)
+    except ValueError as exc:
+        raise CompilationError(f"mix_colors expects CSS colors, got {color!r}") from exc
 
-    hex_color = color.lstrip("#")
-    if len(hex_color) == 3:
-        hex_color = "".join(c * 2 for c in hex_color)
+    r, g, b = int(parsed[0]), int(parsed[1]), int(parsed[2])
+    if not all(0 <= value <= 255 for value in (r, g, b)):
+        raise CompilationError(f"mix_colors expects CSS colors, got {color!r}")
+    return (r, g, b)
 
-    if len(hex_color) != 6:
-        return False
 
-    try:
-        r = int(hex_color[0:2], 16) / 255.0
-        g = int(hex_color[2:4], 16) / 255.0
-        b = int(hex_color[4:6], 16) / 255.0
-    except ValueError:
-        return False
-
-    luminance = 0.299 * r + 0.587 * g + 0.114 * b
-    return luminance < 0.5
+def mix_colors(base: str, overlay: str, fraction: float) -> str:
+    """Blend ``fraction`` of ``overlay`` into ``base``. Returns 6-digit hex.
+
+    Used to derive subtle surface/secondary tiers from theme tokens — e.g. a code
+    background that is the page background nudged toward the text color — so the
+    result tracks the theme on both light and dark backgrounds instead of pinning a
+    constant. ``fraction`` is clamped to [0, 1]; 0 returns ``base``, 1 returns ``overlay``.
+    """
+
+    t = min(1.0, max(0.0, fraction))
+    br, bg, bb = _color_channels(base)
+    o_r, o_g, o_b = _color_channels(overlay)
+    r = round(br + (o_r - br) * t)
+    g = round(bg + (o_g - bg) * t)
+    b = round(bb + (o_b - bb) * t)
+    return f"#{r:02x}{g:02x}{b:02x}"
 
 
 @overload

dataface/core/compile/compiler.py

@@ -437,7 +437,7 @@ def validate_compiled_queries(
 
 
 def compile_file(
-    file_path: Path,
+    file_path: str | Path,
     options: dict[str, Any] | None = None,
     apply_meta: bool = True,
     root_path: Path | None = None,
@@ -468,9 +468,7 @@ def compile_file(
         >>> if result.success:
         ...     print(result.face.title)
     """
-
-    if isinstance(file_path, str):
-        file_path = Path(file_path)
+    file_path = Path(file_path)
 
     if not file_path.exists():
         return CompileResult(

dataface/core/compile/config.py

@@ -23,6 +23,7 @@ YAML is the single source of truth - no Python dataclass defaults.
 
 from __future__ import annotations
 
+import os
 from collections.abc import Mapping
 from copy import deepcopy
 from functools import cache
@@ -36,8 +37,8 @@ from dataface.core.compile.models.config import (
     ConfigNode,
     ConfigPatch,
     ExecutionConfig,
-    MarkdownConfig,
     RenderingConfig,
+    ServerConfig,
     VegaRuntimeConfig,
     as_plain_mapping,
     is_mapping_like,
@@ -61,7 +62,6 @@ _core_dir: Path = Path(__file__).parent.parent
 _MODULE_DEFAULT_PATHS: list[Path] = [
     _core_dir / "inspect" / "defaults.yml",
     _core_dir / "render" / "geo_defaults.yml",
-    _core_dir / "render" / "markdown_defaults.yml",
     _core_dir / "render" / "terminal_defaults.yml",
 ]
 
@@ -122,11 +122,6 @@ def get_chart_rendering() -> ConfigNode:
     return get_config().chart_rendering
 
 
-def get_markdown_config() -> MarkdownConfig:
-    """Narrow getter — markdown rendering color config."""
-    return get_config().markdown
-
-
 def get_terminal_config() -> ConfigNode:
     """Narrow getter — terminal rendering defaults."""
     return get_config().terminal
@@ -147,6 +142,42 @@ def get_execution_config() -> ExecutionConfig:
     return get_config().execution
 
 
+def resolve_max_workers(explicit: int | None) -> int:
+    """Resolve the query-parallelism width: explicit arg → DFT_MAX_WORKERS → config.
+
+    Single source of truth for both the render-time worker pool and the
+    per-source connection pool, so the two never disagree on width.
+    """
+    if explicit is not None:
+        return explicit
+    env_val = os.getenv("DFT_MAX_WORKERS")  # noqa: TID251 — DFT_MAX_WORKERS knob
+    if env_val is not None:
+        return int(env_val)
+    return get_execution_config().max_workers
+
+
+def get_project_server_config(project_dir: Path) -> ServerConfig:
+    """Read project-level ``server:`` settings from dataface.yml/yaml.
+
+    Only the ``server:`` section is validated here. dataface.yml is also used
+    as a lightweight project marker in tests and examples, so unrelated top-level
+    keys must not make serve startup fail.
+    """
+    base = get_config().server.to_plain_dict(exclude_none=False)
+    resolved_dir = project_dir.resolve()
+    for candidate in (resolved_dir / "dataface.yml", resolved_dir / "dataface.yaml"):
+        if candidate.exists():
+            file_data = _as_mapping(_load_yaml_data(candidate), candidate.name)
+            server_section = file_data.get("server")
+            if server_section is None:
+                break
+            server_data = _as_mapping(
+                server_section, f"{candidate.name} server section"
+            )
+            return ServerConfig.model_validate(_deep_merge(base, server_data))
+    return ServerConfig.model_validate(base)
+
+
 def load_config(path: Path) -> Config:
     """Load configuration from a custom YAML file.
 
@@ -444,7 +475,7 @@ def set_default_theme_name(theme_name: str) -> None:
     """Override the in-process default theme name.
 
     Validates the theme exists before patching. Raises ValueError on unknown names.
-    Called at serve startup by apply_default_theme_from_env(); not for general use.
+    Called at serve startup by apply_default_theme(); not for general use.
 
     Args:
         theme_name: A built-in theme stem (e.g. "carbong100", "light").
@@ -628,6 +659,38 @@ def get_project_warnings_ignore(project_dir: Path) -> frozenset[str]:
     return frozenset()
 
 
+# ============================================================================
+# PROJECT DEFAULT THEME
+# ============================================================================
+
+
+def get_project_default_theme(project_dir: Path) -> str | None:
+    """Return the project-declared default theme from ``dataface.yml``.
+
+    Reads the top-level ``theme:`` key. Returns ``None`` when the file is
+    absent or the key is unauthored. Raises ``TypeError`` for any non-string
+    value so misauthored configs fail loud at startup.
+
+    Validation of the theme name (must be a built-in theme) lives in
+    ``apply_default_theme`` so that env-var and config-file inputs share one
+    structured-error path.
+    """
+    resolved_dir = project_dir.resolve()
+    for candidate in (resolved_dir / "dataface.yml", resolved_dir / "dataface.yaml"):
+        if candidate.exists():
+            file_data = _as_mapping(_load_yaml_data(candidate), candidate.name)
+            if "theme" not in file_data:
+                return None
+            value = file_data["theme"]
+            if not isinstance(value, str):
+                raise TypeError(
+                    f"{candidate.name}: theme must be a string, "
+                    f"got {type(value).__name__}: {value!r}"
+                )
+            return value
+    return None
+
+
 # ============================================================================
 # META CONFIG CLASSES
 # ============================================================================