pyobs-gui 2.0.0.dev1__tar.gz → 2.0.0.dev2__tar.gz

pyobs_gui-2.0.0.dev2/.claude/skills/verify/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: verify
+description: Drive the real pyobs-gui app headlessly against a real pyobs module (LocalComm) to verify a widget change actually works end-to-end.
+---
+
+# Verifying pyobs-gui changes
+
+pyobs-gui is a PySide6 app that talks to pyobs modules over `Comm`. There's no
+pytest suite (see `DEVELOPMENT.md`) — verification means running the real
+`GUI` module against a real target module and observing widget state /
+screenshots. This works headlessly, no Xvfb needed.
+
+## The recipe
+
+`test/*.yaml` are `MultiModule` fixtures that run a target module (e.g.
+`DummyCamera`) and `pyobs_gui.GUI` in one process, connected via
+`pyobs.comm.local.LocalComm` (in-process, no network). Normally launched with
+`uv run pyobs test/camera.yaml`, but for scripted verification, drive it from
+Python directly so you can reach into live widget state:
+
+```python
+import os
+os.environ["QT_QPA_PLATFORM"] = "offscreen"  # before importing PySide6/qasync
+
+import asyncio, yaml
+from pyobs.object import get_object
+from pyobs.modules import Module
+from pyobs_gui.gui import GUI
+
+async def main():
+    with open("test/camera.yaml") as f:
+        cfg = yaml.safe_load(f)
+    multi = get_object(cfg, Module)
+    await multi.open()          # returns once sub-modules are *scheduled*, not ready
+    gui = multi["gui"]
+    # poll gui._window, then window._widgets["<module-name>"] until present
+    ...
+
+loop = GUI.new_event_loop()     # QApplication(offscreen) + qasync.QEventLoop
+asyncio.set_event_loop(loop)
+loop.run_until_complete(main())
+```
+
+A working end-to-end example lives in git history / can be reconstructed from
+this skill — see the gotchas below, they're all non-obvious.
+
+## Gotchas
+
+1. **`MultiModule.open()` doesn't wait for children.** Each sub-module opens
+   as its own asyncio task. Poll `gui._window is not None`, then
+   `"<name>" in window._widgets`, with `asyncio.sleep(0.1)` between checks.
+
+2. **Widgets only run `_init()` on a real Qt `showEvent`**
+   (`pyobs_gui/base.py:245-252`, `BaseWidget.showEvent`/`_showEvent`). A
+   widget sitting in a `QStackedWidget` that's never made current, or a
+   `QMainWindow` that's never `.show()`n, never fires it — `has_proxy`/
+   `subscribe_state` calls in `_init()` never run, buttons stay disabled
+   forever. Always `window.stackedWidget.setCurrentWidget(widget)` +
+   `window.show()` *before* waiting for the widget to become enabled.
+
+3. **Don't call `QApplication.processEvents()` manually inside a coroutine
+   running on the qasync loop.** It reenters qasync's own dispatch and
+   silently drops other scheduled coroutines (you'll see spurious
+   `RuntimeWarning: coroutine '...' was never awaited` for totally unrelated
+   widgets). Just `await asyncio.sleep(...)` — qasync pumps Qt events as
+   part of the normal loop.
+
+4. **Fire-and-forget RPCs prove nothing about the server side just by not
+   raising.** Methods like `IDataSequence.grab_sequence()` return
+   immediately; the real work happens in a background task on the target
+   module. A clean `await proxy.grab_sequence(...)` only means the call
+   dispatched — verify the actual effect via the pushed state
+   (`subscribe_state` callback / widget fields) or a registered event
+   handler (e.g. `NewImageEvent`), not the call's return.
+
+5. **`DummyCamera`'s default `"pyobs"` VFS root is hardcoded to
+   `/opt/pyobs/storage/`** (`pyobs/vfs/vfs.py`), used for its FITS
+   frame-number cache regardless of your `vfs:` config — not writable by a
+   regular user. Override it in the loaded config before `get_object()`:
+   ```python
+   cfg["vfs"]["roots"]["pyobs"] = {"class": "pyobs.vfs.LocalFile", "root": "/tmp/some-writable-dir/"}
+   ```
+   (YAML anchors mean `cfg["vfs"]` is shared by reference with each module's
+   `vfs: *vfs`, so mutating the top-level dict before construction is
+   enough.)
+
+6. **`DummyCamera` needs the optional `photutils` package** to simulate
+   images at all (`pip install photutils` into the venv — not a pyobs-gui
+   dependency, just needed for this fixture). Even then, as of photutils
+   3.0.0 there's a real incompatibility bug in pyobs-core's
+   `DummyCamera._simulate_image()`: `make_model_image()` is called with a
+   params table using column name `x_0`, which newer photutils rejects
+   (`ValueError: value "x_0" not in params_table column names`) — but only
+   when `exposure_time > 0` (it tries to paint simulated star sources sized
+   by exposure). Setting exposure_time to `0.0` sidesteps it entirely, and
+   `DummyCamera`'s default `readout_time=2` (seconds, per grab) is still
+   enough on its own to observe multi-grab sequence progress and test
+   aborting mid-sequence.
+
+## Capturing evidence
+
+`window.grab().save(path)` on the (offscreen) `QMainWindow` produces a real
+PNG of the actual rendered UI — read it back with the Read tool to inspect.

