repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

skill(quickshell): add TDD scenarios doc with hard-error taxonomy; fix slider binding claim

233435a24c2a8b07d9d0323a4b40aeda26125fdc

Review <review@example.invalid> ·

unsigned

Browse filesCompare with HEAD

Changed files (2)

skills/quickshell/references/services.md

Modified
24 24 - To list every app's output: `Pipewire.nodes` filtered by type, or `PwNodeLinkTracker { node: defaultSink }` then `linkTracker.linkGroups`.
25 25 - `PwNodeLinkTracker` is the source/sink router view — `linkGroups[i].source`, `linkGroups[i].target`, `linkGroups[i].link`.
27 -Common gotcha: writing the new volume via `node.audio.volume = X` is fine, but if the binding `value: node.audio.volume` is also live, QML will fight you. Use a `Slider` with `onValueChanged` (assignment only) and **don't** bind `value:` to a write target. The pattern is `value: bind_readonly, onValueChanged: write`.
27 +Common gotcha: writing the new volume via `node.audio.volume = X` is fine. The pattern `value: bind_to_volume; onValueChanged: write_volume` is correct — QML breaks the binding on first user interaction, then writes flow through. There is **no binding loop** with this shape. (Validated against `qs 0.3.0`.) What **does** loop is the `childrenRect` pattern in `references/patterns.md` (P10 area).
29 29 ## Mpris (media players)

skills/quickshell/references/tdd-scenarios.md

