Fix external monitor brightness OSD

brightnessctl drives the kernel backlight class, which laptop panels
have and this desktop does not -- it reports only keyboard and NIC LEDs.
So BrightnessControl removed itself and there was no way to dim the
screen from Panama at all. DDC/CI is the channel the buttons on a
monitor's bezel drive, and it is the only brightness an external display
has. Both sources now render a row each, so a machine gets whichever it
actually has, or none.

Displays are enumerated from sysfs rather than `ddcutil detect`. The
kernel publishes the connector-to-bus mapping as
/sys/class/drm/<card>-<connector>/ddc along with whether anything is
plugged in, which beats parsing detect's undocumented brief output,
yields the connector name spelled exactly as Hyprland spells it, and
probes only connectors with a monitor attached -- one bus on this
machine rather than fourteen, where each empty bus costs a timeout.
No model name is read: Hyprland already knows what every output is
called, so the UI joins on the connector instead of keeping a second
source of truth that could disagree with the Displays page.

Writes are debounced, serial, and read back. Serial because DDC/CI has
no arbitration and two ddcutil processes on one bus interleave their
exchanges and both return garbage. Read back because a write is not a
promise: panels clamp to their own range, ignore values while waking
from standby, and drop writes that arrive too fast. Without the read the
slider would show what Panama asked for rather than what the monitor
did, which is the same class of lie as trusting `hyprctl keyword`.

Brightness is deliberately not a stored preference. The monitor
remembers it and the bezel buttons change it behind Panama's back, so
persisting it would mean restoring a value the panel had moved past.

The contract runs against fixtures with ddcutil stubbed and both sysfs
roots redirected, so it never touches a real monitor. Its fixture
reports a maximum of 200 rather than 100 on purpose -- at 100 the
scaling arithmetic is the identity and a helper that ignored the
reported maximum would pass everything. Verified it catches that, plus a
dropped connection-status filter and an unstripped connector prefix.

Not yet confirmed against hardware: this machine cannot open any I2C bus
yet. ddcutil's udev rule grants that through uaccess but only to devices
created after it was installed, so it needs one udevadm trigger. The
helper detects exactly that case and returns the command as its error
rather than reporting "no displays".

Claude-Session: https://claude.ai/code/session_01BRvzt4H8XXLPVH5MyYdk9L

.gitignore

@@ -13,3 +13,6 @@
 # Python helper bytecode is local runtime state.
 __pycache__/
 *.py[cod]
+
+# Generated from the colour scheme; machine state, not configuration.
+/config/dot/kitty/current-theme.conf

config/dot/kitty/kitty.conf

@@ -183,7 +183,6 @@ font_size 14.0
 
 #: Cursor customization {{{
 
-cursor #c8d3f5
 
 #: Default cursor color. If set to the special value none the cursor
 #: will be rendered with a "reverse video" effect. It's color will be
@@ -193,7 +192,6 @@ cursor #c8d3f5
 #: precedence. Also, the cursor colors are modified if the cell
 #: background and foreground colors have very low contrast.
 
-cursor_text_color #111325
 
 #: The color of text under the cursor. If you want it rendered with
 #: the background color of the cell underneath instead, use the
@@ -312,7 +310,6 @@ cursor_shape block
 #: robustly with the ever-changing sea of bugs that is Cocoa is too
 #: much effort.
 
-url_color #4fd6be
 # url_style curly
 
 #: The color and style for highlighting URLs on mouse-over. url_style
@@ -734,12 +731,10 @@ window_border_width 1pt
 #: placed centrally. A value of top-left means the padding will be
 #: only at the bottom and right edges.
 
-active_border_color #82aaff
 
 #: The color for the border of the active window. Set this to none to
 #: not draw borders around the active window.
 
-inactive_border_color #2f334d
 
 #: The color for the border of inactive windows.
 
@@ -960,16 +955,11 @@ tab_powerline_style round
 #: Template to use for active tabs. If not specified falls back to
 #: tab_title_template.
 
-active_tab_foreground   #1e2030
-active_tab_background   #82aaff
 # active_tab_font_style   bold-italic
-inactive_tab_foreground #c8d3f5
-inactive_tab_background #42465a
 # inactive_tab_font_style normal
 
 #: Tab bar colors and styles.
 
-tab_bar_background #222436
 
 #: Background color for the tab bar. Defaults to using the terminal
 #: background color.
@@ -983,8 +973,8 @@ tab_bar_margin_color none
 
 #: Color scheme {{{
 
-foreground #c8d3f5
+
-background #222436
+include current-theme.conf
 
 #: The foreground and background colors.
 
@@ -1043,8 +1033,6 @@ dim_opacity 1
 #: How much to dim text that has the DIM/FAINT attribute set. One
 #: means no dimming and zero means fully dimmed (i.e. invisible).
 
-selection_foreground #2d3f76
-selection_background #c8d3f5
 
 #: The foreground and background colors for text selected with the
 #: mouse. Setting both of these to none will cause a "reverse video"
@@ -1060,47 +1048,29 @@ selection_background #c8d3f5
 #: dull and bright version, for the first 16 colors. You can set the
 #: remaining 240 colors as color16 to color255.
 
-color0 #1b1d2b
-color8 #444a73
 
 #: black
 
-color1 #ff757f
-color9 #ff757f
 
 #: red
 
-color2  #a5e8b5
-color10 #a5e8b5
 
 #: green
-color3  #ffc777
-color11 #ffc777
 
 #: yellow
 
-color4  #82aaff
-color12 #82aaff
 
 #: blue
 
-color5  #c099ff
-color13 #c099ff
 
 #: magenta
 
-color6  #86e1fc
-color14 #86e1fc
 
 #: cyan
 
-color7  #828bb8
-color15 #c8d3f5
 
 #: white
 
-color16 #ff966c
-color17 #c53b53
 
 # mark1_foreground black
 

config/dot/kitty/themes/tokyonight-day.conf

@@ -0,0 +1,38 @@
+# Tokyo Night Day — the palette's own light variant.
+#
+# The same hues as Moon at a different lightness, so a terminal in light mode
+# still belongs to this desktop rather than looking like a different machine.
+# Kept in the same order as tokyonight-moon.conf so the two can be diffed.
+
+cursor #3760bf
+cursor_text_color #e1e2e7
+url_color #118c74
+active_border_color #2e7de9
+inactive_border_color #c4c8da
+active_tab_foreground   #e1e2e7
+active_tab_background   #2e7de9
+inactive_tab_foreground #3760bf
+inactive_tab_background #c4c8da
+tab_bar_background #e1e2e7
+foreground #3760bf
+background #e1e2e7
+selection_foreground #e1e2e7
+selection_background #99a7df
+color0 #e9e9ed
+color8 #a1a6c5
+color1 #f52a65
+color9 #f52a65
+color2  #587539
+color10 #587539
+color3  #8c6c3e
+color11 #8c6c3e
+color4  #2e7de9
+color12 #2e7de9
+color5  #9854f1
+color13 #9854f1
+color6  #007197
+color14 #007197
+color7  #6172b0
+color15 #3760bf
+color16 #b15c00
+color17 #c64343

config/dot/kitty/themes/tokyonight-moon.conf

@@ -0,0 +1,42 @@
+# Tokyo Night Moon — the dark theme Panama ships.
+#
+# Extracted from kitty.conf so the two schemes can be swapped. kitty.conf
+# includes current-theme.conf, which Panama generates from the colour scheme
+# setting; that generated file is gitignored because it is machine state.
+#
+# Live changes go through `kitty @ set-colors`, which is why kitty.conf enables
+# remote control. Without it a scheme change would only reach terminals opened
+# afterwards.
+
+cursor #c8d3f5
+cursor_text_color #111325
+url_color #4fd6be
+active_border_color #82aaff
+inactive_border_color #2f334d
+active_tab_foreground #1e2030
+active_tab_background #82aaff
+inactive_tab_foreground #c8d3f5
+inactive_tab_background #42465a
+tab_bar_background #222436
+foreground #c8d3f5
+background #222436
+selection_foreground #2d3f76
+selection_background #c8d3f5
+color0 #1b1d2b
+color8 #444a73
+color1 #ff757f
+color9 #ff757f
+color2 #a5e8b5
+color10 #a5e8b5
+color3 #ffc777
+color11 #ffc777
+color4 #82aaff
+color12 #82aaff
+color5 #c099ff
+color13 #c099ff
+color6 #86e1fc
+color14 #86e1fc
+color7 #828bb8
+color15 #c8d3f5
+color16 #ff966c
+color17 #c53b53

