phase: 92_theme_save_and_coverage

**Phase 92 final verification pass — all green.** This pass re-verified the completed tasks (all 5 task files already in `complete/`) against every completion criterion; no defects found, nothing to fix. - Verified: 9th identity var `grid_line` end-to-end (migration `0015` at head, model/`theming.py`/schemas/API, 422 + built-in→NULL tests present); `styles.css` zero hardcoded literals outside `:root` + derived `--brand-*` vars; 9th picker in theme form; wordmark themed; `theme.js` save/reset/re-show/mount live-sync; dedicated E2E suite + phase-91 suite updated. - `uv run pytest --cov=app --cov-report=term-missing` → **1845 passed, exit 0, TOTAL 99%** (>90%) - `uv run ruff check .` → clean; `uv run pyright` → 0 errors, 0 warnings - `uv run pytest tests/e2e/test_theme_save_and_coverage.py -v --no-cov` → **3 passed** (save-live, reset-live, whole-site) - `uv run pytest tests/e2e/test_admin_theme_tab.py -v --no-cov` → **5 passed** - Criteria: (1) Save/Reset repaint open page, no nav, SPA-nav survives, pre-paint intact ✅; (2) both `rg` gates green (only `:root` + documented `#fff` Stop label; zero SVG hex attrs), grid/selection/hovers/wash/wordmark E2E-proven ✅; (3) no-op contract live-checked: row-less `/` = no tag + exact A1 CSP, grid-only row = 9-var tag in `COLOR_FIELDS` order + sha256 CSP, with-row ≡ row-less bytes ✅; (4) full suite/coverage/lint/both E2E ✅; (5) commit left to the harness per instructions. - Deviations (previously made, probe-verified, kept): live repaint uses CSSOM `<html>` overrides because Chromium blocks `<style>` textContent mutations under the locked sha256-only CSP (tag text still mirrors the next load; `<html>` style exact-saved after Save, empty after Reset); wordmark themed via 3 `.brand-mark` CSS rules instead of inline styles (task 03's inline attrs were CSP-blocked — fixed during task 04). - Next pending phase: none — `todo/` contains only `92_theme_save_and_coverage`.
2026-09-10 00:23:08 -04:00
parent d22d260b8b
commit df91c6316c
49 changed files with 2282 additions and 189 deletions
@@ -7,12 +7,12 @@ authoring guide before task 03 deleted it) and the DB-over-env /
 DB-over-built-in resolver shared by ``/api/ui-settings`` and
 ``/api/config``:

-* ``BUILTIN_COLORS`` — the DRIFT GUARD: the 8 built-ins must equal the
+* ``BUILTIN_COLORS`` — the DRIFT GUARD: the 9 built-ins must equal the
  values parsed straight out of ``frontend/assets/styles.css``'s
  ``:root`` block, so the Python palette and the stylesheet can never
  silently diverge;
 * ``theme_style_tag`` — the byte-identical contract (all built-in →
-  ``""``) and the exact tag shape (all 8 variables, ``COLOR_FIELDS``
+  ``""``) and the exact tag shape (all 9 variables, ``COLOR_FIELDS``
  order, lowercased hex);
 * ``effective_settings`` — missing row → env strings + built-ins; a DB
  row's set columns win; an empty-string DB string falls back to env
@@ -45,6 +45,14 @@ def _delete_row() -> Any:
    return delete(UiSettings).where(UiSettings.id == 1)


+def _start_row_missing(db: Session) -> None:
+    """The single row is global state: wipe it so every DB test starts
+    from the row-missing state it asserts (a stale row from an earlier
+    interrupted run must not break them)."""
+    db.execute(_delete_row())
+    db.commit()
+
+
 def _root_declarations() -> dict[str, str]:
    """The ``--name: value`` declarations of styles.css's (first)
    ``:root`` block, comments stripped, in file order."""
@@ -59,13 +67,13 @@ def _root_declarations() -> dict[str, str]:
 def test_builtin_colors_match_styles_css_root() -> None:
    """The drift guard: every built-in equals the stylesheet's ``:root``
    value for the same variable (and ``BUILTIN_COLORS`` names exactly
-    the 8 identity variables — no more, no fewer)."""
+    the 9 identity variables — no more, no fewer)."""
    decls = _root_declarations()
    builtin_names = set(theming.BUILTIN_COLORS)
    assert builtin_names == {
-        "bg", "surface", "ink", "ink_soft", "line",
+        "bg", "surface", "ink", "ink_soft", "line", "grid_line",
        "brand", "brand_soft", "brand_ink",
-    }, f"BUILTIN_COLORS must name exactly the 8 identity variables, got {sorted(builtin_names)}"
+    }, f"BUILTIN_COLORS must name exactly the 9 identity variables, got {sorted(builtin_names)}"
    for name, value in theming.BUILTIN_COLORS.items():
        css_name = f"--{name.replace('_', '-')}"
        assert css_name in decls, f"styles.css :root is missing {css_name}"
@@ -75,12 +83,15 @@ def test_builtin_colors_match_styles_css_root() -> None:
        )


-def test_color_fields_are_the_eight_keys_in_readme_order() -> None:
-    """``COLOR_FIELDS`` is the 8 keys in the themes-README order — the
-    order the resolver, the API, and the tag renderer all rely on."""
+def test_color_fields_are_the_nine_keys_in_readme_order() -> None:
+    """``COLOR_FIELDS`` is the 9 keys in the themes-README order — the
+    order the resolver, the API, and the tag renderer all rely on.
+    (Phase 92, task 01: ``grid_line`` is the 9th identity variable,
+    slotting in between ``line`` and ``brand`` — structural colors
+    first, brand last.)"""
    assert theming.COLOR_FIELDS == (
        "bg", "surface", "ink", "ink_soft",
-        "line", "brand", "brand_soft", "brand_ink",
+        "line", "grid_line", "brand", "brand_soft", "brand_ink",
    )
    assert theming.STRING_FIELDS == ("app_name", "input_placeholder", "footer_text")

@@ -102,7 +113,8 @@ def _env_settings() -> Settings:

 def test_effective_missing_row_is_env_strings_plus_builtins(db: Session) -> None:
    """A missing row (GET creates nothing) means "defaults": the env
