phase: 93_theme_semantic_completion

All verification is complete. Final report:

**Phase 93 — Theme semantic completion: FINAL VERIFICATION PASS — ALL GREEN**

- Verified full implementation in tree: migration `0016` (8 nullable semantic columns, applied at head), 17-var `BUILTIN_COLORS`/`COLOR_FIELDS`/`effective_settings`, API validation, `#view-theme` State-colors fieldset (17 pickers), `theme.js` FIELDS/PAIRS (5→8), `.page-head` surface panel (6 shell views + doc-edit + shared.html; login card / document sticky header audited as already-surfaced), mock_llm `content: None` fix
- Fixed 2 pre-existing defects (both fail identically on baseline `d4f38ad`, proven via worktree A/B): `test_nav_rename_sources` — expected nav tail missing the phase-91 "Theme" link; `test_stale_ui_copy` — now truncates `saved_chats` before/after (house `test_suggestion_chips` pattern) so the seed-chip contract is deterministic on the shared dev DB (owner's 22 saved chats triggered phase-80 last-3-questions)
- Tests: `uv run pytest --cov=app --cov-report=term-missing` → **1868 passed, app/ 99%** (>90% ✓); `uv run ruff check .` → clean; `uv run pyright` → **0 errors**
- E2E: dedicated `uv run pytest tests/e2e/test_theme_semantic_completion.py -v --no-cov` → **8/8 in isolation** (all-gray 17-color theme: zero residual color on saved-result/Stale/Revoked/Local/tool-call elements, text labels intact, gray heads non-transparent, pre-paint tag, Reset → byte-identical no-tag); 15 theme/header/nav/responsive suites green in isolation; full 85-file combined run: only the 2 fixed pre-existing failures + 1 combined-run artifact (`test_sync_upload_progress`, green in isolation)
- Completion criteria: (1) monochrome E2E ✓ (2) default byte-identical, no `#bor-theme` tag ✓ (3) all page heads on solid surface ✓ (4) suite/coverage/lint/E2E green ✓ (5) phases 01–92 no behavior change ✓ (6) commit left to harness per protocol
- Notable: cleaned stray uvicorn leftovers from prior implementation pass (owner's `--reload` dev server untouched); no deviations from the phase design
- Next pending phase: `94_ls_tree_drilldown`

tests/integration/test_ui_settings_api.py

@@ -149,7 +149,70 @@ def test_admin_grid_line_validation_and_normalization(
     r = client.get("/api/ui-settings")
     assert r.status_code == 200
     assert r.json()["grid_line"] == "#123123"  # the stored value reads back
-    assert len(r.json()) == 12  # the 12-key response shape (9 colors + 3 strings)
+    assert len(r.json()) == 20  # the 20-value shape (17 colors + 3 strings, phase 93)
+
+
+def test_admin_semantic_fields_round_trip(client: TestClient, db: Session) -> None:
+    """Phase 93 (task 01): the 8 semantic state colors against the LIVE
+    API — a bad hex is a 422 naming the field (same fixed detail as the
+    identity colors); a non-built-in value is lowercased on store and
+    reads back through GET; a built-in value stores NULL (the response
+    still reports the built-in); an absent (null) field stores NULL.
+    The response is the effective values for all 20 keys."""
+    client.post("/api/login", json={"password": ADMIN_PASSWORD})
+
+    r = client.put("/api/ui-settings", json={"ok_bg": "not-a-color"})
+    assert r.status_code == 422, r.text
+    assert r.json()["detail"] == "ok_bg must be a #rrggbb hex color"
+
+    r = client.put(
+        "/api/ui-settings",
+        json={"ok_ink": "#444444", "accent_bg": "#222222", "err_line": "#EFEFEF"},
+    )
+    assert r.status_code == 200, r.text
+    assert r.json()["ok_ink"] == "#444444"  # stored + reported
+    assert r.json()["accent_bg"] == "#222222"  # stored + reported
+    assert r.json()["err_line"] == "#efefef"  # upper → lowercased on store
+
+    row = db.execute(select(UiSettings).where(UiSettings.id == 1)).scalars().first()
+    assert row is not None, "the PUT upsert creates the id-1 row"
+    assert row.ok_ink == "#444444"
+    assert row.accent_bg == "#222222"
+    assert row.err_line == "#efefef"  # the stored column, lowercase
+    assert row.err_bg is None  # absent (null) field → NULL
+    assert row.accent_ink is None  # absent (null) field → NULL
+
+    r = client.get("/api/ui-settings")
+    assert r.status_code == 200
+    body = r.json()
+    assert set(body) == set(theming.STRING_FIELDS) | set(theming.COLOR_FIELDS)
+    assert len(body) == 20
+    # GET returns the EFFECTIVE values: the stored ones over the
+    # built-ins for the untouched 14 colors.
+    assert body["ok_ink"] == "#444444"
+    assert body["err_bg"] == theming.BUILTIN_COLORS["err_bg"]
+    assert body["accent_ink"] == theming.BUILTIN_COLORS["accent_ink"]
+    untouched = [k for k in theming.COLOR_FIELDS if k not in ("ok_ink", "accent_bg", "err_line")]
+    assert {k: body[k] for k in untouched} == {
+        k: theming.BUILTIN_COLORS[k] for k in untouched
+    }  # the 14 untouched colors report their built-ins
+
+    # The built-in → NULL normalization: PUT the built-in back (one in
+    # uppercase) — the row's semantic columns return to NULL and the
+    # effective values are still the built-ins (no-op contract).
+    body_put = {"ok_ink": theming.BUILTIN_COLORS["ok_ink"].upper(),
+                "accent_bg": theming.BUILTIN_COLORS["accent_bg"],
+                "err_line": theming.BUILTIN_COLORS["err_line"]}
+    r = client.put("/api/ui-settings", json=body_put)
+    assert r.status_code == 200, r.text
+    db.expire_all()
+    row = db.execute(select(UiSettings).where(UiSettings.id == 1)).scalars().first()
+    assert row is not None
+    assert row.ok_ink is None  # built-in (uppercase in) → NULL
+    assert row.accent_bg is None  # built-in → NULL
+    assert row.err_line is None  # built-in → NULL
+    for key in theming.COLOR_FIELDS:
+        assert r.json()[key] == theming.BUILTIN_COLORS[key]
 
 
 def _config_keys() -> set[str]: