trackerkeeper 0.1.0__py3-none-any.whl

trackerkeeper/blur/__init__.py

@@ -0,0 +1,212 @@
+"""Window "blur behind" — the frosted-glass effect for translucent
+surfaces. This is what visually separates Frosted mode (blurred glass)
+from Transparent mode (clear glass).
+
+Public API:
+    is_supported() -> bool          # backend can *request* blur
+    apply(widget, enabled) -> bool  # enable/disable blur behind widget
+    status() -> BlurStatus          # is a real backdrop VERIFIED behind us?
+
+The status() call is the one that fixes the "frosted renders see-through"
+class of bug: `apply()` is fire-and-forget (KWin gives no success signal),
+so a frosted body painted at ~67% opacity goes transparent-broken wherever
+blur silently no-ops (Blur effect off, missing plugin, no compositing, a
+non-KDE desktop, Windows < 11). `status()` probes whether a real backdrop
+is actually present so the theme layer can pick the body alpha — full glass
+when blur landed, a near-opaque "frosted panel" fallback when it didn't.
+See trackerkeeper/theme.body_color_for() and docs/research/portable_blur.md.
+
+Backend (Linux): KDE's KWindowSystem — `KWindowEffects::enableBlurBehind`
+to request blur and `KWindowEffects::isEffectAvailable(BlurBehind)` to
+verify it, both via ctypes (no PySide6 binding exists). KWindowSystem
+speaks `ext-background-effect-v1` where the compositor offers it and falls
+back to the legacy `org_kde_kwin_blur` — so this covers KWin, and also niri
+/ COSMIC where KWindowSystem is installed.
+
+Everywhere else (Windows, macOS, or a Linux box without KWindowSystem, or a
+compositor with no blur protocol — Hyprland/Wayfire/sway/GNOME): the
+backend reports UNSUPPORTED and the window paints a near-opaque body. On
+compositors that blur via user config rather than a protocol (Hyprland,
+Wayfire, SwayFX), the user can target trackerkeeper in their own window rules:
+our Wayland app_id is the stable string "trackerkeeper" (set via
+setDesktopFileName).
+"""
+
+from __future__ import annotations
+
+import enum
+import os
+
+
+class BlurStatus(enum.Enum):
+    """Whether a real compositor/OS backdrop is verified to sit behind the
+    window — the signal the theme layer maps to a body opacity.
+
+    ACTIVE                 — blur issued AND positive evidence it landed;
+                             frosted surfaces ride it at full glass alpha.
+    REQUESTED_UNVERIFIABLE — blur was issued but we can't confirm it took
+                             (no success feedback, or a known-flaky path
+                             like KDE X11); paint a conservative near-opaque
+                             body so we never gamble on a see-through window.
+    UNSUPPORTED            — the backend can't request blur here at all;
+                             paint the near-opaque fallback body.
+    DISABLED               — the active theme doesn't ask for blur (Solid /
+                             Transparent); not an error. Bodies keep their
+                             own opaque/translucent alpha unchanged.
+    """
+
+    ACTIVE = "active"
+    REQUESTED_UNVERIFIABLE = "unverifiable"
+    UNSUPPORTED = "unsupported"
+    DISABLED = "disabled"
+
+
+from trackerkeeper.platform_compat import IS_LINUX, IS_MACOS, IS_WINDOWS
+
+if IS_LINUX:
+    from trackerkeeper.blur import _kwin as _backend
+elif IS_WINDOWS:  # pragma: no cover - exercised on Windows
+    from trackerkeeper.blur import _dwm as _backend
+elif IS_MACOS:  # pragma: no cover - exercised on macOS
+    from trackerkeeper.blur import _macos as _backend
+else:  # pragma: no cover
+    from trackerkeeper.blur import _unsupported as _backend
+
+
+# Process-wide cache. Blur availability is a per-session compositor/OS fact,
+# not a per-window one (KWindowEffects::isEffectAvailable takes no window),
+# so we probe once and reuse. force=True re-probes after a compositing /
+# Blur-effect toggle.
+_status_cache: BlurStatus | None = None
+
+# Debug override: TRACKERKEEPER_BLUR_FORCE=active|unverifiable|unsupported pins the
+# reported status, bypassing the probe. Lets you eyeball the near-opaque
+# fallback body (TRACKERKEEPER_BLUR_FORCE=unsupported) without disabling the
+# compositor's Blur effect, and the reverse on a box where blur is off.
+# Same JT_* debug-switch family as TRACKERKEEPER_OPAQUE.
+_FORCE = os.environ.get("TRACKERKEEPER_BLUR_FORCE", "").strip().lower()
+
+
+def opaque_mode_active() -> bool:
+    """Dev diagnostic: fully-opaque chrome — no translucency, no blur — via the
+    ``TRACKERKEEPER_OPAQUE=1`` env switch. When on, :func:`status` reports UNSUPPORTED (so
+    frosted bodies + popups use their near-opaque fallback) and :func:`apply`
+    skips requesting compositor blur.
+
+    Env-only on purpose — there is NO user-facing setting. A frosted theme that
+    can't get real blur already falls back to a near-opaque body automatically
+    (status() → UNSUPPORTED/REQUESTED_UNVERIFIABLE), which covers the real user
+    need; the old Settings toggle additionally dropped WA_TranslucentBackground
+    and broke the window's rounded corners, so it was removed. TRACKERKEEPER_OPAQUE stays
+    for the screencast / streaming-flicker repro it was born for. Never raises."""
+    return os.environ.get("TRACKERKEEPER_OPAQUE") == "1"
+
+
+def is_supported() -> bool:
+    """True if the backend can *request* blur (KWindowSystem present /
+    Windows 11 build). A True here doesn't guarantee the compositor will
+    actually blur — that's what status() checks."""
+    return _backend.is_supported()
+
+
+def apply(
+    widget,
+    enabled: bool,
+    corner_radius: int = 0,
+    dark: bool | None = None,
+    elevated: bool = False,
+) -> bool:
+    """Enable (``enabled=True``) or remove (``False``) compositor blur
+    behind ``widget``'s window. ``widget`` is a QWidget; its QWindow must
+    already exist (call after ``show()``).
+
+    ``corner_radius``: when > 0 the blur region is shaped to a rounded
+    rectangle of that radius matching the widget's current size — pass this
+    for frameless rounded windows (mini player, settings dialog) so the blur
+    doesn't bleed into the transparent corners. ``0`` blurs the whole window
+    rectangle — correct for server-side-decorated windows.
+
+    ``dark``: dark vs light variant for backends whose backdrop has one
+    (Windows Mica's immersive dark/light tint). ``None`` (the default)
+    resolves it from the active theme, so every call site gets the right
+    variant for free; the KWin / macOS / unsupported backends ignore it.
+
+    ``elevated``: True for elevated popups (menus / dropdowns / volume
+    popups / tooltips) that paint their own status-aware QSS frost fill.
+    Backends whose blur material carries a built-in tint (Windows
+    Acrylic) drop it to near-zero so the popup isn't double-veiled —
+    KWin's blur is untinted, so on Linux this is a no-op and the QSS
+    fill stays the single tint source everywhere.
+
+    Returns True if the request was issued, False on any unsupported /
+    not-yet-shown case. The return is best-effort ("issued", not "blurred")
+    — use status() to learn whether blur actually landed. Never raises."""
+    if enabled and opaque_mode_active():
+        # User forced opaque chrome — never request blur (and remove any
+        # already-applied blur on this widget).
+        enabled = False
+    # "Never raises" is part of the contract (blur is progressive enhancement)
+    # — theme resolution + the backend call are best-effort, so swallow errors.
+    try:
+        if dark is None:
+            from trackerkeeper.theme import get_active_theme
+
+            dark = get_active_theme().dark
+        # On macOS this dispatches to the live NSVisualEffectView vibrancy
+        # backend (trackerkeeper/blur/_macos.py): it installs a "behind window" effect
+        # view as a SIBLING ordered strictly below Qt's content view, so the
+        # system frost shows through the translucent body — the mac-native
+        # equivalent of KWin's blur-behind. corner_radius/dark/elevated all
+        # forward through, same as the KWin/DWM backends.
+        return _backend.apply(widget, enabled, corner_radius, dark, elevated)
+    except Exception:
+        return False
+
+
+def status(*, force: bool = False) -> BlurStatus:
+    """Whether a real backdrop is VERIFIED behind our windows on this
+    machine/session — the value the theme layer uses to choose body opacity.
+
+    Computed once and cached (the answer is a per-session compositor/OS
+    fact). Pass ``force=True`` to re-probe, e.g. after the window is mapped
+    or a compositing/Blur-effect toggle. Returns ACTIVE /
+    REQUESTED_UNVERIFIABLE / UNSUPPORTED — never DISABLED (that's the theme's
+    call, not the machine's). Never raises; any failure resolves to the
+    conservative REQUESTED_UNVERIFIABLE so a frosted body stays near-opaque
+    rather than risking see-through."""
+    global _status_cache
+    if opaque_mode_active():
+        # User forced opaque chrome — report no backdrop so frosted bodies +
+        # popups fall back to their near-opaque alpha.
+        return BlurStatus.UNSUPPORTED
+    if _FORCE:
+        try:
+            forced = BlurStatus(_FORCE)
+        except ValueError:
+            forced = None  # unrecognised value → ignore, probe normally
+        # status() reports a machine capability and never returns DISABLED
+        # (that's the theme's call) — so TRACKERKEEPER_BLUR_FORCE=disabled is ignored.
+        if forced is not None and forced is not BlurStatus.DISABLED:
+            return forced
+    if _status_cache is not None and not force:
+        return _status_cache
+    try:
+        _status_cache = _backend.probe()
+    except Exception:
+        _status_cache = BlurStatus.REQUESTED_UNVERIFIABLE
+    return _status_cache
+
+
+def reason() -> str:
+    """A short, human-readable explanation of the current blur status — for
+    the boot log and the Settings hint when a frosted theme can't get real
+    blur (e.g. "GNOME has no app-controllable window blur", "KWin's Blur
+    effect is off", "Windows 10 has no Mica backdrop"). Reads status()
+    (cached) + the environment via the active backend. Never raises."""
+    st = status()
+    try:
+        return _backend.reason(st)
+    except Exception:
+        if st is BlurStatus.ACTIVE:
+            return "compositor blur active"
+        return "compositor blur unavailable — using a near-opaque body"

