1 +#
System Popup Redesign — Design Spec 4 +**Status:** Approved (brainstorming complete)
5 +**Goal:** Replace the slow, cluttered system popup with a fast, graphical Quickshell widget that shows machine identity, live stats, and proactively surfaces potential issues.
11 +The current system popout (`PopoutHost.qml` `systemContent`, backed by `Resources.qml`) is slow and hard to read. The slowness comes from a CPU-rasterized **Canvas** line chart (`ResourceMeter`) repainting five animated series every 2 s, a large `systemWidgetState()` JSON serialized on every read, a per-2 s shell spawn for temperature, and unbounded (3600-sample) history arrays. The host is a 2012 ThinkPad X230 (Intel i5-3320M, 4 threads, HD 4000) — perf is a hard constraint.
13 +The redesign delivers three things in one popup:
15 +1. **Machine identity** — macchina-style facts (host, model, kernel, distro, WM, packages, shell, uptime, battery).
16 +2. **Live, fast stats** — CPU, memory, swap, temperature/fan, network, disk, load — each as a graphical fill-bar + sparkline.
17 +3. **Potential issues** — a proactive checklist (failed services, thermal/throttling, low disk, memory/swap pressure, battery health, pending updates, high load) with click-to-act.
19 +Layout: two equal rounded cards (identity | live) over an issues band over a top-processes row. Visual language matches the rest of nuguland (rounded cards, theme colors, Nerd Font icons, `NuguText`) — **a graphical desktop widget, not a TUI**.
21 +Architecture mirrors the CalDAV feature: a pure, node-tested JS module (`sysinfo.js`) for all parsing and logic, a thin QML service (`Resources.qml`) for I/O and cadence, and a pure-view UI.
25 +##
2. Decisions (locked) 29 +| Content | Two equal sections: machine identity + live stats, plus an issues band and a top-processes row |
30 +| Visual style | Graphical Quickshell widget (rounded cards, fill-bars, Rectangle sparklines, icons) — **never** monospace/unicode-block TUI aesthetic |
31 +| Parsing/logic | Pure JS in `sysinfo.js` (dual-mode: node `require` + QML import), node-tested — same pattern as `caldav.js` |
32 +| Live data source | `/proc/{stat,meminfo,net/dev,diskstats,loadavg}` + `/sys/.../hwmon/*` via `FileView` (Quickshell.Io). **No shell spawns** for live data |
33 +| Battery | `Quickshell.Services.UPower` `displayDevice` (native) — `percentage`, `healthPercentage`, `state`, `changeRate`, `timeToEmpty/Full`, `isLaptopBattery`. No `/sys/class/power_supply` parsing |
34 +| Throttling signal | `Quickshell.Services.UPower` `PowerProfiles.degradationReason` (native) in addition to the temperature threshold |
35 +| Brightness fact | Reuse existing `Brightness.qml` service (no re-read) |
36 +| Sparklines | Row of thin rounded `Rectangle`s, height = sample, metric-colored. No Canvas, no shader |
37 +| Cadence | Fast 2 s (live `/proc` + hwmon reads); Slow 5 s (only while popout open — `df`, `systemctl --failed`, top `ps`); Rare on-open (identity facts cached, `checkupdates` async) |
38 +| History buffers | Ring buffers capped at 32 samples per metric (was 3600) |
39 +| Issue checks | Failed services, thermal/throttling, low disk (<10%), memory+swap pressure, battery health, pending updates, high load average |
40 +| Issue actions | Click an issue to act: failed service → `systemctl status` in terminal; temp → `btm`; updates → update command in terminal |
41 +| Top processes | Top 5 by CPU, refreshed every 5 s, only while popout open |
42 +| Removed | `ResourceMeter` Canvas, `system-mini-graph` shader references, `SystemMetric`, btm launch button, per-frame JSON, per-2 s temp shell spawn, 3600-sample arrays |
43 +| IPC contract | Keep a (trimmed) `systemWidgetState()`/`stateJson()` and add `selfTest()` — see [[nuguland-statejson-is-ipc-contract]] |
44 +| DI | UPower + Brightness injected via `shell.qml` → `Bar.qml` → `PopoutHost.qml`; never a singleton — see [[nuguland-di-no-singleton]] |
48 +##
3. Architecture & Data Flow 51 +/proc/stat,meminfo,net/dev,diskstats,loadavg ─FileView─┐
52 +/sys/.../hwmon/* (temp, fan) ─FileView─┤ fast 2s
54 +UPower.displayDevice, PowerProfiles ──binding──► Resources.qml ──┐
55 +Brightness.qml ──binding──► (I/O + cadence) │
56 +df, systemctl --failed, ps ─Process─► (slow 5s, popout-open) │ calls
57 +checkupdates ─Process─► (rare, async, on-open) │ sysinfo.js
59 + sysinfo.js (pure: parse + detectIssues)
60 + │ props + rings + issues
62 + PopoutHost.qml systemContent (pure view)
63 + • identity card • live card (MetricRow + Sparkline)
64 + • issues band • top-processes row
69 +- **Fast (2 s, always):** reload the `/proc` and `/sys/hwmon` `FileView`s; compute CPU/net/disk deltas, memory, swap, load, temp, fan via `sysinfo.js`; update live properties and push to ring buffers. Pure file reads — no process spawn.
70 +- **Slow (5 s, only while popout visible):** `systemctl --failed` (system + user), `df`, top-5 `ps`. Gated on popout visibility so a closed popup costs nothing beyond the fast loop.
71 +- **Rare (on popout open + long interval):** identity facts (cached after first read); `checkupdates` for pending-update count, run async and network-tolerant.
72 +- **Event-driven (no polling):** battery and power-profile via UPower bindings; brightness via the `Brightness` service.
76 +##
4. Components & Responsibilities 78 +###
4.1 `sysinfo.js` (new — pure JS, node-tested) 82 +- `cpuDelta(prev, curLine) → {usage, next}` — `/proc/stat` first line; idle/total delta.
83 +- `parseMeminfo(text) → {memTotal, memAvailable, swapTotal, swapFree, memoryUsage, swapUsage}`.
84 +- `parseNetDev(text) → {rx, tx}` — sum non-`lo` interfaces.
85 +- `parseDiskstats(text) → {readBytes, writeBytes}` — sum non-`loop`/`ram`, sectors×512.
86 +- `rate(prev, cur, seconds) → number` — generic per-second rate (net/disk).
87 +- `parseLoadavg(text) → {one, five, fifteen}`.
88 +- `parseDf(text) → [{target, usedPercent}]`.
89 +- `parseFailedUnits(text) → [name]`.
90 +- `parsePsTop(text) → [{pid, name, cpu, mem}]`.
91 +- `detectIssues(state) → [{id, severity, icon, label, detail, action}]` — sorted error→warning; `state` carries temp, thresholds, `degradationReason`, disk list, mem/swap-rate, battery `healthPercentage`, load, cores, update count, failed units.
92 +- `formatBytes(n)`, `formatRate(n)`.
93 +- `pushRing(buf, value, cap) → buf` — append, cap length.
95 +Dual-mode export tail (`module.exports` guarded), identical pattern to `caldav.js`.
97 +###
4.2 `sysinfo.test.js` (new — node) 99 +Fixture-driven assertions for every parser, `detectIssues` (each rule fires above its threshold and clears below), battery-wear severity tiers, formatters, and ring-buffer cap. Ends with an `ALL PASS` line.
101 +###
4.3 `Resources.qml` (reworked service) 103 +- `FileView`s: `/proc/stat`, `/proc/meminfo`, `/proc/net/dev`, `/proc/diskstats`, `/proc/loadavg`, and the resolved `/sys/.../hwmon` temp + fan paths (discovered once on start by name: `coretemp`, `thinkpad`).
104 +- Injected: `upower` (UPower singleton or displayDevice), `powerProfiles`, `brightnessService`.
105 +- Live properties (bound by the UI): `cpuUsage`, `memoryUsage`, `swapUsage`, `memTotal/memAvailable`, `swapTotal/swapFree`, `networkRxRate/TxRate`, `diskReadRate/WriteRate`, `cpuTemperatureC`, `fanRpm`, `loadOne/Five/Fifteen`, plus ring buffers `cpuRing`, `memRing`, `tempRing`, `netRing`, `diskRing` (cap 32).
106 +- Issue inputs: `failedUnits`, `diskUsage`, `updateCount`, all from the slow/rare loops.
107 +- `processes` (top 5), refreshed on the slow loop, only while popout open.
108 +- Functions: `refreshFast()`, `refreshSlow()`, `refreshRare()`, `issues()` (delegates to `sysinfo.detectIssues`), `runIssueAction(id)`, `stateJson()` (trimmed), `selfTest()`.
109 +- Three `Timer`s as in §3. Slow/rare gated on a `popoutOpen` property set from the UI.
111 +###
4.4 `PopoutHost.qml` `systemContent` (full rewrite) 113 +- Two rounded cards side by side: **identity** (icon + label rows) and **live** (`MetricRow` per metric).
114 +- Inline components: `MetricRow` (label, value, rounded fill-bar track+fill, `Sparkline`) and `Sparkline` (Repeater of thin rounded `Rectangle`s over a ring buffer).
115 +- **Issues band:** Repeater over `resourceService.issues()`; each row = severity dot/pill + Nerd Font icon + label/detail + a rounded action button (`MouseArea` → `runIssueAction`). Passing checks collapse to one green `✓ … ok` row.
116 +- **Top-processes row:** compact inline list; sets `resourceService.popoutOpen` true on load, false on destruction.
117 +- **Delete** `ResourceMeter`, `SystemMetric`, and `system-mini-graph` shader references.
121 +- `shell.qml`: inject `UPower`/`PowerProfiles`/`Brightness` into `Resources` (or expose them to `PopoutHost` for the identity/battery rows), add `system` IPC `state()`/`selfTest()`.
122 +- `Bar.qml` / `PopoutHost.qml`: pass the services through (existing DI chain).
123 +- `SurfaceManager.qml`: size the `"system"` popup for the two-card layout.
127 +##
5. Issue Checks (rules) 129 +| Check | Fires when | Severity | Action |
130 +|-------|-----------|----------|--------|
131 +| Failed services | `systemctl --failed` (system or user) non-empty | error | `systemctl status <unit>` in terminal |
132 +| Thermal | `cpuTemperatureC ≥ high` (sensor `high`, ~87 °C) **or** `degradationReason` indicates thermal | warning/error | open `btm` |
133 +| Low disk | any mount `usedPercent ≥ 90` | warning (≥90), error (≥95) | open file manager / terminal at mount |
134 +| Mem/swap pressure | `memoryUsage ≥ 0.9` **and** swap actively growing | warning | open `btm` |
135 +| Battery health | `healthSupported` and `healthPercentage < 80` | warning (<80), error (<60) | none (informational) |
136 +| Pending updates | `updateCount > 0` | normal/info | update command in terminal |
137 +| High load | `loadOne > cores` sustained | warning | open `btm` |
139 +All passing → single green `✓ disk · memory · battery · updates ok` row. A check whose data is unavailable (no sensor, no network) is shown as `n/a`, never fired as an issue.
143 +##
6. Error Handling 145 +- Missing temp/fan sensor → value `n/a`, temp sparkline hidden.
146 +- A slow/rare command failing (non-zero exit or empty) → that check is skipped this cycle; last-good value retained; never crashes the service.
147 +- `checkupdates` with no network → update count `n/a`; no false issue.
148 +- UPower reports no laptop battery (`isLaptopBattery === false`) → hide battery identity row and skip the battery-health check.
149 +- All `FileView`s use `printErrors: false`; parse failures fall back to last-good.
155 +- **`sysinfo.test.js` (node):** parsers against captured `/proc`/`df`/`systemctl`/`ps` fixtures; `detectIssues` threshold behavior; battery-wear tiers; formatters; ring cap. Must print `ALL PASS`.
156 +- **`selfTest()` (QML IPC):** integration cases (parse a fixture through the service, issue detection, ring push) returning pass/fail counts — same shape as `CalDav.selfTest()`.
157 +- **Manual/visual:** restart shell, open system popout, screenshot; verify two cards, live sparklines update, the currently-present failed unit (`app-Handy@autostart`) appears as an issue, and perf is smooth (no Canvas).
163 +- Historical graphs beyond the 32-sample sparkline.
164 +- Configurable thresholds / per-user tuning (thresholds are sensible constants).
165 +- GPU utilization% (HD 4000 has no cheap util counter) — GPU shown as identity (model) only.
166 +- Replacing `btm` as the deep-dive tool.