shell: document why UseQApplication is required

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

config/Icons.qml

@@ -11,7 +11,8 @@ Singleton {
     readonly property string thermo:     String.fromCharCode(0xf2c9) // thermometer-half
     readonly property string disk:       String.fromCharCode(0xf0a0) // hdd-o
     readonly property string wifi:       String.fromCharCode(0xf1eb) // wifi
-    readonly property string ethernet:   String.fromCharCode(0xf6ff) // network-wired
+    readonly property string ethernet:   String.fromCodePoint(0xf0200) // md-ethernet (FA5 network-wired 0xf6ff is absent from the bundled Nerd Fonts)
+    readonly property string netOff:     String.fromCodePoint(0xf05aa) // md-wifi-off (shown when there is no active interface)
     readonly property string down:       String.fromCharCode(0xf063) // arrow-down
     readonly property string up:         String.fromCharCode(0xf062) // arrow-up
     readonly property string clock:      String.fromCharCode(0xf017) // clock-o

services/SysStats.qml

@@ -52,6 +52,12 @@ Singleton {
     // poll interval in seconds
     readonly property int interval: 1
 
+    // cpuFreq comes from /proc/cpuinfo, which the kernel regenerates in full on
+    // every read (cost grows with core count) — the priciest per-tick read here.
+    // Frequency on a status bar doesn't need 1 Hz precision, so only refresh it
+    // every Nth tick instead of on the CPU%/mem hot path.
+    readonly property int freqEveryTicks: 3
+
     // discovered sysfs paths (filled once by discover.sh)
     property string tempPath: ""
     property string batPath: ""
@@ -271,15 +277,17 @@ Singleton {
     }
 
     function _tickOnce() {
+        const doFreq = root._tick % root.freqEveryTicks === 0;
+
         statView.reload();
-        cpuInfoView.reload();
+        if (doFreq) cpuInfoView.reload();
         memView.reload();
         routeView.reload();
         if (root.tempPath) tempView.reload();
         if (root.batPath) { batCapView.reload(); batStatusView.reload(); }
 
         _parseCpu();
-        _parseFreq();
+        if (doFreq) _parseFreq();
         _parseMem();
         _parseTemp();
         _parseBattery();

shell.qml

@@ -1,4 +1,7 @@
 //@ pragma UseQApplication
+// Required: Quickshell renders the system-tray context menu (right-click in
+// Tray.qml -> item.display()) via QtWidgets' QMenu. Dropping this loads the
+// lighter QGuiApplication but breaks tray menus. Verified 2026-06-08.
 
 import Quickshell
 import "widgets"

widgets/Bar.qml

@@ -29,7 +29,20 @@ PanelWindow {
         left: true
         right: true
     }
-    implicitHeight: Theme.barHeight
+
+    // Wrap onto two rows when a single row can't hold everything (portrait
+    // outputs). Needed width is computed from implicit sizes, which don't
+    // depend on which row anything sits in, so this can't bind-loop.
+    readonly property real neededWidth:
+        (Theme.gap + 2) * 2                 // outer margins
+        + workspaces.implicitWidth
+        + Theme.gap * 4                     // breathing room between clusters
+        + metricsRow.implicitWidth
+        + Theme.gap
+        + endRow.implicitWidth
+    readonly property bool twoRows: width > 0 && neededWidth > width
+
+    implicitHeight: twoRows ? Theme.barHeight * 2 : Theme.barHeight
 
     // background strip
     Rectangle {
@@ -37,19 +50,35 @@ PanelWindow {
         color: Theme.barColor
     }
 
-    // left: workspaces
+    // row 1 left: workspaces
     Workspaces {
+        id: workspaces
         anchors.left: parent.left
-        anchors.verticalCenter: parent.verticalCenter
         anchors.leftMargin: Theme.gap + 2
+        y: (Theme.barHeight - height) / 2
         screen: panel.modelData
     }
 
-    // right: battery, system metrics, volume, clock, tray
+    // row 1 right: clock, tray
     RowLayout {
+        id: endRow
         anchors.right: parent.right
-        anchors.verticalCenter: parent.verticalCenter
         anchors.rightMargin: Theme.gap + 2
+        y: (Theme.barHeight - height) / 2
+        spacing: Theme.gap
+
+        Clock {}
+        Tray { panelWindow: panel }
+    }
+
+    // metrics: left of the clock in one-row mode, own second row when narrow
+    RowLayout {
+        id: metricsRow
+        anchors.right: panel.twoRows ? parent.right : endRow.left
+        anchors.rightMargin: panel.twoRows ? Theme.gap + 2 : Theme.gap
+        y: panel.twoRows
+            ? Theme.barHeight + (Theme.barHeight - height) / 2
+            : (Theme.barHeight - height) / 2
         spacing: Theme.gap
 
         Battery {}
@@ -59,7 +88,5 @@ PanelWindow {
         Disk {}
         Network {}
         Volume {}
-        Clock {}
-        Tray { panelWindow: panel }
     }
 }

widgets/Network.qml

@@ -20,10 +20,11 @@ Item {
         spacing: Theme.spacing
 
         Text {
-            text: SysStats.iface.startsWith("wl") ? Icons.wifi : Icons.ethernet
+            text: SysStats.iface === "" ? Icons.netOff
+                : SysStats.iface.startsWith("wl") ? Icons.wifi : Icons.ethernet
             font.family: Theme.monoFont
             font.pixelSize: Theme.fontSize + 1
-            color: Theme.sky
+            color: SysStats.iface === "" ? Theme.overlay : Theme.sky
             Layout.alignment: Qt.AlignVCenter
         }
 
@@ -127,10 +128,11 @@ Item {
                     spacing: Theme.spacing
 
                     Text {
-                        text: SysStats.iface.startsWith("wl") ? Icons.wifi : Icons.ethernet
+                        text: SysStats.iface === "" ? Icons.netOff
+                            : SysStats.iface.startsWith("wl") ? Icons.wifi : Icons.ethernet
                         font.family: Theme.monoFont
                         font.pixelSize: Theme.fontSize + 1
-                        color: Theme.sky
+                        color: SysStats.iface === "" ? Theme.overlay : Theme.sky
                     }
                     Text {
                         text: "Network by process"

widgets/Volume.qml

@@ -17,11 +17,20 @@ MouseArea {
     cursorShape: Qt.PointingHandCursor
     acceptedButtons: Qt.LeftButton
 
+    // accumulate raw wheel deltas so high-res / inertial scrolling doesn't
+    // fire a full step per micro-event; one notch (120 units) == one step
+    property real _wheelAccum: 0
+    readonly property real _wheelStep: 0.02
+
     onClicked: { if (audio) audio.muted = !audio.muted; }
     onWheel: wheel => {
         if (!audio) return;
+        _wheelAccum += wheel.angleDelta.y;
+        const notches = Math.trunc(_wheelAccum / 120);
+        if (notches === 0) return;
+        _wheelAccum -= notches * 120;
         audio.volume = Math.max(0, Math.min(1,
-            audio.volume + (wheel.angleDelta.y > 0 ? 0.05 : -0.05)));
+            audio.volume + notches * _wheelStep));
     }
 
     // keep the sink's audio properties live