Give Sound the whole story, and keep the buttons inside the card

Claude-Session: https://claude.ai/code/session_01Ms2FbjQy31TVf3CEvQhGM8

config/dot/quickshell/scripts/panama-osd

@@ -3,6 +3,54 @@
 set -u
 
 readonly PANAMA_OSD_SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+readonly PANAMA_OSD_BLIP_DEFAULT="/usr/share/sounds/freedesktop/stereo/audio-volume-change.oga"
+
+# ── Panama's own preferences ────────────────────────────────────────────────
+#
+# These run as keybinds, so the shell may not be up and there is no IPC to ask.
+# settings.json is read straight off disk instead, and every failure -- no file
+# on a fresh install, a file written before the key existed, a file that is not
+# JSON at all -- means the schema default rather than a broken volume key.
+settings_file() {
+    printf '%s/panama/settings.json\n' "${XDG_CONFIG_HOME:-$HOME/.config}"
+}
+
+setting_bool() {
+    local key="$1" fallback="$2" file value
+    file="$(settings_file)"
+    [[ -r $file ]] || { printf '%s\n' "$fallback"; return 0; }
+    command -v jq >/dev/null 2>&1 || { printf '%s\n' "$fallback"; return 0; }
+    value="$(jq -r --arg key "$key" '
+        if type == "object" and (.[$key] | type) == "boolean" then .[$key] else empty end
+    ' "$file" 2>/dev/null)" || value=""
+    [[ $value == true || $value == false ]] || value="$fallback"
+    printf '%s\n' "$value"
+}
+
+# wpctl clamps to 1.0 by default, and it clamps the *result* -- so the ceiling
+# has to be passed on the way down as well. Without it, stepping down from 130%
+# would snap to 100% instead of 124%, which reads as the slider jumping on its
+# own. The microphone never gets this: gain past 100% on a capture device buys
+# noise, not signal, and the Sound page's input slider stays 0-100 to match.
+volume_limit() {
+    if [[ $(setting_bool overAmplification false) == true ]]; then
+        printf '1.5\n'
+    else
+        printf '1\n'
+    fi
+}
+
+# The click that says the volume moved. Backgrounded and never waited on: it is
+# feedback about something that has already happened, so it must not sit between
+# the key press and the OSD. A distribution without the freedesktop sound theme
+# has no file to play, which is a silent desktop rather than a broken key.
+play_blip() {
+    local sound="${PANAMA_OSD_BLIP_SOUND:-$PANAMA_OSD_BLIP_DEFAULT}"
+    [[ $(setting_bool volumeChangeBlip true) == true ]] || return 0
+    [[ -f $sound ]] || return 0
+    pw-play "$sound" >/dev/null 2>&1 &
+    disown 2>/dev/null || true
+}
 
 strict_delivery() {
     [[ ${PANAMA_OSD_STRICT:-false} == true || ${PANAMA_OSD_STRICT:-false} == 1 ]]
@@ -48,13 +96,15 @@ show_volume() {
 }
 
 adjust_volume() {
-    local action="${1:-}" step="${2:-6}" target="@DEFAULT_AUDIO_SINK@"
+    local action="${1:-}" step="${2:-6}" target="@DEFAULT_AUDIO_SINK@" limit
+    limit="$(volume_limit)"
     case "$action" in
-        up) wpctl set-volume -l 1 "$target" "${step}%+" || return ;;
-        down) wpctl set-volume "$target" "${step}%-" || return ;;
+        up) wpctl set-volume -l "$limit" "$target" "${step}%+" || return ;;
+        down) wpctl set-volume -l "$limit" "$target" "${step}%-" || return ;;
         toggle) wpctl set-mute "$target" toggle || return ;;
         *) printf 'Usage: panama-osd volume up|down|toggle [step]\n' >&2; return 2 ;;
     esac
+    play_blip
     show_volume "$target" volume
 }
 
@@ -62,7 +112,7 @@ adjust_microphone() {
     local action="${1:-}" step="${2:-6}" target="@DEFAULT_AUDIO_SOURCE@"
     case "$action" in
         up) wpctl set-volume -l 1 "$target" "${step}%+" || return ;;
-        down) wpctl set-volume "$target" "${step}%-" || return ;;
+        down) wpctl set-volume -l 1 "$target" "${step}%-" || return ;;
         toggle) wpctl set-mute "$target" toggle || return ;;
         *) printf 'Usage: panama-osd microphone up|down|toggle [step]\n' >&2; return 2 ;;
     esac