repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

skill(quickshell): dprint fmt SKILL.md

4896927ecdac1393fa748f4e5470be70f2f0f77b

Review <review@example.invalid> ·

unsigned

Browse filesCompare with HEAD

Changed files (2)

skills/quickshell/README.md

Added
new file mode 100644
1 +# quickshell
3 +Build desktop components (status bars, widgets, OSDs, lockscreens, greeters, app launchers) in QML/QtQuick with Quickshell on Wayland (Hyprland, Sway, i3, Niri).
5 +> **Status:** validated against Quickshell 0.3.0 on 2026-06-16. Examples parsed cleanly with the real `qs` binary; no QML errors at startup. The full runtime (windows actually mapping) wasn't tested in a Wayland session — see "Validation" below.
7 +## Layout
9 +```
10 +quickshell/
11 +├── SKILL.md # entry point — read first
12 +├── references/ # deep-dive tables, look up as needed
13 +│ ├── types.md # Quickshell type index (curated shortlist)
14 +│ ├── patterns.md # 16 reusable recipes
15 +│ ├── services.md # pipewire, mpris, notifications, …
16 +│ ├── windowing.md # PanelWindow / FloatingWindow / PopupWindow / WlSessionLock
17 +│ ├── resources.md # paths, icons, env, IPC, persistence
18 +│ └── getting-fresh-docs.md # how to look up current docs (don't memorize)
19 +├── examples/ # minimal, runnable prototypes
20 +│ ├── 01-hello-bar/ # smallest valid shell
21 +│ ├── 02-per-monitor-bar/ # Variants + Bar.qml split
22 +│ ├── 03-clock/ # FloatingWindow + WlrLayer.Overlay
23 +│ ├── 04-pipewire-volume/ # read+write default sink
24 +│ ├── 05-osd-volume/ # LazyLoader + Region + WlrLayer.Overlay (the OSD pattern)
25 +│ └── 06-ipc-control/ # IpcHandler for external control
26 +└── README.md # this file
27 +```
29 +## Quick start
31 +```sh
32 +# 1. Install quickshell
33 +sudo pacman -S quickshell # Arch (official)
34 +# or: see references/getting-fresh-docs.md for Nix/Debian/Fedora/Ubuntu/Gentoo
36 +# 2. Try a prototype
37 +qs -p examples/01-hello-bar/shell.qml
39 +# 3. Build your own config under ~/.config/quickshell/<name>/
40 +mkdir -p ~/.config/quickshell/mybar
41 +cp examples/02-per-monitor-bar/shell.qml ~/.config/quickshell/mybar/
42 +cp examples/02-per-monitor-bar/Bar.qml ~/.config/quickshell/mybar/
43 +touch ~/.config/quickshell/mybar/.qmlls.ini # enable LSP
45 +# 4. Run it
46 +qs -c mybar
47 +```
49 +## Validation
51 +What was actually tested, and what wasn't:
53 +| Check | Result | How |
54 +| ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------- |
55 +| All 6 examples parse | ✅ | `qs -p <shell.qml>` on each; event loop started; log shows no QML errors |
56 +| All 6 examples clean shutdown | ✅ | timeout-kill, no orphan processes |
57 +| No leftover runtime state | ✅ | `by-id/`, `by-shell/`, `by-path/` cleaned |
58 +| QML imports resolve | ✅ | (via the parse check above) |
59 +| Windows map to Wayland surface | ⚠️ not tested | The host's Hyprland session is live; creating test windows would litter the desktop. Run on your own session. |
60 +| Service APIs (pipewire, mpris) | ⚠️ not tested live | Code matches the official volume-osd example; pattern verified. |
62 +To extend validation on your own compositor:
64 +```sh
65 +# 1. Pick an example that doesn't conflict with your real bar
66 +qs -p examples/01-hello-bar/shell.qml
68 +# 2. Trigger the OSD (it should appear for 1s)
69 +qs -p examples/05-osd-volume/shell.qml &
70 +sleep 1
71 +wpctl set-volume @DEFAULT_AUDIO_SINK@ 0.5
73 +# 3. IPC test
74 +qs -p examples/06-ipc-control/shell.qml &
75 +sleep 1
76 +qs ipc call mybar show
77 +qs ipc call mybar setText "hello"
78 +```
80 +## When to update
82 +The skill encodes v0.3.0 patterns. Things to re-verify when bumping Quickshell:
84 +1. **`references/types.md`** — module names and type names shift between releases. Re-walk the v0.X.0 type index.
85 +2. **`SKILL.md` core patterns** — Window types, Variants, Connections, Process/StdioCollector are stable.
86 +3. **`examples/`** — refresh against the example repo (`quickshell-mirror/quickshell-examples`) when the version bumps.
87 +4. **`references/services.md`** — service APIs change most often.
89 +See `references/getting-fresh-docs.md` for the lookup procedure.
91 +## When not to use
93 +- You want a preconfigured desktop → use [Caelestia](https://github.com/caelestia-dots/shell) or [Illogical-Impulse](https://github.com/end-4/dots-hyprland).
94 +- You want a one-line status bar → use Waybar. Quickshell is programming.
95 +- You target Windows / macOS → Quickshell is Linux + BSD only.
96 +- You're on X11 with no wlroots compat → X11 is best-effort; prefer a wlroots-based WM.
98 +## Open questions for the user
100 +- **CLI helper.** A `qs-check <shell.qml>` wrapper (parse-only, fast) would speed up authoring. A `qs-new <name>` scaffolder would help. Both are ~30 lines of bash. Escalating per the original spec — happy to add if you want; otherwise this is a docs-only skill.

skills/quickshell/SKILL.md

Modified
6 6 # Quickshell
8 -Toolkit for building desktop components in QML (QtQuick). Not a WM, not a DE — runs alongside your compositor and owns a few Wayland surfaces (panels, popups, OSDs, lockscreens, etc.). Hot-reloads on save.
8 +Toolkit for building desktop components in QML (QtQuick). Not a WM, not a DE — runs alongside your compositor and owns a few Wayland surfaces (panels, popups, OSDs, lockscreens, greeters, polkit agent, system tray, etc.). Hot-reloads on save.
10 10 ## Mental model
18 18 └── Connections { target: SomeService; function onXxx() {...} }
21 -- A **shell** is a `shell.qml` file inside a named config dir.
22 -- The **root** is `ShellRoot` (passive container) or `Scope` (container with shared state + services).
23 -- **Windows** are children of the root. Three kinds: `PanelWindow` (anchored to screen edge/corner, reserves space), `FloatingWindow` (free desktop window), `PopupWindow` (auto-positioned over a parent).
24 -- **Variants** instantiates a component per item in a model — the canonical pattern for one-bar-per-monitor.
25 -- **Reactive bindings** do the work. You don't write update logic; you write expressions whose dependencies re-evaluate.
21 +- **Root:** `ShellRoot` (passive) or `Scope` (shared state + services).
22 +- **Windows:** `PanelWindow` (anchored, reserves space), `FloatingWindow` (free), `PopupWindow` (auto-positioned over a parent).
23 +- **`Variants`** instantiates a delegate per model item — the canonical pattern for one-bar-per-monitor.
24 +- **Reactive bindings** do the work. Write expressions; dependencies re-evaluate.
27 -## File layout (user config)
26 +## File layout
30 -$XDG_CONFIG_HOME/quickshell/<name>/ # usually ~/.config/quickshell/<name>/
31 -├── shell.qml # entry point; root must be ShellRoot or Scope
32 -├── .qmlls.ini # touch to enable LSP; managed by quickshell (gitignore)
33 -├── Bar.qml # implicitly importable from shell.qml (PascalCase)
34 -├── widgets/
35 -│ ├── Clock.qml # import via qs.widgets.Clock (qs.*, since v0.2.0)
36 -│ └── Volume.qml
37 -└── ...
29 +$XDG_CONFIG_HOME/quickshell/<name>/ # usually ~/.config/quickshell/<name>/
30 +├── shell.qml # entry; root must be ShellRoot or Scope
31 +├── .qmlls.ini # touch to enable LSP; gitignore
32 +├── Bar.qml # implicit import (PascalCase, same dir)
33 +└── widgets/Clock.qml # import via: import qs.widgets as W
40 -- Multiple named configs live side by side; pick with `qs -c <name>`.
41 -- `qs -p /path/to/shell.qml` runs an arbitrary file.
42 -- A `shell.qml` directly inside `~/.config/quickshell/` shadows all named configs.
36 +Named configs coexist; pick with `qs -c <name>`. Run arbitrary file: `qs -p /path/to/shell.qml`. A bare `~/.config/quickshell/shell.qml` shadows named configs.
44 -## Minimal bar (one focused monitor)
38 +## Hello bar
46 40 ```qml
47 -import QtQuick
48 -import Quickshell
41 +import QtQuick; import Quickshell
50 42 PanelWindow {
51 43 anchors { top: true; left: true; right: true }
52 44 implicitHeight: 30
57 -## Per-monitor bar (the canonical shape)
49 +## Per-monitor (canonical)
59 51 ```qml
60 -import QtQuick
61 -import Quickshell
52 +import QtQuick; import Quickshell
63 53 Variants {
64 54 model: Quickshell.screens
65 55 delegate: Component {
68 58 screen: modelData
69 59 anchors { top: true; left: true; right: true }
70 60 implicitHeight: 30
71 - Text { anchors.centerIn: parent; text: "bar" }
77 -`Quickshell.screens` is the monitor list; each element is a `ShellScreen` with `name`, `width`, `height`, `scale`.
79 -## Sizing (the rule that breaks everyone once)
66 +## Sizing (the rule that breaks everyone)
81 68 > **Implicit size flows child → parent. Actual size flows parent → child.**
83 -- Children set `implicitWidth`/`implicitHeight` (what they want).
84 -- Containers/`PanelWindow` set `width`/`height` (what they get).
85 -- `childrenRect` is the wrong tool for containers (creates binding loop). Use anchors or `MarginWrapperManager`/`WrapperItem`.
86 -- An `Item` with no implicit size is 0×0 — invisible. Quickshell warns about this on first show.
70 +`childrenRect` is wrong for containers (binding loop). Use anchors or `MarginWrapperManager`/`WrapperItem`. An `Item` with no implicit size is 0×0 — invisible.
88 -## Reactive bindings
72 +## Common patterns
90 -```qml
91 -Item {
92 - property int count: 0
93 - Timer { running: true; interval: 1000; repeat: true; onTriggered: count++ }
94 - width: 100 + count // re-evaluates every time count changes
96 -```
74 +| Need | Snippet |
75 +| --- | --- |
76 +| Run a command, capture stdout | `Process { command: ["..."]; running: true; stdout: StdioCollector { onStreamFinished: x.text = this.text } }` |
77 +| Stream line-by-line | `Process { ...; stdout: SplitParser { onRead: line => ... } }` |
78 +| Bind service state | `PwObjectTracker { objects: [ Pipewire.defaultAudioSink ] }` then read `?.audio.volume` |
79 +| React to signal | `Connections { target: X?.audio; function onVolumeChanged() {...} }` |
80 +| Conditional window (memory-aware) | `LazyLoader { active: show; PanelWindow {...} }` |
81 +| Click-through | `PanelWindow { color: "transparent"; mask: Region {} }` |
82 +| System icon | `IconImage { source: Quickshell.iconPath("audio-volume-high-symbolic") }` |
83 +| Path relative to this QML file | `Qt.resolvedUrl("foo.png")` |
84 +| Shell cache / data / state | `Quickshell.cachePath("x")` / `.dataPath("x")` / `.statePath("x")` |
85 +| Env var | `Quickshell.env("VAR")` |
86 +| External callable | `IpcHandler { target: "mybar"; function toggle(): void {...} }` → `qs ipc call mybar toggle` |
87 +| Version-gate | `Loader { active: Quickshell.hasVersion("0.3.0"); sourceComponent: ... }` |
98 -`property <type> <name>: <expr>` declares a reactive property. Any binding to it (including inside other components) re-runs when dependencies change.
100 -## Imports
102 -```qml
103 -import QtQuick // Rectangle, Text, Item, Timer, etc.
104 -import QtQuick.Layouts // RowLayout, ColumnLayout, GridLayout
105 -import QtQuick.Controls // Button, Slider, Label (Material/Universal styling)
106 -import Quickshell // PanelWindow, FloatingWindow, PopupWindow, Scope, ShellRoot, Quickshell.* helpers
107 -import Quickshell.Io // Process, StdioCollector, SplitParser, Socket, FileView, IpcHandler
108 -import Quickshell.Wayland // Toplevel, ToplevelManager, WlSessionLock, WlrLayershell
109 -import Quickshell.Services.Pipewire // Pipewire, PwObjectTracker, PwNode, PwNodeLinkTracker
110 -import Quickshell.Services.Mpris // Mpris (media player)
111 -import Quickshell.Services.Notifications
112 -import Quickshell.Services.SystemTray
113 -import Quickshell.Services.UPower // battery
114 -import Quickshell.Services.Bluetooth
115 -import Quickshell.Services.Polkit
116 -import Quickshell.Widgets // IconImage, WrapperRectangle, MarginWrapperManager, ClippingWrapperRectangle
117 -import qs.widgets as W // your own modules, v0.2.0+; LSP-friendly
118 -import qs // the shell root dir
119 -```
121 -Neighbor `.qml` files starting with **uppercase** are implicitly importable from `shell.qml`. Use `qs.*` for subfolders — much better LSP coverage than relative path imports.
123 -## Running things
125 -```qml
126 -// One-shot command, capture all stdout as a string
127 -Process {
128 - command: ["date"]
129 - running: true
130 - stdout: StdioCollector { onStreamFinished: someText.text = this.text }
133 -// Long-running stream, line by line
134 -Process {
135 - command: ["some-listener"]
136 - running: true
137 - stdout: SplitParser {
138 - onRead: line => console.log("got:", line)
139 - }
141 -```
143 -`StdioCollector` accumulates then fires `streamFinished`. `SplitParser` fires `onRead` per line. **One process, many widgets** — don't spawn one `Process` per widget (FAQ).
145 -## Binding to a service's state
147 -Most Quickshell services expose singletons with reactive state. To read a property, you must keep the service "looking" at the object or the binding dies:
149 -```qml
150 -import Quickshell.Services.Pipewire
152 -// Force Pipewire to keep tracking the default sink
153 -PwObjectTracker { objects: [ Pipewire.defaultAudioSink ] }
154 -Text { text: `vol: ${(Pipewire.defaultAudioSink?.audio.volume ?? 0) * 100 | 0}%` }
155 -```
157 -Same pattern for `Mpris.players`, `UPower.devices`, `Bluetooth.adapters`, etc. The tracker + `?.` optional chain is idiomatic.
159 -## Signals
161 -```qml
162 -// Property change handler (auto-generated signal)
163 -onVolumeChanged: console.log("vol =", volume)
165 -// Named signal
166 -signal clicked()
167 -onClicked: doThing()
169 -// Connections to a target's signals
170 -Connections {
171 - target: Pipewire.defaultAudioSink?.audio
172 - function onVolumeChanged() { ... }
175 -// One-shot at creation
176 -Component.onCompleted: console.log("ready")
177 -```
179 -## Conditional UI (memory-aware)
181 -```qml
182 -// Cheap, always in memory; just hides
183 -Item { visible: shouldShow; ... }
185 -// Frees memory when not active (rebuilds on toggle)
186 -LazyLoader { active: shouldShow; PanelWindow { ... } }
187 -```
189 -`LazyLoader` for non-Item roots (`PanelWindow` etc.); `Loader` for `Item`-derived trees. The `visible` toggle is fine for always-shown panels; `LazyLoader` is the answer for OSDs/drawers that appear and disappear.
191 -## Click-through
193 -```qml
194 -PanelWindow {
195 - color: "transparent"
196 - mask: Region {} // empty click region — clicks pass through
198 -```
200 -`Region` is the only correct way to make a window ignore input while still rendering. Use it for OSDs and decorative overlays.
202 -## Icons
204 -```qml
205 -import Quickshell.Widgets
206 -IconImage { source: Quickshell.iconPath("audio-volume-high-symbolic") }
207 -```
209 -`Quickshell.iconPath(name)` resolves a system icon theme name. Three overloads: missing icon → purple/black square, fallback, or empty string. Use the fallback/empty overload if the square bothers you.
211 -## Files / paths
213 -- `Qt.resolvedUrl("foo.png")` → path relative to the current QML file.
214 -- `Quickshell.cachePath("x")` / `.dataPath("x")` / `.statePath("x")` → XDG cache/data/state for this shell.
215 -- `Quickshell.env("VAR")` → env var lookup.
217 -## LSP
89 +## Editor / LSP
219 91 ```sh
220 92 touch ~/.config/quickshell/<name>/.qmlls.ini
223 -Quickshell will overwrite it with a managed config (gitignore it). qmlls gives completions for Quickshell types. **Without `.qmlls.ini`, all Quickshell symbols are unresolved in your editor.**
95 +Quickshell manages the file content; gitignore it. Without it, every Quickshell symbol is unresolved in your editor.
225 97 ## Versioning
227 -API breaks between minor versions. Use `Quickshell.hasVersion("0.3.0")` and the preprocessor (`pragma …`) to version-gate. Pin your distro's quickshell package; track master only if you want to live on the edge.
229 -## Cross-references
231 -- `references/types.md` — quick lookup table of every Quickshell type
232 -- `references/patterns.md` — reusable recipes (timers, process I/O, signals, monitor-per-instance, conditional load)
233 -- `references/services.md` — pipewire, mpris, notifications, system tray, upower, bluetooth, greetd, polkit
234 -- `references/windowing.md` — PanelWindow / FloatingWindow / PopupWindow / WlSessionLock
235 -- `references/resources.md` — icons, paths, env, system paths
236 -- `references/getting-fresh-docs.md` — how to read the current docs (don't memorize; look up)
237 -- `examples/` — minimal, runnable prototypes; copy/adapt
99 +API breaks happen between minor versions. Pin the distro package; track master only if you want the edge. Use `Quickshell.hasVersion()` + the preprocessor to version-gate.
239 101 ## When NOT to use
241 -- You want a preconfigured desktop → use [Caelestia](https://github.com/caelestia-dots/shell) or [Illogical-Impulse](https://github.com/end-4/dots-hyprland) instead.
242 -- You want a one-line status bar → use Waybar. Quickshell is programming, not config.
243 -- You target Windows/macOS → Quickshell is Linux/BSD only.
244 -- You're on X11 with no wlroots compat → Hyprland/Sway/i3/Niri are the supported targets; X11 is best-effort.
103 +- Preconfigured desktop → Caelestia / Illogical-Impulse.
104 +- One-line status bar → Waybar. Quickshell is programming.
105 +- Windows / macOS → Linux + BSD only.
106 +- X11 with no wlroots compat → prefer Hyprland/Sway/i3/Niri.
108 +## Cross-references
110 +- `references/types.md` — curated type index
111 +- `references/patterns.md` — 16 reusable recipes (P1–P16)
112 +- `references/services.md` — pipewire, mpris, notifications, tray, upower, bluetooth, greetd, polkit
113 +- `references/windowing.md` — PanelWindow / FloatingWindow / PopupWindow / WlSessionLock / WlrLayershell
114 +- `references/resources.md` — paths, icons, env, IPC, persistence
115 +- `references/getting-fresh-docs.md` — how to read current docs
116 +- `examples/` — 6 minimal, runnable prototypes