config/dot/nvim/lua/config/autocmds.lua

@@ -10,3 +10,6 @@ vim.api.nvim_create_autocmd("BufWritePre", {
     vim.fn.winrestview(view)
   end,
 })
+
+-- Follow the desktop's light/dark setting while running, not only at startup.
+require("config.panama").watch()

config/dot/nvim/lua/config/panama.lua

@@ -0,0 +1,88 @@
+-- Panama desktop integration.
+--
+-- Neovim is the one application here that neither reads the desktop portal nor
+-- has a control socket open by default, so it reads the shared settings file
+-- directly -- the same ~/.config/panama/settings.json that the shell and the
+-- Hyprland config read.
+--
+-- Nothing here may raise. A missing or malformed settings file must cost the
+-- user their colour scheme preference and nothing else; editing text is more
+-- important than matching the desktop.
+
+local M = {}
+
+local function settings_path()
+  local config_home = os.getenv("XDG_CONFIG_HOME")
+  if config_home == nil or config_home == "" then
+    local home = os.getenv("HOME")
+    if home == nil or home == "" then
+      return nil
+    end
+    config_home = home .. "/.config"
+  end
+  return config_home .. "/panama/settings.json"
+end
+
+-- "dark" or "light". Defaults to dark, which is what Panama ships.
+function M.color_scheme()
+  local path = settings_path()
+  if not path then
+    return "dark"
+  end
+
+  local ok, contents = pcall(function()
+    local file = io.open(path, "r")
+    if not file then
+      return nil
+    end
+    local text = file:read("*a")
+    file:close()
+    return text
+  end)
+  if not ok or not contents or contents == "" then
+    return "dark"
+  end
+
+  local decoded_ok, decoded = pcall(vim.json.decode, contents)
+  if not decoded_ok or type(decoded) ~= "table" then
+    return "dark"
+  end
+
+  return decoded.colorScheme == "light" and "light" or "dark"
+end
+
+function M.is_light()
+  return M.color_scheme() == "light"
+end
+
+-- tokyonight ships a light variant in the same family, so light mode stays the
+-- same identity rather than becoming a different editor theme.
+function M.tokyonight_style()
+  return M.is_light() and "day" or "moon"
+end
+
+-- Re-apply the scheme when the window regains focus.
+--
+-- Neovim reads the setting once at startup and has no control socket open by
+-- default, so an editor already running when the desktop scheme flips would
+-- otherwise stay on the old palette until it was restarted. FocusGained is
+-- cheap, happens exactly when you would notice the mismatch, and does nothing
+-- at all unless the scheme actually changed.
+function M.watch()
+  local applied = M.color_scheme()
+
+  vim.api.nvim_create_autocmd("FocusGained", {
+    group = vim.api.nvim_create_augroup("PanamaColorScheme", { clear = true }),
+    callback = function()
+      local current = M.color_scheme()
+      if current == applied then
+        return
+      end
+      applied = current
+      vim.o.background = current
+      pcall(vim.cmd.colorscheme, current == "light" and "tokyonight-day" or "tokyonight-moon")
+    end,
+  })
+end
+
+return M

config/dot/nvim/lua/plugins/colorscheme.lua

