From f6ec88a75bdfdeff9e05c3ef202bfd21a8fd04d7 Mon Sep 17 00:00:00 2001
From: jan <jannihanewinkel@gmail.com>
Date: Sat, 25 Apr 2026 19:11:19 +0200
Subject: [PATCH] Document immediate brightness architecture

---
 README.md               | 16 ++++++++++++++++
 bin/brightness-down-all |  3 +++
 bin/brightness-up-all   |  3 +++
 install.sh              |  1 +
 4 files changed, 23 insertions(+)

diff --git a/README.md b/README.md
index b5baca7..3890acc 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,21 @@ The internal display is the master. Brightness keys change the internal panel, s
 
 This avoids drift from letting two outputs auto-adjust independently.
 
+## Architecture
+
+The real brightness change is intentionally immediate:
+
+```text
+brightness-up/down-all
+  -> brightnessctl immediately changes the internal display
+  -> brightness-osd only displays or updates the visual feedback
+  -> external-brightness-sync.service mirrors the internal percentage later
+```
+
+The actual `brightnessctl` call must not be debounced. Only the OSD may be smoothed by reusing the running OSD process and extending its hide timer.
+
+The external monitor is not changed in the key-binding scripts. `ddcutil` is slower than an internal backlight write, so it runs separately in the sync service.
+
 ## Features
 
 - Internal display controlled with `brightnessctl`
@@ -82,6 +97,7 @@ Default config:
 ```bash
 BRIGHTNESS_BACKLIGHT_DEVICE="intel_backlight"
 BRIGHTNESS_SYNC_BACKLIGHT="/sys/class/backlight/intel_backlight"
+BRIGHTNESS_OSD_BACKLIGHT="/sys/class/backlight/intel_backlight"
 BRIGHTNESS_STEP="10"
 BRIGHTNESS_DDCUTIL_MODEL="HG342PCB"
 BRIGHTNESS_DDCUTIL_DISPLAY="1"
diff --git a/bin/brightness-down-all b/bin/brightness-down-all
index e7b1a69..4acf281 100755
--- a/bin/brightness-down-all
+++ b/bin/brightness-down-all
@@ -3,12 +3,15 @@ set -euo pipefail
 
 CONFIG="${BRIGHTNESS_AUTOMATION_CONFIG:-$HOME/.config/brightness-automation/env}"
 if [[ -f "$CONFIG" ]]; then
+  set -a
   # shellcheck disable=SC1090
   source "$CONFIG"
+  set +a
 fi
 
 BACKLIGHT_DEVICE="${BRIGHTNESS_BACKLIGHT_DEVICE:-intel_backlight}"
 STEP="${BRIGHTNESS_STEP:-10}"
+export BRIGHTNESS_OSD_BACKLIGHT="${BRIGHTNESS_OSD_BACKLIGHT:-${BRIGHTNESS_SYNC_BACKLIGHT:-/sys/class/backlight/${BACKLIGHT_DEVICE}}}"
 
 brightnessctl -q -d "$BACKLIGHT_DEVICE" set "${STEP}%-"
 "$HOME/.local/bin/brightness-osd" || true
diff --git a/bin/brightness-up-all b/bin/brightness-up-all
index 27a9daa..c52176c 100755
--- a/bin/brightness-up-all
+++ b/bin/brightness-up-all
@@ -3,12 +3,15 @@ set -euo pipefail
 
 CONFIG="${BRIGHTNESS_AUTOMATION_CONFIG:-$HOME/.config/brightness-automation/env}"
 if [[ -f "$CONFIG" ]]; then
+  set -a
   # shellcheck disable=SC1090
   source "$CONFIG"
+  set +a
 fi
 
 BACKLIGHT_DEVICE="${BRIGHTNESS_BACKLIGHT_DEVICE:-intel_backlight}"
 STEP="${BRIGHTNESS_STEP:-10}"
+export BRIGHTNESS_OSD_BACKLIGHT="${BRIGHTNESS_OSD_BACKLIGHT:-${BRIGHTNESS_SYNC_BACKLIGHT:-/sys/class/backlight/${BACKLIGHT_DEVICE}}}"
 
 brightnessctl -q -d "$BACKLIGHT_DEVICE" set "+${STEP}%"
 "$HOME/.local/bin/brightness-osd" || true
diff --git a/install.sh b/install.sh
index ded9cf4..6f93f4f 100755
--- a/install.sh
+++ b/install.sh
@@ -26,6 +26,7 @@ if [[ ! -f "$HOME/.config/brightness-automation/env" ]]; then
   cat >"$HOME/.config/brightness-automation/env" <<EOF
 BRIGHTNESS_BACKLIGHT_DEVICE="$BACKLIGHT_DEVICE"
 BRIGHTNESS_SYNC_BACKLIGHT="$BACKLIGHT_PATH"
+BRIGHTNESS_OSD_BACKLIGHT="$BACKLIGHT_PATH"
 BRIGHTNESS_STEP="$STEP"
 BRIGHTNESS_DDCUTIL_MODEL="$DDC_MODEL"
 BRIGHTNESS_DDCUTIL_DISPLAY="$DDC_DISPLAY"