repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

wiki: register advanced.html + coverage note for examples repo

a10307af73b6b350ac8262b7aa7b1e3a6a38727a

Review <review@example.invalid> ·

unsigned

Browse filesCompare with HEAD

Changed files (20)

skills/qml/examples/01-hello/README.md

Modified
5 5 **Run:** `qml6 hello.qml`
7 7 **What it teaches:**
8 9 - `Window` is the top-level (use `ApplicationWindow` from `QtQuick.Controls` for menus/toolbars).
9 10 - `import` statements at the top.
10 11 - `Rectangle` is a visible `Item` with a `color` (background) and `radius` (rounded corners).
14 15 - `anchors.margins: 20` adds 20px padding on all sides.
16 17 **What to break and learn from:**
17 19 - Remove `property int count: 0` → `box.count++` fails (no such property).
18 20 - Change `color: ...` to `color: "red"` (no binding) → the rectangle no longer updates on click.
19 21 - Add `width: 100; height: 50` to the Rectangle — its `anchors.fill` will override these. Pick one.

skills/qml/examples/02-repeater/README.md

Modified
5 5 **Run:** `qml6 repeater.qml`
7 7 **What it teaches:**
8 9 - `Repeater` parent: any `Item` (here, a `ColumnLayout`).
9 10 - Model: a JS array of objects. Each element is `modelData` in the delegate.
10 11 - `delegate: Item { ... }` — the per-row template. Each instance gets its own scope.
14 15 - `Layout.preferredWidth: 100` sets the width before stretching (in this case, for the first column).
16 17 **What to break and learn from:**
17 19 - Change `model: [...]` to a number: `model: 5` — the delegate is instantiated 5 times with `index` = 0..4, but `modelData` is the same number each time.
18 20 - Add `model.append({ name: "Eve", role: "New" })` to a button's `onClicked` — but **this is a JS array, not a ListModel**, so the Repeater won't update. Use `ListModel` for observable lists.
19 21 - Remove `Layout.fillWidth: true` — the rows are only as wide as their content, leaving empty space on the right.

skills/qml/examples/03-anchors/README.md

Modified
5 5 **Run:** `qml6 anchors.qml`
7 7 **What it teaches:**
8 9 - `anchors.top: parent.top` — pin the top edge to the parent's top edge.
9 10 - `anchors.left` / `anchors.right` / `anchors.bottom` — same for the other three.
10 11 - `anchors.margins: 16` — uniform margin on all four sides.
14 15 - `anchors.fill: parent` — shorthand for all four edges (left/right/top/bottom all true).
16 17 **What to break and learn from:**
17 19 - Set `width: 200` on the center box while it has `anchors.centerIn: parent` — `width: 200` is the size; `anchors.centerIn` is the position. Both work; the box is 200×100 centered.
18 20 - Try to mix `anchors.fill: parent` with `width: 100` — `anchors.fill` wins; the width is ignored. Pick one.
19 21 - Set `anchors.left: parent.left` and `anchors.right: parent.right` (but not top/bottom) on the bottom-stretch box — it now stretches horizontally only, height stays at 60. Try this; it's the canonical "side panel" pattern.

skills/qml/examples/04-listview/README.md

Modified
5 5 **Run:** `qml6 listview.qml`
7 7 **What it teaches:**
8 9 - `ListModel` is a JS-manipulable list of rows. `append({...})`, `remove(i)`, `setProperty(i, "name", val)`, `count`.
9 10 - `ListElement` is a literal row. Property names become model roles (here, `title` and `done`).
10 11 - `ListView` recycles delegates — only the visible rows are kept in memory. Fine for 10 or 10,000 items.
14 15 - `tasks.count === 0` for an empty-state placeholder.
16 17 **What to break and learn from:**
17 19 - Add 100 items (`for (let i = 0; i < 100; i++) tasks.append(...)`) — `ListView` recycles; no slowdown.
18 20 - Try to bind `width: parent.width` instead of `width: ListView.view.width` — `parent` here is the ListView's contentItem, which may not have the right size. Use `ListView.view.width` for the ListView itself.
19 21 - Set `delegate.height: 200` — delegates are fixed height; spacing is independent. Compare with `implicitHeight: 200` (the desired size before stretching).

skills/qml/examples/05-form/README.md

Modified
5 5 **Run:** `qml6 form.qml`
7 7 **What it teaches:**
8 9 - `ApplicationWindow` is `Window` with a header/footer/menu — a more capable top-level for app-like UIs.
9 10 - `GridLayout { columns: 2 }` for label-input pairs. `Layout.columnSpan: 2` for a full-width row.
10 11 - `readonly property bool isValid: ...` — a derived property that updates whenever its dependencies change.
14 15 - `Qt.callLater(fn)` — defer the work so the UI updates first.
16 17 **What to break and learn from:**
17 19 - Remove `readonly` from `isValid` — without `readonly`, you can assign to it; bindings can break.
18 20 - Add `Layout.alignment: Qt.AlignRight` to all the `Label`s — they're right-aligned in the cell.
19 21 - Set `Layout.columnSpan: 2` on the password row — the field stretches across both columns.

skills/qml/examples/06-animation/README.md