@@ -1,31 +1,68 @@
+-- Tokyo Night, following the desktop's colour scheme.
+--
+-- Moon when Panama is dark, Day when it is light. Same theme family either way,
+-- so the editor keeps the identity the rest of the desktop has rather than
+-- becoming a different-looking application when the scheme flips.
+--
+-- The readability fixes below are deliberately dark-only. They were written
+-- against Moon's palette -- a pale comment colour, a mid-grey gutter -- and
+-- applying them to Day would put light grey text on a light background, which
+-- is exactly the legibility problem they exist to solve, inverted.
+
+local panama = require("config.panama")
+
 return {
   {
     "folke/tokyonight.nvim",
-    opts = {
+    opts = function()
-      style = "moon",
+      local light = panama.is_light()
+
+      return {
+        style = panama.tokyonight_style(),
+        light_style = "day",
         transparent = true,
+
         on_colors = function(colors)
+          if light then
+            -- Day's defaults are tuned for a light ground and mostly need no
+            -- help. Comments are the exception: the shipped #848cb5 measures
+            -- 2.54:1 against the #e1e2e7 background, well under the 3:1 floor
+            -- for secondary text. This is 3.25:1 -- readable, and still clearly
+            -- dimmer than Normal's 4.52:1 so it does not compete with code.
+            colors.comment = "#7079a8"
+            return
+          end
+
           colors.comment = "#a0a7c5"
           colors.fg_gutter = "#787f93"
           colors.terminal_black = "#828bb8"
         end,
+
         on_highlights = function(highlights, colors)
-        -- Fix inline code visibility in markdown
+          -- Inline code in markdown is invisible at both lightnesses without
+          -- an explicit background, because the theme leaves it unset.
           highlights["@markup.raw.markdown_inline"] = {
-          bg = colors.terminal_black,
+            bg = light and colors.bg_highlight or colors.terminal_black,
             fg = colors.fg,
           }
           highlights["RenderMarkdownCodeInline"] = {
-          bg = colors.terminal_black,
+            bg = light and colors.bg_highlight or colors.terminal_black,
             fg = colors.fg,
           }
-        -- Fix LspReference* readability: DiagnosticUnnecessary dims fg for unused
+
-        -- imports, making text nearly invisible against LspReferenceText's background
+          -- LspReference* readability: DiagnosticUnnecessary dims fg for unused
-        highlights["LspReferenceText"] = { bg = colors.fg_gutter, fg = colors.fg }
+          -- imports, making text nearly invisible against LspReferenceText's
-        highlights["LspReferenceRead"] = { bg = colors.fg_gutter, fg = colors.fg }
+          -- background.
-        highlights["LspReferenceWrite"] = { bg = colors.fg_gutter, fg = colors.fg }
+          local reference = {
+            bg = light and colors.bg_visual or colors.fg_gutter,
+            fg = colors.fg,
+          }
+          highlights["LspReferenceText"] = reference
+          highlights["LspReferenceRead"] = reference
+          highlights["LspReferenceWrite"] = reference
+        end,
+      }
     end,
-    },
   },
   {
     "LazyVim/LazyVim",

config/dot/quickshell/modules/quicksettings/BrightnessControl.qml

@@ -1,24 +1,44 @@
-// Backlight slider, via brightnessctl.
+// Brightness, from whichever source this machine actually has.
 //
-// This machine drives an external DisplayPort monitor and has no backlight
+// Two exist and they are not interchangeable:
-// class device at all (brightnessctl only reports keyboard/NIC LEDs), so the
+//
-// row removes itself rather than sitting there as a dead control. Probed once
+//   The kernel backlight class, driven by brightnessctl. Laptop panels have it;
-// at startup — backlight devices do not appear and disappear.
+//   this desktop does not -- brightnessctl reports only keyboard and NIC LEDs.
+//
+//   DDC/CI, the channel the buttons on a monitor's bezel drive. That is the
+//   only brightness an external display has, and it is per-monitor.
+//
+// A machine may have neither, either, or both, so this renders a row per source
+// found and removes itself entirely when there are none, rather than sitting
+// there as a dead control.
+//
+// Connector labels appear only when there is more than one row. A single
+// slider needs no explanation of which screen it dims.
 
 import QtQuick
 import Quickshell
 import Quickshell.Io
 import qs.widgets
 import qs.config
+import qs.services
 
 Item {
     id: root
 
-    property bool available: false
+    property bool backlightAvailable: false
-    property real value: 0
+    property real backlightValue: 0
 
-    visible: root.available
+    readonly property int rowCount: (root.backlightAvailable ? 1 : 0) + Brightness.displays.length
-    implicitHeight: root.available ? 32 : 0
+    readonly property bool labelled: root.rowCount > 1
+
+    visible: root.rowCount > 0
+    implicitHeight: rows.implicitHeight
+
+    // Probing I2C takes on the order of a second, so it waits until the panel
+    // is actually on screen rather than running at shell startup. Monitors do
+    // not come and go, so once is enough.
+    onVisibleChanged: if (visible && !Brightness.scanned) Brightness.refresh()
+    Component.onCompleted: if (root.visible && !Brightness.scanned) Brightness.refresh()
 
     // `-m` is the machine-readable form: name,class,current,percent,max
     Process {
@@ -34,18 +54,85 @@ Item {
             const fields = line.split(",");
             if (fields.length < 5 || fields[1] !== "backlight")
                 continue;
-            root.available = true;
+            root.backlightAvailable = true;
-            root.value = parseInt(fields[3]) / 100;
+            root.backlightValue = parseInt(fields[3]) / 100;
             return;
         }
     }
 
-    function apply(v: real): void {
+    function applyBacklight(v: real): void {
-        root.value = v;
+        root.backlightValue = v;
         // Never go fully dark: a 0% backlight looks like a broken shell.
         Quickshell.execDetached(["brightnessctl", "-c", "backlight", "-q", "set", Math.max(1, Math.round(v * 100)) + "%"]);
     }
 
+    Column {
+        id: rows
+        anchors.left: parent.left
+        anchors.right: parent.right
+        spacing: 4
+
+        BrightnessRow {
+            width: rows.width
+            visible: root.backlightAvailable
+            label: "Built-in"
+            value: root.backlightValue
+            onMoved: v => root.applyBacklight(v)
+        }
+
+        Repeater {
+            model: Brightness.displays
+
+            BrightnessRow {
+                required property var modelData
+                width: rows.width
+                // Hyprland already knows what each output is called, so the
+                // name comes from there rather than from a second source that
+                // could disagree with the Displays page. The connector is the
+                // fallback, so a display is never an unlabelled slider.
+                label: Displays.monitorNamed(modelData.connector)?.description || modelData.connector
+                value: modelData.value / 100
+                onMoved: v => Brightness.set(modelData.bus, Math.round(v * 100))
+            }
+        }
+    }
+
+    component BrightnessRow: Item {
+        id: row
+
+        property string label: ""
+        property real value: 0
+        signal moved(real value)
+
+        implicitHeight: caption.height + control.height
+
+        Text {
+            id: caption
+            anchors.left: parent.left
+            anchors.right: parent.right
+            anchors.leftMargin: 6
+            anchors.rightMargin: 6
+            anchors.top: parent.top
+            visible: root.labelled
+            height: visible ? implicitHeight + 2 : 0
+            text: row.label
+            color: Theme.fgDim
+            font.family: Theme.fontFamily
+            font.pixelSize: Theme.fontSizeSmall
+            elide: Text.ElideRight
+        }
+
+        // The slider and its glyph share one strip so the two stay aligned
+        // whether or not a caption sits above them. Anchoring the glyph to
+        // both a caption and a centre line instead would conflict, and an
+        // anchor set to undefined is not released.
+        Item {
+            id: control
+            anchors.left: parent.left
+            anchors.right: parent.right
+            anchors.top: caption.bottom
+            height: 32
+
             // ValueSlider draws its own leading icon, but symbolic icons need
             // recolouring to be visible — see ThemedIcon.
             ThemedIcon {
@@ -63,7 +150,9 @@ Item {
                 anchors.right: parent.right
                 anchors.rightMargin: 32
                 anchors.verticalCenter: parent.verticalCenter
-        value: root.value
+                value: row.value
-        onMoved: v => root.apply(v)
+                onMoved: v => row.moved(v)
+            }
+        }
     }
 }

config/dot/quickshell/modules/settings/DisplaysPage.qml

@@ -1,7 +1,7 @@
 // Displays.
 //
-// Resolution, refresh rate, scale, and rotation, plus the gaming display
+// Resolution, refresh rate, scale, and rotation, plus panel brightness and the
-// policy that was already here.
+// gaming display policy that was already here.
 //
 // Every geometry change goes through an apply-then-confirm countdown. This is
 // the one page where a wrong value can leave the screen unreadable or blank,
@@ -32,7 +32,14 @@ SettingsPage {
             root.selectedOutput = Displays.monitors.length > 0 ? Displays.monitors[0].name : "";
     }
 
-    Component.onCompleted: root.syncSelectedOutput()
+    // Probing I2C for DDC-capable monitors takes on the order of a second, so
+    // it runs when this page is opened rather than at shell startup. Monitors
+    // do not appear while you are looking at a settings page, so once is enough.
+    Component.onCompleted: {
+        root.syncSelectedOutput();
+        if (!Brightness.scanned)
+            Brightness.refresh();
+    }
     Connections {
         target: Displays
         function onMonitorsChanged(): void { root.syncSelectedOutput(); }
@@ -200,6 +207,45 @@ SettingsPage {
         SliderRow { setting: "nightLightTemperature"; divider: false }
     }
 
+    // Panel brightness, over DDC/CI.
+    //
+    // This is hardware state rather than a stored preference: the monitor
+    // remembers it, the bezel buttons change it behind Panama's back, and
+    // writing it into settings.json would mean restoring a value the panel had
+    // already moved on from. So there is no schema key here and no SliderRow --
+    // the rows read and write the display directly.
+    SettingsCard {
+        visible: Brightness.available || Brightness.lastError !== ""
+        title: "Brightness"
+        subtitle: Brightness.available
+            ? "Sent to the monitor over DDC/CI, the same channel its buttons use."
+            : Brightness.lastError
+
+        Repeater {
+            model: Brightness.displays
+
+            SettingRow {
+                id: brightnessRow
+                required property var modelData
+                required property int index
+
+                label: Displays.monitorNamed(modelData.connector)?.description || modelData.connector
+                detail: modelData.connector ? modelData.connector + " · " + modelData.value + "%"
+                                            : modelData.value + "%"
+                divider: brightnessRow.index < Brightness.displays.length - 1
+                controlWidth: 190
+
+                ValueSlider {
+                    anchors.verticalCenter: parent.verticalCenter
+                    anchors.right: parent.right
+                    width: parent.width
+                    value: brightnessRow.modelData.value / 100
+                    onMoved: v => Brightness.set(brightnessRow.modelData.bus, Math.round(v * 100))
+                }
+            }
+        }
+    }
+
     SettingsCard {
         title: "Gaming display policy"
         subtitle: "Applied immediately and restored when Panama starts."

config/dot/quickshell/scripts/panama-brightness

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+
+# External monitor brightness over DDC/CI.
+#
+# A desktop with no backlight class device has no brightness control at all --
+# brightnessctl only sees keyboard and NIC LEDs. The panel itself still has a
+# brightness setting, reachable over the monitor's DDC/CI channel (VCP feature
+# 0x10), which is what the buttons on the bezel drive.
+#
+# Usage:
+#   panama-brightness list            -> {"displays":[...],"error":""}
+#   panama-brightness get <bus>       -> integer percent
+#   panama-brightness set <bus> <pct> -> applies, prints nothing
+#
+# Displays are enumerated from sysfs rather than from `ddcutil detect`. The
+# kernel publishes the connector-to-I2C-bus mapping directly, as
+# /sys/class/drm/<card>-<connector>/ddc, along with whether anything is plugged
+# in. That is better than parsing detect output in three ways: the format is
+# stable where detect's brief output is undocumented, the connector name comes
+# out exactly as Hyprland and the Displays page already spell it (DP-2), and
+# only connectors with a monitor attached get probed -- one bus on this machine
+# instead of fourteen, which is the difference between a fast scan and a slow
+# one, since each probe of an empty bus waits for a timeout.
+#
+# No model name is reported. Hyprland already knows the human-readable
+# description of every output, so the UI joins on the connector name rather than
+# having two sources of truth for what a monitor is called.
+
+set -uo pipefail
+
+readonly VCP_BRIGHTNESS=0x10
+
+# Test seams. The contract needs to exercise enumeration and parsing on a
+# machine whose real monitors it must not touch, so both roots this script
+# reads are overridable. Nothing sets them in normal use.
+readonly DRM_ROOT="${PANAMA_BRIGHTNESS_DRM_ROOT:-/sys/class/drm}"
+readonly DEV_ROOT="${PANAMA_BRIGHTNESS_DEV_ROOT:-/dev}"
+
+emit_error() {
+    printf '{"displays":[],"error":%s}\n' "$(jq -Rn --arg e "$1" '$e')"
+    exit 0
+}
+
+command -v ddcutil >/dev/null 2>&1 || emit_error 'ddcutil is not installed'
+
+# Reading a VCP value needs read/write access to the monitor's I2C bus. The
+# udev rule ddcutil ships grants that to the seat user through uaccess, but only
+# to devices created after the rule was installed -- so a machine that installed
+# ddcutil without rebooting has the rule in place and no access to show for it.
+# That is by far the most likely reason for an empty list, and it is fixable in
+# one command, so say so rather than reporting "no displays".
+has_accessible_bus() {
+    local dev
+    for dev in "$DEV_ROOT"/i2c-*; do
+        [[ -r "$dev" && -w "$dev" ]] && return 0
+    done
+    return 1
+}
+
+cmd_list() {
+    has_accessible_bus || emit_error 'no I2C bus is accessible. ddcutil ships a udev rule that grants this, but only to devices created after it was installed. Run: sudo udevadm control --reload-rules && sudo udevadm trigger --subsystem-match=i2c-dev --subsystem-match=drm'
+
+    local rows=() connector bus value path
+    for path in "$DRM_ROOT"/card*-*; do
+        [[ -e "$path/ddc" ]] || continue
+        [[ "$(cat "$path/status" 2>/dev/null)" == "connected" ]] || continue
+
+        # card1-DP-2 -> DP-2, the name Hyprland uses.
+        connector="$(basename "$path")"
+        connector="${connector#card*-}"
+
+        bus="$(basename "$(readlink -f "$path/ddc")")"
+        bus="${bus#i2c-}"
+        [[ "$bus" =~ ^[0-9]+$ ]] || continue
+
+        # A monitor that does not implement 0x10 is not an error; it simply
+        # cannot be controlled, and is left out rather than shown as a slider
+        # that does nothing.
+        value="$(cmd_get "$bus")" || continue
+        [[ -n "$value" ]] || continue
+
+        rows+=("$(jq -cn \
+            --argjson bus "$bus" \
+            --arg connector "$connector" \
+            --argjson value "$value" \
+            '{bus: $bus, connector: $connector, value: $value}')")
+    done
+
+    if [[ ${#rows[@]} -eq 0 ]]; then
+        emit_error 'no connected monitor reports DDC/CI brightness. Some panels implement it only when "DDC/CI" is enabled in their on-screen menu.'
+    fi
+
+    printf '{"displays":[%s],"error":""}\n' "$(IFS=,; printf '%s' "${rows[*]}")"
+}
+
+# Prints the current brightness as a whole percent, or nothing when the display
+# cannot report it. `getvcp --brief` is documented as machine readable and
+# answers "VCP 10 C <current> <max>"; the max is almost always 100 but is not
+# guaranteed to be, so it is read rather than assumed.
+cmd_get() {
+    local bus="$1" out current max
+    out="$(timeout 10 ddcutil --bus "$bus" getvcp "$VCP_BRIGHTNESS" --brief 2>/dev/null)" || return 1
+    read -r _ _ _ current max <<<"$out"
+    [[ "$current" =~ ^[0-9]+$ && "$max" =~ ^[0-9]+$ && "$max" -gt 0 ]] || return 1
+    printf '%s' "$(( current * 100 / max ))"
+}
+
+cmd_set() {
+    local bus="$1" percent="$2" max out
+    [[ "$percent" =~ ^[0-9]+$ ]] || return 1
+    (( percent > 100 )) && percent=100
+
+    out="$(timeout 10 ddcutil --bus "$bus" getvcp "$VCP_BRIGHTNESS" --brief 2>/dev/null)" || return 1
+    read -r _ _ _ _ max <<<"$out"
+    [[ "$max" =~ ^[0-9]+$ && "$max" -gt 0 ]] || max=100
+
+    timeout 10 ddcutil --bus "$bus" setvcp "$VCP_BRIGHTNESS" "$(( percent * max / 100 ))" >/dev/null 2>&1
+}
+
+case "${1:-list}" in
+    list) cmd_list ;;
+    get)  cmd_get "${2:?bus required}" ;;
+    set)  cmd_set "${2:?bus required}" "${3:?percent required}" ;;
+    *)    printf 'usage: panama-brightness [list|get <bus>|set <bus> <percent>]\n' >&2; exit 2 ;;
+esac

config/dot/quickshell/scripts/panama-osd

@@ -2,6 +2,8 @@
 
 set -u
 
+readonly PANAMA_OSD_SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+
 strict_delivery() {
     [[ ${PANAMA_OSD_STRICT:-false} == true || ${PANAMA_OSD_STRICT:-false} == 1 ]]
 }
@@ -67,18 +69,151 @@ adjust_microphone() {
     show_volume "$target" microphone
 }
 
+brightness_percent() {
+    local output="$1" percent
+    percent="$(awk -F, 'NR == 1 { value=$5; gsub(/%/, "", value); print value }' <<<"$output")"
+    [[ $percent =~ ^[0-9]+$ ]] || return 1
+    printf '%s\n' "$percent"
+}
+
+brightness_error() {
+    local detail="$1" label="External brightness unavailable"
+    if [[ $detail == *udev* || $detail == *accessible* || $detail == *permission* ]]; then
+        label="Brightness needs permission"
+    fi
+
+    show_message dialog-warning-symbolic "$label" || true
+    if command -v notify-send >/dev/null 2>&1; then
+        notify-send --app-name=Panama --icon=display-brightness-symbolic \
+            "Brightness unavailable" "$detail" >/dev/null 2>&1 || true
+    fi
+}
+
+discover_ddc_bus() {
+    local helper="$1" cache_file="$2" list_json focused selected error bus connector
+
+    command -v jq >/dev/null 2>&1 || {
+        brightness_error "jq is required to discover DDC/CI displays."
+        return 1
+    }
+
+    list_json="$("$helper" list 2>/dev/null)" || {
+        brightness_error "The external brightness helper could not inspect connected displays."
+        return 1
+    }
+    if ! jq -e 'type == "object" and (.displays | type == "array")' >/dev/null 2>&1 <<<"$list_json"; then
+        brightness_error "The external brightness helper returned invalid display information."
+        return 1
+    fi
+
+    error="$(jq -r '.error // empty' <<<"$list_json")"
+    if [[ -n $error ]]; then
+        brightness_error "$error"
+        return 1
+    fi
+
+    focused="$(hyprctl -j monitors 2>/dev/null \
+        | jq -r '.[] | select(.focused == true) | .name' 2>/dev/null \
+        | head -n1)"
+    selected="$(jq -r --arg connector "$focused" '
+        ([.displays[] | select(.connector == $connector)][0] // .displays[0] // empty)
+        | [.bus, .connector]
+        | @tsv
+    ' <<<"$list_json")"
+    IFS=$'\t' read -r bus connector <<<"$selected"
+    if [[ ! $bus =~ ^[0-9]+$ ]]; then
+        brightness_error "No connected monitor exposes DDC/CI brightness control."
+        return 1
+    fi
+
+    umask 077
+    printf '%s\t%s\n' "$bus" "$connector" >"$cache_file"
+    printf '%s\n' "$bus"
+}
+
+adjust_ddc_brightness() {
+    local action="$1" step="$2"
+    local helper="${PANAMA_OSD_BRIGHTNESS_HELPER:-$PANAMA_OSD_SCRIPT_DIR/panama-brightness}"
+    local runtime_dir="${PANAMA_OSD_RUNTIME_DIR:-${XDG_RUNTIME_DIR:-/tmp}/panama-osd-${UID}}"
+    local cache_file="$runtime_dir/brightness-bus" lock_file="$runtime_dir/brightness.lock"
+    local bus="" connector="" current target lock_fd
+
+    [[ -x $helper ]] || {
+        brightness_error "The external brightness helper is not installed."
+        return 0
+    }
+    mkdir -p "$runtime_dir" || return 0
+    chmod 700 "$runtime_dir" 2>/dev/null || true
+
+    exec {lock_fd}>"$lock_file" || return 0
+    # DDC transactions on one I2C bus cannot safely overlap. A short wait also
+    # sheds an excessive key-repeat backlog instead of replaying it seconds later.
+    flock -w 2 "$lock_fd" || return 0
+
+    if [[ -r $cache_file ]]; then
+        IFS=$'\t' read -r bus connector <"$cache_file" || true
+        [[ $bus =~ ^[0-9]+$ ]] || bus=""
+    fi
+
+    if [[ -n $bus ]]; then
+        current="$("$helper" get "$bus" 2>/dev/null)" || current=""
+        if [[ ! $current =~ ^[0-9]+$ ]]; then
+            : >"$cache_file"
+            bus=""
+        fi
+    fi
+
+    if [[ -z $bus ]]; then
+        bus="$(discover_ddc_bus "$helper" "$cache_file")" || return 0
+        current="$("$helper" get "$bus" 2>/dev/null)" || current=""
+    fi
+    if [[ ! $current =~ ^[0-9]+$ ]]; then
+        brightness_error "The selected monitor stopped responding over DDC/CI."
+        return 0
+    fi
+
+    if [[ $action == up ]]; then
+        target=$(( current + step ))
+    else
+        target=$(( current - step ))
+    fi
+    (( target > 100 )) && target=100
+    (( target < 0 )) && target=0
+
+    if ! "$helper" set "$bus" "$target" >/dev/null 2>&1; then
+        brightness_error "The selected monitor did not accept the brightness change."
+        return 0
+    fi
+    show_progress brightness "$target" "${target}%"
+}
+
 adjust_brightness() {
     local action="${1:-}" step="${2:-5}" output percent
+    [[ $step =~ ^[0-9]+$ ]] || {
+        printf 'Usage: panama-osd brightness up|down [step]\n' >&2
+        return 2
+    }
     case "$action" in
-        up) brightnessctl -e4 -n2 set "${step}%+" >/dev/null || return ;;
+        up|down) ;;
-        down) brightnessctl -e4 -n2 set "${step}%-" >/dev/null || return ;;
         *) printf 'Usage: panama-osd brightness up|down [step]\n' >&2; return 2 ;;
     esac
 
+    # Laptop panels expose a kernel backlight class and remain the fastest,
+    # most reliable path. Desktops fall through to DDC/CI monitor control.
+    output="$(brightnessctl -m -c backlight 2>/dev/null)" || output=""
+    if percent="$(brightness_percent "$output")"; then
+        if [[ $action == up ]]; then
+            brightnessctl -e4 -n2 -c backlight set "${step}%+" >/dev/null || return 0
+        else
+            brightnessctl -e4 -n2 -c backlight set "${step}%-" >/dev/null || return 0
+        fi
         output="$(brightnessctl -m -c backlight 2>/dev/null)" || return 0
-    percent="$(awk -F, 'NR == 1 { value=$5; gsub(/%/, "", value); print value }' <<<"$output")"
+        percent="$(brightness_percent "$output")" || return 0
-    [[ $percent =~ ^[0-9]+$ ]] || return 0
         show_progress brightness "$percent" "${percent}%"
+        return
+    fi
+
+    adjust_ddc_brightness "$action" "$step"
 }
 
 media_action() {

config/dot/quickshell/scripts/panama-theme-apps

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+
+# Propagates the colour scheme to applications that do not read the desktop
+# portal.
+#
+# Most modern applications DO follow org.freedesktop.portal.Settings and need
+# nothing from us: GTK4/libadwaita, Qt6, Chromium and Electron all read
+# org.freedesktop.appearance color-scheme, which xdg-desktop-portal-gtk serves
+# from gsettings. Panama sets that, so those follow automatically.
+#
+# Terminals are the notable exception -- they predate the standard and carry
+# their own palettes. kitty is handled here.
+#
+#   panama-theme-apps dark|light
+#
+# kitty gets it twice: the generated include file so terminals opened later
+# start correct, and a live `set-colors` over its control socket so terminals
+# already open change now. Without the second, a scheme change appears to do
+# nothing until you open a new window.
+
+set -euo pipefail
+
+scheme="${1:-dark}"
+case "$scheme" in
+    dark|light) ;;
+    *) printf 'usage: panama-theme-apps [dark|light]\n' >&2; exit 2 ;;
+esac
+
+kitty_dir="${XDG_CONFIG_HOME:-$HOME/.config}/kitty"
+theme_file="$kitty_dir/themes/tokyonight-moon.conf"
+[[ "$scheme" == "light" ]] && theme_file="$kitty_dir/themes/tokyonight-day.conf"
+
+status_kitty="skipped"
+if [[ -r "$theme_file" ]]; then
+    # Written atomically: kitty may read this while a new window is starting.
+    if cp "$theme_file" "$kitty_dir/current-theme.conf.tmp" 2>/dev/null \
+        && mv "$kitty_dir/current-theme.conf.tmp" "$kitty_dir/current-theme.conf" 2>/dev/null; then
+        status_kitty="written"
+    fi
+
+    # Live-apply to running terminals. kitty appends its PID to the socket name
+    # from listen_on, so there is one socket per instance -- "unix:@mykitty"
+    # alone reaches nothing, which is exactly how this looked like remote
+    # control being disabled when it was not.
+    if command -v kitty >/dev/null 2>&1 && command -v ss >/dev/null 2>&1; then
+        applied=0
+        while read -r socket; do
+            [[ -n "$socket" ]] || continue
+            if kitty @ --to "unix:@${socket#@}" set-colors --all --configured "$theme_file" >/dev/null 2>&1; then
+                applied=$((applied + 1))
+            fi
+        done < <(ss -xl 2>/dev/null | grep -oE '@mykitty[^[:space:]]*' | sort -u)
+        (( applied > 0 )) && status_kitty="applied to $applied"
+    fi
+fi
+
+printf '{"scheme":"%s","kitty":"%s"}\n' "$scheme" "$status_kitty"

config/dot/quickshell/services/Brightness.qml

@@ -0,0 +1,163 @@
+pragma Singleton
+
+// Panel brightness for external monitors, over DDC/CI.
+//
+// brightnessctl covers laptop panels through the kernel's backlight class. A
+// desktop driving a DisplayPort monitor has no such device, so it has no
+// brightness control at all -- the only way to dim the screen is the buttons on
+// the bezel. DDC/CI is the channel those buttons drive, and monitors expose it
+// over the same I2C lines that carry EDID.
+//
+// Two things shape everything here:
+//
+//   Detection is slow. Probing every I2C bus takes on the order of a second,
+//   which is far too slow to sit in front of a settings page opening. It runs
+//   once, on demand, and afterwards each display is addressed by its bus number
+//   directly.
+//
+//   Writes are slow AND rate-limited by the monitor's firmware. A slider drag
+//   emits values continuously; sending each one produces a queue the panel
+//   works through seconds after the user let go, and some monitors drop or
+//   garble writes that arrive too fast. So `value` updates immediately for the
+//   UI and the hardware write is debounced, with only the latest value sent.
+//
+// Displays are keyed by DRM connector name (DP-2) so they line up with what
+// Hyprland, the Displays page, and the monitor list already call them.
+
+import Quickshell
+import Quickshell.Io
+import QtQuick
+
+Singleton {
+    id: root
+
+    readonly property string helperPath: Quickshell.shellDir + "/scripts/panama-brightness"
+
+    // [{ bus, connector, model, value }] where value is 0..100.
+    property var displays: []
+    property bool scanning: false
+
+    // Empty when everything is fine. Carries the helper's explanation
+    // otherwise -- most usefully the udev command that grants I2C access,
+    // which is the difference between "brightness is unavailable" and
+    // "brightness is one command away".
+    property string lastError: ""
+
+    readonly property bool available: root.displays.length > 0
+
+    // True once a scan has completed, however it went. Lets the UI tell "not
+    // looked yet" apart from "looked and found nothing", which otherwise render
+    // identically and leave a permanently empty panel with no explanation.
+    property bool scanned: false
+
+    // Pending writes, keyed by bus. A monitor being dragged accumulates exactly
+    // one entry no matter how many values the slider emits.
+    property var pending: ({})
+
+    function refresh(): void {
+        if (root.scanning)
+            return;
+        root.scanning = true;
+        scan.running = true;
+    }
+
+    function displayFor(connector: string): var {
+        return root.displays.find(display => display.connector === connector) ?? null;
+    }
+
+    // Sets brightness for one display. The stored value moves at once so the
+    // slider tracks the pointer; the hardware follows when the drag settles.
+    function set(bus: int, percent: int): void {
+        const clamped = Math.max(0, Math.min(100, Math.round(percent)));
+
+        root.displays = root.displays.map(display =>
+            display.bus === bus ? Object.assign({}, display, { value: clamped }) : display);
+
+        const next = Object.assign({}, root.pending);
+        next[String(bus)] = clamped;
+        root.pending = next;
+        writeDebounce.restart();
+    }
+
+    Process {
+        id: scan
+        command: [root.helperPath, "list"]
+        stdout: StdioCollector {
+            onStreamFinished: {
+                try {
+                    const parsed = JSON.parse(this.text);
+                    root.displays = Array.isArray(parsed.displays) ? parsed.displays : [];
+                    root.lastError = String(parsed.error ?? "");
+                } catch (error) {
+                    root.displays = [];
+                    root.lastError = "Could not read the brightness helper's output.";
+                    console.warn("Brightness: could not parse helper output:", error);
+                }
+                root.scanning = false;
+                root.scanned = true;
+            }
+        }
+    }
+
+    // Long enough that a drag produces one write rather than dozens, short
+    // enough that a single click still feels immediate.
+    Timer {
+        id: writeDebounce
+        interval: 120
+        onTriggered: root.pump()
+    }
+
+    // Writes run one at a time, and each is read back.
+    //
+    // Serial because DDC/CI is a bus protocol with no arbitration: two ddcutil
+    // processes talking to the same monitor interleave their exchanges and both
+    // can come back with garbage. Read back because a write is not a promise --
+    // panels clamp to their own range, ignore values while waking from standby,
+    // and drop writes that arrive too quickly. Without the read the slider shows
+    // what Panama asked for rather than what the monitor did, which is the same
+    // class of lie as trusting `hyprctl keyword` to have applied something.
+    property int writingBus: -1
+
+    function pump(): void {
+        if (writer.running || reader.running)
+            return;
+
+        for (const bus in root.pending) {
+            const value = root.pending[bus];
+            const remaining = Object.assign({}, root.pending);
+            delete remaining[bus];
+            root.pending = remaining;
+
+            root.writingBus = parseInt(bus);
+            writer.command = [root.helperPath, "set", bus, String(value)];
+            writer.running = true;
+            return;
+        }
+    }
+
+    Process {
+        id: writer
+        onExited: {
+            reader.command = [root.helperPath, "get", String(root.writingBus)];
+            reader.running = true;
+        }
+    }
+
+    Process {
+        id: reader
+        stdout: StdioCollector {
+            onStreamFinished: {
+                const actual = parseInt(this.text.trim());
+                if (!isNaN(actual)) {
+                    root.displays = root.displays.map(display =>
+                        display.bus === root.writingBus
+                            ? Object.assign({}, display, { value: actual })
+                            : display);
+                }
+                root.writingBus = -1;
+                // Anything queued while this write was in flight goes now.
+                root.pump();
+            }
+        }
+    }
+}

config/dot/quickshell/services/ColorScheme.qml

@@ -21,6 +21,8 @@ import qs.config
 Singleton {
     id: root
 
+    readonly property string appThemePath: Quickshell.shellDir + "/scripts/panama-theme-apps"
+
     readonly property bool dark: DesktopPreferences.get("colorScheme") !== "light"
     property string lastError: ""
 
@@ -92,6 +94,12 @@ Singleton {
         commands.push(["hyprctl", "eval",
             `hl.config({ general = { col = { inactive_border = "${inactive}" } } })`]);
 
+        // Applications that predate org.freedesktop.appearance and carry their
+        // own palettes -- terminals, chiefly. Everything that reads the portal
+        // (GTK4, Qt6, Chromium, Electron) is already handled by the gsettings
+        // write above and needs nothing here.
+        commands.push([root.appThemePath, root.dark ? "dark" : "light"]);
+
         root.enqueue(commands);
     }
 }

setup/scripts/link-dotfiles

@@ -70,6 +70,27 @@ for dir in "${dirs[@]}"; do
   log "Linked $PANAMA_DOT/$dir → $CONFIG/$dir"
 done
 
+# kitty.conf ends with `include current-theme.conf`, and that file is generated
+# from the desktop colour scheme rather than committed -- it is machine state.
+# A fresh checkout therefore has no such file, and kitty starts by complaining
+# about a missing include and falling back to its stock colours. Seed it from
+# the scheme in settings.json (dark unless the user has chosen otherwise) so a
+# first launch is themed; ColorScheme.qml overwrites it on every change after.
+KITTY_THEME="$PANAMA_DOT/kitty/current-theme.conf"
+if [ -e "$KITTY_THEME" ]; then
+  log "Keeping existing kitty theme at $KITTY_THEME"
+else
+  scheme="dark"
+  settings="${XDG_CONFIG_HOME:-$HOME/.config}/panama/settings.json"
+  if [ -r "$settings" ]; then
+    stored="$(jq -r '.colorScheme // "dark"' "$settings" 2>/dev/null || echo dark)"
+    [ "$stored" = "light" ] && scheme="light"
+  fi
+  [ "$scheme" = "light" ] && theme="tokyonight-day" || theme="tokyonight-moon"
+  cp "$PANAMA_DOT/kitty/themes/$theme.conf" "$KITTY_THEME"
+  log "Seeded kitty $scheme theme ($theme) → $KITTY_THEME"
+fi
+
 # Vicinae 0.26 discovers user themes from its XDG data directory rather than
 # from ~/.config/vicinae. Keep the authored theme in Panama with the rest of
 # the launcher config and expose only that file at Vicinae's runtime path.

tests/quickshell/brightness-helper-contract.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+
+# panama-brightness enumerates monitors from sysfs and speaks DDC/CI to them.
+#
+# The parts worth pinning down are the ones that decide whether a slider appears
+# at all, and whether it appears attached to the right screen:
+#
+#   * only connectors with something plugged in are probed, because probing an
+#     empty bus costs a timeout each and there are fourteen of them here;
+#   * a panel that cannot report brightness is omitted rather than shown as a
+#     control that does nothing;
+#   * the connector name matches what Hyprland calls the output, since the UI
+#     joins on it to get the monitor's description;
+#   * no I2C access produces the udev command that fixes it, not "no displays".
+#
+# Runs entirely against fixtures. Real monitors are never touched: both the
+# sysfs root and the device root are redirected, and ddcutil is replaced on PATH.
+
+set -uo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+helper="$repo_dir/config/dot/quickshell/scripts/panama-brightness"
+
+fail() {
+    printf 'brightness helper contract: %s\n' "$1" >&2
+    exit 1
+}
+
+fixture="$(mktemp -d /tmp/panama-brightness.XXXXXX)"
+trap 'rm -rf "$fixture"' EXIT
+
+mkdir -p "$fixture/drm" "$fixture/dev" "$fixture/bin" "$fixture/i2c"
+
+# Two connectors with a monitor, two without. DP-2 answers DDC; DP-3 is
+# connected but does not implement brightness. HDMI-A-1 and DP-1 are empty and
+# must never be probed at all.
+make_connector() {
+    local name="$1" bus="$2" status="$3"
+    mkdir -p "$fixture/drm/$name"
+    printf '%s\n' "$status" >"$fixture/drm/$name/status"
+    mkdir -p "$fixture/i2c/i2c-$bus"
+    ln -sfn "$fixture/i2c/i2c-$bus" "$fixture/drm/$name/ddc"
+}
+make_connector card1-DP-1     4  disconnected
+make_connector card1-DP-2     5  connected
+make_connector card1-DP-3     6  connected
+make_connector card1-HDMI-A-1 7  disconnected
+
+# has_accessible_bus only needs one readable/writable node to exist.
+touch "$fixture/dev/i2c-5"
+
+# Stub ddcutil. Records every bus it is asked about so the test can prove the
+# disconnected ones were skipped. Bus 6 refuses, standing in for a panel without
+# VCP 0x10.
+#
+# Bus 5 reports its brightness out of 200 rather than 100. Most panels do use
+# 100, which is exactly the problem: with a maximum of 100 the scaling
+# arithmetic is the identity, so a helper that ignored the reported maximum
+# entirely would pass every assertion. 200 makes reads and writes that skip the
+# conversion visibly wrong.
+cat >"$fixture/bin/ddcutil" <<'STUB'
+#!/usr/bin/env bash
+bus=""
+args=("$@")
+for ((i = 0; i < ${#args[@]}; i++)); do
+    [[ "${args[$i]}" == "--bus" ]] && bus="${args[$((i + 1))]}"
+done
+printf '%s\n' "$bus" >>"$DDCUTIL_PROBE_LOG"
+
+for arg in "$@"; do
+    if [[ "$arg" == "setvcp" ]]; then
+        printf 'set %s %s\n' "$bus" "${args[-1]}" >>"$DDCUTIL_SET_LOG"
+        exit 0
+    fi
+done
+
+case "$bus" in
+    5) printf 'VCP 10 C 120 200\n'; exit 0 ;;
+    *) exit 1 ;;
+esac
+STUB
+chmod +x "$fixture/bin/ddcutil"
+
+export DDCUTIL_PROBE_LOG="$fixture/probes.log"
+export DDCUTIL_SET_LOG="$fixture/sets.log"
+: >"$DDCUTIL_PROBE_LOG"
+: >"$DDCUTIL_SET_LOG"
+
+run_helper() {
+    PATH="$fixture/bin:$PATH" \
+    PANAMA_BRIGHTNESS_DRM_ROOT="$fixture/drm" \
+    PANAMA_BRIGHTNESS_DEV_ROOT="$fixture/dev" \
+        "$helper" "$@"
+}
+
+# ── Enumeration ──────────────────────────────────────────────────────────────
+listing="$(run_helper list)"
+jq -e . >/dev/null 2>&1 <<<"$listing" || fail "list did not emit JSON: $listing"
+
+[[ "$(jq -r '.displays | length' <<<"$listing")" == "1" ]] \
+    || fail "expected exactly one controllable display, got: $listing"
+
+[[ "$(jq -r '.displays[0].connector' <<<"$listing")" == "DP-2" ]] \
+    || fail "the connector name must match Hyprland's output name: $listing"
+
+[[ "$(jq -r '.displays[0].bus' <<<"$listing")" == "5" ]] \
+    || fail "the display was mapped to the wrong I2C bus: $listing"
+
+# 120 of a maximum of 200 is 60%.
+[[ "$(jq -r '.displays[0].value' <<<"$listing")" == "60" ]] \
+    || fail "brightness was not read as a percent of the reported maximum: $listing"
+
+[[ "$(jq -r '.error' <<<"$listing")" == "" ]] \
+    || fail "a successful listing must not carry an error: $listing"
+
+# A connected panel that cannot report brightness is dropped, not listed.
+jq -e '.displays | map(.connector) | index("DP-3") == null' >/dev/null <<<"$listing" \
+    || fail 'a display without VCP 0x10 was listed as controllable'
+
+# ── Disconnected connectors are never probed ─────────────────────────────────
+if grep -qxE '4|7' "$DDCUTIL_PROBE_LOG"; then
+    fail "a disconnected connector was probed -- each empty bus costs a timeout: $(tr '\n' ' ' <"$DDCUTIL_PROBE_LOG")"
+fi
+
+# ── Writes scale to the reported maximum ─────────────────────────────────────
+run_helper set 5 40
+[[ "$(tail -1 "$DDCUTIL_SET_LOG")" == "set 5 80" ]] \
+    || fail "set did not scale to the display's maximum: $(cat "$DDCUTIL_SET_LOG")"
+
+run_helper set 5 500
+[[ "$(tail -1 "$DDCUTIL_SET_LOG")" == "set 5 200" ]] \
+    || fail "an out-of-range percent was not clamped: $(cat "$DDCUTIL_SET_LOG")"
+
+# ── No I2C access explains itself ────────────────────────────────────────────
+rm -f "$fixture/dev"/i2c-*
+denied="$(run_helper list)"
+[[ "$(jq -r '.displays | length' <<<"$denied")" == "0" ]] \
+    || fail "displays were reported without I2C access: $denied"
+grep -q 'udevadm' <<<"$(jq -r '.error' <<<"$denied")" \
+    || fail "the no-access error must name the command that fixes it, got: $(jq -r '.error' <<<"$denied")"
+
+printf 'brightness helper contract: PASS\n'

tests/quickshell/displays-contract.sh

@@ -113,6 +113,25 @@ config_home="$(mktemp -d /tmp/panama-displays-config.XXXXXX)"
 run() { XDG_CONFIG_HOME="$config_home" qs -p "$harness" "$@"; }
 status() { run ipc call displays-test status; }
 
+# The shipped geometry, read from the Hyprland config rather than from the
+# running compositor.
+#
+# Everything below captures "original" from what it observes at start, which is
+# correct only if the display is already in a good state. A previous run that
+# failed mid-revert leaves the display changed, and the next run then captures
+# THAT as the original and faithfully restores the desktop to a broken value.
+# One flake becomes permanent. So refuse to run from a state that does not match
+# what the config says, rather than laundering it.
+shipped_scale="$(sed -n 's/^local shipped_scale *= *\([0-9.]*\).*/\1/p' \
+    "$repo_dir/config/dot/hypr/monitors.lua" | head -1)"
+[[ -n "$shipped_scale" ]] || fail 'could not read the shipped scale from monitors.lua -- the guard below depends on it, and skipping it silently is how a dirty baseline gets laundered'
+if [[ -n "$shipped_scale" ]]; then
+    live_scale="$(hyprctl -j monitors | jq -r '.[0].scale')"
+    if ! awk -v a="$live_scale" -v b="$shipped_scale" 'BEGIN { exit !(a == b) }'; then
+        fail "the display is at scale $live_scale but the config ships $shipped_scale -- refusing to capture a dirty state as the baseline. Restore it first: hyprctl eval 'hl.monitor({ output = \"DP-2\", mode = \"4500x3000@60\", scale = $shipped_scale, transform = 0 })'"
+    fi
+fi
+
 original_mode=""
 original_scale=""
 original_transform=""

tests/quickshell/focus-session-expiry.sh

@@ -13,6 +13,20 @@ cleanup() {
 trap cleanup EXIT
 
 qs ipc call focus end >/dev/null 2>&1 || true
+
+# focus start records the caffeine state it found so end() can hand it back, and
+# the assertion below requires caffeine to finish off. Both are only true if
+# caffeine starts off.
+#
+# This test kills and restarts the live shell, so an interrupted run leaves
+# caffeine on with nothing to turn it back off. The next run then records
+# "previously on", faithfully restores it, and fails -- and every run after
+# that fails identically, with the desktop quietly unable to idle or lock the
+# whole time. Refuse to start from that state rather than latching it in.
+if [[ "$(qs ipc call caffeine status 2>/dev/null)" != "false" ]]; then
+    fail 'caffeine is on before the session starts -- this test cannot distinguish "restored correctly" from "never released". Turn it off first: qs ipc call caffeine toggle'
+fi
+
 qs ipc call focus start >/dev/null
 
 state_file=$(find "${XDG_STATE_HOME:-$HOME/.local/state}/quickshell/by-shell" -name focus-session.json -print -quit)

tests/quickshell/osd-helper-contract.sh

@@ -26,10 +26,62 @@ printf 'brightnessctl' >>"$OSD_TEST_LOG"
 printf ' <%s>' "$@" >>"$OSD_TEST_LOG"
 printf '\n' >>"$OSD_TEST_LOG"
 if [[ " $* " == *" -m "* && " $* " != *" set "* ]]; then
+    [[ ${BACKLIGHT_AVAILABLE:-true} == true ]] || exit 1
     printf '%s\n' "${BRIGHTNESS_OUTPUT:-intel_backlight,backlight,500,1000,50%}"
 fi
 SH
 
+cat >"$scratch/bin/panama-brightness" <<'SH'
+#!/bin/bash
+printf 'panama-brightness' >>"$OSD_TEST_LOG"
+printf ' <%s>' "$@" >>"$OSD_TEST_LOG"
+printf '\n' >>"$OSD_TEST_LOG"
+
+case "${1:-}" in
+    list)
+        if [[ -n ${DDC_LIST_JSON:-} ]]; then
+            printf '%s\n' "$DDC_LIST_JSON"
+        else
+            printf '%s\n' '{"displays":[],"error":"No displays"}'
+        fi
+        ;;
+    get)
+        [[ ${DDC_FAIL_GET_BUS:-} != "${2:-}" ]] || exit 1
+        if [[ -s $OSD_DDC_STATE ]]; then
+            cat "$OSD_DDC_STATE"
+        else
+            printf '%s\n' "${DDC_GET_VALUE:-40}"
+        fi
+        ;;
+    set)
+        if [[ -n ${DDC_SET_DELAY:-} ]]; then
+            if ! mkdir "$OSD_DDC_PROBE" 2>/dev/null; then
+                printf 'ddc-overlap\n' >>"$OSD_TEST_LOG"
+            fi
+            sleep "$DDC_SET_DELAY"
+            rmdir "$OSD_DDC_PROBE" 2>/dev/null || true
+        fi
+        printf '%s\n' "${3:-0}" >"$OSD_DDC_STATE"
+        ;;
+    *) exit 2 ;;
+esac
+SH
+
+cat >"$scratch/bin/hyprctl" <<'SH'
+#!/bin/bash
+printf 'hyprctl' >>"$OSD_TEST_LOG"
+printf ' <%s>' "$@" >>"$OSD_TEST_LOG"
+printf '\n' >>"$OSD_TEST_LOG"
+printf '[{"name":"%s","focused":true}]\n' "${FOCUSED_MONITOR:-DP-2}"
+SH
+
+cat >"$scratch/bin/notify-send" <<'SH'
+#!/bin/bash
+printf 'notify-send' >>"$OSD_TEST_LOG"
+printf ' <%s>' "$@" >>"$OSD_TEST_LOG"
+printf '\n' >>"$OSD_TEST_LOG"
+SH
+
 cat >"$scratch/bin/playerctl" <<'SH'
 #!/bin/bash
 printf 'playerctl' >>"$OSD_TEST_LOG"
