refactor(Xray): Update Xray & standalone to frame transitions

- Fix dbar autohide with Xray options that could have blocked bar area content
- Fixes #2729

quickshell/Modules/DankBar/BarCanvas.qml

@@ -10,7 +10,7 @@ Item {
     required property var axis
     required property var barConfig
 
-    readonly property bool frameShapesBar: SettingsData.frameEnabled && barWindow.usesFrameBarChrome
+    readonly property bool frameShapesBar: FrameTransitionState.effectiveFrameEnabled && barWindow.usesFrameBarChrome
 
     visible: !frameShapesBar
 

quickshell/Modules/DankBar/DankBarWindow.qml

@@ -73,7 +73,6 @@ PanelWindow {
 
         let section = "center";
         if (clockButtonRef && clockButtonRef.visualContent && dankDashPopoutLoader.item.setTriggerPosition) {
-            // Calculate barPosition from axis.edge
             const barPosition = axis?.edge === "left" ? 2 : (axis?.edge === "right" ? 3 : (axis?.edge === "top" ? 0 : 1));
             section = clockButtonRef.section || "center";
 
@@ -148,7 +147,8 @@ PanelWindow {
             _blurRebuildTimer.restart();
         }
         function onUsesFrameBarChromeChanged() {
-            _blurRebuildTimer.restart();
+            // Rebuild immediately so the bar region never overlaps FrameWindow's during chrome handoff
+            barBlur.rebuild();
         }
         function onBarRevealedChanged() {
             _blurRebuildTimer.restart();
@@ -179,17 +179,11 @@ PanelWindow {
             teardown();
             if (!BlurService.enabled || !BlurService.available)
                 return;
-            // When the bar is hidden (auto-hide, or config not visible) keep the blur
-            // region empty rather than sliding it off-surface. Some compositors (Hyprland)
-            // gate blur on a non-empty region and then blur the whole surface box when the
-            // clip degenerates to empty, leaving the bar strip blurred while the bar is
-            // hidden (issue #2656). A null region disables the effect cleanly.
+            // Hidden bar keeps a null region — an empty clip makes Hyprland blur the whole surface box
             if (!barWindow.barRevealed)
                 return;
-            // In frame mode, FrameWindow owns the blur region for the entire screen edge
-            // (including the bar area). The bar must not set its own competing blur region
-            // so that frameBlurEnabled acts as the single control for all blur in frame mode.
-            if (SettingsData.frameEnabled && barWindow.usesFrameBarChrome)
+            // FrameWindow owns the blur region for the whole edge while the bar wears frame chrome
+            if (FrameTransitionState.effectiveFrameEnabled && barWindow.usesFrameBarChrome)
                 return;
 
             const widgets = barWindow._blurWidgetItems.filter(w => w && w.visible && w.width > 0 && w.height > 0);
@@ -245,8 +239,8 @@ PanelWindow {
         }
 
         Connections {
-            target: SettingsData
-            function onFrameEnabledChanged() {
+            target: FrameTransitionState
+            function onEffectiveFrameEnabledChanged() {
                 barBlur.rebuild();
             }
         }
@@ -299,7 +293,7 @@ PanelWindow {
     readonly property color _surfaceContainer: Theme.surfaceContainer
     readonly property string _barId: barConfig?.id ?? "default"
     property real _backgroundAlpha: barConfig?.transparency ?? 1.0
-    readonly property color _bgColor: (SettingsData.frameEnabled && usesFrameBarChrome) ? Theme.withAlpha(SettingsData.effectiveFrameColor, SettingsData.frameOpacity) : Theme.withAlpha(_surfaceContainer, _backgroundAlpha)
+    readonly property color _bgColor: (FrameTransitionState.effectiveFrameEnabled && usesFrameBarChrome) ? Theme.withAlpha(SettingsData.effectiveFrameColor, SettingsData.frameOpacity) : Theme.withAlpha(_surfaceContainer, _backgroundAlpha)
 
     function _updateBackgroundAlpha() {
         const live = SettingsData.barConfigs.find(c => c.id === _barId);
@@ -331,9 +325,8 @@ PanelWindow {
         return Theme.snap(Theme.elevationRenderPadding(Theme.elevationLevel2, "top", 4, 8, 16), _dpr);
     }
 
-    // Flatten/spacing collapse for maximized windows is only for frame-integrated layout.
-    // When the bar draws its own pill, keep rounded corners and spacing like the dock.
-    readonly property bool flattenForMaximizedWindow: !SettingsData.frameEnabled || usesFrameBarChrome
+    // Flatten/spacing collapse for maximized windows only applies to frame-integrated layout
+    readonly property bool flattenForMaximizedWindow: !FrameTransitionState.effectiveFrameEnabled || usesFrameBarChrome
 
     property bool hasMaximizedToplevel: false
     property bool shouldHideForWindows: false
@@ -455,7 +448,7 @@ PanelWindow {
         shouldHideForWindows = filtered.length > 0;
     }
 
-    property real effectiveSpacing: (SettingsData.frameEnabled && usesFrameBarChrome) ? 0 : ((flattenForMaximizedWindow && hasMaximizedToplevel) ? 0 : (barConfig?.spacing ?? 4))
+    property real effectiveSpacing: (FrameTransitionState.effectiveFrameEnabled && usesFrameBarChrome) ? 0 : ((flattenForMaximizedWindow && hasMaximizedToplevel) ? 0 : (barConfig?.spacing ?? 4))
 
     Behavior on effectiveSpacing {
         enabled: barWindow.visible
@@ -466,8 +459,8 @@ PanelWindow {
     }
 
     readonly property int notificationCount: NotificationService.notifications.length
-    readonly property real effectiveBarThickness: (SettingsData.frameEnabled && usesFrameBarChrome) ? SettingsData.frameBarSize : Theme.snap(Math.max(barWindow.widgetThickness + (barConfig?.innerPadding ?? 4) + 4, Theme.barHeight - 4 - (8 - (barConfig?.innerPadding ?? 4))), _dpr)
-    readonly property bool effectiveOpenOnOverview: SettingsData.frameEnabled ? SettingsData.frameShowOnOverview : (barConfig?.openOnOverview ?? false)
+    readonly property real effectiveBarThickness: (FrameTransitionState.effectiveFrameEnabled && usesFrameBarChrome) ? SettingsData.frameBarSize : Theme.snap(Math.max(barWindow.widgetThickness + (barConfig?.innerPadding ?? 4) + 4, Theme.barHeight - 4 - (8 - (barConfig?.innerPadding ?? 4))), _dpr)
+    readonly property bool effectiveOpenOnOverview: FrameTransitionState.effectiveFrameEnabled ? SettingsData.frameShowOnOverview : (barConfig?.openOnOverview ?? false)
     readonly property real widgetThickness: Theme.snap(Math.max(20, 26 + (barConfig?.innerPadding ?? 4) * 0.6), _dpr)
 
     readonly property bool hasAdjacentTopBar: {
@@ -665,7 +658,7 @@ PanelWindow {
     anchors.left: !isVertical ? true : (barPos === SettingsData.Position.Left)
     anchors.right: !isVertical ? true : (barPos === SettingsData.Position.Right)
 
-    readonly property bool reserveExclusiveWhenAutoHidden: SettingsData.frameEnabled && usesFrameBarChrome && !!barWindow.screen && SettingsData.isScreenInPreferences(barWindow.screen, SettingsData.frameScreenPreferences)
+    readonly property bool reserveExclusiveWhenAutoHidden: FrameTransitionState.effectiveFrameEnabled && usesFrameBarChrome && !!barWindow.screen && SettingsData.isScreenInPreferences(barWindow.screen, SettingsData.frameScreenPreferences)
 
     exclusiveZone: (!(barConfig?.visible ?? true) || (topBarCore.autoHide && !barWindow.reserveExclusiveWhenAutoHidden)) ? -1 : (barWindow.effectiveBarThickness + effectiveSpacing + (usesFrameBarChrome ? 0 : (barConfig?.bottomGap ?? 0)))
 
@@ -1111,7 +1104,7 @@ PanelWindow {
                         rightWidgetsModel: barWindow.rightWidgetsModel
                     }
 
-                    // Passive HoverHandler to track cursor without intercepting clicks or scroll events.
+                    // Passive: tracks cursor without intercepting clicks or scroll
                     HoverHandler {
                         id: hoverPopoutHandler
                         enabled: (barConfig?.hoverPopouts ?? false) && !barWindow.clickThroughEnabled

quickshell/Modules/Dock/Dock.qml

@@ -717,7 +717,7 @@ Variants {
 
                         Rectangle {
                             anchors.fill: parent
-                            visible: !usesConnectedFrameChrome && (!SettingsData.connectedFrameModeActive || dock.reveal)
+                            visible: !usesConnectedFrameChrome && (!FrameTransitionState.effectiveConnectedFrameModeActive || dock.reveal)
                             color: dock.surfaceColor
                             topLeftRadius: dock.surfaceTopLeftRadius
                             topRightRadius: dock.surfaceTopRightRadius
@@ -727,7 +727,7 @@ Variants {
 
                         Rectangle {
                             anchors.fill: parent
-                            visible: !usesConnectedFrameChrome && (!SettingsData.connectedFrameModeActive || dock.reveal)
+                            visible: !usesConnectedFrameChrome && (!FrameTransitionState.effectiveConnectedFrameModeActive || dock.reveal)
                             color: "transparent"
                             topLeftRadius: dock.surfaceTopLeftRadius
                             topRightRadius: dock.surfaceTopRightRadius
@@ -747,7 +747,7 @@ Variants {
 
                     Item {
                         id: dockConnectedChrome
-                        visible: Theme.isConnectedEffect && dock.reveal && !SettingsData.connectedFrameModeActive
+                        visible: Theme.isConnectedEffect && dock.reveal && !FrameTransitionState.effectiveConnectedFrameModeActive
                         readonly property real extraLeft: dock.isVertical ? 0 : Theme.connectedCornerRadius
                         readonly property real extraTop: dock.isVertical ? Theme.connectedCornerRadius : 0
                         readonly property real bodyRadius: dock.surfaceRadius

quickshell/Modules/Frame/Frame.qml

@@ -14,7 +14,8 @@ Variants {
 
         required property var modelData
 
-        active: SettingsData.frameEnabled && SettingsData.isScreenInPreferences(instanceLoader.modelData, SettingsData.frameScreenPreferences)
+        // Live-or-latched: instances build early on enable, survive until ack on disable
+        active: (SettingsData.frameEnabled || FrameTransitionState.effectiveFrameEnabled) && SettingsData.isScreenInPreferences(instanceLoader.modelData, SettingsData.frameScreenPreferences)
         asynchronous: false
 
         sourceComponent: FrameInstance {

quickshell/Modules/Frame/FrameWindow.qml

@@ -40,7 +40,7 @@ PanelWindow {
     }
 
     readonly property real _dpr: CompositorService.getScreenScale(win.targetScreen)
-    readonly property bool _frameActive: SettingsData.frameEnabled && SettingsData.isScreenInPreferences(win.targetScreen, SettingsData.frameScreenPreferences)
+    readonly property bool _frameActive: FrameTransitionState.effectiveFrameEnabled && SettingsData.isScreenInPreferences(win.targetScreen, SettingsData.frameScreenPreferences)
     readonly property int _windowRegionWidth: win._regionInt(win.width)
     readonly property int _windowRegionHeight: win._regionInt(win.height)
     readonly property string _screenName: win.targetScreen ? win.targetScreen.name : ""

quickshell/Modules/Notifications/Center/NotificationCard.qml

@@ -40,7 +40,7 @@ Rectangle {
     readonly property real actionButtonHeight: compactMode ? 20 : 24
     readonly property real collapsedContentHeight: Math.max(iconSize, Theme.fontSizeSmall * 1.2 + Theme.fontSizeMedium * 1.2 + Theme.fontSizeSmall * 1.2 * (compactMode ? 1 : 2))
     readonly property real baseCardHeight: cardPadding * 2 + collapsedContentHeight + actionButtonHeight + contentSpacing
-    readonly property bool connectedFrameMode: SettingsData.connectedFrameModeActive
+    readonly property bool connectedFrameMode: FrameTransitionState.effectiveConnectedFrameModeActive
 
     width: parent ? parent.width : 400
     height: expanded ? (expandedContent.height + cardPadding * 2) : (baseCardHeight + collapsedContent.extraHeight)

quickshell/Modules/Settings/CompositorLayoutTab.qml

@@ -323,10 +323,12 @@ Item {
                 SettingsToggleRow {
                     // Hidden in Frame Connected mode, where it has no target
                     visible: !(SettingsData.frameEnabled && SettingsData.frameMode === "connected")
+                    enabled: SettingsData.frameEnabled || SettingsData.standaloneBarXrayAvailable
+                    opacity: enabled ? 1 : 0.5
                     tags: ["niri", "xray", "bar", "frame", "performance"]
                     settingKey: "niriLayoutBarXrayEnabled"
                     text: SettingsData.frameEnabled ? I18n.tr("Frame Xray") : I18n.tr("Dank Bar Xray")
-                    description: SettingsData.niriLayoutBarXrayEnabled ? (SettingsData.frameEnabled ? I18n.tr("Xray on makes the Frame's border visible through to the wallpaper; more efficient") : I18n.tr("Xray on makes the Dank Bar visible through to the wallpaper; more efficient")) : (SettingsData.frameEnabled ? I18n.tr("Xray off shows the real background beneath the Frame's border") : I18n.tr("Xray off shows the real background beneath the Dank Bar"))
+                    description: !SettingsData.frameEnabled && !SettingsData.standaloneBarXrayAvailable ? I18n.tr("Unavailable while using Auto Hide as Xray would reveal the wallpaper through windows") : (SettingsData.niriLayoutBarXrayEnabled ? (SettingsData.frameEnabled ? I18n.tr("Xray on makes the Frame's border visible through to the wallpaper; more efficient") : I18n.tr("Xray on makes the Dank Bar visible through to the wallpaper; more efficient")) : (SettingsData.frameEnabled ? I18n.tr("Xray off shows the real background beneath the Frame's border") : I18n.tr("Xray off shows the real background beneath the Dank Bar")))
                     checked: SettingsData.niriLayoutBarXrayEnabled
                     onToggled: checked => SettingsData.set("niriLayoutBarXrayEnabled", checked)
                 }
@@ -449,10 +451,12 @@ Item {
                 SettingsToggleRow {
                     // Hidden in Frame Connected mode, where it has no target
                     visible: !(SettingsData.frameEnabled && SettingsData.frameMode === "connected")
+                    enabled: SettingsData.frameEnabled || SettingsData.standaloneBarXrayAvailable
+                    opacity: enabled ? 1 : 0.5
                     tags: ["hyprland", "xray", "bar", "frame", "performance"]
                     settingKey: "hyprlandLayoutBarXrayEnabled"
                     text: SettingsData.frameEnabled ? I18n.tr("Frame Xray") : I18n.tr("Dank Bar Xray")
-                    description: SettingsData.hyprlandLayoutBarXrayEnabled ? (SettingsData.frameEnabled ? I18n.tr("Xray on makes the Frame's border visible through to the wallpaper; more efficient") : I18n.tr("Xray on makes the Dank Bar visible through to the wallpaper; more efficient")) : (SettingsData.frameEnabled ? I18n.tr("Xray off shows the real background beneath the Frame's border") : I18n.tr("Xray off shows the real background beneath the Dank Bar"))
+                    description: !SettingsData.frameEnabled && !SettingsData.standaloneBarXrayAvailable ? I18n.tr("Unavailable while an enabled Dank Bar uses Auto Hide because Xray would reveal the wallpaper through windows") : (SettingsData.hyprlandLayoutBarXrayEnabled ? (SettingsData.frameEnabled ? I18n.tr("Xray on makes the Frame's border visible through to the wallpaper; more efficient") : I18n.tr("Xray on makes the Dank Bar visible through to the wallpaper; more efficient")) : (SettingsData.frameEnabled ? I18n.tr("Xray off shows the real background beneath the Frame's border") : I18n.tr("Xray off shows the real background beneath the Dank Bar")))
                     checked: SettingsData.hyprlandLayoutBarXrayEnabled
                     onToggled: checked => SettingsData.set("hyprlandLayoutBarXrayEnabled", checked)
                 }