Modified
5 5 **Run:** `qml6 animation.qml`
7 7 **What it teaches:**
8 9 - `Behavior on <property> { ... }` — any change to that property triggers the animation.
9 10 - `NumberAnimation` for `int`/`real` values. `duration: ms`. `easing.type: Easing.InOutQuad`.
10 11 - `ColorAnimation` for `color` properties.
15 16 - `NumberAnimation { target: otherItem; property: "x"; to: ... }` — animate a different item.
17 18 **What to break and learn from:**
18 20 - Remove the `Behavior on x` block on `implicitBox` — the box snaps to the new position; no smooth motion.
19 21 - Set `running: false` on the `SequentialAnimation on y` — the bouncing ball stops.
20 22 - Add `onRunningChanged: console.log("running:", running)` to the pulse — see when the animation starts/stops.

skills/qml/examples/07-tabs/README.md

Modified
5 5 **Run:** `qml6 tabs.qml`
7 7 **What it teaches:**
8 9 - `TabBar { TabButton { text: "..." } }` — one tab per `TabButton`. `currentIndex` is auto-managed.
9 10 - `StackLayout { currentIndex: bar.currentIndex }` — show one child at a time, indexed by the tab bar.
10 11 - `Layout.fillWidth: true` and `Layout.fillHeight: true` on the StackLayout makes it fill the column.
11 12 - Each child of the StackLayout is a full "page" of the app.
13 14 **What to break and learn from:**
14 16 - Add a 4th tab and page — `TabButton { text: "..." }` and a child of the StackLayout.
15 17 - Add icons: `TabButton { icon.name: "go-home" }` — uses the system icon theme.
16 18 - Set `currentIndex: 1` on the StackLayout — opens to the Settings tab.

skills/qml/references/common-pitfalls.md

Modified
58 -This *looks* like a loop but isn't. The `onValueChanged` handler fires when the user moves the slider; the assignment to `model.volume` breaks the binding to it. The next read of `model.volume` re-evaluates the `value:` binding. Standard QML behavior.
58 +This _looks_ like a loop but isn't. The `onValueChanged` handler fires when the user moves the slider; the assignment to `model.volume` breaks the binding to it. The next read of `model.volume` re-evaluates the `value:` binding. Standard QML behavior.
60 60 The **real** binding fight is when an external system writes back to a bound property, causing infinite re-evaluation. The fix is to set one side explicitly (`value: ...; onMoved: ... = value` — `onMoved` fires only for user gestures, not programmatic changes).

skills/qml/references/components.md

Modified
145 145 ## File organization
147 -| Pattern | When |
148 -| --- | --- |
149 -| Inline component (`component X: Item { ... }`) | Type is local to one file. |
150 -| `X.qml` neighbor | Type is small and used in this directory. |
151 -| `widgets/X.qml` + `import "widgets" as W` | Larger project, multiple subdirs. |
152 -| `qmldir` for the directory | Best LSP support for `widgets/`. |
153 -| C++ `Q_OBJECT` registered with `QML_ELEMENT` | High-performance or library types. |
147 +| Pattern | When |
148 +| ---------------------------------------------- | ----------------------------------------- |
149 +| Inline component (`component X: Item { ... }`) | Type is local to one file. |
150 +| `X.qml` neighbor | Type is small and used in this directory. |
151 +| `widgets/X.qml` + `import "widgets" as W` | Larger project, multiple subdirs. |
152 +| `qmldir` for the directory | Best LSP support for `widgets/`. |
153 +| C++ `Q_OBJECT` registered with `QML_ELEMENT` | High-performance or library types. |
155 155 ## The "must start with uppercase" rule

skills/qml/references/javascript.md

Modified
211 211 ## When to use JS vs C++
213 -| Use JS for | Use C++ for |
214 -| --- | --- |
215 -| Property expressions | High-performance loops over millions of items |
216 -| Small algorithms (sort, filter) | Database access |
217 -| UI glue (toggle, format) | Image processing |
218 -| One-time setup | Heavy data models |
219 -| Validation | Network I/O |
213 +| Use JS for | Use C++ for |
214 +| ------------------------------- | --------------------------------------------- |
215 +| Property expressions | High-performance loops over millions of items |
216 +| Small algorithms (sort, filter) | Database access |
217 +| UI glue (toggle, format) | Image processing |
218 +| One-time setup | Heavy data models |
219 +| Validation | Network I/O |
221 221 For anything CPU-bound or data-heavy, push it to C++ via `Q_INVOKABLE` and `Q_PROPERTY` and bind to the result.

skills/qml/references/layouts.md