-    strings + the built-in palette, all 11 keys."""
+    strings + the built-in palette, all 12 keys."""
+    _start_row_missing(db)
    row = db.execute(select(UiSettings).where(UiSettings.id == 1)).scalars().first()
    assert row is None, "the test starts from a row-missing state"
    effective = theming.effective_settings(db, _env_settings())
@@ -117,6 +129,7 @@ def test_effective_db_row_wins_column_by_column(db: Session) -> None:
    """Set columns win, unset columns fall back — per column, so a
    partial row (only ``bg`` set) mixes the DB color with the built-ins
    and the env strings."""
+    _start_row_missing(db)
    db.add(UiSettings(id=1, bg="#111111", app_name="DB Name"))
    db.commit()
    try:
@@ -140,6 +153,7 @@ def test_effective_empty_string_db_string_falls_back_to_env(db: Session) -> None
    Colors: ``None`` → the built-in (an empty color is impossible through
    the API — the hex validator — the resolver's not-None rule covers
    the hand-edited edge by returning whatever the row holds)."""
+    _start_row_missing(db)
    db.add(UiSettings(id=1, app_name=""))
    db.commit()
    try:
@@ -155,9 +169,10 @@ def test_effective_empty_string_db_string_falls_back_to_env(db: Session) -> None
 def test_effective_without_explicit_settings_uses_get_settings(db: Session) -> None:
    """``settings=None`` (the design's call shape) resolves the env
    fallback from the cached :func:`app.config.get_settings` — the
-    values it reports must be real ``str``s for all 11 keys."""
+    values it reports must be real ``str``s for all 12 keys."""
    from app.config import get_settings

+    _start_row_missing(db)
    effective = theming.effective_settings(db)
    assert set(effective) == set(theming.STRING_FIELDS) | set(theming.COLOR_FIELDS)
    assert effective["app_name"] == get_settings().app_name
@@ -181,16 +196,20 @@ def test_theme_style_tag_all_builtins_is_empty_string() -> None:
    assert theming.theme_style_tag(colors) != ""


-def test_theme_style_tag_one_changed_carries_all_eight_in_order() -> None:
-    """A single non-built-in color still emits ALL 8 variables, in
-    ``COLOR_FIELDS`` order, with the exact tag shape (no whitespace)."""
+def test_theme_style_tag_one_changed_carries_all_nine_in_order() -> None:
+    """A single non-built-in color still emits ALL 9 variables, in
+    ``COLOR_FIELDS`` order, with the exact tag shape (no whitespace).
+    Phase 92 (task 01): the tag carries ``--grid-line:#4a2626;`` between
+    ``--line`` and ``--brand`` (the 9th identity variable — the
+    background grid texture)."""
    colors = dict(theming.BUILTIN_COLORS)
    colors["brand"] = "#818cf8"
    tag = theming.theme_style_tag(colors)
    assert tag == (
        '<style id="bor-theme">:root{'
        "--bg:#0f0a0a;--surface:#1a0f0f;--ink:#f0e6e6;--ink-soft:#b8a8a8;"
-        "--line:#2d1a1a;--brand:#818cf8;--brand-soft:#2d0a0a;--brand-ink:#fca5a5;"
+        "--line:#2d1a1a;--grid-line:#4a2626;--brand:#818cf8;"
+        "--brand-soft:#2d0a0a;--brand-ink:#fca5a5;"
        "}</style>"
    )
    # The changed value lands under the dashed CSS name…
@@ -211,7 +230,7 @@ def test_theme_style_tag_multiple_changed() -> None:
    assert tag.startswith('<style id="bor-theme">:root{--bg:#0a0e1a;')
    assert "--brand-ink:#c7d2fe;" in tag
    assert tag.endswith("}</style>")
-    # The order of the 8 dashed names is the COLOR_FIELDS order.
+    # The order of the 9 dashed names is the COLOR_FIELDS order.
    names = re.findall(r"--([a-z-]+):", tag)
    assert names == [k.replace("_", "-") for k in theming.COLOR_FIELDS]