Add configurable native glass window backgrounds

docs/BRAND.md

@@ -44,3 +44,19 @@ The brand board's example `searchi winter.pdf` is illustrative. Documentation
 must show the actual supported CLI syntax. Model downloads require networking;
 file extraction, inference, and search remain local. Never turn visual marketing
 copy into unsupported performance or production-readiness claims.
+
+## Window materials
+
+Appearance settings offer Solid, Glass and Frosted glass, with a bounded
+70–100% tint-strength control (90% by default). Frosted glass layers an extra
+35% milk tint beneath that control; Glass has the lighter direct tint. Both
+currently share Windows native acrylic blur. Native compositor effects expose and soften
+the actual desktop; CSS transparency alone cannot blur other windows. If the
+platform cannot apply its native effect, use an honest opaque fallback. Forced
+colors always make the shell opaque while retaining the saved preference.
+Search input, results, previews and settings keep their opaque reading surfaces;
+never lower text opacity or introduce decorative wallpaper simulations.
+Native acrylic currently requires Windows 11 22H2 or later with a compatible
+compositor and system transparency settings. macOS, Linux and older Windows
+currently use opaque fallback. Native material appearance and compositor
+performance still need actual OS validation.

docs/ROADMAP.md

@@ -36,6 +36,10 @@ Status: implementation started; no production release yet. Windows VM tests use
   see [incremental semantic design](INCREMENTAL-SEMANTIC.md).
 
 ## 3. Desktop
+- [x] Persisted solid/glass/frosted appearance and bounded background tint;
+  opaque reading surfaces, serialized settings updates and high-contrast fallback.
+- [ ] Verify native glass visually on Windows 11 22H2+; macOS/Linux currently
+  use an explicit opaque fallback. Native compositor performance remains open.
 - [ ] Tauri shell, accessible keyboard search, progressive results and previews (shell built; UI interaction verification pending).
 - [ ] Folder selection, exclusion controls, resource budgets and indexing status.
 - [ ] Global shortcut, opening/revealing source files, PDF page navigation.
@@ -197,8 +201,10 @@ Audit and measured priorities: [EMBEDDINGGEMMA2-AUDIT.md](EMBEDDINGGEMMA2-AUDIT.
       media retry status across engine/desktop; genuine CPU promotion reuses
       identical document vectors with zero document re-encodes.
       See [early text setup](EARLY-TEXT-SETUP.md).
-    - [ ] Verify native first use during genuine delayed media download,
-      failure/retry and promotion; record actual first-input timing separately.
+    - [x] Native Linux CPU first use during genuine delayed media download,
+      failure/retry and promotion; actual first-input timing recorded separately.
+      Focused activation retest preserves selection and query process, records
+      fresh timing/current generation after idle. Windows/macOS checks stay open.
 - [ ] Buffered bounded media IPC and linear UTF-8 source-window offset processing.
 - [ ] Evaluate 256d MRL and content-specific vision budgets on independent data.
 - [ ] Validate GPU precision, synchronization-aware timings, parity and fallback

docs/WINDOW-MATERIALS.md

@@ -0,0 +1,42 @@
+# Configurable window backgrounds
+
+Settings → Appearance offers Solid, Glass and Frosted glass. Preferences are
+saved locally. The tint-strength control ranges from 70 to 100%; the default
+is Frosted glass at 90%. Glass uses the direct tint; Frosted glass adds a 35%
+milk layer beneath it. This changes background treatment, never text opacity.
+
+Search input, result and preview panes and settings retain opaque reading
+surfaces. Shell secondary text becomes stronger over translucent backgrounds.
+High contrast immediately forces an opaque surface without changing the saved
+preference. Appearance writes are serialized; obsolete replies cannot overwrite
+the latest preference or accessibility state.
+
+## Platform support
+
+Windows 11 22H2 and newer use a transparent WebView and the established
+window-vibrancy crate's native acrylic implementation. Glass and Frosted glass
+share that native blur; their frontend milk tint differs. Desktop composition
+and OS high-contrast checks precede application, and native HRESULT failure
+returns an explicit solid fallback. Native window chrome remains enabled.
+
+Older Windows, macOS and Linux currently use a solid fallback. This macOS build
+does not enable private WebView transparency APIs. CSS backdrop-filter is not
+used to pretend the desktop is blurred. The settings report the effective
+material and explain the fallback.
+
+## Recorded checks, 2026-10-13
+
+- 57 frontend tests passed, including missing native capability, high contrast,
+  bounded tint, serialized pending preferences and stale failure handling.
+- Frontend type checking, production build and formatting passed.
+- 33 desktop Rust tests passed with one test thread; settings checks cover legacy
+  defaults, persisted preferences and invalid-value rejection preserving the
+  previous file and memory. An earlier parallel run hit a transient Windows
+  AccessDenied in an existing atomic-settings replacement test.
+- Desktop Rust formatting and strict all-target Clippy passed.
+
+Actual native material appearance and resize/compositor performance remain
+unverified. Enabled browser inventory was empty; native Windows capture/input
+access was unavailable. These checks establish implementation and persistence,
+not visual quality on release hardware. macOS/Linux native materials remain
+future work.