brain-of-reese/.agents/phases/complete/177_themed_favicon/00_phase.md

Phase 177 — The favicon's colors follow the effective theme palette

Source: TODO.md L3 — "We need the favicon to change colors to match the theme." Story: n/a (TODO-derived, owner roadmap confirmation 2026-10-13) Context: frontend/assets/favicon.svg (the current static art — a hexagon + center dot + 4 spokes whose three hardcoded colors map 1:1 onto the built-in palette: #1a0f0f = surface, #f43f5e = brand, #fca5a5 = brand_ink), the five templates' L8 <link rel="icon" type="image/svg+xml" href="/assets/favicon.svg"> (frontend/index.html, frontend/document.html, frontend/login.html, frontend/shared.html, frontend/doc-edit.html), app/core/theming.py (BUILTIN_COLORS, COLOR_FIELDS, effective_settings() — the DB-over-env/built-in resolver with NO process cache, theme_style_tag() + inject_theme() — the pre-paint tag pattern, theme_csp_hash()), app/core/caching.py (CachingMiddleware's per-response short-lived-session theme read with the never-break DB-blip fallback; /favicon.svg is neither in HTML_PAGES nor under /assets/ → passes through untouched), app/main.py create_app() (router includes end ~L199; the static catch-all mount at L252 — routes-first), app/core/security_headers.py (CSP default-src 'self'; … img-src 'self' data: — the phase-123 carve-out that makes a data: favicon URI legal; CSP3 governs link[rel=icon] by img-src), frontend/assets/theme.js (the admin Theme tab — previewColor() live preview, the input bindings, saveTheme()/resetTheme() + the bor:view-refresh re-show handler), tests/unit/test_theming.py (the static pin set incl. test_builtin_colors_match_styles_css_root), tests/unit/test_theme_frontend.py (the JS static-pin pattern), tests/e2e/test_theme_save_and_coverage.py + test_theme_semantic_completion.py (the admin theme-tab E2E pattern: e2e/auth_helpers.login(page, app_url, next="/theme.html"), the #theme-* inputs), AGENTS rules 4/6/8/9/10, PLAN §7.4 (the never-stale feedback contract).

Objective

The browser-tab favicon must carry the EFFECTIVE theme palette (built-in or the owner's saved one), painted on first load like everything else — no red hexagon on a graphite theme. The favicon is served by the app from the same resolver that paints the page (effective_settings), and the admin Theme tab's live (unsaved) picks repaint it too (owner-confirmed A4).

Design (shared by all tasks — the executor reads this, not the chat)

• D1 — the pure renderer (task 01, A1). theming.favicon_svg(colors: dict[str, str]) -> str — the SAME artwork (viewBox 0 0 64 64, the hexagon path, the r=6.5 center circle, the 4 spokes, all stroke widths/caps unchanged) with only the three color roles swapped: hexagon fill → surface, hexagon stroke + circle fill → brand, spokes stroke → brand_ink. The input is the full 20-value effective dict (mirroring theme_style_tag's self-contained signature; the function reads its three keys). Byte-identical contract: for the built-in palette the output is EXACTLY the current static file's <svg> element (lowercase hex, same attribute order) — pinned by a golden constant in tests/unit/test_theming.py; the static file's comment header is file packaging, not art, and is not part of the contract.
• D2 — serving (task 02, A2/A3). GET /favicon.svg (+ HEAD for static-file parity) — a no-prefix route in create_app() after the router includes and BEFORE the static catch-all mount (routes-first, the phase-51 shared-page pattern). Sync handler: one short-lived SessionLocal() session (the caching.py house pattern — NO process cache, so a runtime theme change is visible on the next request), effective_settings() → favicon_svg(); ANY exception → logger.exception + favicon_svg(BUILTIN_COLORS) (200, never 500 — the theme-tag's never-break contract, caching.py's DB-blip pattern). Response: media_type="image/svg+xml", Cache-Control: no-cache (the pages are no-cache; the palette changes at runtime, so the browser must revalidate — the route is NOT under /assets/, so no version token; freshness is revalidation, not busting). Deliberately OUTSIDE /api/*: no per-response byte-budget line (AGENTS rule 10 is /api/*-only), no auth dependency (the favicon is chrome, like the login page). CachingMiddleware passes it through untouched (neither an HTML page nor an asset); SecurityHeadersMiddleware still adds the CSP — no change needed (img-src 'self' data: covers the D4 preview).
• D3 — the templates + the static file's deletion (task 03, A2). All five L8 links → href="/favicon.svg"; frontend/assets/favicon.svg is deleted — the route is the single source (the built-in bytes stay pinned by D1's golden constant, so nothing is lost). The new href is not under /assets/, so CachingMiddleware's ?v= rewrite regex can never touch it (a pin keeps this explicit — the link stays bare).
• D4 — the Theme tab live preview (task 04, A4 — owner-confirmed 2026-10-13). theme.js gains a pure themeFaviconDataUri(surface, brand, brandInk) — the CLIENT-SIDE MIRROR of theming.favicon_svg (same artwork, same roles; a unit pin keeps the two from diverging — the PAIRS-mirror house pattern). The existing per-color input binding ALSO updates link[rel="icon"].href to the data: URI whenever one of the three driving fields (surface/brand/brand_ink) changes (rebuilt from the three inputs' current values; the other 14 picks never touch it). Restore to "/favicon.svg" on: Save success (after applyServedTheme), Reset success, the Reset-failure clearPreview() path, and the bor:view-refresh re-show — after every restore the SETTLED palette (re-read per request, no process cache) governs. CSP note (commented in the code): data: is legal for the favicon via the phase-123 img-src 'self' data: carve-out (CSP3: link[rel=icon] is governed by img-src; the carve-out is image-scoped — data: never becomes a script/style/fetch source).
• NOT touched: CachingMiddleware, the #bor-theme tag injection + CSP hash, the 8 semantic state colors (they are NOT in the artwork — a favicon has no state meaning), app/ outside theming.py/main.py, brand.js, the other templates/assets, the theme.js save/reset/contrast machinery beyond the additions above.

Dependencies

• 176_mobile_settings_value_width (todo) — the immediately preceding phase (Protocol B ordering; no functional dependency).
• 92_theme_save_and_coverage (complete) — the served-theme sync + the #theme-* input contract the D4 additions bind to.
• 91_admin_theme_tab (complete) — the Theme tab's live-preview mechanism (previewColor) and the bor:view-refresh re-show hook.

Tasks

1. 01_favicon_svg_renderer.md — theming.favicon_svg(): the pure palette→artwork renderer, byte-identical for the built-in palette (golden pin) — A1.
2. 02_favicon_route.md — GET /favicon.svg (+ HEAD) in create_app(): effective palette, built-in fallback on DB failure (200, never 500), image/svg+xml + no-cache — A2/A3.
3. 03_template_link_swap.md — the five template links → /favicon.svg; frontend/assets/favicon.svg deleted (single source).
4. 04_theme_tab_live_preview.md — the Theme tab's live picks repaint the favicon (the CSP-legal data: mirror, A4); Save/Reset/re-show restore the route URL; the dedicated E2E suite + the atomic commit.

Testing & Quality

• Unit: tests/unit/test_theming.py (task 01): the golden byte-identical pin, the themed-role pin (the three hexes in their exact roles), the geometry-invariance pin (only the 4 color attributes differ); tests/unit/test_theme_frontend.py (task 04): the data: mechanism pin (the three driving field names, the exact /favicon.svg restore, the restore wiring).
• Integration: tests/integration/test_favicon_route.py (tasks 02–03): the three route states (default = golden bytes, themed = effective colors, DB failure = built-in fallback 200), the CSP header presence, the five template link pins (bare /favicon.svg, no ?v=, no /assets/favicon.svg anywhere in the served HTML), the deleted file's 404.
• E2E (AGENTS rule 4, task 04): tests/e2e/test_themed_favicon.py, run in isolation — the full contract in a real browser (default/themed route bytes, the pre-paint tag non-regression, the live-preview data: repaint, the restore contract, zero external requests — rule 6).
• Coverage: >90% on app/ (uv run pytest --cov=app --cov-report=term-missing); lint/types: uv run ruff check . && uv run pyright.

Completion Criteria

• GET /favicon.svg on a default (no ui_settings row) deployment is 200 image/svg+xml with Cache-Control: no-cache and a body byte-identical to the current static art (the golden pin, the integration test).
• With a saved non-default palette (distinct surface/brand/brand_ink), the route's SVG carries those three hexes in their exact roles, and the served pages STILL inject the #bor-theme tag (the phase-91 pin stays green — no regression to the tag/CSP contract).
• A DB failure at request time serves the built-in art with 200 (never 500).
• All five templates link href="/favicon.svg" (bare — no ?v=), /assets/favicon.svg is 404 (the file is deleted), and the favicon actually renders in the browser (the E2E).
• In the admin Theme tab, a live (unsaved) pick of surface/brand/brand_ink repaints the favicon via the data: URI; Save / Reset / re-show restore href="/favicon.svg" with the settled palette governing (the E2E).
• uv run pytest green, app/ coverage >90%, ruff + pyright clean.
• uv run pytest tests/e2e/test_themed_favicon.py -v --no-cov green in isolation; test_theme_save_and_coverage.py + test_theme_semantic_completion.py (phases 92/93) green in isolation (no theme-tab regression).
• ONE atomic Conventional Commits commit (AGENTS rule 8, --no-gpg-sign) covering the phase + this directory + the cleared TODO.md.