1 +#
Brightness Popup Redesign — Design Spec 4 +**Status:** Approved (owner-delegated, autonomous)
5 +**Goal:** Strip narration from the brightness service, extract the small pure logic (clamp / percent / role thresholds) to a node-tested `brightness.js`, and upgrade `BrightnessPanel` to a solid-dark, role-colored, drag-to-set bar with preset chips. Implemented directly (no workflow) — the surface is 131 + 80 lines; a 5-phase workflow would be ceremony (per advisor YAGNI).
10 +- **Narration bloat.** `stateObject()` carries `backend`, `helperProcesses`, `serviceOwnedActions`, `boundedActions`, and a full `shader` descriptor (`brightness-gradient`, `priorArt`, `values`, `colors`). No `ShaderEffect` renders `brightness-gradient.frag.qsb` — only `aurora.frag.qsb` is ever loaded. Dead. Delete.
11 +- **Untested pure logic.** `clamp01`, level percent, and the role thresholds (`<=0.15 ui.minor`, `>=0.85 warning`, else `ui.accent`) live in QML with no boundary tests.
12 +- **Washout-prone view.** Preset chips use translucent `withAlpha(ui.minor, 0.18)` with invisible (`border.width: 0`) borders — washes out on the light frame. Bar is display-only; no drag-to-set; active preset not highlighted; bar fill not role-colored.
17 +| Architecture | Small pure `brightness.js` (node-tested, dual-mode export, no I/O) + thin `Brightness.qml` (native `FileView` reads + `execDetached` writes stay) + reworked `BrightnessPanel` view. |
18 +| `brightness.js` | `clampLevel(v)` → 0..1 (null/NaN→0); `levelPercent(v)` → `Math.round(clampLevel(v)*100)`; `levelRole(v)` → `<=0.15 "ui.minor"`, `>=0.85 "warning"`, else `"ui.accent"`. Dual-mode `module.exports` tail like clip.js. **No `.pragma library`.** Prints `ALL PASS`. |
19 +| Preserve (consumers) | `setLevel(level)`, `increase()`, `decrease()`, `stateJson()` (shell.qml IPC). `stateObject` keeps `level` + `compact{label,role}`. Native `FileView`/`execDetached`/`applyNative` stay in QML. |
20 +| Delete narration | `backend`, `helperProcesses`, `serviceOwnedActions`, `boundedActions`, the entire `shader` block. Service computes `compact.role` via `Brightness.levelRole(level)`. |
21 +| selfTest | Add `selfTest()` → `{pass,fail,cases}` over clampLevel/levelPercent/levelRole boundaries; expose `brightnessSelfTest` IPC in shell.qml. |
22 +| View (washout fix) | Bar: solid `withAlpha(ui.backdrop, 0.88)` base (keep), fill `withAlpha(<role color>, 0.6)` (role-colored), **drag/click on bar sets level** (`setLevel(event.x/width)`). Preset chips: solid `withAlpha(ui.backdrop, 0.55)`, active preset (within 0.02 of level) → `ui.accent` border + `0.82`; others border `withAlpha(ui.minor,0.45)`. Drop the dead `border.width:0`+color pairs. |
25 +- Non-finite / out-of-range level → `clampLevel` → 0..1.
26 +- Missing backlight files → `nativeMax()`/`nativeBrightness()` already floor at 1; level falls back to a valid fraction.
27 +- No `osdService` → osd returns the inline `{event,value}` (keep current try/catch).
30 +- `node brightness.test.js` → `ALL PASS` (clampLevel -1/2/0.5/null; levelPercent 0/0.5/1; levelRole at 0.15/0.85 boundaries + mid).
31 +- `qs -c nuguland ipc call nuguland brightnessSelfTest` after qmlcache clear + restart.
32 +- Live: open brightness popup, screenshot — solid chips, role-colored fill, drag sets level, active preset highlighted. Confirm `increase`/`decrease` IPC still move the bar.
35 +- Multi-display / per-monitor brightness.
36 +- Brightness shader work (deleting the dead descriptor only).
37 +- Auto/adaptive brightness.