qol-plugin-gpui-surfaceslisted
Install: claude install-skill qol-tools/qol-skills
# qol-plugin-gpui-surfaces
qol plugins feel "installed" when their UI is native: summoned from the
launcher, centered on the active monitor, keyboard-first, gone on ESC.
The shared kit in `libs/qol-gpui` makes that a wiring job, not a
windowing project. **Never hand-roll plugin windows; extend the kit.**
Contract-driven settings are hosted by qol-tray; custom pickers, overlays,
and toasts remain plugin-owned.
## The shared kit (libs/qol-gpui)
| Piece | File | What it owns |
| --- | --- | --- |
| `Surface` builder | `surface.rs` | Window creation for `SurfaceKind::Toast` (PopUp, unfocused, corner-anchored, optional timeout) and `SurfaceKind::Panel` (Normal, focused, monitor-centered, designed-size locked) |
| `SurfaceDismisser` | `surface.rs` | Close from anywhere (key handler, click, timer). Deferred out of event dispatch - see invariants |
| `Toast` + `ToastHost` | `toast.rs` | Theme-backed passive messages with semantic tones, timed or persistent lifetime, optional activation, replacement, and dismissal |
| `SettingsWindowHost` | `settings_panel/` | Retains exactly one settings window and implements open, focus-same-plugin, replace-with-another-plugin, and park/reveal across Escape |
| `SettingsRuntime::tray` | `settings_panel/` | Routes hosted runtime queries and actions through qol-tray's existing HTTP API |
| `settings_panel::open` / `run_standalone` | `settings_panel/` | Plugin-owned fallback entrypoints for code already running GPUI or starting a standalone GPUI app