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

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.