Settings window redesign — sidebar + pages¶

Status: IMPLEMENTED on branch feat/settings-sidebar-pages (2026-10-24), unmerged and unreleased. Path: architectural. The owner delegated the open questions (§7) and the implementation; where the build departed from this document, §9 says so.

1. Problem¶

SettingsWindow.__init__ (src/yazses/settingsui/app.py) stacks everything in one QVBoxLayout: tooltip hint, snap banner, Hands-free button, hotkey row, Speech group (8 rows), Audio group, maintenance box, filter box, and only then the QScrollArea holding the capability toggles (well over a hundred rows, grouped by category). The scroll area receives whatever height is left. At the default 680x760 size that is roughly 70 px, so the Features list — the largest part of the product — is effectively invisible, and the window reads as an unstructured form.

2. Goals / success criteria¶

• Any setting reachable in two clicks or one search, without scrolling past unrelated controls.
• The Features list gets the full height of the window, with category navigation.
• Pending changes are always visible and Apply is always reachable.
• Follows the desktop theme (light and dark); keeps the WCAG AA muted-text guarantee of settingsui/theme.py.

3. Non-goals (hard constraints)¶

• No behavior change. Staging, PendingChanges, Apply, restart offer, dependency install, language-profile worker, experimental confirmation, Restore defaults semantics: untouched.
• No config-key, CLI, or IPC change (these are L3 interfaces per AGENTS.md).
• No new dependency; PySide6 stays the optional desktop extra, imported lazily.
• No new network access, telemetry, or anything under ADR-019.
• The ? details dialog, tooltips, accessible names/descriptions are preserved.

4. Design¶

4.1 Shell¶

Window default 900x640, minimum 760x520. Left sidebar (QListWidget, icon-less text entries so it works on every platform without bundled assets), right QStackedWidget.

Pinned outside the stack: - Top: the snap-permission banner (_add_snap_banner), unchanged. - Bottom footer bar: Restore defaults (left), live status text (centre, replaces the _hint line but _hint keeps its role for _apply()/_busy() callers), Apply (right). - Sidebar entries carry a "•" marker when their page holds staged changes.

The long "Hover any capability…" sentence moves from the top of the window to the Features page header, where it is relevant.

4.2 Features page¶

• Top bar: the existing filter box (same syntax: text, on:/off:, tier:), full width, with the describe_filter line beside it. Syntax help moves from a tooltip to a small popover with clickable examples.
• Left pane (~190 px): category list. "All" first, then each category as Name · enabled/total. While a filter is active, categories show their match count and empty ones are greyed.
• Right pane: scrolling rows for the selected category (or all, with headings, for "All"). The category blurb becomes the pane heading.
• Rows: _build_row behavior unchanged (checkbox, ?, tooltip card, accessible description). Visual changes only: flat rows with a divider instead of nested group boxes, a small tier chip from row.tier_label, and an accent bar on rows that are staged but not applied.
• Keyboard: Ctrl+F focuses the filter; Up/Down move through categories; sidebar entries have mnemonics.

4.3 Code shape¶

• New dependency-free module settingsui/pages.py (pure): per-category enabled/total counts, per-page "has staged changes", tier-chip text, category-visibility for a query. Unit-tested directly (house pattern: pure logic beside Qt shell, cf. search.py, controller.py).
• New Qt shell module settingsui/shell.py: sidebar, stack, footer. app.py keeps all apply / restart / install / language logic and only changes the layout assembly in __init__, so the 1,700-line file does not grow.
• Existing attribute names that other code and tests read (_checkboxes, _info_buttons, _group_widgets, _filter_box, _filter_status, _hint, _apply_button, _reset_button, _hotkey_box, _handsfree_button, …) are kept. Filtering continues to change visibility only; a hidden row keeps its staged state.

5. Testing¶

• Pure: tests/test_settingsui_pages.py for §4.3 helpers.
• Offscreen Qt smoke (same style as tests/test_settingsui_window.py): window builds; every slug has exactly one checkbox; selecting a category / filtering hides rows without un-staging; sidebar marker follows staged state; Apply/Restore still enabled during the states they were before.
• The existing test_settingsui_*, test_settings_* and test_tray_settings_* suites must pass unmodified except where a test asserts layout structure; any such edit is called out in the PR body.
• tests/test_gui_job_covers_the_settingsui_family.py must be checked: new modules need to be inside the family the GUI CI job covers.
• Full gates before any claim of done: uv run python -m pytest tests/ -v, uv run ruff check src tests scripts paper/benchmark, uv run mypy src (after uv sync --extra desktop, so Qt call sites are type-checked for real).

6. Docs surfaces¶

CHANGELOG.md [Unreleased]; user-facing settings docs under docs/ if they describe the window layout or include screenshots; design/architecture.md only if the module list is enumerated there. No generated file is touched.

7. Open questions for the owner¶

1. Sidebar order and naming — is "General" the right home for the hotkey, or should Speech own it?
2. Should the window remember its size and last-opened page between launches? (Would need a state file; default proposal: no, keep it stateless.)
3. Screenshots in docs: re-take after implementation, yes/no?

8. Risks¶

• Existing tests reaching into private widgets may assume the old nesting; mitigated by keeping attribute names and by reading those tests during planning before touching __init__.
• Offscreen Qt rendering differs from a real desktop; the final check must include a real screenshot of the window on this machine (light and dark).

9. As built — departures from the draft above¶

• Open questions decided (owner said to decide): the hotkey stays on General; the window is stateless (no remembered size or page); docs screenshots re-taken because docs/settings-gui.md already carried one.
• Tier chips dropped. Each row's subtitle already begins with the tier ("recommended — ..."), so a chip said the same thing twice. pages.tier_chip was removed.
• Disabled categories are hidden, not greyed. Greyed text was unreadable on a light theme.
• Sidebar mnemonics became Ctrl+1..Ctrl+6. A QListWidget has no mnemonics; shortcuts on the window work from any focus.
• Filter syntax is a visible line under the search box rather than a popover.
• Page boxes are unframed (their title is the page heading); the capability categories keep their titled QGroupBox, which the filter and the ampersand guard rely on.
• Category list items are measured from their wrapped text, because Qt clipped one to "…".
• New modules: settingsui/pages.py (pure), settingsui/shell.py (Qt frame). Tests: test_settingsui_pages.py, test_settingsui_window_pages.py. The existing window tests were not edited.
• Not verified: the look on a real desktop session. Screenshots were rendered offscreen with the Fusion style, in light and dark palettes.