Modified
7 7 > **Implicit size flows child → parent. Actual size flows parent → child.**
9 -| Direction | Property | Use |
10 -| --- | --- | --- |
9 +| Direction | Property | Use |
10 +| -------------- | --------------------------------- | ------------------------ |
11 11 | Child → parent | `implicitWidth`, `implicitHeight` | "I want to be this big." |
12 -| Parent → child | `width`, `height` | "You are this big." |
12 +| Parent → child | `width`, `height` | "You are this big." |
14 14 Containers (`RowLayout`, `GridLayout`, `Item`-based) read children's `implicitWidth`/`implicitHeight` to determine their own size, then assign `width`/`height` to children. A child that sets both will be overwritten by the container.
68 68 `Layout.*` attached properties:
70 -| Property | Effect |
71 -| --- | --- |
72 -| `Layout.fillWidth: true` | Stretch to fill the row width. |
73 -| `Layout.fillHeight: true` | Stretch to fill the column height. |
74 -| `Layout.preferredWidth: 100` | The size before stretching. |
75 -| `Layout.minimumWidth: 50` | Won't go below this. |
76 -| `Layout.maximumWidth: 200` | Won't go above this. |
77 -| `Layout.alignment: Qt.AlignCenter` | Position within the cell. |
78 -| `Layout.leftMargin: 8` | Per-side margin override. |
79 -| `Layout.row: 0` / `Layout.column: 1` | For `GridLayout` — explicit cell. |
80 -| `Layout.rowSpan: 2` / `Layout.columnSpan: 2` | For `GridLayout` — span cells. |
70 +| Property | Effect |
71 +| -------------------------------------------- | ---------------------------------- |
72 +| `Layout.fillWidth: true` | Stretch to fill the row width. |
73 +| `Layout.fillHeight: true` | Stretch to fill the column height. |
74 +| `Layout.preferredWidth: 100` | The size before stretching. |
75 +| `Layout.minimumWidth: 50` | Won't go below this. |
76 +| `Layout.maximumWidth: 200` | Won't go above this. |
77 +| `Layout.alignment: Qt.AlignCenter` | Position within the cell. |
78 +| `Layout.leftMargin: 8` | Per-side margin override. |
79 +| `Layout.row: 0` / `Layout.column: 1` | For `GridLayout` — explicit cell. |
80 +| `Layout.rowSpan: 2` / `Layout.columnSpan: 2` | For `GridLayout` — span cells. |
82 82 `Layout.fillWidth: true` + `Layout.fillHeight: true` is the "make me stretch in both directions" combo.
170 170 ## What to choose
172 -| Use case | Pick |
173 -| --- | --- |
174 -| Single rectangle pinned to a corner | `anchors` |
175 -| 3 buttons in a row | `RowLayout` |
176 -| Form with labels + fields | `GridLayout { columns: 2 }` |
177 -| Tabbed views | `StackLayout` + `TabBar` |
178 -| Scrollable list | `ListView` (not a Layout) |
179 -| Auto-margin (no binding loops) | `MarginWrapperManager` (Quickshell extension, see `quickshell` skill) |
172 +| Use case | Pick |
173 +| ----------------------------------- | --------------------------------------------------------------------- |
174 +| Single rectangle pinned to a corner | `anchors` |
175 +| 3 buttons in a row | `RowLayout` |
176 +| Form with labels + fields | `GridLayout { columns: 2 }` |
177 +| Tabbed views | `StackLayout` + `TabBar` |
178 +| Scrollable list | `ListView` (not a Layout) |
179 +| Auto-margin (no binding loops) | `MarginWrapperManager` (Quickshell extension, see `quickshell` skill) |

skills/qml/references/models.md

Modified
37 37 ## Built-in model types
39 -| Type | Source |
40 -| --- | --- |
41 -| `ListModel` | JS appendable list of `ListElement`. |
42 -| `ObjectModel` | List of arbitrary QML objects; delegates are the actual instances. |
43 -| `XmlListModel` | Parses XML. |
44 -| `QAbstractListModel` (C++) | The Qt-standard way to expose data to QML. |
45 -| Any `QAbstractItemModel` | Tree/table models. |
46 -| A JS array | Static list. |
47 -| A number (`model: 10`) | Repeats the delegate N times, `index` is 0..N-1. |
39 +| Type | Source |
40 +| -------------------------- | ------------------------------------------------------------------ |
41 +| `ListModel` | JS appendable list of `ListElement`. |
42 +| `ObjectModel` | List of arbitrary QML objects; delegates are the actual instances. |
43 +| `XmlListModel` | Parses XML. |
44 +| `QAbstractListModel` (C++) | The Qt-standard way to expose data to QML. |
45 +| Any `QAbstractItemModel` | Tree/table models. |
46 +| A JS array | Static list. |
47 +| A number (`model: 10`) | Repeats the delegate N times, `index` is 0..N-1. |
49 49 ## Built-in views
51 -| View | Use |
52 -| --- | --- |
53 -| `Repeater` | Inline; instantiates one delegate per model row, no scrolling. |
54 -| `ListView` | Scrollable vertical list; recycles delegates. |
55 -| `GridView` | Scrollable grid. |
56 -| `PathView` | Along a `Path`. |
57 -| `TableView` | Tabular (rows × columns). |
51 +| View | Use |
52 +| ----------- | -------------------------------------------------------------- |
53 +| `Repeater` | Inline; instantiates one delegate per model row, no scrolling. |
54 +| `ListView` | Scrollable vertical list; recycles delegates. |
55 +| `GridView` | Scrollable grid. |
56 +| `PathView` | Along a `Path`. |
57 +| `TableView` | Tabular (rows × columns). |
59 59 `Repeater` is the simplest. `ListView` recycles (only visible rows are kept in memory) — important for long lists.
97 97 Key things:
98 99 - `ListView.view.width` references the enclosing ListView's width — use this in delegates for full-width rows.
99 100 - `clip: true` prevents drawing outside the view's bounds.
100 101 - Add a `ScrollBar.vertical` (from `QtQuick.Controls`) for usability.

skills/qml/references/syntax.md

