---
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 `setup ddc` action appear without fake values or sliders.
- With controllable displays, the popup shows a global control, four quarter-step presets, and one control per display.
- 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

- Setup progresses through preflight, authorization, installation, detection, reading, verification, and ready stages.
- Every expanded stage remains visibly waiting, running, done, or failed.
- 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 `ddc 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

- Existing brightness, display, setup, and self-test IPC remains available.
- 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.