pyobs_gui-2.0.0.dev2/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "tuesday"
+    target-branch: "develop"
+    labels:
+      - "dependencies"

pyobs_gui-2.0.0.dev2/DEVELOPMENT.md

@@ -0,0 +1,155 @@
+# Development
+
+Backlog of planned work for pyobs-gui. Newest/most important items at the top.
+
+## pyobs-core 2.0 ACLs — hide/grey out actions an operator isn't permitted to use
+
+**Status: Option B implemented and verified end-to-end against pyobs-core 2.0.0.dev11 (the first
+release with ACL support).** `BaseWidget._fetch_permitted_methods()` / `BaseWidget.permitted()`
+(`base.py`) fetch and cache `IModule.get_permitted_methods()` once per widget, guarded by
+`hasattr(IModule, "get_permitted_methods")` so it's a no-op against any older pinned pyobs-core
+(>=2.0.0.dev6) that predates the feature — `permitted()` then falls back to "everything allowed."
+Wired into `filterwidget.py`, `modewidget.py`, and `telescopewidget.py` (buttons, `move()` branches,
+and `compassmovewidget`'s enable state). Fully-denied modules are hidden from the sidebar via the
+same `get_permitted_methods()` fetch in `mainwindow.py:_client_connected`.
+
+Verified with two new fixtures, `test/telescope_acl.yaml` (`acl: allow: {gui: [init, move_radec,
+set_offsets_radec]}`) and `test/telescope_acl_denied.yaml` (`acl: allow: {gui: []}`), driven via a
+`LocalComm`-backed harness (no pytest suite exists in this repo) that opens the real `GUI` module
+against a real ACL-enforcing `DummyTelescope` and inspects live widget state:
+- `telescope_acl.yaml`: `_permitted_methods` came back exactly `{init, move_radec,
+  set_offsets_radec}`; every button/branch gated on a permitted method stayed enabled
+  (`buttonMove`, `buttonSetRaOffset`, `buttonSetDecOffset`, `buttonResetEquatorialOffsets`,
+  `compassmovewidget`, `permitted("move_radec")`), every one gated on a denied method was forced off
+  (`buttonPark`, `buttonSetAltOffset`, `buttonSetAzOffset`, `buttonResetHorizontalOffsets`,
+  `permitted("move_altaz")`) — cross-checked with `motion_status=idle` so state-based gating alone
+  wouldn't explain the result.
+- `telescope_acl_denied.yaml`: `MainWindow._client_connected` returned `False` for the telescope
+  client and it never entered `_widgets`, confirming the fully-denied module never reaches the
+  sidebar.
+
+<details>
+<summary>Original planning notes</summary>
+
+`pyobs-core` 2.0's per-module access control has landed on its `develop` branch: Phase 8 is
+implemented in full (`exc.ForbiddenError`, `acl:` config parsing, the `Module.execute()` check,
+`IModule.get_permitted_methods()`, XMPP `forbidden`-condition mapping) — confirmed directly against
+`pyobs-core`'s code and tests (`pyobs/interfaces/IModule.py`, `pyobs/modules/module.py:388-390,597`,
+`tests/modules/test/standalone.py`), not just its own `DEVELOPMENT.md` claims. See its
+[Access Control (ACLs)](https://github.com/pyobs/pyobs-core/blob/develop/DEVELOPMENT.md#access-control-acls)
+section.
+
+`IModule.get_permitted_methods(**kwargs) -> list[str]` returns the names of methods the *calling*
+module is allowed to invoke on the target — caller-specific, always permitted itself (exempted from
+its own ACL check), so any widget can call it on its target proxy to ask "what am I allowed to do
+here" up front.
+
+**Reactive handling already works today, no change needed:** `BaseWidget._background_task`
+(`pyobs_gui/base.py:271-277`) already catches `exc.PyObsError` generically around every RPC call
+and routes it to `show_error` (`base.py:282-285`), a plain message box with the exception's text.
+`exc.ForbiddenError` is a `RemoteError` is a `PyObsError`, so a denied call already surfaces as a
+normal error dialog — confirmed by reading the actual code, not assumed.
+
+**Open, now unblocked — proactive greying-out of unpermitted actions:** widgets already have a
+disable/enable mechanism built for a different purpose — `_enable_buttons.emit(disable, False)` /
+`w.setEnabled(enable)` (`base.py:268,287-289`) — currently only used to disable buttons while their
+own background task is running. The natural fix is to reuse the same mechanism for "not permitted,"
+fetched once per widget via `get_permitted_methods()` alongside the capabilities/state it already
+pulls from its target proxy at setup, rather than only finding out via an error dialog after the
+operator clicks.
+
+**Decided: grey out individual actions, not hide them — except a fully-blocked module, which can be
+hidden from the sidebar entirely.** `pyobs-core`'s own design doc hedges throughout ("grey out or
+hide") without picking one. Within a widget, the only mechanism it actually points at is the
+existing `_enable_buttons` / `setEnabled()` path, which disables widgets — it doesn't remove them
+from a layout — and hiding individual buttons would be new machinery (layout changes,
+`setVisible(False)` bookkeeping) for no stated benefit, so the per-action plan is disable-only.
+
+But a *module* that's entirely blocked (`get_permitted_methods()` returns `[]` for this GUI's
+identity) is a different case, and there hiding is both possible and natural: `mainwindow.py`'s
+`_client_connected` (376-424) already has an early-return "ignore it?" gate for `show_modules`
+allowlisting, right before a module gets a widget or a nav entry at all
+(`mainwindow.py:381-383`) — before `_add_client` runs, so before `self.listPages.addItem(item)`
+(`mainwindow.py:241-270`). A "fully denied" check slots into the exact same spot: fetch
+`get_permitted_methods()` once per newly-connected client, and if it comes back empty, `return
+False` there instead of building a widget for it — the module never appears in the sidebar/nav list
+at all, not merely greyed out. This reuses the identical pattern already in place for
+`show_modules`, so it's cheap to add alongside the per-widget button work below, not a separate
+design.
+
+**Granularity: fetch per-widget, apply per-button — not a single per-widget on/off switch.** Two
+things are independent:
+
+- **The `get_permitted_methods()` fetch is per-widget** (really per-target-proxy): each widget
+  already talks to one module via `self.comm.proxy(self.module, ...)`, so it fetches once at setup,
+  alongside the state/capabilities it already pulls there.
+- **The enable/disable decision is per-button.** Widgets already have fine-grained, per-button
+  `setEnabled()` calls keyed to current state — e.g. `telescopewidget.py:266-294`:
+  `self.buttonInit.setEnabled(self._motion_status == MotionStatus.PARKED)`,
+  `self.buttonPark.setEnabled(...)`, `self.buttonStop.setEnabled(...)`. Each button maps to a
+  different RPC method (`init`, `park`, `stop`, `move_radec`, ...), often on a different interface
+  (`IMotion`, `IPointingRaDec`, `IOffsetsAltAz`, ...) even within the same widget. ACL greying is a
+  second condition ANDed into each existing check — e.g.
+  `buttonPark.setEnabled(initialized and "park" in self._permitted_methods)` — not a single
+  "is this whole widget permitted" switch.
+
+**Concrete surface: only widgets that already gate buttons on background tasks.** Grepping
+`run_background(` with a `disable=` argument across `pyobs_gui/*.py` finds exactly four files with
+actionable buttons to gate: `telescopewidget.py` (6 call sites), `filterwidget.py`, `modewidget.py`,
+`compassmovewidget.py`. Not every `BaseWidget` subclass needs this — several
+(`weatherwidget.py`, `datadisplaywidget.py`, `eventswidget.py`, etc.) are read-only displays with no
+actions to gate at all.
+
+### Option A: reactive-only (already shipped, zero work)
+
+The reactive path needs no new code at all — confirmed by reading `base.py`, not assumed:
+
+- Every RPC call goes through `BaseWidget._background_task` (`base.py:271-277`), which already
+  wraps `await method(*args, **kwargs)` in `try/except exc.PyObsError as e: await
+  self.show_error(e)`.
+- `show_error` (`base.py:282-285`) already pops a `QAsyncMessageBox.warning` with the exception's
+  own text.
+- A denial surfaces client-side as `exc.RemoteError(sender, f"Forbidden to invoke {method} at
+  {target}!")` (`pyobs-core`'s `pyobs/comm/xmpp/rpc.py:299`) — a `RemoteError` is a `PyObsError`, so
+  it's already caught by the generic handler above with a reasonable message.
+
+Net: zero implementation. The only "work" is a manual smoke test against an ACL-restricted module
+to confirm the dialog text reads sensibly. Weaker UX than greying out (the operator can still click
+into a wall instead of seeing the action disabled up front), but it's the free fallback and already
+covers the "reactive handling" bullet above.
+
+### Option B: proactive greying-out — effort estimate (~half a day, 3-5 hours)
+
+Bigger than Option A, but still small — no new architecture, just extending gating logic that
+already exists in four files:
+
+1. **Fetch (~30 min).** `get_permitted_methods()` lives on `IModule`, not on `Comm` like the cheap
+   `get_interfaces()`/`get_capabilities()` calls, so it needs an actual proxy round trip:
+   `async with self.comm.proxy(self.module, IModule) as proxy: permitted =
+   set(await proxy.get_permitted_methods())`. Mirrors the existing pattern at
+   `telescopewidget.py:144` (`self._interfaces = await self.comm.get_interfaces(self.module)`),
+   fetched once in `_init()`/`open()`. Worth a shared helper on `BaseWidget` so the four widgets
+   don't duplicate the round trip.
+
+2. **Wiring into existing per-button gating (~1.5-2.5 hours, mostly `telescopewidget.py`).**
+   - `filterwidget.py`, `modewidget.py`: trivial — one `setEnabled()` call site each, already gated
+     on state; AND in `"set_filter" in self._permitted` / `"set_mode" in self._permitted`.
+   - `compassmovewidget.py`: **no internal changes needed** — already gated as a whole block by its
+     parent, `self.compassmovewidget.setEnabled(initialized)` at `telescopewidget.py:288`. Just AND
+     the relevant offset method's permission into that one line.
+   - `telescopewidget.py`: the real work — ~8-10 buttons (`buttonInit`, `buttonPark`, `buttonStop`,
+     `buttonMove`, 4x offset buttons, 2x reset-offset buttons), each needing its existing
+     `update_gui()` `setEnabled()` line extended with a permission check. `buttonMove` is the one
+     wrinkle: it maps to 4 different RPC methods (`move_radec`/`move_altaz`/`move_hgs`/
+     `move_helioprojective`) depending on the selected coordinate tab — but `move()`
+     (lines 328-392) already branches per-coordinate-type at click time and pops a
+     `QMessageBox.critical` for unsupported types, so the permission check slots into that existing
+     branch rather than requiring new architecture.
+
+3. **Verification (~1 hour).** UI behavior, not something type-checking catches — needs a manual
+   pass (or a `LocalComm`-backed integration test) against a module with an `acl:` block denying a
+   couple of methods, confirming the right buttons actually grey out.
+
+Option A is a strict subset of Option B's work, so nothing here is wasted if Option B follows later.
+
+</details>

pyobs_gui-2.0.0.dev2/DEV_IAcquisition.md

@@ -0,0 +1,95 @@
+# IAcquisition widget
+
+**Status:** implemented and shipped.
+
+## Shipped (pyobs-core, `develop`)
+
+`IAcquisition` (`pyobs/interfaces/IAcquisition.py`) inherits `IRunning` and `IAbortable`:
+
+```python
+class IAcquisition(IRunning, IAbortable, metaclass=ABCMeta):
+    state = AcquisitionState
+
+    async def acquire_target(self, **kwargs: Any) -> AcquisitionResult: ...
+```
+
+`Acquisition.acquire_target()` publishes `RunningState` around the run, same pattern as
+`IAutoFocus`. Per-attempt telemetry is published live via a dedicated growing state, mirroring
+`AutoFocusState`:
+
+```python
+@dataclass
+class AcquisitionResult:
+    time: Time
+    ra: Annotated[float, Unit.DEGREES]
+    dec: Annotated[float, Unit.DEGREES]
+    alt: Annotated[float, Unit.DEGREES]
+    az: Annotated[float, Unit.DEGREES]
+    offset_frame: OffsetFrame | None = None
+    offset_lon: Annotated[float, Unit.DEGREES] | None = None
+    offset_lat: Annotated[float, Unit.DEGREES] | None = None
+
+@dataclass
+class AcquisitionAttempt:  # AcquisitionState.attempts element
+    attempt: int
+    distance: Annotated[float, Unit.ARCSEC]
+    offset_applied: bool
+    offset_frame: OffsetFrame | None = None
+    offset_lon: Annotated[float, Unit.DEGREES] | None = None
+    offset_lat: Annotated[float, Unit.DEGREES] | None = None
+
+@dataclass
+class AcquisitionState:
+    attempts: list[AcquisitionAttempt] = field(default_factory=list)
+    result: AcquisitionResult | None = None
+    time: Time = field(default_factory=Time.now)
+```
+
+Note this is `offset_frame`/`offset_lon`/`offset_lat`, not the originally-sketched
+`off_ra`/`off_dec`/`off_alt`/`off_az` (see "Resolved from the original open questions" below) —
+`off_ra`/`off_dec` and `off_alt`/`off_az` were mutually-exclusive duplicate field pairs, since only
+one is ever populated depending on mount type; a single `offset_frame` enum + generic `lon`/`lat`
+pair replaces both. `OffsetFrame` itself lives in `pyobs/utils/enums.py` (alongside `Unit`), not in
+this file — it's shared with `IAutoGuiding` and `pyobs.utils.offsets`.
+
+`offset_frame`/`offset_lon`/`offset_lat` report the telescope's **cumulative** offset (queried via
+`IOffsetsRaDec`/`IOffsetsAltAz` state, through a small `Acquisition._get_offsets()` helper), fetched
+after each attempt applies a correction and once more for the final result. This is deliberately
+different from `IAutoGuiding`'s `GuidingState`, which reports the size of each individual correction,
+not a cumulative value — see `DEV_IAutoGuiding.md` for why the two interfaces need different
+semantics despite looking superficially similar.
+
+`Acquisition._acquire()` publishes a new `AcquisitionAttempt` as soon as the distance is known
+(before applying the correction, so the distance plot updates immediately), then republishes the
+same attempt with `offset_frame`/`offset_lon`/`offset_lat` filled in once the correction is applied.
+
+## Widget design (pyobs-gui) — shipped
+
+Same visual language as the `IAutoFocus` widget, but with **two** plots side by side
+(`plt.subplots(1, 2)` in a single `framePlot`):
+
+- left (`ax`): distance-to-target (arcsec) vs. attempt number, integer x-axis ticks
+  (`MaxNLocator(integer=True)`)
+- right (`ax2`): 2D trajectory of the accumulated offset in whichever frame the mount supports
+  (RA/Dec or Alt/Az, degrees), points connected by a line since this is a single converging run,
+  with distinct "start" (red square) and "latest" (green star) markers and reference crosshairs at
+  (0, 0) — this is what actually motivated moving to `offset_frame`/`offset_lon`/`offset_lat`, since
+  a fixed set of four `off_*` labels couldn't drive a "show whichever pair is real" plot cleanly
+- `buttonAcquire` (green) / `buttonAbort` (red), grey out via ACL (`permitted("acquire_target")`/
+  `permitted("abort")`, same convention as `telescopewidget.py`/`filterwidget.py`/`modewidget.py`)
+- `labelStatus` — Idle / Acquiring... / `Acquired.`
+- Result group box: RA/Dec, Alt/Az, and a single offset row whose label text switches between
+  "RA/Dec offset:"/"Alt/Az offset:" based on `AcquisitionResult.offset_frame`
+
+State handling (`_on_running_state`/`_on_acquisition_state`) matches the original sketch: clear
+`self._attempts`/`self._result` on the `IRunning` rising edge, otherwise just mirror
+`AcquisitionState.attempts`/`.result` and re-render on every update.
+
+## Resolved from the original open questions
+
+- ~~`off_ra`/`off_dec` vs `off_alt`/`off_az` are mutually exclusive~~ — resolved by replacing both
+  pairs with a single `offset_frame` (`OffsetFrame.RA_DEC`/`ALT_AZ`) + `offset_lon`/`offset_lat`
+  pair, in both `AcquisitionResult` and `AcquisitionAttempt`. The widget picks the right axis
+  labels/result-row text from `offset_frame` instead of checking which pair is non-`None`.
+- ~~Should `attempts` be capped~~ — left uncapped, as expected: it's naturally bounded by
+  `self._attempts` (the configured max attempt count), same reasoning as before.

