id: NL-SPEC-FDA339B0
type: spec
title: Brightness popup and DDC setup
Brightness popup and DDC setup
Display behavior
Only detected displays are shown.
A built-in row exists only when a usable backlight device exists.
Connected external monitors appear before DDC capability is known.
With no controllable display, detected rows and one primary set up monitor control action appear without fake values or sliders.
With controllable displays, the popup shows four quarter-step presets and one control per display, plus a global control when two or more displays are controllable (owner decision 2026-11-14).
Equal display values produce one normal global fill.
Different values produce one contiguous stacked multislider without a mixed label.
Global drag and presets set every controllable display; per-display drag changes only that display.
Readiness is implied by controls; issue badges appear only on affected rows.
DDC setup behavior
Monitor-control setup renders in Config's Light section; the Light widget links there when setup is needed.
Brightness, dimming and adaptive semantic controls remain in Light; Config navigation never implicitly cancels setup or activates Light sensor demand.
Setup progresses through preflight, authorization, installation, detection, reading, verification, and ready stages.
Setup shows a one-line summary; a failed stage shows its details, and show steps expands every stage as waiting, running, done, or failed (owner decision 2026-11-14).
Authorization occurs only after explicit user action and only when package or current-session setup is incomplete.
Arch's ddcutil package owns persistent system integration.
Nuguland does not duplicate package-owned module or udev configuration.
Detection maps external connectors to I2C buses.
A display becomes controllable only after a successful brightness read.
Partial monitor failure leaves working monitors controllable.
Successful setup collapses to a reopenable, neutral monitor control ready state.
Failures identify the stage and allow retry from that stage.
Duplicate submission is disabled while running.
Cancellation retains completed package-native changes and reports cancellation.
Safety and diagnostics
Privileged setup is initiated only by the user through Nuguland's authorization flow.
Captured output remains internal; exposed diagnostics are bounded and redacted.
Diagnostics exclude passwords, environment variables, and arbitrary command lines.
Detection, reads, and writes have explicit timeouts.
DDC writes run unprivileged against the detected bus.
Successful writes update the row and OSD.
Failed writes preserve the previous value and show an inline error.
Invalid levels are clamped to the supported range.
Interface constraints
Public IPC follows NL-SPEC-86A037A0; brightness and setup panel intents stay on the typed service.
State distinguishes display rows, global none, synced, or mixed state, setup stages, errors, and compact state without debug narration.
Acceptance
Pure tests cover levels, roles, display shaping, mixed and synced state, DDC parsing, stage transitions, partial failure, redaction, timeouts, cancellation, and argument shaping.
QML checks prove setup is observable, writes target detected buses, and privileged work is not detached or opaque.
Full tests and the zero-warning lint gate pass.
A visual check confirms no fake controls, the multislider, presets, display controls, stage feedback, and lowercase labels.
---
id: NL-SPEC-FDA339B0
type: spec
title: Brightness popup and DDC setup
---
# Brightness popup and DDC setup
## Display behavior
- Only detected displays are shown.
- A built-in row exists only when a usable backlight device exists.
- Connected external monitors appear before DDC capability is known.
- With no controllable display, detected rows and one primary `set up monitor control` action appear without fake values or sliders.
- With controllable displays, the popup shows four quarter-step presets and one control per display, plus a global control when two or more displays are controllable (owner decision 2026-11-14).
- Equal display values produce one normal global fill.
- Different values produce one contiguous stacked multislider without a `mixed` label.
- Global drag and presets set every controllable display; per-display drag changes only that display.
- Readiness is implied by controls; issue badges appear only on affected rows.
## DDC setup behavior
- Monitor-control setup renders in Config's Light section; the Light widget links there when setup is needed.
- Brightness, dimming and adaptive semantic controls remain in Light; Config navigation never implicitly cancels setup or activates Light sensor demand.
- Setup progresses through preflight, authorization, installation, detection, reading, verification, and ready stages.
- Setup shows a one-line summary; a failed stage shows its details, and `show steps` expands every stage as waiting, running, done, or failed (owner decision 2026-11-14).
- Authorization occurs only after explicit user action and only when package or current-session setup is incomplete.
- Arch's `ddcutil` package owns persistent system integration.
- Nuguland does not duplicate package-owned module or udev configuration.
- Detection maps external connectors to I2C buses.
- A display becomes controllable only after a successful brightness read.
- Partial monitor failure leaves working monitors controllable.
- Successful setup collapses to a reopenable, neutral `monitor control ready` state.
- Failures identify the stage and allow retry from that stage.
- Duplicate submission is disabled while running.
- Cancellation retains completed package-native changes and reports cancellation.
## Safety and diagnostics
- Privileged setup is initiated only by the user through Nuguland's authorization flow.
- Captured output remains internal; exposed diagnostics are bounded and redacted.
- Diagnostics exclude passwords, environment variables, and arbitrary command lines.
- Detection, reads, and writes have explicit timeouts.
- DDC writes run unprivileged against the detected bus.
- Successful writes update the row and OSD.
- Failed writes preserve the previous value and show an inline error.
- Invalid levels are clamped to the supported range.
## Interface constraints
- Public IPC follows `NL-SPEC-86A037A0`; brightness and setup panel intents stay on the typed service.
- State distinguishes display rows, global none, synced, or mixed state, setup stages, errors, and compact state without debug narration.
## Acceptance
- Pure tests cover levels, roles, display shaping, mixed and synced state, DDC parsing, stage transitions, partial failure, redaction, timeouts, cancellation, and argument shaping.
- QML checks prove setup is observable, writes target detected buses, and privileged work is not detached or opaque.
- Full tests and the zero-warning lint gate pass.
- A visual check confirms no fake controls, the multislider, presets, display controls, stage feedback, and lowercase labels.