@@ -53,9 +105,21 @@ SH
 chmod +x "$scratch/bin/"*
 
 run_helper() {
+    local runtime="${OSD_RUNTIME_DIR:-$scratch/runtime-default}"
+    mkdir -p "$runtime"
     PATH="$scratch/bin:$PATH" OSD_TEST_LOG="$log" \
         OSD_TEST_FAIL_QS="${OSD_TEST_FAIL_QS:-false}" \
         PANAMA_OSD_STRICT="${PANAMA_OSD_STRICT:-false}" \
+        PANAMA_OSD_BRIGHTNESS_HELPER="$scratch/bin/panama-brightness" \
+        PANAMA_OSD_RUNTIME_DIR="$runtime" \
+        OSD_DDC_STATE="$runtime/ddc-state" \
+        OSD_DDC_PROBE="$runtime/ddc-probe" \
+        BACKLIGHT_AVAILABLE="${BACKLIGHT_AVAILABLE:-true}" \
+        DDC_LIST_JSON="${DDC_LIST_JSON:-}" \
+        DDC_GET_VALUE="${DDC_GET_VALUE:-40}" \
+        DDC_FAIL_GET_BUS="${DDC_FAIL_GET_BUS:-}" \
+        DDC_SET_DELAY="${DDC_SET_DELAY:-}" \
+        FOCUSED_MONITOR="${FOCUSED_MONITOR:-DP-2}" \
         "$helper" "$@"
 }
 
