fix: reduce macOS popup compositing cost

.project-docs/50-evidence/topics/20260818-macos-popup-lag-7c4e__popup-compositing.md

@@ -0,0 +1,48 @@
+# macOS Popup Compositing Probe
+
+## Claim
+
+The reported popup lag has a reproducible Renderer-side hotspot in transient
+backdrop sampling. The shared Dialog overlay and glass content both applied
+`backdrop-filter` in the baseline build. A Darwin-scoped rule now removes those
+filters and makes the popup glass surface opaque while leaving other platforms
+unchanged.
+
+## Evidence
+
+- Environment: Windows development host; the Electron E2E launches the real
+  shared Settings Dialog, but Darwin is simulated through the exposed platform
+  marker. A signed macOS package was not available for this run.
+- Baseline probe (before the fix, repeated twice): overlay computed
+  `backdropFilter: blur(3px)`; content computed
+  `backdropFilter: blur(18px) saturate(1.35)`; maximum sampled frame gap was
+  62.5 ms with one frame over 32 ms.
+- Single-variable filter probe: both computed filters became `none`; the same
+  probe observed an approximately 31.4 ms maximum gap and zero frames over
+  32 ms in this environment.
+- A temporary skip-GPU-call probe did not change the sampled result on this
+  non-macOS host, so it does not establish or disprove the real macOS
+  hardware-acceleration hypothesis.
+
+## Implementation
+
+- `src/main.tsx` writes `html[data-platform]` before the first React render.
+- `src/styles/globals.css` disables both `backdrop-filter` implementations for
+  Darwin transient popup roots (`dialog`, `alertdialog`, `menu`, `listbox`,
+  `tooltip`, and full-screen fixed overlays), and uses an opaque background for
+  their glass surfaces.
+- `tests/e2e/popup-performance.spec.ts` checks the real platform marker, Darwin
+  filter removal, and non-Darwin preservation. It does not impose a fixed RAF
+  threshold because CI scheduling is not a stable performance baseline.
+
+## Verification
+
+`build:vite`, `typecheck`, focused ESLint, focused modal unit tests, the popup
+E2E (1/1), and `git diff --check` passed. Existing build warnings are unrelated
+chunk-size and dynamic-import warnings.
+
+## Remaining uncertainty
+
+Real macOS GPU/vibrancy composition, Sheet coverage, nested Dialog coverage, and
+physical frame-time improvement still require signed-package validation on
+macOS hardware.