## Summary

On the ASUS ROG Flow Z13 (GZ302EA), every brightness value above raw **64532**
(of `max_brightness` 65535) switches the panel backlight **fully off** —
`actual_brightness` reads back `0` and the screen goes black. Omarchy's
"Brightness maximum" binding (`omarchy-brightness-display 100%`) and any step
that reaches 100% therefore produce a black screen instead of maximum
brightness.

This is not an Omarchy logic error — the panel firmware (CSOT **TL134ADXP03**)
advertises an invalid top ~1.6% of the PWM range, and the kernel has no quirk
for it yet. But Omarchy can protect affected devices the same way it already
ships model-specific hardware fixes (e.g. `fix-asus-ptl-display-backlight.sh`).

## Hardware

- ASUS ROG Flow Z13 GZ302EA (Ryzen AI MAX 395, Strix Halo), BIOS GZ302EA.311
- Omarchy 4.0.0-1, kernel 7.1.8-arch1-3, amdgpu
- Panel: CSOT TL134ADXP03 (eDP-1), backlight `amdgpu_bl1` (raw), max 65535

## Reproduction

Via Omarchy:

```bash
omarchy-brightness-display 100%    # screen goes black
omarchy-brightness-display 98%     # works again
```

Directly via sysfs (deterministic, verified repeatedly):

```bash
echo 64532 | sudo tee /sys/class/backlight/amdgpu_bl1/brightness
cat /sys/class/backlight/amdgpu_bl1/actual_brightness   # -> 65535 (full on)

echo 64533 | sudo tee /sys/class/backlight/amdgpu_bl1/brightness
cat /sys/class/backlight/amdgpu_bl1/actual_brightness   # -> 0    (backlight off!)
```

Measured threshold:

| raw written | actual_brightness | result |
|------------:|------------------:|--------|
| 64532 (0xFC14) | 65535 | OK, full brightness |
| 64533 (0xFC15) | 0 | backlight off |
| 64550 / 64600 / 65000 / 65535 | 0 | backlight off |

Everything below 64533 works normally (firmware applies its own curve, e.g.
50%→23901, 80%→49371).

## Why this hits Omarchy users

- `SHIFT+XF86MonBrightnessUp` is bound to `omarchy-brightness-display 100%` →
  instant black screen.
- `+5%` / `+1%` steps can cross 64533 (~98.44%) the same way.
- Any other desktop would behave identically; the kernel's
  `drm_panel_backlight_quirks` table (which exists for exactly this class of
  panel bugs) has no entry for TL134ADXP03 yet.

## Proposed fix

Two small changes (patch attached: `0001-backlight-cap-panel-that-turns-off-near-max.patch`):

1. **New** `omarchy-hw-backlight-cap` — matches affected panels by EDID product
   name and prints the highest safe percentage (98 for TL134ADXP03); exits 1 on
   unaffected hardware, so the hot path stays untouched for everyone else.
2. `omarchy-brightness-display` — resolve every step form into an absolute
   target and clamp it to `[1, cap]` in one place. Behavior for all existing
   bindings is byte-for-byte identical on unaffected hardware (verified with a
   mock matrix against the original script: `+5%`, `5%-`, `100%`, `1%`, raw
   values, low-current 1% steps, etc.).

On affected hardware: `100%` and any overflowing step now stop at 98%, which
the panel reports as `actual_brightness = 65535` (physically full brightness),
so users lose nothing visible.

## Longer term

A kernel `drm_panel_backlight_quirks` entry for TL134ADXP03 (EDID match) would
fix this for every distro; the Omarchy-side cap protects users until that
lands. Happy to file the kernel bug too — measurement data above should be
sufficient.


## Patch

```diff
--- a/usr/bin/omarchy-hw-backlight-cap
+++ b/usr/bin/omarchy-hw-backlight-cap
@@ -0,0 +1,27 @@
+#!/bin/bash
+
+# omarchy:summary=Print the highest safe display backlight percentage for panels whose firmware switches the backlight off near max_brightness (exit 1 when no cap applies).
+# omarchy:examples=omarchy-hw-backlight-cap
+
+# Match panels by EDID product name -> highest safe percentage.
+#
+# ASUS ROG Flow Z13 GZ302EA (CSOT TL134ADXP03): the firmware exposes
+# max_brightness 65535, but every raw value >= 64533 switches the backlight
+# fully off (actual_brightness reads back 0). The last working value is 64532
+# (~98.44%); 98% stays safely below the broken threshold. Same bug class as
+# drm_panel_backlight_quirks in the kernel, which has no entry for this panel.
+declare -A caps=(
+  [TL134ADXP03]=98
+)
+
+for edid in /sys/class/drm/*/edid; do
+  # No -s size test here: sysfs reports st_size=0 even for populated EDIDs.
+  for panel in "${!caps[@]}"; do
+    if grep -qa "$panel" "$edid" 2>/dev/null; then
+      echo "${caps[$panel]}"
+      exit 0
+    fi
+  done
+done
+
+exit 1
--- a/usr/bin/omarchy-brightness-display
+++ b/usr/bin/omarchy-brightness-display
@@ -92,28 +92,57 @@
   # Current brightness percentage
   current=$(backlight_brightness "$device") || exit 1
 
-  # Apply non-uniform step size: 1% steps if at or below 5%, otherwise set an
-  # absolute target percentage to avoid raw backlight rounding causing uneven OSD steps.
-  if [[ $step == "+5%" ]]; then
+  # Resolve the step into an absolute target percentage so that clamping
+  # happens in one place below. Keep the non-uniform step size: 1% steps if at
+  # or below 5%, otherwise set an absolute target percentage to avoid raw
+  # backlight rounding causing uneven OSD steps.
+  case $step in
+  "+5%")
     if (( current < 5 )); then
       (( target = current + 1 ))
     else
       (( target = current + 5 ))
     fi
-
-    (( target > 100 )) && target=100
-    step="$target%"
-  elif [[ $step == "5%-" ]]; then
+    ;;
+  "5%-")
     if (( current <= 5 )); then
       (( target = current - 1 ))
     else
       (( target = current - 5 ))
     fi
+    ;;
+  +*%)
+    (( target = current + ${step:1:-1} ))
+    ;;
+  *%-)
+    (( target = current - ${step::-2} ))
+    ;;
+  *%)
+    (( target = ${step%\%} ))
+    ;;
+  *)
+    # Raw value or other brightnessctl form: hand it over unchanged.
+    brightnessctl -d "$device" set "$step" >/dev/null
+    (( no_osd )) || omarchy-osd -i brightness -p "$(backlight_brightness "$device")"
+    exit
+    ;;
+  esac
+
+  [[ $target =~ ^[0-9]+$ ]] || exit 1
 
-    (( target < 1 )) && target=1
-    step="$target%"
+  # Clamp to the usable range. Some panels switch their backlight fully off
+  # near max_brightness (ASUS ROG Flow Z13 GZ302EA: every raw value >= 64533 of
+  # 65535), turning the "Brightness maximum" binding into a black screen.
+  # omarchy-hw-backlight-cap reports the highest safe percentage for panels
+  # known to be affected.
+  (( target > 100 )) && target=100
+  (( target < 1 )) && target=1
+  if cap="$(omarchy-hw-backlight-cap 2>/dev/null)" && (( cap < 100 )) && (( target > cap )); then
+    (( target = cap ))
   fi
 
+  step="$target%"
+
   # Set brightness of the display device.
   brightnessctl -d "$device" set "$step" >/dev/null
 
```