@@ -86,9 +150,102 @@ assert_line 'qs <ipc> <call> <osd> <progress> <microphone-muted> <72> <100> <Mut
 
 : >"$log"
 run_helper brightness up 5
-assert_line 'brightnessctl <-e4> <-n2> <set> <5%+>'
 assert_line 'brightnessctl <-m> <-c> <backlight>'
+assert_line 'brightnessctl <-e4> <-n2> <-c> <backlight> <set> <5%+>'
 assert_line 'qs <ipc> <call> <osd> <progress> <brightness> <50> <100> <50%>'
+if grep -Fq 'panama-brightness' "$log"; then
+    printf 'osd helper contract: DDC fallback ran despite a native backlight\n' >&2
+    exit 1
+fi
+
+: >"$log"
+OSD_RUNTIME_DIR="$scratch/runtime-ddc" \
+BACKLIGHT_AVAILABLE=false \
+DDC_LIST_JSON='{"displays":[{"bus":3,"connector":"HDMI-A-1","value":35},{"bus":5,"connector":"DP-2","value":40}],"error":""}' \
+run_helper brightness up 5
+assert_line 'hyprctl <-j> <monitors>'
+assert_line 'panama-brightness <list>'
+assert_line 'panama-brightness <get> <5>'
+assert_line 'panama-brightness <set> <5> <45>'
+assert_line 'qs <ipc> <call> <osd> <progress> <brightness> <45> <100> <45%>'
+
+# A cached bus avoids the expensive display scan on subsequent key presses.
+: >"$log"
+OSD_RUNTIME_DIR="$scratch/runtime-ddc" \
+BACKLIGHT_AVAILABLE=false \
+DDC_LIST_JSON='{"displays":[{"bus":3,"connector":"HDMI-A-1","value":35},{"bus":5,"connector":"DP-2","value":45}],"error":""}' \
+run_helper brightness down 5
+assert_line 'panama-brightness <get> <5>'
+assert_line 'panama-brightness <set> <5> <40>'
+assert_line 'qs <ipc> <call> <osd> <progress> <brightness> <40> <100> <40%>'
+if grep -Fq 'panama-brightness <list>' "$log"; then
+    printf 'osd helper contract: cached DDC bus triggered another display scan\n' >&2
+    exit 1
+fi
+
+# A disconnected cached monitor is discarded and rediscovered once.
+mkdir -p "$scratch/runtime-ddc-stale"
+printf '9\tDP-9\n' >"$scratch/runtime-ddc-stale/brightness-bus"
+: >"$log"
+OSD_RUNTIME_DIR="$scratch/runtime-ddc-stale" \
+BACKLIGHT_AVAILABLE=false \
+DDC_FAIL_GET_BUS=9 \
+DDC_LIST_JSON='{"displays":[{"bus":5,"connector":"DP-2","value":40}],"error":""}' \
+run_helper brightness up 5
+assert_line 'panama-brightness <get> <9>'
+assert_line 'panama-brightness <list>'
+assert_line 'panama-brightness <get> <5>'
+assert_line 'panama-brightness <set> <5> <45>'
+
+# If the focused output is not DDC-capable, use the first discovered display.
+: >"$log"
+OSD_RUNTIME_DIR="$scratch/runtime-ddc-first" \
+BACKLIGHT_AVAILABLE=false \
+FOCUSED_MONITOR='eDP-1' \
+DDC_GET_VALUE=35 \
+DDC_LIST_JSON='{"displays":[{"bus":3,"connector":"HDMI-A-1","value":35},{"bus":5,"connector":"DP-2","value":40}],"error":""}' \
+run_helper brightness down 10
+assert_line 'panama-brightness <get> <3>'
+assert_line 'panama-brightness <set> <3> <25>'
+assert_line 'qs <ipc> <call> <osd> <progress> <brightness> <25> <100> <25%>'
+
+# Permission and discovery errors must be visible, never masquerade as 0%.
+: >"$log"
+OSD_RUNTIME_DIR="$scratch/runtime-ddc-error" \
+BACKLIGHT_AVAILABLE=false \
+DDC_LIST_JSON='{"displays":[],"error":"Run sudo udevadm control --reload-rules && sudo udevadm trigger --subsystem-match=i2c-dev --subsystem-match=drm"}' \
+run_helper brightness up 5
+assert_line 'qs <ipc> <call> <osd> <message> <dialog-warning-symbolic> <Brightness needs permission>'
+assert_line 'notify-send <--app-name=Panama> <--icon=display-brightness-symbolic> <Brightness unavailable> <Run sudo udevadm control --reload-rules && sudo udevadm trigger --subsystem-match=i2c-dev --subsystem-match=drm>'
+if grep -Fq 'osd> <progress> <brightness>' "$log"; then
+    printf 'osd helper contract: unavailable brightness rendered a false percentage\n' >&2
+    exit 1
+fi
+
+# Separate key-repeat processes must not overlap their DDC transactions.
+: >"$log"
+OSD_RUNTIME_DIR="$scratch/runtime-ddc-lock" \
+BACKLIGHT_AVAILABLE=false \
+DDC_SET_DELAY=0.15 \
+DDC_LIST_JSON='{"displays":[{"bus":5,"connector":"DP-2","value":40}],"error":""}' \
+run_helper brightness up 5 &
+first_pid=$!
+OSD_RUNTIME_DIR="$scratch/runtime-ddc-lock" \
+BACKLIGHT_AVAILABLE=false \
+DDC_SET_DELAY=0.15 \
+DDC_LIST_JSON='{"displays":[{"bus":5,"connector":"DP-2","value":40}],"error":""}' \
+run_helper brightness up 5 &
+second_pid=$!
+wait "$first_pid"
+wait "$second_pid"
+if grep -Fqx 'ddc-overlap' "$log"; then
+    printf 'osd helper contract: concurrent DDC transactions overlapped\n' >&2
+    exit 1
+fi
+if [[ $(<"$scratch/runtime-ddc-lock/ddc-state") != 50 ]]; then
+    printf 'osd helper contract: serialized key repeats did not both apply\n' >&2
+    exit 1
+fi
 
 : >"$log"
 run_helper media next