feat: production-ready Linux & macOS support

- Add `linux` (dbus-python, PyGObject, python-xlib) and `macos`
  (pyobjc) extras to pyproject.toml with sys_platform markers; move
  cross-platform screen-brightness-control + monitorcontrol to base deps.
- build-dist-linux.sh: install `.[linux]`, pkg-config pre-flight for
  dbus-1/glib-2.0, emit a systemd unit with DBUS_SESSION_BUS_ADDRESS +
  XDG_RUNTIME_DIR + ReadWritePaths for ~/.config and ~/.cache so MPRIS
  works and audit-log / thumbnail writes aren't blocked by ProtectHome.
- New build-dist-macos.sh + per-user LaunchAgent installer producing
  MediaServer-vX.Y-macos-{arm64,x86_64}.tar.gz.
- Templated media-server.service updated to match the dist layout with
  proper session-bus env vars and a writable state-dir grant.
- install_linux.sh: drop dead requirements.txt path; install via
  `pip install ".[linux]"` and pre-create the writable state dirs.
- Cross-platform album artwork: abstract MediaController.get_album_art()
  with Linux (mpris:artUrl, file:// + http(s)://) and macOS (Spotify URL)
  impls; routes/media artwork endpoint now awaits the controller.
- LinuxMediaController connects to the session bus lazily — failure no
  longer crashes lifespan startup; MPRIS calls return idle until the bus
  is reachable. Logged once at INFO with a hint about
  `loginctl enable-linger`.
- Startup preflight on Linux warns if DBUS_SESSION_BUS_ADDRESS or
  XDG_RUNTIME_DIR is unset and informs the user when Wayland disables
  the foreground probe.
- /api/media/visualizer/status now reports a per-OS unavailable_reason.
- tray._confirm guarded against ctypes.windll on non-Windows.
- config.example.yaml: per-OS commented script examples; on_turn_off
  default is now a no-op echo (used to silently fail off Windows).
- README: replace stale `pip install -r requirements.txt` instructions
  with the new extras; add systemd lingering doc + troubleshooting
  section; add macOS LaunchAgent section.
- CI: new linux-smoke job (installs `.[linux]`, boots the server under
  dbus-run-session, asserts /api/health). Release workflow gains
  apt-deps step for the Linux build and a best-effort macOS build job.

config.example.yaml

@@ -21,109 +21,140 @@ host: "127.0.0.1"
 port: 8765
 # allow_lan_without_auth: true   # uncomment + change host to 0.0.0.0 for LAN-open mode
 
-# Custom scripts
+# ─── Custom scripts ─────────────────────────────────────────────────────
+#
+# Examples below are platform-specific. Uncomment the block that matches
+# your OS — YAML keys must be unique, so don't ship multiple
+# `lock_screen:` entries.
+
 scripts:
-  lock_screen:
-    command: "rundll32.exe user32.dll,LockWorkStation"
-    label: "Lock Screen"
-    description: "Lock the workstation"
-    icon: "mdi:lock"
-    timeout: 5
-    shell: true
+  # ── Windows ─────────────────────────────────────────────────────────
+  # lock_screen:
+  #   command: "rundll32.exe user32.dll,LockWorkStation"
+  #   label: "Lock Screen"
+  #   description: "Lock the workstation"
+  #   icon: "mdi:lock"
+  #   timeout: 5
+  #   shell: true
+  # sleep:
+  #   command: "rundll32.exe powrprof.dll,SetSuspendState 0,1,0"
+  #   label: "Sleep"
+  #   icon: "mdi:sleep"
+  #   timeout: 10
+  #   shell: true
+  # shutdown:
+  #   command: "shutdown /s /t 0"
+  #   label: "Shutdown"
+  #   icon: "mdi:power"
+  #   timeout: 10
+  #   shell: true
 
-  hibernate:
-    command: "shutdown /h"
-    label: "Hibernate"
-    description: "Hibernate the PC"
-    icon: "mdi:power-sleep"
+  # ── Linux (systemd / xdg) ───────────────────────────────────────────
+  # lock_screen:
+  #   command: "loginctl lock-session"   # or: xdg-screensaver lock
+  #   label: "Lock Screen"
+  #   icon: "mdi:lock"
+  #   timeout: 5
+  #   shell: true
+  # sleep:
+  #   command: "systemctl suspend"
+  #   label: "Sleep"
+  #   icon: "mdi:sleep"
+  #   timeout: 10
+  #   shell: true
+  # shutdown:
+  #   command: "systemctl poweroff"
+  #   label: "Shutdown"
+  #   icon: "mdi:power"
+  #   timeout: 10
+  #   shell: true
+
+  # ── macOS ───────────────────────────────────────────────────────────
+  # lock_screen:
+  #   command: "pmset displaysleepnow"
+  #   label: "Lock Screen"
+  #   icon: "mdi:lock"
+  #   timeout: 5
+  #   shell: true
+  # sleep:
+  #   command: "pmset sleepnow"
+  #   label: "Sleep"
+  #   icon: "mdi:sleep"
+  #   timeout: 5
+  #   shell: true
+  # shutdown:
+  #   command: "osascript -e 'tell application \"System Events\" to shut down'"
+  #   label: "Shutdown"
+  #   icon: "mdi:power"
+  #   timeout: 10
+  #   shell: true
+
+  # Cross-platform smoke test (always defined so first-run users see the UI populate).
+  example_script:
+    command: "echo Hello from Media Server!"
+    description: "Example script - echoes a message"
     timeout: 10
     shell: true
 
-  sleep:
-    command: "rundll32.exe powrprof.dll,SetSuspendState 0,1,0"
-    label: "Sleep"
-    description: "Put PC to sleep"
-    icon: "mdi:sleep"
-    timeout: 10
-    shell: true
-
-  shutdown:
-    command: "shutdown /s /t 0"
-    label: "Shutdown"
-    description: "Shutdown the PC immediately"
-    icon: "mdi:power"
-    timeout: 10
-    shell: true
-
-  restart:
-    command: "shutdown /r /t 0"
-    label: "Restart"
-    description: "Restart the PC immediately"
-    icon: "mdi:restart"
-    timeout: 10
-    shell: true
-
-# Media folder management from Web UI (default: true)
+# Media folder management from Web UI (default: false)
 # When enabled, media folders can be added, edited, and deleted from the Settings tab.
-# Set to false to disable folder management from the UI.
-# media_folders_management: false
+# media_folders_management: true
+
+# ─── Callback scripts (executed by integration events) ──────────────────
+#
+# Callbacks are OS-agnostic — if you want side effects, fill in commands
+# below. The defaults are no-op echos so first-run logs don't error out.
 
-# Callback scripts (executed after media actions)
-# All callbacks are optional - if not defined, the action runs without callback
 callbacks:
-  # Media control callbacks (run after successful action)
   on_play:
     command: "echo Play triggered"
     timeout: 10
     shell: true
-
   on_pause:
     command: "echo Pause triggered"
     timeout: 10
     shell: true
-
   on_stop:
     command: "echo Stop triggered"
     timeout: 10
     shell: true
-
   on_next:
     command: "echo Next track"
     timeout: 10
     shell: true
-
   on_previous:
     command: "echo Previous track"
     timeout: 10
     shell: true
-
   on_volume:
     command: "echo Volume changed"
     timeout: 10
     shell: true
-
   on_mute:
     command: "echo Mute toggled"
     timeout: 10
     shell: true
-
   on_seek:
     command: "echo Seek triggered"
     timeout: 10
     shell: true
 
-  # Turn on/off/toggle (callback-only actions, no default behavior)
+  # Turn on/off/toggle (callback-only actions, no default behavior).
+  # The Windows-only example used to ship as the default for `on_turn_off`,
+  # which silently failed on Linux/macOS. Defaults are now no-ops — pick a
+  # platform-appropriate command below.
   on_turn_on:
     command: "echo Turn on callback"
     timeout: 10
     shell: true
-
   on_turn_off:
-    command: "rundll32.exe user32.dll,LockWorkStation"
+    # Windows: "rundll32.exe user32.dll,LockWorkStation"
+    # Linux:   "loginctl lock-session"
+    # macOS:   "pmset displaysleepnow"
+    command: "echo Turn off callback"
     timeout: 5
     shell: true
-
   on_toggle:
     command: "echo Toggle callback"
     timeout: 10
-    shell: true
+    shell: true