WholeWindowLiquidGlass

Turn an entire macOS window into a single translucent Liquid Glass sheet that samples the desktop behind it, like the system volume / brightness HUD, with the progressive-blur ramp flattened so the backdrop reads crisp instead of milky.

One drop-in file, no dependencies. Verified on macOS 26 (Tahoe).

Why not just .glassEffect?

SwiftUI's .glassEffect never samples behind its own window. It only sees the content of the same window, so a floating panel gets a flat, dark fallback no matter which style you pick. The only thing that honestly samples the desktop backdrop is the AppKit NSGlassEffectView, and getting it to read sharp takes a few private-CAFilter adjustments. This package wraps all of that behind a single modifier.

⚠️ Not for the Mac App Store

The tuner touches private CAFilter inputs (inputBlurOpacity0..4, inputBlurRadius, inputFaceColorMatrix*) on the private glassBackground filter. Adding this package to a target is the opt-in — there is no runtime flag to disable it. Do not ship it in a Mac App Store binary. Gate it with your own compilation condition (e.g. #if DIRECT) or by target membership.

All private-SPI access is responds(to:) / key-presence guarded, so a future SDK that drops the SPI silently falls back to the stock material rather than crashing.

Install

Swift Package Manager:

.package(url: "https://github.com/vientooscuro/WholeWindowLiquidGlass.git", from: "1.0.0")

Then add WholeWindowLiquidGlass to your target's dependencies.

Usage

import WholeWindowLiquidGlass

WindowGroup {
    RootView()
        .wholeWindowLiquidGlass()   // apply once, anywhere inside the window
}

Your root view should draw a transparent/clear background — the glass becomes the window's backdrop and your content floats on top of it. For legibility, use translucent dark fills (~50–65% dark) over the glass. Avoid stacking SwiftUI .glassEffect(.regular) plates on top: .regular reads as a milky slab over the clear sheet.

Configuration:

.wholeWindowLiquidGlass(.init(
    backdropBlurRadius: 2.5,            // crispness (stock ~7–8 reads as mush)
    flattenProgressiveBlur: true,        // zero the progressive-blur bands
    neutralizeRegularGlassFaces: true,   // de-milk .regular glass left in the window
    cornerRadius: 0,
    variant: nil,                        // do NOT set variant 6 on a full window
    logsDiagnostics: false               // + env WHOLE_WINDOW_GLASS_DUMP=1 → layer dump
))

Option	Default	Effect
backdropBlurRadius	2.5	Blur radius after the ramp is flattened. Stock .clear uses ~7–8 (soft); 2.5 matches the crisp system HUD.
flattenProgressiveBlur	true	Zero the progressive-blur bands (inputBlurOpacity0..4) — the main source of the milky mush.
neutralizeRegularGlassFaces	true	Copy the .clear backing's neutral face-colour matrix onto any .glassEffect(.regular) surfaces in the window, de-milking them. Their own face opacity is preserved for legibility.
cornerRadius	0	Corner radius of the window-backing glass sheet.
variant	nil	Private set_variant: override. Leave nil for a full window (6 = light HUD glass, only right for small OSD pills).
logsDiagnostics	false	One-shot diagnostic summary; with WHOLE_WINDOW_GLASS_DUMP=1 also dumps the layer tree.

Hard-won notes (baked into the implementation)

1. SwiftUI .glassEffect can't do this — it never samples behind its own window. Only AppKit NSGlassEffectView honestly samples the desktop backdrop.
2. style = .clear is the only neutral-transparent style. .regular is a milky plate (crushed luma + oversaturation).
3. Do not apply set_variant: 6 to a full window. That is the light HUD variant (right for a small OSD pill); on a window it overrides the dark appearance and washes everything out to white.
4. The "mush" is not the blur radius — it's the progressive-blur bands (inputBlurOpacity0..4) of the glassBackground filter. Zero the bands, keep a small radius (~2.5), and the backdrop reads sharp like the system HUD.
5. Re-apply every frame via NSView.displayLink. AppKit rebuilds the glass material asynchronously (theme change, resize, key/non-key) and clobbers the overrides. The display link auto-pauses while the window is off screen.
6. Insert the NSGlassEffectView fully configured, inside a zero-duration NSAnimationContext with implicit animation disabled. An NSGlassEffectView animating layout under a SwiftUI hosting view has crashed with an AttributeGraph precondition failure.
7. Find the glass filter by its inputBlurOpacity0 key, not by name. SwiftUI and AppKit share the glassBackground name, but the key is the reliable probe.
8. De-milking .regular surfaces: the neutral face-colour matrix is copied from the .clear backing; inputFaceOpacity is deliberately not copied so the surfaces keep a readable body (with opacity 0 the text floats over the raw desktop).

Compatibility

macOS 26 (Tahoe) and later. On earlier macOS the modifier is a no-op, so it is safe to leave in a codebase with a lower deployment target.

License

MIT © 2026 Daniil Nuzhdin