diff --git a/.gitignore b/.gitignore
index f038882..1d2a9a1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,4 @@ dist/
*.AppImage
*.AppImage.sha256
tests/
+.superpowers/
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..db1af6b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,88 @@
+# AGENTS.md
+
+## Architecture
+
+The application is split across two files:
+
+- `mount_manager.py` — entry point, constants, dataclasses (`SharePath`, `ManagedMount`,
+ `DisplayedMount`), exceptions, privileged helper-mode logic (`run_helper_mode`), polkit
+ invocations (`request_helper_*`), and pure helpers (`check_smb_host_reachable`,
+ `load_displayed_mounts`, `validate_credentials`, `_libadwaita_supports`).
+ This module **must remain importable without a display and without libadwaita**: it is
+ re-executed as root via `pkexec /usr/bin/mount-manager --helper …` and that path must
+ not pull in GTK/Adw. Keep all GUI imports lazy (inside `run_gui()`).
+- `mount_manager_ui.py` — all GTK4 / libadwaita UI. Defines a thin module-level
+ `run_gui()` that contains the `MainWindow`, `AddShareDialog`, and
+ `MountManagerApplication` classes nested inside it. Imports the data + helpers it needs
+ from `mount_manager`.
+
+`mount_manager.run_gui()` is a one-line shim that imports `mount_manager_ui` lazily so the
+`--helper` path never loads GUI code.
+
+## UI conventions (libadwaita ≥ 1.5)
+
+- Minimum libadwaita version is enforced by `mount_manager._libadwaita_supports` and
+ `ensure_libadwaita_supported()` in `mount_manager_ui`. Bumping `MIN_LIBADWAITA_VERSION`
+ in `mount_manager.py` is the single source of truth.
+- Color scheme is delegated to `Adw.StyleManager` (`ColorScheme.DEFAULT`). Do not
+ re-introduce custom CSS for theming or a custom color-scheme detector.
+- The mount list uses `Adw.PreferencesPage` → `Adw.PreferencesGroup` → `Adw.ActionRow`
+ per mount with the **hybrid row pattern**: switch + one inline primary suffix
+ (open-folder or Upgrade) + kebab `MenuButton` containing destructive actions.
+ Unmanaged shares show a "Not managed" label and no controls.
+- To enumerate or clear rows in an `Adw.PreferencesGroup`, use
+ `group.get_row(index)` — not `get_first_child()`, which returns the group's internal
+ structure widgets, not the `ActionRow` children.
+- Status / error messages are surfaced as `Adw.Toast` via `MainWindow.show_toast()`.
+ Do not add new `Gtk.Window` / `Adw.Window` message dialogs.
+- Confirmation prompts use `Adw.AlertDialog`; destructive responses get
+ `Adw.ResponseAppearance.DESTRUCTIVE`.
+- The Add Share flow is a single-page progressive-reveal `Adw.Dialog` with a 300ms
+ debounced host check (`GLib.timeout_add` + `GLib.source_remove`). Any pending timer
+ **must** be cancelled on the dialog's `"closed"` signal to avoid firing callbacks on
+ destroyed widgets. The dialog body is an `Adw.Clamp` wrapping a vertical `Gtk.Box`
+ of `Adw.PreferencesGroup`s — **not** `Adw.PreferencesPage`, whose internal
+ `ScrolledWindow` would fix the dialog height and hide content revealed at runtime
+ (e.g. the credentials group) behind a scrollbar.
+- Always escape user-controlled strings (mount paths, statuses) with
+ `GLib.markup_escape_text` before passing them to widgets that render Pango markup.
+- About box uses `Adw.AboutDialog`.
+
+## Tests
+
+- Stock `unittest` only — no pytest, no new dependencies.
+- Run: `python3 -m unittest discover -s tests -v`
+- Unit-test pure-Python helpers (e.g. `_libadwaita_supports`, `mount_status_line`).
+ Widget construction is verified manually — do not add headless GTK widget-tree
+ assertions to the test suite.
+
+## Packaging
+
+- `packaging/build-appimage.sh` installs both `mount_manager.py` and `mount_manager_ui.py`
+ into `$appdir/usr/bin/` under their real filenames, then creates a `mount-manager`
+ symlink pointing at `mount_manager.py` for the AppRun entry point. The real filenames
+ matter: `mount_manager_ui.py` does `from mount_manager import …`, so the file backing
+ that module must be named `mount_manager.py` on disk. Python's `sys.path[0]` covers the
+ script directory, so both imports resolve without `sys.path` manipulation.
+- `packaging/appimage-helper.patch` rewrites the helper invocation so the AppImage
+ re-execs itself under `pkexec`. It targets `mount_manager.py` (the installed filename),
+ not the `mount-manager` symlink. Do not change the helper CLI surface
+ (`--helper {create|delete|upgrade|set-enabled}`) without updating this patch.
+- If you add a new top-level Python module that the GUI imports, you must add a matching
+ `install` line in `packaging/build-appimage.sh` AND in the README's manual-install
+ section.
+
+## Reference docs
+
+- Design spec: `docs/specs/2026-05-28-libadwaita-migration-design.md`
+- Implementation plan (executed, kept for context): `docs/plans/2026-05-28-libadwaita-migration.md`
+
+## Working rules
+- Prefer native tools (view/edit/create/grep/glob) over shell for file reading, editing, and
+ searching. Use shell only when there is no native equivalent (running tests, builds, git, gh,
+ packaging).
+- Ad-hoc `python3 -c '...'` snippets for verification are fine. Do not add new throwaway scripts
+ to the repo; if a check is worth keeping, make it a unittest under `tests/`.
+- Ask before any destructive or irreversible operation: force-push, history rewrites, deleting
+ branches that exist on the remote, mass file deletion, or modifying files outside the repo.
+- Do not add `Co-authored-by:` trailers to commit messages.
diff --git a/README.md b/README.md
index 7ea9246..22fdd2e 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,8 @@ Credentials and app metadata are stored under:
systemd 258 or newer with `systemd-creds` available. The app refuses to start
on older systems.
+libadwaita 1.8 or newer. The app refuses to start on older versions.
+
Credentials are always stored encrypted via `systemd-creds` and decrypted by
systemd at unit start, exposed to `mount.cifs` through `LoadCredentialEncrypted=`.
The plaintext password never touches disk, and the encrypted blob is bound to
@@ -73,6 +75,7 @@ Install the app files into the overlay:
```bash
sudo install -D -m 0755 mount_manager.py /usr/bin/mount-manager
+sudo install -D -m 0644 mount_manager_ui.py /usr/bin/mount_manager_ui.py
sudo install -D -m 0644 data/applications/io.github.xarishark.mount-manager.desktop /usr/share/applications/io.github.xarishark.mount-manager.desktop
sudo install -D -m 0644 data/icons/hicolor/scalable/apps/io.github.xarishark.mount-manager.svg /usr/share/icons/hicolor/scalable/apps/io.github.xarishark.mount-manager.svg
sudo install -D -m 0644 data/metainfo/io.github.xarishark.mount-manager.metainfo.xml /usr/share/metainfo/io.github.xarishark.mount-manager.metainfo.xml
diff --git a/data/metainfo/io.github.xarishark.mount-manager.metainfo.xml b/data/metainfo/io.github.xarishark.mount-manager.metainfo.xml
index 83137e1..9b5933a 100644
--- a/data/metainfo/io.github.xarishark.mount-manager.metainfo.xml
+++ b/data/metainfo/io.github.xarishark.mount-manager.metainfo.xml
@@ -30,7 +30,7 @@
-
+
diff --git a/docs/plans/2026-05-28-hig-fixes.md b/docs/plans/2026-05-28-hig-fixes.md
new file mode 100644
index 0000000..4717c54
--- /dev/null
+++ b/docs/plans/2026-05-28-hig-fixes.md
@@ -0,0 +1,707 @@
+# HIG Fixes Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Address the findings in `~/mount-manager-hig-audit.md` so the libadwaita UI matches GNOME HIG conventions for copy, button styling, keyboard interaction, and accessibility.
+
+**Architecture:** Mostly surgical edits to `mount_manager_ui.py`. The largest task adds application-level `Gio.SimpleAction`s plus a `Gtk.ShortcutsWindow` for the M1 keyboard-accessibility gap. No new modules, no new test dependencies. Per `AGENTS.md`, widget trees are verified manually; existing pure-helper unit tests remain the only automated coverage.
+
+**Tech Stack:** Python 3, PyGObject (`gi`), GTK 4, libadwaita ≥ 1.5, stock `unittest`.
+
+**Source of truth for findings:** `~/mount-manager-hig-audit.md` (file lives outside the repo by user preference, NOT committed).
+
+**Branch:** `feat/libadwaita-01` (continue committing here; do not branch off).
+
+---
+
+## File Map
+
+- Modify: `mount_manager_ui.py` — every task touches this file.
+- Modify: `mount_manager.py` — only Task 6 (register an app-level `Ctrl+Q` accelerator on the `Adw.Application`).
+- No new files.
+
+---
+
+## Task 1: Copy & Terminology Fixes
+
+Addresses audit findings **m1, m2, m3, m4, m6, m7** — pure string changes.
+
+**Files:**
+- Modify: `mount_manager_ui.py`
+
+- [ ] **Step 1: Strip trailing periods from toast titles (audit m1)**
+
+In `mount_manager_ui.py`, change these five toast strings:
+
+```python
+# in MainWindow.open_mount_folder
+self.show_toast(f"Mount folder does not exist: {record.mount_point}")
+# becomes
+self.show_toast(f"Mount folder does not exist: {record.mount_point}") # already no period — verify
+```
+
+Apply the period removal to:
+
+```python
+# MainWindow.upgrade_mount
+self.show_toast(f"{record.source} upgraded.")
+# →
+self.show_toast(f"{record.source} upgraded")
+```
+
+```python
+# MainWindow._on_delete_response
+self.show_toast(f"{record.source} removed.")
+# →
+self.show_toast(f"{record.source} removed")
+```
+
+```python
+# AddShareDialog._on_add_clicked
+self.main_window.show_toast(f"{share} added.")
+# →
+self.main_window.show_toast(f"{share} added")
+```
+
+Also remove the trailing period from every `f"… failed: {exc}"` toast — these end with the exception's text, which often already has no period; the literal `"failed:"` portion is fine. Audit only every toast string in the file and ensure none ends with a literal period in the format string. Specifically check:
+
+```python
+self.show_toast(f"Upgrade failed: {exc}") # no trailing period — leave as-is
+self.show_toast(f"Toggle failed: {exc}") # no trailing period — leave as-is
+self.show_toast(f"Delete failed: {exc}") # no trailing period — leave as-is
+self.show_toast(f"Could not open {record.mount_point}: {exc}") # leave
+```
+
+Search command to verify nothing was missed:
+
+```bash
+grep -nE 'show_toast\(.*\.\"\)' mount_manager_ui.py
+```
+
+Expected: no matches.
+
+- [ ] **Step 2: Replace italic markup in empty-state description (audit m2)**
+
+In `MainWindow.__init__`, find:
+
+```python
+self.empty_page.set_description("Click Add Share to mount one.")
+```
+
+Replace with:
+
+```python
+self.empty_page.set_description('Click "Add Share" to mount one')
+```
+
+(Plain text, no Pango italics, no trailing period.)
+
+- [ ] **Step 3: Rewrite the header-bar Add Share tooltip (audit m3)**
+
+In `MainWindow.__init__`, find:
+
+```python
+add_button = Gtk.Button(label="Add Share")
+add_button.set_tooltip_text("Add share")
+```
+
+Replace the tooltip line with:
+
+```python
+add_button.set_tooltip_text("Mount a new SMB share")
+```
+
+- [ ] **Step 4: Rename primary menu tooltip (audit m4)**
+
+In `MainWindow.__init__`, find:
+
+```python
+menu_button.set_tooltip_text("Main menu")
+```
+
+Replace with:
+
+```python
+menu_button.set_tooltip_text("Primary menu")
+```
+
+- [ ] **Step 5: Make the Delete confirmation button label more specific (audit m6)**
+
+In `MainWindow.confirm_delete`, find:
+
+```python
+alert.add_response("delete", "Delete")
+```
+
+Replace with:
+
+```python
+alert.add_response("delete", "Delete Share")
+```
+
+- [ ] **Step 6: Rename or drop the redundant mount group title (audit m7)**
+
+In `MainWindow.__init__`, find:
+
+```python
+self.mount_group = Adw.PreferencesGroup()
+self.mount_group.set_title("SMB Shares")
+```
+
+Replace with:
+
+```python
+self.mount_group = Adw.PreferencesGroup()
+```
+
+(Drop the title entirely. Single-group preferences pages in libadwaita are conventionally untitled when the window title already provides context.)
+
+- [ ] **Step 7: Run the existing test suite**
+
+```bash
+cd /var/home/mihlo/Projects/mount-manager
+python3 -m unittest discover -s tests -v
+```
+
+Expected: 9 tests pass (no regressions).
+
+- [ ] **Step 8: Smoke-run the UI manually**
+
+```bash
+python3 mount_manager.py
+```
+
+Verify: window opens, toasts (trigger one by toggling a switch off→on with the daemon stopped, if convenient, or by deleting a mount) have no trailing periods. Hover the header buttons to see the new tooltips. Hover-quit.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "fix(ui): align UI copy with GNOME HIG (toasts, tooltips, labels)"
+```
+
+---
+
+## Task 2: Modernize Icon Names
+
+Addresses audit findings **n1** and **n2**.
+
+**Files:**
+- Modify: `mount_manager_ui.py`
+
+- [ ] **Step 1: Replace legacy host-status icons (audit n1)**
+
+In `AddShareDialog._set_host_status`, find:
+
+```python
+if ok:
+ self.host_status_icon.set_from_icon_name("emblem-ok-symbolic")
+else:
+ self.host_status_icon.set_from_icon_name("dialog-error-symbolic")
+```
+
+Replace with:
+
+```python
+if ok:
+ self.host_status_icon.set_from_icon_name("checkmark-symbolic")
+else:
+ self.host_status_icon.set_from_icon_name("error-symbolic")
+```
+
+- [ ] **Step 2: Change the empty-state icon (audit n2)**
+
+In `MainWindow.__init__`, find:
+
+```python
+self.empty_page.set_icon_name("folder-remote-symbolic")
+```
+
+Replace with:
+
+```python
+self.empty_page.set_icon_name("network-server-symbolic")
+```
+
+- [ ] **Step 3: Smoke-run the UI manually**
+
+```bash
+python3 mount_manager.py
+```
+
+Verify:
+
+1. Empty state (with no managed mounts) shows the network-server icon.
+2. Open Add Share, type a reachable host like `//localhost/test` (or any host you know resolves) — the row should show a green check.
+3. Type a definitely-unreachable host like `//unreachable.invalid/x` — the row should show a red error icon.
+
+If a fallback name lookup is needed for either icon, GTK's icon theme falls back gracefully and shows the missing-image glyph. If you see a missing-image glyph in either case, revert that specific name only and note it in the commit message.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "refactor(ui): use modern symbolic icon names"
+```
+
+---
+
+## Task 3: AddShareDialog Ergonomics
+
+Addresses audit findings **m5** (default widget + initial focus) and **n3** (redundant header calls).
+
+**Files:**
+- Modify: `mount_manager_ui.py`
+
+- [ ] **Step 1: Remove redundant header title-button calls (audit n3)**
+
+In `AddShareDialog.__init__`, find:
+
+```python
+header = Adw.HeaderBar()
+header.set_show_start_title_buttons(False)
+header.set_show_end_title_buttons(False)
+header.pack_start(self.cancel_button)
+header.pack_end(self.add_button)
+```
+
+Replace with:
+
+```python
+header = Adw.HeaderBar()
+header.pack_start(self.cancel_button)
+header.pack_end(self.add_button)
+```
+
+`AdwDialog` manages its own title-bar buttons, so these calls have no effect.
+
+- [ ] **Step 2: Set the Add button as the dialog's default widget (audit m5)**
+
+In `AddShareDialog.__init__`, immediately after `self.set_child(toolbar)` (and before the `self.connect("closed", self._cleanup)` line), add:
+
+```python
+self.set_default_widget(self.add_button)
+```
+
+This makes the Add button respond to Enter from any focused entry once it becomes sensitive. The Add button is already gated by `_update_add_sensitive`, so Enter cannot submit prematurely.
+
+- [ ] **Step 3: Focus the share-path entry when the dialog opens (audit m5)**
+
+`Adw.Dialog` emits `map` when it becomes visible. In `AddShareDialog.__init__`, after the `self.connect("closed", self._cleanup)` line, add:
+
+```python
+self.connect("map", lambda _d: self.path_row.grab_focus())
+```
+
+- [ ] **Step 4: Smoke-run the UI manually**
+
+```bash
+python3 mount_manager.py
+```
+
+Verify:
+
+1. Open Add Share — the share-path entry has focus immediately (you can type without clicking).
+2. Type a valid host, fill in username and password.
+3. Press Enter from the password field — the Add button is triggered (the dialog attempts the create instead of doing nothing).
+
+- [ ] **Step 5: Run the existing test suite**
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+Expected: 9 tests pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "fix(ui): improve AddShareDialog focus and keyboard submit"
+```
+
+---
+
+## Task 4: About Dialog Cleanup
+
+Addresses audit finding **n4**.
+
+**Files:**
+- Modify: `mount_manager_ui.py`
+
+- [ ] **Step 1: Remove the duplicate developer field**
+
+In `MainWindow.show_about_dialog`, find:
+
+```python
+about = Adw.AboutDialog(
+ application_name=APP_NAME,
+ application_icon=APP_ICON_NAME,
+ developer_name=APP_DEVELOPERS[0] if APP_DEVELOPERS else "",
+ website=APP_WEBSITE,
+ issue_url=f"{APP_WEBSITE}/issues",
+ license_type=Gtk.License.GPL_3_0_ONLY,
+ comments="Create and manage on-demand SMB mounts.",
+)
+about.set_developers(APP_DEVELOPERS)
+about.present(self)
+```
+
+Replace with:
+
+```python
+about = Adw.AboutDialog(
+ application_name=APP_NAME,
+ application_icon=APP_ICON_NAME,
+ website=APP_WEBSITE,
+ issue_url=f"{APP_WEBSITE}/issues",
+ license_type=Gtk.License.GPL_3_0_ONLY,
+ comments="Create and manage on-demand SMB mounts.",
+)
+about.set_developers(APP_DEVELOPERS)
+about.present(self)
+```
+
+`developer_name` is a single-line credit shown on the front page; `set_developers()` populates the Credits page list. Keep `set_developers` (it's the canonical list) and drop the `developer_name` constructor arg, which was redundant.
+
+- [ ] **Step 2: Smoke-run the UI manually**
+
+```bash
+python3 mount_manager.py
+```
+
+Open the primary menu → "About SMB Mount Manager". Verify the dialog still opens, the Credits page lists the developer(s), and the front page does not show a duplicate name underneath the title.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "refactor(ui): drop duplicate developer field in About dialog"
+```
+
+---
+
+## Task 5: Restyle the Header Bar "Add Share" Button
+
+Addresses audit findings **M2** (label-only suggested-action in primary header bar) and **M3** (two suggested-action buttons visible simultaneously). Fixing M2 fixes M3.
+
+**Files:**
+- Modify: `mount_manager_ui.py`
+
+- [ ] **Step 1: Convert the header Add Share button to icon+label, drop suggested-action**
+
+In `MainWindow.__init__`, find:
+
+```python
+add_button = Gtk.Button(label="Add Share")
+add_button.set_tooltip_text("Mount a new SMB share")
+add_button.add_css_class("suggested-action")
+add_button.connect("clicked", lambda _b: self.show_add_dialog())
+```
+
+Replace with:
+
+```python
+add_button = Adw.ButtonContent(
+ icon_name="list-add-symbolic",
+ label="Add Share",
+)
+add_button_wrapper = Gtk.Button()
+add_button_wrapper.set_child(add_button)
+add_button_wrapper.set_tooltip_text("Mount a new SMB share")
+add_button_wrapper.connect("clicked", lambda _b: self.show_add_dialog())
+```
+
+Then update the `header.pack_start(add_button)` line below to:
+
+```python
+header.pack_start(add_button_wrapper)
+```
+
+`Adw.ButtonContent` is the libadwaita helper that produces a consistent icon+label inside a `Gtk.Button`, and the header-bar style class will automatically remove the visible background per HIG (no `suggested-action` class needed — the pill button on `AdwStatusPage` is now the single suggested-action element in the empty state).
+
+- [ ] **Step 2: Smoke-run the UI manually**
+
+```bash
+python3 mount_manager.py
+```
+
+Verify:
+
+1. Empty state: the header bar shows an Add Share icon+label button with no visible background or accent color; the pill in the centre is still blue (suggested).
+2. Non-empty state: the header button still works and styled the same.
+3. Resize the window narrow — the icon+label fits cleanly.
+4. Hover the header button — tooltip still reads "Mount a new SMB share".
+
+- [ ] **Step 3: Run the existing test suite**
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+Expected: 9 tests pass.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "fix(ui): restyle header-bar Add Share button to follow HIG"
+```
+
+---
+
+## Task 6: Keyboard Shortcuts + ShortcutsWindow
+
+Addresses audit finding **M1** — the largest single fix on the branch.
+
+**Approach:**
+
+- Add a `Gio.SimpleAction` for each shortcut on the `Adw.Application` (`app.quit`, `app.shortcuts`) and on the `MainWindow` (`win.close`, `win.add-share`, `win.refresh`, `win.show-menu`).
+- Use `Gtk.Application.set_accels_for_action()` to bind shortcuts.
+- Build a `Gtk.ShortcutsWindow` programmatically (no UI file — the rest of this codebase doesn't use them).
+- Add a "Keyboard Shortcuts" entry to the primary menu above "About".
+- Rewire existing handlers (refresh, add-share, about) through the new actions so accelerators and menu items both flow through the same code path.
+
+**Files:**
+- Modify: `mount_manager_ui.py`
+- Modify: `mount_manager.py` (only to install the `app.quit` accelerator on the `Adw.Application`)
+
+- [ ] **Step 1: Add the `Adw.Application` accelerators and `app.quit` / `app.shortcuts` actions**
+
+In `mount_manager_ui.py`, replace the entire `MountManagerApplication` class:
+
+```python
+class MountManagerApplication(Adw.Application):
+ def __init__(self) -> None:
+ super().__init__(application_id=APP_ID, flags=Gio.ApplicationFlags.DEFAULT_FLAGS)
+
+ def do_activate(self) -> None:
+ window = self.props.active_window
+ if window is None:
+ window = MainWindow(self)
+ window.present()
+```
+
+with:
+
+```python
+class MountManagerApplication(Adw.Application):
+ def __init__(self) -> None:
+ super().__init__(application_id=APP_ID, flags=Gio.ApplicationFlags.DEFAULT_FLAGS)
+
+ quit_action = Gio.SimpleAction.new("quit", None)
+ quit_action.connect("activate", lambda _a, _p: self.quit())
+ self.add_action(quit_action)
+ self.set_accels_for_action("app.quit", ["q"])
+
+ shortcuts_action = Gio.SimpleAction.new("shortcuts", None)
+ shortcuts_action.connect("activate", lambda _a, _p: self._show_shortcuts())
+ self.add_action(shortcuts_action)
+ self.set_accels_for_action("app.shortcuts", ["question"])
+
+ def _show_shortcuts(self) -> None:
+ window = self.props.active_window
+ if window is None:
+ return
+ shortcuts_window = build_shortcuts_window(window)
+ shortcuts_window.present()
+
+ def do_activate(self) -> None:
+ window = self.props.active_window
+ if window is None:
+ window = MainWindow(self)
+ window.present()
+```
+
+- [ ] **Step 2: Add the `build_shortcuts_window` helper**
+
+In `mount_manager_ui.py`, *inside* `run_gui()` and **above** the `class AddShareDialog` definition, add:
+
+```python
+def build_shortcuts_window(parent: Gtk.Window) -> Gtk.ShortcutsWindow:
+ """Construct the keyboard shortcuts dialog for the app."""
+ window = Gtk.ShortcutsWindow(transient_for=parent, modal=True)
+
+ section = Gtk.ShortcutsSection(section_name="main", visible=True)
+
+ general = Gtk.ShortcutsGroup(title="General")
+ general.add_shortcut(
+ Gtk.ShortcutsShortcut(title="Add Share", accelerator="n")
+ )
+ general.add_shortcut(
+ Gtk.ShortcutsShortcut(title="Refresh", accelerator="r")
+ )
+ general.add_shortcut(
+ Gtk.ShortcutsShortcut(title="Primary Menu", accelerator="F10")
+ )
+ general.add_shortcut(
+ Gtk.ShortcutsShortcut(title="Keyboard Shortcuts", accelerator="question")
+ )
+ general.add_shortcut(
+ Gtk.ShortcutsShortcut(title="Close Window", accelerator="w")
+ )
+ general.add_shortcut(
+ Gtk.ShortcutsShortcut(title="Quit", accelerator="q")
+ )
+ section.add_group(general)
+
+ window.add_section(section)
+ return window
+```
+
+Note: `Gtk.ShortcutsWindow` and its supporting classes (`ShortcutsSection`, `ShortcutsGroup`, `ShortcutsShortcut`) are part of GTK 4 and require no additional imports beyond `Gtk`, which is already imported.
+
+- [ ] **Step 3: Add window-level actions and accelerators in `MainWindow.__init__`**
+
+In `MainWindow.__init__`, find the existing about-action block:
+
+```python
+about_action = Gio.SimpleAction.new("about", None)
+about_action.connect("activate", lambda _a, _p: self.show_about_dialog())
+self.add_action(about_action)
+```
+
+Immediately after that block, add:
+
+```python
+close_action = Gio.SimpleAction.new("close", None)
+close_action.connect("activate", lambda _a, _p: self.close())
+self.add_action(close_action)
+app.set_accels_for_action("win.close", ["w"])
+
+add_share_action = Gio.SimpleAction.new("add-share", None)
+add_share_action.connect("activate", lambda _a, _p: self.show_add_dialog())
+self.add_action(add_share_action)
+app.set_accels_for_action("win.add-share", ["n"])
+
+refresh_action = Gio.SimpleAction.new("refresh", None)
+refresh_action.connect("activate", lambda _a, _p: self.refresh())
+self.add_action(refresh_action)
+app.set_accels_for_action("win.refresh", ["r"])
+
+show_menu_action = Gio.SimpleAction.new("show-menu", None)
+show_menu_action.connect("activate", lambda _a, _p: self._open_primary_menu())
+self.add_action(show_menu_action)
+app.set_accels_for_action("win.show-menu", ["F10"])
+```
+
+- [ ] **Step 4: Hold a reference to the menu button so F10 can open it**
+
+In `MainWindow.__init__`, find:
+
+```python
+menu_button = Gtk.MenuButton(icon_name="open-menu-symbolic")
+menu_button.set_menu_model(menu)
+menu_button.set_tooltip_text("Primary menu")
+```
+
+Replace with:
+
+```python
+self.menu_button = Gtk.MenuButton(icon_name="open-menu-symbolic")
+self.menu_button.set_menu_model(menu)
+self.menu_button.set_tooltip_text("Primary menu")
+```
+
+And update the `header.pack_end(menu_button)` line further down to:
+
+```python
+header.pack_end(self.menu_button)
+```
+
+Then add the helper method on `MainWindow` (anywhere convenient — next to `show_toast` is fine):
+
+```python
+def _open_primary_menu(self) -> None:
+ self.menu_button.popup()
+```
+
+- [ ] **Step 5: Add a "Keyboard Shortcuts" entry to the primary menu**
+
+In `MainWindow.__init__`, find:
+
+```python
+menu = Gio.Menu()
+menu.append(f"About {APP_NAME}", "win.about")
+```
+
+Replace with:
+
+```python
+menu = Gio.Menu()
+menu.append("Keyboard Shortcuts", "app.shortcuts")
+menu.append(f"About {APP_NAME}", "win.about")
+```
+
+The Keyboard Shortcuts entry will automatically display its accelerator (`Ctrl+?`) once `set_accels_for_action` has been called for `app.shortcuts`.
+
+- [ ] **Step 6: Smoke-run the UI manually**
+
+```bash
+python3 mount_manager.py
+```
+
+Verify each accelerator:
+
+1. `Ctrl+N` — opens Add Share dialog.
+2. `Ctrl+R` — refresh fires (rows reload; if you're watching `journalctl`, you'll see the systemd queries re-run).
+3. `F10` — primary menu opens. Press `F10` again or `Esc` to dismiss.
+4. `Ctrl+?` — Keyboard Shortcuts dialog opens, listing all six shortcuts. Press `Esc` to close.
+5. `Ctrl+W` — closes the window.
+6. Reopen the app. `Ctrl+Q` — quits the app entirely.
+7. Open the primary menu — "Keyboard Shortcuts" appears above "About SMB Mount Manager", with its accelerator badge.
+
+- [ ] **Step 7: Run the existing test suite**
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+Expected: 9 tests pass (no regressions).
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "feat(ui): add keyboard shortcuts and shortcuts window"
+```
+
+---
+
+## Task 7: Final Verification
+
+- [ ] **Step 1: Run the full test suite one more time**
+
+```bash
+cd /var/home/mihlo/Projects/mount-manager
+python3 -m unittest discover -s tests -v
+```
+
+Expected: 9 tests pass.
+
+- [ ] **Step 2: Verify the helper path is still GUI-free**
+
+```bash
+python3 -X importtime mount_manager.py --helper set-enabled --manager-id never --enabled 0 2>&1 | grep -E "gi\.repository\.(Gtk|Adw)" || echo "OK: no GUI imports"
+```
+
+Expected: prints `OK: no GUI imports`. (The command itself will fail with a "not found" error from the helper path — that's expected; we only care about the import trace.)
+
+- [ ] **Step 3: Final manual smoke**
+
+```bash
+python3 mount_manager.py
+```
+
+Walk through one more time:
+
+1. Header-bar Add Share button: icon + label, no accent color.
+2. Empty state: status page with `network-server-symbolic`, plain-text description, single suggested-action pill.
+3. Open Add Share via `Ctrl+N`: path entry has focus, type a host, fill credentials, press Enter — submits.
+4. Open About via menu: no duplicate developer name on the front page.
+5. Delete a mount via the kebab menu: confirmation dialog button reads "Delete Share". Cancel.
+6. `Ctrl+?` opens the shortcuts window. `Esc` closes it.
+
+- [ ] **Step 4: Confirm with the user**
+
+Stop here and tell the user the HIG-fix tasks are complete, all tests still pass, and the branch is ready to return to the `finishing-a-development-branch` flow (merge / push+PR / keep / discard).
diff --git a/docs/plans/2026-05-28-libadwaita-1.8-bump.md b/docs/plans/2026-05-28-libadwaita-1.8-bump.md
new file mode 100644
index 0000000..ae44b50
--- /dev/null
+++ b/docs/plans/2026-05-28-libadwaita-1.8-bump.md
@@ -0,0 +1,476 @@
+# Libadwaita 1.8 Baseline Bump — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Raise the minimum libadwaita to 1.8 and adopt the newer APIs it (and modern GTK) enable: `Adw.Spinner`, `Adw.ShortcutsDialog`, `Gtk.FileLauncher`, and `AdwPreferencesGroup.set_separate_rows()`.
+
+**Architecture:** Five small surgical changes on the `feat/libadwaita-01` branch. The version bump comes first (with its test-fixture rebase) so subsequent tasks legitimately depend on the new floor. Each subsequent task swaps a single API call site and gets its own commit. No new modules; no architectural change.
+
+**Tech Stack:** Python 3, GTK 4 (≥ 4.18 transitively), libadwaita ≥ 1.8, PyGObject. Tests: stock `unittest` (no pytest).
+
+**Source spec:** `docs/specs/2026-05-28-libadwaita-1.8-bump-design.md`
+
+**Pre-flight (executor):**
+- Confirm working tree is clean for tracked files (`git status` should show no `M` lines for `mount_manager.py`, `mount_manager_ui.py`, `README.md`, or `tests/`).
+- Confirm the runtime libadwaita is at least 1.8: `python3 -c "import gi; gi.require_version('Adw','1'); from gi.repository import Adw; print(Adw.MAJOR_VERSION, Adw.MINOR_VERSION)"` should print `1 8` or higher.
+- Baseline test run: `python3 -m unittest discover -s tests -v` should report 9 tests, all passing.
+
+---
+
+## Task 1: Bump `MIN_LIBADWAITA_VERSION` to (1, 8)
+
+**Files:**
+- Modify: `mount_manager.py:52-53`
+- Modify: `tests/test_libadwaita_support.py` (full file)
+- Modify: `README.md:27`
+
+This task is genuinely TDD-shaped: the version-support test file is the contract we're changing. Rebase the test fixtures first, watch them fail, then update the constant.
+
+- [ ] **Step 1: Rebase the test fixtures on the new (1, 8) floor**
+
+Replace the entire body of `tests/test_libadwaita_support.py` with:
+
+```python
+"""Unit tests for the libadwaita version comparator."""
+
+import unittest
+
+from mount_manager import _libadwaita_supports
+
+
+class LibadwaitaSupportsTest(unittest.TestCase):
+ def test_minimum_supported_version(self) -> None:
+ self.assertTrue(_libadwaita_supports(1, 8))
+
+ def test_newer_minor_supported(self) -> None:
+ self.assertTrue(_libadwaita_supports(1, 9))
+
+ def test_newer_major_supported(self) -> None:
+ self.assertTrue(_libadwaita_supports(2, 0))
+
+ def test_older_minor_unsupported(self) -> None:
+ self.assertFalse(_libadwaita_supports(1, 7))
+
+ def test_older_major_unsupported(self) -> None:
+ self.assertFalse(_libadwaita_supports(0, 99))
+
+
+if __name__ == "__main__":
+ unittest.main()
+```
+
+- [ ] **Step 2: Run the tests, confirm the floor checks fail**
+
+Run: `python3 -m unittest discover -s tests -v`
+
+Expected: `test_minimum_supported_version` and `test_older_minor_unsupported` FAIL.
+Specifically: `_libadwaita_supports(1, 8)` returns True under the new test but currently True anyway (since 1.8 >= 1.5), so that one will not fail. The real failure is `test_older_minor_unsupported` — `_libadwaita_supports(1, 7)` returns True under the old (1, 5) floor but the test now asserts False.
+
+(The minimum-version test continues to pass coincidentally; the older-minor test is the one that proves the change.)
+
+- [ ] **Step 3: Bump the version constant and comment**
+
+In `mount_manager.py`, replace lines 52–53:
+
+```python
+# Adw.Dialog and Adw.AlertDialog require libadwaita 1.5 or newer.
+MIN_LIBADWAITA_VERSION: tuple[int, int] = (1, 5)
+```
+
+with:
+
+```python
+# Adw.ShortcutsDialog and Adw.Spinner require libadwaita 1.8 or newer.
+MIN_LIBADWAITA_VERSION: tuple[int, int] = (1, 8)
+```
+
+- [ ] **Step 4: Run the tests, confirm all pass**
+
+Run: `python3 -m unittest discover -s tests -v`
+
+Expected: 9 tests, all pass.
+
+- [ ] **Step 5: Update the README**
+
+In `README.md` line 27, replace:
+
+```
+libadwaita 1.5 or newer. The app refuses to start on older versions.
+```
+
+with:
+
+```
+libadwaita 1.8 or newer. The app refuses to start on older versions.
+```
+
+- [ ] **Step 6: Smoke-launch the app**
+
+Run: `timeout 4 python3 mount_manager.py` (in a desktop session). The app should launch and show its main window. Close it (or let the timeout kill it).
+
+Expected: No "libadwaita too old" message. App reaches the main window.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add mount_manager.py tests/test_libadwaita_support.py README.md
+git commit -m "feat: raise minimum libadwaita to 1.8"
+```
+
+---
+
+## Task 2: Swap `Gtk.Spinner` → `Adw.Spinner`
+
+**Files:**
+- Modify: `mount_manager_ui.py` — `AddShareDialog.__init__` host_spinner construction; `AddShareDialog._set_host_status`; `AddShareDialog._run_host_check`.
+
+`Adw.Spinner` (libadwaita 1.6) spins whenever it is realized and visible. It has no `start()` / `stop()` methods — those calls become no-ops on `Adw.Spinner` and would raise `AttributeError`. Replace the construction call and delete the explicit `start()` / `stop()` calls.
+
+- [ ] **Step 1: Swap the construction call**
+
+In `mount_manager_ui.py`, locate (inside `AddShareDialog.__init__`):
+
+```python
+ self.host_spinner = Gtk.Spinner()
+```
+
+Replace with:
+
+```python
+ self.host_spinner = Adw.Spinner()
+```
+
+- [ ] **Step 2: Drop the `stop()` call in `_set_host_status`**
+
+In `_set_host_status`, locate:
+
+```python
+ def _set_host_status(self, *, ok: bool | None, message: str) -> None:
+ self.host_spinner.set_visible(False)
+ self.host_spinner.stop()
+```
+
+Replace with:
+
+```python
+ def _set_host_status(self, *, ok: bool | None, message: str) -> None:
+ self.host_spinner.set_visible(False)
+```
+
+- [ ] **Step 3: Drop the `start()` call in `_run_host_check`**
+
+In `_run_host_check`, locate:
+
+```python
+ self.host_spinner.set_visible(True)
+ self.host_spinner.start()
+```
+
+Replace with:
+
+```python
+ self.host_spinner.set_visible(True)
+```
+
+- [ ] **Step 4: Run the smoke test**
+
+Run: `python3 -m unittest discover -s tests -v`
+
+Expected: 9 tests, all pass. (The smoke test `test_import_mount_manager` will catch any import-level break.)
+
+- [ ] **Step 5: Manual verification (executor or user)**
+
+Launch: `python3 mount_manager.py` → click "Add Share" → type a hostname (e.g. `192.0.2.1`, an unroutable address). The spinner appears next to the share-path field while the host check is in flight, then disappears and is replaced by an error icon. No `AttributeError` in stderr.
+
+(If the executor cannot reach a desktop session, document the verification as deferred to the user and proceed.)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "refactor(ui): use Adw.Spinner in Add Share dialog"
+```
+
+---
+
+## Task 3: Rewrite the shortcuts dialog using `Adw.ShortcutsDialog`
+
+**Files:**
+- Modify: `mount_manager_ui.py` — `build_shortcuts_window()` (helper inside `run_gui()`); `MountManagerApplication._show_shortcuts()`.
+
+`Adw.ShortcutsDialog` (libadwaita 1.8) replaces the deprecated `Gtk.ShortcutsWindow`. It extends `Adw.Dialog` (so it presents via `.present(parent)`, not `transient_for=`). Items can specify `action_name=` and the dialog auto-resolves the accelerator from `set_accels_for_action()` registered on the application — so we no longer duplicate accelerator literals here.
+
+- [ ] **Step 1: Replace the helper function**
+
+In `mount_manager_ui.py`, locate the entire `build_shortcuts_window` function inside `run_gui()`:
+
+```python
+ def build_shortcuts_window(parent: Gtk.Window) -> Gtk.ShortcutsWindow:
+ """Construct the keyboard shortcuts dialog for the app."""
+ window = Gtk.ShortcutsWindow(transient_for=parent, modal=True)
+
+ section = Gtk.ShortcutsSection(section_name="main", visible=True)
+
+ general = Gtk.ShortcutsGroup(title="General")
+ general.append(
+ Gtk.ShortcutsShortcut(title="Add Share", accelerator="n")
+ )
+ general.append(Gtk.ShortcutsShortcut(title="Refresh", accelerator="r"))
+ general.append(Gtk.ShortcutsShortcut(title="Primary Menu", accelerator="F10"))
+ general.append(
+ Gtk.ShortcutsShortcut(
+ title="Keyboard Shortcuts", accelerator="question"
+ )
+ )
+ general.append(
+ Gtk.ShortcutsShortcut(title="Close Window", accelerator="w")
+ )
+ general.append(Gtk.ShortcutsShortcut(title="Quit", accelerator="q"))
+ section.append(general)
+
+ window.add_section(section)
+ return window
+```
+
+Replace with:
+
+```python
+ def build_shortcuts_dialog() -> Adw.ShortcutsDialog:
+ """Construct the keyboard shortcuts dialog for the app."""
+ dialog = Adw.ShortcutsDialog()
+
+ general = Adw.ShortcutsSection(title="General")
+ general.add(Adw.ShortcutsItem(title="Add Share", action_name="win.add-share"))
+ general.add(Adw.ShortcutsItem(title="Refresh", action_name="win.refresh"))
+ general.add(Adw.ShortcutsItem(title="Primary Menu", action_name="win.show-menu"))
+ general.add(Adw.ShortcutsItem(title="Keyboard Shortcuts", action_name="app.shortcuts"))
+ general.add(Adw.ShortcutsItem(title="Close Window", action_name="win.close"))
+ general.add(Adw.ShortcutsItem(title="Quit", action_name="app.quit"))
+
+ dialog.add(general)
+ return dialog
+```
+
+(Note: the helper is renamed from `build_shortcuts_window` to `build_shortcuts_dialog` to match the new return type. Step 2 updates the only caller.)
+
+- [ ] **Step 2: Update `MountManagerApplication._show_shortcuts()`**
+
+In `mount_manager_ui.py`, locate (inside `MountManagerApplication`):
+
+```python
+ def _show_shortcuts(self) -> None:
+ window = self.props.active_window
+ if window is None:
+ return
+ shortcuts_window = build_shortcuts_window(window)
+ shortcuts_window.present()
+```
+
+Replace with:
+
+```python
+ def _show_shortcuts(self) -> None:
+ window = self.props.active_window
+ if window is None:
+ return
+ dialog = build_shortcuts_dialog()
+ dialog.present(window)
+```
+
+- [ ] **Step 3: Confirm no other references to the old name**
+
+Run: `grep -n "build_shortcuts_window\|Gtk.ShortcutsWindow\|Gtk.ShortcutsSection\|Gtk.ShortcutsGroup\|Gtk.ShortcutsShortcut" mount_manager_ui.py`
+
+Expected: no output. If anything matches, fix it before continuing.
+
+- [ ] **Step 4: Run the smoke test**
+
+Run: `python3 -m unittest discover -s tests -v`
+
+Expected: 9 tests, all pass.
+
+- [ ] **Step 5: Manual verification (executor or user)**
+
+Launch: `python3 mount_manager.py` → press `Ctrl+?`. A libadwaita-styled shortcuts dialog appears. Each row shows its accelerator (e.g. `Ctrl+N` next to "Add Share"); the accelerators are sourced automatically from `set_accels_for_action()`. No deprecation warnings in stderr.
+
+(If the executor cannot reach a desktop session, document the verification as deferred to the user and proceed.)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "refactor(ui): use Adw.ShortcutsDialog for keyboard shortcuts"
+```
+
+---
+
+## Task 4: Swap `xdg-open` subprocess → `Gtk.FileLauncher`
+
+**Files:**
+- Modify: `mount_manager_ui.py` — `MainWindow.open_mount_folder()`; possibly the `run_command` import at the top of the file.
+
+`Gtk.FileLauncher` (GTK 4.10) opens a file or folder with the desktop's default handler. It's async and reports failures via `GError` so we can distinguish user cancellation from real failures.
+
+- [ ] **Step 1: Rewrite `open_mount_folder` and add `_on_open_folder_done`**
+
+In `mount_manager_ui.py`, locate (inside `MainWindow`):
+
+```python
+ def open_mount_folder(self, record: ManagedMount) -> None:
+ if not record.mount_point.exists():
+ self.show_toast(f"Mount folder does not exist: {record.mount_point}")
+ return
+ try:
+ run_command(["xdg-open", str(record.mount_point)])
+ except MountManagerError as exc:
+ self.show_toast(f"Could not open {record.mount_point}: {exc}")
+```
+
+Replace with:
+
+```python
+ def open_mount_folder(self, record: ManagedMount) -> None:
+ if not record.mount_point.exists():
+ self.show_toast(f"Mount folder does not exist: {record.mount_point}")
+ return
+ launcher = Gtk.FileLauncher.new(Gio.File.new_for_path(str(record.mount_point)))
+ launcher.launch(self, None, self._on_open_folder_done)
+
+ def _on_open_folder_done(
+ self, launcher: Gtk.FileLauncher, result: Gio.AsyncResult
+ ) -> None:
+ try:
+ launcher.launch_finish(result)
+ except GLib.Error as exc:
+ if exc.matches(Gio.io_error_quark(), Gio.IOErrorEnum.CANCELLED):
+ return
+ self.show_toast(f"Could not open folder: {exc.message}")
+```
+
+- [ ] **Step 2: Check whether `run_command` is still used in `mount_manager_ui.py`**
+
+Run: `grep -n "run_command" mount_manager_ui.py`
+
+If the only remaining match is the import line at the top of the file, remove `run_command` from the import list.
+
+Locate (near the top of the file):
+
+```python
+from mount_manager import (
+ ...
+ run_command,
+ ...
+)
+```
+
+If `run_command` is no longer referenced anywhere else in the file, delete the ` run_command,` line from the import.
+
+- [ ] **Step 3: Run the smoke test**
+
+Run: `python3 -m unittest discover -s tests -v`
+
+Expected: 9 tests, all pass.
+
+- [ ] **Step 4: Static check — confirm the new symbols are imported**
+
+Run: `grep -nE "^from gi.repository" mount_manager_ui.py`
+
+Expected: the line already imports `Gio`, `GLib`, and `Gtk`, so no import changes are needed for the new code.
+
+- [ ] **Step 5: Manual verification (executor or user)**
+
+Launch: `python3 mount_manager.py`. With at least one managed mount enabled, click its folder icon. The system file manager opens at the mount point. If you have no managed mounts handy, skip the visible part of this check — the `unittest` smoke test will have already caught any Python-level breakage.
+
+(If the executor cannot reach a desktop session, document the verification as deferred to the user and proceed.)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "refactor(ui): open mount folders with Gtk.FileLauncher"
+```
+
+---
+
+## Task 5: Render mount rows as separate cards
+
+**Files:**
+- Modify: `mount_manager_ui.py` — `MainWindow.__init__` mount group construction.
+
+`AdwPreferencesGroup.set_separate_rows(True)` (libadwaita 1.6) renders each row as its own boxed card instead of a single grouped container. The empty state is unaffected (the `AdwStatusPage` is shown in place of the group when no mounts exist).
+
+- [ ] **Step 1: Add the `set_separate_rows` call**
+
+In `mount_manager_ui.py`, locate (inside `MainWindow.__init__`):
+
+```python
+ self.mount_group = Adw.PreferencesGroup()
+ self.preferences_page.add(self.mount_group)
+```
+
+Replace with:
+
+```python
+ self.mount_group = Adw.PreferencesGroup()
+ self.mount_group.set_separate_rows(True)
+ self.preferences_page.add(self.mount_group)
+```
+
+- [ ] **Step 2: Run the smoke test**
+
+Run: `python3 -m unittest discover -s tests -v`
+
+Expected: 9 tests, all pass.
+
+- [ ] **Step 3: Manual verification (executor or user)**
+
+Launch: `python3 mount_manager.py`. With at least one managed mount listed, each mount renders as its own card row rather than as a list inside a single bordered container.
+
+(If the executor cannot reach a desktop session, document the verification as deferred to the user and proceed.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "feat(ui): render mount rows as separate cards"
+```
+
+---
+
+## Final verification
+
+After all five tasks are committed:
+
+- [ ] **Run the full test suite:**
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+Expected: 9 tests, all pass.
+
+- [ ] **Verify the helper path is still GUI-free:**
+
+```bash
+python3 -X importtime mount_manager.py --helper set-enabled --manager-id never --enabled 0 2>&1 | grep -E "gi\.repository\.(Gtk|Adw)"
+```
+
+Expected: no matches. (Per `AGENTS.md`: the helper path must not import GTK/Adw.)
+
+The command will exit non-zero (the helper is unprivileged when not run via pkexec, so it'll bail) — that's expected. We only care that no GTK/Adw import showed up.
+
+- [ ] **Inspect commit history:**
+
+```bash
+git log --oneline -n 5
+```
+
+Expected: five new commits, one per task, on the `feat/libadwaita-01` branch.
+
+- [ ] **Verify no deprecation warnings when launching:**
+
+```bash
+timeout 4 python3 mount_manager.py 2>&1 | grep -iE "deprecat|warning" || echo "OK — no deprecations"
+```
+
+Expected: `OK — no deprecations`. (In particular, the `Gtk.ShortcutsWindow.add_section` deprecation noted at the end of the HIG-fixes plan should no longer appear.)
diff --git a/docs/plans/2026-05-28-libadwaita-migration.md b/docs/plans/2026-05-28-libadwaita-migration.md
new file mode 100644
index 0000000..f25e1bd
--- /dev/null
+++ b/docs/plans/2026-05-28-libadwaita-migration.md
@@ -0,0 +1,1368 @@
+# libadwaita UI Migration Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Migrate the Mount Manager GUI from plain GTK 4 widgets to libadwaita ≥ 1.5, splitting the UI code out of `mount_manager.py` into a new `mount_manager_ui.py` module.
+
+**Architecture:** In-place migration. `mount_manager.py` keeps data models, systemd/credentials plumbing, polkit handoff, and the `--helper` subprocess entry point. A new `mount_manager_ui.py` defines `Adw.Application`, `Adw.ApplicationWindow` (with `Adw.ToolbarView` + `Adw.ToastOverlay`), an `AddShareDialog(Adw.Dialog)`, an `Adw.AlertDialog`-based delete confirmation, and an `Adw.AboutDialog`. The custom `APP_CSS` and manual color-scheme detection are deleted in favor of `Adw.StyleManager`.
+
+**Tech Stack:** Python 3, PyGObject (`gi`), GTK 4, libadwaita ≥ 1.5, stdlib `unittest` for tests.
+
+**Spec reference:** `docs/specs/2026-05-28-libadwaita-migration-design.md`
+
+## Testing strategy
+
+This project has no existing test suite. We add stdlib `unittest` tests for the **pure-Python helpers** introduced or touched by this plan (`_libadwaita_supports`, `mount_status_line`). For the GTK/Adw widget construction we use **manual verification on a Bazzite host** because headless widget-tree assertions add little value and would require introducing Xvfb/`gi` to CI for no gain. Each task that builds widgets includes a concrete manual-verification checklist; tasks that introduce a pure helper include a real unittest.
+
+**Test command** (used throughout): `python3 -m unittest discover -s tests -v`
+**App run command** (used throughout): `python3 mount_manager.py`
+
+---
+
+## File Structure
+
+After this plan is complete:
+
+- `mount_manager.py` — data models, systemd/creds plumbing, `--helper` subprocess, `_libadwaita_supports()`, `main()`. **No GUI code.**
+- `mount_manager_ui.py` *(new)* — `gi.require_version("Adw","1")` at module level. Defines `ensure_libadwaita_supported`, `apply_style_manager`, `mount_status_line`, `MainWindow(Adw.ApplicationWindow)`, `AddShareDialog(Adw.Dialog)`, `DeleteAlertDialog` (factory returning `Adw.AlertDialog`), `MountManagerApplication(Adw.Application)`, and `run_gui()`.
+- `tests/` *(new)* — `__init__.py` (empty), `test_libadwaita_support.py`, `test_mount_status_line.py`.
+- `packaging/build-appimage.sh` — installs `mount_manager_ui.py` alongside `mount_manager.py`.
+- `README.md` — adds libadwaita requirement and updates manual-install commands.
+
+---
+
+## Task 1: Test scaffolding
+
+**Files:**
+- Create: `tests/__init__.py`
+- Create: `tests/test_smoke.py`
+
+This task establishes the test harness so later tasks can add real tests. It includes a single trivial smoke test that imports `mount_manager` to confirm the harness works.
+
+- [ ] **Step 1: Create empty `tests/__init__.py`**
+
+```bash
+mkdir -p tests
+: > tests/__init__.py
+```
+
+- [ ] **Step 2: Create `tests/test_smoke.py`**
+
+```python
+"""Smoke test ensuring the test harness can import the main module."""
+
+import unittest
+
+
+class ImportSmokeTest(unittest.TestCase):
+ def test_import_mount_manager(self) -> None:
+ import mount_manager # noqa: F401
+
+ self.assertTrue(hasattr(mount_manager, "main"))
+
+
+if __name__ == "__main__":
+ unittest.main()
+```
+
+- [ ] **Step 3: Run the test**
+
+Run: `python3 -m unittest discover -s tests -v`
+Expected output ends with `OK` and shows `test_import_mount_manager ... ok`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests/
+git commit -m "test: add unittest scaffolding with import smoke test"
+```
+
+---
+
+## Task 2: `_libadwaita_supports()` version check helper
+
+**Files:**
+- Modify: `mount_manager.py` (add helper near `MIN_SYSTEMD_VERSION`)
+- Create: `tests/test_libadwaita_support.py`
+
+Adds a pure comparator usable without `gi` so it can be unit-tested directly. The actual `ensure_libadwaita_supported()` (which reads `Adw.MAJOR_VERSION`/`Adw.MINOR_VERSION`) lives in the UI module and calls this.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test_libadwaita_support.py`:
+
+```python
+"""Unit tests for the libadwaita version comparator."""
+
+import unittest
+
+from mount_manager import _libadwaita_supports
+
+
+class LibadwaitaSupportsTest(unittest.TestCase):
+ def test_minimum_supported_version(self) -> None:
+ self.assertTrue(_libadwaita_supports(1, 5))
+
+ def test_newer_minor_supported(self) -> None:
+ self.assertTrue(_libadwaita_supports(1, 7))
+
+ def test_newer_major_supported(self) -> None:
+ self.assertTrue(_libadwaita_supports(2, 0))
+
+ def test_older_minor_unsupported(self) -> None:
+ self.assertFalse(_libadwaita_supports(1, 4))
+
+ def test_older_major_unsupported(self) -> None:
+ self.assertFalse(_libadwaita_supports(0, 99))
+
+
+if __name__ == "__main__":
+ unittest.main()
+```
+
+- [ ] **Step 2: Run the test to confirm it fails**
+
+Run: `python3 -m unittest tests.test_libadwaita_support -v`
+Expected: `ImportError: cannot import name '_libadwaita_supports' from 'mount_manager'`
+
+- [ ] **Step 3: Add the helper and a `MIN_LIBADWAITA_VERSION` constant**
+
+In `mount_manager.py`, locate the line `MIN_SYSTEMD_VERSION = 258` and insert immediately after it:
+
+```python
+# Adw.Dialog and Adw.AlertDialog require libadwaita 1.5 or newer.
+MIN_LIBADWAITA_VERSION: tuple[int, int] = (1, 5)
+
+
+def _libadwaita_supports(major: int, minor: int) -> bool:
+ """Return True if the given libadwaita (major, minor) meets the app's minimum."""
+ return (major, minor) >= MIN_LIBADWAITA_VERSION
+```
+
+- [ ] **Step 4: Run the test to confirm it passes**
+
+Run: `python3 -m unittest tests.test_libadwaita_support -v`
+Expected: all five tests pass, output ends with `OK`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add mount_manager.py tests/test_libadwaita_support.py
+git commit -m "feat: add libadwaita version comparator"
+```
+
+---
+
+## Task 3: Extract UI to `mount_manager_ui.py` (pure refactor)
+
+**Files:**
+- Create: `mount_manager_ui.py`
+- Modify: `mount_manager.py` (lines ~1148–1682: remove `import_gtk`, `apply_theme`, `run_gui` body, all nested UI classes)
+
+This is a **pure refactor with no UI behavior change**. We move the existing GTK widgets verbatim into a new module so subsequent tasks operate on a smaller file. `APP_CSS` and `apply_theme` move with the GUI code (they will be deleted in Task 4). Constants needed by the UI (`APP_NAME`, `APP_ID`, `APP_DEVELOPERS`, `APP_WEBSITE`, `APP_ICON_NAME`, `COLOR_SCHEME_ENV`) are imported from `mount_manager`.
+
+- [ ] **Step 1: Create `mount_manager_ui.py` with the extracted code**
+
+Create `mount_manager_ui.py` with:
+
+```python
+"""GTK 4 GUI for SMB Mount Manager.
+
+This module is imported lazily from ``mount_manager.run_gui``. Keeping it
+separate from ``mount_manager.py`` lets the helper subprocess avoid importing
+GTK when invoked with ``--helper``.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import gi
+
+gi.require_version("Gdk", "4.0")
+gi.require_version("Gtk", "4.0")
+gi.require_version("Pango", "1.0")
+from gi.repository import Gdk, Gio, Gtk, Pango # noqa: E402
+
+from mount_manager import (
+ APP_DEVELOPERS,
+ APP_ICON_NAME,
+ APP_ID,
+ APP_NAME,
+ APP_WEBSITE,
+ DisplayedMount,
+ ManagedMount,
+ MountManagerError,
+ SharePath,
+ check_smb_host_reachable,
+ detect_color_scheme,
+ load_displayed_mounts,
+ request_helper_create,
+ request_helper_delete,
+ request_helper_set_enabled,
+ request_helper_upgrade,
+ run_command,
+ validate_credentials,
+)
+
+
+APP_CSS = """
+# ... PASTE THE EXISTING APP_CSS STRING VERBATIM FROM mount_manager.py ...
+"""
+
+
+def apply_theme(Gtk: Any, Gdk: Any) -> None:
+ settings = Gtk.Settings.get_default()
+ if settings is not None:
+ settings.set_property(
+ "gtk-application-prefer-dark-theme",
+ detect_color_scheme() == "dark",
+ )
+
+ display = Gdk.Display.get_default()
+ if display is None:
+ return
+
+ Gtk.Window.set_default_icon_name(APP_ICON_NAME)
+
+ provider = Gtk.CssProvider()
+ provider.load_from_data(APP_CSS.encode("utf-8"))
+ Gtk.StyleContext.add_provider_for_display(
+ display,
+ provider,
+ Gtk.STYLE_PROVIDER_PRIORITY_APPLICATION,
+ )
+
+
+def run_gui() -> int:
+ if not Gtk.init_check():
+ print(
+ "GTK could not connect to your graphical session. Run this from your "
+ "desktop session, not a plain TTY.",
+ file=sys.stderr,
+ )
+ return 1
+ if Gdk.Display.get_default() is None:
+ print(
+ "GTK did not provide a usable display. Run this from your desktop "
+ "session, not a plain TTY.",
+ file=sys.stderr,
+ )
+ return 1
+ apply_theme(Gtk, Gdk)
+
+ # PASTE THE EXISTING NESTED CLASSES (AddShareWindow, MessageWindow,
+ # DeleteMountWindow, MainWindow, MountManagerApplication) VERBATIM HERE,
+ # AS NESTED CLASSES INSIDE run_gui — DO NOT REINDENT OR EDIT THEM.
+
+ app = MountManagerApplication()
+ return app.run(sys.argv)
+```
+
+Copy the exact text of `APP_CSS` (currently `mount_manager.py` lines 53–122) into the placeholder. Copy the exact nested class definitions from `mount_manager.py` (currently lines 1200–1679) into the `run_gui` body in place of the placeholder comment — preserve indentation.
+
+- [ ] **Step 2: Trim `mount_manager.py`**
+
+In `mount_manager.py`:
+
+1. Delete the `APP_CSS = """..."""` block (currently lines 53–122).
+2. Delete `import_gtk()` (currently lines 1148–1156).
+3. Delete `apply_theme(Gtk, Gdk)` (currently lines 1159–1179).
+4. Replace the entire body of `run_gui()` with:
+
+```python
+def run_gui() -> int:
+ from mount_manager_ui import run_gui as _run_gui
+
+ return _run_gui()
+```
+
+5. Leave the existing imports in `mount_manager.py` alone — leftover imports from removed code don't affect correctness and chasing them down here is risky. They can be cleaned up after the migration is verified.
+
+- [ ] **Step 3: Run the import smoke test**
+
+Run: `python3 -m unittest discover -s tests -v`
+Expected: all tests pass (smoke + libadwaita comparator). `OK`.
+
+- [ ] **Step 4: Manual verification — app still works**
+
+Run: `python3 mount_manager.py`
+Expected:
+- Main window opens with the same look as before this task (custom CSS still active, GTK header bar, "ADD SHARE" button visible).
+- Existing mounts are listed.
+- Add Share → Cancel works.
+- About menu entry opens the existing `Gtk.AboutDialog`.
+
+If anything is broken, fix the extraction (most likely cause: a missing import or a missed class reference between the nested classes).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add mount_manager.py mount_manager_ui.py
+git commit -m "refactor: split GUI code into mount_manager_ui module"
+```
+
+---
+
+## Task 4: Adw application bootstrap, version check, StyleManager
+
+**Files:**
+- Modify: `mount_manager_ui.py`
+
+We require libadwaita 1.5+, switch to `Adw.StyleManager`, and delete the custom CSS / theme code introduced by Task 3.
+
+- [ ] **Step 1: Add Adw imports and version-check function**
+
+At the top of `mount_manager_ui.py`, after `gi.require_version("Pango", "1.0")`, add:
+
+```python
+gi.require_version("Adw", "1")
+```
+
+Update the `from gi.repository` line to include `Adw`:
+
+```python
+from gi.repository import Adw, Gdk, Gio, Gtk, Pango # noqa: E402
+```
+
+Add to the imports from `mount_manager`:
+
+```python
+ MIN_LIBADWAITA_VERSION,
+ _libadwaita_supports,
+```
+
+Below the imports add:
+
+```python
+def ensure_libadwaita_supported() -> None:
+ """Print an error and raise SystemExit if libadwaita is too old."""
+ if not _libadwaita_supports(Adw.MAJOR_VERSION, Adw.MINOR_VERSION):
+ required = ".".join(str(v) for v in MIN_LIBADWAITA_VERSION)
+ found = f"{Adw.MAJOR_VERSION}.{Adw.MINOR_VERSION}"
+ print(
+ f"libadwaita {found} found, but this app requires {required} or newer.",
+ file=sys.stderr,
+ )
+ raise SystemExit(1)
+
+
+def apply_style_manager() -> None:
+ """Hand color-scheme selection to libadwaita's system preference tracker."""
+ Adw.StyleManager.get_default().set_color_scheme(Adw.ColorScheme.DEFAULT)
+ Gtk.Window.set_default_icon_name(APP_ICON_NAME)
+```
+
+- [ ] **Step 2: Delete `APP_CSS` and `apply_theme`**
+
+In `mount_manager_ui.py`, delete the whole `APP_CSS = """..."""` block and the `apply_theme(Gtk, Gdk)` function added during Task 3.
+
+- [ ] **Step 3: Replace the prelude of `run_gui`**
+
+Replace the existing `apply_theme(Gtk, Gdk)` call (and the `Gdk.Display.get_default()` check that came after `Gtk.init_check`) so the prelude reads:
+
+```python
+def run_gui() -> int:
+ ensure_libadwaita_supported()
+ if not Gtk.init_check():
+ print(
+ "GTK could not connect to your graphical session. Run this from your "
+ "desktop session, not a plain TTY.",
+ file=sys.stderr,
+ )
+ return 1
+ if Gdk.Display.get_default() is None:
+ print(
+ "GTK did not provide a usable display. Run this from your desktop "
+ "session, not a plain TTY.",
+ file=sys.stderr,
+ )
+ return 1
+ apply_style_manager()
+
+ # ... existing nested classes unchanged for now ...
+```
+
+- [ ] **Step 4: Convert the Application class**
+
+Inside `run_gui()`, change the `MountManagerApplication` definition (currently `class MountManagerApplication(Gtk.Application):`) to:
+
+```python
+ class MountManagerApplication(Adw.Application):
+ def __init__(self) -> None:
+ super().__init__(application_id=APP_ID, flags=Gio.ApplicationFlags.DEFAULT_FLAGS)
+
+ def do_activate(self) -> None:
+ window = self.props.active_window
+ if window is None:
+ window = MainWindow(self)
+ window.present()
+```
+
+The base class change is the only behavioral edit; `do_activate` is unchanged.
+
+- [ ] **Step 5: Manual verification**
+
+Run: `python3 mount_manager.py`
+Expected:
+- App still launches.
+- Window still shows the same content as before (we have not yet changed `MainWindow`).
+- Color scheme follows the system: switch GNOME's "Style" preference (Settings → Appearance) between Light and Dark; the window should follow without restart.
+- No custom CSS — the window background and header bar may look slightly different from the pre-Adw look; that is expected.
+
+- [ ] **Step 6: Run unit tests**
+
+Run: `python3 -m unittest discover -s tests -v`
+Expected: `OK`.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add mount_manager.py mount_manager_ui.py
+git commit -m "feat(ui): switch to Adw.Application and Adw.StyleManager"
+```
+
+---
+
+## Task 5: Adw.ApplicationWindow + ToolbarView + HeaderBar + ToastOverlay
+
+**Files:**
+- Modify: `mount_manager_ui.py` (the nested `MainWindow` class)
+
+Convert `MainWindow` to libadwaita's shell. The header bar gets an "Add Share" suggested-action button on the left and refresh + menu buttons on the right. A `Adw.ToastOverlay` is added around the content so later tasks can call `self.show_toast("…")`. The mount list rendering inside the window body is unchanged in this task (still `Gtk.ListBox` with `boxed-list`); Tasks 6–8 replace it.
+
+- [ ] **Step 1: Replace the `MainWindow` class header and constructor**
+
+Inside `run_gui()`, replace the existing `class MainWindow(Gtk.ApplicationWindow):` definition (constructor only — keep `refresh`, `row_for`, `show_add_dialog`, etc. unchanged for now) with:
+
+```python
+ class MainWindow(Adw.ApplicationWindow):
+ def __init__(self, app: Adw.Application) -> None:
+ super().__init__(application=app, title=APP_NAME)
+ self.set_default_size(760, 480)
+ self.set_icon_name(APP_ICON_NAME)
+
+ about_action = Gio.SimpleAction.new("about", None)
+ about_action.connect("activate", lambda _a, _p: self.show_about_dialog())
+ self.add_action(about_action)
+
+ menu = Gio.Menu()
+ menu.append(f"About {APP_NAME}", "win.about")
+
+ menu_button = Gtk.MenuButton(icon_name="open-menu-symbolic")
+ menu_button.set_menu_model(menu)
+ menu_button.set_tooltip_text("Main menu")
+
+ refresh_button = Gtk.Button.new_from_icon_name("view-refresh-symbolic")
+ refresh_button.set_tooltip_text("Refresh")
+ refresh_button.connect("clicked", lambda _b: self.refresh())
+
+ add_button = Gtk.Button(label="Add Share")
+ add_button.set_tooltip_text("Add share")
+ add_button.add_css_class("suggested-action")
+ add_button.connect("clicked", lambda _b: self.show_add_dialog())
+
+ header = Adw.HeaderBar()
+ header.pack_start(add_button)
+ header.pack_end(menu_button)
+ header.pack_end(refresh_button)
+
+ self.toast_overlay = Adw.ToastOverlay()
+
+ # Content area; Tasks 6-8 replace the list/empty children inside it.
+ self.content_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0)
+ self.toast_overlay.set_child(self.content_box)
+
+ self.empty_label = Gtk.Label(label="No SMB mounts found.")
+ self.empty_label.add_css_class("dim-label")
+ self.empty_label.set_margin_top(32)
+
+ self.list_box = Gtk.ListBox()
+ self.list_box.set_selection_mode(Gtk.SelectionMode.NONE)
+ self.list_box.add_css_class("boxed-list")
+
+ scroller = Gtk.ScrolledWindow()
+ scroller.set_policy(Gtk.PolicyType.NEVER, Gtk.PolicyType.AUTOMATIC)
+ scroller.set_child(self.list_box)
+ scroller.set_vexpand(True)
+ scroller.set_margin_top(16)
+ scroller.set_margin_bottom(16)
+ scroller.set_margin_start(16)
+ scroller.set_margin_end(16)
+
+ self.content_box.append(scroller)
+ self.content_box.append(self.empty_label)
+
+ toolbar_view = Adw.ToolbarView()
+ toolbar_view.add_top_bar(header)
+ toolbar_view.set_content(self.toast_overlay)
+ self.set_content(toolbar_view)
+
+ self.refresh()
+
+ def show_toast(self, message: str) -> None:
+ self.toast_overlay.add_toast(Adw.Toast(title=message))
+```
+
+Leave the remaining `MainWindow` methods (`refresh`, `row_for`, `show_add_dialog`, `show_about_dialog`, `mount_created`, `open_mount_folder`, `upgrade_mount`, `toggle_mount`, `confirm_delete`) unchanged. They still operate on `self.list_box` and `self.empty_label`.
+
+- [ ] **Step 2: Manual verification**
+
+Run: `python3 mount_manager.py`
+Expected:
+- Header bar shows "Add Share" (suggested-action, blue) on the left; refresh and menu buttons on the right.
+- Window title reads "SMB Mount Manager".
+- The mount list shows the same rows as before (we have not yet converted them).
+- Add Share dialog still opens (uses the unmodified `AddShareWindow` for now).
+- About menu still works (uses the unmodified `Gtk.AboutDialog`).
+- Refreshing works.
+
+- [ ] **Step 3: Run unit tests**
+
+Run: `python3 -m unittest discover -s tests -v`
+Expected: `OK`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "feat(ui): adopt Adw.ApplicationWindow with ToolbarView and ToastOverlay"
+```
+
+---
+
+## Task 6: `mount_status_line()` helper
+
+**Files:**
+- Modify: `mount_manager_ui.py` (add helper at module scope)
+- Create: `tests/test_mount_status_line.py`
+
+A pure helper that builds the subtitle string used by each `AdwActionRow`. Task 7 uses it.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test_mount_status_line.py`:
+
+```python
+"""Unit tests for the AdwActionRow subtitle builder."""
+
+import unittest
+from pathlib import Path
+
+from mount_manager import DisplayedMount
+
+
+def _mount(**overrides: object) -> DisplayedMount:
+ defaults = dict(
+ source="//host/share",
+ mount_point=Path("/mnt/mount-manager/share"),
+ status="Mounted",
+ active=True,
+ openable=True,
+ needs_upgrade=False,
+ managed=True,
+ managed_record=None,
+ )
+ defaults.update(overrides)
+ return DisplayedMount(**defaults) # type: ignore[arg-type]
+
+
+class MountStatusLineTest(unittest.TestCase):
+ def test_combines_mount_point_and_status(self) -> None:
+ from mount_manager_ui import mount_status_line
+
+ line = mount_status_line(_mount(status="Mounted"))
+ self.assertEqual(line, "/mnt/mount-manager/share · Mounted")
+
+ def test_idle_status(self) -> None:
+ from mount_manager_ui import mount_status_line
+
+ line = mount_status_line(_mount(status="Idle", active=False))
+ self.assertEqual(line, "/mnt/mount-manager/share · Idle")
+
+ def test_unmanaged_uses_unmanaged_status(self) -> None:
+ from mount_manager_ui import mount_status_line
+
+ line = mount_status_line(
+ _mount(
+ mount_point=Path("/mnt/elsewhere"),
+ status="Mounted (not managed)",
+ managed=False,
+ )
+ )
+ self.assertEqual(line, "/mnt/elsewhere · Mounted (not managed)")
+
+
+if __name__ == "__main__":
+ unittest.main()
+```
+
+- [ ] **Step 2: Run the test to confirm it fails**
+
+Run: `python3 -m unittest tests.test_mount_status_line -v`
+Expected: `ImportError: cannot import name 'mount_status_line' from 'mount_manager_ui'`.
+
+- [ ] **Step 3: Add the helper at module scope in `mount_manager_ui.py`**
+
+After the `apply_style_manager` function (and **outside** `run_gui`), add:
+
+```python
+def mount_status_line(mount: DisplayedMount) -> str:
+ """Build the AdwActionRow subtitle for a mount: `` · ``."""
+ return f"{mount.mount_point} \u00b7 {mount.status}"
+```
+
+- [ ] **Step 4: Run the test to confirm it passes**
+
+Run: `python3 -m unittest tests.test_mount_status_line -v`
+Expected: three tests pass, `OK`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add mount_manager_ui.py tests/test_mount_status_line.py
+git commit -m "feat(ui): add mount_status_line helper"
+```
+
+---
+
+## Task 7: Replace `row_for()` with `AdwPreferencesGroup` + `AdwActionRow`
+
+**Files:**
+- Modify: `mount_manager_ui.py` (`MainWindow` class)
+
+Replace the `boxed-list` `Gtk.ListBox` set up in Task 5 with an `Adw.PreferencesPage` containing one `Adw.PreferencesGroup`. Replace `row_for()` to return an `Adw.ActionRow` with the controls in the order: **switch, open-folder (or upgrade), kebab**. Unmanaged rows show a "Not managed" label and no controls.
+
+- [ ] **Step 1: Replace the list scaffolding inside `MainWindow.__init__`**
+
+In the body of `MainWindow.__init__` (the part added in Task 5), replace the `self.list_box`, `scroller`, and the calls that append them to `self.content_box` with:
+
+```python
+ self.preferences_page = Adw.PreferencesPage()
+ self.preferences_page.set_vexpand(True)
+
+ self.mount_group = Adw.PreferencesGroup()
+ self.mount_group.set_title("SMB Shares")
+ self.preferences_page.add(self.mount_group)
+
+ self.content_box.append(self.preferences_page)
+ self.content_box.append(self.empty_label)
+```
+
+The variables `self.list_box` and `scroller` no longer exist. Update `MainWindow.refresh` (next step) accordingly.
+
+- [ ] **Step 2: Rewrite `MainWindow.refresh`**
+
+Replace the existing `refresh` method body with:
+
+```python
+ def refresh(self) -> None:
+ child = self.mount_group.get_first_child()
+ # Remove any previously added rows. Adw.PreferencesGroup exposes them
+ # via .remove(); iterating with get_first_child() is the safe pattern.
+ rows_to_remove = []
+ row = child
+ while row is not None:
+ rows_to_remove.append(row)
+ row = row.get_next_sibling()
+ for row in rows_to_remove:
+ # Only ActionRow children we added belong here; leave internal
+ # widgets of the group untouched by filtering on the type we add.
+ if isinstance(row, Adw.ActionRow):
+ self.mount_group.remove(row)
+
+ mounts = load_displayed_mounts()
+ self.empty_label.set_visible(not mounts)
+ self.preferences_page.set_visible(bool(mounts))
+
+ for mount in mounts:
+ self.mount_group.add(self.row_for(mount))
+```
+
+> **Note:** `Adw.PreferencesGroup` keeps its title/description widgets internally; the `isinstance(row, Adw.ActionRow)` filter avoids accidentally removing them. If a future Adw release exposes `remove_all()`, that becomes a one-liner.
+
+- [ ] **Step 3: Rewrite `MainWindow.row_for`**
+
+Replace the existing `row_for` method with:
+
+```python
+ def row_for(self, mount: DisplayedMount) -> Adw.ActionRow:
+ row = Adw.ActionRow()
+ row.set_title(GLib_markup_escape(mount.source))
+ row.set_subtitle(GLib_markup_escape(mount_status_line(mount)))
+
+ if not mount.managed or mount.managed_record is None:
+ not_managed_label = Gtk.Label(label="Not managed")
+ not_managed_label.add_css_class("dim-label")
+ not_managed_label.set_valign(Gtk.Align.CENTER)
+ row.add_suffix(not_managed_label)
+ return row
+
+ record = mount.managed_record
+
+ mount_switch = Gtk.Switch()
+ mount_switch.set_valign(Gtk.Align.CENTER)
+ mount_switch.set_active(mount.active)
+ mount_switch.set_sensitive(not mount.needs_upgrade)
+ if mount.needs_upgrade:
+ mount_switch.set_tooltip_text("Upgrade this older mount before enabling it")
+ else:
+ mount_switch.set_tooltip_text(
+ "Enable or disable on-demand access for this managed mount"
+ )
+ mount_switch.connect(
+ "notify::active",
+ lambda switch, _param: self.toggle_mount(record, switch),
+ )
+ row.add_suffix(mount_switch)
+
+ if mount.needs_upgrade:
+ upgrade_button = Gtk.Button(label="Upgrade")
+ upgrade_button.set_valign(Gtk.Align.CENTER)
+ upgrade_button.set_tooltip_text(
+ "Upgrade mount units using the existing encrypted credentials"
+ )
+ upgrade_button.add_css_class("suggested-action")
+ upgrade_button.connect("clicked", lambda _b: self.upgrade_mount(record))
+ row.add_suffix(upgrade_button)
+ else:
+ open_button = Gtk.Button.new_from_icon_name("folder-open-symbolic")
+ open_button.set_valign(Gtk.Align.CENTER)
+ open_button.add_css_class("flat")
+ open_button.set_sensitive(mount.openable)
+ open_button.set_tooltip_text(
+ "Open mount folder"
+ if mount.openable
+ else "Enable on-demand access to open its folder"
+ )
+ open_button.connect("clicked", lambda _b: self.open_mount_folder(record))
+ row.add_suffix(open_button)
+
+ menu = Gio.Menu()
+ menu.append("Delete\u2026", f"row.delete::{record.manager_id}")
+
+ row_action_group = Gio.SimpleActionGroup()
+ delete_action = Gio.SimpleAction.new("delete", GLib_VariantType("s"))
+ delete_action.connect(
+ "activate", lambda _a, _p, r=record: self.confirm_delete(r)
+ )
+ row_action_group.add_action(delete_action)
+ row.insert_action_group("row", row_action_group)
+
+ menu_button = Gtk.MenuButton()
+ menu_button.set_valign(Gtk.Align.CENTER)
+ menu_button.set_icon_name("view-more-symbolic")
+ menu_button.add_css_class("flat")
+ menu_button.set_menu_model(menu)
+ menu_button.set_tooltip_text("More actions")
+ row.add_suffix(menu_button)
+
+ return row
+```
+
+- [ ] **Step 4: Add the small GLib helpers used above**
+
+At the **top** of `mount_manager_ui.py`, just under the existing `from gi.repository import …` line, add:
+
+```python
+from gi.repository import GLib # noqa: E402
+
+
+def GLib_markup_escape(text: str) -> str:
+ """Escape Pango markup characters in row titles/subtitles."""
+ return GLib.markup_escape_text(text, -1)
+
+
+def GLib_VariantType(spec: str) -> GLib.VariantType:
+ return GLib.VariantType.new(spec)
+```
+
+(These exist as tiny wrappers so the code reads cleanly.)
+
+- [ ] **Step 5: Manual verification**
+
+Run: `python3 mount_manager.py`
+Expected:
+- The mount list is rendered as a single boxed group titled "SMB Shares" with one row per mount.
+- Each managed row shows: source as title, "` · `" as subtitle, then on the right edge: switch, open-folder button (or "Upgrade" button if `needs_upgrade`), then a kebab (⋯) button.
+- Toggling the switch enables/disables on-demand access (verify with `systemctl status ` for one of your mounts).
+- Open folder still opens the mount target in the file manager.
+- Kebab → Delete… still opens the existing `DeleteMountWindow` (replaced in Task 10).
+- Unmanaged mounts (e.g. an SMB mount you created outside this app) show a "Not managed" label and no controls.
+- Switching system color scheme still toggles light/dark instantly.
+
+- [ ] **Step 6: Run unit tests**
+
+Run: `python3 -m unittest discover -s tests -v`
+Expected: `OK`.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "feat(ui): render mounts as AdwPreferencesGroup with AdwActionRow"
+```
+
+---
+
+## Task 8: `Adw.StatusPage` empty state
+
+**Files:**
+- Modify: `mount_manager_ui.py` (`MainWindow`)
+
+Replace the dim "No SMB mounts found." label with an `Adw.StatusPage` that includes an action button.
+
+- [ ] **Step 1: Replace `self.empty_label` setup**
+
+In `MainWindow.__init__`, remove the `self.empty_label = Gtk.Label(...)`, `add_css_class("dim-label")`, and `set_margin_top(32)` lines added earlier. Replace with:
+
+```python
+ self.empty_page = Adw.StatusPage()
+ self.empty_page.set_icon_name("folder-remote-symbolic")
+ self.empty_page.set_title("No SMB shares")
+ self.empty_page.set_description("Click Add Share to mount one.")
+ self.empty_page.set_vexpand(True)
+
+ empty_action = Gtk.Button(label="Add Share")
+ empty_action.set_halign(Gtk.Align.CENTER)
+ empty_action.add_css_class("suggested-action")
+ empty_action.add_css_class("pill")
+ empty_action.connect("clicked", lambda _b: self.show_add_dialog())
+ self.empty_page.set_child(empty_action)
+```
+
+Update the `content_box.append(self.empty_label)` line added in Task 7 to:
+
+```python
+ self.content_box.append(self.empty_page)
+```
+
+- [ ] **Step 2: Update `refresh()`**
+
+Replace `self.empty_label.set_visible(not mounts)` with:
+
+```python
+ self.empty_page.set_visible(not mounts)
+```
+
+- [ ] **Step 3: Manual verification**
+
+Run: `python3 mount_manager.py`
+Expected:
+- If you have any mounts, behavior is unchanged.
+- If you remove all mounts (delete them through the app), the empty status page appears centered with the folder-remote icon, the heading "No SMB shares", and a pill suggested-action "Add Share" button. Clicking it opens the Add Share flow.
+
+- [ ] **Step 4: Run unit tests**
+
+Run: `python3 -m unittest discover -s tests -v`
+Expected: `OK`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "feat(ui): replace empty label with Adw.StatusPage"
+```
+
+---
+
+## Task 9: `AddShareDialog(Adw.Dialog)` — single page, progressive reveal
+
+**Files:**
+- Modify: `mount_manager_ui.py` (`run_gui` body and `MainWindow.show_add_dialog`)
+
+Replace the existing `AddShareWindow(Gtk.Window)` class with `AddShareDialog(Adw.Dialog)`. The dialog uses a single `Adw.PreferencesPage` whose Credentials group is insensitive until the host check succeeds. The "Check host" button is replaced by an automatic debounced check (300 ms after the user stops typing). On success the dialog closes and the main window shows a toast. On failure inside the create flow, an `Adw.Banner` is shown in the dialog and the dialog stays open.
+
+- [ ] **Step 1: Replace the `AddShareWindow` definition**
+
+Inside `run_gui`, **delete** the entire `class AddShareWindow(Gtk.Window):` block. In its place add:
+
+```python
+ class AddShareDialog(Adw.Dialog):
+ def __init__(self, main_window: "MainWindow") -> None:
+ super().__init__()
+ self.set_title("Add SMB Share")
+ self.set_content_width(420)
+ self.main_window = main_window
+ self.share_path: SharePath | None = None
+ self._debounce_id: int = 0
+
+ self.cancel_button = Gtk.Button(label="Cancel")
+ self.cancel_button.connect("clicked", lambda _b: self.close())
+
+ self.add_button = Gtk.Button(label="Add")
+ self.add_button.add_css_class("suggested-action")
+ self.add_button.set_sensitive(False)
+ self.add_button.connect("clicked", lambda _b: self._on_add_clicked())
+
+ header = Adw.HeaderBar()
+ header.set_show_start_title_buttons(False)
+ header.set_show_end_title_buttons(False)
+ header.pack_start(self.cancel_button)
+ header.pack_end(self.add_button)
+
+ self.banner = Adw.Banner()
+ self.banner.set_revealed(False)
+
+ page = Adw.PreferencesPage()
+
+ share_group = Adw.PreferencesGroup()
+ share_group.set_title("Share")
+ page.add(share_group)
+
+ self.path_row = Adw.EntryRow()
+ self.path_row.set_title("Share path")
+ self.path_row.set_tooltip_text(
+ "Example: //192.168.1.2/sharename or //hostname/sharename"
+ )
+ self.path_row.connect("changed", lambda _r: self._on_path_changed())
+ share_group.add(self.path_row)
+
+ self.host_spinner = Gtk.Spinner()
+ self.host_spinner.set_valign(Gtk.Align.CENTER)
+ self.host_spinner.set_visible(False)
+ self.path_row.add_suffix(self.host_spinner)
+
+ self.host_status_icon = Gtk.Image()
+ self.host_status_icon.set_valign(Gtk.Align.CENTER)
+ self.host_status_icon.set_visible(False)
+ self.path_row.add_suffix(self.host_status_icon)
+
+ self.credentials_group = Adw.PreferencesGroup()
+ self.credentials_group.set_title("Credentials")
+ self.credentials_group.set_sensitive(False)
+ page.add(self.credentials_group)
+
+ self.user_row = Adw.EntryRow()
+ self.user_row.set_title("Username")
+ self.user_row.connect("changed", lambda _r: self._update_add_sensitive())
+ self.credentials_group.add(self.user_row)
+
+ self.password_row = Adw.PasswordEntryRow()
+ self.password_row.set_title("Password")
+ self.password_row.connect("changed", lambda _r: self._update_add_sensitive())
+ self.credentials_group.add(self.password_row)
+
+ body = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0)
+ body.append(self.banner)
+ body.append(page)
+
+ toolbar = Adw.ToolbarView()
+ toolbar.add_top_bar(header)
+ toolbar.set_content(body)
+ self.set_child(toolbar)
+
+ def _show_banner(self, message: str) -> None:
+ self.banner.set_title(message)
+ self.banner.set_revealed(True)
+
+ def _hide_banner(self) -> None:
+ self.banner.set_revealed(False)
+
+ def _set_host_status(self, *, ok: bool | None, message: str) -> None:
+ self.host_spinner.set_visible(False)
+ self.host_spinner.stop()
+ if ok is None:
+ self.host_status_icon.set_visible(False)
+ self.path_row.set_title("Share path")
+ return
+ if ok:
+ self.host_status_icon.set_from_icon_name("emblem-ok-symbolic")
+ else:
+ self.host_status_icon.set_from_icon_name("dialog-error-symbolic")
+ self.host_status_icon.set_visible(True)
+ self.host_status_icon.set_tooltip_text(message)
+
+ def _on_path_changed(self) -> None:
+ self.share_path = None
+ self.credentials_group.set_sensitive(False)
+ self._update_add_sensitive()
+ self._hide_banner()
+ self._set_host_status(ok=None, message="")
+ if self._debounce_id:
+ GLib.source_remove(self._debounce_id)
+ self._debounce_id = 0
+ text = self.path_row.get_text().strip()
+ if not text:
+ return
+ self._debounce_id = GLib.timeout_add(300, self._run_host_check)
+
+ def _run_host_check(self) -> bool:
+ self._debounce_id = 0
+ self.host_spinner.set_visible(True)
+ self.host_spinner.start()
+ try:
+ share_path = check_smb_host_reachable(self.path_row.get_text())
+ except MountManagerError as exc:
+ self._set_host_status(ok=False, message=str(exc))
+ return False
+ except Exception as exc:
+ self._set_host_status(ok=False, message=f"Unexpected error: {exc}")
+ return False
+
+ self.share_path = share_path
+ self._set_host_status(ok=True, message="Host is reachable")
+ self.credentials_group.set_sensitive(True)
+ self._update_add_sensitive()
+ return False # don't repeat the timeout
+
+ def _update_add_sensitive(self) -> None:
+ ready = (
+ self.share_path is not None
+ and bool(self.user_row.get_text().strip())
+ and bool(self.password_row.get_text())
+ )
+ self.add_button.set_sensitive(ready)
+
+ def _on_add_clicked(self) -> None:
+ if self.share_path is None:
+ return
+ share = self.share_path.source
+ username = self.user_row.get_text()
+ password = self.password_row.get_text()
+ try:
+ validate_credentials(username, password)
+ request_helper_create(share, username, password)
+ except MountManagerError as exc:
+ self._show_banner(str(exc))
+ return
+ except Exception as exc:
+ self._show_banner(f"Unexpected error: {exc}")
+ return
+
+ self.close()
+ self.main_window.refresh()
+ self.main_window.show_toast(f"{share} will mount when accessed.")
+```
+
+- [ ] **Step 2: Replace `MainWindow.show_add_dialog` and remove `MainWindow.mount_created`**
+
+In `MainWindow`, replace:
+
+```python
+ def show_add_dialog(self) -> None:
+ AddShareWindow(self, self.mount_created).present()
+```
+
+with:
+
+```python
+ def show_add_dialog(self) -> None:
+ AddShareDialog(self).present(self)
+```
+
+Delete the entire `mount_created` method — its work is now done inline by `AddShareDialog._on_add_clicked`.
+
+- [ ] **Step 3: Manual verification**
+
+Run: `python3 mount_manager.py`
+Expected:
+- Clicking "Add Share" presents an adaptive Adw dialog (desktop-style centered dialog on a desktop).
+- Typing in the share path triggers an automatic host check after ~300 ms: spinner appears at the end of the row, then a green check or red error icon. The error icon's tooltip explains the failure.
+- The Credentials group stays insensitive until the check passes.
+- Once credentials are filled, "Add" becomes active.
+- On success the dialog closes and the main window shows a toast at the bottom: "//host/share will mount when accessed."
+- On failure (e.g. wrong password) a banner appears at the top of the dialog with the error; dialog stays open; you can correct and retry.
+- Cancel closes the dialog with no side effects.
+
+- [ ] **Step 4: Run unit tests**
+
+Run: `python3 -m unittest discover -s tests -v`
+Expected: `OK`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "feat(ui): replace AddShareWindow with AdwDialog and progressive reveal"
+```
+
+---
+
+## Task 10: `Adw.AlertDialog` for delete confirmation
+
+**Files:**
+- Modify: `mount_manager_ui.py`
+
+Replace `DeleteMountWindow(Gtk.Window)` with an `Adw.AlertDialog`-based factory. Errors close the alert and surface as a toast in the main window.
+
+- [ ] **Step 1: Delete the existing `DeleteMountWindow` class**
+
+Inside `run_gui`, delete the entire `class DeleteMountWindow(Gtk.Window):` block.
+
+- [ ] **Step 2: Replace `MainWindow.confirm_delete`**
+
+In `MainWindow`, replace the existing `confirm_delete` method with:
+
+```python
+ def confirm_delete(self, record: ManagedMount) -> None:
+ alert = Adw.AlertDialog(
+ heading="Delete this SMB mount?",
+ body=(
+ f"Removes {record.source} and its systemd units. "
+ "The encrypted credentials will also be deleted."
+ ),
+ )
+ alert.add_response("cancel", "Cancel")
+ alert.add_response("delete", "Delete")
+ alert.set_response_appearance(
+ "delete", Adw.ResponseAppearance.DESTRUCTIVE
+ )
+ alert.set_default_response("cancel")
+ alert.set_close_response("cancel")
+ alert.connect("response", self._on_delete_response, record)
+ alert.present(self)
+
+ def _on_delete_response(
+ self, _alert: Adw.AlertDialog, response: str, record: ManagedMount
+ ) -> None:
+ if response != "delete":
+ return
+ try:
+ request_helper_delete(record)
+ except MountManagerError as exc:
+ self.show_toast(f"Delete failed: {exc}")
+ return
+ except Exception as exc:
+ self.show_toast(f"Delete failed: {exc}")
+ return
+ self.refresh()
+ self.show_toast(f"{record.source} removed.")
+```
+
+- [ ] **Step 3: Manual verification**
+
+Run: `python3 mount_manager.py`
+Expected:
+- Kebab → Delete… on a managed row opens an Adw alert dialog with two buttons: "Cancel" (default) and "Delete" (destructive red appearance).
+- Pressing Esc dismisses (cancel response).
+- Cancel does nothing.
+- Delete removes the mount, the list refreshes, and a toast appears: "//host/share removed."
+- Simulate a failure (e.g. temporarily revoke polkit auth or rename `/usr/bin/pkexec`): the alert closes and a toast shows "Delete failed: …".
+
+- [ ] **Step 4: Run unit tests**
+
+Run: `python3 -m unittest discover -s tests -v`
+Expected: `OK`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "feat(ui): replace DeleteMountWindow with Adw.AlertDialog"
+```
+
+---
+
+## Task 11: Replace `MessageWindow` with toasts + remove the class
+
+**Files:**
+- Modify: `mount_manager_ui.py`
+
+`MessageWindow` is no longer used by Add Share or Delete after Tasks 9 and 10. The remaining call sites are in `open_mount_folder`, `upgrade_mount`, and `toggle_mount`. Convert each to a toast. Delete the `MessageWindow` class.
+
+- [ ] **Step 1: Update `MainWindow.open_mount_folder`**
+
+Replace its body with:
+
+```python
+ def open_mount_folder(self, record: ManagedMount) -> None:
+ if not record.mount_point.exists():
+ self.show_toast(f"Mount folder does not exist: {record.mount_point}")
+ return
+ try:
+ run_command(["xdg-open", str(record.mount_point)])
+ except MountManagerError as exc:
+ self.show_toast(f"Could not open {record.mount_point}: {exc}")
+```
+
+- [ ] **Step 2: Update `MainWindow.upgrade_mount`**
+
+Replace its body with:
+
+```python
+ def upgrade_mount(self, record: ManagedMount) -> None:
+ try:
+ request_helper_upgrade(record)
+ except MountManagerError as exc:
+ self.show_toast(f"Upgrade failed: {exc}")
+ return
+ except Exception as exc:
+ self.show_toast(f"Upgrade failed: {exc}")
+ return
+ self.refresh()
+ self.show_toast(f"{record.source} upgraded; will mount when accessed.")
+```
+
+- [ ] **Step 3: Update `MainWindow.toggle_mount`**
+
+Replace its body with:
+
+```python
+ def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None:
+ enabled = switch.get_active()
+ switch.set_sensitive(False)
+ try:
+ request_helper_set_enabled(record, enabled)
+ except MountManagerError as exc:
+ self.show_toast(f"Toggle failed: {exc}")
+ except Exception as exc:
+ self.show_toast(f"Toggle failed: {exc}")
+ finally:
+ self.refresh()
+```
+
+- [ ] **Step 4: Delete the `MessageWindow` class**
+
+Inside `run_gui`, delete the entire `class MessageWindow(Gtk.Window):` block.
+
+- [ ] **Step 5: Manual verification**
+
+Run: `python3 mount_manager.py`
+Expected:
+- Successful upgrade → toast "//host/share upgraded; will mount when accessed."
+- Toggling a switch off then on works without modal interruption; failures surface as toasts.
+- Open folder failure (try renaming the mount target) shows a toast, not a window.
+- No remaining references to `MessageWindow` (verify with `grep MessageWindow mount_manager_ui.py` — should return nothing).
+
+- [ ] **Step 6: Run unit tests**
+
+Run: `python3 -m unittest discover -s tests -v`
+Expected: `OK`.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "feat(ui): replace MessageWindow with AdwToast notifications"
+```
+
+---
+
+## Task 12: `Adw.AboutDialog`
+
+**Files:**
+- Modify: `mount_manager_ui.py` (`MainWindow.show_about_dialog`)
+
+- [ ] **Step 1: Replace `show_about_dialog`**
+
+Replace the existing `show_about_dialog` method on `MainWindow` with:
+
+```python
+ def show_about_dialog(self) -> None:
+ about = Adw.AboutDialog(
+ application_name=APP_NAME,
+ application_icon=APP_ICON_NAME,
+ developer_name=APP_DEVELOPERS[0] if APP_DEVELOPERS else "",
+ website=APP_WEBSITE,
+ issue_url=f"{APP_WEBSITE}/issues",
+ license_type=Gtk.License.GPL_3_0_ONLY,
+ comments="Create and manage on-demand SMB mounts.",
+ )
+ about.set_developers(APP_DEVELOPERS)
+ about.present(self)
+```
+
+- [ ] **Step 2: Manual verification**
+
+Run: `python3 mount_manager.py`
+Expected:
+- Menu → "About SMB Mount Manager" presents the modern Adw about dialog with the app icon, name, version-less header (Adw shows the application_name), developer credit, website link, and license tab.
+- No deprecation warning in stderr about `Gtk.AboutDialog`.
+
+- [ ] **Step 3: Run unit tests**
+
+Run: `python3 -m unittest discover -s tests -v`
+Expected: `OK`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add mount_manager_ui.py
+git commit -m "feat(ui): use Adw.AboutDialog"
+```
+
+---
+
+## Task 13: Packaging and README updates
+
+**Files:**
+- Modify: `packaging/build-appimage.sh`
+- Modify: `README.md`
+
+- [ ] **Step 1: Update `packaging/build-appimage.sh`**
+
+The AppImage installs `mount_manager.py` to `$appdir/usr/bin/mount-manager` (the executable script). When Python runs that script, `sys.path[0]` is `/usr/bin` (the script's directory), so placing `mount_manager_ui.py` in the same directory makes `import mount_manager_ui` resolve correctly without a shim.
+
+In `packaging/build-appimage.sh`, immediately after the line:
+
+```bash
+install -D -m 0755 "$repo_root/mount_manager.py" "$appdir/usr/bin/mount-manager"
+```
+
+(currently line 90), add:
+
+```bash
+install -D -m 0644 "$repo_root/mount_manager_ui.py" "$appdir/usr/bin/mount_manager_ui.py"
+```
+
+No other build-script changes are needed. The patch in `packaging/appimage-helper.patch` only touches `mount-manager` (the renamed `mount_manager.py`) and is unaffected by the new file, because the privileged helper subprocess does not import the UI module.
+
+- [ ] **Step 2: Update `README.md` requirements section**
+
+In `README.md`, find the "Requirements" section. After the line about systemd 258, add:
+
+```markdown
+libadwaita 1.5 or newer. The app refuses to start on older versions.
+```
+
+- [ ] **Step 3: Update `README.md` install commands**
+
+In the "Test as an installed app on Bazzite" section, find the block of `sudo install -D …` commands. Immediately after the existing line for `mount_manager.py`, add:
+
+```bash
+sudo install -D -m 0644 mount_manager_ui.py /usr/bin/mount_manager_ui.py
+```
+
+This places the UI module next to the executable so `python3 /usr/bin/mount-manager` can import it (Python adds the script's directory to `sys.path` automatically).
+
+- [ ] **Step 4: Manual verification**
+
+Run the README's documented install commands on a Bazzite test host (or VM). Verify `mount-manager` launches with the new Adw UI from the installed path. Confirm `which mount-manager` still resolves and `mount-manager --helper create < input` still works as a privileged subprocess (the helper code path is unchanged but the import path must resolve when re-execed under pkexec).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packaging/build-appimage.sh README.md
+git commit -m "build: include mount_manager_ui in packaging and document libadwaita requirement"
+```
+
+---
+
+## Final verification
+
+- [ ] **Run the full test suite**
+
+Run: `python3 -m unittest discover -s tests -v`
+Expected: all tests pass.
+
+- [ ] **End-to-end smoke on Bazzite**
+
+Run `python3 mount_manager.py` from a desktop session and exercise every flow:
+1. Empty state appears when there are no mounts; clicking "Add Share" from the empty state opens the dialog.
+2. Add a real share end-to-end → toast on success → row appears.
+3. Toggle the switch → systemctl reports the automount unit enabled/disabled accordingly.
+4. Open folder works.
+5. Delete confirmation works and surfaces toast on success.
+6. Failure paths surface toasts/banners as documented.
+7. Color scheme follows system preference.
+8. About dialog shows Adw layout.
+
+- [ ] **Grep for orphaned references**
+
+Run: `grep -nE 'MessageWindow|AddShareWindow|DeleteMountWindow|APP_CSS|apply_theme' mount_manager.py mount_manager_ui.py`
+Expected: no matches in either file.
+
+Run: `grep -nE 'Gtk\.AboutDialog' mount_manager.py mount_manager_ui.py`
+Expected: no matches.
diff --git a/docs/specs/2026-05-28-hig-fixes-design.md b/docs/specs/2026-05-28-hig-fixes-design.md
new file mode 100644
index 0000000..2e98b40
--- /dev/null
+++ b/docs/specs/2026-05-28-hig-fixes-design.md
@@ -0,0 +1,224 @@
+# GNOME HIG audit — SMB Mount Manager
+
+Date: 2026-05-28
+Scope: Full sweep of the libadwaita UI on branch `feat/libadwaita-01`.
+Reference: https://developer.gnome.org/hig/index.html
+
+Findings are organized by severity. Each cites the HIG page it draws from so it
+can be split into individual GitHub issues without losing context.
+
+---
+
+## Critical
+
+*(None.)* The app respects the big architectural HIG choices: `AdwApplicationWindow`
++ `AdwToolbarView` + `AdwToastOverlay`, hybrid `AdwActionRow` pattern,
+`AdwStatusPage` empty state, `AdwAlertDialog` for destructive confirmation,
+`AdwAboutDialog` with proper metadata, color scheme delegated to
+`Adw.StyleManager`.
+
+---
+
+## Major
+
+### M1. No keyboard shortcuts at all
+
+**HIG:** `guidelines/keyboard.html`, `reference/keyboard.html`
+
+Every common action should be keyboard-reachable and standard accelerators
+should be wired up. Currently the app has zero accelerators.
+
+Missing, at minimum:
+
+- `Ctrl+W` — close window
+- `Ctrl+Q` — quit
+- `Ctrl+N` — Add Share (closest standard mapping for "create new item")
+- `Ctrl+R` — refresh
+- `F10` — primary menu
+- `Ctrl+?` — Keyboard Shortcuts dialog
+
+And the supporting UI:
+
+- A `Gtk.ShortcutsWindow` describing the above.
+- A "Keyboard Shortcuts" entry in the primary menu.
+
+Also: when the AddShareDialog opens, no widget has explicit initial focus
+(see m5).
+
+### M2. Suggested-action label-only button in a primary-window header bar
+
+**HIG:** `patterns/containers/header-bars.html` → Button Style
+
+> Types of buttons which don't automatically have their appearance adjusted
+> when in a header bar include buttons with: a text label only;
+> the suggested and destructive action styles … These button types should
+> generally be avoided for primary window header bars, since it leads to a
+> complex and inconsistent visual appearance.
+
+The header-bar "Add Share" button has both attributes. Fix:
+
+- Add an icon (e.g. `list-add-symbolic`) so the button is icon+label.
+- Drop the `suggested-action` CSS class on the header copy.
+- Keep the empty-state pill button as the lone suggested-action CTA.
+
+### M3. Two suggested-action buttons visible simultaneously in the empty state
+
+**HIG:** `patterns/controls/buttons.html` → Suggested & Destructive Actions
+
+> Each view should only ever include a single button using either the
+> suggested or destructive styles.
+
+In the empty state, both the header-bar "Add Share" and the pill "Add Share"
+on the `AdwStatusPage` carry `suggested-action`. Fixing M2 (drop suggested
+from the header button) also fixes this.
+
+---
+
+## Minor
+
+### m1. Toast titles end with periods
+
+**HIG:** `guidelines/writing-style.html` → Periods; `patterns/feedback/toasts.html` →
+toasts use the informal heading style.
+
+> Text generally shouldn't end with a period.
+
+Affected strings in `mount_manager_ui.py`:
+
+- `f"{share} added."`
+- `f"{record.source} removed."`
+- `f"{record.source} upgraded."`
+- All `f"… failed: {exc}"` toasts and the "Mount folder does not exist: …" toast.
+
+Drop the trailing period from every toast title.
+
+### m2. Empty-state description uses Pango italics
+
+`empty_page.set_description("Click Add Share to mount one.")` renders the
+button name in italics. Italic emphasis is not an HIG pattern for
+`AdwStatusPage` descriptions. Use plain text:
+
+> `Click "Add Share" to mount one`
+
+(Note: also drop the trailing period per m1.)
+
+### m3. Header-bar "Add Share" tooltip duplicates the label
+
+**HIG:** Tooltips should add information, not echo the label.
+
+Current: button label `"Add Share"`, tooltip `"Add share"`. Either remove the
+tooltip or change it to add value — e.g. `"Mount a new SMB share"`.
+
+### m4. Primary menu tooltip says "Main menu"
+
+**HIG:** standard terminology is "Primary menu." Change the
+`open-menu-symbolic` `MenuButton` tooltip from `"Main menu"` to
+`"Primary menu"`.
+
+### m5. AddShareDialog does not set a default widget / initial focus
+
+**HIG:** `patterns/feedback/dialogs.html`
+
+> Assign the return key to activate the affirmative button. However, this
+> should not be done if its action is irreversible, destructive or otherwise
+> inconvenient to the user.
+> When opening a dialog, provide initial keyboard focus to the component that
+> you expect users to operate first.
+
+Currently neither is done. Add:
+
+- `self.set_default_widget(self.add_button)` so Enter in the password field
+ submits.
+- Explicit focus on `self.path_row` when the dialog presents.
+
+### m6. AlertDialog affirmative button labelled "Delete"
+
+**HIG:** `patterns/feedback/dialogs.html`
+
+> Label the affirmative button with a specific imperative verb.
+
+Borderline — the dialog heading ("Delete this SMB mount?") carries the object.
+`"Delete Share"` or `"Remove Mount"` is more in line with the guideline. Low
+priority; mention if revisiting that dialog.
+
+### m7. Mount group title `"SMB Shares"` duplicates the window title context
+
+The window is already "SMB Mount Manager." Single-group preferences pages
+typically omit the group title, or use a neutral one. Consider dropping it or
+renaming to `"Mounts"`.
+
+---
+
+## Nits
+
+### n1. Legacy icon names
+
+`emblem-ok-symbolic` → `checkmark-symbolic`
+`dialog-error-symbolic` → `error-symbolic`
+
+Both legacy names still resolve; the new names are more idiomatic in fresh
+GTK4 / libadwaita code.
+
+### n2. Empty-state icon
+
+`folder-remote-symbolic` is fine but `network-server-symbolic` is arguably a
+better match for SMB. Subjective.
+
+### n3. Redundant calls in AddShareDialog header
+
+`self._header.set_show_start_title_buttons(False)` and
+`set_show_end_title_buttons(False)` are redundant — `AdwDialog` already manages
+its title-bar buttons.
+
+### n4. About dialog has overlapping developer fields
+
+`AdwAboutDialog` is constructed with both
+`developer_name=APP_DEVELOPERS[0]` and then `set_developers(APP_DEVELOPERS)`.
+Both end up populated; pick one form per role (`developer_name` is the
+single-line credit, `developers` is the list shown on the credits page).
+
+---
+
+## Intentionally non-compliant (justified)
+
+### Destructive Delete uses confirmation, not undo
+
+**HIG:** `patterns/feedback/dialogs.html` → Confirmation Dialogs
+
+> Undo is typically a better option than a confirmation dialog.
+
+Undoing delete here would require re-creating the systemd units and
+re-decrypting credentials — non-trivial. Confirmation is the right call. Worth
+being explicit in the code so future contributors understand why this path was
+chosen.
+
+---
+
+## Strengths (for completeness)
+
+- `AdwApplicationWindow` + `AdwToolbarView` + `AdwToastOverlay` shell.
+- Hybrid `AdwActionRow` pattern (switch + single inline suffix + kebab menu).
+- `AdwStatusPage` empty state with a clear primary CTA.
+- `AdwAlertDialog` with `DESTRUCTIVE` response appearance, `cancel` set as both
+ default and close response.
+- `AdwAboutDialog` with developers, website, issue URL, license type.
+- Color scheme delegated to `Adw.StyleManager.ColorScheme.DEFAULT` (respects
+ system preference; no custom CSS).
+- Debounced host check with `Gio.Cancellable` and explicit `GLib.source_remove`
+ on dialog close — no race between debounce, worker thread, and dialog
+ teardown.
+- All user-controlled strings escaped with `GLib.markup_escape_text` before
+ being rendered as Pango markup.
+
+---
+
+## Suggested ordering when filing issues
+
+1. M1 — keyboard shortcuts + shortcuts window (largest accessibility gap)
+2. M2 + M3 — header-bar Add Share style (small fix, fixes both)
+3. m1 — toast period sweep
+4. m2 — empty-state description
+5. m3 + m4 — tooltip copy
+6. m5 — AddShareDialog default widget + initial focus
+7. m6, m7 — copy refinements
+8. n1–n4 — opportunistic cleanups
diff --git a/docs/specs/2026-05-28-libadwaita-1.8-bump-design.md b/docs/specs/2026-05-28-libadwaita-1.8-bump-design.md
new file mode 100644
index 0000000..abdfd86
--- /dev/null
+++ b/docs/specs/2026-05-28-libadwaita-1.8-bump-design.md
@@ -0,0 +1,284 @@
+# Libadwaita 1.8 Baseline Bump — Design
+
+**Date:** 2026-05-28
+**Branch:** `feat/libadwaita-01` (pre-merge)
+**Status:** Approved by user; ready for implementation plan.
+
+## Goal
+
+Raise the minimum libadwaita to 1.8 and opportunistically adopt newer APIs
+made possible by the bump (`Adw.Spinner`, `Adw.ShortcutsDialog`). Also
+modernize the "open folder" path off `xdg-open` onto `Gtk.FileLauncher`
+(GTK 4.10) while we're touching the stack. This keeps the floor in line
+with current GNOME, clears the accepted `Gtk.ShortcutsWindow` deprecation
+noted at the end of the HIG-fixes plan, and removes a subprocess wart.
+
+## Scope
+
+Five coupled changes:
+
+1. **Bump the floor.** `MIN_LIBADWAITA_VERSION: tuple[int, int] = (1, 5)` →
+ `(1, 8)` in `mount_manager.py`. Update the comment above it (currently
+ "Adw.Dialog and Adw.AlertDialog require libadwaita 1.5 or newer") to
+ reflect what 1.8 buys us.
+
+2. **`Gtk.Spinner` → `Adw.Spinner`** (libadwaita 1.6) inside
+ `AddShareDialog`. `Adw.Spinner` spins whenever it is visible, so the
+ `start()` / `stop()` calls in `_set_host_status` and `_run_host_check` can
+ be deleted entirely — `set_visible(True/False)` is sufficient.
+
+3. **`Gtk.ShortcutsWindow` family → `Adw.ShortcutsDialog` family**
+ (libadwaita 1.8) inside `build_shortcuts_window()`. The replacement uses
+ `Adw.ShortcutsDialog.add(section)` with `Adw.ShortcutsSection(title=...)`
+ containing `Adw.ShortcutsItem` children. The new API lets each item refer
+ to an action by name (`action_name="app.quit"`) and libadwaita
+ auto-discovers the accelerator from `set_accels_for_action`, so we no
+ longer have to repeat each accelerator literal. Resolves the deprecation
+ note from Task 6 of the HIG-fixes plan.
+
+4. **`xdg-open` subprocess → `Gtk.FileLauncher`** (GTK 4.10) inside
+ `MainWindow.open_mount_folder()`. The current implementation shells out
+ to `xdg-open` via `run_command`, which collapses every failure mode
+ into a generic `MountManagerError`. `Gtk.FileLauncher.launch()` is
+ async, integrates with the desktop's URI launcher (and portals where
+ applicable), and reports failure via a proper `GError` we can show as a
+ toast.
+
+5. **`AdwPreferencesGroup.set_separate_rows(True)`** (libadwaita 1.6) on
+ the mount list group in `MainWindow`. Renders each mount as its own
+ boxed card row instead of a single grouped container. Visually
+ confirmed to read better than the grouped style for this list. One
+ line in `MainWindow.__init__`. No change needed for the empty state
+ (the `AdwStatusPage` is shown instead of the group when there are no
+ mounts).
+
+## Out of scope
+
+- Adoption of any other 1.6–1.8 API (`AdwBottomSheet`, `AdwMultiLayoutView`,
+ `AdwInlineViewSwitcher`, `AdwButtonRow`, `AdwToggleGroup`). These have no
+ current pull from the codebase and will be considered as needs arise.
+- Refactoring the hybrid `AdwActionRow` mount-row pattern to use
+ `AdwSwitchRow`. The hybrid pattern was a deliberate design choice from
+ the libadwaita migration; switching now would unwind that. Out of scope.
+
+## Files touched
+
+| File | Change |
+|------|--------|
+| `mount_manager.py` | Version constant + the comment above it. ~2 lines. |
+| `mount_manager_ui.py` | `Adw.Spinner` swap (~3 lines, net simpler). `build_shortcuts_window()` rewrite (~30 lines net). `open_mount_folder()` swap to `Gtk.FileLauncher` (~10 lines). `mount_group.set_separate_rows(True)` (1 line). |
+| `README.md` | "libadwaita 1.5 or newer" → "libadwaita 1.8 or newer" (line 27). |
+| `tests/test_libadwaita_support.py` | Rebase fixture values on `(1, 8)` — e.g. `older_minor=(1, 7)`, `newer_minor=(1, 9)`, `newer_major=(2, 0)`, etc. |
+| `AGENTS.md` | No change. It already says `MIN_LIBADWAITA_VERSION` is the single source of truth and never hardcodes a number. |
+
+## Detailed API notes
+
+### Adw.Spinner (1.6)
+
+`Adw.Spinner` is a `Gtk.Widget` subclass with no methods of its own
+(inherited GObject only). It spins continuously when realized and visible.
+No `start()` / `stop()`. Sizing follows allocation, never smaller than
+16×16, never larger than 64×64. As an `EntryRow` suffix the row's natural
+height will allocate appropriately; no `width-request`/`height-request`
+needed.
+
+Current usage in `AddShareDialog`:
+
+```python
+self.host_spinner = Gtk.Spinner()
+self.host_spinner.set_valign(Gtk.Align.CENTER)
+self.host_spinner.set_visible(False)
+self.path_row.add_suffix(self.host_spinner)
+# …
+self.host_spinner.set_visible(False)
+self.host_spinner.stop()
+# …
+self.host_spinner.set_visible(True)
+self.host_spinner.start()
+```
+
+After:
+
+```python
+self.host_spinner = Adw.Spinner()
+self.host_spinner.set_valign(Gtk.Align.CENTER)
+self.host_spinner.set_visible(False)
+self.path_row.add_suffix(self.host_spinner)
+# …
+self.host_spinner.set_visible(False)
+# …
+self.host_spinner.set_visible(True)
+```
+
+### Adw.ShortcutsDialog (1.8)
+
+`Adw.ShortcutsDialog` extends `Adw.Dialog` (so it presents via `.present(parent)`,
+not `transient_for=`). Sections are added with `dialog.add(section)`. Items
+within a section can specify either `accelerator=` (literal) or
+`action_name=` (auto-resolves the accelerator from
+`set_accels_for_action`).
+
+Current usage in `build_shortcuts_window()`:
+
+```python
+window = Gtk.ShortcutsWindow(transient_for=parent, modal=True)
+section = Gtk.ShortcutsSection(section_name="main", visible=True)
+general = Gtk.ShortcutsGroup(title="General")
+general.add_shortcut(Gtk.ShortcutsShortcut(title="Add Share", accelerator="n"))
+# … five more shortcuts with literal accelerators …
+section.add_group(general)
+window.add_section(section)
+return window
+```
+
+After (new function name reflects the new return type):
+
+```python
+def build_shortcuts_dialog() -> Adw.ShortcutsDialog:
+ """Construct the keyboard shortcuts dialog for the app."""
+ dialog = Adw.ShortcutsDialog()
+
+ general = Adw.ShortcutsSection(title="General")
+ general.add(Adw.ShortcutsItem(title="Add Share", action_name="win.add-share"))
+ general.add(Adw.ShortcutsItem(title="Refresh", action_name="win.refresh"))
+ general.add(Adw.ShortcutsItem(title="Primary Menu", action_name="win.show-menu"))
+ general.add(Adw.ShortcutsItem(title="Keyboard Shortcuts", action_name="app.shortcuts"))
+ general.add(Adw.ShortcutsItem(title="Close Window", action_name="win.close"))
+ general.add(Adw.ShortcutsItem(title="Quit", action_name="app.quit"))
+
+ dialog.add(general)
+ return dialog
+```
+
+The `_show_shortcuts()` method in `MountManagerApplication` changes from
+`shortcuts_window.present()` (no parent) to
+`shortcuts_dialog.present(window)` (AdwDialog requires a parent):
+
+```python
+def _show_shortcuts(self) -> None:
+ window = self.props.active_window
+ if window is None:
+ return
+ dialog = build_shortcuts_dialog()
+ dialog.present(window)
+```
+
+**Action-name auto-discovery prerequisites:** The actions
+(`win.add-share`, `win.refresh`, `win.show-menu`, `win.close`,
+`app.shortcuts`, `app.quit`) and their accelerators must already be
+registered via `set_accels_for_action()` before the dialog is built.
+They are — both `MountManagerApplication.__init__` (`app.*`) and
+`MainWindow.__init__` (`win.*`) run before any `Ctrl+?` press.
+
+### Gtk.FileLauncher (GTK 4.10)
+
+`Gtk.FileLauncher` opens a file or folder with the desktop's default
+handler. Constructed from a `Gio.File`, launched async with a parent
+window for modality, completed via a `GAsyncReadyCallback`. Errors come
+back as `GError` from `launch_finish()`, so we get distinct failure
+reasons (cancelled, no handler, permission denied) instead of a single
+`MountManagerError` from a subprocess exit code.
+
+Current usage in `MainWindow.open_mount_folder`:
+
+```python
+def open_mount_folder(self, record: ManagedMount) -> None:
+ if not record.mount_point.exists():
+ self.show_toast(f"Mount folder does not exist: {record.mount_point}")
+ return
+ try:
+ run_command(["xdg-open", str(record.mount_point)])
+ except MountManagerError as exc:
+ self.show_toast(f"Could not open {record.mount_point}: {exc}")
+```
+
+After:
+
+```python
+def open_mount_folder(self, record: ManagedMount) -> None:
+ if not record.mount_point.exists():
+ self.show_toast(f"Mount folder does not exist: {record.mount_point}")
+ return
+ launcher = Gtk.FileLauncher.new(Gio.File.new_for_path(str(record.mount_point)))
+ launcher.launch(self, None, self._on_open_folder_done)
+
+def _on_open_folder_done(
+ self, launcher: Gtk.FileLauncher, result: Gio.AsyncResult
+) -> None:
+ try:
+ launcher.launch_finish(result)
+ except GLib.Error as exc:
+ # Gio.IOErrorEnum.CANCELLED is the user dismissing a portal/handler
+ # dialog; not worth a toast.
+ if exc.matches(Gio.io_error_quark(), Gio.IOErrorEnum.CANCELLED):
+ return
+ self.show_toast(f"Could not open folder: {exc.message}")
+```
+
+The `run_command` import in `mount_manager_ui.py` may become unused — drop
+it if so. `Gtk.FileLauncher` was introduced in GTK 4.10; our minimum
+libadwaita 1.8 transitively requires GTK ≥ 4.18 (libadwaita 1.8's hard
+floor), so this is always available.
+
+## Distribution impact
+
+Libadwaita 1.8 was released in September 2025. As of May 2026 the floor
+covers:
+
+- Fedora 43+ (current release)
+- Ubuntu 25.10+
+- Rolling distros (Arch, openSUSE Tumbleweed)
+- Flatpak runtime 48
+- AppImage users: unaffected — `packaging/build-appimage.sh` bundles
+ libadwaita into the AppImage at build time
+
+Users on Fedora ≤ 42, Ubuntu LTS 24.04 or 25.04 will see the version-gate
+error and must use the AppImage or a newer distro. Acceptable cost per
+user direction (the branch has not landed in any production release).
+
+## Testing
+
+- Stock `unittest` only, per `AGENTS.md`. No new test dependencies.
+- `tests/test_libadwaita_support.py` fixture values rebased on `(1, 8)`.
+ All five existing test cases (`test_minimum_supported_version`,
+ `test_newer_major_supported`, `test_newer_minor_supported`,
+ `test_older_major_unsupported`, `test_older_minor_unsupported`) keep
+ their shape — only the numeric inputs change.
+- Widget construction is verified manually per `AGENTS.md`. The smoke
+ test (`test_import_mount_manager`) will catch any Python-level breakage
+ in the spinner and dialog rewrites.
+
+Manual verification checklist for the user:
+
+1. App launches; no "libadwaita too old" message.
+2. Add Share → type a host → spinner spins while resolving, disappears
+ when the check completes; check icon appears for reachable host, error
+ icon for unreachable.
+3. `Ctrl+?` opens a libadwaita-styled shortcuts dialog (note: visually
+ distinct from the old `Gtk.ShortcutsWindow` look). Each row shows its
+ accelerator badge sourced from `set_accels_for_action`.
+4. No deprecation warnings appear in stderr when running the app.
+5. With at least one managed mount enabled, click the folder icon → the
+ system file manager opens at the mount point. Dismissing any portal
+ dialog does not produce a toast; a real failure (e.g. mount point
+ removed mid-click) does.
+6. Mount list rows render as separate cards (one boxed row per mount)
+ rather than a single grouped container.
+
+## Risks / open questions
+
+- **None blocking.** API surface confirmed against current libadwaita
+ documentation. Action-name auto-discovery is the only non-obvious
+ mechanism and its prerequisites are already satisfied by the existing
+ code structure.
+
+## Reference
+
+- Libadwaita ShortcutsDialog docs:
+ https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.ShortcutsDialog.html
+- Libadwaita Spinner docs:
+ https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.Spinner.html
+- HIG-fixes plan (notes the deprecation this spec resolves):
+ `docs/plans/2026-05-28-hig-fixes.md` Task 6
+- Original migration design (for context on hybrid row pattern, etc.):
+ `docs/specs/2026-05-28-libadwaita-migration-design.md`
diff --git a/docs/specs/2026-05-28-libadwaita-migration-design.md b/docs/specs/2026-05-28-libadwaita-migration-design.md
new file mode 100644
index 0000000..000d86b
--- /dev/null
+++ b/docs/specs/2026-05-28-libadwaita-migration-design.md
@@ -0,0 +1,217 @@
+# libadwaita UI migration — design
+
+**Status:** approved (draft, pre-implementation)
+**Date:** 2026-05-28
+
+## Goal
+
+Migrate the Mount Manager GUI from plain GTK 4 widgets to libadwaita so the app
+matches the look and behavior of native GNOME / Bazzite applications, and
+remove the custom CSS and dark-mode detection currently used to approximate
+that look.
+
+The privileged helper-mode subprocess, polkit invocation, systemd-creds
+handling, mount-unit generation, and credential storage paths are out of scope
+and must not change.
+
+## Approach
+
+In-place migration of the existing code, with a single targeted refactor: the
+GUI is moved out of `mount_manager.py` into a new sibling module so that
+`mount_manager.py` retains only the data models, systemd / credential plumbing,
+and helper-mode subprocess entry point.
+
+The migration targets **libadwaita ≥ 1.5** so that `Adw.Dialog` and
+`Adw.AlertDialog` are available. The app gains an explicit version check at
+startup, parallel to today's systemd 258 check, that refuses to start with a
+clear error if the host's libadwaita is too old.
+
+## File layout
+
+- `mount_manager.py`
+ - Keeps everything it has today **except** the body of `run_gui()` and the
+ UI classes nested inside it.
+ - `run_gui()` becomes a thin shim:
+ `from mount_manager_ui import run_gui as _run_gui; return _run_gui()`.
+ - Helper mode (`run_helper_mode`, `--helper` arg), data models
+ (`ManagedMount`, `DisplayedMount`, `SharePath`), systemd / credential
+ helpers, polkit handoff (`request_helper_*`), and `main()` stay put.
+ - `import_gtk()`, `apply_theme()`, and the `APP_CSS` constant are removed.
+- `mount_manager_ui.py` *(new)*
+ - Module-level `gi.require_version("Gtk", "4.0")` and
+ `gi.require_version("Adw", "1")`, followed by `from gi.repository import …`.
+ - Defines: `ensure_libadwaita_supported()`, `apply_style_manager()`,
+ `MainWindow`, `AddShareDialog`, `DeleteAlertDialog` (thin wrapper around
+ `Adw.AlertDialog`), `MountManagerApplication`, and a `run_gui()` entry
+ point.
+ - Imports data models, constants, and helper-invocation functions from
+ `mount_manager`.
+- `packaging/build-appimage.sh` — install the new file alongside
+ `mount_manager.py` (one additional copy/install line).
+- `README.md` — add `mount_manager_ui.py` to the "Test as an installed app on
+ Bazzite" install commands, and add `libadwaita ≥ 1.5` to the requirements
+ section.
+
+## Window & theming
+
+- `MountManagerApplication` becomes `Adw.Application`. Application ID and
+ flags unchanged.
+- `MainWindow` becomes `Adw.ApplicationWindow` containing an
+ `Adw.ToolbarView`. The top bar is an `Adw.HeaderBar`; the content area is an
+ `Adw.ToastOverlay` wrapping the list / status-page widget.
+- The window title is `APP_NAME`; the icon name is unchanged. No manual title
+ widget is set — libadwaita derives the header title from the window title.
+- Theming: `APP_CSS` and `apply_theme()` are deleted.
+ `Adw.StyleManager.get_default().set_color_scheme(Adw.ColorScheme.DEFAULT)` is
+ called once at startup so the app follows the system / portal preference
+ automatically.
+
+### Header bar
+
+- Start side: a suggested-action **Add Share** button (text label, no icon).
+- End side: a refresh icon button (`view-refresh-symbolic`), then a menu
+ button (`open-menu-symbolic`) whose menu contains a single `About` entry.
+
+## Mount list
+
+- The content is an `Adw.Clamp` wrapping an `Adw.PreferencesPage` with one
+ `Adw.PreferencesGroup` titled "SMB Shares".
+- Each mount is rendered as an `Adw.ActionRow`:
+ - Title: the share source (e.g. `//192.168.1.10/media`).
+ - Subtitle: the mount point and a short status string
+ (`/mnt/mount-manager/media · Mounted`, `… · Idle`, `… · Needs upgrade`,
+ `… · Mounted (not managed)`).
+ - Trailing widgets, in order:
+ 1. **Switch** — enables / disables the systemd automount, same semantics as
+ today's `mount_switch`. Insensitive when the row is unmanaged or needs
+ upgrading.
+ 2. **Open folder** icon button (`folder-open-symbolic`) — sensitive only
+ when on-demand access is active, matching today's `open_button.set_sensitive`
+ logic.
+ 3. **Primary action** (only when applicable): for rows that need an
+ upgrade, an inline button labeled "Upgrade" is shown in place of the
+ open-folder button (matches today's behavior of swapping these two).
+ 4. **Kebab** (`Gtk.MenuButton` with `view-more-symbolic`) — menu contains a
+ destructive "Delete…" entry.
+- Unmanaged mounts: no switch, no open button, no kebab. The trailing area
+ shows a dim "Not managed" label as today.
+- Tooltips on the switch and open button preserve today's exact strings.
+
+## Empty state
+
+When `load_displayed_mounts()` returns no rows, the preferences page is
+hidden and replaced by an `Adw.StatusPage`:
+
+- icon: `folder-remote-symbolic`
+- title: "No SMB shares"
+- description: "Click *Add Share* to mount one."
+- child: a suggested-action button "Add Share" that opens the Add Share dialog
+ (same handler as the header button).
+
+## Add Share dialog
+
+`AddShareDialog(Adw.Dialog)` — single page, progressive reveal.
+
+- Header: `Adw.HeaderBar` with `Cancel` (start) and a suggested-action `Add`
+ (end). `Add` is insensitive until the host check has succeeded and both
+ credential fields are non-empty.
+- Body: `Adw.Clamp` wrapping a vertical `Gtk.Box` of two
+ `Adw.PreferencesGroup`s (not `Adw.PreferencesPage`, whose internal
+ `ScrolledWindow` would pin the dialog at a fixed height and prevent it from
+ growing when the credentials group is revealed):
+ - **Share** group:
+ - `Adw.EntryRow` titled "Share path". The group description carries the
+ example: `//192.168.1.2/sharename or //hostname/sharename`.
+ - The host check (currently a separate "Check host" button) runs
+ automatically after a short typing debounce once the entered path
+ parses. A spinner is shown in the row's apply / trailing area while the
+ check is in flight, replaced by a green check icon on success or a red
+ error icon on failure. The row's subtitle conveys the result text.
+ - **Credentials** group:
+ - `Adw.EntryRow` titled "Username".
+ - `Adw.PasswordEntryRow` titled "Password".
+ - The group's `visible` property is bound to "host check succeeded".
+- Submitting `Add` runs the existing test-mount → helper-create flow on a
+ worker thread (today's logic is preserved). On success the dialog closes,
+ the main window's list refreshes, and a toast is shown. On failure an
+ `Adw.Banner` is added at the top of the dialog body with the error message;
+ the dialog stays open so the user can correct input and retry.
+
+## Delete confirmation
+
+`DeleteAlertDialog` is an `Adw.AlertDialog`:
+
+- Heading: "Delete this SMB mount?"
+- Body: "Removes `{record.source}` and its systemd units. The encrypted
+ credentials will also be deleted."
+- Responses: `cancel` ("Cancel", default) and `delete` ("Delete",
+ destructive appearance).
+
+On confirm, the existing helper-delete flow runs. On failure, the alert
+closes and a toast is shown with the error; if the error message is long, the
+toast has a "Details" button that opens a transient `Adw.AlertDialog` with the
+full text.
+
+## About dialog
+
+`Adw.AboutDialog` populated from the existing constants:
+
+- application name: `APP_NAME`
+- application icon: `APP_ICON_NAME`
+- developer name(s): `APP_DEVELOPERS`
+- website: `APP_WEBSITE`
+- license type: `Gtk.License.GPL_3_0_ONLY`
+- comments: "Create and manage on-demand SMB mounts."
+
+The current `Gtk.AboutDialog` invocation is removed.
+
+## Toasts and banners (replacing MessageWindow)
+
+`MessageWindow` is deleted. Every existing call site is reclassified:
+
+| Existing call | New behavior |
+| --- | --- |
+| `MessageWindow(self, "SMB Mount Created", …)` | `Adw.Toast` in main window. |
+| `MessageWindow(self, "SMB Mount Upgraded", …)` | `Adw.Toast` in main window. |
+| `MessageWindow(self, "Open Folder Failed", …)` | `Adw.Toast` (with "Details" button if message is long). |
+| `MessageWindow(self, "Upgrade Failed", …)` | `Adw.Toast` (with "Details" button). |
+| `MessageWindow(self, "Mount Toggle Failed", …)` | `Adw.Toast` (with "Details" button). |
+| Test-mount failure inside Add Share | `Adw.Banner` at top of Add Share dialog, dialog stays open. |
+| Delete failure inside Delete confirmation | Alert closes, error shown as toast in main window. |
+
+## Startup checks
+
+A new `ensure_libadwaita_supported()` function runs before window creation. It
+checks the linked libadwaita version (via `Adw.MAJOR_VERSION`,
+`Adw.MINOR_VERSION`) and refuses to start with a clear stderr message if the
+version is below 1.5. This mirrors the existing `require_systemd_support()`
+pattern.
+
+## Out of scope
+
+- Helper-mode subprocess (`--helper create|delete|upgrade|set-enabled`).
+- polkit / `pkexec` invocation.
+- systemd-creds encryption and credential file paths.
+- Mount-unit generation and the `/mnt/mount-manager` / `/etc/mount-manager`
+ layout.
+- `argparse`, `main()`, and the `--helper` entry point in `mount_manager.py`.
+- No new third-party Python dependencies. The only new runtime dependency is
+ the system libadwaita ≥ 1.5 typing, already present on supported targets.
+- RPM spec changes are not in this repo; only README and AppImage notes are
+ updated here.
+
+## Risks
+
+- **Host libadwaita version drift.** The AppImage runs against the host's
+ libadwaita. Systems with libadwaita < 1.5 will be rejected at startup with a
+ clear message. Bazzite and current Fedora ship ≥ 1.5, so impact is limited
+ to outliers.
+- **Toast vs. window for success messages.** The user no longer dismisses a
+ modal window after each successful operation. This is a deliberate UX
+ improvement but should be verified by manual testing on a real Bazzite
+ install before release.
+- **Automatic host check on type.** Removing the explicit "Check host" button
+ means hostname / DNS lookups run as the user types (debounced). Network
+ errors and slow DNS need to be surfaced clearly in the row's status area to
+ avoid the dialog feeling broken. The existing host-check function is reused
+ unchanged; only its invocation timing changes.
diff --git a/mount_manager.py b/mount_manager.py
index 712b968..f36bef3 100644
--- a/mount_manager.py
+++ b/mount_manager.py
@@ -9,8 +9,6 @@
mode through pkexec so only the system-changing work runs as root.
"""
-from __future__ import annotations
-
import argparse
import dataclasses
import hashlib
@@ -32,7 +30,6 @@
APP_CREATOR = "Zacharias Xenakis (Xarishark)"
APP_DEVELOPERS = [APP_CREATOR]
APP_WEBSITE = "https://github.com/Xarishark/mount-manager"
-COLOR_SCHEME_ENV = "MOUNT_MANAGER_COLOR_SCHEME"
APP_ICON_NAME = APP_ID
MANAGED_ROOT = Path("/etc/mount-manager")
@@ -50,76 +47,14 @@
# Mount-unit credentials (LoadCredentialEncrypted=) require this systemd version.
MIN_SYSTEMD_VERSION = 258
-APP_CSS = """
-window {
- background: @theme_bg_color;
- color: @theme_fg_color;
-}
-
-headerbar {
- background: @theme_base_color;
- color: @theme_text_color;
-}
-
-.mount-root {
- background: @theme_bg_color;
-}
-
-.boxed-list {
- background: @theme_base_color;
- color: @theme_text_color;
- border: 1px solid alpha(@theme_fg_color, 0.16);
- border-radius: 8px;
-}
-
-.boxed-list row {
- background: transparent;
- color: @theme_text_color;
-}
-
-.boxed-list row:not(:last-child) {
- border-bottom: 1px solid alpha(@theme_fg_color, 0.10);
-}
-
-.dim-label {
- opacity: 0.72;
-}
-
-.error {
- color: #c01c28;
-}
-
-.success {
- color: #26a269;
-}
-
-button.headerbar-control,
-menubutton.headerbar-control > button {
- min-height: 34px;
- min-width: 34px;
- padding-top: 4px;
- padding-bottom: 4px;
-}
-
-button.add-share-button {
- font-weight: 700;
- padding-left: 12px;
- padding-right: 12px;
-}
-
-button.upgrade-action {
- background: #26a269;
- color: white;
-}
-
-button.upgrade-action:hover {
- background: #2ec27e;
-}
-
-button.upgrade-action:active {
- background: #1a7f52;
-}
-"""
+# Adw.ShortcutsDialog and Adw.Spinner require libadwaita 1.8 or newer.
+MIN_LIBADWAITA_VERSION: tuple[int, int] = (1, 8)
+
+
+def libadwaita_supports(major: int, minor: int) -> bool:
+ """Return True if the given libadwaita (major, minor) meets the app's minimum."""
+ return (major, minor) >= MIN_LIBADWAITA_VERSION
+
HOST_RE = re.compile(
r"^(?=.{1,253}$)(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)*"
@@ -984,41 +919,6 @@ def load_displayed_mounts() -> list[DisplayedMount]:
return displayed
-def detect_color_scheme(env: dict[str, str] | None = None) -> str:
- if env is None:
- env = os.environ
-
- explicit = env.get(COLOR_SCHEME_ENV, "").strip().lower()
- if explicit in {"dark", "light"}:
- return explicit
-
- gtk_theme = env.get("GTK_THEME", "").lower()
- if "dark" in gtk_theme:
- return "dark"
- if "light" in gtk_theme:
- return "light"
-
- try:
- result = subprocess.run(
- ["gsettings", "get", "org.gnome.desktop.interface", "color-scheme"],
- check=False,
- text=True,
- stdout=subprocess.PIPE,
- stderr=subprocess.PIPE,
- timeout=2,
- )
- except (FileNotFoundError, subprocess.SubprocessError):
- return "light"
-
- if result.returncode != 0:
- return "light"
-
- value = result.stdout.strip().strip("'\"").lower()
- if value == "prefer-dark":
- return "dark"
- return "light"
-
-
def run_privileged_helper(action: str, payload: dict[str, Any]) -> dict[str, Any]:
pkexec = shutil.which("pkexec")
if pkexec is None:
@@ -1145,542 +1045,12 @@ def run_helper_mode(action: str) -> int:
return 0
-def import_gtk() -> tuple[Any, Any, Any, Any]:
- import gi
-
- gi.require_version("Gdk", "4.0")
- gi.require_version("Gtk", "4.0")
- gi.require_version("Pango", "1.0")
- from gi.repository import Gdk, Gio, Gtk, Pango
-
- return Gdk, Gio, Gtk, Pango
-
-
-def apply_theme(Gtk: Any, Gdk: Any) -> None:
- settings = Gtk.Settings.get_default()
- if settings is not None:
- settings.set_property(
- "gtk-application-prefer-dark-theme",
- detect_color_scheme() == "dark",
- )
-
- display = Gdk.Display.get_default()
- if display is None:
- return
-
- Gtk.Window.set_default_icon_name(APP_ICON_NAME)
-
- provider = Gtk.CssProvider()
- provider.load_from_data(APP_CSS.encode("utf-8"))
- Gtk.StyleContext.add_provider_for_display(
- display,
- provider,
- Gtk.STYLE_PROVIDER_PRIORITY_APPLICATION,
- )
def run_gui() -> int:
- Gdk, Gio, Gtk, Pango = import_gtk()
- if not Gtk.init_check():
- print(
- "GTK could not connect to your graphical session. Run this from your "
- "desktop session, not a plain TTY.",
- file=sys.stderr,
- )
- return 1
- if Gdk.Display.get_default() is None:
- print(
- "GTK did not provide a usable display. Run this from your desktop "
- "session, not a plain TTY.",
- file=sys.stderr,
- )
- return 1
- apply_theme(Gtk, Gdk)
-
- class AddShareWindow(Gtk.Window):
- def __init__(self, parent: Gtk.Window, on_complete: Any) -> None:
- super().__init__(title="Add SMB Share")
- self.set_transient_for(parent)
- self.set_modal(True)
- self.set_default_size(560, -1)
- self.set_resizable(False)
- self.on_complete = on_complete
- self.share_path: SharePath | None = None
-
- root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=14)
- root.set_margin_top(18)
- root.set_margin_bottom(18)
- root.set_margin_start(18)
- root.set_margin_end(18)
- self.set_child(root)
-
- self.path_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=8)
- root.append(self.path_box)
-
- path_label = Gtk.Label(label="Please add share path")
- path_label.set_xalign(0)
- self.path_box.append(path_label)
-
- self.path_entry = Gtk.Entry()
- self.path_entry.set_placeholder_text("//hostname/share")
- self.path_entry.set_hexpand(True)
- self.path_entry.connect("activate", lambda _entry: self.on_next_clicked())
- self.path_box.append(self.path_entry)
-
- path_help = Gtk.Label(label="Example: //192.168.1.2/sharename or //hostname/sharename")
- path_help.set_xalign(0)
- path_help.add_css_class("dim-label")
- self.path_box.append(path_help)
-
- self.credentials_box = Gtk.Grid(column_spacing=12, row_spacing=10)
- self.credentials_box.set_visible(False)
- root.append(self.credentials_box)
-
- host_status_label = Gtk.Label(label="")
- host_status_label.set_xalign(0)
- host_status_label.add_css_class("success")
- self.credentials_box.attach(host_status_label, 0, 0, 2, 1)
- self.host_status_label = host_status_label
-
- user_label = Gtk.Label(label="Username")
- user_label.set_xalign(0)
- self.credentials_box.attach(user_label, 0, 1, 1, 1)
-
- self.user_entry = Gtk.Entry()
- self.user_entry.set_hexpand(True)
- self.user_entry.connect("activate", lambda _entry: self.password_entry.grab_focus())
- self.credentials_box.attach(self.user_entry, 1, 1, 1, 1)
-
- password_label = Gtk.Label(label="Password")
- password_label.set_xalign(0)
- self.credentials_box.attach(password_label, 0, 2, 1, 1)
-
- self.password_entry = Gtk.PasswordEntry()
- self.password_entry.set_hexpand(True)
- self.password_entry.connect("activate", lambda _entry: self.on_next_clicked())
- self.credentials_box.attach(self.password_entry, 1, 2, 1, 1)
-
- self.status_label = Gtk.Label()
- self.status_label.set_xalign(0)
- self.status_label.set_wrap(True)
- self.status_label.add_css_class("dim-label")
- self.status_label.set_visible(False)
- root.append(self.status_label)
-
- buttons = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8)
- buttons.set_halign(Gtk.Align.END)
- root.append(buttons)
-
- cancel_button = Gtk.Button(label="Cancel")
- cancel_button.connect("clicked", lambda _button: self.close())
- buttons.append(cancel_button)
-
- self.back_button = Gtk.Button(label="Back")
- self.back_button.set_visible(False)
- self.back_button.connect("clicked", lambda _button: self.show_path_step())
- buttons.append(self.back_button)
-
- self.next_button = Gtk.Button(label="Check host")
- self.next_button.add_css_class("suggested-action")
- self.next_button.connect("clicked", lambda _button: self.on_next_clicked())
- buttons.append(self.next_button)
-
- self.path_entry.grab_focus()
-
- def set_status(self, message: str, css_class: str) -> None:
- self.status_label.remove_css_class("error")
- self.status_label.remove_css_class("success")
- self.status_label.add_css_class(css_class)
- self.status_label.set_text(message)
- self.status_label.set_visible(True)
-
- def show_path_step(self) -> None:
- self.share_path = None
- self.path_entry.set_sensitive(True)
- self.path_box.set_visible(True)
- self.credentials_box.set_visible(False)
- self.back_button.set_visible(False)
- self.next_button.set_label("Check host")
- self.status_label.set_visible(False)
- self.path_entry.grab_focus()
-
- def show_credentials_step(self, share_path: SharePath) -> None:
- self.share_path = share_path
- self.path_entry.set_sensitive(False)
- self.path_box.set_visible(True)
- self.credentials_box.set_visible(True)
- self.host_status_label.set_text("Host is reachable. Please enter credentials.")
- self.back_button.set_visible(True)
- self.next_button.set_label("Create")
- self.status_label.set_visible(False)
- self.user_entry.grab_focus()
-
- def on_next_clicked(self) -> None:
- if self.share_path is None:
- self.check_host()
- else:
- self.create_share()
-
- def check_host(self) -> None:
- try:
- share_path = check_smb_host_reachable(self.path_entry.get_text())
- except MountManagerError as exc:
- self.set_status(str(exc), "error")
- return
- except Exception as exc:
- self.set_status(f"Unexpected error: {exc}", "error")
- return
-
- self.show_credentials_step(share_path)
-
- def create_share(self) -> None:
- if self.share_path is None:
- self.set_status("Check the share path before entering credentials.", "error")
- return
-
- share = self.share_path.source
- username = self.user_entry.get_text()
- password = self.password_entry.get_text()
-
- try:
- validate_credentials(username, password)
- self.set_status("Creating encrypted on-demand mount...", "success")
- request_helper_create(share, username, password)
- except MountManagerError as exc:
- self.set_status(str(exc), "error")
- return
- except Exception as exc:
- self.set_status(f"Unexpected error: {exc}", "error")
- return
-
- self.close()
- self.on_complete(share)
-
- class MessageWindow(Gtk.Window):
- def __init__(self, parent: Gtk.Window, title: str, message: str) -> None:
- super().__init__(title=title)
- self.set_transient_for(parent)
- self.set_modal(True)
- self.set_default_size(420, -1)
- self.set_resizable(False)
-
- root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=14)
- root.set_margin_top(18)
- root.set_margin_bottom(18)
- root.set_margin_start(18)
- root.set_margin_end(18)
- self.set_child(root)
-
- heading = Gtk.Label(label=title)
- heading.add_css_class("title-3")
- heading.set_xalign(0)
- root.append(heading)
-
- label = Gtk.Label(label=message)
- label.set_wrap(True)
- label.set_xalign(0)
- root.append(label)
-
- buttons = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8)
- buttons.set_halign(Gtk.Align.END)
- root.append(buttons)
-
- ok_button = Gtk.Button(label="OK")
- ok_button.add_css_class("suggested-action")
- ok_button.connect("clicked", lambda _button: self.close())
- buttons.append(ok_button)
-
- class DeleteMountWindow(Gtk.Window):
- def __init__(self, parent: Gtk.Window, record: ManagedMount, on_complete: Any) -> None:
- super().__init__(title="Delete SMB Mount")
- self.set_transient_for(parent)
- self.set_modal(True)
- self.set_default_size(460, -1)
- self.set_resizable(False)
- self.record = record
- self.on_complete = on_complete
-
- root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=14)
- root.set_margin_top(18)
- root.set_margin_bottom(18)
- root.set_margin_start(18)
- root.set_margin_end(18)
- self.set_child(root)
-
- heading = Gtk.Label(label="Delete SMB Mount")
- heading.add_css_class("title-3")
- heading.set_xalign(0)
- root.append(heading)
-
- label = Gtk.Label(label=f"Delete {record.source} and remove its systemd units?")
- label.set_wrap(True)
- label.set_xalign(0)
- root.append(label)
-
- self.error_label = Gtk.Label()
- self.error_label.set_xalign(0)
- self.error_label.set_wrap(True)
- self.error_label.add_css_class("error")
- self.error_label.set_visible(False)
- root.append(self.error_label)
-
- buttons = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=8)
- buttons.set_halign(Gtk.Align.END)
- root.append(buttons)
-
- cancel_button = Gtk.Button(label="Cancel")
- cancel_button.connect("clicked", lambda _button: self.close())
- buttons.append(cancel_button)
-
- delete_button = Gtk.Button(label="Delete")
- delete_button.add_css_class("destructive-action")
- delete_button.connect("clicked", lambda _button: self.delete_share())
- buttons.append(delete_button)
-
- def show_error(self, message: str) -> None:
- self.error_label.set_text(message)
- self.error_label.set_visible(True)
-
- def delete_share(self) -> None:
- try:
- request_helper_delete(self.record)
- except MountManagerError as exc:
- self.show_error(str(exc))
- return
- except Exception as exc:
- self.show_error(f"Unexpected error: {exc}")
- return
-
- self.close()
- self.on_complete()
-
- class MainWindow(Gtk.ApplicationWindow):
- def __init__(self, app: Gtk.Application) -> None:
- super().__init__(application=app, title=APP_NAME)
- self.set_default_size(760, 480)
- self.set_icon_name(APP_ICON_NAME)
-
- header = Gtk.HeaderBar()
- title = Gtk.Label(label=APP_NAME)
- title.add_css_class("heading")
- header.set_title_widget(title)
-
- refresh_button = Gtk.Button.new_from_icon_name("view-refresh-symbolic")
- refresh_button.set_tooltip_text("Refresh")
- refresh_button.add_css_class("headerbar-control")
- refresh_button.connect("clicked", lambda _button: self.refresh())
-
- about_action = Gio.SimpleAction.new("about", None)
- about_action.connect("activate", lambda _action, _param: self.show_about_dialog())
- self.add_action(about_action)
-
- menu = Gio.Menu()
- menu.append(f"About {APP_NAME}", "win.about")
-
- menu_button = Gtk.MenuButton()
- menu_button.set_icon_name("open-menu-symbolic")
- menu_button.set_menu_model(menu)
- menu_button.set_tooltip_text("Main menu")
- menu_button.add_css_class("headerbar-control")
-
- add_button = Gtk.Button(label="ADD SHARE")
- add_button.set_tooltip_text("Add share")
- add_button.add_css_class("suggested-action")
- add_button.add_css_class("headerbar-control")
- add_button.add_css_class("add-share-button")
- add_button.connect("clicked", lambda _button: self.show_add_dialog())
- header.pack_start(add_button)
- header.pack_end(menu_button)
- header.pack_end(refresh_button)
-
- self.set_titlebar(header)
-
- root = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=12)
- root.add_css_class("mount-root")
- root.set_margin_top(16)
- root.set_margin_bottom(16)
- root.set_margin_start(16)
- root.set_margin_end(16)
- self.set_child(root)
-
- self.empty_label = Gtk.Label(label="No SMB mounts found.")
- self.empty_label.add_css_class("dim-label")
- self.empty_label.set_margin_top(32)
-
- self.list_box = Gtk.ListBox()
- self.list_box.set_selection_mode(Gtk.SelectionMode.NONE)
- self.list_box.add_css_class("boxed-list")
-
- scroller = Gtk.ScrolledWindow()
- scroller.set_policy(Gtk.PolicyType.NEVER, Gtk.PolicyType.AUTOMATIC)
- scroller.set_child(self.list_box)
- scroller.set_vexpand(True)
- root.append(scroller)
- root.append(self.empty_label)
-
- self.refresh()
-
- def refresh(self) -> None:
- while True:
- row = self.list_box.get_first_child()
- if row is None:
- break
- self.list_box.remove(row)
-
- mounts = load_displayed_mounts()
- self.empty_label.set_visible(not mounts)
- self.list_box.set_visible(bool(mounts))
-
- for mount in mounts:
- self.list_box.append(self.row_for(mount))
-
- def row_for(self, mount: DisplayedMount) -> Gtk.ListBoxRow:
- row = Gtk.ListBoxRow()
- box = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=12)
- box.set_margin_top(10)
- box.set_margin_bottom(10)
- box.set_margin_start(12)
- box.set_margin_end(12)
-
- mount_switch = Gtk.Switch()
- mount_switch.set_valign(Gtk.Align.CENTER)
- mount_switch.set_active(mount.active)
- mount_switch.set_sensitive(mount.managed and not mount.needs_upgrade)
- if mount.managed and mount.managed_record is not None:
- if mount.needs_upgrade:
- mount_switch.set_tooltip_text("Upgrade this older mount before enabling it")
- else:
- mount_switch.set_tooltip_text("Enable or disable on-demand access for this managed mount")
- mount_switch.connect(
- "notify::active",
- lambda switch, _param: self.toggle_mount(mount.managed_record, switch),
- )
- else:
- mount_switch.set_tooltip_text("This SMB mount is not managed by this app")
-
- text_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=3)
- text_box.set_hexpand(True)
-
- source_label = Gtk.Label(label=mount.source)
- source_label.set_xalign(0)
- source_label.add_css_class("heading")
- source_label.set_ellipsize(Pango.EllipsizeMode.END)
-
- detail = f"{mount.mount_point} - {mount.status}"
- detail_label = Gtk.Label(label=detail)
- detail_label.set_xalign(0)
- detail_label.add_css_class("dim-label")
- detail_label.set_ellipsize(Pango.EllipsizeMode.END)
-
- text_box.append(source_label)
- text_box.append(detail_label)
-
- box.append(mount_switch)
- box.append(text_box)
-
- if mount.managed and mount.managed_record is not None:
- if mount.needs_upgrade:
- upgrade_button = Gtk.Button(label="Upgrade")
- upgrade_button.set_tooltip_text("Upgrade mount units using the existing encrypted credentials")
- upgrade_button.add_css_class("upgrade-action")
- upgrade_button.connect("clicked", lambda _button: self.upgrade_mount(mount.managed_record))
- box.append(upgrade_button)
- else:
- open_button = Gtk.Button.new_from_icon_name("folder-open-symbolic")
- open_button.set_sensitive(mount.openable)
- open_button.set_tooltip_text(
- "Open mount folder" if mount.openable else "Enable on-demand access to open its folder"
- )
- open_button.connect("clicked", lambda _button: self.open_mount_folder(mount.managed_record))
- box.append(open_button)
-
- delete_button = Gtk.Button.new_from_icon_name("user-trash-symbolic")
- delete_button.set_tooltip_text("Delete mount")
- delete_button.add_css_class("destructive-action")
- delete_button.connect("clicked", lambda _button: self.confirm_delete(mount.managed_record))
-
- box.append(delete_button)
- else:
- not_managed_label = Gtk.Label(label="Not managed")
- not_managed_label.add_css_class("dim-label")
- not_managed_label.set_valign(Gtk.Align.CENTER)
- box.append(not_managed_label)
-
- row.set_child(box)
- return row
-
- def show_add_dialog(self) -> None:
- AddShareWindow(self, self.mount_created).present()
-
- def show_about_dialog(self) -> None:
- dialog = Gtk.AboutDialog()
- dialog.set_transient_for(self)
- dialog.set_modal(True)
- dialog.set_program_name(APP_NAME)
- dialog.set_logo_icon_name(APP_ICON_NAME)
- dialog.set_comments("Create and manage on-demand SMB mounts.")
- dialog.set_authors(APP_DEVELOPERS)
- dialog.add_credit_section("Developed by", APP_DEVELOPERS)
- dialog.set_website(APP_WEBSITE)
- dialog.set_website_label("Project homepage")
- dialog.set_license_type(Gtk.License.GPL_3_0_ONLY)
- dialog.present()
-
- def mount_created(self, share: str) -> None:
- self.refresh()
- MessageWindow(self, "SMB Mount Created", f"{share} will mount when accessed.").present()
-
- def open_mount_folder(self, record: ManagedMount) -> None:
- if not record.mount_point.exists():
- MessageWindow(self, "Open Folder Failed", f"Mount folder does not exist: {record.mount_point}").present()
- return
-
- try:
- run_command(["xdg-open", str(record.mount_point)])
- except MountManagerError as exc:
- MessageWindow(self, "Open Folder Failed", f"Could not open {record.mount_point}: {exc}").present()
-
- def upgrade_mount(self, record: ManagedMount) -> None:
- try:
- request_helper_upgrade(record)
- except MountManagerError as exc:
- MessageWindow(self, "Upgrade Failed", str(exc)).present()
- return
- except Exception as exc:
- MessageWindow(self, "Upgrade Failed", f"Unexpected error: {exc}").present()
- return
-
- self.refresh()
- MessageWindow(self, "SMB Mount Upgraded", f"{record.source} will mount when accessed.").present()
-
- def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None:
- enabled = switch.get_active()
- switch.set_sensitive(False)
- try:
- request_helper_set_enabled(record, enabled)
- except MountManagerError as exc:
- MessageWindow(self, "Mount Toggle Failed", str(exc)).present()
- except Exception as exc:
- MessageWindow(self, "Mount Toggle Failed", f"Unexpected error: {exc}").present()
- finally:
- self.refresh()
-
- def confirm_delete(self, record: ManagedMount) -> None:
- DeleteMountWindow(self, record, self.refresh).present()
-
- class MountManagerApplication(Gtk.Application):
- def __init__(self) -> None:
- super().__init__(application_id=APP_ID, flags=Gio.ApplicationFlags.DEFAULT_FLAGS)
-
- def do_activate(self) -> None:
- window = self.props.active_window
- if window is None:
- window = MainWindow(self)
- window.present()
-
- app = MountManagerApplication()
- return app.run(sys.argv)
+ from mount_manager_ui import run_gui as _run_gui
+ return _run_gui()
def parse_args(argv: list[str]) -> argparse.Namespace:
parser = argparse.ArgumentParser(description=APP_NAME)
diff --git a/mount_manager_ui.py b/mount_manager_ui.py
new file mode 100644
index 0000000..e0d7eba
--- /dev/null
+++ b/mount_manager_ui.py
@@ -0,0 +1,602 @@
+"""GTK 4 GUI for SMB Mount Manager.
+
+This module is imported lazily from ``mount_manager.run_gui``. Keeping it
+separate from ``mount_manager.py`` lets the helper subprocess avoid importing
+GTK when invoked with ``--helper``.
+"""
+
+from mount_manager import (
+ APP_DEVELOPERS,
+ APP_ICON_NAME,
+ APP_ID,
+ APP_NAME,
+ APP_WEBSITE,
+ MIN_LIBADWAITA_VERSION,
+ DisplayedMount,
+ ManagedMount,
+ MountManagerError,
+ SharePath,
+ libadwaita_supports,
+ check_smb_host_reachable,
+ load_displayed_mounts,
+ request_helper_create,
+ request_helper_delete,
+ request_helper_set_enabled,
+ request_helper_upgrade,
+ validate_credentials,
+)
+
+import sys
+import threading
+import gi
+
+gi.require_version("Adw", "1")
+gi.require_version("Gdk", "4.0")
+gi.require_version("Gtk", "4.0")
+from gi.repository import Adw, Gdk, Gio, GLib, Gtk
+
+
+def GLib_markup_escape(text: str) -> str:
+ """Escape Pango markup characters in row titles/subtitles."""
+ return GLib.markup_escape_text(text, -1)
+
+
+def ensure_libadwaita_supported() -> None:
+ """Print an error and raise SystemExit if libadwaita is too old."""
+ if not libadwaita_supports(Adw.MAJOR_VERSION, Adw.MINOR_VERSION):
+ required = ".".join(str(v) for v in MIN_LIBADWAITA_VERSION)
+ found = f"{Adw.MAJOR_VERSION}.{Adw.MINOR_VERSION}"
+ print(
+ f"libadwaita {found} found, but this app requires {required} or newer.",
+ file=sys.stderr,
+ )
+ raise SystemExit(1)
+
+
+def apply_style_manager() -> None:
+ """Hand color-scheme selection to libadwaita's preference tracker."""
+ Adw.StyleManager.get_default().set_color_scheme(Adw.ColorScheme.DEFAULT)
+ Gtk.Window.set_default_icon_name(APP_ICON_NAME)
+
+
+def mount_status_line(mount: DisplayedMount) -> str:
+ """Build the AdwActionRow subtitle: `` · ``."""
+ return f"{mount.mount_point} · {mount.status}"
+
+
+def run_gui() -> int:
+ ensure_libadwaita_supported()
+ if not Gtk.init_check():
+ print(
+ "GTK could not connect to your graphical session. Run this "
+ "from your desktop session, not a plain TTY.",
+ file=sys.stderr,
+ )
+ return 1
+ if Gdk.Display.get_default() is None:
+ print(
+ "GTK did not provide a usable display. Run this from your desktop "
+ "session, not a plain TTY.",
+ file=sys.stderr,
+ )
+ return 1
+ apply_style_manager()
+
+ def bind_action(
+ owner,
+ app,
+ qualified_name: str,
+ callback,
+ accels: tuple[str, ...] = (),
+ ) -> None:
+ """Register a parameterless action on ``owner`` and wire its accelerators on ``app``.
+
+ ``qualified_name`` is the full action name (``"win.refresh"`` / ``"app.quit"``).
+ """
+ action = Gio.SimpleAction.new(qualified_name.split(".", 1)[1], None)
+ action.connect("activate", lambda _a, _p: callback())
+ owner.add_action(action)
+ if accels:
+ app.set_accels_for_action(qualified_name, list(accels))
+
+ def build_shortcuts_dialog() -> Adw.ShortcutsDialog:
+ """Construct the keyboard shortcuts dialog for the app."""
+ dialog = Adw.ShortcutsDialog()
+
+ general = Adw.ShortcutsSection(title="General")
+ for title, action_name in (
+ ("Add Share", "win.add-share"),
+ ("Refresh", "win.refresh"),
+ ("Primary Menu", "win.show-menu"),
+ ("Keyboard Shortcuts", "app.shortcuts"),
+ ("Close Window", "win.close"),
+ ("Quit", "app.quit"),
+ ):
+ general.add(Adw.ShortcutsItem(title=title, action_name=action_name))
+
+ dialog.add(general)
+ return dialog
+
+ class AddShareDialog(Adw.Dialog):
+ def __init__(self, main_window: "MainWindow") -> None:
+ super().__init__()
+ self.set_title("Add SMB Share")
+ self.set_content_width(420)
+ self.main_window = main_window
+ self.share_path: SharePath | None = None
+ self._debounce_id: int = 0
+ self._cancellable: Gio.Cancellable | None = None
+
+ self.cancel_button = Gtk.Button(label="Cancel")
+ self.cancel_button.connect("clicked", lambda _b: self.close())
+
+ self.add_button = Gtk.Button(label="Add")
+ self.add_button.add_css_class("suggested-action")
+ self.add_button.set_sensitive(False)
+ self.add_button.connect("clicked", lambda _b: self._on_add_clicked())
+
+ header = Adw.HeaderBar()
+ header.set_show_end_title_buttons(False)
+ header.pack_start(self.cancel_button)
+ header.pack_end(self.add_button)
+
+ self.banner = Adw.Banner()
+ self.banner.set_revealed(False)
+
+ groups_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=24)
+ groups_box.set_margin_top(24)
+ groups_box.set_margin_bottom(24)
+ groups_box.set_margin_start(12)
+ groups_box.set_margin_end(12)
+
+ share_group = Adw.PreferencesGroup()
+ share_group.set_title("Share")
+ share_group.set_description(
+ "Example: //192.168.1.2/sharename or //hostname/sharename"
+ )
+ groups_box.append(share_group)
+
+ self.path_row = Adw.EntryRow()
+ self.path_row.set_title("Share path")
+ self.path_row.connect("changed", lambda _r: self._on_path_changed())
+ share_group.add(self.path_row)
+
+ self.host_spinner = Adw.Spinner()
+ self.host_spinner.set_valign(Gtk.Align.CENTER)
+ self.host_spinner.set_visible(False)
+ self.path_row.add_suffix(self.host_spinner)
+
+ self.host_status_icon = Gtk.Image()
+ self.host_status_icon.set_valign(Gtk.Align.CENTER)
+ self.host_status_icon.set_visible(False)
+ self.path_row.add_suffix(self.host_status_icon)
+
+ self.credentials_group = Adw.PreferencesGroup()
+ self.credentials_group.set_title("Credentials")
+ self.credentials_group.set_visible(False)
+ groups_box.append(self.credentials_group)
+
+ self.user_row = Adw.EntryRow()
+ self.user_row.set_title("Username")
+ self.user_row.connect("changed", lambda _r: self._update_add_sensitive())
+ self.credentials_group.add(self.user_row)
+
+ self.password_row = Adw.PasswordEntryRow()
+ self.password_row.set_title("Password")
+ self.password_row.connect(
+ "changed", lambda _r: self._update_add_sensitive()
+ )
+ self.credentials_group.add(self.password_row)
+
+ clamp = Adw.Clamp()
+ clamp.set_maximum_size(600)
+ clamp.set_child(groups_box)
+
+ body = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0)
+ body.append(self.banner)
+ body.append(clamp)
+
+ toolbar = Adw.ToolbarView()
+ toolbar.add_top_bar(header)
+ toolbar.set_content(body)
+ self.set_child(toolbar)
+ self.set_default_widget(self.add_button)
+
+ self.connect("closed", self._cleanup)
+ self.connect("map", lambda _d: self.path_row.grab_focus())
+
+ def _cancel_pending_host_check(self) -> None:
+ if self._cancellable is not None:
+ self._cancellable.cancel()
+ self._cancellable = None
+ if self._debounce_id:
+ GLib.source_remove(self._debounce_id)
+ self._debounce_id = 0
+
+ def _cleanup(self, *_args) -> None:
+ self._cancel_pending_host_check()
+
+ def _show_banner(self, message: str) -> None:
+ self.banner.set_title(message)
+ self.banner.set_revealed(True)
+
+ def _hide_banner(self) -> None:
+ self.banner.set_revealed(False)
+
+ def _set_host_status(self, *, ok: bool | None, message: str) -> None:
+ self.host_spinner.set_visible(False)
+ if ok is None:
+ self.host_status_icon.set_visible(False)
+ self.path_row.set_title("Share path")
+ return
+ if ok:
+ self.host_status_icon.set_from_icon_name("object-select-symbolic")
+ else:
+ self.host_status_icon.set_from_icon_name("dialog-error-symbolic")
+ self.host_status_icon.set_visible(True)
+ self.host_status_icon.set_tooltip_text(message)
+
+ def _on_path_changed(self) -> None:
+ self.share_path = None
+ self.credentials_group.set_visible(False)
+ self._update_add_sensitive()
+ self._hide_banner()
+ self._set_host_status(ok=None, message="")
+ self._cancel_pending_host_check()
+ text = self.path_row.get_text().strip()
+ if not text:
+ return
+ self._debounce_id = GLib.timeout_add(300, self._run_host_check)
+
+ def _run_host_check(self) -> bool:
+ self._debounce_id = 0
+ text = self.path_row.get_text()
+ cancellable = Gio.Cancellable()
+ self._cancellable = cancellable
+ self.host_spinner.set_visible(True)
+ thread = threading.Thread(
+ target=self._host_check_worker,
+ args=(cancellable, text),
+ daemon=True,
+ )
+ thread.start()
+ return False
+
+ def _host_check_worker(self, cancellable: Gio.Cancellable, text: str) -> None:
+ try:
+ result: tuple[SharePath | None, BaseException | None] = (
+ check_smb_host_reachable(text),
+ None,
+ )
+ except Exception as exc:
+ result = (None, exc)
+ if cancellable.is_cancelled():
+ return
+ GLib.idle_add(self._on_host_check_done, cancellable, result[0], result[1])
+
+ def _on_host_check_done(
+ self,
+ cancellable: Gio.Cancellable,
+ share_path: SharePath | None,
+ exc: BaseException | None,
+ ) -> bool:
+ if cancellable.is_cancelled() or cancellable is not self._cancellable:
+ return False # stale or cancelled; ignore
+ self._cancellable = None
+ if exc is not None:
+ if isinstance(exc, MountManagerError):
+ self._set_host_status(ok=False, message=str(exc))
+ else:
+ self._set_host_status(ok=False, message=f"Unexpected error: {exc}")
+ return False
+ self.share_path = share_path
+ self._set_host_status(ok=True, message="Host is reachable")
+ self.credentials_group.set_visible(True)
+ self._update_add_sensitive()
+ return False
+
+ def _update_add_sensitive(self) -> None:
+ ready = (
+ self.share_path is not None
+ and bool(self.user_row.get_text().strip())
+ and bool(self.password_row.get_text())
+ )
+ self.add_button.set_sensitive(ready)
+
+ def _on_add_clicked(self) -> None:
+ if self.share_path is None:
+ return
+ share = self.share_path.source
+ username = self.user_row.get_text()
+ password = self.password_row.get_text()
+ try:
+ validate_credentials(username, password)
+ request_helper_create(share, username, password)
+ except MountManagerError as exc:
+ self._show_banner(str(exc))
+ return
+ except Exception as exc:
+ self._show_banner(f"Unexpected error: {exc}")
+ return
+
+ self.close()
+ self.main_window.refresh()
+ self.main_window.show_toast(f"{share} added")
+
+ class MainWindow(Adw.ApplicationWindow):
+ def __init__(self, app: Adw.Application) -> None:
+ super().__init__(application=app, title=APP_NAME)
+ self.set_default_size(760, 480)
+ self.set_icon_name(APP_ICON_NAME)
+
+ bind_action(self, app, "win.about", self.show_about_dialog)
+ bind_action(self, app, "win.close", self.close, ("w",))
+ bind_action(self, app, "win.add-share", self.show_add_dialog, ("n",))
+ bind_action(self, app, "win.refresh", self.refresh, ("r",))
+ bind_action(self, app, "win.show-menu", self._open_primary_menu, ("F10",))
+
+ menu = Gio.Menu()
+ menu.append("Keyboard Shortcuts", "app.shortcuts")
+ menu.append(f"About {APP_NAME}", "win.about")
+
+ self.menu_button = Gtk.MenuButton(icon_name="open-menu-symbolic")
+ self.menu_button.set_menu_model(menu)
+ self.menu_button.set_tooltip_text("Primary menu")
+
+ refresh_button = Gtk.Button.new_from_icon_name("view-refresh-symbolic")
+ refresh_button.set_tooltip_text("Refresh")
+ refresh_button.set_action_name("win.refresh")
+
+ add_button = Gtk.Button.new_from_icon_name("list-add-symbolic")
+ add_button.set_tooltip_text("Add SMB share")
+ add_button.set_action_name("win.add-share")
+
+ header = Adw.HeaderBar()
+ header.pack_start(add_button)
+ header.pack_end(self.menu_button)
+ header.pack_end(refresh_button)
+
+ self.toast_overlay = Adw.ToastOverlay()
+
+ self.content_box = Gtk.Box(orientation=Gtk.Orientation.VERTICAL, spacing=0)
+ self.toast_overlay.set_child(self.content_box)
+
+ self.empty_page = Adw.StatusPage()
+ self.empty_page.set_icon_name("network-server-symbolic")
+ self.empty_page.set_title("No SMB shares")
+ self.empty_page.set_vexpand(True)
+
+ empty_action = Gtk.Button(label="Add Share")
+ empty_action.set_halign(Gtk.Align.CENTER)
+ empty_action.add_css_class("suggested-action")
+ empty_action.add_css_class("pill")
+ empty_action.set_action_name("win.add-share")
+ self.empty_page.set_child(empty_action)
+
+ self.preferences_page = Adw.PreferencesPage()
+ self.preferences_page.set_vexpand(True)
+
+ self.mount_group = Adw.PreferencesGroup()
+ self.mount_group.set_separate_rows(True)
+ self.preferences_page.add(self.mount_group)
+
+ self.content_box.append(self.preferences_page)
+ self.content_box.append(self.empty_page)
+
+ toolbar_view = Adw.ToolbarView()
+ toolbar_view.add_top_bar(header)
+ toolbar_view.set_content(self.toast_overlay)
+ self.set_content(toolbar_view)
+
+ self.refresh()
+
+ def _open_primary_menu(self) -> None:
+ self.menu_button.popup()
+
+ def show_toast(self, message: str) -> None:
+ self.toast_overlay.add_toast(Adw.Toast(title=message))
+
+ def refresh(self) -> None:
+ while (row := self.mount_group.get_row(0)) is not None:
+ self.mount_group.remove(row)
+
+ mounts = load_displayed_mounts()
+ self.empty_page.set_visible(not mounts)
+ self.preferences_page.set_visible(bool(mounts))
+
+ for mount in mounts:
+ self.mount_group.add(self.row_for(mount))
+
+ def row_for(self, mount: DisplayedMount) -> Adw.ActionRow:
+ row = Adw.ActionRow()
+ row.set_title(GLib_markup_escape(mount.source))
+ row.set_subtitle(GLib_markup_escape(mount_status_line(mount)))
+
+ if not mount.managed or mount.managed_record is None:
+ not_managed_label = Gtk.Label(label="Not managed")
+ not_managed_label.add_css_class("dim-label")
+ not_managed_label.set_valign(Gtk.Align.CENTER)
+ row.add_suffix(not_managed_label)
+ return row
+
+ record = mount.managed_record
+
+ mount_switch = Gtk.Switch()
+ mount_switch.set_valign(Gtk.Align.CENTER)
+ mount_switch.set_active(mount.active)
+ mount_switch.set_sensitive(not mount.needs_upgrade)
+ if mount.needs_upgrade:
+ mount_switch.set_tooltip_text(
+ "Upgrade this older mount before enabling it"
+ )
+ else:
+ mount_switch.set_tooltip_text(
+ "Enable or disable on-demand access for this managed mount"
+ )
+ mount_switch.connect(
+ "notify::active",
+ lambda switch, _param: self.toggle_mount(record, switch),
+ )
+ row.add_suffix(mount_switch)
+
+ if mount.needs_upgrade:
+ upgrade_button = Gtk.Button(label="Upgrade")
+ upgrade_button.set_valign(Gtk.Align.CENTER)
+ upgrade_button.set_tooltip_text(
+ "Upgrade mount units using the existing encrypted credentials"
+ )
+ upgrade_button.add_css_class("suggested-action")
+ upgrade_button.connect("clicked", lambda _b: self.upgrade_mount(record))
+ row.add_suffix(upgrade_button)
+ else:
+ open_button = Gtk.Button.new_from_icon_name("folder-open-symbolic")
+ open_button.set_valign(Gtk.Align.CENTER)
+ open_button.add_css_class("flat")
+ open_button.set_sensitive(mount.openable)
+ open_button.set_tooltip_text(
+ "Open mount folder"
+ if mount.openable
+ else "Enable on-demand access to open its folder"
+ )
+ open_button.connect(
+ "clicked", lambda _b: self.open_mount_folder(record)
+ )
+ row.add_suffix(open_button)
+
+ menu = Gio.Menu()
+ menu.append("Delete\u2026", f"row.delete::{record.manager_id}")
+
+ row_action_group = Gio.SimpleActionGroup()
+ delete_action = Gio.SimpleAction.new("delete", GLib.VariantType.new("s"))
+ delete_action.connect(
+ "activate", lambda _a, _p, r=record: self.confirm_delete(r)
+ )
+ row_action_group.add_action(delete_action)
+ row.insert_action_group("row", row_action_group)
+
+ menu_button = Gtk.MenuButton()
+ menu_button.set_valign(Gtk.Align.CENTER)
+ menu_button.set_icon_name("view-more-symbolic")
+ menu_button.add_css_class("flat")
+ menu_button.set_menu_model(menu)
+ menu_button.set_tooltip_text("More actions")
+ row.add_suffix(menu_button)
+
+ return row
+
+ def show_add_dialog(self) -> None:
+ AddShareDialog(self).present(self)
+
+ def show_about_dialog(self) -> None:
+ about = Adw.AboutDialog(
+ application_name=APP_NAME,
+ application_icon=APP_ICON_NAME,
+ website=APP_WEBSITE,
+ issue_url=f"{APP_WEBSITE}/issues",
+ license_type=Gtk.License.GPL_3_0_ONLY,
+ comments="Create and manage on-demand SMB mounts.",
+ )
+ about.set_developers(APP_DEVELOPERS)
+ about.present(self)
+
+ def open_mount_folder(self, record: ManagedMount) -> None:
+ if not record.mount_point.exists():
+ self.show_toast(f"Mount folder does not exist: {record.mount_point}")
+ return
+ launcher = Gtk.FileLauncher.new(
+ Gio.File.new_for_path(str(record.mount_point))
+ )
+ launcher.launch(self, None, self._on_open_folder_done)
+
+ def _on_open_folder_done(
+ self, launcher: Gtk.FileLauncher, result: Gio.AsyncResult
+ ) -> None:
+ try:
+ launcher.launch_finish(result)
+ except GLib.Error as exc:
+ if exc.matches(Gio.io_error_quark(), Gio.IOErrorEnum.CANCELLED):
+ return
+ self.show_toast(f"Could not open folder: {exc.message}")
+
+ def _run_helper_action(self, label: str, callback) -> bool:
+ """Invoke a privileged helper callback, toast on failure, return True on success."""
+ try:
+ callback()
+ except Exception as exc:
+ self.show_toast(f"{label} failed: {exc}")
+ return False
+ return True
+
+ def upgrade_mount(self, record: ManagedMount) -> None:
+ if self._run_helper_action(
+ "Upgrade", lambda: request_helper_upgrade(record)
+ ):
+ self.refresh()
+ self.show_toast(f"{record.source} upgraded")
+
+ def toggle_mount(self, record: ManagedMount, switch: Gtk.Switch) -> None:
+ enabled = switch.get_active()
+ switch.set_sensitive(False)
+ self._run_helper_action(
+ "Toggle", lambda: request_helper_set_enabled(record, enabled)
+ )
+ self.refresh()
+
+ def confirm_delete(self, record: ManagedMount) -> None:
+ alert = Adw.AlertDialog(
+ heading="Delete this SMB mount?",
+ body=(
+ f"Removes {record.source} and its systemd units. "
+ "The encrypted credentials will also be deleted."
+ ),
+ )
+ alert.add_response("cancel", "Cancel")
+ alert.add_response("delete", "Delete Share")
+ alert.set_response_appearance("delete", Adw.ResponseAppearance.DESTRUCTIVE)
+ alert.set_default_response("cancel")
+ alert.set_close_response("cancel")
+ alert.connect("response", self._on_delete_response, record)
+ alert.present(self)
+
+ def _on_delete_response(
+ self, _alert: Adw.AlertDialog, response: str, record: ManagedMount
+ ) -> None:
+ if response != "delete":
+ return
+ if self._run_helper_action(
+ "Delete", lambda: request_helper_delete(record)
+ ):
+ self.refresh()
+ self.show_toast(f"{record.source} removed")
+
+ class MountManagerApplication(Adw.Application):
+ def __init__(self) -> None:
+ super().__init__(
+ application_id=APP_ID,
+ flags=Gio.ApplicationFlags.DEFAULT_FLAGS,
+ )
+
+ bind_action(self, self, "app.quit", self.quit, ("q",))
+ bind_action(
+ self,
+ self,
+ "app.shortcuts",
+ self._show_shortcuts,
+ ("question",),
+ )
+
+ def _show_shortcuts(self) -> None:
+ window = self.props.active_window
+ if window is None:
+ return
+ dialog = build_shortcuts_dialog()
+ dialog.present(window)
+
+ def do_activate(self) -> None:
+ window = self.props.active_window
+ if window is None:
+ window = MainWindow(self)
+ window.present()
+
+ app = MountManagerApplication()
+ return app.run(sys.argv)
diff --git a/packaging/appimage-helper.patch b/packaging/appimage-helper.patch
index dfe2bb6..d9437c1 100644
--- a/packaging/appimage-helper.patch
+++ b/packaging/appimage-helper.patch
@@ -1,10 +1,14 @@
-diff --git a/mount-manager b/mount-manager
---- a/mount-manager
-+++ b/mount-manager
-@@ -1019,18 +1019,51 @@
- return "light"
+diff --git a/mount_manager.py b/mount_manager.py
+--- a/mount_manager.py
++++ b/mount_manager.py
+@@ -921,18 +921,51 @@
+ return displayed
+-def run_privileged_helper(action: str, payload: dict[str, Any]) -> dict[str, Any]:
+- pkexec = shutil.which("pkexec")
+- if pkexec is None:
+- raise CommandError("pkexec was not found. Install polkit to manage mounts.")
+def appimage_helper_path(env: dict[str, str] | None = None, source_path: Path | None = None) -> str | None:
+ """Return the original AppImage path when running from an AppImage mount."""
+ if env is None:
@@ -24,7 +28,8 @@ diff --git a/mount-manager b/mount-manager
+
+ return appimage
+
-+
+
+- command = [
+def privileged_helper_command(pkexec: str, action: str) -> list[str]:
+ appimage = appimage_helper_path()
+ if appimage is not None:
@@ -36,26 +41,19 @@ diff --git a/mount-manager b/mount-manager
+ ]
+
+ return [
-+ pkexec,
-+ sys.executable,
-+ str(Path(__file__).resolve()),
-+ "--helper",
-+ action,
-+ ]
-+
-+
- def run_privileged_helper(action: str, payload: dict[str, Any]) -> dict[str, Any]:
- pkexec = shutil.which("pkexec")
- if pkexec is None:
- raise CommandError("pkexec was not found. Install polkit to manage mounts.")
-
-- command = [
-- pkexec,
-- sys.executable,
-- str(Path(__file__).resolve()),
-- "--helper",
-- action,
-- ]
+ pkexec,
+ sys.executable,
+ str(Path(__file__).resolve()),
+ "--helper",
+ action,
+ ]
++
++
++def run_privileged_helper(action: str, payload: dict[str, Any]) -> dict[str, Any]:
++ pkexec = shutil.which("pkexec")
++ if pkexec is None:
++ raise CommandError("pkexec was not found. Install polkit to manage mounts.")
++
+ command = privileged_helper_command(pkexec, action)
result = subprocess.run(
command,
diff --git a/packaging/build-appimage.sh b/packaging/build-appimage.sh
index 4132ed8..b5f2a59 100755
--- a/packaging/build-appimage.sh
+++ b/packaging/build-appimage.sh
@@ -87,7 +87,8 @@ mkdir -p "$appdir/usr/share/licenses/$APP_ID"
mkdir -p "$appdir/usr/share/metainfo"
mkdir -p "$dist_dir"
-install -D -m 0755 "$repo_root/mount_manager.py" "$appdir/usr/bin/mount-manager"
+install -D -m 0755 "$repo_root/mount_manager.py" "$appdir/usr/bin/mount_manager.py"
+install -D -m 0644 "$repo_root/mount_manager_ui.py" "$appdir/usr/bin/mount_manager_ui.py"
if ! command -v git >/dev/null 2>&1; then
echo "git is required to apply the AppImage helper workaround." >&2
exit 1
@@ -96,6 +97,7 @@ fi
cd "$appdir/usr/bin"
GIT_DIR= GIT_WORK_TREE=. git apply --no-index --quiet "$repo_root/packaging/appimage-helper.patch"
)
+ln -sf mount_manager.py "$appdir/usr/bin/mount-manager"
install -D -m 0644 "$repo_root/data/icons/hicolor/scalable/apps/$APP_ID.svg" \
"$appdir/usr/share/icons/hicolor/scalable/apps/$APP_ID.svg"
install -D -m 0644 "$repo_root/data/metainfo/$APP_ID.metainfo.xml" \
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/test_libadwaita_support.py b/tests/test_libadwaita_support.py
new file mode 100644
index 0000000..3fd194c
--- /dev/null
+++ b/tests/test_libadwaita_support.py
@@ -0,0 +1,26 @@
+"""Unit tests for the libadwaita version comparator."""
+
+import unittest
+
+from mount_manager import libadwaita_supports
+
+
+class LibadwaitaSupportsTest(unittest.TestCase):
+ def test_minimum_supported_version(self) -> None:
+ self.assertTrue(libadwaita_supports(1, 8))
+
+ def test_newer_minor_supported(self) -> None:
+ self.assertTrue(libadwaita_supports(1, 9))
+
+ def test_newer_major_supported(self) -> None:
+ self.assertTrue(libadwaita_supports(2, 0))
+
+ def test_older_minor_unsupported(self) -> None:
+ self.assertFalse(libadwaita_supports(1, 7))
+
+ def test_older_major_unsupported(self) -> None:
+ self.assertFalse(libadwaita_supports(0, 99))
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_mount_status_line.py b/tests/test_mount_status_line.py
new file mode 100644
index 0000000..b4e15aa
--- /dev/null
+++ b/tests/test_mount_status_line.py
@@ -0,0 +1,51 @@
+"""Unit tests for the AdwActionRow subtitle builder."""
+
+import unittest
+from pathlib import Path
+
+from mount_manager import DisplayedMount
+
+
+def _mount(**overrides: object) -> DisplayedMount:
+ defaults = dict(
+ source="//host/share",
+ mount_point=Path("/mnt/mount-manager/share"),
+ status="Mounted",
+ active=True,
+ openable=True,
+ needs_upgrade=False,
+ managed=True,
+ managed_record=None,
+ )
+ defaults.update(overrides)
+ return DisplayedMount(**defaults) # type: ignore[arg-type]
+
+
+class MountStatusLineTest(unittest.TestCase):
+ def test_combines_mount_point_and_status(self) -> None:
+ from mount_manager_ui import mount_status_line
+
+ line = mount_status_line(_mount(status="Mounted"))
+ self.assertEqual(line, "/mnt/mount-manager/share · Mounted")
+
+ def test_idle_status(self) -> None:
+ from mount_manager_ui import mount_status_line
+
+ line = mount_status_line(_mount(status="Idle", active=False))
+ self.assertEqual(line, "/mnt/mount-manager/share · Idle")
+
+ def test_unmanaged_uses_unmanaged_status(self) -> None:
+ from mount_manager_ui import mount_status_line
+
+ line = mount_status_line(
+ _mount(
+ mount_point=Path("/mnt/elsewhere"),
+ status="Mounted (not managed)",
+ managed=False,
+ )
+ )
+ self.assertEqual(line, "/mnt/elsewhere · Mounted (not managed)")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_smoke.py b/tests/test_smoke.py
new file mode 100644
index 0000000..030792f
--- /dev/null
+++ b/tests/test_smoke.py
@@ -0,0 +1,14 @@
+"""Smoke test ensuring the test harness can import the main module."""
+
+import unittest
+
+
+class ImportSmokeTest(unittest.TestCase):
+ def test_import_mount_manager(self) -> None:
+ import mount_manager # noqa: F401
+
+ self.assertTrue(hasattr(mount_manager, "main"))
+
+
+if __name__ == "__main__":
+ unittest.main()