74 lines
3.2 KiB
Markdown
74 lines
3.2 KiB
Markdown
# Optional QuickShell integration
|
|
|
|
The CLI runs without QuickShell. This repository does not install a Control
|
|
Center, copy personal dotfiles or alter compositor/session configuration.
|
|
|
|
A local integration was validated with QuickShell 0.3.1 and SwayFX 0.6 on the
|
|
tested laptop. It adds a compact page to an existing Control Center. Its general
|
|
Catppuccin Mocha theme is independent of the saturated keyboard colors:
|
|
|
|
| Preset | RGB |
|
|
|---|---|
|
|
| Violet (first choice) | `#8000FF` |
|
|
| Blue | `#0040FF` |
|
|
| Cyan | `#00FFFF` |
|
|
| Green | `#00FF40` |
|
|
| Pink | `#FF0080` |
|
|
| Red | `#FF0000` |
|
|
| Orange | `#FF6000` |
|
|
| Yellow | `#FFFF00` |
|
|
|
|
## Process contract
|
|
|
|
Use native `Quickshell.Io.Process` and an argument array. For example, the
|
|
command for a validated violet preset is:
|
|
|
|
```qml
|
|
Process {
|
|
command: ["labfy-rgb", "set", "#8000FF"]
|
|
// Start only in response to an explicit user action.
|
|
running: false
|
|
}
|
|
```
|
|
|
|
A production integration should:
|
|
|
|
- Validate custom colors with `^#[0-9A-Fa-f]{6}$` and integer intensity 0..100.
|
|
- Reserve a single shared busy owner before starting the process, including
|
|
across multiple screen bars. Refuse concurrent writes.
|
|
- Use `["labfy-rgb", "set", color]` for a preset click; it uses the CLI default
|
|
intensity of 100%. The optional fourth argument can combine color/intensity.
|
|
- Use `["labfy-rgb", "brightness", String(percent)]` for intensity and
|
|
`["labfy-rgb", "auto"]` for an explicit firmware button.
|
|
- Update a slider draft without spawning processes on every movement. Apply
|
|
on a deliberate button or a controlled release/debounce strategy.
|
|
- Handle both nonzero exit/crash status and failure to start. Clear busy on all
|
|
completion paths and show a bounded error message.
|
|
- Refresh with `["labfy-rgb", "status", "--json"]` after a command completes.
|
|
Validate schema and fields before displaying results.
|
|
- Keep the firmware button usable if a previous status/cache read failed;
|
|
the CLI performs its own identity checks.
|
|
|
|
Do not use sudo, pkexec, `sh -c`, `bash -c` or shell command concatenation. The
|
|
normal user must already have access to the controller, as described in README.
|
|
An absolute installed executable path is also acceptable when the session PATH
|
|
is unsuitable; it should not be a hard-coded personal checkout path.
|
|
|
|
## State and optional restoration
|
|
|
|
Label cached values as the **last commanded** color/intensity/mode. Do not imply
|
|
that `observed_mode: "unknown"` or a null color is a measured white keyboard.
|
|
On the tested firmware, `auto` visibly returned to white; a different firmware
|
|
may select another effect.
|
|
|
|
Keep startup restoration disabled by default and require an explicit opt-in.
|
|
Store only validated, successfully acknowledged preferences. Firmware preference
|
|
must take precedence over an old color, and uncertain write failures should
|
|
invalidate replay eligibility. If implemented, use a bounded one-shot startup
|
|
check with clear error handling, not permanent polling. Do not replay private or
|
|
corrupt runtime cache bytes across logins. Suspend/resume restoration is not
|
|
provided or enabled by this project.
|
|
|
|
The native cache is temporary command history. Persistent UI preferences are a
|
|
separate opt-in concern. No root service, extra daemon, autostart entry or
|
|
QuickShell dependency is installed with Labfy RGB.
|