Stage Manager: 1-frame black flicker in translucent area on focus regain (macOS Tahoe OS limitation)

[EinfachValle]

Summary

When the app window regains focus via Stage Manager (and to a lesser extent Cmd-Tab / Dock-click), the translucent/see-through areas of the window flash black for ~1 frame during the swap-in animation. The sequence the user sees is:

blur (snapshot) → black → blur (live)

The black appears only in the transparent areas where the desktop blur normally shows through (the gaps between opaque React surfaces), not over the opaque UI.

Environment

• macOS Tahoe (26.x)
• Tauri v2, transparent window (transparent: true, macOSPrivateApi: true, decorations: false)
• Translucency = OS vibrancy material behind a transparent WKWebView

Root cause (confirmed by elimination)

The black flash is the OS vibrancy material (NSVisualEffectView / NSGlassEffectView, BehindWindow blending) flashing during the Stage Manager swap-in animation. This is an OS-level (AppKit) behaviour on macOS Tahoe, not something the app can fix while keeping the desktop blur.

This was established by systematically toggling each layer and observing the result:

Configuration	Desktop blur	Black flicker
OS material on — NSGlassEffectView (liquid-glass plugin)	yes	flickers
OS material on — NSVisualEffectView, FollowsWindowActiveState	yes	flickers
OS material on — NSVisualEffectView, Active	yes	flickers
WKWebView occlusion detection disabled (_setWindowOcclusionDetectionEnabled:NO)	—	no change, still flickers
NSWindow backing forced clearColor + isOpaque=NO	—	no change (window was already transparent)
OS material removed entirely	no	no flicker (only a mild tint darkening)

Key findings

1. The black flicker is inseparable from the OS material. Removing the material removes the flicker — but also removes the blur.
2. CSS backdrop-filter cannot blur the desktop behind a transparent window. The window-server composites the desktop outside the web content, so backdrop-filter (which only blurs same-document content) never touches it. Confirmed: with the OS material off, the window is 100% transparent with zero blur, despite the CSS ::before backdrop-filter being active. ⇒ The blur slider (blurIntensity → --translucency-blur-px) currently has no visible effect; all blur comes from the fixed-radius OS material. (Worth tracking separately — the CSS blur layer is effectively dead code.)
3. Related Apple bug reports:
   • Black Pixel Flicker When Using glassEffect() with Animation
   • NSGlassEffectView caching/render bug on macOS 26.2 (Apple's own suggested workaround: revert to NSVisualEffectView)
   • macOS Tahoe persistent display flicker
   • Tauri #8255 — transparent window glitch on focus change

Decision

Accepted as a known macOS limitation. We keep the desktop blur (via window-vibrancy / NSVisualEffectView, Sidebar material, Active state) and accept the one-frame Stage Manager flicker. Reverting to NSGlassEffectView is worse (same flicker + extra macOS 26 glass bugs). Removing the material kills the flicker but also the blur, which isn't an acceptable trade for the default experience.

Possible future mitigations

• Revisit when Apple fixes the macOS Tahoe vibrancy/Stage Manager compositing (track macOS point releases).
• Optional setting "Desktop blur (off by default)" so flicker-sensitive users get a clean, flicker-free tinted-translucent mode.
• Investigate masking the swap-in frame with a theme-coloured overlay (uncertain — the flash is during the OS animation, before app code runs).
• Separate cleanup: the CSS backdrop-filter layer + blur slider are no-ops for desktop blur — either remove or repurpose.

Current implementation

• Translucency material applied in app/src-tauri/src/commands/theme.rs::apply_translucency via window-vibrancy.
• tauri-plugin-liquid-glass was removed (it forced the buggy NSGlassEffectView on macOS 26).