Modified
21 21 ## Imports
23 -| Form | Use |
24 -| --- | --- |
25 -| `import QtQuick` | A Qt module. Optional major.minor version. |
26 -| `import QtQuick 6.5` | Pin a version for stability. |
27 -| `import QtQuick as Q` | Namespace prefix. Use `Q.Item`. |
28 -| `import "my.js" as MyJs` | JavaScript file as namespace. |
29 -| `import "subfolder"` | Relative-path folder import. |
30 -| `import "subfolder" as Sub` | Same, namespaced. |
23 +| Form | Use |
24 +| --------------------------- | ------------------------------------------ |
25 +| `import QtQuick` | A Qt module. Optional major.minor version. |
26 +| `import QtQuick 6.5` | Pin a version for stability. |
27 +| `import QtQuick as Q` | Namespace prefix. Use `Q.Item`. |
28 +| `import "my.js" as MyJs` | JavaScript file as namespace. |
29 +| `import "subfolder"` | Relative-path folder import. |
30 +| `import "subfolder" as Sub` | Same, namespaced. |
32 32 **Module and namespace names** must start with an uppercase letter. `import qtquick` is an error.
56 56 The QML value types, with QML-side aliases:
58 -| Type | Example | Notes |
59 -| --- | --- | --- |
60 -| `int` | `0`, `-1` | |
61 -| `real` | `0.5`, `1e-3` | QML's float = double. |
62 -| `double` | (rare) | |
63 -| `string` | `"hello"` | |
64 -| `bool` | `true` | |
65 -| `color` | `"red"`, `"#ff0000"`, `Qt.rgba(1, 0, 0, 1)` | |
66 -| `url` | `"https://..."` | Resolved against the QML file's URL. |
67 -| `var` | `[1, "x"]`, `{a: 1}` | Untyped. Use sparingly. |
68 -| `date` | `new Date()` | JS Date. |
69 -| `point` | `Qt.point(0, 0)` | `{x, y}`. |
70 -| `size` | `Qt.size(100, 50)` | `{width, height}`. |
71 -| `rect` | `Qt.rect(0, 0, 100, 50)` | `{x, y, width, height}`. |
72 -| `vector2d`, `vector3d`, `vector4d` | `Qt.vector2d(0, 0)` | |
73 -| `quaternion` | `Qt.quaternion(0, 0, 0, 1)` | |
74 -| `matrix4x4` | `Qt.matrix4x4(...)` | |
75 -| `font` | `font.family: "Inter"` | Structured type. |
76 -| `enumeration` | `Text.AlignLeft` | Object's enums. |
58 +| Type | Example | Notes |
59 +| ---------------------------------- | ------------------------------------------- | ------------------------------------ |
60 +| `int` | `0`, `-1` | |
61 +| `real` | `0.5`, `1e-3` | QML's float = double. |
62 +| `double` | (rare) | |
63 +| `string` | `"hello"` | |
64 +| `bool` | `true` | |
65 +| `color` | `"red"`, `"#ff0000"`, `Qt.rgba(1, 0, 0, 1)` | |
66 +| `url` | `"https://..."` | Resolved against the QML file's URL. |
67 +| `var` | `[1, "x"]`, `{a: 1}` | Untyped. Use sparingly. |
68 +| `date` | `new Date()` | JS Date. |
69 +| `point` | `Qt.point(0, 0)` | `{x, y}`. |
70 +| `size` | `Qt.size(100, 50)` | `{width, height}`. |
71 +| `rect` | `Qt.rect(0, 0, 100, 50)` | `{x, y, width, height}`. |
72 +| `vector2d`, `vector3d`, `vector4d` | `Qt.vector2d(0, 0)` | |
73 +| `quaternion` | `Qt.quaternion(0, 0, 0, 1)` | |
74 +| `matrix4x4` | `Qt.matrix4x4(...)` | |
75 +| `font` | `font.family: "Inter"` | Structured type. |
76 +| `enumeration` | `Text.AlignLeft` | Object's enums. |
78 78 ## Property modifiers
80 -| Modifier | Effect |
81 -| --- | --- |
82 -| `readonly` | Can be assigned in the initial binding only. |
83 -| `default` | This is the default property — child objects go into it. |
84 -| `required` | The user must set this property. `qmllint` enforces. |
85 -| `property` (alone) | The default — a normal reactive property. |
80 +| Modifier | Effect |
81 +| ------------------ | -------------------------------------------------------- |
82 +| `readonly` | Can be assigned in the initial binding only. |
83 +| `default` | This is the default property — child objects go into it. |
84 +| `required` | The user must set this property. `qmllint` enforces. |
85 +| `property` (alone) | The default — a normal reactive property. |
87 87 ```qml
88 88 Item {
112 112 onClicked: count = count + 1
115 -**Important:** assigning to a property *breaks* any active binding. After `height = 200`, the `height: parent.width / 2` binding is gone forever.
115 +**Important:** assigning to a property _breaks_ any active binding. After `height = 200`, the `height: parent.width / 2` binding is gone forever.
117 117 ## Common patterns
178 178 ## Useful singletons
180 -| Singleton | What |
181 -| --- | --- |
182 -| `Qt` | Format functions, point/size/rect, `Qt.callLater(fn)`, `Qt.platform`, `Qt.application`. |
183 -| `Application` | `Application.name`, `Application.version`, `Application.organization`. |
184 -| `Settings` (from `Qt.labs.settings`) | Persist properties to QSettings. |
185 -| `Workspace` (in Qt 6) | Mutex for app-wide locks. |
180 +| Singleton | What |
181 +| ------------------------------------ | --------------------------------------------------------------------------------------- |
182 +| `Qt` | Format functions, point/size/rect, `Qt.callLater(fn)`, `Qt.platform`, `Qt.application`. |
183 +| `Application` | `Application.name`, `Application.version`, `Application.organization`. |
184 +| `Settings` (from `Qt.labs.settings`) | Persist properties to QSettings. |
185 +| `Workspace` (in Qt 6) | Mutex for app-wide locks. |
187 187 For more, see the Qt documentation linked in `SKILL.md`.

skills/quickshell/SKILL.md

Modified
112 112 - `references/services.md` — pipewire, mpris, notifications, tray, upower, bluetooth, greetd, polkit
113 113 - `references/windowing.md` — PanelWindow / FloatingWindow / PopupWindow / WlSessionLock / WlrLayershell
114 114 - `references/resources.md` — paths, icons, env, IPC, persistence
115 +- `references/packaging.md` — distro packages, source build, troubleshooting
116 +- `references/advanced.md` — pragmas, preprocessor, env vars
117 +- `references/tdd-scenarios.md` — how the skill was developed (RED-GREEN-REFACTOR)
118 +- `references/official-examples-coverage.md` — which patterns from each official example are covered
115 119 - `references/getting-fresh-docs.md` — how to read current docs
116 -- `examples/` — 6 minimal, runnable prototypes
120 +- `examples/` — 8 minimal, runnable prototypes
121 +- **`qml` skill** — pure QML/QtQuick (property bindings, components, layouts, signals, JS, models, common pitfalls). This skill assumes you already know QML; refer to `qml` for the language itself.

skills/quickshell/examples/07-composite-bar/README.md

Modified
5 5 **Run:** `qs -p examples/07-composite-bar/shell.qml`
7 7 **What it teaches:**
8 9 - Multiple services compose in a single `PanelWindow`.
9 10 - `RowLayout` for horizontal distribution with `Layout.fillWidth: true` spacers to push left/right clusters apart.
10 11 - `Hyprland.focusedWorkspace` for live workspace indicator (Hyprland-specific).
12 13 - All five services can read state in the same `Text` bindings without conflict.
14 15 **What to break and learn from:**
15 17 - Remove `PwObjectTracker` — the volume `Text` will read `undefined` once the default sink's object drops out of pipewire's tracking.
16 18 - Run on a non-Hyprland WM — `Hyprland.focusedWorkspace` returns `null`; the `Text` shows `?`. The bar still works.
17 19 - Add a `WindowManager` (generic) workspace indicator as a fallback when Hyprland is unavailable — the generic interface covers Niri/Sway, the specific module adds data.
18 20 - Add a `Mpris` repeater for media playback between the clock and the right cluster.
20 22 **Pattern:**
21 24 - One `PwObjectTracker` per service whose state you want to keep alive.
22 25 - One `SystemClock` per "ticking" UI.
23 26 - `RowLayout` + spacers for the bar layout — much cleaner than manual `x`/`width` calculations.
25 -**Validated:** `INFO: Configuration Loaded` with no QML errors against `qs 0.3.0`.
28 +**Validated:** `INFO: Configuration Loaded` with no QML errors against `qs 0.3.0`. Tested both `qs -p examples/07-composite-bar/shell.qml` and the install workflow (`cp -r examples/07-composite-bar ~/.config/quickshell/compositebar/ && qs -c compositebar`). Both pass.
30 +**One real warning you'll see in the log:** `WARN: Could not load icon "audio-volume-high-symbolic"` if your icon theme doesn't ship that name. Either install a theme that has it, or use the `Quickshell.iconPath(name, fallback)` overload — see `references/resources.md`.

skills/quickshell/examples/08-notification-daemon/README.md

Added
new file mode 100644
1 +# 08 — notification daemon
3 +A minimal notification daemon. Replaces mako/dunst/swaync with a Quickshell-based implementation.
5 +**Run:** `qs -p examples/08-notification-daemon/shell.qml`
7 +**Test it:** in another terminal, run:
9 +```sh
10 +notify-send "Hello" "This is a test"
11 +```
13 +A popup should appear at the bottom-right of the focused monitor for 5 seconds.
15 +**To replace your real notification daemon:**
17 +1. Stop mako/dunst/swaync.
18 +2. Run this shell in the background (e.g. as a systemd user service).
20 +**What it teaches:**
22 +- `NotificationServer` registers itself on the DBus session bus as the notification daemon — no separate registration needed.
23 +- `onNotification: (notification) => { notification.tracked = true }` keeps the notification from being auto-dismissed.
24 +- `server.trackedNotifications` is an `ObjectModel<Notification>` — bind a `Repeater` to it to render each one.
25 +- A `Timer` can auto-dismiss a notification by setting `tracked = false` after `expireTimeout` ms.
26 +- Each `PanelWindow` in a `Repeater` gets its own `modelData` (the `Notification` instance).
27 +- Click-through via `mask: Region {}` lets the user interact with the desktop behind the popup.
29 +**What to break and learn from:**
31 +- Forgot `notification.tracked = true` in the signal handler — the notification appears for a flash then disappears (auto-dismissed by the server).
32 +- Multiple notifications with `margins.bottom: 30 + (index * 80)` — change the multiplier to 100 for more spacing; or use a `Column` to stack them automatically.
33 +- Add `MouseArea` with `onClicked: notification.dismiss()` to make popups click-to-close.
34 +- Set `keepOnReload: false` to clear all popups on config reload.
36 +**Limitations of this example:**
38 +- No actions (reply, accept, decline) — the `actions` property is read but not rendered. See `QsMenuOpener` for that.
39 +- No history (closed popups are gone forever). Persist with `persistenceSupported: true` + a `FileView` for storage.
40 +- No grouping per app.
41 +- The `Repeater` approach re-creates `PanelWindow` for every change in `trackedNotifications`, which causes flicker. For production, use a `Loader` per slot or pre-allocate N windows.
43 +**Validated:** `INFO: Configuration Loaded` with no QML errors against `qs 0.3.0`. Tested under `qs -p` and the install workflow `qs -c <name>`.

skills/quickshell/references/advanced.md

Added
new file mode 100644
1 +# Advanced Options
3 +Quickshell-specific pragmas, the preprocessor, and environment variables. The complete reference is at `https://quickshell.org/docs/v0.3.0/guide/advanced/`. This file is a curated shortlist.
5 +## Pragmas
7 +Pragmas are special comments that influence execution. They look like `//@ pragma <name> <args>`.
9 +### Per-file pragmas
11 +| Pragma | Effect |
12 +| --------------------- | ----------------------------------------------------------------------------- |
13 +| `//@ pragma Internal` | Marks a QML file as internal to a module. The file is not exposed for import. |
15 +### Instance pragmas (only at the top of root `shell.qml`)
17 +| Pragma | Effect |
18 +| --------------------------------- | --------------------------------------------------------------------------------------------------------- |
19 +| `//@ pragma Env VAR = VAL` | Set env var for Quickshell's own process. |
20 +| `//@ pragma DefaultEnv VAR = VAL` | Set env var only if not already set. |
21 +| `//@ pragma UseQApplication` | Use `QApplication` instead of `QGuiApplication`. Needed for `qqc2-desktop-style` (KDE). |
22 +| `//@ pragma NativeTextRendering` | Use the system text rendering backend (equivalent to `Text.renderType: Text.NativeRendering` everywhere). |
23 +| `//@ pragma IgnoreSystemSettings` | Ignore system app-style settings entirely. Rarely useful. |
24 +| `//@ pragma RespectSystemStyle` | Don't override the QtQuick Controls style to Fusion (Quickshell does this by default). |
25 +| `//@ pragma DropExpensiveFonts` | Skip `woff`/`woff2` font loading to save memory. |
26 +| `//@ pragma IconTheme <name>` | Set the Qt icon theme. Equivalent to `QS_ICON_THEME`. |
27 +| `//@ pragma AppId <id>` | Override the desktop application ID. |
28 +| `//@ pragma ShellId <id>` | Override the path-derived shell ID. |
29 +| `//@ pragma DataDir <dir>` | Override the XDG data dir (`$BASE/` expands to the base dir). |
30 +| `//@ pragma StateDir <dir>` | Override the XDG state dir. |
31 +| `//@ pragma CacheDir <dir>` | Override the XDG cache dir. |
33 +The dir pragmas use `$BASE/` to mean "use the XDG base dir (data, state, or cache)". For example: `//@ pragma CacheDir $BASE/qml-cache` becomes `$XDG_CACHE_HOME/qml-cache` resolved against the Quickshell shell ID.
35 +## Preprocessor
37 +```qml
38 +//@ if <condition>
39 +//@ <qml content>
40 +//@ endif
41 +```
43 +The content disappears at parse time if `<condition>` is false. Conditions are JavaScript expressions.
45 +### Available preprocessor functions
47 +| Function | Returns |
48 +| ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
49 +| `hasVersion(major, minor, features): bool` | True if the running Quickshell matches the version (and features). Same as `Quickshell.hasVersion()`. |
50 +| `hasQtVersion(major, minor): bool` | True if the bundled Qt matches. |
51 +| `env(name): string` | Env var value. Empty string if unset. |
52 +| `isEnvSet(name): bool` | True if env var is set (even to empty). |
54 +Example:
56 +```qml
57 +//@ if hasVersion("0.3.0")
58 +import Quickshell.Networking // only available in 0.3.0+
59 +//@ endif
60 +```
62 +This is the safe way to use version-gated features in a config that might be loaded by older Quickshell versions.
64 +## Environment variables
66 +| Var | Purpose |
67 +| --------------------------- | ---------------------------------------------------------------- |
68 +| `QS_CONFIG_PATH` | Equivalent to `--path`. |
69 +| `QS_APP_ID` | Override the desktop app ID. |
70 +| `QS_ICON_THEME` | Override the icon theme. |
71 +| `QS_DROP_EXPENSIVE_FONTS=1` | Skip `woff`/`woff2` loading. |
72 +| `QS_DISABLE_FILE_WATCHER` | Disable hot-reload watching. |
73 +| `QS_NO_RELOAD_POPUP` | Disable the built-in reload popup. |
74 +| `QS_DISABLE_CRASH_HANDLER` | Disable the crash handler. |
75 +| `QS_CRASHREPORT_URL` | Override the crash report URL. |
76 +| `QS_NO_XINERAMA_STRUTS` | X11 bar-positioning hack. May help or hurt depending on WM bugs. |
78 +## When to use
80 +- **`hasVersion` in preprocessor:** when the same `shell.qml` needs to work across Quickshell versions (rare, but useful for community configs).
81 +- **`pragma Env`:** when you need to set a Qt env var (like `QT_QUICK_CONTROLS_STYLE`) declaratively, not via shell export.
82 +- **`pragma DropExpensiveFonts`:** on memory-constrained systems or when many font variants are loaded.
83 +- **`pragma ShellId`:** when the same config appears at multiple paths (e.g. symlinked from different locations) and you want the runtime state dirs to be the same.
84 +- **`QS_NO_RELOAD_POPUP`:** for the hot-reload cycle to be silent (no popup when you save). Or replace the popup with a custom one — see `references/official-examples-coverage.md`.
86 +## When NOT to use
88 +- **`pragma UseQApplication`:** only if you need `qqc2-desktop-style` (KDE style). Most configs don't.
89 +- **`pragma IgnoreSystemSettings`:** almost never. Set explicit values instead.
90 +- **Preprocessor `#if` for code style:** use QML's reactive bindings, not C-preprocessor patterns.