pyobs_gui-2.0.0.dev2/DEV_IAutoFocus.md

@@ -0,0 +1,162 @@
+# IAutoFocus widget
+
+**Status:** design proposal — not implemented yet.
+
+## Current state (pyobs-core, `develop`)
+
+`IAutoFocus` (`pyobs/interfaces/IAutoFocus.py:30`) inherits only `IAbortable`, not `IRunning`:
+
+```python
+class IAutoFocus(IAbortable, metaclass=ABCMeta):
+    state = AutoFocusState  # points: list[AutoFocusPoint], time
+```
+
+`AutoFocusState.points` (`IAutoFocus.py:25`) grows during a run — the sole implementation,
+`AutoFocusSeries` (`pyobs/modules/focus/focusseries.py`), calls
+`set_state(IAutoFocus, AutoFocusState(points=...))` once per focus step (`focusseries.py:224`)
+after resetting the series at the start of `_auto_focus()`.
+
+The module tracks a `self._running` flag locally (`focusseries.py:68`, set `True`/`False` around
+the run at `126`/`131`) but never publishes it — there is no live "is this thing running" signal on
+the wire. The only completion signal is `FocusFoundEvent` (`pyobs/events/focusfound.py`), sent once
+on success; nothing is sent on failure or abort.
+
+## Gap
+
+A widget that didn't itself trigger the run (e.g. the scheduler ran an autofocus) has no way to know
+a run started, and no way to know a run ended in *failure* — points just stop growing, silently.
+
+## Proposed pyobs-core change
+
+Add `IRunning` to `IAutoFocus`'s bases, and have `AutoFocusSeries` actually publish it:
+
+```python
+# IAutoFocus.py
+from .IRunning import IRunning, RunningState
+
+class IAutoFocus(IRunning, IAbortable, metaclass=ABCMeta):
+    ...
+```
+
+```python
+# focusseries.py
+async def auto_focus(self, count: int, step: float, exposure_time: float, **kwargs: Any) -> AutoFocusResult:
+    try:
+        self._running = True
+        await self.comm.set_state(IRunning, RunningState(running=True))
+        focus, error = await self._auto_focus(count, step, exposure_time, **kwargs)
+        return AutoFocusResult(focus=focus, focus_err=error)
+    finally:
+        self._running = False
+        await self.comm.set_state(IRunning, RunningState(running=False))
+
+async def is_running(self, **kwargs: Any) -> bool:
+    return self._running
+```
+
+`AutoFocusState` and `RunningState` are independent pubsub topics (`set_state`/`subscribe_state` key
+off the interface class passed in — confirmed against `pyobs/comm/comm.py:468,544`), so this
+doesn't conflict with the existing points state, and mirrors the pattern `FocusWidget` already uses
+for `IFocuser` + `IMotion`.
+
+## Widget design (pyobs-gui)
+
+A focus/value scatter plot, matplotlib-in-a-frame the same way `TemperaturesPlotWidget` does it
+(`pyobs_gui/temperaturesplotwidget.py`), plus run controls.
+
+Layout:
+- `framePlot` — matplotlib canvas, x = focus, y = metric
+- `spinCount` / `spinStep` / `spinExposureTime` — the three `auto_focus()` params
+- `buttonRunAutoFocus` (green) / `buttonAbort` (red)
+- `labelStatus` — Idle / Running... / `Focus: 12.345 ± 0.012 mm`
+
+```python
+class AutoFocusWidget(BaseWidget, Ui_AutoFocusWidget):
+    signal_update_gui = QtCore.Signal()
+
+    def __init__(self, **kwargs: Any):
+        BaseWidget.__init__(self, **kwargs)
+        self.setupUi(self)
+
+        self._points: list[AutoFocusPoint] = []
+        self._running = False
+        self._last_result: tuple[float, float] | None = None
+
+        self.figure, self.ax = plt.subplots()
+        layout = QtWidgets.QVBoxLayout(self.framePlot)
+        self.canvas = FigureCanvas(self.figure)
+        layout.addWidget(self.canvas)
+
+        self.signal_update_gui.connect(self.update_gui)
+        self.buttonRunAutoFocus.clicked.connect(self._run_auto_focus)
+        self.buttonAbort.clicked.connect(self._abort)
+        self.colorize_button(self.buttonRunAutoFocus, QtCore.Qt.GlobalColor.green)
+        self.colorize_button(self.buttonAbort, QtCore.Qt.GlobalColor.red)
+
+    async def _init(self) -> None:
+        await self.comm.subscribe_state(self.module, IRunning, self._on_running_state)
+        await self.comm.subscribe_state(self.module, IAutoFocus, self._on_autofocus_state)
+        await self.comm.register_event(FocusFoundEvent, self._on_focus_found)
+
+    def _on_running_state(self, state: RunningState) -> None:
+        if state.running and not self._running:
+            # rising edge -> a new run started (possibly triggered elsewhere), clear the plot
+            self._points = []
+            self._last_result = None
+        self._running = state.running
+        self.signal_update_gui.emit()
+
+    def _on_autofocus_state(self, state: AutoFocusState) -> None:
+        self._points = state.points
+        self.signal_update_gui.emit()
+
+    def _on_focus_found(self, event: FocusFoundEvent, sender: str) -> None:
+        if sender != self.module:
+            return
+        self._last_result = (event.focus, event.error or 0.0)
+        self.signal_update_gui.emit()
+
+    def update_gui(self) -> None:
+        self.buttonRunAutoFocus.setEnabled(not self._running)
+        self.buttonAbort.setEnabled(self._running)
+        self.labelStatus.setText(
+            "Running..." if self._running
+            else f"Focus: {self._last_result[0]:.3f} \u00b1 {self._last_result[1]:.3f} mm" if self._last_result
+            else "Idle"
+        )
+
+        self.ax.clear()
+        if self._points:
+            self.ax.scatter([p.focus for p in self._points], [p.value for p in self._points], color="tab:blue")
+        if self._last_result and not self._running:
+            self.ax.axvline(self._last_result[0], color="tab:green", linestyle="--", label="fitted focus")
+            self.ax.legend()
+        self.ax.set_xlabel("Focus [mm]")
+        self.ax.set_ylabel("Metric")
+        self.ax.grid(linestyle=":", alpha=0.5)
+        self.ax.set_axisbelow(True)
+        self.canvas.draw()
+
+    @qasync.asyncSlot()  # type: ignore
+    async def _run_auto_focus(self) -> None:
+        async with self.comm.proxy(self.module, IAutoFocus) as proxy:
+            await proxy.auto_focus(self.spinCount.value(), self.spinStep.value(), self.spinExposureTime.value())
+
+    @qasync.asyncSlot()  # type: ignore
+    async def _abort(self) -> None:
+        async with self.comm.proxy(self.module, IAutoFocus) as proxy:
+            await proxy.abort()
+```
+
+The widget is entirely state-driven: `_run_auto_focus`/`_abort` just fire RPCs, and the display
+updates purely from what the module publishes — correct with multiple GUI instances open, or a
+scheduler-triggered run, unlike a design that tracks "am I running" as local widget state.
+
+## Open questions
+
+- `FocusFoundEvent` still isn't sent on failure/abort — with `RunningState` in place the widget at
+  least knows the run *ended*, but not *why*. Worth a follow-up event (`FocusFailedEvent`?) or just
+  leaving "Idle" as the catch-all for "not running, no success yet" and letting the operator check
+  logs for failures.
+- Should the fitted-focus vertical line persist across the next run's points, or clear immediately
+  on the next rising edge? Current design clears it on rising edge (new run hides the old fit).