Phase 4: radial Actions Ring overlay

.github/workflows/test.yml

@@ -17,9 +17,17 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-      - name: Install
+      - name: Install xvfb and Qt runtime libs
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            xvfb libgl1 libegl1 libxkbcommon-x11-0 libdbus-1-3 \
+            libxcb-cursor0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 \
+            libxcb-randr0 libxcb-render-util0 libxcb-shape0 \
+            libxcb-xinerama0 libxcb-xkb1
+      - name: Install package
         run: |
           python -m pip install --upgrade pip
-          pip install -e ".[dev]"
+          pip install -e ".[dev,ring]"
       - name: Run pytest
-        run: pytest
+        run: xvfb-run -a pytest -q

.gitignore

@@ -1,4 +1,5 @@
 .venv/
+venv/
 *.egg-info/
 __pycache__/
 .pytest_cache/

README.md

@@ -13,9 +13,10 @@ Start with the useful behavior first:
 
 ## Project status
 
-Phase 2 MVP: the CLI listens on a real Logitech MX device via `evdev` and
-fires shell-command actions on configured button presses. No device grabbing,
-no overlay, no profiles yet — those are scheduled for later phases.
+Phase 4: the radial Actions Ring is implemented. The CLI listens on a real
+Logitech MX device via `evdev`, and configured buttons can either fire a
+single action on press or open a radial overlay where the released segment
+fires the action. X11 only in v1; Wayland support is a separate phase.
 
 ## Planned features
 
@@ -30,7 +31,7 @@ no overlay, no profiles yet — those are scheduled for later phases.
 ```bash
 python3 -m venv .venv
 source .venv/bin/activate
-pip install -e ".[dev]"
+pip install -e ".[dev,ring]"
 pytest
 logitechmouse --help
 ```
@@ -65,6 +66,60 @@ See `examples/config.toml` for a working sample. Default examples bind the
 gesture button (`BTN_TASK`) because it has no OS-default action — `BTN_SIDE`
 and `BTN_EXTRA` will double-fire with browser back/forward in this MVP.
 
+### Rings
+
+A `[rings.NAME]` table defines a radial overlay with 3-12 segments. Each
+segment names an existing `[actions.X]` and a label. To open the ring on a
+button, set the binding's target to `ring:NAME`:
+
+```toml
+[rings.thumb_ring]
+segments = [
+  { action = "screenshot_area", label = "Area" },
+  { action = "screenshot_full", label = "Full" },
+  { action = "lock",            label = "Lock" },
+]
+
+[bindings.gesture_button]
+trigger = "BTN_TASK"
+target  = "ring:thumb_ring"
+```
+
+The ring opens on key-down at the cursor position, follows your cursor as you
+hold the button, and fires the highlighted segment when you release. Releasing
+in the center cancels.
+
+### Targets vs legacy `action = "..."`
+
+Bindings use `target = "kind:name"`:
+- `target = "action:screenshot"` - fire `actions.screenshot` on press.
+- `target = "ring:thumb_ring"` - open `rings.thumb_ring` on press, fire on release.
+
+The Phase 2 form `action = "screenshot"` is still accepted; the loader maps it
+to `target = "action:screenshot"` and logs a one-line migration note.
+
+### Optional install for ring support
+
+The radial ring needs PyQt6. Install with:
+
+```bash
+pip install 'logitechmouse[ring]'
+```
+
+Without `[ring]` you can still use action-only bindings; configs that define
+ring bindings will fail validation with a clear message.
+
+### Themes
+
+The ring ships with a dark default. A second palette is available via env var:
+
+```bash
+LOGITECHMOUSE_THEME=brazil logitechmouse listen
+```
+
+Themes today: `dark` (default), `brazil` (green/yellow/blue, bandeira do Brasil).
+Full theming via config is a polish phase; the env var is the v1 escape hatch.
+
 ## Documents
 
 - [Product Requirements](docs/PRD.md)

docs/PRD.md

@@ -13,7 +13,7 @@ A Linux laptop or desktop user with a Logitech MX mouse who wants one-press prod
 - Bind MX mouse buttons to user-defined actions.
 - Support command execution and keyboard shortcut emission.
 - Make screenshots a first-class built-in workflow.
-- Provide a path toward an optional radial overlay.
+- Provide an optional radial overlay (Phase 4 — shipped).
 
 ## Non-goals
 
@@ -36,4 +36,5 @@ The MVP should:
 - a user can press one MX button and capture a screenshot
 - configuration changes do not require code edits
 - the system is modular enough to add overlay support later
+- pressing and holding a configured button opens a ring; releasing on a segment fires its action.