skills/quickshell/references/official-examples-coverage.md

Added
new file mode 100644
1 +# Official Examples — Coverage Analysis
3 +The official Quickshell examples live at `https://git.outfoxxed.me/quickshell/quickshell-examples` (mirror: `github.com/quickshell-mirror/quickshell-examples`). The skill was built against these — this file maps each official example to the skill section that covers it.
5 +| Official example | What it shows | Skill coverage |
6 +| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
7 +| [activate_linux](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/activate_linux) | PanelWindow + Variants + WlrLayershell.Overlay + click-through + `WlrLayershell.namespace` | `SKILL.md` per-monitor pattern; `references/windowing.md` WlrLayershell section |
8 +| [focus_following_panel](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/focus_following_panel) | Hyprland `Socket` connection + `SplitParser` regex + `Quickshell.env("HYPRLAND_INSTANCE_SIGNATURE")` | `references/patterns.md` Process / SplitParser; Socket pattern (added below); env-var note (added below) |
9 +| [lockscreen](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/lockscreen) | WlSessionLock + WlSessionLockSurface + PamContext + multi-file shell | `references/windowing.md` WlSessionLock section; `references/services.md` Pam section |
10 +| [mixer](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/mixer) | FloatingWindow + ScrollView + PwNodeLinkTracker + Repeater + custom MixerEntry component | `references/services.md` Pipewire section; `references/patterns.md` P14 (custom component) |
11 +| [reload-popup](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/reload-popup) | Replacing the built-in reload popup with a custom one | `references/patterns.md` P15 (custom reload popup) |
12 +| [volume-osd](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/volume-osd) | Scope + LazyLoader + PanelWindow + PwObjectTracker + Connections + Timer + Region | `SKILL.md` patterns table; `examples/05-osd-volume/` mirrors this example |
13 +| [wlogout](https://git.outfoxxed.me/quickshell/quickshell-examples/src/branch/master/wlogout) | Custom logout menu with QML keybinds (`Qt.Key_K`) + WlrKeyboardFocus.Exclusive + WlrLayershell.namespace | `references/windowing.md`; `references/patterns.md` P9 + new keybind section below |
15 +## Patterns unique to official examples (and added to the skill in this pass)
17 +### Socket connection to a Unix socket (focus_following_panel)
19 +For event-stream consumers that aren't a `Process` (e.g. compositor IPC over a Unix socket):
21 +```qml
22 +import Quickshell.Io
24 +Socket {
25 + path: `/tmp/hypr/${Quickshell.env("HYPRLAND_INSTANCE_SIGNATURE")}/.socket2.sock`
26 + connected: true
28 + parser: SplitParser {
29 + property var regex: new RegExp("focusedmon>>(.+),.*")
30 + onRead: msg => {
31 + const match = regex.exec(msg)
32 + if (match) doStuff(match[1])
33 + }
34 + }
36 +```
38 +The parser receives lines, fires `onRead(line)`. The `Socket` connects to the path, sends nothing by default. For Hyprland, the socket path is `/tmp/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock` (event socket) or `.socket.sock` (command socket).
40 +### Env var lookup pattern (focus_following_panel)
42 +```qml
43 +Quickshell.env("HYPRLAND_INSTANCE_SIGNATURE") // "1234567890"
44 +Quickshell.env("HOME") // "/home/user"
45 +Quickshell.env("WAYLAND_DISPLAY") // "wayland-0"
46 +```
48 +`Quickshell.env(name)` returns the env var or `undefined`. Use `?.` or `??` for safe defaults. For checking if a var is _set_ (vs empty), the preprocessor has `isEnvSet()` — see `references/advanced.md`.
50 +### Custom QML keybinds (wlogout)
52 +```qml
53 +Item {
54 + id: btn
55 + focus: true
56 + Keys.onPressed: (event) => {
57 + if (event.key === Qt.Key_K && event.modifiers === Qt.NoModifier) {
58 + command()
59 + }
60 + }
62 +```
64 +To take global keybinds (no focus needed), use `Quickshell.Hyprland.GlobalShortcut` (Hyprland-only) or wire up compositor keybinds → `qs ipc call` (cross-WM). See `examples/06-ipc-control/` and `references/patterns.md` P12.
66 +### Reload popup replacement / inhibition (reload-popup)
68 +To **disable** the built-in reload popup entirely:
70 +```qml
71 +// in shell.qml
72 +ShellRoot {
73 + // Add a ReloadPopup from your own module path; setting inhibit disables the built-in.
74 + // Quickshell-specific: the example defines a ReloadPopup { } component that calls
75 + // Quickshell.inhibitReloadPopup to suppress the default.
77 +```
79 +To **replace** it: define a `ReloadPopup { }` component in your own module path. Quickshell prefers yours over the built-in.
81 +### WlrLayershell.namespace (activate_linux, wlogout)
83 +```qml
84 +PanelWindow {
85 + WlrLayershell.namespace: "mybar"
86 + WlrLayershell.layer: WlrLayer.Overlay
87 + WlrLayershell.keyboardFocus: WlrKeyboardFocus.Exclusive // capture all keys
89 +```
91 +The `namespace` is a string that groups panel surfaces. Two panels with the same namespace stack together; the compositor decides the order within the namespace. Useful when you have multiple components (bar + popups) that should be in the same group.
93 +`keyboardFocus: WlrKeyboardFocus.Exclusive` makes the panel capture all keyboard input (the focus is taken from everything else). For an OSD, use `None`. For a lockscreen, use `Exclusive`. For a bar, default is fine.
95 +## What the official examples don't cover (intentionally)
97 +- **Cross-WM workspace manager** (Sway, i3, Niri) — the `WindowManager` interface works, but no official example exists yet.
98 +- **Live reloading on file change** — the `FileView` type watches a single file; the Quickshell shell itself hot-reloads on save of any `.qml` in the config dir. No code needed.
99 +- **Compositor-agnostic keybinds** — the official examples target Hyprland (because it's what the lead dev uses). For Sway/i3/Niri, you wire up compositor `bindsym` → `qs ipc call` (see `examples/06-ipc-control/`).

skills/quickshell/references/tdd-scenarios.md

Modified
23 23 - 04-pipewire-volume: same as 02 (`import QtQuick.Layouts` + `import QtQuick.Controls`).
24 24 - 05-osd-volume: `WlrLayershell` is attached to `PanelWindow`, not `FloatingWindow` — using it on a `FloatingWindow` is a hard error.
26 -**Root cause of the miss:** the first validation used `grep -iE 'error|warn|fail|invalid|cannot|undefined'` on the runtime log. The actual error messages did contain those words, but the script's regex included the *log* path, and the messages were sometimes in `log.qslog` (the formatted output) rather than `log.log` (the detailed one). The grep was applied to the wrong file in some cases. The second pass ran `qs -p` and read *all* of `log.log`, finding the errors.
26 +**Root cause of the miss:** the first validation used `grep -iE 'error|warn|fail|invalid|cannot|undefined'` on the runtime log. The actual error messages did contain those words, but the script's regex included the _log_ path, and the messages were sometimes in `log.qslog` (the formatted output) rather than `log.log` (the detailed one). The grep was applied to the wrong file in some cases. The second pass ran `qs -p` and read _all_ of `log.log`, finding the errors.
28 -**Lesson for future skill validation:** validate by reading the entire log of *both* `log.log` and `log.qslog`, not by pattern-grepping one file. A "CLEAN" result is meaningful only when the log was actually read.
28 +**Lesson for future skill validation:** validate by reading the entire log of _both_ `log.log` and `log.qslog`, not by pattern-grepping one file. A "CLEAN" result is meaningful only when the log was actually read.
30 30 ## Hard-error vs silent-failure taxonomy

skills/quickshell/references/types.md

Modified
12 12 ## Windows
14 -| Type | Use for |
15 -| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
16 -| `PanelWindow` | Bars, sidebars, drawers, status strips. Reserves space on the screen. Anchored. |
17 -| `FloatingWindow` | Free desktop windows (settings dialogs, popovers that need their own decorations). |
18 -| `PopupWindow` | Anchored to a parent window with `anchor.window`; auto-positions above/below/side. Good for menus and tooltips. |
14 +| Type | Use for |
15 +| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
16 +| `PanelWindow` | Bars, sidebars, drawers, status strips. Reserves space on the screen. Anchored. |
17 +| `FloatingWindow` | Free desktop windows (settings dialogs, popovers that need their own decorations). |
18 +| `PopupWindow` | Anchored to a parent window with `anchor.window`; auto-positions above/below/side. Good for menus and tooltips. |
19 19 | `FloatingWindow` (with `WlrLayershell.layer: WlrLayer.Overlay`) | Fullscreen overlays (like the "Activate Linux" notification). ⚠️ Not actually valid: `WlrLayershell` is a PanelWindow attached property. For overlays use `PanelWindow` + `WlrLayershell.layer: WlrLayer.Overlay` instead. |
21 21 All windows share `QsWindow` base: `screen`, `anchors`, `mask`, `color`, `surfaceFormat`, `WlrLayershell.*` (when on wlroots).