diff --git a/docs/semantic-frontend-protocol.md b/docs/semantic-frontend-protocol.md
index 8814bae..3258fb7 100644
--- a/docs/semantic-frontend-protocol.md
+++ b/docs/semantic-frontend-protocol.md
@@ -116,6 +116,26 @@ layout-local frontend consumes). Peer cursors reuse the existing
 is: one capability bit, ~five instance→frontend interpretation
 variants, and one frontend→instance `Viewport` variant.
 
+**`BufferSnapshot` resets buffer-scoped interpretation state.** A
+frontend receiving a snapshot drops everything it holds for the
+named buffer — spans, decorations, adornments, minimap summary,
+completion popup, search and menu prompts (which also gate the
+frontend's key/pointer interception), and status facts — and
+rebuilds from the frames that follow; the instance mirrors this by
+invalidating its per-buffer emission baselines whenever it writes a
+snapshot, so the frontend's post-snapshot viewport declaration
+receives authoritative re-sends even when nothing changed
+daemon-side (the unchanged-generation A → B → A revisit). Bufferless
+facts (`ThemeFacts`, the minibuffer prompt) and per-frontend state
+(the gutter mode) survive snapshots on both sides, and the
+instance's stale-store diagnostic-count freeze is store knowledge,
+not session state — the re-sent `StatusFacts` after a snapshot
+carries the frozen counts, never zeros, including for a session
+whose first frame lands during staleness (a late joiner attaching
+mid-edit). The store maintains those per-URI severity totals with
+the retained vector, so frame-time producers read them in O(1)
+rather than rescanning diagnostics for every attached session.
+
 ## Capability and version mechanics
 
 Identical pattern to `crdt_replica`:
@@ -205,6 +225,26 @@ ResourceOffer {
     mime: String,
     body: ResourceBody, // Inline(Vec<u8>) | Uri(String)
 },
+
+/// Themes arc Q#TH7 (protocol v16): the daemon-resolved UI face
+/// table. Bufferless — the theme is one global instance. Complete
+/// replacement each send: a face absent from `faces` is unset and
+/// the frontend uses its own default for that surface. Every
+/// attachment receives exactly one authoritative table (the empty
+/// table included) with its first emission after viewport
+/// declaration; cached-compare suppressed thereafter, so an
+/// unthemed session pays one small message and nothing more.
+/// Resolution (the `ui.*` dotted-prefix inheritance walk) happens
+/// daemon-side over the stage-1 face inventory — frontends do
+/// exact-name lookup only, and apply each face within its
+/// stage-1 component mask (docs/theme-faces-framing.md Q#TH3/Q#TH5:
+/// a set face owns its surface; `Default` components mean the
+/// frontend's plain rendering; out-of-mask components are never
+/// read). Daemon-gated `>= 16`; appended as the FINAL variant —
+/// postcard discriminants are ordinal.
+ThemeFacts {
+    faces: Vec<ThemeFace>, // { name: String, style: Style }, sorted by name
+},
 ```
 
 Each family member diffs against the previous frame the same way
diff --git a/docs/theme-faces-framing.md b/docs/theme-faces-framing.md
new file mode 100644
index 0000000..0a00b3d
--- /dev/null
+++ b/docs/theme-faces-framing.md
@@ -0,0 +1,1038 @@
+# Theme faces — framing (Arc 4 stage 1, themes)
+
+**Revision 9 — 2026-07-15. Status: implemented on branch
+`theme-faces` (PR #120); revision 9 folds PR round 5.**
+
+Revision 9 (PR #120 round 5, one finding): the store-sourced freeze
+no longer rescans the retained diagnostic vector at frame cadence.
+`DiagnosticStore` maintains per-URI severity totals alongside
+`by_uri`, replacing or removing both in `set` / `clear` while
+`mark_stale` deliberately preserves both. `status_facts_msg` reads
+that tuple in O(1), so the round-4 late-join correctness does not
+turn a long stale interval into O(frames x diagnostics x semantic
+sessions) work under the shared store mutex. Acceptance item 34 is
+the store unit pin: all four totals replace correctly, survive
+staleness, and clear with the diagnostic vector.
+
+Revision 8 (PR #120 round 4, one finding): the diagnostic-count
+freeze is sourced from the diag store itself, superseding round 3's
+per-session `frozen_diag_counts` cache. That cache only seeded from
+fresh computations, so a session FIRST rendering during staleness —
+a late joiner attaching mid-edit, or a buffer first visited between
+didChange and fresh diagnostics — had no entry and fell back to
+(0, 0), contradicting the documented "frozen counts, never zeros"
+contract. But `mark_stale` (T M11.8) keeps the last published
+diagnostic vector — only the positions are invalid — so
+`status_facts_msg` now counts the retained `for_uri` entries even
+while stale: the retained entries ARE the frozen value, with no
+session state to lose to a snapshot reset and no history needed at
+attach. The per-session cache is deleted; the round-3 reset-survival
+property holds by construction. Acceptance item 33 (a store marked
+stale BEFORE the session exists still reports the preserved counts
+on the first frame); item 32's round-trip claim is unchanged and
+still passes against the new mechanism.
+
+Revision 7 (PR #120 round 3, findings 1–2): the reset contract is
+now symmetric on the GPU. The round-2 producer reset covered
+search/menu/status baselines, but the GPU's `BufferSnapshot` arm
+only cleared spans, decorations, adornments, summary, and the
+completion popup — a menu (or search) open at switch time survived
+the snapshot with no close message ever coming (the new buffer's
+first CLOSED state is suppressed daemon-side), leaving a stale
+popup that also gated key and pointer interception
+(`daemon_intercepts_keys`) indefinitely. The arm now clears
+`search_prompt`, `menu`, and `status_facts`; the minibuffer is
+deliberately exempt (one global core instance, matching the
+producer's surviving `last_minibuffer` baseline) (finding 1). And
+the round-2 reset broke the diagnostic-count freeze: `last_status`
+was both the peer emission baseline and the stale-store freeze
+source, so a snapshot between didChange and fresh diagnostics
+re-shipped `StatusFacts` with zeroed counts. The freeze source now
+lives apart — `frozen_diag_counts`, daemon-side knowledge about the
+buffer, advanced on every fresh count and read when the store is
+stale — and survives `on_buffer_snapshot_sent`, which keeps killing
+the emission baseline to force the re-send (finding 2). Acceptance
+items 31–32.
+
+Revision 6 (PR #120 round 2, findings 1–2): the producer gains the
+**snapshot/baseline reset contract**
+(`SemanticRenderState::on_buffer_snapshot_sent`). A `BufferSnapshot`
+resets the receiving frontend's buffer-scoped render state wholesale
+— spans, decorations, adornments, minimap summary, completion popup —
+but the returned viewport only replaced the producer's declared
+viewport, leaving every per-buffer emission baseline intact. On an
+unchanged A → B → A round trip, `last_summary[A]`'s key still
+matched, so the daemon emitted nothing and the frontend never
+regained A's themed minimap (or A's `StatusFacts` — the band kept
+showing B's name) until an edit, diagnostic republish, or theme
+mutation happened to move the key. The daemon now invalidates every
+buffer-scoped baseline for the snapshot's buffer wherever it writes
+one — the active-buffer-follow path and the F29 upgrade broadcast;
+the attach bootstrap needs no call because its session state is
+constructed fresh — general contract, not a minimap special case
+(finding 1). Deliberately surviving the reset: the bufferless
+`ThemeFacts` pair (the frontend keeps its face table across
+snapshots), the global minibuffer baseline, the per-frontend gutter
+mode, and the revision-keyed diag line cache (a compute cache, not a
+peer-state baseline); other buffers' baselines also survive, since
+any buffer the frontend navigates to receives its own snapshot
+first. Acceptance items 28–30 cover the producer round trip (themed
+summary and `StatusFacts` return at one generation), the real-daemon
+wiring over the wire, and the GPU minimap's pixel-identical return.
+The acceptance-suite manifest header now lists the true item split
+(finding 2).
+
+Revision 5 (PR #120 round 1, findings 1–4): accepting a
+`FileStyleSummary` on the GPU now drops the cached minimap vertices —
+theme recolors and diagnostic republishes arrive at an UNCHANGED
+generation, and the cache keys only on (generation, dims, scroll), so
+the stale strokes survived until an edit/resize/scroll; the daemon's
+payload-equality suppression makes the invalidation precise
+(finding 1). `lua_to_style` propagates every `Table::get` error: the
+lookups run `__index`, so a raising metatable previously parsed as an
+all-default style and the merge SUCCEEDED, committing its valid
+siblings against the Q#TH6 all-or-nothing contract; boolean fields
+deliberately keep Lua truthiness (mlua's `bool`), so only lookups
+that RAISE fail the transaction (finding 2). The producer is
+peer-version-aware: `SemanticRenderState::for_peer` records whether
+the peer negotiated >= 16, and below that no `ThemeFacts` is produced
+at all AND no `ui.diag.*` face is folded into the `FileStyleSummary`
+marks — that summary is an ungated pre-v16 channel, and a v15 peer
+must not get face-derived minimap colors while its squiggles, signs,
+and counters stay unthemed; the summary's cache key zeroes its
+face-epoch component for such peers so face edits don't trigger
+pointless whole-file recomputes (finding 3). And the "canonical
+severity color" claim is weakened to what is true: the
+daemon-RESOLVED color is canonical (TUI squiggle/marker/minimap and,
+when a face is set, all GPU surfaces), but the GPU's BUILT-IN
+defaults — bright RGB constants for squiggles/signs/counters vs the
+minimap's converted `Indexed(1/3/6/8)` — are a pre-existing
+divergence this arc keeps, because unset faces must render
+byte-identically to before (finding 4).
+
+Revision 4 (framing round 3, findings 1–7):
+`ui.minibuffer.candidate` now has a real GPU site: its `fg` colors the
+existing minibuffer-dropdown candidate glyph layer, while popup
+background/selection theming stays deferred; the mask is therefore a
+true intersection of both render paths (finding 1). The v15
+discriminant guard pins the byte encoding of `CompletionPopup`, the
+actual final pre-v16 variant, rather than the earlier `LineNumbers`
+variant (finding 2). The deterministic transactional bite now targets
+the production ordered-result helper: it consumes an iterator of
+`Result<(String, Style)>`, collects every result before taking the
+theme lock, and commits only the completed vector, so an `Ok` followed
+by an `Err` is both representable and guaranteed to leave the theme
+untouched (finding 3). An empty diagnostic child is named as an
+explicit reset to the built-in severity color, not as "unset" -- it
+blocks parent inheritance -- and acceptance covers a themed
+`ui.diag` parent plus an empty `ui.diag.error` child (finding 4). GPU
+acceptance now covers every distinct stage-1 route: modeline reverse,
+transient status text, minibuffer and isearch text, candidate-dropdown
+glyphs, normal/active search washes, and the existing gutter,
+selection, and diagnostic paths (finding 5). The prose and unset
+fixture use the exact `ui`-or-`ui.*` predicate (finding 6). Finally,
+the peer-selection acceptance drives the actual decoration collector
+with simultaneous local and peer selections and inspects their
+emitted colors; it is not a helper-only assertion (finding 7).
+
+Revision 3 (framing round 2, findings 1–9): the cross-frontend
+contract is structural now — every face carries a stage-1
+**component mask**, identical on both frontends and sized to what
+both can render today (the GPU gutter has no background layer; wash
+quads cannot recolor or reverse glyphs); out-of-mask components are
+ignored *everywhere*, so `ui.selection = { fg = 1 }` and
+`ui.gutter = { bg = 1 }` are component no-ops on the TUI too, and
+mask widening is a named, additive deferral (finding 1). Diag faces
+get a representable `Default` policy: `Default` fg means the
+built-in severity color, not "plain" — the minimap summary encodes
+diagnostic *presence* by copying that color into `underline_color`,
+where `Default` reads as "no mark", so an all-default diag face
+uses the built-in severity color rather than an unrepresentable plain mark
+(finding 2). The face predicate is explicit —
+`name == "ui" || name.starts_with("ui.")` — shared by the
+reservation, the counter-bump classification, and a merge-bare-`ui`
+acceptance case (finding 3). The consecutive-`set` bite interleaves
+render/observe between the mutations; two `set`s inside one dispatch
+legitimately coalesce into one emission (finding 4). Producer and
+gate caches advance on computation, not on emission:
+`last_face_epoch` is `Option<u64>` (the gate cannot short-circuit
+while the payload baseline is absent, guaranteeing the first
+authoritative send against an epoch-0 daemon), an identical rebuild
+records the epoch it inspected, and the summary inserts its new key
+even when payload equality withholds the message; Rust units pin
+single-recompute, which traffic assertions cannot see (finding 5).
+`SearchView::new` takes `Option<ThemeHandle>` — a bare core
+constructs an unthemed view, no contradiction (finding 6).
+`ThemeFacts` is appended after `CompletionPopup`, and a byte-level
+encoding pin of the final existing variant guards the placement — postcard
+discriminants are ordinal, and the new variant's own round-trip
+cannot detect a shift that would corrupt v15 peers (finding 7). The
+malformed-merge Lua acceptance pins only the order-independent user
+contract; the deterministic bite is a Rust unit on an ordered result
+stream, since Lua table iteration order is unspecified
+(finding 8). `ui.selection` themes the local selection only: the
+GPU splits its resolution path so peer selection rects keep the
+constant, and peer theming stays deferred with the peer-cursor
+palette (finding 9).
+
+Revision 2 (framing round 1, findings 1–8): the theme mutation
+contract is transactional and monotonic — all four mutators parse
+and validate their full input before taking the lock, commit
+all-or-nothing, and bump from the prior counter value after every
+successful commit; `set` replaces the `by_capture` field, never the
+`Theme` value, so counters survive wholesale replacement (finding 1).
+The counter is split into `syntax_epoch` (keys the `StyleGate`) and
+`face_epoch` (keys the `ThemeFacts` producer), so a face-only edit
+never re-runs the tree-sitter span query; the minimap summary keys on
+both — diag faces feed its marks — and gains payload-equality
+suppression, so a non-diag face edit recomputes once per mutation and
+emits nothing (finding 8). Stage 2 takes protocol v17: once a v16
+binary ships, a variant added under v16 would let two incompatible
+v16 schemas negotiate successfully (finding 2). Face application is
+unified as "a set face owns its surface" — both frontends replace
+the site default wholesale, with `Default` components meaning that
+frontend's *plain* rendering (GPU mapping table in Q#TH5); the
+finding-5 divergences (`{ fg }` keeping the GPU band bg, empty
+`ui.selection` diverging) are gone, and the residual divergences
+(`Indexed` palette meaning; GPU chrome honoring fg/bg/reverse only in
+stage 1) are named and tested. `ThemeFacts` is authoritative per
+attachment: the baseline seeds to `None`, every attachment receives
+exactly one table — empty included — after viewport declaration, so
+a frontend retaining face state across attachments is corrected even
+by an unthemed daemon (finding 4; the current GPU has no reconnect
+path, so this is contract, not accident). GPU ThemeFacts application
+invalidates the status-band shaping cache — `E:`/`W:` colors are
+baked into shaped rich text and re-shaping is gated on string
+equality, so a diag-face change with constant counts kept stale
+colors (finding 3). The grid views get a real theme path:
+`EditorCore` gains an injected `ThemeHandle` for
+`ensure_search_overlay`, and `install_diag` threads the handle to
+`DiagnosticView`; acceptance drives the dispatched-search and Lua
+diagnostic-attachment paths, not bare constructors (finding 6). The
+reserved namespace covers the bare root `ui` as well as `ui.*`,
+matching the inheritance walk's terminal (finding 7). Acceptance
+adds consecutive-`set` monotonicity, malformed-merge atomicity, GPU
+diag-recolor-with-constant-counts, owns-surface cross-frontend
+semantics, and absence assertions for face-only mutations.
+
+Revision 1: initial framing.
+
+Arc 4 ("Themes + extensibility surface", `docs/roadmap-2026-07.md:83`)
+names three deliverables: named UI faces wired to both frontends, a
+`pmacs.gpu.set_font` runtime font swap, and a Lua statusline-segment
+API. This framing covers **stage 1 only — named UI faces plus the
+`ThemeFacts` wire channel (protocol v15→16)**. Font swap and
+statusline segments are stages 2 and 3, each with its own framing
+(Q#TH1). One branch (`theme-faces`), one PR.
+
+## Ground truth (as of `13dbadd`)
+
+### The theme substrate today
+
+- `Theme { by_capture: HashMap<String, Style>, default_style: Style }`
+  — `src/highlight.rs:59-67`. One global instance behind
+  `ThemeHandle = Arc<Mutex<Theme>>` (`highlight.rs:190`), owned by the
+  `SyntaxRegistry` (`src/syntax.rs:496`, seeded `Theme::default_dark()`
+  at `:518`, exposed via `.theme()` at `:527`; line refs re-verified
+  after the #114/#115/#116 highlight-stack merges, whose bundled CUDA
+  and shell grammars introduce no `ui`-named capture).
+- `Theme::lookup` (`highlight.rs:161-172`) tries the full dotted name,
+  strips one `.`-segment at a time, and **falls back to
+  `default_style`** — correct for syntax captures, wrong for faces
+  (an unset face must mean "keep today's hardcoded look", which is
+  not expressible as a `Style` on the semantic path).
+- Lua surface is complete and mounted: `pmacs.theme.{set, merge, get,
+  clear, default, current}` — `src/lua_bindings/mod.rs:6898-6993`.
+  `set` replaces `by_capture` wholesale but preserves `default_style`
+  (`:6913-6915`). Style/color marshalling: `lua_to_style` `:6865`,
+  `lua_to_color` `:6780` (nil/"default" → `Color::Default`, 0..=255 →
+  `Indexed`, `{r,g,b}` → `Rgb`).
+- Mutator shapes today: `set` parses the whole table into a scratch
+  `Theme` *before* locking, then wholesale-replaces the locked value
+  (`:6906-6915`) — already transactional, but the replacement would
+  reset any naive counter carried on `Theme`. `merge` locks first and
+  inserts while iterating (`:6925-6931`) — a malformed later entry
+  errors out with earlier entries already applied.
+- Wire vocabulary already suffices: `Color { Default, Rgb, Indexed }`
+  and `Style { fg, bg, bold, italic, underline, reverse,
+  underline_color }` — `pmacs-protocol/src/cell.rs:84-133`. No alpha
+  channel (relevant for GPU washes, Q#TH8).
+- Theme colors already cross the wire *indirectly*: `scoped_style_spans`
+  (`src/semantic_render.rs:1501-1566`) clones the theme, resolves
+  capture → `Style`, and ships `StyleSpans`. Nothing chrome-related
+  crosses at all.
+
+### Chrome colors today — every one a hardcoded literal
+
+Grid path (daemon paints cells for the TUI; `paint_frame`,
+`src/editor.rs:2086`, has `&EditorState` and therefore theme access):
+
+| Site | Where | Literal |
+|---|---|---|
+| Per-window mode line | `editor.rs:2474` (`paint_mode_line`) | `reverse: true` (`:2499-2502`) |
+| Status/echo row | `editor.rs:2260` (`paint_status_line`) | `reverse: true` (`:2275-2286`) |
+| Line-number gutter | `editor.rs:2320` | `fg: Indexed(8)` (`:2332-2335`) |
+| Selection | `editor.rs:2375` | `cell.style.reverse = true` (`:2431`) |
+| Minibuffer prompt/input/fill | `editor.rs:2541` | `Style::default()` (`:2571`, `:2588`, `:2613-2617`) |
+| Minibuffer candidate suffix | `editor.rs:2605-2608` | `reverse: true` |
+| Search prompt row | `editor.rs:2629` | `Style::default()` (`:2659`, `:2677`) |
+| Search matches | `src/search.rs:362-378` | bg `Indexed(3)`/fg `Indexed(0)`; active bg `Indexed(11)` |
+| Diagnostic severity color | `src/diag.rs:90-97` | `Indexed(1)/(3)/(6)/(8)` — shared by squiggle `underline_color`, column-0 marker, minimap mark |
+
+GPU path (frontend-local constants, `pmacs-gpu/src/main.rs`):
+
+| Site | Where | Literal |
+|---|---|---|
+| Status band bg | `:130` | `STATUS_BAND_BG [0.105, 0.105, 0.145, 1.0]` |
+| Band left text (name/prompt) | `:4511` | `rgb(200,200,210)` |
+| Band right readout | `:4496` | `rgb(168,168,180)` |
+| Band `E:`/`W:` counters | `:3401`, `:3407` | `rgb(241,76,76)`, `rgb(245,245,67)` |
+| Gutter digits | `:4534` | `rgb(120,120,135)` |
+| Selection wash | `:6661` | `[0.31, 0.42, 0.82, 0.30]` |
+| Search washes | `:6673-6674` | `[0.85,0.78,0.20,0.30]`, `[0.95,0.55,0.12,0.48]` |
+| Diag squiggles/signs | `:6606-6623` | Error `[0.945,0.298,0.298]`, Warning `[0.961,0.961,0.263]`, Info `[0.231,0.557,0.918]`, Hint `[0.4,0.4,0.4]` |
+| Surface clear / caret / menu / minimap | `:61-66`, `:73-74`, `:145-147`, `:111-114` | out of stage-1 scope (Deferred) |
+
+`Indexed` colors mean different things per frontend: the TUI defers
+to the user's terminal palette; the GPU has its own hardcoded xterm
+table (`indexed_to_glyphon`, `main.rs:6552-6587`). A face set with
+`Indexed` colors will render per-frontend, same as syntax styles do
+today — documented, not fixed here (Deferred).
+
+### The facts-channel template (LineNumbers, Q#UX1)
+
+- `PROTOCOL_VERSION = 15` (`pmacs-protocol/src/message.rs:1333`);
+  `SUPPORTED_PROTOCOL_VERSIONS = [6..=15]` (`:1393`). Standard bump
+  shape: additive variant + daemon write-loop gate on
+  `negotiated_protocol_version` (`src/daemon.rs:1119-1121`,
+  `:1153-1157`); old peers receive nothing on the channel.
+- Producer pattern: cached-compare field on `SemanticRenderState`,
+  emit-on-change from `render_frame`'s emission list
+  (`src/semantic_render.rs:462-478`; `line_numbers_msg` `:810-825`).
+  Nothing emits before the frontend declares a viewport (`:307-310`).
+- Late join is free: per-session state is built fresh at attach
+  (`daemon.rs:1377-1381`), and a baseline seeded to the *frontend's
+  default belief* re-emits exactly the non-default state
+  (`semantic_render.rs:265-269`). `InlineAdornments` additionally
+  suppresses "nothing to say, nothing ever sent" (`:297-304`).
+- TUI drops the whole family silently (`src/frontend.rs:380-422`) —
+  its chrome arrives pre-painted in the cell grid.
+- Pin tests updated every bump: `assert_eq!(PROTOCOL_VERSION, …)` at
+  `src/protocol.rs:1710`, the resume-ladder test at `:1774-1797`
+  (accepted range and the rejected next version), and a postcard
+  round-trip pin per new variant.
+- The dormant `InstanceMessage::ModeLine(Vec<Cell>)` (`message.rs:506`)
+  is cell-shaped, unproduced, and not what this arc needs; it stays
+  dormant.
+
+### Pre-existing staleness bug (this arc fixes it)
+
+`StyleGate` (`semantic_render.rs:226-246`) keys the `StyleSpans`
+recompute on (parse-bundle `Arc`, CRDT generation, viewport) — never
+the theme. `file_style_summary_msg` similarly keys the minimap
+summary on `(generation, diag_epoch)` (`:914`). A mid-session
+`pmacs.theme.set` therefore re-ships **nothing** to a semantic
+frontend until the next buffer edit: the GPU keeps stale colors. The
+grid path is immune (`SyntaxHighlightView` clones the theme every
+render, `highlight.rs:316`), as is the ungated LSP-token span path.
+There is no theme mutation counter anywhere in `src/`. Q#TH6
+introduces two (syntax/face) and folds them into the gates.
+
+## Decisions
+
+### Q#TH1 — Scope: stage 1 of Arc 4; faces + wire only
+
+This PR delivers named UI faces resolved daemon-side, applied by both
+frontends, controlled through the existing `pmacs.theme` surface, and
+shipped to semantic frontends over a new v16 `ThemeFacts` channel.
+`pmacs.gpu.set_font` (stage 2) and the statusline-segment API
+(stage 3) are deferred with named hooks: **stage 2 takes protocol
+v17** — once a v16 binary exists, adding another variant under v16
+would let old and new v16 peers negotiate successfully despite
+incompatible schemas (postcard is not self-describing); reusing 16
+is possible only if stage 2's wire shape lands in this same PR,
+which it does not. The segment API lands after faces so segments can
+carry face names instead of raw colors.
+
+### Q#TH2 — Faces are theme entries under the reserved `ui` / `ui.*` namespace
+
+A face is an entry in the existing `by_capture` map whose name is
+exactly `ui` or starts with `ui.` -- no new type, no second map, no new
+Lua API.
+`pmacs.theme.merge { ["ui.modeline"] = { bg = 236, fg = 252 } }`
+works today, unmodified. The face predicate is one explicit
+function, used by every consumer — the docs reservation, Q#TH6's
+counter-bump classification, and the producer's key filter:
+
+```rust
+fn is_face_name(name: &str) -> bool {
+    name == "ui" || name.starts_with("ui.")
+}
+```
+
+The bare root `ui` is included because Q#TH4 makes it the walk's
+deliberate catch-all — a `merge { ui = … }` must bump `face_epoch`
+and emit `ThemeFacts`, not disappear into the syntax path. No
+tree-sitter capture or LSP token type is named `ui` or `ui.*`
+(verified against `default_dark` and the grammar queries).
+`pmacs.theme.get("ui.x")` keeps its
+existing `lookup` semantics (resolves through to `default_style`) —
+introspection tolerates that; rendering does not (Q#TH4).
+
+### Q#TH3 — Stage-1 face inventory: twelve faces
+
+The roadmap's five surfaces, plus the two chrome families that
+already have daemon-side palettes (search, diagnostics), plus the
+minibuffer's one sub-face. Effects per frontend (unset = exactly
+today's literal, from the Ground-truth tables):
+
+The **mask** column is the stage-1 component contract of Q#TH5:
+identical on both frontends, sized to what both can render today.
+
+| Face | Mask | Grid/TUI effect | GPU effect |
+|---|---|---|---|
+| `ui.modeline` | fg bg reverse | per-window mode-line row | status-band bg quad; band name + readout text |
+| `ui.statusline` | fg | bottom status/echo row | echo-message segment text |
+| `ui.minibuffer` | fg | prompt + input + fill; search prompt row | minibuffer/isearch band text |
+| `ui.minibuffer.candidate` | fg | inline candidate suffix | minibuffer-dropdown candidate glyphs |
+| `ui.gutter` | fg | line-number strip | gutter digit text |
+| `ui.selection` | bg | local-region cells (wash) | local-selection wash RGB |
+| `ui.search.match` | bg | lazy-match cells (wash) | match wash RGB |
+| `ui.search.match.active` | bg | active-match cells (wash) | active wash RGB |
+| `ui.diag.error` | fg† | severity color | squiggle + gutter sign + band `E:` counter |
+| `ui.diag.warning` | fg† | severity color | squiggle + sign + `W:` counter |
+| `ui.diag.info` | fg† | severity color | squiggle + sign |
+| `ui.diag.hint` | fg† | severity color | squiggle + sign |
+
+† diag faces carry the special `Default` policy of Q#TH5: `Default`
+fg means the built-in severity color, not "plain".
+
+The GPU status band is the mode-line analogue (one band, no separate
+echo row — a structural divergence this arc does not resolve), so it
+takes `ui.modeline` for its surface and `ui.statusline`/`ui.minibuffer`
+only for the text of the corresponding *content* it happens to be
+showing. `ui.minibuffer.candidate` colors the existing dropdown's
+candidate glyphs only; its background and selected-row quad remain
+popup chrome. Deliberately excluded from stage 1 (all named in Deferred):
+popup/menu/completion-dropdown backgrounds and selection quads,
+completion/menu glyph faces, `ui.background`, `ui.caret`,
+`ui.modeline.inactive`, minimap chrome, peer-cursor palette,
+inlay-hint face.
+
+### Q#TH4 — Resolution: `Theme::face()`, `None` when unset, never `default_style`
+
+New method on `Theme`:
+
+```rust
+pub fn face(&self, name: &str) -> Option<Style>
+```
+
+Same dotted-prefix walk as `lookup`, but the walk returns `None` when
+nothing matches instead of falling back to `default_style` — an
+unset face must leave the paint site's hardcoded default untouched,
+and a user's `pmacs.theme.default` (a *syntax* fallback) must never
+bleed into chrome. The walk gives inheritance for free:
+`ui.search.match.active` falls back to `ui.search.match`, the four
+`ui.diag.*` to `ui.diag`, and everything to a deliberate catch-all
+`ui` (a theme can tint all chrome in one entry; a consequence of
+uniform walk semantics, not a special case). Callers pass full face
+names only.
+
+### Q#TH5 — A set face owns its surface, within its component mask
+
+Wire `Style` cannot distinguish an omitted component from an
+explicitly-requested default, so per-component fallback to the
+site's old literal would diverge across frontends (`ui.modeline =
+{ fg = 252 }` would drop the TUI's reverse video while the GPU kept
+its band background; an empty `ui.selection` would disable the TUI
+wash but leave the GPU wash intact). And an unmasked wholesale rule
+is not implementable either: the GPU gutter has only a foreground
+text layer (`main.rs:4522`), and the selection/search washes are
+background quads that can neither recolor nor reverse glyphs
+(`main.rs:4801`) — an unrestricted contract would make
+`ui.selection = { fg = 1 }` recolor TUI glyphs with no GPU
+counterpart. The unified rule:
+
+- **Unset face** (resolution `None`): the site's hardcoded default,
+  both frontends, byte-identical to today.
+- **Set face**: the surface resets to plain, and the face's
+  components **within the face's mask** (the Q#TH3 table) apply.
+  Components outside the mask are ignored on BOTH frontends — the
+  mask is the cross-frontend contract, sized to the intersection of
+  what the two render paths can express today, so equivalence is
+  structural rather than aspirational. `ui.selection = { fg = 1 }`
+  is a component no-op on the TUI too (an effectively-empty wash
+  face: wash disabled on both); `ui.gutter = { bg = 1 }` likewise
+  renders as an all-default gutter face on both. Widening a mask
+  later (GPU gutter background layer, wash glyph recolor/reverse,
+  chrome bold/italic/underline) is additive and named in Deferred.
+- **`Default` within the mask** means *that frontend's plain
+  rendering*, never "the old chrome look". On the TUI, plain =
+  terminal defaults. On the GPU, a fixed mapping: `Default` fg ↦
+  the buffer-text default `rgb(230,230,235)` (`main.rs:4482`);
+  `Default` bg ↦ the window background (an untinted band quad; no
+  wash quad); `reverse` (in-mask only for `ui.modeline`) swaps
+  fg/bg after the mapping. `ui.modeline = { fg = 252 }` therefore
+  yields "plain background, color-252 text" on both frontends, and
+  `ui.selection = {}` disables the selection wash on both —
+  consistent, if deliberately drab; the user asked for an
+  all-default surface.
+- **Wash faces** (`ui.selection`, `ui.search.match`,
+  `ui.search.match.active`) remain a *composition* class: the
+  masked face style (bg only, stage 1) replaces the default
+  **overlay** argument of the existing `merge_styles(cell, overlay)`
+  (`src/overlay.rs:136` — non-`Default` components win, booleans
+  OR), then merges over syntax-styled cells as today, so a wash
+  never touches glyph fg in stage 1. The unset defaults remain the
+  full overlay literals of today (`Style { reverse: true, .. }` for
+  selection; the search literals as-is — the mask constrains *face*
+  application, not the unset defaults). On the GPU the wash quad
+  takes the face `bg` RGB with the site's current alpha — wire
+  `Style` has no alpha; translucency is a rendering choice and
+  stays frontend-local (Q#UX1 division).
+- **`ui.selection` themes the local selection only.** The GPU
+  currently colors peer selection rects through the same
+  `DecorationKind::Selection` helper (`main.rs:4946`); the
+  implementation splits that resolution path — the local path
+  resolves the face, the peer path keeps the constant — so peer
+  rendering stays outside the theme system until the deferred
+  peer-cursor palette arc. (The TUI peer path, `overlay_paint.rs`,
+  is already separate.)
+- **`ui.minibuffer.candidate` has one GPU effect in stage 1:** its
+  masked `fg` is the `default_color` of the existing minibuffer
+  dropdown candidate `TextArea` (`main.rs:4594-4610`). This does not
+  theme the popup background or selected-row quad; those remain on
+  their current constants and in Deferred. On the grid path the same
+  face colors the inline selected-candidate suffix.
+- **Diag faces**: the `fg` component is the canonical severity color
+  (the `diag.rs:84-97` contract: squiggle `underline_color`, marker,
+  minimap mark all share it), with a face-family-specific `Default`
+  policy: **`Default` fg means the built-in severity color**, not
+  plain. The severity color doubles as the *presence* encoding in
+  the minimap summary — `scoped_file_summary` copies it into the
+  line's `underline_color` (`semantic_render.rs:1779`), and the GPU
+  reads `underline_color == Default` as "no diagnostic mark"
+  (`main.rs:5551`) — so a plain severity color is unrepresentable
+  and `ui.diag.error = {}` explicitly resets that child to the
+  built-in error color on every surface (squiggle, sign, minimap, band
+  counter). It is not absent: an exact empty child stops Q#TH4's walk,
+  so it overrides an inherited `ui.diag` color with the built-in.
+  Scope of "built-in" (round 1 finding 4): a SET face with a concrete
+  color unifies all surfaces on both frontends, but the per-surface
+  built-in DEFAULTS keep their pre-existing values — the TUI and the
+  wire summary use `Indexed(1/3/6/8)`, while the GPU's squiggle,
+  sign, and counter constants are historical bright RGBs that differ
+  from the minimap's converted `Indexed` marks. That divergence
+  predates this arc and stays, because unset faces must render
+  byte-identically to before.
+
+Residual divergence, accepted and tested: `Indexed` colors mean the
+user's terminal palette on the TUI and the `indexed_to_glyphon`
+table on the GPU (pre-existing; identical to syntax styles today).
+
+### Q#TH6 — Two monotonic mutation counters; transactional mutators
+
+`Theme` gains `syntax_epoch: u64` and `face_epoch: u64` (both 0 at
+construction), owned by the same mutex. The mutation contract for
+the four Lua bindings — the only mid-session mutation paths:
+
+1. **Parse before locking.** The production `set`/`merge` transaction
+   helper accepts a commit mode plus an ordered iterator of
+   `mlua::Result<(String, Style)>`, collects the whole iterator into
+   `mlua::Result<Vec<(String, Style)>>`, and only after `Ok(Vec)`
+   acquires the theme mutex and commits in the requested mode. The Lua
+   table iterator maps each raw `(name, style_table)` entry through
+   `lua_to_style` into that result stream — whose own lookups
+   PROPAGATE errors (round 1 finding 2): `Table::get` runs `__index`,
+   so a raising metatable fails the transaction rather than silently
+   parsing as an all-default style; boolean fields keep Lua
+   truthiness by design. `default` parses its one
+   `Style` before locking; `clear` has no input to parse. `set`
+   already parses into a scratch value pre-lock; `merge` today
+   inserts while iterating under the lock (`mod.rs:6925-6931`), so a
+   malformed later entry currently leaves earlier entries applied —
+   that shape is disallowed.
+2. **Commit all-or-nothing.** Every entry applies, or the binding
+   errors with the theme untouched (and therefore no counter bump
+   and no downstream emission).
+3. **Bump from the prior value after every successful commit.**
+   `set` replaces the `by_capture` *field* — never `*theme =
+   new_theme`, whose zeroed counters would let consecutive `set`
+   calls share an epoch and stay invisible to every gate — then
+   bumps; counters only ever increment. Per mutator: `set` and
+   `clear` bump both counters; `merge` classifies every committed
+   key through `is_face_name` (Q#TH2 — bare `ui` is a face key) and
+   bumps `syntax_epoch` iff any non-face key committed, `face_epoch`
+   iff any face key did; `default` bumps `syntax_epoch` only.
+
+Consumers:
+
+- `StyleGate` gains a `syntax_epoch` field, compared in `matches()`
+  — a capture recolor forces the tree-sitter span recompute and the
+  changed spans ship (the fix for the pre-existing GPU staleness
+  bug, bite-able on its own: mid-session `pmacs.theme.set` with no
+  buffer edit must produce a `StyleSpans` re-emission). A face-only
+  edit leaves `syntax_epoch` untouched and never re-runs the query.
+- `file_style_summary_msg`'s cache key becomes `(generation,
+  diag_epoch, syntax_epoch, face_epoch)` — `face_epoch` belongs in
+  the key because `ui.diag.*` feeds the minimap marks — **plus a
+  payload-equality suppression**: a face edit that leaves the
+  summary unchanged (e.g. `ui.modeline`) recomputes it once per
+  mutation, not per tick, and emits nothing. The cache key advances
+  on *computation*, not on emission — the suppressed send still
+  inserts the new key, or the recompute repeats every tick and the
+  performance contract is a fiction. Rust units pin the
+  single-recompute (by asserting the advanced cache state); traffic
+  assertions cannot see repeated computation.
+- The `ThemeFacts` producer gates on `face_epoch` (Q#TH7).
+
+The LSP-token span path and the whole grid path already re-resolve
+per tick/frame and need nothing.
+
+### Q#TH7 — `ThemeFacts` channel: bufferless resolved-face table, protocol v15→16
+
+```rust
+/// Themes arc (Q#TH7, protocol v16). The daemon-resolved UI faces.
+/// The theme is one global instance, so this is bufferless (the
+/// `MinibufferPrompt` shape). Complete replacement each send: a
+/// face absent from `faces` is unset, and the frontend uses its
+/// own default for that surface. Cached-compare suppressed;
+/// daemon-gated `>= 16`.
+ThemeFacts {
+    /// Every stage-1 face that resolves to a style (Q#TH4 walk),
+    /// full names, sorted by name for deterministic comparison.
+    faces: Vec<ThemeFace>,
+},
+
+pub struct ThemeFace {
+    pub name: String,
+    pub style: crate::cell::Style,
+}
+```
+
+- **Resolution is daemon-side**: the producer walks the known face
+  list (the Q#TH3 twelve) through `Theme::face()` and ships concrete
+  entries — frontends do exact-name lookup, no walk, no inheritance
+  logic. The daemon owns face semantics; frontends own pixels
+  (Q#UX1). No epoch on the wire — the payload is self-contained and
+  the house facts style carries no counters.
+- **The producer is peer-version-aware** (round 1 finding 3):
+  daemon sessions construct via `SemanticRenderState::for_peer`, and
+  below v16 no `ThemeFacts` is produced at all — more importantly,
+  no `ui.diag.*` face is folded into the `FileStyleSummary` marks,
+  because that summary is an ungated pre-v16 channel and a v15 peer
+  must not receive face-derived minimap colors while its squiggles,
+  signs, and counters stay unthemed. The write-loop gate remains as
+  the belt-and-braces filter. The summary cache key zeroes its
+  face-epoch component for such peers (no whole-file recompute per
+  face edit that could never change their marks).
+- **Producer**: `theme_facts_msg` on `SemanticRenderState`, called
+  from the `render_frame` emission list. Per-tick cheapness comes
+  from a `last_face_epoch: Option<u64>` gate **seeded `None`** —
+  `Option`, not a bare zero, because an unthemed daemon sits at
+  `face_epoch == 0` and a `0 == 0` short-circuit would starve the
+  first authoritative send; the gate can only short-circuit once it
+  has recorded an inspected epoch. Emission truth comes from
+  comparing the rebuilt table against `last_theme_faces`, also
+  seeded `None`. Both records advance on *computation*: an
+  identical rebuild (e.g. after a payload-equal re-merge) records
+  the epoch it inspected even though nothing ships, so subsequent
+  ticks skip — a Rust unit pins the no-rebuild second tick. Every
+  attachment receives exactly one authoritative table — the empty
+  table included — with its first emission after viewport
+  declaration, cached-compare suppressed thereafter. One small
+  message per unthemed session buys a reconnect-safe contract: a
+  frontend that retains face state across attachments is corrected
+  even by an unthemed daemon, instead of depending on every frontend
+  starting empty. (The current GPU has no reconnect path — a
+  disconnect only swaps the displayed text, `main.rs:1435` — so this
+  is contract, not a load-bearing assumption about today's client.)
+- **Variant placement**: `ThemeFacts` is **appended after
+  `CompletionPopup`** (`message.rs:961`), the current final
+  `InstanceMessage` variant. Postcard discriminants are ordinal — a
+  variant inserted earlier shifts every later variant's tag and
+  silently corrupts v15 peers on channels that are *not* gated, and
+  the new variant's own round-trip test cannot detect the shift. A
+  byte-level encoding pin of `CompletionPopup` -- the final existing
+  variant, so any insertion before any v15 variant moves its ordinal --
+  asserts its serialized bytes, discriminant included, are unchanged
+  by the v16 build.
+- **Gating**: `PROTOCOL_VERSION` 15→16 with a ladder paragraph;
+  `SUPPORTED_PROTOCOL_VERSIONS` grows 16; daemon write-loop
+  `peer_knows_theme_facts = negotiated_protocol_version >= 16` +
+  skip arm; TUI silent-drop arm (`frontend.rs:380-422`); GPU
+  debug-name arm (`main.rs:5606-5628`); `ThemeFace` re-exported from
+  `pmacs-protocol/src/lib.rs`; pin tests at `protocol.rs:1710` and
+  the ladder test (accept 16, reject 17); postcard round-trip pin.
+- **Snapshot/baseline reset contract** (round 2 finding 1): a
+  `BufferSnapshot` resets the receiving frontend's buffer-scoped
+  render state wholesale, so wherever the daemon writes one it calls
+  `SemanticRenderState::on_buffer_snapshot_sent(buffer_id)`, killing
+  every buffer-scoped emission baseline for that buffer — spans +
+  style gate, decorations, adornments, summary, status, search/menu
+  prompts, completion popup. Without this, an unchanged-generation
+  A → B → A round trip suppressed every re-send and the frontend
+  never regained A's themed minimap or `StatusFacts`. Call sites:
+  the active-buffer-follow path and the F29 upgrade broadcast; the
+  attach bootstrap constructs its session state fresh, so its sweep
+  needs no call. NOT reset: `last_face_epoch` / `last_theme_faces`
+  (this channel is bufferless — the frontend keeps its face table
+  across snapshots), the global minibuffer baseline, the
+  per-frontend gutter mode, the revision-keyed diag line cache, and
+  other buffers' baselines (each buffer's own snapshot precedes its
+  revisit). The diagnostic-count freeze needs no protection here
+  (rounds 3–4): it is sourced from the diag store's retained vector
+  and its cached per-URI severity tuple — `mark_stale` keeps the last
+  published diagnostics and counts, which merely lag — never from
+  session state, so the reset cannot zero mid-edit counts and the
+  freeze holds even for a session attaching during staleness. The
+  producer reads the tuple in O(1), rather than scanning the retained
+  vector for every semantic session at frame cadence (round 5).
+  Resetting on a failed write is harmless — the
+  failure mode is one redundant re-send, never staleness. The GPU's `BufferSnapshot` arm mirrors the contract
+  (round 3 finding 1): it clears its buffer-scoped facts —
+  search/menu popups (which gate key and pointer interception) and
+  the status band — alongside spans, decorations, adornments,
+  summary, and the completion popup; the minibuffer survives on
+  both sides.
+- `docs/semantic-frontend-protocol.md` gains the channel's contract
+  section.
+
+### Q#TH8 — GPU application: exact-name map, Q#TH5 mapping, shaping-cache invalidation
+
+`State` gains `faces: HashMap<String, Style>`; the
+`apply_attach_message` arm replaces the map, **invalidates the
+status-band shaping cache**, and `request_redraw()`s (extending the
+`LineNumbers` arm shape, `main.rs:2686-2692`). The invalidation is
+load-bearing, not belt-and-braces: the `E:`/`W:` counter colors are
+baked into glyphon rich-text attributes at compose time
+(`compose_status_spans`, `main.rs:3390-3441`), and
+`refresh_status_line` skips re-shaping whenever the composed strings
+are unchanged (`main.rs:3502-3546`) — without clearing those cached
+comparison strings, a diag-face change with constant counts keeps
+stale counter colors indefinitely.
+
+A newly accepted `FileStyleSummary` drops the cached minimap
+vertices (round 1 finding 1): theme recolors and diagnostic
+republishes ship a new summary at an UNCHANGED generation, and the
+minimap cache keys only on (generation, dims, scroll) — without the
+explicit invalidation the stale strokes survive until an edit,
+resize, or scroll. The daemon payload-suppresses identical
+summaries, so every accepted one is genuinely new.
+
+Each themed site resolves per draw with the Q#TH5 rule: face absent
+→ today's site constant; face present → the face's **in-mask**
+components, with `Default` fg ↦ the buffer-text default, `Default`
+bg ↦ the window background (untinted quad / no wash quad),
+`reverse` (`ui.modeline` only) as a post-map swap, and the diag
+`Default`-fg ↦ built-in-severity-color policy. Out-of-mask
+components are never read. `Rgb` maps directly; `Indexed` through
+the existing `indexed_to_glyphon` table; quad colors convert u8 RGB
+into the same color space the current float constants use;
+band/wash alphas keep their current values. Peer selection rects
+resolve through the split constant path, never the face (Q#TH5).
+The minibuffer candidate face supplies the existing dropdown
+`TextArea.default_color`; `refresh_mb_buffer` already runs before each
+dropdown paint (`main.rs:4337-4341`), and the default color is resolved
+again when preparing the `TextArea`, so no new shaping-cache contract is
+needed for its fg-only mask.
+
+### Q#TH9 — Grid application: one theme clone per frame; views gain the handle
+
+`paint_frame` clones the `Theme` once per frame (single mutex lock,
+same discipline as `SyntaxHighlightView::render`) and passes `&Theme`
+down to `paint_mode_line` / `paint_status_line` / `paint_minibuffer` /
+`paint_search_prompt` / `paint_line_number_gutter` /
+`paint_local_selection` (signature additions; `paint_mode_line` takes
+the resolved `Style` since it is a pure formatter). `SearchView` and
+`DiagnosticView` gain a `ThemeHandle` constructor parameter and
+resolve faces under the lock per render — the exact
+`SyntaxHighlightView::new` precedent (`highlight.rs:246`).
+
+Ownership, named: `SearchView` is constructed inside
+`EditorCore::ensure_search_overlay` (`src/editor_core.rs:858`), and
+`EditorCore` owns no syntax state — so `EditorCore` gains a
+`theme: Option<ThemeHandle>` field, injected once at editor bring-up
+right after `SyntaxRegistry` construction, and
+`SearchView::new(store, theme: Option<ThemeHandle>)` takes the
+`Option` directly: `ensure_search_overlay` passes the field through
+unconditionally, so a bare core (unit-test construction, field
+`None`) still constructs a working view that resolves no faces and
+paints today's literals — no contradiction between "views take the
+handle" and "bare cores have none". `DiagnosticView`
+is attached by the Lua path — `install_diag`
+(`src/lua_bindings/diag.rs:46`, construction at `:220`) — which gains
+the handle as a parameter, threaded from the installer call site
+(`mod.rs:8626`). Acceptance exercises the real attachment paths: a
+dispatched `C-s` reaching `ensure_search_overlay`, and the Lua
+diagnostic attachment — never bare constructors. The completion
+popup and menu keep their literals (faces deferred).
+
+### Q#TH10 — `pmacs.theme.set` wholesale semantics include faces
+
+`set` replaces the whole `by_capture` map today and therefore wipes
+faces along with captures; `merge` is the incremental path. This is
+kept unchanged — a "theme" legitimately includes its chrome, and a
+theme-switching user wants no stale faces from the previous theme.
+Documented in the Lua API docs alongside the `ui.` namespace
+reservation.
+
+## Bets
+
+- The reserved-namespace design (Q#TH2) means zero new Lua API and
+  zero protocol vocabulary beyond one variant — the whole feature
+  rides existing `Style` plumbing.
+- The authoritative-per-attachment contract (seed `None`) makes
+  late-join and stateful reconnect correct by construction for the
+  price of one small message per session; unthemed steady-state
+  traffic remains zero.
+- Daemon-side resolution keeps both frontends walk-free and makes
+  face inheritance testable in one place.
+- The split-counter fix (Q#TH6) closes the mid-session staleness bug
+  at one-u64-compare per-tick cost, while face-only edits stay off
+  the tree-sitter path entirely; the one whole-file summary
+  recompute per face mutation is user-action-rate, not tick-rate.
+- The owns-surface-within-mask rule (Q#TH5) is the only semantic
+  expressible with the existing `Style` (no omitted-vs-default
+  distinction) that renders equivalently on both frontends, and the
+  masks make that equivalence structural — the contract promises
+  only what both render paths can draw today, and widening a mask
+  later is additive. Its cost — partial faces reset the rest of
+  their surface to plain, and some components are simply not
+  themable yet — is documented and falls only on users who theme.
+- Unset faces reproduce today's rendering byte-identically on both
+  frontends — the acceptance baseline tests pin this, so shipping
+  stage 1 changes nothing for users who theme nothing.
+- Twelve faces cover the roadmap's named surfaces; the deferred
+  chrome (popups, background, caret) reuses the same substrate
+  without another protocol bump.
+
+## Deferred (named)
+
+Popup/menu/completion-dropdown background, selected-row, and general
+glyph faces (`ui.popup`, `ui.menu`, …; the fg-only
+`ui.minibuffer.candidate` exception is in scope);
+`ui.background` and `ui.caret` (GPU-only effect; background interacts
+with the TUI's terminal-default philosophy and deserves its own
+decision); `ui.modeline.inactive` (active/inactive split);
+minimap chrome faces; peer-cursor palette theming
+(`overlay_color.rs` — deliberately not on the wire today);
+inlay-hint face (`ui.inlay_hint` — `semantic_render.rs:1137` names
+the gap; its adornment producer needs the same epoch treatment when
+it lands); alpha on the wire (washes keep frontend-local alpha until
+a real theme needs to change it); unifying `Indexed` palette meaning
+across frontends; named-theme registry / light-theme builtin /
+persistence (no unified config surface yet — handoff §6); the
+grid-vs-wire `default_style` asymmetry (uncaptured text: wire ships
+nothing where the grid paints the base style — orthogonal to faces);
+mask widening (GPU gutter background layer; wash glyph
+recolor/reverse; a distinct GPU echo surface so `ui.statusline`
+could carry bg; chrome bold/italic/underline — attribute re-shaping
+that compounds the Q#TH8 shaping-cache invalidation);
+`ui.selection` for peer selections (rides the deferred peer-cursor
+palette; the GPU resolution path is already split);
+`pmacs.gpu.set_font` (stage 2,
+**protocol v17** per finding 2 — and the `pmacs-gpu-design.md:299`
+claim that font customization needs no wire change is superseded by
+the Q#UX1 lesson, to be corrected in that framing); Lua
+statusline-segment API (stage 3 — should ship segments carrying face
+names, hence after this arc).
+
+## Acceptance
+
+Suites: `tests/theme_faces_acceptance.rs` (grid-path rendering +
+Lua surface + wire facts) and the existing pin/round-trip homes
+(`src/protocol.rs`); GPU behavior in `pmacs-gpu` behind
+`PMACS_REQUIRE_GPU=1` (frame-difference pattern, `main.rs:7877+`).
+Keybinding-driven tests dispatch keys, never `pmacs.command.invoke`.
+
+1. **Unset = today, byte-identical**: with neither a bare `ui` entry
+   nor any `ui.*` entry, a
+   painted frame (mode line, status row, gutter, minibuffer,
+   selection, search matches, diag squiggle) is cell-for-cell
+   identical to the pre-arc rendering; additionally a loud
+   `pmacs.theme.default` (syntax fallback) leaks into **no** chrome
+   cell (pins Q#TH4's `None`-not-`default_style`).
+2. **Each surface face applies** (grid): setting `ui.modeline`,
+   `ui.statusline`, `ui.minibuffer`, `ui.minibuffer.candidate`,
+   `ui.gutter` each changes exactly its rows'/strip's cells to the
+   masked face style on the next frame, per-cell asserted.
+3. **Owns-surface semantics** (Q#TH5): `ui.modeline = { fg = 252 }`
+   paints the grid mode line with fg 252 and **no** reverse video
+   (partial face resets the surface to plain); `ui.selection = {}`
+   leaves selected cells identical to unselected ones.
+4. **Mask enforcement** (round 2 finding 1): `ui.selection = { fg = 1,
+   reverse = true, bg = B }` renders exactly as `{ bg = B }` on both
+   frontends — grid per-cell (glyph fg untouched under the wash),
+   GPU frame identical to the bg-only variant; `ui.gutter = { bg =
+   1, reverse = true, fg = F }` renders exactly as `{ fg = F }` on
+   both.
+5. **Wash faces merge**: `ui.selection` and both search faces
+   compose over syntax-styled cells with `merge_styles` semantics —
+   a bg-only wash keeps the syntax `fg` under the wash (per-cell
+   fg+bg assertions, not any-styled-cell). Search asserted through a
+   dispatched `C-s` reaching `ensure_search_overlay` (the real
+   construction path), never a bare constructor.
+6. **Diag faces**: `ui.diag.warning` recolors the squiggle
+   `underline_color`, the column-0 marker, and the minimap mark,
+   attached via the real Lua diagnostic path (`install_diag`);
+   unset severities keep `Indexed` defaults. **Empty diag face**
+   (round 2 finding 2, clarified in round 3): with no parent,
+   `ui.diag.error = {}` renders identically to the built-in error face
+   on every surface -- squiggle, sign, minimap mark (present, not
+   vanished), band counter. With `ui.diag = { fg = C }` also set, the
+   exact empty `ui.diag.error` child blocks inheritance and resets
+   errors to the built-in color while warning/info/hint remain `C`.
+7. **Inheritance**: with only `ui.diag` set, all four severities
+   resolve to it; an explicit `ui.diag.error` then wins for errors
+   only. Same for `ui.search.match.active` ← `ui.search.match`.
+8. **Bare `ui` is a face** (round 2 finding 3):
+   `pmacs.theme.merge { ui = … }` bumps `face_epoch` and ships a
+   `ThemeFacts` table with every stage-1 face resolved to the
+   catch-all, with **no** `StyleSpans` re-emission (the key
+   classifies as face, not syntax).
+9. **Mid-session recolor, no edit (the staleness bite)**: a semantic
+   session with a grammar-backed buffer receives fresh `StyleSpans`
+   after `pmacs.theme.set` changes a capture color with zero buffer
+   edits — fails against pre-arc `StyleGate`. Twin for the minimap:
+   `FileStyleSummary` re-emits on a diag-face change.
+10. **Consecutive `set` monotonicity** (round 1 finding 1,
+    observation shape per round 2 finding 4): `set` →
+    render/observe one `StyleSpans` emission → `set` (different
+    capture colors) → render/observe a second emission — fails if
+    wholesale replacement resets the counters and the second `set`
+    shares the first's epoch. Two mutations inside one dispatch
+    legitimately coalesce: a companion assertion pins that
+    back-to-back `set`s followed by one render yield one emission.
+11. **Malformed merge is atomic**: the Lua acceptance pins the
+    order-independent user contract — one `pmacs.theme.merge`
+    carrying a valid and a malformed entry errors, every entry of
+    that merge is absent afterwards, and no `ThemeFacts` or
+    `StyleSpans` re-emission occurs. Lua table iteration order is
+    unspecified (round 2 finding 8), so the deterministic bite drives
+    the production transaction helper with an ordered iterator
+    `[Ok((valid_name, valid_style)), Err(malformed)]`. The helper must
+    return the error before acquiring the theme lock; the unit asserts
+    the pre-existing map, `syntax_epoch`, and `face_epoch` are all
+    unchanged. An implementation that locks and inserts while
+    consuming the iterator fails deterministically.
+12. **ThemeFacts emission discipline**: every v16 semantic attachment
+    receives exactly one authoritative table after viewport
+    declaration — the **empty table** for an unthemed session
+    (`face_epoch` still 0; pins the `Option` gate of Q#TH7) — then
+    silence; after `pmacs.theme.merge` of a face, exactly one
+    message with the resolved sorted table; an identical re-merge
+    emits nothing; `pmacs.theme.clear` emits the empty table.
+13. **Face-only mutations stay cheap** (round 1 finding 8): after a
+    `ui.modeline` merge, no `StyleSpans` and no `FileStyleSummary`
+    re-emission occurs (absence assertions) while `ThemeFacts`
+    ships.
+14. **Caches advance on computation** (round 2 finding 5, Rust
+    units): after an identical re-merge, `theme_facts_msg` rebuilds
+    once and the next tick skips via the recorded epoch; after a
+    non-diag face mutation, the summary recomputes once and its
+    cache key advances despite the suppressed emission — asserted
+    on the internal cache state, since traffic cannot show repeated
+    computation.
+15. **Resolution is daemon-side**: with only `ui.diag` set, the
+    shipped table contains the four concrete `ui.diag.*` entries
+    (frontends never walk).
+16. **Late join**: faces set via init.lua/first session; a second
+    semantic frontend attaching later receives the face table among
+    its first frames without any mutation occurring post-attach.
+17. **Version gate and placement**: a v15 peer session never
+    receives `ThemeFacts` (daemon skip arm); pin tests updated —
+    `assert_eq!(PROTOCOL_VERSION, 16)`, ladder accepts 6..=16 and
+    rejects 17, `ThemeFacts` postcard round-trip pin, **and a
+    byte-level encoding pin of `CompletionPopup`**, the final v15
+    variant, proving the appended placement shifted no existing
+    discriminant (round 2 finding 7, corrected in round 3).
+18. **TUI drop arm**: grid-session frontend consumes a `ThemeFacts`
+    message without error (silent drop, family test pattern).
+19. **`set` wipes faces** (Q#TH10): `pmacs.theme.set` with a
+    captures-only table removes prior faces — next frame chrome is
+    back to defaults and `ThemeFacts` ships the empty table.
+20. **GPU surface/text routes** (`PMACS_REQUIRE_GPU=1`): an empty
+    `ThemeFacts` table renders identically to never-themed. A
+    `ui.modeline` bg changes the band, and a modeline face with
+    `reverse = true` swaps the sampled band/text colors after Default
+    mapping. A `ui.gutter` fg changes only the gutter digits. With the
+    composed strings held constant, `ui.statusline` recolors a
+    transient-message left segment, while `ui.minibuffer` recolors
+    both a live minibuffer and an isearch band without recoloring the
+    ordinary buffer-name state. `ui.minibuffer.candidate` recolors the
+    actual dropdown candidate glyph region while leaving its popup
+    background and selected-row quad at their constants.
+21. **GPU wash routes** (`PMACS_REQUIRE_GPU=1`): a local selection
+    uses `ui.selection` (including the mask-equivalence assertion in
+    item 4); simultaneous normal and active search decorations use
+    `ui.search.match` and `ui.search.match.active` respectively, with
+    distinct sampled/decoded quad colors and unchanged glyph fg.
+22. **GPU diagnostic route and shaping invalidation**
+    (`PMACS_REQUIRE_GPU=1`): changing `ui.diag.error` while the
+    composed band text and diagnostic counts stay constant changes
+    the squiggle, gutter sign, minimap mark, and `E:` counter. The
+    counter assertion fails without clearing the rich-text comparison
+    cache; the empty-child reset case is item 6.
+23. **Peer selections keep the constant** (round 2 finding 9,
+    integration shape corrected in round 3): construct simultaneous,
+    non-overlapping local and peer selections and drive the actual
+    `decoration_background_vertex_bytes` / `collect_peer_rects` path.
+    Decode the emitted vertex colors: the local rectangle uses
+    `ui.selection`, while the peer rectangle remains the hardcoded
+    constant. A helper-only resolver assertion is insufficient.
+24. **Lua surface unchanged**: `pmacs.theme.current()` lists both bare
+    `ui` and `ui.*` entries alongside captures; `get("ui.modeline")`
+    returns the set style (existing lookup semantics).
+25. **Raising `__index` is transactional** (PR round 1 finding 2): a
+    merge whose style value carries a raising `__index` metatable
+    errors with the metatable's own message, commits nothing —
+    including its valid sibling — and emits nothing.
+26. **v15 peers get no face-derived summary marks** (PR round 1
+    finding 3): with a diag face set, a `for_peer(…, 15)` producer
+    ships summary marks at the built-in severity color and produces
+    no `ThemeFacts`; the `for_peer(…, 16)` twin resolves the face.
+27. **Same-generation summary updates repaint the GPU minimap**
+    (PR round 1 finding 1, `PMACS_REQUIRE_GPU=1`): two summaries at
+    one generation with different mark colors render different
+    frames — fails without the cache invalidation on accept.
+28. **Snapshot round trip re-ships buffer-scoped state** (PR round 2
+    finding 1): with a themed diag mark on A, driving the producer
+    through the daemon's exact A → B → A sequence
+    (`on_buffer_snapshot_sent` + viewport re-declaration at each
+    switch) re-ships A's `FileStyleSummary` — identical themed
+    payload, UNCHANGED generation — and A's `StatusFacts`; an
+    unchanged tick before the trip stays suppressed. A Rust unit
+    pins the reset's scope: one buffer's baselines die, other
+    buffers' and the bufferless `ThemeFacts` pair survive.
+29. **The daemon wiring, end to end** (PR round 2 finding 1, CRDT):
+    a real daemon session navigating A → B → A via dispatched keys
+    (the active-buffer-follow path writes the snapshots) re-ships
+    `FileStyleSummary` for A at its unchanged generation after the
+    revisit's viewport re-declaration.
+30. **The GPU minimap returns** (PR round 2 finding 1,
+    `PMACS_REQUIRE_GPU=1`): after a real `BufferSnapshot` A → B → A
+    round trip (same text both buffers, isolating the minimap), the
+    stale minimap is gone, and applying the re-shipped summary at
+    the same generation restores the first visit's pixels exactly.
+31. **Snapshots clear GPU search/menu/status and release the
+    intercept gate** (PR round 3 finding 1, `PMACS_REQUIRE_GPU=1`):
+    with an open search prompt, menu popup, and status facts,
+    applying a `BufferSnapshot` clears all three, flips
+    `daemon_intercepts_keys` back to local key handling, and removes
+    the popup pixels — hand-bitten by disabling the three clears.
+32. **The reset preserves the diagnostic-count freeze** (PR round 3
+    finding 2): render nonzero counts, mark the store stale
+    (didChange), apply the snapshot reset — the re-sent
+    `StatusFacts` carries the frozen nonzero counts, never (0, 0).
+33. **The freeze holds without session history** (PR round 4): mark
+    a populated store stale BEFORE constructing the
+    `SemanticRenderState` — the session's first frame reports the
+    store's preserved counts, because the freeze is the retained
+    diagnostic vector itself, not a per-session cache.
+34. **Frozen counts stay O(1) at frame cadence** (PR round 5, Rust
+    unit): `DiagnosticStore` caches all four per-URI severity totals;
+    replacement updates them, `mark_stale` preserves them, and
+    `clear` / an empty replacement remove them with the diagnostic
+    vector. `StatusFacts` reads this tuple rather than rescanning
+    `for_uri` for every semantic session on every frame.
diff --git a/pmacs-gpu/src/main.rs b/pmacs-gpu/src/main.rs
index d4b1956..79567e4 100644
--- a/pmacs-gpu/src/main.rs
+++ b/pmacs-gpu/src/main.rs
@@ -678,6 +678,14 @@ struct State {
     gutter_buffer: Buffer,
     /// Dedicated renderer for the gutter number layer (like the menu / mb).
     gutter_text_renderer: TextRenderer,
+    /// The daemon-resolved UI face table (themes arc Q#TH7, protocol
+    /// v16). Exact-name lookup only — inheritance is resolved
+    /// daemon-side, so the frontend never walks. Complete replacement
+    /// per `ThemeFacts`; a face absent from the map means "use the
+    /// site's hardcoded default". Applied per draw through the
+    /// `face_fg_or` / `face_wash_or` / `modeline_face_colors` /
+    /// `diag_face_rgba` resolvers (Q#TH5 mask + `Default` mapping).
+    faces: HashMap<String, CellStyle>,
 }
 
 /// Kind-glyph column for a completion row: the LSP
@@ -2019,6 +2027,7 @@ impl State {
             completion_bg_vertex_buffer: ReusableVertexBuffer::new(),
             minimap_cache: None,
             line_numbers: LineNumberMode::Off,
+            faces: HashMap::new(),
             gutter_buffer,
             gutter_text_renderer,
         }
@@ -2456,6 +2465,22 @@ impl State {
                 // keep hijacking Esc/RET/TAB. The daemon-side session
                 // was already invalidated by the switch.
                 self.completion = None;
+                // PR #120 round 3 finding 1 — the remaining
+                // buffer-scoped facts, same reasoning: search and menu
+                // popups anchor in the prior buffer AND gate key and
+                // pointer interception (`daemon_intercepts_keys`, the
+                // pointer arms), and the new buffer's first CLOSED
+                // state is suppressed daemon-side, so no close message
+                // ever comes — a retained popup would hijack input
+                // forever. The status band's name/counts describe the
+                // buffer we just left; the producer's reset contract
+                // re-ships the new buffer's facts on its first frame.
+                // The minibuffer deliberately survives: it is one
+                // global core instance, matching the producer's
+                // surviving `last_minibuffer` baseline.
+                self.search_prompt = None;
+                self.menu = None;
+                self.status_facts = None;
                 self.cursor_fresh = false;
                 self.optimistic_cursor_floor = None;
                 self.optimistic_floor_set_at = None;
@@ -2690,6 +2715,21 @@ impl State {
                 }
                 None
             }
+            // Themes Q#TH7 (protocol v16): the daemon-resolved UI face
+            // table — complete replacement each send. The status-band
+            // shaping cache MUST be invalidated here (Q#TH8): the
+            // E:/W: counter colors are baked into glyphon rich-text
+            // attributes at compose time and `refresh_status_line`
+            // skips re-shaping while the composed strings are
+            // unchanged, so a diag-face change with constant counts
+            // would keep stale colors indefinitely without this.
+            InstanceMessage::ThemeFacts { faces } => {
+                self.faces = faces.into_iter().map(|f| (f.name, f.style)).collect();
+                self.status_text.clear();
+                self.status_left_text.clear();
+                self.request_redraw();
+                None
+            }
             // Q#SR5 / Q#RX6 — the live isearch prompt (protocol v10).
             // `query: None` clears the band (search ended); `Some` shows
             // `[Regex] I-search: <query> (n/m)` on the band's left side.
@@ -3382,6 +3422,134 @@ impl State {
         self.request_redraw();
     }
 
+    // -----------------------------------------------------------------
+    // Themes (Q#TH5/Q#TH7/Q#TH8): UI-face resolution. Faces arrive
+    // daemon-resolved over `ThemeFacts`; lookups are exact-name. A set
+    // face owns its surface within its stage-1 mask, and a `Default`
+    // component inside the mask maps to the frontend's PLAIN rendering
+    // — the buffer-text default fg / the window-background bg — never
+    // the old chrome constant. An UNSET face keeps the site constant.
+    // -----------------------------------------------------------------
+
+    /// fg resolution for an {fg}-mask site: face set → its fg
+    /// (`Default` ↦ the plain text color); unset → `fallback`
+    /// (today's site constant).
+    fn face_fg_or(&self, name: &str, fallback: Color) -> Color {
+        match self.faces.get(name) {
+            Some(f) => cell_color_to_glyphon(f.fg).unwrap_or_else(plain_text_color),
+            None => fallback,
+        }
+    }
+
+    /// Wash resolution for a {bg}-mask face: face set → its bg RGB
+    /// carrying the site's current alpha (`Default` bg ↦ no wash — a
+    /// fully transparent quad); unset → `fallback` (today's wash
+    /// constant, alpha included).
+    fn face_wash_or(&self, name: &str, fallback: [f32; 4]) -> [f32; 4] {
+        match self.faces.get(name) {
+            Some(f) => match cell_color_to_glyphon(f.bg) {
+                Some(c) => glyphon_to_rgba(c, fallback[3]),
+                None => [0.0, 0.0, 0.0, 0.0],
+            },
+            None => fallback,
+        }
+    }
+
+    /// `Some((band quad rgba, band text color))` when `ui.modeline`
+    /// is set — mask {fg, bg, reverse}: `Default` bg ↦ the window
+    /// background (an untinted band), `Default` fg ↦ the plain text
+    /// color, `reverse` swaps the two after mapping. `None` when
+    /// unset: each band site keeps its own constant.
+    fn modeline_face_colors(&self) -> Option<([f32; 4], Color)> {
+        let f = self.faces.get("ui.modeline")?;
+        let text = cell_color_to_glyphon(f.fg).unwrap_or_else(plain_text_color);
+        let quad = match cell_color_to_glyphon(f.bg) {
+            Some(c) => glyphon_to_rgba(c, 1.0),
+            None => WINDOW_BG_RGBA,
+        };
+        Some(if f.reverse {
+            (glyphon_to_rgba(text, 1.0), rgba_to_glyphon(quad))
+        } else {
+            (quad, text)
+        })
+    }
+
+    /// Diag-family TEXT color (Q#TH5 policy): the `ui.diag.*` face's
+    /// fg when set with a concrete color, else `fallback` (the
+    /// built-in severity constant). Unlike [`Self::face_fg_or`], a
+    /// set face's `Default` fg maps to the BUILT-IN color, never
+    /// plain — the severity color doubles as the minimap presence
+    /// encoding, so a plain severity is unrepresentable.
+    fn diag_face_fg_or(&self, name: &str, fallback: Color) -> Color {
+        self.faces
+            .get(name)
+            .and_then(|f| cell_color_to_glyphon(f.fg))
+            .unwrap_or(fallback)
+    }
+
+    /// Diag-family quad color — [`Self::diag_face_fg_or`]'s rgba
+    /// twin, keyed by decoration kind.
+    fn diag_face_rgba(&self, kind: DecorationKind, fallback: [f32; 4]) -> [f32; 4] {
+        let name = match kind {
+            DecorationKind::DiagnosticError => "ui.diag.error",
+            DecorationKind::DiagnosticWarning => "ui.diag.warning",
+            DecorationKind::DiagnosticInfo => "ui.diag.info",
+            DecorationKind::DiagnosticHint => "ui.diag.hint",
+            _ => return fallback,
+        };
+        match self
+            .faces
+            .get(name)
+            .and_then(|f| cell_color_to_glyphon(f.fg))
+        {
+            Some(c) => glyphon_to_rgba(c, 1.0),
+            None => fallback,
+        }
+    }
+
+    /// The OWN-window wash color for a background decoration kind:
+    /// the local selection and search washes resolve their faces;
+    /// peer rects (`collect_peer_rects`) deliberately keep the
+    /// constants — peer theming rides the deferred peer-cursor
+    /// palette arc (Q#TH5, round 2 finding 9).
+    fn own_wash_color(&self, kind: DecorationKind) -> Option<[f32; 4]> {
+        let fallback = decoration_kind_to_bg_color(kind)?;
+        let name = match kind {
+            DecorationKind::Selection => "ui.selection",
+            DecorationKind::SearchMatch => "ui.search.match",
+            DecorationKind::SearchMatchActive => "ui.search.match.active",
+            _ => return Some(fallback),
+        };
+        Some(self.face_wash_or(name, fallback))
+    }
+
+    /// The band's left-segment text color, mirroring
+    /// [`Self::compose_status_left`]'s priority: minibuffer/isearch
+    /// content follows `ui.minibuffer`, a transient message follows
+    /// `ui.statusline`, and the buffer name follows `ui.modeline`
+    /// (the framing's content-class applicability, Q#TH3).
+    fn status_left_color(&self) -> Color {
+        const LEFT_DEFAULT: (u8, u8, u8) = (200, 200, 210);
+        let fallback = Color::rgb(LEFT_DEFAULT.0, LEFT_DEFAULT.1, LEFT_DEFAULT.2);
+        if self.minibuffer.is_some()
+            || self
+                .search_prompt
+                .as_ref()
+                .is_some_and(|s| Some(s.buffer_id) == self.current_buffer_id)
+        {
+            return self.face_fg_or("ui.minibuffer", fallback);
+        }
+        let has_message = self
+            .status_facts
+            .as_ref()
+            .filter(|f| Some(f.buffer_id) == self.current_buffer_id)
+            .is_some_and(|f| f.message.is_some());
+        if has_message {
+            return self.face_fg_or("ui.statusline", fallback);
+        }
+        self.modeline_face_colors().map_or(fallback, |(_, t)| t)
+    }
+
     /// Compose the status-band readout (Q#S1): diagnostic counts
     /// (wire-authoritative, severity-colored, omitted when zero),
     /// then cursor L:C from the *optimistic* caret (so it tracks
@@ -3396,15 +3564,19 @@ impl State {
             .filter(|f| Some(f.buffer_id) == self.current_buffer_id)
         {
             if facts.diag_errors > 0 {
+                // Themes Q#TH5: the counters follow the diag faces
+                // (fg mask; the shaping-cache invalidation in the
+                // ThemeFacts arm makes a recolor with constant counts
+                // actually re-shape, Q#TH8).
                 spans.push((
                     format!("E:{}", facts.diag_errors),
-                    Some(Color::rgb(241, 76, 76)),
+                    Some(self.diag_face_fg_or("ui.diag.error", Color::rgb(241, 76, 76))),
                 ));
             }
             if facts.diag_warnings > 0 {
                 spans.push((
                     format!("W:{}", facts.diag_warnings),
-                    Some(Color::rgb(245, 245, 67)),
+                    Some(self.diag_face_fg_or("ui.diag.warning", Color::rgb(245, 245, 67))),
                 ));
             }
         }
@@ -3548,12 +3720,16 @@ impl State {
     /// The status band's background quad (Q#S2): a full-width strip
     /// under the band text.
     fn status_band_vertex_bytes(&self) -> Vec<u8> {
+        // Themes Q#TH5: a set ui.modeline face owns the band surface.
+        let color = self
+            .modeline_face_colors()
+            .map_or(STATUS_BAND_BG, |(quad, _)| quad);
         let rect = MinimapRect {
             x: 0.0,
             y: text_area_bottom(self.config.height),
             w: self.config.width as f32,
             h: STATUS_BAND_HEIGHT,
-            color: STATUS_BAND_BG,
+            color,
         };
         rects_to_vertex_bytes(&[rect], self.config.width, self.config.height)
     }
@@ -3935,6 +4111,15 @@ impl State {
         }
         self.current_line_shapes = minimap_line_shapes(&self.current_text);
         self.current_summary = Some(FileStyleSummaryState { generation, lines });
+        // PR #120 round 1 finding 1: a newly accepted summary can
+        // arrive at an UNCHANGED generation (theme recolor,
+        // diagnostic republish) and the minimap cache keys only on
+        // (generation, dims, scroll) — without an explicit drop the
+        // stale vertices survive until an edit, resize, or scroll.
+        // The daemon payload-suppresses identical summaries, so every
+        // summary accepted here is genuinely new and the invalidation
+        // is precise.
+        self.minimap_cache = None;
         self.request_redraw();
     }
 
@@ -4457,6 +4642,14 @@ impl State {
         } else {
             0
         };
+        // Themes Q#TH5/Q#TH9: resolve the face-driven colors before
+        // the prepare call — its `&mut self.*` field borrows preclude
+        // method calls on `self` inside the argument list.
+        let readout_color = self
+            .modeline_face_colors()
+            .map_or(Color::rgb(168, 168, 180), |(_, text)| text);
+        let left_color = self.status_left_color();
+        let gutter_color = self.face_fg_or("ui.gutter", Color::rgb(120, 120, 135));
         self.text_renderer
             .prepare(
                 &self.device,
@@ -4493,7 +4686,10 @@ impl State {
                             right: self.config.width.cast_signed(),
                             bottom: self.config.height.cast_signed(),
                         },
-                        default_color: Color::rgb(168, 168, 180),
+                        // Themes Q#TH5: a set ui.modeline face colors
+                        // the readout too (its fg after the reverse
+                        // swap); unset keeps the dimmer gray.
+                        default_color: readout_color,
                         custom_glyphs: &[],
                     },
                     TextArea {
@@ -4508,7 +4704,11 @@ impl State {
                             right: (status_left - STATUS_TEXT_PAD).max(0.0).round() as i32,
                             bottom: self.config.height.cast_signed(),
                         },
-                        default_color: Color::rgb(200, 200, 210),
+                        // Themes Q#TH3: the left segment's face follows
+                        // its CONTENT class (minibuffer/isearch →
+                        // ui.minibuffer; message → ui.statusline; name
+                        // → ui.modeline).
+                        default_color: left_color,
                         custom_glyphs: &[],
                     },
                 ],
@@ -4531,7 +4731,8 @@ impl State {
                     right: gutter_clip_left,
                     bottom: text_area_bottom(self.config.height).round() as i32,
                 },
-                default_color: Color::rgb(120, 120, 135),
+                // Themes Q#TH5: ui.gutter's {fg} mask colors the digits.
+                default_color: gutter_color,
                 custom_glyphs: &[],
             }]
         } else {
@@ -4591,6 +4792,8 @@ impl State {
         // by `first` rows so line `first` lands at `top_y`, and the
         // existing `bounds.top`/`bottom` clip the rows scrolled out of the
         // visible window (no per-resize re-shape needed).
+        // Hoisted for the same borrow reason as the band colors above.
+        let candidate_color = self.face_fg_or("ui.minibuffer.candidate", Color::rgb(232, 232, 238));
         let mb_areas: Vec<TextArea> = self
             .mb_visible_window()
             .zip(self.mb_dropdown_rect())
@@ -4605,7 +4808,10 @@ impl State {
                     right: (x + width).round() as i32,
                     bottom: text_area_bottom(self.config.height).round() as i32,
                 },
-                default_color: Color::rgb(232, 232, 238),
+                // Themes Q#TH5 (round 3 finding 1): the candidate
+                // glyph layer is ui.minibuffer.candidate's GPU site;
+                // the popup bg/selection quads stay chrome constants.
+                default_color: candidate_color,
                 custom_glyphs: &[],
             })
             .into_iter()
@@ -4864,7 +5070,9 @@ impl State {
                 if best.is_none_or(|(r, _)| rank < r)
                     && let Some(color) = decoration_kind_to_underline_color(d.kind)
                 {
-                    best = Some((rank, color));
+                    // Themes Q#TH5: gutter signs share the resolved
+                    // severity color with the squiggles.
+                    best = Some((rank, self.diag_face_rgba(d.kind, color)));
                 }
             }
             if let Some((_, color)) = best {
@@ -4902,8 +5110,9 @@ impl State {
             };
             // Diagnostic underlines are squiggles now, drawn by their
             // own pipeline (`squiggle_vertex_bytes`); only the solid
-            // washes belong in this quad batch.
-            if let Some(color) = decoration_kind_to_bg_color(d.kind) {
+            // washes belong in this quad batch. Own washes resolve
+            // their theme faces (Q#TH5); peers keep the constants.
+            if let Some(color) = self.own_wash_color(d.kind) {
                 self.push_glyph_extent_rects(rects, line_offsets, lo, hi, color, None);
             }
         }
@@ -4929,6 +5138,9 @@ impl State {
             let Some(color) = decoration_kind_to_underline_color(d.kind) else {
                 continue;
             };
+            // Themes Q#TH5: squiggles follow the ui.diag.* faces
+            // (fg mask, Default ↦ the built-in severity constant).
+            let color = self.diag_face_rgba(d.kind, color);
             if let Some((lo, hi)) = clip_rebase_range(d.range.start, d.range.end, vstart, vend) {
                 self.push_glyph_extent_rects(
                     &mut rects,
@@ -5627,6 +5839,7 @@ fn instance_message_label(msg: &InstanceMessage) -> &'static str {
         InstanceMessage::DispatchIdle { .. } => "DispatchIdle",
         InstanceMessage::LineNumbers { .. } => "LineNumbers",
         InstanceMessage::CompletionPopup { .. } => "CompletionPopup",
+        InstanceMessage::ThemeFacts { .. } => "ThemeFacts",
     }
 }
 
@@ -6545,6 +6758,45 @@ fn cell_color_to_glyphon(c: CellColor) -> Option<glyphon::Color> {
     }
 }
 
+/// The GPU's "plain" text color — the buffer-text default at
+/// `main.rs`'s primary `TextArea`. The Q#TH5 mapping target for a
+/// set face's `Default` fg.
+fn plain_text_color() -> glyphon::Color {
+    glyphon::Color::rgb(230, 230, 235)
+}
+
+/// The window clear color as a quad rgba — the Q#TH5 mapping target
+/// for a set face's `Default` bg (an untinted surface). Must equal
+/// [`BG`].
+const WINDOW_BG_RGBA: [f32; 4] = [0.05, 0.05, 0.07, 1.0];
+
+/// glyphon (u8) → quad (f32) color, carrying `alpha`. Divides by 255
+/// — the same space every existing float constant uses (e.g. the
+/// error squiggle `[0.945, …]` is exactly `rgb(241, 76, 76) / 255`).
+fn glyphon_to_rgba(c: glyphon::Color, alpha: f32) -> [f32; 4] {
+    [
+        f32::from(c.r()) / 255.0,
+        f32::from(c.g()) / 255.0,
+        f32::from(c.b()) / 255.0,
+        alpha,
+    ]
+}
+
+/// quad (f32) → glyphon (u8) color (alpha dropped) — the `reverse`
+/// swap's other direction.
+#[allow(
+    clippy::cast_possible_truncation,
+    clippy::cast_sign_loss,
+    reason = "inputs are 0.0..=1.0 quad colors by construction"
+)]
+fn rgba_to_glyphon(c: [f32; 4]) -> glyphon::Color {
+    glyphon::Color::rgb(
+        (c[0] * 255.0) as u8,
+        (c[1] * 255.0) as u8,
+        (c[2] * 255.0) as u8,
+    )
+}
+
 /// Standard xterm-style 256-color palette: 16 base colors + 6×6×6
 /// RGB cube (16..=231) + 24-step grayscale (232..=255). Values
 /// pulled from the conventional xterm defaults; the 6×6×6 cube uses
@@ -8097,4 +8349,624 @@ mod tests {
             "a wide window keeps the gutter"
         );
     }
+
+    // -----------------------------------------------------------------
+    // Themes (Q#TH5/Q#TH7/Q#TH8): GPU face application.
+    // -----------------------------------------------------------------
+
+    fn theme_face(name: &str, style: CellStyle) -> pmacs_protocol::ThemeFace {
+        pmacs_protocol::ThemeFace {
+            name: name.into(),
+            style,
+        }
+    }
+
+    fn apply_faces(state: &mut State, faces: Vec<pmacs_protocol::ThemeFace>) {
+        let _ = state.apply_attach_message(InstanceMessage::ThemeFacts { faces });
+    }
+
+    fn px_at(px: &[u8], width: u32, x: u32, y: u32) -> [u8; 4] {
+        let i = ((y * width + x) * 4) as usize;
+        [px[i], px[i + 1], px[i + 2], px[i + 3]]
+    }
+
+    #[test]
+    fn headless_theme_facts_empty_table_renders_identically() {
+        // Acceptance 20: the authoritative empty table (an unthemed
+        // daemon's first send) must change nothing.
+        let Some(mut state) = headless_or_skip(320, 240, "fn main() {}") else {
+            return;
+        };
+        let base = state.render_offscreen();
+        apply_faces(&mut state, Vec::new());
+        let themed = state.render_offscreen();
+        assert_eq!(base, themed, "an empty face table must be a no-op");
+    }
+
+    #[test]
+    fn headless_modeline_face_owns_the_band_and_reverse_swaps() {
+        // Acceptance 20: ui.modeline bg retints the band quad, and
+        // reverse swaps quad/text after the Default mapping. Sampled
+        // at a band pixel left of the text pad — comparing two states
+        // whose (fg, bg, reverse) SHOULD produce the same quad avoids
+        // any dependence on the surface's exact color space.
+        let (w, h) = (400u32, 300u32);
+        let fg = CellColor::Rgb(200, 30, 30);
+        let bg = CellColor::Rgb(10, 60, 110);
+        let Some(mut plain) = headless_or_skip(w, h, "hello") else {
+            return;
+        };
+        let plain_sample = px_at(&plain.render_offscreen(), w, 2, h - 2);
+
+        apply_faces(
+            &mut plain,
+            vec![theme_face(
+                "ui.modeline",
+                CellStyle {
+                    fg,
+                    bg,
+                    ..CellStyle::default()
+                },
+            )],
+        );
+        let tinted_sample = px_at(&plain.render_offscreen(), w, 2, h - 2);
+        assert_ne!(
+            plain_sample, tinted_sample,
+            "a bg face must retint the band quad"
+        );
+
+        // Swapped face + reverse ⇒ the identical quad color…
+        apply_faces(
+            &mut plain,
+            vec![theme_face(
+                "ui.modeline",
+                CellStyle {
+                    fg: bg,
+                    bg: fg,
+                    reverse: true,
+                    ..CellStyle::default()
+                },
+            )],
+        );
+        let swapped_sample = px_at(&plain.render_offscreen(), w, 2, h - 2);
+        assert_eq!(
+            tinted_sample, swapped_sample,
+            "reverse must swap fg/bg after mapping (same quad both ways)"
+        );
+
+        // …while reverse on the ORIGINAL face tints the quad with fg.
+        apply_faces(
+            &mut plain,
+            vec![theme_face(
+                "ui.modeline",
+                CellStyle {
+                    fg,
+                    bg,
+                    reverse: true,
+                    ..CellStyle::default()
+                },
+            )],
+        );
+        let reversed_sample = px_at(&plain.render_offscreen(), w, 2, h - 2);
+        assert_ne!(
+            tinted_sample, reversed_sample,
+            "reverse must move the quad off the bg color"
+        );
+    }
+
+    #[test]
+    fn headless_gutter_face_recolors_only_the_gutter_region() {
+        // Acceptance 20: a ui.gutter fg change alters the gutter
+        // digits and nothing else — every differing pixel lies left
+        // of the text origin and above the band.
+        let (w, h) = (400u32, 300u32);
+        let text = "alpha\nbeta\ngamma\ndelta\n";
+        let Some(mut state) = headless_or_skip(w, h, text) else {
+            return;
+        };
+        state.line_numbers = LineNumberMode::Absolute;
+        let text_left = state.text_left().ceil() as u32;
+        let band_top = text_area_bottom(h).floor() as u32;
+        let base = state.render_offscreen();
+        apply_faces(
+            &mut state,
+            vec![theme_face(
+                "ui.gutter",
+                CellStyle {
+                    fg: CellColor::Rgb(220, 120, 40),
+                    ..CellStyle::default()
+                },
+            )],
+        );
+        let themed = state.render_offscreen();
+        let mut differing = 0usize;
+        for (i, (a, b)) in base.iter().zip(&themed).enumerate() {
+            if a != b {
+                differing += 1;
+                let pixel = (i / 4) as u32;
+                let (x, y) = (pixel % w, pixel / w);
+                assert!(
+                    x < text_left && y < band_top,
+                    "gutter face leaked outside the gutter region at ({x}, {y})"
+                );
+            }
+        }
+        assert!(differing > 20, "the digits must actually recolor");
+    }
+
+    #[test]
+    fn headless_band_text_faces_follow_content_class() {
+        // Acceptance 20: with the composed strings held constant,
+        // ui.statusline recolors a transient message, ui.minibuffer
+        // recolors a live minibuffer and an isearch band — and each
+        // face is a NO-OP on the content classes it doesn't own.
+        let (w, h) = (400u32, 300u32);
+        let Some(mut state) = headless_or_skip(w, h, "hello") else {
+            return;
+        };
+        let bid = BufferId::next();
+        state.current_buffer_id = Some(bid);
+        let statusline_face = vec![theme_face(
+            "ui.statusline",
+            CellStyle {
+                fg: CellColor::Rgb(240, 140, 40),
+                ..CellStyle::default()
+            },
+        )];
+        let minibuffer_face = vec![theme_face(
+            "ui.minibuffer",
+            CellStyle {
+                fg: CellColor::Rgb(40, 220, 140),
+                ..CellStyle::default()
+            },
+        )];
+
+        // (a) Buffer name showing: ui.statusline must not repaint it.
+        state.status_facts = Some(StatusFactsLocal {
+            buffer_id: bid,
+            name: "main.rs".into(),
+            modified: false,
+            diag_errors: 0,
+            diag_warnings: 0,
+            message: None,
+        });
+        let name_base = state.render_offscreen();
+        apply_faces(&mut state, statusline_face.clone());
+        assert_eq!(
+            name_base,
+            state.render_offscreen(),
+            "ui.statusline must not color the buffer-name class"
+        );
+        apply_faces(&mut state, Vec::new());
+
+        // (b) Transient message showing: ui.statusline recolors it.
+        state.status_facts = Some(StatusFactsLocal {
+            buffer_id: bid,
+            name: "main.rs".into(),
+            modified: false,
+            diag_errors: 0,
+            diag_warnings: 0,
+            message: Some("12 references".into()),
+        });
+        let msg_base = state.render_offscreen();
+        apply_faces(&mut state, statusline_face);
+        assert_ne!(
+            msg_base,
+            state.render_offscreen(),
+            "ui.statusline must recolor the transient message"
+        );
+        apply_faces(&mut state, Vec::new());
+
+        // (c) Live minibuffer: ui.minibuffer recolors the band text.
+        state.minibuffer = Some(MinibufferLocal {
+            prompt: "M-x ".into(),
+            input: "theme".into(),
+            cursor: 5,
+            candidates: Vec::new(),
+            selected: None,
+            total: 0,
+        });
+        let mb_base = state.render_offscreen();
+        apply_faces(&mut state, minibuffer_face.clone());
+        assert_ne!(
+            mb_base,
+            state.render_offscreen(),
+            "ui.minibuffer must recolor the live minibuffer"
+        );
+        apply_faces(&mut state, Vec::new());
+        state.minibuffer = None;
+
+        // (d) Isearch band: same face, same route.
+        state.search_prompt = Some(SearchPromptLocal {
+            buffer_id: bid,
+            query: "needle".into(),
+            active: Some(0),
+            total: 2,
+            regex: false,
+            invalid: false,
+        });
+        let isearch_base = state.render_offscreen();
+        apply_faces(&mut state, minibuffer_face);
+        assert_ne!(
+            isearch_base,
+            state.render_offscreen(),
+            "ui.minibuffer must recolor the isearch band"
+        );
+    }
+
+    #[test]
+    fn headless_candidate_face_recolors_the_dropdown_glyphs() {
+        // Acceptance 20 (round 3 finding 1): ui.minibuffer.candidate's
+        // GPU site is the dropdown's candidate glyph layer.
+        let (w, h) = (400u32, 300u32);
+        let Some(mut state) = headless_or_skip(w, h, "hello") else {
+            return;
+        };
+        state.minibuffer = Some(MinibufferLocal {
+            prompt: "M-x ".into(),
+            input: "the".into(),
+            cursor: 3,
+            candidates: vec!["theme-set".into(), "theme-clear".into()],
+            selected: Some(0),
+            total: 2,
+        });
+        let base = state.render_offscreen();
+        apply_faces(
+            &mut state,
+            vec![theme_face(
+                "ui.minibuffer.candidate",
+                CellStyle {
+                    fg: CellColor::Rgb(250, 80, 160),
+                    ..CellStyle::default()
+                },
+            )],
+        );
+        assert_ne!(
+            base,
+            state.render_offscreen(),
+            "the candidate glyphs must recolor"
+        );
+    }
+
+    #[test]
+    fn headless_diag_face_recolors_band_counter_despite_unchanged_text() {
+        // Acceptance 22 — the round-1 finding-3 bite. The E: counter
+        // color is baked into shaped rich text and the composed string
+        // is CONSTANT here, so this fails without the ThemeFacts arm's
+        // shaping-cache invalidation (Q#TH8). The empty diag child is
+        // the built-in reset (Q#TH5): identical to unthemed.
+        let (w, h) = (400u32, 300u32);
+        let Some(mut state) = headless_or_skip(w, h, "alpha\nbeta\n") else {
+            return;
+        };
+        let bid = BufferId::next();
+        state.current_buffer_id = Some(bid);
+        state.view_range = (0, state.current_text.len() as u64);
+        state.status_facts = Some(StatusFactsLocal {
+            buffer_id: bid,
+            name: "main.rs".into(),
+            modified: false,
+            diag_errors: 2,
+            diag_warnings: 0,
+            message: None,
+        });
+        state.current_decorations.push(Decoration {
+            range: ByteRange { start: 0, end: 5 },
+            kind: DecorationKind::DiagnosticError,
+        });
+        let base = state.render_offscreen();
+
+        apply_faces(
+            &mut state,
+            vec![theme_face(
+                "ui.diag.error",
+                CellStyle {
+                    fg: CellColor::Rgb(40, 200, 255),
+                    ..CellStyle::default()
+                },
+            )],
+        );
+        assert_ne!(
+            base,
+            state.render_offscreen(),
+            "the counter (and squiggle) must recolor with counts constant"
+        );
+
+        // An all-default diag child resets to the built-in color.
+        apply_faces(
+            &mut state,
+            vec![theme_face("ui.diag.error", CellStyle::default())],
+        );
+        assert_eq!(
+            base,
+            state.render_offscreen(),
+            "ui.diag.error = {{}} must render as the built-in severity color"
+        );
+    }
+
+    #[test]
+    fn headless_same_generation_summary_update_repaints_the_minimap() {
+        // PR #120 round 1 finding 1: theme recolors and diagnostic
+        // republishes ship a NEW summary at the SAME CRDT generation,
+        // and the minimap cache keys only on (generation, dims,
+        // scroll) — accepting a summary must drop the cached vertices
+        // or the stale strokes survive until an edit/resize/scroll.
+        let text = "alpha\nbeta\ngamma\ndelta\n";
+        let (w, h) = (400u32, 300u32);
+        let Some(mut state) = headless_or_skip(w, h, text) else {
+            return;
+        };
+        let bid = BufferId::next();
+        state.current_buffer_id = Some(bid);
+        state.view_range = (0, text.len() as u64);
+        let summary = |color: CellColor| -> Vec<CellStyle> {
+            (0..4)
+                .map(|_| CellStyle {
+                    fg: color,
+                    ..CellStyle::default()
+                })
+                .collect()
+        };
+        let _ = state.apply_attach_message(InstanceMessage::FileStyleSummary {
+            buffer_id: bid,
+            generation: 7,
+            lines: summary(CellColor::Rgb(200, 40, 40)),
+        });
+        let first = state.render_offscreen();
+        // Same generation, different colors — a theme-recolor twin.
+        let _ = state.apply_attach_message(InstanceMessage::FileStyleSummary {
+            buffer_id: bid,
+            generation: 7,
+            lines: summary(CellColor::Rgb(40, 200, 40)),
+        });
+        let second = state.render_offscreen();
+        assert_ne!(
+            first, second,
+            "a same-generation summary recolor must repaint the minimap"
+        );
+    }
+
+    #[test]
+    fn headless_snapshot_round_trip_summary_restores_the_minimap() {
+        // PR #120 round 2 finding 1 (frontend half): a `BufferSnapshot`
+        // drops `current_summary` with the rest of the buffer-scoped
+        // state, so after an A → B → A round trip no stale minimap
+        // may survive — and when the daemon's baseline reset re-ships
+        // the summary at the unchanged generation, the first visit's
+        // pixels must return exactly.
+        let text = "alpha\nbeta\ngamma\ndelta\n";
+        let (w, h) = (400u32, 300u32);
+        let Some(mut state) = headless_or_skip(w, h, text) else {
+            return;
+        };
+        // Both buffers carry the same text so the frames differ by
+        // the minimap alone.
+        let snapshot = || -> Vec<u8> {
+            let doc = loro::LoroDoc::new();
+            doc.get_text(LORO_TEXT_CONTAINER)
+                .insert(0, text)
+                .expect("insert snapshot text");
+            doc.export(loro::ExportMode::Snapshot)
+                .expect("export snapshot")
+        };
+        let bid_a = BufferId::next();
+        let bid_b = BufferId::next();
+        let visit = |state: &mut State, bid: BufferId| {
+            let _ = state.apply_attach_message(InstanceMessage::BufferSnapshot {
+                buffer_id: bid,
+                crdt_snapshot: snapshot(),
+            });
+            state.view_range = (0, text.len() as u64);
+        };
+        let lines: Vec<CellStyle> = (0..4)
+            .map(|_| CellStyle {
+                fg: CellColor::Rgb(200, 40, 40),
+                ..CellStyle::default()
+            })
+            .collect();
+
+        visit(&mut state, bid_a);
+        let _ = state.apply_attach_message(InstanceMessage::FileStyleSummary {
+            buffer_id: bid_a,
+            generation: 7,
+            lines: lines.clone(),
+        });
+        let first_visit = state.render_offscreen();
+
+        visit(&mut state, bid_b);
+        visit(&mut state, bid_a);
+        assert_ne!(
+            first_visit,
+            state.render_offscreen(),
+            "the round trip dropped the summary — no stale minimap"
+        );
+
+        let _ = state.apply_attach_message(InstanceMessage::FileStyleSummary {
+            buffer_id: bid_a,
+            generation: 7,
+            lines,
+        });
+        assert_eq!(
+            first_visit,
+            state.render_offscreen(),
+            "the re-shipped summary restores the first visit's minimap"
+        );
+    }
+
+    #[test]
+    fn headless_snapshot_clears_search_menu_status_and_the_intercept_gate() {
+        // PR #120 round 3 finding 1: search/menu popups anchor in the
+        // prior buffer AND gate key/pointer interception, and the new
+        // buffer's first CLOSED state is suppressed daemon-side, so
+        // no close message ever comes — a `BufferSnapshot` must clear
+        // them (and the stale status band) or the popup hijacks input
+        // forever. The minibuffer is global and deliberately exempt.
+        let text = "alpha\nbeta\n";
+        let Some(mut state) = headless_or_skip(400, 300, text) else {
+            return;
+        };
+        let bid_a = BufferId::next();
+        state.current_buffer_id = Some(bid_a);
+        let _ = state.apply_attach_message(InstanceMessage::DispatchIdle { idle: true });
+        assert!(
+            !state.daemon_intercepts_keys(),
+            "idle with nothing open: keys apply locally"
+        );
+
+        let _ = state.apply_attach_message(InstanceMessage::SearchPrompt {
+            buffer_id: bid_a,
+            query: Some("al".into()),
+            active: Some(0),
+            total: 1,
+            regex: false,
+            invalid: false,
+        });
+        let _ = state.apply_attach_message(InstanceMessage::MenuPrompt {
+            buffer_id: bid_a,
+            rows: vec![MenuPromptRow {
+                label: "Cut".into(),
+                separator: false,
+            }],
+            active: Some(0),
+        });
+        let _ = state.apply_attach_message(InstanceMessage::StatusFacts {
+            buffer_id: bid_a,
+            name: "old.rs".into(),
+            modified: false,
+            diag_errors: 3,
+            diag_warnings: 1,
+            message: None,
+        });
+        assert!(
+            state.daemon_intercepts_keys(),
+            "an open search/menu round-trips every key"
+        );
+        let with_popups = state.render_offscreen();
+
+        let doc = loro::LoroDoc::new();
+        doc.get_text(LORO_TEXT_CONTAINER)
+            .insert(0, text)
+            .expect("insert snapshot text");
+        let _ = state.apply_attach_message(InstanceMessage::BufferSnapshot {
+            buffer_id: BufferId::next(),
+            crdt_snapshot: doc.export(loro::ExportMode::Snapshot).expect("export"),
+        });
+
+        assert!(
+            state.search_prompt.is_none() && state.menu.is_none() && state.status_facts.is_none(),
+            "buffer-scoped search/menu/status facts die with the snapshot"
+        );
+        assert!(
+            !state.daemon_intercepts_keys(),
+            "the intercept gate releases — keys apply locally again"
+        );
+        assert_ne!(
+            with_popups,
+            state.render_offscreen(),
+            "the popup pixels are gone"
+        );
+    }
+
+    #[test]
+    fn own_wash_faces_color_local_rects_peers_keep_the_constant() {
+        // Acceptance 21 + 23: decode the emitted decoration vertex
+        // colors — the LOCAL selection and both search washes resolve
+        // their faces (site alpha preserved), while simultaneous PEER
+        // selection/current-line rects keep the hardcoded constants.
+        fn decode_quad_colors(bytes: &[u8]) -> Vec<[f32; 4]> {
+            bytes
+                .chunks_exact(24)
+                .map(|v| {
+                    let f = |i: usize| {
+                        f32::from_ne_bytes(v[i * 4..i * 4 + 4].try_into().expect("4 bytes"))
+                    };
+                    [f(2), f(3), f(4), f(5)]
+                })
+                .collect()
+        }
+        let text = "alpha\nbeta\ngamma\ndelta\n";
+        let Some(mut state) = headless_or_skip(400, 300, text) else {
+            return;
+        };
+        let bid = BufferId::next();
+        state.current_buffer_id = Some(bid);
+        state.view_range = (0, text.len() as u64);
+        state.current_decorations.extend([
+            Decoration {
+                range: ByteRange { start: 0, end: 5 }, // "alpha"
+                kind: DecorationKind::Selection,
+            },
+            Decoration {
+                range: ByteRange { start: 6, end: 10 }, // "beta"
+                kind: DecorationKind::SearchMatch,
+            },
+            Decoration {
+                range: ByteRange { start: 11, end: 16 }, // "gamma"
+                kind: DecorationKind::SearchMatchActive,
+            },
+        ]);
+        state.peer_presences.insert(
+            FrontendId(7),
+            PeerPresence {
+                buffer_id: bid,
+                cursor: 17,
+                selection: Some(SelectionSnapshot {
+                    anchor: 17,
+                    active: 22, // "delta"
+                }),
+            },
+        );
+        apply_faces(
+            &mut state,
+            vec![
+                theme_face(
+                    "ui.selection",
+                    CellStyle {
+                        bg: CellColor::Rgb(9, 99, 199),
+                        ..CellStyle::default()
+                    },
+                ),
+                theme_face(
+                    "ui.search.match",
+                    CellStyle {
+                        bg: CellColor::Rgb(10, 20, 30),
+                        ..CellStyle::default()
+                    },
+                ),
+                theme_face(
+                    "ui.search.match.active",
+                    CellStyle {
+                        bg: CellColor::Rgb(40, 50, 60),
+                        ..CellStyle::default()
+                    },
+                ),
+            ],
+        );
+        let colors = decode_quad_colors(&state.decoration_background_vertex_bytes());
+        // Exact float equality is deliberate: both sides derive from
+        // the same constants through the same arithmetic.
+        let has = |c: [f32; 4]| colors.contains(&c);
+        // Local rects: face RGB with each site's original alpha.
+        assert!(
+            has(glyphon_to_rgba(glyphon::Color::rgb(9, 99, 199), 0.30)),
+            "local selection must use ui.selection"
+        );
+        assert!(
+            has(glyphon_to_rgba(glyphon::Color::rgb(10, 20, 30), 0.30)),
+            "search match must use ui.search.match"
+        );
+        assert!(
+            has(glyphon_to_rgba(glyphon::Color::rgb(40, 50, 60), 0.48)),
+            "active match must use ui.search.match.active"
+        );
+        // Peer rects: the hardcoded constants, face table ignored.
+        assert!(
+            has([0.31, 0.42, 0.82, 0.30]),
+            "the peer selection must keep the Selection constant"
+        );
+        assert!(
+            has([0.55, 0.60, 0.75, 0.22]),
+            "the peer cursor line must keep the CurrentLine constant"
+        );
+    }
 }
diff --git a/pmacs-protocol/src/lib.rs b/pmacs-protocol/src/lib.rs
index 01eb91c..1585558 100644
--- a/pmacs-protocol/src/lib.rs
+++ b/pmacs-protocol/src/lib.rs
@@ -52,7 +52,7 @@ pub use message::{
     InstanceCapabilities, InstanceIdentity, InstanceMessage, InstanceSignal, Key, KeyEvent,
     LineNumberMode, MenuPromptRow, Modifiers, MouseButton, MouseEvent, MouseKind,
     NegotiatedCapabilities, PROTOCOL_VERSION, PointerKind, ResourceBody,
-    SUPPORTED_PROTOCOL_VERSIONS, SelectionSnapshot, StyleSegment, StyleSpan, is_builtin_pair_char,
-    is_supported_protocol_version, negotiate_capabilities,
+    SUPPORTED_PROTOCOL_VERSIONS, SelectionSnapshot, StyleSegment, StyleSpan, ThemeFace,
+    is_builtin_pair_char, is_supported_protocol_version, negotiate_capabilities,
 };
 pub use transport::{MAX_FRAME_BYTES, TransportError, read_message, write_message};
diff --git a/pmacs-protocol/src/message.rs b/pmacs-protocol/src/message.rs
index 57e8d4f..3318e87 100644
--- a/pmacs-protocol/src/message.rs
+++ b/pmacs-protocol/src/message.rs
@@ -974,6 +974,40 @@ pub enum InstanceMessage {
         /// Total candidate count (the window is a slice of this).
         total: u32,
     },
+    /// Themes arc (Q#TH7, protocol v16). The daemon-resolved UI faces.
+    /// The theme is one global instance, so this is bufferless (the
+    /// [`Self::MinibufferPrompt`] shape). Complete replacement each
+    /// send: a face absent from `faces` is unset, and the frontend
+    /// uses its own default for that surface. Every attachment
+    /// receives exactly one authoritative table — the empty table
+    /// included — with its first emission after viewport declaration;
+    /// cached-compare suppressed thereafter. Daemon-gated `>= 16`.
+    ///
+    /// Appended as the FINAL variant deliberately: postcard
+    /// discriminants are ordinal, so inserting earlier would shift
+    /// every later variant's tag and corrupt v15 peers on ungated
+    /// channels. The `CompletionPopup` byte pin in `src/protocol.rs`
+    /// guards this placement.
+    ThemeFacts {
+        /// Every stage-1 face that resolves to a style (the Q#TH4
+        /// dotted-prefix walk, resolved daemon-side — frontends do
+        /// exact-name lookup, no walk), full names, sorted by name
+        /// for deterministic comparison.
+        faces: Vec<ThemeFace>,
+    },
+}
+
+/// One resolved UI face for [`InstanceMessage::ThemeFacts`]: a full
+/// face name (e.g. `"ui.modeline"`) and the style the daemon resolved
+/// for it. The face's component *mask* (which components a frontend
+/// may read) is a stage-1 contract documented per face in the themes
+/// framing; out-of-mask components are never read by either frontend.
+#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct ThemeFace {
+    /// Full face name (`ui` or `ui.`-prefixed).
+    pub name: String,
+    /// The daemon-resolved style for this face.
+    pub style: crate::cell::Style,
 }
 
 /// Line-number gutter mode for a window (UX gutter arc). Shared across the
@@ -1330,7 +1364,16 @@ pub enum ResourceBody {
 /// (encoding change to that variant; its gate moved `>= 8` → `>= 15`,
 /// so a v14 peer's status band goes dark rather than mis-decoding —
 /// the v10 `SearchPrompt` / v14 `LineNumbers` shape).
-pub const PROTOCOL_VERSION: u32 = 15;
+///
+/// Theme faces (Q#TH7): bumped 15 → 16 for
+/// [`InstanceMessage::ThemeFacts`] — a new additive variant carrying
+/// the daemon-resolved UI face table. Daemon-gated `< 16`; a v15 peer
+/// negotiates v15 and simply receives no `ThemeFacts` (its chrome
+/// stays on the frontend defaults), like every prior additive bump.
+/// The variant is appended after `CompletionPopup` — the final v15
+/// variant — because postcard discriminants are ordinal and an
+/// earlier insertion would shift existing tags under v15 peers.
+pub const PROTOCOL_VERSION: u32 = 16;
 
 /// T M10.5: the set of protocol versions a v1.0 binary accepts on
 /// the wire. v0.1 binaries only accepted `[1]`; v1.0 binaries accept
@@ -1390,7 +1433,10 @@ pub const PROTOCOL_VERSION: u32 = 15;
 ///
 /// Q#C5: extended to `[6, ..., 15]`. `InstanceMessage::CompletionPopup`
 /// is additive and daemon-gated per session.
-pub const SUPPORTED_PROTOCOL_VERSIONS: &[u32] = &[6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
+///
+/// Q#TH7: extended to `[6, ..., 16]`. `InstanceMessage::ThemeFacts`
+/// is additive and daemon-gated per session, so the ladder resumes.
+pub const SUPPORTED_PROTOCOL_VERSIONS: &[u32] = &[6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16];
 
 /// T M10.5: predicate for the handshake check. Returns `true` if
 /// `peer_version` is in [`SUPPORTED_PROTOCOL_VERSIONS`].
diff --git a/src/daemon.rs b/src/daemon.rs
index 973188c..8d3d901 100644
--- a/src/daemon.rs
+++ b/src/daemon.rs
@@ -984,6 +984,7 @@ fn dispatcher_loop(
                         upgraded,
                         &session_registry,
                         &mut streams,
+                        &mut semantic_states,
                     );
                     // The broadcast just delivered this buffer to this
                     // frontend too; record it so the follow check below
@@ -1022,6 +1023,14 @@ fn dispatcher_loop(
                         && last_active_buffer_sent.get(fid) != Some(&active_now)
                     {
                         send_buffer_snapshot_to_frontend(editor, active_now, *fid, &mut streams);
+                        // PR #120 round 2 — the snapshot just wiped
+                        // this frontend's buffer-scoped render state;
+                        // the emission baselines must die with it or
+                        // an unchanged-generation revisit (A → B → A)
+                        // suppresses every re-send.
+                        if let Some(sem) = semantic_states.get_mut(fid) {
+                            sem.on_buffer_snapshot_sent(active_now);
+                        }
                         last_active_buffer_sent.insert(*fid, active_now);
                     }
                 }
@@ -1125,6 +1134,11 @@ fn dispatcher_loop(
                 let peer_knows_completion_popup = session_registry
                     .session_state(*fid)
                     .is_some_and(|s| s.negotiated_protocol_version >= 15);
+                // Themes Q#TH7 — ThemeFacts gated at v16; a v15 peer's
+                // chrome simply stays on its frontend defaults.
+                let peer_knows_theme_facts = session_registry
+                    .session_state(*fid)
+                    .is_some_and(|s| s.negotiated_protocol_version >= 16);
                 for msg in &messages {
                     if !peer_knows_status_facts
                         && matches!(msg, InstanceMessage::StatusFacts { .. })
@@ -1160,6 +1174,10 @@ fn dispatcher_loop(
                     {
                         continue;
                     }
+                    if !peer_knows_theme_facts && matches!(msg, InstanceMessage::ThemeFacts { .. })
+                    {
+                        continue;
+                    }
                     // T M10.10 Day 4 / M10.11 F2 — the criterion-1
                     // jitter site: render-write latency.
                     //
@@ -1366,6 +1384,9 @@ fn handle_session_established(
     // fires: the semantic frontend holds the rope locally and the
     // semantic frame ships no text.
     let semantic_render = session_state.negotiated_capabilities.semantic_render;
+    // Captured before `register_session` consumes the state: the
+    // semantic producer needs the peer's version (finding 3 below).
+    let negotiated_protocol_version = session_state.negotiated_protocol_version;
     if crdt_replica {
         send_buffer_snapshots(editor, &mut write_stream);
     }
@@ -1377,7 +1398,14 @@ fn handle_session_established(
     if semantic_render {
         semantic_states.insert(
             frontend_id,
-            crate::semantic_render::SemanticRenderState::new(frontend_id),
+            // for_peer, not new (PR #120 round 1 finding 3): a v15
+            // peer's producer must not resolve faces into the
+            // FileStyleSummary marks — that channel predates the v16
+            // gate.
+            crate::semantic_render::SemanticRenderState::for_peer(
+                frontend_id,
+                negotiated_protocol_version,
+            ),
         );
     } else {
         let mut render_state = RenderState::new(initial_size);
@@ -1844,6 +1872,7 @@ fn broadcast_buffer_snapshot_to_replicas(
     buffer_id: crate::buffer::BufferId,
     session_registry: &SessionRegistry,
     streams: &mut HashMap<FrontendId, UnixStream>,
+    semantic_states: &mut HashMap<FrontendId, crate::semantic_render::SemanticRenderState>,
 ) {
     let Some(snapshot_bytes) = export_buffer_snapshot(editor, buffer_id) else {
         return;
@@ -1862,6 +1891,12 @@ fn broadcast_buffer_snapshot_to_replicas(
         if let Err(e) = write_message(stream, &msg) {
             eprintln!("pmacs: F29 send BufferSnapshot for {buffer_id:?} to {fid:?} failed: {e}");
         }
+        // PR #120 round 2 — same reset contract as the follow path:
+        // the snapshot wiped this replica's buffer-scoped render
+        // state, so its emission baselines for the buffer die too.
+        if let Some(sem) = semantic_states.get_mut(fid) {
+            sem.on_buffer_snapshot_sent(buffer_id);
+        }
     }
 }
 
diff --git a/src/diag.rs b/src/diag.rs
index 0db0b2e..c7ea236 100644
--- a/src/diag.rs
+++ b/src/diag.rs
@@ -196,6 +196,10 @@ impl Diagnostic {
 #[derive(Default)]
 pub struct DiagnosticStore {
     by_uri: HashMap<String, Vec<Diagnostic>>,
+    /// Per-URI severity totals, maintained alongside `by_uri` so
+    /// frame-time consumers do not rescan every diagnostic at render
+    /// cadence. Entries exist exactly when `by_uri` entries do.
+    severity_counts: HashMap<String, (u32, u32, u32, u32)>,
     /// URIs whose stored diagnostics are known to be out of date
     /// because a `textDocument/didChange` was issued after the last
     /// `publishDiagnostics` was absorbed. `Self::set` clears entries
@@ -210,6 +214,20 @@ pub struct DiagnosticStore {
     epochs: HashMap<String, u64>,
 }
 
+fn count_severities(diags: &[Diagnostic]) -> (u32, u32, u32, u32) {
+    let mut counts = (0u32, 0u32, 0u32, 0u32);
+    for diagnostic in diags {
+        let slot = match diagnostic.severity {
+            DiagnosticSeverity::Error => &mut counts.0,
+            DiagnosticSeverity::Warning => &mut counts.1,
+            DiagnosticSeverity::Information => &mut counts.2,
+            DiagnosticSeverity::Hint => &mut counts.3,
+        };
+        *slot = slot.saturating_add(1);
+    }
+    counts
+}
+
 impl DiagnosticStore {
     /// Empty store.
     #[must_use]
@@ -227,11 +245,14 @@ impl DiagnosticStore {
     pub fn set(&mut self, uri: impl Into<String>, mut diags: Vec<Diagnostic>) {
         diags.sort_by(Diagnostic::compare_by_position);
         let uri = uri.into();
+        let counts = count_severities(&diags);
         self.stale_uris.remove(&uri);
         *self.epochs.entry(uri.clone()).or_insert(0) += 1;
         if diags.is_empty() {
             self.by_uri.remove(&uri);
+            self.severity_counts.remove(&uri);
         } else {
+            self.severity_counts.insert(uri.clone(), counts);
             self.by_uri.insert(uri, diags);
         }
     }
@@ -240,6 +261,7 @@ impl DiagnosticStore {
     /// no entry to be stale about.
     pub fn clear(&mut self, uri: &str) {
         self.by_uri.remove(uri);
+        self.severity_counts.remove(uri);
         self.stale_uris.remove(uri);
         *self.epochs.entry(uri.to_owned()).or_insert(0) += 1;
     }
@@ -285,19 +307,26 @@ impl DiagnosticStore {
         let mut w = 0;
         let mut i = 0;
         let mut h = 0;
-        for diags in self.by_uri.values() {
-            for d in diags {
-                match d.severity {
-                    DiagnosticSeverity::Error => e += 1,
-                    DiagnosticSeverity::Warning => w += 1,
-                    DiagnosticSeverity::Information => i += 1,
-                    DiagnosticSeverity::Hint => h += 1,
-                }
-            }
+        for &(errors, warnings, information, hints) in self.severity_counts.values() {
+            e += errors as usize;
+            w += warnings as usize;
+            i += information as usize;
+            h += hints as usize;
         }
         (e, w, i, h)
     }
 
+    /// Per-URI totals `(error, warning, information, hint)`.
+    ///
+    /// The tuple is computed once by [`Self::set`] and deliberately
+    /// survives [`Self::mark_stale`]: staleness invalidates byte
+    /// positions, while the last published counts remain valid as a
+    /// frozen status summary until the next publication.
+    #[must_use]
+    pub fn severity_counts_for(&self, uri: &str) -> (u32, u32, u32, u32) {
+        self.severity_counts.get(uri).copied().unwrap_or_default()
+    }
+
     /// Per-URI count.
     #[must_use]
     pub fn count_for(&self, uri: &str) -> usize {
@@ -363,63 +392,61 @@ pub fn make_shared_store() -> SharedDiagStore {
 /// [`crate::text_view`] and [`crate::highlight`].
 const TAB_WIDTH: u32 = 8;
 
-/// Style applied to bytes covered by an `Error` diagnostic. Wavy
-/// underline colored via `underline_color` (not `fg`) so the
-/// squiggle reads red while the syntax view's text color survives
-/// underneath (T M4.6, protocol v6).
-fn error_style() -> Style {
-    Style {
-        underline: UnderlineStyle::Curly,
-        underline_color: DiagnosticSeverity::Error.underline_color(),
-        ..Style::default()
+/// The RESOLVED severity color (themes arc Q#TH5): the `ui.diag.*`
+/// face's `fg` when a face is set with a concrete color, else the
+/// built-in [`DiagnosticSeverity::underline_color`]. The diag family
+/// carries a special `Default` policy — `Default` fg means the
+/// built-in severity color, never "plain" — because the color doubles
+/// as the *presence* encoding in the minimap summary
+/// (`FileStyleSummary.underline_color`, where `Default` reads as "no
+/// mark"), so a plain severity color is unrepresentable and
+/// `ui.diag.error = {}` degrades to the built-in on every surface.
+#[must_use]
+pub fn severity_color(
+    theme: Option<&crate::highlight::Theme>,
+    severity: DiagnosticSeverity,
+) -> Color {
+    let name = match severity {
+        DiagnosticSeverity::Error => "ui.diag.error",
+        DiagnosticSeverity::Warning => "ui.diag.warning",
+        DiagnosticSeverity::Information => "ui.diag.info",
+        DiagnosticSeverity::Hint => "ui.diag.hint",
+    };
+    match theme.and_then(|t| t.face(name)) {
+        Some(f) if f.fg != Color::Default => f.fg,
+        _ => severity.underline_color(),
     }
 }
 
-/// Style applied to bytes covered by a `Warning` diagnostic.
-fn warning_style() -> Style {
+/// Style applied to bytes covered by a diagnostic: severity-shaped
+/// underline (wavy for error/warning, single for info, dotted for
+/// hint) colored via `underline_color` (not `fg`) so the squiggle
+/// reads its severity color while the syntax view's text color
+/// survives underneath (T M4.6, protocol v6). `color` is the
+/// resolved severity color ([`severity_color`]).
+fn style_for(severity: DiagnosticSeverity, color: Color) -> Style {
+    let underline = match severity {
+        DiagnosticSeverity::Error | DiagnosticSeverity::Warning => UnderlineStyle::Curly,
+        DiagnosticSeverity::Information => UnderlineStyle::Single,
+        DiagnosticSeverity::Hint => UnderlineStyle::Dotted,
+    };
     Style {
-        underline: UnderlineStyle::Curly,
-        underline_color: DiagnosticSeverity::Warning.underline_color(),
+        underline,
+        underline_color: color,
         ..Style::default()
     }
 }
 
-/// Style applied to bytes covered by an `Information` diagnostic.
-fn info_style() -> Style {
-    Style {
-        underline: UnderlineStyle::Single,
-        underline_color: DiagnosticSeverity::Information.underline_color(),
-        ..Style::default()
-    }
-}
-
-/// Style applied to bytes covered by a `Hint` diagnostic.
-fn hint_style() -> Style {
-    Style {
-        underline: UnderlineStyle::Dotted,
-        underline_color: DiagnosticSeverity::Hint.underline_color(),
-        ..Style::default()
-    }
-}
-
-fn style_for(severity: DiagnosticSeverity) -> Style {
-    match severity {
-        DiagnosticSeverity::Error => error_style(),
-        DiagnosticSeverity::Warning => warning_style(),
-        DiagnosticSeverity::Information => info_style(),
-        DiagnosticSeverity::Hint => hint_style(),
-    }
-}
-
 /// Style of the column-0 line marker — the TUI's gutter sign
 /// (T M4.6). The TUI reserves no gutter column, so the sign is a
 /// severity-colored *background* on the line's first cell: the
 /// glyph and its syntax color survive (the view contract is
 /// style-only), and zero-width diagnostics — invisible to the
-/// underline pass — still get a visible artifact.
-fn marker_style_for(severity: DiagnosticSeverity) -> Style {
+/// underline pass — still get a visible artifact. `color` is the
+/// resolved severity color ([`severity_color`]).
+fn marker_style_for(color: Color) -> Style {
     Style {
-        bg: severity.underline_color(),
+        bg: color,
         ..Style::default()
     }
 }
@@ -436,15 +463,25 @@ pub struct DiagnosticView {
     /// Shared store; mutated by the LSP manager, read by this view
     /// on every render.
     store: SharedDiagStore,
+    /// Shared theme for the `ui.diag.*` face resolution (themes arc
+    /// Q#TH9; the `SyntaxHighlightView` precedent). `None` — a bare
+    /// test construction — paints the built-in severity colors.
+    theme: Option<crate::highlight::ThemeHandle>,
 }
 
 impl DiagnosticView {
-    /// Construct a diagnostic view for `uri` against `store`.
+    /// Construct a diagnostic view for `uri` against `store`,
+    /// resolving severity colors through `theme` when given.
     #[must_use]
-    pub fn new(uri: impl Into<String>, store: SharedDiagStore) -> Self {
+    pub fn new(
+        uri: impl Into<String>,
+        store: SharedDiagStore,
+        theme: Option<crate::highlight::ThemeHandle>,
+    ) -> Self {
         Self {
             uri: uri.into(),
             store,
+            theme,
         }
     }
 
@@ -502,8 +539,15 @@ impl View for DiagnosticView {
         let mut line_markers: std::collections::HashMap<u32, DiagnosticSeverity> =
             std::collections::HashMap::new();
 
+        // One theme clone per render (themes arc Q#TH9, the
+        // SyntaxHighlightView discipline) for the ui.diag.* faces.
+        let theme = self
+            .theme
+            .as_ref()
+            .map(|t| t.lock().expect("theme mutex poisoned").clone());
+
         for diag in &diags {
-            let style = style_for(diag.severity);
+            let style = style_for(diag.severity, severity_color(theme.as_ref(), diag.severity));
             // Apply to each line the diagnostic touches. LSP ranges
             // are half-open at the end position; if end_col == 0
             // the diagnostic stops at the start of `end_line` so
@@ -580,6 +624,7 @@ impl View for DiagnosticView {
             viewport.gutter_w,
             max_cols,
             &line_markers,
+            theme.as_ref(),
         );
     }
 }
@@ -597,9 +642,11 @@ fn paint_line_markers(
     gutter_w: u32,
     max_cols: u32,
     line_markers: &std::collections::HashMap<u32, DiagnosticSeverity>,
+    theme: Option<&crate::highlight::Theme>,
 ) {
     for (&row_offset, &severity) in line_markers {
         let row = cell_origin.row + row_offset;
+        let color = severity_color(theme, severity);
         if gutter_w > 0 {
             let cell = cells.at(CellCoord::new(
                 row,
@@ -607,12 +654,12 @@ fn paint_line_markers(
             ));
             cell.glyph = Glyph::Char(severity.gutter_glyph());
             cell.style = Style {
-                fg: severity.underline_color(),
+                fg: color,
                 ..Style::default()
             };
         } else if max_cols > 0 {
             let cell = cells.at(CellCoord::new(row, cell_origin.col));
-            cell.style = merge_styles(cell.style, marker_style_for(severity));
+            cell.style = merge_styles(cell.style, marker_style_for(color));
         }
     }
 }
@@ -842,12 +889,47 @@ mod tests {
         assert_eq!(totals, (2, 1, 1, 1));
     }
 
+    #[test]
+    fn cached_severity_counts_replace_clear_and_survive_staleness() {
+        let mut store = DiagnosticStore::new();
+        assert_eq!(store.severity_counts_for("file:///a"), (0, 0, 0, 0));
+
+        store.set(
+            "file:///a",
+            vec![
+                diag(0, DiagnosticSeverity::Error, "1"),
+                diag(1, DiagnosticSeverity::Error, "2"),
+                diag(2, DiagnosticSeverity::Warning, "3"),
+                diag(3, DiagnosticSeverity::Information, "4"),
+                diag(4, DiagnosticSeverity::Hint, "5"),
+            ],
+        );
+        assert_eq!(store.severity_counts_for("file:///a"), (2, 1, 1, 1));
+
+        store.mark_stale("file:///a");
+        assert_eq!(
+            store.severity_counts_for("file:///a"),
+            (2, 1, 1, 1),
+            "staleness freezes the last published counts"
+        );
+
+        store.set(
+            "file:///a",
+            vec![diag(0, DiagnosticSeverity::Warning, "replacement")],
+        );
+        assert_eq!(store.severity_counts_for("file:///a"), (0, 1, 0, 0));
+
+        store.clear("file:///a");
+        assert_eq!(store.severity_counts_for("file:///a"), (0, 0, 0, 0));
+    }
+
     #[test]
     fn empty_set_clears_uri() {
         let mut s = DiagnosticStore::new();
         s.set("a", vec![diag(0, DiagnosticSeverity::Error, "x")]);
         s.set("a", Vec::new());
         assert!(s.for_uri("a").is_empty());
+        assert_eq!(s.severity_counts_for("a"), (0, 0, 0, 0));
         assert_eq!(s.uris().count(), 0);
     }
 
@@ -921,7 +1003,7 @@ mod tests {
             DiagnosticSeverity::Information,
             DiagnosticSeverity::Hint,
         ] {
-            let style = style_for(s);
+            let style = style_for(s, severity_color(None, s));
             assert_eq!(style.fg, Color::Default, "{s:?} must not set fg");
             assert_ne!(
                 style.underline_color,
@@ -959,7 +1041,7 @@ mod tests {
         // `pmacs.window._overlay_kinds()` introspection (task #23 wire-up,
         // mirroring "syntax-highlight" / LspStyleView) relies on this.
         let store = make_shared_store();
-        let view = DiagnosticView::new("file:///a", store);
+        let view = DiagnosticView::new("file:///a", store, None);
         assert_eq!(view.kind(), "diagnostic");
     }
 
@@ -984,7 +1066,7 @@ mod tests {
         })
         .expect("seed buffer");
 
-        let mut view = DiagnosticView::new("file:///a", store);
+        let mut view = DiagnosticView::new("file:///a", store, None);
         let mut backing = vec![Cell::default(); 10];
         let mut grid = CellGrid {
             cells: &mut backing,
@@ -1046,7 +1128,7 @@ mod tests {
         })
         .expect("seed buffer");
 
-        let mut view = DiagnosticView::new("file:///a", store);
+        let mut view = DiagnosticView::new("file:///a", store, None);
         let mut backing = vec![Cell::default(); 30];
         // Pre-paint glyphs at column 0 to pin the style-only contract.
         backing[0].glyph = Glyph::Char('h');
@@ -1123,7 +1205,7 @@ mod tests {
 
         // A 2-cell gutter: text is shifted to column 2, signs land at
         // window column 0 (`cell_origin.col - gutter_w`).
-        let mut view = DiagnosticView::new("file:///a", store);
+        let mut view = DiagnosticView::new("file:///a", store, None);
         let mut backing = vec![Cell::default(); 30];
         let mut grid = CellGrid {
             cells: &mut backing,
@@ -1191,7 +1273,7 @@ mod tests {
         })
         .expect("seed buffer");
 
-        let mut view = DiagnosticView::new("file:///a", store);
+        let mut view = DiagnosticView::new("file:///a", store, None);
         let mut backing = vec![Cell::default(); 20];
         let mut grid = CellGrid {
             cells: &mut backing,
diff --git a/src/editor.rs b/src/editor.rs
index 0f23c07..955db8a 100644
--- a/src/editor.rs
+++ b/src/editor.rs
@@ -206,6 +206,11 @@ impl EditorState {
             lua_host.registry(),
         )
         .expect("install pmacs.parse");
+        // Themes Q#TH9: inject the shared theme into the core right
+        // after SyntaxRegistry construction — the core owns no syntax
+        // state, but its search overlay resolves wash faces through
+        // this handle.
+        core.borrow_mut().theme = Some(syntax_registry.theme());
         lua_host
             .eval(
                 Some("@pmacs/builtin/runtime/syntax.lua"),
@@ -2093,6 +2098,14 @@ pub fn paint_frame(
     }
     let text_rows = term_size.rows - 1;
 
+    // Themes Q#TH9: one theme clone per frame for the chrome faces —
+    // the same single-lock discipline as `SyntaxHighlightView::render`.
+    let theme = {
+        let handle = state.syntax_registry.theme();
+        let t = handle.lock().expect("theme mutex poisoned");
+        t.clone()
+    };
+
     let mut core_ref = state.core.borrow_mut();
     let core: &mut EditorCore = &mut core_ref;
 
@@ -2175,12 +2188,12 @@ pub fn paint_frame(
         // overlay in attach order. See [`crate::view::View`].
         window.text_view.render(buf, viewport, grid);
         if gutter_w > 0 {
-            paint_line_number_gutter(grid, window, &rect, inner_rows, gutter_w);
+            paint_line_number_gutter(grid, window, &rect, inner_rows, gutter_w, &theme);
         }
         for overlay in &mut window.overlays {
             overlay.render(buf, viewport, grid);
         }
-        paint_local_selection(grid, buf, window, &rect, inner_rows, gutter_w);
+        paint_local_selection(grid, buf, window, &rect, inner_rows, gutter_w, &theme);
         // Mode line for this window. Painted last so the line
         // itself is always visible regardless of overlay activity.
         let coord = window
@@ -2212,21 +2225,29 @@ pub fn paint_frame(
             coord.col,
             &scroll,
             &diags,
+            mode_line_style(&theme),
         );
     }
     drop(reg);
 
-    paint_status_line(grid, core, &state.lua_host, &state.dispatcher, term_size);
+    paint_status_line(
+        grid,
+        core,
+        &state.lua_host,
+        &state.dispatcher,
+        term_size,
+        &theme,
+    );
 
     // An active isearch owns the bottom row (its prompt + match
     // readout), but the terminal cursor stays in the buffer at the
     // active match so the eye follows the search — so paint the prompt
     // and fall through to the buffer-cursor placement below.
     let mb_cursor_col = if core.search_active() {
-        paint_search_prompt(grid, core, term_size);
+        paint_search_prompt(grid, core, term_size, &theme);
         None
     } else if core.minibuffer.is_active() {
-        Some(paint_minibuffer(grid, core, term_size))
+        Some(paint_minibuffer(grid, core, term_size, &theme))
     } else {
         None
     };
@@ -2257,33 +2278,59 @@ pub fn paint_frame(
     Some(CellCoord::new(grid_row, grid_col))
 }
 
+/// The mode-line row style (themes arc Q#TH5): a set `ui.modeline`
+/// face owns the surface within its {fg, bg, reverse} mask — the row
+/// resets to plain plus the face's in-mask components — else today's
+/// reverse video.
+fn mode_line_style(theme: &crate::highlight::Theme) -> crate::cell::Style {
+    theme.face("ui.modeline").map_or(
+        crate::cell::Style {
+            reverse: true,
+            ..Default::default()
+        },
+        |f| crate::cell::Style {
+            fg: f.fg,
+            bg: f.bg,
+            reverse: f.reverse,
+            ..Default::default()
+        },
+    )
+}
+
 fn paint_status_line(
     grid: &mut crate::cell::CellGrid<'_>,
     core: &EditorCore,
     lua_host: &LuaHost,
     dispatcher: &KeyDispatcher,
     term_size: crate::cell::CellSize,
+    theme: &crate::highlight::Theme,
 ) {
     let status = build_status_line(core, lua_host, dispatcher, term_size.cols);
     let row = term_size.rows - 1;
+    // Themes Q#TH5: a set `ui.statusline` face owns the row within its
+    // {fg} mask (surface resets to plain); unset keeps reverse video.
+    let style = theme.face("ui.statusline").map_or(
+        crate::cell::Style {
+            reverse: true,
+            ..Default::default()
+        },
+        |f| crate::cell::Style {
+            fg: f.fg,
+            ..Default::default()
+        },
+    );
     for (col, ch) in status.chars().enumerate() {
         if col >= term_size.cols as usize {
             break;
         }
         let cell = grid.at(CellCoord::new(row, col as u32));
         cell.glyph = crate::cell::Glyph::Char(ch);
-        cell.style = crate::cell::Style {
-            reverse: true,
-            ..Default::default()
-        };
+        cell.style = style;
     }
     for col in (status.chars().count() as u32)..term_size.cols {
         let cell = grid.at(CellCoord::new(row, col));
         cell.glyph = crate::cell::Glyph::Char(' ');
-        cell.style = crate::cell::Style {
-            reverse: true,
-            ..Default::default()
-        };
+        cell.style = style;
     }
 }
 
@@ -2323,16 +2370,25 @@ fn paint_line_number_gutter(
     rect: &crate::window::Rect,
     inner_rows: u32,
     gutter_w: u32,
+    theme: &crate::highlight::Theme,
 ) {
     let line_count = window.text_view.line_count();
     // Relative/Hybrid measure distance from the cursor's buffer line;
     // Absolute ignores it. Computed once per frame (the gutter repaints on
     // cursor motion, so this stays current).
     let cursor_line = window.text_view.line_at_offset(window.cursor);
-    let style = crate::cell::Style {
-        fg: crate::cell::Color::Indexed(8),
-        ..crate::cell::Style::default()
-    };
+    // Themes Q#TH5: a set `ui.gutter` face owns the strip within its
+    // {fg} mask; unset keeps the dim Indexed(8).
+    let style = theme.face("ui.gutter").map_or(
+        crate::cell::Style {
+            fg: crate::cell::Color::Indexed(8),
+            ..crate::cell::Style::default()
+        },
+        |f| crate::cell::Style {
+            fg: f.fg,
+            ..crate::cell::Style::default()
+        },
+    );
     // The number's rightmost digit sits at `field - 1`; the last gutter
     // cell (`gutter_w - 1`) is a trailing pad separating it from the code.
     let field = gutter_w.saturating_sub(1);
@@ -2382,10 +2438,25 @@ fn paint_local_selection(
     // text-relative display column shifted right by this (Q#UX2). 0 when
     // the gutter is off, so this is a no-op then.
     gutter_w: u32,
+    theme: &crate::highlight::Theme,
 ) {
     let Some((sel_start, sel_end)) = window.region() else {
         return;
     };
+    // Themes Q#TH5: the selection is a wash — a set `ui.selection`
+    // face replaces the default overlay wholesale within its {bg}
+    // mask (an all-default face disables the wash; out-of-mask
+    // fg/reverse are never read); unset keeps today's reverse video.
+    let overlay = theme.face("ui.selection").map_or(
+        crate::cell::Style {
+            reverse: true,
+            ..crate::cell::Style::default()
+        },
+        |f| crate::cell::Style {
+            bg: f.bg,
+            ..crate::cell::Style::default()
+        },
+    );
     if inner_rows == 0 || rect.size.cols == 0 || sel_start >= sel_end {
         return;
     }
@@ -2428,7 +2499,7 @@ fn paint_local_selection(
                 rect.origin.row + row_offset,
                 rect.origin.col + gutter_w + col,
             ));
-            cell.style.reverse = true;
+            cell.style = crate::overlay::merge_styles(cell.style, overlay);
         }
     }
 }
@@ -2481,6 +2552,10 @@ fn paint_mode_line(
     cursor_col: u32,
     scroll: &str,
     diags: &str,
+    // The resolved row style ([`mode_line_style`]) — this fn is a
+    // pure formatter, so the `ui.modeline` face resolution stays with
+    // the caller (themes arc Q#TH9).
+    mode_style: crate::cell::Style,
 ) {
     if rect.size.rows == 0 || rect.size.cols == 0 {
         return;
@@ -2495,11 +2570,7 @@ fn paint_mode_line(
         format!(" {diags} L{}:C{} {scroll} ", cursor_row + 1, cursor_col + 1)
     };
 
-    // Fill the row with reverse-video spaces.
-    let mode_style = crate::cell::Style {
-        reverse: true,
-        ..Default::default()
-    };
+    // Fill the row with the mode-line style.
     for c in 0..rect.size.cols {
         let cell = grid.at(CellCoord::new(row, rect.origin.col + c));
         cell.glyph = crate::cell::Glyph::Char(' ');
@@ -2538,10 +2609,23 @@ fn paint_mode_line(
 /// Paint the minibuffer line on the bottom row, replacing the status
 /// line. Returns the screen column the terminal cursor should sit
 /// at (so the user can see what they're typing).
+/// The minibuffer base style (themes arc Q#TH5): a set `ui.minibuffer`
+/// face owns the prompt/input/fill (and the search prompt row) within
+/// its {fg} mask; unset keeps the terminal default.
+fn minibuffer_style(theme: &crate::highlight::Theme) -> crate::cell::Style {
+    theme
+        .face("ui.minibuffer")
+        .map_or(crate::cell::Style::default(), |f| crate::cell::Style {
+            fg: f.fg,
+            ..crate::cell::Style::default()
+        })
+}
+
 fn paint_minibuffer(
     grid: &mut crate::cell::CellGrid<'_>,
     core: &EditorCore,
     term_size: crate::cell::CellSize,
+    theme: &crate::highlight::Theme,
 ) -> u32 {
     let session = core
         .minibuffer
@@ -2562,13 +2646,27 @@ fn paint_minibuffer(
     let max = term_size.cols;
     let cursor_byte = core.minibuffer.cursor;
 
+    let base = minibuffer_style(theme);
+    // Themes Q#TH5: the inline candidate suffix has its own face,
+    // `ui.minibuffer.candidate` ({fg} mask); unset keeps reverse.
+    let candidate = theme.face("ui.minibuffer.candidate").map_or(
+        crate::cell::Style {
+            reverse: true,
+            ..Default::default()
+        },
+        |f| crate::cell::Style {
+            fg: f.fg,
+            ..crate::cell::Style::default()
+        },
+    );
+
     for ch in prompt.chars() {
         if col >= max {
             break;
         }
         let cell = grid.at(CellCoord::new(row, col));
         cell.glyph = crate::cell::Glyph::Char(ch);
-        cell.style = crate::cell::Style::default();
+        cell.style = base;
         col += 1;
         written += 1;
     }
@@ -2585,7 +2683,7 @@ fn paint_minibuffer(
         }
         let cell = grid.at(CellCoord::new(row, col));
         cell.glyph = crate::cell::Glyph::Char(ch);
-        cell.style = crate::cell::Style::default();
+        cell.style = base;
         col += 1;
         written += 1;
         byte_pos += ch.len_utf8() as u64;
@@ -2602,10 +2700,7 @@ fn paint_minibuffer(
         }
         let cell = grid.at(CellCoord::new(row, col));
         cell.glyph = crate::cell::Glyph::Char(ch);
-        cell.style = crate::cell::Style {
-            reverse: true,
-            ..Default::default()
-        };
+        cell.style = candidate;
         col += 1;
         written += 1;
     }
@@ -2613,7 +2708,7 @@ fn paint_minibuffer(
     for col in written..max {
         let cell = grid.at(CellCoord::new(row, col));
         cell.glyph = crate::cell::Glyph::Char(' ');
-        cell.style = crate::cell::Style::default();
+        cell.style = base;
     }
 
     cursor_col.min(max.saturating_sub(1))
@@ -2630,7 +2725,11 @@ fn paint_search_prompt(
     grid: &mut crate::cell::CellGrid<'_>,
     core: &EditorCore,
     term_size: crate::cell::CellSize,
+    theme: &crate::highlight::Theme,
 ) {
+    // Themes Q#TH5: the search prompt is the echo-area input line, so
+    // it follows `ui.minibuffer` (the framing's applicability table).
+    let base = minibuffer_style(theme);
     let prompt = match (core.search_is_regex(), core.search_forward()) {
         (false, true) => "I-search: ",
         (false, false) => "I-search backward: ",
@@ -2656,7 +2755,7 @@ fn paint_search_prompt(
         if *col < max {
             let cell = grid.at(CellCoord::new(row, *col));
             cell.glyph = crate::cell::Glyph::Char(ch);
-            cell.style = crate::cell::Style::default();
+            cell.style = base;
             *col += 1;
         }
     };
@@ -2670,11 +2769,11 @@ fn paint_search_prompt(
         put(grid, &mut col, ch);
     }
     // Clear the remainder of the row (the status line underneath used
-    // reverse video; blank it with the default style).
+    // reverse video; blank it with the prompt's base style).
     for c in col..max {
         let cell = grid.at(CellCoord::new(row, c));
         cell.glyph = crate::cell::Glyph::Char(' ');
-        cell.style = crate::cell::Style::default();
+        cell.style = base;
     }
 }
 
@@ -2852,7 +2951,14 @@ mod tests {
             size: CellSize::new(rows, cols),
         };
         let rect = Rect::new(0, 0, rows, cols);
-        paint_line_number_gutter(&mut grid, &window, &rect, rows, 4);
+        paint_line_number_gutter(
+            &mut grid,
+            &window,
+            &rect,
+            rows,
+            4,
+            &crate::highlight::Theme::empty(),
+        );
 
         let glyph = |r: u32, c: u32| storage[(r * cols + c) as usize].glyph.clone();
         // Row 0 = line 1: "  1 " (digit right-aligned at col 2, col 3 = pad).
@@ -6894,7 +7000,7 @@ mod tests {
         {
             let mut core = s.core.borrow_mut();
             core.active_window_mut()
-                .push_overlay(Box::new(crate::diag::DiagnosticView::new(uri, store)));
+                .push_overlay(Box::new(crate::diag::DiagnosticView::new(uri, store, None)));
         }
         let (cells, stride, _) = render_to_grid(&s, 24, 80);
         // Both surfaces of the same store: the overlay's underline
diff --git a/src/editor_core.rs b/src/editor_core.rs
index 0ef913b..fea6261 100644
--- a/src/editor_core.rs
+++ b/src/editor_core.rs
@@ -285,6 +285,13 @@ pub struct EditorCore {
     /// ([`crate::semantic_render`]) and the TUI search overlay.
     /// Cheaply cloneable (`Arc<Mutex>`); shared with both readers.
     pub search_store: crate::search::SharedSearchStore,
+    /// Shared theme handle (themes arc Q#TH9), injected once at editor
+    /// bring-up right after `SyntaxRegistry` construction — the core
+    /// owns no syntax state, but `ensure_search_overlay` constructs
+    /// `SearchView`s that resolve wash faces through it. A bare core
+    /// (unit-test construction) carries `None` and paints today's
+    /// literals.
+    pub theme: Option<crate::highlight::ThemeHandle>,
     /// Live incremental-search session (Q#SR5), or `None` when no
     /// search is running. Frontend-agnostic: the TUI run loop and the
     /// daemon's `FrontendEvent::Key` path both drive it through the
@@ -385,6 +392,7 @@ impl EditorCore {
             pending_crdt_ops: Vec::new(),
             jump_ring: Vec::new(),
             search_store: crate::search::make_shared_store(),
+            theme: None,
             search: None,
             clipboard_slot: Vec::new(),
             pending_clipboard: None,
@@ -857,9 +865,12 @@ impl EditorCore {
     /// rendered buffer, so one instance suffices per window.
     fn ensure_search_overlay(&mut self) {
         let store = self.search_store.clone();
+        // Themes Q#TH9: pass the injected theme through unconditionally
+        // — a bare core (None) constructs a working unthemed view.
+        let theme = self.theme.clone();
         let win = self.active_window_mut();
         if !win.overlay_kinds().contains(&"search") {
-            win.push_overlay(Box::new(crate::search::SearchView::new(store)));
+            win.push_overlay(Box::new(crate::search::SearchView::new(store, theme)));
         }
     }
 
diff --git a/src/frontend.rs b/src/frontend.rs
index 2595ebd..76cfee1 100644
--- a/src/frontend.rs
+++ b/src/frontend.rs
@@ -413,6 +413,11 @@ impl Frontend {
             // completion dropdown; the TUI paints the popup via its
             // CompletionView cell overlay, so it drops this silently.
             | InstanceMessage::CompletionPopup { .. }
+            // Themes Q#TH7 — ThemeFacts is the semantic-frontend face
+            // table; the cell-grid TUI receives its chrome pre-painted
+            // (the daemon resolves faces at paint time), so it drops
+            // this silently like the other semantic families.
+            | InstanceMessage::ThemeFacts { .. }
             | InstanceMessage::ResourceOffer { .. }
             // T M11.6 — DispatchIdle is consumed by `attach.rs`'s
             // optimistic-apply gate; if any reaches this render path
@@ -760,6 +765,32 @@ mod tests {
         }
     }
 
+    #[test]
+    fn theme_facts_drops_silently_on_the_grid_frontend() {
+        // Themes Q#TH7 / acceptance 18: the cell-grid TUI receives its
+        // chrome pre-painted (the daemon resolves faces at paint
+        // time), so a `ThemeFacts` reaching this client — which never
+        // negotiates it — must fall into the semantic-family silent
+        // drop, not error. Constructed directly (no terminal
+        // takeover); the drop arm writes nothing.
+        let mut fe = Frontend {
+            out: BufWriter::new(io::stdout()),
+            size: CellSize::new(24, 80),
+            raw_mode: false,
+            alt_screen: false,
+            bracketed_paste: false,
+            mouse: false,
+            keyboard_enhancement: false,
+        };
+        fe.apply_message(&InstanceMessage::ThemeFacts {
+            faces: vec![pmacs_protocol::ThemeFace {
+                name: "ui.modeline".into(),
+                style: Style::default(),
+            }],
+        })
+        .expect("the grid frontend must drop ThemeFacts silently");
+    }
+
     #[test]
     fn emit_span_writes_cursor_move_then_chars() {
         let span = DiffSpan {
diff --git a/src/highlight.rs b/src/highlight.rs
index bce8c71..8b10981 100644
--- a/src/highlight.rs
+++ b/src/highlight.rs
@@ -58,12 +58,39 @@ use crate::view::{View, Viewport};
 /// the same hierarchy in both cases.
 #[derive(Clone, Debug, Default)]
 pub struct Theme {
-    /// Direct map from capture name → style. T M4.3.
+    /// Direct map from capture name → style. T M4.3. Names matching
+    /// [`is_face_name`] (`ui` / `ui.*`) are UI faces (themes arc
+    /// Q#TH2), reserved by convention — no tree-sitter capture or LSP
+    /// token type uses them.
     pub by_capture: HashMap<String, Style>,
     /// Fallback style when no capture matches. Defaults to the
     /// terminal default colors (no override) so unhighlighted text
     /// looks identical to plain rendering.
     pub default_style: Style,
+    /// Monotonic syntax-mutation counter (themes arc Q#TH6). Bumped
+    /// by every successful Lua mutation that commits a non-face key
+    /// (or touches `default_style`); keys the `StyleGate` and the
+    /// minimap summary so a mid-session recolor re-ships spans.
+    /// INVARIANT: only ever incremented — a wholesale `set` must
+    /// replace `by_capture`, never the whole `Theme`, or consecutive
+    /// mutations share an epoch and become invisible to every gate.
+    pub syntax_epoch: u64,
+    /// Monotonic face-mutation counter (themes arc Q#TH6). Bumped by
+    /// every successful Lua mutation that commits a face key
+    /// ([`is_face_name`]); keys the `ThemeFacts` producer and the
+    /// minimap summary (`ui.diag.*` feeds its marks). Same
+    /// increment-only invariant as `syntax_epoch`.
+    pub face_epoch: u64,
+}
+
+/// Themes arc Q#TH2: the face predicate. A theme key names a UI face
+/// iff it is exactly `ui` (the deliberate inheritance catch-all —
+/// [`Theme::face`]'s walk terminal) or starts with `ui.`. Shared by
+/// the namespace reservation, the mutation-counter classification,
+/// and the `ThemeFacts` producer's key filter.
+#[must_use]
+pub fn is_face_name(name: &str) -> bool {
+    name == "ui" || name.starts_with("ui.")
 }
 
 impl Theme {
@@ -151,6 +178,8 @@ impl Theme {
         Self {
             by_capture,
             default_style: Style::default(),
+            syntax_epoch: 0,
+            face_epoch: 0,
         }
     }
 
@@ -171,6 +200,32 @@ impl Theme {
         }
     }
 
+    /// Resolve a UI face name to its style, or `None` when unset
+    /// (themes arc Q#TH4). Same dotted-prefix walk as [`Self::lookup`]
+    /// — so `ui.search.match.active` falls back to `ui.search.match`,
+    /// the `ui.diag.*` children to `ui.diag`, and everything to the
+    /// bare-`ui` catch-all — but the walk returns `None` instead of
+    /// falling back to `default_style`: an unset face must leave the
+    /// paint site's hardcoded default untouched, and a user's
+    /// `pmacs.theme.default` (a *syntax* fallback) must never bleed
+    /// into chrome. An exact entry stops the walk, so an explicitly
+    /// empty child (e.g. `ui.diag.error = {}`) blocks inheritance
+    /// from a themed parent. Callers pass full face names only.
+    #[must_use]
+    pub fn face(&self, name: &str) -> Option<Style> {
+        debug_assert!(is_face_name(name), "face() takes ui/ui.* names");
+        let mut name = name;
+        loop {
+            if let Some(s) = self.by_capture.get(name) {
+                return Some(*s);
+            }
+            match name.rfind('.') {
+                Some(idx) => name = &name[..idx],
+                None => return None,
+            }
+        }
+    }
+
     /// Set the style for one capture name, replacing any prior entry.
     pub fn insert(&mut self, capture_name: impl Into<String>, style: Style) {
         self.by_capture.insert(capture_name.into(), style);
@@ -685,6 +740,83 @@ mod tests {
         assert!(!s.bold);
     }
 
+    #[test]
+    fn face_returns_none_when_unset_never_default_style() {
+        // Q#TH4: an unset face leaves the paint site's hardcoded
+        // default untouched — even a loud user default_style (a
+        // SYNTAX fallback) must not bleed into chrome.
+        let mut t = Theme::empty();
+        t.default_style = Style {
+            bold: true,
+            ..Style::default()
+        };
+        assert_eq!(t.face("ui.modeline"), None);
+        assert_eq!(t.face("ui"), None);
+        // lookup, by contrast, resolves through to default_style.
+        assert!(t.lookup("ui.modeline").bold);
+    }
+
+    #[test]
+    fn face_walks_dotted_prefixes_to_the_ui_catch_all() {
+        let mut t = Theme::empty();
+        t.insert(
+            "ui",
+            Style {
+                italic: true,
+                ..Style::default()
+            },
+        );
+        t.insert(
+            "ui.search.match",
+            Style {
+                bold: true,
+                ..Style::default()
+            },
+        );
+        // Exact match.
+        assert!(t.face("ui.search.match").expect("set").bold);
+        // One-segment fallback: active inherits from ui.search.match.
+        assert!(t.face("ui.search.match.active").expect("inherit").bold);
+        // Everything else falls to the bare-ui catch-all.
+        assert!(t.face("ui.modeline").expect("catch-all").italic);
+        assert!(t.face("ui.diag.error").expect("catch-all").italic);
+    }
+
+    #[test]
+    fn face_exact_empty_child_blocks_parent_inheritance() {
+        // Q#TH5 (round 3 finding 4): with a themed ui.diag parent, an
+        // explicitly empty ui.diag.error child stops the walk at the
+        // exact entry — errors reset to the built-in (the Default fg
+        // policy applies at the consumer) while siblings inherit.
+        let mut t = Theme::empty();
+        t.insert(
+            "ui.diag",
+            Style {
+                fg: Color::Indexed(93),
+                ..Style::default()
+            },
+        );
+        t.insert("ui.diag.error", Style::default());
+        assert_eq!(t.face("ui.diag.error"), Some(Style::default()));
+        assert_eq!(
+            t.face("ui.diag.warning").expect("inherits").fg,
+            Color::Indexed(93)
+        );
+    }
+
+    #[test]
+    fn face_predicate_accepts_ui_root_and_prefix_only() {
+        // Q#TH2: exactly `ui` or `ui.`-prefixed — nothing else. A
+        // name like `uix` must classify as syntax, not face.
+        assert!(is_face_name("ui"));
+        assert!(is_face_name("ui.modeline"));
+        assert!(is_face_name("ui.search.match.active"));
+        assert!(!is_face_name("uix"));
+        assert!(!is_face_name("u"));
+        assert!(!is_face_name("keyword"));
+        assert!(!is_face_name("gui.modeline"));
+    }
+
     #[test]
     fn line_offsets_basic() {
         let src = b"a\nbb\nccc";
diff --git a/src/lua_bindings/diag.rs b/src/lua_bindings/diag.rs
index 08951f5..c462f44 100644
--- a/src/lua_bindings/diag.rs
+++ b/src/lua_bindings/diag.rs
@@ -43,7 +43,11 @@ fn diagnostic_to_lua(lua: &Lua, d: &Diagnostic) -> mlua::Result<Table> {
     clippy::too_many_lines,
     reason = "linear list of raw bindings; splitting fragments a coherent surface"
 )]
-pub fn install_diag(lua: &Lua, manager: &SharedLspManager) -> mlua::Result<()> {
+pub fn install_diag(
+    lua: &Lua,
+    manager: &SharedLspManager,
+    theme: &crate::highlight::ThemeHandle,
+) -> mlua::Result<()> {
     let pmacs: Table = lua.globals().get("pmacs")?;
     let diag_mod = lua.create_table()?;
 
@@ -202,6 +206,7 @@ pub fn install_diag(lua: &Lua, manager: &SharedLspManager) -> mlua::Result<()> {
     // per buffer; double-attach stacks duplicate overlays.
     {
         let m = manager.clone();
+        let th = theme.clone();
         diag_mod.set(
             "_attach_view",
             lua.create_function(move |lua, (id, uri): (BufferIdLua, String)| {
@@ -217,7 +222,10 @@ pub fn install_diag(lua: &Lua, manager: &SharedLspManager) -> mlua::Result<()> {
                         id.0
                     )));
                 }
-                let overlay = crate::diag::DiagnosticView::new(uri, store_handle);
+                // Themes Q#TH9: the Lua attachment path threads the
+                // shared theme so ui.diag.* faces reach the squiggles
+                // and gutter signs.
+                let overlay = crate::diag::DiagnosticView::new(uri, store_handle, Some(th.clone()));
                 win.push_overlay(Box::new(overlay));
                 Ok(true)
             })?,
diff --git a/src/lua_bindings/mod.rs b/src/lua_bindings/mod.rs
index 0ad2752..b153ffd 100644
--- a/src/lua_bindings/mod.rs
+++ b/src/lua_bindings/mod.rs
@@ -55,7 +55,7 @@ use crate::buffer_registry::BufferRegistry;
 use crate::cell::{Color, Style, UnderlineStyle};
 use crate::command::{Command, CommandError, CommandRegistry, SourceLocation};
 use crate::editor_core::EditorCore;
-use crate::highlight::{SyntaxHighlightView, Theme};
+use crate::highlight::SyntaxHighlightView;
 use crate::hook::{Hook, HookRegistry};
 use crate::key::{display_sequence, parse_sequence};
 use crate::keymap_stack::KeymapStack;
@@ -6862,18 +6862,26 @@ fn underline_to_lua(style: UnderlineStyle) -> &'static str {
 /// default to the same values as `Style::default()` --- a Lua table
 /// with `{ bold = true }` produces a style that is otherwise
 /// terminal-default.
+///
+/// Every lookup PROPAGATES its error (PR #120 round 1 finding 2):
+/// `Table::get` runs `__index`, so a raising metatable must fail the
+/// enclosing transactional mutation (Q#TH6 all-or-nothing), not
+/// silently parse as an all-default style and let sibling entries
+/// commit. Color/underline fields validate strictly through their
+/// converters; the boolean fields follow Lua truthiness (mlua's
+/// `bool` conversion), so `reverse = 1` reads as `true` by design.
 fn lua_to_style(t: &Table) -> mlua::Result<Style> {
-    let fg: mlua::Value = t.get("fg").unwrap_or(mlua::Value::Nil);
-    let bg: mlua::Value = t.get("bg").unwrap_or(mlua::Value::Nil);
-    let underline: mlua::Value = t.get("underline").unwrap_or(mlua::Value::Nil);
-    let underline_color: mlua::Value = t.get("underline_color").unwrap_or(mlua::Value::Nil);
+    let fg: mlua::Value = t.get("fg")?;
+    let bg: mlua::Value = t.get("bg")?;
+    let underline: mlua::Value = t.get("underline")?;
+    let underline_color: mlua::Value = t.get("underline_color")?;
     Ok(Style {
         fg: lua_to_color(&fg)?,
         bg: lua_to_color(&bg)?,
-        bold: t.get("bold").unwrap_or(false),
-        italic: t.get("italic").unwrap_or(false),
+        bold: t.get::<Option<bool>>("bold")?.unwrap_or(false),
+        italic: t.get::<Option<bool>>("italic")?.unwrap_or(false),
         underline: lua_to_underline(&underline)?,
-        reverse: t.get("reverse").unwrap_or(false),
+        reverse: t.get::<Option<bool>>("reverse")?.unwrap_or(false),
         underline_color: lua_to_color(&underline_color)?,
     })
 }
@@ -6895,6 +6903,83 @@ fn style_to_lua(lua: &Lua, style: Style) -> mlua::Result<Table> {
 /// attached [`SyntaxHighlightView`] sees the change on its next
 /// render. T M4.3 acceptance: "theming via Lua-defined color
 /// schemes."
+/// Themes arc Q#TH6: how [`commit_theme_entries`] applies a parsed
+/// entry set to the theme's capture map.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+enum ThemeCommit {
+    /// `pmacs.theme.set`: the parsed entries become the whole map
+    /// (faces wiped with captures, Q#TH10); `default_style` is
+    /// untouched.
+    Replace,
+    /// `pmacs.theme.merge`: insert/overwrite the parsed entries.
+    Merge,
+}
+
+/// Themes arc Q#TH6: the transactional mutation helper behind
+/// `pmacs.theme.set` / `pmacs.theme.merge`. Collects the WHOLE entry
+/// stream before touching the theme lock, so a malformed entry
+/// anywhere in the input returns its error with the theme untouched
+/// and the mutation counters unbumped — the pre-fix `merge` inserted
+/// while iterating, letting early entries land before a later one
+/// failed. After a successful commit the counters bump from their
+/// prior values (never reset — [`crate::highlight::Theme`]'s
+/// increment-only invariant): `Replace` touches both namespaces
+/// wholesale so it bumps both; `Merge` classifies every committed
+/// key through [`crate::highlight::is_face_name`] (bare `ui`
+/// included) and bumps `syntax_epoch` iff any non-face key
+/// committed, `face_epoch` iff any face key did.
+fn commit_theme_entries(
+    theme: &crate::highlight::ThemeHandle,
+    mode: ThemeCommit,
+    entries: impl Iterator<Item = mlua::Result<(String, Style)>>,
+) -> mlua::Result<()> {
+    let entries: Vec<(String, Style)> = entries.collect::<mlua::Result<_>>()?;
+    let mut th = theme.lock().expect("theme mutex poisoned");
+    match mode {
+        ThemeCommit::Replace => {
+            // Replace the FIELD, never the `Theme` value: a fresh
+            // Theme's zeroed counters would let consecutive `set`
+            // calls share an epoch and stay invisible to every gate.
+            th.by_capture = entries.into_iter().collect();
+            th.syntax_epoch += 1;
+            th.face_epoch += 1;
+        }
+        ThemeCommit::Merge => {
+            let any_face = entries
+                .iter()
+                .any(|(n, _)| crate::highlight::is_face_name(n));
+            let any_syntax = entries
+                .iter()
+                .any(|(n, _)| !crate::highlight::is_face_name(n));
+            for (name, style) in entries {
+                th.by_capture.insert(name, style);
+            }
+            if any_syntax {
+                th.syntax_epoch += 1;
+            }
+            if any_face {
+                th.face_epoch += 1;
+            }
+        }
+    }
+    Ok(())
+}
+
+/// Adapt a Lua theme table to [`commit_theme_entries`]'s ordered
+/// result stream: each raw `(name, style_table)` pair maps through
+/// [`lua_to_style`], and any iteration or conversion error rides the
+/// stream so the helper can fail before locking.
+fn lua_theme_entries(table: &Table) -> impl Iterator<Item = mlua::Result<(String, Style)>> + use<> {
+    table
+        .pairs::<String, Table>()
+        .map(|pair| {
+            let (name, style) = pair?;
+            Ok((name, lua_to_style(&style)?))
+        })
+        .collect::<Vec<_>>()
+        .into_iter()
+}
+
 fn install_theme(lua: &Lua, syntax: &SharedSyntaxRegistry) -> mlua::Result<Table> {
     let theme_mod = lua.create_table()?;
 
@@ -6903,17 +6988,7 @@ fn install_theme(lua: &Lua, syntax: &SharedSyntaxRegistry) -> mlua::Result<Table
         theme_mod.set(
             "set",
             lua.create_function(move |_, table: Table| {
-                let mut new_theme = Theme::empty();
-                table.for_each(|name: String, style: Table| {
-                    new_theme.insert(name, lua_to_style(&style)?);
-                    Ok(())
-                })?;
-                let theme = s.theme();
-                let mut th = theme.lock().expect("theme mutex poisoned");
-                let prev_default = th.default_style;
-                *th = new_theme;
-                th.default_style = prev_default;
-                Ok(())
+                commit_theme_entries(&s.theme(), ThemeCommit::Replace, lua_theme_entries(&table))
             })?,
         )?;
     }
@@ -6923,13 +6998,7 @@ fn install_theme(lua: &Lua, syntax: &SharedSyntaxRegistry) -> mlua::Result<Table
         theme_mod.set(
             "merge",
             lua.create_function(move |_, table: Table| {
-                let theme = s.theme();
-                let mut th = theme.lock().expect("theme mutex poisoned");
-                table.for_each(|name: String, style: Table| {
-                    th.insert(name, lua_to_style(&style)?);
-                    Ok(())
-                })?;
-                Ok(())
+                commit_theme_entries(&s.theme(), ThemeCommit::Merge, lua_theme_entries(&table))
             })?,
         )?;
     }
@@ -6952,7 +7021,11 @@ fn install_theme(lua: &Lua, syntax: &SharedSyntaxRegistry) -> mlua::Result<Table
             "clear",
             lua.create_function(move |_, ()| {
                 let theme = s.theme();
-                theme.lock().expect("theme mutex poisoned").clear();
+                let mut th = theme.lock().expect("theme mutex poisoned");
+                th.clear();
+                // Q#TH6: clear empties both namespaces — bump both.
+                th.syntax_epoch += 1;
+                th.face_epoch += 1;
                 Ok(())
             })?,
         )?;
@@ -6963,8 +7036,13 @@ fn install_theme(lua: &Lua, syntax: &SharedSyntaxRegistry) -> mlua::Result<Table
         theme_mod.set(
             "default",
             lua.create_function(move |_, style: Table| {
+                // Q#TH6: parse before locking; default_style is a
+                // syntax-namespace fallback, so bump syntax only.
+                let parsed = lua_to_style(&style)?;
                 let theme = s.theme();
-                theme.lock().expect("theme mutex poisoned").default_style = lua_to_style(&style)?;
+                let mut th = theme.lock().expect("theme mutex poisoned");
+                th.default_style = parsed;
+                th.syntax_epoch += 1;
                 Ok(())
             })?,
         )?;
@@ -8623,7 +8701,7 @@ pub fn make_lsp_manager(
 ) -> mlua::Result<SharedLspManager> {
     let manager = Rc::new(RefCell::new(LspManager::new(supervisor, runtime)));
     install_lsp(lua, &manager, syntax)?;
-    diag::install_diag(lua, &manager)?;
+    diag::install_diag(lua, &manager, &syntax.theme())?;
     install_completion(lua, &manager)?;
     install_hover(lua, &manager)?;
     install_signature(lua, &manager)?;
@@ -12118,6 +12196,123 @@ mod tests {
         (lua, reg, cmds, kms, hks)
     }
 
+    /// A theme handle with one syntax entry and nonzero counters, for
+    /// pinning that failed commits change nothing and successful ones
+    /// bump from the PRIOR values (themes arc Q#TH6).
+    fn seeded_theme() -> crate::highlight::ThemeHandle {
+        let mut th = crate::highlight::Theme::empty();
+        th.insert(
+            "keyword",
+            Style {
+                bold: true,
+                ..Style::default()
+            },
+        );
+        th.syntax_epoch = 3;
+        th.face_epoch = 5;
+        std::sync::Arc::new(std::sync::Mutex::new(th))
+    }
+
+    #[test]
+    fn theme_commit_is_all_or_nothing_with_untouched_counters() {
+        // Q#TH6 / acceptance 11 (the deterministic bite): an ordered
+        // entry stream whose TAIL is malformed must error with zero
+        // theme mutation — the helper collects the whole stream
+        // before taking the lock. The pre-fix merge inserted while
+        // iterating, so the leading Ok entry landed before the Err.
+        let theme = seeded_theme();
+        let entries: Vec<mlua::Result<(String, Style)>> = vec![
+            Ok((
+                "string".to_owned(),
+                Style {
+                    italic: true,
+                    ..Style::default()
+                },
+            )),
+            Err(mlua::Error::RuntimeError("malformed style".into())),
+        ];
+        let res = commit_theme_entries(&theme, ThemeCommit::Merge, entries.into_iter());
+        assert!(res.is_err(), "a malformed tail entry must error");
+        let th = theme.lock().expect("lock");
+        assert!(
+            !th.by_capture.contains_key("string"),
+            "the leading Ok entry must NOT have landed"
+        );
+        assert!(
+            th.by_capture.contains_key("keyword"),
+            "pre-existing entries survive"
+        );
+        assert_eq!(th.syntax_epoch, 3, "failed commit bumps nothing");
+        assert_eq!(th.face_epoch, 5, "failed commit bumps nothing");
+    }
+
+    #[test]
+    fn theme_commit_replace_advances_counters_from_prior_values() {
+        // Q#TH6 / acceptance 10: consecutive wholesale replacements
+        // must each advance the counters — replacing the FIELD, not
+        // the Theme value, or two `set`s share an epoch. Replace also
+        // leaves default_style alone (the historical `set` contract).
+        let theme = seeded_theme();
+        theme.lock().expect("lock").default_style = Style {
+            reverse: true,
+            ..Style::default()
+        };
+        for expected in [(4, 6), (5, 7)] {
+            let entries: Vec<mlua::Result<(String, Style)>> =
+                vec![Ok(("type".to_owned(), Style::default()))];
+            commit_theme_entries(&theme, ThemeCommit::Replace, entries.into_iter())
+                .expect("commit");
+            let th = theme.lock().expect("lock");
+            assert_eq!((th.syntax_epoch, th.face_epoch), expected);
+            assert!(!th.by_capture.contains_key("keyword"), "replaced wholesale");
+            assert!(th.default_style.reverse, "default_style preserved");
+        }
+    }
+
+    #[test]
+    fn theme_commit_merge_classifies_face_and_syntax_keys() {
+        // Q#TH6: merge bumps syntax_epoch iff any non-face key
+        // committed and face_epoch iff any face key did — bare `ui`
+        // classifies as a face (Q#TH2, round 2 finding 3).
+        let theme = seeded_theme();
+        // One lock per observation: two `lock()` calls inside one
+        // tuple expression self-deadlock (the first guard outlives
+        // the second call).
+        let epochs = |theme: &crate::highlight::ThemeHandle| {
+            let th = theme.lock().expect("lock");
+            (th.syntax_epoch, th.face_epoch)
+        };
+
+        let face_only: Vec<mlua::Result<(String, Style)>> =
+            vec![Ok(("ui.modeline".to_owned(), Style::default()))];
+        commit_theme_entries(&theme, ThemeCommit::Merge, face_only.into_iter()).expect("commit");
+        assert_eq!(
+            epochs(&theme),
+            (3, 6),
+            "face-only merge bumps face_epoch only"
+        );
+
+        let bare_ui: Vec<mlua::Result<(String, Style)>> =
+            vec![Ok(("ui".to_owned(), Style::default()))];
+        commit_theme_entries(&theme, ThemeCommit::Merge, bare_ui.into_iter()).expect("commit");
+        assert_eq!(epochs(&theme), (3, 7), "bare ui is a face key");
+
+        let mixed: Vec<mlua::Result<(String, Style)>> = vec![
+            Ok(("comment".to_owned(), Style::default())),
+            Ok(("ui.gutter".to_owned(), Style::default())),
+        ];
+        commit_theme_entries(&theme, ThemeCommit::Merge, mixed.into_iter()).expect("commit");
+        assert_eq!(epochs(&theme), (4, 8), "mixed merge bumps both");
+
+        let empty: Vec<mlua::Result<(String, Style)>> = Vec::new();
+        commit_theme_entries(&theme, ThemeCommit::Merge, empty.into_iter()).expect("commit");
+        assert_eq!(
+            epochs(&theme),
+            (4, 8),
+            "an empty merge commits nothing and bumps nothing"
+        );
+    }
+
     #[test]
     fn create_query_insert_observe_round_trip() {
         let (lua, _reg, _cmds, _kms, _hks) = fresh();
diff --git a/src/protocol.rs b/src/protocol.rs
index 43c361d..0805b3f 100644
--- a/src/protocol.rs
+++ b/src/protocol.rs
@@ -1683,7 +1683,7 @@ mod tests {
     // --- M5.5a handshake & postcard round-trips ---
 
     #[test]
-    fn protocol_version_is_fifteen_for_completion_popup() {
+    fn protocol_version_is_sixteen_for_theme_facts() {
         // Pin the value: T M10.5 bumped 1→2 (v1.0 wire: CrdtOp /
         // PresenceUpdate). T M11.1 bumped 2→3 (v1.1 wire: the
         // SemanticFrame family + FrontendEvent::Viewport). T M11.6
@@ -1706,8 +1706,10 @@ mod tests {
         // gutter modes bumped 13→14 (`LineNumbers` swapped `enabled: bool`
         // for a `LineNumberMode` enum — encoding change, still daemon-gated).
         // Arc 1a Q#C5 bumped 14→15 (`InstanceMessage::CompletionPopup`,
-        // additive + daemon-gated).
-        assert_eq!(PROTOCOL_VERSION, 15);
+        // additive + daemon-gated). Themes Q#TH7 bumped 15→16
+        // (`InstanceMessage::ThemeFacts`, additive + daemon-gated,
+        // appended as the final variant — see the placement pin).
+        assert_eq!(PROTOCOL_VERSION, 16);
     }
 
     #[test]
@@ -1781,21 +1783,84 @@ mod tests {
         // (`TripleDown`), v8 (`StatusFacts`), v9 + v10 (`SearchPrompt` +
         // regex/invalid), v11 (the context menu), v12 (the GUI
         // minibuffer), v13 (`LineNumbers`), v14 (`LineNumberMode`), v15
-        // (`CompletionPopup`) all interoperate, so v6 through v15 talk.
-        for accepted in 6..=15 {
+        // (`CompletionPopup`), v16 (`ThemeFacts`) all interoperate, so
+        // v6 through v16 talk.
+        for accepted in 6..=16 {
             assert!(
                 is_supported_protocol_version(accepted),
                 "v{accepted} must be accepted"
             );
         }
-        for rejected in [0, 1, 2, 3, 4, 5, 16, u32::MAX] {
+        for rejected in [0, 1, 2, 3, 4, 5, 17, u32::MAX] {
             assert!(
                 !is_supported_protocol_version(rejected),
-                "v{rejected} must be rejected by a v15 binary"
+                "v{rejected} must be rejected by a v16 binary"
             );
         }
     }
 
+    #[test]
+    fn theme_facts_round_trips_through_postcard() {
+        // Themes Q#TH7 (v16): the daemon-resolved UI face table. Pin
+        // the empty (authoritative-unthemed) and populated shapes.
+        for msg in [
+            InstanceMessage::ThemeFacts { faces: Vec::new() },
+            InstanceMessage::ThemeFacts {
+                faces: vec![
+                    pmacs_protocol::ThemeFace {
+                        name: "ui.gutter".into(),
+                        style: crate::cell::Style {
+                            fg: crate::cell::Color::Indexed(245),
+                            ..crate::cell::Style::default()
+                        },
+                    },
+                    pmacs_protocol::ThemeFace {
+                        name: "ui.modeline".into(),
+                        style: crate::cell::Style {
+                            fg: crate::cell::Color::Rgb(200, 200, 210),
+                            bg: crate::cell::Color::Rgb(30, 30, 46),
+                            ..crate::cell::Style::default()
+                        },
+                    },
+                ],
+            },
+        ] {
+            let bytes = postcard::to_allocvec(&msg).expect("encode");
+            let decoded: InstanceMessage = postcard::from_bytes(&bytes).expect("decode");
+            assert_eq!(msg, decoded);
+        }
+    }
+
+    #[test]
+    fn completion_popup_encoding_is_unchanged_by_the_v16_build() {
+        // Themes Q#TH7 placement pin: postcard discriminants are
+        // ordinal, so a variant inserted anywhere before the end of
+        // `InstanceMessage` would shift every later variant's tag and
+        // silently corrupt v15 peers on channels that are NOT
+        // version-gated. `ThemeFacts` must therefore be APPENDED after
+        // `CompletionPopup` — the final v15 variant, whose ordinal
+        // moves if anything is inserted before any v15 variant. These
+        // are the exact bytes a v15 binary produced for this value
+        // (discriminant 22 as a postcard varint, then the fields);
+        // the new variant's own round-trip cannot detect a shift.
+        let msg = InstanceMessage::CompletionPopup {
+            buffer_id: pmacs_protocol::BufferId::from_raw(3),
+            anchor: Some(5),
+            prefix_len: 2,
+            rows: Vec::new(),
+            selected: None,
+            total: 9,
+        };
+        let bytes = postcard::to_allocvec(&msg).expect("encode");
+        assert_eq!(
+            bytes,
+            [22, 3, 1, 5, 2, 0, 0, 9],
+            "CompletionPopup's v15 wire bytes changed — a variant was \
+             inserted before it; append new InstanceMessage variants \
+             at the end"
+        );
+    }
+
     #[test]
     fn hello_round_trips_through_postcard() {
         let h = Hello {
diff --git a/src/search.rs b/src/search.rs
index fbe7f2b..7ff49c1 100644
--- a/src/search.rs
+++ b/src/search.rs
@@ -385,6 +385,10 @@ fn active_match_style() -> Style {
 /// maps to one row.
 pub struct SearchView {
     store: SharedSearchStore,
+    /// Shared theme for the `ui.search.match(.active)` wash faces
+    /// (themes arc Q#TH9). `None` — a bare core with no injected
+    /// theme — paints the built-in yellow literals.
+    theme: Option<crate::highlight::ThemeHandle>,
 }
 
 impl SearchView {
@@ -393,10 +397,11 @@ impl SearchView {
     /// ([`Buffer::id`]) rather than a fixed id, so a single attached
     /// instance keeps highlighting correctly even if the window
     /// switches buffers (the store is per-buffer; a buffer with no
-    /// search entry simply paints nothing).
+    /// search entry simply paints nothing). Wash faces resolve
+    /// through `theme` when given.
     #[must_use]
-    pub fn new(store: SharedSearchStore) -> Self {
-        Self { store }
+    pub fn new(store: SharedSearchStore, theme: Option<crate::highlight::ThemeHandle>) -> Self {
+        Self { store, theme }
     }
 }
 
@@ -437,11 +442,36 @@ impl View for SearchView {
         let max_cols = viewport.cell_size.cols;
         let cell_origin = viewport.cell_origin;
 
+        // Themes Q#TH5: a set wash face replaces the default overlay
+        // wholesale within its {bg} mask — the face's bg is the wash,
+        // everything else plain (so `ui.search.match = {}` disables
+        // the wash; out-of-mask fg/reverse are never read). Unset
+        // keeps today's literals. One theme clone per render (Q#TH9).
+        let (match_overlay, active_overlay) = {
+            let theme = self
+                .theme
+                .as_ref()
+                .map(|t| t.lock().expect("theme mutex poisoned").clone());
+            let resolve = |name: &str, fallback: fn() -> Style| -> Style {
+                theme
+                    .as_ref()
+                    .and_then(|t| t.face(name))
+                    .map_or_else(fallback, |f| Style {
+                        bg: f.bg,
+                        ..Style::default()
+                    })
+            };
+            (
+                resolve("ui.search.match", match_style),
+                resolve("ui.search.match.active", active_match_style),
+            )
+        };
+
         for m in &matches {
             let style = if Some(*m) == active {
-                active_match_style()
+                active_overlay
             } else {
-                match_style()
+                match_overlay
             };
             // A regex match may span multiple lines (Q#RX4); wash each
             // row's clipped slice, mirroring the selection renderer.
@@ -707,7 +737,7 @@ mod tests {
             .unwrap()
             .set(bid, "lo", find_all(b"lo lo lo\n", "lo"));
 
-        let mut view = SearchView::new(store.clone());
+        let mut view = SearchView::new(store.clone(), None);
         let mut backing = vec![Cell::default(); 10];
         let mut grid = CellGrid {
             cells: &mut backing,
@@ -783,7 +813,7 @@ mod tests {
             stride: cols,
             size: CellSize::new(rows, cols),
         };
-        SearchView::new(store.clone()).render(
+        SearchView::new(store.clone(), None).render(
             &buf,
             Viewport {
                 buffer_start: 0,
diff --git a/src/semantic_render.rs b/src/semantic_render.rs
index 216cb85..cf64e7a 100644
--- a/src/semantic_render.rs
+++ b/src/semantic_render.rs
@@ -160,14 +160,27 @@ pub struct SemanticRenderState {
     /// buffer at the same generation re-uses what the frontend
     /// already has and emits nothing. First emission happens on the
     /// first frame for a buffer; further emissions only after edits.
-    /// `(crdt_generation, diag_epoch)` the last emitted summary was
-    /// computed against. Diagnostics arrive without a generation
-    /// bump, so the epoch half catches republishes (minimap marks,
-    /// T M4.6 GPU parity).
-    last_summary: HashMap<BufferId, (u64, u64)>,
+    /// `(crdt_generation, diag_epoch, syntax_epoch, face_epoch)` the
+    /// last summary was computed against, plus that computed payload.
+    /// Diagnostics arrive without a generation bump, so the diag
+    /// epoch catches republishes (minimap marks, T M4.6 GPU parity);
+    /// the theme epochs (Q#TH6) catch mid-session recolors —
+    /// `face_epoch` belongs in the key because `ui.diag.*` feeds the
+    /// marks. The payload copy backs the Q#TH6 payload-equality
+    /// suppression: a face edit that leaves the summary unchanged
+    /// (e.g. `ui.modeline`) recomputes once per mutation and emits
+    /// nothing. The key advances on COMPUTATION, not emission — a
+    /// suppressed send still inserts, or the whole-file recompute
+    /// repeats every tick.
+    last_summary: HashMap<BufferId, SummaryCache>,
     /// `(name, modified, diag_errors, diag_warnings, message)` last
     /// emitted as `StatusFacts` (Q#S1; `message` since v15) —
-    /// cached-compare suppression.
+    /// cached-compare suppression. A peer emission baseline ONLY:
+    /// the diagnostic-count freeze deliberately holds no session
+    /// state (rounds 3–4) — it is sourced from the diag store's
+    /// retained vector, so it needs nothing here to survive the
+    /// `on_buffer_snapshot_sent` reset and it holds for sessions
+    /// with no history (a late joiner attaching mid-edit).
     last_status: HashMap<BufferId, (String, bool, u32, u32, Option<String>)>,
     /// Last-emitted line-number gutter mode (UX gutter arc, protocol v14) —
     /// cached-compare suppression. Seeded to `Some(Off)` (the frontend's
@@ -193,11 +206,36 @@ pub struct SemanticRenderState {
     /// viewport* (which the GPU frontend sets to the entire buffer)
     /// and clones the theme — too expensive to repeat on every tick.
     /// The styling depends only on the parse bundle, the CRDT
-    /// generation, and the viewport — never the cursor — so a gate
-    /// built from those lets cursor-only ticks skip the query entirely.
-    /// Only the grammar (tree-sitter) path is gated; the LSP-token path
-    /// has no comparably cheap handle and recomputes as before.
+    /// generation, the viewport, and the theme's syntax epoch
+    /// (Q#TH6) — never the cursor — so a gate built from those lets
+    /// cursor-only ticks skip the query entirely while a mid-session
+    /// `pmacs.theme.set` still re-ships recolored spans without an
+    /// edit. Only the grammar (tree-sitter) path is gated; the
+    /// LSP-token path has no comparably cheap handle and recomputes
+    /// as before.
     last_style_gate: HashMap<BufferId, StyleGate>,
+    /// The theme `face_epoch` the `ThemeFacts` producer last
+    /// INSPECTED (Q#TH7) — `Option`, not a bare zero, because an
+    /// unthemed daemon sits at `face_epoch == 0` and a `0 == 0`
+    /// short-circuit would starve the first authoritative send.
+    /// Advances on computation, not emission: an identical rebuild
+    /// records the epoch it inspected even though nothing ships.
+    last_face_epoch: Option<u64>,
+    /// The face table the frontend believes (Q#TH7), seeded `None` so
+    /// every attachment receives exactly one authoritative table —
+    /// the empty table included — with its first emission after
+    /// viewport declaration. A frontend retaining face state across
+    /// attachments is therefore corrected even by an unthemed daemon.
+    last_theme_faces: Option<Vec<crate::protocol::ThemeFace>>,
+    /// Whether the peer negotiated protocol >= 16 (PR #120 round 1
+    /// finding 3). Faces reach a semantic frontend through TWO
+    /// channels: `ThemeFacts` (daemon write-loop gated) and the
+    /// `ui.diag.*` colors folded into `FileStyleSummary` — an OLDER
+    /// channel the version gate does not filter. A v15 peer must not
+    /// receive face-derived minimap marks while its squiggles, signs,
+    /// and counters stay unthemed, so this producer resolves faces
+    /// only when the peer can apply the whole face table.
+    peer_knows_theme_facts: bool,
     /// Cached byte↔line table for the diagnostics projection, keyed
     /// by buffer revision. Building it costs an O(buffer) rope copy
     /// plus a full scan; before this cache, that ran on *every tick*
@@ -215,6 +253,43 @@ struct DiagLineCache {
     source_len: u64,
 }
 
+/// One [`SemanticRenderState::last_summary`] entry: the inputs the
+/// summary was computed against and the computed per-line payload.
+struct SummaryCache {
+    /// `(crdt_generation, diag_epoch, syntax_epoch, face_epoch)`.
+    key: (u64, u64, u64, u64),
+    /// The computed summary — compared before emitting (Q#TH6
+    /// payload-equality suppression).
+    lines: Vec<Style>,
+}
+
+/// The stage-1 UI face inventory (themes arc Q#TH3): the names the
+/// `ThemeFacts` producer resolves through [`crate::highlight::Theme::face`]
+/// and ships. Resolution is daemon-side — frontends do exact-name
+/// lookup on the shipped table, no walk (Q#TH7). Kept sorted; the
+/// wire table's deterministic ordering rides on it.
+const UI_FACES: &[&str] = &[
+    "ui.diag.error",
+    "ui.diag.hint",
+    "ui.diag.info",
+    "ui.diag.warning",
+    "ui.gutter",
+    "ui.minibuffer",
+    "ui.minibuffer.candidate",
+    "ui.modeline",
+    "ui.search.match",
+    "ui.search.match.active",
+    "ui.selection",
+    "ui.statusline",
+];
+
+/// Read both theme mutation counters under one lock (Q#TH6).
+fn theme_epochs(state: &EditorState) -> (u64, u64) {
+    let theme = state.syntax_registry.theme();
+    let th = theme.lock().expect("theme mutex poisoned");
+    (th.syntax_epoch, th.face_epoch)
+}
+
 /// Recompute gate for [`scoped_style_spans`] on a grammar-backed
 /// buffer. Holds the current parse bundle `Arc` so its address stays
 /// stable while cached — comparing by `Arc::ptr_eq` then can't be
@@ -230,6 +305,11 @@ struct StyleGate {
     generation: u64,
     /// Declared viewport.
     visible: ByteRange,
+    /// The theme's syntax mutation counter (Q#TH6): spans are a pure
+    /// function of the theme too, and before this half the gate a
+    /// mid-session `pmacs.theme.set` shipped nothing until the next
+    /// buffer edit — the GPU kept stale colors.
+    syntax_epoch: u64,
 }
 
 impl StyleGate {
@@ -237,6 +317,7 @@ impl StyleGate {
     fn matches(&self, other: &Self) -> bool {
         self.generation == other.generation
             && self.visible == other.visible
+            && self.syntax_epoch == other.syntax_epoch
             && match (&self.bundle, &other.bundle) {
                 (Some(a), Some(b)) => std::sync::Arc::ptr_eq(a, b),
                 (None, None) => true,
@@ -246,8 +327,22 @@ impl StyleGate {
 }
 
 impl SemanticRenderState {
+    /// Fresh session state for a peer that negotiated
+    /// `negotiated_protocol_version` — the real daemon construction
+    /// path (PR #120 round 1 finding 3): a `< 16` peer gets no
+    /// `ThemeFacts` produced at all and, crucially, no face-derived
+    /// colors folded into its `FileStyleSummary` marks.
+    #[must_use]
+    pub fn for_peer(frontend_id: FrontendId, negotiated_protocol_version: u32) -> Self {
+        let mut s = Self::new(frontend_id);
+        s.peer_knows_theme_facts = negotiated_protocol_version >= 16;
+        s
+    }
+
     /// Fresh session state for frontend `frontend_id`: no viewport
-    /// declared, nothing sent.
+    /// declared, nothing sent. Assumes a current-build peer (>= 16);
+    /// daemon sessions with a real negotiated version use
+    /// [`Self::for_peer`].
     #[must_use]
     pub fn new(frontend_id: FrontendId) -> Self {
         Self {
@@ -268,6 +363,13 @@ impl SemanticRenderState {
             // toggle-on (or later toggle-off) ships a message.
             last_line_numbers: Some(crate::window::LineNumberMode::Off),
             last_style_gate: HashMap::new(),
+            // Q#TH7: both seeded None — the first frame after viewport
+            // declaration always ships an authoritative face table
+            // (empty included), and the epoch gate cannot short-circuit
+            // an epoch-0 daemon before that send.
+            last_face_epoch: None,
+            last_theme_faces: None,
+            peer_knows_theme_facts: true,
             diag_line_cache: HashMap::new(),
         }
     }
@@ -284,6 +386,48 @@ impl SemanticRenderState {
         });
     }
 
+    /// Snapshot/baseline reset contract (PR #120 round 2 finding 1).
+    ///
+    /// A `BufferSnapshot` resets the receiving frontend's
+    /// buffer-scoped render state wholesale — spans, decorations,
+    /// adornments, minimap summary, completion popup (see the GPU's
+    /// `BufferSnapshot` arm) — so every buffer-scoped emission
+    /// baseline this producer holds for that buffer must die with the
+    /// send. Otherwise an unchanged-key revisit (the A → B → A round
+    /// trip at one CRDT generation) suppresses every re-send and the
+    /// frontend never regains the state until an edit, diagnostic
+    /// republish, or theme mutation happens to move the key.
+    ///
+    /// Called by the daemon wherever it writes a `BufferSnapshot` to
+    /// this session's stream. Resetting when the write later fails is
+    /// harmless — the failure mode is one redundant re-send, never
+    /// staleness.
+    ///
+    /// Deliberately NOT reset: `last_face_epoch` / `last_theme_faces`
+    /// (`ThemeFacts` is bufferless — the frontend keeps its face
+    /// table across snapshots), `last_minibuffer` (one global core
+    /// instance, not buffer-scoped), `last_line_numbers`
+    /// (per-frontend gutter mode, kept by the frontend across the
+    /// switch), and `diag_line_cache` (a revision-keyed compute
+    /// cache, not a peer-state baseline). The diagnostic-count
+    /// freeze survives by construction (rounds 3–4): it is sourced
+    /// from the diag store's retained vector, never from session
+    /// state, so this reset cannot zero mid-edit counts. Baselines
+    /// for OTHER buffers also survive — the snapshot names one
+    /// buffer, and any buffer the frontend navigates to receives its
+    /// own snapshot first.
+    pub fn on_buffer_snapshot_sent(&mut self, buffer_id: BufferId) {
+        self.last_sent.remove(&buffer_id);
+        self.last_style_gate.remove(&buffer_id);
+        self.last_decorations.remove(&buffer_id);
+        self.last_adornments.remove(&buffer_id);
+        self.last_summary.remove(&buffer_id);
+        self.last_status.remove(&buffer_id);
+        self.last_search_prompt.remove(&buffer_id);
+        self.last_menu_prompt.remove(&buffer_id);
+        self.last_completion_popup.remove(&buffer_id);
+    }
+
     /// Project one frame.
     ///
     /// Returns up to three messages — [`InstanceMessage::StyleSpans`]
@@ -475,6 +619,8 @@ impl SemanticRenderState {
         out.extend(self.minibuffer_prompt_msg(state, vp.buffer_id));
         // --- CompletionPopup (Arc 1a Q#C5, protocol v15) ---
         out.extend(self.completion_popup_msg(state, vp.buffer_id));
+        // --- ThemeFacts (UI faces; themes arc Q#TH7, protocol v16) ---
+        out.extend(self.theme_facts_msg(state));
         out
     }
 
@@ -740,9 +886,14 @@ impl SemanticRenderState {
     /// nothing changed. Carries the facts a semantic frontend cannot
     /// derive locally: buffer name, modified flag, whole-file
     /// diagnostic counts (errors / warnings). Counts freeze at their
-    /// last value while the diag store is stale — mid-edit positions
-    /// are wrong but *counts* merely lag, and flickering to zero on
-    /// every keystroke would be worse. The daemon's write loop keeps
+    /// last published value while the diag store is stale — mid-edit
+    /// positions are wrong but *counts* merely lag, and flickering
+    /// to zero on every keystroke would be worse. The freeze IS the
+    /// store's retained state (rounds 3–5): `mark_stale` keeps the
+    /// last published diagnostics and their cached severity totals,
+    /// so reading the totals while stale yields the frozen value in
+    /// O(1) with no session state to lose — not to a snapshot reset,
+    /// and not by attaching mid-edit. The daemon's write loop keeps
     /// the variant off wires negotiated `< 8`.
     fn status_facts_msg(
         &mut self,
@@ -761,32 +912,32 @@ impl SemanticRenderState {
             let buf = reg.get(buffer_id).ok()?;
             (buf.name().to_owned(), buf.is_modified(), message)
         };
-        let counts = {
+        let (diag_errors, diag_warnings) = {
             let core = state.core.borrow();
-            buffer_file_uri(&core, buffer_id).and_then(|uri| {
+            buffer_file_uri(&core, buffer_id).map_or((0, 0), |uri| {
                 let store = state.lsp_manager.borrow().diag_store();
                 let guard = store.lock().expect("diag store mutex poisoned");
-                if guard.is_stale(&uri) {
-                    None // keep the cached counts
-                } else {
-                    let mut errors = 0u32;
-                    let mut warnings = 0u32;
-                    for d in guard.for_uri(&uri) {
-                        match d.severity {
-                            crate::diag::DiagnosticSeverity::Error => errors += 1,
-                            crate::diag::DiagnosticSeverity::Warning => warnings += 1,
-                            _ => {}
-                        }
-                    }
-                    Some((errors, warnings))
-                }
+                // Read even while the store is STALE (round 4):
+                // `mark_stale` keeps the last published diagnostics
+                // (T M11.8) — positions are invalid mid-edit, but
+                // counts merely lag, so the retained totals ARE the
+                // frozen value. Sourcing the freeze from the store
+                // rather than any per-session cache means a session
+                // first rendering during staleness — a late joiner,
+                // or a buffer first visited mid-edit — reports the
+                // preserved counts instead of zeros, and the snapshot
+                // reset has nothing count-related to preserve.
+                // `DiagnosticStore::set` computes this tuple once
+                // (round 5). StatusFacts runs at frame cadence for
+                // every semantic session, so rescanning the retained
+                // vector here would make stale intervals
+                // O(frames * diagnostics).
+                let (errors, warnings, _, _) = guard.severity_counts_for(&uri);
+                (errors, warnings)
             })
         };
-        let cached = self.last_status.get(&buffer_id);
-        let (diag_errors, diag_warnings) =
-            counts.unwrap_or_else(|| cached.map_or((0, 0), |c| (c.2, c.3)));
         let facts = (name, modified, diag_errors, diag_warnings, message);
-        if cached == Some(&facts) {
+        if self.last_status.get(&buffer_id) == Some(&facts) {
             return None;
         }
         let msg = InstanceMessage::StatusFacts {
@@ -910,13 +1061,48 @@ impl SemanticRenderState {
         // publish without a generation bump — key the cache on the
         // diag store's per-URI epoch as well, so a republish
         // refreshes the marks and anything else stays suppressed.
+        // The theme epochs (Q#TH6) join the key so a mid-session
+        // recolor refreshes the strokes — face_epoch included, since
+        // `ui.diag.*` feeds the marks.
         let diag_epoch = diagnostics_epoch(state, buffer_id);
-        if self.last_summary.get(&buffer_id).copied() == Some((generation, diag_epoch)) {
+        let (syntax_epoch, face_epoch) = theme_epochs(state);
+        // A v15 peer's marks never resolve faces (finding 3), so a
+        // face mutation cannot change its summary either — zero the
+        // key component rather than recompute a whole-file pass per
+        // face edit just to payload-suppress it.
+        let face_key = if self.peer_knows_theme_facts {
+            face_epoch
+        } else {
+            0
+        };
+        let key = (generation, diag_epoch, syntax_epoch, face_key);
+        if self
+            .last_summary
+            .get(&buffer_id)
+            .is_some_and(|c| c.key == key)
+        {
+            return None;
+        }
+        let lines = scoped_file_summary(state, buffer_id, self.peer_knows_theme_facts);
+        // Payload-equality suppression (Q#TH6): a face edit that
+        // leaves the summary unchanged (e.g. `ui.modeline`) emits
+        // nothing — but the key still advances, on computation rather
+        // than emission, or this whole-file pass would repeat every
+        // tick.
+        let unchanged = self
+            .last_summary
+            .get(&buffer_id)
+            .is_some_and(|c| c.lines == lines);
+        self.last_summary.insert(
+            buffer_id,
+            SummaryCache {
+                key,
+                lines: lines.clone(),
+            },
+        );
+        if unchanged {
             return None;
         }
-        let lines = scoped_file_summary(state, buffer_id);
-        self.last_summary
-            .insert(buffer_id, (generation, diag_epoch));
         Some(InstanceMessage::FileStyleSummary {
             buffer_id,
             generation,
@@ -924,6 +1110,49 @@ impl SemanticRenderState {
         })
     }
 
+    /// The `ThemeFacts` message for this frame, or `None` when the
+    /// face table is unchanged (themes arc Q#TH7, protocol v16).
+    /// Resolves the [`UI_FACES`] inventory through
+    /// [`crate::highlight::Theme::face`] under one lock — resolution
+    /// is daemon-side; frontends do exact-name lookup, no walk. The
+    /// `last_face_epoch` gate keeps unchanged ticks to one u64
+    /// compare; `last_theme_faces` (the frontend's believed table)
+    /// decides emission. Both advance on computation, and both seed
+    /// `None`, so every attachment ships exactly one authoritative
+    /// table — the empty table included — on its first frame.
+    fn theme_facts_msg(&mut self, state: &EditorState) -> Option<InstanceMessage> {
+        // PR #120 round 1 finding 3: never even produced for a peer
+        // below v16 (the daemon write-loop gate remains as the
+        // belt-and-braces filter).
+        if !self.peer_knows_theme_facts {
+            return None;
+        }
+        let theme = state.syntax_registry.theme();
+        let (faces, face_epoch) = {
+            let th = theme.lock().expect("theme mutex poisoned");
+            if self.last_face_epoch == Some(th.face_epoch) {
+                return None;
+            }
+            let faces: Vec<crate::protocol::ThemeFace> = UI_FACES
+                .iter()
+                .filter_map(|name| {
+                    th.face(name).map(|style| crate::protocol::ThemeFace {
+                        name: (*name).to_owned(),
+                        style,
+                    })
+                })
+                .collect();
+            (faces, th.face_epoch)
+        };
+        self.last_face_epoch = Some(face_epoch);
+        let unchanged = self.last_theme_faces.as_ref() == Some(&faces);
+        self.last_theme_faces = Some(faces.clone());
+        if unchanged {
+            return None;
+        }
+        Some(InstanceMessage::ThemeFacts { faces })
+    }
+
     /// Project the [`Decoration`] set intersecting the declared
     /// viewport: the session's selection (instance-authoritative,
     /// byte-native) and LSP diagnostics (line/col → byte, severity →
@@ -1481,6 +1710,7 @@ fn grammar_style_key(
         bundle: handle.current(),
         generation,
         visible: vp.visible,
+        syntax_epoch: theme_epochs(state).0,
     })
 }
 
@@ -1676,7 +1906,11 @@ fn lsp_scoped_style_spans(state: &EditorState, vp: &DeclaredViewport) -> Vec<Sty
 /// `O(spans × lines)` in the worst case; the caller short-circuits on
 /// unchanged CRDT generation so this only runs on first sight of a
 /// buffer or after an edit, not per frame.
-fn scoped_file_summary(state: &EditorState, buffer_id: BufferId) -> Vec<Style> {
+fn scoped_file_summary(
+    state: &EditorState,
+    buffer_id: BufferId,
+    resolve_faces: bool,
+) -> Vec<Style> {
     let source = {
         let core = state.core.borrow();
         let registry = core.registry.clone();
@@ -1707,7 +1941,7 @@ fn scoped_file_summary(state: &EditorState, buffer_id: BufferId) -> Vec<Style> {
     if spans.is_empty() {
         // No styled runs — but diagnostic marks are independent of
         // syntax styling (a plain-text buffer can still have lints).
-        overlay_diagnostic_marks(state, buffer_id, &mut out);
+        overlay_diagnostic_marks(state, buffer_id, &mut out, resolve_faces);
         return out;
     }
 
@@ -1740,7 +1974,7 @@ fn scoped_file_summary(state: &EditorState, buffer_id: BufferId) -> Vec<Style> {
             *line_dominant = winner.0;
         }
     }
-    overlay_diagnostic_marks(state, buffer_id, &mut out);
+    overlay_diagnostic_marks(state, buffer_id, &mut out, resolve_faces);
     out
 }
 
@@ -1752,7 +1986,12 @@ fn scoped_file_summary(state: &EditorState, buffer_id: BufferId) -> Vec<Style> {
 /// describe pre-edit text, same discipline as the decorations
 /// producer (the marks return on republish, which bumps the diag
 /// epoch and recomputes this summary).
-fn overlay_diagnostic_marks(state: &EditorState, buffer_id: BufferId, lines: &mut [Style]) {
+fn overlay_diagnostic_marks(
+    state: &EditorState,
+    buffer_id: BufferId,
+    lines: &mut [Style],
+    resolve_faces: bool,
+) {
     let uri = {
         let core = state.core.borrow();
         let Some(uri) = buffer_file_uri(&core, buffer_id) else {
@@ -1776,9 +2015,22 @@ fn overlay_diagnostic_marks(state: &EditorState, buffer_id: BufferId, lines: &mu
             *slot = Some(slot.map_or(d.severity, |s| s.min(d.severity)));
         }
     }
+    // Themes Q#TH5: the mark color is the RESOLVED severity color —
+    // `ui.diag.*` faces reach the minimap through this summary. The
+    // diag `Default`-fg policy guarantees a diagnosed line never
+    // writes `Default` here, which the GPU reads as "no mark".
+    // `resolve_faces` is false for a peer below v16 (PR #120 round 1
+    // finding 3): this summary is an ungated pre-v16 channel, and a
+    // v15 frontend must not get face-derived marks on one surface
+    // while every other severity surface stays unthemed.
+    let theme = resolve_faces.then(|| {
+        let handle = state.syntax_registry.theme();
+        let t = handle.lock().expect("theme mutex poisoned");
+        t.clone()
+    });
     for (line, severity) in lines.iter_mut().zip(best) {
         if let Some(s) = severity {
-            line.underline_color = s.underline_color();
+            line.underline_color = crate::diag::severity_color(theme.as_ref(), s);
         }
     }
 }
@@ -1877,10 +2129,256 @@ mod tests {
         );
     }
 
+    /// Pull the `ThemeFacts` table out of a frame, if any.
+    fn theme_facts_of(msgs: &[InstanceMessage]) -> Option<Vec<crate::protocol::ThemeFace>> {
+        msgs.iter().find_map(|m| match m {
+            InstanceMessage::ThemeFacts { faces } => Some(faces.clone()),
+            _ => None,
+        })
+    }
+
+    /// Simulate a committed face mutation: what `pmacs.theme.merge`
+    /// does after its transactional parse (insert + face-epoch bump).
+    fn merge_face(state: &EditorState, name: &str, style: Style) {
+        let theme = state.syntax_registry.theme();
+        let mut th = theme.lock().expect("theme mutex poisoned");
+        th.insert(name, style);
+        th.face_epoch += 1;
+    }
+
+    #[test]
+    fn theme_facts_authoritative_empty_then_silent_then_face_change_emits() {
+        // Q#TH7: the first frame after viewport declaration ships the
+        // authoritative table — EMPTY for an unthemed daemon, which
+        // the Option epoch gate must not short-circuit at 0 == 0 —
+        // then unchanged ticks say nothing; a face commit re-emits
+        // the resolved table.
+        let state = empty_state();
+        let mut s = local();
+        let buffer_id = active_buffer(&state);
+        s.set_viewport(buffer_id, ByteRange { start: 0, end: 64 }, 0);
+
+        let first = s.render_frame(&state);
+        assert_eq!(
+            theme_facts_of(&first),
+            Some(Vec::new()),
+            "an unthemed attachment still receives one authoritative empty table"
+        );
+        assert_eq!(
+            theme_facts_of(&s.render_frame(&state)),
+            None,
+            "unchanged ticks emit nothing"
+        );
+
+        merge_face(
+            &state,
+            "ui.gutter",
+            Style {
+                fg: crate::cell::Color::Indexed(99),
+                ..Style::default()
+            },
+        );
+        let facts = theme_facts_of(&s.render_frame(&state)).expect("face change emits");
+        assert_eq!(facts.len(), 1);
+        assert_eq!(facts[0].name, "ui.gutter");
+        assert_eq!(facts[0].style.fg, crate::cell::Color::Indexed(99));
+        assert_eq!(
+            theme_facts_of(&s.render_frame(&state)),
+            None,
+            "and suppresses again once shipped"
+        );
+    }
+
+    #[test]
+    fn theme_facts_resolution_is_daemon_side() {
+        // Q#TH7 / acceptance 15: with only `ui.diag` set, the shipped
+        // table carries the four concrete `ui.diag.*` children — the
+        // walk happens here, never in a frontend.
+        let state = empty_state();
+        let mut s = local();
+        let buffer_id = active_buffer(&state);
+        s.set_viewport(buffer_id, ByteRange { start: 0, end: 64 }, 0);
+        let _ = s.render_frame(&state);
+
+        merge_face(
+            &state,
+            "ui.diag",
+            Style {
+                fg: crate::cell::Color::Indexed(93),
+                ..Style::default()
+            },
+        );
+        let facts = theme_facts_of(&s.render_frame(&state)).expect("emits");
+        let names: Vec<&str> = facts.iter().map(|f| f.name.as_str()).collect();
+        assert_eq!(
+            names,
+            [
+                "ui.diag.error",
+                "ui.diag.hint",
+                "ui.diag.info",
+                "ui.diag.warning"
+            ],
+            "only the concrete stage-1 children ship, sorted"
+        );
+        assert!(
+            facts
+                .iter()
+                .all(|f| f.style.fg == crate::cell::Color::Indexed(93)),
+            "each child resolved through the parent"
+        );
+    }
+
+    #[test]
+    fn theme_facts_identical_rebuild_advances_epoch_without_emitting() {
+        // Q#TH7 / acceptance 14: an epoch bump with an unchanged
+        // table (an identical re-merge) emits nothing but still
+        // records the inspected epoch — the cache advances on
+        // computation, or every subsequent tick would rebuild.
+        let state = empty_state();
+        let mut s = local();
+        let buffer_id = active_buffer(&state);
+        s.set_viewport(buffer_id, ByteRange { start: 0, end: 64 }, 0);
+        let _ = s.render_frame(&state);
+
+        let bumped = {
+            let theme = state.syntax_registry.theme();
+            let mut th = theme.lock().expect("lock");
+            th.face_epoch += 1; // identical re-merge: no table change
+            th.face_epoch
+        };
+        assert_eq!(
+            theme_facts_of(&s.render_frame(&state)),
+            None,
+            "identical rebuild is suppressed"
+        );
+        assert_eq!(
+            s.last_face_epoch,
+            Some(bumped),
+            "the inspected epoch advanced despite the suppressed send"
+        );
+    }
+
+    #[test]
+    fn summary_cache_key_advances_on_suppressed_emission() {
+        // Q#TH6 / acceptance 14: a face mutation that leaves the
+        // summary unchanged (ui.modeline touches no minimap stroke)
+        // recomputes once, emits nothing, and STILL advances the
+        // cache key — otherwise the whole-file pass repeats per tick.
+        let state = empty_state();
+        let mut s = local();
+        let buffer_id = active_buffer(&state);
+        s.set_viewport(buffer_id, ByteRange { start: 0, end: 64 }, 0);
+        let first = s.render_frame(&state);
+        assert!(
+            first
+                .iter()
+                .any(|m| matches!(m, InstanceMessage::FileStyleSummary { .. })),
+            "first frame ships the summary"
+        );
+
+        merge_face(&state, "ui.modeline", Style::default());
+        let (_, _, _, face_epoch) = {
+            let theme = state.syntax_registry.theme();
+            let th = theme.lock().expect("lock");
+            (0, 0, th.syntax_epoch, th.face_epoch)
+        };
+        let next = s.render_frame(&state);
+        assert!(
+            !next
+                .iter()
+                .any(|m| matches!(m, InstanceMessage::FileStyleSummary { .. })),
+            "an unchanged summary is suppressed"
+        );
+        assert_eq!(
+            s.last_summary
+                .get(&buffer_id)
+                .expect("cache entry exists")
+                .key
+                .3,
+            face_epoch,
+            "the cache key advanced despite the suppressed send"
+        );
+    }
+
+    #[test]
+    fn snapshot_reset_drops_one_buffers_baselines_and_keeps_the_rest() {
+        // PR #120 round 2 finding 1 — the reset contract's scope: a
+        // `BufferSnapshot` for buffer A kills A's buffer-scoped
+        // emission baselines (here: summary and status, the two the
+        // A → B → A round trip visibly strands) while OTHER buffers'
+        // baselines and the bufferless ThemeFacts pair survive.
+        let state = empty_state();
+        let mut s = local();
+        let a = active_buffer(&state);
+        let b = {
+            let core = state.core.borrow();
+            let mut reg = core.registry.borrow_mut();
+            reg.create("other")
+        };
+        s.set_viewport(a, ByteRange { start: 0, end: 64 }, 0);
+        let first = s.render_frame(&state);
+        assert!(
+            first
+                .iter()
+                .any(|m| matches!(m, InstanceMessage::FileStyleSummary { .. })),
+            "first frame ships A's summary"
+        );
+        s.set_viewport(b, ByteRange { start: 0, end: 64 }, 0);
+        let _ = s.render_frame(&state);
+        assert!(s.last_summary.contains_key(&a));
+        assert!(s.last_summary.contains_key(&b));
+        assert!(s.last_status.contains_key(&a));
+        let facts_baseline = s.last_theme_faces.clone();
+        assert!(facts_baseline.is_some(), "first frame shipped ThemeFacts");
+
+        s.on_buffer_snapshot_sent(a);
+
+        assert!(
+            !s.last_summary.contains_key(&a) && !s.last_status.contains_key(&a),
+            "A's baselines die with A's snapshot"
+        );
+        assert!(
+            s.last_summary.contains_key(&b),
+            "B's baselines survive A's snapshot"
+        );
+        assert_eq!(
+            s.last_theme_faces, facts_baseline,
+            "ThemeFacts is bufferless — the face table survives snapshots"
+        );
+
+        // And the behavioral consequence: revisiting A at the SAME
+        // generation re-ships the summary the frontend just dropped.
+        s.set_viewport(a, ByteRange { start: 0, end: 64 }, 0);
+        let back = s.render_frame(&state);
+        assert!(
+            back.iter()
+                .any(|m| matches!(m, InstanceMessage::FileStyleSummary { .. })),
+            "the unchanged-generation revisit re-ships A's summary"
+        );
+    }
+
+    #[test]
+    fn style_gate_differs_when_syntax_epoch_bumps() {
+        // Q#TH6: the gate is a pure function of the theme too — a
+        // syntax-epoch bump must force the span recompute (the
+        // pre-existing mid-session staleness bug).
+        let g1 = StyleGate {
+            bundle: None,
+            generation: 1,
+            visible: ByteRange { start: 0, end: 10 },
+            syntax_epoch: 0,
+        };
+        let mut g2 = g1.clone();
+        assert!(g1.matches(&g2), "identical gates match");
+        g2.syntax_epoch = 1;
+        assert!(!g1.matches(&g2), "a theme mutation breaks the match");
+    }
+
     /// All `InstanceMessage` variants the semantic projection may
     /// emit are `StyleSpans`, `Decorations`, `InlineAdornments`,
-    /// `FileStyleSummary`, `StatusFacts` (Q#S1), or `SearchPrompt`
-    /// (Q#SR5) — never `CellDelta`, grid `Cursor`, or the still-unwired
+    /// `FileStyleSummary`, `StatusFacts` (Q#S1), `SearchPrompt`
+    /// (Q#SR5), `LineNumbers`, or `ThemeFacts` (Q#TH7) — never
+    /// `CellDelta`, grid `Cursor`, or the still-unwired
     /// `BlockAdornments` / `FoldState` families.
     fn assert_semantic_only(msgs: &[InstanceMessage]) {
         for m in msgs {
@@ -1894,6 +2392,7 @@ mod tests {
                         | InstanceMessage::StatusFacts { .. }
                         | InstanceMessage::SearchPrompt { .. }
                         | InstanceMessage::LineNumbers { .. }
+                        | InstanceMessage::ThemeFacts { .. }
                 ),
                 "semantic projection emitted an unexpected variant: {m:?}"
             );
@@ -2063,12 +2562,14 @@ mod tests {
         // (the frontend clears its viewport), carrying empty segments.
         // FileStyleSummary also emits on the first frame for this buffer
         // (post-M11 minimap producer, generation-keyed), as does
-        // StatusFacts (Q#S1, cached-compare).
+        // StatusFacts (Q#S1, cached-compare) and the authoritative
+        // ThemeFacts table (Q#TH7 — empty for an unthemed daemon).
         let first = s.render_frame(&state);
         assert_eq!(
             first.len(),
-            4,
-            "first frame ships StyleSpans + Decorations + FileStyleSummary + StatusFacts"
+            5,
+            "first frame ships StyleSpans + Decorations + FileStyleSummary \
+             + StatusFacts + ThemeFacts"
         );
         assert_semantic_only(&first);
         let (style_full, _) = style_segments(&first).expect("StyleSpans present");
diff --git a/tests/theme_faces_acceptance.rs b/tests/theme_faces_acceptance.rs
new file mode 100644
index 0000000..c591839
--- /dev/null
+++ b/tests/theme_faces_acceptance.rs
@@ -0,0 +1,1507 @@
+// theme_faces_acceptance.rs --- Themes Arc 4 stage 1 acceptance
+// (docs/theme-faces-framing.md, acceptance items 1–19, 24–26, 28–29,
+// and 32–33; the GPU routes — 20–23, 27, and 30–31 — live in
+// pmacs-gpu's headless suite; item 34 is a `DiagnosticStore` unit in
+// src/diag.rs).
+
+//! Named UI faces (`ui` / `ui.*` theme entries) + the `ThemeFacts`
+//! wire channel (protocol v16).
+//!
+//! Grid-path rendering drives the full `paint_frame` (mode line,
+//! status row, gutter, minibuffer, selection, search, diagnostics all
+//! paint there); keybinding claims dispatch keys per the standing
+//! discipline; wire claims drive a `SemanticRenderState` frame by
+//! frame, and the version gate exercises a real daemon.
+
+use crossterm::event::{KeyCode, KeyEvent, KeyEventKind, KeyEventState, KeyModifiers};
+use pmacs::cell::{Cell, CellGrid, CellSize, Color, Style, UnderlineStyle};
+use pmacs::editor::EditorState;
+use pmacs::protocol::{ByteRange, FrontendId, InstanceMessage, ThemeFace};
+use pmacs::semantic_render::SemanticRenderState;
+use std::time::{Duration, Instant};
+
+#[cfg(feature = "crdt")]
+mod common;
+
+// ---------------------------------------------------------------------------
+// Harness (compile_mode_acceptance conventions)
+// ---------------------------------------------------------------------------
+
+fn key(code: KeyCode, mods: KeyModifiers) -> KeyEvent {
+    KeyEvent {
+        code,
+        modifiers: mods,
+        kind: KeyEventKind::Press,
+        state: KeyEventState::NONE,
+    }
+}
+
+fn ctrl(s: &mut EditorState, c: char) {
+    s.dispatch_key(
+        FrontendId::LOCAL,
+        key(KeyCode::Char(c), KeyModifiers::CONTROL),
+    );
+}
+
+fn alt(s: &mut EditorState, c: char) {
+    s.dispatch_key(FrontendId::LOCAL, key(KeyCode::Char(c), KeyModifiers::ALT));
+}
+
+fn press(s: &mut EditorState, code: KeyCode) {
+    s.dispatch_key(FrontendId::LOCAL, key(code, KeyModifiers::NONE));
+}
+
+fn type_str(s: &mut EditorState, text: &str) {
+    for ch in text.chars() {
+        s.dispatch_key(
+            FrontendId::LOCAL,
+            key(KeyCode::Char(ch), KeyModifiers::NONE),
+        );
+    }
+}
+
+fn exec(s: &EditorState, src: &str) {
+    s.lua_host.lua().load(src.to_string()).exec().unwrap();
+}
+
+fn exec_err(s: &EditorState, src: &str) -> mlua::Error {
+    s.lua_host
+        .lua()
+        .load(src.to_string())
+        .exec()
+        .expect_err("chunk must error")
+}
+
+fn eval<T: mlua::FromLuaMulti>(s: &EditorState, src: &str) -> T {
+    s.lua_host.lua().load(src.to_string()).eval().unwrap()
+}
+
+/// Fresh editor with LSP spawning disabled.
+fn editor() -> EditorState {
+    let s = EditorState::new();
+    exec(&s, "pmacs.lsp.config = {}");
+    s
+}
+
+/// Paint the FULL frame (windows + mode lines + status row /
+/// minibuffer) — the chrome surfaces under test all render here.
+fn paint_full_frame(state: &EditorState, rows: u32, cols: u32) -> Vec<Cell> {
+    let mut backing = vec![Cell::default(); (rows * cols) as usize];
+    let mut grid = CellGrid {
+        cells: &mut backing,
+        stride: cols,
+        size: CellSize::new(rows, cols),
+    };
+    let _cursor = pmacs::editor::paint_frame(state, &mut grid, CellSize::new(rows, cols));
+    backing
+}
+
+fn at(cells: &[Cell], cols: u32, row: u32, col: u32) -> &Cell {
+    &cells[(row * cols + col) as usize]
+}
+
+fn row_text(cells: &[Cell], cols: u32, row: u32) -> String {
+    (0..cols)
+        .map(|c| match &at(cells, cols, row, c).glyph {
+            pmacs::cell::Glyph::Char(ch) => *ch,
+            _ => ' ',
+        })
+        .collect()
+}
+
+// --- Wire helpers -----------------------------------------------------------
+
+fn active_buffer(state: &EditorState) -> pmacs::buffer::BufferId {
+    state.core.borrow().active_window().buffer_id
+}
+
+fn semantic(state: &EditorState) -> SemanticRenderState {
+    let buffer_id = active_buffer(state);
+    let mut s = SemanticRenderState::new(FrontendId::LOCAL);
+    s.set_viewport(
+        buffer_id,
+        ByteRange {
+            start: 0,
+            end: 1 << 20,
+        },
+        0,
+    );
+    s
+}
+
+fn theme_facts_of(msgs: &[InstanceMessage]) -> Option<Vec<ThemeFace>> {
+    msgs.iter().find_map(|m| match m {
+        InstanceMessage::ThemeFacts { faces } => Some(faces.clone()),
+        _ => None,
+    })
+}
+
+fn has_style_spans(msgs: &[InstanceMessage]) -> bool {
+    msgs.iter()
+        .any(|m| matches!(m, InstanceMessage::StyleSpans { .. }))
+}
+
+fn summary_of(msgs: &[InstanceMessage]) -> Option<Vec<Style>> {
+    msgs.iter().find_map(|m| match m {
+        InstanceMessage::FileStyleSummary { lines, .. } => Some(lines.clone()),
+        _ => None,
+    })
+}
+
+// --- Grammar fixtures (m4_acceptance conventions) ---------------------------
+
+fn pump_async<F: Fn(&EditorState) -> bool>(state: &mut EditorState, predicate: F) {
+    let deadline = Instant::now() + Duration::from_secs(5);
+    while !predicate(state) {
+        assert!(Instant::now() < deadline, "async pump deadline exceeded");
+        state.tick_async();
+        std::thread::sleep(Duration::from_millis(2));
+    }
+}
+
+fn current_tree_language(state: &EditorState) -> Option<String> {
+    let chunk = r"
+        local buf = pmacs.window.buffer()
+        if not buf then return nil end
+        local tree = pmacs.parse.tree(buf)
+        if not tree then return nil end
+        return tree:language()
+    ";
+    state
+        .lua_host
+        .lua()
+        .load(chunk)
+        .eval::<Option<String>>()
+        .ok()
+        .flatten()
+}
+
+/// Open `path` and pump until its parse settles (highlights attached).
+fn open_and_wait_for_parse(path: std::path::PathBuf) -> EditorState {
+    let mut state = EditorState::open(path).expect("open file");
+    exec(&state, "pmacs.lsp.config = {}");
+    pump_async(&mut state, |s| current_tree_language(s).is_some());
+    state
+}
+
+fn rust_fixture(dir: &tempfile::TempDir) -> std::path::PathBuf {
+    let path = dir.path().join("faces.rs");
+    std::fs::write(&path, b"fn main() {}\n").expect("write fixture");
+    path
+}
+
+// --- Diagnostics fixture -----------------------------------------------------
+
+fn diag(severity: pmacs::diag::DiagnosticSeverity) -> pmacs::diag::Diagnostic {
+    pmacs::diag::Diagnostic {
+        start_line: 0,
+        start_col: 0,
+        end_line: 0,
+        end_col: 3,
+        severity,
+        message: "boom".into(),
+        source: None,
+        code: None,
+    }
+}
+
+/// Give the active buffer a file path, publish `diags` for it, and
+/// attach the diagnostic overlay through the REAL Lua path
+/// (`pmacs.diag._attach_view` — `install_diag`), never a bare
+/// constructor (Q#TH9).
+fn attach_diags(state: &EditorState, diags: Vec<pmacs::diag::Diagnostic>) -> String {
+    let uri: String = eval(
+        state,
+        r#"
+        local buf = pmacs.window.buffer()
+        local uri = "file:///tmp/theme_faces_diag.rs"
+        assert(pmacs.diag._attach_view(buf, uri))
+        return uri
+        "#,
+    );
+    {
+        let core = state.core.borrow();
+        let registry = core.registry.clone();
+        let mut reg = registry.borrow_mut();
+        let buf = reg.get_mut(core.active_buffer_id()).unwrap();
+        buf.set_file_path(Some(std::path::PathBuf::from("/tmp/theme_faces_diag.rs")));
+    }
+    let store = state.lsp_manager.borrow().diag_store();
+    store
+        .lock()
+        .expect("diag store lock")
+        .set(uri.clone(), diags);
+    uri
+}
+
+// --- Daemon wire helpers (item 29; CRDT suites only) -------------------------
+
+#[cfg(feature = "crdt")]
+fn wire_viewport(
+    stream: &mut std::os::unix::net::UnixStream,
+    fid: FrontendId,
+    buffer_id: pmacs::buffer::BufferId,
+) {
+    pmacs::transport::write_message(
+        stream,
+        &pmacs::protocol::FrontendEvent::Viewport {
+            frontend_id: fid,
+            buffer_id,
+            visible: ByteRange {
+                start: 0,
+                end: 4096,
+            },
+            generation: 0,
+        },
+    )
+    .expect("write Viewport");
+}
+
+#[cfg(feature = "crdt")]
+fn wire_key(
+    stream: &mut std::os::unix::net::UnixStream,
+    fid: FrontendId,
+    key: pmacs::protocol::Key,
+) {
+    pmacs::transport::write_message(
+        stream,
+        &pmacs::protocol::FrontendEvent::Key(pmacs::protocol::KeyEvent {
+            frontend_id: fid,
+            key,
+            mods: pmacs::protocol::Modifiers::NONE,
+            timestamp_ns: 0,
+        }),
+    )
+    .expect("write Key");
+}
+
+/// Read wire messages until `pick` returns, or panic at the deadline.
+#[cfg(feature = "crdt")]
+fn wire_wait_for<T>(
+    stream: &mut std::os::unix::net::UnixStream,
+    what: &str,
+    mut pick: impl FnMut(InstanceMessage) -> Option<T>,
+) -> T {
+    let deadline = Instant::now() + Duration::from_secs(5);
+    while Instant::now() < deadline {
+        if let Ok(msg) = pmacs::transport::read_message::<InstanceMessage>(stream)
+            && let Some(t) = pick(msg)
+        {
+            return t;
+        }
+    }
+    panic!("timeout waiting for {what}");
+}
+
+// ---------------------------------------------------------------------------
+// 1 — unset faces: byte-identical chrome; default_style never leaks
+// ---------------------------------------------------------------------------
+
+#[test]
+fn unset_faces_keep_todays_chrome_and_syntax_default_never_leaks() {
+    let mut state = editor();
+    type_str(&mut state, "hello");
+    let (rows, cols) = (8u32, 20u32);
+    let base = paint_full_frame(&state, rows, cols);
+
+    // Today's literals, spot-pinned: mode line (window's last row) and
+    // status row are reverse video with no colors.
+    let mode_row = rows - 2;
+    let status_row = rows - 1;
+    for col in 0..cols {
+        let m = at(&base, cols, mode_row, col);
+        assert!(m.style.reverse, "mode line is reverse video when unthemed");
+        assert_eq!(m.style.fg, Color::Default);
+        let s = at(&base, cols, status_row, col);
+        assert!(s.style.reverse, "status row is reverse video when unthemed");
+    }
+
+    // A loud SYNTAX default must not bleed into chrome (Q#TH4:
+    // face resolution returns None, never default_style).
+    exec(
+        &state,
+        "pmacs.theme.default { fg = 5, bg = 3, bold = true }",
+    );
+    let loud = paint_full_frame(&state, rows, cols);
+    assert_eq!(base, loud, "pmacs.theme.default must change no chrome cell");
+}
+
+// ---------------------------------------------------------------------------
+// 2 + 3 — surface faces apply per cell; owns-surface resets to plain
+// ---------------------------------------------------------------------------
+
+#[test]
+fn surface_faces_apply_and_partial_faces_reset_to_plain() {
+    let mut state = editor();
+    type_str(&mut state, "one\ntwo\nthree");
+    let (rows, cols) = (8u32, 20u32);
+    let mode_row = rows - 2;
+    let status_row = rows - 1;
+
+    // Full modeline face: fg + bg, no reverse.
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.modeline"] = { fg = 252, bg = 236 },
+                              ["ui.statusline"] = { fg = 4 } }"#,
+    );
+    let themed = paint_full_frame(&state, rows, cols);
+    for col in 0..cols {
+        let m = at(&themed, cols, mode_row, col);
+        assert_eq!(m.style.fg, Color::Indexed(252), "modeline fg at {col}");
+        assert_eq!(m.style.bg, Color::Indexed(236), "modeline bg at {col}");
+        assert!(!m.style.reverse, "a set face owns the surface: no reverse");
+        let s = at(&themed, cols, status_row, col);
+        assert_eq!(s.style.fg, Color::Indexed(4), "statusline fg at {col}");
+        assert!(!s.style.reverse, "statusline surface resets to plain");
+    }
+
+    // Owns-surface (Q#TH5): an fg-only modeline face still drops the
+    // reverse video — partial faces reset the rest to plain.
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.modeline"] = { fg = 252 } }"#,
+    );
+    let partial = paint_full_frame(&state, rows, cols);
+    let m = at(&partial, cols, mode_row, 0);
+    assert_eq!(m.style.fg, Color::Indexed(252));
+    assert_eq!(m.style.bg, Color::Default, "unset bg is plain");
+    assert!(!m.style.reverse, "partial face resets reverse to plain");
+
+    // Gutter face ({fg} mask) on the line-number strip.
+    exec(&state, r#"pmacs.window.set_line_numbers("absolute")"#);
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.gutter"] = { fg = 13 } }"#,
+    );
+    let with_gutter = paint_full_frame(&state, rows, cols);
+    let g = at(&with_gutter, cols, 0, 0);
+    assert_eq!(g.style.fg, Color::Indexed(13), "gutter digits recolor");
+}
+
+// ---------------------------------------------------------------------------
+// 3 (rest) — ui.selection = {} disables the wash on the grid
+// ---------------------------------------------------------------------------
+
+#[test]
+fn empty_selection_face_disables_the_wash() {
+    let mut state = editor();
+    type_str(&mut state, "alpha beta");
+    let (rows, cols) = (6u32, 20u32);
+
+    let set_selection = |state: &EditorState| {
+        let mut core = state.core.borrow_mut();
+        let win = core.active_window_mut();
+        win.selection = Some(pmacs::window::Selection { anchor: 0 });
+        win.cursor = 5;
+    };
+    let clear_selection = |state: &EditorState| {
+        state.core.borrow_mut().active_window_mut().selection = None;
+    };
+
+    // Unset face: reverse-video wash, exactly today.
+    set_selection(&state);
+    let washed = paint_full_frame(&state, rows, cols);
+    assert!(
+        at(&washed, cols, 0, 0).style.reverse,
+        "unthemed selection is reverse video"
+    );
+
+    // Empty face: the wash disappears — selected cells render exactly
+    // like unselected ones (Q#TH5, all-default overlay).
+    exec(&state, r#"pmacs.theme.merge { ["ui.selection"] = {} }"#);
+    let disabled = paint_full_frame(&state, rows, cols);
+    clear_selection(&state);
+    let unselected = paint_full_frame(&state, rows, cols);
+    assert_eq!(
+        disabled, unselected,
+        "an all-default selection face must disable the wash"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 4 — mask enforcement: out-of-mask components are ignored
+// ---------------------------------------------------------------------------
+
+#[test]
+fn out_of_mask_components_are_ignored_on_the_grid() {
+    let mut state = editor();
+    type_str(&mut state, "alpha beta");
+    let (rows, cols) = (8u32, 20u32);
+    {
+        let mut core = state.core.borrow_mut();
+        let win = core.active_window_mut();
+        win.selection = Some(pmacs::window::Selection { anchor: 0 });
+        win.cursor = 5;
+    }
+
+    // ui.selection mask is {bg}: fg + reverse must be ignored.
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.selection"] = { bg = 17 } }"#,
+    );
+    let bg_only = paint_full_frame(&state, rows, cols);
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.selection"] = { fg = 1, reverse = true, bg = 17 } }"#,
+    );
+    let with_extras = paint_full_frame(&state, rows, cols);
+    assert_eq!(
+        bg_only, with_extras,
+        "fg/reverse on a wash face must render exactly as the bg-only face"
+    );
+    assert_eq!(
+        at(&bg_only, cols, 0, 0).style.bg,
+        Color::Indexed(17),
+        "the in-mask bg applies"
+    );
+    assert_eq!(
+        at(&bg_only, cols, 0, 0).style.fg,
+        Color::Default,
+        "the out-of-mask fg does not"
+    );
+
+    // ui.gutter mask is {fg}: bg + reverse must be ignored.
+    exec(&state, r#"pmacs.window.set_line_numbers("absolute")"#);
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.gutter"] = { fg = 9 } }"#,
+    );
+    let fg_only = paint_full_frame(&state, rows, cols);
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.gutter"] = { fg = 9, bg = 1, reverse = true } }"#,
+    );
+    let gutter_extras = paint_full_frame(&state, rows, cols);
+    assert_eq!(
+        fg_only, gutter_extras,
+        "bg/reverse on a foreground-only site must render as the fg-only face"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 5 — wash faces merge over syntax-styled cells; the real search path
+// ---------------------------------------------------------------------------
+
+#[test]
+fn search_wash_faces_merge_over_syntax_and_split_active_from_lazy() {
+    let dir = tempfile::tempdir().expect("tempdir");
+    // Two `fn` occurrences so a lazy and an active match coexist.
+    let path = dir.path().join("faces.rs");
+    std::fs::write(&path, b"fn main() { fn_helper(); }\n").expect("write");
+    let mut state = open_and_wait_for_parse(path);
+    let (rows, cols) = (8u32, 40u32);
+
+    exec(
+        &state,
+        r#"pmacs.theme.merge {
+            ["ui.search.match"] = { bg = 17 },
+            ["ui.search.match.active"] = { bg = 22 },
+        }"#,
+    );
+    // The syntax-styled frame BEFORE any search: the per-cell fg
+    // baseline the wash must preserve (`fn` at 0 is a keyword; the
+    // `fn` inside `fn_helper` is function-colored — the wash must
+    // keep each as-is, whatever the grammar decided).
+    let before = paint_full_frame(&state, rows, cols);
+
+    // The REAL path: dispatched C-s reaching ensure_search_overlay.
+    ctrl(&mut state, 's');
+    type_str(&mut state, "fn");
+    let cells = paint_full_frame(&state, rows, cols);
+
+    // Both `fn` occurrences: cols 0..2 and 12..14 on row 0.
+    let first = at(&cells, cols, 0, 0);
+    let second = at(&cells, cols, 0, 12);
+    let bgs = [first.style.bg, second.style.bg];
+    assert!(
+        bgs.contains(&Color::Indexed(22)),
+        "one match is active (got {bgs:?})"
+    );
+    assert!(
+        bgs.contains(&Color::Indexed(17)),
+        "one match is lazy (got {bgs:?})"
+    );
+    // Merge semantics: each cell's syntax fg survives under the
+    // bg-only wash (per-cell fg assertion, not any-styled-cell).
+    for col in [0u32, 1, 12, 13] {
+        assert_eq!(
+            at(&cells, cols, 0, col).style.fg,
+            at(&before, cols, 0, col).style.fg,
+            "a bg-only wash keeps the syntax fg underneath (col {col})"
+        );
+        assert_ne!(
+            at(&before, cols, 0, col).style.bg,
+            at(&cells, cols, 0, col).style.bg,
+            "the wash bg landed (col {col})"
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// 6 + 7 — diag faces on every grid surface + inheritance + empty child
+// ---------------------------------------------------------------------------
+
+#[test]
+fn diag_faces_recolor_squiggle_and_marker_with_inheritance_and_empty_child_reset() {
+    use pmacs::diag::DiagnosticSeverity;
+
+    let mut state = editor();
+    type_str(&mut state, "boom\nfine\n");
+    attach_diags(
+        &state,
+        vec![
+            diag(DiagnosticSeverity::Error),
+            pmacs::diag::Diagnostic {
+                start_line: 1,
+                start_col: 0,
+                end_line: 1,
+                end_col: 3,
+                severity: DiagnosticSeverity::Warning,
+                message: "warn".into(),
+                source: None,
+                code: None,
+            },
+        ],
+    );
+    let (rows, cols) = (8u32, 20u32);
+
+    // Unset: built-in severity colors (error Indexed(1) squiggle,
+    // warning Indexed(3)).
+    let base = paint_full_frame(&state, rows, cols);
+    assert_eq!(at(&base, cols, 0, 0).style.underline, UnderlineStyle::Curly);
+    assert_eq!(
+        at(&base, cols, 0, 0).style.underline_color,
+        Color::Indexed(1)
+    );
+    assert_eq!(
+        at(&base, cols, 1, 0).style.underline_color,
+        Color::Indexed(3)
+    );
+
+    // Inheritance: a themed ui.diag parent colors all severities.
+    exec(&state, r#"pmacs.theme.merge { ["ui.diag"] = { fg = 93 } }"#);
+    let inherited = paint_full_frame(&state, rows, cols);
+    assert_eq!(
+        at(&inherited, cols, 0, 0).style.underline_color,
+        Color::Indexed(93),
+        "error inherits ui.diag"
+    );
+    assert_eq!(
+        at(&inherited, cols, 1, 0).style.underline_color,
+        Color::Indexed(93),
+        "warning inherits ui.diag"
+    );
+
+    // An exact EMPTY child blocks inheritance and resets errors to
+    // the built-in color; warnings keep the parent's (Q#TH5, round 3
+    // finding 4).
+    exec(&state, r#"pmacs.theme.merge { ["ui.diag.error"] = {} }"#);
+    let reset = paint_full_frame(&state, rows, cols);
+    assert_eq!(
+        at(&reset, cols, 0, 0).style.underline_color,
+        Color::Indexed(1),
+        "empty child resets errors to the built-in"
+    );
+    assert_eq!(
+        at(&reset, cols, 1, 0).style.underline_color,
+        Color::Indexed(93),
+        "warnings still inherit"
+    );
+
+    // An explicit colored child wins over the parent.
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.diag.error"] = { fg = 45 } }"#,
+    );
+    let explicit = paint_full_frame(&state, rows, cols);
+    assert_eq!(
+        at(&explicit, cols, 0, 0).style.underline_color,
+        Color::Indexed(45)
+    );
+}
+
+#[test]
+fn diag_face_recolors_the_minimap_marks_and_reships_the_summary() {
+    use pmacs::diag::DiagnosticSeverity;
+
+    let mut state = editor();
+    type_str(&mut state, "boom\nfine\n");
+    attach_diags(&state, vec![diag(DiagnosticSeverity::Error)]);
+
+    let mut sem = semantic(&state);
+    let first = sem.render_frame(&state);
+    let lines = summary_of(&first).expect("first frame ships the summary");
+    assert_eq!(
+        lines[0].underline_color,
+        Color::Indexed(1),
+        "unthemed mark carries the built-in error color"
+    );
+
+    // A diag-face change with NO buffer edit re-ships the summary
+    // with the resolved color (the minimap twin of the staleness
+    // bite).
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.diag.error"] = { fg = 45 } }"#,
+    );
+    let next = sem.render_frame(&state);
+    let lines = summary_of(&next).expect("diag-face change re-ships the summary");
+    assert_eq!(
+        lines[0].underline_color,
+        Color::Indexed(45),
+        "the mark recolors through ui.diag.error"
+    );
+    // The mark is PRESENT (never Default — the diag Default policy
+    // keeps presence representable).
+    assert_ne!(lines[0].underline_color, Color::Default);
+}
+
+// ---------------------------------------------------------------------------
+// 8 — bare ui is a face key
+// ---------------------------------------------------------------------------
+
+#[test]
+fn bare_ui_merge_ships_the_catch_all_without_touching_spans() {
+    let dir = tempfile::tempdir().expect("tempdir");
+    let state = open_and_wait_for_parse(rust_fixture(&dir));
+    let mut sem = semantic(&state);
+    let first = sem.render_frame(&state);
+    assert!(has_style_spans(&first), "grammar buffer ships spans");
+    assert_eq!(theme_facts_of(&first), Some(Vec::new()));
+
+    exec(&state, r"pmacs.theme.merge { ui = { fg = 3 } }");
+    let next = sem.render_frame(&state);
+    let facts = theme_facts_of(&next).expect("bare ui bumps face_epoch and emits");
+    assert_eq!(facts.len(), 12, "the catch-all resolves every stage-1 face");
+    assert!(
+        facts
+            .iter()
+            .all(|f| f.style.fg == Color::Indexed(3) && f.name.starts_with("ui")),
+        "each face resolved through the catch-all"
+    );
+    assert!(
+        !has_style_spans(&next),
+        "a face key must classify as face, not syntax — no span re-emission"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 9 + 10 — the staleness bite + consecutive-set monotonicity
+// ---------------------------------------------------------------------------
+
+#[test]
+fn mid_session_recolor_reships_spans_without_an_edit() {
+    let dir = tempfile::tempdir().expect("tempdir");
+    let state = open_and_wait_for_parse(rust_fixture(&dir));
+    let mut sem = semantic(&state);
+    assert!(has_style_spans(&sem.render_frame(&state)));
+    assert!(
+        !has_style_spans(&sem.render_frame(&state)),
+        "an unchanged tick is span-silent (the gate holds)"
+    );
+
+    // Zero buffer edits; a capture recolor alone must re-ship. This
+    // is the pre-existing GPU staleness bug's bite: pre-arc, the
+    // StyleGate ignored the theme and this frame shipped nothing.
+    exec(&state, r"pmacs.theme.set { keyword = { fg = 99 } }");
+    assert!(
+        has_style_spans(&sem.render_frame(&state)),
+        "a mid-session pmacs.theme.set must re-ship StyleSpans"
+    );
+}
+
+#[test]
+fn consecutive_sets_each_reship_and_coalesce_within_one_frame() {
+    let dir = tempfile::tempdir().expect("tempdir");
+    let state = open_and_wait_for_parse(rust_fixture(&dir));
+    let mut sem = semantic(&state);
+    let _ = sem.render_frame(&state);
+
+    // set → observe → set → observe (round 2 finding 4's shape): each
+    // mutation is observed by a render. Fails if wholesale
+    // replacement resets the counters (the second set would share the
+    // first's epoch and ship nothing).
+    exec(&state, r"pmacs.theme.set { keyword = { fg = 99 } }");
+    assert!(
+        has_style_spans(&sem.render_frame(&state)),
+        "first set re-ships"
+    );
+    exec(&state, r"pmacs.theme.set { keyword = { fg = 111 } }");
+    assert!(
+        has_style_spans(&sem.render_frame(&state)),
+        "second set re-ships"
+    );
+
+    // Companion: two mutations inside one frame legitimately coalesce
+    // into one emission carrying the SECOND set's color.
+    exec(&state, r"pmacs.theme.set { keyword = { fg = 120 } }");
+    exec(&state, r"pmacs.theme.set { keyword = { fg = 130 } }");
+    let frame = sem.render_frame(&state);
+    let span_styles: Vec<Style> = frame
+        .iter()
+        .find_map(|m| match m {
+            InstanceMessage::StyleSpans { segments, .. } => Some(
+                segments
+                    .iter()
+                    .flat_map(|s| s.spans.iter().map(|sp| sp.style))
+                    .collect(),
+            ),
+            _ => None,
+        })
+        .expect("coalesced frame ships once");
+    assert!(
+        span_styles.iter().any(|s| s.fg == Color::Indexed(130)),
+        "the coalesced emission reflects the final set"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 11 — malformed merge is atomic (Lua contract; the deterministic
+// bite is the commit-boundary unit in lua_bindings)
+// ---------------------------------------------------------------------------
+
+#[test]
+fn malformed_merge_is_atomic_from_lua() {
+    let dir = tempfile::tempdir().expect("tempdir");
+    let state = open_and_wait_for_parse(rust_fixture(&dir));
+    let mut sem = semantic(&state);
+    let _ = sem.render_frame(&state);
+
+    exec(&state, r"pmacs.theme.merge { keyword = { fg = 42 } }");
+    let _ = sem.render_frame(&state);
+
+    // One merge carrying a valid entry AND a malformed one (a string
+    // is not a style table). Lua table iteration order is unspecified
+    // (round 2 finding 8), so this pins only the order-independent
+    // user contract: error, nothing landed, nothing emitted.
+    let err = exec_err(
+        &state,
+        r#"pmacs.theme.merge { string = { fg = 7 }, ["ui.modeline"] = "nope" }"#,
+    );
+    let msg = format!("{err}");
+    assert!(!msg.is_empty());
+
+    let fg: i64 = eval(&state, r#"return pmacs.theme.get("keyword").fg"#);
+    assert_eq!(fg, 42, "prior entries survive");
+    let string_fg: i64 = eval(&state, r#"return pmacs.theme.get("string").fg"#);
+    assert_ne!(
+        string_fg, 7,
+        "the valid entry of the failed merge is absent"
+    );
+
+    let frame = sem.render_frame(&state);
+    assert!(
+        !has_style_spans(&frame) && theme_facts_of(&frame).is_none(),
+        "a failed merge bumps nothing and emits nothing"
+    );
+}
+
+#[test]
+fn raising_index_metamethods_fail_the_merge_transactionally() {
+    // PR #120 round 1 finding 2: `Table::get` runs __index, so a
+    // raising metatable must error the whole merge. Pre-fix, the
+    // trapped lookup silently parsed as an all-default style and the
+    // merge SUCCEEDED, committing the valid sibling — against the
+    // Q#TH6 all-or-nothing contract.
+    let mut state = editor();
+    type_str(&mut state, "hello");
+    let mut sem = semantic(&state);
+    let _ = sem.render_frame(&state);
+
+    let err = exec_err(
+        &state,
+        r#"
+        local trap = setmetatable({}, { __index = function() error("trapdoor") end })
+        pmacs.theme.merge { ["ui.gutter"] = trap, zebra = { fg = 42 } }
+        "#,
+    );
+    assert!(
+        format!("{err}").contains("trapdoor"),
+        "the metatable's own error surfaces: {err}"
+    );
+    // `zebra` is not in default_dark, so its presence would prove the
+    // valid sibling leaked through the failed merge.
+    let (zebra, gutter): (bool, bool) = eval(
+        &state,
+        r#"
+        local t = pmacs.theme.current()
+        return t["zebra"] ~= nil, t["ui.gutter"] ~= nil
+        "#,
+    );
+    assert!(
+        !zebra && !gutter,
+        "nothing from the failed merge landed (zebra={zebra}, gutter={gutter})"
+    );
+    let frame = sem.render_frame(&state);
+    assert!(
+        theme_facts_of(&frame).is_none() && !has_style_spans(&frame),
+        "a failed merge bumps nothing and emits nothing"
+    );
+    // (Boolean fields deliberately follow Lua truthiness — mlua's
+    // bool conversion — so `reverse = "yes"` is Some(true), not an
+    // error; the transactional contract is about lookups that RAISE.)
+}
+
+#[test]
+fn v15_peers_get_no_face_derived_summary_marks() {
+    // PR #120 round 1 finding 3: ui.diag.* colors reach the minimap
+    // through FileStyleSummary — an ungated pre-v16 channel. A v15
+    // semantic peer must keep built-in marks (its squiggles, signs,
+    // and counters are unthemed too); a v16 peer gets the face.
+    use pmacs::diag::DiagnosticSeverity;
+
+    let mut state = editor();
+    type_str(&mut state, "boom\nfine\n");
+    attach_diags(&state, vec![diag(DiagnosticSeverity::Error)]);
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.diag.error"] = { fg = 45 } }"#,
+    );
+    let buffer_id = active_buffer(&state);
+    let viewport = ByteRange {
+        start: 0,
+        end: 1 << 20,
+    };
+
+    let mut v15 = SemanticRenderState::for_peer(FrontendId::LOCAL, 15);
+    v15.set_viewport(buffer_id, viewport, 0);
+    let frame = v15.render_frame(&state);
+    let lines = summary_of(&frame).expect("v15 still receives the summary");
+    assert_eq!(
+        lines[0].underline_color,
+        Color::Indexed(1),
+        "a v15 peer's marks keep the built-in severity color"
+    );
+    assert!(
+        theme_facts_of(&frame).is_none(),
+        "and no ThemeFacts is produced for it at all"
+    );
+
+    let mut v16 = SemanticRenderState::for_peer(FrontendId::LOCAL, 16);
+    v16.set_viewport(buffer_id, viewport, 0);
+    let frame = v16.render_frame(&state);
+    assert_eq!(
+        summary_of(&frame).expect("summary ships")[0].underline_color,
+        Color::Indexed(45),
+        "a v16 peer's marks resolve the face"
+    );
+    assert!(theme_facts_of(&frame).is_some());
+}
+
+// ---------------------------------------------------------------------------
+// 28 + 29 — snapshot/baseline reset: the A → B → A round trip
+// (PR #120 round 2 finding 1)
+// ---------------------------------------------------------------------------
+
+#[test]
+fn snapshot_round_trip_restores_the_themed_summary_at_one_generation() {
+    // A `BufferSnapshot` wipes the frontend's buffer-scoped render
+    // state, so the producer's emission baselines must die with the
+    // send (`on_buffer_snapshot_sent`). Pre-fix, revisiting A at an
+    // unchanged generation matched `last_summary[A]` and the
+    // frontend never regained the themed minimap — or A's
+    // StatusFacts — until an edit, republish, or theme mutation
+    // happened to move the key.
+    use pmacs::diag::DiagnosticSeverity;
+
+    let mut state = editor();
+    type_str(&mut state, "boom\nfine\n");
+    attach_diags(&state, vec![diag(DiagnosticSeverity::Error)]);
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.diag.error"] = { fg = 45 } }"#,
+    );
+    exec(&state, "_G.__A = pmacs.window.buffer()");
+
+    let summary_msg = |msgs: &[InstanceMessage]| {
+        msgs.iter().find_map(|m| match m {
+            InstanceMessage::FileStyleSummary {
+                generation, lines, ..
+            } => Some((*generation, lines.clone())),
+            _ => None,
+        })
+    };
+    let has_status = |msgs: &[InstanceMessage]| {
+        msgs.iter()
+            .any(|m| matches!(m, InstanceMessage::StatusFacts { .. }))
+    };
+    let viewport = ByteRange {
+        start: 0,
+        end: 1 << 20,
+    };
+
+    let a = active_buffer(&state);
+    let mut sem = semantic(&state);
+    let first = sem.render_frame(&state);
+    let (gen_a, themed) = summary_msg(&first).expect("first frame ships the summary");
+    assert_eq!(
+        themed[0].underline_color,
+        Color::Indexed(45),
+        "the mark is themed"
+    );
+    assert!(has_status(&first), "first frame ships StatusFacts");
+    let quiet = sem.render_frame(&state);
+    assert!(
+        summary_msg(&quiet).is_none() && !has_status(&quiet),
+        "an unchanged tick is suppressed"
+    );
+
+    // The daemon switches this session to B: it writes snapshot(B)
+    // (resetting B's baselines) and the frontend re-declares.
+    exec(
+        &state,
+        "local id = pmacs.instance.show(); pmacs.window.switch_buffer(id)",
+    );
+    let b = active_buffer(&state);
+    assert_ne!(a, b, "the instance buffer is a distinct buffer");
+    sem.on_buffer_snapshot_sent(b);
+    sem.set_viewport(b, viewport, 0);
+    let _ = sem.render_frame(&state);
+
+    // ... and back to A. Zero edits: same CRDT generation.
+    exec(&state, "pmacs.window.switch_buffer(_G.__A)");
+    assert_eq!(active_buffer(&state), a);
+    sem.on_buffer_snapshot_sent(a);
+    sem.set_viewport(a, viewport, 0);
+    let back = sem.render_frame(&state);
+    let (gen_back, lines_back) = summary_msg(&back).expect("the revisit re-ships the summary");
+    assert_eq!(
+        gen_back, gen_a,
+        "at the SAME generation — no edit forced it"
+    );
+    assert_eq!(lines_back, themed, "the identical themed payload returns");
+    assert!(has_status(&back), "StatusFacts returns with it");
+}
+
+#[cfg(feature = "crdt")]
+#[test]
+fn daemon_reships_the_summary_after_a_real_buffer_round_trip() {
+    // Item 29 — the daemon wiring for finding 1: a REAL daemon whose
+    // session navigates A → B → A (via dispatched keys, so the
+    // active-buffer-follow path writes the snapshots) must re-ship
+    // `FileStyleSummary` for A at its unchanged generation. Pre-fix,
+    // the producer baselines survived the snapshot and the revisit
+    // was summary-silent forever.
+    use common::daemon::{TestDaemon, build_default_caps};
+    use pmacs::protocol::{AttachRequest, FrontendCapabilities, Hello, Key};
+    use pmacs::transport::{read_message, write_message};
+
+    let daemon = TestDaemon::spawn_with_config(
+        r#"
+        pmacs.command.define {
+          name = "test.go-instance",
+          description = "themes round 2: switch to the instance buffer",
+          fn = function()
+            _G.__orig = pmacs.window.buffer()
+            local id = pmacs.instance.show()
+            pmacs.window.switch_buffer(id)
+          end,
+        }
+        pmacs.command.define {
+          name = "test.go-back",
+          description = "themes round 2: switch back to the original buffer",
+          fn = function() pmacs.window.switch_buffer(_G.__orig) end,
+        }
+        pmacs.keymap.bind { scope = "global", sequence = "<f6>", command = "test.go-instance" }
+        pmacs.keymap.bind { scope = "global", sequence = "<f7>", command = "test.go-back" }
+        "#,
+    );
+
+    let mut stream = daemon.connect();
+    stream
+        .set_read_timeout(Some(Duration::from_millis(250)))
+        .unwrap();
+    let hello: Hello = read_message(&mut stream).expect("read Hello");
+    let fid = hello.assigned_frontend_id;
+    write_message(
+        &mut stream,
+        &AttachRequest {
+            protocol_version: 16,
+            frontend_capabilities: FrontendCapabilities {
+                multi_frontend: true,
+                crdt_replica: true,
+                semantic_render: true,
+                ..build_default_caps()
+            },
+            initial_size: CellSize::new(24, 80),
+        },
+    )
+    .expect("write AttachRequest");
+
+    // Learn buffer A from the bootstrap snapshot, declare, and note
+    // the first summary's generation.
+    let a = wire_wait_for(&mut stream, "bootstrap BufferSnapshot", |m| match m {
+        InstanceMessage::BufferSnapshot { buffer_id, .. } => Some(buffer_id),
+        _ => None,
+    });
+    wire_viewport(&mut stream, fid, a);
+    let gen_a = wire_wait_for(&mut stream, "first FileStyleSummary(A)", |m| match m {
+        InstanceMessage::FileStyleSummary {
+            buffer_id,
+            generation,
+            ..
+        } if buffer_id == a => Some(generation),
+        _ => None,
+    });
+
+    // A → B: the follow path writes snapshot(B); re-declare for B.
+    wire_key(&mut stream, fid, Key::F(6));
+    let b = wire_wait_for(&mut stream, "BufferSnapshot(B)", |m| match m {
+        InstanceMessage::BufferSnapshot { buffer_id, .. } if buffer_id != a => Some(buffer_id),
+        _ => None,
+    });
+    wire_viewport(&mut stream, fid, b);
+
+    // B → A: the follow path writes snapshot(A) — the reset under
+    // test — and the revisit must re-ship A's summary, unchanged
+    // generation included.
+    wire_key(&mut stream, fid, Key::F(7));
+    wire_wait_for(&mut stream, "BufferSnapshot(A) on revisit", |m| match m {
+        InstanceMessage::BufferSnapshot { buffer_id, .. } if buffer_id == a => Some(()),
+        _ => None,
+    });
+    wire_viewport(&mut stream, fid, a);
+    let gen_back = wire_wait_for(&mut stream, "re-shipped FileStyleSummary(A)", |m| match m {
+        InstanceMessage::FileStyleSummary {
+            buffer_id,
+            generation,
+            ..
+        } if buffer_id == a => Some(generation),
+        _ => None,
+    });
+    assert_eq!(
+        gen_back, gen_a,
+        "the revisit summary arrives at A's unchanged generation"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 32 — the snapshot reset must not break the diagnostic-count freeze
+// (PR #120 round 3 finding 2)
+// ---------------------------------------------------------------------------
+
+#[test]
+fn snapshot_reset_keeps_frozen_diag_counts_while_the_store_is_stale() {
+    // `last_status` was both the peer emission baseline AND the
+    // stale-store freeze source, so the round-2 reset zeroed the
+    // counts: a buffer switch between didChange and fresh
+    // diagnostics re-shipped StatusFacts with (0, 0). The freeze is
+    // now the diag store's own retained vector (round 4 superseded
+    // round 3's per-session cache), so the reset has nothing
+    // count-related to lose.
+    use pmacs::diag::DiagnosticSeverity;
+
+    let mut state = editor();
+    type_str(&mut state, "boom\nfine\n");
+    let uri = attach_diags(
+        &state,
+        vec![
+            diag(DiagnosticSeverity::Error),
+            diag(DiagnosticSeverity::Warning),
+        ],
+    );
+
+    let status_counts = |msgs: &[InstanceMessage]| {
+        msgs.iter().find_map(|m| match m {
+            InstanceMessage::StatusFacts {
+                diag_errors,
+                diag_warnings,
+                ..
+            } => Some((*diag_errors, *diag_warnings)),
+            _ => None,
+        })
+    };
+
+    let a = active_buffer(&state);
+    let mut sem = semantic(&state);
+    assert_eq!(
+        status_counts(&sem.render_frame(&state)),
+        Some((1, 1)),
+        "fresh counts ship on the first frame"
+    );
+
+    // didChange: the store goes stale — counts freeze, never zero.
+    {
+        let store = state.lsp_manager.borrow().diag_store();
+        store
+            .lock()
+            .expect("diag store lock")
+            .mark_stale(uri.clone());
+    }
+
+    // The daemon writes snapshot(A) mid-staleness (a revisit, or the
+    // F29 upgrade broadcast). The reset kills the emission baseline —
+    // forcing the re-send — but must not discard the freeze source.
+    sem.on_buffer_snapshot_sent(a);
+    sem.set_viewport(
+        a,
+        ByteRange {
+            start: 0,
+            end: 1 << 20,
+        },
+        0,
+    );
+    assert_eq!(
+        status_counts(&sem.render_frame(&state)),
+        Some((1, 1)),
+        "the re-sent StatusFacts preserves the frozen counts"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 33 — the freeze holds without session history (PR #120 round 4)
+// ---------------------------------------------------------------------------
+
+#[test]
+fn a_session_first_rendering_during_staleness_reports_preserved_counts() {
+    // `mark_stale` keeps the last published diagnostic vector — only
+    // the positions are invalid — so the freeze must hold for a
+    // session with NO per-session history. Pre-fix, the producer
+    // skipped the retained entries while stale and a late joiner (or
+    // a buffer first visited mid-edit) fell back to (0, 0), against
+    // the documented "frozen counts, never zeros" contract.
+    use pmacs::diag::DiagnosticSeverity;
+
+    let mut state = editor();
+    type_str(&mut state, "boom\nfine\n");
+    let uri = attach_diags(
+        &state,
+        vec![
+            diag(DiagnosticSeverity::Error),
+            diag(DiagnosticSeverity::Warning),
+        ],
+    );
+
+    // didChange BEFORE any session exists for this buffer.
+    {
+        let store = state.lsp_manager.borrow().diag_store();
+        store
+            .lock()
+            .expect("diag store lock")
+            .mark_stale(uri.clone());
+    }
+
+    let mut sem = semantic(&state);
+    let first = sem.render_frame(&state);
+    let counts = first.iter().find_map(|m| match m {
+        InstanceMessage::StatusFacts {
+            diag_errors,
+            diag_warnings,
+            ..
+        } => Some((*diag_errors, *diag_warnings)),
+        _ => None,
+    });
+    assert_eq!(
+        counts,
+        Some((1, 1)),
+        "a late joiner's first frame reports the store's preserved counts"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 12 + 16 + 19 — ThemeFacts emission discipline; late join; set wipes
+// ---------------------------------------------------------------------------
+
+#[test]
+fn theme_facts_emission_discipline_and_set_wipes_faces() {
+    let mut state = editor();
+    type_str(&mut state, "hello");
+    let mut sem = semantic(&state);
+
+    // Exactly one authoritative EMPTY table for an unthemed session.
+    assert_eq!(theme_facts_of(&sem.render_frame(&state)), Some(Vec::new()));
+    assert_eq!(theme_facts_of(&sem.render_frame(&state)), None);
+
+    // A face merge ships the resolved sorted table exactly once.
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.gutter"] = { fg = 13 }, ["ui.modeline"] = { bg = 236 } }"#,
+    );
+    let facts = theme_facts_of(&sem.render_frame(&state)).expect("face merge emits");
+    let names: Vec<&str> = facts.iter().map(|f| f.name.as_str()).collect();
+    assert_eq!(names, ["ui.gutter", "ui.modeline"], "sorted, concrete");
+    assert_eq!(theme_facts_of(&sem.render_frame(&state)), None);
+
+    // An identical re-merge emits nothing.
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.gutter"] = { fg = 13 } }"#,
+    );
+    assert_eq!(
+        theme_facts_of(&sem.render_frame(&state)),
+        None,
+        "identical re-merge is suppressed"
+    );
+
+    // Q#TH10: a captures-only wholesale set wipes the faces — the
+    // wire ships the empty table and the chrome returns to defaults.
+    exec(&state, r"pmacs.theme.set { keyword = { fg = 1 } }");
+    assert_eq!(
+        theme_facts_of(&sem.render_frame(&state)),
+        Some(Vec::new()),
+        "set wipes faces along with captures"
+    );
+    let cells = paint_full_frame(&state, 8, 20);
+    assert!(
+        at(&cells, 20, 6, 0).style.reverse,
+        "chrome is back to the reverse-video default"
+    );
+
+    // pmacs.theme.clear also ships the empty table when faces existed.
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.gutter"] = { fg = 13 } }"#,
+    );
+    let _ = sem.render_frame(&state);
+    exec(&state, "pmacs.theme.clear()");
+    assert_eq!(
+        theme_facts_of(&sem.render_frame(&state)),
+        Some(Vec::new()),
+        "clear ships the empty table"
+    );
+}
+
+#[test]
+fn late_joiner_receives_the_face_table_without_new_mutations() {
+    let mut state = editor();
+    type_str(&mut state, "hello");
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.gutter"] = { fg = 13 } }"#,
+    );
+
+    // First session consumes the table.
+    let mut a = semantic(&state);
+    assert!(theme_facts_of(&a.render_frame(&state)).is_some());
+    assert_eq!(theme_facts_of(&a.render_frame(&state)), None);
+
+    // A second, later attachment gets the authoritative table on its
+    // first frame with zero mutations since (Q#TH7 None seeding).
+    let mut b = semantic(&state);
+    let facts = theme_facts_of(&b.render_frame(&state)).expect("late joiner is corrected");
+    assert_eq!(facts.len(), 1);
+    assert_eq!(facts[0].name, "ui.gutter");
+}
+
+// ---------------------------------------------------------------------------
+// 13 — face-only mutations stay off the syntax paths
+// ---------------------------------------------------------------------------
+
+#[test]
+fn face_only_mutations_ship_facts_but_no_spans_or_summary() {
+    let dir = tempfile::tempdir().expect("tempdir");
+    let state = open_and_wait_for_parse(rust_fixture(&dir));
+    let mut sem = semantic(&state);
+    let first = sem.render_frame(&state);
+    assert!(has_style_spans(&first) && summary_of(&first).is_some());
+
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ["ui.modeline"] = { bg = 236 } }"#,
+    );
+    let frame = sem.render_frame(&state);
+    assert!(theme_facts_of(&frame).is_some(), "the face table ships");
+    assert!(
+        !has_style_spans(&frame),
+        "a face-only merge never re-runs the tree-sitter path"
+    );
+    assert!(
+        summary_of(&frame).is_none(),
+        "the unchanged summary is payload-suppressed"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 15 — resolution is daemon-side
+// ---------------------------------------------------------------------------
+
+#[test]
+fn resolution_is_daemon_side_for_the_diag_family() {
+    let mut state = editor();
+    type_str(&mut state, "hello");
+    let mut sem = semantic(&state);
+    let _ = sem.render_frame(&state);
+
+    exec(&state, r#"pmacs.theme.merge { ["ui.diag"] = { fg = 93 } }"#);
+    let facts = theme_facts_of(&sem.render_frame(&state)).expect("emits");
+    let names: Vec<&str> = facts.iter().map(|f| f.name.as_str()).collect();
+    assert_eq!(
+        names,
+        [
+            "ui.diag.error",
+            "ui.diag.hint",
+            "ui.diag.info",
+            "ui.diag.warning"
+        ],
+        "the walk happens daemon-side: concrete children ship, the parent doesn't"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 17 — the daemon version gate (v15 peer never receives ThemeFacts)
+// ---------------------------------------------------------------------------
+
+#[cfg(feature = "crdt")]
+#[test]
+fn v15_peer_never_receives_theme_facts_and_v16_does() {
+    use common::daemon::{TestDaemon, build_default_caps};
+    use pmacs::protocol::{AttachRequest, FrontendCapabilities, FrontendEvent, Hello};
+    use pmacs::transport::{read_message, write_message};
+
+    fn semantic_caps() -> FrontendCapabilities {
+        FrontendCapabilities {
+            multi_frontend: true,
+            crdt_replica: true,
+            semantic_render: true,
+            ..build_default_caps()
+        }
+    }
+
+    /// Attach a semantic session at `version`, declare a viewport,
+    /// and report `(saw_theme_facts, saw_style_spans)` within the
+    /// deadline.
+    fn probe(daemon: &TestDaemon, version: u32) -> (bool, bool) {
+        let mut stream = daemon.connect();
+        stream
+            .set_read_timeout(Some(Duration::from_millis(250)))
+            .unwrap();
+        let hello: Hello = read_message(&mut stream).expect("read Hello");
+        let fid = hello.assigned_frontend_id;
+        write_message(
+            &mut stream,
+            &AttachRequest {
+                protocol_version: version,
+                frontend_capabilities: semantic_caps(),
+                initial_size: CellSize::new(24, 80),
+            },
+        )
+        .expect("write AttachRequest");
+        // Learn a buffer id from the bootstrap snapshot, declare the
+        // viewport, then classify what arrives.
+        let mut buf = None;
+        let learn_by = Instant::now() + Duration::from_secs(2);
+        while Instant::now() < learn_by && buf.is_none() {
+            if let Ok(InstanceMessage::BufferSnapshot { buffer_id, .. }) =
+                read_message::<InstanceMessage>(&mut stream)
+            {
+                buf = Some(buffer_id);
+            }
+        }
+        let buffer_id = buf.expect("received a BufferSnapshot");
+        write_message(
+            &mut stream,
+            &FrontendEvent::Viewport {
+                frontend_id: fid,
+                buffer_id,
+                visible: ByteRange {
+                    start: 0,
+                    end: 4096,
+                },
+                generation: 0,
+            },
+        )
+        .expect("write Viewport");
+        let deadline = Instant::now() + Duration::from_secs(3);
+        let (mut saw_facts, mut saw_spans) = (false, false);
+        while Instant::now() < deadline && !(saw_facts && saw_spans) {
+            match read_message::<InstanceMessage>(&mut stream) {
+                Ok(InstanceMessage::ThemeFacts { .. }) => saw_facts = true,
+                Ok(InstanceMessage::StyleSpans { .. }) => saw_spans = true,
+                Ok(_) | Err(_) => {}
+            }
+        }
+        (saw_facts, saw_spans)
+    }
+
+    let daemon = TestDaemon::spawn();
+    let (v16_facts, v16_spans) = probe(&daemon, 16);
+    assert!(v16_spans, "a v16 semantic session receives StyleSpans");
+    assert!(
+        v16_facts,
+        "a v16 semantic session receives the authoritative ThemeFacts"
+    );
+    let (v15_facts, v15_spans) = probe(&daemon, 15);
+    assert!(v15_spans, "a v15 peer still receives StyleSpans");
+    assert!(
+        !v15_facts,
+        "the daemon skip arm must keep ThemeFacts off a v15 wire"
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 24 — the Lua surface is unchanged
+// ---------------------------------------------------------------------------
+
+#[test]
+fn lua_surface_lists_faces_alongside_captures() {
+    let state = editor();
+    exec(
+        &state,
+        r#"pmacs.theme.merge { ui = { fg = 3 }, ["ui.modeline"] = { fg = 252, bg = 236 },
+                              keyword = { fg = 1 } }"#,
+    );
+    let (has_ui, has_modeline, has_keyword): (bool, bool, bool) = eval(
+        &state,
+        r#"
+        local t = pmacs.theme.current()
+        return t["ui"] ~= nil, t["ui.modeline"] ~= nil, t["keyword"] ~= nil
+        "#,
+    );
+    assert!(has_ui && has_modeline && has_keyword);
+    let (fg, bg): (i64, i64) = eval(
+        &state,
+        r#"
+        local s = pmacs.theme.get("ui.modeline")
+        return s.fg, s.bg
+        "#,
+    );
+    assert_eq!((fg, bg), (252, 236), "get returns the set face style");
+}
+
+// ---------------------------------------------------------------------------
+// Minibuffer faces (items 2's remaining surfaces): prompt/input/fill
+// through the dispatched M-x path; the candidate suffix through
+// selection.
+// ---------------------------------------------------------------------------
+
+#[test]
+fn minibuffer_and_candidate_faces_apply_through_m_x() {
+    let mut state = editor();
+    let (rows, cols) = (8u32, 40u32);
+    exec(
+        &state,
+        r#"pmacs.theme.merge {
+            ["ui.minibuffer"] = { fg = 6 },
+            ["ui.minibuffer.candidate"] = { fg = 11 },
+        }"#,
+    );
+
+    alt(&mut state, 'x');
+    type_str(&mut state, "window");
+    press(&mut state, KeyCode::Down);
+    let cells = paint_full_frame(&state, rows, cols);
+    let bottom = rows - 1;
+    let text = row_text(&cells, cols, bottom);
+    assert!(text.starts_with("M-x window"), "minibuffer open: {text:?}");
+
+    // Prompt + input carry the minibuffer face, plain surface.
+    let prompt_cell = at(&cells, cols, bottom, 0);
+    assert_eq!(prompt_cell.style.fg, Color::Indexed(6));
+    assert!(!prompt_cell.style.reverse);
+
+    // The selected-candidate suffix (`  [cand]`) carries its own face.
+    if let Some(bracket) = text.find('[') {
+        let cand_cell = at(&cells, cols, bottom, bracket as u32);
+        assert_eq!(
+            cand_cell.style.fg,
+            Color::Indexed(11),
+            "candidate suffix face"
+        );
+        assert!(
+            !cand_cell.style.reverse,
+            "candidate surface resets to plain"
+        );
+    } else {
+        panic!("no candidate suffix rendered: {text:?}");
+    }
+}