trackerkeeper/blur/_dwm.py

@@ -0,0 +1,348 @@
+"""Windows blur backend for the Frosted theme.
+
+The DEFAULT is real **Acrylic** blur-behind — live frosted glass — driven by
+the legacy ``SetWindowCompositionAttribute`` accent policy
+(``ACCENT_ENABLE_ACRYLICBLURBEHIND``); see ``apply_acrylic``. ``TRACKERKEEPER_NO_WIN_BLUR``
+opts out to the DWM **Mica** system backdrop instead (an opaque, once-sampled
+wallpaper tint — NOT a live blur). Both composite BEHIND the window, visible
+through transparent Qt pixels — the Windows analog of KWin's blur-behind. The
+main window pairs the Acrylic path with a NON-layered window (trackerkeeper/app.py's
+``_win_blur`` drops ``WA_TranslucentBackground``); the layered mini player /
+dialogs keep it.
+
+``DwmSetWindowAttribute`` returns an HRESULT, so the Mica fallback has real
+success feedback. Build gates for that fallback (verified against
+learn.microsoft.com):
+
+  * Windows 11 22H2+ (build >= 22621): the documented
+    ``DWMWA_SYSTEMBACKDROP_TYPE`` (38) = ``DWMSBT_MAINWINDOW`` (2 = Mica).
+  * Windows 11 21H2 (22000..22620): the undocumented ``DWMWA_MICA_EFFECT``
+    (1029) = 1.
+  * Windows 10 / older (< 22000): no backdrop — UNSUPPORTED → near-opaque body.
+
+Mica only renders when Windows' "Transparency effects" toggle is on; when it's
+off we'd paint a translucent body over nothing (see-through), so ``probe()``
+reads that setting from the registry and reports UNSUPPORTED when it's off —
+the Windows analog of KDE's ``kwinrc blurEnabled`` demotion.
+
+See docs/research/portable_blur.md §5. The DWM calls are exercised on Windows
+only; the build/transparency gating is unit-tested cross-platform.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import sys
+
+from trackerkeeper.platform_compat import IS_WINDOWS
+
+# ── DWM attribute ids + backdrop enum (learn.microsoft.com) ──────────────
+_DWMWA_USE_IMMERSIVE_DARK_MODE = 20  # dark native titlebar
+_DWMWA_SYSTEMBACKDROP_TYPE = 38  # documented; build >= 22621
+_DWMWA_MICA_EFFECT = 1029  # legacy undocumented; build 22000..22620
+_DWMWA_WINDOW_CORNER_PREFERENCE = 33  # round a frameless window; build >= 22000
+_DWMWCP_ROUND = 2  # DWMWCP_ROUND — round the corners
+_DWMSBT_NONE = 1  # remove the backdrop
+_DWMSBT_MAINWINDOW = 2  # Mica
+
+_MIN_BUILD_MICA = 22000  # Windows 11 21H2
+_MIN_BUILD_DOCUMENTED = 22621  # Windows 11 22H2 (documented attr 38)
+
+
+def _build() -> int:
+    """Windows build number, or 0 where unavailable (non-Windows / error)."""
+    try:
+        return int(sys.getwindowsversion().build)
+    except Exception:
+        return 0
+
+
+def _transparency_enabled() -> bool:
+    """Windows "Transparency effects" toggle (Settings → Personalization →
+    Colors). Mica does not render when it's off, so we'd be painting a
+    translucent body over nothing — read it to demote to the near-opaque
+    fallback instead. HKCU\\…\\Themes\\Personalize\\EnableTransparency;
+    defaults True when unreadable (apply stays best-effort). The Windows
+    analog of KDE's ``kwinrc [Plugins] blurEnabled`` check."""
+    try:
+        import winreg
+
+        with winreg.OpenKey(
+            winreg.HKEY_CURRENT_USER,
+            r"Software\Microsoft\Windows\CurrentVersion\Themes\Personalize",
+        ) as key:
+            val, _ = winreg.QueryValueEx(key, "EnableTransparency")
+            return bool(val)
+    except Exception:
+        return True
+
+
+def is_supported() -> bool:
+    """True on a Windows 11 build that can show Mica. A True here doesn't
+    guarantee it renders (transparency could be off) — that's probe()'s job."""
+    return IS_WINDOWS and _build() >= _MIN_BUILD_MICA
+
+
+class _MARGINS(ctypes.Structure):
+    _fields_ = [
+        ("cxLeftWidth", ctypes.c_int),
+        ("cxRightWidth", ctypes.c_int),
+        ("cyTopHeight", ctypes.c_int),
+        ("cyBottomHeight", ctypes.c_int),
+    ]
+
+
+def _set_attr(hwnd: int, attr: int, value: int) -> int:
+    """DwmSetWindowAttribute(hwnd, attr, &value, 4) → HRESULT.
+
+    ``restype`` is ``c_long`` (signed) so ``E_INVALIDARG`` (0x80070057, high
+    bit set) reads back as a negative failure rather than a huge positive."""
+    fn = ctypes.windll.dwmapi.DwmSetWindowAttribute
+    fn.restype = ctypes.c_long
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_uint, ctypes.c_void_p, ctypes.c_uint]
+    val = ctypes.c_int(value)
+    return fn(
+        ctypes.c_void_p(hwnd),
+        ctypes.c_uint(attr),
+        ctypes.byref(val),
+        ctypes.c_uint(ctypes.sizeof(val)),
+    )
+
+
+def _extend_frame(hwnd: int) -> None:
+    """Extend the window frame across the whole client area (margins all -1)
+    so the Mica backdrop fills it. Required on the legacy 1029 path and
+    harmless-recommended on 22621+."""
+    fn = ctypes.windll.dwmapi.DwmExtendFrameIntoClientArea
+    fn.restype = ctypes.c_long
+    fn.argtypes = [ctypes.c_void_p, ctypes.c_void_p]
+    margins = _MARGINS(-1, -1, -1, -1)
+    fn(ctypes.c_void_p(hwnd), ctypes.byref(margins))
+
+
+# ── SetWindowCompositionAttribute accent policy (undocumented user32) ──────
+# The legacy accent-policy API drives the real Acrylic blur-behind (see
+# apply_acrylic). Undocumented user32, so every call is best-effort.
+_WCA_ACCENT_POLICY = 19
+
+
+class _ACCENT_POLICY(ctypes.Structure):
+    _fields_ = [
+        ("AccentState", ctypes.c_uint),
+        ("AccentFlags", ctypes.c_uint),
+        ("GradientColor", ctypes.c_uint),
+        ("AnimationId", ctypes.c_uint),
+    ]
+
+
+class _WINCOMPATTRDATA(ctypes.Structure):
+    _fields_ = [
+        ("Attribute", ctypes.c_int),
+        ("Data", ctypes.c_void_p),
+        ("SizeOfData", ctypes.c_size_t),
+    ]
+
+
+def _set_wca(hwnd: int, attribute: int, payload) -> bool:
+    """SetWindowCompositionAttribute(hwnd, &WINCOMPATTRDATA) — best-effort.
+    ``payload`` is any ctypes object (ACCENT_POLICY struct or a c_int).
+
+    Returns whether the call was *issued* successfully: the function returns a
+    BOOL (nonzero = accepted), so we propagate it (rather than always claiming
+    success) to give the Acrylic path the same honest 'issued' signal the Mica
+    branch gets from its HRESULT. The undocumented API is best-effort either
+    way — the visible blur is identical whatever this returns; only apply()'s
+    return becomes truthful. False on a zero return, a missing export, or any
+    error (including off-Windows, where ``ctypes.windll`` is absent)."""
+    try:
+        data = _WINCOMPATTRDATA()
+        data.Attribute = attribute
+        data.Data = ctypes.cast(ctypes.byref(payload), ctypes.c_void_p)
+        data.SizeOfData = ctypes.sizeof(payload)
+        fn = ctypes.windll.user32.SetWindowCompositionAttribute
+        fn.restype = ctypes.c_int
+        fn.argtypes = [ctypes.c_void_p, ctypes.c_void_p]
+        return bool(fn(ctypes.c_void_p(hwnd), ctypes.byref(data)))
+    except Exception:
+        return False
+
+
+# ── Acrylic blur-behind (real frosted glass) ──────────────────────────────
+# Unlike Mica (opaque, wallpaper-sampled-once tint), Acrylic is a live
+# frosted-glass blur. The maintained qframelesswindow drives it through the
+# LEGACY accent-policy API (ACCENT_ENABLE_ACRYLICBLURBEHIND), NOT the modern
+# DWMWA_SYSTEMBACKDROP_TYPE — the system-backdrop Acrylic (DWMSBT_TRANSIENT)
+# is for transient surfaces. The GradientColor is the tint over the blur,
+# packed AABBGGRR; alpha governs how much wallpaper-blur reads through.
+_ACCENT_DISABLED = 0
+_ACCENT_ENABLE_ACRYLICBLURBEHIND = 4
+# Border/shadow flags qframelesswindow passes (draw the 4 edges).
+_ACCENT_DRAW_ALL_BORDERS = 0x20 | 0x40 | 0x80 | 0x100
+# Dark carries a heavier veil than light: at the shared 0x99 the dark
+# theme read "too transparent — missing the weight of a dark themed
+# app" over a bright wallpaper (eyeball-calibrated to 190/0xBE on the
+# Windows 11 laptop, 2026-06-10; light stays at qframelesswindow's
+# default, which calibrated as already right).
+_ACRYLIC_TINT_DARK = 0xBE202020  # A=0xBE (190) over (32,32,32)
+_ACRYLIC_TINT_LIGHT = 0x99F2F2F2  # qframelesswindow's default light tint
+
+
+def _acrylic_tint(dark: bool, elevated: bool = False) -> int:
+    """Acrylic tint (AABBGGRR). TRACKERKEEPER_WIN_BLUR_ALPHA overrides just the alpha
+    (0–255): lower = more blur reads through, higher = more solid tint.
+
+    ``elevated`` (menus / dropdowns / volume popups / tooltips): these
+    surfaces carry their own status-aware QSS frost fill — the same veil
+    that KDE's UNTINTED KWin blur composites under on Linux. Acrylic's
+    default tint stacked a second warm veil on top, so Windows popups
+    read warmer + more opaque than the same popup on Linux (2026-06-10
+    Windows round). Elevated surfaces therefore request a near-zero
+    tint alpha — 0x01, not 0x00, because a fully transparent gradient
+    disables the Acrylic material on some builds — leaving the QSS fill
+    as the single tint source on every platform. TRACKERKEEPER_WIN_POPUP_BLUR_ALPHA
+    tunes it live for eyeball calibration."""
+    base = _ACRYLIC_TINT_DARK if dark else _ACRYLIC_TINT_LIGHT
+    if elevated:
+        try:
+            a = int(os.environ.get("TRACKERKEEPER_WIN_POPUP_BLUR_ALPHA", "1"))
+        except ValueError:
+            a = 1
+        return (max(1, min(255, a)) << 24) | (base & 0x00FFFFFF)
+    try:
+        a = int(os.environ.get("TRACKERKEEPER_WIN_BLUR_ALPHA", ""))
+    except ValueError:
+        return base
+    return (max(0, min(255, a)) << 24) | (base & 0x00FFFFFF)
+
+
+def apply_acrylic(hwnd: int, dark: bool, enabled: bool = True, elevated: bool = False) -> bool:
+    """Apply (or remove) the legacy Acrylic blur-behind accent policy — the
+    qframelesswindow recipe for genuine frosted glass. Best-effort; returns
+    whether the accent-policy call was issued successfully (propagated from
+    ``_set_wca``), mirroring the Mica branch's HRESULT check."""
+    accent = _ACCENT_POLICY()
+    if enabled:
+        accent.AccentState = _ACCENT_ENABLE_ACRYLICBLURBEHIND
+        accent.AccentFlags = _ACCENT_DRAW_ALL_BORDERS
+        accent.GradientColor = _acrylic_tint(dark, elevated=elevated)
+    else:
+        accent.AccentState = _ACCENT_DISABLED
+    return _set_wca(hwnd, _WCA_ACCENT_POLICY, accent)
+
+
+def apply(
+    widget,
+    enabled: bool,
+    corner_radius: int = 0,
+    dark: bool = True,
+    elevated: bool = False,
+) -> bool:
+    """Apply (``enabled``) or remove (``not enabled``) the Windows backdrop
+    behind ``widget`` — real Acrylic blur by default, the Mica system backdrop
+    when ``TRACKERKEEPER_NO_WIN_BLUR`` is set. ``corner_radius > 0`` additionally asks DWM to round
+    the window's corners — needed for the frameless, self-painted surfaces
+    (mini player + dialogs, and the main window once it goes frameless on
+    Windows), because Windows does NOT clip a frameless translucent HWND to
+    the painted rounded body, so without this the corners read square. The
+    pixel radius itself is DWM's choice (Win11's standard ~8 px), so the value
+    only acts as a "round me" flag; it's harmless on the native-framed window
+    (already rounded).
+
+    Must be called AFTER ``show()`` (``winId()`` needs a real HWND, and Qt
+    6.8+ re-runs native window setup that would clobber a constructor-time
+    call). Returns True if the backdrop request was accepted (HRESULT S_OK),
+    False on any non-Windows / pre-22000 / not-yet-shown / error case. Never
+    raises — blur is progressive enhancement."""
+    if not IS_WINDOWS:
+        return False
+    build = _build()
+    if build < _MIN_BUILD_MICA:
+        return False
+    try:
+        # windowHandle() check BEFORE winId(): winId() force-creates the
+        # native window on a never-shown widget, so the bare int() call both
+        # violated the "returns False when not-yet-shown" contract above and
+        # triggered exactly the premature native-window setup the Qt 6.8 note
+        # warns about. Mirrors the KWin backend's guard.
+        if widget.windowHandle() is None:
+            return False  # never shown — no platform window to blur
+        hwnd = int(widget.winId())
+        if not hwnd:
+            return False  # no native window yet
+        # Frameless surfaces self-paint a rounded body but Windows leaves the
+        # HWND square; ask DWM to round it (Win11 22000+, the build we already
+        # gated on). Runs whether or not Mica is enabled so a Solid-theme
+        # frameless dialog still gets rounded corners.
+        if corner_radius > 0:
+            _set_attr(hwnd, _DWMWA_WINDOW_CORNER_PREFERENCE, _DWMWCP_ROUND)
+        # Match the titlebar AND the Mica backdrop variant to the theme:
+        # immersive-dark on for dark themes (dark Mica), off for light
+        # themes (light, wallpaper-tinted Mica). Follows the OS live when
+        # the theme_mode is "auto".
+        _set_attr(hwnd, _DWMWA_USE_IMMERSIVE_DARK_MODE, 1 if dark else 0)
+        # Real frosted-glass blur — the DEFAULT on Windows (TRACKERKEEPER_NO_WIN_BLUR
+        # opts out to the Mica system-backdrop below). Drive the legacy
+        # Acrylic accent policy instead of Mica (Mica is an opaque
+        # once-sampled tint, not a live blur). The main window pairs this with
+        # a NON-layered window (trackerkeeper/app.py `_win_blur` drops
+        # WA_TranslucentBackground); the accent path also blurs the layered
+        # mini player / dialogs. enabled=False (a Solid theme) removes it.
+        if not os.environ.get("TRACKERKEEPER_NO_WIN_BLUR"):
+            # Propagate the accent-policy result instead of an unconditional
+            # True — symmetric with the Mica branch below (`_set_attr(...) == 0`)
+            # so apply()'s "issued" return is honest on BOTH paths. Safe to
+            # change: no caller reads this return (it's best-effort by contract,
+            # see blur/__init__.py), and the visible blur is unaffected.
+            return apply_acrylic(hwnd, dark, enabled, elevated=elevated)
+        _extend_frame(hwnd)
+        if build >= _MIN_BUILD_DOCUMENTED:
+            attr = _DWMWA_SYSTEMBACKDROP_TYPE
+            value = _DWMSBT_MAINWINDOW if enabled else _DWMSBT_NONE
+        else:
+            attr = _DWMWA_MICA_EFFECT  # legacy: 1 = Mica, 0 = off
+            value = 1 if enabled else 0
+        return _set_attr(hwnd, attr, value) == 0
+    except Exception:
+        return False
+
+
+def probe():
+    """Verified BlurStatus for Windows. Mica availability is a build-version
+    fact (no window needed): Windows 11 22000+ with Transparency effects on
+    gets a real backdrop → ACTIVE (translucent body rides Mica). Pre-22000,
+    or transparency disabled, → UNSUPPORTED (near-opaque body, never
+    see-through). See trackerkeeper/blur/__init__.py."""
+    from trackerkeeper.blur import BlurStatus
+
+    if not IS_WINDOWS or _build() < _MIN_BUILD_MICA:
+        return BlurStatus.UNSUPPORTED
+    if not _transparency_enabled():
+        return BlurStatus.UNSUPPORTED
+    return BlurStatus.ACTIVE
+
+
+def reason(status) -> str:
+    """Human-readable explanation of the Windows blur status — for the boot
+    log + Settings hint. Mirrors the other backends' ``reason(status)``; reads
+    the build + transparency facts so the message is actionable. Never raises."""
+    from trackerkeeper.blur import BlurStatus
+
+    if not IS_WINDOWS:
+        return "not running on Windows"
+    if _build() < _MIN_BUILD_MICA:
+        return "Windows 10 has no Mica backdrop — using a near-opaque body"
+    if not _transparency_enabled():
+        return (
+            "Windows 'Transparency effects' is off (Settings → Personalization "
+            "→ Colors) — using a near-opaque body"
+        )
+    if status == BlurStatus.ACTIVE:
+        # Default is the real Acrylic accent blur; TRACKERKEEPER_NO_WIN_BLUR falls back
+        # to the (flat) Mica system-backdrop.
+        return (
+            "Windows 11 Mica backdrop active"
+            if os.environ.get("TRACKERKEEPER_NO_WIN_BLUR")
+            else "Windows 11 Acrylic blur active"
+        )
+    return "blur unavailable — using a near-opaque body"