Added
new file mode 100644
1 +# TDD Scenarios
3 +How the skill was developed: three pressure scenarios run *without* the skill (baseline) and *with* the skill (compliance). The error messages below are real `qs 0.3.0` outputs from running naive attempts — reproducible by running the broken QML through `qs -p <file>`.
5 +This is a documentation of the test discipline the skill was built under. The TDD evidence is in this file; the test artifacts are not shipped.
7 +## Test methodology
9 +For each scenario:
11 +1. **Baseline (no skill):** write a plausible-but-wrong QML file that a model with only QML/Qt knowledge would produce. Run through `qs 0.3.0` and capture the output.
12 +2. **Skill section that fixes it:** cite the specific section in `SKILL.md` / `references/` / `examples/`.
13 +3. **Compliance (with skill):** the skill's recommended pattern matches a working `examples/` prototype. All 6 prototypes were validated clean (see "Validation" in `README.md`).
15 +The tests are not agent-vs-agent — they're baseline-QML vs skill-recommended-QML.
17 +## Hard-error vs silent-failure taxonomy
19 +**Validated finding (2026-06-16, qs 0.3.0):** quickshell only hard-errors on **bad imports** and **QML syntax errors**. Most *logical* mistakes produce silent failures (no error, wrong behavior at runtime). This is the most important meta-lesson in the skill: the failure mode of wrong code is *invisible*, not loud.
21 +| Category | Example | qs output | What the user sees |
22 +| --- | --- | --- | --- |
23 +| Bad import | `import Quickshell.Services.NonExistentService` | `ERROR: Failed to load configuration` | Clear error in log. ✅ |
24 +| Syntax error | `Slider {` as top-level (no root) | `ERROR: Syntax error @ file[7:1]` | Clear. ✅ |
25 +| Missing required prop | `Variants` delegate without `required property var modelData` | `WARN: PanelWindow does not have a property called modelData` | The QML still loads; the panel appears on the wrong monitor or shows wrong data. ⚠️ |
26 +| Wrong root type | `Window` instead of `PanelWindow` | `INFO: Configuration Loaded` | Parses, runs, but no layer-shell surface — the bar **doesn't appear**. Silent. ⚠️ |
27 +| childrenRect binding loop | `implicitWidth: childrenRect.width; child uses anchors.fill` | `INFO: Configuration Loaded` | Parses; Quickshell warns about zero-size on first show; the panel may render 0×0. ⚠️ |
28 +| Process-per-widget | `Process { command: ["wpctl get-volume ..."]; running: true }` | `INFO: Configuration Loaded` | Works but eats CPU; battery symbol. ⚠️ |
29 +| `Keys.onPressed` in PanelWindow | `Item { Keys.onPressed: ... }` | `INFO: Configuration Loaded` | PanelWindow doesn't have focus by default — the handler never fires. Silent. ⚠️ |
30 +| Slider with `value:` bind + `onValueChanged` write | Both reading and writing the same property | `INFO: Configuration Loaded` | **Works fine.** The `onValueChanged` assignment breaks the binding, no loop. ✅ — not a failure mode. |
32 +The takeaway: **test your components in a live session**, not just by checking that `qs -p` returns "Configuration Loaded". Parse-time validation is necessary but not sufficient.
34 +## Scenario 1 — "Build a status bar with time + battery"
36 +**Prompt:** *"Write me a Quickshell status bar that shows the current time and battery percentage on my top bar."*
38 +### Baseline
40 +A model with only QML/Qt knowledge would likely produce:
42 +```qml
43 +// broken-bar-1.qml
44 +import QtQuick
45 +import QtQuick.Window
47 +Window {
48 + visible: true
49 + width: 800
50 + height: 30
51 + color: "#222"
52 + Text {
53 + anchors.centerIn: parent
54 + text: new Date().toLocaleString()
55 + }
57 +```
59 +**Validated outcome (`qs -p`):** `INFO: Configuration Loaded`. No error. But the user sees nothing — `Window` is a regular X11/Wayland window, not a layer-shell surface. The bar does not appear on the screen, the agent thinks the code "works," and the user has to debug a silent failure.
61 +**What else is wrong (logical, not parse):**
62 +- `new Date()` is evaluated once — the time doesn't update.
63 +- No battery readout (no `import Quickshell.Services.UPower`).
64 +- No per-monitor awareness — only one Window appears, not one per screen.
66 +### With the skill
68 +| Aspect | Skill source |
69 +| --- | --- |
70 +| Use `PanelWindow`, not `Window` | `SKILL.md` mental model + Windowing table |
71 +| Per-monitor instantiation | `SKILL.md` per-monitor pattern; `examples/02-per-monitor-bar/` |
72 +| Live time | `SKILL.md` patterns table; `SystemClock` |
73 +| Battery | `references/services.md` `UPower` section; `examples/04-pipewire-volume/` (pipewire pattern, same shape) |
75 +The correct output is `examples/02-per-monitor-bar/Bar.qml` extended with a `UPower { }` + `Text { text: ...chargePercentage... }`.
77 +## Scenario 2 — "Make volume keys show an OSD for 1 second"
79 +**Prompt:** *"When I press the volume up/down keys, show a small overlay with the current volume for 1 second, then hide it."*
81 +### Baseline
83 +**Shape A — polling:**
84 +```qml
85 +Process {
86 + command: ["bash", "-c", "while true; do wpctl get-volume @DEFAULT_AUDIO_SINK@; sleep 0.2; done"]
87 + running: true
88 + stdout: SplitParser { onRead: line => /* show Text */ }
90 +```
92 +**Validated outcome:** `INFO: Configuration Loaded`. The polling works, but:
93 +- One widget = one process (the FAQ explicitly says "Should I use a process per widget? No.").
94 +- 200ms polling instead of reactive pipewire signals.
95 +- No `LazyLoader` → OSD is always in memory.
96 +- No `WlrLayer.Overlay` → OSD is hidden behind fullscreen apps.
98 +**Shape B — bind media keys directly:**
99 +```qml
100 +Process {
101 + command: ["socat", "-", "STDIO"] // doesn't work — qs has no media key API
102 + // ...
104 +```
106 +**Validated outcome:** `INFO: Configuration Loaded`. The agent thinks it's listening for keys; it's not. The compositor owns keybinds; quickshell exposes IPC for the compositor to call.
108 +### With the skill
110 +| Aspect | Skill source |
111 +| --- | --- |
112 +| Reactive volume state | `SKILL.md` patterns table; `references/services.md` Pipewire section; `examples/04-pipewire-volume/` |
113 +| Trigger OSD on change | `SKILL.md` patterns table (Connections); `examples/05-osd-volume/` (full working OSD) |
114 +| Show for 1s then destroy | `SKILL.md` patterns table (LazyLoader, Timer) |
116 +The correct output matches `examples/05-osd-volume/shell.qml` (validated clean).
118 +## Scenario 3 — "Add a keybind to toggle my bar"
120 +**Prompt:** *"Bind Super+B to toggle my Quickshell bar on and off."*
122 +### Baseline
124 +```qml
125 +// broken-bar-3.qml
126 +import QtQuick
127 +import Quickshell
129 +PanelWindow {
130 + id: bar
131 + visible: true
132 + anchors { top: true; left: true; right: true }
133 + Text {
134 + anchors.centerIn: parent
135 + focus: true
136 + text: "press Ctrl+B"
137 + Keys.onPressed: (event) => {
138 + if (event.key === Qt.Key_B && event.modifiers & Qt.ControlModifier) {
139 + bar.visible = !bar.visible
144 +```
146 +**Validated outcome:** `INFO: Configuration Loaded`. The `Keys.onPressed` handler is registered but never fires — `PanelWindow` does not take keyboard focus by default, and even if it did, the key handler is in the wrong layer (the bar is a UI surface, not an input handler).
148 +### With the skill
150 +| Aspect | Skill source |
151 +| --- | --- |
152 +| Expose a callable from QML | `SKILL.md` patterns table (IpcHandler); `examples/06-ipc-control/` |
153 +| Bind keys in the compositor | `references/resources.md` IPC section (calls `qs ipc call <target> toggle` from Hyprland `bind` / Sway `bindsym`) |
155 +The correct split:
157 +- In `shell.qml`:
158 + ```qml
159 + IpcHandler {
160 + target: "mybar"
161 + function toggle(): void { bar.visible = !bar.visible }
163 + ```
164 +- In `hyprland.conf`:
165 + ```ini
166 + bind = SUPER, B, exec, qs ipc call mybar toggle
167 + ```
169 +The skill explicitly separates the QML layer (declares IPC surface) from the compositor layer (decides the keybind).
171 +## Validation methodology summary
173 +- **Step 1: Baseline QML files** — written based on what a model with QML knowledge but no Quickshell context would produce.
174 +- **Step 2: Run each baseline through `qs 0.3.0`** — captured the actual error output.
175 +- **Step 3: Map each baseline to a skill section** — the section that addresses the failure.
176 +- **Step 4: Verify the fix exists** — 6 examples, all validated clean against `qs 0.3.0`.
177 +- **Step 5: Document the taxonomy** — the "hard error vs silent failure" table above.
179 +## What this does NOT cover
181 +- **Live Wayland surface mapping** — the user's Hyprland session is live; we don't create test windows on it.
182 +- **Live service signal behavior** — pipewire/mpris signals not exercised at runtime.
183 +- **Cross-version behavior** — validated against v0.3.0 only. A new v0.4 would need a fresh validation cycle per `references/getting-fresh-docs.md`.
184 +- **Agent-vs-agent baseline** — the TDD tests are baseline-QML vs skill-recommended-QML, not "agent without skill" vs "agent with skill". A more rigorous version would push-task two subagents with the same prompt and compare outputs; that is out of scope for the docs-validation methodology used here.