fix(hyprland): cap output volume at 100 percent

Route the volume and brightness keys through swayosd-client, which raises
a transient on-screen popup that auto-hides a moment after the last press,
so the level is visible while adjusting without a permanent widget. A new
osd module runs the server for the graphical session and makes the
backlight node group-writable so it dims without root.

Supersedes the plain brightnessctl binds, whose control swayosd bundles.

modules/desktop/desktop.nix

@@ -25,5 +25,6 @@ in
     modules.desktop.theming.enable = lib.mkDefault true;
     modules.desktop.waybar.enable = lib.mkDefault true;
     modules.desktop.audio.enable = lib.mkDefault true;
+    modules.desktop.osd.enable = lib.mkDefault true;
   };
 }

modules/desktop/hyprland/hyprland.nix

@@ -141,15 +141,19 @@ in
         ]
         ++ workspaceBinds;
 
-        # Volume keys repeat while held, capped at 150 percent.
+        # Volume and brightness keys repeat while held, each raising a popup
+        # through the OSD client. Volume is capped at 100 percent; the client
+        # floors brightness so a full hold cannot black the screen out.
         binde = [
-          ", XF86AudioRaiseVolume, exec, ${pkgs.wireplumber}/bin/wpctl set-volume -l 1.5 @DEFAULT_AUDIO_SINK@ 5%+"
+          ", XF86AudioRaiseVolume, exec, ${pkgs.swayosd}/bin/swayosd-client --output-volume raise --max-volume 100"
-          ", XF86AudioLowerVolume, exec, ${pkgs.wireplumber}/bin/wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-"
+          ", XF86AudioLowerVolume, exec, ${pkgs.swayosd}/bin/swayosd-client --output-volume lower"
+          ", XF86MonBrightnessUp, exec, ${pkgs.swayosd}/bin/swayosd-client --brightness raise"
+          ", XF86MonBrightnessDown, exec, ${pkgs.swayosd}/bin/swayosd-client --brightness lower"
         ];
 
         # Mute and media transport still fire while the session is locked.
         bindl = [
-          ", XF86AudioMute, exec, ${pkgs.wireplumber}/bin/wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle"
+          ", XF86AudioMute, exec, ${pkgs.swayosd}/bin/swayosd-client --output-volume mute-toggle"
           ", XF86AudioPlay, exec, ${pkgs.playerctl}/bin/playerctl play-pause"
           ", XF86AudioNext, exec, ${pkgs.playerctl}/bin/playerctl next"
           ", XF86AudioPrev, exec, ${pkgs.playerctl}/bin/playerctl previous"

modules/desktop/osd.nix

@@ -0,0 +1,40 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+# SwayOSD: a transient on-screen popup for volume and brightness changes.
+let
+  cfg = config.modules.desktop.osd;
+  user = config.user.name;
+in
+{
+  options.modules.desktop.osd.enable = lib.mkEnableOption "the SwayOSD volume and brightness popup";
+
+  config = lib.mkIf cfg.enable {
+    environment.systemPackages = [ pkgs.swayosd ];
+
+    # The udev rule chgrps each backlight's brightness node to `video` and adds
+    # group write, so the server dims the panel without root. Membership below
+    # grants the running session that access.
+    services.udev.packages = [ pkgs.swayosd ];
+    users.users.${user}.extraGroups = [ "video" ];
+
+    # The server draws the popups, so it runs for the whole graphical session.
+    # Bound to the target uwsm activates, like the bar, rather than an
+    # exec-once in the compositor config.
+    home-manager.users.${user}.systemd.user.services.swayosd = {
+      Unit = {
+        Description = "SwayOSD on-screen display server";
+        PartOf = [ "graphical-session.target" ];
+        After = [ "graphical-session.target" ];
+      };
+      Service = {
+        ExecStart = "${pkgs.swayosd}/bin/swayosd-server";
+        Restart = "on-failure";
+      };
+      Install.WantedBy = [ "graphical-session.target" ];
+    };
+  };
+}