Checkpoint: preserve all uncommitted rust-rewrite worktree work

Safety commit before reconciling this worktree with main, which has
diverged with its own separate fixes today. Nothing here is reviewed
or curated yet - this exists purely so none of this work can be lost
to a git operation, disk issue, or worktree cleanup while that
reconciliation happens.

83 files changed, 12335 insertions, 3194 deletions

diff --git a/Cargo.lock b/Cargo.lock
index 4305b11..ce2155d 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2115,6 +2115,7 @@ dependencies = [
 name = "srd-cli"
 version = "0.1.0"
 dependencies = [
+ "libc",
  "srdwm-platform",
 ]
 
diff --git a/config/srd/init.lua b/config/srd/init.lua
index 5ac8a6b..2a79109 100644
--- a/config/srd/init.lua
+++ b/config/srd/init.lua
@@ -15,7 +15,9 @@ srd.load("startup")
 srd.set("general.default_layout", "dynamic")
 srd.set("general.smart_placement", true)
 srd.set("general.window_gap", 8)
-srd.set("general.border_width", 2)
+- Border width lives under theme.decorations.border.width (see themes.lua),
+- not here - see docs/DEFAULTS.md for why general.border_width never
+- existed as a real setting.
 srd.set("general.animations", true)
 srd.set("general.animation_duration", 200)
 
diff --git a/config/srd/themes.lua b/config/srd/themes.lua
index 4233b46..cf35b47 100644
--- a/config/srd/themes.lua
+++ b/config/srd/themes.lua
@@ -1,27 +1,152 @@
-- Nord-inspired theme (matches the built-in defaults; edit freely).
+- Theme presets for srdwm. Pick one by leaving its `apply(...)` call
+- uncommented at the bottom and commenting out the others - exactly one
+- should be active. Copying a whole preset table, editing values, and
+- pointing the bottom call at the copy works too; nothing here is special
+- beyond being a plain Lua table passed to srd.theme.set_colors/
+- set_decorations.
+--
+- `border.inactive_dim` is a factor applied to `active_color` for the
+- unfocused-window border, not a second explicit colour - 0.0 fades it to
+- black, 1.0 makes it identical to focused. See docs/DEFAULTS.md.
+--
+- `border.width = 4`, not a thinner value: srdwm rounds the border's own
+- corner via a CPU-rasterised bitmap, not a real-resolution GPU shader, so
+- a 2px-thick strip only has 2 rows to draw a curve into - not enough to
+- read as curved at all, just a slightly-softened square. 4px is the
+-- minimum found actually visible as a real curve; go lower and the corner
+- starts looking square again regardless of `radius`.
+--
+- `title_bar.height` below is *not* the real titlebar band - that's
+- `srdwm_core::TITLEBAR_HEIGHT` (currently `32`), a compile-time constant
+- shared between hit-testing and rendering so the two can never disagree.
+- Kept here at the same value purely so this file doesn't read as
+- disagreeing with the real height; changing it has no effect.
+--
+- `title_bar.button_style` - "traffic_lights" (default: filled, coloured
+- macOS-style dots, zoom-arrow maximize) or "traditional" (plain glyphs
+- straight on the titlebar background, no fill except a neutral hover
+- backdrop, square maximize) - see `ThemeConfig::traffic_light_buttons`'s
+- own doc comment. Independent of `button_side`: either style can sit on
+- either side, though `traffic_lights` + left and `traditional` + right
+- are this file's own two ready-made combinations below, matching macOS
+- and Windows/GNOME convention respectively.
+
 local srd = require("srd")
 
-srd.theme.set_colors({
-    background = "#2e3440",
-    foreground = "#eceff4",
-    primary = "#88c0d0",
-    secondary = "#81a1c1",
-    accent = "#5e81ac",
-    error = "#bf616a",
-    warning = "#ebcb8b",
-    success = "#a3be8c",
-})
+local function apply(preset)
+    srd.theme.set_colors(preset.colors)
+    srd.theme.set_decorations(preset.decorations)
+end
 
-srd.theme.set_decorations({
-    border = {
-        width = 2,
-        active_color = "#88c0d0",
-        inactive_color = "#4c566a",
-    },
-    title_bar = {
-        height = 30,
-        show = true,
+- ---------------------------------------------------------------------
+- Nord (dark) - srdwm's own compiled-in defaults (`ThemeConfig::
+- default`), written out explicitly so the preset is visible and
+- editable rather than left implicit.
+- ---------------------------------------------------------------------
+local nord = {
+    colors = {
         background = "#2e3440",
         foreground = "#eceff4",
+        primary = "#88c0d0",
+        secondary = "#81a1c1",
+        accent = "#5e81ac",
+        error = "#bf616a",
+        warning = "#ebcb8b",
+        success = "#a3be8c",
+    },
+    decorations = {
+        border = {
+            width = 4,
+            radius = 12,
+            active_color = "#88c0d0",
+            inactive_dim = 0.35,
+        },
+        title_bar = {
+            height = 32,
+            show = true,
+            background = "#2e3440",
+            foreground_focused = "#88c0d0",
+            foreground_unfocused = "#4c566a",
+            text_align = "left",
+            button_side = "right",
+            button_glyph = "hover",
+        },
+    },
+}
+
+- ---------------------------------------------------------------------
+- macOS - centered title, left-aligned traffic-light buttons (real
+- macOS convention, not this system's own GTK button-layout convention --
+- see `title_bar.button_side`'s own doc comment in `crates/core/src/
+- theme.rs` if picking a different button order/side). Grey titlebar
+- background matches a real GTK dark theme's own CSD row (measured live
+- off a real WhiteSur-Dark screenshot, (44,44,44)) rather than fighting
+- it with an accent colour, so srdwm's own decorated windows read as the
+- same family of chrome as Firefox/Nemo/every other GTK app's CSD, not a
+- visibly different one sitting right next to them.
+--
+- For the *system* half of a full macOS look (which side Firefox/GTK
+- apps' own CSD buttons draw on, real traffic-light gradients on GTK
+- apps' own dots) see docs/DEFAULTS.md's "macOS look" section - that
+- part is outside srdwm entirely (a `gsettings` value plus a userChrome.
+- css/gtk.css of your own), so it isn't and can't be shipped from here.
+- ---------------------------------------------------------------------
+local macos = {
+    colors = {
+        background = "#1e1e1e",
+        foreground = "#f5f5f5",
+        primary = "#0a84ff",
+        secondary = "#5e5ce6",
+        accent = "#64d2ff",
+        error = "#ff453a",
+        warning = "#ffd60a",
+        success = "#32d74b",
     },
-})
+    decorations = {
+        border = {
+            width = 4,
+            radius = 12,
+            active_color = "#0a84ff",
+            inactive_dim = 0.35,
+        },
+        title_bar = {
+            height = 32,
+            show = true,
+            background = "#2c2c2c",
+            foreground_focused = "#f5f5f5",
+            foreground_unfocused = "#9a9a9a",
+            text_align = "center",
+            button_side = "left",
+            button_glyph = "hover",
+        },
+    },
+}
+
+- ---------------------------------------------------------------------
+- Traditional - plain glyphs, right-aligned, no traffic lights: this
+- project's own original look and the real Windows/GNOME convention, as
+- distinct from `macos` above. Otherwise identical to `nord`; only
+- `button_style` differs.
+- ---------------------------------------------------------------------
+local traditional = {
+    colors = nord.colors,
+    decorations = {
+        border = nord.decorations.border,
+        title_bar = {
+            height = 32,
+            show = true,
+            background = "#2e3440",
+            foreground_focused = "#88c0d0",
+            foreground_unfocused = "#4c566a",
+            text_align = "left",
+            button_side = "right",
+            button_glyph = "hover",
+            button_style = "traditional",
+        },
+    },
+}
+
+- Pick exactly one. Comment out the other two.
+apply(nord)
+- apply(macos)
+- apply(traditional)
diff --git a/crates/config/src/engine/general.rs b/crates/config/src/engine/general.rs
index 98cfebe..94b029b 100644
--- a/crates/config/src/engine/general.rs
+++ b/crates/config/src/engine/general.rs
@@ -194,6 +194,41 @@ impl Engine {
         })?)
     }
 
+    /// `srd.monitor.split(name, parts[, direction])` - divides connector
+    /// `name`'s real output into `parts` equal logical monitors for
+    /// placement/tiling purposes ("monitors inside monitors"), no new
+    /// `wl_output` involved - see `srdwm_core::monitor::MonitorSplit`'s
+    /// own doc comment for exactly what that does and doesn't give a
+    /// client. `direction` is `"columns"` (default, side-by-side) or
+    /// `"rows"` (stacked); any other value is treated as `"columns"`
+    /// rather than erroring, same "malformed value falls back to a
+    /// sensible default" stance other config setters already take.
+    /// `parts <= 1` clears an existing split for `name`.
+    pub(super) fn fn_monitor_split(&self) -> Result<mlua::Function<'_>> {
+        let state = self.state.clone();
+        Ok(self.lua.create_function(move |_, (name, parts, direction): (String, u32, Option<String>)| {
+            let rows = matches!(direction.as_deref(), Some("rows"));
+            state.borrow().wm.borrow_mut().set_monitor_split(name, parts, rows);
+            Ok(())
+        })?)
+    }
+
+    /// `srd.monitor.scale(name, factor)` - sets connector `name`'s
+    /// output scale, applied the next time a backend brings that head up
+    /// (startup, hotplug, or re-enable). A physically large monitor with
+    /// the same pixel count as a smaller one (a big low-DPI external
+    /// display next to a small high-DPI laptop panel, say) can run below
+    /// `1.0` to show more logical desktop space rather than just larger
+    /// text at the same resolution. `factor <= 0` clears an existing
+    /// override.
+    pub(super) fn fn_monitor_scale(&self) -> Result<mlua::Function<'_>> {
+        let state = self.state.clone();
+        Ok(self.lua.create_function(move |_, (name, factor): (String, f64)| {
+            state.borrow().wm.borrow_mut().set_monitor_scale(name, factor);
+            Ok(())
+        })?)
+    }
+
     pub(super) fn fn_load(&self) -> Result<mlua::Function<'_>> {
         let state = self.state.clone();
         Ok(self.lua.create_function(move |lua, module: String| {
diff --git a/crates/config/src/engine/register.rs b/crates/config/src/engine/register.rs
index 0cf64bc..4ef6844 100644
--- a/crates/config/src/engine/register.rs
+++ b/crates/config/src/engine/register.rs
@@ -75,6 +75,11 @@ impl Engine {
         workspace.set("move_window", self.fn_workspace_move_window()?)?;
         srd.set("workspace", workspace)?;
 
+        let monitor = lua.create_table()?;
+        monitor.set("split", self.fn_monitor_split()?)?;
+        monitor.set("scale", self.fn_monitor_scale()?)?;
+        srd.set("monitor", monitor)?;
+
         let theme = lua.create_table()?;
         theme.set("set_colors", self.fn_theme_set("theme.colors")?)?;
         theme.set("set_decorations", self.fn_theme_set("theme.decorations")?)?;
diff --git a/crates/config/src/engine/support.rs b/crates/config/src/engine/support.rs
index 0f83885..b67a688 100644
--- a/crates/config/src/engine/support.rs
+++ b/crates/config/src/engine/support.rs
@@ -80,13 +80,13 @@ pub(super) fn validate(s: &SharedState) -> Vec<String> {
     check_range("layout.dynamic.gaps.outer", 0.0, 100.0);
     check_range("layout.floating.gaps.inner", 0.0, 100.0);
     check_range("layout.floating.gaps.outer", 0.0, 100.0);
-    check_range("general.border_width", 0.0, 20.0);
     check_range("theme.decorations.border.width", 0.0, 20.0);
     check_range("theme.decorations.border.radius", 0.0, 100.0);
     check_range("general.animation_duration", 0.0, 1000.0);
     check_range("general.resize_margin", 1.0, 50.0);
     check_range("performance.max_fps", 30.0, 240.0);
     check_range("performance.window_cache_size", 10.0, 10000.0);
+    check_range("theme.decorations.border.inactive_dim", 0.0, 1.0);
 
     let layouts: Vec<String> = s.wm.borrow().available_layouts().iter().map(|l| l.to_string()).collect();
     for key in ["general.default_layout", "monitor.primary_layout", "monitor.secondary_layout"] {
@@ -110,6 +110,8 @@ pub(super) fn validate(s: &SharedState) -> Vec<String> {
         "theme.decorations.border.inactive_color",
         "theme.decorations.title_bar.background",
         "theme.decorations.title_bar.foreground",
+        "theme.decorations.title_bar.foreground_focused",
+        "theme.decorations.title_bar.foreground_unfocused",
     ];
     for key in color_keys {
         if let Some(v) = s.values.get(key).and_then(ConfigValue::as_str) {
@@ -138,7 +140,6 @@ pub(super) fn default_config() -> HashMap<String, ConfigValue> {
     set("general.default_layout", String("dynamic".into()));
     set("general.smart_placement", Bool(true));
     set("general.window_gap", Number(8.0));
-    set("general.border_width", Number(2.0));
     set("general.animations", Bool(true));
     set("general.animation_duration", Number(200.0));
     set("general.shadows", Bool(true));
@@ -163,12 +164,11 @@ pub(super) fn default_config() -> HashMap<String, ConfigValue> {
     set("monitor.primary_layout", String("dynamic".into()));
     set("monitor.secondary_layout", String("tiling".into()));
     set("monitor.auto_detect", Bool(true));
-    // Deliberately *not* seeded, unlike everything else here: srdwm has one
-    // flat workspace list shared by every monitor (see WindowManager's
-    // `current_workspace` doc comment), not Hyprland-style independent
-    // per-monitor workspace sets - "this monitor's primary workspace" and
-    // "this monitor's workspace count" describe a design that doesn't
-    // exist. `workspace.count` is the one knob that actually does anything.
+    // "This monitor's workspace *count*" specifically is still deliberately
+    // not seeded/implemented - `workspace.count` is one flat number for
+    // the whole desktop, not per-monitor. Independent per-monitor
+    // workspace *sets* (which workspace each monitor is showing) is a
+    // different, now-real knob: see `workspace.per_monitor` below.
 
     // The `window.*` namespace this codebase's own `docs/DEFAULTS.md`
     // documented (focus_follows_mouse/mouse_follows_focus/auto_raise/
@@ -190,6 +190,13 @@ pub(super) fn default_config() -> HashMap<String, ConfigValue> {
     // absence from this function, though that one differs by backend
     // rather than being simply unbuilt.
     set("workspace.auto_back_and_forth", Bool(false));
+    // `false`: srdwm's original single-shared-workspace design (switching
+    // workspace changes what's visible on every monitor at once) - `true`
+    // switches to Hyprland/niri-style independent per-monitor workspace
+    // sets, each monitor tracking and displaying its own current
+    // workspace. See `WindowManager::per_monitor_workspaces`'s own doc
+    // comment.
+    set("workspace.per_monitor", Bool(false));
 
     set("performance.vsync", Bool(true));
     set("performance.max_fps", Number(60.0));
@@ -246,6 +253,11 @@ pub(super) fn default_config() -> HashMap<String, ConfigValue> {
     set("theme.decorations.border.radius", Number(6.0));
     set("theme.decorations.border.active_color", String("#88c0d0".into()));
     set("theme.decorations.border.inactive_color", String("#2e3440".into()));
+    // The actually-wired unfocused-border knob (`apply_general_settings`,
+    // `srdwm_core::ThemeConfig::border_inactive_dim`): a factor applied to
+    // `border.active_color`, not the unused absolute `inactive_color`
+    // above. `1.0` matches focused exactly; `0.0` fades to black.
+    set("theme.decorations.border.inactive_dim", Number(0.35));
     set("theme.decorations.border.focused_style", String("solid".into()));
     set("theme.decorations.border.unfocused_style", String("solid".into()));
     set("theme.decorations.title_bar.height", Number(24.0));
@@ -253,6 +265,11 @@ pub(super) fn default_config() -> HashMap<String, ConfigValue> {
     set("theme.decorations.title_bar.font", String("JetBrains Mono 10".into()));
     set("theme.decorations.title_bar.background", String("#2e3440".into()));
     set("theme.decorations.title_bar.foreground", String("#eceff4".into()));
+    // The actually-wired pair (`apply_general_settings`): titlebar text has
+    // always used two colours - brighter on the focused window, dimmer on
+    // every other one - never the single `foreground` key above.
+    set("theme.decorations.title_bar.foreground_focused", String("#88c0d0".into()));
+    set("theme.decorations.title_bar.foreground_unfocused", String("#4c566a".into()));
 
     set("platform.backend", String("auto".into()));
     set("platform.x11.use_ewmh", Bool(true));
diff --git a/crates/config/src/engine/tests.rs b/crates/config/src/engine/tests.rs
index 521dc5a..f170320 100644
--- a/crates/config/src/engine/tests.rs
+++ b/crates/config/src/engine/tests.rs
@@ -197,6 +197,58 @@
     }
 
     #[test]
+    fn srd_monitor_split_stores_a_split_request_by_connector_name() {
+        let dir = tempfile::tempdir().unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+        let engine = Engine::new(wm.clone(), dir.path()).unwrap();
+        engine.lua.load(r#"srd.monitor.split("eDP-1", 2, "rows")"#).exec().unwrap();
+        let split = wm.borrow().monitor_split("eDP-1").unwrap();
+        assert_eq!(split.parts, 2);
+        assert!(split.rows);
+    }
+
+    #[test]
+    fn srd_monitor_split_direction_defaults_to_columns() {
+        let dir = tempfile::tempdir().unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+        let engine = Engine::new(wm.clone(), dir.path()).unwrap();
+        engine.lua.load(r#"srd.monitor.split("HDMI-A-1", 3)"#).exec().unwrap();
+        let split = wm.borrow().monitor_split("HDMI-A-1").unwrap();
+        assert_eq!(split.parts, 3);
+        assert!(!split.rows);
+    }
+
+    #[test]
+    fn srd_monitor_scale_stores_a_factor_by_connector_name() {
+        let dir = tempfile::tempdir().unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+        let engine = Engine::new(wm.clone(), dir.path()).unwrap();
+        engine.lua.load(r#"srd.monitor.scale("HDMI-A-1", 0.75)"#).exec().unwrap();
+        assert_eq!(wm.borrow().monitor_scale("HDMI-A-1"), Some(0.75));
+    }
+
+    #[test]
+    fn srd_monitor_scale_with_a_non_positive_factor_clears_it() {
+        let dir = tempfile::tempdir().unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+        let engine = Engine::new(wm.clone(), dir.path()).unwrap();
+        engine.lua.load(r#"srd.monitor.scale("HDMI-A-1", 0.75)"#).exec().unwrap();
+        engine.lua.load(r#"srd.monitor.scale("HDMI-A-1", 0)"#).exec().unwrap();
+        assert_eq!(wm.borrow().monitor_scale("HDMI-A-1"), None);
+    }
+
+    #[test]
+    fn srd_monitor_split_with_one_part_clears_an_existing_split() {
+        let dir = tempfile::tempdir().unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+        let engine = Engine::new(wm.clone(), dir.path()).unwrap();
+        engine.lua.load(r#"srd.monitor.split("eDP-1", 2)"#).exec().unwrap();
+        assert!(wm.borrow().monitor_split("eDP-1").is_some());
+        engine.lua.load(r#"srd.monitor.split("eDP-1", 1)"#).exec().unwrap();
+        assert!(wm.borrow().monitor_split("eDP-1").is_none());
+    }
+
+    #[test]
     fn srd_window_scratchpad_hides_the_focused_window_and_show_brings_it_back() {
         let dir = tempfile::tempdir().unwrap();
         let wm = Rc::new(RefCell::new(WindowManager::new()));
diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs
index 56f8779..7905504 100644
--- a/crates/core/src/lib.rs
+++ b/crates/core/src/lib.rs
@@ -15,11 +15,14 @@ pub use event::{canonicalize_key_combo, key_combo_string, parse_key_combo, Event
 pub use geometry::Rect;
 pub use layout::{Layout, MasterStackLayout, NoOpLayout, TilingConfig};
 pub use lock_config::LockConfig;
-pub use manager::{CaptureRequest, Direction, WindowManager};
+pub use manager::{CaptureRequest, ColorFilter, Direction, WindowManager};
 pub use monitor::{Monitor, MonitorId};
 pub use placement::{PlacementConfig, SmartPlacement, SnapZoneKind};
 pub use regex::Regex;
 pub use rules::{WindowMatch, WindowRule, WindowRuleActions};
 pub use theme::{parse_hex_color, ThemeConfig};
-pub use window::{classify_menu_source, GlobalMenu, MenuSource, ResizeEdge, TitlebarHit, Window, WindowId, RESIZE_MARGIN, TITLEBAR_HEIGHT};
+pub use window::{
+    classify_menu_source, parse_button_order, ButtonOrder, GlobalMenu, MenuSource, ResizeEdge, TitlebarButton, TitlebarHit, Window, WindowId,
+    BUTTON_CLUSTER_MARGIN, BUTTON_PITCH, RESIZE_MARGIN, TITLEBAR_HEIGHT,
+};
 pub use workspace::{Workspace, WorkspaceId};
diff --git a/crates/core/src/manager/dragresize.rs b/crates/core/src/manager/dragresize.rs
index 06a6db9..b3132a5 100644
--- a/crates/core/src/manager/dragresize.rs
+++ b/crates/core/src/manager/dragresize.rs
@@ -28,7 +28,16 @@ impl WindowManager {
         // maximize avoid it. Clamping a drag to the shrunk usable area
         // made it physically impossible to ever drag a window past a
         // dock, at any speed or angle.
-        let monitor_bounds = self.windows.get(&drag.window).and_then(|w| self.monitor_for(w.monitor)).map(|m| m.full_geometry);
+        //
+        // `all_monitors_bounds`, not `monitor_for(w.monitor)` (the window's
+        // own *starting* monitor, looked up once and never updated as the
+        // drag moves) - see that function's own doc comment for the real
+        // multi-monitor bug this fixes: the old single-monitor clamp made
+        // it mathematically impossible to ever drag a window from one
+        // monitor onto another, confirmed live with two real monitors
+        // connected, one of them otherwise fully working at the
+        // compositor/DRM level.
+        let monitor_bounds = self.all_monitors_bounds();
         if let Some(bounds) = monitor_bounds {
             new_geom.x = new_geom.x.clamp(bounds.x - new_geom.width as i32 + 40, bounds.right() - 40);
             new_geom.y = new_geom.y.clamp(bounds.y, bounds.bottom() - 40);
@@ -43,6 +52,25 @@ impl WindowManager {
     /// near a monitor edge.
     pub fn end_drag(&mut self) {
         if let Some(drag) = self.drag.take() {
+            // `w.monitor` only ever gets set at window creation (or by
+            // `set_monitors`, reactively, on the *next* hotplug) - a drag
+            // that crossed onto a different monitor leaves it stale
+            // pointing at wherever the window *started*, same gap
+            // `set_monitors`'s own doc comment already documents for the
+            // hotplug-rehoming case. Corrected here, before computing the
+            // snap zone below, not after - using the stale value there
+            // would check the *wrong* monitor's snap zones (e.g. still
+            // snapping against monitor 1's left edge for a window that's
+            // now actually sitting near monitor 2's), the same bug this is
+            // fixing for maximize/fullscreen one level up.
+            if let Some(w) = self.windows.get(&drag.window) {
+                if let Some(now_on) = self.monitors.iter().find(|m| m.geometry.overlaps(&w.geometry)) {
+                    let now_on_id = now_on.id;
+                    if let Some(w) = self.windows.get_mut(&drag.window) {
+                        w.monitor = now_on_id;
+                    }
+                }
+            }
             let snapped = self.windows.get(&drag.window).and_then(|w| {
                 self.monitor_for(w.monitor).and_then(|m| SmartPlacement::snap_zone(w.geometry, m, &self.placement))
             });
@@ -73,6 +101,20 @@ impl WindowManager {
     }
 
     pub fn end_resize(&mut self) {
+        // Remembers this app's new size for its *next* window - see
+        // `remembered_sizes`' own doc comment for why this is the one
+        // resize-ending path that updates it (not maximize/fullscreen, not
+        // a drag-to-edge snap). Keyed by `app_id`, so a window that never
+        // got one (a backend/client that hasn't reported it yet) simply
+        // isn't remembered - no worse than today, and consistent with how
+        // window rules already treat an empty `app_id` as unmatchable.
+        if let Some(r) = &self.resize {
+            if let Some(w) = self.windows.get(&r.window) {
+                if !w.app_id.is_empty() {
+                    self.remembered_sizes.insert(w.app_id.clone(), (w.geometry.width, w.geometry.height));
+                }
+            }
+        }
         self.resize = None;
     }
 
@@ -80,6 +122,16 @@ impl WindowManager {
         self.resize.is_some()
     }
 
+    /// Which window is currently being interactively resized, if any - so
+    /// a backend can skip an expensive-but-cosmetic per-window effect
+    /// (content corner-masking, concretely - see its own call site's
+    /// comment) for just that one window while its content is reflowing
+    /// on every single frame, without touching every *other* window's own
+    /// masking.
+    pub fn resizing_window(&self) -> Option<WindowId> {
+        self.resize.as_ref().map(|r| r.window)
+    }
+
     /// The edge currently being dragged, if a resize is in progress - so a
     /// backend can keep showing the matching resize cursor for the whole
     /// drag, not just while the pointer happens to still be hovering that
diff --git a/crates/core/src/manager/hittest.rs b/crates/core/src/manager/hittest.rs
index 06ac659..ab19a5c 100644
--- a/crates/core/src/manager/hittest.rs
+++ b/crates/core/src/manager/hittest.rs
@@ -20,14 +20,65 @@ impl WindowManager {
     /// happened to occupy the same screen coordinates sent the click to the
     /// invisible one.
     pub fn hit_test(&self, x: i32, y: i32) -> Option<(WindowId, TitlebarHit)> {
+        self.hit_test_with(x, y, |_, geometry| geometry)
+    }
+
+    /// Same as [`Self::hit_test`], but lets the caller substitute a
+    /// different rect than `w.geometry` for whichever window is being
+    /// tested - `geometry_for(id, w.geometry)` is called once per window in
+    /// the same topmost-first order, and its return value is what actually
+    /// gets tested instead of `w.geometry` directly.
+    ///
+    /// This exists for exactly one reason: a backend that animates window
+    /// geometry (currently only the Wayland one, via `window_anims` in
+    /// `CompState`) draws the border/titlebar at the *interpolated* rect
+    /// every frame (`WindowAnim::current_rect`), but `w.geometry` here is
+    /// always the animation's *target* - core has no concept of animation
+    /// at all, deliberately (`Window.geometry` is meant to be the single
+    /// source of truth every other subsystem reads). Calling plain
+    /// `hit_test` during an active animation (toggling maximize/fullscreen,
+    /// a Snap-Layouts zone, or a new window's open-slide - see
+    /// `WindowManager::toggle_maximize`/`apply_snap_zone`/
+    /// `toggle_fullscreen` for where `anim_from` gets set) meant the
+    /// decoration/resize-margin hit-test used the window's *final* position
+    /// while the border was still visibly animating toward it - reported
+    /// live as "the border isn't always truly on the edge of the window",
+    /// i.e. hovering what you can see as the edge doesn't match what's
+    /// actually clickable there for as long as `animation_duration_ms`
+    /// (200ms by default) hasn't elapsed since the last toggle/snap/open.
+    /// Content clicks never had this problem - `space.map_element` already
+    /// maps the client's surface at the same interpolated rect the border
+    /// draws at (`state/geometry.rs::sync_geometry`), so `space.element_
+    /// under` and the border were already agreeing with each other; only
+    /// this compositor's own decoration hit-test was reading a different
+    /// number than what it was drawing on screen.
+    pub fn hit_test_with(&self, x: i32, y: i32, geometry_for: impl Fn(WindowId, Rect) -> Rect) -> Option<(WindowId, TitlebarHit)> {
         for w in self.order.iter().rev().filter_map(|id| self.windows.get(id)) {
             if w.minimized || w.workspace != self.current_workspace {
                 continue;
             }
             let margin = w.resize_margin.unwrap_or(self.resize_margin);
-            if let Some(hit) = ResizeEdge::hit_test(w.geometry, x, y, w.decorated, w.border_width, margin) {
+            let geometry = geometry_for(w.id, w.geometry);
+            if let Some(hit) = ResizeEdge::hit_test(geometry, x, y, w.decorated, w.border_width, margin, self.theme.buttons_left, self.theme.button_order, w.is_dialog) {
                 return Some((w.id, hit));
             }
+            // Not a titlebar/border/resize-margin hit on `w` - but if the
+            // point still falls inside `w`'s own plain content rect, `w`'s
+            // real, opaque content is what's actually drawn there (this is
+            // topmost-first order, so nothing checked so far is above it),
+            // and continuing the loop into a *lower* window's own border/
+            // resize zone at this same point would return a hit for
+            // something the user cannot see or reach - `w`'s content is
+            // in the way regardless of whether `w` itself claimed the
+            // point as one of its own edges. Reported live as being able
+            // to grab a resize edge, or trigger a titlebar-adjacent action,
+            // on a window fully covered by another one on top of it.
+            // Content clicks (the content-hit branch in `input.rs`) are
+            // unaffected - they already resolve via `Space::element_under`,
+            // smithay's own real Z-order, which never had this gap.
+            if geometry.contains_point(x, y) {
+                return None;
+            }
         }
         None
     }
diff --git a/crates/core/src/manager/mod.rs b/crates/core/src/manager/mod.rs
index 38e0bbb..74be06b 100644
--- a/crates/core/src/manager/mod.rs
+++ b/crates/core/src/manager/mod.rs
@@ -1,11 +1,11 @@
 use crate::geometry::Rect;
 use crate::layout::{Layout, MasterStackLayout, NoOpLayout, TilingConfig};
-use crate::monitor::{Monitor, MonitorId};
+use crate::monitor::{DisabledMonitor, Monitor, MonitorId, MonitorSplit};
 use crate::placement::{PlacementConfig, SmartPlacement, SnapZoneKind, MIN_WINDOW_HEIGHT, MIN_WINDOW_WIDTH};
 use crate::rules::WindowRule;
 use crate::lock_config::LockConfig;
 use crate::theme::ThemeConfig;
-use crate::window::{ResizeEdge, TitlebarHit, Window, WindowId, RESIZE_MARGIN};
+use crate::window::{likely_draws_own_titlebar, ResizeEdge, TitlebarHit, Window, WindowId, RESIZE_MARGIN};
 use crate::workspace::{Workspace, WorkspaceId};
 use std::collections::HashMap;
 
@@ -17,6 +17,25 @@ pub enum Direction {
     Down,
 }
 
+/// A whole-screen colour treatment, drawn by each Wayland backend as a
+/// translucent full-output overlay above every window but below the
+/// cursor - see `srdwm_wayland::color_filter` for the actual overlay
+/// colour/alpha each variant maps to, and why an alpha-blended overlay
+/// rather than a true per-pixel shader was chosen at all.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum ColorFilter {
+    #[default]
+    None,
+    /// Warm tint, reduces perceived blue light. Ported from a Hyprland
+    /// `decoration:screen_shader` config that multiplied the framebuffer
+    /// by `vec3(1.0, 0.82, 0.60)`.
+    NightLight,
+    /// Desaturating tint, for reduced visual noise during long-form
+    /// reading. Ported from a Hyprland `decoration:screen_shader` config
+    /// that replaced every pixel with its own luminance (flat grayscale).
+    ReadingMode,
+}
+
 struct DragState {
     window: WindowId,
     start_x: i32,
@@ -55,6 +74,31 @@ pub struct WindowManager {
     /// backend's next monitor query, same as any other hotplug/reconfigure.
     output_position_requests: Vec<(MonitorId, i32, i32)>,
     /// Same cross-boundary-request pattern as `output_position_requests`
+    /// just above, for enable/disable - see `request_output_enabled`'s
+    /// own doc comment for why this is keyed by name, not `MonitorId`.
+    output_enable_requests: Vec<(String, bool)>,
+    /// The opposite direction of `output_enable_requests`: not a request
+    /// *to* the backend, but the backend *reporting* an administratively-
+    /// disabled-but-still-connected output's last-known state, purely for
+    /// listing purposes - see `set_disabled_monitor`'s own doc comment
+    /// for why this deliberately never touches `monitors`/real placement
+    /// at all.
+    disabled_monitors: HashMap<String, DisabledMonitor>,
+    /// `srd.monitor.split(name, parts, direction)` requests, by connector
+    /// name - read by a backend's own `monitors()` query to divide one
+    /// real output's rectangle into several logical `Monitor` entries. See
+    /// [`MonitorSplit`]'s own doc comment for what this deliberately does
+    /// and does not give a client (no new `wl_output`).
+    monitor_splits: HashMap<String, MonitorSplit>,
+    /// `srd.monitor.scale(name, factor)` requests, by connector name --
+    /// read once by a backend when it brings a head up (startup, hotplug,
+    /// or re-enable), so a physically large, low-DPI monitor can run
+    /// below `1.0` to show more logical desktop space instead of just
+    /// larger text at the same pixel count. srdwm otherwise always drove
+    /// every real output at a hardcoded `1.0`, with no way to change that
+    /// short of a client speaking wlr-output-management itself.
+    monitor_scales: HashMap<String, f64>,
+    /// Same cross-boundary-request pattern as `output_position_requests`
     /// just above - core has no way to actually blank the screen and
     /// start drawing srdwm's own lock UI itself (that's real compositor
     /// rendering, backend-owned), so an IPC `"lock"` dispatch queues the
@@ -68,11 +112,15 @@ pub struct WindowManager {
     /// screencopy protocol can see).
     capture_requests: Vec<capture::CaptureRequest>,
     workspaces: Vec<Workspace>,
-    /// One flat value shared by every monitor - not per-output. Unlike
-    /// Hyprland, srdwm has no notion of an independent workspace set per
-    /// monitor; switching workspace changes what's visible on every screen
-    /// at once. See `visible_windows`'s doc comment for the filter this
-    /// actually drives.
+    /// The shared-mode value, used directly when `per_monitor_workspaces`
+    /// is `false` (the default - unlike Hyprland, srdwm's original design
+    /// has no notion of an independent workspace set per monitor;
+    /// switching workspace changes what's visible on every screen at
+    /// once). Still meaningful even when `per_monitor_workspaces` is `true`
+    /// - it's the fallback `workspace_for_monitor` returns for a monitor
+    /// that has never had its own workspace switched independently yet,
+    /// and what a plain `current_workspace()` call reports either way. See
+    /// `visible_windows`'s doc comment for the filter this actually drives.
     current_workspace: WorkspaceId,
     /// Whichever workspace was current immediately before the current one
     /// became current - see `switch_workspace`'s doc comment.
@@ -82,6 +130,34 @@ pub struct WindowManager {
     /// instead - sway's `workspace_auto_back_and_forth` behavior, a quick
     /// "jump back to whatever I was just on" toggle on a single keybinding.
     pub auto_back_and_forth: bool,
+    /// Read from `workspace.per_monitor` - `false` (the default) keeps
+    /// srdwm's original single-shared-workspace design exactly as it was;
+    /// `true` switches to Hyprland/niri-style independent per-monitor
+    /// workspace sets, where each monitor tracks and displays its own
+    /// current workspace, switchable without affecting any other monitor.
+    /// Explicitly requested as a configurable choice, not a hardcoded
+    /// switch to one model or the other - see `workspace_for_monitor` and
+    /// `switch_workspace_on_monitor` for what this actually gates.
+    pub per_monitor_workspaces: bool,
+    /// Read from `monitor.primary_layout`/`monitor.secondary_layout` --
+    /// validated/defaulted config keys that were never read anywhere
+    /// before (same dead-config shape as `general.default_layout`'s own
+    /// siblings). Empty string means "not set, no override". Applied by
+    /// `set_monitors` to whichever workspace `workspace_for_monitor`
+    /// resolves for each connected monitor - which only ever *differs*
+    /// between monitors when `per_monitor_workspaces` is `true` (every
+    /// monitor shares one workspace otherwise, so a primary/secondary
+    /// split has nothing distinct to apply to and is skipped).
+    pub primary_layout: String,
+    pub secondary_layout: String,
+    /// Each monitor's own current workspace, when `per_monitor_workspaces`
+    /// is `true`. A monitor with no entry here yet (never had its
+    /// workspace switched independently - e.g. right after the mode was
+    /// turned on, or a newly connected monitor) falls back to
+    /// `current_workspace`, the same shared value shared-mode always uses
+    /// - see `workspace_for_monitor`. Unused, and left empty, whenever
+    /// `per_monitor_workspaces` is `false`.
+    monitor_workspaces: HashMap<MonitorId, WorkspaceId>,
     next_workspace_id: WorkspaceId,
     next_window_id: WindowId,
     layouts: HashMap<String, Box<dyn Layout>>,
@@ -113,6 +189,14 @@ pub struct WindowManager {
     /// redraws constantly - see `crates/wayland/src/rounded_corners.rs`).
     /// `Some(_)` only when the user explicitly set it, and wins either way.
     pub rounded_corners_enabled: Option<bool>,
+    /// The whole-screen colour treatment currently active (night light's
+    /// warm tint or reading mode's desaturation), live-settable via `srd
+    /// set night_light`/`srd set reading_mode` - see [`ColorFilter`]. Off
+    /// by default; the two are mutually exclusive by construction (one
+    /// enum, not two independent bools), matching the ported Hyprland
+    /// scripts this replaces, which pointed the same single
+    /// `screen_shader` slot at one file or the other.
+    pub color_filter: ColorFilter,
     /// Whether hovering a window (no click needed) focuses it, read from
     /// `general.focus_follows_mouse`. Off by default - matches
     /// `general.focus_follows_mouse`'s own documented default, and every
@@ -133,6 +217,23 @@ pub struct WindowManager {
     drag: Option<DragState>,
     resize: Option<ResizeState>,
     rules: Vec<WindowRule>,
+    /// Last floating size a user interactively resized each `app_id` to,
+    /// applied to that app's *next* new window instead of the fixed
+    /// 800x600 every backend otherwise hardcodes - see `end_resize` (where
+    /// this is recorded) and `add_window` (where it's read). Keyed by
+    /// `app_id` alone, not per-window: the ask is "my terminal should open
+    /// at the size I last used a terminal at", not per-window-instance
+    /// memory. Only an interactive drag-resize (`end_resize`) updates this
+    /// - not a maximize/fullscreen toggle (that's a separate, temporary
+    /// state with its own `restore_geometry`, not a new "size I want to
+    /// keep using") and not a drag-to-edge snap (a deliberate one-off
+    /// snap to a half/quarter of the screen isn't "the size I'll want my
+    /// next terminal to open at" either). Session-lifetime only, not
+    /// persisted to disk - a real per-app-size-memory feature that
+    /// survives a restart would need a config-file-backed store, which is
+    /// meaningfully more machinery than "remember it while running" asks
+    /// for.
+    remembered_sizes: HashMap<String, (u32, u32)>,
     /// Windows a client-close was requested for, drained once per tick by
     /// `main.rs`'s event loop and forwarded to `Platform::close`. Needed
     /// because `WindowManager` is platform-agnostic and has no way to send
@@ -155,6 +256,23 @@ pub struct WindowManager {
     /// `close_requests`, for the same reason: `WindowManager` has no real
     /// keyboard/seat handle of its own to cycle.
     keyboard_layout_cycle_requests: u32,
+    /// Which monitor the pointer is currently over, as last reported by
+    /// `set_pointer_monitor` - core has no pointer of its own (backend-
+    /// agnostic, same reason `close_requests` exists instead of a direct
+    /// client call), so a real backend's own pointer-motion handler is the
+    /// only thing that can ever know this. `add_window`'s own target-
+    /// monitor fallback chain reads it: a new window already preferred the
+    /// *focused* window's monitor over the primary one (see that fix's own
+    /// doc comment, `add_window`) - correct when something is focused on
+    /// the monitor the user is actually at, but not when nothing is (an
+    /// empty desktop there, or the last-focused window happens to sit on a
+    /// *different* monitor than the one the user is currently pointing at
+    /// while launching something new). Reported live: opening an
+    /// application while on a non-primary monitor with nothing focused
+    /// there still opened it on the primary one. `None` until the first
+    /// real pointer-motion event arrives (matches `focused`'s own `None`-
+    /// until-something-happens shape).
+    pointer_monitor: Option<MonitorId>,
 }
 
 impl Default for WindowManager {
@@ -176,13 +294,52 @@ impl WindowManager {
             focused: None,
             monitors: Vec::new(),
             output_position_requests: Vec::new(),
+            output_enable_requests: Vec::new(),
+            disabled_monitors: HashMap::new(),
+            monitor_splits: HashMap::new(),
+            monitor_scales: HashMap::new(),
             lock_requested: false,
             capture_requests: Vec::new(),
-            workspaces: vec![Workspace::new(0, "1", "dynamic")],
-            current_workspace: 0,
-            previous_workspace: 0,
+            // 1-based, not 0-based: workspace ids match the human-visible
+            // numbers (`workspace.names` defaults to "1".."9","0",
+            // `apply_workspace_count` names workspace `i+1` "i+1") - an id
+            // of `0` for the first workspace, with everything display-side
+            // calling it "1", was a standing off-by-one between what a user
+            // types/sees and the id `srd dispatch activate workspace <n>`
+            // (and AGS's workspace switcher, which sends the same number it
+            // shows) actually has to send. Matches how Hyprland's own
+            // workspace ids already work (natively 1-based, no translation
+            // layer needed) rather than niri's split id/idx or the
+            // 0-based-plus-AGS-side-`+1` scheme this used to be - both
+            // AGS integrations for those two compositors were checked
+            // before choosing this, and neither needs hand-rolled offset
+            // arithmetic the way srdwm's old 0-based ids forced `lib/
+            // srdwm.ts` to.
+            //
+            // Rolling this out requires `crates/config`'s shipped default,
+            // this user's own `~/.config/srd/keybindings.lua`, and AGS's
+            // `lib/srdwm.ts`/`service/wsPreview.ts` to all agree with core
+            // at the same time - they cannot update atomically with a
+            // single srdwm restart, so whichever of AGS/srdwm is running
+            // the *other* scheme during that window will visibly
+            // misbehave (confirmed live: AGS's Overview padding
+            // `workspace.count` slots and matching real workspaces onto
+            // them by id showed one extra/unmatched slot while AGS's own
+            // code had already been updated to assume 1-based ids but the
+            // live srdwm process was still 0-based). AGS's side is
+            // deliberately reverted back to its old `+1` offset for now,
+            // matching the still-running old build, and must be re-applied
+            // in the same breath as the next real srdwm restart - not
+            // before.
+            workspaces: vec![Workspace::new(1, "1", "dynamic")],
+            current_workspace: 1,
+            previous_workspace: 1,
             auto_back_and_forth: false,
-            next_workspace_id: 1,
+            per_monitor_workspaces: false,
+            primary_layout: String::new(),
+            secondary_layout: String::new(),
+            monitor_workspaces: HashMap::new(),
+            next_workspace_id: 2,
             next_window_id: 1,
             layouts,
             tiling: TilingConfig::default(),
@@ -192,6 +349,7 @@ impl WindowManager {
             shadows_enabled: true,
             resize_margin: RESIZE_MARGIN,
             rounded_corners_enabled: None,
+            color_filter: ColorFilter::None,
             focus_follows_mouse: false,
             auto_raise: false,
             theme: ThemeConfig::default(),
@@ -199,9 +357,11 @@ impl WindowManager {
             drag: None,
             resize: None,
             rules: Vec::new(),
+            remembered_sizes: HashMap::new(),
             close_requests: Vec::new(),
             keyboard_layout: String::new(),
             keyboard_layout_cycle_requests: 0,
+            pointer_monitor: None,
         }
     }
 
diff --git a/crates/core/src/manager/monitors.rs b/crates/core/src/manager/monitors.rs
index 9783e14..bff3bc9 100644
--- a/crates/core/src/manager/monitors.rs
+++ b/crates/core/src/manager/monitors.rs
@@ -82,6 +82,48 @@ impl WindowManager {
                 window.geometry = target;
             }
         }
+        self.apply_monitor_layouts();
+    }
+
+    /// Applies `primary_layout`/`secondary_layout` to whichever workspace
+    /// [`Self::workspace_for_monitor`] resolves for the primary monitor,
+    /// and for any other monitor that has *already* been given its own
+    /// distinct workspace via an independent switch - see those fields'
+    /// own doc comments for why this is a no-op outside `per_monitor_
+    /// workspaces` mode. Deliberately skips a non-primary monitor still
+    /// showing the same fallback workspace as the primary (nothing
+    /// distinct to apply `secondary_layout` to yet without also
+    /// clobbering what `primary_layout` just set on that same shared
+    /// workspace).
+    ///
+    /// Runs on every `set_monitors` call (startup and every hotplug
+    /// alike) rather than on every workspace switch - applying it
+    /// continuously would fight a workspace's own manually-set layout
+    /// every time a monitor switched back to it.
+    fn apply_monitor_layouts(&mut self) {
+        if !self.per_monitor_workspaces || (self.primary_layout.is_empty() && self.secondary_layout.is_empty()) {
+            return;
+        }
+        let Some(primary_id) = self.primary_monitor().map(|m| m.id) else { return };
+        let primary_ws = self.workspace_for_monitor(primary_id);
+        let registered: Vec<String> = self.available_layouts().iter().map(|s| s.to_string()).collect();
+        if !self.primary_layout.is_empty() && registered.contains(&self.primary_layout) {
+            self.set_layout(primary_ws, self.primary_layout.clone());
+        }
+        if self.secondary_layout.is_empty() || !registered.contains(&self.secondary_layout) {
+            return;
+        }
+        let monitors = self.monitors.clone();
+        for m in &monitors {
+            if m.id == primary_id {
+                continue;
+            }
+            let ws = self.workspace_for_monitor(m.id);
+            if ws == primary_ws {
+                continue;
+            }
+            self.set_layout(ws, self.secondary_layout.clone());
+        }
     }
 
     pub fn monitors(&self) -> &[Monitor] {
@@ -117,6 +159,98 @@ impl WindowManager {
         std::mem::take(&mut self.output_position_requests)
     }
 
+    /// Queues a request to enable or disable the output named `name` --
+    /// "primary only"/a per-display toggle, the two AGS monitor-layout
+    /// panel rows gated pending this. Same "core has no real output
+    /// handle, the backend drains and applies on its own next poll" shape
+    /// as `request_output_position` above, and the same reasoning:
+    /// turning a real CRTC's power state on or off is backend/hardware
+    /// work, not something this crate can do itself.
+    ///
+    /// By *name*, not `MonitorId` like `request_output_position` - a
+    /// disabled output is administratively removed from `monitors()`
+    /// entirely (the same real unplug/replug code path a genuine hotplug
+    /// already goes through, see the udev platform's own drain site), so
+    /// its id - an index into whatever's currently connected - stops
+    /// meaning anything the moment it's disabled. The connector's own
+    /// name survives the round trip; nothing else does.
+    pub fn request_output_enabled(&mut self, name: String, enabled: bool) {
+        self.output_enable_requests.retain(|(existing, _)| *existing != name);
+        self.output_enable_requests.push((name, enabled));
+    }
+
+    /// [`Self::drain_output_position_requests`]'s counterpart for
+    /// enable/disable requests.
+    pub fn drain_output_enable_requests(&mut self) -> Vec<(String, bool)> {
+        std::mem::take(&mut self.output_enable_requests)
+    }
+
+    /// Reports (or updates) `name`'s last-known state as an
+    /// administratively-disabled-but-still-connected output - called by
+    /// the backend at the moment it disables a connector, purely so `srd
+    /// monitors`/the `monitors` subscribe event can keep listing it (as
+    /// requested directly by the AGS peer session: a control that removes
+    /// its own target from view the moment it's used is one-way, not a
+    /// toggle). Deliberately separate from `monitors`/`set_monitors` --
+    /// see `DisabledMonitor`'s own doc comment for why this must never
+    /// touch real placement.
+    pub fn set_disabled_monitor(&mut self, name: String, geometry: Rect, full_geometry: Rect, primary: bool) {
+        self.disabled_monitors.insert(name, DisabledMonitor { geometry, full_geometry, primary });
+    }
+
+    /// Clears `name`'s disabled-monitor record - called by the backend
+    /// once it re-enables the connector (it's live again, `monitors()`
+    /// itself will report it) or discovers it's been genuinely unplugged
+    /// while disabled (nothing left to offer re-enabling at all; see
+    /// `reprobe_outputs`'s own doc comment on why "off" and "not
+    /// connected" have to be reported differently).
+    pub fn clear_disabled_monitor(&mut self, name: &str) {
+        self.disabled_monitors.remove(name);
+    }
+
+    /// Every currently-known disabled-but-connected output, by name - see
+    /// `set_disabled_monitor`'s own doc comment.
+    pub fn disabled_monitors(&self) -> impl Iterator<Item = (&str, &DisabledMonitor)> {
+        self.disabled_monitors.iter().map(|(name, m)| (name.as_str(), m))
+    }
+
+    /// `srd.monitor.split(name, parts, direction)` - divides connector
+    /// `name`'s real output into `parts` equal logical monitors from the
+    /// next time a backend queries `monitors()`. `parts <= 1` clears any
+    /// existing split for `name` rather than storing a meaningless
+    /// one-part split.
+    pub fn set_monitor_split(&mut self, name: String, parts: u32, rows: bool) {
+        if parts <= 1 {
+            self.monitor_splits.remove(&name);
+        } else {
+            self.monitor_splits.insert(name, MonitorSplit { parts, rows });
+        }
+    }
+
+    /// `name`'s current split request, if any - read by a backend's own
+    /// `monitors()` query.
+    pub fn monitor_split(&self, name: &str) -> Option<MonitorSplit> {
+        self.monitor_splits.get(name).copied()
+    }
+
+    /// `srd.monitor.scale(name, factor)` - a backend applies this the
+    /// next time it brings connector `name`'s head up (startup, hotplug,
+    /// or re-enable). `factor <= 0.0` clears any existing override rather
+    /// than storing a meaningless non-positive scale.
+    pub fn set_monitor_scale(&mut self, name: String, factor: f64) {
+        if factor > 0.0 {
+            self.monitor_scales.insert(name, factor);
+        } else {
+            self.monitor_scales.remove(&name);
+        }
+    }
+
+    /// `name`'s current scale override, if any - read by a backend when
+    /// bringing that connector's head up.
+    pub fn monitor_scale(&self, name: &str) -> Option<f64> {
+        self.monitor_scales.get(name).copied()
+    }
+
     pub fn primary_monitor(&self) -> Option<&Monitor> {
         self.monitors.iter().find(|m| m.primary).or_else(|| self.monitors.first())
     }
@@ -125,4 +259,41 @@ impl WindowManager {
         self.monitors.iter().find(|m| m.id == id).or_else(|| self.primary_monitor())
     }
 
+    /// Records which monitor the pointer is over right now - see `pointer_
+    /// monitor`'s own doc comment for why core needs to be told this rather
+    /// than knowing it already, and `add_window`'s target-monitor fallback
+    /// chain for the one thing it's actually used for. Called from a real
+    /// backend's pointer-motion handler; never `srd`/IPC-driven (nothing
+    /// external has a legitimate reason to claim where the pointer is).
+    pub fn set_pointer_monitor(&mut self, id: Option<MonitorId>) {
+        self.pointer_monitor = id;
+    }
+
+    /// The bounding rect of every registered monitor's own `full_geometry`
+    /// combined - the whole multi-monitor desktop's real screen area, not
+    /// just one output's. `None` only when there are no monitors at all
+    /// (never true in practice once startup has run).
+    ///
+    /// Exists specifically so `update_drag` can clamp a dragged window to
+    /// "somewhere on some real screen" instead of "within the one monitor
+    /// it happened to start the drag on" - the latter (what this
+    /// replaced) made it *mathematically impossible* to drag a window from
+    /// one monitor to another at all: the clamp bounds were computed once,
+    /// from `w.monitor` at drag-start, and never updated as the drag
+    /// crossed into a different monitor's own screen space, so `new_geom.x`
+    /// could never exceed the starting monitor's own right edge no matter
+    /// how far or fast the pointer moved. Reported live: a second monitor
+    /// connected and fully working at the compositor/DRM level (`srd
+    /// monitors` listed it, hotplug brought it up) still couldn't receive
+    /// a dragged window at all.
+    pub(super) fn all_monitors_bounds(&self) -> Option<Rect> {
+        self.monitors.iter().map(|m| m.full_geometry).reduce(|a, b| {
+            let x = a.x.min(b.x);
+            let y = a.y.min(b.y);
+            let right = a.right().max(b.right());
+            let bottom = a.bottom().max(b.bottom());
+            Rect::new(x, y, (right - x) as u32, (bottom - y) as u32)
+        })
+    }
+
 }
diff --git a/crates/core/src/manager/tests.rs b/crates/core/src/manager/tests.rs
index aa2fb1a..9af0181 100644
--- a/crates/core/src/manager/tests.rs
+++ b/crates/core/src/manager/tests.rs
@@ -154,6 +154,114 @@
     }
 
     #[test]
+    fn ending_a_resize_remembers_the_new_size_for_the_apps_next_window() {
+        let mut wm = wm_with_monitor();
+        // Tiling layout, so `add_window` skips `SmartPlacement`'s grid/
+        // cascade sizing entirely and the asserted geometry below reflects
+        // only the remembered-size lookup itself, not incidental grid math.
+        wm.set_layout(wm.current_workspace(), "tiling");
+        let a = wm.alloc_window_id();
+        let mut w = Window::new(a, "a");
+        w.app_id = "alacritty".into();
+        w.geometry = Rect::new(100, 100, 300, 200);
+        wm.add_window(w);
+        wm.start_resize(a, ResizeEdge::BottomRight, 400, 300);
+        wm.update_resize(500, 400);
+        wm.end_resize();
+
+        let b = wm.alloc_window_id();
+        let mut w2 = Window::new(b, "b");
+        w2.app_id = "alacritty".into();
+        // Whatever a backend would have hardcoded before calling add_window --
+        // the remembered size must win over this, not just supplement it.
+        w2.geometry = Rect::new(0, 0, 800, 600);
+        wm.add_window(w2);
+        let placed = wm.window(b).unwrap().geometry;
+        assert_eq!((placed.width, placed.height), (400, 300), "the second alacritty window must open at the size the first was resized to");
+    }
+
+    #[test]
+    fn remembered_size_is_keyed_by_app_id_not_shared_across_different_apps() {
+        let mut wm = wm_with_monitor();
+        // Tiling layout, so `add_window` skips `SmartPlacement`'s grid/
+        // cascade sizing entirely and the asserted geometry below reflects
+        // only the remembered-size lookup itself, not incidental grid math.
+        wm.set_layout(wm.current_workspace(), "tiling");
+        let a = wm.alloc_window_id();
+        let mut w = Window::new(a, "a");
+        w.app_id = "alacritty".into();
+        w.geometry = Rect::new(100, 100, 300, 200);
+        wm.add_window(w);
+        wm.start_resize(a, ResizeEdge::BottomRight, 400, 300);
+        wm.update_resize(500, 400);
+        wm.end_resize();
+
+        let b = wm.alloc_window_id();
+        let mut w2 = Window::new(b, "b");
+        w2.app_id = "firefox".into();
+        w2.geometry = Rect::new(0, 0, 800, 600);
+        wm.add_window(w2);
+        let placed = wm.window(b).unwrap().geometry;
+        assert_eq!((placed.width, placed.height), (800, 600), "a different app's default size must be untouched by alacritty's remembered size");
+    }
+
+    #[test]
+    fn maximizing_then_unmaximizing_does_not_change_the_remembered_size() {
+        // Only an interactive drag-resize should update `remembered_sizes` --
+        // maximize/fullscreen have their own separate `restore_geometry` and
+        // are not "a size the user wants their next window to open at".
+        let mut wm = wm_with_monitor();
+        // Tiling layout, so `add_window` skips `SmartPlacement`'s grid/
+        // cascade sizing entirely and the asserted geometry below reflects
+        // only the remembered-size lookup itself, not incidental grid math.
+        wm.set_layout(wm.current_workspace(), "tiling");
+        let a = wm.alloc_window_id();
+        let mut w = Window::new(a, "a");
+        w.app_id = "alacritty".into();
+        w.geometry = Rect::new(100, 100, 300, 200);
+        wm.add_window(w);
+        wm.toggle_maximize(a);
+        wm.toggle_maximize(a);
+
+        let b = wm.alloc_window_id();
+        let mut w2 = Window::new(b, "b");
+        w2.app_id = "alacritty".into();
+        w2.geometry = Rect::new(0, 0, 800, 600);
+        wm.add_window(w2);
+        let placed = wm.window(b).unwrap().geometry;
+        assert_eq!((placed.width, placed.height), (800, 600), "maximize/unmaximize alone must not have remembered anything");
+    }
+
+    #[test]
+    fn a_rules_explicit_geometry_still_wins_over_a_remembered_size() {
+        let mut wm = wm_with_monitor();
+        // Tiling layout, so `add_window` skips `SmartPlacement`'s grid/
+        // cascade sizing entirely and the asserted geometry below reflects
+        // only the remembered-size lookup itself, not incidental grid math.
+        wm.set_layout(wm.current_workspace(), "tiling");
+        let a = wm.alloc_window_id();
+        let mut w = Window::new(a, "a");
+        w.app_id = "alacritty".into();
+        w.geometry = Rect::new(100, 100, 300, 200);
+        wm.add_window(w);
+        wm.start_resize(a, ResizeEdge::BottomRight, 400, 300);
+        wm.update_resize(500, 400);
+        wm.end_resize();
+
+        wm.add_rule(WindowRule {
+            matcher: crate::rules::WindowMatch { class: Some("alacritty".into()), ..Default::default() },
+            actions: crate::rules::WindowRuleActions { geometry: Some(Rect::new(0, 0, 640, 480)), ..Default::default() },
+        });
+        let b = wm.alloc_window_id();
+        let mut w2 = Window::new(b, "b");
+        w2.app_id = "alacritty".into();
+        w2.geometry = Rect::new(0, 0, 800, 600);
+        wm.add_window(w2);
+        let placed = wm.window(b).unwrap().geometry;
+        assert_eq!((placed.width, placed.height), (640, 480), "a rule's explicit geometry is more specific and must win");
+    }
+
+    #[test]
     fn toggle_maximize_restores_original_geometry() {
         let mut wm = wm_with_monitor();
         let a = wm.alloc_window_id();
@@ -294,6 +402,30 @@
     }
 
     #[test]
+    fn hit_test_does_not_see_through_a_covering_windows_content_to_a_lower_windows_edge() {
+        // Reported live: a resize edge (or other titlebar/border zone)
+        // could still be grabbed on a window that was fully covered by
+        // another window on top of it, as long as the covering window's
+        // own edges didn't happen to land on that exact point. `a`'s left
+        // resize edge sits at x=0; `b` is stacked on top and covers that
+        // point with its own real content, but `b`'s own edges are far
+        // away (left at x=-100, nowhere near x=0), so `b` itself doesn't
+        // register a hit there - the bug was falling through to `a`'s
+        // edge underneath instead of stopping at `b`'s opaque content.
+        let mut wm = wm_with_monitor();
+        let a = wm.alloc_window_id();
+        let mut wa = Window::new(a, "a");
+        wa.geometry = Rect::new(0, 0, 400, 300);
+        wm.add_window(wa);
+        let b = wm.alloc_window_id();
+        let mut wb = Window::new(b, "b");
+        wb.geometry = Rect::new(-100, 0, 600, 300); // added later -> on top, fully covers a
+        wm.add_window(wb);
+
+        assert_eq!(wm.hit_test(0, 150), None, "a's edge must not be reachable through b's opaque content");
+    }
+
+    #[test]
     fn per_window_resize_margin_overrides_the_wm_wide_default() {
         // Hyprland's per-window `extend_border_grab_area` equivalent.
         let mut wm = wm_with_monitor();
@@ -389,10 +521,10 @@
         let ws2 = wm.add_workspace("2", "dynamic");
         wm.switch_workspace(ws2);
         assert_eq!(wm.current_workspace(), ws2);
-        // Re-selecting the already-active workspace jumps back to 0, the
+        // Re-selecting the already-active workspace jumps back to 1, the
         // one that was active right before.
         wm.switch_workspace(ws2);
-        assert_eq!(wm.current_workspace(), 0);
+        assert_eq!(wm.current_workspace(), 1);
     }
 
     #[test]
@@ -405,6 +537,129 @@
     }
 
     #[test]
+    fn switching_to_a_workspace_with_a_window_focuses_it() {
+        // Regression test: `switch_workspace` used to only ever touch
+        // `current_workspace`, never `self.focused` - reported live as
+        // switching to a workspace with an open window leaving that window
+        // unfocused while whatever was focused *before* the switch (now
+        // invisible, off on the old workspace) kept receiving real
+        // keyboard input.
+        let mut wm = wm_with_monitor();
+        let a = wm.alloc_window_id();
+        wm.add_window(Window::new(a, "a"));
+        let ws2 = wm.add_workspace("2", "dynamic");
+        let b = wm.alloc_window_id();
+        wm.add_window(Window::new(b, "b"));
+        wm.move_window_to_workspace(b, ws2);
+        wm.focus_window(a);
+        assert_eq!(wm.focused_id(), Some(a), "sanity: a is focused on the original workspace");
+
+        wm.switch_workspace(ws2);
+        assert_eq!(wm.focused_id(), Some(b), "switching to a workspace with a window must focus it, not leave the old workspace's window focused");
+    }
+
+    #[test]
+    fn switching_to_an_empty_workspace_clears_focus() {
+        let mut wm = wm_with_monitor();
+        let a = wm.alloc_window_id();
+        wm.add_window(Window::new(a, "a"));
+        wm.focus_window(a);
+        let empty_ws = wm.add_workspace("2", "dynamic");
+
+        wm.switch_workspace(empty_ws);
+        assert_eq!(wm.focused_id(), None, "no window on the new workspace to focus, and the old one is no longer visible");
+    }
+
+    #[test]
+    fn per_monitor_workspaces_off_by_default_switch_workspace_still_moves_every_monitor() {
+        // Sanity: the new `per_monitor_workspaces` field must default to
+        // `false` and leave shared-mode behaviour completely unchanged --
+        // every existing workspace test above this one relies on that.
+        let mut wm = WindowManager::new();
+        wm.set_monitors(two_monitors());
+        assert!(!wm.per_monitor_workspaces, "shared mode must be the default");
+        let ws2 = wm.add_workspace("2", "dynamic");
+        wm.switch_workspace(ws2);
+        assert_eq!(wm.workspace_for_monitor(0), ws2);
+        assert_eq!(wm.workspace_for_monitor(1), ws2, "shared mode: every monitor must agree");
+    }
+
+    #[test]
+    fn per_monitor_workspaces_on_switching_one_monitor_leaves_the_other_alone() {
+        let mut wm = WindowManager::new();
+        wm.set_monitors(two_monitors());
+        wm.per_monitor_workspaces = true;
+        let ws2 = wm.add_workspace("2", "dynamic");
+
+        wm.switch_workspace_on_monitor(ws2, 1);
+
+        assert_eq!(wm.workspace_for_monitor(1), ws2, "monitor 1 switched");
+        assert_eq!(wm.workspace_for_monitor(0), 1, "monitor 0 must still fall back to current_workspace, untouched");
+    }
+
+    #[test]
+    fn per_monitor_workspaces_on_visible_windows_respects_each_monitors_own_workspace() {
+        let mut wm = WindowManager::new();
+        wm.set_monitors(two_monitors());
+        wm.per_monitor_workspaces = true;
+        let ws2 = wm.add_workspace("2", "dynamic");
+
+        let a = wm.alloc_window_id();
+        wm.add_window(Window::new(a, "on-monitor-0-workspace-1"));
+        wm.window_mut(a).unwrap().monitor = 0;
+
+        let b = wm.alloc_window_id();
+        wm.add_window(Window::new(b, "on-monitor-1-workspace-2"));
+        wm.window_mut(b).unwrap().monitor = 1;
+        wm.move_window_to_workspace(b, ws2);
+
+        // Before switching monitor 1 to workspace 2, b isn't visible yet
+        // (monitor 1 still falls back to workspace 1).
+        assert!(!wm.visible_windows().any(|w| w.id == b));
+
+        wm.switch_workspace_on_monitor(ws2, 1);
+
+        let visible: Vec<_> = wm.visible_windows().map(|w| w.id).collect();
+        assert!(visible.contains(&a), "monitor 0's own window must still be visible");
+        assert!(visible.contains(&b), "monitor 1's window must become visible once its monitor switches to workspace 2");
+    }
+
+    #[test]
+    fn per_monitor_workspaces_on_multiple_workspaces_can_be_active_at_once() {
+        let mut wm = WindowManager::new();
+        wm.set_monitors(two_monitors());
+        wm.per_monitor_workspaces = true;
+        let ws2 = wm.add_workspace("2", "dynamic");
+
+        wm.switch_workspace_on_monitor(ws2, 1);
+
+        assert!(wm.is_workspace_visible(1), "monitor 0 is still showing workspace 1");
+        assert!(wm.is_workspace_visible(ws2), "monitor 1 is showing workspace 2");
+    }
+
+    #[test]
+    fn switching_to_a_workspace_where_the_already_focused_window_lives_is_a_no_op_for_focus() {
+        // The auto-focus-on-switch behavior above must not fight
+        // `focus_window`'s own workspace-follow call into `switch_workspace`
+        // (see that function's doc comment): when a window on another
+        // workspace is focused directly, that window - not merely "the
+        // topmost window on its workspace" - must end up focused, even if
+        // it isn't the topmost one.
+        let mut wm = wm_with_monitor();
+        let ws2 = wm.add_workspace("2", "dynamic");
+        let a = wm.alloc_window_id();
+        wm.add_window(Window::new(a, "a"));
+        wm.move_window_to_workspace(a, ws2);
+        let b = wm.alloc_window_id();
+        wm.add_window(Window::new(b, "b"));
+        wm.move_window_to_workspace(b, ws2);
+        // b was added after a, so it's topmost - focusing a directly must
+        // still result in a being focused, not b.
+        wm.focus_window(a);
+        assert_eq!(wm.focused_id(), Some(a));
+    }
+
+    #[test]
     fn focusing_a_window_on_another_workspace_switches_to_it() {
         // Regression test: `focus_window` used to mark the target focused
         // without ever touching `current_workspace` - reported live
@@ -421,7 +676,7 @@
         let id = wm.alloc_window_id();
         wm.add_window(Window::new(id, "a"));
         wm.move_window_to_workspace(id, ws2);
-        assert_eq!(wm.current_workspace(), 0, "sanity: still on the default workspace");
+        assert_eq!(wm.current_workspace(), 1, "sanity: still on the default workspace");
 
         wm.focus_window(id);
         assert_eq!(wm.current_workspace(), ws2, "focusing a window must bring its workspace along");
@@ -482,7 +737,7 @@
         // workspace id that was never really visited.
         wm.auto_back_and_forth = true;
         wm.switch_workspace(ws2);
-        assert_eq!(wm.current_workspace(), 0);
+        assert_eq!(wm.current_workspace(), 1);
     }
 
     #[test]
@@ -642,6 +897,75 @@
     }
 
     #[test]
+    fn disabled_monitor_is_reported_but_never_shows_up_in_monitors() {
+        // The whole point of keeping this separate from `set_monitors`:
+        // real placement (`monitors()`) must never see a disabled output,
+        // even though `srd monitors`/AGS's panel now needs to list it.
+        let mut wm = WindowManager::new();
+        wm.set_monitors(two_monitors());
+        wm.set_disabled_monitor("HDMI-A-1".to_string(), Rect::new(1920, 0, 1920, 1080), Rect::new(1920, 0, 1920, 1080), false);
+
+        assert_eq!(wm.monitors().len(), 2, "disabled_monitors must not leak into real placement's monitor list");
+        let disabled: Vec<_> = wm.disabled_monitors().collect();
+        assert_eq!(disabled.len(), 1);
+        assert_eq!(disabled[0].0, "HDMI-A-1");
+    }
+
+    #[test]
+    fn re_enabling_clears_the_disabled_monitor_record() {
+        let mut wm = WindowManager::new();
+        wm.set_disabled_monitor("HDMI-A-1".to_string(), Rect::new(0, 0, 1920, 1080), Rect::new(0, 0, 1920, 1080), false);
+        assert_eq!(wm.disabled_monitors().count(), 1);
+
+        wm.clear_disabled_monitor("HDMI-A-1");
+        assert_eq!(wm.disabled_monitors().count(), 0);
+    }
+
+    #[test]
+    fn primary_secondary_layout_is_a_no_op_outside_per_monitor_workspaces_mode() {
+        // Shared mode: every monitor shows the same one workspace, so a
+        // primary/secondary split has nothing distinct to apply to.
+        let mut wm = WindowManager::new();
+        wm.primary_layout = "dynamic".to_string();
+        wm.secondary_layout = "tiling".to_string();
+        wm.set_monitors(two_monitors());
+        assert_eq!(wm.workspace(1).unwrap().layout, "dynamic", "must not touch the shared workspace's layout");
+    }
+
+    #[test]
+    fn primary_secondary_layout_applies_once_workspaces_are_split_per_monitor() {
+        let mut wm = WindowManager::new();
+        wm.per_monitor_workspaces = true;
+        wm.primary_layout = "dynamic".to_string();
+        wm.secondary_layout = "tiling".to_string();
+        wm.set_monitors(two_monitors());
+        // Give the secondary monitor its own workspace, same as a real
+        // independent per-monitor switch would.
+        let ws2 = wm.add_workspace("2", "dynamic");
+        wm.switch_workspace_on_monitor(ws2, 1);
+        // Re-applied on the next monitor-list refresh (a hotplug or
+        // restart), not continuously - see `apply_monitor_layouts`'s own
+        // doc comment for why it doesn't hook every workspace switch.
+        wm.set_monitors(two_monitors());
+
+        assert_eq!(wm.workspace(wm.workspace_for_monitor(0)).unwrap().layout, "dynamic");
+        assert_eq!(wm.workspace(ws2).unwrap().layout, "tiling");
+    }
+
+    #[test]
+    fn primary_secondary_layout_does_not_clobber_the_still_shared_workspace() {
+        // Neither monitor has been independently switched yet - both
+        // still resolve to the same fallback workspace. secondary_layout
+        // must not stomp what primary_layout just set on it.
+        let mut wm = WindowManager::new();
+        wm.per_monitor_workspaces = true;
+        wm.primary_layout = "dynamic".to_string();
+        wm.secondary_layout = "tiling".to_string();
+        wm.set_monitors(two_monitors());
+        assert_eq!(wm.workspace(1).unwrap().layout, "dynamic");
+    }
+
+    #[test]
     fn unplugging_a_monitor_rehomes_its_windows_to_the_primary() {
         let mut wm = WindowManager::new();
         wm.set_monitors(two_monitors());
@@ -749,6 +1073,69 @@
         );
     }
 
+    #[test]
+    fn a_new_window_lands_on_the_focused_windows_monitor_not_always_primary() {
+        // Real bug, reported live: "why do all windows only open on the
+        // first monitor" - `add_window` used to resolve its target
+        // monitor via `primary_monitor()` unconditionally, so a second
+        // monitor being the one the user was actually working on never
+        // mattered at all.
+        let mut wm = WindowManager::new();
+        wm.set_monitors(two_monitors());
+
+        let first = wm.alloc_window_id();
+        wm.add_window(Window::new(first, "on-primary"));
+        assert_eq!(wm.window(first).unwrap().monitor, 0, "sanity: nothing focused yet falls back to primary");
+
+        // `add_window` itself focuses whatever it just added, so moving
+        // this window onto the secondary monitor and leaving it focused is
+        // enough to make it "the window the user is currently on" for the
+        // next one.
+        wm.window_mut(first).unwrap().monitor = 1;
+
+        let second = wm.alloc_window_id();
+        wm.add_window(Window::new(second, "should-follow-focus"));
+        assert_eq!(wm.window(second).unwrap().monitor, 1, "a new window must land on the focused window's monitor, not primary");
+    }
+
+    #[test]
+    fn a_new_window_lands_on_the_pointers_monitor_when_nothing_is_focused_there() {
+        // Real bug, reported live: with nothing focused (a fresh session,
+        // or the last-focused window sitting on a *different* monitor than
+        // the one just clicked/hovered), a new window still fell all the
+        // way back to primary - even though the user was demonstrably at
+        // the second monitor when they launched it. `set_pointer_monitor`
+        // is what a real backend's pointer-motion handler calls to tell
+        // core this.
+        let mut wm = WindowManager::new();
+        wm.set_monitors(two_monitors());
+        wm.set_pointer_monitor(Some(1));
+
+        let id = wm.alloc_window_id();
+        wm.add_window(Window::new(id, "should-follow-pointer"));
+        assert_eq!(wm.window(id).unwrap().monitor, 1, "a new window must land on the pointer's monitor when nothing is focused, not primary");
+    }
+
+    #[test]
+    fn a_focused_window_still_wins_over_the_pointers_monitor() {
+        // The pointer is only a fallback for when nothing is focused --
+        // see `add_window`'s own doc comment for why focus stays the
+        // primary signal (matches every mainstream desktop's "new window
+        // opens where you're working" convention, which is about the
+        // focused context, not incidental cursor position).
+        let mut wm = WindowManager::new();
+        wm.set_monitors(two_monitors());
+
+        let first = wm.alloc_window_id();
+        wm.add_window(Window::new(first, "focused-on-primary"));
+        wm.window_mut(first).unwrap().monitor = 0;
+        wm.set_pointer_monitor(Some(1));
+
+        let second = wm.alloc_window_id();
+        wm.add_window(Window::new(second, "should-still-follow-focus"));
+        assert_eq!(wm.window(second).unwrap().monitor, 0, "a focused window's monitor must win over the pointer's");
+    }
+
     // ---- Fullscreen ------------------------------------------------------
 
     #[test]
diff --git a/crates/core/src/manager/windows.rs b/crates/core/src/manager/windows.rs
index d73dec1..7e2046d 100644
--- a/crates/core/src/manager/windows.rs
+++ b/crates/core/src/manager/windows.rs
@@ -26,7 +26,7 @@ impl WindowManager {
         window.border_color = self.theme.default_border_color;
         window.border_width = self.theme.default_border_width;
         window.corner_radius = self.theme.default_corner_radius;
-        window.decorated = self.theme.default_decorated;
+        window.decorated = self.theme.default_decorated && !likely_draws_own_titlebar(&window.app_id);
         let actions = self.rules.iter().find(|r| r.matcher.matches(&window)).map(|r| r.actions.clone());
         // See `Window::rules_applied`'s doc comment: a native Wayland window
         // still has empty title/app_id at this point, so a real (if
@@ -62,7 +62,50 @@ impl WindowManager {
             }
         }
 
-        if let Some(monitor) = self.primary_monitor() {
+        // A remembered size (`remembered_sizes`' own doc comment) wins over
+        // whatever fixed default a backend hardcoded into `window.geometry`
+        // before calling this - but a rule's explicit `geometry` action
+        // below still wins over *this*, since that's a deliberate per-app
+        // override, more specific than "whatever I last resized this app
+        // to". Clamped to the same minimums a live resize itself can never
+        // go below, so a corrupted/stale entry can't hand a new window a
+        // degenerate size.
+        if !window.app_id.is_empty() {
+            if let Some(&(w, h)) = self.remembered_sizes.get(&window.app_id) {
+                window.geometry.width = w.max(MIN_WINDOW_WIDTH);
+                window.geometry.height = h.max(MIN_WINDOW_HEIGHT);
+            }
+        }
+        // Every new window used to land on the *primary* monitor
+        // unconditionally, regardless of which monitor the user was
+        // actually working on - reported live as "why do all windows only
+        // open on the first monitor" once a second, non-primary monitor
+        // was actually in use. Placing on the *focused* window's monitor
+        // instead matches every mainstream desktop's own convention (a new
+        // window opens where you're currently working, not wherever
+        // "primary" happens to be), and needs no new state: `self.focused`
+        // already exists for exactly this kind of "what's the user looking
+        // at right now" question.
+        //
+        // Falling all the way back to the primary monitor whenever nothing
+        // is focused was still wrong for a second, later-reported case:
+        // nothing focused *on the monitor the user is actually at* - an
+        // empty desktop there, or the last-focused window happening to sit
+        // on a different monitor than the one just clicked/hovered before
+        // launching something new - landed the new window on primary
+        // regardless of which monitor was genuinely in use. `pointer_
+        // monitor` (see its own doc comment) is a second, better fallback
+        // for exactly that gap, checked before giving up to primary
+        // entirely - which stays the last resort for the one case neither
+        // signal can answer, a fresh session's very first window before any
+        // pointer motion has been reported at all.
+        let target_monitor = self
+            .focused
+            .and_then(|id| self.windows.get(&id))
+            .and_then(|w| self.monitors.iter().find(|m| m.id == w.monitor))
+            .or_else(|| self.pointer_monitor.and_then(|id| self.monitors.iter().find(|m| m.id == id)))
+            .or_else(|| self.primary_monitor());
+        if let Some(monitor) = target_monitor {
             window.monitor = monitor.id;
             let layout_name = self.workspace(workspace).map(|w| w.layout.clone()).unwrap_or_default();
             if layout_name != "tiling" {
@@ -116,7 +159,17 @@ impl WindowManager {
         let actions = self.rules.iter().find(|r| r.matcher.matches(window)).map(|r| r.actions.clone());
         let Some(window) = self.windows.get_mut(&id) else { return false };
         window.rules_applied = true;
-        let Some(actions) = actions else { return false };
+        // `add_window`'s matching fallback only ever sees this once
+        // `app_id` is actually known - for a native Wayland window that's
+        // usually after creation (`set_app_id` lands later), which is
+        // exactly why this needs its own check here too, not just there.
+        // A rule's own `decorated` action, if any, still wins below.
+        let mut heuristic_changed = false;
+        if actions.as_ref().and_then(|a| a.decorated).is_none() && window.decorated && likely_draws_own_titlebar(&window.app_id) {
+            window.decorated = false;
+            heuristic_changed = true;
+        }
+        let Some(actions) = actions else { return heuristic_changed };
         if let Some(floating) = actions.floating {
             window.floating = floating;
         }
diff --git a/crates/core/src/manager/workspaces.rs b/crates/core/src/manager/workspaces.rs
index 6ffb21b..f502d6b 100644
--- a/crates/core/src/manager/workspaces.rs
+++ b/crates/core/src/manager/workspaces.rs
@@ -30,7 +30,12 @@ impl WindowManager {
         if self.workspaces.len() <= 1 {
             return;
         }
-        let fallback = self.workspaces.iter().map(|w| w.id).find(|&w| w != id).unwrap_or(0);
+        // `unwrap_or(1)` is unreachable in practice - the `len() <= 1`
+        // guard above means `find` always has at least one other workspace
+        // to return - but `1`, not `0`, since workspace ids are 1-based
+        // (see `WindowManager::new`'s own doc comment) and `0` is no longer
+        // a real workspace id this could plausibly fall back to.
+        let fallback = self.workspaces.iter().map(|w| w.id).find(|&w| w != id).unwrap_or(1);
         for w in self.windows.values_mut().filter(|w| w.workspace == id) {
             w.workspace = fallback;
         }
@@ -53,6 +58,23 @@ impl WindowManager {
         if self.workspaces.iter().any(|w| w.id == target) && target != self.current_workspace {
             self.previous_workspace = self.current_workspace;
             self.current_workspace = target;
+            // Keyboard focus otherwise stayed on whatever was focused
+            // *before* the switch - this function only ever touched
+            // `current_workspace`, never `self.focused` - so real input
+            // kept going to a window that had just gone invisible while
+            // whatever's now on screen, if anything, received nothing.
+            // Reported live: switching to a workspace with an open window
+            // left that window unfocused and the previous workspace's
+            // window still receiving keystrokes. Only reassigns focus when
+            // the currently-focused window isn't actually on the new
+            // workspace - an already-correct focus (e.g. `focus_window`'s
+            // own workspace-follow call into this function, where the
+            // target window IS what should end up focused) must not get
+            // silently overridden by "pick the topmost window instead".
+            let focus_still_valid = self.focused.and_then(|id| self.windows.get(&id)).is_some_and(|w| w.workspace == target);
+            if !focus_still_valid {
+                self.focused = self.window_ids_on_workspace_front_to_back(target).into_iter().next();
+            }
         }
     }
 
@@ -60,6 +82,76 @@ impl WindowManager {
         self.current_workspace
     }
 
+    /// The workspace actually showing on `monitor` right now - `current_
+    /// workspace` directly when `per_monitor_workspaces` is `false` (every
+    /// monitor always agrees, by construction, since only `switch_
+    /// workspace` - never `switch_workspace_on_monitor` - can run in that
+    /// mode); otherwise this monitor's own independently-switched
+    /// workspace, or `current_workspace` as the fallback for a monitor
+    /// that has never had one switched independently yet (freshly
+    /// connected, or the mode was just turned on).
+    pub fn workspace_for_monitor(&self, monitor: MonitorId) -> WorkspaceId {
+        if self.per_monitor_workspaces {
+            self.monitor_workspaces.get(&monitor).copied().unwrap_or(self.current_workspace)
+        } else {
+            self.current_workspace
+        }
+    }
+
+    /// Whether `id` is showing on *any* currently-connected monitor right
+    /// now - what `srd workspaces`/AGS's own workspace pills should treat
+    /// as "active" (`crates/platform/src/ipc.rs::workspace_snapshot`).
+    /// Structurally allows more than one workspace to be active at once,
+    /// which only actually happens in `per_monitor_workspaces` mode with
+    /// two monitors on different workspaces - shared mode (the default)
+    /// always has exactly one, same as before this existed.
+    pub fn is_workspace_visible(&self, id: WorkspaceId) -> bool {
+        if self.per_monitor_workspaces {
+            self.monitors.iter().any(|m| self.workspace_for_monitor(m.id) == id)
+        } else {
+            id == self.current_workspace
+        }
+    }
+
+    /// The `per_monitor_workspaces`-aware counterpart to `switch_
+    /// workspace`: switches `monitor`'s own workspace to `id` without
+    /// affecting any other monitor, when the mode is on. Falls straight
+    /// through to the ordinary shared-mode `switch_workspace` (ignoring
+    /// `monitor` entirely) when it's off, so a caller can always use this
+    /// one entry point regardless of which mode is active rather than
+    /// branching on the config flag itself - see its own call site in
+    /// `crates/platform/src/ipc.rs`'s `activate_workspace` handler.
+    ///
+    /// `monitor` is "whichever monitor this switch should apply to", not
+    /// necessarily where the pointer is - the caller decides that (the
+    /// focused window's own monitor, in practice), same as real per-output
+    /// keybinding routing in Hyprland/niri.
+    pub fn switch_workspace_on_monitor(&mut self, id: WorkspaceId, monitor: MonitorId) {
+        if !self.per_monitor_workspaces {
+            self.switch_workspace(id);
+            return;
+        }
+        let current = self.workspace_for_monitor(monitor);
+        let target = if self.auto_back_and_forth && id == current {
+            self.monitor_workspaces.get(&monitor).copied().unwrap_or(self.previous_workspace)
+        } else {
+            id
+        };
+        if !self.workspaces.iter().any(|w| w.id == target) || target == current {
+            return;
+        }
+        self.previous_workspace = current;
+        self.monitor_workspaces.insert(monitor, target);
+        // Same reasoning as `switch_workspace`'s own matching comment:
+        // reassign focus only when the currently-focused window isn't
+        // already correctly on the new workspace, so an already-correct
+        // focus assignment from elsewhere doesn't get silently overridden.
+        let focus_still_valid = self.focused.and_then(|id| self.windows.get(&id)).is_some_and(|w| w.workspace == target);
+        if !focus_still_valid {
+            self.focused = self.window_ids_on_workspace_front_to_back(target).into_iter().next();
+        }
+    }
+
     pub fn workspace(&self, id: WorkspaceId) -> Option<&Workspace> {
         self.workspaces.iter().find(|w| w.id == id)
     }
@@ -74,15 +166,20 @@ impl WindowManager {
         }
     }
 
-    /// Windows that should currently be shown to the user: those on the
-    /// current workspace, and not minimized.
+    /// Windows that should currently be shown to the user: those on
+    /// whichever workspace their own monitor is currently showing, and not
+    /// minimized.
     ///
-    /// `current_workspace` is a single value shared by every monitor --
-    /// srdwm does not have Hyprland-style independent per-monitor
-    /// workspaces, so switching workspace changes what's shown on every
-    /// screen at once. `w.monitor` plays no part in this filter at all.
+    /// In shared mode (`per_monitor_workspaces` off, the default) every
+    /// monitor is always showing `current_workspace`, so this reduces to
+    /// exactly the original single-shared-workspace filter and `w.monitor`
+    /// plays no part in it - switching workspace still changes what's
+    /// shown on every screen at once. In per-monitor mode, each window is
+    /// checked against its *own* monitor's independently-switched
+    /// workspace (`workspace_for_monitor`) instead, so two monitors on two
+    /// different workspaces each correctly show only their own.
     pub fn visible_windows(&self) -> impl Iterator<Item = &Window> {
-        self.windows.values().filter(|w| w.workspace == self.current_workspace && !w.minimized)
+        self.windows.values().filter(|w| w.workspace == self.workspace_for_monitor(w.monitor) && !w.minimized)
     }
 
     /// Same windows as [`Self::visible_windows`], but in real front-to-back
@@ -95,7 +192,7 @@ impl WindowManager {
     /// `self.order` reversed is the same "topmost first" convention
     /// `hit_test`/`window_at` already use.
     pub fn visible_windows_front_to_back(&self) -> impl Iterator<Item = &Window> {
-        self.order.iter().rev().filter_map(|id| self.windows.get(id)).filter(|w| w.workspace == self.current_workspace && !w.minimized)
+        self.order.iter().rev().filter_map(|id| self.windows.get(id)).filter(|w| w.workspace == self.workspace_for_monitor(w.monitor) && !w.minimized)
     }
 
 }
diff --git a/crates/core/src/monitor.rs b/crates/core/src/monitor.rs
index 01f54cb..6ea053f 100644
--- a/crates/core/src/monitor.rs
+++ b/crates/core/src/monitor.rs
@@ -42,10 +42,247 @@ pub struct Monitor {
     pub name: String,
     pub refresh_rate_mhz: u32,
     pub primary: bool,
+    /// `true` when this entry is one part of a real output divided by
+    /// `srd.monitor.split` - not a second `wl_output`, not a second
+    /// physical connector. A display-arrangement UI reads this to tell a
+    /// split part apart from a genuinely separate monitor, so it does not
+    /// offer to move or extend a physical arrangement onto something that
+    /// is not a real, independent output. `false` for an ordinary,
+    /// undivided output.
+    pub split: bool,
+    /// This output's real scale factor (automatic, from `srdwm_core::
+    /// monitor::auto_scale_for`, or an explicit `srd.monitor.scale`
+    /// override) - `1.0` for an unscaled output. Every other field on
+    /// this struct (`geometry`, `full_geometry`, `maximize_geometry`) is
+    /// in *physical* pixels, not the logical points a Wayland client
+    /// itself sees; a caller that needs to convert between the two (a
+    /// display-arrangement UI chaining outputs by their reported size,
+    /// for instance) multiplies logical by this to get physical, or
+    /// divides physical by this to get logical. Requested directly by the
+    /// AGS peer session after a real bug (`srd dispatch set output
+    /// position` and this compositor's own physical-pixel bookkeeping
+    /// silently disagreeing with a client's logical one at any scale
+    /// other than `1.0`) traced back to exactly this missing piece of
+    /// information.
+    pub scale: f64,
 }
 
 impl Monitor {
     pub fn new(id: MonitorId, name: impl Into<String>, geometry: Rect) -> Self {
-        Self { id, name: name.into(), geometry, full_geometry: geometry, maximize_geometry: geometry, refresh_rate_mhz: 60_000, primary: false }
+        Self { id, name: name.into(), geometry, full_geometry: geometry, maximize_geometry: geometry, refresh_rate_mhz: 60_000, primary: false, split: false, scale: 1.0 }
+    }
+}
+
+/// A connector a backend has administratively disabled (`srd dispatch set
+/// output enabled <name> false`) but that's still physically connected --
+/// purely informational, reported by the backend via `WindowManager::
+/// set_disabled_monitor` for `srd monitors`/the `monitors` subscribe event
+/// to list (so a display-settings UI can offer to turn it back on by
+/// name), and deliberately never fed into `WindowManager::monitors()` or
+/// any real placement/tiling logic, which continues to see only genuinely
+/// live outputs exactly as before this existed. Geometry is a last-known
+/// snapshot from the moment it was disabled - stale by construction, and
+/// meant to be: a caller wanting to reposition it correctly re-queries
+/// once it's actually re-enabled, not from this.
+#[derive(Debug, Clone)]
+pub struct DisabledMonitor {
+    pub geometry: Rect,
+    pub full_geometry: Rect,
+    pub primary: bool,
+}
+
+/// A `srd.monitor.split(name, parts, direction)` config-time request:
+/// divide one real output into `parts` equal (within a pixel) logical
+/// [`Monitor`] entries, so placement/tiling can treat them as separate
+/// screens without any DRM/`wl_output` involvement - see `split_rect`'s
+/// own doc comment for the actual division, and the udev platform's
+/// `monitors()` for where this turns into real `Monitor` entries.
+///
+/// Deliberately just a division of one real output's rectangle for
+/// placement purposes, not a second `wl_output` global - a client
+/// fullscreening or querying `wl_output.enter`/scale for a specific
+/// sub-region still sees it as part of the one real output. See the
+/// "different monitors mode in one" plan for why that's an accepted,
+/// explicitly-flagged limitation of this first version.
+#[derive(Debug, Clone, Copy)]
+pub struct MonitorSplit {
+    pub parts: u32,
+    /// `false` (the default): side-by-side columns, splitting width.
+    /// `true`: stacked rows, splitting height.
+    pub rows: bool,
+}
+
+/// Divides `rect` into `parts` equal (within one pixel) pieces along one
+/// axis, returning piece number `index` (`0..parts`). `rows` chooses which
+/// axis: stacked rows (splitting height) when `true`, side-by-side columns
+/// (splitting width) when `false`.
+///
+/// Any remainder from an uneven division is spread one pixel at a time
+/// across the first `remainder` pieces, rather than dumped entirely onto
+/// the last one - so a 1919px-wide monitor split into 2 columns yields
+/// 960/959, not a lopsided 959/960 vs. a naive 959/960-plus-slack-on-one-
+/// side that would leave one part visibly wider for no reason tied to the
+/// actual pixel count.
+///
+/// `index >= parts` or `parts == 0` returns `rect` unchanged - callers
+/// are expected to only iterate `0..parts.max(1)`, this is just a safe
+/// fallback rather than a panic for a config-driven value.
+pub fn split_rect(rect: Rect, index: u32, parts: u32, rows: bool) -> Rect {
+    if parts <= 1 || index >= parts {
+        return rect;
+    }
+    let total = if rows { rect.height } else { rect.width };
+    let other = if rows { rect.width } else { rect.height };
+    let base = total / parts;
+    let remainder = total % parts;
+    let size_for = |i: u32| base + if i < remainder { 1 } else { 0 };
+    let offset: u32 = (0..index).map(size_for).sum();
+    let size = size_for(index);
+    if rows {
+        Rect::new(rect.x, rect.y + offset as i32, other, size)
+    } else {
+        Rect::new(rect.x + offset as i32, rect.y, size, other)
+    }
+}
+
+/// The pixel density (in real, physical-size terms) srdwm treats as
+/// needing no scale correction at all. `92`, close to the classic desktop
+/// "96 DPI" constant - lowered from an initial `109` (roughly a 24"
+/// 1920x1080 or 27" 2560x1440 monitor) after live testing on a real 1080p
+/// monitor at ~78 PPI: `109` produced a `0.71` scale there, reported as
+/// too aggressive a shrink; `92` produces `~0.85`, still a real reduction
+/// but closer to what actually reads as "more space", not "suddenly tiny
+/// text".
+const REFERENCE_PPI: f64 = 92.0;
+
+/// Automatically derives an output scale from real EDID physical size and
+/// native resolution, with no monitor name or fixed size bucket involved
+/// anywhere - a large panel with low pixel density (a big monitor at the
+/// same resolution as a much smaller one, the concrete case this exists
+/// for) gets scaled down smoothly in proportion to how far its real PPI
+/// falls below [`REFERENCE_PPI`], clamped to `0.5` so a pathologically
+/// large/low-res panel doesn't shrink text into illegibility. Deliberately
+/// never scales *above* `1.0` on its own - a high-density panel already
+/// benefits from more detail, not less, and plenty of people want native
+/// crispness there; `srd.monitor.scale` remains the explicit, manual way
+/// to opt into upscaling a specific connector.
+///
+/// `physical_mm` of `(0, 0)` (no EDID physical-size descriptor at all --
+/// some VMs/adapters report this) returns `1.0` rather than guessing from
+/// nothing.
+pub fn auto_scale_for(physical_mm: (i32, i32), resolution_px: (i32, i32)) -> f64 {
+    let (pw, ph) = physical_mm;
+    if pw <= 0 || ph <= 0 {
+        return 1.0;
+    }
+    let diagonal_mm = ((pw as f64).powi(2) + (ph as f64).powi(2)).sqrt();
+    let diagonal_in = diagonal_mm / 25.4;
+    let (rw, rh) = resolution_px;
+    let diagonal_px = ((rw as f64).powi(2) + (rh as f64).powi(2)).sqrt();
+    let ppi = diagonal_px / diagonal_in;
+    if ppi >= REFERENCE_PPI {
+        1.0
+    } else {
+        (ppi / REFERENCE_PPI).clamp(0.5, 1.0)
+    }
+}
+
+#[cfg(test)]
+mod auto_scale_tests {
+    use super::*;
+
+    #[test]
+    fn a_15_inch_1080p_laptop_panel_needs_no_correction() {
+        // 340mm x 190mm, ~143 PPI - comfortably above the reference, and
+        // the concrete real-hardware case this must not regress: this
+        // laptop's own panel was already correct at 1.0.
+        assert_eq!(auto_scale_for((340, 190), (1920, 1080)), 1.0);
+    }
+
+    #[test]
+    fn a_physically_large_1080p_monitor_scales_down() {
+        // 600mm x 400mm at the same 1920x1080 as the laptop above --
+        // ~78 PPI, well under the reference. The concrete case this whole
+        // function exists for: reported live as "too big, should utilize
+        // greater real estate" on exactly this monitor.
+        let s = auto_scale_for((600, 400), (1920, 1080));
+        assert!(s < 1.0 && s > 0.5, "expected a real scale-down, got {s}");
+    }
+
+    #[test]
+    fn a_high_density_panel_is_never_auto_upscaled() {
+        // A small, very high-resolution panel (e.g. a 13" 4K) - far above
+        // the reference PPI. Must clamp at 1.0, not scale past it.
+        assert_eq!(auto_scale_for((290, 170), (3840, 2160)), 1.0);
+    }
+
+    #[test]
+    fn an_extreme_low_density_panel_clamps_at_half_scale() {
+        let s = auto_scale_for((2000, 1200), (1024, 768));
+        assert_eq!(s, 0.5);
+    }
+
+    #[test]
+    fn missing_physical_size_does_not_guess() {
+        assert_eq!(auto_scale_for((0, 0), (1920, 1080)), 1.0);
+    }
+}
+
+#[cfg(test)]
+mod split_tests {
+    use super::*;
+
+    #[test]
+    fn single_part_returns_the_whole_rect_unchanged() {
+        let r = Rect::new(0, 0, 1920, 1080);
+        assert_eq!(split_rect(r, 0, 1, false), r);
+    }
+
+    #[test]
+    fn even_columns_split_width_with_no_gap_or_overlap() {
+        let r = Rect::new(100, 0, 1920, 1080);
+        let a = split_rect(r, 0, 2, false);
+        let b = split_rect(r, 1, 2, false);
+        assert_eq!(a, Rect::new(100, 0, 960, 1080));
+        assert_eq!(b, Rect::new(1060, 0, 960, 1080));
+        assert_eq!(a.right(), b.x, "no gap or overlap between adjacent parts");
+    }
+
+    #[test]
+    fn uneven_columns_spread_the_remainder_one_pixel_at_a_time() {
+        let r = Rect::new(0, 0, 1919, 1080);
+        let a = split_rect(r, 0, 2, false);
+        let b = split_rect(r, 1, 2, false);
+        assert_eq!(a.width, 960);
+        assert_eq!(b.width, 959);
+        assert_eq!(a.width + b.width, r.width);
+        assert_eq!(a.right(), b.x);
+    }
+
+    #[test]
+    fn rows_split_height_and_leave_width_untouched() {
+        let r = Rect::new(0, 50, 1920, 1080);
+        let a = split_rect(r, 0, 2, true);
+        let b = split_rect(r, 1, 2, true);
+        assert_eq!(a, Rect::new(0, 50, 1920, 540));
+        assert_eq!(b, Rect::new(0, 590, 1920, 540));
+        assert_eq!(a.bottom(), b.y);
+    }
+
+    #[test]
+    fn three_parts_covers_the_whole_rect_exactly() {
+        let r = Rect::new(0, 0, 1000, 500);
+        let parts: Vec<Rect> = (0..3).map(|i| split_rect(r, i, 3, false)).collect();
+        let total_width: u32 = parts.iter().map(|p| p.width).sum();
+        assert_eq!(total_width, r.width);
+        for w in parts.windows(2) {
+            assert_eq!(w[0].right(), w[1].x);
+        }
+    }
+
+    #[test]
+    fn out_of_range_index_returns_the_whole_rect_unchanged() {
+        let r = Rect::new(0, 0, 1920, 1080);
+        assert_eq!(split_rect(r, 5, 2, false), r);
     }
 }
diff --git a/crates/core/src/theme.rs b/crates/core/src/theme.rs
index 1511a1f..882326f 100644
--- a/crates/core/src/theme.rs
+++ b/crates/core/src/theme.rs
@@ -16,11 +16,30 @@ pub struct ThemeConfig {
     pub titlebar_fg_focused: (u8, u8, u8),
     pub titlebar_fg_unfocused: (u8, u8, u8),
     pub default_border_color: (u8, u8, u8),
+    /// `4`, not the `2` this used to default to - at `2`, the border
+    /// strip's own rounded-corner cut (`decoration::render_border_top`/
+    /// `_bottom`, continuing the titlebar's larger radius outward) only
+    /// ever had two rows of pixels to draw an arc into, which - even
+    /// anti-aliased (`decoration::blend_corner_pixel`) - reads as barely
+    /// more than a single soft pixel, not a curve. That's most visible on
+    /// an undecorated/CSD window (no compositor-drawn titlebar to anchor
+    /// a bigger curve nearby, Firefox concretely): reported live as
+    /// "not all windows curved". Twice the rows makes the same curve
+    /// actually legible without touching content rounding at all, which
+    /// stays a real, deliberate per-backend cost/default tradeoff (see
+    /// `rounded_corners_pixman`'s module doc comment) rather than
+    /// something to paper over with a thicker border.
     pub default_border_width: u32,
     /// Titlebar/border-strip corner radius, in logical pixels - the same
     /// value `Window::corner_radius` copies onto every window at creation
     /// (see `WindowManager::add_window`), which a rule's own `corner_radius`
     /// action can still override afterward, same as `default_border_width`.
+    /// `12`, not the original `6`: matches real macOS's own ~0.36 radius-to-
+    /// titlebar-height proportion rather than this project's original,
+    /// visibly tighter `0.2` (docs/TODO.md's macOS-comparison research).
+    /// Moves in step with `TITLEBAR_HEIGHT` (currently `32`, matched
+    /// directly against a live Firefox window) to keep that same ratio,
+    /// not a separate size decision of its own.
     pub default_corner_radius: u32,
     /// Whether a newly created window gets srdwm's own titlebar
     /// (server-side decoration) by default, before any `xdg-decoration`
@@ -45,6 +64,99 @@ pub struct ThemeConfig {
     /// examples - see `theme.decorations.default_mode` in the Lua config
     /// for the persistent equivalent.
     pub default_decorated: bool,
+    /// How much an unfocused window's border is dimmed from its own
+    /// configured colour - `1.0` keeps it identical to focused, `0.0`
+    /// removes the border entirely when unfocused. Was a hardcoded `0.35`
+    /// constant in `state::effective_border_color` with no way to change it
+    /// at all; `theme.decorations.border.inactive_dim` in the Lua config is
+    /// the first way to actually reach it, closing the exact gap
+    /// `apply_general_settings`'s own doc comment flagged (`border.
+    /// inactive_color` was left unwired because setting an *explicit*
+    /// colour would silently erase the dimming scheme for anyone who never
+    /// touched it - a *factor* on top of the same scheme has no such
+    /// footgun: the unconfigured default below reproduces the old
+    /// hardcoded behaviour exactly).
+    pub border_inactive_dim: f32,
+    /// Centers the titlebar's title text instead of the longstanding
+    /// left-aligned default - `theme.decorations.title_bar.text_align`
+    /// in the Lua config (`"center"` sets this; anything else, including
+    /// unset, keeps left-aligned). Explicitly requested as its own
+    /// config knob, not a hardcoded switch - macOS centers title text by
+    /// convention, GNOME/Windows both left-align, so neither is a
+    /// universal default worth forcing.
+    pub title_centered: bool,
+    /// Titlebar buttons on the left (macOS convention: close, minimize,
+    /// maximize, left to right) instead of the longstanding right-aligned
+    /// default (Windows/GTK convention: minimize, maximize, close) --
+    /// `theme.decorations.title_bar.button_side` in the Lua config
+    /// (`"left"` sets this; anything else, including unset, keeps
+    /// right-aligned). Researched against mutter's own `button-layout`
+    /// GSettings key before choosing this shape (one config value, not a
+    /// bespoke per-button scheme) - see `docs/TODO.md`.
+    ///
+    /// This has to stay in perfect agreement with `ResizeEdge::hit_test`'s
+    /// own `buttons_left` parameter, not just `decoration::render_titlebar`'s
+    /// rendering - a button that renders on one side but hit-tests on the
+    /// other is worse than not being configurable at all, since every
+    /// click would silently miss.
+    pub buttons_left: bool,
+    /// An explicit `close,minimize,maximize`-style override for the three
+    /// buttons' relative order, applied to whichever side `buttons_left`
+    /// already selects - `theme.decorations.button_order` in the Lua
+    /// config, parsed by `window::parse_button_order`. `None` (the
+    /// default, unset) keeps this project's own two built-in defaults
+    /// exactly as they were before this field existed.
+    ///
+    /// Added after `buttons_left`'s own doc comment above had already
+    /// deliberately chosen "one config value, not a bespoke per-button
+    /// scheme" - revisited once a real comparison against KWin's
+    /// `ButtonsOnLeft`/`ButtonsOnRight`, GNOME/Adwaita's own `decoration-
+    /// layout` (confirmed, contrary to this project's own earlier
+    /// assumption from Mutter's C source alone, to be a real per-button
+    /// ordering string, not just a fixed convention), and Openbox's
+    /// `titlelayout` found all three independently converged on exactly
+    /// this shape. Additive, not a reversal: `buttons_left` still exists
+    /// and still means what it always did.
+    pub button_order: Option<crate::window::ButtonOrder>,
+    /// The titlebar button glyph (dash/square/X) is always drawn instead
+    /// of only fading in on hover - `theme.decorations.title_bar.
+    /// button_glyph` in the Lua config (`"always"` sets this; anything
+    /// else, including unset, keeps the animated hover-reveal default).
+    ///
+    /// Researched (DE-weighted, per explicit request) before defaulting to
+    /// hover-reveal: real, extracted libadwaita CSS on this machine
+    /// (`gresource extract` on the installed `.so`, not guessed) shows
+    /// current GNOME/Adwaita actually keeps the glyph always visible and
+    /// only animates the background circle's opacity on hover - the
+    /// "always" mode here matches that. Classic macOS instead hides the
+    /// glyph entirely at rest and animates it in on hover - the default,
+    /// per this project's own explicit choice between the two once told
+    /// they're genuinely different conventions, not the same thing
+    /// assumed two different ways.
+    pub button_glyph_always: bool,
+    /// Whether the three titlebar buttons render as filled, coloured
+    /// macOS-style traffic lights, or as plain glyphs directly on the
+    /// titlebar's own background - `theme.decorations.title_bar.
+    /// button_style` in the Lua config (`"traditional"` sets this to
+    /// `false`; anything else, including unset, keeps the traffic-light
+    /// default).
+    ///
+    /// Explicitly requested as a separate axis from `buttons_left`: the
+    /// two defaulted to moving together (macOS convention is traffic
+    /// lights on the left; this project's own original look was plain
+    /// glyphs on the right), but neither implies the other - a caller can
+    /// still combine plain glyphs with left-aligned buttons or the reverse.
+    /// `false` swaps two things together, both handled in `decoration::
+    /// render_titlebar`: no `fill_button_dot` call except a subtle, neutral
+    /// hover backdrop (there's no coloured circle to brighten on hover
+    /// instead), and the glyphs themselves draw in `foreground` (this
+    /// project's original look; readable straight on the titlebar's own
+    /// dark background) rather than the near-black shade a traffic light's
+    /// own bright fill needs instead. Maximize also draws as a plain
+    /// square glyph rather than the macOS "zoom" double-arrow, matching
+    /// this convention's own (Windows/GNOME) maximize icon rather than
+    /// borrowing the other convention's.
+    pub traffic_light_buttons: bool,
 }
 
 impl Default for ThemeConfig {
@@ -54,9 +166,15 @@ impl Default for ThemeConfig {
             titlebar_fg_focused: (0x88, 0xc0, 0xd0),
             titlebar_fg_unfocused: (0x4c, 0x56, 0x6a),
             default_border_color: (136, 192, 208), // Nord accent, matches legacy theme default
-            default_border_width: 2,
-            default_corner_radius: 6,
+            default_border_width: 4,
+            default_corner_radius: 12,
             default_decorated: true,
+            border_inactive_dim: 0.35,
+            title_centered: false,
+            buttons_left: false,
+            button_order: None,
+            button_glyph_always: false,
+            traffic_light_buttons: true,
         }
     }
 }
diff --git a/crates/core/src/window.rs b/crates/core/src/window.rs
index 7df7b5c..b30cf7b 100644
--- a/crates/core/src/window.rs
+++ b/crates/core/src/window.rs
@@ -119,6 +119,31 @@ pub fn classify_menu_source(gtk_menu_path: Option<String>, is_real_gtk_applicati
     }
 }
 
+/// Whether `app_id` almost certainly belongs to an application that draws
+/// its own header bar (a `GtkHeaderBar`/`Adw.HeaderBar` widget embedded
+/// directly in its content, unconditionally) regardless of whatever
+/// `xdg-decoration` mode actually gets negotiated - see
+/// `crates/wayland/src/protocols.rs`'s `XdgDecorationHandler` doc comment
+/// for why the protocol itself can't tell such an app apart from a normal
+/// one: both Firefox and Nemo negotiate a decoration mode fine, and still
+/// draw a second title row under srdwm's server-side one regardless.
+/// Confirmed live for both (a screenshot showing two stacked bars) before
+/// either got its own `decorated = false` entry in `rules.lua`.
+///
+/// `org.gnome.*` app ids are the one case general enough to catch here
+/// instead of needing a `rules.lua` entry added for each one as it's
+/// discovered live: the GNOME HIG mandates every one of GNOME's own apps
+/// use an embedded header bar, with no exceptions, so the namespace alone
+/// is enough to know in advance. Deliberately narrow: a third-party GTK4/
+/// libadwaita app under `io.github.*`, or any other reverse-DNS scheme, is
+/// left to `rules.lua`'s per-app list instead - those toolkits don't share
+/// GNOME's HIG mandate, so guessing from the app id alone there would
+/// misclassify plenty of ordinary, well-behaved server-side-decorated apps
+/// that also happen to use a reverse-DNS-style id.
+pub fn likely_draws_own_titlebar(app_id: &str) -> bool {
+    app_id.to_ascii_lowercase().starts_with("org.gnome.")
+}
+
 /// State of a single managed window. This is platform-independent: backends
 /// (X11, Wayland, ...) own the real surface/client handle and keep a `Window`
 /// in sync with it via `srdwm_core::WindowManager`.
@@ -135,6 +160,19 @@ pub struct Window {
     /// Geometry to restore to when un-maximizing.
     pub restore_geometry: Option<Rect>,
     pub decorated: bool,
+    /// Whether this window declared an `xdg_toplevel` parent (`set_parent`)
+    /// - a dialog/utility window belonging to another one, not a normal
+    /// top-level app window. Backend-set (the wayland crate reads the real
+    /// `ToplevelSurface::parent()`, refreshed on every decoration redraw),
+    /// same as `decorated` itself; `core` has no protocol concept of its
+    /// own to derive this from. Only ever `true` for a genuine `xdg_
+    /// toplevel` client that set a parent - an XWayland dialog's own
+    /// `WM_TRANSIENT_FOR` isn't read yet, so this misses those specifically
+    /// (a real, known gap, not an oversight). Requested directly: a
+    /// dialog's titlebar should show only a close button, no traffic
+    /// lights - see `hit_test`'s and `decoration::render_titlebar`'s own
+    /// use of this for what actually changes.
+    pub is_dialog: bool,
     /// `decorated`'s value from just before entering fullscreen, restored
     /// on exit - see `WindowManager::toggle_fullscreen`'s doc comment on
     /// why this can't just hardcode `true` back.
@@ -205,6 +243,7 @@ impl Window {
             geometry: Rect::new(0, 0, 640, 480),
             restore_geometry: None,
             decorated: true,
+            is_dialog: false,
             restore_decorated: None,
             floating: false,
             minimized: false,
@@ -217,7 +256,13 @@ impl Window {
             corner_radius: 6,
             opacity: 1.0,
             resize_margin: None,
-            workspace: 0,
+            // Always overwritten by `WindowManager::add_window` before this
+            // is ever read for real (to the current workspace, or a rule's
+            // own `workspace` action) - `1`, not `0`, only because
+            // workspace ids are 1-based now (see `WindowManager::new`'s own
+            // doc comment), so this placeholder still names a workspace
+            // that could plausibly exist.
+            workspace: 1,
             monitor: 0,
             rules_applied: false,
             anim_from: None,
@@ -228,7 +273,59 @@ impl Window {
 
 /// The height, in pixels, of the drawn title bar. Shared between backends so
 /// hit-testing and rendering agree on the same band.
-pub const TITLEBAR_HEIGHT: u32 = 30;
+///
+/// `32`, measured directly against a real, live Firefox window: a
+/// side-by-side screenshot of both windows at identical scale, scanned
+/// column-by-column for the pixel row where the titlebar's own background
+/// colour gives way to the next row down (Firefox's tab strip), put that
+/// boundary at row 32 sharp. An earlier value of `38` came from a Nemo
+/// headerbar measured the same way (~40px) - Nemo's own headerbar carries
+/// extra chrome (a search/menu button row) a bare titlebar doesn't, so it
+/// isn't the right reference once Firefox is the thing actually being
+/// matched. `ThemeConfig::default_corner_radius` moves with this (see its
+/// own doc comment) to keep the same `radius / TITLEBAR_HEIGHT` ratio
+/// rather than just looking proportionally smaller on top of already being
+/// shorter.
+pub const TITLEBAR_HEIGHT: u32 = 32;
+/// The centre-to-centre spacing between titlebar buttons, and the size of
+/// the square each one's own dot/click-box is drawn/hit-tested inside --
+/// deliberately *not* the same value as `TITLEBAR_HEIGHT` (which used to
+/// double as this too). Reported live: with the two tied together, growing
+/// `TITLEBAR_HEIGHT` to `38` to match a real GTK headerbar's own *row*
+/// height also silently grew the buttons themselves to a visibly bigger
+/// scale than that same headerbar's own buttons - a real GTK/Firefox CSD
+/// row reserves generous padding above and below a comparatively compact
+/// button cluster, not one dimension sized off the other. `24`, matching a
+/// real Firefox window's own measured button-to-button spacing (via
+/// screenshot, at this system's own scale) - kept a separate constant
+/// from `TITLEBAR_HEIGHT` specifically so the two can each move for their
+/// own reason without dragging the other along. `decoration::button_box`
+/// centres this smaller box vertically inside the taller `TITLEBAR_HEIGHT`
+/// band for rendering; `ResizeEdge::hit_test` below has no matching
+/// vertical narrowing to do - a click anywhere in the titlebar's own
+/// height column-wise inside a button's `BUTTON_PITCH`-wide slice still
+/// counts as that button, the same generous-vertical-target convention
+/// every mainstream desktop already uses.
+pub const BUTTON_PITCH: u32 = 24;
+/// The gap, in pixels, between the titlebar's own edge (whichever side the
+/// button cluster renders on) and the first button's own click/draw box --
+/// measured directly against a live Firefox window: its visible dot's own
+/// left edge sits 17px in from the window's real left edge, while the
+/// button's own box margin (`decoration::BUTTON_MARGIN_LEFT`, applied to
+/// every box the same way) only accounts for 4px of that. The remaining
+/// `13` is this - a real macOS/GTK titlebar's own leading margin is
+/// visibly bigger than the gap *between* buttons, not the same value
+/// reused for both. Added once, before the first button's own `BUTTON_
+/// PITCH`-spaced offset, on whichever edge `buttons_left` selects (`decoration
+/// ::render_titlebar`'s `offset` calculation, and the matching `left`/
+/// `right` base below in `hit_test` - the two have to move together, the
+/// same "renders on one side, hit-tests on the other" trap every other
+/// button-geometry constant here already has to avoid). Before this
+/// existed, the dead strip between the titlebar's real edge and the first
+/// visible dot silently counted as a hit on that button (`hit_test`'s
+/// slice starts flush with the edge) - clicking blank titlebar background
+/// right at the corner closed the window instead of dragging it.
+pub const BUTTON_CLUSTER_MARGIN: u32 = 13;
 /// Default width, in pixels, of the resize grab band along each window
 /// edge - `WindowManager::resize_margin`'s starting value, read from
 /// `general.resize_margin`, and what every `hit_test` call in this file's
@@ -248,25 +345,53 @@ pub const TITLEBAR_HEIGHT: u32 = 30;
 /// edge back. Still configurable per the doc comment above if 6px turns
 /// out to be too little in the other direction for someone.
 pub const RESIZE_MARGIN: i32 = 6;
-/// Top-edge resize margin for an *undecorated* window specifically --
+/// Resize margin for an *undecorated* window, on every edge and corner --
 /// narrower than [`RESIZE_MARGIN`] on purpose.
 ///
-/// An undecorated (client-side-decorated) window has no titlebar band for
-/// srdwm to treat as a drag handle - Firefox's own tab strip, concretely --
-/// so the client's own header area sits directly at `frame.y` with nothing
-/// srdwm-drawn to grab. The client detects a drag on its own header and
-/// asks to be moved via `xdg_toplevel.move`, but only for clicks that
-/// actually reach it as a normal button press; the full 10px `RESIZE_MARGIN`
-/// swallowed every click within the first 10 rows of the window - including
-/// most of a typical natural grab point near the top of a tab strip - as a
-/// top-edge resize instead, so the client's own move request never fired.
-/// Reported live as "can't drag-move Firefox from its own top bar."
-/// Resize-from-the-top-edge still works (a deliberate earlier trade-off --
-/// see `undecorated_window_still_resizes_from_every_edge_including_top`'s
-/// own comment - since an undecorated window is still a window), just from
-/// a much narrower band that a click meant to grab the tab strip is very
-/// unlikely to land in by accident.
-pub const UNDECORATED_TOP_RESIZE_MARGIN: i32 = 3;
+/// An undecorated (client-side-decorated) window has no srdwm-drawn band
+/// anywhere for srdwm to treat as its own - every pixel right up to each
+/// edge is the client's real content: Firefox's tab strip at the top, its
+/// own window-control dots in a top corner, Nemo's tab-close X hard against
+/// its right edge, a minimize button nowhere near any corner at all. The
+/// full `RESIZE_MARGIN` (and, at a corner, `CORNER_MARGIN`'s further
+/// multiple of it) was tuned for a window srdwm decorates itself, where none
+/// of that applies - the whole titlebar band, buttons included, is checked
+/// before `resize_edge_at` ever runs, so widening its own resize zone never
+/// costs it a click. Applied to an undecorated window instead, that same
+/// width competed with the client's own controls for the same pixels on
+/// every edge, not just the top - first found as "can't drag-move Firefox
+/// from its own top bar" (the original, narrower-top-only version of this
+/// margin), then reported again, live, as real mouse clicks on Nemo's own
+/// tab-close and minimize buttons - one hard against the right edge, the
+/// other not even near a corner - landing "a distance" from the visible
+/// button. Resize-from-every-edge still works (a deliberate trade-off - see
+/// `undecorated_window_still_resizes_from_every_edge_including_top`'s own
+/// comment - since an undecorated window is still a window), just from a
+/// much narrower band on every side that a click meant for the client's own
+/// content is very unlikely to land in by accident. No corner-widening for
+/// an undecorated window at all: that widening exists purely to make a
+/// diagonal drag easier to land on a window srdwm itself has no competing
+/// content in, which is never true here.
+pub const UNDECORATED_RESIZE_MARGIN: i32 = 3;
+/// Top-edge resize margin for a *decorated* window's own titlebar band --
+/// unlike [`UNDECORATED_RESIZE_MARGIN`], this has no client content to
+/// avoid stealing a click from (the whole titlebar band is srdwm's own
+/// drawn UI, not the client's), so it can just reuse [`RESIZE_MARGIN`]
+/// outright rather than needing its own narrower value.
+///
+/// Reported live as a real gap, not a guess: a decorated window's titlebar
+/// had *no* top-edge resize zone at all outside the two tiny diagonal
+/// corners - every other pixel of the band, including the top row,
+/// resolved to `Drag` unconditionally - while an undecorated window
+/// (Firefox) could already be resized from its own top edge via
+/// `UNDECORATED_RESIZE_MARGIN` above. "Can't resize tmux's window from
+/// the top, but can in Firefox" was the exact live report. `hit_test`'s
+/// own decorated-titlebar branch checks a button's x-range *before* this
+/// margin, not after, so a button sitting within the first few rows of
+/// the titlebar (true for every button, since `decoration::button_box`
+/// spans nearly the full titlebar height) still always wins there --
+/// this only ever applies to the button-free part of the band.
+pub const DECORATED_TOP_RESIZE_MARGIN: i32 = RESIZE_MARGIN;
 /// How much wider than [`RESIZE_MARGIN`] a corner's own diagonal-resize
 /// zone reaches, as a multiplier on whatever margin is actually in effect
 /// - see `ResizeEdge::resize_edge_at`'s doc comment for why corners need
@@ -304,7 +429,25 @@ impl ResizeEdge {
     /// client. Resize-from-edge still applies either way: an undecorated
     /// window is still a window, and dragging its (invisible) edge to
     /// resize is still expected to work.
-    pub fn hit_test(frame: Rect, x: i32, y: i32, decorated: bool, border_width: u32, resize_margin: i32) -> Option<TitlebarHit> {
+    #[allow(clippy::too_many_arguments)]
+    pub fn hit_test(
+        frame: Rect,
+        x: i32,
+        y: i32,
+        decorated: bool,
+        border_width: u32,
+        resize_margin: i32,
+        buttons_left: bool,
+        order_override: Option<ButtonOrder>,
+        // `Window::is_dialog`'s resolved value - see its own doc comment.
+        // A dialog only ever shows/recognizes Close, never Minimize/
+        // Maximize, regardless of `order_override`; must stay in exact
+        // agreement with `decoration::render_titlebar`'s own `is_dialog`
+        // parameter, the same "renders on one side, hit-tests on the
+        // other" trap every other button-geometry value here already has
+        // to avoid.
+        is_dialog: bool,
+    ) -> Option<TitlebarHit> {
         // Border strips render *outside* `frame` (`decoration::
         // border_strips`, `border_width` pixels past each edge) - without
         // widening the containment check to match, those visible pixels
@@ -321,37 +464,110 @@ impl ResizeEdge {
             return None;
         }
         if decorated && y < frame.y + TITLEBAR_HEIGHT as i32 {
-            // The titlebar's own top-left corner pixels are still the
-            // window's outer corner - without this, a decorated window's
-            // top-left diagonal resize was completely unreachable: every y
-            // inside the titlebar band returned here unconditionally,
-            // before `resize_edge_at` (checked below, for every other edge)
-            // ever ran. A genuine small square right at the corner (both x
-            // *and* y within it), not just "close on one axis" - otherwise
-            // this would claim the whole left end of the drag area at any
-            // height within the titlebar, not just its actual corner.
+            // The titlebar's own outer corner (on whichever side doesn't
+            // hold the buttons) is still the window's outer corner --
+            // without this, a decorated window's diagonal resize there was
+            // completely unreachable: every y inside the titlebar band
+            // returned here unconditionally, before `resize_edge_at`
+            // (checked below, for every other edge) ever ran. A genuine
+            // small square right at the corner (both x *and* y within it),
+            // not just "close on one axis" - otherwise this would claim
+            // the whole drag area at any height within the titlebar, not
+            // just its actual corner.
             //
-            // The top-right corner deliberately does *not* get the same
-            // treatment: it's where the close button already lives, and
-            // every mainstream desktop's convention is that the corner of a
-            // titlebar closes the window, not resizes it. Adding a
-            // competing resize zone there would trade a real, expected
-            // target (close) for a rarely-wanted one at exactly the spot a
-            // miss is most costly.
+            // The corner *with* the buttons deliberately does not get the
+            // same treatment: every mainstream desktop's convention is
+            // that the corner of a titlebar closes the window, not
+            // resizes it - see `decoration::button_box`'s own doc
+            // comment for the matching rendering-side placement this has
+            // to agree with. Adding a competing resize zone there would
+            // trade a real, expected target (close) for a rarely-wanted
+            // one at exactly the spot a miss is most costly. `buttons_left`
+            // flips which corner gets which treatment, not just where the
+            // buttons render - the two have to move together.
             let corner_zone = CORNER_MARGIN * resize_margin;
-            if x <= frame.x + corner_zone && y <= frame.y + corner_zone {
+            if !buttons_left && x <= frame.x + corner_zone && y <= frame.y + corner_zone {
                 return Some(TitlebarHit::Resize(ResizeEdge::TopLeft));
             }
-            const BUTTON: i32 = TITLEBAR_HEIGHT as i32;
-            let right = frame.right();
-            if x >= right - BUTTON {
-                return Some(TitlebarHit::Close);
+            if buttons_left && x >= frame.right() - corner_zone && y <= frame.y + corner_zone {
+                return Some(TitlebarHit::Resize(ResizeEdge::TopRight));
+            }
+            // Box size is *not* bigger when left-aligned, even though the
+            // visible dot is (see `decoration::BUTTON_MARGIN_LEFT`) - the
+            // box is already capped at `BUTTON_PITCH` vertically by
+            // `decoration::button_box`'s own centring, so a genuinely
+            // bigger *box* would draw a dot that gets clipped top/bottom
+            // against it. A bigger dot within the same click box gets the
+            // requested "bigger" look with no such clipping risk, and
+            // keeps this hit-test box in exact agreement with `decoration::
+            // button_box`'s own size, not just its side. `BUTTON_PITCH`,
+            // not `TITLEBAR_HEIGHT` - see that constant's own doc comment
+            // for why the two aren't the same value.
+            let button: i32 = BUTTON_PITCH as i32;
+            // Closest-to-the-aligned-edge first - see `ButtonOrder`'s own
+            // doc comment for why the two built-in defaults are genuinely
+            // different relative orderings, not mirrors of each other,
+            // and why an explicit override applies identically regardless
+            // of side rather than trying to preserve that asymmetry.
+            // A dialog always recognizes Close, full stop - not just
+            // whichever button an `order_override` would otherwise put
+            // first, or Minimize/Maximize could still end up the one hit-
+            // testable button. Matches `decoration::render_titlebar`'s own
+            // identical override for the same reason.
+            let order: ButtonOrder = if is_dialog {
+                [TitlebarButton::Close; 3]
+            } else {
+                order_override.unwrap_or(if buttons_left {
+                    [TitlebarButton::Close, TitlebarButton::Minimize, TitlebarButton::Maximize]
+                } else {
+                    [TitlebarButton::Close, TitlebarButton::Maximize, TitlebarButton::Minimize]
+                })
+            };
+            // A dialog only ever recognizes the first slot, matching
+            // `decoration::render_titlebar` only ever drawing the one
+            // button there too.
+            let button_count = if is_dialog { 1 } else { 3 };
+            if buttons_left {
+                let left = frame.x + BUTTON_CLUSTER_MARGIN as i32;
+                // `x >= left` excludes the dead `BUTTON_CLUSTER_MARGIN`
+                // strip between the titlebar's real edge and the first
+                // button - without this guard, `x < left + button` (the
+                // first iteration below) is trivially true for any `x`
+                // left of `left` too, so that whole blank strip silently
+                // counted as a Close hit.
+                if x >= left {
+                    for (i, b) in order.iter().take(button_count).enumerate() {
+                        if x < left + button * (i as i32 + 1) {
+                            return Some(match b {
+                                TitlebarButton::Close => TitlebarHit::Close,
+                                TitlebarButton::Minimize => TitlebarHit::Minimize,
+                                TitlebarButton::Maximize => TitlebarHit::Maximize,
+                            });
+                        }
+                    }
+                }
+                if y <= frame.y + DECORATED_TOP_RESIZE_MARGIN {
+                    return Some(TitlebarHit::Resize(ResizeEdge::Top));
+                }
+                return Some(TitlebarHit::Drag);
             }
-            if x >= right - BUTTON * 2 {
-                return Some(TitlebarHit::Maximize);
+            let right = frame.right() - BUTTON_CLUSTER_MARGIN as i32;
+            // Same guard, mirrored: `x <= right` excludes the dead strip
+            // between the first (rightmost) button and the titlebar's real
+            // right edge.
+            if x <= right {
+                for (i, b) in order.iter().take(button_count).enumerate() {
+                    if x >= right - button * (i as i32 + 1) {
+                        return Some(match b {
+                            TitlebarButton::Close => TitlebarHit::Close,
+                            TitlebarButton::Minimize => TitlebarHit::Minimize,
+                            TitlebarButton::Maximize => TitlebarHit::Maximize,
+                        });
+                    }
+                }
             }
-            if x >= right - BUTTON * 3 {
-                return Some(TitlebarHit::Minimize);
+            if y <= frame.y + DECORATED_TOP_RESIZE_MARGIN {
+                return Some(TitlebarHit::Resize(ResizeEdge::Top));
             }
             return Some(TitlebarHit::Drag);
         }
@@ -360,27 +576,24 @@ impl ResizeEdge {
     }
 
     fn resize_edge_at(frame: Rect, x: i32, y: i32, decorated: bool, resize_margin: i32) -> Option<ResizeEdge> {
-        let m = resize_margin;
-        let top_m = if decorated { m } else { UNDECORATED_TOP_RESIZE_MARGIN };
-
         // A corner resize gets a bigger, prioritized hit zone than a plain
-        // single edge, checked first - a diagonal drag is a harder target
-        // to land than a straight edge, and several desktops (GNOME, KDE)
-        // give it noticeably more room for exactly that reason. Reported
-        // live: corners felt like they had no priority over sides at all,
-        // which tracked - a corner previously only registered in the exact
-        // pixel square where both edges' own `resize_margin` zones happened
-        // to overlap (6x6px at the default margin), nothing wider.
-        // `corner_top_m` still respects the undecorated window's much
-        // narrower top reach (`UNDECORATED_TOP_RESIZE_MARGIN`) rather than
-        // widening it too - this must not reopen the "can't grab Firefox's
-        // tab strip" bug near a top corner, only the horizontal reach grows
-        // there.
-        let corner_m = CORNER_MARGIN * m;
-        let corner_top_m = if decorated { corner_m } else { UNDECORATED_TOP_RESIZE_MARGIN };
+        // single edge for a *decorated* window - a diagonal drag is a
+        // harder target to land than a straight edge, and several desktops
+        // (GNOME, KDE) give it noticeably more room for exactly that reason.
+        // Reported live: corners felt like they had no priority over sides
+        // at all, which tracked - a corner previously only registered in
+        // the exact pixel square where both edges' own `resize_margin` zones
+        // happened to overlap (6x6px at the default margin), nothing wider.
+        //
+        // None of that widening applies to an *undecorated* window, on any
+        // edge or corner - see [`UNDECORATED_RESIZE_MARGIN`]'s own doc
+        // comment for why a single small, uniform margin is what's actually
+        // correct there.
+        let (m, corner_m) = if decorated { (resize_margin, CORNER_MARGIN * resize_margin) } else { (UNDECORATED_RESIZE_MARGIN, UNDECORATED_RESIZE_MARGIN) };
+
         let corner_left = x <= frame.x + corner_m;
         let corner_right = x >= frame.right() - corner_m;
-        let corner_top = y <= frame.y + corner_top_m;
+        let corner_top = y <= frame.y + corner_m;
         let corner_bottom = y >= frame.bottom() - corner_m;
         if corner_left && corner_top {
             return Some(ResizeEdge::TopLeft);
@@ -397,7 +610,7 @@ impl ResizeEdge {
 
         let near_left = x <= frame.x + m;
         let near_right = x >= frame.right() - m;
-        let near_top = y <= frame.y + top_m;
+        let near_top = y <= frame.y + m;
         let near_bottom = y >= frame.bottom() - m;
         match (near_left, near_right, near_top, near_bottom) {
             (true, false, false, false) => Some(ResizeEdge::Left),
@@ -455,6 +668,112 @@ pub enum TitlebarHit {
     Resize(ResizeEdge),
 }
 
+/// One of the three titlebar buttons, for [`ButtonOrder`] - a narrower
+/// type than [`TitlebarHit`] on purpose: `TitlebarHit` also carries
+/// `Drag`/`Resize`, neither of which is a button a layout can place.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TitlebarButton {
+    Close,
+    Minimize,
+    Maximize,
+}
+
+/// A custom `close,minimize,maximize`-style ordering for the three
+/// titlebar buttons, overriding this project's own default order for
+/// whichever side `buttons_left` already selects - KWin's `ButtonsOnLeft`/
+/// `ButtonsOnRight`, GNOME/Adwaita's `decoration-layout`, and Openbox's
+/// `titlelayout` each independently converged on exactly this "ordered
+/// list of button names" idea, confirmed this session by reading each
+/// project's own real config docs/source rather than assuming.
+///
+/// Positions are read closest-to-the-aligned-edge first, same as this
+/// project's own two built-in defaults already are: on the left, index 0
+/// sits at the window's own left edge; on the right, index 0 sits at the
+/// window's own right edge. This project's two defaults (macOS-style
+/// close-minimize-maximize on the left, Windows/GTK-style close-maximize-
+/// minimize on the right) are genuinely different *relative* orderings,
+/// not mirrors of each other - seem `hit_test`'s own doc comment on why
+/// that's deliberate - so `None` (the default, no override configured)
+/// keeps using whichever of those two already applies rather than this
+/// type imposing one order on both sides.
+pub type ButtonOrder = [TitlebarButton; 3];
+
+/// Parses a `srd.set("theme.decorations.button_order", "...")` value like
+/// `"close,minimize,maximize"` into a [`ButtonOrder`] - `None` if it
+/// doesn't name each of the three buttons exactly once (a typo'd or
+/// partial list falls back to this project's own built-in default rather
+/// than silently hiding a button or drawing one twice).
+pub fn parse_button_order(s: &str) -> Option<ButtonOrder> {
+    let mut close = None;
+    let mut minimize = None;
+    let mut maximize = None;
+    for (i, part) in s.split(',').map(str::trim).enumerate() {
+        match part.to_ascii_lowercase().as_str() {
+            "close" => close = Some(i),
+            "minimize" | "minimise" => minimize = Some(i),
+            "maximize" | "maximise" => maximize = Some(i),
+            _ => return None,
+        }
+    }
+    let (Some(c), Some(mn), Some(mx)) = (close, minimize, maximize) else { return None };
+    let mut order = [TitlebarButton::Close; 3];
+    for (slot, button) in [(c, TitlebarButton::Close), (mn, TitlebarButton::Minimize), (mx, TitlebarButton::Maximize)] {
+        if slot >= 3 {
+            return None;
+        }
+        order[slot] = button;
+    }
+    // Every slot must have been assigned exactly once - three distinct
+    // source indices (0, 1, 2) covering three slots guarantees that; a
+    // repeated button name (e.g. "close,close,maximize") would have
+    // reused one slot index and left another unset, which range 0..3
+    // alone can't catch.
+    let mut seen = [false; 3];
+    for i in [c, mn, mx] {
+        if seen[i] {
+            return None;
+        }
+        seen[i] = true;
+    }
+    Some(order)
+}
+
+#[cfg(test)]
+mod button_order_tests {
+    use super::*;
+
+    #[test]
+    fn parses_a_well_formed_order() {
+        assert_eq!(parse_button_order("close,minimize,maximize"), Some([TitlebarButton::Close, TitlebarButton::Minimize, TitlebarButton::Maximize]));
+        assert_eq!(parse_button_order("maximize,minimize,close"), Some([TitlebarButton::Maximize, TitlebarButton::Minimize, TitlebarButton::Close]));
+    }
+
+    #[test]
+    fn is_case_insensitive_and_trims_whitespace() {
+        assert_eq!(parse_button_order(" Close, MINIMIZE ,Maximize"), Some([TitlebarButton::Close, TitlebarButton::Minimize, TitlebarButton::Maximize]));
+    }
+
+    #[test]
+    fn accepts_the_british_spelling() {
+        assert_eq!(parse_button_order("close,minimise,maximise"), Some([TitlebarButton::Close, TitlebarButton::Minimize, TitlebarButton::Maximize]));
+    }
+
+    #[test]
+    fn rejects_a_missing_button() {
+        assert_eq!(parse_button_order("close,minimize"), None);
+    }
+
+    #[test]
+    fn rejects_a_duplicated_button() {
+        assert_eq!(parse_button_order("close,close,maximize"), None);
+    }
+
+    #[test]
+    fn rejects_an_unknown_token() {
+        assert_eq!(parse_button_order("close,minimize,help"), None);
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -499,29 +818,99 @@ mod tests {
     #[test]
     fn close_button_is_top_right_corner_of_titlebar() {
         let f = frame();
-        let hit = ResizeEdge::hit_test(f, f.right() - 5, f.y + 5, true, 0, RESIZE_MARGIN);
+        // `BUTTON_CLUSTER_MARGIN` back from the edge, not just `- 5`: that
+        // margin is a real dead strip now (see its own doc comment) - a
+        // point only `5` in from the raw edge landed inside it, not on the
+        // button.
+        let hit = ResizeEdge::hit_test(f, f.right() - BUTTON_CLUSTER_MARGIN as i32 - 5, f.y + 5, true, 0, RESIZE_MARGIN, false, None, false);
         assert_eq!(hit, Some(TitlebarHit::Close));
     }
 
     #[test]
     fn maximize_is_left_of_close() {
         let f = frame();
-        let hit = ResizeEdge::hit_test(f, f.right() - TITLEBAR_HEIGHT as i32 - 5, f.y + 5, true, 0, RESIZE_MARGIN);
+        let hit = ResizeEdge::hit_test(f, f.right() - BUTTON_CLUSTER_MARGIN as i32 - BUTTON_PITCH as i32 - 5, f.y + 5, true, 0, RESIZE_MARGIN, false, None, false);
         assert_eq!(hit, Some(TitlebarHit::Maximize));
     }
 
     #[test]
+    fn a_dialog_only_ever_recognizes_close_not_minimize_or_maximize() {
+        // The whole point of `is_dialog`: the same point that hits Maximize
+        // for a normal window (see `maximize_is_left_of_close` just above)
+        // must not hit anything at all for a dialog - that button was
+        // never drawn there in the first place (`decoration::
+        // render_titlebar`'s own `is_dialog` branch), so a phantom hit zone
+        // there would be exactly the "click does nothing, or worse, hits
+        // the wrong control" bug this codebase already fixed once for
+        // undecorated windows.
+        let f = frame();
+        let maximize_spot = f.right() - BUTTON_CLUSTER_MARGIN as i32 - BUTTON_PITCH as i32 - 5;
+        let hit = ResizeEdge::hit_test(f, maximize_spot, f.y + 5, true, 0, RESIZE_MARGIN, false, None, true);
+        assert_ne!(hit, Some(TitlebarHit::Maximize), "a dialog must not have a Maximize hit zone at all");
+        assert_ne!(hit, Some(TitlebarHit::Minimize), "a dialog must not have a Minimize hit zone at all");
+        // The one real button (Close) must still be exactly where it always
+        // is - `is_dialog` removes the other two, not shifts this one.
+        let close_hit = ResizeEdge::hit_test(f, f.right() - BUTTON_CLUSTER_MARGIN as i32 - 5, f.y + 5, true, 0, RESIZE_MARGIN, false, None, true);
+        assert_eq!(close_hit, Some(TitlebarHit::Close));
+    }
+
+    #[test]
+    fn a_dialog_recognizes_close_even_with_a_button_order_override_that_does_not_start_with_it() {
+        // An explicit `button_order` still must not be able to put
+        // Minimize/Maximize where a dialog's one real button (Close) is --
+        // see `hit_test`'s own doc comment on why `is_dialog` ignores
+        // `order_override` outright rather than just capping how many of
+        // it get used.
+        let f = frame();
+        let order = [TitlebarButton::Maximize, TitlebarButton::Minimize, TitlebarButton::Close];
+        let hit = ResizeEdge::hit_test(f, f.right() - BUTTON_CLUSTER_MARGIN as i32 - 5, f.y + 5, true, 0, RESIZE_MARGIN, false, Some(order), true);
+        assert_eq!(hit, Some(TitlebarHit::Close));
+    }
+
+    #[test]
+    fn an_explicit_button_order_moves_the_hit_zones_to_match() {
+        // Same point `maximize_is_left_of_close` above hits as Maximize
+        // under the built-in default - an override putting minimize
+        // there instead must change what a click there actually does,
+        // not just what gets drawn.
+        let f = frame();
+        let order = [TitlebarButton::Close, TitlebarButton::Minimize, TitlebarButton::Maximize];
+        let hit = ResizeEdge::hit_test(f, f.right() - BUTTON_CLUSTER_MARGIN as i32 - BUTTON_PITCH as i32 - 5, f.y + 5, true, 0, RESIZE_MARGIN, false, Some(order), false);
+        assert_eq!(hit, Some(TitlebarHit::Minimize));
+    }
+
+    #[test]
+    fn a_button_order_override_applies_the_same_way_on_either_side() {
+        // The whole point of an explicit override: unlike the two built-
+        // in defaults (genuinely different relative orderings per side,
+        // see `ButtonOrder`'s own doc comment), a caller-specified order
+        // reads closest-to-edge-first the same way whichever side it's
+        // on.
+        let f = frame();
+        let order = [TitlebarButton::Maximize, TitlebarButton::Minimize, TitlebarButton::Close];
+        let left_hit = ResizeEdge::hit_test(f, f.x + BUTTON_CLUSTER_MARGIN as i32 + 5, f.y + 5, true, 0, RESIZE_MARGIN, true, Some(order), false);
+        let right_hit = ResizeEdge::hit_test(f, f.right() - BUTTON_CLUSTER_MARGIN as i32 - 5, f.y + 5, true, 0, RESIZE_MARGIN, false, Some(order), false);
+        assert_eq!(left_hit, Some(TitlebarHit::Maximize));
+        assert_eq!(right_hit, Some(TitlebarHit::Maximize));
+    }
+
+    #[test]
     fn middle_of_titlebar_is_drag() {
+        // Past `DECORATED_TOP_RESIZE_MARGIN`, not just `f.y + 5` (this
+        // test's original y) - once the titlebar's own thin top edge
+        // gained a resize zone, a point that shallow no longer tests
+        // "plain drag area" at all. See `decorated_window_very_top_edge_
+        // of_titlebar_resizes_not_drags` for that zone's own coverage.
         let f = frame();
         let (cx, _) = f.center();
-        let hit = ResizeEdge::hit_test(f, cx, f.y + 5, true, 0, RESIZE_MARGIN);
+        let hit = ResizeEdge::hit_test(f, cx, f.y + DECORATED_TOP_RESIZE_MARGIN + 5, true, 0, RESIZE_MARGIN, false, None, false);
         assert_eq!(hit, Some(TitlebarHit::Drag));
     }
 
     #[test]
     fn bottom_right_corner_is_resize() {
         let f = frame();
-        let hit = ResizeEdge::hit_test(f, f.right() - 1, f.bottom() - 1, true, 0, RESIZE_MARGIN);
+        let hit = ResizeEdge::hit_test(f, f.right() - 1, f.bottom() - 1, true, 0, RESIZE_MARGIN, false, None, false);
         assert_eq!(hit, Some(TitlebarHit::Resize(ResizeEdge::BottomRight)));
     }
 
@@ -538,7 +927,7 @@ mod tests {
         // outside RESIZE_MARGIN, so a real resize edge can't also explain a
         // `None` here - undecorated, this must not be treated as
         // decoration (or a resize edge) at all, just plain content.
-        let hit = ResizeEdge::hit_test(f, cx, f.y + 20, false, 0, RESIZE_MARGIN);
+        let hit = ResizeEdge::hit_test(f, cx, f.y + 20, false, 0, RESIZE_MARGIN, false, None, false);
         assert_eq!(hit, None);
     }
 
@@ -546,7 +935,7 @@ mod tests {
     fn undecorated_window_still_resizes_from_every_edge_including_top() {
         let f = frame();
         let (cx, _) = f.center();
-        let hit = ResizeEdge::hit_test(f, cx, f.y + 1, false, 0, RESIZE_MARGIN);
+        let hit = ResizeEdge::hit_test(f, cx, f.y + 1, false, 0, RESIZE_MARGIN, false, None, false);
         assert_eq!(hit, Some(TitlebarHit::Resize(ResizeEdge::Top)));
     }
 
@@ -557,23 +946,64 @@ mod tests {
         // click meant to drag-move it via the client's own `xdg_toplevel.
         // move` has to actually reach the client - the full `RESIZE_MARGIN`
         // (10px) swallowed most of a natural grab point near the top as a
-        // resize instead. A *decorated* window's top band is unaffected --
-        // it already has TITLEBAR_HEIGHT worth of unambiguous drag space
-        // above where `RESIZE_MARGIN` even starts to matter.
+        // resize instead. A *decorated* window's own top band gained a
+        // matching (if wider) resize margin of its own since this test was
+        // first written - see `DECORATED_TOP_RESIZE_MARGIN`'s own doc
+        // comment - so this now checks *past* both margins, where the two
+        // must still agree (undecorated: reaches the client; decorated:
+        // plain drag), rather than claiming the decorated band has no top
+        // resize zone at all, which is no longer true.
         let f = frame();
         let (cx, _) = f.center();
-        assert_eq!(ResizeEdge::hit_test(f, cx, f.y + 5, false, 0, RESIZE_MARGIN), None, "5px in: past the narrow undecorated band, must reach the client");
+        assert_eq!(ResizeEdge::hit_test(f, cx, f.y + 5, false, 0, RESIZE_MARGIN, false, None, false), None, "5px in: past the narrow undecorated band, must reach the client");
         assert_eq!(
-            ResizeEdge::hit_test(f, cx, f.y + 5, true, 0, RESIZE_MARGIN),
+            ResizeEdge::hit_test(f, cx, f.y + DECORATED_TOP_RESIZE_MARGIN + 5, true, 0, RESIZE_MARGIN, false, None, false),
             Some(TitlebarHit::Drag),
-            "decorated: 5px in is still well inside the titlebar band, not a resize edge"
+            "decorated: past its own (wider) top resize margin, still plain drag"
         );
     }
 
     #[test]
+    fn undecorated_corner_resize_is_not_widened_either() {
+        // Same regression as the top-margin test above, but for a corner --
+        // a real live report was a click on Nemo's own tab-close button,
+        // hard against the window's right edge, near the top, landing on a
+        // phantom resize instead of the client. This point is well past
+        // `UNDECORATED_RESIZE_MARGIN` (3px) on both axes but was still
+        // within the old, decorated-window-sized corner zone
+        // (`CORNER_MARGIN * RESIZE_MARGIN` = 18px) before this fix.
+        let f = frame();
+        let hit = ResizeEdge::hit_test(f, f.right() - 10, f.y + 10, false, 0, RESIZE_MARGIN, false, None, false);
+        assert_eq!(hit, None, "past the narrow undecorated corner margin on both axes, must reach the client");
+    }
+
+    #[test]
+    fn undecorated_bottom_right_corner_also_uses_the_narrow_margin() {
+        // The top corners aren't the only ones a CSD client can draw real
+        // content near - nothing about `CORNER_MARGIN`'s widening should
+        // survive for an undecorated window at any corner.
+        let f = frame();
+        let hit = ResizeEdge::hit_test(f, f.right() - 10, f.bottom() - 10, false, 0, RESIZE_MARGIN, false, None, false);
+        assert_eq!(hit, None, "past the narrow undecorated corner margin on both axes, must reach the client");
+    }
+
+    #[test]
+    fn undecorated_window_resizes_from_right_and_bottom_edges_within_the_narrow_margin() {
+        // Confirms the narrow margin is still a real, working resize zone on
+        // every edge, not just the top - this fix must not trade "buttons
+        // near an edge are clickable" for "can't resize from that edge at
+        // all".
+        let f = frame();
+        let (_, cy) = f.center();
+        let (cx, _) = f.center();
+        assert_eq!(ResizeEdge::hit_test(f, f.right() - 1, cy, false, 0, RESIZE_MARGIN, false, None, false), Some(TitlebarHit::Resize(ResizeEdge::Right)));
+        assert_eq!(ResizeEdge::hit_test(f, cx, f.bottom() - 1, false, 0, RESIZE_MARGIN, false, None, false), Some(TitlebarHit::Resize(ResizeEdge::Bottom)));
+    }
+
+    #[test]
     fn outside_frame_is_none() {
         let f = frame();
-        assert_eq!(ResizeEdge::hit_test(f, 0, 0, true, 0, RESIZE_MARGIN), None);
+        assert_eq!(ResizeEdge::hit_test(f, 0, 0, true, 0, RESIZE_MARGIN, false, None, false), None);
     }
 
     #[test]
@@ -588,16 +1018,16 @@ mod tests {
         let border_width = 2;
         // One pixel into the border strip, past the left edge.
         let x = f.x - 1;
-        assert_eq!(ResizeEdge::hit_test(f, x, cy, true, 0, RESIZE_MARGIN), None, "sanity check: with no border, this point really is outside the window");
+        assert_eq!(ResizeEdge::hit_test(f, x, cy, true, 0, RESIZE_MARGIN, false, None, false), None, "sanity check: with no border, this point really is outside the window");
         assert_eq!(
-            ResizeEdge::hit_test(f, x, cy, true, border_width, RESIZE_MARGIN),
+            ResizeEdge::hit_test(f, x, cy, true, border_width, RESIZE_MARGIN, false, None, false),
             Some(TitlebarHit::Resize(ResizeEdge::Left)),
             "one pixel into the actual drawn border must still register as the left edge"
         );
         // Just past the border entirely (border_width + 1 outside frame) is
         // still nothing - the fix widens the dead zone's boundary, it
         // doesn't remove it.
-        assert_eq!(ResizeEdge::hit_test(f, f.x - border_width as i32 - 1, cy, true, border_width, RESIZE_MARGIN), None);
+        assert_eq!(ResizeEdge::hit_test(f, f.x - border_width as i32 - 1, cy, true, border_width, RESIZE_MARGIN, false, None, false), None);
     }
 
     #[test]
@@ -614,7 +1044,7 @@ mod tests {
         assert!(corner_reach > RESIZE_MARGIN, "the whole point of this test is that corner reach exceeds a plain edge's");
         let x = f.x + corner_reach - 1;
         let y = f.bottom() - corner_reach + 1;
-        assert_eq!(ResizeEdge::hit_test(f, x, y, true, 0, RESIZE_MARGIN), Some(TitlebarHit::Resize(ResizeEdge::BottomLeft)));
+        assert_eq!(ResizeEdge::hit_test(f, x, y, true, 0, RESIZE_MARGIN, false, None, false), Some(TitlebarHit::Resize(ResizeEdge::BottomLeft)));
     }
 
     #[test]
@@ -625,7 +1055,7 @@ mod tests {
         // - must read as a plain bottom edge, not a corner.
         let x = f.x + corner_reach + 5;
         let y = f.bottom() - 1;
-        assert_eq!(ResizeEdge::hit_test(f, x, y, true, 0, RESIZE_MARGIN), Some(TitlebarHit::Resize(ResizeEdge::Bottom)));
+        assert_eq!(ResizeEdge::hit_test(f, x, y, true, 0, RESIZE_MARGIN, false, None, false), Some(TitlebarHit::Resize(ResizeEdge::Bottom)));
     }
 
     #[test]
@@ -636,7 +1066,7 @@ mod tests {
         // `resize_edge_at` never even ran for a y inside the titlebar.
         let f = frame();
         let corner_reach = CORNER_MARGIN * RESIZE_MARGIN;
-        let hit = ResizeEdge::hit_test(f, f.x + corner_reach - 1, f.y + corner_reach - 1, true, 0, RESIZE_MARGIN);
+        let hit = ResizeEdge::hit_test(f, f.x + corner_reach - 1, f.y + corner_reach - 1, true, 0, RESIZE_MARGIN, false, None, false);
         assert_eq!(hit, Some(TitlebarHit::Resize(ResizeEdge::TopLeft)));
     }
 
@@ -647,7 +1077,52 @@ mod tests {
         // convention, rather than competing with a resize zone at exactly
         // the spot a miss is most costly.
         let f = frame();
-        let hit = ResizeEdge::hit_test(f, f.right() - 1, f.y + 1, true, 0, RESIZE_MARGIN);
+        // Just inside `BUTTON_CLUSTER_MARGIN`, not the raw corner pixel --
+        // the raw corner itself now sits in that real dead strip (see its
+        // own doc comment), which correctly falls through to drag/resize,
+        // not Close.
+        let hit = ResizeEdge::hit_test(f, f.right() - BUTTON_CLUSTER_MARGIN as i32 - 1, f.y + 1, true, 0, RESIZE_MARGIN, false, None, false);
+        assert_eq!(hit, Some(TitlebarHit::Close));
+    }
+
+    #[test]
+    fn decorated_window_very_top_edge_of_titlebar_resizes_not_drags() {
+        // The actual regression: reported live as "can't resize tmux's
+        // window from the top, but can in Firefox" - a decorated window's
+        // titlebar band claimed *every* button-free pixel as `Drag`
+        // unconditionally, with no top-edge resize zone at all outside the
+        // two tiny diagonal corners, unlike an undecorated window's own
+        // (narrower) top-edge margin. `x` is the titlebar's horizontal
+        // middle, clear of both the corner zones and either side's button
+        // boxes, so this is testing the plain top edge specifically.
+        let f = frame();
+        let x = f.x + f.width as i32 / 2;
+        let hit = ResizeEdge::hit_test(f, x, f.y + DECORATED_TOP_RESIZE_MARGIN - 1, true, 0, RESIZE_MARGIN, false, None, false);
+        assert_eq!(hit, Some(TitlebarHit::Resize(ResizeEdge::Top)));
+    }
+
+    #[test]
+    fn decorated_window_titlebar_below_the_top_margin_still_drags() {
+        // Sanity check for the fix above: only the thin top margin itself
+        // gained a resize zone - the rest of the titlebar (where most
+        // real drags actually start) must still read as `Drag`, not have
+        // silently grown a resize zone everywhere.
+        let f = frame();
+        let x = f.x + f.width as i32 / 2;
+        let hit = ResizeEdge::hit_test(f, x, f.y + DECORATED_TOP_RESIZE_MARGIN + 5, true, 0, RESIZE_MARGIN, false, None, false);
+        assert_eq!(hit, Some(TitlebarHit::Drag));
+    }
+
+    #[test]
+    fn decorated_window_top_edge_over_a_button_still_hits_the_button() {
+        // The other half of the fix: the new top-margin resize zone must
+        // not swallow clicks meant for a button just because that button
+        // also happens to sit within the first few rows of the titlebar --
+        // exactly the "buttons... not swallowing" risk this was written to
+        // avoid. Right-aligned close button's box starts at `right - 30`;
+        // well inside it, at the very top row.
+        let f = frame();
+        let hit = ResizeEdge::hit_test(f, f.right() - 15, f.y + 1, true, 0, RESIZE_MARGIN, false, None, false);
         assert_eq!(hit, Some(TitlebarHit::Close));
     }
 
diff --git a/crates/ctl/Cargo.toml b/crates/ctl/Cargo.toml
index bd8f72b..f80fcc9 100644
--- a/crates/ctl/Cargo.toml
+++ b/crates/ctl/Cargo.toml
@@ -15,3 +15,6 @@ path = "src/main.rs"
 # to run - see `socket_path()`'s doc comment. Deliberately still no JSON
 # dependency of its own; that stays server-side.
 srdwm-platform.workspace = true
+# Only for restoring default SIGPIPE disposition at startup - see `main`'s
+# own doc comment on why `srd subscribe` needs this.
+libc = "0.2"
diff --git a/crates/ctl/src/main.rs b/crates/ctl/src/main.rs
index a22477c..8ed6d2f 100644
--- a/crates/ctl/src/main.rs
+++ b/crates/ctl/src/main.rs
@@ -7,14 +7,17 @@
 //! Usage:
 //!   srd clients                        list windows, one JSON object
 //!   srd workspaces                     list workspaces, one JSON object
+//!   srd settings                       current shadows/rounded_corners/
+//!                                       animations/night_light/reading_mode
+//!                                       state, one JSON object
 //!   srd keyboard layout                active XKB layout name, one JSON object
 //!   srd subscribe                      like `clients`, then one JSON
 //!                                       object per line forever, each time
-//!                                       the window list, workspace list, or
-//!                                       keyboard layout actually changes
-//!                                       (one "clients"/"workspaces"/
-//!                                       "keyboard_layout"-tagged line per
-//!                                       event)
+//!                                       the window list, workspace list,
+//!                                       keyboard layout, or monitor list
+//!                                       actually changes (one "clients"/
+//!                                       "workspaces"/"keyboard_layout"/
+//!                                       "monitors"-tagged line per event)
 //!
 //! `dispatch` reads as a real verb phrase, not a joined identifier --
 //! `toggle floating`, not `toggle_floating`. Multi-word actions are
@@ -32,6 +35,14 @@
 //!   srd dispatch move workspace ID WORKSPACE
 //!   srd dispatch activate workspace ID
 //!   srd dispatch cycle keyboard layout  no ID - there's only ever one keyboard
+//!   srd dispatch set output position NAME|ID X Y   NAME (e.g. HDMI-A-1, as
+//!                                    `srd monitors` reports it) or a plain
+//!                                    numeric id, either works
+//!   srd dispatch set output enabled NAME|ID true|false   real DRM power
+//!                                    state, not just hiding it - a
+//!                                    disabled output stops presenting
+//!                                    and its `wl_output` global goes away
+//!                                    until re-enabled
 //!   srd set border_width 3          live theme values, applied immediately
 //!   srd set border_color '#cba6f7'  (hex string)
 //!   srd set corner_radius 10
@@ -39,6 +50,11 @@
 //!   srd set gap_outer 16
 //!   srd set shadows true
 //!   srd set rounded_corners true
+//!   srd set animations true
+//!   srd set night_light true        warm tint; false clears it regardless
+//!   srd set reading_mode true       desaturating tint; same "false clears
+//!                                    either" rule - `srd settings` reads
+//!                                    back which one (if any) is active
 //!   srd set decoration_mode server|client
 //!
 //! The socket is Unix-domain; on platforms without one this always fails
@@ -47,6 +63,22 @@
 
 #[cfg(unix)]
 fn main() {
+    // Rust masks SIGPIPE to SIG_IGN at process startup (so a write past a
+    // closed pipe/socket surfaces as a normal `Err`, not a silent kill) --
+    // restoring the default here (SIG_DFL) is what a well-behaved Unix CLI
+    // tool is expected to do, since `srd subscribe`'s whole design is
+    // printing one line per event forever until its reader goes away.
+    // Without this, that reader closing (AGS quitting, a piped `head -1`,
+    // anything) doesn't kill this process the normal Unix way - instead
+    // the next `println!` gets `Err(BrokenPipe)`, and `std::io::stdio::
+    // _print` panics on that rather than returning it, so the process dies
+    // through a Rust unwind/abort instead of the expected SIGPIPE. Caught
+    // live: a peer session's AGS instance running `srd subscribe` as a
+    // long-lived child over a stdout pipe hit exactly this panic every
+    // single time it quit.
+    unsafe {
+        libc::signal(libc::SIGPIPE, libc::SIG_DFL);
+    }
     let args: Vec<String> = std::env::args().skip(1).collect();
     let request = match build_request(&args) {
         Ok(r) => r,
@@ -106,6 +138,7 @@ fn build_request(args: &[String]) -> Result<String, String> {
         Some("clients") => Ok(r#"{"cmd":"clients"}"#.to_string()),
         Some("monitors") => Ok(r#"{"cmd":"monitors"}"#.to_string()),
         Some("workspaces") => Ok(r#"{"cmd":"workspaces"}"#.to_string()),
+        Some("settings") => Ok(r#"{"cmd":"settings"}"#.to_string()),
         Some("keyboard") if args.get(1).map(String::as_str) == Some("layout") => Ok(r#"{"cmd":"keyboard_layout"}"#.to_string()),
         Some("keyboard") => Err("did you mean 'srd keyboard layout'?".to_string()),
         Some("subscribe") => Ok(r#"{"cmd":"subscribe"}"#.to_string()),
@@ -144,15 +177,15 @@ fn build_request(args: &[String]) -> Result<String, String> {
         // need to land unquoted for the server's `as_bool()` to see them
         // as booleans at all, not a string it then has to reject.
         Some("set") => {
-            let key = args
-                .get(1)
-                .ok_or("set needs a key (border_width/border_color/corner_radius/gap_inner/gap_outer/shadows/rounded_corners/decoration_mode)")?;
+            let key = args.get(1).ok_or(
+                "set needs a key (border_width/border_color/corner_radius/gap_inner/gap_outer/shadows/rounded_corners/animations/night_light/reading_mode/decoration_mode)",
+            )?;
             let raw = args.get(2).ok_or("set needs a value")?;
             let value = match key.as_str() {
                 "border_width" | "corner_radius" | "gap_inner" | "gap_outer" => {
                     raw.parse::<u64>().map_err(|_| format!("{key} needs a numeric value"))?.to_string()
                 }
-                "shadows" | "rounded_corners" => match raw.as_str() {
+                "shadows" | "rounded_corners" | "animations" | "night_light" | "reading_mode" => match raw.as_str() {
                     "true" | "false" => raw.clone(),
                     _ => return Err(format!("{key} needs 'true' or 'false'")),
                 },
@@ -166,7 +199,7 @@ fn build_request(args: &[String]) -> Result<String, String> {
             Ok(format!(r#"{{"cmd":"set","key":"{key}","value":{value}}}"#))
         }
         _ => Err(
-            "expected 'clients', 'monitors', 'workspaces', 'keyboard layout', 'subscribe', 'dispatch <action> <id>', 'capture workspace <id> <path>', or 'set <key> <value>'"
+            "expected 'clients', 'monitors', 'workspaces', 'settings', 'keyboard layout', 'subscribe', 'dispatch <action> <id>', 'capture workspace <id> <path>', or 'set <key> <value>'"
                 .to_string(),
         ),
     }
@@ -248,6 +281,46 @@ fn build_dispatch(args: &[String]) -> Result<String, String> {
             }
             Ok(r#"{"cmd":"cycle_keyboard_layout"}"#.to_string())
         }
+        // `srd dispatch set output position <name|id> <x> <y>` - the CLI
+        // surface for the IPC layer's own `set_output_position`, which
+        // existed before this but had no way to reach it outside a client
+        // willing to speak the raw socket itself. `<name|id>` accepts
+        // either: try parsing as a plain integer id first (matching every
+        // other dispatch target here), and if that fails, pass it through
+        // as a monitor name instead - `srd monitors` and `wlr-output-
+        // management-v1` both key on name (`eDP-1`), not
+        // an arbitrary index, so a caller listing outputs that way
+        // shouldn't have to look an id up first just to hand it straight
+        // back.
+        "set" => {
+            if args.get(1).map(String::as_str) != Some("output") {
+                return Err(format!("'set' only supports 'output position'/'output enabled' - {usage_hint}"));
+            }
+            let noun = args.get(2).ok_or("'set output' needs a target: position or enabled")?;
+            let target = args.get(3).ok_or("'set output' needs a monitor name or id")?;
+            match noun.as_str() {
+                "position" => {
+                    let x: i64 = args.get(4).ok_or("'set output position' needs an x coordinate")?.parse().map_err(|_| "x must be a number".to_string())?;
+                    let y: i64 = args.get(5).ok_or("'set output position' needs a y coordinate")?.parse().map_err(|_| "y must be a number".to_string())?;
+                    match target.parse::<u64>() {
+                        Ok(id) => Ok(format!(r#"{{"cmd":"set_output_position","id":{id},"x":{x},"y":{y}}}"#)),
+                        Err(_) => Ok(format!(r#"{{"cmd":"set_output_position","name":"{target}","x":{x},"y":{y}}}"#)),
+                    }
+                }
+                "enabled" => {
+                    let enabled = match args.get(4).map(String::as_str) {
+                        Some("true") => true,
+                        Some("false") => false,
+                        _ => return Err("'set output enabled' needs true or false".to_string()),
+                    };
+                    match target.parse::<u64>() {
+                        Ok(id) => Ok(format!(r#"{{"cmd":"set_output_enabled","id":{id},"enabled":{enabled}}}"#)),
+                        Err(_) => Ok(format!(r#"{{"cmd":"set_output_enabled","name":"{target}","enabled":{enabled}}}"#)),
+                    }
+                }
+                _ => Err(format!("unknown 'set output' target '{noun}' - {usage_hint}")),
+            }
+        }
         _ => Err(format!("unknown dispatch action '{verb}' - {usage_hint}")),
     }
 }
@@ -257,6 +330,7 @@ fn print_usage() {
     eprintln!("  srd clients");
     eprintln!("  srd monitors");
     eprintln!("  srd workspaces");
+    eprintln!("  srd settings");
     eprintln!("  srd keyboard layout");
     eprintln!("  srd subscribe");
     eprintln!("  srd dispatch focus <id>");
@@ -271,6 +345,8 @@ fn print_usage() {
     eprintln!("  srd dispatch move workspace <id> <workspace>");
     eprintln!("  srd dispatch activate workspace <id>");
     eprintln!("  srd dispatch cycle keyboard layout");
+    eprintln!("  srd dispatch set output position <name|id> <x> <y>");
+    eprintln!("  srd dispatch set output enabled <name|id> <true|false>");
     eprintln!("  srd capture workspace <id> <path> [<width>x<height>]");
     eprintln!("  srd set border_width <n>");
     eprintln!("  srd set border_color <#hex>");
@@ -279,6 +355,9 @@ fn print_usage() {
     eprintln!("  srd set gap_outer <n>");
     eprintln!("  srd set shadows <true|false>");
     eprintln!("  srd set rounded_corners <true|false>");
+    eprintln!("  srd set animations <true|false>");
+    eprintln!("  srd set night_light <true|false>");
+    eprintln!("  srd set reading_mode <true|false>");
     eprintln!("  srd set decoration_mode <server|client>");
 }
 
@@ -331,6 +410,47 @@ mod tests {
     }
 
     #[test]
+    fn set_output_position_accepts_a_numeric_id() {
+        assert_eq!(
+            build_request(&args(&["dispatch", "set", "output", "position", "1", "1920", "0"])).unwrap(),
+            r#"{"cmd":"set_output_position","id":1,"x":1920,"y":0}"#
+        );
+    }
+
+    #[test]
+    fn set_output_position_accepts_a_name_when_not_purely_numeric() {
+        // `srd monitors`/`wlr-output-management-v1` both key on the real
+        // connector name (`HDMI-A-1`), not an arbitrary id - a caller
+        // that already has the name shouldn't have to look its id up
+        // first just to send it straight back.
+        assert_eq!(
+            build_request(&args(&["dispatch", "set", "output", "position", "HDMI-A-1", "1920", "0"])).unwrap(),
+            r#"{"cmd":"set_output_position","name":"HDMI-A-1","x":1920,"y":0}"#
+        );
+    }
+
+    #[test]
+    fn set_output_position_needs_both_coordinates() {
+        assert!(build_request(&args(&["dispatch", "set", "output", "position", "1", "1920"])).is_err(), "missing y must error");
+        assert!(build_request(&args(&["dispatch", "set", "output", "position", "1", "not-a-number", "0"])).is_err());
+    }
+
+    #[test]
+    fn set_output_enabled_accepts_a_numeric_id_and_a_name() {
+        assert_eq!(build_request(&args(&["dispatch", "set", "output", "enabled", "1", "false"])).unwrap(), r#"{"cmd":"set_output_enabled","id":1,"enabled":false}"#);
+        assert_eq!(
+            build_request(&args(&["dispatch", "set", "output", "enabled", "HDMI-A-1", "true"])).unwrap(),
+            r#"{"cmd":"set_output_enabled","name":"HDMI-A-1","enabled":true}"#
+        );
+    }
+
+    #[test]
+    fn set_output_enabled_rejects_anything_but_true_or_false() {
+        assert!(build_request(&args(&["dispatch", "set", "output", "enabled", "1", "yes"])).is_err());
+        assert!(build_request(&args(&["dispatch", "set", "output", "enabled", "1"])).is_err(), "missing value must error");
+    }
+
+    #[test]
     fn lock_needs_no_id() {
         assert_eq!(build_request(&args(&["dispatch", "lock"])).unwrap(), r#"{"cmd":"lock"}"#);
     }
@@ -367,6 +487,19 @@ mod tests {
         assert_eq!(build_request(&args(&["set", "decoration_mode", "client"])).unwrap(), r#"{"cmd":"set","key":"decoration_mode","value":"client"}"#);
         assert!(build_request(&args(&["set", "decoration_mode", "both"])).is_err());
     }
+
+    #[test]
+    fn night_light_and_reading_mode_accept_only_true_or_false() {
+        assert_eq!(build_request(&args(&["set", "night_light", "true"])).unwrap(), r#"{"cmd":"set","key":"night_light","value":true}"#);
+        assert_eq!(build_request(&args(&["set", "night_light", "false"])).unwrap(), r#"{"cmd":"set","key":"night_light","value":false}"#);
+        assert_eq!(build_request(&args(&["set", "reading_mode", "true"])).unwrap(), r#"{"cmd":"set","key":"reading_mode","value":true}"#);
+        assert!(build_request(&args(&["set", "night_light", "warm"])).is_err());
+    }
+
+    #[test]
+    fn settings_query_needs_no_further_arguments() {
+        assert_eq!(build_request(&args(&["settings"])).unwrap(), r#"{"cmd":"settings"}"#);
+    }
 }
 
 #[cfg(unix)]
diff --git a/crates/platform/src/ipc.rs b/crates/platform/src/ipc.rs
index 8c58259..1a4b12f 100644
--- a/crates/platform/src/ipc.rs
+++ b/crates/platform/src/ipc.rs
@@ -53,6 +53,9 @@ pub struct IpcServer {
     /// `last_broadcast`'s keyboard-layout equivalent - see
     /// `KeyboardLayoutEvent`'s own doc comment.
     last_broadcast_keyboard_layout: String,
+    /// `last_broadcast`'s monitor equivalent - see `MonitorsEvent`'s own
+    /// doc comment.
+    last_broadcast_monitors: Vec<MonitorInfo>,
 }
 
 impl IpcServer {
@@ -85,6 +88,7 @@ impl IpcServer {
             last_broadcast: Vec::new(),
             last_broadcast_workspaces: Vec::new(),
             last_broadcast_keyboard_layout: String::new(),
+            last_broadcast_monitors: Vec::new(),
         })
     }
 
@@ -199,6 +203,16 @@ impl IpcServer {
             }
             self.last_broadcast_keyboard_layout = current_layout;
         }
+        let current_monitors = monitor_snapshot(wm);
+        if current_monitors != self.last_broadcast_monitors {
+            if !self.subscribers.is_empty() {
+                if let Ok(mut out) = serde_json::to_vec(&MonitorsEvent { event: "monitors", monitors: &current_monitors }) {
+                    out.push(b'\n');
+                    self.subscribers.retain_mut(|s| s.write_all(&out).is_ok());
+                }
+            }
+            self.last_broadcast_monitors = current_monitors;
+        }
         self.subscribers.extend(new_subscribers);
         dirty
     }
@@ -330,6 +344,23 @@ struct WorkspacesResponse {
     workspaces: Vec<WorkspaceInfo>,
 }
 
+/// `"settings"`'s one-shot reply - the live-settable toggles `"set"`
+/// accepts, so a migrated toggle script (night-light, reading-mode,
+/// hypr-performance-profile) can read current state back instead of
+/// tracking its own on/off marker file, the same gap `hyprctl getoption
+/// -j` used to fill for the Hyprland scripts these replaced.
+/// `rounded_corners` is `null` for "never explicitly set" (see
+/// `WindowManager::rounded_corners_enabled`'s own doc comment) --
+/// `Option<bool>` serializes to exactly that.
+#[derive(Serialize)]
+struct SettingsResponse {
+    shadows: bool,
+    rounded_corners: Option<bool>,
+    animations: bool,
+    night_light: bool,
+    reading_mode: bool,
+}
+
 /// `"keyboard_layout"`'s one-shot reply shape - the active XKB layout's
 /// own name (e.g. `"English (US)"`), whatever `WindowManager::keyboard_
 /// layout` currently holds. Added for an AGS peer session's keyboard-
@@ -359,6 +390,18 @@ struct WorkspaceInfo {
     name: String,
     layout: String,
     active: bool,
+    // The monitor currently showing this workspace, if any - `None` when
+    // it isn't visible anywhere right now. In shared mode (`workspace.
+    // per_monitor` off, the default) every monitor shows the same
+    // workspace, so at most one workspace ever has this set; in per-
+    // monitor mode each monitor can be on a different one, so more than
+    // one entry here can carry a (different) monitor id at once. Requested
+    // by an AGS peer session alongside `MonitorInfo::active_workspace`
+    // below - the same fact, indexed from the other direction, so a
+    // caller can look it up from whichever side (a workspace pill, or a
+    // per-monitor picker) it already has in hand without cross-
+    // referencing the other endpoint itself.
+    monitor: Option<srdwm_core::MonitorId>,
 }
 
 /// One entry per `srdwm_core::Monitor` - both rects a panel/dock actually
@@ -367,25 +410,93 @@ struct WorkspaceInfo {
 /// AGS peer session after two separate live-debugging rounds (maximize-
 /// past-dock, fullscreen-past-dock) each took several back-and-forth turns
 /// that a single read of this would have settled immediately.
-#[derive(Serialize)]
+///
+/// Every geometry field here - `x`/`y`/`width`/`height` and `full_x`/
+/// `full_y`/`full_width`/`full_height` alike - is in the same space:
+/// *physical* pixels, matching the real output mode, not the logical
+/// points a Wayland client itself sees. `srd dispatch set output
+/// position` takes the same physical space, so an arrangement computed
+/// purely from fields on this struct (chaining outputs by `full_width`,
+/// say) can be sent straight back with no conversion. `scale` is the one
+/// exception - multiply a logical value by it to get physical, or divide
+/// physical by it to get logical - needed only when a caller has to
+/// reconcile this compositor's own physical bookkeeping against a real
+/// Wayland client's logical one (window positions/sizes a client reports
+/// about itself, for instance). See `srdwm_core::monitor::Monitor::
+/// scale`'s own doc comment for the live bug this was added to fix: an
+/// AGS peer session's own arrangement math, built purely from this
+/// struct's fields, silently opened a dead gap between two monitors on
+/// any output whose scale wasn't exactly `1.0`, because nothing here told
+/// it a non-`1.0` scale was even in play.
+#[derive(Serialize, Clone, PartialEq)]
 struct MonitorInfo {
     id: u32,
     name: String,
     primary: bool,
-    // The usable area: the output shrunk by any layer-shell exclusive
-    // zone currently reserved on it (a bar/dock's `set_exclusive_zone`).
-    // What `toggle_maximize`/new-window placement/tiling all target.
+    // The usable area (work area): the output shrunk by any layer-shell
+    // exclusive zone currently reserved on it (a bar/dock's `set_
+    // exclusive_zone`). What `toggle_maximize`/new-window placement/
+    // tiling all target - NOT what a display-arrangement UI should
+    // position outputs by. Confirmed live: an AGS peer session's monitor-
+    // layout panel originally read x/y/width/height here for positioning
+    // outputs relative to each other and got every layout offset by
+    // whatever the bar's own reserved zone happened to be (34px, on this
+    // machine) - the bare, unprefixed names here read as "the output"
+    // rather than "the output's usable sub-rect", which is exactly the
+    // trap. Position outputs using `full_x`/`full_y`/`full_width`/
+    // `full_height` below instead.
     x: i32,
     y: i32,
     width: u32,
     height: u32,
     // The output's true full rect, ignoring any exclusive zone - what
-    // `toggle_fullscreen` targets. Equal to x/y/width/height above when
-    // nothing on this monitor currently reserves any space at all.
+    // `toggle_fullscreen` targets, and what a display-arrangement/output-
+    // positioning UI should read (`set_output_position` moves this rect,
+    // not the work-area one above). Equal to x/y/width/height above when
+    // nothing on this monitor currently reserves any space at all, which
+    // is exactly why the mistake above is easy to make and easy to miss
+    // in testing - it only shows up once something (a bar, a dock) is
+    // actually reserving space.
     full_x: i32,
     full_y: i32,
     full_width: u32,
     full_height: u32,
+    // `true` for every genuinely live output. `false` marks an
+    // administratively-disabled-but-still-connected one (`srd dispatch
+    // set output enabled <name> false`) - requested directly by the AGS
+    // peer session so their monitor-layout panel has a name/row to
+    // re-enable by, rather than the output vanishing from this list
+    // entirely the moment the control that turns it off is used. A
+    // genuinely *unplugged* output, disabled or not, still just
+    // disappears from this list as before - `enabled: false` means "off,
+    // but still here to turn back on", not "not connected".
+    enabled: bool,
+    // `true` when this entry is one part of a real output divided by
+    // `srd.monitor.split` - not a second `wl_output`, not a second
+    // physical connector. See `srdwm_core::monitor::Monitor::split`'s own
+    // doc comment: a display-arrangement UI should not offer to move or
+    // extend a physical arrangement onto one of these, since there is no
+    // independent output behind it, only a placement-only division of a
+    // real one.
+    split: bool,
+    // This output's real scale factor - `1.0` for an unscaled one. See
+    // this struct's own doc comment for what it converts between and why.
+    scale: f64,
+    // The workspace id currently showing on this monitor - `Window
+    // Manager::workspace_for_monitor`, keyed by monitor id, not name (a
+    // display-arrangement UI already has this monitor's own id in hand
+    // from this same entry). Every monitor has exactly one value here even
+    // in shared mode (`workspace.per_monitor` off): they all report the
+    // same id, `current_workspace`, rather than this field going missing
+    // just because it isn't independently meaningful yet - a caller
+    // shouldn't need to know which mode is active just to read this.
+    // `0` (an id that can never be real - workspace ids are 1-based) for
+    // a disabled-but-listed output below: it shows nothing, so there is no
+    // real answer, and `0` reads unambiguously as "none" rather than
+    // silently reusing `current_workspace`, which that output isn't
+    // actually displaying. See `WorkspaceInfo::monitor` for the same fact
+    // indexed from the other direction.
+    active_workspace: usize,
 }
 
 /// Pushed to every subscriber (and used as `subscribe`'s own initial
@@ -424,6 +535,21 @@ struct KeyboardLayoutEvent<'a> {
     layout: &'a str,
 }
 
+/// A fourth independently-diffed `subscribe` event - a monitor connecting
+/// or disconnecting touches neither a window, a workspace, nor the
+/// keyboard layout, so it needs the same dedicated change-diff those three
+/// already get. Requested by an AGS peer session so a display-arrangement
+/// panel's "output connected" indicator can drop its own 4-second poll of
+/// `"monitors"` (worked, but `hypr.connect("monitor-added", ...)` - the
+/// signal this shell normally listens for - is a dead handler id on any
+/// backend but Hyprland, since `lib/compositor.ts` swallows unknown signal
+/// names by design rather than erroring).
+#[derive(Serialize)]
+struct MonitorsEvent<'a> {
+    event: &'static str,
+    monitors: &'a [MonitorInfo],
+}
+
 /// The same per-window snapshot both `"clients"` and `"subscribe"`/the
 /// change-diff in `IpcServer::poll` build - pulled out so the two can
 /// never silently drift into reporting different fields.
@@ -458,8 +584,28 @@ fn client_snapshot(wm: &std::rc::Rc<std::cell::RefCell<WindowManager>>) -> Vec<C
 /// reporting different fields for the same state.
 fn workspace_snapshot(wm: &std::rc::Rc<std::cell::RefCell<WindowManager>>) -> Vec<WorkspaceInfo> {
     let wm = wm.borrow();
-    let current = wm.current_workspace();
-    wm.workspaces().iter().map(|w| WorkspaceInfo { id: w.id, name: w.name.clone(), layout: w.layout.clone(), active: w.id == current }).collect()
+    // `is_workspace_visible`, not a single `id == current` comparison: in
+    // `workspace.per_monitor` mode more than one workspace can be showing
+    // at once (one per monitor), each needing its own `active: true` here
+    // - `WorkspaceInfo::active` is already a plain per-workspace bool, not
+    // "the one active id", so this needed no wire-format change at all,
+    // just computing the flag correctly for both modes. Shared mode
+    // (`per_monitor_workspaces` off, the default) behaves exactly as
+    // before: `is_workspace_visible` reduces straight back to the same
+    // `id == current` check.
+    let monitors = wm.monitors();
+    wm.workspaces()
+        .iter()
+        .map(|w| {
+            // First monitor (if any) currently showing this workspace --
+            // see `WorkspaceInfo::monitor`'s own doc comment for why "first"
+            // rather than "the" is the honest framing (shared mode never has
+            // more than one; per-monitor mode could, in principle, if a
+            // caller pointed two monitors at the same workspace id).
+            let monitor = monitors.iter().find(|m| wm.workspace_for_monitor(m.id) == w.id).map(|m| m.id);
+            WorkspaceInfo { id: w.id, name: w.name.clone(), layout: w.layout.clone(), active: wm.is_workspace_visible(w.id), monitor }
+        })
+        .collect()
 }
 
 #[derive(Serialize)]
@@ -469,6 +615,86 @@ struct OkResponse {
     error: Option<&'static str>,
 }
 
+/// Shared by the one-shot `"monitors"` reply and `IpcServer::poll`'s own
+/// subscribe-broadcast diff below, so a hotplug event and a plain query
+/// can never quietly drift into reporting different fields for the same
+/// monitor - the same reasoning `client_snapshot`/`workspace_snapshot`
+/// already established for their own data.
+/// Resolves a dispatch's target monitor from whichever of `id`/`name` it
+/// actually sent - shared by `set_output_position` and `set_output_
+/// enabled`, both of which accept either. `id` wins if both are somehow
+/// given (matching the generic `id` field every other dispatch already
+/// reads); `name` is resolved against the live monitor list, matching
+/// what `srd monitors`/`wlr-output-management-v1` both key on
+/// (`eDP-1`, not an arbitrary index) - a display-
+/// arrangement UI reasonably lists outputs by that name rather than
+/// making a caller look its own id up first just to turn around and send
+/// it straight back.
+fn resolve_monitor_id(wm: &std::rc::Rc<std::cell::RefCell<WindowManager>>, id: Option<WindowId>, name: Option<&str>) -> Option<srdwm_core::MonitorId> {
+    match id {
+        Some(id) => Some(id as srdwm_core::MonitorId),
+        None => name.and_then(|name| wm.borrow().monitors().iter().find(|m| m.name == name).map(|m| m.id)),
+    }
+}
+
+fn monitor_snapshot(wm: &std::rc::Rc<std::cell::RefCell<WindowManager>>) -> Vec<MonitorInfo> {
+    let wm = wm.borrow();
+    let live = wm.monitors().iter().map(|m| MonitorInfo {
+        id: m.id,
+        name: m.name.clone(),
+        primary: m.primary,
+        x: m.geometry.x,
+        y: m.geometry.y,
+        width: m.geometry.width,
+        height: m.geometry.height,
+        full_x: m.full_geometry.x,
+        full_y: m.full_geometry.y,
+        full_width: m.full_geometry.width,
+        full_height: m.full_geometry.height,
+        enabled: true,
+        split: m.split,
+        scale: m.scale,
+        active_workspace: wm.workspace_for_monitor(m.id),
+    });
+    // Disabled-but-still-connected outputs, appended rather than merged in
+    // by name - see `MonitorInfo::enabled`'s own doc comment for why
+    // these are listed at all. `id: u32::MAX`: a disabled output has no
+    // real backend id any more (see `WindowManager::request_output_
+    // enabled`'s own doc comment on why re-enabling has to go by name),
+    // so this is a deliberate, obviously-not-a-real-index sentinel rather
+    // than reusing `0`/whatever the id happened to be before disabling,
+    // which could collide with (or be mistaken for) a real live monitor's
+    // own id.
+    let disabled = wm.disabled_monitors().map(|(name, m)| MonitorInfo {
+        id: u32::MAX,
+        name: name.to_string(),
+        primary: m.primary,
+        x: m.geometry.x,
+        y: m.geometry.y,
+        width: m.geometry.width,
+        height: m.geometry.height,
+        full_x: m.full_geometry.x,
+        full_y: m.full_geometry.y,
+        full_width: m.full_geometry.width,
+        full_height: m.full_geometry.height,
+        enabled: false,
+        split: false,
+        // Not tracked for a disabled output - `DisabledMonitor` keeps a
+        // last-known geometry snapshot but not a scale, and re-deriving
+        // one from stale connector state isn't worth the plumbing for an
+        // output that's off. `1.0` here means "unknown", not "confirmed
+        // unscaled" - a caller re-arranging outputs shouldn't trust it
+        // until this one is live again and `srd monitors` reports its
+        // real value.
+        scale: 1.0,
+        // See `MonitorInfo::active_workspace`'s own doc comment - `0` for
+        // "shows nothing, not tracked" the same way `id: u32::MAX` above
+        // is a deliberate not-a-real-value sentinel for this same entry.
+        active_workspace: 0,
+    });
+    live.chain(disabled).collect()
+}
+
 fn ok() -> Vec<u8> {
     serde_json::to_vec(&OkResponse { ok: true, error: None }).unwrap_or_default()
 }
@@ -506,34 +732,25 @@ fn handle_request(line: &[u8], wm: &std::rc::Rc<std::cell::RefCell<WindowManager
     match cmd {
         "clients" => (serde_json::to_vec(&ClientsResponse { clients: client_snapshot(wm) }).unwrap_or_default(), false),
         "workspaces" => (serde_json::to_vec(&WorkspacesResponse { workspaces: workspace_snapshot(wm) }).unwrap_or_default(), false),
-        "monitors" => {
-            let monitors: Vec<MonitorInfo> = wm
-                .borrow()
-                .monitors()
-                .iter()
-                .map(|m| MonitorInfo {
-                    id: m.id,
-                    name: m.name.clone(),
-                    primary: m.primary,
-                    x: m.geometry.x,
-                    y: m.geometry.y,
-                    width: m.geometry.width,
-                    height: m.geometry.height,
-                    full_x: m.full_geometry.x,
-                    full_y: m.full_geometry.y,
-                    full_width: m.full_geometry.width,
-                    full_height: m.full_geometry.height,
-                })
-                .collect();
-            (serde_json::to_vec(&MonitorsResponse { monitors }).unwrap_or_default(), false)
+        "settings" => {
+            let wm = wm.borrow();
+            let settings = SettingsResponse {
+                shadows: wm.shadows_enabled,
+                rounded_corners: wm.rounded_corners_enabled,
+                animations: wm.animations_enabled,
+                night_light: wm.color_filter == srdwm_core::ColorFilter::NightLight,
+                reading_mode: wm.color_filter == srdwm_core::ColorFilter::ReadingMode,
+            };
+            (serde_json::to_vec(&settings).unwrap_or_default(), false)
         }
+        "monitors" => (serde_json::to_vec(&MonitorsResponse { monitors: monitor_snapshot(wm) }).unwrap_or_default(), false),
         // The connection is handed off to `IpcServer::subscribers` by the
         // caller (`poll`, which is the only place that can see the raw
         // `cmd` string this deep call already consumed) right after this
         // reply is written - this arm only has to produce that reply, in
         // the same `ClientsEvent` shape every later push uses.
         "subscribe" => {
-            // Three JSON objects, not one: `poll` writes this response plus
+            // Four JSON objects, not one: `poll` writes this response plus
             // one trailing `\n` verbatim, so an embedded `\n` between each
             // here is all it takes to hand a fresh subscriber every initial
             // snapshot as its own line - exactly the shape every later
@@ -542,11 +759,14 @@ fn handle_request(line: &[u8], wm: &std::rc::Rc<std::cell::RefCell<WindowManager
             let clients = client_snapshot(wm);
             let workspaces = workspace_snapshot(wm);
             let layout = wm.borrow().keyboard_layout.clone();
+            let monitors = monitor_snapshot(wm);
             let mut out = serde_json::to_vec(&ClientsEvent { event: "clients", clients: &clients }).unwrap_or_default();
             out.push(b'\n');
             out.extend(serde_json::to_vec(&WorkspacesEvent { event: "workspaces", workspaces: &workspaces }).unwrap_or_default());
             out.push(b'\n');
             out.extend(serde_json::to_vec(&KeyboardLayoutEvent { event: "keyboard_layout", layout: &layout }).unwrap_or_default());
+            out.push(b'\n');
+            out.extend(serde_json::to_vec(&MonitorsEvent { event: "monitors", monitors: &monitors }).unwrap_or_default());
             (out, false)
         }
         "keyboard_layout" => {
@@ -668,7 +888,29 @@ fn handle_request(line: &[u8], wm: &std::rc::Rc<std::cell::RefCell<WindowManager
         // already reads serves both, same as every other dispatch arm.
         "activate_workspace" => {
             let Some(id) = id else { return (err("missing id"), false) };
-            wm.borrow_mut().switch_workspace(id as srdwm_core::WorkspaceId);
+            let before = wm.borrow().current_workspace();
+            // `switch_workspace_on_monitor` falls straight through to the
+            // ordinary shared-mode `switch_workspace` when `workspace.
+            // per_monitor` is off, so this is the one call site that works
+            // correctly either way - no branching on the config flag
+            // needed here. The monitor it applies to in per-monitor mode:
+            // the focused window's own monitor, falling back to the
+            // primary monitor if nothing is focused (an empty desktop) --
+            // the same "whichever output a keybinding should apply to"
+            // choice real per-output-aware WMs (Hyprland, niri) make.
+            {
+                let mut wm = wm.borrow_mut();
+                let monitor = wm
+                    .focused_id()
+                    .and_then(|f| wm.window(f))
+                    .map(|w| w.monitor)
+                    .or_else(|| wm.primary_monitor().map(|m| m.id))
+                    .unwrap_or(0);
+                wm.switch_workspace_on_monitor(id as srdwm_core::WorkspaceId, monitor);
+            }
+            let after = wm.borrow().current_workspace();
+            let known: Vec<_> = wm.borrow().workspaces().iter().map(|w| w.id).collect();
+            log::warn!("WS-IPC-DIAG requested_id={id} before={before} after={after} known_ids={known:?}");
             (ok(), true)
         }
         // `{"cmd":"set_output_position","id":<monitor id>,"x":<i32>,"y":<i32>}`
@@ -701,11 +943,52 @@ fn handle_request(line: &[u8], wm: &std::rc::Rc<std::cell::RefCell<WindowManager
         // this genuinely will change what's on screen once the backend
         // catches up, just not synchronously within this call.
         "set_output_position" => {
-            let Some(id) = id else { return (err("missing id"), false) };
+            // Accepts a monitor `name` as well as the plain `id` every
+            // other dispatch already reads - `srd monitors`/`wlr-output-
+            // management-v1` both key on name first (`eDP-1`,
+            // not an arbitrary index), and a display-arrangement UI
+            // reasonably lists outputs by that name rather than making a
+            // caller look its own id up first just to turn around and send
+            // it straight back. `id` still wins if both are somehow given.
+            let Some(monitor_id) = resolve_monitor_id(wm, id, req.get("name").and_then(|v| v.as_str())) else {
+                return (err("missing id or a name matching a connected monitor"), false);
+            };
             let (Some(x), Some(y)) = (req.get("x").and_then(|v| v.as_i64()), req.get("y").and_then(|v| v.as_i64())) else {
                 return (err("missing x/y"), false);
             };
-            wm.borrow_mut().request_output_position(id as srdwm_core::MonitorId, x as i32, y as i32);
+            wm.borrow_mut().request_output_position(monitor_id, x as i32, y as i32);
+            (ok(), true)
+        }
+        // `{"cmd":"set_output_enabled","id"|"name":...,"enabled":<bool>}`
+        // - "primary only"/a per-display toggle, the two AGS monitor-
+        // layout panel rows gated pending this. Disabling and re-enabling
+        // reuse this backend's own existing hotplug-removal/bring-up code
+        // paths rather than a new mechanism (see the udev platform's own
+        // drain site) - the same real, already-tested steps a genuine
+        // unplug/replug already goes through, just triggered
+        // administratively instead of by a real DRM event.
+        //
+        // Resolved to a *name* here, unlike `set_output_position` (which
+        // stays on `resolve_monitor_id`/plain `MonitorId`) - see
+        // `WindowManager::request_output_enabled`'s own doc comment for
+        // why: disabling removes the output from `monitors()` entirely, so
+        // its id has nothing left to mean by the time a caller wants to
+        // *re-enable* it. `id` is still accepted, resolved against the
+        // live list the same way `resolve_monitor_id` does, but that only
+        // ever works for the disable direction (the output is still live
+        // when you ask to turn it off) - re-enabling a currently-disabled
+        // output needs its `name` given directly, since no live entry
+        // exists to resolve an `id` against at that point.
+        "set_output_enabled" => {
+            let name = match req.get("name").and_then(|v| v.as_str()) {
+                Some(name) => Some(name.to_string()),
+                None => id.and_then(|id| wm.borrow().monitors().iter().find(|m| m.id == id as srdwm_core::MonitorId).map(|m| m.name.clone())),
+            };
+            let Some(name) = name else { return (err("missing name, or an id matching a currently-connected monitor"), false) };
+            let Some(enabled) = req.get("enabled").and_then(|v| v.as_bool()) else {
+                return (err("missing enabled"), false);
+            };
+            wm.borrow_mut().request_output_enabled(name, enabled);
             (ok(), true)
         }
         // `{"cmd":"capture_workspace","id":<workspace id>,"path":<string>,
@@ -879,7 +1162,35 @@ fn handle_set(req: &serde_json::Value, wm: &std::rc::Rc<std::cell::RefCell<Windo
             wm.borrow_mut().rounded_corners_enabled = Some(v);
             (ok(), true)
         }
+        // Same shape as `shadows` - `WindowManager::animations_enabled`
+        // already existed (config-settable at startup via `general.
+        // animations`) but had no live IPC toggle, unlike shadows/rounded
+        // corners which did. Added specifically so a performance-profile
+        // script (ported from a Hyprland one that used `hyprctl keyword
+        // animations:enabled`) has something real to call instead of
+        // silently no-op-ing under srdwm.
+        "animations" => {
+            let Some(v) = value.and_then(|v| v.as_bool()) else { return (err("animations needs a boolean value"), false) };
+            wm.borrow_mut().animations_enabled = v;
+            (ok(), true)
+        }
         "blur" => (err("blur is not supported - no GPU shader path on this compositor's software renderer yet"), false),
+        // The two ported Hyprland `decoration:screen_shader` scripts --
+        // mutually exclusive by construction (`srdwm_core::ColorFilter` is
+        // one enum, not two bools), matching the original scripts' own
+        // "both point at the same single shader slot" behaviour: setting
+        // either key `true` clears the other, and `false` always clears to
+        // `None` regardless of which one (if any) was actually active.
+        "night_light" => {
+            let Some(v) = value.and_then(|v| v.as_bool()) else { return (err("night_light needs a boolean value"), false) };
+            wm.borrow_mut().color_filter = if v { srdwm_core::ColorFilter::NightLight } else { srdwm_core::ColorFilter::None };
+            (ok(), true)
+        }
+        "reading_mode" => {
+            let Some(v) = value.and_then(|v| v.as_bool()) else { return (err("reading_mode needs a boolean value"), false) };
+            wm.borrow_mut().color_filter = if v { srdwm_core::ColorFilter::ReadingMode } else { srdwm_core::ColorFilter::None };
+            (ok(), true)
+        }
         _ => (err("unknown set key"), false),
     }
 }
@@ -924,23 +1235,63 @@ mod tests {
         client.write_all(b"{\"cmd\":\"subscribe\"}\n").unwrap();
         server.poll(&wm);
 
-        // Three lines, not one: a client snapshot, a workspace snapshot,
-        // and a keyboard-layout snapshot, same as every later push - see
-        // the `"subscribe"` match arm's own doc comment for why all three
-        // are sent immediately rather than waiting for the first real
-        // change of each kind.
+        // Four lines, not one: a client snapshot, a workspace snapshot, a
+        // keyboard-layout snapshot, and a monitor snapshot, same as every
+        // later push - see the `"subscribe"` match arm's own doc comment
+        // for why all four are sent immediately rather than waiting for
+        // the first real change of each kind.
         let clients_line = read_line(&mut reader);
         assert!(clients_line.contains(r#""event":"clients""#));
         assert!(clients_line.contains(r#""clients":[]"#));
 
         let workspaces_line = read_line(&mut reader);
         assert!(workspaces_line.contains(r#""event":"workspaces""#));
-        assert!(workspaces_line.contains(r#""id":0"#));
+        assert!(workspaces_line.contains(r#""id":1"#));
         assert!(workspaces_line.contains(r#""active":true"#));
 
         let layout_line = read_line(&mut reader);
         assert!(layout_line.contains(r#""event":"keyboard_layout""#));
         assert!(layout_line.contains(r#""layout":""#));
+
+        let monitors_line = read_line(&mut reader);
+        assert!(monitors_line.contains(r#""event":"monitors""#));
+        assert!(monitors_line.contains(r#""monitors":[]"#));
+    }
+
+    #[test]
+    fn subscribe_then_a_monitor_change_pushes_a_fresh_monitors_event() {
+        let dir = tempfile::tempdir().unwrap();
+        let mut server = IpcServer::bind_in(dir.path(), "test").unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+
+        let mut client = UnixStream::connect(&server.path).unwrap();
+        let mut reader = std::io::BufReader::new(client.try_clone().unwrap());
+        client.write_all(b"{\"cmd\":\"subscribe\"}\n").unwrap();
+        server.poll(&wm);
+        let _ = read_line(&mut reader); // clients
+        let _ = read_line(&mut reader); // workspaces
+        let _ = read_line(&mut reader); // keyboard_layout
+        let _ = read_line(&mut reader); // monitors (empty)
+
+        wm.borrow_mut().set_monitors(vec![{
+            let mut m = srdwm_core::Monitor::new(0, "HDMI-A-1", srdwm_core::Rect::new(0, 0, 1920, 1080));
+            m.primary = true;
+            m
+        }]);
+        server.poll(&wm);
+
+        // A real monitor existing for the first time also changes which
+        // monitor (if any) `WorkspaceInfo::monitor` reports for the
+        // now-visible workspace - `None` (no monitor existed to show it)
+        // to `Some(0)` - so a "workspaces" event fires too, ahead of
+        // "monitors" in `poll`'s own emission order. Drained here, not
+        // asserted on: this test is about the monitors event specifically.
+        let workspaces_line = read_line(&mut reader);
+        assert!(workspaces_line.contains(r#""event":"workspaces""#));
+
+        let line = read_line(&mut reader);
+        assert!(line.contains(r#""event":"monitors""#));
+        assert!(line.contains(r#""name":"HDMI-A-1""#));
     }
 
     #[test]
@@ -956,6 +1307,7 @@ mod tests {
         let _initial_clients = read_line(&mut reader);
         let _initial_workspaces = read_line(&mut reader);
         let _initial_layout = read_line(&mut reader);
+        let _initial_monitors = read_line(&mut reader);
 
         {
             let mut wm = wm.borrow_mut();
@@ -983,8 +1335,9 @@ mod tests {
         let _initial_clients = read_line(&mut reader);
         let _initial_workspaces = read_line(&mut reader);
         let _initial_layout = read_line(&mut reader);
+        let _initial_monitors = read_line(&mut reader);
 
-        wm.borrow_mut().switch_workspace(1);
+        wm.borrow_mut().switch_workspace(2);
         server.poll(&wm);
 
         // Switching touches no window, so the clients list is unchanged --
@@ -992,7 +1345,7 @@ mod tests {
         // clients one that never comes.
         let pushed = read_line(&mut reader);
         assert!(pushed.contains(r#""event":"workspaces""#));
-        assert!(pushed.contains(r#""id":1,"name":"2","layout":"dynamic","active":true"#));
+        assert!(pushed.contains(r#""id":2,"name":"2","layout":"dynamic","active":true"#));
     }
 
     #[test]
@@ -1008,6 +1361,7 @@ mod tests {
         let _initial_clients = read_line(&mut reader);
         let _initial_workspaces = read_line(&mut reader);
         let _initial_layout = read_line(&mut reader);
+        let _initial_monitors = read_line(&mut reader);
 
         // Nothing changed between these two polls - a second push would
         // show up as a second readable line the client isn't expecting.
@@ -1034,7 +1388,90 @@ mod tests {
 
         let line = read_line(&mut reader);
         assert!(!line.contains(r#""event""#), "one-shot command, same plain shape as \"clients\"");
-        assert!(line.contains(r#""id":0,"name":"1","layout":"dynamic","active":true"#));
+        assert!(line.contains(r#""id":1,"name":"1","layout":"dynamic","active":true"#));
+    }
+
+    #[test]
+    fn workspaces_and_monitors_agree_on_which_monitor_shows_which_workspace() {
+        // `WorkspaceInfo::monitor` and `MonitorInfo::active_workspace` are
+        // the same fact from either direction - requested by an AGS peer
+        // session so a workspace pill or a per-monitor picker can each
+        // read it from whichever side it already has in hand. Default
+        // `WindowManager::new()` starts on workspace `1` with no real
+        // monitor set up yet; adding one real monitor (id `0`) must make
+        // workspace `1`'s own `monitor` read back `0`, and that monitor's
+        // `active_workspace` read back `1`.
+        let dir = tempfile::tempdir().unwrap();
+        let mut server = IpcServer::bind_in(dir.path(), "test").unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+        wm.borrow_mut().set_monitors(vec![srdwm_core::Monitor::new(0, "eDP-1", srdwm_core::Rect::new(0, 0, 1920, 1080))]);
+
+        // Two separate connections, not one reused - a one-shot command's
+        // connection closes after its reply (see `a_oneshot_clients_
+        // request_still_closes_the_connection_as_before`), so a second
+        // command on the same `client` would just hit a broken pipe.
+        let mut workspaces_client = UnixStream::connect(&server.path).unwrap();
+        let mut workspaces_reader = std::io::BufReader::new(workspaces_client.try_clone().unwrap());
+        workspaces_client.write_all(b"{\"cmd\":\"workspaces\"}\n").unwrap();
+        server.poll(&wm);
+        let workspaces_line = read_line(&mut workspaces_reader);
+        assert!(workspaces_line.contains(r#""id":1,"name":"1","layout":"dynamic","active":true,"monitor":0"#));
+
+        let mut monitors_client = UnixStream::connect(&server.path).unwrap();
+        let mut monitors_reader = std::io::BufReader::new(monitors_client.try_clone().unwrap());
+        monitors_client.write_all(b"{\"cmd\":\"monitors\"}\n").unwrap();
+        server.poll(&wm);
+        let monitors_line = read_line(&mut monitors_reader);
+        assert!(monitors_line.contains(r#""name":"eDP-1""#));
+        assert!(monitors_line.contains(r#""active_workspace":1"#));
+    }
+
+    #[test]
+    fn settings_command_reflects_a_prior_set() {
+        let dir = tempfile::tempdir().unwrap();
+        let mut server = IpcServer::bind_in(dir.path(), "test").unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+
+        // A fresh connection per command - one-shot commands close the
+        // connection after replying (see `a_oneshot_clients_request_
+        // still_closes_the_connection_as_before`), so a second write on
+        // the same client after its first reply hits a closed socket.
+        let mut set_client = UnixStream::connect(&server.path).unwrap();
+        set_client.write_all(b"{\"cmd\":\"set\",\"key\":\"night_light\",\"value\":true}\n").unwrap();
+        server.poll(&wm);
+        let _set_reply = read_line(&mut std::io::BufReader::new(set_client.try_clone().unwrap()));
+
+        let mut settings_client = UnixStream::connect(&server.path).unwrap();
+        settings_client.write_all(b"{\"cmd\":\"settings\"}\n").unwrap();
+        server.poll(&wm);
+        let line = read_line(&mut std::io::BufReader::new(settings_client));
+        assert!(!line.contains(r#""event""#), "one-shot command, same plain shape as \"clients\"");
+        assert!(line.contains(r#""night_light":true"#));
+        assert!(line.contains(r#""reading_mode":false"#), "night_light and reading_mode share one slot, so setting one leaves the other off");
+    }
+
+    #[test]
+    fn setting_night_light_then_reading_mode_clears_night_light() {
+        let dir = tempfile::tempdir().unwrap();
+        let mut server = IpcServer::bind_in(dir.path(), "test").unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+
+        let mut client = UnixStream::connect(&server.path).unwrap();
+        client.write_all(b"{\"cmd\":\"set\",\"key\":\"night_light\",\"value\":true}\n").unwrap();
+        server.poll(&wm);
+        let _ = read_line(&mut std::io::BufReader::new(client));
+
+        let mut client = UnixStream::connect(&server.path).unwrap();
+        client.write_all(b"{\"cmd\":\"set\",\"key\":\"reading_mode\",\"value\":true}\n").unwrap();
+        server.poll(&wm);
+        let _ = read_line(&mut std::io::BufReader::new(client));
+
+        let mut client = UnixStream::connect(&server.path).unwrap();
+        client.write_all(b"{\"cmd\":\"settings\"}\n").unwrap();
+        server.poll(&wm);
+        let line = read_line(&mut std::io::BufReader::new(client));
+        assert!(line.contains(r#""night_light":false"#));
+        assert!(line.contains(r#""reading_mode":true"#));
     }
 
     #[test]
@@ -1082,11 +1519,156 @@ mod tests {
 
         let mut client = UnixStream::connect(&server.path).unwrap();
         let mut reader = std::io::BufReader::new(client.try_clone().unwrap());
-        client.write_all(b"{\"cmd\":\"activate_workspace\",\"id\":1}\n").unwrap();
+        // `id: 2`, not `1` - `WindowManager::new`'s default workspace is
+        // id 1 (already current), and `switch_workspace` no-ops when asked
+        // to "switch" to the already-current workspace, so activating `1`
+        // would silently test nothing: the assertion below would pass
+        // whether or not this dispatch actually worked at all.
+        client.write_all(b"{\"cmd\":\"activate_workspace\",\"id\":2}\n").unwrap();
         server.poll(&wm);
         let _ = read_line(&mut reader);
 
-        assert_eq!(wm.borrow().current_workspace(), 1);
+        assert_eq!(wm.borrow().current_workspace(), 2);
+    }
+
+    #[test]
+    fn set_output_position_resolves_a_monitor_name_to_its_id() {
+        // The CLI (`srd dispatch set output position <name> <x> <y>`)
+        // sends a `name`, not an `id`, whenever the caller didn't already
+        // have a numeric id handy - `srd monitors` reports names, not an
+        // arbitrary index, so a display-arrangement UI reasonably works
+        // in those terms.
+        let dir = tempfile::tempdir().unwrap();
+        let mut server = IpcServer::bind_in(dir.path(), "test").unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+        wm.borrow_mut().set_monitors(vec![
+            srdwm_core::Monitor::new(0, "EmbeddedDisplayPort-1", srdwm_core::Rect::new(0, 0, 1920, 1080)),
+            srdwm_core::Monitor::new(1, "HDMI-A-1", srdwm_core::Rect::new(1920, 0, 1920, 1080)),
+        ]);
+
+        let mut client = UnixStream::connect(&server.path).unwrap();
+        let mut reader = std::io::BufReader::new(client.try_clone().unwrap());
+        client.write_all(b"{\"cmd\":\"set_output_position\",\"name\":\"HDMI-A-1\",\"x\":1920,\"y\":0}\n").unwrap();
+        server.poll(&wm);
+        let _ = read_line(&mut reader);
+
+        let queued = wm.borrow_mut().drain_output_position_requests();
+        assert_eq!(queued, vec![(1, 1920, 0)], "must resolve to monitor id 1, not treat the name as missing");
+    }
+
+    #[test]
+    fn set_output_position_with_an_unknown_name_errors_instead_of_silently_no_opping() {
+        let dir = tempfile::tempdir().unwrap();
+        let mut server = IpcServer::bind_in(dir.path(), "test").unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+        wm.borrow_mut().set_monitors(vec![srdwm_core::Monitor::new(0, "EmbeddedDisplayPort-1", srdwm_core::Rect::new(0, 0, 1920, 1080))]);
+
+        let mut client = UnixStream::connect(&server.path).unwrap();
+        let mut reader = std::io::BufReader::new(client.try_clone().unwrap());
+        client.write_all(b"{\"cmd\":\"set_output_position\",\"name\":\"nonexistent-output\",\"x\":0,\"y\":0}\n").unwrap();
+        server.poll(&wm);
+        let line = read_line(&mut reader);
+
+        assert!(line.contains(r#""error""#), "an unresolvable name must error, not silently queue nothing");
+        assert!(wm.borrow_mut().drain_output_position_requests().is_empty());
+    }
+
+    #[test]
+    fn set_output_enabled_accepts_a_name_directly() {
+        let dir = tempfile::tempdir().unwrap();
+        let mut server = IpcServer::bind_in(dir.path(), "test").unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+        wm.borrow_mut().set_monitors(vec![srdwm_core::Monitor::new(0, "HDMI-A-1", srdwm_core::Rect::new(0, 0, 1920, 1080))]);
+
+        let mut client = UnixStream::connect(&server.path).unwrap();
+        let mut reader = std::io::BufReader::new(client.try_clone().unwrap());
+        client.write_all(b"{\"cmd\":\"set_output_enabled\",\"name\":\"HDMI-A-1\",\"enabled\":false}\n").unwrap();
+        server.poll(&wm);
+        let _ = read_line(&mut reader);
+
+        assert_eq!(wm.borrow_mut().drain_output_enable_requests(), vec![("HDMI-A-1".to_string(), false)]);
+    }
+
+    #[test]
+    fn set_output_enabled_resolves_an_id_to_its_name_for_the_disable_direction() {
+        // `id` only ever resolves against the *live* monitor list - fine
+        // for disabling something currently connected, which is the only
+        // case where a stale-index concern doesn't apply yet.
+        let dir = tempfile::tempdir().unwrap();
+        let mut server = IpcServer::bind_in(dir.path(), "test").unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+        wm.borrow_mut().set_monitors(vec![srdwm_core::Monitor::new(3, "HDMI-A-1", srdwm_core::Rect::new(0, 0, 1920, 1080))]);
+
+        let mut client = UnixStream::connect(&server.path).unwrap();
+        let mut reader = std::io::BufReader::new(client.try_clone().unwrap());
+        client.write_all(b"{\"cmd\":\"set_output_enabled\",\"id\":3,\"enabled\":false}\n").unwrap();
+        server.poll(&wm);
+        let _ = read_line(&mut reader);
+
+        assert_eq!(wm.borrow_mut().drain_output_enable_requests(), vec![("HDMI-A-1".to_string(), false)]);
+    }
+
+    #[test]
+    fn set_output_enabled_with_neither_name_nor_a_resolvable_id_errors() {
+        let dir = tempfile::tempdir().unwrap();
+        let mut server = IpcServer::bind_in(dir.path(), "test").unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+
+        let mut client = UnixStream::connect(&server.path).unwrap();
+        let mut reader = std::io::BufReader::new(client.try_clone().unwrap());
+        client.write_all(b"{\"cmd\":\"set_output_enabled\",\"enabled\":true}\n").unwrap();
+        server.poll(&wm);
+        let line = read_line(&mut reader);
+
+        assert!(line.contains(r#""error""#));
+        assert!(wm.borrow_mut().drain_output_enable_requests().is_empty());
+    }
+
+    #[test]
+    fn monitors_query_lists_a_disabled_output_alongside_live_ones() {
+        // What the AGS peer session asked for directly: a disabled output
+        // must not just vanish from `srd monitors` - it needs a row
+        // (name + `enabled: false`) to offer turning back on.
+        let dir = tempfile::tempdir().unwrap();
+        let mut server = IpcServer::bind_in(dir.path(), "test").unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+        wm.borrow_mut().set_monitors(vec![srdwm_core::Monitor::new(0, "EmbeddedDisplayPort-1", srdwm_core::Rect::new(0, 0, 1920, 1080))]);
+        wm.borrow_mut().set_disabled_monitor("HDMI-A-1".to_string(), srdwm_core::Rect::new(1920, 0, 1920, 1080), srdwm_core::Rect::new(1920, 0, 1920, 1080), false);
+
+        let mut client = UnixStream::connect(&server.path).unwrap();
+        let mut reader = std::io::BufReader::new(client.try_clone().unwrap());
+        client.write_all(b"{\"cmd\":\"monitors\"}\n").unwrap();
+        server.poll(&wm);
+        let line = read_line(&mut reader);
+
+        assert!(line.contains(r#""name":"EmbeddedDisplayPort-1""#));
+        assert!(line.contains(r#""enabled":true"#), "live outputs must report enabled:true");
+        assert!(line.contains(r#""name":"HDMI-A-1""#), "disabled output must still be listed");
+        assert!(line.contains(r#""enabled":false"#), "the disabled output's own row must say so");
+    }
+
+    #[test]
+    fn monitors_query_marks_a_split_part_so_a_client_does_not_treat_it_as_a_real_output() {
+        let dir = tempfile::tempdir().unwrap();
+        let mut server = IpcServer::bind_in(dir.path(), "test").unwrap();
+        let wm = Rc::new(RefCell::new(WindowManager::new()));
+        let whole = srdwm_core::Monitor::new(0, "eDP-1", srdwm_core::Rect::new(0, 0, 1920, 1080));
+        let mut half = srdwm_core::Monitor::new(1, "eDP-1-1", srdwm_core::Rect::new(0, 0, 960, 1080));
+        half.split = true;
+        wm.borrow_mut().set_monitors(vec![whole, half]);
+
+        let mut client = UnixStream::connect(&server.path).unwrap();
+        let mut reader = std::io::BufReader::new(client.try_clone().unwrap());
+        client.write_all(b"{\"cmd\":\"monitors\"}\n").unwrap();
+        server.poll(&wm);
+        let line = read_line(&mut reader);
+
+        let parsed: serde_json::Value = serde_json::from_str(&line).unwrap();
+        let monitors = parsed["monitors"].as_array().unwrap();
+        let whole = monitors.iter().find(|m| m["name"] == "eDP-1").unwrap();
+        let half = monitors.iter().find(|m| m["name"] == "eDP-1-1").unwrap();
+        assert_eq!(whole["split"], false, "an ordinary output must not be marked as a split part");
+        assert_eq!(half["split"], true, "a split part must be marked so a client can tell it apart from a real output");
     }
 
     #[test]
@@ -1201,13 +1783,13 @@ mod tests {
 
         let mut client = UnixStream::connect(&server.path).unwrap();
         let mut reader = std::io::BufReader::new(client.try_clone().unwrap());
-        client.write_all(format!("{{\"cmd\":\"move_to_workspace\",\"id\":{id},\"workspace\":1}}\n").as_bytes()).unwrap();
+        client.write_all(format!("{{\"cmd\":\"move_to_workspace\",\"id\":{id},\"workspace\":2}}\n").as_bytes()).unwrap();
         server.poll(&wm);
         let _ = read_line(&mut reader);
 
         let wm = wm.borrow();
-        assert_eq!(wm.window(id).unwrap().workspace, 1);
-        assert_eq!(wm.current_workspace(), 0, "moving a window to a workspace must not also switch to it");
+        assert_eq!(wm.window(id).unwrap().workspace, 2);
+        assert_eq!(wm.current_workspace(), 1, "moving a window to a workspace must not also switch to it");
     }
 
     #[test]
diff --git a/crates/srdwm/src/main.rs b/crates/srdwm/src/main.rs
index c6f4f2b..1f33a74 100644
--- a/crates/srdwm/src/main.rs
+++ b/crates/srdwm/src/main.rs
@@ -174,28 +174,80 @@ fn apply_general_settings(engine: &Engine, wm: &Rc<RefCell<WindowManager>>) {
     let focus_follows_mouse = engine.get_bool("general.focus_follows_mouse", false);
     let auto_raise = engine.get_bool("general.auto_raise", false);
 
-    // Only the three `theme.*` keys with an unambiguous, already-rendered
-    // counterpart are wired - see `srdwm_core::ThemeConfig`'s doc comment.
-    // `theme.colors.foreground`/`theme.decorations.title_bar.foreground`
-    // and `theme.decorations.border.inactive_color` are deliberately left
-    // alone: their own shipped defaults ("#eceff4", "#2e3440") don't match
-    // what unfocused text/border actually render as today (an accent-
-    // dimming scheme, not a second explicit colour), so wiring them in as
-    // written would silently change - in `border.inactive_color`'s case,
-    // erase - the unfocused appearance for anyone who never touched
-    // theme.* at all. A real design decision belongs there, not a guess
-    // made in passing while sweeping for dead keys.
+    // `theme.colors.foreground` stays unwired: it has no unambiguous
+    // rendered counterpart of its own (nothing currently paints "generic
+    // foreground text" outside the titlebar, which has its own two keys
+    // below), so wiring it would be a guess at what it should affect.
+    //
+    // Everything else here has a real, non-destructive default: each key's
+    // fallback in `get_string`/`get_f64` below is the exact value
+    // `ThemeConfig::default()` already ships, so a config that never
+    // touches `theme.*` renders identically to before this function read
+    // it at all - these are additions, not behaviour changes.
     let mut theme = srdwm_core::ThemeConfig::default();
     if let Some(rgb) = srdwm_core::parse_hex_color(&engine.get_string("theme.decorations.title_bar.background", "#2e3440")) {
         theme.titlebar_bg = rgb;
     }
+    if let Some(rgb) = srdwm_core::parse_hex_color(&engine.get_string("theme.decorations.title_bar.foreground_focused", "#88c0d0")) {
+        theme.titlebar_fg_focused = rgb;
+    }
+    if let Some(rgb) = srdwm_core::parse_hex_color(&engine.get_string("theme.decorations.title_bar.foreground_unfocused", "#4c566a")) {
+        theme.titlebar_fg_unfocused = rgb;
+    }
+    // "center" or "left" (default) - see `ThemeConfig::title_centered`'s
+    // own doc comment. Anything other than exactly "center" is treated as
+    // "left", the existing default, rather than erroring on a typo.
+    theme.title_centered = engine.get_string("theme.decorations.title_bar.text_align", "left") == "center";
+    // "left" or "right" (default) - see `ThemeConfig::buttons_left`'s own
+    // doc comment. Anything other than exactly "left" is treated as
+    // "right", the existing default.
+    theme.buttons_left = engine.get_string("theme.decorations.title_bar.button_side", "right") == "left";
+    // `"close,minimize,maximize"`-style override for the three buttons'
+    // relative order - see `ThemeConfig::button_order`'s own doc
+    // comment. Unset (empty string, the default `get_string` fallback
+    // here) leaves this project's own two built-in defaults untouched. A
+    // set-but-unparseable value (a typo, a missing button, a repeat) logs
+    // and falls back the same way rather than silently hiding a button.
+    let button_order_str = engine.get_string("theme.decorations.title_bar.button_order", "");
+    theme.button_order = if button_order_str.is_empty() {
+        None
+    } else {
+        let parsed = srdwm_core::parse_button_order(&button_order_str);
+        if parsed.is_none() {
+            log::warn!("theme.decorations.title_bar.button_order = '{button_order_str}' is not a valid ordering of close, minimize, maximize; keeping the built-in default");
+        }
+        parsed
+    };
+    // "hover" (default, classic macOS: glyph hidden until hovered, then
+    // animates in) or "always" (modern GNOME/Adwaita: glyph always
+    // visible) - see `ThemeConfig::button_glyph_always`'s own doc
+    // comment for the research behind offering both.
+    theme.button_glyph_always = engine.get_string("theme.decorations.title_bar.button_glyph", "hover") == "always";
+    // "traffic_lights" (default: filled, coloured macOS-style dots) or
+    // "traditional" (plain glyphs straight on the titlebar background,
+    // square maximize, no fill) - see `ThemeConfig::traffic_light_buttons`'s
+    // own doc comment. Anything other than exactly "traditional" keeps the
+    // traffic-light default, same fallback shape as every other string
+    // switch above.
+    theme.traffic_light_buttons = engine.get_string("theme.decorations.title_bar.button_style", "traffic_lights") != "traditional";
     let border_width = engine.get_f64("theme.decorations.border.width", 2.0).max(0.0) as u32;
     theme.default_border_width = border_width;
-    let corner_radius = engine.get_f64("theme.decorations.border.radius", 6.0).max(0.0) as u32;
+    // 12, not the original 6: matches real macOS's own ~0.36 radius-to-
+    // titlebar-height proportion (docs/TODO.md's macOS-comparison research)
+    // against `TITLEBAR_HEIGHT = 32` - see that constant's own doc comment
+    // for where that value comes from.
+    let corner_radius = engine.get_f64("theme.decorations.border.radius", 12.0).max(0.0) as u32;
     theme.default_corner_radius = corner_radius;
     if let Some(rgb) = srdwm_core::parse_hex_color(&engine.get_string("theme.decorations.border.active_color", "#88c0d0")) {
         theme.default_border_color = rgb;
     }
+    // A *factor* applied to `border.active_color`, not a second explicit
+    // colour - `border.inactive_color` still doesn't exist as a config
+    // key, because an absolute override would erase the dimming scheme
+    // instead of participating in it (see `ThemeConfig::border_inactive_
+    // dim`'s doc comment). `1.0` keeps unfocused identical to focused;
+    // `0.0` fades it to black.
+    theme.border_inactive_dim = engine.get_f64("theme.decorations.border.inactive_dim", theme.border_inactive_dim as f64).clamp(0.0, 1.0) as f32;
     // "server" (srdwm draws the titlebar, Windows/macOS-style) or "client"
     // (srdwm steps back for anything with no decoration opinion of its
     // own, GNOME-style) - see `ThemeConfig::default_decorated`'s own doc
@@ -248,6 +300,18 @@ fn apply_general_settings(engine: &Engine, wm: &Rc<RefCell<WindowManager>>) {
     wm.theme = theme;
     wm.lock = lock;
     wm.auto_back_and_forth = engine.get_bool("workspace.auto_back_and_forth", false);
+    // `false` (the default) keeps srdwm's original single-shared-workspace
+    // design exactly as it always was; `true` switches to Hyprland/niri-
+    // style independent per-monitor workspace sets. See `WindowManager::
+    // per_monitor_workspaces`'s own doc comment for what this actually
+    // changes.
+    wm.per_monitor_workspaces = engine.get_bool("workspace.per_monitor", false);
+    // Validated/defaulted since the config engine's beginning but never
+    // read anywhere until now - see `WindowManager::primary_layout`'s own
+    // doc comment for what actually applies them (a no-op outside
+    // `workspace.per_monitor` mode).
+    wm.primary_layout = engine.get_string("monitor.primary_layout", "");
+    wm.secondary_layout = engine.get_string("monitor.secondary_layout", "");
 }
 
 /// Applies `general.default_layout` to the workspaces that exist at
@@ -407,17 +471,38 @@ fn sync(wm: &Rc<RefCell<WindowManager>>, platform: &mut dyn Platform, last_synce
     // change silently undid itself within milliseconds, confirmed via the
     // core diagnostic logging two `switch_workspace` calls a few
     // milliseconds apart, the second putting it right back where it
-    // started. Re-asserting real platform focus still happens on every
-    // *genuine* focus change, which is everything the comment above this
-    // one actually needed fixed.
+    // started. This gate alone wasn't the complete fix, though - see the
+    // unconditional update just below for the other half.
     if focused != *last_synced_focus {
         if let Some(id) = focused {
             if let Err(e) = platform.focus(id) {
                 log::warn!("focus({id}) failed: {e}");
             }
         }
-        *last_synced_focus = focused;
     }
+    // Unconditional, not just inside the block above: a real mouse click
+    // changes `wm.focused_id()` through a completely separate, synchronous
+    // path (`input::focus_window`, called directly from the click handler)
+    // that never touches `last_synced_focus` at all. Updating it only when
+    // *this* function was the one to act on a change meant the very first
+    // real click after startup left it permanently stale - every dirty
+    // tick from then on saw `focused != *last_synced_focus` (comparing the
+    // click's real, current value against this now-ancient one), treated
+    // it as a fresh genuine change, and called `platform.focus()` again
+    // for a focus that hadn't actually moved since the last tick.
+    // `focus_window`'s own workspace-follow side effect then fired on that
+    // spurious re-assertion and switched back to the still-focused
+    // window's own (unchanged) workspace - silently reverting any
+    // `activate_workspace` IPC call within roughly a millisecond. Reported
+    // live as `srd dispatch activate workspace` having no visible effect;
+    // confirmed via temporary diagnostic logging in `switch_workspace`/
+    // `focus_window` showing exactly this switch-then-immediate-revert
+    // pair. This line now runs every tick regardless, so `last_synced_
+    // focus` always reflects the real current focus by the time this
+    // function returns - genuine changes (from any source: click, IPC,
+    // Alt-Tab) are still caught by the comparison above, but a tick where
+    // nothing changed can no longer be mistaken for one where it did.
+    *last_synced_focus = focused;
     let (visible, hidden) = {
         let wm = wm.borrow();
         // Bottom-to-top stacking order, not `visible_windows()`'s arbitrary
@@ -614,6 +699,21 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
                     dirty = true;
                 }
                 Event::WindowMoved { .. } | Event::WindowResized { .. } => dirty = true,
+                // `CoreEvent::WindowFocused` existed as a variant already
+                // (pushed by `input.rs`'s `focus_window` on every real
+                // focus change) but had no arm here at all - it fell
+                // through to the catch-all below, which does not set
+                // `dirty`. A focus change that doesn't also move, resize,
+                // create, or destroy a window (the common case: clicking a
+                // second, already-visible window) never reached `sync()`
+                // at all through this loop, so nothing here ever gave the
+                // border/titlebar recolor a second chance if the direct,
+                // synchronous `set_window_activated` path inside the click
+                // handler itself didn't already catch it. Reported live as
+                // a window's border staying stuck at whatever focus state
+                // it last happened to redraw with, in either direction,
+                // regardless of which window was actually focused now.
+                Event::WindowFocused(_) => dirty = true,
                 Event::WorkspaceChanged => dirty = true,
                 // Laptop lid. The handler is a plain Lua function, so the
                 // config decides what to do (lock, suspend, nothing).
diff --git a/crates/wayland/src/color_filter.rs b/crates/wayland/src/color_filter.rs
new file mode 100644
index 0000000..f9a259e
--- /dev/null
+++ b/crates/wayland/src/color_filter.rs
@@ -0,0 +1,98 @@
+//! Whole-screen colour treatments (`srd set night_light`/`srd set
+//! reading_mode`), ported from a Hyprland setup that pointed its
+//! `decoration:screen_shader` at a small GLSL fragment shader - one that
+//! multiplied every pixel by a warm tint, the other that flattened every
+//! pixel to its own luminance.
+//!
+//! Neither backend has an equivalent hook: the udev backend's
+//! `PixmanRenderer` is software-only (see `blur.rs`'s own doc comment),
+//! and reproducing the effect faithfully even on the GLES/winit backend
+//! would mean a full-frame capture + per-pixel transform + re-import on
+//! every damaged frame - the same per-frame CPU cost this codebase has
+//! already measured and rejected once for something far smaller (see
+//! `rounded_corners_pixman`'s module doc comment, and `udev/render.rs`'s
+//! own note on why that backend defaults corner-rounding off: "a full
+//! row-by-row buffer copy on every commit of a constantly-repainting
+//! client", named video specifically as the cost case that mattered).
+//! A whole-output tint is that same cost applied to *every* pixel of
+//! *every* frame, not just a window's corners.
+//!
+//! Instead, both effects are approximated with a single translucent
+//! `SolidColorRenderElement` covering the output, alpha-blended over the
+//! real scene by the renderer's native (and therefore free) `Frame::
+//! draw_solid` - no readback, no per-pixel work, no texture import.
+//! Blending any colour with a fixed colour is mathematically a pull
+//! toward that colour on every channel, which is close enough to both
+//! source shaders' actual intent (night light: pull blue/green down more
+//! than red; reading mode: pull every channel toward flat gray) to read
+//! as the same effect, at a cost indistinguishable from one extra
+//! ordinary border strip.
+
+use smithay::backend::renderer::element::solid::{SolidColorBuffer, SolidColorRenderElement};
+use smithay::backend::renderer::element::Kind;
+use smithay::backend::renderer::Color32F;
+use smithay::utils::Point;
+
+use srdwm_core::ColorFilter;
+
+/// `(r, g, b, a)`, each `0.0..=1.0`, for the given filter - `None` for
+/// [`ColorFilter::None`], meaning "draw nothing".
+///
+/// Night light's warm colour (255, 166, 87) and reading mode's neutral
+/// gray (128, 128, 128) are standard picks for this exact overlay trick
+/// (the same warm RGB triple Redshift/f.lux converge on for a low colour
+/// temperature); the alphas were picked by eye against the ported
+/// shaders' own strength - night light stays subtle (it runs for hours),
+/// reading mode is deliberately stronger (it is opted into for a single
+/// focused task).
+fn overlay_rgba(filter: ColorFilter) -> Option<(f32, f32, f32, f32)> {
+    match filter {
+        ColorFilter::None => None,
+        ColorFilter::NightLight => Some((1.0, 0.65, 0.34, 0.35)),
+        ColorFilter::ReadingMode => Some((0.5, 0.5, 0.5, 0.55)),
+    }
+}
+
+/// Builds the full-output overlay element for `filter`, or `None` for
+/// [`ColorFilter::None`] (nothing to draw). `buf` must be a *persistent*
+/// buffer kept one-per-output across frames, exactly like `elements::
+/// border_side_render_element`'s own `buf` parameter - a fresh
+/// `SolidColorBuffer` every frame gets a fresh `Id`, which defeats the
+/// damage tracker's element cache and marks the whole output damaged
+/// forever (see that function's doc comment for the full mechanism, and
+/// why border strips themselves used to have this exact bug).
+pub(crate) fn render_element(buf: &mut SolidColorBuffer, filter: ColorFilter, size: (i32, i32)) -> Option<SolidColorRenderElement> {
+    let (r, g, b, a) = overlay_rgba(filter)?;
+    buf.update(size, Color32F::new(r, g, b, a));
+    Some(SolidColorRenderElement::from_buffer(buf, Point::from((0, 0)), 1.0, 1.0, Kind::Unspecified))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn none_draws_nothing() {
+        assert_eq!(overlay_rgba(ColorFilter::None), None);
+    }
+
+    #[test]
+    fn night_light_pulls_blue_down_the_most_and_red_the_least() {
+        let (r, g, b, _) = overlay_rgba(ColorFilter::NightLight).unwrap();
+        assert!(r > g && g > b, "warm tint should redden more than it greens, and green more than it blues");
+    }
+
+    #[test]
+    fn reading_mode_is_neutral_gray() {
+        let (r, g, b, _) = overlay_rgba(ColorFilter::ReadingMode).unwrap();
+        assert_eq!((r, g, b), (0.5, 0.5, 0.5));
+    }
+
+    #[test]
+    fn every_variant_alpha_is_a_real_blend_not_opaque_or_invisible() {
+        for filter in [ColorFilter::NightLight, ColorFilter::ReadingMode] {
+            let (.., a) = overlay_rgba(filter).unwrap();
+            assert!(a > 0.0 && a < 1.0, "{filter:?}'s overlay must still let the real scene show through");
+        }
+    }
+}
diff --git a/crates/wayland/src/decoration.rs b/crates/wayland/src/decoration.rs
index 36915e5..98bb9d1 100644
--- a/crates/wayland/src/decoration.rs
+++ b/crates/wayland/src/decoration.rs
@@ -1,97 +1,71 @@
-//! Software rasterization of the titlebar band: solid background + drawn
-//! title text, as a BGRA8 pixel buffer (the byte order `Fourcc::Argb8888`
-//! expects when uploaded via `smithay`'s `GlesRenderer`, see
-//! `format::gl_internal_format` - it maps to `GL_BGRA_EXT`/`GL_UNSIGNED_BYTE`).
+//! Software rasterization of every hand-drawn piece of window chrome this
+//! compositor's own CPU/Pixman render path draws itself: the titlebar band
+//! (background, title text, button cluster), the border strips, the drop
+//! shadow, and two small standalone popups (the titlebar right-click menu,
+//! the Snap-Layouts flyout) - all as BGRA8 pixel buffers (the byte order
+//! `Fourcc::Argb8888` expects when uploaded via `smithay`'s `GlesRenderer`,
+//! see `format::gl_internal_format` - it maps to `GL_BGRA_EXT`/
+//! `GL_UNSIGNED_BYTE`).
 //!
-//! Deliberately has zero `smithay` dependency: it's a pure `(width, height,
-//! text) -> Vec<u8>` function, unit-testable without a GL context or
-//! display, with a thin adapter in `lib.rs` uploading the result into a
-//! `MemoryRenderBuffer`.
-
-use fontdue::{Font, FontSettings};
-use std::sync::OnceLock;
-
-pub(crate) const FONT_PIXELS: f32 = 13.0;
-pub(crate) const TEXT_LEFT_PADDING: f32 = 8.0;
-
-/// Titlebar buttons are laid out right-aligned in `height`-wide squares --
-/// matching `ResizeEdge::hit_test` in `crates/core/src/window.rs`, whose
-/// `BUTTON` constant is also `TITLEBAR_HEIGHT`. That function only computes
-/// *where* a click on close/maximize/minimize lands; nothing painted the
-/// buttons themselves, so the whole band was one undifferentiated bar with
-/// no visible way to tell where those three clickable regions were.
-const BUTTON_MARGIN: f32 = 0.32;
-
-/// Common monospace font file locations on Linux desktops. Not a full
-/// fontconfig query (no new system dependency for something this small) --
-/// if none of these resolve, titlebars fall back to solid-color-only, same
-/// as before text rendering existed.
-pub(crate) fn find_system_font() -> Option<Font> {
-    static FONT: OnceLock<Option<Font>> = OnceLock::new();
-    FONT.get_or_init(load_any_monospace_font).clone()
-}
-
-fn load_any_monospace_font() -> Option<Font> {
-    let roots = ["/usr/share/fonts", "/usr/local/share/fonts"];
-    let mut home_roots = Vec::new();
-    if let Ok(home) = std::env::var("HOME") {
-        home_roots.push(format!("{home}/.local/share/fonts"));
-        home_roots.push(format!("{home}/.fonts"));
-    }
-    let all_roots = roots.iter().map(|s| s.to_string()).chain(home_roots);
-
-    let mut best: Option<std::path::PathBuf> = None;
-    for root in all_roots {
-        find_ttf_preferring_mono(std::path::Path::new(&root), &mut best);
-        if best.is_some() {
-            break;
-        }
-    }
-    let path = best?;
-    let bytes = std::fs::read(&path).ok()?;
-    match Font::from_bytes(bytes, FontSettings::default()) {
-        Ok(f) => {
-            log::info!("wayland titlebar font: {}", path.display());
-            Some(f)
-        }
-        Err(e) => {
-            log::warn!("failed to parse font {}: {e}", path.display());
-            None
-        }
-    }
-}
-
-/// Walks `dir` looking for a `.ttf`/`.otf` file, preferring one whose name
-/// contains "mono". Stops early once a mono-named file is found.
-fn find_ttf_preferring_mono(dir: &std::path::Path, best: &mut Option<std::path::PathBuf>) {
-    let Ok(entries) = std::fs::read_dir(dir) else { return };
-    for entry in entries.flatten() {
-        let path = entry.path();
-        if path.is_dir() {
-            find_ttf_preferring_mono(&path, best);
-            if matches!(best, Some(p) if p.to_string_lossy().to_lowercase().contains("mono")) {
-                return;
-            }
-            continue;
-        }
-        let is_font = path.extension().and_then(|e| e.to_str()).map(|e| e.eq_ignore_ascii_case("ttf") || e.eq_ignore_ascii_case("otf")).unwrap_or(false);
-        if !is_font {
-            continue;
-        }
-        let is_mono = path.to_string_lossy().to_lowercase().contains("mono");
-        if is_mono {
-            *best = Some(path);
-            return;
-        }
-        if best.is_none() {
-            *best = Some(path);
-        }
-    }
-}
+//! Deliberately has zero `smithay` dependency throughout: every function
+//! here is a pure `(dimensions, ...) -> Vec<u8>` call, unit-testable
+//! without a GL context or display, with a thin adapter in `lib.rs`
+//! uploading each result into a `MemoryRenderBuffer`.
+//!
+//! Split by concern, matching niri's own `render_helpers/` module
+//! boundaries (see `docs/TODO.md`'s "module splits" entry for the research
+//! behind that choice) - this file itself only re-exports each
+//! submodule's own public API plus the two standalone popup renderers that
+//! don't belong to any single one of them:
+//! - [`color`]: byte-order conversion and the two directional colour
+//!   blends (`brighten`/`darken`) shared by several submodules.
+//! - [`font`]: locating a system monospace font and blitting its
+//!   rasterized glyphs.
+//! - [`corners`]: rounding a bitmap's own top/bottom corners to a
+//!   quarter-circle - shared by `titlebar`/`border`.
+//! - [`shadow`]: a window's drop shadow.
+//! - [`border`]: the four strips around a window's `geometry`.
+//! - [`buttons`]: the three titlebar buttons' own dots and glyphs.
+//! - [`titlebar`]: laying out and rasterizing the whole titlebar band,
+//!   using `buttons`/`corners`/`font`/`color`.
+
+mod border;
+mod buttons;
+mod color;
+mod corners;
+mod font;
+mod shadow;
+mod titlebar;
+
+pub use border::{border_strips, render_border_bottom, render_border_top};
+pub(crate) use border::{border_bottom_visible_rows, border_top_visible_rows};
+pub(crate) use buttons::HOVER_GLYPH_DURATION;
+pub(crate) use color::rgb_to_bgra;
+pub(crate) use corners::{round_bottom_corners, round_top_corners};
+pub(crate) use font::{blit_glyph, find_system_font, FONT_PIXELS, TEXT_LEFT_PADDING};
+pub use shadow::{shadow_bitmap, shadow_rect};
+pub(crate) use shadow::SHADOW_MAX_ALPHA;
+pub use titlebar::render_titlebar;
 
-pub(crate) fn rgb_to_bgra(rgb: (u8, u8, u8), alpha: u8) -> [u8; 4] {
-    [rgb.2, rgb.1, rgb.0, alpha]
-}
+/// Default corner radius, in pixels, applied to a window at creation
+/// (`Window::corner_radius`/`ThemeConfig::default_corner_radius`) - kept
+/// here only as this file's own test fixture default now that the real
+/// radius is a live, per-window value (`theme.decorations.border.radius`
+/// in config, `srd set corner_radius <n>` live, `srd.window.
+/// set_corner_radius(n)`/a rule's `corner_radius` action per-window).
+/// `render_border_top`/`render_border_bottom`/`render_titlebar` all take
+/// the real radius as a parameter now rather than reading this directly.
+/// `12`, not the original `6`: a `radius / TITLEBAR_HEIGHT` ratio of
+/// `0.36`, matching real macOS's own ~10pt/28pt proportions rather than
+/// this project's original, visibly-tighter `0.2` (docs/TODO.md's
+/// macOS-comparison research) - kept in sync with `ThemeConfig::
+/// default_corner_radius` and the shipped `theme.decorations.border.radius`
+/// default in `crates/srdwm/src/main.rs` so this fixture actually
+/// represents what a fresh install renders. Moves in step with
+/// `srdwm_core::TITLEBAR_HEIGHT` (currently `32`) - same ratio, not a
+/// separate size decision.
+#[cfg(test)]
+pub(crate) const CORNER_RADIUS: u32 = 12;
 
 /// The titlebar right-click window menu (minimize/maximize/always-on-top/
 /// close) - the one interaction virtually every desktop WM has always
@@ -220,703 +194,5 @@ pub fn render_snap_flyout(columns: u32, cell_width: u32, cell_height: u32, label
     buf
 }
 
-/// The four border strips (top, bottom, left, right) around a window's
-/// full rect, `width` thick, drawn *outside* `geometry` - additive to the
-/// window's on-screen footprint, the same as a native X11 border, rather
-/// than overlapping and clipping into the titlebar or content. This is
-/// purely a rendering concern: `geometry` alone stays authoritative for
-/// hit-testing and placement, nothing reads the strips back.
-///
-/// Without any border at all, a compositor-drawn titlebar and independently
-/// client-rendered content have nothing visually tying them together as
-/// one window - reported live as the titlebar "not seeming part of the
-/// window". `Window.border_color`/`border_width` already existed (and are
-/// drawn by the X11 backend via a native X11 border) but were dead fields
-/// on the Wayland side - `set_border_color`/`set_border_width` were both
-/// no-op stubs.
-pub fn border_strips(geometry: srdwm_core::Rect, width: u32) -> [srdwm_core::Rect; 4] {
-    let w = width as i32;
-    [
-        srdwm_core::Rect::new(geometry.x - w, geometry.y - w, geometry.width + 2 * width, width),
-        srdwm_core::Rect::new(geometry.x - w, geometry.y + geometry.height as i32, geometry.width + 2 * width, width),
-        srdwm_core::Rect::new(geometry.x - w, geometry.y, width, geometry.height),
-        srdwm_core::Rect::new(geometry.x + geometry.width as i32, geometry.y, width, geometry.height),
-    ]
-}
-
-/// How far a window's drop shadow extends past its geometry on each side.
-pub const SHADOW_SIZE: u32 = 12;
-
-/// The shadow's darkest alpha, right at the window's own edge - out of
-/// 255. Deliberately subtle (Nord/GNOME-default territory, not a heavy
-/// drop shadow): this compositor has no blur primitive to soften it with
-/// (see `shadow_bitmap`'s own doc comment), so a strong value would read as
-/// a hard dark ring rather than a shadow.
-const SHADOW_MAX_ALPHA: u8 = 90;
-
-/// `geometry` expanded by [`SHADOW_SIZE`] on every side - the full bounding
-/// box [`shadow_bitmap`] rasterises into, and where the caller positions it
-/// (top-left corner at `(geometry.x - SHADOW_SIZE, geometry.y - SHADOW_SIZE)`).
-pub fn shadow_rect(geometry: srdwm_core::Rect) -> srdwm_core::Rect {
-    let s = SHADOW_SIZE as i32;
-    srdwm_core::Rect::new(geometry.x - s, geometry.y - s, geometry.width + SHADOW_SIZE * 2, geometry.height + SHADOW_SIZE * 2)
-}
-
-/// Renders a window's drop shadow as a BGRA8 bitmap: black at an alpha that
-/// falls off linearly from [`SHADOW_MAX_ALPHA`] right at the window's own
-/// edge to fully transparent [`SHADOW_SIZE`] pixels out. `win_width`/
-/// `win_height` are the window's own footprint (`geometry`, border strips
-/// included if any - whatever the caller already draws as opaque); the
-/// returned bitmap is `shadow_rect`'s size, `SHADOW_SIZE` larger on every
-/// side.
-///
-/// Not a true Gaussian blur - no blur primitive is available without a GPU
-/// shader (the udev backend's `PixmanRenderer` is software-only) or a new
-/// image-processing dependency - so this is a stepless *linear* falloff
-/// using Chebyshev (square-ring) distance from the window's edge rather
-/// than a rounded/radial one, cheap enough to rebuild on every resize (see
-/// the caller for when that is) without a per-pixel sqrt. Reads as "soft
-/// enough" at the sizes a titlebar-height window actually uses, the same
-/// "approximate cutoff over true anti-aliasing" trade-off `round_top_corners`
-/// already makes for corners.
-///
-/// The region directly under the window itself (`dist == 0` below) is left
-/// fully transparent rather than filled - harmless either way since the
-/// window's own border/titlebar/content always draws over it, but skipping
-/// it is one less branch of work for the common case (a window with no
-/// occluders in front of it, so most of the bitmap's interior never
-/// contributes a visible pixel).
-pub fn shadow_bitmap(win_width: u32, win_height: u32) -> Vec<u8> {
-    let (win_width, win_height) = (win_width.max(1), win_height.max(1));
-    let width = win_width + SHADOW_SIZE * 2;
-    let height = win_height + SHADOW_SIZE * 2;
-    let mut buf = vec![0u8; (width * height * 4) as usize];
-    for y in 0..height {
-        let dy = edge_distance(y, SHADOW_SIZE, win_height);
-        if dy > SHADOW_SIZE {
-            continue;
-        }
-        for x in 0..width {
-            let dx = edge_distance(x, SHADOW_SIZE, win_width);
-            let dist = dx.max(dy);
-            if dist == 0 || dist > SHADOW_SIZE {
-                continue;
-            }
-            let alpha = (SHADOW_MAX_ALPHA as u32 * (SHADOW_SIZE - dist) / SHADOW_SIZE) as u8;
-            if alpha == 0 {
-                continue;
-            }
-            let i = ((y * width + x) * 4) as usize;
-            // Premultiplied BGRA, but the colour is black (0, 0, 0) - a
-            // premultiplied black pixel is just (0, 0, 0, alpha) at any
-            // alpha, so there's no separate multiply step needed here.
-            buf[i + 3] = alpha;
-        }
-    }
-    buf
-}
-
-/// How far outside `[margin, margin + extent)` - the window's own span
-/// along one axis, inside the shadow's `margin`-pixel border on each side
-/// - position `pos` sits, in pixels. `0` anywhere inside that span
-/// (including exactly on its edge).
-fn edge_distance(pos: u32, margin: u32, extent: u32) -> u32 {
-    if pos < margin {
-        margin - pos
-    } else if pos >= margin + extent {
-        pos - (margin + extent) + 1
-    } else {
-        0
-    }
-}
-
-/// Renders the top border strip (`border_strips`'s first rect) as a BGRA8
-/// bitmap instead of a plain solid fill, with its own outer top corners cut
-/// the same way `render_titlebar`'s `round_corners` cuts the titlebar's --
-/// see that parameter's doc comment for why a titlebar rounds but a square
-/// border frame around it used to defeat the point. Rounding *this* strip
-/// too, at a radius `width` pixels larger than the titlebar's (so the cut
-/// continues outward from the titlebar's own, rather than starting over),
-/// is what makes a bordered window's corner read as one continuous curve
-/// instead of a rounded titlebar sitting inside a square frame.
-///
-/// [`render_border_bottom`] gives the bottom strip the matching treatment
-/// for its own two corners. The left/right strips don't participate in any
-/// visible corner at all (`border_strips`' geometry has them span only the
-/// height *between* the top and bottom strips) and stay plain solid fills
-/// - see their render call sites.
-pub fn render_border_top(width: u32, thickness: u32, color: (u8, u8, u8), radius: u32) -> Vec<u8> {
-    let (width, thickness) = (width.max(1) as usize, thickness.max(1) as usize);
-    let bg = rgb_to_bgra(color, 255);
-    let mut buf = vec![0u8; width * thickness * 4];
-    for px in buf.chunks_exact_mut(4) {
-        px.copy_from_slice(&bg);
-    }
-    round_top_corners(&mut buf, width, thickness, radius + thickness as u32);
-    buf
-}
-
-/// [`render_border_top`]'s mirror for the bottom strip - same construction,
-/// its own two corners (bottom-left/bottom-right) cut instead. Reported
-/// live, alongside the top-corner work: a bordered window's bottom two
-/// corners still read as square next to the now-rounded top ones, the same
-/// "inconsistently square" complaint that motivated rounding the top strip
-/// in the first place.
-///
-/// Handled as one all-or-nothing bitmap rather than folded into the
-/// left/right strips' per-fragment occlusion splitting (`visible_border_
-/// fragments`) - the same trade-off `render_border_top`'s own call site
-/// already makes and for the same reason: cropping a rounded bitmap's
-/// source rect per fragment is real extra work for a strip this thin.
-pub fn render_border_bottom(width: u32, thickness: u32, color: (u8, u8, u8), radius: u32) -> Vec<u8> {
-    let (width, thickness) = (width.max(1) as usize, thickness.max(1) as usize);
-    let bg = rgb_to_bgra(color, 255);
-    let mut buf = vec![0u8; width * thickness * 4];
-    for px in buf.chunks_exact_mut(4) {
-        px.copy_from_slice(&bg);
-    }
-    round_bottom_corners(&mut buf, width, thickness, radius + thickness as u32);
-    buf
-}
-
-/// Renders a `width x height` BGRA8 buffer: filled with `background`, with
-/// `title` drawn left-aligned in `foreground` (best-effort glyph layout --
-/// no text shaping/kerning, adequate for the ASCII-heavy titles window
-/// managers actually display). Returns `None` (caller keeps the previous
-/// solid-color-only look) only if no usable font was found on this system.
-///
-/// `round_corners` should be `false` only for a window whose border strips
-/// are rendered as plain square-cornered fills with no matching rounded
-/// treatment of their own. `render_border_top` gives the border's top strip
-/// the same rounded-corner cut (see its own doc comment for how the two
-/// stay visually continuous), so a normal bordered window should pass
-/// `true` here same as a borderless one now - reported live as most
-/// windows (anything with the default border) looking inconsistently
-/// square next to the few borderless ones that were rounded.
-pub fn render_titlebar(width: u32, height: u32, title: &str, background: (u8, u8, u8), foreground: (u8, u8, u8), round_corners: bool, radius: u32) -> Vec<u8> {
-    let (width, height) = (width.max(1) as usize, height.max(1) as usize);
-    let bg = rgb_to_bgra(background, 255);
-    let mut buf = vec![0u8; width * height * 4];
-    for px in buf.chunks_exact_mut(4) {
-        px.copy_from_slice(&bg);
-    }
-
-    // Reserve the right-hand button squares before laying out text, so a
-    // long title elides under them the same way it would under real window
-    // furniture rather than drawing on top of it.
-    let button_count = if width >= height * 3 { 3 } else { 0 };
-    let text_limit = width.saturating_sub(height * button_count);
-
-    if let Some(font) = find_system_font() {
-        let baseline = (height as f32 * 0.72).round();
-        let mut pen_x = TEXT_LEFT_PADDING;
-        for ch in title.chars() {
-            if ch.is_control() {
-                continue;
-            }
-            let (metrics, coverage) = font.rasterize(ch, FONT_PIXELS);
-            if metrics.width > 0 && metrics.height > 0 {
-                let glyph_x = pen_x + metrics.xmin as f32;
-                let glyph_y = baseline - metrics.height as f32 - metrics.ymin as f32;
-                blit_glyph(&mut buf, width, height, glyph_x.round() as i32, glyph_y.round() as i32, &metrics, &coverage, background, foreground);
-            }
-            pen_x += metrics.advance_width;
-            if pen_x as usize >= text_limit {
-                break;
-            }
-        }
-    }
-
-    if button_count == 3 {
-        draw_minimize_icon(&mut buf, width, height, height * 2, foreground);
-        draw_maximize_icon(&mut buf, width, height, height, foreground);
-        draw_close_icon(&mut buf, width, height, 0, foreground);
-    }
-    if round_corners {
-        round_top_corners(&mut buf, width, height, radius);
-    }
-    buf
-}
-
-/// Default corner radius, in pixels, applied to a window at creation
-/// (`Window::corner_radius`/`ThemeConfig::default_corner_radius`) - kept
-/// here only as this file's own test fixture default now that the real
-/// radius is a live, per-window value (`theme.decorations.border.radius`
-/// in config, `srd set corner_radius <n>` live, `srd.window.
-/// set_corner_radius(n)`/a rule's `corner_radius` action per-window).
-/// `render_border_top`/`render_border_bottom`/`render_titlebar` all take
-/// the real radius as a parameter now rather than reading this directly.
 #[cfg(test)]
-pub(crate) const CORNER_RADIUS: u32 = 6;
-
-/// Clips the top-left and top-right corners of a titlebar buffer to a
-/// quarter-circle by making the pixels outside it fully transparent, so
-/// whatever's behind (the desktop, on every top-level window) shows through
-/// instead of a hard square corner.
-///
-/// Only the *top* corners: the titlebar's bottom edge meets the window's
-/// content, which this compositor has no way to clip (content is rendered
-/// entirely by the client) - rounding that seam too would need a
-/// compositor-wide clip mask over arbitrary client buffers, a much larger
-/// change than this cosmetic pass. Real desktops mostly round this the same
-/// way: only the outermost corners of a window, not every internal seam.
-///
-/// Hard cutoff rather than an anti-aliased edge, matching this codebase's
-/// existing pixel-art aesthetic elsewhere (the cursor bitmaps) rather than
-/// mixing rendering styles for one corner treatment.
-///
-/// Zeroes all four BGRA bytes for a cut pixel, not just alpha: this buffer
-/// is `Fourcc::Argb8888`, which both Wayland/`wl_shm` and Pixman treat as
-/// premultiplied - a genuinely transparent premultiplied pixel is `(0, 0,
-/// 0, 0)` in every channel, not just alpha, since the stored colour already
-/// carries the alpha multiplied in. Leaving the opaque titlebar-background
-/// RGB behind while zeroing only alpha produced a byte pattern Pixman's own
-/// `OVER` compositing (`result = src + dst * (1 - src_alpha)`) does not
-/// actually treat as "nothing here": with `src_alpha = 0` the formula still
-/// adds the stale, un-premultiplied `src` RGB straight through, so the
-/// "cut" pixel came out opaque and the corner still read as square --
-/// confirmed live, pixel-by-pixel, no visible transparency anywhere in a
-/// window's real top corner despite this function running and a nonzero
-/// radius. `rounded_corners_pixman.rs`'s `apply_corner_mask` - the
-/// equivalent mask for client *content* - already gets this right (scales
-/// all four bytes together); this was the one corner-rounding path in the
-/// codebase that didn't match it.
-fn round_top_corners(buf: &mut [u8], width: usize, height: usize, radius: u32) {
-    let r = (radius as usize).min(width / 2).min(height);
-    if r == 0 {
-        return;
-    }
-    // Corner centres: `r` in from each edge, `r` down from the top - the
-    // standard quarter-circle-in-a-square construction.
-    let is_outside_corner = |x: usize, y: usize, cx: usize, cy: usize| -> bool {
-        let (dx, dy) = (x as i64 - cx as i64, y as i64 - cy as i64);
-        (dx * dx + dy * dy) as u64 > (r * r) as u64
-    };
-    for y in 0..r {
-        for x in 0..r {
-            if is_outside_corner(x, y, r, r) {
-                buf[(y * width + x) * 4..(y * width + x) * 4 + 4].fill(0);
-            }
-        }
-        for x in (width - r)..width {
-            if is_outside_corner(x, y, width - r - 1, r) {
-                buf[(y * width + x) * 4..(y * width + x) * 4 + 4].fill(0);
-            }
-        }
-    }
-}
-
-/// [`round_top_corners`]'s mirror for the bottom two corners - same
-/// construction, corner centres `r` *up* from the bottom instead of down
-/// from the top. Same premultiplied-alpha fix, same reason - see that
-/// function's own doc comment.
-fn round_bottom_corners(buf: &mut [u8], width: usize, height: usize, radius: u32) {
-    let r = (radius as usize).min(width / 2).min(height);
-    if r == 0 {
-        return;
-    }
-    // `cy` as a signed offset, not a `usize` - `height - r` can be exactly
-    // `0` (a strip whose radius clamp landed on its own full height, same
-    // as `round_top_corners` allows for `r == height`), which would
-    // underflow a plain `usize` subtraction one step further below.
-    let is_outside_corner = |x: usize, y: usize, cx: usize, cy: i64| -> bool {
-        let (dx, dy) = (x as i64 - cx as i64, y as i64 - cy);
-        (dx * dx + dy * dy) as u64 > (r * r) as u64
-    };
-    let cy = height as i64 - r as i64 - 1;
-    for y in (height - r)..height {
-        for x in 0..r {
-            if is_outside_corner(x, y, r, cy) {
-                buf[(y * width + x) * 4..(y * width + x) * 4 + 4].fill(0);
-            }
-        }
-        for x in (width - r)..width {
-            if is_outside_corner(x, y, width - r - 1, cy) {
-                buf[(y * width + x) * 4..(y * width + x) * 4 + 4].fill(0);
-            }
-        }
-    }
-}
-
-/// Sets one pixel to `color` if it falls inside the buffer - every icon
-/// drawn below goes through this so none of them need their own bounds
-/// checks.
-fn set_px(buf: &mut [u8], width: usize, height: usize, x: i32, y: i32, color: (u8, u8, u8)) {
-    if x < 0 || y < 0 || x as usize >= width || y as usize >= height {
-        return;
-    }
-    let idx = (y as usize * width + x as usize) * 4;
-    buf[idx..idx + 4].copy_from_slice(&rgb_to_bgra(color, 255));
-}
-
-/// The square `right_offset` pixels in from the right edge of the titlebar,
-/// inset by `BUTTON_MARGIN` on each side - the box a button's glyph is
-/// drawn inside.
-fn button_box(width: usize, height: usize, right_offset: usize) -> (i32, i32, i32, i32) {
-    let square = height as f32;
-    let inset = (square * BUTTON_MARGIN).round() as i32;
-    let right = width as i32 - right_offset as i32;
-    let left = right - height as i32;
-    (left + inset, inset, right - inset, height as i32 - inset)
-}
-
-/// Bresenham line, since none of these icons need anything fancier.
-fn draw_line(buf: &mut [u8], width: usize, height: usize, from: (i32, i32), to: (i32, i32), color: (u8, u8, u8)) {
-    let (mut x0, mut y0) = from;
-    let (x1, y1) = to;
-    let dx = (x1 - x0).abs();
-    let dy = -(y1 - y0).abs();
-    let sx = if x0 < x1 { 1 } else { -1 };
-    let sy = if y0 < y1 { 1 } else { -1 };
-    let mut err = dx + dy;
-    loop {
-        set_px(buf, width, height, x0, y0, color);
-        if x0 == x1 && y0 == y1 {
-            break;
-        }
-        let e2 = 2 * err;
-        if e2 >= dy {
-            err += dy;
-            x0 += sx;
-        }
-        if e2 <= dx {
-            err += dx;
-            y0 += sy;
-        }
-    }
-}
-
-fn draw_close_icon(buf: &mut [u8], width: usize, height: usize, right_offset: usize, color: (u8, u8, u8)) {
-    let (x0, y0, x1, y1) = button_box(width, height, right_offset);
-    draw_line(buf, width, height, (x0, y0), (x1, y1), color);
-    draw_line(buf, width, height, (x0, y1), (x1, y0), color);
-}
-
-fn draw_maximize_icon(buf: &mut [u8], width: usize, height: usize, right_offset: usize, color: (u8, u8, u8)) {
-    let (x0, y0, x1, y1) = button_box(width, height, right_offset);
-    draw_line(buf, width, height, (x0, y0), (x1, y0), color);
-    draw_line(buf, width, height, (x0, y1), (x1, y1), color);
-    draw_line(buf, width, height, (x0, y0), (x0, y1), color);
-    draw_line(buf, width, height, (x1, y0), (x1, y1), color);
-}
-
-fn draw_minimize_icon(buf: &mut [u8], width: usize, height: usize, right_offset: usize, color: (u8, u8, u8)) {
-    let (x0, _, x1, y1) = button_box(width, height, right_offset);
-    draw_line(buf, width, height, (x0, y1), (x1, y1), color);
-}
-
-#[allow(clippy::too_many_arguments)]
-pub(crate) fn blit_glyph(
-    buf: &mut [u8],
-    width: usize,
-    height: usize,
-    glyph_x: i32,
-    glyph_y: i32,
-    metrics: &fontdue::Metrics,
-    coverage: &[u8],
-    background: (u8, u8, u8),
-    foreground: (u8, u8, u8),
-) {
-    for row in 0..metrics.height {
-        let y = glyph_y + row as i32;
-        if y < 0 || y as usize >= height {
-            continue;
-        }
-        for col in 0..metrics.width {
-            let x = glyph_x + col as i32;
-            if x < 0 || x as usize >= width {
-                continue;
-            }
-            let cov = coverage[row * metrics.width + col] as f32 / 255.0;
-            if cov <= 0.0 {
-                continue;
-            }
-            let blend = |bg: u8, fg: u8| -> u8 { (bg as f32 * (1.0 - cov) + fg as f32 * cov).round() as u8 };
-            let r = blend(background.0, foreground.0);
-            let g = blend(background.1, foreground.1);
-            let b = blend(background.2, foreground.2);
-            let idx = (y as usize * width + x as usize) * 4;
-            buf[idx..idx + 4].copy_from_slice(&rgb_to_bgra((r, g, b), 255));
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn border_strips_surround_geometry_without_overlapping_it() {
-        let geom = srdwm_core::Rect::new(100, 100, 200, 150);
-        let [top, bottom, left, right] = border_strips(geom, 3);
-        // Every strip's own rect must stay entirely outside `geom` - these
-        // are meant to frame the window, not clip into its own titlebar or
-        // content.
-        assert_eq!(top, srdwm_core::Rect::new(97, 97, 206, 3));
-        assert_eq!(bottom, srdwm_core::Rect::new(97, 250, 206, 3));
-        assert_eq!(left, srdwm_core::Rect::new(97, 100, 3, 150));
-        assert_eq!(right, srdwm_core::Rect::new(300, 100, 3, 150));
-    }
-
-    #[test]
-    fn shadow_rect_expands_geometry_by_shadow_size_on_every_side() {
-        let geom = srdwm_core::Rect::new(100, 100, 200, 150);
-        let s = shadow_rect(geom);
-        assert_eq!(s, srdwm_core::Rect::new(100 - SHADOW_SIZE as i32, 100 - SHADOW_SIZE as i32, 200 + SHADOW_SIZE * 2, 150 + SHADOW_SIZE * 2));
-    }
-
-    #[test]
-    fn shadow_bitmap_is_the_expected_size_and_transparent_under_the_window() {
-        let buf = shadow_bitmap(40, 20);
-        let width = 40 + SHADOW_SIZE * 2;
-        let height = 20 + SHADOW_SIZE * 2;
-        assert_eq!(buf.len(), (width * height * 4) as usize);
-        // Dead center is inside the window's own footprint - must stay
-        // fully transparent, since the window's own content draws over it.
-        let mid = ((height / 2) * width + width / 2) * 4;
-        assert_eq!(buf[mid as usize + 3], 0);
-    }
-
-    #[test]
-    fn shadow_bitmap_is_darkest_right_at_the_window_edge_and_fades_outward() {
-        let buf = shadow_bitmap(40, 20);
-        let width = (40 + SHADOW_SIZE * 2) as usize;
-        // Walking straight up from the window's horizontal center, from one
-        // pixel above its top edge (row SHADOW_SIZE - 1) out to the shadow's
-        // own outer edge (row 0): alpha must start near SHADOW_MAX_ALPHA and
-        // strictly decrease to 0.
-        let x = width / 2;
-        let mut last_alpha = 255u8;
-        for row in (0..SHADOW_SIZE as usize).rev() {
-            let i = (row * width + x) * 4;
-            let alpha = buf[i + 3];
-            assert!(alpha <= last_alpha, "alpha rose from {last_alpha} to {alpha} moving outward at row {row}");
-            last_alpha = alpha;
-        }
-        assert_eq!(last_alpha, 0, "outermost row must be fully transparent");
-    }
-
-    #[test]
-    fn fills_background_when_no_text() {
-        let buf = render_titlebar(40, 20, "", (0x2e, 0x34, 0x40), (0xec, 0xef, 0xf4), true, CORNER_RADIUS);
-        assert_eq!(buf.len(), 40 * 20 * 4);
-        // Center, not (0,0): the top-left pixel is inside the rounded
-        // corner `round_top_corners` clips away, so it's transparent by
-        // design - see `corners_are_clipped_but_the_middle_is_not` below.
-        let mid = ((20 / 2) * 40 + 40 / 2) * 4;
-        assert_eq!(&buf[mid..mid + 4], &rgb_to_bgra((0x2e, 0x34, 0x40), 255));
-    }
-
-    #[test]
-    fn button_icons_are_drawn_in_the_squares_hit_test_assigns_them() {
-        // Regression test for a bug where every drawn icon was one full
-        // button-width left of where a click on it actually landed: the
-        // visible "X" triggered Maximize, the visible square triggered
-        // Minimize, and the true Close hit-zone (the rightmost
-        // TITLEBAR_HEIGHT-wide band) was blank. `button_box`'s
-        // `right_offset` must put each icon in the same square
-        // `ResizeEdge::hit_test` assigns to it - checked here by picking
-        // the centre pixel of each drawn icon's square and confirming
-        // `hit_test` reports the matching button for that same point.
-        let (width, height) = (300u32, srdwm_core::TITLEBAR_HEIGHT);
-        let bg = (0x2e, 0x34, 0x40);
-        let fg = (0xec, 0xef, 0xf4);
-        let buf = render_titlebar(width, height, "", bg, fg, true, CORNER_RADIUS);
-        let frame = srdwm_core::Rect::new(0, 0, width, height);
-        let (width, height) = (width as usize, height as usize);
-
-        let bg_bytes = rgb_to_bgra(bg, 255);
-        for (right_offset, expected) in [(0, srdwm_core::TitlebarHit::Close), (height, srdwm_core::TitlebarHit::Maximize), (height * 2, srdwm_core::TitlebarHit::Minimize)] {
-            let (x0, y0, x1, y1) = button_box(width, height, right_offset);
-            let drawn = (y0..=y1).any(|y| (x0..=x1).any(|x| buf[(y as usize * width + x as usize) * 4..(y as usize * width + x as usize) * 4 + 4] != bg_bytes));
-            assert!(drawn, "expected some drawn icon pixel inside the right_offset={right_offset} square");
-            let cx = (x0 + x1) / 2;
-            let cy = (y0 + y1) / 2;
-            assert_eq!(
-                srdwm_core::ResizeEdge::hit_test(frame, cx, cy, true, 0, srdwm_core::RESIZE_MARGIN),
-                Some(expected),
-                "icon drawn at right_offset={right_offset} does not land in the square hit_test assigns to {expected:?}"
-            );
-        }
-    }
-
-    #[test]
-    fn drawing_title_changes_some_pixels_when_font_available() {
-        if find_system_font().is_none() {
-            eprintln!("skipping: no system font found in this sandbox");
-            return;
-        }
-        let bg = (0x2e, 0x34, 0x40);
-        let fg = (0xec, 0xef, 0xf4);
-        let buf = render_titlebar(200, 30, "Terminal", bg, fg, true, CORNER_RADIUS);
-        let bg_bytes = rgb_to_bgra(bg, 255);
-        let changed = buf.chunks_exact(4).any(|px| px != bg_bytes);
-        assert!(changed, "expected at least one pixel to differ from the background once text is drawn");
-    }
-
-    #[test]
-    fn empty_title_leaves_buffer_all_background_outside_the_rounded_corners() {
-        let bg = (0x10, 0x20, 0x30);
-        let (width, height) = (50, 24);
-        let buf = render_titlebar(width, height, "", bg, (0xff, 0xff, 0xff), true, CORNER_RADIUS);
-        let bg_bytes = rgb_to_bgra(bg, 255);
-        for (i, px) in buf.chunks_exact(4).enumerate() {
-            let (x, y) = (i % width as usize, i / width as usize);
-            let in_top_left = x < CORNER_RADIUS as usize && y < CORNER_RADIUS as usize;
-            let in_top_right = x >= width as usize - CORNER_RADIUS as usize && y < CORNER_RADIUS as usize;
-            if !in_top_left && !in_top_right {
-                assert_eq!(px, bg_bytes, "unexpected non-background pixel at ({x}, {y})");
-            }
-        }
-    }
-
-    #[test]
-    fn corners_are_clipped_but_the_middle_is_not() {
-        let bg = (0x10, 0x20, 0x30);
-        let (width, height) = (50, 24);
-        let buf = render_titlebar(width, height, "", bg, (0xff, 0xff, 0xff), true, CORNER_RADIUS);
-        let alpha_at = |x: usize, y: usize| buf[(y * width as usize + x) * 4 + 3];
-        // The very corner pixel is well outside the quarter-circle at any
-        // sane radius - fully clipped.
-        assert_eq!(alpha_at(0, 0), 0, "top-left corner pixel should be transparent");
-        assert_eq!(alpha_at(width as usize - 1, 0), 0, "top-right corner pixel should be transparent");
-        // Bottom corners are deliberately left square (see the function's
-        // doc comment: the titlebar's bottom edge meets client content,
-        // which can't be clipped the same way).
-        assert_eq!(alpha_at(0, height as usize - 1), 255, "bottom-left must stay square");
-        assert_eq!(alpha_at(width as usize - 1, height as usize - 1), 255, "bottom-right must stay square");
-        // Centre is nowhere near either corner circle - untouched.
-        assert_eq!(alpha_at(width as usize / 2, height as usize / 2), 255);
-    }
-
-    #[test]
-    fn clipped_corner_pixels_are_fully_premultiplied_zero_not_just_alpha() {
-        // Regression test: `round_top_corners` used to zero only the alpha
-        // byte of a clipped pixel, leaving the opaque background RGB behind
-        // it untouched. This buffer is `Fourcc::Argb8888`, which both
-        // Wayland/`wl_shm` and Pixman treat as premultiplied - Pixman's own
-        // `OVER` compositing (`result = src + dst * (1 - src_alpha)`) does
-        // not treat `alpha=0, rgb=<something>` as "contributes nothing": it
-        // adds that stale, un-premultiplied `rgb` straight through, so the
-        // "clipped" corner still rendered fully opaque and every window's
-        // top corners read as square regardless of a nonzero radius --
-        // confirmed live, pixel-by-pixel, zero transparency anywhere in a
-        // real window's corner. A genuinely transparent premultiplied pixel
-        // is `(0, 0, 0, 0)` in every channel, not just alpha.
-        let bg = (0x10, 0x20, 0x30);
-        let (width, height) = (50, 24);
-        let buf = render_titlebar(width, height, "", bg, (0xff, 0xff, 0xff), true, CORNER_RADIUS);
-        let px_at = |x: usize, y: usize| &buf[(y * width as usize + x) * 4..(y * width as usize + x) * 4 + 4];
-        assert_eq!(px_at(0, 0), [0, 0, 0, 0], "top-left corner pixel must be fully zeroed (premultiplied transparent), not just alpha");
-        assert_eq!(px_at(width as usize - 1, 0), [0, 0, 0, 0], "top-right corner pixel must be fully zeroed (premultiplied transparent), not just alpha");
-    }
-
-    #[test]
-    fn round_corners_false_leaves_the_top_corners_square() {
-        let bg = (0x10, 0x20, 0x30);
-        let (width, height) = (50, 24);
-        let buf = render_titlebar(width, height, "", bg, (0xff, 0xff, 0xff), false, CORNER_RADIUS);
-        let alpha_at = |x: usize, y: usize| buf[(y * width as usize + x) * 4 + 3];
-        assert_eq!(alpha_at(0, 0), 255, "top-left corner should stay square when round_corners is false");
-        assert_eq!(alpha_at(width as usize - 1, 0), 255, "top-right corner should stay square when round_corners is false");
-    }
-
-    #[test]
-    fn border_top_rounds_its_own_top_corners_to_match_the_titlebar() {
-        // Regression coverage for the "not all window borders are rounded"
-        // report: a bordered window's titlebar used to render with
-        // `round_corners = false` specifically to avoid clashing with this
-        // strip's square corners. Now that this strip rounds too, that
-        // workaround is gone (`render_titlebar` is always called with
-        // `true`) - this just confirms the strip actually does what that
-        // change now depends on.
-        let color = (0x40, 0x50, 0x60);
-        let (width, thickness) = (60, 2);
-        let buf = render_border_top(width, thickness, color, CORNER_RADIUS);
-        let alpha_at = |x: usize, y: usize| buf[(y * width as usize + x) * 4 + 3];
-        assert_eq!(alpha_at(0, 0), 0, "top-left corner pixel should be clipped");
-        assert_eq!(alpha_at(width as usize - 1, 0), 0, "top-right corner pixel should be clipped");
-        // A 2px-thick strip is thinner than any sane radius, so the clamp
-        // in `round_top_corners` bounds the cut to the strip's own height --
-        // the bottom row, at least at the strip's horizontal centre, must
-        // stay opaque or there would be no border left to see at all.
-        assert_eq!(alpha_at(width as usize / 2, thickness as usize - 1), 255, "centre of the strip must stay opaque");
-    }
-
-    #[test]
-    fn border_bottom_rounds_its_own_bottom_corners() {
-        let color = (0x40, 0x50, 0x60);
-        let (width, thickness) = (60, 2);
-        let buf = render_border_bottom(width, thickness, color, CORNER_RADIUS);
-        let alpha_at = |x: usize, y: usize| buf[(y * width as usize + x) * 4 + 3];
-        assert_eq!(alpha_at(0, thickness as usize - 1), 0, "bottom-left corner pixel should be clipped");
-        assert_eq!(alpha_at(width as usize - 1, thickness as usize - 1), 0, "bottom-right corner pixel should be clipped");
-        assert_eq!(alpha_at(width as usize / 2, 0), 255, "centre of the strip must stay opaque");
-    }
-
-    #[test]
-    fn context_menu_is_one_row_tall_per_item() {
-        let items = [("Minimize", false), ("Maximize", false), ("Always on Top", false), ("Close", false)];
-        let buf = render_context_menu(160, 28, &items, (0x2e, 0x34, 0x40), (0xff, 0xff, 0xff), (0x4c, 0x56, 0x6a), (0x10, 0x10, 0x10));
-        assert_eq!(buf.len(), 160 * (28 * 4) * 4);
-    }
-
-    #[test]
-    fn context_menu_highlighted_row_has_a_different_background_than_the_rest() {
-        let items = [("Minimize", false), ("Close", true)];
-        let bg = (0x2e, 0x34, 0x40);
-        let highlight = (0x4c, 0x56, 0x6a);
-        let buf = render_context_menu(160, 28, &items, bg, (0xff, 0xff, 0xff), highlight, (0x10, 0x10, 0x10));
-        let width = 160usize;
-        // Sample a background pixel from each row, away from the text/border.
-        let px_at = |x: usize, y: usize| -> [u8; 3] {
-            let i = (y * width + x) * 4;
-            [buf[i + 2], buf[i + 1], buf[i]] // BGRA -> RGB
-        };
-        assert_eq!(px_at(100, 5), [bg.0, bg.1, bg.2], "row 0 (not highlighted) should use bg");
-        assert_eq!(px_at(100, 33), [highlight.0, highlight.1, highlight.2], "row 1 (highlighted) should use highlight_bg");
-    }
-
-    #[test]
-    fn context_menu_border_is_opaque_at_every_edge() {
-        let items = [("Close", false)];
-        let buf = render_context_menu(100, 28, &items, (0, 0, 0), (0xff, 0xff, 0xff), (0, 0, 0), (0x99, 0x99, 0x99));
-        let alpha_at = |x: usize, y: usize| buf[(y * 100 + x) * 4 + 3];
-        assert_eq!(alpha_at(0, 0), 255);
-        assert_eq!(alpha_at(99, 0), 255);
-        assert_eq!(alpha_at(0, 27), 255);
-        assert_eq!(alpha_at(99, 27), 255);
-    }
-
-    #[test]
-    fn snap_flyout_is_sized_for_a_full_grid_of_labels() {
-        let labels = ["Left Half", "Right Half", "Top Left", "Top Right", "Bottom Left", "Bottom Right"];
-        let buf = render_snap_flyout(3, 90, 60, &labels, (0x2e, 0x34, 0x40), (0xff, 0xff, 0xff), (0x10, 0x10, 0x10));
-        // 3 columns x 2 rows (6 labels / 3 columns, rounded up).
-        assert_eq!(buf.len(), (90 * 3) * (60 * 2) * 4);
-    }
-
-    #[test]
-    fn snap_flyout_border_is_opaque_at_every_outer_edge() {
-        let labels = ["A", "B", "C", "D", "E", "F"];
-        let (cell_w, cell_h) = (90, 60);
-        let buf = render_snap_flyout(3, cell_w, cell_h, &labels, (0, 0, 0), (0xff, 0xff, 0xff), (0x99, 0x99, 0x99));
-        let (width, height) = (cell_w * 3, cell_h * 2);
-        let alpha_at = |x: usize, y: usize| buf[(y * width as usize + x) * 4 + 3];
-        assert_eq!(alpha_at(0, 0), 255);
-        assert_eq!(alpha_at(width as usize - 1, 0), 255);
-        assert_eq!(alpha_at(0, height as usize - 1), 255);
-        assert_eq!(alpha_at(width as usize - 1, height as usize - 1), 255);
-    }
-
-    #[test]
-    fn snap_flyout_has_an_internal_grid_line_between_columns() {
-        let labels = ["A", "B", "C", "D", "E", "F"];
-        let (cell_w, cell_h) = (90, 60);
-        let buf = render_snap_flyout(3, cell_w, cell_h, &labels, (0, 0, 0), (0xff, 0xff, 0xff), (0x99, 0x99, 0x99));
-        let width = cell_w * 3;
-        // The boundary between column 0 and column 1, away from the outer border.
-        let idx = (30 * width as usize + cell_w as usize) * 4;
-        assert_eq!(buf[idx + 3], 255, "column boundary must be drawn, not just the outer border");
-    }
-}
+mod tests;
diff --git a/crates/wayland/src/decoration/border.rs b/crates/wayland/src/decoration/border.rs
new file mode 100644
index 0000000..472ef3b
--- /dev/null
+++ b/crates/wayland/src/decoration/border.rs
@@ -0,0 +1,184 @@
+//! The four solid-colour strips around a decorated window's own `geometry`
+//! - top/bottom rendered as small rounded bitmaps (their own two outer
+//! corners cut to match `titlebar::render_titlebar`'s), left/right left to
+//! the caller as plain flat fills (`elements::border_side_render_element`).
+
+use super::color::rgb_to_bgra;
+use super::corners::{round_bottom_corners, round_top_corners};
+
+pub fn border_strips(geometry: srdwm_core::Rect, width: u32) -> [srdwm_core::Rect; 4] {
+    let w = width as i32;
+    [
+        srdwm_core::Rect::new(geometry.x - w, geometry.y - w, geometry.width + 2 * width, width),
+        srdwm_core::Rect::new(geometry.x - w, geometry.y + geometry.height as i32, geometry.width + 2 * width, width),
+        srdwm_core::Rect::new(geometry.x - w, geometry.y, width, geometry.height),
+        srdwm_core::Rect::new(geometry.x + geometry.width as i32, geometry.y, width, geometry.height),
+    ]
+}
+
+/// Renders the top border strip (`border_strips`'s first rect) as a BGRA8
+/// bitmap instead of a plain solid fill, with its own outer top corners cut
+/// the same way `titlebar::render_titlebar`'s `round_corners` cuts the
+/// titlebar's - see that parameter's doc comment for why a titlebar rounds
+/// but a square border frame around it used to defeat the point. This
+/// strip's own row 0 sits at the *true* top of the combined titlebar-plus-
+/// border shape (the border is the outermost layer), so it shares the
+/// titlebar's exact same circle - same `radius`, unshifted `center_row` --
+/// rather than a same-centre-different-radius circle of its own; see
+/// `corners::round_top_corners`'s own doc comment for why an earlier
+/// version of this (`radius + thickness` as the radius passed there) drew a
+/// visibly different curve that didn't actually meet the titlebar's at the
+/// seam between them, and `titlebar::render_titlebar`'s call site for the
+/// other half of this pair.
+///
+/// [`render_border_bottom`] gives the bottom strip the matching treatment
+/// for its own two corners.
+///
+/// The buffer is `thickness.max(radius)` rows tall, not always exactly
+/// `thickness` - when `radius > thickness` (true even at this codebase's
+/// own theme defaults, radius 6 over a 4px border), the corner's curve
+/// doesn't finish resolving to flat within just `thickness` rows, and the
+/// left/right strips (`border_side_render_element`, plain flat rectangles
+/// with no curve awareness of their own, starting immediately at this
+/// strip's own bottom edge) have no way to cover the rest of it - the
+/// result was a real, visible wedge of bare background between the
+/// straight border segments and the window's own rounded silhouette,
+/// worse the larger the radius/thickness gap, confirmed live via pixel-
+/// level inspection of a real screenshot (not just reasoned about): the
+/// horizontal top segment only became visible some ~20 columns in from the
+/// corner while the vertical side segment started almost immediately,
+/// exactly the asymmetry a too-short top strip and a curve-blind side
+/// strip produce together. Extending this buffer to the *full* radius
+/// gives the curve enough room to finish, and - since this element draws
+/// on top of the side strips (`render_udev_frame` pushes it first, and
+/// earlier-pushed custom elements composite over later ones) - the extra
+/// rows correctly overpaint the side strip's naive square corner with the
+/// real curve, no changes needed to the side strips or their occlusion-
+/// fragment splitting at all.
+///
+/// Rows past the original `thickness` are real *extra* canvas purely so
+/// the corner columns have room to curve - the middle (non-corner)
+/// columns of those rows sit visually inside where the titlebar/content
+/// begins, not the border ring, so they're forced transparent after
+/// rounding rather than left as solid `color` (which would otherwise paint
+/// a solid border-coloured bar over the titlebar's own left/right edges
+/// for however many rows this extended by).
+pub fn render_border_top(width: u32, thickness: u32, color: (u8, u8, u8), radius: u32) -> Vec<u8> {
+    let (width, thickness) = (width.max(1) as usize, thickness.max(1) as usize);
+    let height = thickness.max(radius as usize).max(1);
+    let bg = rgb_to_bgra(color, 255);
+    let mut buf = vec![0u8; width * height * 4];
+    for px in buf.chunks_exact_mut(4) {
+        px.copy_from_slice(&bg);
+    }
+    round_top_corners(&mut buf, width, height, radius, radius as i32);
+    clip_middle_beyond_thickness(&mut buf, width, radius as usize, thickness..height);
+    buf
+}
+
+/// Zeroes the non-corner (middle) columns of every row in `rows` - the
+/// "extra" rows `render_border_top`/`render_border_bottom` add past their
+/// own true `thickness` purely to give a corner's curve room to resolve.
+/// Left untouched, those rows would stay solid `color` outside the two
+/// corner column-ranges (nothing else clips them), painting a border-
+/// coloured bar across whatever the titlebar/content actually owns there.
+/// `radius` here is the corner column width on each side (already clamped
+/// to `width / 2` inside `corners::round_top_corners`/`round_bottom_
+/// corners`, so this re-derives the same clamp rather than trusting the
+/// caller's raw value).
+fn clip_middle_beyond_thickness(buf: &mut [u8], width: usize, radius: usize, rows: std::ops::Range<usize>) {
+    let r = radius.min(width / 2);
+    if r * 2 >= width {
+        return;
+    }
+    for y in rows {
+        let row = y * width * 4;
+        buf[row + r * 4..row + (width - r) * 4].fill(0);
+    }
+}
+
+/// [`render_border_top`]'s mirror for the bottom strip - same construction,
+/// its own two corners (bottom-left/bottom-right) cut instead. Reported
+/// live, alongside the top-corner work: a bordered window's bottom two
+/// corners still read as square next to the now-rounded top ones, the same
+/// "inconsistently square" complaint that motivated rounding the top strip
+/// in the first place.
+///
+/// Handled as one all-or-nothing bitmap rather than folded into the
+/// left/right strips' per-fragment occlusion splitting (`visible_border_
+/// fragments`) - the same trade-off `render_border_top`'s own call site
+/// already makes and for the same reason: cropping a rounded bitmap's
+/// source rect per fragment is real extra work for a strip this thin.
+pub fn render_border_bottom(width: u32, thickness: u32, color: (u8, u8, u8), radius: u32) -> Vec<u8> {
+    let (width, thickness) = (width.max(1) as usize, thickness.max(1) as usize);
+    let height = thickness.max(radius as usize).max(1);
+    let bg = rgb_to_bgra(color, 255);
+    let mut buf = vec![0u8; width * height * 4];
+    for px in buf.chunks_exact_mut(4) {
+        px.copy_from_slice(&bg);
+    }
+    // Plain `radius`, not `radius + thickness` (what this line passed
+    // before) - that drew the corner against a *larger*, self-invented
+    // circle than the window's own `corner_radius`, the exact same wrong
+    // shape the top strip's own seam fix already rejected for an
+    // equivalent reason (see `corners::round_top_corners`'s doc comment):
+    // sampling only the near-flat tip of an oversized circle produces a
+    // curve that barely bends at all, not one that matches the window's
+    // real corner. `render_border_top` gets `radius` used unshifted here
+    // for the same reason it does: this buffer's own outermost row is
+    // genuinely the true tip of the shape.
+    round_bottom_corners(&mut buf, width, height, radius);
+    // Extra rows sit above the original `thickness`, not below - the
+    // bottom strip's curve resolves going *up* into content, the mirror of
+    // the top strip's resolving *down* into it. See
+    // `clip_middle_beyond_thickness`'s own doc comment for why this needs
+    // to happen at all.
+    clip_middle_beyond_thickness(&mut buf, width, radius as usize, 0..height - thickness);
+    buf
+}
+
+/// Which rows of `render_border_top`'s own buffer a real call site should
+/// actually draw, and how far below the strip's nominal position to start
+/// (`(start_row, row_count, position_shift_down)`) - pulled out as a
+/// plain, backend-independent function so both `udev/render.rs` and
+/// `winit/render.rs` share one tested answer instead of two hand-written
+/// copies that could quietly drift apart.
+///
+/// `decorated` matters because the buffer's own "extra" rows (past
+/// `border_width`, present whenever `corner_radius > border_width`) are
+/// colour-filled at the two corner columns by design - safe to draw only
+/// because a *decorated* window has a titlebar band directly beneath this
+/// strip to receive them (see `render_border_top`'s own doc comment). An
+/// undecorated (CSD) window has no such band: `frame.y` is the top of the
+/// client's own real content, immediately below the nominal `border_width`
+/// rows, so those same extra rows would paint a border-coloured wedge onto
+/// it instead - confirmed live on a real Firefox window, not assumed.
+/// Cropping to just the nominal rows in that case is the fix; the buffer's
+/// own row 0 already sits at the correct position either way (this strip
+/// grows *downward*, unlike its bottom sibling), so the shift is always 0.
+pub(crate) fn border_top_visible_rows(decorated: bool, border_width: u32, corner_radius: u32) -> (u32, u32, u32) {
+    let border_width = border_width.max(1);
+    if decorated {
+        (0, border_width.max(corner_radius), 0)
+    } else {
+        (0, border_width, 0)
+    }
+}
+
+/// [`border_top_visible_rows`]'s mirror for `render_border_bottom`'s own
+/// buffer, whose extra rows sit *above* the nominal ones (growing upward
+/// into content) rather than below - so the nominal, safe-to-draw-
+/// unconditionally rows are the buffer's *last* `border_width` of them,
+/// starting at `start_row = extra`, and skipping them entirely (undecorated
+/// case) also means skipping the compensating downward-shift-into-content
+/// a decorated window's fuller buffer needs, landing back at this strip's
+/// own unshifted nominal position instead.
+pub(crate) fn border_bottom_visible_rows(decorated: bool, border_width: u32, corner_radius: u32) -> (u32, u32, u32) {
+    let border_width = border_width.max(1);
+    let extra = border_width.max(corner_radius) - border_width;
+    if decorated {
+        (0, border_width.max(corner_radius), extra)
+    } else {
+        (extra, border_width, 0)
+    }
+}
diff --git a/crates/wayland/src/decoration/buttons.rs b/crates/wayland/src/decoration/buttons.rs
new file mode 100644
index 0000000..a965ef6
--- /dev/null
+++ b/crates/wayland/src/decoration/buttons.rs
@@ -0,0 +1,291 @@
+//! The three titlebar buttons' own dots and glyphs - traffic-light fill,
+//! glossy shading, and the four hand-drawn glyph shapes (X / dash / square
+//! / zoom-arrows). `titlebar.rs` owns *laying out* the cluster (which
+//! button goes where, which side, how many); everything here just draws
+//! one button once given its own box.
+
+use super::color::rgb_to_bgra;
+
+/// Titlebar buttons are laid out right-aligned in `srdwm_core::BUTTON_PITCH`-
+/// wide squares, vertically centred inside the taller `height` band --
+/// matching `ResizeEdge::hit_test` in `crates/core/src/window.rs`, whose
+/// `BUTTON` constant is also `BUTTON_PITCH`, not `TITLEBAR_HEIGHT` (see that
+/// constant's own doc comment for why the two were split apart). That
+/// function only computes *where* a click on close/maximize/minimize lands;
+/// nothing painted the buttons themselves, so the whole band was one
+/// undifferentiated bar with no visible way to tell where those three
+/// clickable regions were.
+pub(super) const BUTTON_MARGIN: f32 = 0.32;
+/// Smaller margin used only when `buttons_left` is set - explicitly
+/// requested ("bigger" buttons on the left, matching macOS convention).
+/// The button's own *box* stays the same size as the right-aligned case
+/// (see `ResizeEdge::hit_test`'s matching comment on why growing the box
+/// itself would clip against its own pitch); a smaller margin just lets
+/// the dot fill more of that same box. `0.1667` specifically: a button
+/// diameter is `BUTTON_PITCH * (1 - 2 * margin)`, which at `BUTTON_PITCH
+/// = 24` gives a 16px dot - measured directly against a real, live
+/// Firefox window (column-scanned screenshot, edges at 40% luminance
+/// difference from the titlebar background): dot diameter 16px, centre-
+/// to-centre pitch 24px, at this same system's own scale. A previous
+/// `0.25` (12px dot) undershot this - it came from an estimate against a
+/// downloaded reference screenshot rather than a live, same-scale
+/// measurement.
+pub(super) const BUTTON_MARGIN_LEFT: f32 = 0.1667;
+/// How long the titlebar-button glyph-reveal-on-hover animation takes to
+/// reach full opacity - matches real, extracted libadwaita CSS on this
+/// machine almost exactly (`transition: ... 200ms cubic-bezier(...)` on
+/// `windowcontrols > button > image`, found via `gresource extract` on the
+/// installed `.so`, not guessed), even though this project's own default
+/// mode (`ThemeConfig::button_glyph_always`) animates the glyph itself in
+/// rather than Adwaita's own choice of animating the background circle
+/// with the glyph always shown - the *timing* still carries over as the
+/// one piece of real DE precedent either mode can share.
+pub(crate) const HOVER_GLYPH_DURATION: std::time::Duration = std::time::Duration::from_millis(200);
+
+/// Traffic-light button colours (close/minimize/maximize), matching macOS's
+/// own - and, on this machine, matching what Firefox's own CSD already
+/// renders via the WhiteSur GTK theme (confirmed live via `grim`: an
+/// unfocused Firefox window shows the same flat grey dots
+/// `TRAFFIC_LIGHT_INACTIVE` below produces). srdwm's own SSD titlebar used
+/// to draw a plain outline glyph (X/square/dash) in the ordinary text
+/// colour instead - reported live as looking nothing like the traffic-
+/// light buttons every CSD client on this theme already has, and as
+/// visibly different window furniture between, e.g., Firefox (CSD, real
+/// traffic lights) and a terminal (SSD, srdwm's own outline glyphs) side by
+/// side. These are deliberately plain colour constants, not new theme
+/// fields - the accepted, still-open ask is hover-state glyph/highlight
+/// work on top of this base look (see `docs/TODO.md`), not a configurable
+/// palette for it.
+pub(super) const TRAFFIC_LIGHT_CLOSE: (u8, u8, u8) = (0xff, 0x5f, 0x57);
+pub(super) const TRAFFIC_LIGHT_MINIMIZE: (u8, u8, u8) = (0xff, 0xbd, 0x2e);
+pub(super) const TRAFFIC_LIGHT_MAXIMIZE: (u8, u8, u8) = (0x28, 0xc8, 0x40);
+/// Unfocused state for all three buttons - real macOS (and this WhiteSur
+/// theme) dims every traffic light to the same flat grey when its window
+/// isn't active, rather than keeping the colours at reduced opacity.
+pub(super) const TRAFFIC_LIGHT_INACTIVE: (u8, u8, u8) = (0x6e, 0x6e, 0x6e);
+
+/// The `srdwm_core::BUTTON_PITCH`-square box a button's dot is drawn inside,
+/// `offset` pixels in from whichever edge `from_left` selects and centred
+/// vertically inside the taller `height` titlebar band - the box's own
+/// size is the same regardless of side (see `ResizeEdge::hit_test`'s
+/// matching comment on why a *bigger box* on the left would risk the dot
+/// clipping against its own pitch; only the margin, and so the dot within
+/// the same box, actually grows there - `titlebar::render_titlebar`'s own
+/// call site picks `BUTTON_MARGIN`/`BUTTON_MARGIN_LEFT` accordingly).
+pub(super) fn button_box(width: usize, height: usize, offset: usize, from_left: bool, margin: f32) -> (i32, i32, i32, i32) {
+    let square = srdwm_core::BUTTON_PITCH as i32;
+    let inset = (square as f32 * margin).round() as i32;
+    let top = ((height as i32 - square) / 2).max(0);
+    let (left, right) = if from_left { (offset as i32, offset as i32 + square) } else { (width as i32 - offset as i32 - square, width as i32 - offset as i32) };
+    (left + inset, top + inset, right - inset, top + square - inset)
+}
+
+/// Fills a traffic-light dot centred in its button square, anti-aliased the
+/// same `smoothstep` way `corners::blend_corner_pixel` rounds a window's
+/// own corners - a hard-edged circle at this size (typically well under
+/// `TITLEBAR_HEIGHT`, i.e. a ~20px-diameter dot) read as visibly jagged,
+/// the same class of problem the corner-seam fix already solved for a
+/// bigger radius. Unlike that function (which reduces an existing pixel's
+/// alpha to clip it away), this blends *toward* `color` over whatever's
+/// already in `buf` - the titlebar background, always already opaque here
+/// - so the result stays fully opaque at every edge pixel rather than
+/// letting the background show through a soft ring.
+pub(super) fn fill_button_dot(buf: &mut [u8], width: usize, height: usize, offset: usize, from_left: bool, margin: f32, color: (u8, u8, u8)) {
+    let (x0, y0, x1, y1) = button_box(width, height, offset, from_left, margin);
+    let cx = (x0 + x1) as f32 / 2.0;
+    let cy = (y0 + y1) as f32 / 2.0;
+    let radius = ((x1 - x0).min(y1 - y0) as f32 / 2.0).max(0.0);
+    let span = radius.ceil() as i32 + 2;
+    for y in (cy.round() as i32 - span)..=(cy.round() as i32 + span) {
+        if y < 0 || y as usize >= height {
+            continue;
+        }
+        for x in (cx.round() as i32 - span)..=(cx.round() as i32 + span) {
+            if x < 0 || x as usize >= width {
+                continue;
+            }
+            let (dx, dy) = (x as f32 - cx, y as f32 - cy);
+            let dist = (dx * dx + dy * dy).sqrt();
+            let t = ((dist - (radius - 1.0)) / 2.0).clamp(0.0, 1.0);
+            let coverage = 1.0 - (t * t * (3.0 - 2.0 * t));
+            if coverage <= 0.0 {
+                continue;
+            }
+            // Shaded per-pixel, not once for the whole dot - see
+            // `glossy_shade`'s own doc comment for why a flat fill read as
+            // noticeably flatter than real macOS's own traffic lights.
+            let target = rgb_to_bgra(glossy_shade(color, dx, dy, radius.max(1.0)), 255);
+            let idx = (y as usize * width + x as usize) * 4;
+            if coverage >= 1.0 {
+                buf[idx..idx + 4].copy_from_slice(&target);
+                continue;
+            }
+            for c in 0..3 {
+                let existing = buf[idx + c] as f32;
+                buf[idx + c] = (existing + (target[c] as f32 - existing) * coverage).round() as u8;
+            }
+            buf[idx + 3] = 255;
+        }
+    }
+}
+
+/// Shades a flat traffic-light colour into the soft glossy-sphere look real
+/// macOS buttons have, referenced directly against a real screenshot
+/// (Finder's own traffic lights, `~/Downloads`) rather than guessed at: a
+/// gentle highlight toward the upper-left, where its own light source
+/// sits, fading through the flat colour and into a touch of shadow toward
+/// the lower-right rim. Deliberately restrained on both ends - the lit
+/// side never blows out to white and the shadowed side never drops to a
+/// hard black ring - so every dot still reads as its own colour at a
+/// glance, just with real dimensionality instead of a flat fill. `(dx,
+/// dy)` is the pixel's own offset from the dot's centre, in the same units
+/// as `radius`, so this has no dependency on the caller's coordinate
+/// system beyond that.
+fn glossy_shade(color: (u8, u8, u8), dx: f32, dy: f32, radius: f32) -> (u8, u8, u8) {
+    let (nx, ny) = (dx / radius, dy / radius);
+    // Light source up and to the left - the same convention every real
+    // desktop's own icon/button shading already uses.
+    const LIGHT: (f32, f32) = (-0.55, -0.7);
+    const LIGHT_LEN: f32 = 0.888_819_44; // sqrt(0.55^2 + 0.7^2), precomputed
+    let facing = (nx * LIGHT.0 + ny * LIGHT.1) / LIGHT_LEN;
+    // A glossy sphere isn't uniformly lit even on its bright side - it
+    // dims gradually toward every edge, not just the shadowed one.
+    let rim = (nx * nx + ny * ny).min(1.0);
+    let highlight = facing.max(0.0) * (1.0 - rim * 0.4);
+    let shadow = (-facing).max(0.0) * 0.5 + rim * 0.15;
+    let mix_toward = |c: u8, target: f32, amount: f32| (c as f32 + (target - c as f32) * amount).clamp(0.0, 255.0) as u8;
+    let lit = (mix_toward(color.0, 255.0, highlight * 0.45), mix_toward(color.1, 255.0, highlight * 0.45), mix_toward(color.2, 255.0, highlight * 0.45));
+    (mix_toward(lit.0, 0.0, shadow * 0.35), mix_toward(lit.1, 0.0, shadow * 0.35), mix_toward(lit.2, 0.0, shadow * 0.35))
+}
+
+/// A semi-opaque colour blended over whatever's already at `(x, y)`, scaled
+/// by both `alpha` (the glyph-reveal animation's own current progress --
+/// see `tick_hover_glyph_animation`, or a flat 255 in `glyph_always` mode)
+/// and `coverage` (this pixel's own distance-based antialiasing weight from
+/// `blend_glyph_line`, 0..=1). `alpha == 0` is a plain no-op, so a not-yet-
+/// hovered button pays nothing for a glyph nobody can see yet, not even a
+/// fully-transparent draw call. `shade` is the colour blended toward --
+/// near-black for a glyph drawn on a traffic light's own bright fill, or
+/// the titlebar's real foreground colour for one drawn straight on the
+/// titlebar background instead (see `titlebar::render_titlebar`'s own
+/// `glyph_shade` local for which, and why).
+fn blend_glyph_px(buf: &mut [u8], width: usize, height: usize, x: i32, y: i32, alpha: u8, coverage: f32, shade: (u8, u8, u8)) {
+    if x < 0 || y < 0 || x as usize >= width || y as usize >= height || alpha == 0 || coverage <= 0.0 {
+        return;
+    }
+    let idx = (y as usize * width + x as usize) * 4;
+    let a = (alpha as f32 / 255.0) * coverage.min(1.0);
+    for (c, target) in [shade.0, shade.1, shade.2].into_iter().enumerate() {
+        let existing = buf[idx + c] as f32;
+        buf[idx + c] = (existing + (target as f32 - existing) * a).round().clamp(0.0, 255.0) as u8;
+    }
+}
+
+/// Half the glyph stroke's own width, in pixels, before the antialiased
+/// feather outside it - `0.55` reads as a crisp, thin stroke at this dot's
+/// own ~16px scale, matching how thin a real toolkit-rendered traffic-light
+/// glyph actually is. Reported live (a real, live screenshot, not the
+/// downloaded macOS reference this session started from) as visibly too
+/// bold at the previous `1.0` - a real glyph is a hairline, not a stroke
+/// that reads as almost as thick as the dot's own edge AA.
+const GLYPH_HALF_WIDTH: f32 = 0.55;
+
+/// A line segment with a soft, antialiased stroke - a raw Bresenham 1px
+/// line (the original implementation) has hard-stepped, jagged edges on
+/// any diagonal, which stood out badly against every other shape in this
+/// file (`fill_button_dot`, `corners::blend_corner_pixel`) already being
+/// smoothstep-antialiased. Distance-to-segment per candidate pixel, not a
+/// stepped walk, so the diagonal close-glyph "X" gets the same smooth edge
+/// its own button dot does. `shade` - see `blend_glyph_px`'s own doc
+/// comment - passes straight through unchanged.
+fn blend_glyph_line(buf: &mut [u8], width: usize, height: usize, from: (i32, i32), to: (i32, i32), alpha: u8, shade: (u8, u8, u8)) {
+    if alpha == 0 {
+        return;
+    }
+    let (x0, y0) = (from.0 as f32, from.1 as f32);
+    let (x1, y1) = (to.0 as f32, to.1 as f32);
+    let (dx, dy) = (x1 - x0, y1 - y0);
+    let len2 = (dx * dx + dy * dy).max(0.0001);
+    const FEATHER: f32 = 0.7;
+    let reach = (GLYPH_HALF_WIDTH + FEATHER).ceil() as i32;
+    let (xmin, xmax) = (from.0.min(to.0) - reach, from.0.max(to.0) + reach);
+    let (ymin, ymax) = (from.1.min(to.1) - reach, from.1.max(to.1) + reach);
+    for y in ymin..=ymax {
+        if y < 0 || y as usize >= height {
+            continue;
+        }
+        for x in xmin..=xmax {
+            if x < 0 || x as usize >= width {
+                continue;
+            }
+            let t = (((x as f32 - x0) * dx + (y as f32 - y0) * dy) / len2).clamp(0.0, 1.0);
+            let (px, py) = (x0 + t * dx, y0 + t * dy);
+            let dist = ((x as f32 - px).powi(2) + (y as f32 - py).powi(2)).sqrt();
+            let ft = ((dist - GLYPH_HALF_WIDTH) / FEATHER).clamp(0.0, 1.0);
+            let coverage = 1.0 - (ft * ft * (3.0 - 2.0 * ft));
+            blend_glyph_px(buf, width, height, x, y, alpha, coverage, shade);
+        }
+    }
+}
+
+/// The `[0.46]` shrink is deliberate, not arbitrary - the glyph has to sit
+/// visibly *inside* the dot's own circular edge (see `fill_button_dot`),
+/// not touch or cross it, matching real macOS traffic-light glyphs, which
+/// are always noticeably smaller than the button itself. `0.46`, not an
+/// earlier `0.62`: reported live (a rendered dump compared directly
+/// against a real reference screenshot) as too big - a real macOS hover
+/// glyph reads as a small, delicate mark centred in the dot, not a shape
+/// that nearly fills it.
+fn glyph_box(width: usize, height: usize, offset: usize, from_left: bool, margin: f32) -> (i32, i32, i32, i32) {
+    let (x0, y0, x1, y1) = button_box(width, height, offset, from_left, margin);
+    let (cx, cy) = ((x0 + x1) as f32 / 2.0, (y0 + y1) as f32 / 2.0);
+    let half = (x1 - x0).min(y1 - y0) as f32 / 2.0 * 0.46;
+    ((cx - half).round() as i32, (cy - half).round() as i32, (cx + half).round() as i32, (cy + half).round() as i32)
+}
+
+pub(super) fn draw_close_glyph(buf: &mut [u8], width: usize, height: usize, offset: usize, from_left: bool, margin: f32, alpha: u8, shade: (u8, u8, u8)) {
+    let (x0, y0, x1, y1) = glyph_box(width, height, offset, from_left, margin);
+    blend_glyph_line(buf, width, height, (x0, y0), (x1, y1), alpha, shade);
+    blend_glyph_line(buf, width, height, (x0, y1), (x1, y0), alpha, shade);
+}
+
+/// The plain square maximize icon - this project's own original look
+/// (`traffic_lights = false`, a real Windows/GNOME titlebar's own
+/// convention), and still what a traffic-light-style maximize falls back
+/// to if it doesn't get `draw_zoom_glyph` instead. See `titlebar::
+/// render_titlebar`'s own call site for which mode picks which.
+pub(super) fn draw_maximize_glyph(buf: &mut [u8], width: usize, height: usize, offset: usize, from_left: bool, margin: f32, alpha: u8, shade: (u8, u8, u8)) {
+    let (x0, y0, x1, y1) = glyph_box(width, height, offset, from_left, margin);
+    blend_glyph_line(buf, width, height, (x0, y0), (x1, y0), alpha, shade);
+    blend_glyph_line(buf, width, height, (x0, y1), (x1, y1), alpha, shade);
+    blend_glyph_line(buf, width, height, (x0, y0), (x0, y1), alpha, shade);
+    blend_glyph_line(buf, width, height, (x1, y0), (x1, y1), alpha, shade);
+}
+
+pub(super) fn draw_minimize_glyph(buf: &mut [u8], width: usize, height: usize, offset: usize, from_left: bool, margin: f32, alpha: u8, shade: (u8, u8, u8)) {
+    let (x0, y0, x1, y1) = glyph_box(width, height, offset, from_left, margin);
+    let mid = (y0 + y1) / 2;
+    blend_glyph_line(buf, width, height, (x0, mid), (x1, mid), alpha, shade);
+}
+
+/// Real macOS's "zoom" maximize glyph - a double-headed diagonal arrow,
+/// not a square - for `traffic_lights = true` only (see `titlebar::
+/// render_titlebar`'s own call site). One diagonal shaft from the glyph
+/// box's bottom-left to its top-right corner, plus a small two-stroke
+/// arrowhead at each end pointing further outward (away from the glyph's
+/// own centre) - the same primitive (`blend_glyph_line`) every other
+/// glyph here already uses, so this reads as the same family of icon
+/// rather than a different rendering technique bolted on just for this one
+/// shape.
+pub(super) fn draw_zoom_glyph(buf: &mut [u8], width: usize, height: usize, offset: usize, from_left: bool, margin: f32, alpha: u8, shade: (u8, u8, u8)) {
+    let (x0, y0, x1, y1) = glyph_box(width, height, offset, from_left, margin);
+    blend_glyph_line(buf, width, height, (x0, y1), (x1, y0), alpha, shade);
+    let head = (((x1 - x0).max(1) as f32) * 0.4).round() as i32;
+    // Top-right arrowhead, pointing further up-right (away from centre).
+    blend_glyph_line(buf, width, height, (x1, y0), (x1 - head, y0), alpha, shade);
+    blend_glyph_line(buf, width, height, (x1, y0), (x1, y0 + head), alpha, shade);
+    // Bottom-left arrowhead, pointing further down-left (away from centre).
+    blend_glyph_line(buf, width, height, (x0, y1), (x0 + head, y1), alpha, shade);
+    blend_glyph_line(buf, width, height, (x0, y1), (x0, y1 - head), alpha, shade);
+}
+
diff --git a/crates/wayland/src/decoration/color.rs b/crates/wayland/src/decoration/color.rs
new file mode 100644
index 0000000..7ea9d80
--- /dev/null
+++ b/crates/wayland/src/decoration/color.rs
@@ -0,0 +1,34 @@
+//! Small, dependency-free colour helpers shared across every other
+//! `decoration` submodule - converting to the renderer's own byte order,
+//! and the two directional blends (`brighten`/`darken`) button/glyph
+//! shading needs. Nothing here reads a pixel buffer or knows what a
+//! titlebar/border/shadow is; see `buttons.rs` for the module that actually
+//! applies these.
+
+pub(crate) fn rgb_to_bgra(rgb: (u8, u8, u8), alpha: u8) -> [u8; 4] {
+    [rgb.2, rgb.1, rgb.0, alpha]
+}
+
+/// Lightens a button colour for the hover state - see `render_titlebar`'s
+/// `hovered` parameter. Blends toward white rather than just scaling each
+/// channel up, so a fully-saturated channel (e.g. green's `0x00` blue) still
+/// visibly brightens instead of clamping at its own max with nothing left
+/// to move.
+pub(crate) fn brighten(color: (u8, u8, u8)) -> (u8, u8, u8) {
+    const AMOUNT: f32 = 0.35;
+    let mix = |c: u8| (c as f32 + (255.0 - c as f32) * AMOUNT).round() as u8;
+    (mix(color.0), mix(color.1), mix(color.2))
+}
+
+/// Darkens a colour toward black by a fixed fraction - used for a traffic-
+/// light glyph's own shade (see `render_titlebar`'s call site): real macOS
+/// draws each button's glyph as a *darker shade of that same button's own
+/// hue* (a dark red mark on the red button, dark amber on the yellow one),
+/// not one universal near-black tint reused across all three - reported
+/// live as looking too dark/heavy and not colour-matched once compared
+/// directly against a real hover-glyph screenshot.
+pub(crate) fn darken(color: (u8, u8, u8)) -> (u8, u8, u8) {
+    const AMOUNT: f32 = 0.45;
+    let mix = |c: u8| (c as f32 * (1.0 - AMOUNT)).round() as u8;
+    (mix(color.0), mix(color.1), mix(color.2))
+}
diff --git a/crates/wayland/src/decoration/corners.rs b/crates/wayland/src/decoration/corners.rs
new file mode 100644
index 0000000..db32209
--- /dev/null
+++ b/crates/wayland/src/decoration/corners.rs
@@ -0,0 +1,165 @@
+//! Rounding a rasterized titlebar/border bitmap's own top or bottom
+//! corners to a quarter-circle, by fading the pixels outside it to fully
+//! transparent - the CPU-bitmap equivalent of `rounded_corners.rs`'s GLES
+//! fragment shader, for the software-only udev/Pixman render path. Shared
+//! by `titlebar.rs` and `border.rs`, which both cut corners out of their
+//! own otherwise-independent buffers and need the two curves to agree
+//! exactly where they meet.
+
+/// Clips the top-left and top-right corners of a titlebar buffer to a
+/// quarter-circle by making the pixels outside it fully transparent, so
+/// whatever's behind (the desktop, on every top-level window) shows through
+/// instead of a hard square corner.
+///
+/// Only the *top* corners: the titlebar's bottom edge meets the window's
+/// content, which this compositor has no way to clip (content is rendered
+/// entirely by the client) - rounding that seam too would need a
+/// compositor-wide clip mask over arbitrary client buffers, a much larger
+/// change than this cosmetic pass. Real desktops mostly round this the same
+/// way: only the outermost corners of a window, not every internal seam.
+///
+/// Hard cutoff rather than an anti-aliased edge, matching this codebase's
+/// existing pixel-art aesthetic elsewhere (the cursor bitmaps) rather than
+/// mixing rendering styles for one corner treatment.
+///
+/// Zeroes all four BGRA bytes for a cut pixel, not just alpha: this buffer
+/// is `Fourcc::Argb8888`, which both Wayland/`wl_shm` and Pixman treat as
+/// premultiplied - a genuinely transparent premultiplied pixel is `(0, 0,
+/// 0, 0)` in every channel, not just alpha, since the stored colour already
+/// carries the alpha multiplied in. Leaving the opaque titlebar-background
+/// RGB behind while zeroing only alpha produced a byte pattern Pixman's own
+/// `OVER` compositing (`result = src + dst * (1 - src_alpha)`) does not
+/// actually treat as "nothing here": with `src_alpha = 0` the formula still
+/// adds the stale, un-premultiplied `src` RGB straight through, so the
+/// "cut" pixel came out opaque and the corner still read as square --
+/// confirmed live, pixel-by-pixel, no visible transparency anywhere in a
+/// window's real top corner despite this function running and a nonzero
+/// radius. `rounded_corners_pixman.rs`'s `apply_corner_mask` - the
+/// equivalent mask for client *content* - already gets this right (scales
+/// all four bytes together); this was the one corner-rounding path in the
+/// codebase that didn't match it.
+/// `center_row` is which row of *this* buffer's own local coordinates the
+/// corner circle's centre sits on - not always `radius` itself. A plain
+/// titlebar with nothing above it passes `radius as i32` (the ordinary
+/// case: the circle's top tip is this buffer's own row 0, same as this
+/// function always assumed before `center_row` existed). A border-top
+/// strip sitting `thickness` rows *above* the titlebar it visually
+/// continues into needs the *same* radius and the *same* circle - not a
+/// same-centre-different-radius circle of its own, which is what passing
+/// `radius + thickness` here used to do (see the doc comment on
+/// `render_border_top`'s call site for why that was tried first). Two
+/// concentric circles of different radii do not meet smoothly at any
+/// boundary between them: at the exact seam, one buffer's mask is
+/// computed against one radius and the other buffer's mask is computed
+/// one pixel later against a different radius, producing a visible jump
+/// rather than a continuous curve - confirmed live, screenshotted at
+/// actual render resolution, not just reasoned about: the titlebar-to-
+/// border seam showed a hard stepped notch, not a curve. Since a border
+/// strip's own row 0 already sits at the *true* top of the combined
+/// shape, it passes `radius as i32` too (unshifted) - it's the titlebar,
+/// starting `thickness` rows *into* the circle instead of at its top,
+/// that needs to shift, by passing `radius as i32 - border_width as
+/// i32` (see `render_titlebar`'s call site).
+pub(crate) fn round_top_corners(buf: &mut [u8], width: usize, height: usize, radius: u32, center_row: i32) {
+    let r = (radius as usize).min(width / 2);
+    if r == 0 {
+        return;
+    }
+    let rf = r as f32;
+    let cy = center_row as f32;
+    // Only rows that could plausibly need blending at all: below
+    // `center_row` (this buffer's slice of the circle, whatever portion
+    // of it falls within `[0, height)`) is where the actual curve lives;
+    // rows above `center_row - r` or at/below `center_row` are either
+    // already past the transparent tip or already fully inside the
+    // shape, and calling `blend_corner_pixel` there would either be a
+    // wasted no-op (large `dist`, `mask >= 1`) or - critically, for a
+    // *tall* buffer whose straight edge extends far past the corner --
+    // wrongly compute a huge `dist` from being far below the centre and
+    // clip an ordinary straight-edge pixel to transparent. The original
+    // unshifted version of this function avoided that the same way, by
+    // simply never iterating past row `r`; this is that same bound,
+    // generalised to an arbitrary `center_row`.
+    let y_lo = (center_row - r as i32).max(0) as usize;
+    let y_hi = (center_row.max(0) as usize).min(height);
+    for y in y_lo..y_hi {
+        for x in 0..r {
+            blend_corner_pixel(buf, width, x, y, rf, cy, rf);
+        }
+        for x in (width - r)..width {
+            blend_corner_pixel(buf, width, x, y, (width - r - 1) as f32, cy, rf);
+        }
+    }
+}
+
+/// Multiplies the pixel at `(x, y)` by a smoothed 0..1 mask based on its
+/// distance from `(cx, cy)` versus `radius` - `1` (unchanged) well inside
+/// the circle, `0` (fully transparent) well outside it, blended over a ~2px
+/// band at the boundary. Same anti-aliasing technique `rounded_corners.rs`'s
+/// GLES fragment shader already uses for content rounding
+/// (`smoothstep(radius - 1.0, radius + 1.0, dist)`), applied here to a CPU
+/// bitmap pixel by pixel instead of a per-fragment shader.
+///
+/// The previous version of both callers did a hard binary cut instead --
+/// fully opaque or fully transparent, nothing between - which read as a
+/// jagged single-pixel "break" in the border line rather than a curve,
+/// especially in a border strip only a couple of rows tall (the common
+/// case: `border_width` is usually 2-3px) where there's no room for the
+/// eye to average a staircase into something that looks round. Reported
+/// live as "line breaks" right where a window's border met its curved
+/// corner.
+///
+/// `buf` is premultiplied BGRA (`color::rgb_to_bgra`'s own convention), so
+/// scaling all four bytes by the same factor is the correct way to reduce a
+/// pixel's effective alpha - same reasoning
+/// `clipped_corner_pixels_are_fully_premultiplied_zero_not_just_alpha`
+/// already established for the hard-cut case this replaces.
+fn blend_corner_pixel(buf: &mut [u8], width: usize, x: usize, y: usize, cx: f32, cy: f32, radius: f32) {
+    let (dx, dy) = (x as f32 - cx, y as f32 - cy);
+    let dist = (dx * dx + dy * dy).sqrt();
+    let t = ((dist - (radius - 1.0)) / 2.0).clamp(0.0, 1.0);
+    let mask = 1.0 - (t * t * (3.0 - 2.0 * t));
+    if mask >= 1.0 {
+        return;
+    }
+    let idx = (y * width + x) * 4;
+    if mask <= 0.0 {
+        buf[idx..idx + 4].fill(0);
+        return;
+    }
+    for c in &mut buf[idx..idx + 4] {
+        *c = (*c as f32 * mask).round() as u8;
+    }
+}
+
+/// [`round_top_corners`]'s mirror for the bottom two corners - same
+/// construction, corner centres `r` *up* from the bottom instead of down
+/// from the top. Same anti-aliasing, same reason - see
+/// [`blend_corner_pixel`]'s own doc comment.
+pub(crate) fn round_bottom_corners(buf: &mut [u8], width: usize, height: usize, radius: u32) {
+    let r = (radius as usize).min(width / 2);
+    if r == 0 {
+        return;
+    }
+    // See `round_top_corners`' matching comment: `r` (the real corner
+    // radius) must stay unclamped by `height`, or a strip thinner than the
+    // radius cuts its own separate, too-tight arc instead of continuing the
+    // titlebar's. `rows` is just how many of that circle's rows this
+    // buffer actually has room for.
+    let rows = r.min(height);
+    let rf = r as f32;
+    // As a float, not the signed-`i64`-offset trick the hard-cut version
+    // needed to avoid a `usize` underflow - `blend_corner_pixel` already
+    // takes float centres, so `height - r - 1` going negative when `r >
+    // height` (the strip-thinner-than-radius case above) is just a
+    // negative `f32`, no special-casing required.
+    let cy = height as f32 - rf - 1.0;
+    for y in (height - rows)..height {
+        for x in 0..r {
+            blend_corner_pixel(buf, width, x, y, rf, cy, rf);
+        }
+        for x in (width - r)..width {
+            blend_corner_pixel(buf, width, x, y, (width - r - 1) as f32, cy, rf);
+        }
+    }
+}
diff --git a/crates/wayland/src/decoration/font.rs b/crates/wayland/src/decoration/font.rs
new file mode 100644
index 0000000..27df347
--- /dev/null
+++ b/crates/wayland/src/decoration/font.rs
@@ -0,0 +1,146 @@
+//! Locating a system monospace font and blitting its rasterized glyphs into
+//! a titlebar's own pixel buffer - everything `render_titlebar`'s title-
+//! text pass needs, kept separate from the titlebar layout/button logic
+//! that actually calls it.
+
+use super::color::rgb_to_bgra;
+use fontdue::{Font, FontSettings};
+use std::sync::OnceLock;
+
+pub(crate) const FONT_PIXELS: f32 = 13.0;
+pub(crate) const TEXT_LEFT_PADDING: f32 = 8.0;
+
+/// Common monospace font file locations on Linux desktops. Not a full
+/// fontconfig query (no new system dependency for something this small) --
+/// if none of these resolve, titlebars fall back to solid-color-only, same
+/// as before text rendering existed.
+pub(crate) fn find_system_font() -> Option<Font> {
+    static FONT: OnceLock<Option<Font>> = OnceLock::new();
+    FONT.get_or_init(load_any_monospace_font).clone()
+}
+
+fn load_any_monospace_font() -> Option<Font> {
+    let roots = ["/usr/share/fonts", "/usr/local/share/fonts"];
+    let mut home_roots = Vec::new();
+    if let Ok(home) = std::env::var("HOME") {
+        home_roots.push(format!("{home}/.local/share/fonts"));
+        home_roots.push(format!("{home}/.fonts"));
+    }
+    let all_roots = roots.iter().map(|s| s.to_string()).chain(home_roots);
+
+    let mut best: Option<(std::path::PathBuf, u8)> = None;
+    for root in all_roots {
+        find_best_font(std::path::Path::new(&root), &mut best);
+        if matches!(best, Some((_, 0))) {
+            break;
+        }
+    }
+    let (path, _) = best?;
+    let bytes = std::fs::read(&path).ok()?;
+    match Font::from_bytes(bytes, FontSettings::default()) {
+        Ok(f) => {
+            log::info!("wayland titlebar font: {}", path.display());
+            Some(f)
+        }
+        Err(e) => {
+            log::warn!("failed to parse font {}: {e}", path.display());
+            None
+        }
+    }
+}
+
+/// Ranks a font file by how suitable it is for titlebar text: `0` (best) is
+/// a mono-named file with no weight/style marker at all (a plain
+/// "Regular"), `1` is mono but italic/oblique/some other non-regular
+/// weight, `2` is not mono-named at all. Lower is better.
+///
+/// The style-marker list matters as much as the mono check: without it, a
+/// directory listing that happens to turn up `...Mono...-Italic.ttf`
+/// before any regular-weight mono file sorts no worse than one, and gets
+/// picked and stuck with for the process's whole lifetime (`find_system_
+/// font`'s own `OnceLock`). Reported live: this exact case, `/usr/share/
+/// fonts/TTF/JetBrainsMonoNerdFontPropo-Italic.ttf` picked over every
+/// regular-weight JetBrains Mono variant also installed on the same
+/// system, purely because "mono" matched and nothing excluded italic --
+/// every titlebar rendered in italic instead of upright text.
+fn font_rank(path: &std::path::Path) -> u8 {
+    let name = path.to_string_lossy().to_lowercase();
+    let is_mono = name.contains("mono");
+    let is_styled =
+        ["italic", "oblique", "bold", "light", "thin", "black", "medium", "semibold", "extrabold", "condensed"].iter().any(|s| name.contains(s));
+    match (is_mono, is_styled) {
+        (true, false) => 0,
+        (true, true) => 1,
+        (false, _) => 2,
+    }
+}
+
+/// Walks `dir` for the lowest-`font_rank` `.ttf`/`.otf` file, checking
+/// every file rather than stopping at the first mono match - unlike rank
+/// alone, "first found" says nothing about *style*, and the filesystem's
+/// own directory-listing order is not something to trust for that. Only
+/// stops early once a genuine rank-`0` (mono, unstyled) match is found,
+/// since nothing could ever beat that.
+fn find_best_font(dir: &std::path::Path, best: &mut Option<(std::path::PathBuf, u8)>) {
+    if matches!(best, Some((_, 0))) {
+        return;
+    }
+    let Ok(entries) = std::fs::read_dir(dir) else { return };
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if path.is_dir() {
+            find_best_font(&path, best);
+            if matches!(best, Some((_, 0))) {
+                return;
+            }
+            continue;
+        }
+        let is_font = path.extension().and_then(|e| e.to_str()).map(|e| e.eq_ignore_ascii_case("ttf") || e.eq_ignore_ascii_case("otf")).unwrap_or(false);
+        if !is_font {
+            continue;
+        }
+        let rank = font_rank(&path);
+        if best.as_ref().is_none_or(|(_, r)| rank < *r) {
+            *best = Some((path, rank));
+            if rank == 0 {
+                return;
+            }
+        }
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn blit_glyph(
+    buf: &mut [u8],
+    width: usize,
+    height: usize,
+    glyph_x: i32,
+    glyph_y: i32,
+    metrics: &fontdue::Metrics,
+    coverage: &[u8],
+    background: (u8, u8, u8),
+    foreground: (u8, u8, u8),
+) {
+    for row in 0..metrics.height {
+        let y = glyph_y + row as i32;
+        if y < 0 || y as usize >= height {
+            continue;
+        }
+        for col in 0..metrics.width {
+            let x = glyph_x + col as i32;
+            if x < 0 || x as usize >= width {
+                continue;
+            }
+            let cov = coverage[row * metrics.width + col] as f32 / 255.0;
+            if cov <= 0.0 {
+                continue;
+            }
+            let blend = |bg: u8, fg: u8| -> u8 { (bg as f32 * (1.0 - cov) + fg as f32 * cov).round() as u8 };
+            let r = blend(background.0, foreground.0);
+            let g = blend(background.1, foreground.1);
+            let b = blend(background.2, foreground.2);
+            let idx = (y as usize * width + x as usize) * 4;
+            buf[idx..idx + 4].copy_from_slice(&rgb_to_bgra((r, g, b), 255));
+        }
+    }
+}
diff --git a/crates/wayland/src/decoration/shadow.rs b/crates/wayland/src/decoration/shadow.rs
new file mode 100644
index 0000000..df0a0dd
--- /dev/null
+++ b/crates/wayland/src/decoration/shadow.rs
@@ -0,0 +1,186 @@
+//! A window's drop shadow, rasterized as its own BGRA8 bitmap - extent,
+//! sizing, and the corner-aware falloff distance function it needs to read
+//! as rounded next to a window with a real rounded corner, rather than a
+//! plain square-cornered glow sitting incongruously beside one.
+
+/// How far a window's drop shadow extends past its geometry on each side.
+///
+/// `24`, not the original `12`: reported live as srdwm's own shadow
+/// reading as a thin, tight dark line rather than the soft, generously-
+/// sized glow real macOS windows have - doubled, and paired with
+/// `shadow_bitmap`'s own falloff moving from a plain linear ramp to an
+/// eased (`smoothstep`) one, which reads as noticeably softer at the same
+/// pixel budget even without a real blur primitive to work with.
+pub const SHADOW_SIZE: u32 = 24;
+
+/// The shadow's darkest alpha, right at the window's own edge - out of
+/// 255. Deliberately subtle (Nord/GNOME-default territory, not a heavy
+/// drop shadow): this compositor has no blur primitive to soften it with
+/// (see `shadow_bitmap`'s own doc comment), so a strong value would read as
+/// a hard dark ring rather than a shadow. This is the *focused*-window
+/// value - see `shadow_bitmap`'s own `max_alpha` parameter for why an
+/// unfocused window doesn't just reuse it unconditionally.
+pub(crate) const SHADOW_MAX_ALPHA: u8 = 90;
+
+/// `geometry` expanded by [`SHADOW_SIZE`] on every side - the full bounding
+/// box [`shadow_bitmap`] rasterises into, and where the caller positions it
+/// (top-left corner at `(geometry.x - SHADOW_SIZE, geometry.y - SHADOW_SIZE)`).
+pub fn shadow_rect(geometry: srdwm_core::Rect) -> srdwm_core::Rect {
+    let s = SHADOW_SIZE as i32;
+    srdwm_core::Rect::new(geometry.x - s, geometry.y - s, geometry.width + SHADOW_SIZE * 2, geometry.height + SHADOW_SIZE * 2)
+}
+
+/// Renders a window's drop shadow as a BGRA8 bitmap: black at an alpha that
+/// falls off linearly from [`SHADOW_MAX_ALPHA`] right at the window's own
+/// edge to fully transparent [`SHADOW_SIZE`] pixels out. `win_width`/
+/// `win_height` are the window's own footprint (`geometry`, border strips
+/// included if any - whatever the caller already draws as opaque); the
+/// returned bitmap is `shadow_rect`'s size, `SHADOW_SIZE` larger on every
+/// side.
+///
+/// Not a true Gaussian blur - no blur primitive is available without a GPU
+/// shader (the udev backend's `PixmanRenderer` is software-only) or a new
+/// image-processing dependency - so this is a stepless *linear* falloff
+/// using Chebyshev (square-ring) distance from the window's edge rather
+/// than a rounded/radial one, cheap enough to rebuild on every resize (see
+/// the caller for when that is) without a per-pixel sqrt. Reads as "soft
+/// enough" at the sizes a titlebar-height window actually uses, the same
+/// "approximate cutoff over true anti-aliasing" trade-off `corners::round_
+/// top_corners` already makes for corners.
+///
+/// The region directly under the window itself (`dist == 0` below) is left
+/// fully transparent rather than filled - harmless either way since the
+/// window's own border/titlebar/content always draws over it, but skipping
+/// it is one less branch of work for the common case (a window with no
+/// occluders in front of it, so most of the bitmap's interior never
+/// contributes a visible pixel).
+///
+/// `max_alpha` - the shadow's own darkest value, right at the window's
+/// edge - is a parameter rather than always `SHADOW_MAX_ALPHA`, so a
+/// caller can dim an *unfocused* window's shadow the same way `theme.
+/// border.inactive_dim` already dims an unfocused window's border colour
+/// (see `effective_border_color`). Real desktop convention, not invented
+/// here: Hyprland's own `decoration:shadow` config exposes `color` and
+/// `color_inactive` as two separate values specifically for this, common
+/// user configs going as far as a fully transparent `color_inactive` (no
+/// shadow at all once a window loses focus) - confirmed via Hyprland's
+/// own wiki, not assumed. `redraw_decoration_buffer` reuses `theme.
+/// border_inactive_dim` for this rather than adding a second, separately
+/// configurable factor: both are "how much does losing focus fade this
+/// window's own chrome", and this codebase already has a user-tunable
+/// answer to that question.
+pub fn shadow_bitmap(win_width: u32, win_height: u32, radius: u32, max_alpha: u8) -> Vec<u8> {
+    let (win_width, win_height) = (win_width.max(1), win_height.max(1));
+    let width = win_width + SHADOW_SIZE * 2;
+    let height = win_height + SHADOW_SIZE * 2;
+    // Clamped the same way `corners::round_top_corners`/`round_bottom_
+    // corners` clamp their own radius against the buffer they're cutting --
+    // a radius that would eat more than half of either the window's own
+    // width or height isn't geometrically meaningful.
+    let radius = radius.min(win_width / 2).min(win_height / 2);
+    let mut buf = vec![0u8; (width * height * 4) as usize];
+    for y in 0..height {
+        let dy = edge_distance(y, SHADOW_SIZE, win_height);
+        // The widest a row can still possibly contribute a visible pixel:
+        // a corner-quadrant pixel's distance is `sqrt(qx^2 + qy^2) -
+        // radius` where `qy = dy - radius`, and that can still be `<=
+        // SHADOW_SIZE` (this function's own cutoff below) even with
+        // `qx == 0`, i.e. up to `dy == SHADOW_SIZE + 2 * radius` - not
+        // just `SHADOW_SIZE + radius`, which would cut off real corner
+        // pixels a few rows early.
+        if dy > SHADOW_SIZE + 2 * radius {
+            continue;
+        }
+        for x in 0..width {
+            let dx = edge_distance(x, SHADOW_SIZE, win_width);
+            let dist = rounded_edge_distance(dx, dy, radius);
+            if dist == 0 || dist > SHADOW_SIZE {
+                continue;
+            }
+            // Eased (`smoothstep`), not a plain linear ramp - the same
+            // curve `apply_corner_mask`/`fill_button_dot` already use for
+            // their own anti-aliased edges, applied here across the whole
+            // shadow's width instead of a 2px antialiasing band. A linear
+            // falloff reads as a visible ring with a hard-ish inner edge
+            // even when fully transparent at both ends; easing both ends
+            // of the same 0..=1 range softens the transition into and out
+            // of the shadow without needing a real blur primitive.
+            let t = dist as f32 / SHADOW_SIZE as f32;
+            let eased = 1.0 - (t * t * (3.0 - 2.0 * t));
+            let alpha = (max_alpha as f32 * eased).round() as u8;
+            if alpha == 0 {
+                continue;
+            }
+            let i = ((y * width + x) * 4) as usize;
+            // Premultiplied BGRA, but the colour is black (0, 0, 0) - a
+            // premultiplied black pixel is just (0, 0, 0, alpha) at any
+            // alpha, so there's no separate multiply step needed here.
+            buf[i + 3] = alpha;
+        }
+    }
+    buf
+}
+
+/// `edge_distance`'s corner-aware version: `dx`/`dy` are already `edge_
+/// distance`'s own plain per-axis distances past the window's true edge
+/// (`0` on either axis means "not in a corner quadrant at all" - directly
+/// above/below/left/right of the window, or inside it) - this only
+/// changes what happens where *both* are positive, i.e. genuinely outside
+/// the window on both axes at once. Along a flat edge, a rounded rect's
+/// boundary is identical to a square one's (rounding only touches the
+/// corners), so the plain `max(dx, dy)` this replaces was already correct
+/// there and stays correct here too.
+///
+/// Without this, the shadow was a plain square-cornered falloff (`shadow_
+/// bitmap`'s own historical doc comment called this out as a deliberate
+/// Chebyshev-not-radial simplification - reasonable for a soft blur where
+/// nothing else in the frame gives the eye a hard edge to compare against,
+/// but wrong once the window it belongs to has a *visibly* rounded corner
+/// right next to it) - confirmed live via a real screenshot at actual
+/// render resolution: the shadow's own corner cut a hard diagonal well
+/// outside the window's own curve, plainly a different, unrelated shape
+/// sitting right beside it.
+///
+/// The corner-quadrant formula: place the window's true (sharp) corner at
+/// the origin, with the window occupying the quadrant behind it - `dx`/
+/// `dy` are how far past that origin the shadow pixel sits on each axis. A
+/// *rounded* corner's circle sits centred `radius` pixels in from that
+/// origin on both axes, i.e. at `(-radius, -radius)`. Straight-line
+/// distance from the pixel to that centre is `sqrt((dx + radius)^2 + (dy +
+/// radius)^2)`; subtracting `radius` converts "distance to the circle's
+/// centre" into "distance to the circle's own boundary", which is what a
+/// real rounded corner's curve actually traces. (At `dx = dy = 0` - the
+/// old sharp corner's own tip - this correctly comes out positive, not
+/// `0`: the rounded window's boundary has curved away from that point
+/// entirely, so it's already outside the window, not sitting right on its
+/// edge the way a real square corner's tip would be.)
+pub(super) fn rounded_edge_distance(dx: u32, dy: u32, radius: u32) -> u32 {
+    // `radius == 0` (nothing to round - kept byte-identical to the
+    // pre-existing Chebyshev-everywhere behaviour, not just "close
+    // enough": true Euclidean distance to a sharp corner *point* differs
+    // from Chebyshev distance to it even without any rounding, and this
+    // function must not change a square window's own shadow shape) or a
+    // genuine flat-edge point (`dx == 0` xor `dy == 0` - rounding never
+    // touches these, only the four corners) both use plain Chebyshev
+    // distance, unchanged from before this function existed.
+    if radius == 0 || (dx == 0) != (dy == 0) {
+        return dx.max(dy);
+    }
+    let (ex, ey) = (dx as f32 + radius as f32, dy as f32 + radius as f32);
+    let corner_dist = (ex * ex + ey * ey).sqrt() - radius as f32;
+    corner_dist.max(0.0).round() as u32
+}
+
+/// How far outside `[margin, margin + extent)` - the window's own span
+/// along one axis, inside the shadow's `margin`-pixel border on each side
+/// - position `pos` sits, in pixels. `0` anywhere inside that span
+/// (including exactly on its edge).
+fn edge_distance(pos: u32, margin: u32, extent: u32) -> u32 {
+    if pos < margin {
+        margin - pos
+    } else if pos >= margin + extent {
+        pos - (margin + extent) + 1
+    } else {
+        0
+    }
+}
diff --git a/crates/wayland/src/decoration/tests.rs b/crates/wayland/src/decoration/tests.rs
new file mode 100644
index 0000000..0cc5d45
--- /dev/null
+++ b/crates/wayland/src/decoration/tests.rs
@@ -0,0 +1,756 @@
+use super::*;
+use super::border::*;
+use super::buttons::*;
+use super::color::*;
+use super::corners::*;
+use super::font::*;
+use super::shadow::*;
+use super::titlebar::*;
+
+#[test]
+fn border_strips_surround_geometry_without_overlapping_it() {
+    let geom = srdwm_core::Rect::new(100, 100, 200, 150);
+    let [top, bottom, left, right] = border_strips(geom, 3);
+    // Every strip's own rect must stay entirely outside `geom` - these
+    // are meant to frame the window, not clip into its own titlebar or
+    // content.
+    assert_eq!(top, srdwm_core::Rect::new(97, 97, 206, 3));
+    assert_eq!(bottom, srdwm_core::Rect::new(97, 250, 206, 3));
+    assert_eq!(left, srdwm_core::Rect::new(97, 100, 3, 150));
+    assert_eq!(right, srdwm_core::Rect::new(300, 100, 3, 150));
+}
+
+#[test]
+fn shadow_rect_expands_geometry_by_shadow_size_on_every_side() {
+    let geom = srdwm_core::Rect::new(100, 100, 200, 150);
+    let s = shadow_rect(geom);
+    assert_eq!(s, srdwm_core::Rect::new(100 - SHADOW_SIZE as i32, 100 - SHADOW_SIZE as i32, 200 + SHADOW_SIZE * 2, 150 + SHADOW_SIZE * 2));
+}
+
+#[test]
+fn shadow_bitmap_is_the_expected_size_and_transparent_under_the_window() {
+    let buf = shadow_bitmap(40, 20, 0, SHADOW_MAX_ALPHA);
+    let width = 40 + SHADOW_SIZE * 2;
+    let height = 20 + SHADOW_SIZE * 2;
+    assert_eq!(buf.len(), (width * height * 4) as usize);
+    // Dead center is inside the window's own footprint - must stay
+    // fully transparent, since the window's own content draws over it.
+    let mid = ((height / 2) * width + width / 2) * 4;
+    assert_eq!(buf[mid as usize + 3], 0);
+}
+
+#[test]
+fn shadow_bitmap_is_darkest_right_at_the_window_edge_and_fades_outward() {
+    let buf = shadow_bitmap(40, 20, 0, SHADOW_MAX_ALPHA);
+    let width = (40 + SHADOW_SIZE * 2) as usize;
+    // Walking straight up from the window's horizontal center, from one
+    // pixel above its top edge (row SHADOW_SIZE - 1) out to the shadow's
+    // own outer edge (row 0): alpha must start near SHADOW_MAX_ALPHA and
+    // strictly decrease to 0.
+    let x = width / 2;
+    let mut last_alpha = 255u8;
+    for row in (0..SHADOW_SIZE as usize).rev() {
+        let i = (row * width + x) * 4;
+        let alpha = buf[i + 3];
+        assert!(alpha <= last_alpha, "alpha rose from {last_alpha} to {alpha} moving outward at row {row}");
+        last_alpha = alpha;
+    }
+    assert_eq!(last_alpha, 0, "outermost row must be fully transparent");
+}
+
+#[test]
+fn shadow_falloff_is_eased_not_linear() {
+    // The actual visual change: a plain linear ramp drops the same
+    // amount of alpha every pixel, which reads as a visible ring with
+    // a hard-ish inner edge even though it's transparent at both
+    // ends. An eased (smoothstep) curve drops *less* per pixel near
+    // both ends and *more* in the middle - this is what distinguishes
+    // it from linear at the byte level, not just "still monotonic".
+    let buf = shadow_bitmap(40, 20, 0, SHADOW_MAX_ALPHA);
+    let width = (40 + SHADOW_SIZE * 2) as usize;
+    let x = width / 2;
+    let alpha_at = |dist_from_edge: u32| {
+        let row = SHADOW_SIZE - dist_from_edge;
+        buf[(row as usize * width + x) * 4 + 3] as i32
+    };
+    // Step near the shadow's own inner edge (dist 1 -> 2) versus a
+    // step through the middle (dist SHADOW_SIZE/2 -> SHADOW_SIZE/2+1):
+    // eased must drop less near the edge than a linear ramp would
+    // (linear drops `max_alpha / SHADOW_SIZE` every single step,
+    // uniformly) - the middle step must drop more than that same
+    // uniform linear amount to compensate, since both curves start
+    // and end at the same two values.
+    let linear_step = SHADOW_MAX_ALPHA as i32 / SHADOW_SIZE as i32;
+    let near_edge_drop = alpha_at(1) - alpha_at(2);
+    let middle_drop = alpha_at(SHADOW_SIZE / 2) - alpha_at(SHADOW_SIZE / 2 + 1);
+    assert!(near_edge_drop < linear_step, "near-edge step ({near_edge_drop}) should be gentler than a linear ramp's own uniform step ({linear_step})");
+    assert!(middle_drop > near_edge_drop, "the steepest part of an eased curve should be in the middle ({middle_drop}), not at the edge ({near_edge_drop})");
+}
+
+#[test]
+fn a_lower_max_alpha_produces_a_strictly_fainter_shadow_throughout() {
+    // Locks in the `max_alpha` parameter's actual effect - an
+    // unfocused window's dimmed shadow (see `redraw_decoration_
+    // buffer`'s own call site) must never be darker than the focused
+    // one at any pixel, not just "different".
+    let focused = shadow_bitmap(40, 20, 0, SHADOW_MAX_ALPHA);
+    let dimmed = shadow_bitmap(40, 20, 0, SHADOW_MAX_ALPHA / 2);
+    assert_ne!(focused, dimmed, "sanity: halving max_alpha must actually change the bitmap");
+    for (f, d) in focused.chunks_exact(4).zip(dimmed.chunks_exact(4)) {
+        assert!(d[3] <= f[3], "dimmed alpha {} must never exceed focused alpha {}", d[3], f[3]);
+    }
+}
+
+#[test]
+fn rounded_shadow_corner_tip_is_further_than_the_square_corners_own() {
+    // Regression coverage for the actual live bug: a window's shadow
+    // used to always taper with plain Chebyshev (square) distance, so
+    // its own corner cut a hard diagonal well outside a *rounded*
+    // window's real curve, sitting there as a visibly different,
+    // unrelated shape - confirmed live via a real screenshot at
+    // actual render resolution. At the window's old sharp-corner tip
+    // (dx = dy = 0), the rounded window's boundary has curved away
+    // entirely, so this point must read as *further* from the window
+    // than plain Chebyshev's `0` - not `0`, which would mean "right on
+    // the window's own edge", true only for a genuinely square corner.
+    let radius = 6;
+    assert_eq!(rounded_edge_distance(0, 0, 0), 0, "sanity: radius 0 must match plain Chebyshev distance exactly");
+    let rounded = rounded_edge_distance(0, 0, radius);
+    assert!(rounded > 0, "the old sharp corner's own tip must be outside a rounded window, not sitting right on its edge");
+    // Exact value, worked out by hand: distance from the tip to the
+    // rounding circle's centre (radius, radius) is radius*sqrt(2), so
+    // distance to the circle's own boundary is radius*(sqrt(2) - 1).
+    let expected = (radius as f32 * (2.0f32.sqrt() - 1.0)).round() as u32;
+    assert_eq!(rounded, expected);
+}
+
+#[test]
+fn rounded_edge_distance_matches_plain_chebyshev_along_a_flat_edge() {
+    // Rounding only ever touches the four corners - directly above,
+    // below, left or right of the window (exactly one of dx/dy is 0),
+    // a rounded rect's boundary is identical to a square one's.
+    for (dx, dy) in [(5, 0), (0, 5), (12, 0), (0, 12)] {
+        assert_eq!(rounded_edge_distance(dx, dy, 6), dx.max(dy), "flat-edge point ({dx}, {dy}) must use plain Chebyshev distance, not the corner formula");
+    }
+}
+
+#[test]
+fn shadow_bitmap_corner_is_softer_than_a_square_windows_when_rounded() {
+    let square = shadow_bitmap(40, 40, 0, SHADOW_MAX_ALPHA);
+    let rounded = shadow_bitmap(40, 40, 6, SHADOW_MAX_ALPHA);
+    let width = (40 + SHADOW_SIZE * 2) as usize;
+    // The old sharp corner's own tip: `SHADOW_SIZE` pixels in from the
+    // bitmap's own outer edge on both axes, i.e. exactly at row/column
+    // `SHADOW_SIZE` - where `dx == dy == 0` in `edge_distance`'s own
+    // terms, the window's true corner point. A square window's shadow
+    // is at its darkest possible value there (`dist == 0`, right on
+    // the window's own edge); a rounded window's real boundary has
+    // already curved away from that exact point, so it must read
+    // strictly lighter there (a real positive distance means a
+    // partially-faded, not maximum, alpha) - not identical, which is
+    // what the bug this fixes looked like.
+    let tip = ((SHADOW_SIZE as usize) * width + SHADOW_SIZE as usize) * 4;
+    assert_eq!(square[tip + 3], 0, "sanity: a square window's shadow is fully suppressed right at its own corner");
+    assert!(rounded[tip + 3] > 0, "a rounded window's shadow must actually draw at the old sharp-corner tip, since that point is genuinely outside the rounded boundary");
+}
+
+#[test]
+fn fills_background_when_no_text() {
+    let buf = render_titlebar(40, 20, "", (0x2e, 0x34, 0x40), (0xec, 0xef, 0xf4), true, CORNER_RADIUS, 0, true, None, false, false, false, None, true, false);
+    assert_eq!(buf.len(), 40 * 20 * 4);
+    // Center, not (0,0): the top-left pixel is inside the rounded
+    // corner `round_top_corners` clips away, so it's transparent by
+    // design - see `corners_are_clipped_but_the_middle_is_not` below.
+    let mid = ((20 / 2) * 40 + 40 / 2) * 4;
+    assert_eq!(&buf[mid..mid + 4], &rgb_to_bgra((0x2e, 0x34, 0x40), 255));
+}
+
+#[test]
+fn button_icons_are_drawn_in_the_squares_hit_test_assigns_them() {
+    // Regression test for a bug where every drawn icon was one full
+    // button-width left of where a click on it actually landed: the
+    // visible "X" triggered Maximize, the visible square triggered
+    // Minimize, and the true Close hit-zone (the rightmost
+    // TITLEBAR_HEIGHT-wide band) was blank. `button_box`'s
+    // `right_offset` must put each icon in the same square
+    // `ResizeEdge::hit_test` assigns to it - checked here by picking
+    // the centre pixel of each drawn icon's square and confirming
+    // `hit_test` reports the matching button for that same point.
+    let (width, height) = (300u32, srdwm_core::TITLEBAR_HEIGHT);
+    let bg = (0x2e, 0x34, 0x40);
+    let fg = (0xec, 0xef, 0xf4);
+    let buf = render_titlebar(width, height, "", bg, fg, true, CORNER_RADIUS, 0, true, None, false, false, false, None, true, false);
+    let frame = srdwm_core::Rect::new(0, 0, width, height);
+    let (width, height) = (width as usize, height as usize);
+
+    let bg_bytes = rgb_to_bgra(bg, 255);
+    let pitch = srdwm_core::BUTTON_PITCH as usize;
+    let margin = srdwm_core::BUTTON_CLUSTER_MARGIN as usize;
+    for (right_offset, expected) in [(margin, srdwm_core::TitlebarHit::Close), (margin + pitch, srdwm_core::TitlebarHit::Maximize), (margin + pitch * 2, srdwm_core::TitlebarHit::Minimize)] {
+        let (x0, y0, x1, y1) = button_box(width, height, right_offset, false, BUTTON_MARGIN);
+        let drawn = (y0..=y1).any(|y| (x0..=x1).any(|x| buf[(y as usize * width + x as usize) * 4..(y as usize * width + x as usize) * 4 + 4] != bg_bytes));
+        assert!(drawn, "expected some drawn icon pixel inside the right_offset={right_offset} square");
+        let cx = (x0 + x1) / 2;
+        let cy = (y0 + y1) / 2;
+        assert_eq!(
+            srdwm_core::ResizeEdge::hit_test(frame, cx, cy, true, 0, srdwm_core::RESIZE_MARGIN, false, None, false),
+            Some(expected),
+            "icon drawn at right_offset={right_offset} does not land in the square hit_test assigns to {expected:?}"
+        );
+    }
+}
+
+#[test]
+fn a_dialog_draws_only_close_and_never_a_coloured_traffic_light() {
+    // Requested directly: "dialog windows shouldn't have maximize/
+    // minimize buttons... don't use traffic lights there ever."
+    let (width, height) = (300u32, srdwm_core::TITLEBAR_HEIGHT);
+    let bg = (0x2e, 0x34, 0x40);
+    let fg = (0xec, 0xef, 0xf4);
+    let bg_bytes = rgb_to_bgra(bg, 255);
+    // `traffic_lights = true` passed in deliberately - `is_dialog`
+    // must override it regardless of what the active theme otherwise
+    // uses everywhere else. `glyph_always = true` so Close's own X is
+    // visible without needing a live hover to check it landed.
+    let dialog = render_titlebar(width, height, "", bg, fg, true, CORNER_RADIUS, 0, true, None, false, false, true, None, true, true);
+    let normal = render_titlebar(width, height, "", bg, fg, true, CORNER_RADIUS, 0, true, None, false, false, true, None, true, false);
+    let (w, h) = (width as usize, height as usize);
+
+    // Where a normal (non-dialog) titlebar draws Maximize (offset
+    // `BUTTON_PITCH`) must be untouched background on the dialog --
+    // that button was never drawn there at all, not just hit-test-
+    // unreachable.
+    let margin = srdwm_core::BUTTON_CLUSTER_MARGIN as usize;
+    let maximize_box = button_box(w, h, margin + srdwm_core::BUTTON_PITCH as usize, false, BUTTON_MARGIN);
+    let maximize_drawn_on_normal =
+        (maximize_box.1..=maximize_box.3).any(|y| (maximize_box.0..=maximize_box.2).any(|x| normal[(y as usize * w + x as usize) * 4..(y as usize * w + x as usize) * 4 + 4] != bg_bytes));
+    assert!(maximize_drawn_on_normal, "sanity: a normal titlebar really does draw something at the Maximize slot");
+    let maximize_drawn_on_dialog =
+        (maximize_box.1..=maximize_box.3).any(|y| (maximize_box.0..=maximize_box.2).any(|x| dialog[(y as usize * w + x as usize) * 4..(y as usize * w + x as usize) * 4 + 4] != bg_bytes));
+    assert!(!maximize_drawn_on_dialog, "a dialog must draw nothing at all at the Maximize slot");
+
+    // Close's own box: no coloured fill (a flat, opaque red/near-red
+    // dot, same family `TRAFFIC_LIGHT_CLOSE` produces) anywhere in it
+    // - only the plain-glyph X, drawn in `fg`, may appear.
+    let close_box = button_box(w, h, margin, false, BUTTON_MARGIN);
+    for y in close_box.1..=close_box.3 {
+        for x in close_box.0..=close_box.2 {
+            let i = (y as usize * w + x as usize) * 4;
+            let px = &dialog[i..i + 4];
+            // BGRA - a red-family traffic light has a strongly
+            // dominant red channel (index 2) well above both blue and
+            // green; the plain glyph (`fg`, near-white/grey) and the
+            // untouched background do not.
+            let (b, g, r) = (px[0] as i32, px[1] as i32, px[2] as i32);
+            assert!(!(r > g + 40 && r > b + 40), "close button pixel at ({x},{y}) reads as a coloured traffic light: bgra={px:?}");
+        }
+    }
+}
+
+#[test]
+fn drawing_title_changes_some_pixels_when_font_available() {
+    if find_system_font().is_none() {
+        eprintln!("skipping: no system font found in this sandbox");
+        return;
+    }
+    let bg = (0x2e, 0x34, 0x40);
+    let fg = (0xec, 0xef, 0xf4);
+    let buf = render_titlebar(200, 30, "Terminal", bg, fg, true, CORNER_RADIUS, 0, true, None, false, false, false, None, true, false);
+    let bg_bytes = rgb_to_bgra(bg, 255);
+    let changed = buf.chunks_exact(4).any(|px| px != bg_bytes);
+    assert!(changed, "expected at least one pixel to differ from the background once text is drawn");
+}
+
+#[test]
+fn centered_title_starts_further_right_than_left_aligned() {
+    if find_system_font().is_none() {
+        eprintln!("skipping: no system font found in this sandbox");
+        return;
+    }
+    let bg = (0x2e, 0x34, 0x40);
+    let fg = (0xec, 0xef, 0xf4);
+    let (width, height) = (60u32, 30u32);
+    let bg_bytes = rgb_to_bgra(bg, 255);
+    // No buttons at this width (`button_count` gates on
+    // `width >= BUTTON_CLUSTER_MARGIN + BUTTON_PITCH * 3`), so
+    // `text_limit` is the full width and a short title has real room to
+    // actually move when centered - otherwise this could pass even
+    // with centering silently broken.
+    assert!(width < srdwm_core::BUTTON_CLUSTER_MARGIN + srdwm_core::BUTTON_PITCH * 3, "sanity: this fixture must have no button squares eating into text_limit");
+    // Only rows clear of `round_top_corners`' own clipping (confined to
+    // `CORNER_RADIUS` rows from the top - see its doc comment) --
+    // otherwise a clipped-to-transparent corner pixel (a different
+    // byte pattern than `bg_bytes`) registers as "ink" at column 0
+    // regardless of where the text actually starts.
+    let scan_rows = CORNER_RADIUS as usize..height as usize;
+    let leftmost_ink_column = |buf: &[u8]| -> Option<usize> {
+        (0..width as usize).find(|&x| scan_rows.clone().any(|y| buf[(y * width as usize + x) * 4..(y * width as usize + x) * 4 + 4] != bg_bytes))
+    };
+    let left = render_titlebar(width, height, "Hi", bg, fg, true, CORNER_RADIUS, 0, true, None, false, false, false, None, true, false);
+    let centered = render_titlebar(width, height, "Hi", bg, fg, true, CORNER_RADIUS, 0, true, None, true, false, false, None, true, false);
+    let left_start = leftmost_ink_column(&left).expect("left-aligned title must draw some ink");
+    let centered_start = leftmost_ink_column(&centered).expect("centered title must draw some ink");
+    assert!(centered_start > left_start, "a short title centered in a wide titlebar must start well to the right of the left-aligned version (left starts at {left_start}, centered at {centered_start})");
+}
+
+#[test]
+fn centered_title_ignores_the_button_reservation_and_centers_on_the_whole_width() {
+    if find_system_font().is_none() {
+        eprintln!("skipping: no system font found in this sandbox");
+        return;
+    }
+    let bg = (0x2e, 0x34, 0x40);
+    let fg = (0xec, 0xef, 0xf4);
+    // Wide enough for the 3-button reservation (`width >=
+    // BUTTON_CLUSTER_MARGIN + BUTTON_PITCH * 3`) on the left - this is
+    // exactly the case that used to center in the narrower `text_start
+    // ..text_limit` span left over after the buttons, landing off the
+    // window's true center instead of at `width / 2`.
+    let (width, height) = (300u32, 30u32);
+    assert!(width >= srdwm_core::BUTTON_CLUSTER_MARGIN + srdwm_core::BUTTON_PITCH * 3, "sanity: this fixture must have button squares eating into text_start");
+    let bg_bytes = rgb_to_bgra(bg, 255);
+    let scan_rows = CORNER_RADIUS as usize..height as usize;
+    // Scan only from `text_start` (the button reservation's own right
+    // edge) onward - the centering formula never places text left of
+    // that regardless, and scanning from column 0 would also pick up
+    // the button dots themselves (real, different-colour ink), not
+    // just the title text this is actually trying to measure.
+    let button_reservation = srdwm_core::BUTTON_CLUSTER_MARGIN as usize + srdwm_core::BUTTON_PITCH as usize * 3;
+    let ink_columns = |buf: &[u8]| -> Vec<usize> {
+        (button_reservation..width as usize).filter(|&x| scan_rows.clone().any(|y| buf[(y * width as usize + x) * 4..(y * width as usize + x) * 4 + 4] != bg_bytes)).collect()
+    };
+    let buf = render_titlebar(width, height, "Hi", bg, fg, true, CORNER_RADIUS, 0, true, None, true, true, false, None, true, false);
+    let columns = ink_columns(&buf);
+    let (first, last) = (*columns.first().expect("centered title must draw some ink"), *columns.last().unwrap());
+    let midpoint = (first + last) as f32 / 2.0;
+    let old_buggy_midpoint = 195.0; // center of the 90..300 span the button reservation used to leave
+    assert!((midpoint - width as f32 / 2.0).abs() < 5.0, "title midpoint {midpoint} should land within a few px of the true window center ({}), not the button-adjusted span's own center ({old_buggy_midpoint})", width as f32 / 2.0);
+}
+
+#[test]
+fn empty_title_leaves_buffer_all_background_outside_the_rounded_corners() {
+    let bg = (0x10, 0x20, 0x30);
+    let (width, height) = (50, 24);
+    let buf = render_titlebar(width, height, "", bg, (0xff, 0xff, 0xff), true, CORNER_RADIUS, 0, true, None, false, false, false, None, true, false);
+    let bg_bytes = rgb_to_bgra(bg, 255);
+    for (i, px) in buf.chunks_exact(4).enumerate() {
+        let (x, y) = (i % width as usize, i / width as usize);
+        let in_top_left = x < CORNER_RADIUS as usize && y < CORNER_RADIUS as usize;
+        let in_top_right = x >= width as usize - CORNER_RADIUS as usize && y < CORNER_RADIUS as usize;
+        if !in_top_left && !in_top_right {
+            assert_eq!(px, bg_bytes, "unexpected non-background pixel at ({x}, {y})");
+        }
+    }
+}
+
+#[test]
+fn corners_are_clipped_but_the_middle_is_not() {
+    let bg = (0x10, 0x20, 0x30);
+    let (width, height) = (50, 24);
+    let buf = render_titlebar(width, height, "", bg, (0xff, 0xff, 0xff), true, CORNER_RADIUS, 0, true, None, false, false, false, None, true, false);
+    let alpha_at = |x: usize, y: usize| buf[(y * width as usize + x) * 4 + 3];
+    // The very corner pixel is well outside the quarter-circle at any
+    // sane radius - fully clipped.
+    assert_eq!(alpha_at(0, 0), 0, "top-left corner pixel should be transparent");
+    assert_eq!(alpha_at(width as usize - 1, 0), 0, "top-right corner pixel should be transparent");
+    // Bottom corners are deliberately left square (see the function's
+    // doc comment: the titlebar's bottom edge meets client content,
+    // which can't be clipped the same way).
+    assert_eq!(alpha_at(0, height as usize - 1), 255, "bottom-left must stay square");
+    assert_eq!(alpha_at(width as usize - 1, height as usize - 1), 255, "bottom-right must stay square");
+    // Centre is nowhere near either corner circle - untouched.
+    assert_eq!(alpha_at(width as usize / 2, height as usize / 2), 255);
+}
+
+#[test]
+fn clipped_corner_pixels_are_fully_premultiplied_zero_not_just_alpha() {
+    // Regression test: `round_top_corners` used to zero only the alpha
+    // byte of a clipped pixel, leaving the opaque background RGB behind
+    // it untouched. This buffer is `Fourcc::Argb8888`, which both
+    // Wayland/`wl_shm` and Pixman treat as premultiplied - Pixman's own
+    // `OVER` compositing (`result = src + dst * (1 - src_alpha)`) does
+    // not treat `alpha=0, rgb=<something>` as "contributes nothing": it
+    // adds that stale, un-premultiplied `rgb` straight through, so the
+    // "clipped" corner still rendered fully opaque and every window's
+    // top corners read as square regardless of a nonzero radius --
+    // confirmed live, pixel-by-pixel, zero transparency anywhere in a
+    // real window's corner. A genuinely transparent premultiplied pixel
+    // is `(0, 0, 0, 0)` in every channel, not just alpha.
+    let bg = (0x10, 0x20, 0x30);
+    let (width, height) = (50, 24);
+    let buf = render_titlebar(width, height, "", bg, (0xff, 0xff, 0xff), true, CORNER_RADIUS, 0, true, None, false, false, false, None, true, false);
+    let px_at = |x: usize, y: usize| &buf[(y * width as usize + x) * 4..(y * width as usize + x) * 4 + 4];
+    assert_eq!(px_at(0, 0), [0, 0, 0, 0], "top-left corner pixel must be fully zeroed (premultiplied transparent), not just alpha");
+    assert_eq!(px_at(width as usize - 1, 0), [0, 0, 0, 0], "top-right corner pixel must be fully zeroed (premultiplied transparent), not just alpha");
+}
+
+#[test]
+fn round_corners_false_leaves_the_top_corners_square() {
+    let bg = (0x10, 0x20, 0x30);
+    let (width, height) = (50, 24);
+    let buf = render_titlebar(width, height, "", bg, (0xff, 0xff, 0xff), false, CORNER_RADIUS, 0, true, None, false, false, false, None, true, false);
+    let alpha_at = |x: usize, y: usize| buf[(y * width as usize + x) * 4 + 3];
+    assert_eq!(alpha_at(0, 0), 255, "top-left corner should stay square when round_corners is false");
+    assert_eq!(alpha_at(width as usize - 1, 0), 255, "top-right corner should stay square when round_corners is false");
+}
+
+#[test]
+fn brighten_lightens_every_channel_including_a_saturated_one() {
+    let (r, g, b) = brighten((0x28, 0xc8, 0x00));
+    assert!(r > 0x28, "already-bright channel must still move toward white, not stay put");
+    assert!(g > 0xc8);
+    assert!(b > 0x00, "a fully-unsaturated (0) channel must still brighten, not stay clamped at 0");
+}
+
+#[test]
+fn hovering_the_close_button_brightens_only_that_dot() {
+    // The actual feature this is for: hovering one button must change
+    // *that* button's colour and leave the other two exactly as they
+    // were - not brighten all three, and not brighten the wrong one.
+    let (width, height) = (200u32, srdwm_core::TITLEBAR_HEIGHT);
+    let bg = (0x2e, 0x34, 0x40);
+    let fg = (0xec, 0xef, 0xf4);
+    let plain = render_titlebar(width, height, "", bg, fg, true, CORNER_RADIUS, 0, true, None, false, false, false, None, true, false);
+    let close_hovered = render_titlebar(width, height, "", bg, fg, true, CORNER_RADIUS, 0, true, Some((srdwm_core::TitlebarHit::Close, 255)), false, false, false, None, true, false);
+    let frame = srdwm_core::Rect::new(0, 0, width, height);
+    let (w, h) = (width as usize, height as usize);
+    let margin = srdwm_core::BUTTON_CLUSTER_MARGIN as usize;
+    let close_box = button_box(w, h, margin, false, BUTTON_MARGIN);
+    let minimize_box = button_box(w, h, margin + srdwm_core::BUTTON_PITCH as usize * 2, false, BUTTON_MARGIN);
+    let center_px = |buf: &[u8], (x0, y0, x1, y1): (i32, i32, i32, i32)| {
+        let (cx, cy) = ((x0 + x1) / 2, (y0 + y1) / 2);
+        let i = (cy as usize * w + cx as usize) * 4;
+        buf[i..i + 4].to_vec()
+    };
+    assert_ne!(center_px(&plain, close_box), center_px(&close_hovered, close_box), "hovering close must actually change its own dot's colour");
+    assert_eq!(center_px(&plain, minimize_box), center_px(&close_hovered, minimize_box), "hovering close must not also change the minimize dot");
+    // Sanity: hit_test must actually route a click at this same centre
+    // point to Close, or this test would be checking a hover state
+    // that a real pointer could never reach in the first place.
+    let (cx, cy) = ((close_box.0 + close_box.2) / 2, (close_box.1 + close_box.3) / 2);
+    assert_eq!(srdwm_core::ResizeEdge::hit_test(frame, cx, cy, true, 0, srdwm_core::RESIZE_MARGIN, false, None, false), Some(srdwm_core::TitlebarHit::Close));
+}
+
+#[test]
+fn button_dot_has_a_glossy_highlight_toward_the_upper_left_and_shadow_toward_the_lower_right() {
+    // The actual visual change requested: a flat-filled dot read as
+    // noticeably flatter than real macOS's own traffic lights (see
+    // `glossy_shade`'s own doc comment, referenced against a real
+    // screenshot). This locks in the shape of that gradient, not just
+    // that pixels differ from the center - upper-left must be
+    // brighter than center, lower-right must be darker, matching a
+    // light source up-and-to-the-left.
+    let (width, height) = (200u32, srdwm_core::TITLEBAR_HEIGHT);
+    let bg = (0x2e, 0x34, 0x40);
+    let fg = (0xec, 0xef, 0xf4);
+    let buf = render_titlebar(width, height, "", bg, fg, true, CORNER_RADIUS, 0, true, None, false, false, false, None, true, false);
+    let (w, h) = (width as usize, height as usize);
+    let close_box = button_box(w, h, srdwm_core::BUTTON_CLUSTER_MARGIN as usize, false, BUTTON_MARGIN);
+    let (cx, cy) = ((close_box.0 + close_box.2) / 2, (close_box.1 + close_box.3) / 2);
+    let radius = ((close_box.2 - close_box.0).min(close_box.3 - close_box.1) as f32 / 2.0) * 0.6;
+    let px = |x: i32, y: i32| -> u32 {
+        let i = (y as usize * w + x as usize) * 4;
+        // BGRA - sum the colour channels, ignore alpha (always 255
+        // here), so "brighter"/"darker" reads as a plain luma proxy.
+        buf[i] as u32 + buf[i + 1] as u32 + buf[i + 2] as u32
+    };
+    let center = px(cx, cy);
+    let highlight = px(cx - radius.round() as i32, cy - radius.round() as i32);
+    let shadow = px(cx + radius.round() as i32, cy + radius.round() as i32);
+    assert!(highlight > center, "upper-left of the dot ({highlight}) should be brighter than its centre ({center})");
+    assert!(shadow < center, "lower-right of the dot ({shadow}) should be darker than its centre ({center})");
+}
+
+#[test]
+fn border_top_rounds_its_own_top_corners_to_match_the_titlebar() {
+    // Regression coverage for the "not all window borders are rounded"
+    // report: a bordered window's titlebar used to render with
+    // `round_corners = false` specifically to avoid clashing with this
+    // strip's square corners. Now that this strip rounds too, that
+    // workaround is gone (`render_titlebar` is always called with
+    // `true`) - this just confirms the strip actually does what that
+    // change now depends on.
+    let color = (0x40, 0x50, 0x60);
+    let (width, thickness) = (60, 2);
+    let buf = render_border_top(width, thickness, color, CORNER_RADIUS);
+    let alpha_at = |x: usize, y: usize| buf[(y * width as usize + x) * 4 + 3];
+    assert_eq!(alpha_at(0, 0), 0, "top-left corner pixel should be clipped");
+    assert_eq!(alpha_at(width as usize - 1, 0), 0, "top-right corner pixel should be clipped");
+    // The strip is only `thickness` pixels tall, but its curve is the
+    // titlebar's own radius continued outward (`radius + thickness`,
+    // see `render_border_top`) - so the horizontal centre, well clear
+    // of either corner's cut zone, must stay opaque regardless of how
+    // much taller than the strip that combined radius is.
+    assert_eq!(alpha_at(width as usize / 2, thickness as usize - 1), 255, "centre of the strip must stay opaque");
+}
+
+#[test]
+fn border_top_and_titlebar_corners_meet_without_a_seam() {
+    // Regression coverage for a *different* bug than the one this test
+    // used to check (see git history for the old
+    // `border_top_corner_curve_matches_the_titlebars_larger_radius`):
+    // an earlier version of this pair rounded the border strip to
+    // `radius + thickness` while the titlebar rounded to plain
+    // `radius` - two circles sharing a centre but with *different*
+    // radii, which do not meet smoothly at any boundary between them.
+    // Confirmed live, screenshotted at actual render resolution: a
+    // hard stepped notch right where a decorated window's border met
+    // its titlebar, not a continuous curve. Both now draw their own
+    // slice of the exact same circle (`round_top_corners`'s own doc
+    // comment has the full geometry) - this checks that promise
+    // directly, by rendering both real bitmaps with the same
+    // parameters a live window actually uses and comparing the alpha
+    // at the border's last row against the titlebar's first row,
+    // immediately below it.
+    let color = (0x40, 0x50, 0x60);
+    let (width, thickness, radius) = (60, 4, 6);
+    let border = render_border_top(width, thickness, color, radius);
+    let titlebar = render_titlebar(width, 24, "", color, (0xff, 0xff, 0xff), true, radius, thickness, true, None, false, false, false, None, true, false);
+    let border_alpha_at = |x: usize| border[((thickness as usize - 1) * width as usize + x) * 4 + 3];
+    let titlebar_alpha_at = |x: usize| titlebar[x * 4 + 3];
+    // Every column across the curve's actual reach, not just one
+    // sample point - a seam bug shows up as a jump at some columns
+    // and not others (the exact shape of the mismatch between two
+    // differently-sized circles), so checking only the corner pixel
+    // or only the centre could miss it entirely, the same way the
+    // original bug slipped past the test above it for months. Worked
+    // out by hand (see this fix's own commit) what the two designs
+    // actually produce at every column for radius=6/thickness=4: the
+    // old (`radius + thickness`-for-the-border) design jumped by as
+    // much as 187 out of 255, at *every* column past the first two;
+    // this design jumps by at most 70, confined to the two columns
+    // nearest the exact tip - an inherent limit of splitting one
+    // steep curve across two separately-rasterised bitmaps a single
+    // row apart, not a bug to chase further. `< 90` catches any
+    // regression back toward the old behaviour without demanding
+    // more precision than two 1px-apart raster buffers can give.
+    for x in 0..radius as usize + 2 {
+        let (b, t) = (border_alpha_at(x), titlebar_alpha_at(x));
+        let jump = (b as i32 - t as i32).abs();
+        assert!(jump < 90, "column {x}: border's last row (alpha={b}) and titlebar's first row (alpha={t}) must be close, not a sharp seam (jump={jump})");
+    }
+    // Past the tip's unavoidable steepness (columns 0-1 above), the
+    // curve should be genuinely, near-exactly continuous - both
+    // rows fully opaque by then for this radius/thickness, not just
+    // "close enough".
+    for x in 2..radius as usize + 2 {
+        let (b, t) = (border_alpha_at(x), titlebar_alpha_at(x));
+        let jump = (b as i32 - t as i32).abs();
+        assert!(jump <= 2, "column {x}: past the corner tip the seam should be essentially exact, not just under the looser tip tolerance (jump={jump})");
+    }
+}
+
+#[test]
+fn border_top_visible_rows_decorated_shows_the_whole_taller_buffer() {
+    let (row0, rows, shift) = border_top_visible_rows(true, 4, 11);
+    assert_eq!((row0, rows, shift), (0, 11, 0), "decorated: full max(border_width, radius) buffer, unshifted");
+}
+
+#[test]
+fn border_top_visible_rows_undecorated_crops_to_just_the_nominal_thickness() {
+    // The actual regression this exists for: reported live as a
+    // border-coloured wedge cut into a real undecorated Firefox
+    // window's top-left corner, confirmed via a real screenshot to be
+    // neither Firefox's own rendering nor the content-mask feature --
+    // this buffer's own titlebar-band-only extra rows, painted
+    // straight onto real content instead, were the only remaining
+    // source.
+    let (row0, rows, shift) = border_top_visible_rows(false, 4, 11);
+    assert_eq!((row0, rows, shift), (0, 4, 0), "undecorated: cropped to exactly border_width rows, still starting at row 0 (this strip grows downward)");
+}
+
+#[test]
+fn border_top_visible_rows_radius_no_bigger_than_border_is_a_no_op_either_way() {
+    // When the buffer was never grown taller than `border_width` in
+    // the first place (radius <= border_width), decorated and
+    // undecorated must agree - there are no "extra" rows to disagree
+    // about.
+    assert_eq!(border_top_visible_rows(true, 6, 4), border_top_visible_rows(false, 6, 4));
+}
+
+#[test]
+fn border_bottom_visible_rows_decorated_shows_the_whole_taller_buffer_shifted_up() {
+    let (row0, rows, shift) = border_bottom_visible_rows(true, 4, 11);
+    assert_eq!((row0, rows, shift), (0, 11, 7), "decorated: full buffer, shifted up by extra = max(4,11) - 4 = 7");
+}
+
+#[test]
+fn border_bottom_visible_rows_undecorated_crops_to_the_buffers_last_rows_unshifted() {
+    // Same real bug as the top strip, confirmed on the same Firefox
+    // window's bottom-left corner via a real screenshot - this strip
+    // grows *upward* into content instead of downward, so the safe
+    // rows are the buffer's *last* `border_width` of them (starting at
+    // `row0 = extra`), not its first, and no position shift is needed
+    // once the extra rows themselves are never drawn.
+    let (row0, rows, shift) = border_bottom_visible_rows(false, 4, 11);
+    assert_eq!((row0, rows, shift), (7, 4, 0), "undecorated: last border_width rows only, starting past the 7-row extra, unshifted");
+}
+
+#[test]
+fn border_bottom_visible_rows_radius_no_bigger_than_border_is_a_no_op_either_way() {
+    assert_eq!(border_bottom_visible_rows(true, 6, 4), border_bottom_visible_rows(false, 6, 4));
+}
+
+#[test]
+fn border_top_extra_rows_are_transparent_outside_the_corners() {
+    // `render_border_bottom`'s mirror - see
+    // `border_bottom_extra_rows_are_transparent_outside_the_corners`'s
+    // doc comment for the full story (this is the same real,
+    // live-confirmed bug, the top-strip half of the pair).
+    let color = (0x40, 0x50, 0x60);
+    let (width, thickness, radius) = (60, 2, 6);
+    let buf = render_border_top(width, thickness, color, radius);
+    let height = (thickness as usize).max(radius as usize);
+    assert_eq!(buf.len(), width as usize * height * 4, "buffer must actually be the taller max(thickness, radius) height");
+    let alpha_at = |x: usize, y: usize| buf[(y * width as usize + x) * 4 + 3];
+    // The strip's real thickness sits at the *top* here (rows grow
+    // downward into content, the mirror of the bottom strip growing
+    // upward) - rows 0..thickness must still be fully opaque in the
+    // middle, exactly as before this fix.
+    for y in 0..thickness as usize {
+        assert_eq!(alpha_at(width as usize / 2, y), 255, "row {y}: within the strip's real thickness, the middle column must stay opaque");
+    }
+    for y in thickness as usize..height {
+        assert_eq!(alpha_at(width as usize / 2, y), 0, "row {y}: middle column of an extra row must be transparent, not solid border colour");
+    }
+}
+
+#[test]
+fn border_top_curve_actually_closes_within_the_side_strips_own_width() {
+    // The actual, directly-observable bug this whole fix is for:
+    // confirmed live via pixel-level inspection of a real screenshot
+    // (not just reasoned about) that the horizontal top border segment
+    // only became opaque some ~20 columns in from the corner while the
+    // *flat, curve-blind* left/right strip only ever covers its own
+    // `border_width` columns - so with `radius` meaningfully larger
+    // than `border_width`, there was a real gap of bare background
+    // between them, at exactly the column range a real vertical border
+    // strip occupies. This checks that gap is actually closed: by this
+    // buffer's own last row (where the curve should have fully
+    // resolved to flat, for a `radius` that fits within the strip's
+    // half-width), the column right at the edge of where a
+    // `border_width`-wide side strip would sit must already be opaque.
+    let color = (0x40, 0x50, 0x60);
+    let (width, thickness, border_width, radius) = (60u32, 2u32, 3u32, 6u32);
+    let buf = render_border_top(width, thickness, color, radius);
+    let height = (thickness as usize).max(radius as usize);
+    let alpha_at = |x: usize, y: usize| buf[(y * width as usize + x) * 4 + 3];
+    assert_eq!(alpha_at(border_width as usize - 1, height - 1), 255, "the side strip's own rightmost column must be fully covered by the curve at the buffer's last row, not left as a gap");
+}
+
+#[test]
+fn border_bottom_rounds_its_own_bottom_corners() {
+    // `thickness` (2) < `CORNER_RADIUS` (6) here, same as the live
+    // theme defaults (border width 4, radius 6) - so the buffer is
+    // taller than `thickness`, and the true tip (fully clipped corner)
+    // sits at the buffer's own *last* row, not `thickness - 1` (see
+    // `render_border_bottom`'s doc comment for why the buffer grows at
+    // all).
+    let color = (0x40, 0x50, 0x60);
+    let (width, thickness) = (60, 2);
+    let buf = render_border_bottom(width, thickness, color, CORNER_RADIUS);
+    let height = (thickness as usize).max(CORNER_RADIUS as usize);
+    assert_eq!(buf.len(), width as usize * height * 4, "buffer must actually be the taller max(thickness, radius) height");
+    let alpha_at = |x: usize, y: usize| buf[(y * width as usize + x) * 4 + 3];
+    let tip_row = height - 1;
+    assert_eq!(alpha_at(0, tip_row), 0, "bottom-left corner pixel should be clipped");
+    assert_eq!(alpha_at(width as usize - 1, tip_row), 0, "bottom-right corner pixel should be clipped");
+    assert_eq!(alpha_at(width as usize / 2, tip_row), 255, "centre of the strip must stay opaque even at the tip row");
+}
+
+#[test]
+fn border_bottom_extra_rows_are_transparent_outside_the_corners() {
+    // Regression coverage for the real bug this pair of functions was
+    // fixed for: with `radius > thickness`, the strip's own curve
+    // didn't reach far enough to meet the (curve-blind, flat) side
+    // strips, leaving a wedge of bare background between them --
+    // confirmed live via pixel-level inspection of a real screenshot,
+    // not just reasoned about. The fix grows the buffer to
+    // `max(thickness, radius)` so the curve has room to fully resolve,
+    // but the *extra* rows (above the original `thickness`, since this
+    // strip grows upward into content - see `render_border_bottom`'s
+    // doc comment) must stay transparent in the middle (non-corner)
+    // columns, or they'd paint a solid border-coloured bar across
+    // whatever the content actually owns there.
+    let color = (0x40, 0x50, 0x60);
+    let (width, thickness, radius) = (60, 2, 6);
+    let buf = render_border_bottom(width, thickness, color, radius);
+    let height = (thickness as usize).max(radius as usize);
+    let alpha_at = |x: usize, y: usize| buf[(y * width as usize + x) * 4 + 3];
+    for y in 0..height - thickness as usize {
+        assert_eq!(alpha_at(width as usize / 2, y), 0, "row {y}: middle column of an extra row must be transparent, not solid border colour");
+    }
+    // The original `thickness` rows (now at the *bottom* of the taller
+    // buffer) must still be the strip's real, fully opaque body in the
+    // middle - this fix must not have eaten into the strip's own
+    // legitimate thickness.
+    for y in height - thickness as usize..height {
+        assert_eq!(alpha_at(width as usize / 2, y), 255, "row {y}: within the strip's real thickness, the middle column must stay opaque");
+    }
+}
+
+#[test]
+fn context_menu_is_one_row_tall_per_item() {
+    let items = [("Minimize", false), ("Maximize", false), ("Always on Top", false), ("Close", false)];
+    let buf = render_context_menu(160, 28, &items, (0x2e, 0x34, 0x40), (0xff, 0xff, 0xff), (0x4c, 0x56, 0x6a), (0x10, 0x10, 0x10));
+    assert_eq!(buf.len(), 160 * (28 * 4) * 4);
+}
+
+#[test]
+fn context_menu_highlighted_row_has_a_different_background_than_the_rest() {
+    let items = [("Minimize", false), ("Close", true)];
+    let bg = (0x2e, 0x34, 0x40);
+    let highlight = (0x4c, 0x56, 0x6a);
+    let buf = render_context_menu(160, 28, &items, bg, (0xff, 0xff, 0xff), highlight, (0x10, 0x10, 0x10));
+    let width = 160usize;
+    // Sample a background pixel from each row, away from the text/border.
+    let px_at = |x: usize, y: usize| -> [u8; 3] {
+        let i = (y * width + x) * 4;
+        [buf[i + 2], buf[i + 1], buf[i]] // BGRA -> RGB
+    };
+    assert_eq!(px_at(100, 5), [bg.0, bg.1, bg.2], "row 0 (not highlighted) should use bg");
+    assert_eq!(px_at(100, 33), [highlight.0, highlight.1, highlight.2], "row 1 (highlighted) should use highlight_bg");
+}
+
+#[test]
+fn context_menu_border_is_opaque_at_every_edge() {
+    let items = [("Close", false)];
+    let buf = render_context_menu(100, 28, &items, (0, 0, 0), (0xff, 0xff, 0xff), (0, 0, 0), (0x99, 0x99, 0x99));
+    let alpha_at = |x: usize, y: usize| buf[(y * 100 + x) * 4 + 3];
+    assert_eq!(alpha_at(0, 0), 255);
+    assert_eq!(alpha_at(99, 0), 255);
+    assert_eq!(alpha_at(0, 27), 255);
+    assert_eq!(alpha_at(99, 27), 255);
+}
+
+#[test]
+fn snap_flyout_is_sized_for_a_full_grid_of_labels() {
+    let labels = ["Left Half", "Right Half", "Top Left", "Top Right", "Bottom Left", "Bottom Right"];
+    let buf = render_snap_flyout(3, 90, 60, &labels, (0x2e, 0x34, 0x40), (0xff, 0xff, 0xff), (0x10, 0x10, 0x10));
+    // 3 columns x 2 rows (6 labels / 3 columns, rounded up).
+    assert_eq!(buf.len(), (90 * 3) * (60 * 2) * 4);
+}
+
+#[test]
+fn snap_flyout_border_is_opaque_at_every_outer_edge() {
+    let labels = ["A", "B", "C", "D", "E", "F"];
+    let (cell_w, cell_h) = (90, 60);
+    let buf = render_snap_flyout(3, cell_w, cell_h, &labels, (0, 0, 0), (0xff, 0xff, 0xff), (0x99, 0x99, 0x99));
+    let (width, height) = (cell_w * 3, cell_h * 2);
+    let alpha_at = |x: usize, y: usize| buf[(y * width as usize + x) * 4 + 3];
+    assert_eq!(alpha_at(0, 0), 255);
+    assert_eq!(alpha_at(width as usize - 1, 0), 255);
+    assert_eq!(alpha_at(0, height as usize - 1), 255);
+    assert_eq!(alpha_at(width as usize - 1, height as usize - 1), 255);
+}
+
+#[test]
+fn snap_flyout_has_an_internal_grid_line_between_columns() {
+    let labels = ["A", "B", "C", "D", "E", "F"];
+    let (cell_w, cell_h) = (90, 60);
+    let buf = render_snap_flyout(3, cell_w, cell_h, &labels, (0, 0, 0), (0xff, 0xff, 0xff), (0x99, 0x99, 0x99));
+    let width = cell_w * 3;
+    // The boundary between column 0 and column 1, away from the outer border.
+    let idx = (30 * width as usize + cell_w as usize) * 4;
+    assert_eq!(buf[idx + 3], 255, "column boundary must be drawn, not just the outer border");
+}
diff --git a/crates/wayland/src/decoration/titlebar.rs b/crates/wayland/src/decoration/titlebar.rs
new file mode 100644
index 0000000..49f9de5
--- /dev/null
+++ b/crates/wayland/src/decoration/titlebar.rs
@@ -0,0 +1,295 @@
+//! Laying out and rasterizing the whole titlebar band: background, title
+//! text, and the button cluster (which one goes where, which side, how
+//! many). The buttons' own dots/glyphs are `buttons.rs`'s job; the corner
+//! cut at the end is `corners.rs`'s.
+
+use super::buttons::{
+    draw_close_glyph, draw_maximize_glyph, draw_minimize_glyph, draw_zoom_glyph, fill_button_dot, BUTTON_MARGIN, BUTTON_MARGIN_LEFT, TRAFFIC_LIGHT_CLOSE,
+    TRAFFIC_LIGHT_INACTIVE, TRAFFIC_LIGHT_MAXIMIZE, TRAFFIC_LIGHT_MINIMIZE,
+};
+use super::color::{brighten, darken, rgb_to_bgra};
+use super::corners::round_top_corners;
+use super::font::{blit_glyph, find_system_font, FONT_PIXELS, TEXT_LEFT_PADDING};
+
+/// Renders a `width x height` BGRA8 buffer: filled with `background`, with
+/// `title` drawn left-aligned in `foreground` (best-effort glyph layout --
+/// no text shaping/kerning, adequate for the ASCII-heavy titles window
+/// managers actually display). Returns `None` (caller keeps the previous
+/// solid-color-only look) only if no usable font was found on this system.
+///
+/// `round_corners` should be `false` only for a window whose border strips
+/// are rendered as plain square-cornered fills with no matching rounded
+/// treatment of their own. `border::render_border_top` gives the border's
+/// top strip the same rounded-corner cut (see its own doc comment for how
+/// the two stay visually continuous), so a normal bordered window should
+/// pass `true` here same as a borderless one now - reported live as most
+/// windows (anything with the default border) looking inconsistently
+/// square next to the few borderless ones that were rounded.
+///
+/// `border_width` shifts the corner circle's centre by that many rows (see
+/// `corners::round_top_corners`'s own doc comment): a titlebar with a
+/// border strip sitting above it starts `border_width` rows *into* the
+/// shared circle, not at its top, so it needs the same shift subtracted to
+/// draw its own correct slice of that one circle rather than a second,
+/// uncoordinated one. Pass `0` for an undecorated/borderless window's
+/// titlebar (there is none in practice - an undecorated window has no
+/// titlebar at all - but `0` is also the correct, harmless value if
+/// `round_corners` handling ever changes to allow it).
+#[allow(clippy::too_many_arguments)]
+pub fn render_titlebar(
+    width: u32,
+    height: u32,
+    title: &str,
+    background: (u8, u8, u8),
+    foreground: (u8, u8, u8),
+    round_corners: bool,
+    radius: u32,
+    border_width: u32,
+    focused: bool,
+    // `(button, glyph alpha 0..=255)` - the alpha is the eased hover-
+    // reveal animation's own current progress (see `tick_hover_glyph_
+    // animation`), already discretized by the caller so this stays a
+    // plain data-in function with no `Instant`/timing concept of its own.
+    hovered: Option<(srdwm_core::TitlebarHit, u8)>,
+    centered: bool,
+    buttons_left: bool,
+    // Modern GNOME/Adwaita mode (see `ThemeConfig::button_glyph_always`'s
+    // own doc comment): every glyph drawn at full opacity always, `hovered`
+    // only still used for the background-circle brighten below, not glyph
+    // visibility.
+    glyph_always: bool,
+    // `ThemeConfig::button_order`'s resolved value - see `ButtonOrder`'s
+    // own doc comment. Must stay in agreement with whatever `ResizeEdge::
+    // hit_test` was called with for the same window, the same "renders on
+    // one side, hit-tests on the other" trap `buttons_left` itself already
+    // has to avoid.
+    button_order: Option<srdwm_core::ButtonOrder>,
+    // `ThemeConfig::traffic_light_buttons`'s resolved value - see its own
+    // doc comment for what each mode actually draws differently.
+    traffic_lights: bool,
+    // `Window::is_dialog`'s resolved value - see its own doc comment. Only
+    // Close is ever drawn for a dialog, and never as a coloured traffic
+    // light regardless of `traffic_lights` above (forced off below):
+    // requested directly ("dialog windows shouldn't have maximize/minimize
+    // buttons... don't use traffic lights there ever"). Must stay in exact
+    // agreement with `ResizeEdge::hit_test`'s own `is_dialog` parameter,
+    // the same "renders on one side, hit-tests on the other" trap every
+    // other button-geometry value here already has to avoid.
+    is_dialog: bool,
+) -> Vec<u8> {
+    let (width, height) = (width.max(1) as usize, height.max(1) as usize);
+    // Forced off, not just defaulted - a dialog never gets coloured
+    // traffic lights even when the active theme otherwise uses them
+    // everywhere else.
+    let traffic_lights = traffic_lights && !is_dialog;
+    let bg = rgb_to_bgra(background, 255);
+    let mut buf = vec![0u8; width * height * 4];
+    for px in buf.chunks_exact_mut(4) {
+        px.copy_from_slice(&bg);
+    }
+
+    // Reserve the button squares (whichever side they're actually on)
+    // before laying out text, so a long title elides under them the same
+    // way it would under real window furniture rather than drawing on top
+    // of it. `text_start`/`text_limit` bound the span text is allowed to
+    // occupy - both edges when `buttons_left` (buttons eat into the left,
+    // not the right), only the far edge otherwise.
+    let pitch = srdwm_core::BUTTON_PITCH as usize;
+    let cluster_margin = srdwm_core::BUTTON_CLUSTER_MARGIN as usize;
+    // A dialog only ever gets one button (Close) - see this function's own
+    // `is_dialog` doc comment.
+    let wanted_buttons = if is_dialog { 1 } else { 3 };
+    let button_count = if width >= cluster_margin + pitch * wanted_buttons { wanted_buttons } else { 0 };
+    // `BUTTON_CLUSTER_MARGIN` included, not just the buttons' own `pitch *
+    // button_count` span - the cluster's own leading gap needs reserving
+    // too, or a long title's text could draw underneath it (or, on the
+    // `buttons_left` side, right through the gap between the titlebar's
+    // real edge and the first button).
+    let reserved = if button_count > 0 { cluster_margin + pitch * button_count } else { 0 };
+    let (text_start, text_limit) = if buttons_left { (reserved as f32, width as f32) } else { (TEXT_LEFT_PADDING, width.saturating_sub(reserved) as f32) };
+
+    if let Some(font) = find_system_font() {
+        let baseline = (height as f32 * 0.72).round();
+        // Rasterized up front, not drawn incrementally in one pass - see
+        // `title_centered`'s own doc comment: centering needs the title's
+        // total advance width known *before* the first pixel is placed,
+        // and reusing these glyphs for the real draw below avoids
+        // rasterizing every character twice just to get there. Same
+        // truncation rule as before this existed: a glyph whose own
+        // advance crosses `text_limit` still gets drawn (matches a real
+        // window's furniture starting exactly at `text_limit`, not one
+        // glyph-width short of it), only the *next* one is dropped.
+        let mut glyphs: Vec<(fontdue::Metrics, Vec<u8>)> = Vec::new();
+        let mut total_width = 0.0f32;
+        for ch in title.chars() {
+            if ch.is_control() {
+                continue;
+            }
+            let (metrics, coverage) = font.rasterize(ch, FONT_PIXELS);
+            let advance = metrics.advance_width;
+            let already_past_limit = text_start + total_width >= text_limit;
+            if already_past_limit {
+                break;
+            }
+            total_width += advance;
+            glyphs.push((metrics, coverage));
+        }
+        // Centered on the *whole* titlebar width, not on the narrower
+        // `text_start..text_limit` span left over after reserving the
+        // button squares - matches real macOS, which ignores its own
+        // traffic-light cluster for centering purposes rather than
+        // centering in the remaining space. Centering in the reserved
+        // span instead (the previous behaviour) put the text visibly off
+        // the window's true center - for a 3-button, 30px-tall titlebar
+        // that's a 90px reservation, shifting the centered point 45px
+        // off true center, exactly the "not real center" a user would
+        // notice at a glance. Still clamped into `text_start..text_limit`
+        // afterward so a long title never draws under the buttons.
+        let start_x = if centered { ((width as f32 - total_width) / 2.0).max(text_start).min((text_limit - total_width).max(text_start)) } else { text_start };
+        let mut pen_x = start_x;
+        for (metrics, coverage) in &glyphs {
+            if metrics.width > 0 && metrics.height > 0 {
+                let glyph_x = pen_x + metrics.xmin as f32;
+                let glyph_y = baseline - metrics.height as f32 - metrics.ymin as f32;
+                blit_glyph(&mut buf, width, height, glyph_x.round() as i32, glyph_y.round() as i32, metrics, coverage, background, foreground);
+            }
+            pen_x += metrics.advance_width;
+        }
+    }
+
+    if button_count > 0 {
+        let (mut close_c, mut minimize_c, mut maximize_c) = if !traffic_lights {
+            // Unused in this mode (no dot is ever filled at rest - see the
+            // `traffic_lights` branch below), except as the base colour
+            // `brighten` starts from for the neutral hover backdrop.
+            (background, background, background)
+        } else if focused {
+            (TRAFFIC_LIGHT_CLOSE, TRAFFIC_LIGHT_MINIMIZE, TRAFFIC_LIGHT_MAXIMIZE)
+        } else {
+            (TRAFFIC_LIGHT_INACTIVE, TRAFFIC_LIGHT_INACTIVE, TRAFFIC_LIGHT_INACTIVE)
+        };
+        // Explicitly requested background-highlight-on-hover for the
+        // titlebar buttons (see docs/TODO.md) - brightens whichever one
+        // is actually hovered, close included, rather than giving close a
+        // separate hardcoded hover colour: close is already red at rest
+        // (focused) or grey (unfocused), same as the other two, so
+        // "red-on-hover for close" falls out of this same brightening,
+        // not a special case. Brightened as soon as a hover is in
+        // progress at all (any glyph alpha > 0), not gated on it having
+        // finished animating in - the circle brightening and the glyph
+        // reveal read as one combined "waking up" motion when they start
+        // together, not two separately-timed effects.
+        //
+        // One button at a time, not the whole cluster - a group-hover
+        // version (matching real macOS's own behaviour) was tried in this
+        // same session and explicitly reverted: the user confirmed this
+        // project's own convention is per-button, not per-cluster, despite
+        // what real macOS itself does.
+        let (mut close_glyph, mut minimize_glyph, mut maximize_glyph) = (0u8, 0u8, 0u8);
+        match hovered {
+            Some((srdwm_core::TitlebarHit::Close, a)) => {
+                close_c = brighten(close_c);
+                close_glyph = a;
+            }
+            Some((srdwm_core::TitlebarHit::Minimize, a)) => {
+                minimize_c = brighten(minimize_c);
+                minimize_glyph = a;
+            }
+            Some((srdwm_core::TitlebarHit::Maximize, a)) => {
+                maximize_c = brighten(maximize_c);
+                maximize_glyph = a;
+            }
+            _ => {}
+        }
+        // Traditional (non-traffic-light) glyphs are always visible, same
+        // as a real Windows/GNOME titlebar's own icons - there's no
+        // filled dot drawing attention to the button at rest the way a
+        // traffic light does, so hiding the glyph too, pending an explicit
+        // `button_glyph = "always"`, would leave the button showing
+        // nothing at all until hovered.
+        let glyph_always = glyph_always || !traffic_lights;
+        if glyph_always {
+            close_glyph = 255;
+            minimize_glyph = 255;
+            maximize_glyph = 255;
+        }
+        // A traffic-light glyph is `darken`ed from that *same* button's own
+        // (possibly already-`brighten`ed-by-hover) colour - real macOS
+        // draws a dark red mark on the red button, dark amber on the
+        // yellow one, not one shared tint reused across all three (see
+        // `darken`'s own doc comment). A traditional glyph instead uses
+        // the titlebar's actual text colour, drawn straight on the
+        // titlebar's own dark background - a dark-on-dark glyph the
+        // traffic-light shade uses would be unreadable there.
+        let (close_shade, minimize_shade, maximize_shade) =
+            if traffic_lights { (darken(close_c), darken(minimize_c), darken(maximize_c)) } else { (foreground, foreground, foreground) };
+        let margin = if buttons_left { BUTTON_MARGIN_LEFT } else { BUTTON_MARGIN };
+        // Closest-to-the-aligned-edge first - must stay in exact
+        // agreement with `ResizeEdge::hit_test`'s own resolution of the
+        // same two fields, the same "renders on one side, hit-tests on
+        // the other" trap `buttons_left` alone already has to avoid. See
+        // `ButtonOrder`'s own doc comment for why the two built-in
+        // defaults are genuinely different relative orderings, not
+        // mirrors of each other.
+        // A dialog always draws Close, full stop - not just whichever
+        // button a `button_order` override would otherwise put first, or
+        // Minimize/Maximize could still end up the one (and only) button
+        // drawn. `button_count` (1 for a dialog) caps the loop below to
+        // just this first slot either way.
+        let order: srdwm_core::ButtonOrder = if is_dialog {
+            [srdwm_core::TitlebarButton::Close; 3]
+        } else {
+            button_order.unwrap_or(if buttons_left {
+                [srdwm_core::TitlebarButton::Close, srdwm_core::TitlebarButton::Minimize, srdwm_core::TitlebarButton::Maximize]
+            } else {
+                [srdwm_core::TitlebarButton::Close, srdwm_core::TitlebarButton::Maximize, srdwm_core::TitlebarButton::Minimize]
+            })
+        };
+        // `BUTTON_CLUSTER_MARGIN` first, then each button's own `pitch * i`
+        // spacing after it - must stay in agreement with `ResizeEdge::
+        // hit_test`'s matching `left`/`right` base, the same "renders on
+        // one side, hit-tests on the other" trap every other button-
+        // geometry value here already has to avoid.
+        for (i, button) in order.iter().take(button_count).enumerate() {
+            let offset = srdwm_core::BUTTON_CLUSTER_MARGIN as usize + pitch * i;
+            match button {
+                srdwm_core::TitlebarButton::Close => {
+                    // Traditional mode has no dot at rest - only once this
+                    // button is actually the hovered one (`close_glyph > 0`,
+                    // the same signal the glyph reveal itself already uses)
+                    // does the neutral, brightened backdrop appear at all.
+                    // A traffic light always fills, rest state included.
+                    if traffic_lights || close_glyph > 0 {
+                        fill_button_dot(&mut buf, width, height, offset, buttons_left, margin, close_c);
+                    }
+                    draw_close_glyph(&mut buf, width, height, offset, buttons_left, margin, close_glyph, close_shade);
+                }
+                srdwm_core::TitlebarButton::Minimize => {
+                    if traffic_lights || minimize_glyph > 0 {
+                        fill_button_dot(&mut buf, width, height, offset, buttons_left, margin, minimize_c);
+                    }
+                    draw_minimize_glyph(&mut buf, width, height, offset, buttons_left, margin, minimize_glyph, minimize_shade);
+                }
+                srdwm_core::TitlebarButton::Maximize => {
+                    if traffic_lights || maximize_glyph > 0 {
+                        fill_button_dot(&mut buf, width, height, offset, buttons_left, margin, maximize_c);
+                    }
+                    // The macOS "zoom" double-arrow only reads correctly
+                    // paired with that same convention's traffic lights --
+                    // traditional mode keeps the plain square every other
+                    // desktop's own maximize icon already uses.
+                    if traffic_lights {
+                        draw_zoom_glyph(&mut buf, width, height, offset, buttons_left, margin, maximize_glyph, maximize_shade);
+                    } else {
+                        draw_maximize_glyph(&mut buf, width, height, offset, buttons_left, margin, maximize_glyph, maximize_shade);
+                    }
+                }
+            }
+        }
+    }
+    if round_corners {
+        round_top_corners(&mut buf, width, height, radius, radius as i32 - border_width as i32);
+    }
+    buf
+}
+
diff --git a/crates/wayland/src/elements.rs b/crates/wayland/src/elements.rs
index deabd42..d64a02d 100644
--- a/crates/wayland/src/elements.rs
+++ b/crates/wayland/src/elements.rs
@@ -151,42 +151,58 @@ where
 /// masked copy of `surface`'s content - see `rounded_corners_pixman`'s
 /// module doc comment for what this actually does and why it needs a cache
 /// at all. `epoch` is the window's current `CompState::content_epoch`
-/// value (bumped once per real commit, in `commit()`); the cached entry is
-/// only rebuilt when that no longer matches what it was last built from, so
-/// a window that isn't currently repainting costs nothing here beyond one
-/// `HashMap` lookup per frame.
+/// value (bumped once per real commit, in `commit()`); `loc`/`size` are
+/// `rounded_corners_pixman::masked_content_buffer`'s own tree-render
+/// origin and off-screen buffer dimensions (the caller's already-computed
+/// negated `content_offset` and content rect) - the cached entry is
+/// rebuilt whenever any of `epoch`/`radius`/`loc`/`size` no longer match
+/// what it was last built from, so a window that isn't currently
+/// repainting, resizing, or having its shadow-margin geometry renegotiated
+/// costs nothing here beyond one `HashMap` lookup per frame.
 ///
-/// Free function taking the two fields it needs directly, rather than a
+/// Free function taking the fields it needs directly, rather than a
 /// `CompState` method, so it can be called from inside `udev/render.rs`'s
 /// loop alongside the already-live `self.udev.as_mut()` borrow - see that
 /// call site.
 ///
-/// `None` either because masking genuinely isn't possible right now (falls
-/// through to `rounded_corners_pixman::masked_content_buffer`'s own `None`
-/// cases) or because it hasn't been attempted yet this call; either way the
-/// caller's fallback is the same: render `surface`'s content unrounded via
-/// [`surface_content_elements`].
+/// `None` either because the off-screen render itself failed (a genuine
+/// renderer error - there is no longer any "this window isn't shaped
+/// right for masking" restriction, see `masked_content_buffer`'s own doc
+/// comment) or because it hasn't been attempted yet this call; either way
+/// the caller's fallback is the same: render `surface`'s content unrounded
+/// via [`surface_content_elements`].
 pub(crate) fn rounded_content_buffer<'a>(
-    cache: &'a mut std::collections::HashMap<srdwm_core::WindowId, (u64, u32, smithay::backend::renderer::element::memory::MemoryRenderBuffer)>,
+    cache: &'a mut std::collections::HashMap<srdwm_core::WindowId, (u64, u32, (i32, i32), (i32, i32), smithay::backend::renderer::element::memory::MemoryRenderBuffer)>,
+    renderer: &mut smithay::backend::renderer::pixman::PixmanRenderer,
     epoch: u64,
     id: srdwm_core::WindowId,
     surface: &WlSurface,
+    loc: (i32, i32),
+    size: (i32, i32),
     radius: f32,
     corners: crate::rounded_corners::RoundedCorners,
 ) -> Option<&'a smithay::backend::renderer::element::memory::MemoryRenderBuffer> {
     let radius_bits = radius.to_bits();
-    let stale = cache.get(&id).map(|(built, r, _)| *built != epoch || *r != radius_bits).unwrap_or(true);
+    let stale = cache.get(&id).map(|(built, r, l, s, _)| *built != epoch || *r != radius_bits || *l != loc || *s != size).unwrap_or(true);
     if stale {
-        match crate::rounded_corners_pixman::masked_content_buffer(surface, radius, corners) {
-            Some(buf) => {
-                cache.insert(id, (epoch, radius_bits, buf));
+        match crate::rounded_corners_pixman::masked_content_buffer(renderer, surface, loc, size, radius, corners) {
+            Some(data) => {
+                let buffer = smithay::backend::renderer::element::memory::MemoryRenderBuffer::from_slice(
+                    &data,
+                    smithay::backend::allocator::Fourcc::Argb8888,
+                    size,
+                    1,
+                    smithay::utils::Transform::Normal,
+                    None,
+                );
+                cache.insert(id, (epoch, radius_bits, loc, size, buffer));
             }
             None => {
                 cache.remove(&id);
             }
         }
     }
-    cache.get(&id).map(|(_, _, b)| b)
+    cache.get(&id).map(|(_, _, _, _, b)| b)
 }
 
 /// Every mapped layer-shell surface on `output` whose [`Layer`] `include`
@@ -199,7 +215,35 @@ pub(crate) fn rounded_content_buffer<'a>(
 /// on `map.layers()` before rendering, so surfaces sharing one `Layer`
 /// keep the same relative stacking smithay's convenience wrapper gave
 /// them, now that this function replaces it.
-pub(crate) fn output_layer_elements<R>(renderer: &mut R, output: &Output, origin: (i32, i32), include: impl Fn(Layer) -> bool) -> Vec<OverlayElement<R>>
+///
+/// Takes no `origin`/global-position parameter, unlike every *other*
+/// per-head element builder in `udev/render.rs` - deliberately: those all
+/// convert a window's `geometry` (stored in *global*, whole-desktop space)
+/// into this one head's local framebuffer space by subtracting the head's
+/// own `origin`. `LayerMap::layer_geometry` is different - confirmed
+/// against smithay 0.7.0's own source (`desktop/wayland/layer.rs`): its
+/// `zone`/layer positions are built from the output's own mode size alone,
+/// with no global offset baked in at all, so it is *already* head-local.
+/// An earlier version of this function added `origin` to it anyway (to
+/// "match" the other element builders' own pattern without checking
+/// whether the input was actually the same kind of value) - harmless for
+/// a single-output setup or this output's own primary/first head, where
+/// `origin` is always `(0, 0)`, but on a second head at a real nonzero
+/// `origin` (e.g. `(1920, 0)`) it shifted every layer-shell surface - a
+/// wallpaper, a bar - clean off the right edge of that head's own
+/// 1920px-wide local framebuffer, never drawn at all despite the surface
+/// being genuinely mapped, configured, and holding real committed pixel
+/// data the entire time. Reported live as a real second monitor showing
+/// nothing but its own clear colour, confirmed root-caused by adding a
+/// temporary diagnostic (`LAYER-ELEMENTS-DIAG`, since removed) that logged
+/// `layer_count`/`has_buffer` per output - both outputs showed identical,
+/// fully-populated state the whole time, which is what pointed at a
+/// positioning bug downstream of element-gathering rather than anything
+/// about the surfaces or the render/flip pipeline itself (the pipeline
+/// itself was separately confirmed alive on this exact head by moving the
+/// real cursor there and seeing it render correctly, a different code path
+/// with no `layer_geometry` involved at all).
+pub(crate) fn output_layer_elements<R>(renderer: &mut R, output: &Output, include: impl Fn(Layer) -> bool) -> Vec<OverlayElement<R>>
 where
     R: Renderer + ImportAll + ImportMem,
     R::TextureId: Clone + Send + 'static,
@@ -211,8 +255,7 @@ where
             continue;
         }
         let Some(geo) = map.layer_geometry(layer) else { continue };
-        let location = (origin.0 + geo.loc.x, origin.1 + geo.loc.y);
-        elements.extend(surface_content_elements(renderer, layer.wl_surface(), location, 1.0));
+        elements.extend(surface_content_elements(renderer, layer.wl_surface(), (geo.loc.x, geo.loc.y), 1.0));
     }
     elements
 }
@@ -388,17 +431,43 @@ pub(crate) fn popup_surface_under(state: &CompState, pos: Point<f64, Logical>) -
 /// the caller: that case is now handled by a second, always-unconditional
 /// pass over the focused/hovered windows specifically, independent of
 /// whether this function's damage-gated pass runs at all this tick.
+///
+/// `origin` is the rendering head's own position in the shared global
+/// space - needed because `damage` comes straight from that head's own
+/// `OutputDamageTracker`, which (like every other per-head render element
+/// in `udev/render.rs`) operates entirely in that head's own *local*
+/// framebuffer space, starting at `(0, 0)` regardless of where the head
+/// actually sits in the multi-monitor desktop. `space.element_geometry`,
+/// by contrast, is always in *global* space (`Space` tracks every window
+/// across the whole desktop, not per-output). Comparing the two directly
+/// - what this function used to do - only ever produced a real overlap
+/// for a head whose own `origin` happened to be `(0, 0)`, i.e. the first/
+/// primary monitor in a left-to-right layout; every window on any other
+/// monitor could never be found "touched" by that monitor's own damage at
+/// all, no matter how much of it was actually changing on screen. A
+/// client relying on this path alone - a video window the user had
+/// switched focus *away* from, since the separate always-unconditional
+/// pass above only covers the focused/hovered window - never received
+/// another frame callback once srdwm's own bootstrap-configure frame
+/// callback was used up, and simply stopped rendering new frames forever:
+/// reported live as a paused-looking video on a second monitor, audio
+/// still playing underneath (a completely separate pipeline, unaffected).
+/// Same root cause and same fix shape as `output_layer_elements`'s own
+/// local/global mismatch, found earlier the same session.
 pub(crate) fn windows_touched_by_damage<'a>(
     space: &'a Space<DWindow>,
     damage: &'a [Rectangle<i32, Physical>],
+    origin: Point<i32, Logical>,
     scale: Scale<f64>,
 ) -> impl Iterator<Item = &'a DWindow> + 'a {
+    let origin_phys = origin.to_physical_precise_round(scale);
     space.elements().filter(move |w| {
         space
             .element_geometry(w)
             .map(|geo| {
                 let phys = geo.to_physical_precise_round(scale);
-                damage.iter().any(|d| d.overlaps(phys))
+                let local = Rectangle::new(phys.loc - origin_phys, phys.size);
+                damage.iter().any(|d| d.overlaps(local))
             })
             .unwrap_or(false)
     })
diff --git a/crates/wayland/src/input.rs b/crates/wayland/src/input.rs
index 5cce9a4..9d31872 100644
--- a/crates/wayland/src/input.rs
+++ b/crates/wayland/src/input.rs
@@ -9,153 +9,46 @@
 //! Every function that routes an event checks the session lock first: while
 //! locked, input goes to the lock surface and nowhere else. See
 //! [`crate::lock`].
+//!
+//! Split by concern, one file per input-event kind, matching niri's own
+//! per-grab-kind module boundaries: [`layers`] (layer-shell hit-testing and
+//! the layer-driven maximize geometry), [`focus`] (focusing/raising/closing
+//! a window - needed by every other kind below regardless of what
+//! triggered the change), [`pointer`] (motion, button, cursor shape),
+//! [`keyboard`] (key events and keysym/modifier translation), [`gestures`]
+//! (workspace scroll and touchpad swipe). `notify_idle_activity` and
+//! [`DRAG_MODIFIER`] stay here, at the root, since every one of those
+//! modules needs at least one of them.
+
+mod focus;
+mod gestures;
+mod keyboard;
+mod layers;
+mod pointer;
 
-use smithay::backend::input::{ButtonState as BackendButtonState, KeyState as BackendKeyState, KeyboardKeyEvent};
-use smithay::backend::session::Session as _;
-use smithay::desktop::{layer_map_for_output, Window as DWindow, WindowSurfaceType};
-use smithay::input::keyboard::FilterResult;
-use smithay::input::pointer::{ButtonEvent, MotionEvent};
-use smithay::output::Output;
-use smithay::reexports::wayland_server::protocol::wl_surface::WlSurface;
-use smithay::reexports::wayland_server::Resource as _;
-use smithay::utils::{Logical, Point, SERIAL_COUNTER};
-use smithay::wayland::compositor::with_states;
-use smithay::wayland::shell::wlr_layer::{Anchor, ExclusiveZone, KeyboardInteractivity, Layer, LayerSurfaceCachedState};
 use std::time::{Duration, Instant};
 
-use srdwm_core::{Event as CoreEvent, Modifiers, TitlebarHit, WindowId};
+use smithay::utils::{Logical, Point};
+
+use srdwm_core::Modifiers;
+
+use crate::state::CompState;
+
+pub(crate) use focus::{close_dwindow, dwindow_wl_surface, focus_window, raise_in_space, sync_keyboard_focus};
+pub(crate) use gestures::{handle_gesture_swipe_begin, handle_gesture_swipe_end, handle_gesture_swipe_update, handle_workspace_scroll};
+pub(crate) use keyboard::handle_keyboard_key_event;
+pub(crate) use layers::maximize_geometry_for;
+pub(crate) use pointer::{handle_pointer_button, handle_pointer_position};
 
 /// Modifier that turns a drag anywhere in a window into move/resize.
 /// Matches the `SUPER` the shipped and ported configs use for
 /// `bindm ... movewindow` / `resizewindow`.
-const DRAG_MODIFIER: Modifiers = Modifiers::SUPER;
-
-use crate::state::CompState;
+pub(super) const DRAG_MODIFIER: Modifiers = Modifiers::SUPER;
 
 pub(crate) fn last_pointer_pos(state: &CompState) -> Point<f64, Logical> {
     state.seat.get_pointer().map(|p| p.current_location()).unwrap_or_default()
 }
 
-/// Topmost layer-shell surface (if any) under `pos`, checked in the same
-/// above-everything-else stacking order `space_render_elements` renders
-/// `Overlay`/`Top` layers in (bars, launchers, notifications, lock UIs).
-/// `Background`/`Bottom` layers (wallpapers) deliberately aren't checked
-/// here: nothing in scope for the daily-driver gate needs pointer input
-/// routed to them, and space windows should stay clickable over a
-/// wallpaper.
-/// `pos` is in the global space; layer geometry is relative to its own
-/// output, so the pointer is translated into output-local coordinates
-/// before hit-testing and the result translated back out.
-/// Only checked for `Overlay`/`Top` before a window hit-test, and again for
-/// `Bottom`/`Background` after one comes up empty - see the two call
-/// sites in `handle_pointer_button`/`handle_pointer_position` for why it's
-/// split rather than one four-layer loop here. A `Bottom`/`Background`
-/// surface (a desktop-icons layer, a wallpaper daemon that wants clicks) is
-/// meant to sit *behind* normal windows, so a window covering that point
-/// should still get the click; `Overlay`/`Top` (an on-screen keyboard, a
-/// bar, a dock) are meant to sit in front of everything, windows included.
-///
-/// Was `Overlay`/`Top` only, full stop - a `Bottom`-layer surface was
-/// silently unclickable no matter what, since nothing else in
-/// `handle_pointer_button` ever checked layers at all. Not the cause of
-/// the live "clicking the dock does nothing" report (confirmed: that dock
-/// uses `Layer::Top`, which was already checked), but a real, separate gap
-/// found while chasing it - worth closing regardless of whether anything
-/// currently deployed sits at `Bottom`/`Background` yet.
-pub(crate) fn layer_surface_under_layers(state: &CompState, pos: Point<f64, Logical>, layers: [Layer; 2]) -> Option<(WlSurface, Point<i32, Logical>)> {
-    let entry = state.output_at(pos)?;
-    let origin = entry.location;
-    let local = pos - origin.to_f64();
-    let map = layer_map_for_output(&entry.output);
-    for layer_kind in layers {
-        // Not `map.layer_under(layer_kind, local)` - that hands back only
-        // the single topmost surface whose *bounding box* contains `local`,
-        // and if that one surface's own input region excludes the point
-        // (its `surface_under` below returns `None`), the old code gave up
-        // on this whole layer-kind rather than trying whatever real,
-        // clickable surface is stacked underneath it. A bbox-only pick is
-        // exactly wrong the moment two surfaces on the same layer-kind
-        // overlap - a transparent, mapped-but-mostly-empty surface (a
-        // backdrop-dismiss popup, concretely: `Overview`'s own bbox-wide
-        // fallback region was exactly this shape before it was fixed
-        // AGS-side) sitting in front of a real one in z-order would
-        // silently swallow every click and even every hover/motion event
-        // meant for the surface underneath, with no way to reach it at
-        // all. Walking every candidate on this layer-kind, topmost first
-        // (`.rev()`, matching `layer_under`'s own z-order convention), and
-        // falling through to the next when a candidate's real input region
-        // doesn't cover the point, is what `layer_under` alone can't do.
-        for layer in map.layers_on(layer_kind).rev() {
-            let Some(geo) = map.layer_geometry(layer) else { continue };
-            if !geo.to_f64().contains(local) {
-                continue;
-            }
-            // Temporary: verifying the `layer_surfaces_shown_once` fix
-            // (state/layers.rs) actually stops a reused `wl_surface`'s
-            // stale layer-shell entry from outliving its role destroy --
-            // live-reproduced this session as a full-monitor click-catcher
-            // popup whose hit-tested geometry came back wider than the
-            // real output after several open/close cycles. Remove once a
-            // restart confirms the geometry stays sane across repeated
-            // popup toggles.
-            let local_in_surface = local - geo.loc.to_f64();
-            // `None` here means "no region ever committed" - per-protocol
-            // that means the *whole* surface is input-sensitive, not that
-            // nothing is, so it is its own distinct, meaningful answer from
-            // `Some([])` (a region was committed and it is empty).
-            let region_dump = with_states(layer.wl_surface(), |states| {
-                states.cached_state.get::<smithay::wayland::compositor::SurfaceAttributes>().current().input_region.as_ref().map(|r| r.rects.clone())
-            });
-            log::info!(
-                "layer_hit_test: layer={:?} namespace={:?} surface={:?} geo={:?} local_in_surface={:?} input_region={:?}",
-                layer_kind,
-                layer.namespace(),
-                layer.wl_surface().id(),
-                geo,
-                local_in_surface,
-                region_dump
-            );
-            if let Some((surface, surface_loc)) = layer.surface_under(local - geo.loc.to_f64(), WindowSurfaceType::ALL) {
-                return Some((surface, origin + geo.loc + surface_loc));
-            }
-        }
-    }
-    None
-}
-
-pub(crate) fn layer_surface_under(state: &CompState, pos: Point<f64, Logical>) -> Option<(WlSurface, Point<i32, Logical>)> {
-    layer_surface_under_layers(state, pos, [Layer::Overlay, Layer::Top])
-}
-
-/// The `Bottom`/`Background` half of the same lookup - see
-/// `layer_surface_under_layers`'s doc comment for the ordering rationale.
-pub(crate) fn background_layer_surface_under(state: &CompState, pos: Point<f64, Logical>) -> Option<(WlSurface, Point<i32, Logical>)> {
-    layer_surface_under_layers(state, pos, [Layer::Bottom, Layer::Background])
-}
-
-/// `full` with only a top-anchored layer surface's exclusive zone (a menu
-/// bar) subtracted back out - see `Monitor::maximize_geometry`'s own doc
-/// comment for why maximize needs this third rect, distinct from both
-/// `geometry` (every zone subtracted) and `full_geometry` (none). Shared by
-/// both backends' `monitors()`, same as everything else in this module.
-/// Deliberately re-derived from the layer list rather than reusing
-/// `non_exclusive_zone()`: that smithay helper folds every anchor
-/// together, with no way to ask it to skip a bottom-anchored dock while
-/// still respecting a top-anchored bar.
-pub(crate) fn maximize_geometry_for(output: &Output, full: srdwm_core::Rect) -> srdwm_core::Rect {
-    let mut rect = full;
-    for layer in layer_map_for_output(output).layers() {
-        let data = with_states(layer.wl_surface(), |states| *states.cached_state.get::<LayerSurfaceCachedState>().current());
-        let ExclusiveZone::Exclusive(amount) = data.exclusive_zone else { continue };
-        if data.anchor.contains(Anchor::TOP) && !data.anchor.contains(Anchor::BOTTOM) {
-            let shrink = (amount as i32 + data.margin.top).max(0);
-            rect.y += shrink;
-            rect.height = rect.height.saturating_sub(shrink as u32);
-        }
-    }
-    rect
-}
-
 /// `ext_idle_notify_v1`'s whole job is answering "has the user touched an
 /// input device recently" - `IdleNotifierState` does the actual timer
 /// bookkeeping (see its own doc comment), this just has to be called from
@@ -176,7 +69,7 @@ pub(crate) fn maximize_geometry_for(output: &Output, full: srdwm_core::Rect) ->
 /// (see `docs/IMPLEMENTATION_STATUS.md`), just cheap enough here (in-memory
 /// bookkeeping, not synchronous I/O) that throttling rather than removing
 /// it outright is the right amount of caution.
-fn notify_idle_activity(state: &mut CompState) {
+pub(super) fn notify_idle_activity(state: &mut CompState) {
     const THROTTLE: Duration = Duration::from_millis(250);
     let now = Instant::now();
     if state.last_idle_notify.is_some_and(|last| now.duration_since(last) < THROTTLE) {
@@ -186,850 +79,3 @@ fn notify_idle_activity(state: &mut CompState) {
     let seat = state.seat.clone();
     state.idle_notifier_state.notify_activity(&seat);
 }
-
-/// Re-resolves and re-asserts real Wayland pointer focus at `pos` - i.e.
-/// re-runs the exact same layer-shell/decoration/content/background
-/// hit-testing `handle_pointer_position` always did, and calls
-/// `pointer.motion()` with whatever it finds, but *without* sending
-/// `wl_pointer.frame` (callers decide when their own batch of events is
-/// done) and without any of `handle_pointer_position`'s other side effects
-/// (cursor shape, focus-follows-mouse, drag/resize updates) - those only
-/// make sense on an actual motion event, not a button press.
-///
-/// Extracted so [`handle_pointer_button`] can call this immediately before
-/// delivering a click, rather than only ever trusting whatever the *last*
-/// real motion event happened to leave `PointerHandle`'s own focus at.
-/// Those can disagree: confirmed live via a temporary diagnostic (since
-/// removed) that `space.element_under(pos)` - srdwm's own, freshly
-/// computed on every click - and
-/// `PointerHandle::current_focus()` - Wayland's, last set by whichever
-/// motion event happened to run before this click - disagreed on a real
-/// user's real clicks, inconsistently, sometimes on the very same window.
-/// A click landing on stale/no Wayland focus reads exactly like "clicking
-/// doesn't work" or "the cursor isn't where clicking happens," even though
-/// srdwm's own idea of what's under the pointer was correct the whole
-/// time. Calling this right before every button event closes that gap
-/// regardless of why focus went stale, rather than chasing the exact
-/// staleness trigger (rapid clicks, a tap-to-click event with no
-/// intervening motion delta, etc.) one cause at a time.
-#[allow(clippy::type_complexity)]
-fn refresh_pointer_focus(
-    state: &mut CompState,
-    pos: Point<f64, Logical>,
-    time: u32,
-) -> (Option<(WindowId, TitlebarHit)>, bool, bool, Option<WindowId>, Option<(WlSurface, Point<f64, Logical>)>) {
-    // Checked before literally everything else, including layer-shell --
-    // see `elements::popup_surface_under`'s own doc comment for why: a
-    // popup (tooltip, dropdown, right-click menu) always renders on top of
-    // everything else, popups on their own parent's content and layer-shell
-    // bars/docks alike, and hit-testing has to match that same priority or
-    // a click/scroll over an open popup silently lands on whatever's
-    // underneath it instead.
-    let popup_hit = crate::elements::popup_surface_under(state, pos);
-    let layer_hit = layer_surface_under(state, pos);
-    // Broadened, not just layer-shell: both a layer surface and an open
-    // popup are transient client UI that should suppress WM-level
-    // decoration-cursor guessing and focus-follows-mouse the same way (see
-    // both call sites below) - hovering a dropdown menu must not refocus
-    // whatever window happens to sit underneath it.
-    let over_layer_surface = layer_hit.is_some() || popup_hit.is_some();
-    let hit = state.wm.borrow().hit_test(pos.x as i32, pos.y as i32);
-    let under = state
-        .space
-        .element_under(pos)
-        .filter(|(w, _)| dwindow_is_visible(state, w))
-        .map(|(w, loc)| (w.clone(), loc));
-    let over_content = under.is_some();
-    // Whichever core window the pointer is over right now, decoration or
-    // content - `None` while over a layer-shell surface or bare desktop.
-    // Only `handle_pointer_position` actually uses this (focus-follows-
-    // mouse), but it needs `under` before that's consumed by the match
-    // below, so it's computed here rather than recomputed by the caller.
-    let hovered_id = hit
-        .map(|(id, _)| id)
-        .or_else(|| under.as_ref().and_then(|(window, _)| dwindow_wl_surface(window)).and_then(|s| state.surface_to_id.get(&s).copied()));
-
-    let Some(pointer) = state.seat.get_pointer() else { return (hit, over_layer_surface, over_content, hovered_id, None) };
-    // Freshly resolved target from ordinary hit-testing - overridden below
-    // by `pointer_button_grab` when a button is held, per its own doc
-    // comment (the Wayland implicit-grab rule).
-    let resolved: Option<(WlSurface, Point<f64, Logical>)> = if let Some((surface, loc)) = popup_hit {
-        Some((surface, loc.to_f64()))
-    } else if let Some((surface, loc)) = layer_hit {
-        Some((surface, loc.to_f64()))
-    } else if hit.is_some() {
-        None // Over our own decoration - no client focus.
-    } else if let Some((window, loc)) = &under {
-        // `window.toplevel()` is only ever `Some` for a native xdg-shell
-        // surface - it's `None` for every XWayland window, and even for a
-        // plain xdg-shell one it's always the *root* surface regardless of
-        // which subsurface the pointer is actually over (video/GL overlays,
-        // some GTK/Electron popups). Either way that meant pointer focus
-        // landed on the wrong surface - or no surface at all, for X11
-        // clients - and the click coordinates were relative to the window
-        // root rather than whatever was actually under the cursor.
-        // `Window::surface_under` is smithay's own hit-test for this: it
-        // walks the real surface tree (subsurfaces and popups included) and
-        // unifies the xdg-shell/X11 cases the way `dwindow_wl_surface` does
-        // elsewhere in this module.
-        let win_relative = pos - loc.to_f64();
-        window.surface_under(win_relative, WindowSurfaceType::ALL).map(|(surface, offset)| (surface, (*loc + offset).to_f64()))
-    } else {
-        // Bare desktop, no window there either - last chance for a
-        // `Bottom`/`Background` layer surface (see
-        // `layer_surface_under_layers`'s doc comment) before giving up.
-        background_layer_surface_under(state, pos).map(|(surface, loc)| (surface, loc.to_f64()))
-    };
-    let delivery = state.pointer_button_grab.clone().or_else(|| resolved.clone());
-    if let Some((surface, origin)) = delivery {
-        let surface_loc = pos - origin;
-        pointer.motion(state, Some((surface, origin)), &MotionEvent { location: surface_loc, serial: SERIAL_COUNTER.next_serial(), time });
-    } else {
-        pointer.motion(state, None, &MotionEvent { location: pos, serial: SERIAL_COUNTER.next_serial(), time });
-    }
-    (hit, over_layer_surface, over_content, hovered_id, resolved)
-}
-
-pub(crate) fn handle_pointer_position(state: &mut CompState, pos: Point<f64, Logical>, time: u32) {
-    notify_idle_activity(state);
-    // Locked: pointer motion goes to the lock surface only. No hit-testing
-    // against windows/decorations, so no hover, no drag, no resize.
-    if state.lock.locked {
-        let surface = state.any_lock_surface().cloned();
-        if let Some(pointer) = state.seat.get_pointer() {
-            let focus = surface.map(|s| (s, Point::from((0, 0)).to_f64()));
-            pointer.motion(state, focus, &MotionEvent { location: pos, serial: SERIAL_COUNTER.next_serial(), time });
-            pointer.frame(state);
-        }
-        return;
-    }
-
-    let (hit, over_layer_surface, over_content, hovered_id, _) = refresh_pointer_focus(state, pos, time);
-    let Some(pointer) = state.seat.get_pointer() else { return };
-    // `PointerHandle::motion`/`button`/`axis` only queue the event with the
-    // active grab - nothing sends `wl_pointer.frame` on its own (confirmed
-    // reading smithay's `DefaultGrab`: its `motion`/`button` impls call
-    // straight through to the handle and never call `frame`). `frame` is
-    // what tells a client "the events since the last frame are one atomic
-    // update, process them now" - required by the protocol since
-    // `wl_pointer` version 5, and this compositor advertises v9. Without
-    // it, any client that correctly waits for `frame` before acting on
-    // motion/button state (most modern toolkits, confirmed live: neither
-    // Firefox nor wezterm registered a click or a drag-selection, in both
-    // cases with the cursor sitting squarely on the target) never actually
-    // processes what it was sent, even though every event up to this point
-    // was individually correct. This is likely the real root cause behind
-    // this whole session's "clicking/scrolling doesn't work" reports --
-    // every fix so far (subsurface routing, decoration geometry, app_id)
-    // was real and necessary, but none of them could have mattered if the
-    // client was never told to look at what it received.
-    pointer.frame(state);
-
-    update_cursor_shape(state, hit, over_layer_surface, over_content);
-
-    let mut wm = state.wm.borrow_mut();
-    let dragging_or_resizing = wm.is_dragging() || wm.is_resizing();
-    if wm.is_dragging() {
-        wm.update_drag(pos.x as i32, pos.y as i32);
-    } else if wm.is_resizing() {
-        wm.update_resize(pos.x as i32, pos.y as i32);
-    }
-    let focused = wm.focused_id();
-    // `general.focus_follows_mouse`: hovering a *different* window focuses
-    // it, no click needed - classic X11 sloppy focus. Gated on `hit`/
-    // `under` actually landing on a window (not a layer surface or bare
-    // desktop) and on not already being mid-drag/resize, where the pointer
-    // sweeps over unrelated windows constantly and none of that should
-    // steal focus from whatever's actually being dragged. `hovered_id !=
-    // focused` both skips redundant work on every one of the many motion
-    // events a stationary pointer over an already-focused window still
-    // generates, and is what makes `auto_raise` (below) only fire on an
-    // actual focus change rather than every motion tick too.
-    let focus_follow_target =
-        (wm.focus_follows_mouse && !dragging_or_resizing && !over_layer_surface).then_some(hovered_id).flatten().filter(|id| Some(*id) != focused);
-    if let Some(id) = focus_follow_target {
-        if wm.auto_raise {
-            // `raise_window` alone here, not `focus_window` - the actual
-            // core + real Wayland/X11 keyboard focus change happens once,
-            // below, through the same `focus_window` free function every
-            // click-driven focus change already goes through (sets real
-            // keyboard focus too, which `WindowManager::focus_window`
-            // alone does not).
-            wm.raise_window(id);
-        }
-    }
-    drop(wm);
-    if let Some(id) = focus_follow_target {
-        focus_window(state, id);
-    }
-    if dragging_or_resizing {
-        if let Some(id) = focused {
-            state.sync_geometry(id);
-        }
-    }
-}
-
-/// Sets the pointer to a resize-direction shape while hovering (or
-/// actively dragging) one of our own decoration's resize edges, and back
-/// to the default arrow when leaving our decoration for anything else.
-///
-/// Only ever touches `cursor_status` for our own decoration - never while
-/// `layer_hit`/client content has focus, since a client surface drives its
-/// own cursor via `wl_pointer.set_cursor` once it starts receiving
-/// `pointer.motion()`/`enter` (already sent above, by the time this runs),
-/// and stomping on that here would fight the client for control of its own
-/// cursor rather than just leaving it alone.
-///
-/// Without this, `cursor_status` was only ever set by client requests --
-/// nothing on the compositor's own side ever asked for a resize cursor at
-/// all, so hovering or dragging one of our own decoration's edges never
-/// looked any different from hovering plain content, regardless of what
-/// shapes `cursor.rs` can actually render.
-///
-/// `over_content` distinguishes "over a client surface that will drive its
-/// own cursor" from "over the bare desktop, where nothing ever will" --
-/// without it, dragging off one of our decoration's resize edges straight
-/// onto empty desktop left `cursor_status` stuck on that resize icon
-/// forever: there is no client there to ever call `set_cursor` and reset
-/// it, and this function's own early-return (for the "let the client drive
-/// it" case) doesn't distinguish an *absent* client from a slow one.
-fn update_cursor_shape(state: &mut CompState, hit: Option<(WindowId, TitlebarHit)>, over_layer_surface: bool, over_content: bool) {
-    use smithay::input::pointer::{CursorIcon, CursorImageStatus};
-
-    if over_layer_surface {
-        return;
-    }
-    let edge = match hit {
-        Some((_, TitlebarHit::Resize(edge))) => Some(edge),
-        _ => state.wm.borrow().resize_edge(),
-    };
-    let icon = match edge {
-        Some(edge) => resize_cursor_icon(edge),
-        // Hovering our own decoration but not an edge (the drag area, a
-        // button) and not actively resizing: back to the plain arrow.
-        None if hit.is_some() => CursorIcon::Default,
-        // Over a client's own content: leave `cursor_status` alone, per the
-        // doc comment above - the client drives it.
-        None if over_content => return,
-        // Bare desktop: nothing else will ever reset this, so we have to.
-        None => CursorIcon::Default,
-    };
-    state.cursor_status = CursorImageStatus::Named(icon);
-}
-
-fn resize_cursor_icon(edge: srdwm_core::ResizeEdge) -> smithay::input::pointer::CursorIcon {
-    use smithay::input::pointer::CursorIcon;
-    use srdwm_core::ResizeEdge;
-    match edge {
-        ResizeEdge::Left | ResizeEdge::Right => CursorIcon::EwResize,
-        ResizeEdge::Top | ResizeEdge::Bottom => CursorIcon::NsResize,
-        ResizeEdge::TopLeft | ResizeEdge::BottomRight => CursorIcon::NwseResize,
-        ResizeEdge::TopRight | ResizeEdge::BottomLeft => CursorIcon::NeswResize,
-    }
-}
-
-/// The underlying `wl_surface` for a mapped window, regardless of whether
-/// it's a native `xdg-shell` toplevel or an XWayland `X11Surface` --
-/// `desktop::Window` exposes these as two separate accessors with no
-/// shared one.
-pub(crate) fn dwindow_wl_surface(w: &DWindow) -> Option<WlSurface> {
-    if let Some(top) = w.toplevel() {
-        return Some(top.wl_surface().clone());
-    }
-    w.x11_surface().and_then(|x| x.wl_surface())
-}
-
-/// Whether `w` is actually visible right now - on the current workspace and
-/// not minimized - matching `WindowManager::visible_windows`'s own filter.
-///
-/// `state.space` (smithay's `Space`) is not workspace-aware: a window stays
-/// mapped in it, and so stays hit-testable by `Space::element_under`, from
-/// the moment it's created until it's explicitly minimized or destroyed --
-/// switching workspace never unmaps anything (see `minimize` in
-/// `udev::platform`, the only other place that calls `unmap_elem`, and the
-/// absence of any workspace-switch handler that touches `self.space` at
-/// all). Without this check, `element_under` freely returns a window sitting
-/// on a workspace that isn't even shown, and a click "through" empty desktop
-/// on the current workspace silently focuses/raises/moves motion onto that
-/// invisible window instead of whatever (if anything) is really there.
-fn dwindow_is_visible(state: &CompState, w: &DWindow) -> bool {
-    let Some(id) = dwindow_wl_surface(w).and_then(|s| state.surface_to_id.get(&s).copied()) else { return false };
-    let wm = state.wm.borrow();
-    wm.window(id).is_some_and(|win| !win.minimized && win.workspace == wm.current_workspace())
-}
-
-/// Requests a client close its window, whichever kind it is.
-pub(crate) fn close_dwindow(w: &DWindow) {
-    if let Some(top) = w.toplevel() {
-        top.send_close();
-    } else if let Some(x11) = w.x11_surface() {
-        let _ = x11.close();
-    }
-}
-
-/// Focuses `id` in our own `WindowManager` *and* gives its surface real
-/// Wayland/X11 keyboard focus - without this, a window can be raised and
-/// tiled correctly yet never receive a single keystroke.
-pub(crate) fn focus_window(state: &mut CompState, id: WindowId) {
-    state.wm.borrow_mut().focus_window(id);
-    // Raises the window in smithay's own `Space` too, not just core's
-    // `order` - `Space` keeps a completely independent stacking order of
-    // its own, which is what actually renders on top *and* what
-    // `space.element_under` hit-tests against; `WindowManager::order`
-    // (which `focus_window` above already updates) has no effect on
-    // either. Without this, any focus path that doesn't also happen to
-    // raise `Space` manually (Alt-Tab, a dock's IPC "focus" dispatch,
-    // scratchpad show, the Snap-Layouts flyout, ...) left a window
-    // genuinely focused - keyboard input, core's own idea of "topmost"
-    // both correct - while it kept rendering *underneath* whatever was
-    // already on top, and a click on the visible (stale-topmost) window
-    // silently reached that one instead. "Focus doesn't bring a window to
-    // the front" and "clicking through a window that's fully covering
-    // another" are the same root cause, not two bugs. Previously only the
-    // plain-content-click branch in `handle_pointer_button` did this,
-    // manually, immediately before calling this function - every other
-    // caller went through unraised. Cheap even when the window is already
-    // topmost (`raise_element` on an already-last element is a no-op
-    // reinsertion), so unconditional here rather than gated on whether
-    // focus is actually changing.
-    if let Some(w) = state.id_to_window.get(&id).cloned() {
-        state.space.raise_element(&w, true);
-        state.raise_pinned();
-    }
-    state.pending.borrow_mut().push(CoreEvent::WindowFocused(id));
-    let surface = state.id_to_window.get(&id).and_then(dwindow_wl_surface);
-    // Routed through `set_keyboard_focus` (rather than calling
-    // `KeyboardHandle::set_focus` directly) so clipboard/primary-selection
-    // focus follows window focus too - see that method's doc comment.
-    state.set_keyboard_focus(surface);
-}
-
-/// Re-syncs real Wayland/X11 keyboard focus to whatever `WindowManager`
-/// already considers focused, without changing what that is.
-///
-/// For callers where core's own focus already moved on its own --
-/// specifically `WindowManager::remove_window`'s fallback to
-/// `self.order.last()` when the just-closed window was the focused one --
-/// and only the Wayland/X11 side needs to catch up to it. Without this, the
-/// window core now considers focused (and renders as such) never actually
-/// receives a keystroke until it's clicked, since nothing told
-/// `set_keyboard_focus` focus had moved.
-///
-/// `focus_window` above is for the opposite direction: driving core's
-/// focus deliberately (a click, a keybinding) and syncing outward from
-/// that. This is "core already decided, catch the rest of the compositor
-/// up" - `wm.focus_window` must not be called again here, since the id
-/// core picked (or `None`, if nothing is left) is exactly what should win.
-pub(crate) fn sync_keyboard_focus(state: &mut CompState) {
-    let focused = state.wm.borrow().focused_id();
-    let surface = focused.and_then(|id| state.id_to_window.get(&id)).and_then(dwindow_wl_surface);
-    state.set_keyboard_focus(surface);
-}
-
-pub(crate) fn handle_pointer_button(state: &mut CompState, pos: Point<f64, Logical>, button: u32, pressed: bool, time: u32) {
-    notify_idle_activity(state);
-    const BTN_LEFT: u32 = 0x110;
-    const BTN_RIGHT: u32 = 0x111;
-    const BTN_MIDDLE: u32 = 0x112;
-    let serial = SERIAL_COUNTER.next_serial();
-
-    // Locked: forward the click to the lock surface (it may have a button or
-    // a text field) but never let it focus, raise, drag, or close a window.
-    if state.lock.locked {
-        if let Some(pointer) = state.seat.get_pointer() {
-            let button_state = if pressed { BackendButtonState::Pressed } else { BackendButtonState::Released };
-            pointer.button(state, &ButtonEvent { serial, time, button, state: button_state });
-            pointer.frame(state);
-        }
-        return;
-    }
-
-    // The context menu, if open, captures every press: a click inside
-    // resolves whichever row it landed on, a click anywhere else just
-    // dismisses it. Neither case falls through to the normal handling
-    // below - opening the menu and then clicking a window underneath it
-    // should not *also* focus/raise/drag that window on the same click,
-    // the same "one click, one action" rule every native window menu
-    // follows.
-    if pressed {
-        if let Some(menu) = state.context_menu.take() {
-            if let Some(row) = menu.row_at(pos.x as i32, pos.y as i32) {
-                let (_, action) = menu.items[row];
-                state.close_context_menu();
-                state.run_context_menu_action(menu.window, action);
-            } else {
-                state.close_context_menu();
-            }
-            return;
-        }
-        // Same "one click, one action" rule as the context menu above --
-        // a click inside the Snap-Layouts flyout applies that zone, a click
-        // anywhere else just dismisses it.
-        if let Some(flyout) = state.snap_flyout.take() {
-            if let Some(zone) = flyout.zone_at(pos.x as i32, pos.y as i32) {
-                state.close_snap_flyout();
-                state.run_snap_flyout_action(flyout.window, zone);
-            } else {
-                state.close_snap_flyout();
-            }
-            return;
-        }
-    }
-
-    // Modifier+drag: with the modifier held, dragging *anywhere* in a window
-    // moves it (left button) or resizes it from the nearest corner (right
-    // button) - the `bindm SUPER, mouse:272/273` gesture. Without this a
-    // window can only be moved by its titlebar, which is useless for
-    // windows that have none (fullscreen, CSD apps, layer surfaces).
-    //
-    // Checked before the titlebar hit-test so the modifier wins over the
-    // decoration: holding the modifier and grabbing the titlebar should
-    // still move, not press a titlebar button.
-    if pressed && (button == BTN_LEFT || button == BTN_RIGHT) {
-        let mods = state.seat.get_keyboard().map(|k| core_modifiers_from_xkb(&k.modifier_state()));
-        if mods.is_some_and(|m| m.contains(DRAG_MODIFIER)) {
-            let target = state.wm.borrow().window_at(pos.x as i32, pos.y as i32);
-            if let Some(id) = target {
-                focus_window(state, id);
-                let mut wm = state.wm.borrow_mut();
-                if button == BTN_LEFT {
-                    wm.start_drag(id, pos.x as i32, pos.y as i32);
-                } else {
-                    let edge = wm.nearest_corner(id, pos.x as i32, pos.y as i32);
-                    wm.start_resize(id, edge, pos.x as i32, pos.y as i32);
-                }
-                return;
-            }
-        }
-    }
-
-    if pressed && button == BTN_LEFT {
-        let layer_hit = layer_surface_under(state, pos);
-        if let Some((surface, _)) = &layer_hit {
-            // Look the surface up on whichever output actually holds it.
-            let on_demand = state
-                .outputs()
-                .find_map(|output| {
-                    layer_map_for_output(output)
-                        .layer_for_surface(surface, WindowSurfaceType::ALL)
-                        .map(|l| {
-                            l.can_receive_keyboard_focus()
-                                && l.cached_state().keyboard_interactivity != KeyboardInteractivity::Exclusive
-                        })
-                })
-                .unwrap_or(false);
-            // `Exclusive` layers (lock screens, exclusive launchers) already
-            // hold focus from `ensure_layer_initial_configure` and keep it
-            // regardless of where else is clicked; only `OnDemand` layers
-            // (e.g. a bar's search field) claim it on click.
-            if on_demand {
-                state.set_keyboard_focus(Some(surface.clone()));
-            }
-        }
-        let hit = if layer_hit.is_some() { None } else { state.wm.borrow().hit_test(pos.x as i32, pos.y as i32) };
-        if let Some((id, hit)) = hit {
-            focus_window(state, id);
-            match hit {
-                TitlebarHit::Drag => {
-                    // Double-click the titlebar to maximise, as every other
-                    // desktop does - one of the few window operations that
-                    // otherwise needs the keyboard or a precise button hit.
-                    if state.is_double_click(id, time) {
-                        state.wm.borrow_mut().toggle_maximize(id);
-                        state.sync_geometry(id);
-                        crate::foreign_toplevel::send_state(state, id);
-                    } else {
-                        state.wm.borrow_mut().start_drag(id, pos.x as i32, pos.y as i32)
-                    }
-                }
-                TitlebarHit::Close => {
-                    if let Some(w) = state.id_to_window.get(&id) {
-                        close_dwindow(w);
-                    }
-                }
-                TitlebarHit::Maximize => {
-                    state.wm.borrow_mut().toggle_maximize(id);
-                    state.sync_geometry(id);
-                    crate::foreign_toplevel::send_state(state, id);
-                }
-                TitlebarHit::Minimize => {
-                    state.wm.borrow_mut().minimize_window(id);
-                    crate::foreign_toplevel::send_state(state, id);
-                }
-                TitlebarHit::Resize(edge) => state.wm.borrow_mut().start_resize(id, edge, pos.x as i32, pos.y as i32),
-            }
-        } else if layer_hit.is_none() {
-            if let Some((window, _loc)) = state.space.element_under(pos).filter(|(w, _)| dwindow_is_visible(state, w)) {
-                let window = window.clone();
-                // `focus_window` itself raises both `Space` and pinned
-                // windows now - see its own doc comment. No longer done
-                // manually here first.
-                if let Some(&id) = dwindow_wl_surface(&window).and_then(|s| state.surface_to_id.get(&s)) {
-                    focus_window(state, id);
-                }
-            }
-        }
-    } else if pressed && (button == BTN_RIGHT || button == BTN_MIDDLE) {
-        // Right-click a titlebar: open the window menu (minimize/maximize/
-        // pin/close) - previously nothing at all, since the only
-        // right-button behaviour anywhere was the SUPER+right-drag resize
-        // gesture above, which needs the modifier held. Middle-click:
-        // lower the window instead, the convention several X11 WMs
-        // (twm, fvwm, IceWM) have always had. Both only fire on the
-        // titlebar's plain drag area - a resize edge or one of the three
-        // buttons keeps its own single meaning regardless of which button
-        // was pressed, so a right-click on the close button, say, doesn't
-        // do something else entirely.
-        let hit = state.wm.borrow().hit_test(pos.x as i32, pos.y as i32);
-        match (button, hit) {
-            (BTN_RIGHT, Some((id, TitlebarHit::Drag))) => state.open_context_menu(id, (pos.x as i32, pos.y as i32)),
-            (BTN_MIDDLE, Some((id, TitlebarHit::Drag))) => state.wm.borrow_mut().lower_window(id),
-            // Right-click the maximize button itself: the Snap-Layouts
-            // flyout (pick a half/quarter position for this window)
-            // instead of the window menu - a plain left-click there still
-            // just toggles maximize, unchanged.
-            (BTN_RIGHT, Some((id, TitlebarHit::Maximize))) => state.open_snap_flyout(id, (pos.x as i32, pos.y as i32)),
-            _ => {}
-        }
-    } else if !pressed {
-        let mut wm = state.wm.borrow_mut();
-        let was_dragging = wm.is_dragging();
-        let was_resizing = wm.is_resizing();
-        // `start_drag`/`start_resize` both focus the window they grab, and
-        // nothing else can change focus while a grab is active (the pointer
-        // is captured by the drag, not routed elsewhere) - so `focused_id`
-        // is reliably the window `end_drag`/`end_resize` are about to
-        // finish, without `WindowManager` needing to hand the id back
-        // itself.
-        let id = wm.focused_id();
-        if was_dragging {
-            wm.end_drag();
-        } else if was_resizing {
-            wm.end_resize();
-        }
-        drop(wm);
-        // `end_drag` can snap the geometry one more time (edge/top-of-
-        // screen snapping, `SmartPlacement::snap_zone`) *after* the last
-        // `update_drag` already moved the window - without this, that
-        // final snap only ever reached `Window.geometry`. The border and
-        // titlebar redraw fresh from live geometry every frame, so they'd
-        // jump to the snapped rect immediately, while the client's actual
-        // mapped surface (driven only by `sync_geometry`'s
-        // `space.map_element`/`xdg_toplevel.configure`) stayed wherever the
-        // drag physically stopped - decoration visibly detached from its
-        // own window's content. Click routing desynced the same way:
-        // `hit_test`/`window_at` read the now-snapped `Window.geometry`
-        // while `space.element_under` still read the stale pre-snap
-        // position, so clicks in the visually-snapped zone resolved
-        // against the wrong rect. The X11 backend already gets this right
-        // (`crates/x11/src/lib.rs`'s `ButtonRelease` handler); this was the
-        // one call site in the module doc'd as "shared by both backends"
-        // that never got the same fix.
-        if was_dragging || was_resizing {
-            if let Some(id) = id {
-                state.sync_geometry(id);
-            }
-        }
-    }
-
-    // Re-assert real Wayland pointer focus at `pos` immediately before the
-    // actual click - see `refresh_pointer_focus`'s own doc comment for why
-    // this can't just trust whatever the last motion event left focus at.
-    // A no-op from the client's perspective when focus was already correct
-    // (an idempotent motion event at the same surface-local coordinates it
-    // already has), so this costs nothing in the common case.
-    //
-    // Also where `pointer_button_grab` starts and ends - see its own doc
-    // comment. Only the 0->1 transition captures a new grab target (a
-    // second button going down mid-gesture keeps whatever the first press
-    // already locked in); only the ->0 transition releases it, and not
-    // before this press/release's own `pointer.button()` below still goes
-    // out under the (still-active) grab.
-    let (.., resolved) = refresh_pointer_focus(state, pos, time);
-    if pressed {
-        if state.pointer_buttons_held == 0 {
-            state.pointer_button_grab = resolved;
-        }
-        state.pointer_buttons_held += 1;
-    } else {
-        state.pointer_buttons_held = state.pointer_buttons_held.saturating_sub(1);
-    }
-    if let Some(pointer) = state.seat.get_pointer() {
-        let button_state = if pressed { BackendButtonState::Pressed } else { BackendButtonState::Released };
-        pointer.button(state, &ButtonEvent { serial, time, button, state: button_state });
-        // See the matching comment in `handle_pointer_position`: `button`
-        // alone never tells the client the event is ready to act on, only
-        // `frame` does.
-        pointer.frame(state);
-    }
-    if !pressed && state.pointer_buttons_held == 0 {
-        state.pointer_button_grab = None;
-    }
-}
-
-/// Shared between the winit (nested) and udev (bare-TTY) backends: both
-/// deliver keyboard events through smithay's generic `KeyboardKeyEvent`
-/// trait, so the precise-keybinding-matching logic (see the module docs)
-/// only needs to exist once.
-pub(crate) fn handle_keyboard_key_event<B: smithay::backend::input::InputBackend, E: KeyboardKeyEvent<B>>(state: &mut CompState, event: &E) {
-    notify_idle_activity(state);
-    let keycode = event.key_code();
-    let key_state = event.state();
-    let time = event.time_msec();
-    let serial = SERIAL_COUNTER.next_serial();
-    let Some(keyboard) = state.seat.get_keyboard() else { return };
-
-    // While the session is locked, every key goes to the lock surface and
-    // *nothing* is treated as a WM keybinding. Skipping this would leave the
-    // lock trivially bypassable - the config binds spawn commands
-    // (`Mod4+Return` opens a terminal), so honouring bindings here would let
-    // anyone at a locked screen run arbitrary programs.
-    if state.lock.locked {
-        // A native lock (`crate::native_lock`) has no external client
-        // surface to forward to at all - srdwm is its own locker, so
-        // every keystroke feeds the password buffer directly instead.
-        // Only on press: a character is typed on key-down, matching
-        // ordinary text input, and password/BackSpace/Return/Escape
-        // handling only make sense once per physical keystroke, not once
-        // per press *and* release.
-        if state.lock.native.is_some() {
-            if key_state == BackendKeyState::Pressed {
-                keyboard.input::<(), _>(state, keycode, key_state, serial, time, |data, mods, handle| {
-                    // `keysym_to_utf8` on the already-resolved keysym
-                    // (rather than the state-aware `xkb_state_key_get_
-                    // utf8` xkbcommon's own docs recommend) is a
-                    // deliberate simplification: correct for plain
-                    // ASCII/shifted-symbol passwords, which is the
-                    // overwhelming common case; the gap is dead-key/
-                    // compose sequences spanning more than one keypress,
-                    // which would just make that one character not match
-                    // rather than ever falsely succeed - a usability
-                    // rough edge, not a security one. Computed before
-                    // `keysym_name_for` below, which takes `handle` by
-                    // value.
-                    let utf8 = xkbcommon::xkb::keysym_to_utf8(handle.modified_sym());
-                    let name = keysym_name_for(handle).unwrap_or_default();
-                    data.native_lock_key(&name, &utf8, mods.caps_lock);
-                    FilterResult::Intercept(())
-                });
-            } else {
-                keyboard.input::<(), _>(state, keycode, key_state, serial, time, |_, _, _| FilterResult::Intercept(()));
-            }
-            return;
-        }
-        keyboard.input::<(), _>(state, keycode, key_state, serial, time, |_, _, _| FilterResult::Forward);
-        return;
-    }
-
-    let bound_keys = state.bound_keys.clone();
-    let matched: Option<(String, Modifiers)> =
-        keyboard.input(state, keycode, key_state, serial, time, move |data, mods, handle| {
-            let modifiers = core_modifiers_from_xkb(mods);
-            // `Ctrl+Alt+F1`..`F12` (xkb emits these as the `XF86Switch_VT_1`..
-            // `_12` keysyms, not a plain function-key + modifier combo) --
-            // handled here, by raw keysym *value* rather than name, since
-            // matching a name string wrong fails silently and looks
-            // identical to this never having been implemented at all (it
-            // wasn't, until now: reported live, the user had to leave the
-            // graphical session entirely and log in on a different TTY to
-            // get a shell back after srdwm went down, because nothing ever
-            // told the session to switch away). Values are contiguous
-            // (0x1008FE01..=0x1008FE0C, xkbcommon's `keysyms.rs`), so `raw -
-            // KEY_XF86SWITCH_VT_1 + 1` is the target VT. Udev/bare-TTY
-            // backend only - `data.udev` is `None` under the nested winit
-            // backend, where VT switching is meaningless, so this is a
-            // no-op there rather than an error, same as every other
-            // udev-only feature in this module.
-            const KEY_XF86SWITCH_VT_1: u32 = 0x1008_FE01;
-            const KEY_XF86SWITCH_VT_12: u32 = 0x1008_FE0C;
-            let raw = handle.modified_sym().raw();
-            if (KEY_XF86SWITCH_VT_1..=KEY_XF86SWITCH_VT_12).contains(&raw) {
-                if key_state == BackendKeyState::Pressed {
-                    if let Some(udev) = data.udev.as_mut() {
-                        let vt = (raw - KEY_XF86SWITCH_VT_1 + 1) as i32;
-                        if let Err(e) = udev.session.change_vt(vt) {
-                            log::warn!("udev: change_vt({vt}) failed: {e}");
-                        }
-                    }
-                }
-                return FilterResult::Intercept((String::new(), modifiers));
-            }
-            match keysym_name_for(handle) {
-                Some(name) if bound_keys.contains(&srdwm_core::key_combo_string(modifiers, &name)) => {
-                    FilterResult::Intercept((name, modifiers))
-                }
-                _ => FilterResult::Forward,
-            }
-        });
-
-    match key_state {
-        BackendKeyState::Pressed => {
-            // An empty `key_name` is the VT-switch case above, already
-            // fully handled inside the closure - it isn't a real
-            // keybinding and must not start a repeat timer or fire a
-            // `CoreEvent::KeyPress` (`Lua` config has nothing bound to `""`,
-            // so this would be harmless either way, but skipping it is both
-            // cheaper and clearer than relying on that).
-            if let Some((key_name, modifiers)) = matched {
-                if !key_name.is_empty() {
-                    state.begin_repeat(keycode, &key_name, modifiers);
-                    state.pending.borrow_mut().push(CoreEvent::KeyPress { key_name, modifiers });
-                }
-            }
-        }
-        // Any release ends a repeat of *that* key; releasing an unrelated
-        // key must not stop it.
-        BackendKeyState::Released => state.end_repeat(keycode),
-    }
-    // Unmatched keys were already forwarded to the focused client by
-    // `FilterResult::Forward` inside the closure above.
-}
-
-/// Translates the effective xkb keysym for this keypress into the same
-/// `"Return"`/`"a"`/`"F5"`-style name `srdwm_core::keysyms` uses, so a
-/// binding written once in Lua resolves identically on X11 and Wayland.
-pub(crate) fn keysym_name_for(handle: smithay::input::keyboard::KeysymHandle<'_>) -> Option<String> {
-    srdwm_core::keysyms::keysym_to_name(handle.modified_sym().raw())
-}
-
-pub(crate) fn core_modifiers_from_xkb(mods: &smithay::input::keyboard::ModifiersState) -> Modifiers {
-    let mut m = Modifiers::empty();
-    if mods.shift {
-        m |= Modifiers::SHIFT;
-    }
-    if mods.ctrl {
-        m |= Modifiers::CTRL;
-    }
-    if mods.alt {
-        m |= Modifiers::ALT;
-    }
-    if mods.logo {
-        m |= Modifiers::SUPER;
-    }
-    m
-}
-
-/// Modifier+scroll cycles workspaces, consuming the event.
-///
-/// Returns `true` if it handled the scroll, in which case the caller must
-/// *not* also forward it to the client. Generic over the input backend for
-/// the same reason the keyboard handler is: both backends deliver scroll
-/// through smithay's `PointerAxisEvent` trait.
-pub(crate) fn handle_workspace_scroll<B, E>(state: &mut CompState, event: &E) -> bool
-where
-    B: smithay::backend::input::InputBackend,
-    E: smithay::backend::input::PointerAxisEvent<B>,
-{
-    use smithay::backend::input::Axis;
-
-    notify_idle_activity(state);
-    if state.lock.locked {
-        return false;
-    }
-    let mods = state.seat.get_keyboard().map(|k| core_modifiers_from_xkb(&k.modifier_state()));
-    if !mods.is_some_and(|m| m.contains(DRAG_MODIFIER)) {
-        return false;
-    }
-    let Some(v) = event.amount(Axis::Vertical).filter(|v| *v != 0.0) else { return false };
-    // Scrolling down (positive) advances, matching `workspace, e+1`.
-    switch_workspace_relative(state, v > 0.0)
-}
-
-/// Switches to the next (`forward`) or previous workspace in id order,
-/// wrapping around, and fires the two follow-up broadcasts a plain
-/// `WindowManager::switch_workspace` call alone doesn't cover. The shared
-/// body behind every *relative* workspace switch - `SUPER`+scroll above,
-/// and a 3+-finger touchpad swipe (`handle_gesture_swipe_end` below) --
-/// pulled out here rather than duplicated a second time: both gaps below
-/// were found missing for the scroll gesture specifically during this same
-/// session, and nothing about either is scroll-only, so a second call site
-/// copy-pasting the same steps would have been one missed broadcast away
-/// from reintroducing the exact bug that was just fixed once already.
-/// Returns `false` (and does nothing) if there are no workspaces at all.
-fn switch_workspace_relative(state: &mut CompState, forward: bool) -> bool {
-    let mut wm = state.wm.borrow_mut();
-    let ids: Vec<_> = wm.workspaces().iter().map(|w| w.id).collect();
-    if ids.is_empty() {
-        return false;
-    }
-    let current = ids.iter().position(|&id| id == wm.current_workspace()).unwrap_or(0);
-    let next = if forward { (current + 1) % ids.len() } else { (current + ids.len() - 1) % ids.len() };
-    wm.switch_workspace(ids[next]);
-    drop(wm);
-    // Without this, the switch above is invisible: nothing shows or hides
-    // a single window for the new workspace until `main.rs`'s `sync()`
-    // runs, which only happens when a polled event sets `dirty` - see
-    // `srdwm_core::Event::WorkspaceChanged`'s doc comment. Found live-
-    // testing the unrelated `ext_workspace_v1` protocol's own `activate`
-    // request, which has the identical problem; the scroll gesture had the
-    // exact same bug already, just never one anyone traced back this far.
-    state.pending.borrow_mut().push(srdwm_core::Event::WorkspaceChanged);
-    // Same reasoning as `foreign_toplevel::send_state`'s call sites: without
-    // this, a dock's workspace pill only ever tracked switches driven
-    // through `ext_workspace_handle_v1.activate` itself, going stale the
-    // moment a gesture (or any other non-protocol trigger) changed the
-    // active workspace instead.
-    crate::workspace::broadcast_active_workspace(state);
-    true
-}
-
-/// A 3+-finger touchpad swipe just started - resets the running horizontal
-/// offset `handle_gesture_swipe_update` accumulates into, or leaves it
-/// `None` while the session is locked so a swipe over the lock screen does
-/// nothing (matching every other pointer/keyboard path's "locked: no normal
-/// handling" rule - see this module's own doc comment).
-pub(crate) fn handle_gesture_swipe_begin<B, E>(state: &mut CompState, event: &E)
-where
-    B: smithay::backend::input::InputBackend,
-    E: smithay::backend::input::GestureBeginEvent<B>,
-{
-    notify_idle_activity(state);
-    state.gesture_swipe = if state.lock.locked { None } else { Some((event.fingers(), 0.0)) };
-}
-
-/// Accumulates one update's worth of horizontal motion into the swipe
-/// started by `handle_gesture_swipe_begin` - `delta_x` is relative to the
-/// *previous* update, not a running total (see `gesture_swipe`'s own doc
-/// comment on `CompState`), so summing here is the only way to know the
-/// swipe's real total distance once it ends.
-pub(crate) fn handle_gesture_swipe_update<B, E>(state: &mut CompState, event: &E)
-where
-    B: smithay::backend::input::InputBackend,
-    E: smithay::backend::input::GestureSwipeUpdateEvent<B>,
-{
-    if let Some((_, total_dx)) = state.gesture_swipe.as_mut() {
-        *total_dx += event.delta_x();
-    }
-}
-
-/// A touchpad swipe just ended - switches workspace if it was a genuine
-/// 3+-finger swipe past `SWIPE_THRESHOLD` and wasn't cancelled (a libinput
-/// gesture is marked cancelled when it doesn't resolve to a clean single
-/// direction, e.g. the fingers moved back and forth). Below the threshold
-/// or below 3 fingers, this does nothing - the same "did you mean it"
-/// floor a mis-clicked drag gets elsewhere in this file, and 2-finger
-/// motion is already handled as ordinary scroll (`PointerAxis`) rather
-/// than reaching here at all on a correctly configured touchpad.
-///
-/// Deliberately claimed entirely by the compositor rather than forwarded to
-/// the focused client, unlike pinch/hold (forwarded as-is in
-/// `udev::session`): `wp_pointer_gestures` swipe is specifically the
-/// 3/4-finger overview-style gesture, and the handful of desktops that
-/// support it at all (GNOME, sway, Hyprland) all reserve it for workspace
-/// switching the same way - there is no real client-side consumer to lose
-/// by not forwarding it. Swipe left (negative `total_dx`) advances to the
-/// next workspace, right goes back, matching macOS's own convention for
-/// swiping between spaces.
-const SWIPE_THRESHOLD: f64 = 60.0;
-
-pub(crate) fn handle_gesture_swipe_end<B, E>(state: &mut CompState, event: &E)
-where
-    B: smithay::backend::input::InputBackend,
-    E: smithay::backend::input::GestureEndEvent<B>,
-{
-    let Some((fingers, total_dx)) = state.gesture_swipe.take() else { return };
-    if event.cancelled() || fingers < 3 || total_dx.abs() < SWIPE_THRESHOLD {
-        return;
-    }
-    switch_workspace_relative(state, total_dx < 0.0);
-}
diff --git a/crates/wayland/src/input/focus.rs b/crates/wayland/src/input/focus.rs
new file mode 100644
index 0000000..ade0759
--- /dev/null
+++ b/crates/wayland/src/input/focus.rs
@@ -0,0 +1,138 @@
+//! Focusing, raising, and closing a window - the small set of helpers
+//! every other input-handling module needs regardless of what triggered
+//! the focus change (a click, a keybinding, an IPC call, a closed window's
+//! fallback).
+
+use smithay::desktop::Window as DWindow;
+use smithay::reexports::wayland_server::protocol::wl_surface::WlSurface;
+
+use srdwm_core::{Event as CoreEvent, WindowId};
+
+use crate::state::CompState;
+
+/// The underlying `wl_surface` for a mapped window, regardless of whether
+/// it's a native `xdg-shell` toplevel or an XWayland `X11Surface` --
+/// `desktop::Window` exposes these as two separate accessors with no
+/// shared one.
+pub(crate) fn dwindow_wl_surface(w: &DWindow) -> Option<WlSurface> {
+    if let Some(top) = w.toplevel() {
+        return Some(top.wl_surface().clone());
+    }
+    w.x11_surface().and_then(|x| x.wl_surface())
+}
+
+/// Whether `w` is actually visible right now - on the current workspace and
+/// not minimized - matching `WindowManager::visible_windows`'s own filter.
+///
+/// `state.space` (smithay's `Space`) is not workspace-aware: a window stays
+/// mapped in it, and so stays hit-testable by `Space::element_under`, from
+/// the moment it's created until it's explicitly minimized or destroyed --
+/// switching workspace never unmaps anything (see `minimize` in
+/// `udev::platform`, the only other place that calls `unmap_elem`, and the
+/// absence of any workspace-switch handler that touches `self.space` at
+/// all). Without this check, `element_under` freely returns a window sitting
+/// on a workspace that isn't even shown, and a click "through" empty desktop
+/// on the current workspace silently focuses/raises/moves motion onto that
+/// invisible window instead of whatever (if anything) is really there.
+pub(super) fn dwindow_is_visible(state: &CompState, w: &DWindow) -> bool {
+    let Some(id) = dwindow_wl_surface(w).and_then(|s| state.surface_to_id.get(&s).copied()) else { return false };
+    let wm = state.wm.borrow();
+    wm.window(id).is_some_and(|win| !win.minimized && win.workspace == wm.current_workspace())
+}
+
+/// Requests a client close its window, whichever kind it is.
+pub(crate) fn close_dwindow(w: &DWindow) {
+    if let Some(top) = w.toplevel() {
+        top.send_close();
+    } else if let Some(x11) = w.x11_surface() {
+        let _ = x11.close();
+    }
+}
+
+/// Focuses `id` in our own `WindowManager` *and* gives its surface real
+/// Wayland/X11 keyboard focus - without this, a window can be raised and
+/// tiled correctly yet never receive a single keystroke.
+pub(crate) fn focus_window(state: &mut CompState, id: WindowId) {
+    state.wm.borrow_mut().focus_window(id);
+    // Raises the window in smithay's own `Space` too, not just core's
+    // `order` - `Space` keeps a completely independent stacking order of
+    // its own, which is what actually renders on top *and* what
+    // `space.element_under` hit-tests against; `WindowManager::order`
+    // (which `focus_window` above already updates) has no effect on
+    // either. Without this, any focus path that doesn't also happen to
+    // raise `Space` manually (Alt-Tab, a dock's IPC "focus" dispatch,
+    // scratchpad show, the Snap-Layouts flyout, ...) left a window
+    // genuinely focused - keyboard input, core's own idea of "topmost"
+    // both correct - while it kept rendering *underneath* whatever was
+    // already on top, and a click on the visible (stale-topmost) window
+    // silently reached that one instead. "Focus doesn't bring a window to
+    // the front" and "clicking through a window that's fully covering
+    // another" are the same root cause, not two bugs. Previously only the
+    // plain-content-click branch in `handle_pointer_button` did this,
+    // manually, immediately before calling this function - every other
+    // caller went through unraised. Cheap even when the window is already
+    // topmost (`raise_element` on an already-last element is a no-op
+    // reinsertion), so unconditional here rather than gated on whether
+    // focus is actually changing.
+    raise_in_space(state, id);
+    state.pending.borrow_mut().push(CoreEvent::WindowFocused(id));
+    let surface = state.id_to_window.get(&id).and_then(dwindow_wl_surface);
+    // Routed through `set_keyboard_focus` (rather than calling
+    // `KeyboardHandle::set_focus` directly) so clipboard/primary-selection
+    // focus follows window focus too - see that method's doc comment.
+    state.set_keyboard_focus(surface);
+}
+
+/// Raises `id` to the top of smithay's own `Space` stacking order (see
+/// `focus_window`'s doc comment for why `Space`'s own order, separate from
+/// core's, has to be kept in sync) without touching core's focus or
+/// workspace state at all.
+///
+/// Split out of `focus_window` specifically so the udev/winit backends'
+/// post-IPC-mutation re-sync (`crate::input::focus_window`'s doc comment
+/// on *that* call site explains why it exists at all: an IPC-only focus
+/// change needs `Space` to catch up too) can re-raise the already-focused
+/// window without going through `WindowManager::focus_window` a second
+/// time. That core method has its own side effect of switching to the
+/// target's workspace if it differs from the current one - correct for a
+/// real focus change, but wrong here: calling it on a window that is
+/// already focused (just re-raising it for `Space`'s benefit) compared the
+/// still-current, still-on-its-old-workspace window against whatever
+/// `current_workspace` had just been set to by the same IPC mutation this
+/// re-sync is reacting to, and silently switched it right back --
+/// confirmed live as `srd dispatch activate workspace <id>` (and, by
+/// extension, any AGS workspace-switcher click going through the same IPC
+/// path) visibly changing `current_workspace` for a moment and then
+/// reverting within milliseconds, every time, unless the same IPC call
+/// also happened to change which window was focused. Exactly the same bug
+/// `main.rs`'s `sync()` was already fixed for (see its own doc comment) --
+/// this is a second call site with the identical unconditional-`focus_
+/// window`-reassertion shape, never fixed at the same time.
+pub(crate) fn raise_in_space(state: &mut CompState, id: WindowId) {
+    if let Some(w) = state.id_to_window.get(&id).cloned() {
+        state.space.raise_element(&w, true);
+        state.raise_pinned();
+    }
+}
+
+/// Re-syncs real Wayland/X11 keyboard focus to whatever `WindowManager`
+/// already considers focused, without changing what that is.
+///
+/// For callers where core's own focus already moved on its own --
+/// specifically `WindowManager::remove_window`'s fallback to
+/// `self.order.last()` when the just-closed window was the focused one --
+/// and only the Wayland/X11 side needs to catch up to it. Without this, the
+/// window core now considers focused (and renders as such) never actually
+/// receives a keystroke until it's clicked, since nothing told
+/// `set_keyboard_focus` focus had moved.
+///
+/// `focus_window` above is for the opposite direction: driving core's
+/// focus deliberately (a click, a keybinding) and syncing outward from
+/// that. This is "core already decided, catch the rest of the compositor
+/// up" - `wm.focus_window` must not be called again here, since the id
+/// core picked (or `None`, if nothing is left) is exactly what should win.
+pub(crate) fn sync_keyboard_focus(state: &mut CompState) {
+    let focused = state.wm.borrow().focused_id();
+    let surface = focused.and_then(|id| state.id_to_window.get(&id)).and_then(dwindow_wl_surface);
+    state.set_keyboard_focus(surface);
+}
diff --git a/crates/wayland/src/input/gestures.rs b/crates/wayland/src/input/gestures.rs
new file mode 100644
index 0000000..f88c633
--- /dev/null
+++ b/crates/wayland/src/input/gestures.rs
@@ -0,0 +1,131 @@
+//! `SUPER`+scroll and touchpad-swipe workspace switching.
+
+use crate::state::CompState;
+
+use super::keyboard::core_modifiers_from_xkb;
+use super::{notify_idle_activity, DRAG_MODIFIER};
+
+/// Modifier+scroll cycles workspaces, consuming the event.
+///
+/// Returns `true` if it handled the scroll, in which case the caller must
+/// *not* also forward it to the client. Generic over the input backend for
+/// the same reason the keyboard handler is: both backends deliver scroll
+/// through smithay's `PointerAxisEvent` trait.
+pub(crate) fn handle_workspace_scroll<B, E>(state: &mut CompState, event: &E) -> bool
+where
+    B: smithay::backend::input::InputBackend,
+    E: smithay::backend::input::PointerAxisEvent<B>,
+{
+    use smithay::backend::input::Axis;
+
+    notify_idle_activity(state);
+    if state.lock.locked {
+        return false;
+    }
+    let mods = state.seat.get_keyboard().map(|k| core_modifiers_from_xkb(&k.modifier_state()));
+    if !mods.is_some_and(|m| m.contains(DRAG_MODIFIER)) {
+        return false;
+    }
+    let Some(v) = event.amount(Axis::Vertical).filter(|v| *v != 0.0) else { return false };
+    // Scrolling down (positive) advances, matching `workspace, e+1`.
+    switch_workspace_relative(state, v > 0.0)
+}
+
+/// Switches to the next (`forward`) or previous workspace in id order,
+/// wrapping around, and fires the two follow-up broadcasts a plain
+/// `WindowManager::switch_workspace` call alone doesn't cover. The shared
+/// body behind every *relative* workspace switch - `SUPER`+scroll above,
+/// and a 3+-finger touchpad swipe (`handle_gesture_swipe_end` below) --
+/// pulled out here rather than duplicated a second time: both gaps below
+/// were found missing for the scroll gesture specifically during this same
+/// session, and nothing about either is scroll-only, so a second call site
+/// copy-pasting the same steps would have been one missed broadcast away
+/// from reintroducing the exact bug that was just fixed once already.
+/// Returns `false` (and does nothing) if there are no workspaces at all.
+fn switch_workspace_relative(state: &mut CompState, forward: bool) -> bool {
+    let mut wm = state.wm.borrow_mut();
+    let ids: Vec<_> = wm.workspaces().iter().map(|w| w.id).collect();
+    if ids.is_empty() {
+        return false;
+    }
+    let current = ids.iter().position(|&id| id == wm.current_workspace()).unwrap_or(0);
+    let next = if forward { (current + 1) % ids.len() } else { (current + ids.len() - 1) % ids.len() };
+    wm.switch_workspace(ids[next]);
+    drop(wm);
+    // Without this, the switch above is invisible: nothing shows or hides
+    // a single window for the new workspace until `main.rs`'s `sync()`
+    // runs, which only happens when a polled event sets `dirty` - see
+    // `srdwm_core::Event::WorkspaceChanged`'s doc comment. Found live-
+    // testing the unrelated `ext_workspace_v1` protocol's own `activate`
+    // request, which has the identical problem; the scroll gesture had the
+    // exact same bug already, just never one anyone traced back this far.
+    state.pending.borrow_mut().push(srdwm_core::Event::WorkspaceChanged);
+    // Same reasoning as `foreign_toplevel::send_state`'s call sites: without
+    // this, a dock's workspace pill only ever tracked switches driven
+    // through `ext_workspace_handle_v1.activate` itself, going stale the
+    // moment a gesture (or any other non-protocol trigger) changed the
+    // active workspace instead.
+    crate::workspace::broadcast_active_workspace(state);
+    true
+}
+
+/// A 3+-finger touchpad swipe just started - resets the running horizontal
+/// offset `handle_gesture_swipe_update` accumulates into, or leaves it
+/// `None` while the session is locked so a swipe over the lock screen does
+/// nothing (matching every other pointer/keyboard path's "locked: no normal
+/// handling" rule - see this module's own doc comment).
+pub(crate) fn handle_gesture_swipe_begin<B, E>(state: &mut CompState, event: &E)
+where
+    B: smithay::backend::input::InputBackend,
+    E: smithay::backend::input::GestureBeginEvent<B>,
+{
+    notify_idle_activity(state);
+    state.gesture_swipe = if state.lock.locked { None } else { Some((event.fingers(), 0.0)) };
+}
+
+/// Accumulates one update's worth of horizontal motion into the swipe
+/// started by `handle_gesture_swipe_begin` - `delta_x` is relative to the
+/// *previous* update, not a running total (see `gesture_swipe`'s own doc
+/// comment on `CompState`), so summing here is the only way to know the
+/// swipe's real total distance once it ends.
+pub(crate) fn handle_gesture_swipe_update<B, E>(state: &mut CompState, event: &E)
+where
+    B: smithay::backend::input::InputBackend,
+    E: smithay::backend::input::GestureSwipeUpdateEvent<B>,
+{
+    if let Some((_, total_dx)) = state.gesture_swipe.as_mut() {
+        *total_dx += event.delta_x();
+    }
+}
+
+/// A touchpad swipe just ended - switches workspace if it was a genuine
+/// 3+-finger swipe past `SWIPE_THRESHOLD` and wasn't cancelled (a libinput
+/// gesture is marked cancelled when it doesn't resolve to a clean single
+/// direction, e.g. the fingers moved back and forth). Below the threshold
+/// or below 3 fingers, this does nothing - the same "did you mean it"
+/// floor a mis-clicked drag gets elsewhere in this file, and 2-finger
+/// motion is already handled as ordinary scroll (`PointerAxis`) rather
+/// than reaching here at all on a correctly configured touchpad.
+///
+/// Deliberately claimed entirely by the compositor rather than forwarded to
+/// the focused client, unlike pinch/hold (forwarded as-is in
+/// `udev::session`): `wp_pointer_gestures` swipe is specifically the
+/// 3/4-finger overview-style gesture, and the handful of desktops that
+/// support it at all (GNOME, sway, Hyprland) all reserve it for workspace
+/// switching the same way - there is no real client-side consumer to lose
+/// by not forwarding it. Swipe left (negative `total_dx`) advances to the
+/// next workspace, right goes back, matching macOS's own convention for
+/// swiping between spaces.
+const SWIPE_THRESHOLD: f64 = 60.0;
+
+pub(crate) fn handle_gesture_swipe_end<B, E>(state: &mut CompState, event: &E)
+where
+    B: smithay::backend::input::InputBackend,
+    E: smithay::backend::input::GestureEndEvent<B>,
+{
+    let Some((fingers, total_dx)) = state.gesture_swipe.take() else { return };
+    if event.cancelled() || fingers < 3 || total_dx.abs() < SWIPE_THRESHOLD {
+        return;
+    }
+    switch_workspace_relative(state, total_dx < 0.0);
+}
diff --git a/crates/wayland/src/input/keyboard.rs b/crates/wayland/src/input/keyboard.rs
new file mode 100644
index 0000000..ae367f4
--- /dev/null
+++ b/crates/wayland/src/input/keyboard.rs
@@ -0,0 +1,174 @@
+//! Keyboard key events: precise keybinding matching against
+//! `srdwm_core::keysyms`, VT switching, and the locked-session/native-lock
+//! password-entry path.
+
+use smithay::backend::input::{KeyState as BackendKeyState, KeyboardKeyEvent};
+use smithay::backend::session::Session as _;
+use smithay::input::keyboard::FilterResult;
+use smithay::utils::SERIAL_COUNTER;
+
+use srdwm_core::{Event as CoreEvent, Modifiers};
+
+use crate::state::CompState;
+
+/// Shared between the winit (nested) and udev (bare-TTY) backends: both
+/// deliver keyboard events through smithay's generic `KeyboardKeyEvent`
+/// trait, so the precise-keybinding-matching logic (see the module docs)
+/// only needs to exist once.
+pub(crate) fn handle_keyboard_key_event<B: smithay::backend::input::InputBackend, E: KeyboardKeyEvent<B>>(state: &mut CompState, event: &E) {
+    super::notify_idle_activity(state);
+    let keycode = event.key_code();
+    let key_state = event.state();
+    let time = event.time_msec();
+    let serial = SERIAL_COUNTER.next_serial();
+    let Some(keyboard) = state.seat.get_keyboard() else { return };
+
+    // While the session is locked, every key goes to the lock surface and
+    // *nothing* is treated as a WM keybinding. Skipping this would leave the
+    // lock trivially bypassable - the config binds spawn commands
+    // (`Mod4+Return` opens a terminal), so honouring bindings here would let
+    // anyone at a locked screen run arbitrary programs.
+    if state.lock.locked {
+        // A native lock (`crate::native_lock`) has no external client
+        // surface to forward to at all - srdwm is its own locker, so
+        // every keystroke feeds the password buffer directly instead.
+        // Only on press: a character is typed on key-down, matching
+        // ordinary text input, and password/BackSpace/Return/Escape
+        // handling only make sense once per physical keystroke, not once
+        // per press *and* release.
+        if state.lock.native.is_some() {
+            if key_state == BackendKeyState::Pressed {
+                keyboard.input::<(), _>(state, keycode, key_state, serial, time, |data, mods, handle| {
+                    // `keysym_to_utf8` on the already-resolved keysym
+                    // (rather than the state-aware `xkb_state_key_get_
+                    // utf8` xkbcommon's own docs recommend) is a
+                    // deliberate simplification: correct for plain
+                    // ASCII/shifted-symbol passwords, which is the
+                    // overwhelming common case; the gap is dead-key/
+                    // compose sequences spanning more than one keypress,
+                    // which would just make that one character not match
+                    // rather than ever falsely succeed - a usability
+                    // rough edge, not a security one. Computed before
+                    // `keysym_name_for` below, which takes `handle` by
+                    // value.
+                    let utf8 = xkbcommon::xkb::keysym_to_utf8(handle.modified_sym());
+                    let name = keysym_name_for(handle).unwrap_or_default();
+                    data.native_lock_key(&name, &utf8, mods.caps_lock);
+                    FilterResult::Intercept(())
+                });
+            } else {
+                keyboard.input::<(), _>(state, keycode, key_state, serial, time, |_, _, _| FilterResult::Intercept(()));
+            }
+            return;
+        }
+        keyboard.input::<(), _>(state, keycode, key_state, serial, time, |_, _, _| FilterResult::Forward);
+        return;
+    }
+
+    let bound_keys = state.bound_keys.clone();
+    let matched: Option<(String, Modifiers)> =
+        keyboard.input(state, keycode, key_state, serial, time, move |data, mods, handle| {
+            let modifiers = core_modifiers_from_xkb(mods);
+            // `Ctrl+Alt+F1`..`F12` (xkb emits these as the `XF86Switch_VT_1`..
+            // `_12` keysyms, not a plain function-key + modifier combo) --
+            // handled here, by raw keysym *value* rather than name, since
+            // matching a name string wrong fails silently and looks
+            // identical to this never having been implemented at all (it
+            // wasn't, until now: reported live, the user had to leave the
+            // graphical session entirely and log in on a different TTY to
+            // get a shell back after srdwm went down, because nothing ever
+            // told the session to switch away). Values are contiguous
+            // (0x1008FE01..=0x1008FE0C, xkbcommon's `keysyms.rs`), so `raw -
+            // KEY_XF86SWITCH_VT_1 + 1` is the target VT. Udev/bare-TTY
+            // backend only - `data.udev` is `None` under the nested winit
+            // backend, where VT switching is meaningless, so this is a
+            // no-op there rather than an error, same as every other
+            // udev-only feature in this module.
+            const KEY_XF86SWITCH_VT_1: u32 = 0x1008_FE01;
+            const KEY_XF86SWITCH_VT_12: u32 = 0x1008_FE0C;
+            let raw = handle.modified_sym().raw();
+            if (KEY_XF86SWITCH_VT_1..=KEY_XF86SWITCH_VT_12).contains(&raw) {
+                if key_state == BackendKeyState::Pressed {
+                    if let Some(udev) = data.udev.as_mut() {
+                        let vt = (raw - KEY_XF86SWITCH_VT_1 + 1) as i32;
+                        if let Err(e) = udev.session.change_vt(vt) {
+                            log::warn!("udev: change_vt({vt}) failed: {e}");
+                        }
+                    }
+                }
+                return FilterResult::Intercept((String::new(), modifiers));
+            }
+            match keysym_name_for(handle) {
+                Some(name) if bound_keys.contains(&srdwm_core::key_combo_string(modifiers, &name)) => {
+                    FilterResult::Intercept((name, modifiers))
+                }
+                _ => FilterResult::Forward,
+            }
+        });
+
+    match key_state {
+        BackendKeyState::Pressed => {
+            // An empty `key_name` is the VT-switch case above, already
+            // fully handled inside the closure - it isn't a real
+            // keybinding and must not start a repeat timer or fire a
+            // `CoreEvent::KeyPress` (`Lua` config has nothing bound to `""`,
+            // so this would be harmless either way, but skipping it is both
+            // cheaper and clearer than relying on that).
+            if let Some((key_name, modifiers)) = matched {
+                if !key_name.is_empty() {
+                    state.begin_repeat(keycode, &key_name, modifiers);
+                    state.pending.borrow_mut().push(CoreEvent::KeyPress { key_name, modifiers });
+                }
+            }
+        }
+        // Any release ends a repeat of *that* key; releasing an unrelated
+        // key must not stop it.
+        BackendKeyState::Released => state.end_repeat(keycode),
+    }
+    // Unmatched keys were already forwarded to the focused client by
+    // `FilterResult::Forward` inside the closure above.
+}
+
+/// Translates the effective xkb keysym for this keypress into the same
+/// `"Return"`/`"a"`/`"F5"`-style name `srdwm_core::keysyms` uses, so a
+/// binding written once in Lua resolves identically on X11 and Wayland.
+pub(crate) fn keysym_name_for(handle: smithay::input::keyboard::KeysymHandle<'_>) -> Option<String> {
+    // `raw_syms()` - the keycode's level-0 (unshifted) symbol for the
+    // *current* layout, not `modified_sym()` (what Shift actually turns it
+    // into). For a keybinding like `Super+Shift+2`, matching against
+    // `modified_sym()` looked up whatever Shift+2 really produces on the
+    // active layout - `@` on US, and something else again on most other
+    // layouts - which never equals the literal name `"2"` the Lua config
+    // binds against. Every `Super+Shift+<number>` binding
+    // (`keybindings.lua`'s `workspace.move_window`) silently never matched
+    // anything, indistinguishable from not being bound at all. Shift is
+    // still fully honored as a *modifier* - `core_modifiers_from_xkb`
+    // reads it independently of which symbol this function returns - this
+    // only changes which symbol *name* represents "the 2 key", the same
+    // physical-key-plus-modifier-flags model every other keybinding system
+    // (Hyprland, i3, sway) uses. The other caller of this function (the
+    // native lock's password entry) only ever compares the result against
+    // non-shift-sensitive names (`BackSpace`/`Return`/`Escape`), so this
+    // doesn't change that path's behavior at all - real character input
+    // there already goes through `keysym_to_utf8(handle.modified_sym())`
+    // separately, untouched by this.
+    let sym = handle.raw_syms().first().copied().unwrap_or_else(|| handle.modified_sym());
+    srdwm_core::keysyms::keysym_to_name(sym.raw())
+}
+
+pub(crate) fn core_modifiers_from_xkb(mods: &smithay::input::keyboard::ModifiersState) -> Modifiers {
+    let mut m = Modifiers::empty();
+    if mods.shift {
+        m |= Modifiers::SHIFT;
+    }
+    if mods.ctrl {
+        m |= Modifiers::CTRL;
+    }
+    if mods.alt {
+        m |= Modifiers::ALT;
+    }
+    if mods.logo {
+        m |= Modifiers::SUPER;
+    }
+    m
+}
diff --git a/crates/wayland/src/input/layers.rs b/crates/wayland/src/input/layers.rs
new file mode 100644
index 0000000..718d83f
--- /dev/null
+++ b/crates/wayland/src/input/layers.rs
@@ -0,0 +1,169 @@
+//! `zwlr_layer_shell_v1` pointer hit-testing (bars, docks, launchers) and
+//! the layer-driven maximize-geometry computation both backends' `monitors()`
+//! need.
+
+use smithay::desktop::{layer_map_for_output, WindowSurfaceType};
+use smithay::output::Output;
+use smithay::reexports::wayland_server::protocol::wl_surface::WlSurface;
+use smithay::reexports::wayland_server::Resource as _;
+use smithay::utils::{Logical, Point};
+use smithay::wayland::compositor::with_states;
+use smithay::wayland::shell::wlr_layer::{Anchor, ExclusiveZone, Layer, LayerSurfaceCachedState};
+
+use crate::state::CompState;
+
+/// Topmost layer-shell surface (if any) under `pos`, checked in the same
+/// above-everything-else stacking order `space_render_elements` renders
+/// `Overlay`/`Top` layers in (bars, launchers, notifications, lock UIs).
+/// `Background`/`Bottom` layers (wallpapers) deliberately aren't checked
+/// here: nothing in scope for the daily-driver gate needs pointer input
+/// routed to them, and space windows should stay clickable over a
+/// wallpaper.
+/// `pos` is in the global space; layer geometry is relative to its own
+/// output, so the pointer is translated into output-local coordinates
+/// before hit-testing and the result translated back out.
+/// Only checked for `Overlay`/`Top` before a window hit-test, and again for
+/// `Bottom`/`Background` after one comes up empty - see the two call
+/// sites in `handle_pointer_button`/`handle_pointer_position` for why it's
+/// split rather than one four-layer loop here. A `Bottom`/`Background`
+/// surface (a desktop-icons layer, a wallpaper daemon that wants clicks) is
+/// meant to sit *behind* normal windows, so a window covering that point
+/// should still get the click; `Overlay`/`Top` (an on-screen keyboard, a
+/// bar, a dock) are meant to sit in front of everything, windows included.
+///
+/// Was `Overlay`/`Top` only, full stop - a `Bottom`-layer surface was
+/// silently unclickable no matter what, since nothing else in
+/// `handle_pointer_button` ever checked layers at all. Not the cause of
+/// the live "clicking the dock does nothing" report (confirmed: that dock
+/// uses `Layer::Top`, which was already checked), but a real, separate gap
+/// found while chasing it - worth closing regardless of whether anything
+/// currently deployed sits at `Bottom`/`Background` yet.
+pub(super) fn layer_surface_under_layers(state: &CompState, pos: Point<f64, Logical>, layers: [Layer; 2]) -> Option<(WlSurface, Point<i32, Logical>)> {
+    let entry = state.output_at(pos)?;
+    let origin = entry.location;
+    let local = pos - origin.to_f64();
+    let map = layer_map_for_output(&entry.output);
+    for layer_kind in layers {
+        // Not `map.layer_under(layer_kind, local)` - that hands back only
+        // the single topmost surface whose *bounding box* contains `local`,
+        // and if that one surface's own input region excludes the point
+        // (its `surface_under` below returns `None`), the old code gave up
+        // on this whole layer-kind rather than trying whatever real,
+        // clickable surface is stacked underneath it. A bbox-only pick is
+        // exactly wrong the moment two surfaces on the same layer-kind
+        // overlap - a transparent, mapped-but-mostly-empty surface (a
+        // backdrop-dismiss popup, concretely: `Overview`'s own bbox-wide
+        // fallback region was exactly this shape before it was fixed
+        // AGS-side) sitting in front of a real one in z-order would
+        // silently swallow every click and even every hover/motion event
+        // meant for the surface underneath, with no way to reach it at
+        // all. Walking every candidate on this layer-kind, topmost first
+        // (`.rev()`, matching `layer_under`'s own z-order convention), and
+        // falling through to the next when a candidate's real input region
+        // doesn't cover the point, is what `layer_under` alone can't do.
+        for layer in map.layers_on(layer_kind).rev() {
+            let Some(geo) = map.layer_geometry(layer) else { continue };
+            if !geo.to_f64().contains(local) {
+                continue;
+            }
+            // Temporary: verifying the `layer_surfaces_shown_once` fix
+            // (state/layers.rs) actually stops a reused `wl_surface`'s
+            // stale layer-shell entry from outliving its role destroy --
+            // live-reproduced this session as a full-monitor click-catcher
+            // popup whose hit-tested geometry came back wider than the
+            // real output after several open/close cycles. Remove once a
+            // restart confirms the geometry stays sane across repeated
+            // popup toggles.
+            let local_in_surface = local - geo.loc.to_f64();
+            // `None` here means "no region ever committed" - per-protocol
+            // that means the *whole* surface is input-sensitive, not that
+            // nothing is, so it is its own distinct, meaningful answer from
+            // `Some([])` (a region was committed and it is empty).
+            let region_dump = with_states(layer.wl_surface(), |states| {
+                states.cached_state.get::<smithay::wayland::compositor::SurfaceAttributes>().current().input_region.as_ref().map(|r| r.rects.clone())
+            });
+            log::info!(
+                "layer_hit_test: layer={:?} namespace={:?} surface={:?} geo={:?} local_in_surface={:?} input_region={:?}",
+                layer_kind,
+                layer.namespace(),
+                layer.wl_surface().id(),
+                geo,
+                local_in_surface,
+                region_dump
+            );
+            if let Some((surface, surface_loc)) = layer.surface_under(local - geo.loc.to_f64(), WindowSurfaceType::ALL) {
+                return Some((surface, origin + geo.loc + surface_loc));
+            }
+        }
+    }
+    None
+}
+
+pub(super) fn layer_surface_under(state: &CompState, pos: Point<f64, Logical>) -> Option<(WlSurface, Point<i32, Logical>)> {
+    layer_surface_under_layers(state, pos, [Layer::Overlay, Layer::Top])
+}
+
+/// The `Bottom`/`Background` half of the same lookup - see
+/// `layer_surface_under_layers`'s doc comment for the ordering rationale.
+pub(super) fn background_layer_surface_under(state: &CompState, pos: Point<f64, Logical>) -> Option<(WlSurface, Point<i32, Logical>)> {
+    layer_surface_under_layers(state, pos, [Layer::Bottom, Layer::Background])
+}
+
+/// `full` with only a top-anchored layer surface's exclusive zone (a menu
+/// bar) subtracted back out - see `Monitor::maximize_geometry`'s own doc
+/// comment for why maximize needs this third rect, distinct from both
+/// `geometry` (every zone subtracted) and `full_geometry` (none). Shared by
+/// both backends' `monitors()`, same as everything else in this module.
+/// Deliberately re-derived from the layer list rather than reusing
+/// `non_exclusive_zone()`: that smithay helper folds every anchor
+/// together with no way to ask it to skip one edge - see below for which
+/// edges this now shrinks for and why.
+///
+/// Shrinks for a reservation on *any* edge (top, bottom, left, or right),
+/// not top only - reported live as a maximized window's own bottom edge
+/// and border ending up underneath a bottom-anchored dock, indistinguishable
+/// from the dock not rendering at all. An earlier version of this
+/// function shrank only for a top-anchored bar, on the reasoning that
+/// maximize should be able to "go past" a dock while fullscreen (which
+/// already ignores every zone, via `full_geometry`) covers the case that
+/// wants the screen entirely to itself - but no other edge actually
+/// benefits from that distinction the way a top menu bar does, and
+/// respecting every edge here is what every mainstream desktop's own
+/// maximize convention already does. Fullscreen is unaffected - it never
+/// called this function, and still doesn't.
+pub(crate) fn maximize_geometry_for(output: &Output, full: srdwm_core::Rect) -> srdwm_core::Rect {
+    let mut rect = full;
+    // `exclusive_zone`/`margin` are logical (a layer-shell client reports
+    // its own reservation the same way every other layer-shell geometry
+    // is expressed), while `full` is physical pixels - same unit
+    // mismatch `Platform::monitors()` needed fixing for, and the same
+    // fix: scale the logical amount into physical pixels before touching
+    // a physical rect with it. Left unconverted, a scaled output's
+    // maximize target shrank by the wrong number of physical rows/columns
+    // for its own bar/dock (too few at scale < 1.0, too many above 1.0).
+    let scale = output.current_scale().fractional_scale();
+    for layer in layer_map_for_output(output).layers() {
+        let data = with_states(layer.wl_surface(), |states| *states.cached_state.get::<LayerSurfaceCachedState>().current());
+        let ExclusiveZone::Exclusive(amount) = data.exclusive_zone else { continue };
+        let scaled = |margin: i32| ((amount as f64 + margin as f64) * scale).round().max(0.0) as i32;
+        if data.anchor.contains(Anchor::TOP) && !data.anchor.contains(Anchor::BOTTOM) {
+            let shrink = scaled(data.margin.top);
+            rect.y += shrink;
+            rect.height = rect.height.saturating_sub(shrink as u32);
+        }
+        if data.anchor.contains(Anchor::BOTTOM) && !data.anchor.contains(Anchor::TOP) {
+            let shrink = scaled(data.margin.bottom);
+            rect.height = rect.height.saturating_sub(shrink as u32);
+        }
+        if data.anchor.contains(Anchor::LEFT) && !data.anchor.contains(Anchor::RIGHT) {
+            let shrink = scaled(data.margin.left);
+            rect.x += shrink;
+            rect.width = rect.width.saturating_sub(shrink as u32);
+        }
+        if data.anchor.contains(Anchor::RIGHT) && !data.anchor.contains(Anchor::LEFT) {
+            let shrink = scaled(data.margin.right);
+            rect.width = rect.width.saturating_sub(shrink as u32);
+        }
+    }
+    rect
+}
diff --git a/crates/wayland/src/input/pointer.rs b/crates/wayland/src/input/pointer.rs
new file mode 100644
index 0000000..7b3bbce
--- /dev/null
+++ b/crates/wayland/src/input/pointer.rs
@@ -0,0 +1,683 @@
+//! Pointer motion, button presses, and cursor-shape resolution.
+
+use smithay::backend::input::ButtonState as BackendButtonState;
+use smithay::desktop::{layer_map_for_output, WindowSurfaceType};
+use smithay::input::pointer::{ButtonEvent, MotionEvent};
+use smithay::reexports::wayland_server::protocol::wl_surface::WlSurface;
+use smithay::utils::{Logical, Point, SERIAL_COUNTER};
+use smithay::wayland::shell::wlr_layer::KeyboardInteractivity;
+
+use srdwm_core::{TitlebarHit, WindowId};
+
+use crate::state::CompState;
+
+use super::focus::{close_dwindow, dwindow_is_visible, dwindow_wl_surface, focus_window};
+use super::keyboard::core_modifiers_from_xkb;
+use super::layers::{background_layer_surface_under, layer_surface_under};
+use super::{notify_idle_activity, DRAG_MODIFIER};
+
+/// `WindowManager::hit_test`, but substituting each window's currently
+/// *animated* rect (if it has one active in `state.window_anims`) for its
+/// final `geometry` - see `hit_test_with`'s own doc comment in
+/// `crates/core/src/manager/hittest.rs` for why plain `hit_test` alone gets
+/// this wrong during a maximize/fullscreen/snap toggle or a new window's
+/// open-slide. Every decoration hit-test call site in this module goes
+/// through this now instead of calling `hit_test` on the borrowed
+/// `WindowManager` directly.
+fn hit_test_animated(state: &CompState, x: i32, y: i32) -> Option<(WindowId, TitlebarHit)> {
+    state.wm.borrow().hit_test_with(x, y, |id, geometry| {
+        let animated = state.window_anims.get(&id).map(crate::state::WindowAnim::current_rect).unwrap_or(geometry);
+        // Also corrects for a client whose real committed size differs
+        // from what was requested (a terminal's cell-quantized size, most
+        // commonly) - see `effective_frame`'s own doc comment. Without
+        // this, the resize-margin/border hit-test zone stayed sized to the
+        // *requested* rect even after the border itself moved to match the
+        // real one, so the clickable edge and the visible edge disagreed
+        // again, just like the border and the desktop background used to.
+        state.effective_frame(id, animated)
+    })
+}
+
+/// Re-resolves and re-asserts real Wayland pointer focus at `pos` - i.e.
+/// re-runs the exact same layer-shell/decoration/content/background
+/// hit-testing `handle_pointer_position` always did, and calls
+/// `pointer.motion()` with whatever it finds, but *without* sending
+/// `wl_pointer.frame` (callers decide when their own batch of events is
+/// done) and without any of `handle_pointer_position`'s other side effects
+/// (cursor shape, focus-follows-mouse, drag/resize updates) - those only
+/// make sense on an actual motion event, not a button press.
+///
+/// Extracted so [`handle_pointer_button`] can call this immediately before
+/// delivering a click, rather than only ever trusting whatever the *last*
+/// real motion event happened to leave `PointerHandle`'s own focus at.
+/// Those can disagree: confirmed live via a temporary diagnostic (since
+/// removed) that `space.element_under(pos)` - srdwm's own, freshly
+/// computed on every click - and
+/// `PointerHandle::current_focus()` - Wayland's, last set by whichever
+/// motion event happened to run before this click - disagreed on a real
+/// user's real clicks, inconsistently, sometimes on the very same window.
+/// A click landing on stale/no Wayland focus reads exactly like "clicking
+/// doesn't work" or "the cursor isn't where clicking happens," even though
+/// srdwm's own idea of what's under the pointer was correct the whole
+/// time. Calling this right before every button event closes that gap
+/// regardless of why focus went stale, rather than chasing the exact
+/// staleness trigger (rapid clicks, a tap-to-click event with no
+/// intervening motion delta, etc.) one cause at a time.
+#[allow(clippy::type_complexity)]
+fn refresh_pointer_focus(
+    state: &mut CompState,
+    pos: Point<f64, Logical>,
+    time: u32,
+) -> (Option<(WindowId, TitlebarHit)>, bool, bool, Option<WindowId>, Option<(WlSurface, Point<f64, Logical>)>) {
+    // Checked before literally everything else, including layer-shell --
+    // see `elements::popup_surface_under`'s own doc comment for why: a
+    // popup (tooltip, dropdown, right-click menu) always renders on top of
+    // everything else, popups on their own parent's content and layer-shell
+    // bars/docks alike, and hit-testing has to match that same priority or
+    // a click/scroll over an open popup silently lands on whatever's
+    // underneath it instead.
+    let popup_hit = crate::elements::popup_surface_under(state, pos);
+    let layer_hit = layer_surface_under(state, pos);
+    // Broadened, not just layer-shell: both a layer surface and an open
+    // popup are transient client UI that should suppress WM-level
+    // decoration-cursor guessing and focus-follows-mouse the same way (see
+    // both call sites below) - hovering a dropdown menu must not refocus
+    // whatever window happens to sit underneath it.
+    let over_layer_surface = layer_hit.is_some() || popup_hit.is_some();
+    let hit = hit_test_animated(state, pos.x as i32, pos.y as i32);
+    let under = state
+        .space
+        .element_under(pos)
+        .filter(|(w, _)| dwindow_is_visible(state, w))
+        .map(|(w, loc)| (w.clone(), loc));
+    let over_content = under.is_some();
+    // Whichever core window the pointer is over right now, decoration or
+    // content - `None` while over a layer-shell surface or bare desktop.
+    // Only `handle_pointer_position` actually uses this (focus-follows-
+    // mouse), but it needs `under` before that's consumed by the match
+    // below, so it's computed here rather than recomputed by the caller.
+    let hovered_id = hit
+        .map(|(id, _)| id)
+        .or_else(|| under.as_ref().and_then(|(window, _)| dwindow_wl_surface(window)).and_then(|s| state.surface_to_id.get(&s).copied()));
+
+    let Some(pointer) = state.seat.get_pointer() else { return (hit, over_layer_surface, over_content, hovered_id, None) };
+    // Freshly resolved target from ordinary hit-testing - overridden below
+    // by `pointer_button_grab` when a button is held, per its own doc
+    // comment (the Wayland implicit-grab rule).
+    let resolved: Option<(WlSurface, Point<f64, Logical>)> = if let Some((surface, loc)) = popup_hit {
+        Some((surface, loc.to_f64()))
+    } else if let Some((surface, loc)) = layer_hit {
+        Some((surface, loc.to_f64()))
+    } else if hit.is_some() {
+        None // Over our own decoration - no client focus.
+    } else if let Some((window, loc)) = &under {
+        // `window.toplevel()` is only ever `Some` for a native xdg-shell
+        // surface - it's `None` for every XWayland window, and even for a
+        // plain xdg-shell one it's always the *root* surface regardless of
+        // which subsurface the pointer is actually over (video/GL overlays,
+        // some GTK/Electron popups). Either way that meant pointer focus
+        // landed on the wrong surface - or no surface at all, for X11
+        // clients - and the click coordinates were relative to the window
+        // root rather than whatever was actually under the cursor.
+        // `Window::surface_under` is smithay's own hit-test for this: it
+        // walks the real surface tree (subsurfaces and popups included) and
+        // unifies the xdg-shell/X11 cases the way `dwindow_wl_surface` does
+        // elsewhere in this module.
+        //
+        // `loc` (from `Space`) is the window's raw *buffer*-origin in screen
+        // space, NOT its visible top-left - see `sync_geometry`'s own doc
+        // comment (`state/geometry.rs`), which positions every window via
+        // `map_element(w, (geom.x - content_offset.x, ...))` *specifically*
+        // so that `pos - loc` alone already lands in the buffer-local
+        // coordinates `Window::surface_under` expects (confirmed against
+        // smithay 0.7.0's own source: the ordinary toplevel branch hands
+        // `point` straight through with a hardcoded `(0, 0)` offset, unlike
+        // its sibling popup branch a few lines above, which does add
+        // `self.geometry().loc` - so a toplevel's `point` has to already
+        // be buffer-local, and `map_element`'s own placement is what makes
+        // `pos - loc` be exactly that with no further adjustment needed).
+        //
+        // A previous version of this line added `content_offset` back a
+        // *second* time (`pos - loc + content_offset`), reasoning that
+        // `loc` was the visible position and needed shifting back to
+        // buffer-local - but `sync_geometry` had already done that
+        // shifting into `loc` itself, so this double-applied it: every
+        // click on a CSD window with a nonzero shadow margin (GTK4 clients
+        // - Firefox concretely, on its own titlebar/tab-strip buttons
+        // specifically, since that's real content on an undecorated
+        // window, not srdwm's own decoration) landed `content_offset`
+        // *past* whatever was actually clicked, in the opposite direction
+        // from the original (pre-any-fix) bug. Both versions were wrong in
+        // opposite directions; plain `pos - loc` is what `sync_geometry`'s
+        // own contract actually calls for.
+        let win_relative = pos - loc.to_f64();
+        window.surface_under(win_relative, WindowSurfaceType::ALL).map(|(surface, offset)| (surface, (*loc + offset).to_f64()))
+    } else {
+        // Bare desktop, no window there either - last chance for a
+        // `Bottom`/`Background` layer surface (see
+        // `layer_surface_under_layers`'s doc comment) before giving up.
+        background_layer_surface_under(state, pos).map(|(surface, loc)| (surface, loc.to_f64()))
+    };
+    // `pointer_button_grab`'s own lock is deliberately skipped whenever a
+    // real Wayland-level grab is active (`pointer.is_grabbed()`) - most
+    // concretely, a client-initiated `wl_data_device` drag-and-drop
+    // (`DnDGrab`, installed the moment a client calls `start_drag`, e.g. a
+    // browser tab being torn out into another window). smithay's own
+    // `DnDGrab::motion` ignores this call's `focus` argument for the
+    // client-facing side (it explicitly calls `handle.motion(data, None,
+    // event)`, since no client gets ordinary pointer focus mid-drag) but
+    // *does* feed the same `focus` straight into `update_focus`, which is
+    // what actually decides the current drop target as the cursor moves.
+    // Keeping the origin-surface lock active here as well meant that value
+    // stayed pinned to whichever window the drag *started* over for the
+    // entire gesture, so `update_focus` could never see a second window as
+    // the drop target no matter where the cursor actually went - reported
+    // live as not being able to drag a tab from one window onto another.
+    // The lock's own reason for existing (a GTK drag recognizer treating a
+    // mid-gesture `leave` as "abort", see this field's own doc comment)
+    // only applies to *ordinary* pointer motion, which is exactly the case
+    // `is_grabbed()` being false identifies - once a real grab has taken
+    // over, that grab's own implementation is already responsible for
+    // routing enter/leave correctly, and needs the true, freshly-resolved
+    // surface to do it, not a stale one.
+    let delivery = if pointer.is_grabbed() { resolved.clone() } else { state.pointer_button_grab.clone().or_else(|| resolved.clone()) };
+    if let Some((surface, origin)) = delivery {
+        // `MotionEvent.location` is documented on `smithay::input::pointer::
+        // MotionEvent` itself as "Location of the pointer in compositor
+        // space" - i.e. global, the same space `pos` is already in.
+        // `PointerHandle::motion`'s own `focus` parameter carries `origin`
+        // specifically so smithay can compute the surface-relative
+        // coordinate *itself* (`event.location - loc`, see `PointerInternal
+        // ::motion` in smithay's `input/pointer/mod.rs`) before handing it
+        // to the client and storing the *global* value in its own internal
+        // `self.location` (what `PointerHandle::current_location()` later
+        // returns). Subtracting `origin` here as well, before this call,
+        // fed the client `pos - origin - origin` - doubly-offset, and
+        // wrong in a way that grows with a window's distance from the
+        // screen origin - while also corrupting smithay's own idea of
+        // "where is the pointer" for anything else that reads
+        // `current_location()`. `pos` unmodified, letting smithay subtract
+        // `origin` exactly once, is what every other call site in this
+        // file (and this same function's own `None`/lock-surface branches)
+        // already does correctly.
+        pointer.motion(state, Some((surface, origin)), &MotionEvent { location: pos, serial: SERIAL_COUNTER.next_serial(), time });
+    } else {
+        pointer.motion(state, None, &MotionEvent { location: pos, serial: SERIAL_COUNTER.next_serial(), time });
+    }
+    (hit, over_layer_surface, over_content, hovered_id, resolved)
+}
+
+pub(crate) fn handle_pointer_position(state: &mut CompState, pos: Point<f64, Logical>, time: u32) {
+    notify_idle_activity(state);
+    // Locked: pointer motion goes to the lock surface only. No hit-testing
+    // against windows/decorations, so no hover, no drag, no resize.
+    if state.lock.locked {
+        let surface = state.any_lock_surface().cloned();
+        if let Some(pointer) = state.seat.get_pointer() {
+            let focus = surface.map(|s| (s, Point::from((0, 0)).to_f64()));
+            pointer.motion(state, focus, &MotionEvent { location: pos, serial: SERIAL_COUNTER.next_serial(), time });
+            pointer.frame(state);
+        }
+        return;
+    }
+
+    // Tells core which monitor the pointer is physically over right now --
+    // core has no pointer of its own to know this (see `pointer_monitor`'s
+    // own doc comment), and `add_window`'s target-monitor fallback needs
+    // it for the one case the *focused* window's monitor can't answer:
+    // nothing focused on whichever monitor the user is actually at when
+    // launching something new. `full_geometry`, not the bar-shrunk
+    // `geometry` - this is "which physical screen is this pixel on", not
+    // a work-area question. `None` if the pointer is somehow outside every
+    // known monitor (shouldn't happen given `UdevState::bounds()` already
+    // clamps to their union, but a real `None` here is honest rather than
+    // guessing).
+    {
+        let mut wm = state.wm.borrow_mut();
+        let current = wm.monitors().iter().find(|m| m.full_geometry.contains_point(pos.x as i32, pos.y as i32)).map(|m| m.id);
+        wm.set_pointer_monitor(current);
+    }
+    let (hit, over_layer_surface, over_content, hovered_id, _) = refresh_pointer_focus(state, pos, time);
+    // The only pointer-position telemetry this compositor exposes to
+    // anything outside itself - kept at `trace` (off by default, `RUST_LOG`
+    // enables it same as any other target here) rather than removed
+    // outright: a peer session building against this compositor over IPC
+    // pointed out that without *some* "where is the pointer right now" oracle,
+    // a synthetic-input tool has no way to tell whether it moved the pointer
+    // at all versus landed somewhere unexpected, short of corner-clamping (4
+    // fixed points) or hover feedback (binary, only over a reactive widget).
+    // Every earlier version of this line ran at `warn`, unconditionally on --
+    // see `docs/TODO.md`'s matching cleanup entry for why that was too loud
+    // for daily use, not for why the telemetry itself was ever the problem.
+    log::trace!("pointer motion pos={:?} hit={hit:?}", (pos.x, pos.y));
+    // Titlebar button hover highlighting (explicitly requested, see
+    // docs/TODO.md) - `Drag`/`Resize` aren't buttons, so only the three
+    // real ones count. Compared against the previous value rather than
+    // set unconditionally so an unchanged hover (the overwhelmingly common
+    // case: most motion events land on the same button, or on none at all)
+    // doesn't force a redraw every single pointer-motion event.
+    let new_hover = hit.and_then(|(id, h)| matches!(h, srdwm_core::TitlebarHit::Close | srdwm_core::TitlebarHit::Minimize | srdwm_core::TitlebarHit::Maximize).then_some((id, h)));
+    // Compared as just `(id, hit)`, ignoring the `Instant` already stored
+    // - the field itself carries a timestamp, but "is this the same hover
+    // as before" must not depend on it, or every motion event within the
+    // same button would read as a *new* hover and keep resetting the
+    // glyph-reveal animation's own start time back to zero.
+    let currently_hovering = state.hovered_titlebar_button.map(|(id, h, _)| (id, h));
+    if new_hover != currently_hovering {
+        let old = state.hovered_titlebar_button.take();
+        state.hovered_titlebar_button = new_hover.map(|(id, h)| (id, h, std::time::Instant::now()));
+        // Both windows need a fresh signature check: the newly-hovered one
+        // (to actually draw the highlight) and the previously-hovered one,
+        // if it's a *different* window, to clear its own highlight again.
+        if let Some((id, _, _)) = old {
+            state.redraw_decoration_buffer(id);
+        }
+        if let Some((id, _)) = new_hover {
+            state.redraw_decoration_buffer(id);
+        }
+    }
+    let Some(pointer) = state.seat.get_pointer() else { return };
+    // `PointerHandle::motion`/`button`/`axis` only queue the event with the
+    // active grab - nothing sends `wl_pointer.frame` on its own (confirmed
+    // reading smithay's `DefaultGrab`: its `motion`/`button` impls call
+    // straight through to the handle and never call `frame`). `frame` is
+    // what tells a client "the events since the last frame are one atomic
+    // update, process them now" - required by the protocol since
+    // `wl_pointer` version 5, and this compositor advertises v9. Without
+    // it, any client that correctly waits for `frame` before acting on
+    // motion/button state (most modern toolkits, confirmed live: neither
+    // Firefox nor wezterm registered a click or a drag-selection, in both
+    // cases with the cursor sitting squarely on the target) never actually
+    // processes what it was sent, even though every event up to this point
+    // was individually correct. This is likely the real root cause behind
+    // this whole session's "clicking/scrolling doesn't work" reports --
+    // every fix so far (subsurface routing, decoration geometry, app_id)
+    // was real and necessary, but none of them could have mattered if the
+    // client was never told to look at what it received.
+    pointer.frame(state);
+
+    update_cursor_shape(state, hit, over_layer_surface, over_content);
+
+    let mut wm = state.wm.borrow_mut();
+    let dragging_or_resizing = wm.is_dragging() || wm.is_resizing();
+    if wm.is_dragging() {
+        wm.update_drag(pos.x as i32, pos.y as i32);
+    } else if wm.is_resizing() {
+        wm.update_resize(pos.x as i32, pos.y as i32);
+    }
+    let focused = wm.focused_id();
+    // `general.focus_follows_mouse`: hovering a *different* window focuses
+    // it, no click needed - classic X11 sloppy focus. Gated on `hit`/
+    // `under` actually landing on a window (not a layer surface or bare
+    // desktop) and on not already being mid-drag/resize, where the pointer
+    // sweeps over unrelated windows constantly and none of that should
+    // steal focus from whatever's actually being dragged. `hovered_id !=
+    // focused` both skips redundant work on every one of the many motion
+    // events a stationary pointer over an already-focused window still
+    // generates, and is what makes `auto_raise` (below) only fire on an
+    // actual focus change rather than every motion tick too.
+    let focus_follow_target =
+        (wm.focus_follows_mouse && !dragging_or_resizing && !over_layer_surface).then_some(hovered_id).flatten().filter(|id| Some(*id) != focused);
+    if let Some(id) = focus_follow_target {
+        if wm.auto_raise {
+            // `raise_window` alone here, not `focus_window` - the actual
+            // core + real Wayland/X11 keyboard focus change happens once,
+            // below, through the same `focus_window` free function every
+            // click-driven focus change already goes through (sets real
+            // keyboard focus too, which `WindowManager::focus_window`
+            // alone does not).
+            wm.raise_window(id);
+        }
+    }
+    drop(wm);
+    if let Some(id) = focus_follow_target {
+        focus_window(state, id);
+    }
+    if dragging_or_resizing {
+        if let Some(id) = focused {
+            state.sync_geometry(id);
+        }
+    }
+}
+
+/// Sets the pointer to a resize-direction shape while hovering (or
+/// actively dragging) one of our own decoration's resize edges, and back
+/// to the default arrow when leaving our decoration for anything else.
+///
+/// Only ever *forces* `cursor_status` for our own decoration - never while
+/// `layer_hit`/client content has focus, since a client surface drives its
+/// own cursor via `wl_pointer.set_cursor` once it starts receiving
+/// `pointer.motion()`/`enter` (already sent above, by the time this runs),
+/// and stomping on that here would fight the client for control of its own
+/// cursor rather than just leaving it alone.
+///
+/// Without this, `cursor_status` was only ever set by client requests --
+/// nothing on the compositor's own side ever asked for a resize cursor at
+/// all, so hovering or dragging one of our own decoration's edges never
+/// looked any different from hovering plain content, regardless of what
+/// shapes `cursor.rs` can actually render.
+///
+/// `over_content` distinguishes "over a client surface that will drive its
+/// own cursor" from "over the bare desktop, where nothing ever will" --
+/// without it, dragging off one of our decoration's resize edges straight
+/// onto empty desktop left `cursor_status` stuck on that resize icon
+/// forever: there is no client there to ever call `set_cursor` and reset
+/// it, and this function's own early-return (for the "let the client drive
+/// it" case) doesn't distinguish an *absent* client from a slow one.
+///
+/// `state.decoration_cursor_active` is what makes the "leave it alone"
+/// branch below safe rather than sticky: reported live as "the resize icon
+/// stays on screen long after the pointer is nowhere near an edge." Moving
+/// from a decoration edge onto plain content sets no new `wl_pointer` focus
+/// (an undecorated/CSD window's edge and its content are the same surface,
+/// just different bands of it - see `hit_test`'s `UNDECORATED_TOP_RESIZE_
+/// MARGIN`), so the client never gets an `enter` event to react to, and most
+/// toolkits only re-call `set_cursor` when *their own* idea of which widget
+/// is hovered changes - which it hasn't, from their point of view, since
+/// they were never told the pointer was ever over a resize edge to begin
+/// with. The resize icon we forced while hovering that edge was therefore
+/// never going to be overwritten by anything, ever, without this: the very
+/// first content tick after leaving a decoration/resize hover resets to the
+/// plain arrow *once*, and only if we're the one who last set it - a
+/// client that has since claimed the cursor itself (tracked by `cursor_
+/// image` in `protocols.rs` clearing this same flag) is left alone on every
+/// following tick, so this can't fight a legitimate client cursor that
+/// isn't changing simply because the pointer kept moving.
+fn update_cursor_shape(state: &mut CompState, hit: Option<(WindowId, TitlebarHit)>, over_layer_surface: bool, over_content: bool) {
+    use smithay::input::pointer::{CursorIcon, CursorImageStatus};
+
+    if over_layer_surface {
+        return;
+    }
+    let edge = match hit {
+        Some((_, TitlebarHit::Resize(edge))) => Some(edge),
+        _ => state.wm.borrow().resize_edge(),
+    };
+    // A live "forcing the cursor here has no visible effect" report earlier
+    // this session turned out to be a real *design* gap, not a rendering
+    // bug: hovering a titlebar button used to fall into the same
+    // `CursorIcon::Default` branch as the plain drag area below it --
+    // indistinguishable from "not hovering anything special" (the desktop's
+    // own baseline cursor is also `Default`), so there was never any visible
+    // change to notice in the first place. `Pointer` (a real hand/finger
+    // cursor - see `cursor.rs`'s own `pointer_bitmap`) is what every
+    // mainstream desktop shows over a clickable titlebar button instead.
+    let icon = match edge {
+        Some(edge) => resize_cursor_icon(edge),
+        // A real button (Close/Maximize/Minimize), not the plain drag
+        // area - a hand cursor, matching every mainstream desktop's own
+        // convention for a clickable titlebar control.
+        None if matches!(hit, Some((_, TitlebarHit::Close | TitlebarHit::Maximize | TitlebarHit::Minimize))) => CursorIcon::Pointer,
+        // Hovering our own decoration but not an edge or a button (the
+        // drag area) and not actively resizing: back to the plain arrow.
+        None if hit.is_some() => CursorIcon::Default,
+        // Over a client's own content: leave `cursor_status` alone once the
+        // client has claimed it - but if we're still showing whatever we
+        // last forced (a resize icon from the edge just left), reset it
+        // back to the plain arrow this one time rather than leaving it
+        // stuck, since nothing else is ever going to.
+        None if over_content => {
+            if state.decoration_cursor_active {
+                state.cursor_status = CursorImageStatus::Named(CursorIcon::Default);
+                state.decoration_cursor_active = false;
+            }
+            return;
+        }
+        // Bare desktop: nothing else will ever reset this, so we have to.
+        None => CursorIcon::Default,
+    };
+    state.cursor_status = CursorImageStatus::Named(icon);
+    state.decoration_cursor_active = true;
+}
+
+fn resize_cursor_icon(edge: srdwm_core::ResizeEdge) -> smithay::input::pointer::CursorIcon {
+    use smithay::input::pointer::CursorIcon;
+    use srdwm_core::ResizeEdge;
+    match edge {
+        ResizeEdge::Left | ResizeEdge::Right => CursorIcon::EwResize,
+        ResizeEdge::Top | ResizeEdge::Bottom => CursorIcon::NsResize,
+        ResizeEdge::TopLeft | ResizeEdge::BottomRight => CursorIcon::NwseResize,
+        ResizeEdge::TopRight | ResizeEdge::BottomLeft => CursorIcon::NeswResize,
+    }
+}
+
+pub(crate) fn handle_pointer_button(state: &mut CompState, pos: Point<f64, Logical>, button: u32, pressed: bool, time: u32) {
+    notify_idle_activity(state);
+    const BTN_LEFT: u32 = 0x110;
+    const BTN_RIGHT: u32 = 0x111;
+    const BTN_MIDDLE: u32 = 0x112;
+    let serial = SERIAL_COUNTER.next_serial();
+
+    // Locked: forward the click to the lock surface (it may have a button or
+    // a text field) but never let it focus, raise, drag, or close a window.
+    if state.lock.locked {
+        if let Some(pointer) = state.seat.get_pointer() {
+            let button_state = if pressed { BackendButtonState::Pressed } else { BackendButtonState::Released };
+            pointer.button(state, &ButtonEvent { serial, time, button, state: button_state });
+            pointer.frame(state);
+        }
+        return;
+    }
+
+    // The context menu, if open, captures every press: a click inside
+    // resolves whichever row it landed on, a click anywhere else just
+    // dismisses it. Neither case falls through to the normal handling
+    // below - opening the menu and then clicking a window underneath it
+    // should not *also* focus/raise/drag that window on the same click,
+    // the same "one click, one action" rule every native window menu
+    // follows.
+    if pressed {
+        if let Some(menu) = state.context_menu.take() {
+            if let Some(row) = menu.row_at(pos.x as i32, pos.y as i32) {
+                let (_, action) = menu.items[row];
+                state.close_context_menu();
+                state.run_context_menu_action(menu.window, action);
+            } else {
+                state.close_context_menu();
+            }
+            return;
+        }
+        // Same "one click, one action" rule as the context menu above --
+        // a click inside the Snap-Layouts flyout applies that zone, a click
+        // anywhere else just dismisses it.
+        if let Some(flyout) = state.snap_flyout.take() {
+            if let Some(zone) = flyout.zone_at(pos.x as i32, pos.y as i32) {
+                state.close_snap_flyout();
+                state.run_snap_flyout_action(flyout.window, zone);
+            } else {
+                state.close_snap_flyout();
+            }
+            return;
+        }
+    }
+
+    // Modifier+drag: with the modifier held, dragging *anywhere* in a window
+    // moves it (left button) or resizes it from the nearest corner (right
+    // button) - the `bindm SUPER, mouse:272/273` gesture. Without this a
+    // window can only be moved by its titlebar, which is useless for
+    // windows that have none (fullscreen, CSD apps, layer surfaces).
+    //
+    // Checked before the titlebar hit-test so the modifier wins over the
+    // decoration: holding the modifier and grabbing the titlebar should
+    // still move, not press a titlebar button.
+    if pressed && (button == BTN_LEFT || button == BTN_RIGHT) {
+        let mods = state.seat.get_keyboard().map(|k| core_modifiers_from_xkb(&k.modifier_state()));
+        if mods.is_some_and(|m| m.contains(DRAG_MODIFIER)) {
+            let target = state.wm.borrow().window_at(pos.x as i32, pos.y as i32);
+            if let Some(id) = target {
+                focus_window(state, id);
+                let mut wm = state.wm.borrow_mut();
+                if button == BTN_LEFT {
+                    wm.start_drag(id, pos.x as i32, pos.y as i32);
+                } else {
+                    let edge = wm.nearest_corner(id, pos.x as i32, pos.y as i32);
+                    wm.start_resize(id, edge, pos.x as i32, pos.y as i32);
+                }
+                return;
+            }
+        }
+    }
+
+    if pressed && button == BTN_LEFT {
+        let layer_hit = layer_surface_under(state, pos);
+        if let Some((surface, _)) = &layer_hit {
+            // Look the surface up on whichever output actually holds it.
+            let on_demand = state
+                .outputs()
+                .find_map(|output| {
+                    layer_map_for_output(output)
+                        .layer_for_surface(surface, WindowSurfaceType::ALL)
+                        .map(|l| {
+                            l.can_receive_keyboard_focus()
+                                && l.cached_state().keyboard_interactivity != KeyboardInteractivity::Exclusive
+                        })
+                })
+                .unwrap_or(false);
+            // `Exclusive` layers (lock screens, exclusive launchers) already
+            // hold focus from `ensure_layer_initial_configure` and keep it
+            // regardless of where else is clicked; only `OnDemand` layers
+            // (e.g. a bar's search field) claim it on click.
+            if on_demand {
+                state.set_keyboard_focus(Some(surface.clone()));
+            }
+        }
+        let hit = if layer_hit.is_some() { None } else { hit_test_animated(state, pos.x as i32, pos.y as i32) };
+        if let Some((id, hit)) = hit {
+            focus_window(state, id);
+            match hit {
+                TitlebarHit::Drag => {
+                    // Double-click the titlebar to maximise, as every other
+                    // desktop does - one of the few window operations that
+                    // otherwise needs the keyboard or a precise button hit.
+                    if state.is_double_click(id, time) {
+                        state.wm.borrow_mut().toggle_maximize(id);
+                        state.sync_geometry(id);
+                        crate::foreign_toplevel::send_state(state, id);
+                    } else {
+                        state.wm.borrow_mut().start_drag(id, pos.x as i32, pos.y as i32)
+                    }
+                }
+                TitlebarHit::Close => {
+                    if let Some(w) = state.id_to_window.get(&id) {
+                        close_dwindow(w);
+                    }
+                }
+                TitlebarHit::Maximize => {
+                    state.wm.borrow_mut().toggle_maximize(id);
+                    state.sync_geometry(id);
+                    crate::foreign_toplevel::send_state(state, id);
+                }
+                TitlebarHit::Minimize => {
+                    state.wm.borrow_mut().minimize_window(id);
+                    crate::foreign_toplevel::send_state(state, id);
+                }
+                TitlebarHit::Resize(edge) => state.wm.borrow_mut().start_resize(id, edge, pos.x as i32, pos.y as i32),
+            }
+        } else if layer_hit.is_none() {
+            if let Some((window, _loc)) = state.space.element_under(pos).filter(|(w, _)| dwindow_is_visible(state, w)) {
+                let window = window.clone();
+                // `focus_window` itself raises both `Space` and pinned
+                // windows now - see its own doc comment. No longer done
+                // manually here first.
+                if let Some(&id) = dwindow_wl_surface(&window).and_then(|s| state.surface_to_id.get(&s)) {
+                    focus_window(state, id);
+                }
+            }
+        }
+    } else if pressed && (button == BTN_RIGHT || button == BTN_MIDDLE) {
+        // Right-click a titlebar: open the window menu (minimize/maximize/
+        // pin/close) - previously nothing at all, since the only
+        // right-button behaviour anywhere was the SUPER+right-drag resize
+        // gesture above, which needs the modifier held. Middle-click:
+        // lower the window instead, the convention several X11 WMs
+        // (twm, fvwm, IceWM) have always had. Both only fire on the
+        // titlebar's plain drag area - a resize edge or one of the three
+        // buttons keeps its own single meaning regardless of which button
+        // was pressed, so a right-click on the close button, say, doesn't
+        // do something else entirely.
+        let hit = hit_test_animated(state, pos.x as i32, pos.y as i32);
+        match (button, hit) {
+            (BTN_RIGHT, Some((id, TitlebarHit::Drag))) => state.open_context_menu(id, (pos.x as i32, pos.y as i32)),
+            (BTN_MIDDLE, Some((id, TitlebarHit::Drag))) => state.wm.borrow_mut().lower_window(id),
+            // Right-click the maximize button itself: the Snap-Layouts
+            // flyout (pick a half/quarter position for this window)
+            // instead of the window menu - a plain left-click there still
+            // just toggles maximize, unchanged.
+            (BTN_RIGHT, Some((id, TitlebarHit::Maximize))) => state.open_snap_flyout(id, (pos.x as i32, pos.y as i32)),
+            _ => {}
+        }
+    } else if !pressed {
+        let mut wm = state.wm.borrow_mut();
+        let was_dragging = wm.is_dragging();
+        let was_resizing = wm.is_resizing();
+        // `start_drag`/`start_resize` both focus the window they grab, and
+        // nothing else can change focus while a grab is active (the pointer
+        // is captured by the drag, not routed elsewhere) - so `focused_id`
+        // is reliably the window `end_drag`/`end_resize` are about to
+        // finish, without `WindowManager` needing to hand the id back
+        // itself.
+        let id = wm.focused_id();
+        if was_dragging {
+            wm.end_drag();
+        } else if was_resizing {
+            wm.end_resize();
+        }
+        drop(wm);
+        // `end_drag` can snap the geometry one more time (edge/top-of-
+        // screen snapping, `SmartPlacement::snap_zone`) *after* the last
+        // `update_drag` already moved the window - without this, that
+        // final snap only ever reached `Window.geometry`. The border and
+        // titlebar redraw fresh from live geometry every frame, so they'd
+        // jump to the snapped rect immediately, while the client's actual
+        // mapped surface (driven only by `sync_geometry`'s
+        // `space.map_element`/`xdg_toplevel.configure`) stayed wherever the
+        // drag physically stopped - decoration visibly detached from its
+        // own window's content. Click routing desynced the same way:
+        // `hit_test`/`window_at` read the now-snapped `Window.geometry`
+        // while `space.element_under` still read the stale pre-snap
+        // position, so clicks in the visually-snapped zone resolved
+        // against the wrong rect. The X11 backend already gets this right
+        // (`crates/x11/src/lib.rs`'s `ButtonRelease` handler); this was the
+        // one call site in the module doc'd as "shared by both backends"
+        // that never got the same fix.
+        if was_dragging || was_resizing {
+            if let Some(id) = id {
+                state.sync_geometry(id);
+            }
+        }
+    }
+
+    // Re-assert real Wayland pointer focus at `pos` immediately before the
+    // actual click - see `refresh_pointer_focus`'s own doc comment for why
+    // this can't just trust whatever the last motion event left focus at.
+    // A no-op from the client's perspective when focus was already correct
+    // (an idempotent motion event at the same surface-local coordinates it
+    // already has), so this costs nothing in the common case.
+    //
+    // Also where `pointer_button_grab` starts and ends - see its own doc
+    // comment. Only the 0->1 transition captures a new grab target (a
+    // second button going down mid-gesture keeps whatever the first press
+    // already locked in); only the ->0 transition releases it, and not
+    // before this press/release's own `pointer.button()` below still goes
+    // out under the (still-active) grab.
+    let (.., resolved) = refresh_pointer_focus(state, pos, time);
+    if pressed {
+        if state.pointer_buttons_held == 0 {
+            state.pointer_button_grab = resolved;
+        }
+        state.pointer_buttons_held += 1;
+    } else {
+        state.pointer_buttons_held = state.pointer_buttons_held.saturating_sub(1);
+    }
+    if let Some(pointer) = state.seat.get_pointer() {
+        let button_state = if pressed { BackendButtonState::Pressed } else { BackendButtonState::Released };
+        pointer.button(state, &ButtonEvent { serial, time, button, state: button_state });
+        // See the matching comment in `handle_pointer_position`: `button`
+        // alone never tells the client the event is ready to act on, only
+        // `frame` does.
+        pointer.frame(state);
+    }
+    if !pressed && state.pointer_buttons_held == 0 {
+        state.pointer_button_grab = None;
+    }
+}
diff --git a/crates/wayland/src/lib.rs b/crates/wayland/src/lib.rs
index 70e5c57..90660d1 100644
--- a/crates/wayland/src/lib.rs
+++ b/crates/wayland/src/lib.rs
@@ -33,11 +33,16 @@
 //!   client; everything else is forwarded, mirroring X11's grab-specific-keys
 //!   behavior instead of the coarser "any Super-held key is ours" heuristic
 //!   an earlier pass used.
-//! - xdg-decoration is forced to server-side mode (`Mode::ServerSide`) so
-//!   well-behaved clients don't also draw their own client-side titlebar.
+//! - xdg-decoration offers server-side mode by default (`theme.
+//!   default_decorated`/`srd set decoration_mode`), but a client that
+//!   explicitly requests client-side is honored rather than overridden --
+//!   see `XdgDecorationHandler::request_mode` in `protocols.rs` for why
+//!   forcing server-side unconditionally used to give some clients (Firefox,
+//!   concretely) two overlapping sets of window buttons.
 
 mod appmenu;
 mod blur;
+mod color_filter;
 mod context_menu;
 mod snap_flyout;
 mod cursor;
@@ -49,6 +54,7 @@ mod gtk_shell;
 mod gtk_shell_protocol;
 mod input;
 mod lock;
+mod monitor_layout;
 mod native_lock;
 mod output_management;
 mod output_power;
diff --git a/crates/wayland/src/monitor_layout.rs b/crates/wayland/src/monitor_layout.rs
new file mode 100644
index 0000000..775eb05
--- /dev/null
+++ b/crates/wayland/src/monitor_layout.rs
@@ -0,0 +1,153 @@
+//! Persists and restores monitor layout (position, enabled state) across
+//! restarts - srdwm's own responsibility, not any particular panel's.
+//!
+//! Before this, whatever arranged outputs on a restart was whichever panel
+//! happened to be running: it read back its own remembered layout from its
+//! own config store, seconds after srdwm itself had already brought every
+//! head up at some arbitrary default position, and dispatched `srd
+//! dispatch set output position` for each one to fix it up after the fact.
+//! That has three real problems, not just one: the user watches the wrong
+//! arrangement for however long the panel takes to start and apply it (one
+//! peer session measured 13.7s on its own, worse on a cold boot before the
+//! panel is even launched); the layout is never restored at all if that
+//! panel doesn't run or loses its own store; and this compositor is meant
+//! to work with any panel or none, not assume one particular shell exists
+//! to do this job.
+//!
+//! Applied once, at startup, before the Wayland socket is even bound (see
+//! `UdevPlatform::connect`'s call site) - no client, panel or otherwise,
+//! can possibly see a pre-restore arrangement, not even for one frame.
+//! Saved on every live position/enabled change (`apply_output_position`,
+//! `disable_connector_by_name`, `enable_connector_by_name`), so a panel's
+//! own output-management UI (or `srd dispatch set output ...` run by hand)
+//! keeps working exactly as before and this file just stays the one place
+//! that remembers the result.
+
+use std::collections::HashMap;
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq)]
+pub(crate) struct PersistedOutput {
+    /// Physical pixels - this compositor's own convention throughout, the
+    /// same space `srd monitors`/`apply_output_position` already use.
+    pub(crate) x: i32,
+    pub(crate) y: i32,
+    pub(crate) enabled: bool,
+}
+
+#[derive(Serialize, Deserialize, Default)]
+struct PersistedLayout {
+    /// Keyed by connector name (`eDP-1`, `HDMI-A-1`, ...) - the same
+    /// identifier every other per-monitor config in this codebase
+    /// (`srd.monitor.scale`, `srd dispatch set output ...`) already keys
+    /// off, and the one thing guaranteed stable across a reboot that a
+    /// kernel-assigned head index or CRTC handle is not.
+    outputs: HashMap<String, PersistedOutput>,
+}
+
+/// `$XDG_STATE_HOME/srd`, else `~/.local/state/srd` - state, not config:
+/// this file records what the compositor *did*, not something the user
+/// hand-edits, the same distinction XDG draws between the two directories.
+/// Mirrors `srdwm/src/main.rs`'s own `config_dir()` shape (`$SRDWM_*`
+/// override first, then the XDG var, then the hardcoded fallback) without
+/// sharing code with it - this is `srdwm-wayland`, that's the `srdwm`
+/// binary crate, and duplicating four lines beats a cross-crate dependency
+/// for it.
+fn state_dir() -> PathBuf {
+    if let Ok(p) = std::env::var("SRDWM_STATE_PATH") {
+        return PathBuf::from(p);
+    }
+    if let Ok(xdg) = std::env::var("XDG_STATE_HOME") {
+        return PathBuf::from(xdg).join("srd");
+    }
+    if let Ok(home) = std::env::var("HOME") {
+        return PathBuf::from(home).join(".local/state/srd");
+    }
+    PathBuf::from("state/srd")
+}
+
+fn layout_path() -> PathBuf {
+    state_dir().join("monitor-layout.json")
+}
+
+/// Every remembered output, by connector name. Empty (not an error) if the
+/// file doesn't exist yet - the ordinary case on a machine's first run,
+/// or the first run after this feature shipped - or if it's present but
+/// unreadable/corrupt, since a bad state file should degrade to "use the
+/// default layout", not stop the compositor from starting at all.
+pub(crate) fn load() -> HashMap<String, PersistedOutput> {
+    let path = layout_path();
+    let Ok(bytes) = std::fs::read(&path) else { return HashMap::new() };
+    match serde_json::from_slice::<PersistedLayout>(&bytes) {
+        Ok(layout) => layout.outputs,
+        Err(e) => {
+            log::warn!("monitor_layout: couldn't parse {path:?} ({e}); starting with the default layout instead");
+            HashMap::new()
+        }
+    }
+}
+
+/// Overwrites one connector's remembered position/enabled state and
+/// rewrites the whole file. Read-modify-write, not an in-memory cache kept
+/// across calls - position/enabled changes are rare (a user rearranging
+/// monitors, not a per-frame event), so re-reading the small file each
+/// time costs nothing and needs no separate cache-invalidation story.
+pub(crate) fn save_output(name: &str, entry: PersistedOutput) {
+    let mut layout = PersistedLayout { outputs: load() };
+    layout.outputs.insert(name.to_string(), entry);
+    let dir = state_dir();
+    if let Err(e) = std::fs::create_dir_all(&dir) {
+        log::warn!("monitor_layout: couldn't create {dir:?} ({e}); this layout change won't survive a restart");
+        return;
+    }
+    let Ok(bytes) = serde_json::to_vec_pretty(&layout) else { return };
+    let path = layout_path();
+    // Written to a `.tmp` sibling and renamed into place - same reasoning
+    // as `udev/capture.rs`'s `write_ppm`: a crash or a second srdwm
+    // instance racing this write must never leave a half-written, corrupt
+    // file behind for the next startup's `load()` to choke on.
+    let tmp = path.with_extension("json.tmp");
+    if let Err(e) = std::fs::write(&tmp, &bytes) {
+        log::warn!("monitor_layout: couldn't write {tmp:?} ({e}); this layout change won't survive a restart");
+        return;
+    }
+    if let Err(e) = std::fs::rename(&tmp, &path) {
+        log::warn!("monitor_layout: couldn't rename {tmp:?} to {path:?} ({e}); this layout change won't survive a restart");
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Only the pure JSON round-trip is exercised here - `state_dir()`/
+    // `load()`/`save_output()` all touch real environment variables and
+    // the filesystem, which parallel `cargo test` execution can't safely
+    // share (a per-test `SRDWM_STATE_PATH` override would race every other
+    // test in this binary reading the same process-global env var), the
+    // same reasoning `config_dir()` in `srdwm/src/main.rs` already has no
+    // test coverage for.
+    #[test]
+    fn a_persisted_layout_survives_a_json_round_trip() {
+        let mut outputs = HashMap::new();
+        outputs.insert("eDP-1".to_string(), PersistedOutput { x: 0, y: 0, enabled: true });
+        outputs.insert("HDMI-A-1".to_string(), PersistedOutput { x: -1920, y: 0, enabled: false });
+        let layout = PersistedLayout { outputs };
+        let bytes = serde_json::to_vec(&layout).unwrap();
+        let parsed: PersistedLayout = serde_json::from_slice(&bytes).unwrap();
+        assert_eq!(parsed.outputs.get("eDP-1"), Some(&PersistedOutput { x: 0, y: 0, enabled: true }));
+        assert_eq!(parsed.outputs.get("HDMI-A-1"), Some(&PersistedOutput { x: -1920, y: 0, enabled: false }));
+    }
+
+    #[test]
+    fn corrupt_json_falls_back_to_an_empty_layout_not_an_error() {
+        let result = serde_json::from_slice::<PersistedLayout>(b"not valid json");
+        assert!(result.is_err(), "sanity: this fixture must actually fail to parse");
+        // `load()` itself can't be called here (touches the real
+        // filesystem/env) - this locks in the *shape* of the fallback
+        // `load()` relies on: a parse error, not a panic, is what lets it
+        // degrade to `HashMap::new()` instead of taking the compositor down.
+    }
+}
diff --git a/crates/wayland/src/native_lock.rs b/crates/wayland/src/native_lock.rs
index ef59ba6..31c4fc3 100644
--- a/crates/wayland/src/native_lock.rs
+++ b/crates/wayland/src/native_lock.rs
@@ -357,7 +357,7 @@ where
 /// `blit_glyph`/`rgb_to_bgra`), promoted to `pub(crate)` there rather than
 /// duplicated here.
 fn render_ui_box(native: &NativeLock, theme: &srdwm_core::LockConfig) -> (Vec<u8>, (i32, i32)) {
-    use crate::decoration::{blit_glyph, find_system_font, rgb_to_bgra, FONT_PIXELS, TEXT_LEFT_PADDING};
+    use crate::decoration::{blit_glyph, find_system_font, rgb_to_bgra, round_bottom_corners, round_top_corners, FONT_PIXELS, TEXT_LEFT_PADDING};
 
     const WIDTH: usize = 360;
     const HEIGHT: usize = 170;
@@ -408,18 +408,34 @@ fn render_ui_box(native: &NativeLock, theme: &srdwm_core::LockConfig) -> (Vec<u8
 
     // Border, drawn last so it isn't overdrawn by any fill above --
     // same convention `render_context_menu`/`render_snap_flyout` use.
+    // 2px, matching `ThemeConfig::default_border_width` - a 1px line at
+    // this box's size read as a thin, easy-to-miss hairline rather than a
+    // deliberate frame around the box.
+    const BORDER: usize = 2;
     let border_px = rgb_to_bgra(theme.box_border, 255);
-    for x in 0..WIDTH {
-        buf[x * 4..x * 4 + 4].copy_from_slice(&border_px);
-        let last_row = (HEIGHT - 1) * WIDTH + x;
-        buf[last_row * 4..last_row * 4 + 4].copy_from_slice(&border_px);
-    }
-    for y in 0..HEIGHT {
-        let left = y * WIDTH;
-        buf[left * 4..left * 4 + 4].copy_from_slice(&border_px);
-        let right = y * WIDTH + WIDTH - 1;
-        buf[right * 4..right * 4 + 4].copy_from_slice(&border_px);
+    for t in 0..BORDER {
+        for x in 0..WIDTH {
+            buf[(t * WIDTH + x) * 4..(t * WIDTH + x) * 4 + 4].copy_from_slice(&border_px);
+            let row = (HEIGHT - 1 - t) * WIDTH + x;
+            buf[row * 4..row * 4 + 4].copy_from_slice(&border_px);
+        }
+        for y in 0..HEIGHT {
+            let left = y * WIDTH + t;
+            buf[left * 4..left * 4 + 4].copy_from_slice(&border_px);
+            let right = y * WIDTH + WIDTH - 1 - t;
+            buf[right * 4..right * 4 + 4].copy_from_slice(&border_px);
+        }
     }
 
+    // Rounded, like every other srdwm-drawn surface (titlebar, window
+    // border) - `LockConfig::corner_radius` existed as a config field
+    // (default 10) already, but nothing here ever actually read it, so the
+    // lock box always rendered as a hard flat rectangle regardless of its
+    // value. Clipping after the border fill above means the corner pixels
+    // of that border get cut along with the background, the same "cut,
+    // don't stroke" treatment `render_titlebar`'s own corners get.
+    round_top_corners(&mut buf, WIDTH, HEIGHT, theme.corner_radius, theme.corner_radius as i32);
+    round_bottom_corners(&mut buf, WIDTH, HEIGHT, theme.corner_radius);
+
     (buf, (WIDTH as i32, HEIGHT as i32))
 }
diff --git a/crates/wayland/src/output_management.rs b/crates/wayland/src/output_management.rs
index 05040b9..2e2ae85 100644
--- a/crates/wayland/src/output_management.rs
+++ b/crates/wayland/src/output_management.rs
@@ -309,7 +309,14 @@ fn apply_or_test(state: &mut CompState, config: &ZwlrOutputConfigurationV1, data
                 output.change_current_state(None, None, Some(Scale::Fractional(*s)), None);
             }
             if let Some((x, y)) = position {
-                apply_output_position(state, &output, Point::from((*x, *y)));
+                // A real `wlr-output-management-v1` client's own position
+                // request is logical, by protocol convention - `apply_
+                // output_position` wants physical (see its own doc
+                // comment), so it gets converted here rather than assumed.
+                let output_scale = output.current_scale().fractional_scale();
+                let physical: Point<i32, smithay::utils::Logical> =
+                    (((*x as f64) * output_scale).round() as i32, ((*y as f64) * output_scale).round() as i32).into();
+                apply_output_position(state, &output, physical);
             }
         }
     }
@@ -327,16 +334,48 @@ fn apply_or_test(state: &mut CompState, config: &ZwlrOutputConfigurationV1, data
 /// (used to translate render geometry into head-local space) each keep
 /// their own copy for reasons documented on their own fields, and would
 /// otherwise silently drift from what `Output` now reports.
-pub(crate) fn apply_output_position(state: &mut CompState, output: &Output, new_location: Point<i32, smithay::utils::Logical>) {
-    output.change_current_state(None, None, None, Some(new_location));
+///
+/// `new_location` is *physical* pixels - the same space `Platform::
+/// monitors()` reports `full_x`/`full_y` in (see that function's own doc
+/// comment for why), which is what `entry.location`/`head.location` are
+/// everywhere else in this compositor (render geometry, damage tracking,
+/// cursor clamping). `output.change_current_state`'s own position
+/// parameter is a real Wayland-protocol value, and `wl_output`/
+/// `xdg_output` report position to clients in *logical* points - always,
+/// not a choice this compositor makes - so it gets a separately scaled
+/// copy here rather than the raw physical value. Storing the unconverted
+/// physical value in `change_current_state` too (what this used to do)
+/// looked harmless locally but told every real Wayland client the wrong
+/// logical position for any output whose scale isn't exactly `1.0`,
+/// reported from the AGS peer session as a dead gap between two monitors'
+/// desktop space wide enough to drop a window or a pointer into: their
+/// own arrangement math chains outputs by the physical width `srd
+/// monitors` reports, correctly, but a `1.25`-scale output being told a
+/// `1920`-logical-point position when its real logical width was `1536`
+/// opened exactly that gap.
+///
+/// Callers already holding a *logical* position (a real `wlr-output-
+/// management-v1` client's own request, which is logical by protocol
+/// convention) must convert to physical before calling this - see this
+/// function's own call site in `handle_apply_or_test` for that
+/// conversion.
+pub(crate) fn apply_output_position(state: &mut CompState, output: &Output, new_location_physical: Point<i32, smithay::utils::Logical>) {
+    let scale = output.current_scale().fractional_scale();
+    let logical: Point<i32, smithay::utils::Logical> =
+        ((new_location_physical.x as f64 / scale).round() as i32, (new_location_physical.y as f64 / scale).round() as i32).into();
+    output.change_current_state(None, None, None, Some(logical));
     if let Some(entry) = state.outputs.iter_mut().find(|e| &e.output == output) {
-        entry.location = new_location;
+        entry.location = new_location_physical;
     }
     if let Some(udev) = state.udev.as_mut() {
         if let Some(head) = udev.heads.iter_mut().find(|h| &h.output == output) {
-            head.location = new_location;
+            head.location = new_location_physical;
         }
     }
+    // Remembered for next startup - see `monitor_layout`'s own module doc
+    // comment for why this compositor persists its own layout rather than
+    // leaving that to whichever panel happens to be running.
+    crate::monitor_layout::save_output(&output.name(), crate::monitor_layout::PersistedOutput { x: new_location_physical.x, y: new_location_physical.y, enabled: true });
 }
 
 fn announce_head(state: &mut CompState, manager: &ZwlrOutputManagerV1, output: &Output, client: &Client, dh: &DisplayHandle) {
diff --git a/crates/wayland/src/protocols.rs b/crates/wayland/src/protocols.rs
index 391f665..664e889 100644
--- a/crates/wayland/src/protocols.rs
+++ b/crates/wayland/src/protocols.rs
@@ -6,806 +6,34 @@
 //! hold no logic of their own beyond what the protocol itself dictates. The
 //! session-lock handler is the one exception, living in [`crate::lock`]
 //! alongside the rest of that feature.
+//!
+//! Split one file per protocol handler, matching niri's own convention (see
+//! docs/TODO.md's "module splits" entry) - [`buffer`] groups `ShmHandler`/
+//! `BufferHandler`/`DmabufHandler` together since none has more than a
+//! handful of lines, and [`misc`] groups the three purely-default-impl stub
+//! handlers (`OutputHandler`/`TabletSeatHandler`/`FractionalScaleHandler`)
+//! for the same reason; every other module is exactly one handler.
+
+mod buffer;
+mod compositor;
+mod idle;
+mod input_method;
+mod layer_shell;
+mod misc;
+mod seat;
+mod selection;
+mod xdg_activation;
+mod xdg_decoration;
+mod xdg_shell;
 
-use smithay::desktop::{find_popup_root_surface, layer_map_for_output, LayerSurface as DesktopLayerSurface, PopupKeyboardGrab, PopupKind, PopupPointerGrab};
-use smithay::input::pointer::{CursorImageStatus, Focus};
-use smithay::input::{Seat, SeatHandler, SeatState};
-use smithay::reexports::wayland_protocols::xdg::decoration::zv1::server::zxdg_toplevel_decoration_v1::Mode as DecorationMode;
-use smithay::reexports::wayland_protocols::xdg::shell::server::xdg_toplevel;
-use smithay::reexports::wayland_server::protocol::wl_buffer::WlBuffer;
-use smithay::reexports::wayland_server::protocol::wl_output::WlOutput;
-use smithay::reexports::wayland_server::protocol::wl_seat;
-use smithay::reexports::wayland_server::protocol::wl_surface::WlSurface;
-use smithay::reexports::wayland_server::Client;
-use smithay::reexports::wayland_server::Resource;
-use smithay::backend::allocator::dmabuf::Dmabuf;
-use smithay::backend::renderer::ImportDma;
-use smithay::utils::Serial;
-use smithay::wayland::buffer::BufferHandler;
-use smithay::wayland::compositor::{CompositorClientState, CompositorHandler, CompositorState};
-use smithay::wayland::dmabuf::{DmabufGlobal, DmabufHandler, DmabufState, ImportNotifier};
-use smithay::wayland::xdg_activation::{XdgActivationHandler, XdgActivationState, XdgActivationToken, XdgActivationTokenData};
-use smithay::wayland::input_method::PopupSurface as ImePopupSurface;
-use smithay::wayland::selection::data_device::{
-    ClientDndGrabHandler, DataDeviceHandler, DataDeviceState, ServerDndGrabHandler,
-};
-use smithay::wayland::selection::primary_selection::{PrimarySelectionHandler, PrimarySelectionState};
-use smithay::wayland::selection::wlr_data_control::{DataControlHandler, DataControlState};
-use smithay::wayland::compositor::{add_pre_commit_hook, with_states};
-use smithay::wayland::selection::SelectionHandler;
-use smithay::wayland::shell::wlr_layer::{
-    Layer, LayerSurface as WlrLayerSurface, LayerSurfaceCachedState, WlrLayerShellHandler, WlrLayerShellState,
-};
-use smithay::wayland::shell::xdg::decoration::XdgDecorationHandler;
-use smithay::wayland::shell::xdg::{PopupSurface, PositionerState, ToplevelSurface, XdgShellHandler, XdgShellState};
-use smithay::wayland::shm::{ShmHandler, ShmState};
-use smithay::wayland::tablet_manager::TabletSeatHandler;
 use smithay::{
     delegate_compositor, delegate_cursor_shape, delegate_data_control, delegate_data_device, delegate_dmabuf,
-    delegate_layer_shell, delegate_output, delegate_primary_selection, delegate_seat, delegate_session_lock,
-    delegate_shm, delegate_xdg_activation, delegate_xdg_decoration, delegate_xdg_shell,
-    delegate_input_method_manager, delegate_text_input_manager,
+    delegate_input_method_manager, delegate_layer_shell, delegate_output, delegate_primary_selection, delegate_seat,
+    delegate_session_lock, delegate_shm, delegate_text_input_manager, delegate_virtual_keyboard_manager,
+    delegate_xdg_activation, delegate_xdg_decoration, delegate_xdg_shell,
 };
 
-use crate::state::{ClientState, CompState};
-
-impl CompositorHandler for CompState {
-    fn compositor_state(&mut self) -> &mut CompositorState {
-        &mut self.compositor_state
-    }
-
-    fn client_compositor_state<'a>(&self, client: &'a Client) -> &'a CompositorClientState {
-        // Two possible client kinds now: our own `ClientState` for regular
-        // Wayland clients, or smithay's `XWaylandClientData` for the single
-        // XWayland client (see `xwayland.rs`) - both carry a
-        // `CompositorClientState`, just under different wrapper types.
-        if let Some(state) = client.get_data::<ClientState>() {
-            return &state.compositor_state;
-        }
-        &client.get_data::<smithay::xwayland::XWaylandClientData>().expect("client is neither ours nor XWayland's").compositor_state
-    }
-
-    /// Workaround for a real smithay bug (see docs/PANEL_SUPPORT_TODO.md and
-    /// `layer_destroyed` below): destroying a `zwlr_layer_surface_v1` role
-    /// resets the surface's `LayerSurfaceCachedState` to
-    /// `Default::default()` (size 0x0, no anchor) rather than removing it,
-    /// but the pre-commit hook smithay itself registers at
-    /// `get_layer_surface` time keeps validating that state against every
-    /// future commit regardless of whether the role still exists --
-    /// tripping its own `width/height 0 requested without ... anchors`
-    /// check and posting `invalid_size`, which kills the client's whole
-    /// connection over what is protocol-legal (committing a now-roleless
-    /// surface).
-    ///
-    /// Fixed by registering our own pre-commit hook here, in `new_surface`
-    /// - called at `wl_compositor.create_surface`, strictly before any
-    /// later `get_layer_surface` on the same surface could register
-    /// smithay's own hook. Hooks run in registration order (`tree.rs`:
-    /// `pre_commit_hooks` is a plain `Vec`, pushed and iterated in order),
-    /// so ours always runs first and can neutralize the stale reset state
-    /// before smithay's hook ever inspects it. This depends on that
-    /// ordering guarantee holding in future smithay versions - it isn't
-    /// documented as an API contract, just an implementation detail
-    /// confirmed against 0.7.0's source - so re-check this file against
-    /// whatever smithay version replaces it.
-    ///
-    /// Cost: one closure registered per `wl_surface` (not just layer
-    /// surfaces, since we don't know in advance which ones will become
-    /// one), each a no-op unless that exact surface is in
-    /// `dead_layer_surfaces`.
-    fn new_surface(&mut self, surface: &WlSurface) {
-        add_pre_commit_hook::<CompState, _>(surface, |state, _dh, surface| {
-            if !state.dead_layer_surfaces.contains(surface) {
-                return;
-            }
-            with_states(surface, |states| {
-                let mut cached = states.cached_state.get::<LayerSurfaceCachedState>();
-                let pending = cached.pending();
-                if pending.size.w == 0 && !pending.anchor.anchored_horizontally() {
-                    pending.size.w = 1;
-                }
-                if pending.size.h == 0 && !pending.anchor.anchored_vertically() {
-                    pending.size.h = 1;
-                }
-            });
-        });
-    }
-
-    fn commit(&mut self, surface: &WlSurface) {
-        smithay::backend::renderer::utils::on_commit_buffer_handler::<CompState>(surface);
-        // XWayland's association of an X11 window with this wl_surface can
-        // arrive at any point relative to the map request (see
-        // `xwayland.rs`'s module docs); `surface_associated` handles the
-        // common ordering, this retries the surfaces still waiting on a
-        // commit to actually make that association queryable.
-        self.retry_pending_x11_windows();
-        if let Some(&id) = self.surface_to_id.get(surface) {
-            if let Some(w) = self.id_to_window.get(&id) {
-                w.on_commit();
-            }
-            // See `content_epoch`'s doc comment: this is the only per-commit
-            // signal the udev backend's rounded-corner mask cache has to
-            // invalidate itself, since content can change every frame,
-            // independent of the geometry-driven points `redraw_decoration_
-            // buffer` already runs at.
-            *self.content_epoch.entry(id).or_insert(0) += 1;
-            crate::state::sync_toplevel_metadata(self, id, surface);
-        }
-        // Before `ensure_layer_initial_configure`: if this commit just
-        // hid or re-showed a layer surface, `sync_layer_visibility` needs
-        // to unmap/re-map it first, so the lookup that function does via
-        // `layer_for_surface` sees the corrected state rather than acting
-        // on stale membership in `LayerMap`'s own list.
-        self.sync_layer_visibility(surface);
-        self.ensure_layer_initial_configure(surface);
-        // Advances a just-created popup from unmapped to mapped (needed for
-        // `PopupManager::popups_for_surface`, which `popup_render_elements`
-        // reads at render time) and prunes dead ones. Cheap and only does
-        // real work on a popup-role surface, so doing it on every commit
-        // rather than throttling is not worth the extra bookkeeping.
-        self.popups.commit(surface);
-        self.popups.cleanup();
-    }
-}
-
-impl XdgShellHandler for CompState {
-    fn xdg_shell_state(&mut self) -> &mut XdgShellState {
-        &mut self.xdg_shell_state
-    }
-
-    fn new_toplevel(&mut self, surface: ToplevelSurface) {
-        self.new_managed_window(surface);
-    }
-
-    /// `move_request`/`resize_request` were also still smithay's default
-    /// no-op implementations - a much larger gap than the five below:
-    /// this is *how a client-side-decorated window gets dragged or resized
-    /// by its own titlebar/edges at all*. A window we draw our own
-    /// decoration for never needed this (`TitlebarHit::Drag`/`Resize` in
-    /// `input.rs` detect the click directly, since we own those pixels),
-    /// but a window that negotiated client-side decoration and draws its
-    /// own titlebar - Firefox, and most GTK4 apps by default - handles
-    /// the click itself and then asks the compositor to actually perform
-    /// the move/resize via exactly these two requests. Left unimplemented,
-    /// dragging or resizing any such window by its own chrome did
-    /// nothing at all - the only way to reposition it was the
-    /// modifier+drag-anywhere gesture (`bindm`), which most users have no
-    /// reason to know exists and doesn't work for resize-from-a-specific-
-    /// edge at all. Reuses the exact same `WindowManager::start_drag`/
-    /// `start_resize` the pointer-driven titlebar handlers call --
-    /// `handle_pointer_position`/`handle_pointer_button` already drive any
-    /// in-progress drag/resize to completion on subsequent motion/release
-    /// regardless of what started it, so no smithay pointer grab is
-    /// needed here at all, just the same start call from a different
-    /// trigger.
-    fn move_request(&mut self, surface: ToplevelSurface, _seat: wl_seat::WlSeat, _serial: Serial) {
-        // Temporary: added to trace a live report that dragging a CSD
-        // window (Firefox) by its own tab strip/header bar does nothing --
-        // this is the only way to tell "the client never sent xdg_toplevel
-        // ::move at all" apart from "it sent it and something downstream
-        // of here didn't follow through." Remove once that's settled.
-        match self.surface_to_id.get(surface.wl_surface()) {
-            Some(&id) => {
-                let pos = crate::input::last_pointer_pos(self);
-                log::info!("move_request: window {id:?} at pointer {pos:?}");
-                self.wm.borrow_mut().start_drag(id, pos.x as i32, pos.y as i32);
-            }
-            None => log::warn!("move_request: surface has no tracked window id"),
-        }
-    }
-
-    fn resize_request(&mut self, surface: ToplevelSurface, _seat: wl_seat::WlSeat, _serial: Serial, edges: xdg_toplevel::ResizeEdge) {
-        let Some(edge) = (match edges {
-            xdg_toplevel::ResizeEdge::Top => Some(srdwm_core::ResizeEdge::Top),
-            xdg_toplevel::ResizeEdge::Bottom => Some(srdwm_core::ResizeEdge::Bottom),
-            xdg_toplevel::ResizeEdge::Left => Some(srdwm_core::ResizeEdge::Left),
-            xdg_toplevel::ResizeEdge::Right => Some(srdwm_core::ResizeEdge::Right),
-            xdg_toplevel::ResizeEdge::TopLeft => Some(srdwm_core::ResizeEdge::TopLeft),
-            xdg_toplevel::ResizeEdge::TopRight => Some(srdwm_core::ResizeEdge::TopRight),
-            xdg_toplevel::ResizeEdge::BottomLeft => Some(srdwm_core::ResizeEdge::BottomLeft),
-            xdg_toplevel::ResizeEdge::BottomRight => Some(srdwm_core::ResizeEdge::BottomRight),
-            // `None` is a valid protocol value (the client leaves the edge
-            // unspecified) but `WindowManager::start_resize` needs one --
-            // there's nothing sensible to default it to that wouldn't be a
-            // guess, so this is a no-op rather than picking one.
-            _ => None,
-        }) else {
-            return;
-        };
-        if let Some(&id) = self.surface_to_id.get(surface.wl_surface()) {
-            let pos = crate::input::last_pointer_pos(self);
-            self.wm.borrow_mut().start_resize(id, edge, pos.x as i32, pos.y as i32);
-        }
-    }
-
-    /// `maximize_request`/`unmaximize_request`/`fullscreen_request`/
-    /// `unfullscreen_request`/`minimize_request` were all still smithay's
-    /// default no-op (or configure-only) implementations - found
-    /// investigating the `toggle_fullscreen` decoration bug above, by
-    /// checking what else routes through the same `WindowManager` calls
-    /// the titlebar-button click handlers in `input.rs` already use.
-    /// These five are the *client-initiated* equivalent of those clicks: a
-    /// client's own window-menu "Maximize", pressing F11, an HTML5 video
-    /// going fullscreen, or (for a client that negotiated client-side
-    /// decoration and draws its own titlebar, like Firefox) that titlebar's
-    /// own maximize button - all ask the compositor to actually perform
-    /// the state change via these requests rather than the compositor
-    /// noticing on its own. Left unimplemented, every one of them was a
-    /// silent no-op: the client's button did nothing, with no error and
-    /// nothing to suggest why, from any app that relies on this instead of
-    /// (or in addition to) a compositor-side keybinding.
-    fn maximize_request(&mut self, surface: ToplevelSurface) {
-        if let Some(&id) = self.surface_to_id.get(surface.wl_surface()) {
-            if !self.wm.borrow().window(id).is_some_and(|w| w.maximized) {
-                self.wm.borrow_mut().toggle_maximize(id);
-                self.sync_geometry(id);
-                crate::foreign_toplevel::send_state(self, id);
-            }
-        }
-        surface.send_configure();
-    }
-
-    fn unmaximize_request(&mut self, surface: ToplevelSurface) {
-        if let Some(&id) = self.surface_to_id.get(surface.wl_surface()) {
-            if self.wm.borrow().window(id).is_some_and(|w| w.maximized) {
-                self.wm.borrow_mut().toggle_maximize(id);
-                self.sync_geometry(id);
-                crate::foreign_toplevel::send_state(self, id);
-            }
-        }
-        surface.send_configure();
-    }
-
-    /// `_output` (the client's requested target output) is ignored --
-    /// single-seat, and every other fullscreen entry point (the titlebar
-    /// button, `srd.window.fullscreen()`) already fullscreens on whatever
-    /// monitor the window is already on, so this matches that instead of
-    /// introducing an output-aware fullscreen path only this one request
-    /// would use.
-    fn fullscreen_request(&mut self, surface: ToplevelSurface, _output: Option<WlOutput>) {
-        if let Some(&id) = self.surface_to_id.get(surface.wl_surface()) {
-            if !self.wm.borrow().is_fullscreen(id) {
-                // `redraw_decoration_buffer` first, same reason
-                // `set_decorated_from_mode` calls it before `sync_geometry`:
-                // fullscreen also flips `Window.decorated`, and dropping
-                // the decoration needs the buffer actually removed, not
-                // just left stale for `sync_geometry`'s own resize-only
-                // redraw check to skip.
-                self.wm.borrow_mut().toggle_fullscreen(id);
-                self.redraw_decoration_buffer(id);
-                self.sync_geometry(id);
-                crate::foreign_toplevel::send_state(self, id);
-            }
-        }
-        surface.send_configure();
-    }
-
-    fn unfullscreen_request(&mut self, surface: ToplevelSurface) {
-        if let Some(&id) = self.surface_to_id.get(surface.wl_surface()) {
-            if self.wm.borrow().is_fullscreen(id) {
-                self.wm.borrow_mut().toggle_fullscreen(id);
-                self.redraw_decoration_buffer(id);
-                self.sync_geometry(id);
-                crate::foreign_toplevel::send_state(self, id);
-            }
-        }
-        surface.send_configure();
-    }
-
-    /// No `send_configure` here, matching the pointer-driven
-    /// `TitlebarHit::Minimize` handler in `input.rs`: minimizing doesn't
-    /// change the window's own size, only whether it's currently shown, so
-    /// there's nothing new to tell the client about its own geometry.
-    fn minimize_request(&mut self, surface: ToplevelSurface) {
-        if let Some(&id) = self.surface_to_id.get(surface.wl_surface()) {
-            self.wm.borrow_mut().minimize_window(id);
-            crate::foreign_toplevel::send_state(self, id);
-        }
-    }
-
-    /// Was a bare no-op - no `send_configure` at all. Per xdg-shell,
-    /// `xdg_surface.configure` is required before a popup's first commit;
-    /// real toolkits (confirmed live: GTK4's Wayland backend) block that
-    /// commit in a synchronous roundtrip waiting for it, so every popup
-    /// hung its client forever. GTK4 implements tooltips *and*
-    /// `Gtk.Popover` as `xdg_popup`, so this fired on hovering almost any
-    /// widget with a tooltip - confirmed by a peer session's gdb backtrace
-    /// (blocked in `wl_display_dispatch_queue` under `gtk_widget_show`)
-    /// after AGS wedged.
-    ///
-    /// Geometry is `positioner.get_geometry()` un-constrained - no
-    /// on-screen clamping yet (`PositionerState::get_unconstrained_geometry`
-    /// needs a target rect in the parent's surface-local space, which is a
-    /// real follow-up, not this fix); an occasional popup placed near a
-    /// screen edge may render partly off it, which is cosmetic, not a hang.
-    fn new_popup(&mut self, surface: PopupSurface, positioner: PositionerState) {
-        surface.with_pending_state(|state| {
-            state.geometry = positioner.get_geometry();
-            state.positioner = positioner;
-        });
-        if surface.send_configure().is_err() {
-            return;
-        }
-        let _ = self.popups.track_popup(smithay::desktop::PopupKind::Xdg(surface));
-    }
-
-    /// Implicit grab + dismiss-on-outside-click. Previously believed
-    /// blocked on `CompState`'s `SeatHandler` associated types not
-    /// satisfying `PopupManager::grab_popup`'s `WaylandFocus +
-    /// From<PopupKind>` bound - rechecked while implementing
-    /// `move_request`/`resize_request` (same trait, adjacent methods) and
-    /// it turns out they already do: `KeyboardFocus`/`PointerFocus` are
-    /// both plain `WlSurface`, smithay provides `impl From<PopupKind> for
-    /// WlSurface` itself, and `WlSurface: From<WlSurface>` trivially. No
-    /// blocker ever existed by the time of this pass; the bound just
-    /// hadn't been rechecked since being noted as unmet.
-    ///
-    /// `self.seat.clone()` rather than resolving `_seat` (the client's
-    /// `wl_seat` resource) via `Seat::from_resource` - this compositor
-    /// only ever has the one seat, matching how `move_request`/
-    /// `resize_request` already ignore the same parameter.
-    fn grab(&mut self, surface: PopupSurface, _seat: wl_seat::WlSeat, serial: Serial) {
-        let popup = PopupKind::Xdg(surface);
-        let Ok(root) = find_popup_root_surface(&popup) else {
-            log::warn!("POPUP-GRAB-DIAG find_popup_root_surface failed");
-            return;
-        };
-        let seat = self.seat.clone();
-        let grab = match self.popups.grab_popup(root, popup, &seat, serial) {
-            Ok(g) => g,
-            Err(e) => {
-                log::warn!("POPUP-GRAB-DIAG grab_popup failed: {e:?}");
-                return;
-            }
-        };
-        log::warn!("POPUP-GRAB-DIAG grab established, has_pointer={} has_keyboard={}", seat.get_pointer().is_some(), seat.get_keyboard().is_some());
-        if let Some(keyboard) = seat.get_keyboard() {
-            keyboard.set_grab(self, PopupKeyboardGrab::new(&grab), serial);
-        }
-        if let Some(pointer) = seat.get_pointer() {
-            pointer.set_grab(self, PopupPointerGrab::new(&grab), serial, Focus::Keep);
-        }
-    }
-
-    fn reposition_request(&mut self, surface: PopupSurface, positioner: PositionerState, token: u32) {
-        surface.with_pending_state(|state| {
-            state.geometry = positioner.get_geometry();
-            state.positioner = positioner;
-        });
-        surface.send_repositioned(token);
-    }
-
-    fn toplevel_destroyed(&mut self, surface: ToplevelSurface) {
-        self.remove_window(surface.wl_surface());
-    }
-}
-
-impl XdgDecorationHandler for CompState {
-    /// Offers whichever mode `theme.decorations.default_mode`/`srd set
-    /// decoration_mode` currently prefers - a client with a real opinion
-    /// of its own still overrides this via `request_mode` below regardless
-    /// of what's offered here; this only decides what a client with *no*
-    /// preference ends up with. See `srdwm_core::ThemeConfig::
-    /// default_decorated`'s own doc comment for why this is configurable
-    /// rather than hardcoded to one mode.
-    fn new_decoration(&mut self, toplevel: ToplevelSurface) {
-        let offer = if self.wm.borrow().theme.default_decorated { DecorationMode::ServerSide } else { DecorationMode::ClientSide };
-        toplevel.with_pending_state(|state| {
-            state.decoration_mode = Some(offer);
-        });
-    }
-
-    /// Honors whichever mode the client actually asked for, rather than
-    /// always forcing server-side - and mirrors the result into our own
-    /// `Window.decorated`, so a client drawing its own titlebar doesn't
-    /// *also* get one drawn on top of it by us.
-    ///
-    /// Always forcing `ServerSide` (what this used to do) is why some
-    /// clients ended up with two sets of window buttons: Firefox requests
-    /// client-side decoration when its own "use system titlebar" setting
-    /// is off, and draws its own close/minimize/maximize row regardless of
-    /// what the compositor grants - so forcing server-side just added
-    /// srdwm's row on top of the one Firefox was drawing anyway, instead
-    /// of preventing it. Respecting the request means srdwm steps out of
-    /// the way for exactly those clients, while everything that accepts
-    /// (or has no preference and gets offered) server-side still gets our
-    /// titlebar as before.
-    fn request_mode(&mut self, toplevel: ToplevelSurface, mode: DecorationMode) {
-        toplevel.with_pending_state(|state| {
-            state.decoration_mode = Some(mode);
-        });
-        toplevel.send_configure();
-        self.set_decorated_from_mode(toplevel.wl_surface(), mode == DecorationMode::ServerSide);
-    }
-
-    /// The client dropped its decoration-mode preference. `new_decoration`
-    /// already offers the configured default as the mode the next
-    /// configure will carry, so mirror that same default here rather than
-    /// leaving whatever mode was negotiated before this - otherwise a
-    /// client that requests one mode, then later unsets it expecting the
-    /// default back, would stay stuck in that mode forever.
-    fn unset_mode(&mut self, toplevel: ToplevelSurface) {
-        let default_decorated = self.wm.borrow().theme.default_decorated;
-        let mode = if default_decorated { DecorationMode::ServerSide } else { DecorationMode::ClientSide };
-        toplevel.with_pending_state(|state| {
-            state.decoration_mode = Some(mode);
-        });
-        toplevel.send_configure();
-        self.set_decorated_from_mode(toplevel.wl_surface(), default_decorated);
-    }
-}
-
-impl ShmHandler for CompState {
-    fn shm_state(&self) -> &ShmState {
-        &self.shm_state
-    }
-}
-
-impl BufferHandler for CompState {
-    fn buffer_destroyed(&mut self, _buffer: &WlBuffer) {}
-}
-
-impl DmabufHandler for CompState {
-    fn dmabuf_state(&mut self) -> &mut DmabufState {
-        &mut self.dmabuf_state
-    }
-
-    /// Validates a client's dmabuf by actually importing it wherever a
-    /// renderer is reachable from here, so a genuinely bad buffer (wrong
-    /// modifier, format the renderer doesn't support) gets the protocol
-    /// error instead of silently rendering garbage later.
-    ///
-    /// That's only the udev backend: its `PixmanRenderer` lives inside
-    /// `self.udev` (`UdevState`), a field of this same struct.
-    /// `PixmanRenderer` supports dmabuf import despite being a pure
-    /// software renderer - `dmabuf_formats()` only advertises the Linear
-    /// modifier, which it imports by mmap'ing the buffer and reading it
-    /// directly as pixels, no GPU involved. This is what actually answers
-    /// `docs/PANEL_SUPPORT_TODO.md`'s P0.3: GTK4 allocates via its own
-    /// EGL/gbm path against the real DRM render node (untouched by this
-    /// compositor either way) and hands the result here as a Linear-
-    /// modifier dmabuf, which pixman can read straight off.
-    ///
-    /// The winit (nested/dev) backend's `GlesRenderer` lives on
-    /// `WaylandPlatform`, a sibling of `CompState`, not reachable from a
-    /// method on `CompState` itself. Accepted there without eager
-    /// validation - the buffer still gets imported the same way every
-    /// other buffer type already is, lazily, the first time it is actually
-    /// rendered via `render_elements_from_surface_tree`. Real hardware,
-    /// where P0.3 actually bites, always goes through the udev path.
-    fn dmabuf_imported(&mut self, _global: &DmabufGlobal, dmabuf: Dmabuf, notifier: ImportNotifier) {
-        match self.udev.as_mut() {
-            Some(udev) => match udev.renderer.import_dmabuf(&dmabuf, None) {
-                Ok(_) => {
-                    let _ = notifier.successful::<CompState>();
-                }
-                Err(e) => {
-                    log::warn!("udev: rejecting dmabuf import: {e}");
-                    notifier.failed();
-                }
-            },
-            None => {
-                let _ = notifier.successful::<CompState>();
-            }
-        }
-    }
-}
-
-impl XdgActivationHandler for CompState {
-    fn activation_state(&mut self) -> &mut XdgActivationState {
-        &mut self.xdg_activation_state
-    }
-
-    /// A launcher spawns an app after first getting a token
-    /// (`get_activation_token`) and handing it to the new process (usually
-    /// via `XDG_ACTIVATION_TOKEN`); the app's own first window then
-    /// presents that same token back here via `activate`, asking to be
-    /// raised. Without this, that request was silently ignored - the new
-    /// window opened and just sat there unfocused behind everything,
-    /// exactly the gap `docs/PANEL_SUPPORT_TODO.md`'s P1 flagged.
-    ///
-    /// No token bookkeeping of our own: `token_created`'s default already
-    /// accepts every token (fine for a single-user session with no
-    /// cross-client trust boundary to enforce), so all that's left is
-    /// mapping the activating `surface` to a `WindowId` and reusing the
-    /// exact same `focus_window` path a dock's "activate" request already
-    /// goes through (`foreign_toplevel.rs`). If the surface isn't tracked
-    /// yet - the activation raced ahead of this window's own mapping --
-    /// there is nothing to focus yet, so this is a no-op rather than an
-    /// error; the protocol doesn't require honoring every activation.
-    fn request_activation(&mut self, _token: XdgActivationToken, _token_data: XdgActivationTokenData, surface: WlSurface) {
-        if let Some(&id) = self.surface_to_id.get(&surface) {
-            crate::input::focus_window(self, id);
-        }
-    }
-}
-
-/// `zwp_text_input_manager_v3` + `zwp_input_method_manager_v2`: lets a real
-/// input method (fcitx5, ibus, any CJK/dead-key/emoji-picker IME) attach to
-/// whichever surface has keyboard focus and draw its own candidate/
-/// composition popup. Without these two globals a client that only speaks
-/// text-input (most modern toolkits do, GTK4/Qt6 included) has no way to
-/// tell the compositor "I have an editable text field, here is its cursor
-/// rectangle" - every desktop app's search box, address bar, and chat
-/// input silently loses IME support, not just an edge case.
-///
-/// Focus tracking needs *no* wiring here at all: `CompState::KeyboardFocus`
-/// is a plain `WlSurface`, and smithay's own blanket `impl KeyboardTarget
-/// for WlSurface` already calls `seat.text_input().set_focus/.enter()/
-/// .leave()` and `seat.input_method().activate_input_method()/
-/// deactivate_input_method()` from inside `enter`/`leave` - which
-/// `set_keyboard_focus`'s existing `keyboard.set_focus(...)` call already
-/// triggers on every real focus change. The only things actually missing
-/// were the two manager globals and this handler for the popup surface
-/// lifecycle.
-impl smithay::wayland::input_method::InputMethodHandler for CompState {
-    /// A candidate/composition window (an emoji picker, a CJK candidate
-    /// list) just opened. Tracked as a regular [`PopupKind::InputMethod`]
-    /// in the same [`PopupManager`](smithay::desktop::PopupManager) that
-    /// already owns every `xdg_popup` - `elements::popup_render_elements`
-    /// renders both kinds identically, so no separate render path is
-    /// needed for this to actually become visible.
-    fn new_popup(&mut self, surface: ImePopupSurface) {
-        if let Err(e) = self.popups.track_popup(PopupKind::from(surface)) {
-            log::warn!("input-method: failed to track popup: {e}");
-        }
-    }
-
-    fn dismiss_popup(&mut self, surface: ImePopupSurface) {
-        if let Some(parent) = surface.get_parent().map(|p| p.surface.clone()) {
-            let _ = smithay::desktop::PopupManager::dismiss_popup(&parent, &PopupKind::from(surface));
-        }
-    }
-
-    /// The IME moved its own popup (e.g. following the text cursor as the
-    /// user types) - `PopupSurface::location()` already reflects the new
-    /// position; nothing else needs updating on this side, matching every
-    /// other smithay-based compositor's own no-op here.
-    fn popup_repositioned(&mut self, _surface: ImePopupSurface) {}
-
-    /// Where the IME should anchor its popup, in the parent surface's own
-    /// output-independent (logical, window-relative-origin) space - same
-    /// geometry `elements::popup_targets` already computes for xdg popups,
-    /// reused here rather than duplicated. A window not yet tracked (the
-    /// activation raced ahead of its own mapping) gets a default/zero rect,
-    /// same "no-op rather than an error" stance as `request_activation`
-    /// above.
-    fn parent_geometry(&self, parent: &WlSurface) -> smithay::utils::Rectangle<i32, smithay::utils::Logical> {
-        let Some(&id) = self.surface_to_id.get(parent) else {
-            return smithay::utils::Rectangle::default();
-        };
-        let wm = self.wm.borrow();
-        let Some(w) = wm.window(id) else {
-            return smithay::utils::Rectangle::default();
-        };
-        let band = if w.decorated { srdwm_core::TITLEBAR_HEIGHT as i32 } else { 0 };
-        smithay::utils::Rectangle::new((w.geometry.x, w.geometry.y + band).into(), (w.geometry.width as i32, w.geometry.height as i32).into())
-    }
-}
-
-impl smithay::wayland::output::OutputHandler for CompState {}
-
-/// `wp_cursor_shape_v1`: lets a client ask for a *named* cursor (text,
-/// grab, resize edges, ...) instead of rendering and attaching its own
-/// surface. Its requests route straight into `SeatHandler::cursor_image`
-/// below, same as a client-drawn cursor surface does - no extra state on
-/// our side. Without this global at all, a client that only speaks this
-/// (increasingly the norm - recent GTK4/Firefox use it for most cursor
-/// changes) has no way to tell us the pointer should look like anything
-/// but whatever it last was, which reads as the cursor going stale, wrong,
-/// or simply disappearing depending on what was showing when the client
-/// gave up trying.
-///
-/// `TabletSeatHandler` is a supertrait bound of this protocol's `Dispatch`
-/// impl (cursor-shape covers tablet tools too); srdwm has no tablet
-/// support to speak of, so every method is left at its no-op default.
-impl TabletSeatHandler for CompState {}
-
-/// Fractional scaling. srdwm runs every output at scale 1, so there is
-/// nothing to compute - but the global has to exist, because clients that
-/// use it (notably wallpaper daemons) treat it as mandatory.
-impl smithay::wayland::fractional_scale::FractionalScaleHandler for CompState {}
-
-impl SeatHandler for CompState {
-    type KeyboardFocus = WlSurface;
-    type PointerFocus = WlSurface;
-    type TouchFocus = WlSurface;
-
-    fn seat_state(&mut self) -> &mut SeatState<Self> {
-        &mut self.seat_state
-    }
-
-    fn focus_changed(&mut self, _seat: &Seat<Self>, _focused: Option<&WlSurface>) {}
-    /// Clients set their own cursor (an I-beam over text, a hand over a
-    /// link). Recorded here and drawn by the render paths - on a bare TTY
-    /// nothing else would draw it. See `cursor.rs`.
-    fn cursor_image(&mut self, _seat: &Seat<Self>, image: CursorImageStatus) {
-        self.cursor_status = image;
-    }
-}
-
-impl WlrLayerShellHandler for CompState {
-    fn shell_state(&mut self) -> &mut WlrLayerShellState {
-        &mut self.layer_shell_state
-    }
-
-    fn new_layer_surface(&mut self, surface: WlrLayerSurface, wl_output: Option<WlOutput>, _layer: Layer, namespace: String) {
-        // Logged before anything else can early-return or panic: the
-        // question this answers (see docs/PANEL_SUPPORT_TODO.md) is
-        // whether this handler is reached AT ALL for a later
-        // `get_layer_surface` request in a create -> commit -> destroy ->
-        // commit-again -> create sequence, or whether the client's
-        // dispatch is already dead by then and this never runs.
-        log::debug!("layer-shell: new_layer_surface entered, surface={:?} namespace={namespace:?} output_named={}", surface.wl_surface().id(), wl_output.is_some());
-        // A client may name the output it wants (a bar on a specific
-        // monitor); if it doesn't, or names one we don't drive, it lands on
-        // the primary output.
-        let output = wl_output
-            .as_ref()
-            .and_then(|wl| self.output_for_wl(wl))
-            .map(|e| e.output.clone())
-            .or_else(|| self.primary_output().cloned());
-        let Some(output) = output else {
-            log::warn!("wayland: layer surface requested but no output exists yet");
-            return;
-        };
-        // Paired with the debug log in `ensure_layer_initial_configure`'s
-        // early return - see docs/PANEL_SUPPORT_TODO.md's P0. This is the
-        // other half of "did map_layer actually succeed, and on which
-        // output": logged unconditionally (not just on the error paths
-        // that already existed) so a real reproduction shows both sides of
-        // the handoff instead of just the failure.
-        let surface_id = surface.wl_surface().id();
-        let layer_surface = DesktopLayerSurface::new(surface, namespace);
-        let result = layer_map_for_output(&output).map_layer(&layer_surface);
-        match &result {
-            Ok(()) => log::debug!("layer-shell: mapped surface {surface_id:?} onto output {}", output.name()),
-            Err(e) => log::warn!("wayland: failed to map layer surface {surface_id:?}: {e}"),
-        }
-    }
-
-    fn layer_destroyed(&mut self, surface: WlrLayerSurface) {
-        // See the matching top-of-function log in `new_layer_surface`.
-        log::debug!("layer-shell: layer_destroyed entered, surface={:?}", surface.wl_surface().id());
-        // Marks this surface for the pre-commit-hook workaround in
-        // `new_surface` - see that function's doc comment for the bug
-        // this exists to route around.
-        self.dead_layer_surfaces.insert(surface.wl_surface().clone());
-        // GTK (confirmed live via an AGS peer session's WAYLAND_DEBUG trace)
-        // reuses the same `wl_surface` for the next `get_layer_surface` role
-        // rather than creating a fresh one - so without this, a "shown at
-        // least once" flag from *this* role would leak onto the next one
-        // and make `sync_layer_visibility` treat that new role's own
-        // ack-configure commit as eligible to hide again, the same bug
-        // `layer_surfaces_shown_once` exists to prevent, just reintroduced
-        // for exactly the reused-surface case that matters here.
-        self.layer_surfaces_shown_once.remove(surface.wl_surface());
-        // The surface belongs to exactly one output's map, but which one is
-        // the client's choice, so unmap from whichever holds it.
-        for output in self.outputs().cloned().collect::<Vec<_>>() {
-            let mut map = layer_map_for_output(&output);
-            let found = map.layers().find(|l| l.layer_surface() == &surface).cloned();
-            if let Some(layer) = found {
-                // Same zone-change recompute `ensure_layer_initial_configure`
-                // already does on every commit that changes a layer's
-                // exclusive zone (state/layers.rs) - but this is the *only* place
-                // that ever runs for a surface that goes away without one
-                // last commit. `unmap_layer` alone doesn't trigger it:
-                // reported live (by the AGS peer session) as a bar unmapping
-                // for fullscreen yet `srd monitors` still reporting the
-                // bar's old reserved_top for as long as fullscreen lasted --
-                // harmless there only because fullscreen targets
-                // `full_geometry`, which ignores the reservation anyway, but
-                // wrong for anything that reads `usable`/`geometry` while a
-                // bar is unmapped without exiting cleanly (a crash, not just
-                // AGS's cooperative fullscreen hide).
-                let zone_before = map.non_exclusive_zone();
-                map.unmap_layer(&layer);
-                let zone_after = map.non_exclusive_zone();
-                if zone_after != zone_before {
-                    self.pending.borrow_mut().push(srdwm_core::Event::MonitorAdded(srdwm_core::Monitor::new(0, "", srdwm_core::Rect::new(0, 0, 0, 0))));
-                }
-                break;
-            }
-        }
-        // A lock/launcher surface holding exclusive keyboard focus just
-        // vanished (crash, or a normal close) - don't leave focus dangling
-        // on a dead surface.
-        //
-        // `sync_keyboard_focus`, not a bare `set_keyboard_focus(None)`: an
-        // `OnDemand` layer surface (a launcher/quicksettings/datemenu
-        // popup, per `wlr-layer-shell`) claiming focus on click
-        // (`input.rs`'s `on_demand` branch) goes straight through
-        // `set_keyboard_focus` without ever touching `WindowManager::
-        // focused` - core has no concept of a layer surface to focus, so
-        // it still correctly points at whatever real toplevel was focused
-        // before the popup opened. Hardcoding `None` here threw that away
-        // regardless, leaving nothing focused until the user happened to
-        // click a window again - reported live (an AGS peer session's
-        // user) as "focus never returns after using the bar". `sync_
-        // keyboard_focus` reads that still-correct core state and restores
-        // real Wayland focus to it, falling through to `None` only if core
-        // genuinely has nothing focused either.
-        if self.seat.get_keyboard().and_then(|k| k.current_focus()).as_ref() == Some(surface.wl_surface()) {
-            crate::input::sync_keyboard_focus(self);
-        }
-    }
-}
-
-/// Clipboard/primary-selection/drag-and-drop.
-///
-/// All three selection protocols below (`wl_data_device_manager`,
-/// `zwp_primary_selection_v1`, `zwlr_data_control_manager_v1`) share
-/// smithay's single `SelectionHandler`. Every transfer here is
-/// *client-to-client*: one client owns the selection and writes the bytes
-/// itself, and smithay wires the two ends together without the data passing
-/// through us. `send_selection` is only ever called for a
-/// **compositor-provided** selection (one this WM set itself via
-/// `set_data_device_selection`), which srdwm never does - so it is
-/// deliberately left unimplemented rather than faked.
-impl SelectionHandler for CompState {
-    type SelectionUserData = ();
-}
-
-impl DataDeviceHandler for CompState {
-    fn data_device_state(&self) -> &DataDeviceState {
-        &self.data_device_state
-    }
-}
-
-// Drag-and-drop: the default trait methods already do the right thing for a
-// compositor that doesn't draw its own drag icon or offer server-side drag
-// sources - smithay runs the pointer grab and the offer/accept negotiation
-// internally. Both are implemented empty (rather than skipped) because
-// `DataDeviceHandler` requires them as supertraits.
-impl ClientDndGrabHandler for CompState {}
-impl ServerDndGrabHandler for CompState {}
-
-impl PrimarySelectionHandler for CompState {
-    fn primary_selection_state(&self) -> &PrimarySelectionState {
-        &self.primary_selection_state
-    }
-}
-
-/// `zwlr_data_control_manager_v1`: lets a client read/watch the selection
-/// without ever holding keyboard focus. This is what `wl-paste --watch`
-/// (and thus `cliphist store`, which the user's session autostarts) needs
-/// - a focus-following clipboard manager is impossible without it.
-impl DataControlHandler for CompState {
-    fn data_control_state(&self) -> &DataControlState {
-        &self.data_control_state
-    }
-}
-
-/// `ext_idle_notify_v1`. All the real logic (per-notification timers,
-/// resetting them on activity, honouring inhibition) already lives in
-/// smithay's own `IdleNotifierState` - this is just the getter it needs.
-/// See `input.rs`'s `notify_idle_activity` for the other half: nothing
-/// calls `notify_activity` on its own, that has to happen from every real
-/// input path.
-impl smithay::wayland::idle_notify::IdleNotifierHandler for CompState {
-    fn idle_notifier_state(&mut self) -> &mut smithay::wayland::idle_notify::IdleNotifierState<Self> {
-        &mut self.idle_notifier_state
-    }
-}
-
-/// `zwp_idle_inhibit_manager_v1`. A video player (or anything else that
-/// wants the screen to stay on/unlocked while it runs) creates one of
-/// these tied to its own surface; as long as at least one is alive,
-/// `IdleNotifierState::set_is_inhibited` stops idle timers from firing at
-/// all - see `idle_inhibiting_surfaces`'s doc comment on `CompState` for
-/// the one simplification (not workspace-visibility-aware) this takes.
-impl smithay::wayland::idle_inhibit::IdleInhibitHandler for CompState {
-    fn inhibit(&mut self, surface: WlSurface) {
-        self.idle_inhibiting_surfaces.push(surface);
-        self.idle_notifier_state.set_is_inhibited(true);
-    }
-
-    fn uninhibit(&mut self, surface: WlSurface) {
-        self.idle_inhibiting_surfaces.retain(|s| s != &surface);
-        self.idle_notifier_state.set_is_inhibited(!self.idle_inhibiting_surfaces.is_empty());
-    }
-}
+use crate::state::CompState;
 
 delegate_compositor!(CompState);
 delegate_xdg_shell!(CompState);
@@ -815,6 +43,7 @@ delegate_dmabuf!(CompState);
 delegate_xdg_activation!(CompState);
 delegate_text_input_manager!(CompState);
 delegate_input_method_manager!(CompState);
+delegate_virtual_keyboard_manager!(CompState);
 delegate_seat!(CompState);
 delegate_output!(CompState);
 delegate_layer_shell!(CompState);
diff --git a/crates/wayland/src/protocols/buffer.rs b/crates/wayland/src/protocols/buffer.rs
new file mode 100644
index 0000000..7730de6
--- /dev/null
+++ b/crates/wayland/src/protocols/buffer.rs
@@ -0,0 +1,68 @@
+//! `wl_shm`/`wl_buffer`/`zwp_linux_dmabuf_v1`: the three buffer-transport
+//! protocols, grouped together since none has more than a handful of lines
+//! on its own.
+
+use smithay::backend::allocator::dmabuf::Dmabuf;
+use smithay::backend::renderer::ImportDma;
+use smithay::reexports::wayland_server::protocol::wl_buffer::WlBuffer;
+use smithay::wayland::buffer::BufferHandler;
+use smithay::wayland::dmabuf::{DmabufGlobal, DmabufHandler, DmabufState, ImportNotifier};
+use smithay::wayland::shm::{ShmHandler, ShmState};
+
+use crate::state::CompState;
+
+impl ShmHandler for CompState {
+    fn shm_state(&self) -> &ShmState {
+        &self.shm_state
+    }
+}
+
+impl BufferHandler for CompState {
+    fn buffer_destroyed(&mut self, _buffer: &WlBuffer) {}
+}
+
+impl DmabufHandler for CompState {
+    fn dmabuf_state(&mut self) -> &mut DmabufState {
+        &mut self.dmabuf_state
+    }
+
+    /// Validates a client's dmabuf by actually importing it wherever a
+    /// renderer is reachable from here, so a genuinely bad buffer (wrong
+    /// modifier, format the renderer doesn't support) gets the protocol
+    /// error instead of silently rendering garbage later.
+    ///
+    /// That's only the udev backend: its `PixmanRenderer` lives inside
+    /// `self.udev` (`UdevState`), a field of this same struct.
+    /// `PixmanRenderer` supports dmabuf import despite being a pure
+    /// software renderer - `dmabuf_formats()` only advertises the Linear
+    /// modifier, which it imports by mmap'ing the buffer and reading it
+    /// directly as pixels, no GPU involved. This is what actually answers
+    /// `docs/PANEL_SUPPORT_TODO.md`'s P0.3: GTK4 allocates via its own
+    /// EGL/gbm path against the real DRM render node (untouched by this
+    /// compositor either way) and hands the result here as a Linear-
+    /// modifier dmabuf, which pixman can read straight off.
+    ///
+    /// The winit (nested/dev) backend's `GlesRenderer` lives on
+    /// `WaylandPlatform`, a sibling of `CompState`, not reachable from a
+    /// method on `CompState` itself. Accepted there without eager
+    /// validation - the buffer still gets imported the same way every
+    /// other buffer type already is, lazily, the first time it is actually
+    /// rendered via `render_elements_from_surface_tree`. Real hardware,
+    /// where P0.3 actually bites, always goes through the udev path.
+    fn dmabuf_imported(&mut self, _global: &DmabufGlobal, dmabuf: Dmabuf, notifier: ImportNotifier) {
+        match self.udev.as_mut() {
+            Some(udev) => match udev.renderer.import_dmabuf(&dmabuf, None) {
+                Ok(_) => {
+                    let _ = notifier.successful::<CompState>();
+                }
+                Err(e) => {
+                    log::warn!("udev: rejecting dmabuf import: {e}");
+                    notifier.failed();
+                }
+            },
+            None => {
+                let _ = notifier.successful::<CompState>();
+            }
+        }
+    }
+}
diff --git a/crates/wayland/src/protocols/compositor.rs b/crates/wayland/src/protocols/compositor.rs
new file mode 100644
index 0000000..f7e7b74
--- /dev/null
+++ b/crates/wayland/src/protocols/compositor.rs
@@ -0,0 +1,182 @@
+//! `wl_compositor`/`wl_surface`: surface creation and the per-commit
+//! bookkeeping every other protocol handler in this module tree depends on
+//! (window mapping, layer-surface visibility, popup lifecycle).
+
+use smithay::reexports::wayland_server::protocol::wl_surface::WlSurface;
+use smithay::reexports::wayland_server::Client;
+use smithay::wayland::compositor::{add_pre_commit_hook, with_states, CompositorClientState, CompositorHandler, CompositorState};
+use smithay::wayland::shell::wlr_layer::LayerSurfaceCachedState;
+
+use crate::state::{ClientState, CompState};
+
+impl CompositorHandler for CompState {
+    fn compositor_state(&mut self) -> &mut CompositorState {
+        &mut self.compositor_state
+    }
+
+    fn client_compositor_state<'a>(&self, client: &'a Client) -> &'a CompositorClientState {
+        // Two possible client kinds now: our own `ClientState` for regular
+        // Wayland clients, or smithay's `XWaylandClientData` for the single
+        // XWayland client (see `xwayland.rs`) - both carry a
+        // `CompositorClientState`, just under different wrapper types.
+        if let Some(state) = client.get_data::<ClientState>() {
+            return &state.compositor_state;
+        }
+        &client.get_data::<smithay::xwayland::XWaylandClientData>().expect("client is neither ours nor XWayland's").compositor_state
+    }
+
+    /// Workaround for a real smithay bug (see docs/PANEL_SUPPORT_TODO.md and
+    /// `layer_destroyed` below): destroying a `zwlr_layer_surface_v1` role
+    /// resets the surface's `LayerSurfaceCachedState` to
+    /// `Default::default()` (size 0x0, no anchor) rather than removing it,
+    /// but the pre-commit hook smithay itself registers at
+    /// `get_layer_surface` time keeps validating that state against every
+    /// future commit regardless of whether the role still exists --
+    /// tripping its own `width/height 0 requested without ... anchors`
+    /// check and posting `invalid_size`, which kills the client's whole
+    /// connection over what is protocol-legal (committing a now-roleless
+    /// surface).
+    ///
+    /// Fixed by registering our own pre-commit hook here, in `new_surface`
+    /// - called at `wl_compositor.create_surface`, strictly before any
+    /// later `get_layer_surface` on the same surface could register
+    /// smithay's own hook. Hooks run in registration order (`tree.rs`:
+    /// `pre_commit_hooks` is a plain `Vec`, pushed and iterated in order),
+    /// so ours always runs first and can neutralize the stale reset state
+    /// before smithay's hook ever inspects it. This depends on that
+    /// ordering guarantee holding in future smithay versions - it isn't
+    /// documented as an API contract, just an implementation detail
+    /// confirmed against 0.7.0's source - so re-check this file against
+    /// whatever smithay version replaces it.
+    ///
+    /// Cost: one closure registered per `wl_surface` (not just layer
+    /// surfaces, since we don't know in advance which ones will become
+    /// one), each a no-op unless that exact surface is in
+    /// `dead_layer_surfaces`.
+    fn new_surface(&mut self, surface: &WlSurface) {
+        add_pre_commit_hook::<CompState, _>(surface, |state, _dh, surface| {
+            if !state.dead_layer_surfaces.contains(surface) {
+                return;
+            }
+            with_states(surface, |states| {
+                let mut cached = states.cached_state.get::<LayerSurfaceCachedState>();
+                let pending = cached.pending();
+                if pending.size.w == 0 && !pending.anchor.anchored_horizontally() {
+                    pending.size.w = 1;
+                }
+                if pending.size.h == 0 && !pending.anchor.anchored_vertically() {
+                    pending.size.h = 1;
+                }
+            });
+        });
+    }
+
+    fn commit(&mut self, surface: &WlSurface) {
+        smithay::backend::renderer::utils::on_commit_buffer_handler::<CompState>(surface);
+        // XWayland's association of an X11 window with this wl_surface can
+        // arrive at any point relative to the map request (see
+        // `xwayland.rs`'s module docs); `surface_associated` handles the
+        // common ordering, this retries the surfaces still waiting on a
+        // commit to actually make that association queryable.
+        self.retry_pending_x11_windows();
+        if let Some(&id) = self.surface_to_id.get(surface) {
+            if let Some(w) = self.id_to_window.get(&id) {
+                w.on_commit();
+            }
+            // See `content_epoch`'s doc comment: this is the only per-commit
+            // signal the udev backend's rounded-corner mask cache has to
+            // invalidate itself, since content can change every frame,
+            // independent of the geometry-driven points `redraw_decoration_
+            // buffer` already runs at.
+            *self.content_epoch.entry(id).or_insert(0) += 1;
+            crate::state::sync_toplevel_metadata(self, id, surface);
+            // `redraw_decoration_buffer` reads `dwindow.geometry()` (via
+            // `effective_frame`) to size the border/titlebar/shadow against
+            // what the client's surface *really* committed - but nothing
+            // updates that value except this very commit
+            // (`on_commit()` above). Without a call here, a client whose
+            // first real commit settles at a different size than what was
+            // requested (a terminal snapping to a whole character-cell
+            // grid) wouldn't get corrected decoration until some unrelated
+            // trigger (a resize, a focus change) happened to call this
+            // again - cheap regardless, since the signature check inside
+            // makes every commit that didn't actually change the *visible*
+            // size an early return, not a real rebuild.
+            self.redraw_decoration_buffer(id);
+            // `sync_geometry` is what actually maps this window into
+            // `self.space` at `geom.x - content_offset.x, ...` - the same
+            // `content_offset` (`dwindow.geometry().loc`) the render loop
+            // (`udev/render.rs`'s per-frame `pos` computation) reads fresh
+            // on every single frame, straight off the live surface, not
+            // from any cache. Before this call existed here, `self.space`
+            // only got a fresh position from whichever *other* trigger last
+            // called `sync_geometry` (a resize, `maximize_request`, a
+            // decoration-mode change) - so a client that recommits a
+            // *different* `xdg_surface::set_window_geometry` on its own,
+            // with no accompanying resize (a GTK4/Firefox CSD window
+            // shrinking its declared shadow margin once real content
+            // replaces its first, provisional paint, concretely), left
+            // `self.space`'s cached position silently stale while the
+            // render loop kept self-correcting every frame - confirmed
+            // live via temporary diagnostic logging: a window's real render
+            // position and `self.space`'s own `element_under`-reported
+            // position for it disagreed by exactly one `content_offset`,
+            // 10 physical pixels on both axes for the Firefox window that
+            // exposed it. `refresh_pointer_focus`'s content-click path
+            // (`input.rs`) computes `win_relative` from *that* stale
+            // position, not the render loop's fresh one - every click on
+            // such a window was silently off by the same 10px the whole
+            // time it stayed unmapped-and-remapped-by-nothing-else, which
+            // reads as "clicks land near, but not on, whatever's visibly
+            // there" - worst for a window's own small CSD buttons,
+            // exactly what was reported live. Same idempotent-when-nothing-
+            // moved shape as `redraw_decoration_buffer` above: `map_element`
+            // itself is unconditional and cheap (a hashmap insert), and the
+            // one potentially-expensive part - sending a fresh
+            // `xdg_toplevel::configure` - stays gated on `size_changed`
+            // and the existing throttle, both untouched, so a commit that
+            // didn't change size never sends one just because this call is
+            // now here too.
+            self.sync_geometry(id);
+        } else {
+            // `surface` itself isn't a tracked window's root, but may be a
+            // descendant (subsurface) of one - a real commit still
+            // happened, just not on the surface `surface_to_id` keys off.
+            // `masked_content_buffer`'s own resolver
+            // (`rounded_corners_pixman::resolve_content_surface`) reads a
+            // *child* subsurface's buffer directly for the common GTK4/
+            // WebRender pattern (confirmed live: Firefox), so a repaint
+            // that only ever commits that child - which is the normal
+            // case, that's where the real content lives - must still
+            // bump this window's own `content_epoch`, or the masked-
+            // corner cache never sees a reason to invalidate and freezes
+            // on whatever the first frame happened to show. Bounded to a
+            // handful of hops purely as a safety net against a malformed
+            // subsurface tree looping back on itself - a real one is
+            // never more than one or two levels deep.
+            let mut ancestor = smithay::wayland::compositor::get_parent(surface);
+            for _ in 0..8 {
+                let Some(parent) = ancestor else { break };
+                if let Some(&id) = self.surface_to_id.get(&parent) {
+                    *self.content_epoch.entry(id).or_insert(0) += 1;
+                    break;
+                }
+                ancestor = smithay::wayland::compositor::get_parent(&parent);
+            }
+        }
+        // Before `ensure_layer_initial_configure`: if this commit just
+        // hid or re-showed a layer surface, `sync_layer_visibility` needs
+        // to unmap/re-map it first, so the lookup that function does via
+        // `layer_for_surface` sees the corrected state rather than acting
+        // on stale membership in `LayerMap`'s own list.
+        self.sync_layer_visibility(surface);
+        self.ensure_layer_initial_configure(surface);
+        // Advances a just-created popup from unmapped to mapped (needed for
+        // `PopupManager::popups_for_surface`, which `popup_render_elements`
+        // reads at render time) and prunes dead ones. Cheap and only does
+        // real work on a popup-role surface, so doing it on every commit
+        // rather than throttling is not worth the extra bookkeeping.
+        self.popups.commit(surface);
+        self.popups.cleanup();
+    }
+}
diff --git a/crates/wayland/src/protocols/idle.rs b/crates/wayland/src/protocols/idle.rs
new file mode 100644
index 0000000..a554453
--- /dev/null
+++ b/crates/wayland/src/protocols/idle.rs
@@ -0,0 +1,35 @@
+//! `ext_idle_notify_v1` + `zwp_idle_inhibit_manager_v1`.
+
+use smithay::reexports::wayland_server::protocol::wl_surface::WlSurface;
+
+use crate::state::CompState;
+
+/// `ext_idle_notify_v1`. All the real logic (per-notification timers,
+/// resetting them on activity, honouring inhibition) already lives in
+/// smithay's own `IdleNotifierState` - this is just the getter it needs.
+/// See `input.rs`'s `notify_idle_activity` for the other half: nothing
+/// calls `notify_activity` on its own, that has to happen from every real
+/// input path.
+impl smithay::wayland::idle_notify::IdleNotifierHandler for CompState {
+    fn idle_notifier_state(&mut self) -> &mut smithay::wayland::idle_notify::IdleNotifierState<Self> {
+        &mut self.idle_notifier_state
+    }
+}
+
+/// `zwp_idle_inhibit_manager_v1`. A video player (or anything else that
+/// wants the screen to stay on/unlocked while it runs) creates one of
+/// these tied to its own surface; as long as at least one is alive,
+/// `IdleNotifierState::set_is_inhibited` stops idle timers from firing at
+/// all - see `idle_inhibiting_surfaces`'s doc comment on `CompState` for
+/// the one simplification (not workspace-visibility-aware) this takes.
+impl smithay::wayland::idle_inhibit::IdleInhibitHandler for CompState {
+    fn inhibit(&mut self, surface: WlSurface) {
+        self.idle_inhibiting_surfaces.push(surface);
+        self.idle_notifier_state.set_is_inhibited(true);
+    }
+
+    fn uninhibit(&mut self, surface: WlSurface) {
+        self.idle_inhibiting_surfaces.retain(|s| s != &surface);
+        self.idle_notifier_state.set_is_inhibited(!self.idle_inhibiting_surfaces.is_empty());
+    }
+}
diff --git a/crates/wayland/src/protocols/input_method.rs b/crates/wayland/src/protocols/input_method.rs
new file mode 100644
index 0000000..525383f
--- /dev/null
+++ b/crates/wayland/src/protocols/input_method.rs
@@ -0,0 +1,86 @@
+//! `zwp_text_input_manager_v3` + `zwp_input_method_manager_v2`: lets a real
+//! input method (fcitx5, ibus, any CJK/dead-key/emoji-picker IME) attach to
+//! whichever surface has keyboard focus and draw its own candidate/
+//! composition popup. Without these two globals a client that only speaks
+//! text-input (most modern toolkits do, GTK4/Qt6 included) has no way to
+//! tell the compositor "I have an editable text field, here is its cursor
+//! rectangle" - every desktop app's search box, address bar, and chat
+//! input silently loses IME support, not just an edge case.
+//!
+//! Focus tracking needs *no* wiring here at all: `CompState::KeyboardFocus`
+//! is a plain `WlSurface`, and smithay's own blanket `impl KeyboardTarget
+//! for WlSurface` already calls `seat.text_input().set_focus/.enter()/
+//! .leave()` and `seat.input_method().activate_input_method()/
+//! deactivate_input_method()` from inside `enter`/`leave` - which
+//! `set_keyboard_focus`'s existing `keyboard.set_focus(...)` call already
+//! triggers on every real focus change. The only things actually missing
+//! were the two manager globals and this handler for the popup surface
+//! lifecycle.
+
+use smithay::desktop::PopupKind;
+use smithay::reexports::wayland_server::protocol::wl_surface::WlSurface;
+use smithay::wayland::input_method::PopupSurface as ImePopupSurface;
+
+use crate::state::CompState;
+
+impl smithay::wayland::input_method::InputMethodHandler for CompState {
+    /// A candidate/composition window (an emoji picker, a CJK candidate
+    /// list) just opened. Tracked as a regular [`PopupKind::InputMethod`]
+    /// in the same [`PopupManager`](smithay::desktop::PopupManager) that
+    /// already owns every `xdg_popup` - `elements::popup_render_elements`
+    /// renders both kinds identically, so no separate render path is
+    /// needed for this to actually become visible.
+    fn new_popup(&mut self, surface: ImePopupSurface) {
+        if let Err(e) = self.popups.track_popup(PopupKind::from(surface)) {
+            log::warn!("input-method: failed to track popup: {e}");
+        }
+    }
+
+    fn dismiss_popup(&mut self, surface: ImePopupSurface) {
+        if let Some(parent) = surface.get_parent().map(|p| p.surface.clone()) {
+            let _ = smithay::desktop::PopupManager::dismiss_popup(&parent, &PopupKind::from(surface));
+        }
+    }
+
+    /// The IME moved its own popup (e.g. following the text cursor as the
+    /// user types) - `PopupSurface::location()` already reflects the new
+    /// position; nothing else needs updating on this side, matching every
+    /// other smithay-based compositor's own no-op here.
+    fn popup_repositioned(&mut self, _surface: ImePopupSurface) {}
+
+    /// Where the IME should anchor its popup, in the parent surface's own
+    /// output-independent (logical, window-relative-origin) space - same
+    /// geometry `elements::popup_targets` already computes for xdg popups,
+    /// reused here rather than duplicated. A window not yet tracked (the
+    /// activation raced ahead of its own mapping) gets a default/zero rect,
+    /// same "no-op rather than an error" stance as `request_activation`
+    /// above.
+    fn parent_geometry(&self, parent: &WlSurface) -> smithay::utils::Rectangle<i32, smithay::utils::Logical> {
+        let Some(&id) = self.surface_to_id.get(parent) else {
+            return smithay::utils::Rectangle::default();
+        };
+        let (geometry, decorated) = {
+            let wm = self.wm.borrow();
+            let Some(w) = wm.window(id) else {
+                return smithay::utils::Rectangle::default();
+            };
+            (w.geometry, w.decorated)
+        };
+        let band = if decorated { srdwm_core::TITLEBAR_HEIGHT as i32 } else { 0 };
+        // `content_offset`/`effective_frame`: same corrections every other
+        // real position/size computation in this codebase applies (see
+        // `state/geometry.rs::effective_frame`'s doc comment) - missed
+        // here originally, so an IME popup anchored against a CSD window's
+        // raw, unshifted geometry instead of its real visible content,
+        // same class of drift as the border/screenshot gaps fixed
+        // elsewhere.
+        let content_offset = self.id_to_window.get(&id).map(|w| w.geometry().loc).unwrap_or_default();
+        // `frame.height` includes the titlebar band (see `effective_frame`'s
+        // own doc comment) - subtracted back out here since this rect is
+        // meant to cover the content area only, matching the original
+        // (pre-fix) code's own intent for `w.geometry.height`.
+        let frame = self.effective_frame(id, geometry);
+        let content_height = (frame.height as i32 - band).max(0);
+        smithay::utils::Rectangle::new((frame.x - content_offset.x, frame.y + band - content_offset.y).into(), (frame.width as i32, content_height).into())
+    }
+}
diff --git a/crates/wayland/src/protocols/layer_shell.rs b/crates/wayland/src/protocols/layer_shell.rs
new file mode 100644
index 0000000..931ddb4
--- /dev/null
+++ b/crates/wayland/src/protocols/layer_shell.rs
@@ -0,0 +1,117 @@
+//! `zwlr_layer_shell_v1`: panels, bars, launchers, and other output-anchored
+//! shell surfaces (AGS's own bar and popups, notably).
+
+use smithay::desktop::{layer_map_for_output, LayerSurface as DesktopLayerSurface};
+use smithay::reexports::wayland_server::protocol::wl_output::WlOutput;
+use smithay::reexports::wayland_server::Resource;
+use smithay::wayland::shell::wlr_layer::{Layer, LayerSurface as WlrLayerSurface, WlrLayerShellHandler, WlrLayerShellState};
+
+use crate::state::CompState;
+
+impl WlrLayerShellHandler for CompState {
+    fn shell_state(&mut self) -> &mut WlrLayerShellState {
+        &mut self.layer_shell_state
+    }
+
+    fn new_layer_surface(&mut self, surface: WlrLayerSurface, wl_output: Option<WlOutput>, _layer: Layer, namespace: String) {
+        // Logged before anything else can early-return or panic: the
+        // question this answers (see docs/PANEL_SUPPORT_TODO.md) is
+        // whether this handler is reached AT ALL for a later
+        // `get_layer_surface` request in a create -> commit -> destroy ->
+        // commit-again -> create sequence, or whether the client's
+        // dispatch is already dead by then and this never runs.
+        log::debug!("layer-shell: new_layer_surface entered, surface={:?} namespace={namespace:?} output_named={}", surface.wl_surface().id(), wl_output.is_some());
+        // A client may name the output it wants (a bar on a specific
+        // monitor); if it doesn't, or names one we don't drive, it lands on
+        // the primary output.
+        let output = wl_output
+            .as_ref()
+            .and_then(|wl| self.output_for_wl(wl))
+            .map(|e| e.output.clone())
+            .or_else(|| self.primary_output().cloned());
+        let Some(output) = output else {
+            log::warn!("wayland: layer surface requested but no output exists yet");
+            return;
+        };
+        // Paired with the debug log in `ensure_layer_initial_configure`'s
+        // early return - see docs/PANEL_SUPPORT_TODO.md's P0. This is the
+        // other half of "did map_layer actually succeed, and on which
+        // output": logged unconditionally (not just on the error paths
+        // that already existed) so a real reproduction shows both sides of
+        // the handoff instead of just the failure.
+        let surface_id = surface.wl_surface().id();
+        let layer_surface = DesktopLayerSurface::new(surface, namespace);
+        let result = layer_map_for_output(&output).map_layer(&layer_surface);
+        match &result {
+            Ok(()) => log::debug!("layer-shell: mapped surface {surface_id:?} onto output {}", output.name()),
+            Err(e) => log::warn!("wayland: failed to map layer surface {surface_id:?}: {e}"),
+        }
+    }
+
+    fn layer_destroyed(&mut self, surface: WlrLayerSurface) {
+        // See the matching top-of-function log in `new_layer_surface`.
+        log::debug!("layer-shell: layer_destroyed entered, surface={:?}", surface.wl_surface().id());
+        // Marks this surface for the pre-commit-hook workaround in
+        // `new_surface` - see that function's doc comment for the bug
+        // this exists to route around.
+        self.dead_layer_surfaces.insert(surface.wl_surface().clone());
+        // GTK (confirmed live via an AGS peer session's WAYLAND_DEBUG trace)
+        // reuses the same `wl_surface` for the next `get_layer_surface` role
+        // rather than creating a fresh one - so without this, a "shown at
+        // least once" flag from *this* role would leak onto the next one
+        // and make `sync_layer_visibility` treat that new role's own
+        // ack-configure commit as eligible to hide again, the same bug
+        // `layer_surfaces_shown_once` exists to prevent, just reintroduced
+        // for exactly the reused-surface case that matters here.
+        self.layer_surfaces_shown_once.remove(surface.wl_surface());
+        // The surface belongs to exactly one output's map, but which one is
+        // the client's choice, so unmap from whichever holds it.
+        for output in self.outputs().cloned().collect::<Vec<_>>() {
+            let mut map = layer_map_for_output(&output);
+            let found = map.layers().find(|l| l.layer_surface() == &surface).cloned();
+            if let Some(layer) = found {
+                // Same zone-change recompute `ensure_layer_initial_configure`
+                // already does on every commit that changes a layer's
+                // exclusive zone (state/layers.rs) - but this is the *only* place
+                // that ever runs for a surface that goes away without one
+                // last commit. `unmap_layer` alone doesn't trigger it:
+                // reported live (by the AGS peer session) as a bar unmapping
+                // for fullscreen yet `srd monitors` still reporting the
+                // bar's old reserved_top for as long as fullscreen lasted --
+                // harmless there only because fullscreen targets
+                // `full_geometry`, which ignores the reservation anyway, but
+                // wrong for anything that reads `usable`/`geometry` while a
+                // bar is unmapped without exiting cleanly (a crash, not just
+                // AGS's cooperative fullscreen hide).
+                let zone_before = map.non_exclusive_zone();
+                map.unmap_layer(&layer);
+                let zone_after = map.non_exclusive_zone();
+                if zone_after != zone_before {
+                    self.pending.borrow_mut().push(srdwm_core::Event::MonitorAdded(srdwm_core::Monitor::new(0, "", srdwm_core::Rect::new(0, 0, 0, 0))));
+                }
+                break;
+            }
+        }
+        // A lock/launcher surface holding exclusive keyboard focus just
+        // vanished (crash, or a normal close) - don't leave focus dangling
+        // on a dead surface.
+        //
+        // `sync_keyboard_focus`, not a bare `set_keyboard_focus(None)`: an
+        // `OnDemand` layer surface (a launcher/quicksettings/datemenu
+        // popup, per `wlr-layer-shell`) claiming focus on click
+        // (`input.rs`'s `on_demand` branch) goes straight through
+        // `set_keyboard_focus` without ever touching `WindowManager::
+        // focused` - core has no concept of a layer surface to focus, so
+        // it still correctly points at whatever real toplevel was focused
+        // before the popup opened. Hardcoding `None` here threw that away
+        // regardless, leaving nothing focused until the user happened to
+        // click a window again - reported live (an AGS peer session's
+        // user) as "focus never returns after using the bar". `sync_
+        // keyboard_focus` reads that still-correct core state and restores
+        // real Wayland focus to it, falling through to `None` only if core
+        // genuinely has nothing focused either.
+        if self.seat.get_keyboard().and_then(|k| k.current_focus()).as_ref() == Some(surface.wl_surface()) {
+            crate::input::sync_keyboard_focus(self);
+        }
+    }
+}
diff --git a/crates/wayland/src/protocols/misc.rs b/crates/wayland/src/protocols/misc.rs
new file mode 100644
index 0000000..7999ec3
--- /dev/null
+++ b/crates/wayland/src/protocols/misc.rs
@@ -0,0 +1,30 @@
+//! Small protocol handlers whose entire implementation is smithay's own
+//! no-op default - the global still has to exist for clients that treat it
+//! as mandatory, but there's nothing for this compositor to do in response.
+
+use smithay::wayland::tablet_manager::TabletSeatHandler;
+
+use crate::state::CompState;
+
+impl smithay::wayland::output::OutputHandler for CompState {}
+
+/// `wp_cursor_shape_v1`: lets a client ask for a *named* cursor (text,
+/// grab, resize edges, ...) instead of rendering and attaching its own
+/// surface. Its requests route straight into `SeatHandler::cursor_image`
+/// (see `seat.rs`), same as a client-drawn cursor surface does - no extra
+/// state on our side. Without this global at all, a client that only speaks
+/// this (increasingly the norm - recent GTK4/Firefox use it for most
+/// cursor changes) has no way to tell us the pointer should look like
+/// anything but whatever it last was, which reads as the cursor going
+/// stale, wrong, or simply disappearing depending on what was showing when
+/// the client gave up trying.
+///
+/// `TabletSeatHandler` is a supertrait bound of this protocol's `Dispatch`
+/// impl (cursor-shape covers tablet tools too); srdwm has no tablet
+/// support to speak of, so every method is left at its no-op default.
+impl TabletSeatHandler for CompState {}
+
+/// Fractional scaling. srdwm runs every output at scale 1, so there is
+/// nothing to compute - but the global has to exist, because clients that
+/// use it (notably wallpaper daemons) treat it as mandatory.
+impl smithay::wayland::fractional_scale::FractionalScaleHandler for CompState {}
diff --git a/crates/wayland/src/protocols/seat.rs b/crates/wayland/src/protocols/seat.rs
new file mode 100644
index 0000000..bd7ae4c
--- /dev/null
+++ b/crates/wayland/src/protocols/seat.rs
@@ -0,0 +1,31 @@
+//! `wl_seat`: keyboard/pointer/touch focus types and the client-set cursor
+//! image.
+
+use smithay::input::pointer::CursorImageStatus;
+use smithay::input::{Seat, SeatHandler, SeatState};
+use smithay::reexports::wayland_server::protocol::wl_surface::WlSurface;
+
+use crate::state::CompState;
+
+impl SeatHandler for CompState {
+    type KeyboardFocus = WlSurface;
+    type PointerFocus = WlSurface;
+    type TouchFocus = WlSurface;
+
+    fn seat_state(&mut self) -> &mut SeatState<Self> {
+        &mut self.seat_state
+    }
+
+    fn focus_changed(&mut self, _seat: &Seat<Self>, _focused: Option<&WlSurface>) {}
+    /// Clients set their own cursor (an I-beam over text, a hand over a
+    /// link). Recorded here and drawn by the render paths - on a bare TTY
+    /// nothing else would draw it. See `cursor.rs`.
+    fn cursor_image(&mut self, _seat: &Seat<Self>, image: CursorImageStatus) {
+        self.cursor_status = image;
+        // The client has now explicitly claimed the cursor - see
+        // `decoration_cursor_active`'s own doc comment and `input.rs::
+        // update_cursor_shape` for why this has to be tracked separately
+        // from just overwriting `cursor_status`.
+        self.decoration_cursor_active = false;
+    }
+}
diff --git a/crates/wayland/src/protocols/selection.rs b/crates/wayland/src/protocols/selection.rs
new file mode 100644
index 0000000..fadb0ca
--- /dev/null
+++ b/crates/wayland/src/protocols/selection.rs
@@ -0,0 +1,52 @@
+//! Clipboard/primary-selection/drag-and-drop.
+//!
+//! All three selection protocols below (`wl_data_device_manager`,
+//! `zwp_primary_selection_v1`, `zwlr_data_control_manager_v1`) share
+//! smithay's single `SelectionHandler`. Every transfer here is
+//! *client-to-client*: one client owns the selection and writes the bytes
+//! itself, and smithay wires the two ends together without the data passing
+//! through us. `send_selection` is only ever called for a
+//! **compositor-provided** selection (one this WM set itself via
+//! `set_data_device_selection`), which srdwm never does - so it is
+//! deliberately left unimplemented rather than faked.
+
+use smithay::wayland::selection::data_device::{ClientDndGrabHandler, DataDeviceHandler, DataDeviceState, ServerDndGrabHandler};
+use smithay::wayland::selection::primary_selection::{PrimarySelectionHandler, PrimarySelectionState};
+use smithay::wayland::selection::wlr_data_control::{DataControlHandler, DataControlState};
+use smithay::wayland::selection::SelectionHandler;
+
+use crate::state::CompState;
+
+impl SelectionHandler for CompState {
+    type SelectionUserData = ();
+}
+
+impl DataDeviceHandler for CompState {
+    fn data_device_state(&self) -> &DataDeviceState {
+        &self.data_device_state
+    }
+}
+
+// Drag-and-drop: the default trait methods already do the right thing for a
+// compositor that doesn't draw its own drag icon or offer server-side drag
+// sources - smithay runs the pointer grab and the offer/accept negotiation
+// internally. Both are implemented empty (rather than skipped) because
+// `DataDeviceHandler` requires them as supertraits.
+impl ClientDndGrabHandler for CompState {}
+impl ServerDndGrabHandler for CompState {}
+
+impl PrimarySelectionHandler for CompState {
+    fn primary_selection_state(&self) -> &PrimarySelectionState {
+        &self.primary_selection_state
+    }
+}
+
+/// `zwlr_data_control_manager_v1`: lets a client read/watch the selection
+/// without ever holding keyboard focus. This is what `wl-paste --watch`
+/// (and thus `cliphist store`, which the user's session autostarts) needs
+/// - a focus-following clipboard manager is impossible without it.
+impl DataControlHandler for CompState {
+    fn data_control_state(&self) -> &DataControlState {
+        &self.data_control_state
+    }
+}
diff --git a/crates/wayland/src/protocols/xdg_activation.rs b/crates/wayland/src/protocols/xdg_activation.rs
new file mode 100644
index 0000000..846a213
--- /dev/null
+++ b/crates/wayland/src/protocols/xdg_activation.rs
@@ -0,0 +1,36 @@
+//! `xdg_activation_v1`: a launcher hands a spawned app a token, and the
+//! app's own first window presents it back to ask to be raised and focused.
+
+use smithay::reexports::wayland_server::protocol::wl_surface::WlSurface;
+use smithay::wayland::xdg_activation::{XdgActivationHandler, XdgActivationState, XdgActivationToken, XdgActivationTokenData};
+
+use crate::state::CompState;
+
+impl XdgActivationHandler for CompState {
+    fn activation_state(&mut self) -> &mut XdgActivationState {
+        &mut self.xdg_activation_state
+    }
+
+    /// A launcher spawns an app after first getting a token
+    /// (`get_activation_token`) and handing it to the new process (usually
+    /// via `XDG_ACTIVATION_TOKEN`); the app's own first window then
+    /// presents that same token back here via `activate`, asking to be
+    /// raised. Without this, that request was silently ignored - the new
+    /// window opened and just sat there unfocused behind everything,
+    /// exactly the gap `docs/PANEL_SUPPORT_TODO.md`'s P1 flagged.
+    ///
+    /// No token bookkeeping of our own: `token_created`'s default already
+    /// accepts every token (fine for a single-user session with no
+    /// cross-client trust boundary to enforce), so all that's left is
+    /// mapping the activating `surface` to a `WindowId` and reusing the
+    /// exact same `focus_window` path a dock's "activate" request already
+    /// goes through (`foreign_toplevel.rs`). If the surface isn't tracked
+    /// yet - the activation raced ahead of this window's own mapping --
+    /// there is nothing to focus yet, so this is a no-op rather than an
+    /// error; the protocol doesn't require honoring every activation.
+    fn request_activation(&mut self, _token: XdgActivationToken, _token_data: XdgActivationTokenData, surface: WlSurface) {
+        if let Some(&id) = self.surface_to_id.get(&surface) {
+            crate::input::focus_window(self, id);
+        }
+    }
+}
diff --git a/crates/wayland/src/protocols/xdg_decoration.rs b/crates/wayland/src/protocols/xdg_decoration.rs
new file mode 100644
index 0000000..25973c0
--- /dev/null
+++ b/crates/wayland/src/protocols/xdg_decoration.rs
@@ -0,0 +1,63 @@
+//! `zxdg_decoration_manager_v1`: negotiates whether a toplevel draws its own
+//! (client-side) chrome or lets us draw it (server-side).
+
+use smithay::reexports::wayland_protocols::xdg::decoration::zv1::server::zxdg_toplevel_decoration_v1::Mode as DecorationMode;
+use smithay::wayland::shell::xdg::decoration::XdgDecorationHandler;
+use smithay::wayland::shell::xdg::ToplevelSurface;
+
+use crate::state::CompState;
+
+impl XdgDecorationHandler for CompState {
+    /// Offers whichever mode `theme.decorations.default_mode`/`srd set
+    /// decoration_mode` currently prefers - a client with a real opinion
+    /// of its own still overrides this via `request_mode` below regardless
+    /// of what's offered here; this only decides what a client with *no*
+    /// preference ends up with. See `srdwm_core::ThemeConfig::
+    /// default_decorated`'s own doc comment for why this is configurable
+    /// rather than hardcoded to one mode.
+    fn new_decoration(&mut self, toplevel: ToplevelSurface) {
+        let offer = if self.wm.borrow().theme.default_decorated { DecorationMode::ServerSide } else { DecorationMode::ClientSide };
+        toplevel.with_pending_state(|state| {
+            state.decoration_mode = Some(offer);
+        });
+    }
+
+    /// Honors whichever mode the client actually asked for, rather than
+    /// always forcing server-side - and mirrors the result into our own
+    /// `Window.decorated`, so a client drawing its own titlebar doesn't
+    /// *also* get one drawn on top of it by us.
+    ///
+    /// Always forcing `ServerSide` (what this used to do) is why some
+    /// clients ended up with two sets of window buttons: Firefox requests
+    /// client-side decoration when its own "use system titlebar" setting
+    /// is off, and draws its own close/minimize/maximize row regardless of
+    /// what the compositor grants - so forcing server-side just added
+    /// srdwm's row on top of the one Firefox was drawing anyway, instead
+    /// of preventing it. Respecting the request means srdwm steps out of
+    /// the way for exactly those clients, while everything that accepts
+    /// (or has no preference and gets offered) server-side still gets our
+    /// titlebar as before.
+    fn request_mode(&mut self, toplevel: ToplevelSurface, mode: DecorationMode) {
+        toplevel.with_pending_state(|state| {
+            state.decoration_mode = Some(mode);
+        });
+        toplevel.send_configure();
+        self.set_decorated_from_mode(toplevel.wl_surface(), mode == DecorationMode::ServerSide);
+    }
+
+    /// The client dropped its decoration-mode preference. `new_decoration`
+    /// already offers the configured default as the mode the next
+    /// configure will carry, so mirror that same default here rather than
+    /// leaving whatever mode was negotiated before this - otherwise a
+    /// client that requests one mode, then later unsets it expecting the
+    /// default back, would stay stuck in that mode forever.
+    fn unset_mode(&mut self, toplevel: ToplevelSurface) {
+        let default_decorated = self.wm.borrow().theme.default_decorated;
+        let mode = if default_decorated { DecorationMode::ServerSide } else { DecorationMode::ClientSide };
+        toplevel.with_pending_state(|state| {
+            state.decoration_mode = Some(mode);
+        });
+        toplevel.send_configure();
+        self.set_decorated_from_mode(toplevel.wl_surface(), default_decorated);
+    }
+}
diff --git a/crates/wayland/src/protocols/xdg_shell.rs b/crates/wayland/src/protocols/xdg_shell.rs
new file mode 100644
index 0000000..4fe0f6f
--- /dev/null
+++ b/crates/wayland/src/protocols/xdg_shell.rs
@@ -0,0 +1,258 @@
+//! `xdg_shell`: toplevel and popup lifecycle, and the client-initiated
+//! move/resize/maximize/fullscreen/minimize requests a CSD client sends
+//! instead of (or alongside) the pointer-driven titlebar handlers in
+//! `input.rs`.
+
+use smithay::desktop::{find_popup_root_surface, PopupKeyboardGrab, PopupKind, PopupPointerGrab};
+use smithay::input::pointer::Focus;
+use smithay::reexports::wayland_protocols::xdg::shell::server::xdg_toplevel;
+use smithay::reexports::wayland_server::protocol::wl_output::WlOutput;
+use smithay::reexports::wayland_server::protocol::wl_seat;
+use smithay::reexports::wayland_server::Resource;
+use smithay::utils::Serial;
+use smithay::wayland::shell::xdg::{PopupSurface, PositionerState, ToplevelSurface, XdgShellHandler, XdgShellState};
+
+use crate::state::CompState;
+
+impl XdgShellHandler for CompState {
+    fn xdg_shell_state(&mut self) -> &mut XdgShellState {
+        &mut self.xdg_shell_state
+    }
+
+    fn new_toplevel(&mut self, surface: ToplevelSurface) {
+        self.new_managed_window(surface);
+    }
+
+    /// `move_request`/`resize_request` were also still smithay's default
+    /// no-op implementations - a much larger gap than the five below:
+    /// this is *how a client-side-decorated window gets dragged or resized
+    /// by its own titlebar/edges at all*. A window we draw our own
+    /// decoration for never needed this (`TitlebarHit::Drag`/`Resize` in
+    /// `input.rs` detect the click directly, since we own those pixels),
+    /// but a window that negotiated client-side decoration and draws its
+    /// own titlebar - Firefox, and most GTK4 apps by default - handles
+    /// the click itself and then asks the compositor to actually perform
+    /// the move/resize via exactly these two requests. Left unimplemented,
+    /// dragging or resizing any such window by its own chrome did
+    /// nothing at all - the only way to reposition it was the
+    /// modifier+drag-anywhere gesture (`bindm`), which most users have no
+    /// reason to know exists and doesn't work for resize-from-a-specific-
+    /// edge at all. Reuses the exact same `WindowManager::start_drag`/
+    /// `start_resize` the pointer-driven titlebar handlers call --
+    /// `handle_pointer_position`/`handle_pointer_button` already drive any
+    /// in-progress drag/resize to completion on subsequent motion/release
+    /// regardless of what started it, so no smithay pointer grab is
+    /// needed here at all, just the same start call from a different
+    /// trigger.
+    fn move_request(&mut self, surface: ToplevelSurface, _seat: wl_seat::WlSeat, _serial: Serial) {
+        // Temporary: added to trace a live report that dragging a CSD
+        // window (Firefox) by its own tab strip/header bar does nothing --
+        // this is the only way to tell "the client never sent xdg_toplevel
+        // ::move at all" apart from "it sent it and something downstream
+        // of here didn't follow through." Remove once that's settled.
+        match self.surface_to_id.get(surface.wl_surface()) {
+            Some(&id) => {
+                let pos = crate::input::last_pointer_pos(self);
+                log::info!("move_request: window {id:?} at pointer {pos:?}");
+                self.wm.borrow_mut().start_drag(id, pos.x as i32, pos.y as i32);
+            }
+            None => log::warn!("move_request: surface has no tracked window id"),
+        }
+    }
+
+    fn resize_request(&mut self, surface: ToplevelSurface, _seat: wl_seat::WlSeat, _serial: Serial, edges: xdg_toplevel::ResizeEdge) {
+        let Some(edge) = (match edges {
+            xdg_toplevel::ResizeEdge::Top => Some(srdwm_core::ResizeEdge::Top),
+            xdg_toplevel::ResizeEdge::Bottom => Some(srdwm_core::ResizeEdge::Bottom),
+            xdg_toplevel::ResizeEdge::Left => Some(srdwm_core::ResizeEdge::Left),
+            xdg_toplevel::ResizeEdge::Right => Some(srdwm_core::ResizeEdge::Right),
+            xdg_toplevel::ResizeEdge::TopLeft => Some(srdwm_core::ResizeEdge::TopLeft),
+            xdg_toplevel::ResizeEdge::TopRight => Some(srdwm_core::ResizeEdge::TopRight),
+            xdg_toplevel::ResizeEdge::BottomLeft => Some(srdwm_core::ResizeEdge::BottomLeft),
+            xdg_toplevel::ResizeEdge::BottomRight => Some(srdwm_core::ResizeEdge::BottomRight),
+            // `None` is a valid protocol value (the client leaves the edge
+            // unspecified) but `WindowManager::start_resize` needs one --
+            // there's nothing sensible to default it to that wouldn't be a
+            // guess, so this is a no-op rather than picking one.
+            _ => None,
+        }) else {
+            return;
+        };
+        if let Some(&id) = self.surface_to_id.get(surface.wl_surface()) {
+            let pos = crate::input::last_pointer_pos(self);
+            self.wm.borrow_mut().start_resize(id, edge, pos.x as i32, pos.y as i32);
+        }
+    }
+
+    /// `maximize_request`/`unmaximize_request`/`fullscreen_request`/
+    /// `unfullscreen_request`/`minimize_request` were all still smithay's
+    /// default no-op (or configure-only) implementations - found
+    /// investigating the `toggle_fullscreen` decoration bug above, by
+    /// checking what else routes through the same `WindowManager` calls
+    /// the titlebar-button click handlers in `input.rs` already use.
+    /// These five are the *client-initiated* equivalent of those clicks: a
+    /// client's own window-menu "Maximize", pressing F11, an HTML5 video
+    /// going fullscreen, or (for a client that negotiated client-side
+    /// decoration and draws its own titlebar, like Firefox) that titlebar's
+    /// own maximize button - all ask the compositor to actually perform
+    /// the state change via these requests rather than the compositor
+    /// noticing on its own. Left unimplemented, every one of them was a
+    /// silent no-op: the client's button did nothing, with no error and
+    /// nothing to suggest why, from any app that relies on this instead of
+    /// (or in addition to) a compositor-side keybinding.
+    fn maximize_request(&mut self, surface: ToplevelSurface) {
+        if let Some(&id) = self.surface_to_id.get(surface.wl_surface()) {
+            if !self.wm.borrow().window(id).is_some_and(|w| w.maximized) {
+                self.wm.borrow_mut().toggle_maximize(id);
+                self.sync_geometry(id);
+                crate::foreign_toplevel::send_state(self, id);
+            }
+        }
+        surface.send_configure();
+    }
+
+    fn unmaximize_request(&mut self, surface: ToplevelSurface) {
+        if let Some(&id) = self.surface_to_id.get(surface.wl_surface()) {
+            if self.wm.borrow().window(id).is_some_and(|w| w.maximized) {
+                self.wm.borrow_mut().toggle_maximize(id);
+                self.sync_geometry(id);
+                crate::foreign_toplevel::send_state(self, id);
+            }
+        }
+        surface.send_configure();
+    }
+
+    /// `_output` (the client's requested target output) is ignored --
+    /// single-seat, and every other fullscreen entry point (the titlebar
+    /// button, `srd.window.fullscreen()`) already fullscreens on whatever
+    /// monitor the window is already on, so this matches that instead of
+    /// introducing an output-aware fullscreen path only this one request
+    /// would use.
+    fn fullscreen_request(&mut self, surface: ToplevelSurface, _output: Option<WlOutput>) {
+        if let Some(&id) = self.surface_to_id.get(surface.wl_surface()) {
+            if !self.wm.borrow().is_fullscreen(id) {
+                // `redraw_decoration_buffer` first, same reason
+                // `set_decorated_from_mode` calls it before `sync_geometry`:
+                // fullscreen also flips `Window.decorated`, and dropping
+                // the decoration needs the buffer actually removed, not
+                // just left stale for `sync_geometry`'s own resize-only
+                // redraw check to skip.
+                self.wm.borrow_mut().toggle_fullscreen(id);
+                self.redraw_decoration_buffer(id);
+                self.sync_geometry(id);
+                crate::foreign_toplevel::send_state(self, id);
+            }
+        }
+        surface.send_configure();
+    }
+
+    fn unfullscreen_request(&mut self, surface: ToplevelSurface) {
+        if let Some(&id) = self.surface_to_id.get(surface.wl_surface()) {
+            if self.wm.borrow().is_fullscreen(id) {
+                self.wm.borrow_mut().toggle_fullscreen(id);
+                self.redraw_decoration_buffer(id);
+                self.sync_geometry(id);
+                crate::foreign_toplevel::send_state(self, id);
+            }
+        }
+        surface.send_configure();
+    }
+
+    /// No `send_configure` here, matching the pointer-driven
+    /// `TitlebarHit::Minimize` handler in `input.rs`: minimizing doesn't
+    /// change the window's own size, only whether it's currently shown, so
+    /// there's nothing new to tell the client about its own geometry.
+    fn minimize_request(&mut self, surface: ToplevelSurface) {
+        if let Some(&id) = self.surface_to_id.get(surface.wl_surface()) {
+            self.wm.borrow_mut().minimize_window(id);
+            crate::foreign_toplevel::send_state(self, id);
+        }
+    }
+
+    /// Was a bare no-op - no `send_configure` at all. Per xdg-shell,
+    /// `xdg_surface.configure` is required before a popup's first commit;
+    /// real toolkits (confirmed live: GTK4's Wayland backend) block that
+    /// commit in a synchronous roundtrip waiting for it, so every popup
+    /// hung its client forever. GTK4 implements tooltips *and*
+    /// `Gtk.Popover` as `xdg_popup`, so this fired on hovering almost any
+    /// widget with a tooltip - confirmed by a peer session's gdb backtrace
+    /// (blocked in `wl_display_dispatch_queue` under `gtk_widget_show`)
+    /// after AGS wedged.
+    ///
+    /// Geometry is `positioner.get_geometry()` un-constrained - no
+    /// on-screen clamping yet (`PositionerState::get_unconstrained_geometry`
+    /// needs a target rect in the parent's surface-local space, which is a
+    /// real follow-up, not this fix); an occasional popup placed near a
+    /// screen edge may render partly off it, which is cosmetic, not a hang.
+    fn new_popup(&mut self, surface: PopupSurface, positioner: PositionerState) {
+        // Temporary: live report is that Nemo's right-click context menu
+        // never appears at all (not mispositioned - entirely invisible),
+        // while the exact same xdg_popup mechanism works for Firefox. Logs
+        // the unconstrained geometry this popup gets so a live repro tells
+        // us whether it's landing off-screen/degenerate (the known gap this
+        // function's own doc comment already flags) or something else
+        // entirely. Remove once resolved.
+        let geom = positioner.get_geometry();
+        let parent = surface.get_parent_surface();
+        log::warn!("POPUP-GEOM-DIAG geometry={geom:?} parent={:?}", parent.as_ref().map(|s| s.id()));
+        surface.with_pending_state(|state| {
+            state.geometry = geom;
+            state.positioner = positioner;
+        });
+        if surface.send_configure().is_err() {
+            log::warn!("POPUP-GEOM-DIAG send_configure failed");
+            return;
+        }
+        let _ = self.popups.track_popup(smithay::desktop::PopupKind::Xdg(surface));
+    }
+
+    /// Implicit grab + dismiss-on-outside-click. Previously believed
+    /// blocked on `CompState`'s `SeatHandler` associated types not
+    /// satisfying `PopupManager::grab_popup`'s `WaylandFocus +
+    /// From<PopupKind>` bound - rechecked while implementing
+    /// `move_request`/`resize_request` (same trait, adjacent methods) and
+    /// it turns out they already do: `KeyboardFocus`/`PointerFocus` are
+    /// both plain `WlSurface`, smithay provides `impl From<PopupKind> for
+    /// WlSurface` itself, and `WlSurface: From<WlSurface>` trivially. No
+    /// blocker ever existed by the time of this pass; the bound just
+    /// hadn't been rechecked since being noted as unmet.
+    ///
+    /// `self.seat.clone()` rather than resolving `_seat` (the client's
+    /// `wl_seat` resource) via `Seat::from_resource` - this compositor
+    /// only ever has the one seat, matching how `move_request`/
+    /// `resize_request` already ignore the same parameter.
+    fn grab(&mut self, surface: PopupSurface, _seat: wl_seat::WlSeat, serial: Serial) {
+        let popup = PopupKind::Xdg(surface);
+        let Ok(root) = find_popup_root_surface(&popup) else {
+            log::warn!("POPUP-GRAB-DIAG find_popup_root_surface failed");
+            return;
+        };
+        let seat = self.seat.clone();
+        let grab = match self.popups.grab_popup(root, popup, &seat, serial) {
+            Ok(g) => g,
+            Err(e) => {
+                log::warn!("POPUP-GRAB-DIAG grab_popup failed: {e:?}");
+                return;
+            }
+        };
+        log::warn!("POPUP-GRAB-DIAG grab established, has_pointer={} has_keyboard={}", seat.get_pointer().is_some(), seat.get_keyboard().is_some());
+        if let Some(keyboard) = seat.get_keyboard() {
+            keyboard.set_grab(self, PopupKeyboardGrab::new(&grab), serial);
+        }
+        if let Some(pointer) = seat.get_pointer() {
+            pointer.set_grab(self, PopupPointerGrab::new(&grab), serial, Focus::Keep);
+        }
+    }
+
+    fn reposition_request(&mut self, surface: PopupSurface, positioner: PositionerState, token: u32) {
+        surface.with_pending_state(|state| {
+            state.geometry = positioner.get_geometry();
+            state.positioner = positioner;
+        });
+        surface.send_repositioned(token);
+    }
+
+    fn toplevel_destroyed(&mut self, surface: ToplevelSurface) {
+        self.remove_window(surface.wl_surface());
+    }
+}
diff --git a/crates/wayland/src/rounded_corners_pixman.rs b/crates/wayland/src/rounded_corners_pixman.rs
index 1879b9e..3a712f9 100644
--- a/crates/wayland/src/rounded_corners_pixman.rs
+++ b/crates/wayland/src/rounded_corners_pixman.rs
@@ -5,122 +5,131 @@
 //! mask is a hardcoded flat alpha, and its destination image is private to
 //! smithay's own module - no public hook for a custom mask picture).
 //!
-//! The technique here instead bakes the mask into a *copy* of the client's
-//! own pixel data before it ever reaches the normal compositing path: read
-//! the surface's committed `wl_shm` buffer, punch premultiplied-alpha holes
-//! (this codebase's existing BGRA convention - see `decoration::
-//! shadow_bitmap`'s doc comment) into the four corner regions, and hand the
-//! result to `MemoryRenderBuffer` - the exact same type and render-element
-//! path already used for the titlebar/border/shadow bitmaps. Rendering it
-//! through the ordinary unmasked `render_texture_from_to` is what makes the
-//! corners actually disappear: a premultiplied-zero source pixel there
-//! contributes nothing, leaving whatever was already drawn underneath (the
-//! desktop, or another window) showing through - a real cutout, not a
-//! flat-colour patch.
+//! The technique here: render the window's *entire* surface tree (root
+//! plus every subsurface, exactly what the ordinary unmasked path already
+//! draws) into a private off-screen buffer, read that back as plain BGRA8
+//! bytes, and punch the four corner holes into *those* - the composited
+//! result, not any one client buffer - before handing it to
+//! `MemoryRenderBuffer`, the same type and render-element path already
+//! used for the titlebar/border/shadow bitmaps.
 //!
-//! Deliberately narrow scope, same as the GLES version: only a window's
-//! *main* surface (no subsurfaces), and only the two common `wl_shm`
-//! formats this compositor's own bitmaps already use (`Argb8888`/
-//! `Xrgb8888`) - anything else, a non-`wl_shm` buffer (dmabuf, a GL
-//! client), or a non-identity buffer transform falls back to `None`, which
-//! the caller treats as "render this window's content unrounded" rather
-//! than an error.
+//! A previous version of this instead tried to identify *which one*
+//! surface in the tree held "the real content" (a root-plus-one-child
+//! GTK4/WebRender pattern, confirmed live against Firefox and Chrome) and
+//! masked that single client buffer directly, skipping everything else in
+//! the tree. That was cheaper - no extra render pass - but structurally
+//! fragile: it assumed the *rest* of the tree (whatever the chosen surface
+//! didn't cover) was always invisible padding, true for Chrome's own
+//! shadow-margin inset but false for Firefox, whose tab strip/title row is
+//! painted on the *root* surface, outside its own content child. The
+//! moment that surface-picking heuristic got permissive enough to actually
+//! mask Firefox's real, common case, it started *silently deleting
+//! Firefox's own tab strip* - reported live as "Firefox's titlebar turned
+//! invisible", confirmed by toggling `general.rounded_corners` off, which
+//! brought it straight back. Rendering the whole tree and masking the
+//! *output* instead of guessing which *input* is real sidesteps the whole
+//! question - the same reason a GPU shader-based compositor (niri,
+//! cosmic-comp) never has this class of bug at all: by the time its own
+//! shader runs, the subsurface tree is already flattened into one texture,
+//! so there is nothing left to misidentify.
+//!
+//! Only `wl_shm`/dmabuf-agnostic now - unlike the old per-buffer read,
+//! this never touches a client's own buffer format at all, only the
+//! renderer's own composited output, so the format/transform restrictions
+//! the previous version needed (`Argb8888`/`Xrgb8888` only, no dmabuf
+//! without a dedicated read path, `Transform::Normal` only) no longer
+//! apply - whatever the renderer can already draw (which is everything it
+//! draws for the ordinary unmasked path too), this can mask.
 //!
 //! Cost, and why this stays default-off on this backend (`general.
 //! rounded_corners`, see `WindowManager::rounded_corners_enabled`'s doc
-//! comment): unlike the GLES shader, which the GPU evaluates once per pixel
-//! at zero extra CPU cost, this masks a full copy of the surface's pixel
-//! data on the CPU. The mask math itself only touches the four small
-//! corner boxes, but producing a tightly-packed buffer `MemoryRenderBuffer::
-//! from_slice` accepts (it asserts a `width * 4` stride; a client's own SHM
-//! stride is often larger, padded for alignment) means copying the whole
-//! buffer row by row regardless. The caller is expected to cache the
-//! result and only call this again when the surface's content has actually
-//! changed (see `CompState::content_epoch`), so the real per-frame cost for
-//! idle/static windows is nothing - but a constantly-repainting client
-//! (video, a terminal under heavy scrollback) pays this on every commit for
-//! as long the feature stays on, which is exactly the untested-on-real-
-//! hardware cost the opt-in default exists to avoid forcing on anyone.
+//! comment): a full extra off-screen render pass (allocate a buffer, draw
+//! the tree into it, read the result back) on every real content change,
+//! not just a raw memory copy the old approach needed - strictly more
+//! expensive per rebuild than before, though still gated by the same
+//! `CompState::content_epoch` cache as before, so an idle/static window
+//! still costs nothing per frame, only per genuine repaint.
 
 use crate::rounded_corners::RoundedCorners;
 use smithay::backend::allocator::Fourcc;
-use smithay::backend::renderer::element::memory::MemoryRenderBuffer;
-use smithay::backend::renderer::utils::{with_renderer_surface_state, RendererSurfaceState};
-use smithay::reexports::wayland_server::protocol::wl_shm;
+use smithay::backend::renderer::damage::OutputDamageTracker;
+use smithay::backend::renderer::element::surface::render_elements_from_surface_tree;
+use smithay::backend::renderer::element::Kind;
+use smithay::backend::renderer::pixman::PixmanRenderer;
+use smithay::backend::renderer::{Bind, ExportMem, Offscreen};
 use smithay::reexports::wayland_server::protocol::wl_surface::WlSurface;
-use smithay::utils::Transform;
-use smithay::wayland::compositor::get_children;
-use smithay::wayland::shm::{with_buffer_contents, BufferData};
+use smithay::utils::{Buffer as BufferCoord, Rectangle, Transform};
 
-/// Builds a rounded-corner-masked copy of `surface`'s own committed content,
-/// or `None` if that isn't possible right now - see this module's doc
-/// comment for every case that falls back rather than erroring. `radius` is
-/// in the same logical-pixel units as `decoration::CORNER_RADIUS`; scaled
-/// up to buffer pixels internally using the surface's own buffer scale.
-pub(crate) fn masked_content_buffer(surface: &WlSurface, radius: f32, corners: RoundedCorners) -> Option<MemoryRenderBuffer> {
-    // The module doc comment above has always claimed "only a window's main
-    // surface (no subsurfaces)... falls back to None" - but nothing here
-    // actually checked that; this function read `surface`'s own buffer
-    // unconditionally regardless of whether it had children. A window whose
-    // real content is painted into a subsurface (a common GTK4/WebRender
-    // pattern - confirmed live: Firefox does this) has its own root
-    // surface holding only a blank/background buffer, so masking succeeded
-    // and produced a buffer, just the wrong one - the actual page content
-    // in the child subsurface was never read at all, and the window
-    // rendered as blank with rounded corners on instead of falling back to
-    // the unmasked path (`surface_content_elements`), which does walk the
-    // full surface tree and shows real content correctly.
-    if !get_children(surface).is_empty() {
-        return None;
-    }
-    let (buffer, scale, transform) = with_renderer_surface_state(surface, |state: &mut RendererSurfaceState| {
-        let buffer = state.buffer()?.clone();
-        Some((buffer, state.buffer_scale(), state.buffer_transform()))
-    })??;
-    // A rotated/flipped buffer would need the mask rotated with it; not
-    // worth the extra math for a cosmetic, already-narrow-scope pass.
-    if transform != Transform::Normal {
+/// Renders `surface`'s whole subsurface tree into a private `size`-sized
+/// off-screen buffer - `loc` is the tree's own root-surface-relative
+/// origin to render at, exactly like `render_elements_from_surface_tree`'s
+/// own `location` parameter elsewhere in this codebase (`udev/capture.rs`);
+/// the caller passes the *negated* `content_offset`
+/// (`dwindow.geometry().loc`, the client's own declared shadow-margin
+/// inset) so the buffer's own `(0, 0)` lands exactly on the window's real
+/// visible content top-left, the same correction every other render path
+/// in this compositor already applies (see `udev/render.rs`'s own `pos`
+/// computation) - then punches the four rounded-corner holes into the
+/// result. Returns tightly-packed BGRA8 bytes (`size.0 * size.1 * 4`),
+/// ready for `MemoryRenderBuffer::from_slice`, or `None` if the off-screen
+/// render itself failed (a genuine renderer error, not "this window isn't
+/// shaped right for masking" - there is no such restriction anymore).
+///
+/// `radius` is already in the same units as `size` (this compositor's
+/// outputs are always scale `1.0`, per `WindowManager::rounded_corners_
+/// enabled`'s own doc comment, so there is no separate buffer-scale
+/// factor to fold in here the way the old per-client-buffer read needed).
+pub(crate) fn masked_content_buffer(renderer: &mut PixmanRenderer, surface: &WlSurface, loc: (i32, i32), size: (i32, i32), radius: f32, corners: RoundedCorners) -> Option<Vec<u8>> {
+    let (w, h) = size;
+    if w <= 0 || h <= 0 {
         return None;
     }
-    let radius_px = radius * scale as f32;
-
-    let (data, w, h) = with_buffer_contents(&buffer, move |ptr, len, data: BufferData| -> Option<(Vec<u8>, i32, i32)> {
-        if !matches!(data.format, wl_shm::Format::Argb8888 | wl_shm::Format::Xrgb8888) {
+    // Transparent clear (not opaque black, unlike `udev/capture.rs`'s own
+    // off-screen render): this buffer holds only the window's own content,
+    // with nothing behind it to composite against yet - any area the
+    // surface tree doesn't actually draw into (a subsurface smaller than
+    // its own declared geometry, say) needs to stay real, punch-through
+    // transparency so the border/desktop already drawn underneath on the
+    // real output shows through there, not a solid black patch.
+    let elements = render_elements_from_surface_tree::<_, crate::elements::OverlayElement<PixmanRenderer>>(renderer, surface, loc, 1.0, 1.0, Kind::Unspecified);
+    let mut target = match renderer.create_buffer(Fourcc::Argb8888, (w, h).into()) {
+        Ok(t) => t,
+        Err(e) => {
+            log::debug!("rounded_corners_pixman: masked_content_buffer: create_buffer failed ({e:?}) - giving up unmasked");
             return None;
         }
-        let (w, h, stride, offset) = (data.width, data.height, data.stride, data.offset);
-        if w <= 0 || h <= 0 || stride <= 0 || offset < 0 {
+    };
+    let mut framebuffer = match renderer.bind(&mut target) {
+        Ok(fb) => fb,
+        Err(e) => {
+            log::debug!("rounded_corners_pixman: masked_content_buffer: bind failed ({e:?}) - giving up unmasked");
             return None;
         }
-        let needed = offset as usize + stride as usize * h as usize;
-        if needed > len {
+    };
+    let mut tracker = OutputDamageTracker::new((w, h), 1.0, Transform::Normal);
+    if let Err(e) = tracker.render_output(renderer, &mut framebuffer, 0, &elements, [0.0, 0.0, 0.0, 0.0]) {
+        log::debug!("rounded_corners_pixman: masked_content_buffer: render_output failed ({e:?}) - giving up unmasked");
+        return None;
+    }
+    let region: Rectangle<i32, BufferCoord> = Rectangle::new((0, 0).into(), (w, h).into());
+    let mapping = match renderer.copy_framebuffer(&framebuffer, region, Fourcc::Argb8888) {
+        Ok(m) => m,
+        Err(e) => {
+            log::debug!("rounded_corners_pixman: masked_content_buffer: copy_framebuffer failed ({e:?}) - giving up unmasked");
             return None;
         }
-        // SAFETY: `pool.with_data` (inside `with_buffer_contents`) already
-        // validated `ptr`/`len` cover the whole pool; `needed` above
-        // re-checks this buffer's own slice sits inside that before a
-        // single byte is read.
-        let src = unsafe { std::slice::from_raw_parts(ptr.add(offset as usize), stride as usize * h as usize) };
-
-        // Repack into a tight `width * 4` stride: `MemoryRenderBuffer::
-        // from_slice` computes its own stride from `width` alone and
-        // asserts the data matches it, so the source's (often padded) SHM
-        // stride can't be handed through as-is.
-        let row_bytes = w as usize * 4;
-        let mut out = vec![0u8; row_bytes * h as usize];
-        for y in 0..h as usize {
-            let src_row = &src[y * stride as usize..y * stride as usize + row_bytes];
-            out[y * row_bytes..(y + 1) * row_bytes].copy_from_slice(src_row);
+    };
+    let pixels = match renderer.map_texture(&mapping) {
+        Ok(p) => p,
+        Err(e) => {
+            log::debug!("rounded_corners_pixman: masked_content_buffer: map_texture failed ({e:?}) - giving up unmasked");
+            return None;
         }
-
-        let radius_px = radius_px.min(w as f32 / 2.0).min(h as f32 / 2.0);
-        apply_corner_mask(&mut out, w, h, row_bytes as i32, radius_px, corners);
-        Some((out, w, h))
-    })
-    .ok()
-    .flatten()?;
-
-    Some(MemoryRenderBuffer::from_slice(&data, Fourcc::Argb8888, (w, h), scale, Transform::Normal, None))
+    };
+    let mut out = pixels.to_vec();
+    let radius_px = radius.min(w as f32 / 2.0).min(h as f32 / 2.0);
+    apply_corner_mask(&mut out, w, h, w * 4, radius_px, corners);
+    Some(out)
 }
 
 /// Zeroes (fading over ~2px, matching `rounded_corners::FRAGMENT_SHADER`'s
diff --git a/crates/wayland/src/state/geometry.rs b/crates/wayland/src/state/geometry.rs
index 21cac8d..715881b 100644
--- a/crates/wayland/src/state/geometry.rs
+++ b/crates/wayland/src/state/geometry.rs
@@ -1,5 +1,16 @@
 use super::*;
 
+/// How long `sync_geometry` waits for a client to catch up to a previous
+/// size-changing configure before giving up on the throttle and sending a
+/// new one anyway - see `pending_size_configure`'s own doc comment for
+/// the throttle itself. Generous relative to any real client's own
+/// resize-and-recommit latency (a terminal reflowing text, a browser
+/// re-laying-out a page), so this essentially never fires in practice;
+/// it exists purely as the same kind of bounded self-heal this session's
+/// DRM flip-pending watchdog already uses, not a tuning knob expected to
+/// matter day to day.
+const CONFIGURE_THROTTLE_TIMEOUT: Duration = Duration::from_millis(100);
+
 impl CompState {
 
     /// Re-raises always-on-top windows in the `Space`.
@@ -17,6 +28,110 @@ impl CompState {
         }
     }
 
+    /// `Self::effective_frame`, but as a free function taking only the two
+    /// fields it actually needs (`wm`, `id_to_window`) instead of `&self` --
+    /// a render loop holding `self.udev`/`self.backend` mutably borrowed
+    /// can't also pass `&self` to a method, since Rust can't see through a
+    /// method call to know it only touches two unrelated fields. Called
+    /// through the inherent method below wherever a plain `&self` is
+    /// available (input handling, `redraw_decoration_buffer`); this
+    /// version exists for the render loops specifically.
+    pub(crate) fn effective_frame_of(wm: &Rc<RefCell<WindowManager>>, id_to_window: &HashMap<WindowId, DWindow>, id: WindowId, geom: srdwm_core::Rect) -> srdwm_core::Rect {
+        // A version of this function briefly (this same session) skipped
+        // the committed-size correction below entirely during an active
+        // resize, on the reasoning that trusting the client's stale last
+        // commit over this compositor's own live drag target was what made
+        // the border visibly lag behind content while dragging. Reverted:
+        // that fix was real for *position*-independent reasoning but wrong
+        // in a more important way - every caller of this function that
+        // reads a *bitmap*-backed element (the titlebar, the top/bottom
+        // border strip's own rounded-corner bitmap, both built by `redraw_
+        // decoration_buffer`, itself only called on a real client *commit*,
+        // not on every resize step) uses this rect's width/height to size
+        // the `src` crop rectangle it samples that bitmap with. Making this
+        // function return the *live* drag target while the underlying
+        // bitmap was still sized for whatever the *last commit* actually
+        // was means that crop can end up larger than the real bitmap's own
+        // stored dimensions - `MemoryRenderBufferRenderElement::from_
+        // buffer` does not validate `src` against the texture's real size,
+        // so an oversized crop reads as an out-of-bounds texture sample
+        // (stretched/repeated/garbage pixels, not a clean error) for as
+        // long as a fast resize keeps outrunning the client's own recommit
+        // rate - a worse, more visibly broken failure mode than the
+        // one-frame-stale lag it replaced. Fixing the lag properly needs
+        // `redraw_decoration_buffer` itself rebuilding on every resize
+        // step, not just on commit, which is real, separate scope - not
+        // yet done.
+        let Some(w) = wm.borrow().window(id).cloned() else { return geom };
+        let Some(dwindow) = id_to_window.get(&id) else { return geom };
+        let content = dwindow.geometry();
+        if content.size.w <= 0 || content.size.h <= 0 {
+            // No real committed content yet - racing the first commit
+            // right after creation, most likely. Nothing to correct
+            // against, so fall back to the requested rect rather than
+            // collapsing every dimension down to (near) zero.
+            return geom;
+        }
+        // `content` is `xdg_surface::set_window_geometry` - specified to
+        // carry *logical* points, same as `sync_geometry`'s own `size`
+        // going the other direction (see that function's matching doc
+        // comment). Every caller of this method (border, shadow, occlusion,
+        // resize-margin hit-test) works in this compositor's own physical
+        // convention, same as `geom` - so `content.size` needs converting
+        // back to physical here, the same `* scale` `sync_geometry` divides
+        // by on the way out, or a window on a scaled monitor gets a
+        // border/shadow drawn at the *logical* size while its real content
+        // renders at a different *physical* one. On a monitor with
+        // `scale == 1.0` logical and physical are numerically identical, so
+        // this was invisible until this session's own auto-scale feature
+        // gave a monitor a non-1.0 value - reported live as a purple
+        // border sitting visibly detached, to the east and south, from an
+        // undecorated (CSD) window's real content once that happened.
+        let scale = wm.borrow().monitors().iter().find(|m| m.id == w.monitor).map(|m| m.scale).unwrap_or(1.0);
+        let content_physical = ((content.size.w as f64 * scale).round() as i32, (content.size.h as f64 * scale).round() as i32);
+        let band = if w.decorated { TITLEBAR_HEIGHT as i32 } else { 0 };
+        srdwm_core::Rect { x: geom.x, y: geom.y, width: content_physical.0.max(0) as u32, height: (band + content_physical.1.max(0)) as u32 }
+    }
+
+    /// The rect a window's border, shadow, occlusion test, and resize-
+    /// margin hit-test should actually use - `geom` (the requested target,
+    /// or mid-animation the interpolated rect) with its width/height
+    /// replaced by what the client's own surface really committed, when
+    /// that's known and non-degenerate. `x`/`y` are left untouched: the
+    /// top-left corner is already correctly anchored by `content_offset`
+    /// elsewhere (`sync_geometry`/the render loops), only the far edge can
+    /// end up wrong.
+    ///
+    /// `Window.geometry` (what `geom`'s width/height ultimately come from)
+    /// is this compositor's own *request* - what `sync_geometry` asked the
+    /// client to become via `xdg_toplevel::configure`'s `size`. Nothing
+    /// before this ever read back whether the client actually complied.
+    /// Most do, to the pixel - but a client with its own internal size
+    /// quantization (a terminal emulator, snapping its real content to a
+    /// whole number of character cells) can settle on a slightly different
+    /// real size than what was requested, without that being any kind of
+    /// protocol violation. Every caller of this method used to read `geom`
+    /// directly regardless, so the border (and the shadow, and the resize-
+    /// margin hit-test) kept drawing/testing at the *asked-for* edge while
+    /// the client's real content stopped a few pixels short of it --
+    /// reported live as a transparent gap between a terminal's content and
+    /// srdwm's own border, letting the desktop show through underneath.
+    ///
+    /// Niri's own `LayoutElement::size` (`src/window/mapped.rs` in its
+    /// source) is the model this follows: its entire layout - tile size,
+    /// border, focus ring - is driven by `self.window.geometry().size`,
+    /// the client's real, committed value, never by whatever niri itself
+    /// originally requested. This mirrors that for the specific things
+    /// srdwm draws that have to visually hug the real edge. Deliberately
+    /// narrow, not a wholesale switch: `Space` positioning, the
+    /// `xdg_toplevel::configure` math itself, and tiling layout all keep
+    /// reading `Window.geometry` unchanged - those are about this
+    /// compositor's own bookkeeping staying self-consistent, not about
+    /// matching a client's real pixels.
+    pub(crate) fn effective_frame(&self, id: WindowId, geom: srdwm_core::Rect) -> srdwm_core::Rect {
+        Self::effective_frame_of(&self.wm, &self.id_to_window, id, geom)
+    }
+
     pub(crate) fn sync_geometry(&mut self, id: WindowId) {
         // A pending `anim_from` (set by `toggle_maximize`/`toggle_fullscreen`,
         // or by `new_managed_window` for the open-slide) means the target
@@ -28,7 +143,23 @@ impl CompState {
         // call for the same window (an ordinary drag/resize frame) goes
         // straight back to applying `geometry` immediately, as before.
         let anim_from = self.wm.borrow_mut().window_mut(id).and_then(|w| w.anim_from.take());
-        let Some((target, decorated, maximized, fullscreen)) = self.wm.borrow().window(id).map(|w| (w.geometry, w.decorated, w.maximized, w.fullscreen)) else { return };
+        let Some((target, decorated, maximized, fullscreen, monitor)) =
+            self.wm.borrow().window(id).map(|w| (w.geometry, w.decorated, w.maximized, w.fullscreen, w.monitor))
+        else {
+            return;
+        };
+        // This compositor's own placement/geometry tracking is physical
+        // pixels throughout (see `Platform::monitors()`'s own doc comment
+        // on that choice); `xdg_toplevel::configure`'s `size` is specified
+        // to carry *logical* points, always, independent of which output a
+        // window is on. Every output was `1.0` before this session's own
+        // auto-scale feature existed, so physical and logical were
+        // numerically identical and this conversion's absence was
+        // invisible. Falls back to `1.0` (no conversion) if this window's
+        // own monitor can't be resolved - the same "assume unscaled
+        // rather than guess" default `MonitorInfo::scale`'s own doc
+        // comment already uses for a disabled output.
+        let scale = self.wm.borrow().monitors().iter().find(|m| m.id == monitor).map(|m| m.scale).unwrap_or(1.0);
         if let Some(from) = anim_from {
             let duration_ms = self.wm.borrow().animation_duration_ms;
             if from != target && duration_ms > 0 {
@@ -51,8 +182,40 @@ impl CompState {
         // Position always moves with the pointer; only a size change needs a
         // client configure or a titlebar re-render (see `last_synced_size`'s
         // doc comment).
-        let size = (geom.width as i32, geom.height as i32 - band);
-        let size_changed = self.last_synced_size.insert(id, size) != Some(size);
+        //
+        // Converted to logical points here, before anything below reads
+        // `size` - `xdg_toplevel::configure` is specified to carry
+        // logical points, and `w.geometry()` (what the throttle check
+        // below compares a client's real commit against) is a client's own
+        // `xdg_surface::set_window_geometry`, logical by the same
+        // specification - so keeping the rest of this function in that
+        // one space, not switching back to physical partway through, is
+        // what actually keeps every comparison here meaningful.
+        //
+        // This has a real, desirable second effect beyond fixing the unit
+        // mismatch itself: a window that crosses onto a monitor with a
+        // different scale, at the *same* physical size (an ordinary drag
+        // never changes `geom.width`/`geom.height`), now computes a
+        // *different* logical size purely from `scale` changing --
+        // correctly triggering a fresh configure asking the client to
+        // resize to match, the same way real desktop environments keep a
+        // window's true on-screen footprint consistent across a DPI
+        // change. Before this, a plain cross-monitor drag sent no configure
+        // at all (physical size hadn't changed), so the client kept
+        // rendering its old logical size at the new monitor's different
+        // scale while this compositor's own border kept drawing at the
+        // physical rect it always had - reported live as a window's
+        // border ending up visibly detached from its own content after
+        // being dragged to the other monitor.
+        let size_physical = (geom.width as i32, geom.height as i32 - band);
+        let size = ((size_physical.0 as f64 / scale).round() as i32, (size_physical.1 as f64 / scale).round() as i32);
+        // Peeked, not inserted yet - only actually updated once a
+        // configure for `size` is decided below, so a size that keeps
+        // changing tick to tick while throttled (an active drag didn't
+        // stop just because the client hasn't caught up yet) is still
+        // correctly seen as "different from what's actually been sent"
+        // on every later tick, not just the first.
+        let size_changed = self.last_synced_size.get(&id).copied() != Some(size);
         let mut moved = false;
         if let Some(w) = self.id_to_window.get(&id) {
             // `w.geometry().loc` is the client's own `xdg_surface::
@@ -60,25 +223,64 @@ impl CompState {
             // concretely) declares its real visible content as a sub-rect
             // inset within a larger buffer that also reserves an invisible
             // shadow margin, even once the tiled-state hint below has told
-            // it to skip drawing that shadow. `render_udev_frame`/
-            // `winit/render.rs` both subtract this same offset from where
-            // they draw the window's content, specifically so the client's
-            // visible content lands at `geom.x, geom.y` instead of a
-            // shadow-margin's width/height short of it - `space` has to
-            // agree with that adjustment, not just rendering, or every
-            // click computed via `win_relative = pos - space_loc` would
-            // land `content_offset` short of whatever the user actually
-            // clicked on: rendering moves the content, hit-testing keeps
-            // routing against where the client's raw, unshifted buffer
-            // origin used to be.
-            let content_offset = w.geometry().loc;
-            self.space.map_element(w.clone(), (geom.x - content_offset.x, geom.y + band - content_offset.y), false);
+            // it to skip drawing that shadow.
+            //
+            // This used to be subtracted from `location` right here, on the
+            // reasoning that `space` needed to be told about it explicitly,
+            // the same way `render_udev_frame`/`winit/render.rs` do for
+            // drawing. That reasoning was wrong about `Space` specifically:
+            // smithay's own `SpaceElement for Window` reports `geometry()`
+            // as `self.geometry()` (this exact `content_offset`, non-zero
+            // `.loc` included), and `Space`'s internal `render_location()`
+            // (what every hit-test - `element_under`, and so `refresh_
+            // pointer_focus`'s `win_relative = pos - loc` - actually reads)
+            // already computes `location - element.geometry().loc` on its
+            // own, unconditionally, for every mapped element. Subtracting
+            // `content_offset` again here meant `Space`'s own tracked
+            // position ended up short by *two* `content_offset`s, not one --
+            // confirmed live via temporary diagnostic logging on both sides:
+            // this call computing a correct, single-subtraction position,
+            // and `Space::element_under` reporting a position exactly one
+            // more `content_offset` short of it for the same window on the
+            // very same commit. The render loops' own manual subtraction is
+            // unaffected and stays - they position elements by hand,
+            // entirely bypassing `Space`'s automatic handling, so they still
+            // have to do this themselves; `xwayland.rs`'s own `map_element`
+            // calls already never did this (X11 windows have no equivalent
+            // shadow-margin geometry), which in hindsight was the correct
+            // pattern being followed there all along.
+            self.space.map_element(w.clone(), (geom.x, geom.y + band), false);
             moved = true;
             if let Some(top) = w.toplevel() {
                 // xdg-shell position is a purely compositor-side concept --
                 // the client is never told it - so only a size change
                 // needs a configure here.
-                if size_changed {
+                //
+                // Throttled to at most one size-changing configure "in
+                // flight" per window, the same way niri does (`window/
+                // mapped.rs`'s `ConfigureIntent::Throttled`) - see
+                // `pending_size_configure`'s own doc comment for why: this
+                // used to send a fresh configure on every single pointer-
+                // motion tick of an active resize regardless of whether the
+                // client had caught up to the *previous* one yet, which a
+                // fast pointer (a real high-poll-rate mouse, niri's own
+                // stated motivation for the same throttle) could easily
+                // outrun into a real backlog. `w.geometry().size` is the
+                // client's actual last-committed content size - once it
+                // matches whatever was last sent, that configure is
+                // considered caught up and the throttle clears on its own,
+                // no separate ack-tracking needed. Bounded by
+                // `CONFIGURE_THROTTLE_TIMEOUT` regardless, so a client that
+                // never catches up for any reason (slow, buggy, wedged)
+                // can't jam resizing shut forever - the same self-healing
+                // shape as this session's own DRM flip-pending watchdog.
+                let throttled = self.pending_size_configure.get(&id).is_some_and(|(pending_size, sent_at)| {
+                    let caught_up = w.geometry().size.w == pending_size.0 && w.geometry().size.h == pending_size.1;
+                    !caught_up && sent_at.elapsed() < CONFIGURE_THROTTLE_TIMEOUT
+                });
+                if size_changed && !throttled {
+                    self.last_synced_size.insert(id, size);
+                    self.pending_size_configure.insert(id, (size, Instant::now()));
                     top.with_pending_state(|state| {
                         state.size = Some(size.into());
                         // No configure from this compositor, ever, set any
@@ -167,7 +369,18 @@ impl CompState {
                 let _ = x11.configure(Rectangle::new((geom.x, geom.y + band).into(), size.into()));
             }
         }
-        if size_changed && self.decorations.contains_key(&id) {
+        // Not gated on `self.decorations.contains_key(&id)` - that map only
+        // ever holds an entry for a *decorated* window (see
+        // `redraw_decoration_buffer`, which only inserts into it when
+        // `w.decorated`), so that gate was permanently false for every
+        // undecorated/CSD window, even one with `border_width > 0`. Its
+        // border bitmaps were rendered once at creation and never rebuilt on
+        // any later resize - reported live as the border "not truly around"
+        // the window after resizing. `redraw_decoration_buffer` already
+        // self-guards via `decoration_signatures` (see its own doc comment),
+        // so calling it unconditionally here costs nothing once the size
+        // genuinely hasn't changed the rasterized output.
+        if size_changed {
             self.redraw_decoration_buffer(id);
         }
         // See `resync_stacking_order`'s doc comment: `map_element` above
diff --git a/crates/wayland/src/state/lifecycle.rs b/crates/wayland/src/state/lifecycle.rs
index db2de44..259979b 100644
--- a/crates/wayland/src/state/lifecycle.rs
+++ b/crates/wayland/src/state/lifecycle.rs
@@ -74,6 +74,45 @@ impl CompState {
         let Some(w) = self.wm.borrow().window(id).cloned() else { return };
         let focused = self.wm.borrow().focused_id() == Some(id);
         let theme = self.wm.borrow().theme;
+        // Read fresh every call, not cached from creation - a client can
+        // call `xdg_toplevel.set_parent` well after its own initial map
+        // (a "Save As" dialog opened from an already-open main window,
+        // say), and this function already re-runs on every relevant state
+        // change. Written back onto the real `Window` (not just used
+        // locally) so `ResizeEdge::hit_test`'s own `is_dialog` parameter
+        // - read from `core`, which has no protocol concept to derive
+        // this from itself - agrees with whatever got drawn here. An
+        // XWayland window's own `WM_TRANSIENT_FOR` isn't read yet, so this
+        // stays `false` for those specifically - see `Window::is_dialog`'s
+        // own doc comment.
+        let is_dialog = self.id_to_window.get(&id).and_then(|dw| dw.toplevel()).map(|t| t.parent().is_some()).unwrap_or(false);
+        if let Some(win) = self.wm.borrow_mut().window_mut(id) {
+            win.is_dialog = is_dialog;
+        }
+        // Corrects `w.geometry`'s far edge to match what the client's
+        // surface really committed, when that's known - see
+        // `effective_frame`'s own doc comment. Every bitmap this method
+        // builds (titlebar, top/bottom border, shadow) is sized from
+        // `frame`, not `w.geometry` directly, so a client that settles on
+        // a slightly different real size than requested (a terminal
+        // snapping to a whole number of character cells, most commonly)
+        // gets decoration that actually hugs its real edge instead of the
+        // asked-for one.
+        let frame = self.effective_frame(id, w.geometry);
+        // Eased (ease-out-cubic, same curve `WindowAnim::current_rect`
+        // already uses - see that doc comment) progress of the glyph-
+        // reveal-on-hover animation, discretized to a `u8` alpha. `theme.
+        // button_glyph_always` skips the timing/easing math entirely and
+        // just asks for full opacity outright - see `render_titlebar`'s
+        // own `glyph_always` parameter for where that's actually applied
+        // (it overrides this per-button, not just here).
+        let hovered_button = self.hovered_titlebar_button.and_then(|(hid, hit, start)| {
+            (hid == id).then(|| {
+                let t = (start.elapsed().as_secs_f32() / decoration::HOVER_GLYPH_DURATION.as_secs_f32()).min(1.0);
+                let eased = 1.0 - (1.0 - t).powi(3);
+                (hit, (eased * 255.0).round() as u8)
+            })
+        });
         // `main.rs`'s `sync()` calls `Platform::redraw_decoration` - which
         // always reaches here - for every visible window on every dirty
         // tick, not only the window that actually changed (see `Comp
@@ -85,8 +124,8 @@ impl CompState {
         // call turns those redundant calls into a cheap signature
         // comparison instead of a full re-rasterization.
         let signature = DecorationSignature {
-            width: w.geometry.width,
-            height: w.geometry.height,
+            width: frame.width,
+            height: frame.height,
             decorated: w.decorated,
             focused,
             title: w.title.clone(),
@@ -96,6 +135,13 @@ impl CompState {
             maximized: w.maximized,
             fullscreen: w.fullscreen,
             shadows_enabled: self.wm.borrow().shadows_enabled,
+            hovered_button,
+            title_centered: theme.title_centered,
+            buttons_left: theme.buttons_left,
+            button_glyph_always: theme.button_glyph_always,
+            button_order: theme.button_order,
+            traffic_light_buttons: theme.traffic_light_buttons,
+            is_dialog,
         };
         if self.decoration_signatures.get(&id) == Some(&signature) {
             return;
@@ -103,13 +149,30 @@ impl CompState {
         self.decoration_signatures.insert(id, signature);
         if w.decorated {
             let fg = if focused { theme.titlebar_fg_focused } else { theme.titlebar_fg_unfocused };
-            let width = w.geometry.width.max(1);
+            let width = frame.width.max(1);
             // Always rounded now, bordered or not - `render_border_top`
             // gives a bordered window's border strip the matching rounded
             // cut, so there's no more square-frame-around-a-round-titlebar
             // clash to avoid. See `render_titlebar`'s `round_corners` doc
             // comment.
-            let data = decoration::render_titlebar(width, TITLEBAR_HEIGHT, &w.title, theme.titlebar_bg, fg, true, w.corner_radius);
+            let data = decoration::render_titlebar(
+                width,
+                TITLEBAR_HEIGHT,
+                &w.title,
+                theme.titlebar_bg,
+                fg,
+                true,
+                w.corner_radius,
+                w.border_width,
+                focused,
+                hovered_button,
+                theme.title_centered,
+                theme.buttons_left,
+                theme.button_glyph_always,
+                theme.button_order,
+                theme.traffic_light_buttons,
+                is_dialog,
+            );
             let buffer = MemoryRenderBuffer::from_slice(&data, Fourcc::Argb8888, (width as i32, TITLEBAR_HEIGHT as i32), 1, Transform::Normal, None);
             self.decorations.insert(id, buffer);
         } else {
@@ -126,20 +189,54 @@ impl CompState {
         // this every render frame (an earlier version of this method did)
         // was a real, continuous cost, not just a redundant one.
         if w.border_width > 0 {
-            let color = effective_border_color(w.border_color, focused);
-            let strips = decoration::border_strips(w.geometry, w.border_width);
+            let color = effective_border_color(w.border_color, focused, theme.border_inactive_dim);
+            let strips = decoration::border_strips(frame, w.border_width);
+            // `render_border_top`/`render_border_bottom` both return a
+            // buffer `border_width.max(corner_radius)` rows tall now, not
+            // always exactly `border_width` - see their own doc comments
+            // for why a strip thinner than the corner radius needs the
+            // extra rows to let the curve actually resolve before handing
+            // off to the (curve-blind) side strips. `render.rs`'s call
+            // site positions this taller buffer to match: the top strip
+            // grows downward from its existing anchor (unchanged), the
+            // bottom strip grows upward, so its anchor shifts up by
+            // exactly the extra height.
+            let strip_h = w.border_width.max(w.corner_radius);
             if strips[0].width > 0 && strips[0].height > 0 {
                 let data = decoration::render_border_top(strips[0].width, w.border_width, color, w.corner_radius);
-                let buffer =
-                    MemoryRenderBuffer::from_slice(&data, Fourcc::Argb8888, (strips[0].width as i32, w.border_width as i32), 1, Transform::Normal, None);
+                let buffer = MemoryRenderBuffer::from_slice(&data, Fourcc::Argb8888, (strips[0].width as i32, strip_h as i32), 1, Transform::Normal, None);
                 self.border_top_decorations.insert(id, buffer);
             } else {
                 self.border_top_decorations.remove(&id);
             }
             if strips[1].width > 0 && strips[1].height > 0 {
                 let data = decoration::render_border_bottom(strips[1].width, w.border_width, color, w.corner_radius);
-                let buffer =
-                    MemoryRenderBuffer::from_slice(&data, Fourcc::Argb8888, (strips[1].width as i32, w.border_width as i32), 1, Transform::Normal, None);
+                // Temporary: chasing a live report that the bottom two
+                // corners render as a solid, uncurved block for the buffer's
+                // own "extra" rows (0..height-thickness) while the nominal
+                // rows (height-thickness..height) curve correctly. Dumps the
+                // alpha byte at x=0..11 for row 0 (should already show some
+                // cutting per a standalone simulation of this exact
+                // algorithm) and the last nominal row, straight out of the
+                // buffer this function just built - before it's wrapped
+                // into a MemoryRenderBuffer at all, so this is ground truth
+                // for whether `render_border_bottom` itself is the problem
+                // or something downstream of it is. Remove once resolved.
+                let w_usize = strips[1].width.max(1) as usize;
+                let h_usize = strip_h.max(1) as usize;
+                let alpha_row = |row: usize| -> Vec<u8> {
+                    (0..12.min(w_usize)).map(|x| data.get((row * w_usize + x) * 4 + 3).copied().unwrap_or(255)).collect()
+                };
+                log::debug!(
+                    "udev::lifecycle: BOTTOM border buffer for {} (id {id:?}): dims={w_usize}x{h_usize} row0_alpha={:?} row3_alpha={:?} row7_alpha={:?} row8_alpha={:?} row11_alpha={:?}",
+                    w.app_id,
+                    alpha_row(0),
+                    alpha_row(3.min(h_usize.saturating_sub(1))),
+                    alpha_row(7.min(h_usize.saturating_sub(1))),
+                    alpha_row(8.min(h_usize.saturating_sub(1))),
+                    alpha_row(11.min(h_usize.saturating_sub(1))),
+                );
+                let buffer = MemoryRenderBuffer::from_slice(&data, Fourcc::Argb8888, (strips[1].width as i32, strip_h as i32), 1, Transform::Normal, None);
                 self.border_bottom_decorations.insert(id, buffer);
             } else {
                 self.border_bottom_decorations.remove(&id);
@@ -158,8 +255,29 @@ impl CompState {
         // against.
         let shadows_enabled = self.wm.borrow().shadows_enabled;
         if shadows_enabled && !w.maximized && !w.fullscreen {
-            let data = decoration::shadow_bitmap(w.geometry.width, w.geometry.height);
-            let rect = decoration::shadow_rect(w.geometry);
+            // A decorated window's corners are *always* rounded (the
+            // titlebar/border strips round to `corner_radius` regardless of
+            // this setting - see their own call sites); an undecorated
+            // (CSD) window's own content only gets rounded when `general.
+            // rounded_corners` is on (default off on this backend - see
+            // `WindowManager::rounded_corners_enabled`'s doc comment). The
+            // shadow has to match whichever is actually true for *this*
+            // window, or it mismatches in the other direction: a rounded
+            // shadow around a still-square undecorated window with content
+            // rounding off.
+            let rounded_corners_enabled = self.wm.borrow().rounded_corners_enabled.unwrap_or(false);
+            let shadow_radius = if w.decorated || rounded_corners_enabled { w.corner_radius } else { 0 };
+            // Dimmed the same way `effective_border_color` dims an
+            // unfocused window's border - see `shadow_bitmap`'s own
+            // `max_alpha` doc comment for the real-desktop convention this
+            // matches (Hyprland's `color`/`color_inactive` shadow split).
+            let max_alpha = if focused {
+                decoration::SHADOW_MAX_ALPHA
+            } else {
+                (decoration::SHADOW_MAX_ALPHA as f32 * theme.border_inactive_dim).round().clamp(0.0, 255.0) as u8
+            };
+            let data = decoration::shadow_bitmap(frame.width, frame.height, shadow_radius, max_alpha);
+            let rect = decoration::shadow_rect(frame);
             let buffer = MemoryRenderBuffer::from_slice(&data, Fourcc::Argb8888, (rect.width as i32, rect.height as i32), 1, Transform::Normal, None);
             self.shadow_buffers.insert(id, buffer);
         } else {
diff --git a/crates/wayland/src/state/mod.rs b/crates/wayland/src/state/mod.rs
index 084e407..e315b2e 100644
--- a/crates/wayland/src/state/mod.rs
+++ b/crates/wayland/src/state/mod.rs
@@ -113,6 +113,44 @@ pub(crate) struct DecorationSignature {
     pub(crate) maximized: bool,
     pub(crate) fullscreen: bool,
     pub(crate) shadows_enabled: bool,
+    /// Which of *this* window's own titlebar buttons (if any) is currently
+    /// hovered, and the glyph-reveal animation's current progress (0..=255)
+    /// - see `CompState::hovered_titlebar_button`'s own doc comment.
+    /// Included here, progress and all, so hovering (or un-hovering) a
+    /// button - and every intermediate frame of the reveal animating in
+    /// between - is a real signature change, not silently absorbed by the
+    /// cache this struct exists to drive; a signature that only recorded
+    /// *which* button was hovered, not the animation's own progress, would
+    /// cache the very first frame of the reveal and never rebuild again
+    /// for the rest of it.
+    pub(crate) hovered_button: Option<(srdwm_core::TitlebarHit, u8)>,
+    /// `theme.title_centered` at the time this was rendered - a live
+    /// `srd`-side theme change (there's no `srd set` for this yet, but
+    /// nothing here assumes there never will be) must still invalidate the
+    /// cache like every other themed input already does.
+    pub(crate) title_centered: bool,
+    /// `theme.buttons_left` at render time - same reasoning as `title_
+    /// centered` above.
+    pub(crate) buttons_left: bool,
+    /// `theme.button_glyph_always`/`theme.button_order`/`theme.
+    /// traffic_light_buttons` at render time - same reasoning as `title_
+    /// centered`/`buttons_left` above (no `srd set` for any of the three
+    /// yet either), and the same real gap those two fields were added to
+    /// close: all three are passed straight into `render_titlebar`
+    /// (`redraw_decoration_buffer`'s own call site) but were missing from
+    /// this struct entirely until a full-pipeline audit found the mismatch
+    /// - a live change to any of the three would have compared equal
+    /// against a stale signature and silently never rebuilt the titlebar
+    /// this window already has cached.
+    pub(crate) button_glyph_always: bool,
+    pub(crate) button_order: Option<srdwm_core::ButtonOrder>,
+    pub(crate) traffic_light_buttons: bool,
+    /// `Window::is_dialog` at render time - a client can call `xdg_
+    /// toplevel.set_parent` well after its own initial map (a "Save As"
+    /// dialog opened from an already-open main window, say), so this needs
+    /// the same cache-invalidation treatment as every other live-
+    /// changeable input here, not just a value read once at creation.
+    pub(crate) is_dialog: bool,
 }
 
 /// Everything smithay's protocol handlers need `&mut` access to. This is the
@@ -190,6 +228,23 @@ pub(crate) struct CompState {
     /// menu` rather than instead of it - they cover disjoint sets of
     /// windows (XWayland-backed vs. Wayland-native), not the same one.
     pub(crate) _appmenu_state: appmenu::AppmenuManagerState,
+    /// `zwp_virtual_keyboard_manager_v1` - lets a client (`wtype`, `ydotool
+    /// type`, an accessibility tool, AGS's own global-menu shortcut items)
+    /// inject synthetic key events through the exact same keyboard-focus/
+    /// keymap pipeline a real key press already goes through, rather than
+    /// needing a compositor-specific IPC of its own. Not `Option`-gated,
+    /// same reasoning as `_appmenu_state` just above: injecting a key event
+    /// has nothing GPU/DRM-specific about it either. Smithay's own
+    /// `wayland::virtual_keyboard` module provides the full protocol
+    /// implementation (`delegate_virtual_keyboard_manager!` in
+    /// `protocols.rs` wires it up); this compositor only supplies the
+    /// global itself. Absence of this was reported live as "most options in
+    /// global menu don't work" - every keyboard-shortcut item there is
+    /// delivered via `wtype`, which silently does nothing at all without
+    /// this protocol (`wtype ""` exits 1 with "Compositor does not support
+    /// the virtual keyboard protocol"), a failure the caller (AGS, fire-
+    /// and-forget) never even saw.
+    pub(crate) _virtual_keyboard_state: smithay::wayland::virtual_keyboard::VirtualKeyboardManagerState,
     pub(crate) _foreign_toplevel_state: foreign_toplevel::ForeignToplevelState,
     /// Every bound `zwlr_foreign_toplevel_manager_v1` (one per dock/switcher
     /// client), so a newly-created window can be announced to all of them --
@@ -238,6 +293,15 @@ pub(crate) struct CompState {
     /// the default when no client has said). See `cursor.rs` for why this
     /// has to be drawn by us on the DRM backend.
     pub(crate) cursor_status: smithay::input::pointer::CursorImageStatus,
+    /// Whether `cursor_status`'s current value was last set by us (hovering
+    /// our own decoration's resize edge/drag area) rather than by a client's
+    /// own `wl_pointer.set_cursor` request - see `input.rs::update_cursor_
+    /// shape`'s doc comment for the bug this exists to fix: without it, a
+    /// resize icon forced while hovering a decoration edge stayed on screen
+    /// indefinitely once the pointer moved onto plain client content,
+    /// because nothing about moving onto content gives the client any
+    /// reason to call `set_cursor` again itself.
+    pub(crate) decoration_cursor_active: bool,
     /// Built-in cursor bitmaps (arrow, text, resize directions), built once
     /// at startup rather than per frame.
     pub(crate) cursor_buffers: crate::cursor::CursorBuffers,
@@ -353,6 +417,22 @@ pub(crate) struct CompState {
     /// own blanket call, which never actually checked whether this
     /// specific window was one of the windows that triggered the tick.
     pub(crate) decoration_signatures: HashMap<WindowId, DecorationSignature>,
+    /// Which titlebar button (if any) the pointer is currently over, on
+    /// which window, and *when that hover started* - set from `handle_
+    /// pointer_position`'s own `hit_test` result, read by `redraw_
+    /// decoration_buffer` to brighten that one button's dot and animate
+    /// its glyph in (see `decoration::render_titlebar`'s `hovered`
+    /// parameter). Explicitly requested background-highlight-on-hover
+    /// behaviour for the titlebar buttons, previously unimplemented - see
+    /// `docs/TODO.md`. A single `Option`, not a per-window map: only one
+    /// button can plausibly be hovered at a time, across every window.
+    /// The `Instant` is *only* updated when the hovered button itself
+    /// changes (see the comparison at its own call site, which ignores
+    /// this field) - it marks "hover started here", not "last motion
+    /// event", so `tick_hover_glyph_animation` can measure real elapsed
+    /// hover time instead of resetting every frame the pointer so much as
+    /// twitches while still over the same button.
+    pub(crate) hovered_titlebar_button: Option<(WindowId, srdwm_core::TitlebarHit, Instant)>,
     /// A window's drop-shadow bitmap (`decoration::shadow_bitmap`), cached
     /// the same way and at the same trigger points as `border_top_decorations`
     /// - rebuilt only on creation or a real size change, not per frame, for
@@ -384,19 +464,24 @@ pub(crate) struct CompState {
     /// terminal, with nothing else in this struct tracking that.
     pub(crate) content_epoch: HashMap<WindowId, u64>,
     /// The udev/Pixman-backend rounded-corner masked copy of a window's own
-    /// content (`rounded_corners_pixman::masked_content_buffer`), paired
-    /// with the `content_epoch` value and the `corner_radius` (in bit-cast
-    /// `u32` form - `f32` has no `Eq`) it was built from - see
-    /// `elements::rounded_content_buffer`, which owns rebuilding this. The
-    /// radius half exists because `corner_radius` is now live-settable
-    /// (`srd set corner_radius`/a rule) without any client commit - content
-    /// epoch alone wouldn't notice that change, leaving a stale mask built
-    /// from the old radius on screen until the client's next real repaint.
-    /// Always empty on the winit backend (GLES rounds via a shader instead,
-    /// `rounded_corners_program`), but costs nothing to declare here
-    /// unconditionally, the same call `rounded_corners_program` itself
-    /// already makes.
-    pub(crate) rounded_content_buffers: HashMap<WindowId, (u64, u32, MemoryRenderBuffer)>,
+    /// content (`rounded_corners_pixman::masked_content_buffer`), keyed by
+    /// everything that can make a rebuilt-from-scratch copy necessary --
+    /// see `elements::rounded_content_buffer`, which owns rebuilding this.
+    /// In order: the `content_epoch` value it was built from (bumped once
+    /// per real client commit); the `corner_radius` it was built from, in
+    /// bit-cast `u32` form (`f32` has no `Eq`) - live-settable (`srd set
+    /// corner_radius`/a rule) without any client commit, so `content_epoch`
+    /// alone wouldn't notice a change; the tree-render `loc` it was built
+    /// from (the negated `content_offset`, changes if a client alters its
+    /// own declared shadow-margin geometry); and the off-screen buffer
+    /// `size` it was built at (the window's own content dimensions --
+    /// stale the moment those change, same reason `redraw_decoration_
+    /// buffer`'s own signature check exists for the titlebar/border
+    /// bitmaps). Always empty on the winit backend (GLES rounds via a
+    /// shader instead, `rounded_corners_program`), but costs nothing to
+    /// declare here unconditionally, the same call `rounded_corners_
+    /// program` itself already makes.
+    pub(crate) rounded_content_buffers: HashMap<WindowId, (u64, u32, (i32, i32), (i32, i32), MemoryRenderBuffer)>,
     /// Persistent solid-colour buffers backing a window's other three
     /// border strips (bottom, left, right - `decoration::border_strips`'
     /// order past index 0), reused by position every frame rather than
@@ -410,8 +495,15 @@ pub(crate) struct CompState {
     /// dropping them would lose the damage-tracking stability the whole
     /// scheme exists for the moment fragment counts fluctuate back up.
     pub(crate) border_side_buffers: HashMap<WindowId, Vec<SolidColorBuffer>>,
-    /// Client-visible size (`geometry` minus the titlebar band) last sent to
-    /// each window via `xdg_toplevel.configure`. `sync_geometry` runs on
+    /// Persistent solid-colour buffer backing the whole-output night-light/
+    /// reading-mode overlay, one per output name - same "reuse the buffer
+    /// so its `Id` stays stable across frames" reasoning as `border_side_
+    /// buffers` above. See `color_filter::render_element`.
+    pub(crate) color_filter_buffers: HashMap<String, SolidColorBuffer>,
+    /// Client-visible size (`geometry` minus the titlebar band, converted
+    /// to logical points for whichever monitor the window is currently on
+    /// - see `sync_geometry`'s own doc comment) last sent to each window
+    /// via `xdg_toplevel.configure`. `sync_geometry` runs on
     /// every pointer-motion tick while a window is being dragged or resized
     /// (see `input::handle_pointer_position`); a plain move changes only
     /// position, not size, so without this it was re-sending a configure
@@ -419,6 +511,28 @@ pub(crate) struct CompState {
     /// motion event of every drag, which is what made moving a window
     /// stutter. Only a real size change now does either.
     pub(crate) last_synced_size: HashMap<WindowId, (i32, i32)>,
+    /// A size-changing `xdg_toplevel.configure` that's been sent but not
+    /// yet reflected in the client's own real committed content size --
+    /// `(size requested, when it was sent)`. `sync_geometry` won't send
+    /// *another* size-changing configure for the same window while an
+    /// entry is still here (unless `CONFIGURE_THROTTLE_TIMEOUT` has
+    /// elapsed - see that constant's own doc comment for why this can
+    /// never wedge resize entirely).
+    ///
+    /// Niri throttles the same way (`window/mapped.rs`'s `ConfigureIntent::
+    /// Throttled`, keyed on the configure serial rather than a size/time
+    /// pair, but the same idea) - its own comment: "some clients do not
+    /// batch size requests, leading to bad behavior with very fast input
+    /// devices... this throttling also helps interactive resize
+    /// transactions preserve visual consistency." srdwm had no equivalent
+    /// at all: `sync_geometry` runs on every pointer-motion tick of an
+    /// active resize and only ever compared the newly-requested size
+    /// against the *previous request*, never against what the client had
+    /// actually caught up to - a fast drag (a real high-poll-rate mouse,
+    /// confirmed as niri's own stated motivation) could queue several
+    /// configures before the client acknowledged the first, the exact
+    /// backlog this field exists to prevent.
+    pub(crate) pending_size_configure: HashMap<WindowId, ((i32, i32), Instant)>,
     pub(crate) pending: Rc<RefCell<Vec<CoreEvent>>>,
     pub(crate) bound_keys: Rc<HashSet<String>>,
     /// Combos that repeat while held (`srd.bind_repeat`).
@@ -650,13 +764,12 @@ impl CompState {
 /// `border_color` is a real, used feature (rules set distinct colours per
 /// app), and dimming keeps that distinction visible at a glance while
 /// still making focus unambiguous.
-pub(crate) fn effective_border_color(configured: (u8, u8, u8), focused: bool) -> (u8, u8, u8) {
+pub(crate) fn effective_border_color(configured: (u8, u8, u8), focused: bool, dim: f32) -> (u8, u8, u8) {
     if focused {
         return configured;
     }
-    const DIM: f32 = 0.35;
-    let dim = |c: u8| (c as f32 * DIM) as u8;
-    (dim(configured.0), dim(configured.1), dim(configured.2))
+    let scale = |c: u8| (c as f32 * dim).round().clamp(0.0, 255.0) as u8;
+    (scale(configured.0), scale(configured.1), scale(configured.2))
 }
 
 /// Output lookup. Everything that used to reach for a single
diff --git a/crates/wayland/src/state/tests.rs b/crates/wayland/src/state/tests.rs
index bccbae2..8d1d8b3 100644
--- a/crates/wayland/src/state/tests.rs
+++ b/crates/wayland/src/state/tests.rs
@@ -2,12 +2,15 @@
 
     #[test]
     fn focused_window_keeps_its_configured_colour() {
-        assert_eq!(effective_border_color((136, 192, 208), true), (136, 192, 208));
+        // The dim factor is irrelevant when focused - passing an
+        // obviously-wrong one here doubles as proof the early return never
+        // even looks at it.
+        assert_eq!(effective_border_color((136, 192, 208), true, 0.0), (136, 192, 208));
     }
 
     #[test]
     fn unfocused_window_is_dimmed_but_still_recognisably_that_colour() {
-        let dimmed = effective_border_color((136, 192, 208), false);
+        let dimmed = effective_border_color((136, 192, 208), false, 0.35);
         // Dimmer in every channel...
         assert!(dimmed.0 < 136 && dimmed.1 < 192 && dimmed.2 < 208);
         // ...but not black, and the channels' relative order is preserved
@@ -19,6 +22,15 @@
     }
 
     #[test]
+    fn inactive_dim_factor_is_actually_configurable() {
+        // `theme.decorations.border.inactive_dim` - `1.0` keeps an
+        // unfocused border identical to focused, `0.0` removes it entirely
+        // (fully black, matching every channel scaled to zero).
+        assert_eq!(effective_border_color((136, 192, 208), false, 1.0), (136, 192, 208));
+        assert_eq!(effective_border_color((136, 192, 208), false, 0.0), (0, 0, 0));
+    }
+
+    #[test]
     fn window_anim_starts_at_from_and_ends_at_to() {
         let anim = WindowAnim {
             from: srdwm_core::Rect::new(0, 100, 300, 200),
diff --git a/crates/wayland/src/state/tick.rs b/crates/wayland/src/state/tick.rs
index 6ef0ed6..333c30b 100644
--- a/crates/wayland/src/state/tick.rs
+++ b/crates/wayland/src/state/tick.rs
@@ -34,6 +34,28 @@ impl CompState {
         }
     }
 
+    /// Forces a fresh `redraw_decoration_buffer` call every frame while the
+    /// titlebar-button glyph-reveal-on-hover animation is still in
+    /// progress; called once per redraw from both backends' poll loops,
+    /// alongside `tick_animations`. Needed for the same reason that one
+    /// is: `redraw_decoration_buffer`'s own signature-based cache only
+    /// rebuilds when *called*, and nothing else calls it once a pointer
+    /// stops moving over an already-hovered button - without this, the
+    /// glyph would jump straight from invisible to full opacity on the
+    /// one motion event that started the hover, then never update again
+    /// for the rest of the animation's own duration, since no further
+    /// motion event arrives to drive it. Does nothing in `theme.
+    /// button_glyph_always` mode or once the animation has actually
+    /// finished (`HOVER_GLYPH_DURATION` elapsed) - both are already a
+    /// stable, cached final state with nothing left to advance.
+    pub(crate) fn tick_hover_glyph_animation(&mut self) {
+        let Some((id, _, start)) = self.hovered_titlebar_button else { return };
+        if self.wm.borrow().theme.button_glyph_always || start.elapsed() >= decoration::HOVER_GLYPH_DURATION {
+            return;
+        }
+        self.redraw_decoration_buffer(id);
+    }
+
     /// Re-applies `WindowManager`'s own stacking order to `Space`, bottom
     /// to top.
     ///
diff --git a/crates/wayland/src/udev/capture.rs b/crates/wayland/src/udev/capture.rs
index bcf2aa4..fb4c22f 100644
--- a/crates/wayland/src/udev/capture.rs
+++ b/crates/wayland/src/udev/capture.rs
@@ -8,22 +8,32 @@
 //! workspace that, most of the time, is *not* the one presented.
 //!
 //! Deliberately simple, not a small reimplementation of
-//! `render_udev_frame`: only window content is drawn, no borders,
-//! shadows, titlebars, cursor or layer-shell surfaces - every consumer
-//! this was built for (a workspace-switcher tile) draws those tiny, where
-//! that detail is imperceptible, and skipping them keeps this from needing
-//! to duplicate that function's animation/occlusion bookkeeping. Always
-//! renders at the target monitor's native resolution and downscales
-//! afterward if a smaller size was requested, rather than trying to get
-//! smithay's fractional-output-scale rendering path exactly right for a
-//! target with no real `Output` behind it.
+//! `render_udev_frame`: no borders, shadows, titlebars or cursor --
+//! every consumer this was built for (a workspace-switcher tile) draws
+//! those tiny, where that detail is imperceptible, and skipping them
+//! keeps this from needing to duplicate that function's animation/
+//! occlusion bookkeeping. The background/bottom layer-shell surfaces
+//! (the wallpaper) *are* included, unlike the rest of that list - a
+//! capture with no windows on it and no wallpaper either is
+//! indistinguishable from broken, and was reported live as exactly that:
+//! "why does current workspace show black background" once measured
+//! against a real screenshot of the same moment (mean luminance ~0.5 vs.
+//! this capture's own ~0.03, i.e. genuinely near-black, not just "looks
+//! dark on this monitor"). An inactive workspace with literally no
+//! windows placed on it rendered *exactly* black (mean and variance both
+//! zero) for the same reason - there was nothing else in the frame at
+//! all to show. Always renders at the target monitor's native resolution
+//! and downscales afterward if a smaller size was requested, rather than
+//! trying to get smithay's fractional-output-scale rendering path
+//! exactly right for a target with no real `Output` behind it.
 
 use super::*;
 use smithay::backend::allocator::Fourcc;
-use smithay::backend::renderer::element::surface::{render_elements_from_surface_tree, WaylandSurfaceRenderElement};
+use smithay::backend::renderer::element::surface::render_elements_from_surface_tree;
 use smithay::backend::renderer::element::Kind;
 use smithay::backend::renderer::{Bind, ExportMem, Offscreen};
 use smithay::utils::{Buffer as BufferCoord, Transform};
+use smithay::wayland::shell::wlr_layer::Layer;
 
 impl CompState {
     /// Services every capture request queued since the last poll. Takes
@@ -56,8 +66,8 @@ impl CompState {
         }
 
         let ids = self.wm.borrow().window_ids_on_workspace_front_to_back(req.workspace);
-        let mut elements: Vec<WaylandSurfaceRenderElement<PixmanRenderer>> = Vec::new();
         let Some(udev) = self.udev.as_mut() else { return Err("no udev backend".to_string()) };
+        let mut elements: Vec<crate::elements::OverlayElement<PixmanRenderer>> = Vec::new();
         for id in ids {
             let Some(w) = self.id_to_window.get(&id) else { continue };
             let Some(surface) = crate::input::dwindow_wl_surface(w) else { continue };
@@ -68,7 +78,26 @@ impl CompState {
             // a gap in the capture too.
             let content_offset = w.geometry().loc;
             let loc = (geom.x - origin.0 - content_offset.x, geom.y - origin.1 - content_offset.y);
-            elements.extend(render_elements_from_surface_tree(&mut udev.renderer, &surface, loc, 1.0, 1.0, Kind::Unspecified));
+            elements.extend(render_elements_from_surface_tree::<_, crate::elements::OverlayElement<PixmanRenderer>>(
+                &mut udev.renderer,
+                &surface,
+                loc,
+                1.0,
+                1.0,
+                Kind::Unspecified,
+            ));
+        }
+        // Background/bottom layer-shell (the wallpaper) last - bottommost,
+        // matching `render_udev_frame`'s own ordering convention (see that
+        // function's matching comment). The real output behind whichever
+        // monitor `origin`/`native` came from, matched by location; missing
+        // entirely (an output that vanished between resolving `origin`
+        // above and here, a narrow race) just means no wallpaper in this
+        // one capture, not a hard failure - windows above still render.
+        if let Some(head) = udev.heads.iter().find(|h| h.location == Point::from(origin)) {
+            elements.extend(crate::elements::output_layer_elements(&mut udev.renderer, &head.output, |layer| {
+                matches!(layer, Layer::Background | Layer::Bottom)
+            }));
         }
 
         let (nw, nh) = (native.0 as i32, native.1 as i32);
diff --git a/crates/wayland/src/udev/drm.rs b/crates/wayland/src/udev/drm.rs
index fd06619..efe53aa 100644
--- a/crates/wayland/src/udev/drm.rs
+++ b/crates/wayland/src/udev/drm.rs
@@ -12,12 +12,22 @@ fn mode_refresh_mhz(mode: &DrmMode) -> i32 {
 /// Brings one connector up: allocates its scanout buffers, sets the mode,
 /// and creates the `wl_output` global. Shared by startup and hotplug so a
 /// monitor plugged in later is set up exactly like one present at boot.
+///
+/// `scale` is `srd.monitor.scale(name, ...)`'s stored value for this
+/// connector, if any - an explicit override always wins. `None` no
+/// longer means "always 1.0": it falls through to `srdwm_core::monitor::
+/// auto_scale_for`, computed fresh from this connector's own real EDID
+/// physical size and resolution, so a physically large, low-density
+/// monitor gets a sensible scale with no per-connector-name config
+/// needed at all.
 pub(crate) fn bring_up_head(
     card: &Card,
     dh: &DisplayHandle,
     probe: &ConnectorProbe,
     crtc: crtc::Handle,
     x_offset: i32,
+    logical_x: i32,
+    scale: Option<f64>,
 ) -> PlatformResult<(UdevHead, crate::state::OutputEntry)> {
     let (width, height) = probe.mode.size();
     let (width, height) = (width as i32, height as i32);
@@ -32,7 +42,8 @@ pub(crate) fn bring_up_head(
     // Physical size in millimeters comes straight from EDID via the
     // connector, not the hardcoded (0, 0) this used to be - some clients
     // compute their own effective DPI from it (independently of the
-    // compositor's own scale factor, which srdwm always reports as 1), so
+    // compositor's own scale factor, which defaults to 1 unless `srd.
+    // monitor.scale` overrides it for this connector), so
     // reporting "no physical size at all" was live, wrong data reaching
     // every client, not just an unfilled-in placeholder.
     let (phys_w, phys_h) = probe.info.size().unwrap_or((0, 0));
@@ -42,7 +53,28 @@ pub(crate) fn bring_up_head(
         PhysicalProperties { size: physical_mm.into(), subpixel: Subpixel::Unknown, make: "srdwm".into(), model: "drm".into() },
     );
     let mode = OutputMode { size: (width, height).into(), refresh: mode_refresh_mhz(&probe.mode) };
-    output.change_current_state(Some(mode), Some(Transform::Normal), None, Some((x_offset, 0).into()));
+    let resolved_scale = scale.unwrap_or_else(|| srdwm_core::monitor::auto_scale_for(physical_mm, (width, height)));
+    // `x_offset` is physical (the caller accumulates it from real head
+    // widths - see `UdevHead::location`'s own doc comment for why that's
+    // the space this compositor tracks output position in internally),
+    // but `change_current_state`'s own position parameter is a real
+    // Wayland-protocol value and `wl_output`/`xdg_output` always report
+    // position to clients in logical points - so it needs the caller's
+    // own *separately*-accumulated `logical_x`, not a value derived from
+    // `x_offset` and this head's own scale alone. Dividing `x_offset` by
+    // just this head's own `resolved_scale` (what this used to do) is only
+    // correct for the first head in a layout, or when every head shares
+    // the same scale - for any later head following one with a
+    // *different* scale, this head's own scale has nothing to do with how
+    // much logical space the *previous* heads actually occupy, so it
+    // computed the wrong logical position for anything past the first
+    // output. Reported live (measured from inside GTK, not inferred) as
+    // two monitors' logical rectangles overlapping by a few hundred
+    // pixels whenever one had a non-1.0 scale - ambiguous "which monitor
+    // is this point on" answers, and hit-testing/screenshots landing on
+    // the wrong output in the overlap band. See `platform.rs`'s startup
+    // loop for how `logical_x` is actually accumulated correctly.
+    output.change_current_state(Some(mode), Some(Transform::Normal), Some(smithay::output::Scale::Fractional(resolved_scale)), Some((logical_x, 0).into()));
     output.set_preferred(mode);
     let global = output.create_global::<CompState>(dh);
 
@@ -56,9 +88,11 @@ pub(crate) fn bring_up_head(
         buffers,
         front: 0,
         flip_pending: false,
+        flip_pending_since: Instant::now(),
         ages: [0, 0],
         location,
         size: (width, height),
+        mode: probe.mode,
     };
     Ok((head, crate::state::OutputEntry { output, location }))
 }
@@ -87,7 +121,16 @@ pub(crate) fn probe_connected(card: &Card) -> PlatformResult<Vec<ConnectorProbe>
         if info.state() != connector::State::Connected {
             continue;
         }
-        let name = format!("{:?}-{}", info.interface(), info.interface_id());
+        // `info.interface()`'s `Debug` output is Rust's own enum variant
+        // name (`HDMIA`, `EmbeddedDisplayPort`) - neither string exists
+        // anywhere else. The kernel, `ddcutil`, `/sys/class/drm`, and any
+        // config the user already has for another compositor all use the
+        // strings in `Interface::as_str()` (`HDMI-A`, `eDP`, and so on --
+        // taken directly from the kernel's own `drm_connector_enum_list`).
+        // Reported live: `srd monitors` showed `HDMIA-1`, a name that
+        // matched nothing, while `/sys/class/drm` and `ddcutil detect`
+        // both said `HDMI-A-1` for the same physical connector.
+        let name = format!("{}-{}", info.interface().as_str(), info.interface_id());
         // Prefer the mode the display advertises as PREFERRED (its native
         // resolution) rather than whatever happens to be listed first --
         // the list order is not guaranteed, and picking wrong means running
diff --git a/crates/wayland/src/udev/mod.rs b/crates/wayland/src/udev/mod.rs
index 501e3fc..1490d13 100644
--- a/crates/wayland/src/udev/mod.rs
+++ b/crates/wayland/src/udev/mod.rs
@@ -33,13 +33,14 @@ use std::rc::Rc;
 use std::time::{Duration, Instant};
 
 use smithay::backend::input::{
-    Axis, ButtonState as BackendButtonState, Event as InputEventTrait, GestureBeginEvent as BackendGestureBeginEvent,
+    AbsolutePositionEvent, Axis, ButtonState as BackendButtonState, Event as InputEventTrait, GestureBeginEvent as BackendGestureBeginEvent,
     GestureEndEvent as BackendGestureEndEvent, GesturePinchUpdateEvent as BackendGesturePinchUpdateEvent, InputEvent,
     PointerAxisEvent, PointerButtonEvent, PointerMotionEvent,
 };
 use smithay::backend::libinput::{LibinputInputBackend, LibinputSessionInterface};
 use smithay::backend::renderer::damage::OutputDamageTracker;
 use smithay::backend::renderer::element::memory::MemoryRenderBufferRenderElement;
+use smithay::backend::renderer::element::solid::SolidColorBuffer;
 use smithay::backend::renderer::element::Kind;
 use smithay::backend::renderer::pixman::PixmanRenderer;
 use smithay::backend::renderer::{Bind, ImportDma};
@@ -128,6 +129,11 @@ pub(crate) struct UdevHead {
     /// A flip is in flight; the next frame for this head waits for the DRM
     /// page-flip event (matched by `crtc`) before starting.
     pub(crate) flip_pending: bool,
+    /// When the current `flip_pending` was set - lets `render_udev_frame`
+    /// notice a page-flip event that never arrived (or arrived but matched
+    /// no head - see `FLIP_TIMEOUT`'s own doc comment) instead of waiting
+    /// on it forever. Meaningless while `flip_pending` is `false`.
+    pub(crate) flip_pending_since: Instant,
     /// Per-buffer-slot age passed to `damage_tracker.render_output`: how
     /// many *damage-producing* renders ago that exact buffer was last
     /// brought fully up to date. 0 means "never rendered, contents
@@ -149,6 +155,16 @@ pub(crate) struct UdevHead {
     /// Origin of this head in the global coordinate space.
     pub(crate) location: Point<i32, Logical>,
     pub(crate) size: (i32, i32),
+    /// The DRM mode this head was actually brought up with - kept so a VT-
+    /// switch resume can reassert the CRTC with its real connector and
+    /// mode (see `register_session_notifier`'s own `ActivateSession` arm),
+    /// rather than the empty connector list and `None` mode that call used
+    /// to pass, which does not reassert a CRTC at all - it is DRM/KMS's
+    /// own shape for *disabling* one. Confirmed live: switching back to
+    /// srdwm's VT after switching away left the screen black, with no
+    /// further VT switch (either direction) able to recover it, matching a
+    /// CRTC left disabled rather than restored.
+    pub(crate) mode: DrmMode,
 }
 
 /// Everything the DRM/udev backend needs that the nested winit backend
@@ -173,14 +189,112 @@ pub(crate) struct UdevState {
     /// backend needed the session handle after startup, so it was never
     /// retained anywhere before this.
     pub(crate) session: LibSeatSession,
+    /// Connector names administratively disabled via `srd dispatch set
+    /// output enabled <name> false` - still physically connected (DRM
+    /// still reports/probes them), just deliberately not driven. Checked
+    /// by `reprobe_outputs`'s own "added" loop so an unrelated hotplug
+    /// event doesn't resurrect one of these the next time anything else
+    /// plugs or unplugs - without this, the very next `Changed` uevent
+    /// (any connector, not just this one) would see a disabled-but-still-
+    /// present connector as newly "added" (present in a fresh probe,
+    /// absent from `heads`, exactly the condition that branch already
+    /// uses to detect a real hotplug) and bring it straight back up.
+    pub(crate) disabled_connectors: std::collections::HashSet<String>,
+    /// `WorkspaceId` this backend last built `custom_elements` for --
+    /// compared against `WindowManager::current_workspace()` at the top of
+    /// every `render_udev_frame` call so a switch can force every head's
+    /// `ages` back to `[0, 0]` (see that call site's own comment for why).
+    /// `None` before the very first frame, which already renders fully
+    /// regardless (every head starts with `ages: [0, 0]` - see
+    /// `UdevHead`'s own field).
+    pub(crate) last_rendered_workspace: Option<srdwm_core::WorkspaceId>,
 }
 
 impl UdevState {
-    /// Bounding box of every head, used to clamp pointer motion.
-    fn bounds(&self) -> (f64, f64) {
-        let w = self.heads.iter().map(|h| h.location.x + h.size.0).max().unwrap_or(0);
-        let h = self.heads.iter().map(|h| h.location.y + h.size.1).max().unwrap_or(0);
-        (w as f64, h as f64)
+    /// Bounding box of every head, used to clamp pointer motion --
+    /// `(min_x, min_y, max_x, max_y)`, not just a `(width, height)`
+    /// implicitly anchored at `(0, 0)` (what this used to return, and what
+    /// every call site clamped into with a hardcoded `0.0` floor). That
+    /// was only ever correct while every head's `location.x`/`location.y`
+    /// stayed `>= 0`, true for `reprobe_outputs`' own left-to-right hotplug
+    /// layout but not guaranteed once `set_output_position` exists: an
+    /// "extend left"/"extend above" arrangement (a real one, requested and
+    /// applied live by an AGS peer session's monitor-layout panel) places
+    /// the newly-added head at a *negative* `x`/`y` relative to whichever
+    /// one stayed at the origin. With the old `(0, w)` clamp, the pointer
+    /// could never actually cross into that negative-origin region at
+    /// all - reported live as "clicked it now I can't go to other
+    /// monitor at all" once such an arrangement was applied. The AGS
+    /// side has since started normalising every arrangement it sends so
+    /// the leftmost/topmost edge lands at `0` again, which works around
+    /// this from outside, but srdwm's own pointer clamp assuming an origin
+    /// no other part of this backend actually enforces is the real bug --
+    /// fixed here instead of just left for every future caller to avoid.
+    fn bounds(&self) -> (f64, f64, f64, f64) {
+        bounds_of(self.heads.iter().map(|h| (h.location.x, h.location.y, h.size.0, h.size.1)))
+    }
+}
+
+/// The actual arithmetic behind [`UdevState::bounds`], over plain
+/// `(x, y, width, height)` tuples rather than real `UdevHead`s - pulled
+/// out so it's testable without a real DRM/`Card` handle, which every
+/// `UdevHead` in this module otherwise needs to even construct.
+fn bounds_of(heads: impl Iterator<Item = (i32, i32, i32, i32)>) -> (f64, f64, f64, f64) {
+    let mut min_x = 0;
+    let mut min_y = 0;
+    let mut max_x = 0;
+    let mut max_y = 0;
+    let mut any = false;
+    for (x, y, w, h) in heads {
+        if !any {
+            min_x = x;
+            min_y = y;
+            any = true;
+        } else {
+            min_x = min_x.min(x);
+            min_y = min_y.min(y);
+        }
+        max_x = max_x.max(x + w);
+        max_y = max_y.max(y + h);
+    }
+    (min_x as f64, min_y as f64, max_x as f64, max_y as f64)
+}
+
+#[cfg(test)]
+mod bounds_tests {
+    use super::bounds_of;
+
+    #[test]
+    fn single_head_at_origin_matches_the_old_zero_anchored_behaviour() {
+        assert_eq!(bounds_of([(0, 0, 1920, 1080)].into_iter()), (0.0, 0.0, 1920.0, 1080.0));
+    }
+
+    #[test]
+    fn two_heads_left_to_right_from_origin() {
+        assert_eq!(bounds_of([(0, 0, 1920, 1080), (1920, 0, 1920, 1080)].into_iter()), (0.0, 0.0, 3840.0, 1080.0));
+    }
+
+    #[test]
+    fn negative_origin_head_is_reflected_in_min_not_clamped_to_zero() {
+        // The actual regression this exists for: an "extend left"
+        // arrangement places the new head at a negative x, and the old
+        // `(width, height)`-only version of this function (implicitly
+        // anchored at 0) made that head's own region completely
+        // unreachable by pointer motion - reported live as "clicked it
+        // now I can't go to other monitor at all".
+        let (min_x, min_y, max_x, max_y) = bounds_of([(0, 0, 1920, 1080), (-1920, 0, 1920, 1080)].into_iter());
+        assert_eq!((min_x, min_y, max_x, max_y), (-1920.0, 0.0, 1920.0, 1080.0));
+    }
+
+    #[test]
+    fn negative_origin_above_is_reflected_in_min_y() {
+        let (min_x, min_y, max_x, max_y) = bounds_of([(0, 0, 1920, 1080), (0, -1080, 1920, 1080)].into_iter());
+        assert_eq!((min_x, min_y, max_x, max_y), (0.0, -1080.0, 1920.0, 1080.0));
+    }
+
+    #[test]
+    fn no_heads_at_all_is_a_degenerate_zero_sized_box_not_a_panic() {
+        assert_eq!(bounds_of(std::iter::empty()), (0.0, 0.0, 0.0, 0.0));
     }
 }
 
@@ -204,8 +318,33 @@ impl UdevHead {
     /// buffer (software rendering writes into its own owned image, not the
     /// scanout memory directly, to avoid tying that image's lifetime to an
     /// mmap - see this module's docs) and flips to it.
-    fn copy_and_flip(&mut self, card: &Card, back: usize) -> std::io::Result<()> {
-        let (src_stride, height) = (self.buffers[back].image.stride(), self.buffers[back].image.height());
+    /// `damage` is the exact set of rects `render_output` just re-rendered
+    /// into `self.buffers[back].image` - an empty slice means "copy
+    /// everything" (the locked/lock-UI render paths don't bother computing
+    /// per-rect damage, so this is also the safe fallback for any caller
+    /// that can't cheaply produce real rects), otherwise only those rows'
+    /// column ranges are copied.
+    ///
+    /// Used to be an unconditional full-buffer copy regardless of how
+    /// little of the frame actually changed - `render_output`'s own
+    /// age-based damage tracking already leaves everything outside
+    /// `damage` untouched in `image` (correct: that buffer's untouched
+    /// pixels still match what was on screen `ages[back]` frames ago), so
+    /// `dumb` - this same buffer's DRM-mapped twin, previously brought up
+    /// to date by this exact function on that same past frame - is
+    /// already correct everywhere outside `damage` too. Copying the whole
+    /// buffer anyway meant a full `stride * height` memcpy on every single
+    /// presented frame, for content as small as a moved cursor or a
+    /// blinking terminal caret - confirmed as the largest per-frame CPU
+    /// cost on this software `PixmanRenderer` backend by a direct
+    /// comparison against niri's DRM-composited present path (which has no
+    /// equivalent copy step at all) and mutter's native backend (which
+    /// explicitly restricts its own swap to damaged regions,
+    /// `swap_buffers_with_damage`) - this is the same technique, adapted
+    /// to a raw byte copy instead of a GL/EGL damage extension.
+    fn copy_and_flip(&mut self, card: &Card, back: usize, damage: &[Rectangle<i32, Physical>]) -> std::io::Result<()> {
+        let (src_stride, height, width) =
+            (self.buffers[back].image.stride(), self.buffers[back].image.height(), self.buffers[back].image.width());
         let byte_len = src_stride * height;
         // SAFETY: `image` owns this memory and outlives the byte slice we
         // construct from it here; we only read, and only for the duration
@@ -224,23 +363,142 @@ impl UdevHead {
         let dst_stride = self.buffers[back].dumb.pitch() as usize;
         {
             let mut mapping = card.map_dumb_buffer(&mut self.buffers[back].dumb)?;
-            let dst = mapping.as_mut();
-            let row_len = src_stride.min(dst_stride);
-            for row in 0..height {
-                let s = row * src_stride;
-                let d = row * dst_stride;
-                if s + row_len > src.len() || d + row_len > dst.len() {
-                    break;
-                }
-                dst[d..d + row_len].copy_from_slice(&src[s..s + row_len]);
-            }
+            copy_damaged_rows(src, mapping.as_mut(), src_stride, dst_stride, width, height, damage);
         }
         card.page_flip(self.crtc, self.buffers[back].fb, PageFlipFlags::EVENT, None)?;
         self.flip_pending = true;
+        self.flip_pending_since = Instant::now();
         Ok(())
     }
 }
 
+/// The row/column copy math behind [`DrmHead::copy_and_flip`], pulled out
+/// as a free function over plain slices so it's testable without a real
+/// `Card`/dumb buffer - everything else in that method needs live DRM
+/// state, this doesn't. `damage` empty means "copy every row in full"
+/// (`width`/`height` are pixels, `src_stride`/`dst_stride` bytes); a
+/// non-empty `damage` copies only each rect's row/column span, clamped to
+/// the narrower of the two strides and to `width`/`height` the same way
+/// the full-copy path always has.
+fn copy_damaged_rows(src: &[u8], dst: &mut [u8], src_stride: usize, dst_stride: usize, width: usize, height: usize, damage: &[Rectangle<i32, Physical>]) {
+    let full_row_len = src_stride.min(dst_stride);
+    let copy_row = |dst: &mut [u8], row: usize, col_start_bytes: usize, col_len: usize| {
+        let s = row * src_stride + col_start_bytes;
+        let d = row * dst_stride + col_start_bytes;
+        let len = col_len.min(full_row_len.saturating_sub(col_start_bytes));
+        if len == 0 || s + len > src.len() || d + len > dst.len() {
+            return;
+        }
+        dst[d..d + len].copy_from_slice(&src[s..s + len]);
+    };
+    if damage.is_empty() {
+        for row in 0..height {
+            copy_row(dst, row, 0, full_row_len);
+        }
+        return;
+    }
+    const BPP: usize = 4; // Argb8888/Xrgb8888, same assumption every other raw-buffer path in this codebase makes.
+    for rect in damage {
+        let y0 = rect.loc.y.max(0) as usize;
+        let y1 = (rect.loc.y.saturating_add(rect.size.h).max(0) as usize).min(height);
+        let x0 = rect.loc.x.max(0) as usize;
+        let x1 = (rect.loc.x.saturating_add(rect.size.w).max(0) as usize).min(width);
+        if x1 <= x0 {
+            continue;
+        }
+        let (col_start_bytes, col_len) = (x0 * BPP, (x1 - x0) * BPP);
+        for row in y0..y1 {
+            copy_row(dst, row, col_start_bytes, col_len);
+        }
+    }
+}
+
+#[cfg(test)]
+mod copy_damaged_rows_tests {
+    use super::copy_damaged_rows;
+    use smithay::utils::{Physical, Point, Rectangle, Size};
+
+    fn rect(x: i32, y: i32, w: i32, h: i32) -> Rectangle<i32, Physical> {
+        Rectangle::new(Point::from((x, y)), Size::from((w, h)))
+    }
+
+    /// A tiny 4x3 BGRA canvas, one distinct byte value per pixel's blue
+    /// channel (row * width + col) so a wrong offset or a skipped pixel
+    /// shows up as the wrong number, not just "still zero".
+    fn make_src(width: usize, height: usize) -> Vec<u8> {
+        let mut buf = vec![0u8; width * height * 4];
+        for (i, px) in buf.chunks_exact_mut(4).enumerate() {
+            px[0] = i as u8;
+            px[3] = 255;
+        }
+        buf
+    }
+
+    #[test]
+    fn empty_damage_copies_every_row_in_full() {
+        let (w, h) = (4, 3);
+        let src = make_src(w, h);
+        let mut dst = vec![0u8; w * h * 4];
+        copy_damaged_rows(&src, &mut dst, w * 4, w * 4, w, h, &[]);
+        assert_eq!(dst, src);
+    }
+
+    #[test]
+    fn a_damage_rect_updates_only_its_own_pixels() {
+        let (w, h) = (4, 3);
+        let src = make_src(w, h);
+        let mut dst = vec![0u8; w * h * 4];
+        // Only the single pixel at (1, 1).
+        copy_damaged_rows(&src, &mut dst, w * 4, w * 4, w, h, &[rect(1, 1, 1, 1)]);
+        let idx = (1 * w + 1) * 4;
+        assert_eq!(dst[idx], src[idx], "the damaged pixel must be copied");
+        assert_eq!(dst[0], 0, "a pixel outside the damage rect must stay untouched");
+        assert_eq!(dst[dst.len() - 4], 0, "the last row's pixel is also outside the rect and must stay untouched");
+    }
+
+    #[test]
+    fn a_full_width_row_rect_copies_that_row_only() {
+        let (w, h) = (4, 3);
+        let src = make_src(w, h);
+        let mut dst = vec![0u8; w * h * 4];
+        copy_damaged_rows(&src, &mut dst, w * 4, w * 4, w, h, &[rect(0, 1, w as i32, 1)]);
+        let row1 = w * 4..w * 4 * 2;
+        assert_eq!(dst[row1.clone()], src[row1], "row 1 must be fully copied");
+        assert_eq!(&dst[..w * 4], &vec![0u8; w * 4][..], "row 0 must stay untouched");
+        assert_eq!(&dst[w * 4 * 2..], &vec![0u8; w * 4][..], "row 2 must stay untouched");
+    }
+
+    #[test]
+    fn a_rect_extending_past_the_buffer_is_clamped_not_panicking() {
+        let (w, h) = (4, 3);
+        let src = make_src(w, h);
+        let mut dst = vec![0u8; w * h * 4];
+        // Starts inside the buffer but both extends past its right/bottom
+        // edge and would run off a naive unclamped copy.
+        copy_damaged_rows(&src, &mut dst, w * 4, w * 4, w, h, &[rect(2, 2, 100, 100)]);
+        let idx = (2 * w + 2) * 4;
+        assert_eq!(dst[idx], src[idx], "the in-bounds corner of an oversized rect must still be copied");
+    }
+
+    #[test]
+    fn a_wider_destination_stride_does_not_shear_rows() {
+        // Destination row padded 4 extra bytes past the source's own
+        // stride - the same "driver-padded dumb buffer pitch" case the
+        // full-copy path was already written to handle; damage-restricted
+        // copying must preserve that, not just the empty-damage fallback.
+        let (w, h) = (4, 3);
+        let src = make_src(w, h);
+        let dst_stride = w * 4 + 4;
+        let mut dst = vec![0u8; dst_stride * h];
+        copy_damaged_rows(&src, &mut dst, w * 4, dst_stride, w, h, &[rect(0, 0, w as i32, h as i32)]);
+        for row in 0..h {
+            let s = row * w * 4..row * w * 4 + w * 4;
+            let d = row * dst_stride..row * dst_stride + w * 4;
+            assert_eq!(dst[d], src[s], "row {row} must land at the destination's own stride, not the source's");
+        }
+    }
+}
+
 mod capture;
 mod drm;
 mod outputs;
diff --git a/crates/wayland/src/udev/outputs.rs b/crates/wayland/src/udev/outputs.rs
index 6e282d6..c3291d8 100644
--- a/crates/wayland/src/udev/outputs.rs
+++ b/crates/wayland/src/udev/outputs.rs
@@ -2,6 +2,46 @@ use super::*;
 use super::drm::{bring_up_head, pick_crtc, probe_connected};
 
 impl CompState {
+    /// Applies whatever monitor layout `monitor_layout::load()` remembers
+    /// from a previous run, on top of the default left-to-right layout
+    /// every head was just brought up with. Call once, right after every
+    /// head exists but before the Wayland socket is bound - see the call
+    /// site in `platform.rs`'s `connect()` for why that ordering is the
+    /// entire point (no client, panel or otherwise, gets a chance to see
+    /// the un-restored arrangement, not even for one frame).
+    ///
+    /// A connector with no remembered entry (a monitor plugged in for the
+    /// first time, or a fresh install with no state file yet) is left
+    /// exactly where the default layout put it - this only ever narrows
+    /// toward a remembered position, never invents one.
+    pub(crate) fn restore_monitor_layout(&mut self) {
+        let remembered = crate::monitor_layout::load();
+        if remembered.is_empty() {
+            return;
+        }
+        // Disables first, deliberately: `disable_connector_by_name` ends
+        // with its own `relayout_outputs()` call, which recomputes every
+        // *remaining* head's position from the default left-to-right
+        // layout - doing that after a position restore below would just
+        // overwrite it again. Processing every disable up front means
+        // that default re-layout has already happened, once, before any
+        // remembered position gets applied on top of it.
+        for (name, entry) in &remembered {
+            if !entry.enabled {
+                self.disable_connector_by_name(name);
+            }
+        }
+        for (name, entry) in &remembered {
+            if !entry.enabled {
+                continue;
+            }
+            let Some(output) = self.udev.as_ref().and_then(|u| u.heads.iter().find(|h| &h.output.name() == name)).map(|h| h.output.clone()) else {
+                continue;
+            };
+            crate::output_management::apply_output_position(self, &output, (entry.x, entry.y).into());
+        }
+    }
+
     /// Re-probes connectors after a hotplug and reconciles the head list.
     ///
     /// Connectors that vanished have their head torn down (global removed,
@@ -23,17 +63,60 @@ impl CompState {
         let present: Vec<connector::Handle> = probes.iter().map(|p| p.connector).collect();
         let existing: Vec<connector::Handle> = udev.heads.iter().map(|h| h.connector).collect();
 
+        // A disabled connector that's genuinely gone from this fresh probe
+        // was actually unplugged, not just left administratively off --
+        // checked (and cleaned up) *before* the `gone.is_empty() &&
+        // added.is_empty()` early-out just below, since a disabled
+        // connector was never in `existing`/`heads` to begin with and so
+        // never affects either of those on its own; without this check
+        // running first, that early-out would fire and this cleanup would
+        // simply never happen for a hotplug event this narrow. See
+        // `MonitorInfo::enabled`'s own doc comment for why "off" and "not
+        // connected" have to be reported differently - this is what
+        // actually makes that transition happen.
+        let present_names: Vec<&str> = probes.iter().map(|p| p.name.as_str()).collect();
+        let unplugged_while_disabled: Vec<String> = udev.disabled_connectors.iter().filter(|name| !present_names.contains(&name.as_str())).cloned().collect();
+        if !unplugged_while_disabled.is_empty() {
+            let mut wm = self.wm.borrow_mut();
+            for name in &unplugged_while_disabled {
+                log::info!("udev: administratively-disabled output {name} was physically unplugged");
+                wm.clear_disabled_monitor(name);
+            }
+        }
+
         let gone: Vec<connector::Handle> = existing.iter().copied().filter(|c| !present.contains(c)).collect();
         let added: Vec<usize> = probes
             .iter()
             .enumerate()
-            .filter(|(_, p)| !existing.contains(&p.connector))
+            // `!udev.disabled_connectors.contains(&p.name)`: without this,
+            // an administratively-disabled-but-still-connected output
+            // (`disable_connector_by_name`) looks identical to a genuinely
+            // new one here - present in a fresh probe, absent from
+            // `heads` - and this *unrelated* hotplug event (any
+            // connector, not just the disabled one) would bring it
+            // straight back up.
+            .filter(|(_, p)| !existing.contains(&p.connector) && !udev.disabled_connectors.contains(&p.name))
             .map(|(i, _)| i)
             .collect();
-        if gone.is_empty() && added.is_empty() {
+        // `udev` (the outer immutable borrow) is done being read after
+        // this point, so `disabled_connectors` can be mutated now to drop
+        // whatever `unplugged_while_disabled` found - deferred this far
+        // specifically because the `added` filter just above still needed
+        // to read it first.
+        if !unplugged_while_disabled.is_empty() {
+            if let Some(udev) = self.udev.as_mut() {
+                udev.disabled_connectors.retain(|name| !unplugged_while_disabled.contains(name));
+            }
+        }
+        if gone.is_empty() && added.is_empty() && unplugged_while_disabled.is_empty() {
             return; // a "changed" event that didn't change the connector set
         }
-        log::info!("udev: hotplug - {} output(s) removed, {} added", gone.len(), added.len());
+        log::info!(
+            "udev: hotplug - {} output(s) removed, {} added, {} disabled-and-unplugged",
+            gone.len(),
+            added.len(),
+            unplugged_while_disabled.len()
+        );
 
         // ---- removals ----
         for connector in &gone {
@@ -62,7 +145,8 @@ impl CompState {
                 continue;
             };
             // Placed at 0 for now; the re-layout below assigns real offsets.
-            match bring_up_head(&card, &self.dh.clone(), probe, crtc, 0) {
+            let scale = self.wm.borrow().monitor_scale(&probe.name);
+            match bring_up_head(&card, &self.dh.clone(), probe, crtc, 0, 0, scale) {
                 Ok((head, entry)) => {
                     log::info!("udev: output {} connected ({}x{})", probe.name, head.size.0, head.size.1);
                     let monitor_id = self.outputs.len() as u32;
@@ -79,20 +163,215 @@ impl CompState {
             }
         }
 
+        // Safety net: never leave the session with zero live outputs.
+        // Real scenario, flagged live before it could actually happen:
+        // administratively disable the internal/laptop panel (`srd
+        // dispatch set output enabled ... false`), then physically unplug
+        // the one remaining external monitor - this same hotplug path
+        // handles the unplug correctly (the external head is removed
+        // above, same as any other disconnect), but without this, the
+        // internal panel stays administratively disabled forever after,
+        // leaving genuinely nothing to drive at all: no picture, and (a
+        // laptop having no other input device to fix it from) no way back
+        // in short of a restart. Re-enabling the most recently disabled
+        // connector that's still physically present - exactly
+        // `enable_connector_by_name`'s own normal path, just triggered by
+        // "we're about to have nothing" instead of an explicit request --
+        // trades the administrative disable for actually having a screen,
+        // which is the only reasonable choice once the alternative is a
+        // fully dark machine.
+        let no_live_heads = self.udev.as_ref().is_some_and(|u| u.heads.is_empty());
+        if no_live_heads {
+            let candidates: Vec<&drm::ConnectorProbe> =
+                self.udev.as_ref().map(|u| probes.iter().filter(|p| u.disabled_connectors.contains(&p.name)).collect()).unwrap_or_default();
+            // The internal/laptop panel specifically, if it's one of the
+            // candidates - `eDP`/`LVDS`/`DSI` are the real DRM connector-
+            // type prefixes an embedded display reports as, matching the
+            // exact scenario this exists for (disable the internal panel,
+            // then lose the external one it was standing in for). Falls
+            // back to whatever else is available rather than doing
+            // nothing, on the same "a screen is better than no screen"
+            // reasoning - an external monitor left administratively
+            // disabled is still a better fallback than a fully dark
+            // machine, even if it wasn't the specific one this was
+            // written for.
+            let fallback = candidates
+                .iter()
+                .find(|p| p.name.starts_with("eDP") || p.name.starts_with("LVDS") || p.name.starts_with("DSI"))
+                .or_else(|| candidates.first())
+                .map(|p| p.name.clone());
+            if let Some(name) = fallback {
+                log::warn!("udev: every output would otherwise be off - re-enabling {name} rather than leaving nothing to drive");
+                self.enable_connector_by_name(&name);
+                return;
+            }
+        }
+
+        self.relayout_outputs();
+    }
+
+    /// Administratively disables the output named `name` - the backend
+    /// half of `srd dispatch set output enabled <name> false`. Reuses
+    /// exactly the same removal steps `reprobe_outputs` already takes for
+    /// a real unplug just above (destroy the `wl_output` global, unmap
+    /// from `Space`, drop lock-surface tracking, free the DRM buffers via
+    /// `head.release`, rehome its windows via a `MonitorRemoved` event) --
+    /// the only difference is remembering the connector's *name*
+    /// afterward, in `UdevState::disabled_connectors`, so `reprobe_
+    /// outputs` won't bring it straight back on the next unrelated
+    /// hotplug, and so `enable_connector_by_name` can find it again later
+    /// without a real replug.
+    pub(crate) fn disable_connector_by_name(&mut self, name: &str) {
+        let Some(udev) = self.udev.as_mut() else { return };
+        let card = udev.card.clone();
+        let Some(index) = udev.heads.iter().position(|h| h.output.name() == name) else {
+            log::warn!("udev: set output enabled false: no connected output named {name}");
+            return;
+        };
+        // Snapshotted before removal, same computation `Platform::
+        // monitors()` itself uses - see `WindowManager::
+        // set_disabled_monitor`'s own doc comment for why `srd monitors`
+        // still wants this after the head is gone (a last-known rect to
+        // show, not a live one).
+        let head_ref = &udev.heads[index];
+        let zone = layer_map_for_output(&head_ref.output).non_exclusive_zone();
+        // `zone` is logical (scale-divided), `head_ref.location`/`size` are
+        // raw physical pixels - same unit mismatch `Platform::monitors()`
+        // itself had to be fixed for, and the same fix: scale `zone` back
+        // into physical pixels before combining. See that function's own
+        // doc comment for the live symptom this caused when left
+        // unconverted (a scaled output's reported geometry overlapping its
+        // neighbor's).
+        let scale = head_ref.output.current_scale().fractional_scale();
+        let zone_physical = |v: i32| (v as f64 * scale).round() as i32;
+        let usable_geometry = srdwm_core::Rect::new(
+            head_ref.location.x + zone_physical(zone.loc.x),
+            head_ref.location.y + zone_physical(zone.loc.y),
+            zone_physical(zone.size.w).max(0) as u32,
+            zone_physical(zone.size.h).max(0) as u32,
+        );
+        let full_geometry = srdwm_core::Rect::new(head_ref.location.x, head_ref.location.y, head_ref.size.0 as u32, head_ref.size.1 as u32);
+        let was_primary = index == 0;
+        let head = udev.heads.remove(index);
+        log::info!("udev: output {name} administratively disabled");
+        self.dh.remove_global::<CompState>(head.global.clone());
+        self.space.unmap_output(&head.output);
+        self.outputs.retain(|e| e.output != head.output);
+        self.lock.surfaces.remove(&head.output.name());
+        self.lock.presented.remove(&head.output.name());
+        head.release(&card);
+        self.pending.borrow_mut().push(CoreEvent::MonitorRemoved(index as u32));
+        if let Some(udev) = self.udev.as_mut() {
+            udev.disabled_connectors.insert(name.to_string());
+        }
+        self.wm.borrow_mut().set_disabled_monitor(name.to_string(), usable_geometry, full_geometry, was_primary);
+        self.relayout_outputs();
+        // Last-known physical position kept alongside `enabled: false` --
+        // re-enabling this same connector later (`enable_connector_by_name`
+        // below) restores it, rather than a disable silently discarding
+        // where it used to be.
+        crate::monitor_layout::save_output(name, crate::monitor_layout::PersistedOutput { x: full_geometry.x, y: full_geometry.y, enabled: false });
+    }
+
+    /// The other half of `disable_connector_by_name` - brings a
+    /// previously-disabled-but-still-connected output back up exactly the
+    /// way `reprobe_outputs` brings up a genuinely new one, since nothing
+    /// about the underlying hardware actually changed in between (the
+    /// connector was never really unplugged, just not driven).
+    pub(crate) fn enable_connector_by_name(&mut self, name: &str) {
+        let Some(udev) = self.udev.as_ref() else { return };
+        let card = udev.card.clone();
+        if !udev.disabled_connectors.contains(name) {
+            log::warn!("udev: set output enabled true: {name} isn't administratively disabled (already on, or never connected)");
+            return;
+        }
+        let probes = match probe_connected(&card) {
+            Ok(p) => p,
+            Err(e) => {
+                log::warn!("udev: re-enable probe for {name} failed: {e}");
+                return;
+            }
+        };
+        let Some(probe) = probes.iter().find(|p| p.name == name) else {
+            log::warn!("udev: set output enabled true: {name} is no longer physically connected");
+            if let Some(udev) = self.udev.as_mut() {
+                udev.disabled_connectors.remove(name);
+            }
+            // "Off" and "not connected" have to read differently to a
+            // listener (see `MonitorInfo::enabled`'s own doc comment) --
+            // this output is now the latter, so it stops being listed at
+            // all, same as a genuine unplug always has.
+            self.wm.borrow_mut().clear_disabled_monitor(name);
+            return;
+        };
+        let used: Vec<crtc::Handle> = udev.heads.iter().map(|h| h.crtc).collect();
+        let Some(crtc) = pick_crtc(&card, probe, &used) else {
+            log::warn!("udev: no free CRTC to re-enable {name}");
+            return;
+        };
+        // Placed at 0 for now; `relayout_outputs` below assigns real
+        // offsets, same as a genuine hotplug addition.
+        let scale = self.wm.borrow().monitor_scale(name);
+        match bring_up_head(&card, &self.dh.clone(), probe, crtc, 0, 0, scale) {
+            Ok((head, entry)) => {
+                log::info!("udev: output {name} re-enabled ({}x{})", head.size.0, head.size.1);
+                let monitor_id = self.outputs.len() as u32;
+                let geometry = srdwm_core::Rect::new(0, 0, head.size.0 as u32, head.size.1 as u32);
+                if let Some(udev) = self.udev.as_mut() {
+                    udev.heads.push(head);
+                    udev.disabled_connectors.remove(name);
+                }
+                self.outputs.push(entry);
+                self.pending.borrow_mut().push(CoreEvent::MonitorAdded(srdwm_core::Monitor::new(monitor_id, name.to_string(), geometry)));
+                // It's live again - `monitors()` reports it directly now,
+                // so it has no business also showing up in the separate
+                // disabled-outputs listing.
+                self.wm.borrow_mut().clear_disabled_monitor(name);
+            }
+            Err(e) => log::warn!("udev: failed to re-enable {name}: {e}"),
+        }
         self.relayout_outputs();
+        // Read back after `relayout_outputs` has assigned this head its
+        // real position, not the `(0, 0)` placeholder it was brought up
+        // at above.
+        if let Some(location) = self.udev.as_ref().and_then(|u| u.heads.iter().find(|h| h.output.name() == name)).map(|h| h.location) {
+            crate::monitor_layout::save_output(name, crate::monitor_layout::PersistedOutput { x: location.x, y: location.y, enabled: true });
+        }
     }
 
     /// Repositions every head left-to-right and republishes the new
     /// positions to the output globals, the `Space`, and the layer maps.
     fn relayout_outputs(&mut self) {
         let Some(udev) = self.udev.as_mut() else { return };
-        let mut x = 0;
+        // Two separate accumulators, not one - `x_physical` is this
+        // compositor's own internal placement convention (`head.location`,
+        // `Space`, everything else), `x_logical` is what actually goes out
+        // over the wire via `change_current_state`, which the Wayland
+        // protocol always specifies in logical points. At `scale == 1.0`
+        // for every output these are numerically identical, which is why
+        // this was invisible until a non-1.0 scale existed: passing the
+        // *physical* offset straight into `change_current_state` here
+        // (this used to do exactly that, unconditionally) put a second
+        // output's *logical* position short of where the first output's
+        // own *logical* width actually ends whenever a scale below 1.0 was
+        // involved - e.g. a first output that's 1920 physical but 2276
+        // logical (0.843 scale) left the second output advertised at
+        // logical x=1920, deep inside the first one's own logical extent,
+        // not past it. Reported live (measured from inside GTK, not
+        // inferred) as the two outputs' logical rectangles overlapping by
+        // a few hundred pixels - ambiguous "which monitor is this point
+        // on" answers, and hit-testing/screenshots landing on the wrong
+        // output entirely in the overlap band.
+        let mut x_physical = 0;
+        let mut x_logical = 0;
         let mut placed: Vec<(Output, Point<i32, Logical>)> = Vec::new();
         for head in &mut udev.heads {
-            head.location = (x, 0).into();
-            head.output.change_current_state(None, None, None, Some((x, 0).into()));
+            let scale = head.output.current_scale().fractional_scale();
+            head.location = (x_physical, 0).into();
+            head.output.change_current_state(None, None, None, Some((x_logical, 0).into()));
             placed.push((head.output.clone(), head.location));
-            x += head.size.0;
+            x_physical += head.size.0;
+            x_logical += (head.size.0 as f64 / scale).round() as i32;
         }
         for (output, location) in placed {
             if let Some(entry) = self.outputs.iter_mut().find(|e| e.output == output) {
diff --git a/crates/wayland/src/udev/platform.rs b/crates/wayland/src/udev/platform.rs
index 88c0d8f..cbcee64 100644
--- a/crates/wayland/src/udev/platform.rs
+++ b/crates/wayland/src/udev/platform.rs
@@ -10,6 +10,12 @@ pub struct UdevPlatform {
     clients: Vec<Client>,
     pending: Rc<RefCell<Vec<CoreEvent>>>,
     ipc: Option<srdwm_platform::IpcServer>,
+    /// Last time `ipc.poll()` actually ran - see its call site in
+    /// `poll_events` for why this exists at all.
+    last_ipc_poll: Instant,
+    /// Last time the unconditional end-of-cycle `render_udev_frame()` call
+    /// actually ran - see its own call site for why.
+    last_render: Instant,
 }
 
 impl UdevPlatform {
@@ -52,16 +58,24 @@ impl UdevPlatform {
         let mut heads: Vec<UdevHead> = Vec::new();
         let mut output_entries: Vec<crate::state::OutputEntry> = Vec::new();
         let mut used_crtcs: Vec<crtc::Handle> = Vec::new();
+        // Two accumulators - see `bring_up_head`'s own doc comment on its
+        // `logical_x` parameter for why a second head's logical position
+        // can't just be derived from the physical offset and its own
+        // scale alone once an earlier head has a *different* scale.
         let mut x_offset = 0;
+        let mut logical_x = 0;
         for probe in &connected {
             let Some(crtc) = pick_crtc(&card, probe, &used_crtcs) else {
                 log::warn!("udev: no free CRTC left for connector {}; not driving it", probe.name);
                 continue;
             };
-            let (head, entry) = bring_up_head(&card, &display_handle, probe, crtc, x_offset)?;
-            log::info!("udev: head {}: {} {}x{} at x={x_offset}", heads.len(), probe.name, head.size.0, head.size.1);
+            let scale = wm.borrow().monitor_scale(&probe.name);
+            let (head, entry) = bring_up_head(&card, &display_handle, probe, crtc, x_offset, logical_x, scale)?;
+            log::info!("udev: head {}: {} {}x{} at x={x_offset} (logical x={logical_x})", heads.len(), probe.name, head.size.0, head.size.1);
             used_crtcs.push(crtc);
+            let resolved_scale = head.output.current_scale().fractional_scale();
             x_offset += head.size.0;
+            logical_x += (head.size.0 as f64 / resolved_scale).round() as i32;
             heads.push(head);
             output_entries.push(entry);
         }
@@ -114,9 +128,11 @@ impl UdevPlatform {
             active: true,
             pointer_pos: (width as f64 / 2.0, height as f64 / 2.0).into(),
             session: session.clone(),
+            disabled_connectors: std::collections::HashSet::new(),
+            last_rendered_workspace: None,
         };
 
-        let state = CompState {
+        let mut state = CompState {
             compositor_state,
             xdg_shell_state,
             _xdg_decoration_state: xdg_decoration_state,
@@ -143,6 +159,7 @@ impl UdevPlatform {
             _screencopy_state: crate::screencopy::ScreencopyState::new::<CompState>(&display_handle),
             screencopy_pending: Vec::new(),
             _appmenu_state: crate::appmenu::AppmenuManagerState::new::<CompState>(&display_handle),
+            _virtual_keyboard_state: smithay::wayland::virtual_keyboard::VirtualKeyboardManagerState::new::<CompState, _>(&display_handle, |_client| true),
             _foreign_toplevel_state: crate::foreign_toplevel::ForeignToplevelState::new::<CompState>(&display_handle),
             foreign_toplevel_managers: Vec::new(),
             foreign_toplevel_handles: HashMap::new(),
@@ -172,6 +189,7 @@ impl UdevPlatform {
             last_broadcast_workspace: None,
             lock: Default::default(),
             cursor_status: smithay::input::pointer::CursorImageStatus::default_named(),
+            decoration_cursor_active: false,
             cursor_buffers: crate::cursor::make_buffers(),
             last_titlebar_click: None,
             gesture_swipe: None,
@@ -189,12 +207,15 @@ impl UdevPlatform {
             border_top_decorations: HashMap::new(),
             border_bottom_decorations: HashMap::new(),
             decoration_signatures: HashMap::new(),
+            hovered_titlebar_button: None,
             shadow_buffers: HashMap::new(),
             rounded_corners_program: None,
             content_epoch: HashMap::new(),
             rounded_content_buffers: HashMap::new(),
             border_side_buffers: HashMap::new(),
+            color_filter_buffers: HashMap::new(),
             last_synced_size: HashMap::new(),
+            pending_size_configure: HashMap::new(),
             pending: pending.clone(),
             bound_keys: Rc::new(bound_keys.iter().cloned().collect::<HashSet<_>>()),
             repeat_keys: Rc::new(repeat_keys.iter().cloned().collect::<HashSet<_>>()),
@@ -209,6 +230,15 @@ impl UdevPlatform {
             appmenu_registrar: None,
         };
 
+        // Before the Wayland socket even binds, deliberately - see
+        // `restore_monitor_layout`'s and `monitor_layout`'s own doc
+        // comments for why this compositor restores its own remembered
+        // layout itself rather than leaving it to whichever panel happens
+        // to be running: no client can possibly connect and see the
+        // default, un-restored arrangement, not even for one frame, since
+        // the socket a client would need to connect to doesn't exist yet.
+        state.restore_monitor_layout();
+
         let listener = ListeningSocket::bind_auto("wayland", 0..32).map_err(err)?;
         if let Some(name) = listener.socket_name() {
             std::env::set_var("WAYLAND_DISPLAY", name);
@@ -248,7 +278,7 @@ impl UdevPlatform {
             log::warn!("XWayland unavailable ({e}); X11-only clients will not run");
         }
 
-        Ok(Self { event_loop, display: dh, state, listener, clients: Vec::new(), pending, ipc })
+        Ok(Self { event_loop, display: dh, state, listener, clients: Vec::new(), pending, ipc, last_ipc_poll: Instant::now(), last_render: Instant::now() })
     }
 
     fn accept_clients(&mut self) -> PlatformResult<()> {
@@ -268,13 +298,97 @@ impl Platform for UdevPlatform {
 
     fn poll_events(&mut self) -> PlatformResult<Vec<CoreEvent>> {
         self.accept_clients()?;
+        let dispatch_start = Instant::now();
         self.event_loop.dispatch(Some(Duration::from_millis(16)), &mut self.state).map_err(err)?;
+        // `dispatch`'s `Duration::from_millis(16)` argument is a *maximum*
+        // wait, not a guarantee - calloop returns the moment any
+        // registered source looks ready, however long or short that takes.
+        // A source stuck permanently "ready" (an fd calloop never removes
+        // even though every read on it comes back EOF/HUP - confirmed live
+        // via `strace`, traced to the libseat session notifier's internal
+        // ping channel, and reproducible on a bare tty1 login within the
+        // first second of every single srdwm start, independent of which
+        // libseat backend - seatd or the logind fallback - is active)
+        // makes `dispatch` return in microseconds forever, turning this
+        // loop into an unthrottled spin that burns 70-90% of a core doing
+        // nothing: `accept_clients`/`tick_repeat`/`dispatch_clients` all
+        // still run their own (cheap) work on every single one of those
+        // spurious wakeups, thousands of times a second, instead of the
+        // ~60 times a second the 16ms figure was meant to cap it at.
+        //
+        // This doesn't fix *why* that source never goes away - that's
+        // upstream, in calloop/libseat's own channel-notification internals
+        // - but it puts a floor under the symptom regardless of which
+        // source eventually turns out to cause it.
+        //
+        // Sleeping the full remainder of a 16ms cycle on *every* fast
+        // return (an earlier version of this did exactly that) blocks this
+        // thread against everything, not just the next spurious wakeup --
+        // a genuine DRM page-flip completion or a client committing its
+        // next video frame that becomes ready *during* the sleep sits
+        // unprocessed until the sleep ends, instead of being picked up
+        // immediately. Reported live as choppy/laggy video playback: up to
+        // 16ms of pure, avoidable latency added to every frame's worth of
+        // real work that happened to land in that window.
+        //
+        // A per-iteration streak counter was tried first, throttling only
+        // once several fast returns in a row looked like true idle
+        // spinning rather than one-off real work - but `dispatch`'s
+        // return time can't actually distinguish the two here: the dead
+        // pipe is *always* ready, so every call returns in microseconds
+        // whether or not it also picked up something real, and a streak
+        // built on that timing never resets during genuine activity
+        // either. Telling real work apart from the spurious wakeup would
+        // need a signal from *inside* dispatch (e.g. the render path
+        // flagging "a frame actually went out this tick"), which is real
+        // plumbing, not a one-line fix.
+        //
+        // Short of that: cap the sleep itself far below 16ms instead of
+        // trying to skip it selectively. `MIN_CYCLE` (~3ms) still turns
+        // the true spin (unbounded, thousands of empty iterations/sec)
+        // into a bounded few hundred/sec - a real, if smaller, win over
+        // no floor at all - while capping how long any genuinely-ready
+        // event can ever sit blocked to something well under one frame at
+        // 60Hz, rather than up to a full frame's worth of latency.
+        const MIN_CYCLE: Duration = Duration::from_millis(3);
+        let elapsed = dispatch_start.elapsed();
+        if elapsed < MIN_CYCLE {
+            std::thread::sleep(MIN_CYCLE - elapsed);
+        }
         // Held bindings that repeat - see `CompState::tick_repeat`.
         self.state.tick_repeat();
         self.display.dispatch_clients(&mut self.state).map_err(err)?;
         self.display.flush_clients().map_err(err)?;
         self.state.apply_registrar_events();
-        if let Some(ipc) = self.ipc.as_mut() {
+        self.state.poll_global_menu_properties();
+        // Throttled to ~60Hz, not run on every single `poll_events` cycle --
+        // `IpcServer::poll` unconditionally rebuilds and diffs a full
+        // `client_snapshot`/`workspace_snapshot` on every call (cloning each
+        // window's title, app_id, global-menu data, ...) even when nothing
+        // has changed and nobody is subscribed, purely so a real change is
+        // never missed. Cheap at a sane call rate; not cheap at the rate
+        // this loop actually runs at - see `MIN_CYCLE`'s own doc comment
+        // just above: the dead libseat pipe that makes `dispatch` return in
+        // microseconds forever means this whole function's "rest of the
+        // cycle" work already runs at whatever `dispatch` gets bounced to
+        // (a few hundred times a second, floor-capped by `MIN_CYCLE`, not
+        // the ~60 times a second one `Duration::from_millis(16)` above was
+        // meant to imply), and that snapshot/diff cost was riding along at
+        // that same needlessly high rate - measured live as a continuous,
+        // unwavering ~20% of a core even at complete idle, unaffected by
+        // toggling shadows/rounded_corners/animations (all purely per-
+        // render-frame costs, not per-cycle ones, so none of them could
+        // have explained a cost that never budged with the screen doing
+        // nothing). A real `srd dispatch`/`srd set` command still lands
+        // within one throttled window (well under a human's own reaction
+        // time), not delayed by anything close to what would read as
+        // input lag.
+        const IPC_POLL_INTERVAL: Duration = Duration::from_millis(16);
+        let ipc_due = self.last_ipc_poll.elapsed() >= IPC_POLL_INTERVAL;
+        if ipc_due {
+            self.last_ipc_poll = Instant::now();
+        }
+        if let Some(ipc) = self.ipc.as_mut().filter(|_| ipc_due) {
             if ipc.poll(&self.state.wm) {
                 self.pending.borrow_mut().push(CoreEvent::WorkspaceChanged);
                 // `ipc.rs`'s `handle_request` (`"focus"`, `"toggle
@@ -295,9 +409,16 @@ impl Platform for UdevPlatform {
                 // unconditionally on any IPC mutation, not just ones that
                 // are definitely focus changes - raising an already-topmost
                 // element is a no-op reinsertion.
+                //
+                // `raise_in_space`, not the full `focus_window` - that one
+                // also re-runs `WindowManager::focus_window`'s workspace-
+                // follow side effect on the already-focused window, which
+                // silently reverted any `activate_workspace` IPC dispatch
+                // within this same cycle (see `raise_in_space`'s own doc
+                // comment for the full story).
                 let focused = self.state.wm.borrow().focused_id();
                 if let Some(id) = focused {
-                    crate::input::focus_window(&mut self.state, id);
+                    crate::input::raise_in_space(&mut self.state, id);
                 }
             }
         }
@@ -344,6 +465,10 @@ impl Platform for UdevPlatform {
                     log::warn!("udev: set_output_position: no head at index {id}");
                     continue;
                 };
+                // `(x, y)` is whatever `srd dispatch set output position`
+                // sent, unconverted - that command's own contract is to
+                // match `srd monitors`' `full_x`/`full_y` (physical),
+                // which is exactly what `apply_output_position` wants.
                 crate::output_management::apply_output_position(&mut self.state, &output, (x, y).into());
                 any_applied = true;
             }
@@ -361,57 +486,144 @@ impl Platform for UdevPlatform {
                 self.pending.borrow_mut().push(CoreEvent::MonitorAdded(srdwm_core::Monitor::new(0, "", srdwm_core::Rect::new(0, 0, 0, 0))));
             }
         }
-        self.state.render_udev_frame();
+        // Applies any `srd set_output_enabled` IPC requests queued since
+        // the last poll - `disable_connector_by_name`/`enable_connector_
+        // by_name` already push their own `MonitorRemoved`/`MonitorAdded`
+        // event, so nothing further is needed here beyond calling them.
+        let enable_requests = self.state.wm.borrow_mut().drain_output_enable_requests();
+        for (name, enabled) in enable_requests {
+            if enabled {
+                self.state.enable_connector_by_name(&name);
+            } else {
+                self.state.disable_connector_by_name(&name);
+            }
+        }
+        // Throttled the same way and for the same underlying reason as the
+        // `ipc.poll()` call above - this is the *other*, larger half of
+        // this cycle's needless work at the dead-pipe-driven spin rate.
+        // `render_udev_frame` isn't only called from here: a real DRM
+        // page-flip completion (`session.rs`), a VT-switch resume, and an
+        // output hotplug each call it directly, immediately, completely
+        // unthrottled by this - those are genuine, comparatively rare
+        // events that should redraw the instant they happen. This one
+        // specific call site is different: it's the unconditional catch-
+        // all that used to run at the end of *every* cycle regardless of
+        // whether `dispatch` actually picked up anything real, which at
+        // this loop's dead-pipe-driven rate meant re-walking every visible
+        // window, rebuilding the whole `custom_elements` list, and running
+        // Pixman's own damage tracking against it a few hundred times a
+        // second, forever - `has_damage` already meant an idle desktop's
+        // *page flip* was skipped, but computing "no, still nothing to
+        // flip" this often is itself most of the cost this whole function
+        // was found burning at idle. `RENDER_INTERVAL` (~8ms, ~120Hz) is
+        // comfortably above any real display's refresh rate - a head can
+        // never actually present faster than its own vblank allows
+        // regardless (`flip_pending` already gates that) - so this cannot
+        // cap real, on-screen frame rate on any hardware this backend
+        // targets; it only stops the redundant "check again" calls in
+        // between.
+        const RENDER_INTERVAL: Duration = Duration::from_millis(8);
+        if self.last_render.elapsed() >= RENDER_INTERVAL {
+            self.last_render = Instant::now();
+            self.state.render_udev_frame();
+        }
         Ok(self.pending.borrow_mut().drain(..).collect())
     }
 
-    /// One `srdwm_core::Monitor` per head, positioned in the global space.
-    /// This is what makes core's layout engine multi-monitor-aware in
-    /// practice: `arrange_workspace` groups windows by `monitor` and lays
-    /// each group out inside that monitor's rectangle.
+    /// One `srdwm_core::Monitor` per head, positioned in the global space
+    /// - or several, when `srd.monitor.split` has requested that head be
+    /// divided into logical sub-monitors ("monitors inside monitors"; see
+    /// `srdwm_core::monitor::MonitorSplit`'s own doc comment). This is
+    /// what makes core's layout engine multi-monitor-aware in practice:
+    /// `arrange_workspace` groups windows by `monitor` and lays each group
+    /// out inside that monitor's rectangle - a split just means more,
+    /// smaller rectangles feeding the same grouping, no other core-side
+    /// change needed.
     fn monitors(&mut self) -> PlatformResult<Vec<srdwm_core::Monitor>> {
         let Some(udev) = self.state.udev.as_ref() else { return Ok(Vec::new()) };
-        Ok(udev
-            .heads
-            .iter()
-            .enumerate()
-            .map(|(i, head)| {
-                // Shrunk by whatever a layer-shell surface (bar, dock) has
-                // reserved via `set_exclusive_zone` - reporting the full
-                // head size here otherwise means core's placement/tiling
-                // treats that strip as ordinary free space, so a new
-                // window's titlebar lands right where the bar renders on
-                // top of it, unreachable to drag. `non_exclusive_zone()` is
-                // output-local, so it's translated into this head's
-                // position in the shared global space the same way
-                // `head.location` already is.
-                let zone = layer_map_for_output(&head.output).non_exclusive_zone();
-                let rect = srdwm_core::Rect::new(
-                    head.location.x + zone.loc.x,
-                    head.location.y + zone.loc.y,
-                    zone.size.w as u32,
-                    zone.size.h as u32,
-                );
-                let mut m = srdwm_core::Monitor::new(i as u32, head.output.name(), rect);
-                // `Monitor::new` defaults `full_geometry` to whatever
-                // `geometry` was constructed with - correct for a monitor
-                // with no layer-shell client at all, wrong the moment one
-                // exists, since `rect` above is already zone-shrunk. Without
-                // this, `full_geometry` was silently identical to `geometry`
-                // for every real monitor this backend ever reported, which
-                // made `toggle_fullscreen`'s whole "ignore the reserved
-                // zone" design a no-op in practice: fullscreen still
-                // stopped at the bar/dock exactly like maximize does.
-                // Reported live as "fullscreen isn't actually going
-                // fullscreen" - confirmed by triggering it and reading
-                // the resulting geometry back over IPC, not just from
-                // reading this code.
-                m.full_geometry = srdwm_core::Rect::new(head.location.x, head.location.y, head.size.0 as u32, head.size.1 as u32);
-                m.maximize_geometry = crate::input::maximize_geometry_for(&head.output, m.full_geometry);
-                m.primary = i == 0;
-                m
-            })
-            .collect())
+        let wm = self.state.wm.clone();
+        let wm = wm.borrow();
+        let mut out = Vec::new();
+        let mut next_id: u32 = 0;
+        for head in udev.heads.iter() {
+            // Shrunk by whatever a layer-shell surface (bar, dock) has
+            // reserved via `set_exclusive_zone` - reporting the full
+            // head size here otherwise means core's placement/tiling
+            // treats that strip as ordinary free space, so a new
+            // window's titlebar lands right where the bar renders on
+            // top of it, unreachable to drag. `non_exclusive_zone()` is
+            // output-local, so it's translated into this head's
+            // position in the shared global space the same way
+            // `head.location` already is.
+            //
+            // `non_exclusive_zone()` is in *logical* (scale-divided)
+            // units - a bar reports its own reserved strip the way every
+            // layer-shell client does, in logical points - while `head.
+            // location`/`head.size` are raw physical pixels straight from
+            // the DRM mode, never touched by `srd.monitor.scale`. Left
+            // unconverted, `usable` silently mixed the two units on any
+            // output with a scale other than exactly `1.0`: at scale
+            // `0.712`, a 1920-physical-pixel-wide head's own `zone.size.w`
+            // came back as ~2697 (logical), reported as this monitor's
+            // *usable* width - larger than its own *full* width, and
+            // large enough to overlap whichever real monitor sat next to
+            // it in the shared global space. Reported live as "Firefox
+            // maximized on one monitor also shows partially on the
+            // other" and general visual glitching on the scaled output --
+            // both are this: placement math trusting an oversized rect
+            // that reached into a neighboring monitor's real screen.
+            // Scaling `zone` back into physical pixels here keeps `usable`
+            // in the same unit as `full`/`maximize`/`head.location`
+            // everywhere else in this compositor.
+            let zone = layer_map_for_output(&head.output).non_exclusive_zone();
+            let scale = head.output.current_scale().fractional_scale();
+            let zone_physical = |v: i32| (v as f64 * scale).round() as i32;
+            let usable = srdwm_core::Rect::new(
+                head.location.x + zone_physical(zone.loc.x),
+                head.location.y + zone_physical(zone.loc.y),
+                zone_physical(zone.size.w).max(0) as u32,
+                zone_physical(zone.size.h).max(0) as u32,
+            );
+            // The head's true full rect, ignoring any exclusive zone --
+            // deliberately *not* defaulted from `usable` the way `Monitor::
+            // new` alone would (see the fullscreen note below).
+            let full = srdwm_core::Rect::new(head.location.x, head.location.y, head.size.0 as u32, head.size.1 as u32);
+            let maximize = crate::input::maximize_geometry_for(&head.output, full);
+            let name = head.output.name();
+            let split = wm.monitor_split(&name);
+            let parts = split.map(|s| s.parts).unwrap_or(1).max(1);
+            let rows = split.map(|s| s.rows).unwrap_or(false);
+            for part in 0..parts {
+                let sub_name = if parts <= 1 { name.clone() } else { format!("{name}-{}", part + 1) };
+                let mut m = srdwm_core::Monitor::new(next_id, sub_name, srdwm_core::monitor::split_rect(usable, part, parts, rows));
+                // `Monitor::new` defaults `full_geometry`/`maximize_
+                // geometry` to whatever `geometry` was constructed with --
+                // correct for a monitor with no layer-shell client and no
+                // split at all, wrong the moment either exists, since the
+                // rect above may already be zone-shrunk and/or a sub-
+                // region. Without this, `full_geometry` was silently
+                // identical to `geometry` for every real monitor this
+                // backend ever reported, which made `toggle_fullscreen`'s
+                // whole "ignore the reserved zone" design a no-op in
+                // practice: fullscreen still stopped at the bar/dock
+                // exactly like maximize does. Reported live as "fullscreen
+                // isn't actually going fullscreen" - confirmed by
+                // triggering it and reading the resulting geometry back
+                // over IPC, not just from reading this code. Each split
+                // part gets its *own* full/maximize rect too - without
+                // this, fullscreening a window in either half of a split
+                // head would cover the *entire* physical panel, silently
+                // erasing the split it was placed to respect.
+                m.full_geometry = srdwm_core::monitor::split_rect(full, part, parts, rows);
+                m.maximize_geometry = srdwm_core::monitor::split_rect(maximize, part, parts, rows);
+                m.primary = next_id == 0;
+                m.split = parts > 1;
+                m.scale = scale;
+                out.push(m);
+                next_id += 1;
+            }
+        }
+        Ok(out)
     }
 
     fn apply_geometry(&mut self, window: srdwm_core::WindowId, _geometry: srdwm_core::Rect) -> PlatformResult<()> {
diff --git a/crates/wayland/src/udev/render.rs b/crates/wayland/src/udev/render.rs
index 6c9c7d2..d5d776d 100644
--- a/crates/wayland/src/udev/render.rs
+++ b/crates/wayland/src/udev/render.rs
@@ -8,6 +8,7 @@ impl CompState {
     /// instead of the slowest one gating the rest.
     pub(crate) fn render_udev_frame(&mut self) {
         self.tick_animations();
+        self.tick_hover_glyph_animation();
         self.tick_dirty_broadcasts();
         let locked = self.lock.locked;
         let elapsed = self.start_time.elapsed();
@@ -47,9 +48,22 @@ impl CompState {
         // looked up fresh per head (head-local `origin` translation).
         let ids: Vec<srdwm_core::WindowId> = if locked { Vec::new() } else { self.wm.borrow().visible_windows_front_to_back().map(|w| w.id).collect() };
         let focused = self.wm.borrow().focused_id();
-        // Default `false` here, unlike winit's `unwrap_or(true)` - see
-        // `rounded_corners_pixman`'s module doc comment for the CPU cost
-        // that makes this backend opt-in rather than on by default.
+        // Stays default `false` here, unlike winit's `unwrap_or(true)` --
+        // see `rounded_corners_pixman`'s module doc comment for the real
+        // CPU cost this backend's masking technique has: a full row-by-row
+        // buffer copy on *every commit* of a constantly-repainting client,
+        // and that doc comment names video specifically as the case that
+        // pays it in full, every frame, for as long as the feature is on.
+        // Flipping this default was tried and reverted in the same pass
+        // that fixed this backend's render-loop latency (see `poll_events`'
+        // own history) - turning it on here would have directly undone
+        // that fix for exactly the content (video) it mattered most for.
+        // The actual "not all windows curved" complaint this was meant to
+        // address (an undecorated/CSD window like Firefox, with no
+        // compositor-drawn titlebar and only a thin border strip to look
+        // rounded at all) is better addressed by giving that border strip
+        // enough rows to show a real curve - see `ThemeConfig::
+        // default_border_width`'s own doc comment.
         let rounded_corners_enabled = self.wm.borrow().rounded_corners_enabled.unwrap_or(false);
         let popup_targets = if locked { Vec::new() } else { crate::elements::popup_targets(self) };
 
@@ -58,7 +72,7 @@ impl CompState {
         // `captures` taken above nowhere to go this pass - put them back
         // rather than silently dropping a client's pending screenshot
         // because a VT switch happened to be in progress at that instant.
-        let Some(udev) = self.udev.as_ref() else {
+        let Some(udev) = self.udev.as_mut() else {
             self.screencopy_pending.extend(captures);
             return;
         };
@@ -66,6 +80,62 @@ impl CompState {
             self.screencopy_pending.extend(captures);
             return;
         }
+        // A workspace switch changes *which windows* `custom_elements`
+        // includes as drastically as a VT switch changes what's been
+        // scanned out in the meantime (see `register_session_notifier`'s
+        // own `head.ages = [0, 0]` for that case) - reported live as
+        // visible corruption (stale, wrong-coloured blocks, worst on a
+        // window that was actively repainting - a scrolling terminal --
+        // right as the switch happened) confined to exactly the frame or
+        // two around a switch, then never self-correcting, consistent with
+        // one transient frame's content getting baked into a buffer slot
+        // and never fully overwritten again since later frames only patch
+        // whatever's *actually* still changing. `render_output`'s own
+        // per-element diffing (`elements_gone`/moved-element damage, plus
+        // each element's own `damage_since`) should in principle already
+        // produce correct total damage for a completely different element
+        // list - this is a defensive belt-and-braces reset, not a
+        // fallback for a specific proven bug in that diffing, matched to
+        // the one other place in this codebase that already resets `ages`
+        // for the same underlying reason ("what's in this buffer might not
+        // be what the tracker's own history thinks it is").
+        let current_workspace = self.wm.borrow().current_workspace();
+        if udev.last_rendered_workspace != Some(current_workspace) {
+            udev.last_rendered_workspace = Some(current_workspace);
+            for head in &mut udev.heads {
+                head.ages = [0, 0];
+            }
+        }
+        // A head whose page-flip event never arrives (kernel-dropped, or a
+        // DRM event this driver never sends for reasons this backend has no
+        // visibility into) would otherwise sit in `flip_pending` forever:
+        // `session.rs`'s DRM-fd handler is the only other place that clears
+        // it, and it can only do that in response to an event that actually
+        // shows up. A head stuck this way is excluded from `ready` below on
+        // every single tick from then on - silently frozen on whatever it
+        // last displayed, with no error logged anywhere (the flip that set
+        // `flip_pending` had already succeeded when it was issued), which
+        // is exactly what a real second monitor did live: it rendered
+        // nothing but its own initial clear colour for the rest of the
+        // session, from moments after being connected. `FLIP_TIMEOUT` is
+        // far above any real vblank interval (even 30Hz is ~33ms) but short
+        // enough that a genuine loss is invisible in practice; forcing
+        // `flip_pending` back to `false` here just lets the normal path
+        // below retry - if a flip is still genuinely in flight, the
+        // kernel's own EBUSY on the next `page_flip` call surfaces as the
+        // existing "udev: page flip failed" log line instead of a silent
+        // freeze.
+        const FLIP_TIMEOUT: Duration = Duration::from_millis(200);
+        for head in udev.heads.iter_mut() {
+            if head.flip_pending && head.flip_pending_since.elapsed() > FLIP_TIMEOUT {
+                log::warn!(
+                    "udev: no page-flip event for output {} after {:?}; forcing recovery",
+                    head.output.name(),
+                    head.flip_pending_since.elapsed()
+                );
+                head.flip_pending = false;
+            }
+        }
         let ready: Vec<(usize, Output)> = udev
             .heads
             .iter()
@@ -83,7 +153,7 @@ impl CompState {
         // frame-callback loop below (after `udev` is no longer borrowed)
         // can notify only the windows that damage actually overlapped --
         // see `windows_touched_by_damage`'s doc comment in elements.rs.
-        let mut presented: Vec<(Output, Vec<Rectangle<i32, Physical>>)> = Vec::new();
+        let mut presented: Vec<(Output, Point<i32, Logical>, Vec<Rectangle<i32, Physical>>)> = Vec::new();
         for (index, output) in ready {
             let lock_surface = self.lock_surface_for(&output).cloned();
             // Extracted before the `self.udev` borrow below starts - see
@@ -116,6 +186,16 @@ impl CompState {
                     origin,
                     hsize,
                 ));
+                // Night light/reading mode - a translucent full-output
+                // overlay, pushed right after the cursor so it colours
+                // everything else (windows, bars, menus) but never the
+                // pointer itself. See `color_filter::render_element` for
+                // why an overlay rather than a true per-pixel shader.
+                let color_filter = self.wm.borrow().color_filter;
+                let buf = self.color_filter_buffers.entry(output.name()).or_insert_with(SolidColorBuffer::default);
+                if let Some(elem) = crate::color_filter::render_element(buf, color_filter, hsize) {
+                    custom_elements.push(crate::elements::OverlayElement::Solid(elem));
+                }
                 // The right-click titlebar menu, if open - pushed right
                 // after the cursor so it's still topmost over every window
                 // but never hides the pointer itself (you need to see what
@@ -164,7 +244,6 @@ impl CompState {
                     custom_elements.extend(crate::elements::output_layer_elements(
                         &mut udev.renderer,
                         &output,
-                        (origin.x, origin.y),
                         |layer| matches!(layer, Layer::Top | Layer::Overlay),
                     ));
                 }
@@ -203,23 +282,165 @@ impl CompState {
                     // windows) has to agree with what `sync_geometry` mapped
                     // the content to, or they drift apart again.
                     let geom = self.window_anims.get(&id).map(crate::state::WindowAnim::current_rect).unwrap_or(w.geometry);
-                    // Drawn first among this window's own decoration, and
-                    // positioned from the same animated `geom` as everything
-                    // else here - not `w.geometry` - for the identical
-                    // reason: a shadow that stayed at the pre-tween rect
-                    // while the window slid past it would look exactly as
-                    // detached as the border did before that fix. Not
-                    // fragment-clipped against `occluders` like the titlebar/
-                    // border below: at `SHADOW_MAX_ALPHA`'s low opacity, a
-                    // shadow bleeding slightly onto a window stacked in front
-                    // of this one reads as a soft edge, not the hard-line
-                    // bleed-through that made the titlebar/border need it.
-                    if let Some(shadow) = self.shadow_buffers.get(&id) {
-                        let rect = decoration::shadow_rect(geom);
-                        let pos = ((rect.x - origin.x) as f64, (rect.y - origin.y) as f64);
-                        match MemoryRenderBufferRenderElement::from_buffer(&mut udev.renderer, pos, shadow, None, None, None, Kind::Unspecified) {
-                            Ok(elem) => custom_elements.push(crate::elements::OverlayElement::Memory(elem)),
-                            Err(e) => log::warn!("udev: failed to import shadow buffer: {e}"),
+                    // `geom` above is this compositor's own request/target;
+                    // `frame` corrects its far edge to match what the
+                    // client's surface really committed (a terminal's
+                    // cell-quantized size, most commonly) - see
+                    // `effective_frame`'s own doc comment. Everything below
+                    // that has to visually hug the real edge (titlebar/
+                    // border placement, the shadow, the occlusion test
+                    // against windows behind this one) reads `frame`; only
+                    // the actual content position still reads `geom`/`band`
+                    // directly, since that's already correctly anchored via
+                    // `content_offset` below regardless of this correction.
+                    let frame = crate::state::CompState::effective_frame_of(&self.wm, &self.id_to_window, id, geom);
+                    // Computed here, ahead of the border strips below,
+                    // purely so they can know it - the actual content
+                    // element that reads this same masked buffer is still
+                    // pushed later, in its own usual place in the loop, and
+                    // gets a cheap cache hit from `rounded_content_buffer`'s
+                    // own `epoch`/`radius_bits` check rather than doing the
+                    // masking work twice. `w.decorated` alone used to gate
+                    // whether the border strips' own "extra" rows (see
+                    // `decoration::border_top_visible_rows`'s doc comment)
+                    // were safe to draw past their nominal `border_width` --
+                    // correct for a decorated window (a titlebar band
+                    // absorbs them) but not for an undecorated one, which
+                    // relies on content-masking instead, and several real
+                    // clients (Firefox, confirmed live) never actually get
+                    // masked at all (`masked_content_buffer`'s own
+                    // subsurface early-out). Cropping unconditionally
+                    // whenever undecorated (the fix's first version) closed
+                    // the wedge bug but cost every undecorated window its
+                    // own visible corner curve even when masking *did*
+                    // succeed, which is unnecessary - this makes that
+                    // decision follow the real per-window, per-frame
+                    // outcome instead of just the static `decorated` flag.
+                    // `masked.is_some()` alone used to be the whole check,
+                    // back when masking meant identifying and reading one
+                    // specific client subsurface directly - wrong the
+                    // moment the resolved child excluded more of the root
+                    // than the client's own declared shadow margin (a GTK4
+                    // client legitimately reserves an invisible margin for
+                    // its own drop shadow, but Firefox's tab strip/title row
+                    // is painted on the *root* surface outside its content
+                    // child, and once that surface-picking heuristic got
+                    // permissive enough to mask Firefox too, it silently
+                    // deleted Firefox's real tab strip - reported live as
+                    // "Firefox's titlebar turned invisible", confirmed by
+                    // toggling `general.rounded_corners` off, which brought
+                    // it straight back). `rounded_corners_pixman::masked_
+                    // content_buffer` no longer has that failure mode at
+                    // all: it renders the window's *whole* surface tree into
+                    // its own off-screen buffer and masks the composited
+                    // result, the same thing a GPU shader-based compositor
+                    // does by construction - so `.is_some()` is genuinely
+                    // the whole answer again. `loc`/`content_size` mirror
+                    // the real content push's own `content_offset`/`band`
+                    // correction below (`pos`'s own doc comment) - both
+                    // call sites have to agree on the origin/size a mask was
+                    // built at, or `rounded_content_buffer`'s cache would
+                    // never consider one stale after a resize.
+                    let content_will_be_masked = if rounded_corners_enabled && self.wm.borrow().resizing_window() != Some(id) {
+                        let content_offset = self.id_to_window.get(&id).map(|dw| dw.geometry().loc).unwrap_or_default();
+                        let band = if w.decorated { srdwm_core::TITLEBAR_HEIGHT as i32 } else { 0 };
+                        let content_size = (frame.width as i32, (frame.height as i32 - band).max(0));
+                        let loc = (-content_offset.x, -content_offset.y);
+                        self.id_to_window
+                            .get(&id)
+                            .and_then(crate::elements::window_wl_surface)
+                            .map(|surface| {
+                                let epoch = self.content_epoch.get(&id).copied().unwrap_or(0);
+                                let corners = if w.decorated { crate::rounded_corners::RoundedCorners::BOTTOM_ONLY } else { crate::rounded_corners::RoundedCorners::ALL };
+                                crate::elements::rounded_content_buffer(&mut self.rounded_content_buffers, &mut udev.renderer, epoch, id, &surface, loc, content_size, w.corner_radius as f32, corners).is_some()
+                            })
+                            .unwrap_or(false)
+                    } else {
+                        false
+                    };
+                    let border_curve_is_safe = w.decorated || content_will_be_masked;
+                    // Temporary: a peer session precisely measured a real
+                    // window's border curving correctly while its content
+                    // stayed hard-square (radius 0), despite both this
+                    // probe and the real content-render call ~200 lines
+                    // below passing identical arguments against the same
+                    // cache - logs the three inputs that decide which
+                    // branch each one actually takes, so a live repro
+                    // says definitively whether `w.decorated` is really
+                    // `false` here (the rule's own intent) or the mask
+                    // genuinely succeeds-then-somehow-doesn't-render.
+                    // Remove once resolved.
+                    log::debug!(
+                        "udev::render: corner-mask state for {} (id {id:?}): decorated={} content_will_be_masked={content_will_be_masked} border_curve_is_safe={border_curve_is_safe} resizing={}",
+                        w.app_id,
+                        w.decorated,
+                        self.wm.borrow().resizing_window() == Some(id)
+                    );
+                    // Pushed *before* the titlebar band below, deliberately --
+                    // unlike the bottom/side strips further down, this one
+                    // isn't confined to `geometry`'s own outside: whenever
+                    // `corner_radius > border_width` (the common case: 12 vs
+                    // 4 by default), `border_top_visible_rows` deliberately
+                    // extends this buffer `corner_radius - border_width` rows
+                    // *past* its nominal thickness, straight down into the
+                    // titlebar band's own top rows, so the one shared curve
+                    // has room to finish (see that function's and `render_
+                    // border_top`'s own doc comments). For that overlap to
+                    // read as one continuous curve rather than the titlebar's
+                    // own, differently-centred corner mask poking a square
+                    // notch through it, this element's border-coloured
+                    // corner columns have to actually paint over the
+                    // titlebar's own attempt at those same pixels - which
+                    // only happens if this pushes first. Reported live,
+                    // confirmed via a zoomed screenshot: pushed after the
+                    // titlebar (the previous order), the titlebar's own
+                    // smaller, square-under-the-curve corner rendered on top
+                    // instead, since `custom_elements` composites earlier-
+                    // pushed entries over later ones - exactly backwards
+                    // from what this overlap needs.
+                    if w.border_width > 0 {
+                        let strips = decoration::border_strips(frame, w.border_width);
+                        // Strip 0 (top) rounded on its own two corners - see
+                        // `render_border_top`'s own doc comment - so it's a
+                        // cached bitmap (rebuilt only in `redraw_decoration_
+                        // buffer`, same as the titlebar itself), not
+                        // rasterized fresh here every frame. Not fragment-
+                        // clipped like the left/right strips further down --
+                        // cropping a bitmap's source rect per fragment is
+                        // real extra work for a strip that's only `border_
+                        // width` pixels tall to begin with, so this only
+                        // handles the all-or-nothing case: skip entirely
+                        // once *fully* covered, accept a small residual
+                        // bleed while only partially covered.
+                        if strips[0].width > 0 && strips[0].height > 0 && !strips[0].subtract_all(&occluders).is_empty() {
+                            if let Some(buffer) = self.border_top_decorations.get(&id) {
+                                // See `decoration::border_top_visible_rows`'s
+                                // own doc comment: an undecorated window's
+                                // top strip crops away this buffer's
+                                // titlebar-band-only "extra" rows, which
+                                // otherwise paint a border-coloured wedge
+                                // straight onto its real content - reported
+                                // live on a real Firefox window, confirmed
+                                // via a screenshot to be neither Firefox's
+                                // own rendering nor the separate content-
+                                // mask feature.
+                                let (row0, rows, shift) = decoration::border_top_visible_rows(border_curve_is_safe, w.border_width, w.corner_radius);
+                                let pos = ((strips[0].x - origin.x) as f64, (strips[0].y - origin.y + shift as i32) as f64);
+                                let src = Some(Rectangle::new(Point::from((0.0, row0 as f64)), Size::from((strips[0].width as f64, rows as f64))));
+                                // Temporary: chasing a live report that the
+                                // bottom two corners render square while the
+                                // top two curve correctly, on the same
+                                // window, same frame. Logs this strip's own
+                                // computed rows/shift/position so a live
+                                // repro can be compared directly against the
+                                // matching bottom-strip line below. Remove
+                                // once resolved.
+                                log::debug!("udev::render: TOP border strip for {} (id {id:?}): row0={row0} rows={rows} shift={shift} pos={pos:?} strip_rect={:?}", w.app_id, strips[0]);
+                                match MemoryRenderBufferRenderElement::from_buffer(&mut udev.renderer, pos, buffer, None, src, None, Kind::Unspecified) {
+                                    Ok(elem) => custom_elements.push(crate::elements::OverlayElement::Memory(elem)),
+                                    Err(e) => log::warn!("udev: failed to import top border buffer: {e}"),
+                                }
+                            }
                         }
                     }
                     if let Some(deco) = self.decorations.get(&id) {
@@ -235,7 +456,7 @@ impl CompState {
                         // visible fragment can come from the matching
                         // sub-rect of the source image rather than the
                         // whole thing.
-                        let titlebar_rect = srdwm_core::Rect::new(geom.x, geom.y, geom.width, srdwm_core::TITLEBAR_HEIGHT);
+                        let titlebar_rect = srdwm_core::Rect::new(frame.x, frame.y, frame.width, srdwm_core::TITLEBAR_HEIGHT);
                         for fragment in crate::elements::visible_border_fragments(titlebar_rect, &occluders) {
                             let pos = ((fragment.x - origin.x) as f64, (fragment.y - origin.y) as f64);
                             let src = Rectangle::new(
@@ -248,47 +469,47 @@ impl CompState {
                             }
                         }
                     }
-                    // Border strips sit entirely outside this window's own
-                    // `geometry` (see `decoration::border_strips`), so they
-                    // never overlap its own decoration/content - draw
-                    // order against those doesn't matter here, only against
-                    // other windows', which iterating `ids` in stacking
-                    // order already gets right *for windows also drawn via
-                    // this same custom_elements loop* - but not against
-                    // any window's own *content*, which is why `occluders`
-                    // below is still needed even with that ordering.
+                    // The bottom strip sits entirely outside this window's
+                    // own `geometry` with no titlebar-style overlap into
+                    // content the way the top strip's own "extra" rows do
+                    // above, so push order against the titlebar doesn't
+                    // matter for it - only against other windows', which
+                    // iterating `ids` in stacking order already gets right
+                    // *for windows also drawn via this same custom_elements
+                    // loop* - but not against any window's own *content*,
+                    // which is why `occluders` below is still needed even
+                    // with that ordering.
+                    //
+                    // The left/right side strips are a different story --
+                    // see their own push site further down for why they
+                    // (unlike the bottom strip) *do* need cropping against
+                    // this same top/bottom-strip overlap, a real bug this
+                    // comment used to claim didn't exist here at all.
                     if w.border_width > 0 {
-                        let color = crate::state::effective_border_color(w.border_color, focused == Some(id));
-                        let strips = decoration::border_strips(geom, w.border_width);
-                        // Strips 0/1 (top/bottom) rounded on their own two
-                        // corners - see `render_border_top`/
-                        // `render_border_bottom`'s doc comments - so both
-                        // are cached bitmaps (rebuilt only in
-                        // `redraw_decoration_buffer`, same as the titlebar
-                        // itself), not rasterized fresh here every frame.
-                        // Not fragment-clipped like the left/right strips
-                        // below - cropping a bitmap's source rect per
-                        // fragment is real extra work for a strip that's
-                        // only `border_width` pixels tall to begin with, so
-                        // this only handles the all-or-nothing case: skip
-                        // entirely once *fully* covered, accept a small
-                        // residual bleed while only partially covered.
-                        if strips[0].width > 0 && strips[0].height > 0 && !strips[0].subtract_all(&occluders).is_empty() {
-                            if let Some(buffer) = self.border_top_decorations.get(&id) {
-                                let pos = ((strips[0].x - origin.x) as f64, (strips[0].y - origin.y) as f64);
-                                match MemoryRenderBufferRenderElement::from_buffer(&mut udev.renderer, pos, buffer, None, None, None, Kind::Unspecified) {
-                                    Ok(elem) => custom_elements.push(crate::elements::OverlayElement::Memory(elem)),
-                                    Err(e) => log::warn!("udev: failed to import top border buffer: {e}"),
-                                }
-                            }
-                        }
-                        // Same all-or-nothing bitmap treatment as the top
-                        // strip, for its own two corners - see
-                        // `decoration::render_border_bottom`'s doc comment.
+                        let color = crate::state::effective_border_color(w.border_color, focused == Some(id), self.wm.borrow().theme.border_inactive_dim);
+                        let strips = decoration::border_strips(frame, w.border_width);
+                        // Strip 1 (bottom), the top strip's own mirror --
+                        // see `decoration::render_border_bottom`'s doc
+                        // comment. Same all-or-nothing bitmap treatment.
                         if strips[1].width > 0 && strips[1].height > 0 && !strips[1].subtract_all(&occluders).is_empty() {
                             if let Some(buffer) = self.border_bottom_decorations.get(&id) {
-                                let pos = ((strips[1].x - origin.x) as f64, (strips[1].y - origin.y) as f64);
-                                match MemoryRenderBufferRenderElement::from_buffer(&mut udev.renderer, pos, buffer, None, None, None, Kind::Unspecified) {
+                                // See `decoration::border_bottom_visible_
+                                // rows`'s own doc comment: relies on
+                                // `BOTTOM_ONLY` content-masking having made
+                                // this corner of a decorated window's
+                                // content transparent already, which several
+                                // real undecorated clients (Firefox,
+                                // confirmed live) never actually get - same
+                                // wedge bug as the top strip, confirmed on
+                                // the same window's bottom-left corner via a
+                                // real screenshot, not assumed.
+                                let (row0, rows, shift) = decoration::border_bottom_visible_rows(border_curve_is_safe, w.border_width, w.corner_radius);
+                                let pos = ((strips[1].x - origin.x) as f64, (strips[1].y - origin.y - shift as i32) as f64);
+                                let src = Some(Rectangle::new(Point::from((0.0, row0 as f64)), Size::from((strips[1].width as f64, rows as f64))));
+                                // Temporary: see the matching TOP border log
+                                // above. Remove once resolved.
+                                log::debug!("udev::render: BOTTOM border strip for {} (id {id:?}): row0={row0} rows={rows} shift={shift} pos={pos:?} strip_rect={:?}", w.app_id, strips[1]);
+                                match MemoryRenderBufferRenderElement::from_buffer(&mut udev.renderer, pos, buffer, None, src, None, Kind::Unspecified) {
                                     Ok(elem) => custom_elements.push(crate::elements::OverlayElement::Memory(elem)),
                                     Err(e) => log::warn!("udev: failed to import bottom border buffer: {e}"),
                                 }
@@ -304,9 +525,45 @@ impl CompState {
                         // visible after subtracting `occluders`, since a
                         // whole unclipped strip is exactly the bug fixed
                         // here.
+                        //
+                        // Cropped top and bottom by `extra` - the same
+                        // `corner_radius - border_width` gap `border_top_
+                        // visible_rows`/`border_bottom_visible_rows` extend
+                        // the top/bottom strips *into* whenever the radius
+                        // exceeds the border's own nominal thickness (the
+                        // common case: 12+ vs 4 at this theme's defaults).
+                        // These side strips are plain flat fills with no
+                        // curve awareness of their own (see this file's own
+                        // stale comment just below, corrected here: "sit
+                        // entirely outside... no titlebar-style overlap"
+                        // was wrong - they *do* overlap the top/bottom
+                        // strip's own extended, curved region), and used to
+                        // span the window's full nominal height
+                        // unconditionally. Since the top/bottom strip is
+                        // pushed *before* these (earlier = topmost, see
+                        // this loop's own ordering), its own curve's
+                        // transparent cutout should be what shows through
+                        // there - but a flat, uncropped side strip sitting
+                        // directly underneath filled that same "supposed to
+                        // be cut away" region with solid colour instead,
+                        // which the curve's transparency does nothing to
+                        // hide, since the side strip isn't part of what the
+                        // curve is cutting *out of*. Reported live as a
+                        // straight vertical line poking out from inside an
+                        // otherwise-correctly-curved corner, confirmed via
+                        // raw pixel sampling: solid border colour at a
+                        // fixed x, starting right at the window's nominal
+                        // top edge, running in parallel with the real
+                        // curve rather than being replaced by it.
+                        let extra = if border_curve_is_safe { w.border_width.max(w.corner_radius).saturating_sub(w.border_width) } else { 0 };
+                        let mut side_strips = [strips[2], strips[3]];
+                        for s in &mut side_strips {
+                            s.y += extra as i32;
+                            s.height = s.height.saturating_sub(2 * extra);
+                        }
                         let pool = self.border_side_buffers.entry(id).or_default();
                         let mut buf_index = 0;
-                        for strip in &strips[2..] {
+                        for strip in &side_strips {
                             if strip.width == 0 || strip.height == 0 {
                                 continue;
                             }
@@ -317,6 +574,43 @@ impl CompState {
                             }
                         }
                     }
+                    // Shadow, positioned from the same animated `geom` as
+                    // everything else here - not `w.geometry` - for the
+                    // same reason a stale-position border read as detached
+                    // from a mid-tween window before that fix: see `geom`'s
+                    // own doc comment above. Pushed *after* the titlebar/
+                    // border above, not before - `custom_elements` treats
+                    // earlier-pushed as topmost (see `border_side_render_
+                    // element`'s doc comment), and a shadow pushed first
+                    // rendered on top of this same window's own border
+                    // strips, alpha-blending black over them and muting the
+                    // configured border colour into a hazy, indistinct
+                    // smear instead of a crisp line. Reported live as
+                    // "spacing before the border" - confirmed by sampling
+                    // pixels straight across a window's edge: no run of the
+                    // configured border colour appeared anywhere, just a
+                    // gradient straight from content black into the
+                    // shadow's own falloff. `shadow_bitmap`'s own doc
+                    // comment already assumed "the window's own border/
+                    // titlebar/content always draws over it" - true for
+                    // content (spatially disjoint from the shadow's
+                    // rendered rect either way) but not for the border,
+                    // which sits inside the shadow's footprint and needs
+                    // the *later* push, not the earlier one, to actually
+                    // end up on top of it. Not fragment-clipped against
+                    // `occluders` like the titlebar/border above: at
+                    // `SHADOW_MAX_ALPHA`'s low opacity, a shadow bleeding
+                    // slightly onto a window stacked in front of this one
+                    // reads as a soft edge, not the hard-line bleed-through
+                    // that made the titlebar/border need it.
+                    if let Some(shadow) = self.shadow_buffers.get(&id) {
+                        let rect = decoration::shadow_rect(frame);
+                        let pos = ((rect.x - origin.x) as f64, (rect.y - origin.y) as f64);
+                        match MemoryRenderBufferRenderElement::from_buffer(&mut udev.renderer, pos, shadow, None, None, None, Kind::Unspecified) {
+                            Ok(elem) => custom_elements.push(crate::elements::OverlayElement::Memory(elem)),
+                            Err(e) => log::warn!("udev: failed to import shadow buffer: {e}"),
+                        }
+                    }
                     // The window's own content, at its own `opacity` --
                     // this, not decoration, is the entire reason content
                     // moved into this loop at all (see the doc comment on
@@ -354,7 +648,35 @@ impl CompState {
                             let content_offset = dwindow.geometry().loc;
                             let pos = (geom.x - origin.x - content_offset.x, geom.y + band - origin.y - content_offset.y);
                             let mut rounded_elem = None;
-                            if rounded_corners_enabled {
+                            // Skipped for whichever window is being
+                            // interactively resized right now, specifically
+                            // (not gated on `is_resizing()` alone, which
+                            // would also blank every *other* window's own
+                            // masking for the duration): `rounded_content_
+                            // buffer`'s own doc comment already flagged this
+                            // backend's real CPU cost - a full row-by-row
+                            // copy of the surface's *entire* pixel buffer on
+                            // every commit, unlike the free-on-GPU winit/
+                            // GLES path - and a resize is exactly the case
+                            // that pays it hardest: content reflows and
+                            // recommits on every single frame of the drag,
+                            // not just once. Reported live as "resizing is
+                            // very laggy" the first time this session real
+                            // hardware actually exercised `general.
+                            // rounded_corners` turned on at all (it defaults
+                            // off for exactly this reason). The corner mask
+                            // is cosmetic and this is the one moment its
+                            // absence is least likely to be noticed --
+                            // attention is on the edge being dragged, not
+                            // the opposite corner's curve - so skipping it
+                            // for the resize's duration and letting it
+                            // reappear the instant it ends (no cache
+                            // invalidation needed either way: `epoch`
+                            // already only rebuilds on a real content
+                            // change) is a real fix, not a visible
+                            // regression.
+                            let being_resized = self.wm.borrow().resizing_window() == Some(id);
+                            if rounded_corners_enabled && !being_resized {
                                 let epoch = self.content_epoch.get(&id).copied().unwrap_or(0);
                                 // Bottom-only for a decorated window, same
                                 // reasoning as `winit/render.rs`'s identical split:
@@ -362,11 +684,24 @@ impl CompState {
                                 // under the titlebar band's own rounded
                                 // bitmap.
                                 let corners = if w.decorated { crate::rounded_corners::RoundedCorners::BOTTOM_ONLY } else { crate::rounded_corners::RoundedCorners::ALL };
-                                if let Some(buffer) =
-                                    crate::elements::rounded_content_buffer(&mut self.rounded_content_buffers, epoch, id, &surface, w.corner_radius as f32, corners)
-                                {
-                                    match MemoryRenderBufferRenderElement::from_buffer(&mut udev.renderer, (pos.0 as f64, pos.1 as f64), buffer, Some(w.opacity), None, None, Kind::Unspecified)
-                                    {
+                                // `content_offset`/`band` above already give
+                                // this window's own content origin/size; the
+                                // mask's own off-screen buffer is rendered
+                                // and sized to match exactly, so (unlike the
+                                // old per-subsurface-buffer approach) the
+                                // result can simply be placed at plain `pos`
+                                // below - see `rounded_corners_pixman`'s own
+                                // module doc comment for why this no longer
+                                // needs a separate offset or a safety check
+                                // against `content_offset` at all: the whole
+                                // surface tree is what gets masked now, not
+                                // one guessed-at subsurface, so there is
+                                // nothing left it could silently exclude.
+                                let content_size = (frame.width as i32, (frame.height as i32 - band).max(0));
+                                let loc = (-content_offset.x, -content_offset.y);
+                                let masked = crate::elements::rounded_content_buffer(&mut self.rounded_content_buffers, &mut udev.renderer, epoch, id, &surface, loc, content_size, w.corner_radius as f32, corners);
+                                if let Some(buffer) = masked {
+                                    match MemoryRenderBufferRenderElement::from_buffer(&mut udev.renderer, (pos.0 as f64, pos.1 as f64), buffer, Some(w.opacity), None, None, Kind::Unspecified) {
                                         Ok(elem) => rounded_elem = Some(elem),
                                         Err(e) => log::warn!("udev: failed to import rounded content buffer: {e}"),
                                     }
@@ -380,7 +715,7 @@ impl CompState {
                             }
                         }
                     }
-                    occluders.push(geom);
+                    occluders.push(frame);
                 }
                 // Background/bottom layer-shell (wallpaper engines) last --
                 // bottommost, matching smithay's own `space_render_elements`
@@ -388,7 +723,6 @@ impl CompState {
                 custom_elements.extend(crate::elements::output_layer_elements(
                     &mut udev.renderer,
                     &output,
-                    (origin.x, origin.y),
                     |layer| matches!(layer, Layer::Background | Layer::Bottom),
                 ));
             }
@@ -499,7 +833,7 @@ impl CompState {
             };
             if has_damage {
                 let head = &mut udev.heads[index];
-                if let Err(e) = head.copy_and_flip(&udev.card, back) {
+                if let Err(e) = head.copy_and_flip(&udev.card, back, &damage_rects) {
                     log::error!("udev: page flip failed: {e}");
                     continue;
                 }
@@ -523,7 +857,7 @@ impl CompState {
                 // reason not to redraw at whatever rate this loop cycled,
                 // forever, since it kept getting told a new frame was
                 // wanted whether or not the screen had changed at all.
-                presented.push((output, damage_rects));
+                presented.push((output, origin, damage_rects));
             }
         }
 
@@ -537,7 +871,7 @@ impl CompState {
         }
 
         // Frame callbacks + lock confirmation, once the `udev` borrow is done.
-        for (output, damage_rects) in presented {
+        for (output, origin, damage_rects) in presented {
             if locked {
                 let surface = self.lock_surface_for(&output).cloned();
                 crate::lock::send_lock_frame(surface.as_ref(), &output, elapsed);
@@ -545,7 +879,7 @@ impl CompState {
             } else {
                 let out = output.clone();
                 let scale = Scale::from(out.current_scale().fractional_scale());
-                for w in crate::elements::windows_touched_by_damage(&self.space, &damage_rects, scale) {
+                for w in crate::elements::windows_touched_by_damage(&self.space, &damage_rects, origin, scale) {
                     w.send_frame(&out, elapsed, None, |_, _| Some(out.clone()));
                 }
             }
diff --git a/crates/wayland/src/udev/session.rs b/crates/wayland/src/udev/session.rs
index 4dd6db0..561ba7a 100644
--- a/crates/wayland/src/udev/session.rs
+++ b/crates/wayland/src/udev/session.rs
@@ -89,9 +89,17 @@ pub(crate) fn register_session_notifier(handle: &LoopHandle<'static, CompState>,
 
                     // Some drivers reset mode-setting state across a VT
                     // switch; reassert every head before rendering again.
+                    //
+                    // The real connector and mode, not an empty connector
+                    // list and no mode - that shape is DRM/KMS's own way
+                    // to *disable* a CRTC, not reassert it, and was
+                    // confirmed live to leave the screen black after
+                    // switching back with no further VT switch, either
+                    // direction, able to recover it. See `UdevHead::mode`'s
+                    // own doc comment.
                     for head in &mut udev.heads {
                         let fb = head.buffers[head.front].fb;
-                        if let Err(e) = card.set_crtc(head.crtc, Some(fb), (0, 0), &[], None) {
+                        if let Err(e) = card.set_crtc(head.crtc, Some(fb), (0, 0), &[head.connector], Some(head.mode)) {
                             log::warn!("udev: failed to reassert crtc on resume: {e}");
                         }
                         // Force a full repaint: contents are undefined after
@@ -139,10 +147,41 @@ fn handle_libinput_event(state: &mut CompState, event: InputEvent<LibinputInputB
             let Some(udev) = state.udev.as_mut() else { return };
             let delta = event.delta();
             // Clamped to the union of every head, so the pointer travels
-            // between monitors instead of stopping at the first one's edge.
-            let (w, h) = udev.bounds();
-            udev.pointer_pos.x = (udev.pointer_pos.x + delta.x).clamp(0.0, (w - 1.0).max(0.0));
-            udev.pointer_pos.y = (udev.pointer_pos.y + delta.y).clamp(0.0, (h - 1.0).max(0.0));
+            // between monitors instead of stopping at the first one's edge
+            // - `min_x`/`min_y`, not a hardcoded `0.0` floor, so a head
+            // placed at a negative origin (a real "extend left"/"extend
+            // above" arrangement) is actually reachable. See `bounds`'s own
+            // doc comment for the live bug this fixes.
+            let (min_x, min_y, max_x, max_y) = udev.bounds();
+            udev.pointer_pos.x = (udev.pointer_pos.x + delta.x).clamp(min_x, (max_x - 1.0).max(min_x));
+            udev.pointer_pos.y = (udev.pointer_pos.y + delta.y).clamp(min_y, (max_y - 1.0).max(min_y));
+            let pos = udev.pointer_pos;
+            handle_pointer_position(state, pos, event.time_msec());
+        }
+        // Absolute-positioning devices (a touchscreen, a drawing tablet,
+        // and - confirmed live via a `WAYLAND_DEBUG=1` trace from a peer
+        // session - ydotool's virtual uinput device, used throughout this
+        // whole debugging effort) had no handler here at all: this match
+        // only ever covered `PointerMotion` (relative deltas), so every
+        // `PointerMotionAbsolute` event fell through to the catch-all
+        // below and was silently dropped. The winit (nested) backend
+        // already handles this exact event via `event.position_transformed`
+        // (see `winit/events.rs`'s matching arm); this is that same
+        // pattern for the bare-metal backend, which never got it. Uses the
+        // same union-of-every-head bounds `PointerMotion` above clamps
+        // into, so a single absolute-positioning device still addresses
+        // the whole multi-monitor span, not just the first head.
+        InputEvent::PointerMotionAbsolute { event } => {
+            let Some(udev) = state.udev.as_mut() else { return };
+            // `position_transformed` maps the device's own normalized
+            // [0,1] position into a `(0, 0)`-anchored size - offset by
+            // `min_x`/`min_y` afterward, same reasoning as `PointerMotion`
+            // above, so this still addresses a negative-origin head.
+            let (min_x, min_y, max_x, max_y) = udev.bounds();
+            let size = Size::from(((max_x - min_x) as i32, (max_y - min_y) as i32));
+            let pos = event.position_transformed(size);
+            udev.pointer_pos.x = (pos.x + min_x).clamp(min_x, (max_x - 1.0).max(min_x));
+            udev.pointer_pos.y = (pos.y + min_y).clamp(min_y, (max_y - 1.0).max(min_y));
             let pos = udev.pointer_pos;
             handle_pointer_position(state, pos, event.time_msec());
         }
diff --git a/crates/wayland/src/winit/capture.rs b/crates/wayland/src/winit/capture.rs
index a96cff9..3b1d38e 100644
--- a/crates/wayland/src/winit/capture.rs
+++ b/crates/wayland/src/winit/capture.rs
@@ -29,7 +29,7 @@ impl WaylandPlatform {
         let hide_top_layers = self.wm.borrow().visible_windows_front_to_back().any(|w| w.fullscreen);
         let mut custom_elements: Vec<crate::elements::OverlayElement<GlesRenderer>> = Vec::new();
         if !hide_top_layers {
-            custom_elements.extend(crate::elements::output_layer_elements(renderer, &self.output, (0, 0), |layer| matches!(layer, Layer::Top | Layer::Overlay)));
+            custom_elements.extend(crate::elements::output_layer_elements(renderer, &self.output, |layer| matches!(layer, Layer::Top | Layer::Overlay)));
         }
         for id in self.wm.borrow().visible_windows_front_to_back().map(|w| w.id).collect::<Vec<_>>() {
             let Some(w) = self.wm.borrow().window(id).cloned() else { continue };
@@ -41,11 +41,22 @@ impl WaylandPlatform {
             if let Some(dwindow) = self.state.id_to_window.get(&id) {
                 if let Some(surface) = crate::elements::window_wl_surface(dwindow) {
                     let band = if w.decorated { srdwm_core::TITLEBAR_HEIGHT as i32 } else { 0 };
-                    custom_elements.extend(crate::elements::surface_content_elements(renderer, &surface, (w.geometry.x, w.geometry.y + band), w.opacity));
+                    // `content_offset`: same `xdg_surface.set_window_geometry`
+                    // subtraction every other render/capture path in this
+                    // codebase already does (`udev/render.rs`, `winit/
+                    // render.rs`, `udev/capture.rs`) - missed here
+                    // specifically. A CSD client's invisible shadow margin
+                    // landed at `w.geometry.x, w.geometry.y + band` instead
+                    // of its real visible content, so a screenshot taken on
+                    // this backend showed the same content_offset-sized gap
+                    // the on-screen render loops already had fixed.
+                    let content_offset = dwindow.geometry().loc;
+                    let pos = (w.geometry.x - content_offset.x, w.geometry.y + band - content_offset.y);
+                    custom_elements.extend(crate::elements::surface_content_elements(renderer, &surface, pos, w.opacity));
                 }
             }
         }
-        custom_elements.extend(crate::elements::output_layer_elements(renderer, &self.output, (0, 0), |layer| matches!(layer, Layer::Background | Layer::Bottom)));
+        custom_elements.extend(crate::elements::output_layer_elements(renderer, &self.output, |layer| matches!(layer, Layer::Background | Layer::Bottom)));
 
         // A throwaway damage tracker, so this pass always draws the whole
         // scene (age 0) and never perturbs the on-screen tracker's history.
diff --git a/crates/wayland/src/winit/connect.rs b/crates/wayland/src/winit/connect.rs
index d18a489..c748ef4 100644
--- a/crates/wayland/src/winit/connect.rs
+++ b/crates/wayland/src/winit/connect.rs
@@ -113,6 +113,7 @@ impl WaylandPlatform {
             _screencopy_state: screencopy::ScreencopyState::new::<CompState>(&dh),
             screencopy_pending: Vec::new(),
             _appmenu_state: crate::appmenu::AppmenuManagerState::new::<CompState>(&dh),
+            _virtual_keyboard_state: smithay::wayland::virtual_keyboard::VirtualKeyboardManagerState::new::<CompState, _>(&dh, |_client| true),
             _foreign_toplevel_state: crate::foreign_toplevel::ForeignToplevelState::new::<CompState>(&dh),
             foreign_toplevel_managers: Vec::new(),
             foreign_toplevel_handles: HashMap::new(),
@@ -142,6 +143,7 @@ impl WaylandPlatform {
             last_broadcast_workspace: None,
             lock: SessionLock::default(),
             cursor_status: smithay::input::pointer::CursorImageStatus::default_named(),
+            decoration_cursor_active: false,
             cursor_buffers: crate::cursor::make_buffers(),
             last_titlebar_click: None,
             gesture_swipe: None,
@@ -159,12 +161,15 @@ impl WaylandPlatform {
             border_top_decorations: HashMap::new(),
             border_bottom_decorations: HashMap::new(),
             decoration_signatures: HashMap::new(),
+            hovered_titlebar_button: None,
             shadow_buffers: HashMap::new(),
             rounded_corners_program,
             content_epoch: HashMap::new(),
             rounded_content_buffers: HashMap::new(),
             border_side_buffers: HashMap::new(),
+            color_filter_buffers: HashMap::new(),
             last_synced_size: HashMap::new(),
+            pending_size_configure: HashMap::new(),
             pending: pending.clone(),
             bound_keys: Rc::new(bound_keys.iter().cloned().collect()),
             repeat_keys: Rc::new(repeat_keys.iter().cloned().collect()),
diff --git a/crates/wayland/src/winit/mod.rs b/crates/wayland/src/winit/mod.rs
index 707055d..6a7bac0 100644
--- a/crates/wayland/src/winit/mod.rs
+++ b/crates/wayland/src/winit/mod.rs
@@ -19,6 +19,7 @@ use smithay::backend::input::{
 };
 use smithay::backend::renderer::damage::OutputDamageTracker;
 use smithay::backend::renderer::element::memory::MemoryRenderBufferRenderElement;
+use smithay::backend::renderer::element::solid::SolidColorBuffer;
 use smithay::backend::renderer::element::Kind;
 use smithay::backend::renderer::gles::GlesRenderer;
 use smithay::backend::renderer::ImportDma;
@@ -94,6 +95,6 @@ const TARGET_FRAME_TIME: Duration = Duration::from_micros(1_000_000 / 60);
 mod capture;
 mod connect;
 mod events;
-mod platform;
+mod nested_platform;
 mod render;
 mod run;
diff --git a/crates/wayland/src/winit/platform.rs b/crates/wayland/src/winit/nested_platform.rs
index 96adde8..330ef91 100644
--- a/crates/wayland/src/winit/platform.rs
+++ b/crates/wayland/src/winit/nested_platform.rs
@@ -48,9 +48,15 @@ impl Platform for WaylandPlatform {
                 // `WindowManager`, never `state.space`, so an IPC focus
                 // change left rendering/hit-testing on the stale topmost
                 // window until something else happened to raise it.
+                //
+                // `raise_in_space`, not `focus_window` - see that
+                // function's doc comment: the full version re-runs the
+                // workspace-follow side effect on the already-focused
+                // window and silently reverts an `activate_workspace` IPC
+                // dispatch from the same cycle.
                 let focused = self.wm.borrow().focused_id();
                 if let Some(id) = focused {
-                    crate::input::focus_window(&mut self.state, id);
+                    crate::input::raise_in_space(&mut self.state, id);
                 }
             }
         }
diff --git a/crates/wayland/src/winit/render.rs b/crates/wayland/src/winit/render.rs
index ec4fd69..60cccb4 100644
--- a/crates/wayland/src/winit/render.rs
+++ b/crates/wayland/src/winit/render.rs
@@ -4,6 +4,7 @@ impl WaylandPlatform {
 
     pub(super) fn render_frame(&mut self) -> PlatformResult<()> {
         self.state.tick_animations();
+        self.state.tick_hover_glyph_animation();
         self.state.tick_dirty_broadcasts();
         let size = self.backend.window_size();
         let resized = self.output.current_mode().map(|m| m.size) != Some(size);
@@ -61,6 +62,20 @@ impl WaylandPlatform {
         // rounded-content push (further down) uses `WinitElement::Rounded`
         // directly.
         let mut custom_elements: Vec<crate::rounded_corners::WinitElement> = Vec::new();
+        // Night light/reading mode - pushed first (topmost) so it colours
+        // everything else, including the context menu below: this backend
+        // draws no cursor of its own to exempt (unlike udev/render.rs's
+        // matching push), so there's nothing that needs to stay above it.
+        // See `color_filter::render_element` for why this is a translucent
+        // overlay rather than a true per-pixel shader.
+        {
+            let color_filter = self.wm.borrow().color_filter;
+            let output_name = self.output.name();
+            let buf = self.state.color_filter_buffers.entry(output_name).or_insert_with(SolidColorBuffer::default);
+            if let Some(elem) = crate::color_filter::render_element(buf, color_filter, (size.w, size.h)) {
+                custom_elements.push(crate::rounded_corners::WinitElement::Base(crate::elements::OverlayElement::Solid(elem)));
+            }
+        }
         // The right-click titlebar menu, if open - pushed first so it's
         // topmost over every window (this backend draws no cursor of its
         // own, see this module's doc comment, so there's no "stay under
@@ -124,7 +139,7 @@ impl WaylandPlatform {
         let rounded_corners_enabled = self.wm.borrow().rounded_corners_enabled.unwrap_or(true);
         if !hide_top_layers {
             custom_elements.extend(
-                crate::elements::output_layer_elements(renderer, &self.output, (0, 0), |layer| matches!(layer, Layer::Top | Layer::Overlay))
+                crate::elements::output_layer_elements(renderer, &self.output, |layer| matches!(layer, Layer::Top | Layer::Overlay))
                     .into_iter()
                     .map(crate::rounded_corners::WinitElement::Base),
             );
@@ -147,24 +162,18 @@ impl WaylandPlatform {
             // (reported live as the border "not flush" with the window
             // during an animated maximize/fullscreen/open-slide transition).
             let geom = self.state.window_anims.get(&id).map(crate::state::WindowAnim::current_rect).unwrap_or(w.geometry);
-            // Same reasoning as udev/render.rs's matching push: positioned from
-            // `geom`, not `w.geometry`, and not fragment-clipped against
-            // `occluders` - see that comment.
-            if let Some(shadow) = self.state.shadow_buffers.get(&id) {
-                let rect = decoration::shadow_rect(geom);
-                let pos = (rect.x as f64, rect.y as f64);
-                match MemoryRenderBufferRenderElement::from_buffer(renderer, pos, shadow, None, None, None, Kind::Unspecified) {
-                    Ok(elem) => custom_elements.push(crate::rounded_corners::WinitElement::Base(crate::elements::OverlayElement::Memory(elem))),
-                    Err(e) => log::warn!("failed to import shadow buffer for window {id}: {e}"),
-                }
-            }
+            // `geom` is this compositor's own request/target; `frame`
+            // corrects its far edge to match what the client's surface
+            // really committed - see `effective_frame`'s own doc comment
+            // and the matching comment in `udev/render.rs`'s render loop.
+            let frame = self.state.effective_frame(id, geom);
             if let Some(deco) = self.state.decorations.get(&id) {
                 // Fragment-clipped, same as udev/render.rs's matching titlebar
                 // push - see that comment for why all-or-nothing (skip
                 // only once *fully* covered) wasn't enough: a titlebar
                 // only partially covered, the common case for cascaded
                 // windows, still bled through the covered part.
-                let titlebar_rect = srdwm_core::Rect::new(geom.x, geom.y, geom.width, srdwm_core::TITLEBAR_HEIGHT);
+                let titlebar_rect = srdwm_core::Rect::new(frame.x, frame.y, frame.width, srdwm_core::TITLEBAR_HEIGHT);
                 for fragment in crate::elements::visible_border_fragments(titlebar_rect, &occluders) {
                     let pos = (fragment.x as f64, fragment.y as f64);
                     let src = Rectangle::new(
@@ -181,9 +190,14 @@ impl WaylandPlatform {
             // `decoration::border_strips`), so they never overlap this same
             // window's own decoration/content pixels - draw order relative
             // to those doesn't matter, only relative to other windows'.
+            // (The left/right strips *do* still need cropping against the
+            // top/bottom strip's own extended curve - see that crop's own
+            // doc comment further down; that's an overlap between two
+            // pieces of this window's own decoration, not with its content,
+            // so it doesn't contradict this paragraph.)
             if w.border_width > 0 {
-                let color = crate::state::effective_border_color(w.border_color, focused == Some(id));
-                let strips = decoration::border_strips(geom, w.border_width);
+                let color = crate::state::effective_border_color(w.border_color, focused == Some(id), self.wm.borrow().theme.border_inactive_dim);
+                let strips = decoration::border_strips(frame, w.border_width);
                 // Strips 0/1 (top/bottom) are rounded on their own two
                 // corners - see `render_border_top`/`render_border_bottom`'s
                 // doc comments - so both are cached bitmaps (rebuilt only in
@@ -199,7 +213,15 @@ impl WaylandPlatform {
                 // all-or-nothing occlusion check.
                 if strips[0].width > 0 && strips[0].height > 0 && !strips[0].subtract_all(&occluders).is_empty() {
                     if let Some(buffer) = self.state.border_top_decorations.get(&id) {
-                        match MemoryRenderBufferRenderElement::from_buffer(renderer, (strips[0].x as f64, strips[0].y as f64), buffer, None, None, None, Kind::Unspecified) {
+                        // See `decoration::border_top_visible_rows`'s own
+                        // doc comment: an undecorated window has no
+                        // titlebar band to safely absorb this buffer's own
+                        // corner-curve-only extra rows, so they're cropped
+                        // away instead of landing on real content.
+                        let (row0, rows, shift) = decoration::border_top_visible_rows(w.decorated, w.border_width, w.corner_radius);
+                        let pos = (strips[0].x as f64, (strips[0].y + shift as i32) as f64);
+                        let src = Some(Rectangle::new(Point::from((0.0, row0 as f64)), Size::from((strips[0].width as f64, rows as f64))));
+                        match MemoryRenderBufferRenderElement::from_buffer(renderer, pos, buffer, None, src, None, Kind::Unspecified) {
                             Ok(elem) => custom_elements.push(crate::rounded_corners::WinitElement::Base(crate::elements::OverlayElement::Memory(elem))),
                             Err(e) => log::warn!("failed to import top border buffer for window {id}: {e}"),
                         }
@@ -210,15 +232,39 @@ impl WaylandPlatform {
                 // render_border_bottom`'s doc comment.
                 if strips[1].width > 0 && strips[1].height > 0 && !strips[1].subtract_all(&occluders).is_empty() {
                     if let Some(buffer) = self.state.border_bottom_decorations.get(&id) {
-                        match MemoryRenderBufferRenderElement::from_buffer(renderer, (strips[1].x as f64, strips[1].y as f64), buffer, None, None, None, Kind::Unspecified) {
+                        // See `decoration::border_bottom_visible_rows`'s
+                        // own doc comment.
+                        let (row0, rows, shift) = decoration::border_bottom_visible_rows(w.decorated, w.border_width, w.corner_radius);
+                        let pos = (strips[1].x as f64, (strips[1].y - shift as i32) as f64);
+                        let src = Some(Rectangle::new(Point::from((0.0, row0 as f64)), Size::from((strips[1].width as f64, rows as f64))));
+                        match MemoryRenderBufferRenderElement::from_buffer(renderer, pos, buffer, None, src, None, Kind::Unspecified) {
                             Ok(elem) => custom_elements.push(crate::rounded_corners::WinitElement::Base(crate::elements::OverlayElement::Memory(elem))),
                             Err(e) => log::warn!("failed to import bottom border buffer for window {id}: {e}"),
                         }
                     }
                 }
+                // Cropped top and bottom by `extra` - see the matching fix
+                // (and its own doc comment) in `udev/render.rs`'s identical
+                // side-strip loop: the top/bottom strip's own curve extends
+                // `corner_radius - border_width` rows into what would
+                // otherwise be these flat, curve-unaware side strips' own
+                // nominal top/bottom rows, and without this crop their
+                // solid fill bled through the curve's own transparent
+                // cutout as a straight vertical line poking out of an
+                // otherwise correctly-rounded corner - reported live,
+                // confirmed via raw pixel sampling on the udev backend;
+                // this backend shares the identical strip geometry and was
+                // never actually confirmed clean, just never specifically
+                // screenshotted the same way.
+                let extra = if w.decorated { w.border_width.max(w.corner_radius).saturating_sub(w.border_width) } else { 0 };
+                let mut side_strips = [strips[2], strips[3]];
+                for s in &mut side_strips {
+                    s.y += extra as i32;
+                    s.height = s.height.saturating_sub(2 * extra);
+                }
                 let pool = self.state.border_side_buffers.entry(id).or_default();
                 let mut buf_index = 0;
-                for strip in &strips[2..] {
+                for strip in &side_strips {
                     if strip.width == 0 || strip.height == 0 {
                         continue;
                     }
@@ -229,6 +275,30 @@ impl WaylandPlatform {
                     }
                 }
             }
+            // Shadow - pushed *after* the titlebar/border above, not
+            // before. See the matching fix (and its full explanation) in
+            // `udev/render.rs`'s render loop: `custom_elements` treats
+            // earlier-pushed as topmost, so a shadow pushed before this
+            // window's own border rendered on top of it, alpha-blending
+            // black over the configured border colour and muting it into a
+            // hazy smear instead of a crisp line - reported live as
+            // "spacing before the border". Positioned from `geom`, not
+            // `w.geometry`, same reasoning as the border above (a stale-
+            // position shadow during an animated tween looks as detached
+            // as the border did before that fix). Not fragment-clipped
+            // against `occluders` like the titlebar/border above: at
+            // `SHADOW_MAX_ALPHA`'s low opacity, a shadow bleeding slightly
+            // onto a window stacked in front of this one reads as a soft
+            // edge, not the hard-line bleed-through that made the
+            // titlebar/border need it.
+            if let Some(shadow) = self.state.shadow_buffers.get(&id) {
+                let rect = decoration::shadow_rect(frame);
+                let pos = (rect.x as f64, rect.y as f64);
+                match MemoryRenderBufferRenderElement::from_buffer(renderer, pos, shadow, None, None, None, Kind::Unspecified) {
+                    Ok(elem) => custom_elements.push(crate::rounded_corners::WinitElement::Base(crate::elements::OverlayElement::Memory(elem))),
+                    Err(e) => log::warn!("failed to import shadow buffer for window {id}: {e}"),
+                }
+            }
             // The window's own content, at its own `opacity` - see the
             // matching push in `udev/render.rs`'s render loop for why. Single
             // output at the global origin, so no offset to subtract (see
@@ -266,13 +336,13 @@ impl WaylandPlatform {
                     }
                 }
             }
-            occluders.push(geom);
+            occluders.push(frame);
         }
         // Background/bottom layer-shell (wallpaper engines) last --
         // bottommost, matching smithay's own `space_render_elements`
         // ordering, which this whole custom loop now replaces.
         custom_elements.extend(
-            crate::elements::output_layer_elements(renderer, &self.output, (0, 0), |layer| matches!(layer, Layer::Background | Layer::Bottom))
+            crate::elements::output_layer_elements(renderer, &self.output, |layer| matches!(layer, Layer::Background | Layer::Bottom))
                 .into_iter()
                 .map(crate::rounded_corners::WinitElement::Base),
         );
@@ -325,7 +395,7 @@ impl WaylandPlatform {
             self.backend.submit(None).map_err(err)?;
             let scale = Scale::from(self.output.current_scale().fractional_scale());
             let now = self.state.start_time.elapsed();
-            for w in crate::elements::windows_touched_by_damage(&self.state.space, &damage_rects, scale) {
+            for w in crate::elements::windows_touched_by_damage(&self.state.space, &damage_rects, (0, 0).into(), scale) {
                 w.send_frame(&self.output, now, None, |_, _| Some(self.output.clone()));
             }
         }
diff --git a/crates/wayland/src/xwayland.rs b/crates/wayland/src/xwayland.rs
index d8c56a3..a51ee97 100644
--- a/crates/wayland/src/xwayland.rs
+++ b/crates/wayland/src/xwayland.rs
@@ -67,7 +67,33 @@ pub(crate) fn spawn(handle: &LoopHandle<'static, CompState>, display_handle: &sm
         log::warn!("could not set up an -shm wrapper for XWayland ({e}); XWayland windows will likely fail to render - see xwayland.rs's `spawn` docs");
     }
 
-    let (xwayland, client) = XWayland::spawn(display_handle, None, std::iter::empty::<(String, String)>(), true, std::process::Stdio::null(), std::process::Stdio::null(), |_| ())?;
+    // Xwayland's own stdout/stderr, not `/dev/null` - a real session hit
+    // XWayland never becoming ready at all (no `Ready`, no `Error`, no
+    // process left running, `com.canonical.AppMenu.Registrar` left
+    // permanently unclaimed as one downstream symptom of it) with
+    // *nothing* logged anywhere to explain why, because whatever Xwayland
+    // itself would have printed about the failure was being thrown away
+    // right here. A manual, standalone run of the exact same binary (and
+    // of the `-shm` wrapper `ensure_shm_wrapper_on_path` installs) both
+    // succeeded outside this process, which points at something specific
+    // to *this* process's environment/context rather than the binary
+    // itself - but confirming that needs Xwayland's own words, not
+    // another guess. Redirected to a file rather than piped and read back
+    // in-process: a real stdout/stderr handle Xwayland can just write to
+    // synchronously, no async plumbing needed for a diagnostic that's
+    // meant to be read after the fact, not reacted to live.
+    let xwayland_log = xwayland_log_path();
+    if let Some(dir) = xwayland_log.parent() {
+        let _ = std::fs::create_dir_all(dir);
+    }
+    let stdio = |path: &std::path::Path| -> std::process::Stdio {
+        std::fs::OpenOptions::new().create(true).append(true).open(path).map(std::process::Stdio::from).unwrap_or_else(|e| {
+            log::warn!("xwayland: couldn't open {path:?} for Xwayland's own stdout/stderr ({e}); falling back to /dev/null");
+            std::process::Stdio::null()
+        })
+    };
+    let (xwayland, client) =
+        XWayland::spawn(display_handle, None, std::iter::empty::<(String, String)>(), true, stdio(&xwayland_log), stdio(&xwayland_log), |_| ())?;
 
     let handle_for_ready = handle.clone();
     handle
@@ -335,6 +361,61 @@ impl EwmhState {
         Some(srdwm_core::GlobalMenu { bus_name, menu_path, app_path, window_path, source })
     }
 
+    /// Selects `PropertyChangeMask` on `xid` - without this, the X server
+    /// never sends this connection a `PropertyNotify` for it at all, no
+    /// matter what changes. Call once, right after a window finishes
+    /// setup; see `poll_property_events`'s own doc comment for why this is
+    /// needed on top of `update_net_active_window`'s focus-triggered read.
+    fn watch_property_changes(&self, xid: u32) {
+        use smithay::reexports::x11rb::connection::Connection;
+        use smithay::reexports::x11rb::protocol::xproto::{ChangeWindowAttributesAux, ConnectionExt as _, EventMask};
+        if let Err(e) = self.conn.change_window_attributes(xid, &ChangeWindowAttributesAux::new().event_mask(EventMask::PROPERTY_CHANGE)) {
+            log::warn!("xwayland: couldn't watch xid={xid} for global-menu property changes: {e}");
+            return;
+        }
+        let _ = self.conn.flush();
+    }
+
+    /// Every xid, watched via `watch_property_changes`, whose global-menu
+    /// atom changed since the last call - non-blocking, `poll_for_event`
+    /// never waits on the network.
+    ///
+    /// Needed on top of `update_net_active_window`'s per-focus-change read:
+    /// that read only fires when a window *gains* focus, but most toolkits
+    /// set `_GTK_UNIQUE_BUS_NAME`/the menu-path atom once, shortly after
+    /// mapping - for an already-focused window (the common case: a freshly
+    /// launched app almost always opens focused) that registration can
+    /// finish *after* the one focus-triggered read already ran, leaving
+    /// `Window.global_menu` stuck at `None` until the user clicks away and
+    /// back. Reported live as "global menu doesn't show up for some
+    /// windows" - this is why it was intermittent rather than affecting
+    /// every window the same way: it depended on a race between window-map
+    /// and D-Bus registration that a plain focus-change hook has no way to
+    /// see.
+    fn poll_property_events(&self) -> Vec<u32> {
+        use smithay::reexports::x11rb::connection::Connection;
+        use smithay::reexports::x11rb::protocol::Event;
+        let menu_atoms = [
+            self.gtk_unique_bus_name,
+            self.gtk_application_object_path,
+            self.gtk_window_object_path,
+            self.gtk_menubar_object_path,
+            self.gtk_app_menu_object_path,
+            self.unity_object_path,
+            self.kde_appmenu_service_name,
+            self.kde_appmenu_object_path,
+        ];
+        let mut xids = Vec::new();
+        while let Ok(Some(event)) = self.conn.poll_for_event() {
+            if let Event::PropertyNotify(n) = event {
+                if menu_atoms.contains(&Some(n.atom)) && !xids.contains(&n.window) {
+                    xids.push(n.window);
+                }
+            }
+        }
+        xids
+    }
+
     /// `xid` is `None` when focus is on a native Wayland window (or
     /// nothing) rather than an X11 one - `_NET_ACTIVE_WINDOW`'s value is
     /// only meaningful for X11 clients, so this writes `0` (the documented
@@ -399,6 +480,25 @@ impl CompState {
         }
     }
 
+    /// Call once per event-loop tick (same cadence as
+    /// `apply_registrar_events`): applies every global-menu property change
+    /// `EwmhState::poll_property_events` picked up since the last call. See
+    /// that method's own doc comment for why this exists on top of the
+    /// focus-triggered read in `update_net_active_window`.
+    pub(crate) fn poll_global_menu_properties(&mut self) {
+        let xids = match &self.ewmh {
+            Some(ewmh) => ewmh.poll_property_events(),
+            None => return,
+        };
+        for xid in xids {
+            let Some(&id) = self.xwayland_windows.get(&xid) else { continue };
+            let menu = self.ewmh.as_ref().and_then(|ewmh| ewmh.read_global_menu(xid));
+            if let Some(w) = self.wm.borrow_mut().window_mut(id) {
+                w.global_menu = menu;
+            }
+        }
+    }
+
     /// Drains `AppmenuRegistrarState`'s channel and applies every event to
     /// the matching `Window.global_menu` - call once per event-loop tick
     /// (`poll_events`), same as `IpcServer::poll`.
@@ -454,6 +554,18 @@ impl CompState {
 /// the wrapper instead of the real binary. The wrapper always re-execs the
 /// real `Xwayland` with `-shm` prepended to whatever arguments it was
 /// given, so it's transparent to everything else `spawn` sets up.
+/// Where Xwayland's own stdout/stderr land - `$XDG_STATE_HOME/srd/
+/// xwayland.log` (`~/.local/state/srd/xwayland.log` fallback), same
+/// directory `monitor_layout.rs` already uses for this compositor's own
+/// state, appended to (not truncated) so a restart doesn't erase whatever
+/// the previous run's Xwayland process said right before this one starts.
+fn xwayland_log_path() -> std::path::PathBuf {
+    let dir = std::env::var_os("XDG_STATE_HOME").map(std::path::PathBuf::from).unwrap_or_else(|| {
+        std::env::var_os("HOME").map(|h| std::path::PathBuf::from(h).join(".local/state")).unwrap_or_else(std::env::temp_dir)
+    });
+    dir.join("srd").join("xwayland.log")
+}
+
 fn ensure_shm_wrapper_on_path() -> std::io::Result<()> {
     use std::os::unix::fs::PermissionsExt;
 
@@ -573,6 +685,12 @@ impl CompState {
         self.set_keyboard_focus(Some(wl_surface));
         self.pending.borrow_mut().push(CoreEvent::WindowCreated(id));
         self.update_net_client_list();
+        // See `poll_global_menu_properties`'s doc comment: without this,
+        // this connection never receives a `PropertyNotify` for this
+        // window at all, no matter what its global-menu atoms later do.
+        if let Some(ewmh) = &self.ewmh {
+            ewmh.watch_property_changes(surface.window_id());
+        }
         crate::foreign_toplevel::window_created(self, id);
     }
 
diff --git a/crates/x11/src/platform/connect.rs b/crates/x11/src/platform/connect.rs
index 2d2f726..060b3d2 100644
--- a/crates/x11/src/platform/connect.rs
+++ b/crates/x11/src/platform/connect.rs
@@ -19,6 +19,8 @@ impl X11Platform {
             atoms._NET_WM_STATE_MAXIMIZED_HORZ,
             atoms._NET_CLIENT_LIST,
             atoms._NET_ACTIVE_WINDOW,
+            atoms._NET_WM_STRUT,
+            atoms._NET_WM_STRUT_PARTIAL,
         ]).map_err(err)?;
 
         let font = conn.generate_id().map_err(err)?;
@@ -95,6 +97,7 @@ impl X11Platform {
             numlock_mask,
             ipc,
             appmenu_registrar: Some(srdwm_platform::AppmenuRegistrarState::new()),
+            struts: HashMap::new(),
         })
     }
 
diff --git a/crates/x11/src/platform/events.rs b/crates/x11/src/platform/events.rs
index ef970f1..30e3f8d 100644
--- a/crates/x11/src/platform/events.rs
+++ b/crates/x11/src/platform/events.rs
@@ -31,8 +31,43 @@ impl X11Platform {
                 self.conn.flush().map_err(err)?;
                 Ok(None)
             }
-            XEvent::UnmapNotify(ev) => Ok(self.unmanage(ev.window)),
-            XEvent::DestroyNotify(ev) => Ok(self.unmanage(ev.window)),
+            XEvent::UnmapNotify(ev) => {
+                let struts_changed = self.forget_strut_window(ev.window);
+                let unmanaged = self.unmanage(ev.window);
+                // `unmanage`'s own `Event::WindowDestroyed` wins if this
+                // window was somehow both a managed client *and* a tracked
+                // strut window (shouldn't happen in practice - see
+                // `track_strut_window`'s own doc comment - but `unmanage`
+                // returning `Some` either way takes priority, since a
+                // closed window matters more to core than a reservation
+                // change on the very same event).
+                Ok(unmanaged.or_else(|| struts_changed.then(struts::monitors_changed_event)))
+            }
+            XEvent::DestroyNotify(ev) => {
+                let struts_changed = self.forget_strut_window(ev.window);
+                let unmanaged = self.unmanage(ev.window);
+                Ok(unmanaged.or_else(|| struts_changed.then(struts::monitors_changed_event)))
+            }
+            // Only a window we aren't already managing as a regular
+            // top-level client - see `track_strut_window`'s own doc
+            // comment for why a real panel/dock typically needs this path
+            // specifically (override-redirect, so it never goes through
+            // `manage_new_window`/`MapRequest` at all). Fires for *every*
+            // other window that maps too (a client's own subwindows, an
+            // override-redirect tooltip/menu popup), but `read_strut`
+            // inside it is a cheap couple of `GetProperty` round-trips
+            // that come back empty for anything that never sets the
+            // property, so this costs nothing beyond that for the common
+            // case of "not a bar".
+            XEvent::MapNotify(ev) => {
+                if self.xid_to_core.contains_key(&ev.window) {
+                    return Ok(None);
+                }
+                Ok(self.track_strut_window(ev.window).then(struts::monitors_changed_event))
+            }
+            XEvent::PropertyNotify(ev) if ev.atom == self.atoms._NET_WM_STRUT || ev.atom == self.atoms._NET_WM_STRUT_PARTIAL => {
+                Ok(self.update_strut_property(ev.window).then(struts::monitors_changed_event))
+            }
             XEvent::ButtonPress(ev) => {
                 let (x, y) = (ev.root_x as i32, ev.root_y as i32);
                 let hit = self.wm.borrow().hit_test(x, y);
diff --git a/crates/x11/src/platform/mod.rs b/crates/x11/src/platform/mod.rs
index 04c918c..8ca2299 100644
--- a/crates/x11/src/platform/mod.rs
+++ b/crates/x11/src/platform/mod.rs
@@ -54,6 +54,8 @@ x11rb::atom_manager! {
         _NET_WM_STATE_MAXIMIZED_HORZ,
         _NET_CLIENT_LIST,
         _NET_ACTIVE_WINDOW,
+        _NET_WM_STRUT,
+        _NET_WM_STRUT_PARTIAL,
         UTF8_STRING,
         // Global-menu properties - see `read_global_menu`'s doc comment.
         // A native X11 client is exactly the same GTK/Qt app the Wayland
@@ -84,6 +86,36 @@ struct Frame {
     supports_delete: bool,
 }
 
+/// One window's own `_NET_WM_STRUT_PARTIAL` (or the older, span-free
+/// `_NET_WM_STRUT`) reservation - the X11 equivalent of a Wayland
+/// layer-shell surface's exclusive zone (`zwlr_layer_surface_v1::set_
+/// exclusive_zone`, read on the Wayland backends via `layer_map_for_
+/// output(...).non_exclusive_zone()`). At most one edge is ever nonzero
+/// for a real panel/dock (a bar reserves *one* strip, not several), but
+/// the property itself allows all four at once, so all four are kept.
+///
+/// Values are in root-window (screen-global) pixels, matching every other
+/// X11 geometry value in this backend - there is no separate logical/
+/// physical scale to convert between the way the Wayland backends' own
+/// `zone_physical` conversion needs (`udev/platform.rs`'s `monitors()`),
+/// since this compositor's X11 backend has no independent output-scale
+/// concept at all.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+struct Strut {
+    left: u32,
+    right: u32,
+    top: u32,
+    bottom: u32,
+    left_start_y: i32,
+    left_end_y: i32,
+    right_start_y: i32,
+    right_end_y: i32,
+    top_start_x: i32,
+    top_end_x: i32,
+    bottom_start_x: i32,
+    bottom_end_x: i32,
+}
+
 fn err(e: impl std::fmt::Display) -> PlatformError {
     PlatformError::Other(e.to_string())
 }
@@ -150,6 +182,22 @@ pub struct X11Platform {
     /// D-Bus service itself can independently fail (see that module's own
     /// `None` handling).
     appmenu_registrar: Option<srdwm_platform::AppmenuRegistrarState>,
+    /// Every currently-mapped window's own `_NET_WM_STRUT_PARTIAL`/`_NET_
+    /// WM_STRUT` reservation, keyed by its X window id - populated on
+    /// `MapNotify` (see `events.rs`) and kept fresh via `PropertyNotify`
+    /// on the same two atoms, removed on `UnmapNotify`/`DestroyNotify`.
+    /// Read by `monitors()` to shrink each monitor's own usable rect the
+    /// same way the Wayland backends' layer-shell exclusive zones already
+    /// do - see that method's own doc comment. Deliberately keyed on
+    /// *any* mapped window that sets the property, not gated on `_NET_WM_
+    /// WINDOW_TYPE_DOCK` specifically: the EWMH spec's actual reservation
+    /// mechanism is the strut property itself, and real struts also come
+    /// from override-redirect panels that never go through `manage_new_
+    /// window`/`xid_to_core` at all (confirmed live by a peer session's
+    /// own aegis bar, an override-redirect `_NET_WM_WINDOW_TYPE_DOCK`
+    /// window) - so this can't be folded into the existing managed-
+    /// window bookkeeping.
+    struts: HashMap<XWindow, Strut>,
 }
 
 
@@ -169,8 +217,12 @@ mod actions;
 mod connect;
 mod events;
 mod global_menu;
+mod struts;
 mod trait_impl;
 mod window;
 
 #[cfg(test)]
+use struts::usable_rect;
+
+#[cfg(test)]
 mod tests;
diff --git a/crates/x11/src/platform/struts.rs b/crates/x11/src/platform/struts.rs
new file mode 100644
index 0000000..1f58192
--- /dev/null
+++ b/crates/x11/src/platform/struts.rs
@@ -0,0 +1,222 @@
+//! `_NET_WM_STRUT_PARTIAL`/`_NET_WM_STRUT` tracking - the X11 half of
+//! monitor usable-area reservation, matching what the Wayland backends
+//! already do for a `zwlr_layer_shell_v1` bar/dock's exclusive zone (see
+//! `udev/platform.rs`'s `monitors()` and its own `non_exclusive_zone`
+//! doc comment). Confirmed missing entirely, live, by a peer session
+//! (`aegis`) building its own X11-backend bar: an override-redirect
+//! `_NET_WM_WINDOW_TYPE_DOCK` window setting a correct `_NET_WM_STRUT_
+//! PARTIAL` never shrank `srd monitors`' own reported usable rect at
+//! all, so a real tiled client would have had its window placed right
+//! underneath the bar. `grep -rl STRUT crates/x11/src` found nothing at
+//! all before this file - the feature had simply never been built for
+//! this backend, not a narrower bug in existing logic.
+
+use super::*;
+
+/// A strut reservation changed, so whatever `monitors()` would report has
+/// too - `crates/srdwm/src/main.rs`'s own event loop already re-queries
+/// `Platform::monitors()` and refreshes `WindowManager`'s cached list on
+/// exactly this event (it's how output hotplug is handled), so reusing it
+/// here is what actually makes a fresh strut reservation visible to `srd
+/// monitors`/tiling/placement at all - the cached list otherwise only
+/// changes on a real hotplug, never on a dock mapping or resizing itself.
+/// The zero-sized placeholder `Monitor` is never read: that event handler
+/// discards the payload and re-queries the real list unconditionally, the
+/// same "cheap sentinel, ignored on arrival" shape the Wayland backends'
+/// own equivalent trigger already uses (`layer_shell.rs`'s `layer_
+/// destroyed`, on an exclusive-zone change).
+pub(super) fn monitors_changed_event() -> Event {
+    Event::MonitorAdded(Monitor::new(0, "", Rect::new(0, 0, 0, 0)))
+}
+
+impl X11Platform {
+    /// Reads `window`'s current strut reservation, preferring `_NET_WM_
+    /// STRUT_PARTIAL` (12 `CARDINAL`s: left, right, top, bottom, then each
+    /// edge's own start/end span) and falling back to the older, span-free
+    /// `_NET_WM_STRUT` (4 `CARDINAL`s: left, right, top, bottom) for a
+    /// client that only sets that - per the EWMH spec, a plain `_STRUT`
+    /// with no `_PARTIAL` reserves its margin across the *entire* length
+    /// of that edge, which is what defaulting its span to `0..root extent`
+    /// below encodes. `None` if neither property is set, or both are
+    /// present but empty/malformed - the same "nothing reserved" answer
+    /// either way.
+    pub(super) fn read_strut(&self, window: XWindow) -> Option<Strut> {
+        if let Ok(cookie) = self.conn.get_property(false, window, self.atoms._NET_WM_STRUT_PARTIAL, x11rb::protocol::xproto::AtomEnum::CARDINAL, 0, 12) {
+            if let Ok(reply) = cookie.reply() {
+                if let Some(v) = reply.value32().map(|it| it.collect::<Vec<u32>>()) {
+                    if v.len() >= 12 {
+                        let s = Strut {
+                            left: v[0],
+                            right: v[1],
+                            top: v[2],
+                            bottom: v[3],
+                            left_start_y: v[4] as i32,
+                            left_end_y: v[5] as i32,
+                            right_start_y: v[6] as i32,
+                            right_end_y: v[7] as i32,
+                            top_start_x: v[8] as i32,
+                            top_end_x: v[9] as i32,
+                            bottom_start_x: v[10] as i32,
+                            bottom_end_x: v[11] as i32,
+                        };
+                        return if s == Strut::default() { None } else { Some(s) };
+                    }
+                }
+            }
+        }
+        let Ok(cookie) = self.conn.get_property(false, window, self.atoms._NET_WM_STRUT, x11rb::protocol::xproto::AtomEnum::CARDINAL, 0, 4) else {
+            return None;
+        };
+        let reply = cookie.reply().ok()?;
+        let v: Vec<u32> = reply.value32()?.collect();
+        if v.len() < 4 || v[..4] == [0, 0, 0, 0] {
+            return None;
+        }
+        let screen = &self.conn.setup().roots[0];
+        let (w, h) = (screen.width_in_pixels as i32, screen.height_in_pixels as i32);
+        Some(Strut {
+            left: v[0],
+            right: v[1],
+            top: v[2],
+            bottom: v[3],
+            left_start_y: 0,
+            left_end_y: h,
+            right_start_y: 0,
+            right_end_y: h,
+            top_start_x: 0,
+            top_end_x: w,
+            bottom_start_x: 0,
+            bottom_end_x: w,
+        })
+    }
+
+    /// Called on `MapNotify` for any window this backend isn't already
+    /// managing as a regular client (see that call site's own comment for
+    /// why: a real panel/dock is typically override-redirect specifically
+    /// to skip window management entirely, so it never reaches `manage_
+    /// new_window`/`xid_to_core` the way an ordinary top-level does).
+    /// Selecting `PROPERTY_CHANGE` here is what makes a later live resize
+    /// of the bar (`update_strut_property`, on `PropertyNotify`) actually
+    /// get noticed - without it, only the reservation this window had at
+    /// the moment it first mapped would ever be seen. Returns `true` when
+    /// a real reservation was found, so the caller can fire the same
+    /// `Event::MonitorAdded` re-query trigger `monitors()`'s own live
+    /// hotplug path already uses (see that call site's own comment for
+    /// why this can't just call `monitors()` again itself - the cached
+    /// list `srd monitors` actually reads lives in `WindowManager`, one
+    /// layer up, not in this struct).
+    pub(super) fn track_strut_window(&mut self, window: XWindow) -> bool {
+        let Some(strut) = self.read_strut(window) else { return false };
+        self.struts.insert(window, strut);
+        let _ = self.conn.change_window_attributes(window, &ChangeWindowAttributesAux::new().event_mask(EventMask::PROPERTY_CHANGE));
+        let _ = self.conn.flush();
+        true
+    }
+
+    /// `PropertyNotify` on `_NET_WM_STRUT`/`_NET_WM_STRUT_PARTIAL` for a
+    /// window already being watched (`track_strut_window` selected the
+    /// event mask that makes this fire at all) - re-reads and either
+    /// updates or drops the reservation, matching whatever the client's
+    /// new property value actually says (a bar shrinking its own reserved
+    /// strip live, or clearing the property to reserve nothing at all).
+    /// Returns `true` only when the reservation actually changed (not
+    /// merely present) - see `track_strut_window`'s own doc comment for
+    /// what the caller does with that.
+    pub(super) fn update_strut_property(&mut self, window: XWindow) -> bool {
+        let new = self.read_strut(window);
+        let changed = self.struts.get(&window).copied() != new;
+        match new {
+            Some(strut) => {
+                self.struts.insert(window, strut);
+            }
+            None => {
+                self.struts.remove(&window);
+            }
+        }
+        changed
+    }
+
+    /// `UnmapNotify`/`DestroyNotify` for a tracked strut window - a no-op
+    /// `HashMap::remove` for every other window, so this is safe to call
+    /// unconditionally from both handlers rather than needing its own
+    /// "was this actually a strut window" check first. Returns `true`
+    /// only when a real reservation actually existed and was removed --
+    /// see `track_strut_window`'s own doc comment for what the caller
+    /// does with that.
+    pub(super) fn forget_strut_window(&mut self, window: XWindow) -> bool {
+        self.struts.remove(&window).is_some()
+    }
+
+    /// `full`, shrunk by every tracked strut whose reserved band actually
+    /// overlaps it - the X11 equivalent of `udev/platform.rs`'s `non_
+    /// exclusive_zone`-based `usable` computation, called once per
+    /// monitor from `monitors()`. See the free [`usable_rect`] function
+    /// below (the actual math, kept separate so it's unit-testable
+    /// without a live X11 connection) for exactly how.
+    pub(super) fn usable_rect_for(&self, full: Rect) -> Rect {
+        let screen = &self.conn.setup().roots[0];
+        let screen_size = (screen.width_in_pixels as i32, screen.height_in_pixels as i32);
+        usable_rect(full, screen_size, self.struts.values().copied())
+    }
+}
+
+/// The actual shrink math behind [`X11Platform::usable_rect_for`], pulled
+/// out as a free function of plain values (no live X11 connection needed)
+/// specifically so it can be unit tested directly - `usable_rect_for`
+/// itself needs `self.conn.setup()` for the root screen's own dimensions,
+/// which only a real connected server can answer.
+///
+/// Every strut value is a distance in from the *screen's* own edge
+/// (ICCCM/EWMH `_NET_WM_STRUT_PARTIAL`: `top` reserves root-absolute
+/// `y ∈ [0, top)`, `bottom` reserves `y ∈ [screen_height - bottom,
+/// screen_height)`, and so on) - not from this monitor's own edge, so
+/// the reserved boundary is computed in root-absolute coordinates first
+/// (needing `screen_size` for the bottom/right cases) and only then
+/// intersected against `full`. A strut anchored on an edge this monitor
+/// doesn't border at all, or whose own start/end span doesn't overlap
+/// this monitor's extent on the perpendicular axis (a bar on a different
+/// monitor entirely, in a multi-monitor setup), correctly contributes no
+/// shrink either way, since its reserved boundary then falls outside
+/// `full` on that axis.
+pub(super) fn usable_rect(full: Rect, screen_size: (i32, i32), struts: impl Iterator<Item = Strut>) -> Rect {
+    let (screen_w, screen_h) = screen_size;
+    let (full_left, full_top) = (full.x, full.y);
+    let (full_right, full_bottom) = (full.x + full.width as i32, full.y + full.height as i32);
+    let (mut left, mut top, mut right, mut bottom) = (full_left, full_top, full_right, full_bottom);
+    for strut in struts {
+        if strut.top > 0 && strut.top_end_x > full_left && strut.top_start_x < full_right {
+            top = top.max(strut.top as i32);
+        }
+        if strut.bottom > 0 && strut.bottom_end_x > full_left && strut.bottom_start_x < full_right {
+            bottom = bottom.min(screen_h - strut.bottom as i32);
+        }
+        if strut.left > 0 && strut.left_end_y > full_top && strut.left_start_y < full_bottom {
+            left = left.max(strut.left as i32);
+        }
+        if strut.right > 0 && strut.right_end_y > full_top && strut.right_start_y < full_bottom {
+            right = right.min(screen_w - strut.right as i32);
+        }
+    }
+    // Clamped against the monitor's own opposite edge, not just `0`: a
+    // strut reservation declared against the *whole screen* can still
+    // exceed a single monitor's own extent in a multi-monitor layout
+    // (e.g. a bar `top=32` on a screen where this particular monitor's
+    // usable band is otherwise smaller than that) - without this, an
+    // overshoot on one axis could invert `left > right`/`top > bottom`
+    // into a negative-size rect instead of clamping to "no usable space
+    // left on this monitor". Each axis's two edges are clamped as
+    // separate statements, in order (`left` before `right`, `top` before
+    // `bottom`), not one combined tuple `let` - a first version of this
+    // used `let (top, bottom) = (top.min(full_bottom), bottom.max(top))`
+    // in one statement, which reads `top` on the right-hand side of both
+    // tuple elements from the *pre-clamp* binding (a `let` only shadows
+    // once the whole statement finishes), silently clamping `bottom`
+    // against the wrong, oversized `top` - caught by a test asserting
+    // `usable.height == 0` for a strut taller than the monitor, which
+    // instead came back as `400`, not `0`.
+    let left = left.min(full_right);
+    let right = right.max(full_left).max(left);
+    let top = top.min(full_bottom);
+    let bottom = bottom.max(full_top).max(top);
+    Rect::new(left, top, (right - left).max(0) as u32, (bottom - top).max(0) as u32)
+}
diff --git a/crates/x11/src/platform/tests.rs b/crates/x11/src/platform/tests.rs
index 61d8124..7af5455 100644
--- a/crates/x11/src/platform/tests.rs
+++ b/crates/x11/src/platform/tests.rs
@@ -46,3 +46,52 @@
         let keycodes = modmap(2, &[(3, 50)]);
         assert_eq!(modmask_for_keycode_in_mod_slots(99, 2, &keycodes), ModMask::from(0u16));
     }
+
+    fn top_strut(height: u32, start_x: i32, end_x: i32) -> Strut {
+        Strut { top: height, top_start_x: start_x, top_end_x: end_x, ..Strut::default() }
+    }
+
+    #[test]
+    fn a_top_bar_shrinks_the_monitor_it_actually_spans() {
+        let full = Rect::new(0, 0, 1920, 1080);
+        let strut = top_strut(32, 0, 1920);
+        let usable = usable_rect(full, (1920, 1080), std::iter::once(strut));
+        assert_eq!(usable, Rect::new(0, 32, 1920, 1048));
+    }
+
+    #[test]
+    fn a_bar_confined_to_a_different_monitor_leaves_this_one_alone() {
+        // A 1920-wide bar sitting entirely over the first monitor
+        // (x 0..1920) must not shrink a second monitor placed to its
+        // right (x 1920..3840) - struts are screen-global, not
+        // monitor-relative, so this is the only thing that tells them
+        // apart.
+        let second_monitor = Rect::new(1920, 0, 1920, 1080);
+        let strut = top_strut(32, 0, 1920);
+        let usable = usable_rect(second_monitor, (3840, 1080), std::iter::once(strut));
+        assert_eq!(usable, second_monitor);
+    }
+
+    #[test]
+    fn a_bottom_strut_is_measured_from_the_screen_bottom_not_the_monitor() {
+        let full = Rect::new(0, 0, 1920, 1080);
+        let strut = Strut { bottom: 40, bottom_start_x: 0, bottom_end_x: 1920, ..Strut::default() };
+        let usable = usable_rect(full, (1920, 1080), std::iter::once(strut));
+        assert_eq!(usable, Rect::new(0, 0, 1920, 1040));
+    }
+
+    #[test]
+    fn a_strut_larger_than_the_monitor_clamps_to_zero_size_not_a_negative_one() {
+        let full = Rect::new(0, 0, 800, 600);
+        let strut = top_strut(1000, 0, 800);
+        let usable = usable_rect(full, (800, 600), std::iter::once(strut));
+        assert_eq!(usable.height, 0);
+        assert!(usable.width > 0, "only the top edge was reserved, the sides must stay untouched");
+    }
+
+    #[test]
+    fn no_struts_at_all_leaves_the_monitor_exactly_as_reported() {
+        let full = Rect::new(100, 50, 1024, 768);
+        let usable = usable_rect(full, (1920, 1080), std::iter::empty());
+        assert_eq!(usable, full);
+    }
diff --git a/crates/x11/src/platform/trait_impl.rs b/crates/x11/src/platform/trait_impl.rs
index 1ff7845..b45a4aa 100644
--- a/crates/x11/src/platform/trait_impl.rs
+++ b/crates/x11/src/platform/trait_impl.rs
@@ -56,14 +56,37 @@ impl Platform for X11Platform {
                 continue;
             }
             let name = String::from_utf8_lossy(&info.name).to_string();
-            let mut m = Monitor::new(i as u32, name, Rect::new(crtc.x as i32, crtc.y as i32, crtc.width as u32, crtc.height as u32));
+            let full = Rect::new(crtc.x as i32, crtc.y as i32, crtc.width as u32, crtc.height as u32);
+            // Shrunk by whatever `_NET_WM_STRUT`/`_NET_WM_STRUT_PARTIAL`
+            // a panel/dock has reserved - see `struts::usable_rect_for`'s
+            // own doc comment; this is the X11 mirror of `udev/platform.
+            // rs`'s `monitors()` shrinking by `non_exclusive_zone()`.
+            // Reporting the full head size here otherwise means core's
+            // placement/tiling treats a bar's own reserved strip as
+            // ordinary free space, exactly the gap a peer session (aegis)
+            // found and reported live building its own X11-backend bar.
+            let usable = self.usable_rect_for(full);
+            let mut m = Monitor::new(i as u32, name, usable);
+            m.full_geometry = full;
+            // Same as `geometry`, not top-only - see `udev/platform.rs`'s
+            // own `maximize_geometry_for` doc comment for why a dock on
+            // any edge, not just a top menu bar, should keep maximize
+            // from covering it: no edge actually benefits from the
+            // top-only distinction the way a plain top menu bar once did,
+            // and respecting every edge here is what every mainstream
+            // desktop's own maximize convention already does.
+            m.maximize_geometry = usable;
             m.primary = i == 0;
             monitors.push(m);
         }
         if monitors.is_empty() {
             let screen = &self.conn.setup().roots[0];
+            let full = Rect::new(0, 0, screen.width_in_pixels as u32, screen.height_in_pixels as u32);
+            let usable = self.usable_rect_for(full);
             monitors.push({
-                let mut m = Monitor::new(0, "default", Rect::new(0, 0, screen.width_in_pixels as u32, screen.height_in_pixels as u32));
+                let mut m = Monitor::new(0, "default", usable);
+                m.full_geometry = full;
+                m.maximize_geometry = usable;
                 m.primary = true;
                 m
             });
diff --git a/docs/DEFAULTS.md b/docs/DEFAULTS.md
index 68d3839..c5d8d4a 100644
--- a/docs/DEFAULTS.md
+++ b/docs/DEFAULTS.md
@@ -30,12 +30,67 @@ either.
 ```lua
 srd.set("monitor.primary_layout", "dynamic")           -- Default: "dynamic"
 srd.set("monitor.secondary_layout", "tiling")          -- Default: "tiling"
-srd.set("monitor.auto_detect", true)                   -- Default: true
 ```
-srdwm has one flat workspace list shared by every monitor, not an
-independent set per monitor - there is no "this monitor's primary
-workspace"/"this monitor's workspace count" to configure. `workspace.count`
-below is the actual knob.
+These two keys set the layout for the primary monitor and for secondary
+monitors. They apply only when `workspace.per_monitor` is `true`. Set
+`workspace.per_monitor` to `false` (the default) and every monitor shares
+one workspace. In that mode there is no separate primary/secondary
+workspace to apply a different layout to, so these keys do nothing.
+
+`monitor.auto_detect` is not implemented. Monitor detection runs
+unconditionally; there is no toggle for it.
+
+#### `srd.monitor.split(name, parts[, direction])`
+
+Splits one physical monitor into `parts` equal logical monitors. Each
+logical monitor gets its own name (`eDP-1-1`, `eDP-1-2`, and so on), its
+own id, and its own placement rules. Windows tile and place within one
+logical monitor the same way they do on a real one.
+
+`direction` is `"columns"` (default) or `"rows"`. Columns place the
+logical monitors side by side. Rows stack them.
+
+```lua
+srd.monitor.split("eDP-1", 2)              -- two side-by-side halves
+srd.monitor.split("HDMI-A-1", 2, "rows")   -- two stacked halves
+```
+
+This does not create a second `wl_output`. A client that asks for
+`wl_output.enter` or the output's scale still sees the one real output.
+Fullscreen and maximize inside a logical monitor stay within that logical
+monitor's own bounds; they do not spill into the other half.
+
+`srd monitors` and the `monitors` event mark each split part with
+`"split": true`. An ordinary, undivided output reports `"split": false`.
+A display-arrangement UI should read this field and treat a split part
+differently from a real output: do not offer to move it, resize it, or
+extend a physical arrangement onto it, since there is no independent
+output behind it.
+
+#### `srd.monitor.scale(name, factor)`
+
+Sets the output scale for one monitor by connector name.
+
+srdwm sets scale automatically by default. It reads each monitor's
+physical size and resolution from EDID, computes real pixel density
+(PPI), and scales down monitors below roughly 109 PPI - a large monitor
+at the same resolution as a smaller one, for example. It never scales a
+monitor above `1.0` on its own.
+
+Use `srd.monitor.scale` to override the automatic value for one
+connector:
+
+```lua
+srd.monitor.scale("HDMI-A-1", 0.75)
+```
+
+Set `factor` to `0` or less to clear an override and return that
+connector to the automatic value.
+
+A scale change, automatic or explicit, takes effect the next time srdwm
+brings that connector's output up: at startup, at hotplug, or after
+`srd dispatch set output enabled <name> true`. It does not apply to an
+already-running output on a plain config reload.
 
 ### Window Behavior (`window.*`)
 Not implemented: this whole namespace duplicated `general.*`'s own focus
@@ -152,19 +207,22 @@ srd.theme.set_colors({
 ```lua
 srd.theme.set_decorations({
     border = {
-        width = 2,                                      -- Default: 2
-        radius = 6,                                      -- Default: 6 (corner radius, logical px)
+        width = 4,                                      -- Default: 4
+        radius = 12,                                     -- Default: 12 (corner radius, logical px)
         active_color = "#88c0d0",                       -- Default: Nord blue
-        inactive_color = "#2e3440",                     -- Default: Nord dark
+        inactive_color = "#2e3440",                     -- Accepted, not read: see inactive_dim below
+        inactive_dim = 0.35,                            -- Default: 0.35 - unfocused border = active_color scaled by this factor (0 = black, 1 = same as focused). The real unfocused-border knob; inactive_color above is validated but never applied, since an absolute override would erase the dimming scheme instead of participating in it.
         focused_style = "solid",                        -- Default: "solid"
         unfocused_style = "solid"                       -- Default: "solid"
     },
     title_bar = {
-        height = 24,                                    -- Default: 24
+        height = 32,                                    -- Not actually read - see the note below the table
         show = true,                                    -- Default: true
         font = "JetBrains Mono 10",                     -- Default: "JetBrains Mono 10"
         background = "#2e3440",                         -- Default: Nord dark
-        foreground = "#eceff4"                          -- Default: Nord light
+        foreground = "#eceff4",                         -- Accepted, not read: see foreground_focused/foreground_unfocused below
+        foreground_focused = "#88c0d0",                 -- Default: Nord blue - titlebar text/icon colour on the focused window
+        foreground_unfocused = "#4c566a"                -- Default: Nord dark gray - titlebar text/icon colour on every other window
     },
     - Which decoration mode a window gets before any per-window rule or
     - the window's own `xdg-decoration` request has a say. "server"
@@ -182,6 +240,111 @@ srd.theme.set_decorations({
 })
 ```
 
+`title_bar.height` above is accepted but not read: the real titlebar band
+is `srdwm_core::TITLEBAR_HEIGHT`, a compile-time constant (currently `32`)
+shared between hit-testing and rendering so the two can never disagree.
+Setting this key has no effect; it's kept in the table only so a preset
+copied from here doesn't read as silently missing a value real desktops
+all expose.
+
+Four more `theme.decorations.title_bar.*` keys are flat `srd.set` values, not part of
+the `set_decorations` table above:
+
+```lua
+srd.set("theme.decorations.title_bar.text_align", "left")     -- Default: "left"
+srd.set("theme.decorations.title_bar.button_side", "right")   -- Default: "right"
+srd.set("theme.decorations.title_bar.button_order", "")        -- Default: "" (unset)
+srd.set("theme.decorations.title_bar.button_glyph", "hover")   -- Default: "hover"
+srd.set("theme.decorations.title_bar.button_style", "traffic_lights")  -- Default: "traffic_lights"
+```
+
+`text_align` sets `"center"` for the macOS convention (title centered on
+the whole titlebar width, ignoring the button cluster the way real macOS
+does) or `"left"` (default) for the Windows/GTK convention. Any value
+other than exactly `"center"` keeps `"left"`.
+
+`button_side` sets `"left"` for the macOS convention (close, minimize,
+maximize, left to right) or `"right"` for the Windows/GTK convention
+(minimize, maximize, close). Any value other than exactly `"left"` keeps
+`"right"`.
+
+`button_order` overrides the relative order of the three buttons on
+whichever side `button_side` selects. Set it to a comma-separated list
+naming each button once: `"close,minimize,maximize"`. Unset (the
+default) keeps `button_side`'s own built-in order. A value that does not
+name each button exactly once is rejected with a warning in the log; the
+built-in order stays in effect.
+
+`button_side` and `button_order` are independent settings: `button_side`
+alone chooses which convention's default order applies; `button_order`
+replaces that order with your own, applied to whichever side `button_side`
+selected. This matches KWin's `ButtonsOnLeft`/`ButtonsOnRight`, GNOME/
+Adwaita's `decoration-layout`, and Openbox's `titlelayout` - each
+independently uses a comma- or letter-separated button list for exactly
+this purpose.
+
+`button_glyph` sets `"always"` to keep each button's icon visible at all
+times (modern GNOME/Adwaita), or `"hover"` (the default, classic macOS)
+to hide the icon until the pointer is over that button.
+
+`button_style` sets `"traffic_lights"` (the default) for filled, coloured
+macOS-style dots with a glossy gradient and a "zoom" double-arrow maximize
+icon, or `"traditional"` for plain glyphs (X / square / dash) drawn
+straight on the titlebar background - no filled dot except a subtle,
+neutral hover backdrop - and a plain square maximize icon, matching a
+real Windows or GNOME titlebar's own convention instead. Any value other
+than exactly `"traditional"` keeps `"traffic_lights"`. Independent of
+`button_side` and `button_order`: either style can sit on either side in
+either order, though `"traffic_lights"` paired with `button_side =
+"left"` (macOS) and `"traditional"` paired with `button_side = "right"`
+(Windows/GNOME) are the two ready-made combinations `config/srd/
+themes.lua` ships (`macos` and `traditional` presets respectively).
+
+### Getting a full macOS look
+
+`apply(macos)` in `config/srd/themes.lua` covers everything srdwm itself
+draws: centered titlebar text, left-aligned traffic-light buttons with a
+glossy gradient, grey chrome matching a dark GTK theme. It does **not**
+cover any other application's own window decoration - an undecorated
+(client-side-decorated) window like Firefox or a GTK file manager draws
+its *own* titlebar buttons, entirely outside srdwm's control. Getting
+those to match too is three separate, srdwm-external steps, each a normal
+part of *this desktop's* own configuration, not something a compositor
+can apply on an app's behalf:
+
+1. **Button side for every GTK/Firefox-on-Linux app**: Firefox and GTK3/4
+   apps both read `org.gnome.desktop.wm.preferences button-layout`
+   directly for which side to draw their own window buttons on --
+   independent of any srdwm setting.
+   ```sh
+   gsettings set org.gnome.desktop.wm.preferences button-layout 'close,minimize,maximize:'
+   ```
+   (System-wide; revert with `'appmenu:minimize,maximize,close'`, GNOME's
+   own default.)
+
+2. **Firefox's own button colour/gradient**: Firefox draws its titlebar
+   buttons itself and only reads a stylesheet you provide, in your own
+   profile, never srdwm's config. Requires `toolkit.
+   legacyUserProfileCustomizations.stylesheets = true` in `about:config`
+   (one-time per profile) plus a full Firefox restart, and a
+   `userChrome.css` in that profile's own `chrome/` directory targeting
+   `.titlebar-close`/`.titlebar-min`/`.titlebar-max`/`.titlebar-restore`
+   (Firefox's own class names for these buttons - confirmed directly
+   against a real Firefox install's own `browser.xhtml`, inside its
+   `omni.ja`, rather than assumed, since these have changed across
+   versions before).
+
+3. **Other GTK apps' own button colour/gradient** (Nemo, etc.): these
+   follow the system GTK theme, so a user `~/.config/gtk-3.0/gtk.css` /
+   `~/.config/gtk-4.0/gtk.css` overriding `headerbar button.titlebutton`
+   (loaded after whatever theme is active in `gtk-theme-name`) gets the
+   same gradient onto every such app at once, without touching the theme
+   package itself.
+
+None of this ships from srdwm or from this repo's own `config/srd/` --
+it lives in each user's own dotfiles/profile, the same as any other
+per-application customization on Linux.
+
 ## Key Binding Defaults
 
 ### Essential Bindings
diff --git a/docs/PANEL_SUPPORT_TODO.md b/docs/PANEL_SUPPORT_TODO.md
index 33a2214..d9c5305 100644
--- a/docs/PANEL_SUPPORT_TODO.md
+++ b/docs/PANEL_SUPPORT_TODO.md
@@ -387,10 +387,15 @@ session_lock, shm, viewporter, xdg_decoration, xdg_shell, xwayland_shell.
       on exit.** `IpcServer`'s `Drop` impl already removes its socket path
       unconditionally; verified while auditing `foreign_toplevel`/protocol
       cleanup paths this pass.
-- [ ] `jq: parse error: Invalid numeric literal at line 1, column 28` repeats
-      continuously in `~/.local/state/wm-session-latest.log` - something in the
-      session scripts pipes non-JSON into `jq` in a loop. Harmless, but it buries
-      real errors.
+- [x] FIXED - `jq: parse error: Invalid numeric literal at line 1, column 28`
+      repeated continuously in `~/.local/state/wm-session-latest.log` --
+      `hyprctl`'s own "not running" message goes to stdout, not stderr, so
+      every script that still called it unconditionally after the
+      Hyprland-to-srdwm migration fed that sentence straight into `jq` as
+      if it were JSON. Fixed with an `[ -n "${HYPRLAND_INSTANCE_SIGNATURE:-}" ]`
+      guard added to `~/.scripts/sys/night-light`, `reading-mode`, and
+      `~/.scripts/utils/toggle-blur`, `move_terminal` - confirmed present
+      in all four as of 2026-08-19.
 
 ---
 
diff --git a/docs/TODO.md b/docs/TODO.md
new file mode 100644
index 0000000..eec8845
--- /dev/null
+++ b/docs/TODO.md
@@ -0,0 +1,1596 @@
+# TODO / planned features - master checklist
+
+The single consolidated list of pending work. Before this file, "what's
+left" was scattered across four places that each grew their own list
+independently (`MISSING.md`, `PANEL_SUPPORT_TODO.md`,
+`IMPLEMENTATION_STATUS.md`'s tail, `SESSION_HANDOFF.md`), and
+`PANEL_SUPPORT_TODO.md` in particular had gone almost entirely stale -
+90%+ of its items were actually done and just never checked off. This
+file doesn't replace any of them (each still holds the real narrative:
+root cause, what was tried, what was ruled out) - it's the one place to
+look to see everything pending at a glance, with a pointer to the doc
+that has the full story. Keep this list current as items close or open;
+update the source doc's own entry too, don't let this drift into a
+second stale copy the way `PANEL_SUPPORT_TODO.md` did.
+
+## Real bug, root-caused and fixed: `DecorationSignature` was missing three of `render_titlebar`'s own inputs, so a live change to any of them would never invalidate the cache (2026-08-24)
+
+Found by a full-pipeline audit requested directly ("please do a deep dive into our codebase") after several rounds of live-reported rendering issues. `redraw_decoration_buffer`'s call to `decoration::render_titlebar` (`state/lifecycle.rs`) passes `theme.button_glyph_always`/`theme.button_order`/`theme.traffic_light_buttons` as three of its arguments, but `DecorationSignature` (`state/mod.rs`) - whose own doc comment states its goal outright, "one signature covering every input this function reads" - never included any of the three. `title_centered`/`buttons_left` were already in the struct specifically for this reason (their own doc comments say so explicitly: "there's no `srd set` for this yet, but nothing here assumes there never will be"), making the omission of the other three look like a straightforward miss rather than a deliberate exclusion.
+
+Currently latent, not reachable today: nothing in `srd set`'s current command list can change any of the three live, so this was a landmine for whenever live theme reload or a new `srd set` grows to cover them, not a bug with a live repro today. Fixed anyway, matching the existing fields' own precedent, rather than left for a future session to rediscover the same gap. Test suite run pending; built.
+
+## Real bug, root-caused, first fix attempt reverted as unsafe - still open: a decorated/undecorated window's border, shadow, and resize hit-test all lag a stale, previous-frame size for the whole duration of an interactive resize (2026-08-24)
+
+Reported live: "notice how in firefox window the borders are misaligned, especially when i resize the window." Root cause in `state/geometry.rs`'s `effective_frame_of` - the function every border/shadow/occlusion/resize-hit-test call site uses to correct a window's drawn rect against what the client *actually* committed, rather than what this compositor merely requested (built earlier this session to fix a real, different bug: a terminal's own cell-quantized size leaving a gap between its content and the border). That correction is applied *unconditionally*, including while the window is being actively, interactively resized - but during a live drag, `geom` (the compositor's own live target) updates on every pointer-motion event, while the client's last real commit is however far behind that a full relayout pass takes. For a heavy client (Firefox, concretely - a plain terminal reflows near-instantly and never showed this visibly) that lag is real and continuous, so the border/shadow keeps drawing at a stale size for the *entire* drag, worst at exactly the edge/corner being dragged, while the content underneath (never routed through this function at all) renders whatever the client has actually gotten around to committing.
+
+**First fix attempt (skip the correction entirely while `WindowManager::resizing_window() == Some(id)`) was reverted in the same session it landed, before ever being confirmed live.** A full-pipeline audit (prompted by the user directly asking for one after this fix still didn't resolve their report) traced the actual consequence: the titlebar bitmap and the top/bottom border strip's own rounded-corner bitmap (both built by `redraw_decoration_buffer`, itself only called on a real client *commit*, not on every resize step) are sampled in `udev/render.rs`/`winit/render.rs` via a `src` crop rectangle sized from this same function's return value. Making this function return the *live* drag target while the underlying bitmap was still sized for the *last commit* means that crop can exceed the bitmap's real stored dimensions - `MemoryRenderBufferRenderElement::from_buffer` (smithay) does not validate `src` against the texture's real size, so an oversized crop is an out-of-bounds texture sample (stretched/repeated/garbage pixels, not a clean error), not just a stale-lag cosmetic issue. Almost shipped a worse bug in place of the one being fixed; caught by tracing the actual downstream consumers before installing, not by testing.
+
+`effective_frame_of` is back to its original, unconditional behavior (safe, internally consistent, but still one-or-more-frames-stale during a fast resize). The audit's own recommendation, not yet done: fix this at the *source* - have `redraw_decoration_buffer` rebuild on every `update_resize` step (not just on commit) so the bitmap itself never falls behind what the live frame asks for - rather than patching the render-time read again. Real, bounded scope (titlebar re-rasterization involves font glyph rendering per character, so calling this on every pointer-motion tick during a fast drag needs its own cost check, possibly a throttle), not attempted this session given the demonstrated risk of a hasty fix in this exact area.
+
+Same-audit related finding, lower priority: the shadow bitmap has the identical commit-vs-live-position gap (`shadow_rect(frame)`'s position is live, the shadow bitmap's own size is commit-gated) - but shadow is pushed with `src: None`, which smithay's own `from_buffer` resolves to the buffer's *real* native size rather than a crop, so this one is NOT at risk of out-of-bounds sampling, only the same soft cosmetic detachment the border/titlebar bug had before the corruption risk was found. Same eventual fix (rebuild on every resize step) would close this too.
+
+## Real bug, reported by a peer session (aegis), not yet root-caused: `srd clients`'s own `focused` field goes stale after a `zwlr_foreign_toplevel_handle_v1.activate`-driven focus change (2026-08-24)
+
+Found building aegis's dock primitive against the real protocol (confirmed otherwise working correctly: initial-existing-window replay and activate/close all behave right). Repro, on nested `srdwm --wayland` with two alacritty windows: calling `activate` on the non-focused one correctly flips that window's own `activated` state in the `zwlr_foreign_toplevel_handle_v1` state event sent back (both windows' flags update, in the right direction) - but `srd clients`, queried immediately after and again a few seconds later (ruled out as a race), keeps reporting the *other* (previously-focused) window as `focused: true`. Two different "what's focused" views disagreeing: whatever `send_state`/`focused_id()` uses for the protocol feedback (correct) and whatever `srd clients` reads (stale, specifically after an activate-driven change - not checked yet whether a mouse/keyboard-driven focus change has the same gap).
+
+Not yet root-caused on this side: `foreign_toplevel.rs`'s `Activate` handler calls the same `focus_window(state, id)` every other focus path uses (mouse click, keybinding), and `crates/platform/src/ipc.rs`'s `"clients"` request handler calls `client_snapshot(wm)` fresh on every query (no caching) which reads `wm.focused_id()` directly - both look correct in isolation from a first read, so the actual disagreement is somewhere less obvious (worth checking whether `WindowManager::focus_window` itself has a guard that no-ops for this case, or whether the winit/nested backend specifically has its own focus-sync gap the udev backend doesn't - the peer's repro was on nested `srdwm --wayland` specifically). Not blocking aegis (protocol-level behavior is correct, which is what actually matters for a dock), but a real gap for any other tooling reading `srd clients` to know what's focused.
+
+## Real bug, root-caused and fixed: a straight vertical border line poked out of every decorated window's own rounded corners, on both the udev and winit backends (2026-08-24)
+
+Reported live, insistently, over several rounds: "the vertical border lines are protruding out" / "it's drawing onto windows." Every earlier check this session (raw pixel sampling, visual crops, multiple apps, multiple radii up to a deliberately oversized `30` live test) had been looking at the top/bottom border strip's own curve in isolation and finding it genuinely correct - which was true, but beside the point: the actual defect was a *second*, separate element bleeding through the *first* one's own correctly-cut transparent region.
+
+Root cause: the left/right border strips (`decoration::border_strips`'s `strips[2]`/`strips[3]`) are plain flat rectangles with no rounded-corner awareness of their own, and started at the window's nominal `geometry.y` unconditionally. But the top/bottom strip's own curve (`border_top_visible_rows`/`border_bottom_visible_rows`) extends *into* that exact region - by `corner_radius - border_width` rows - whenever the radius exceeds the border's own thickness, which is the common case (12+ vs 4 at this theme's defaults, worse at a manually-bumped `30`). The top/bottom strip is pushed first (topmost, per this codebase's own "earlier-pushed = topmost" convention) specifically so its curve's transparent cutout shows through to whatever's behind - but the side strips sit *underneath* it in the exact same region, still filled solid, with nothing about the top/bottom strip's own transparency doing anything to hide a *different* element sitting behind it. Confirmed via raw pixel sampling at the fixed x of the line: identical, fully-opaque border colour to the curve itself (`(187, 154, 247)` both places), starting right at the window's nominal top edge and running in a straight line in parallel with the real curve rather than being replaced by it.
+
+A pre-existing comment at both call sites (`udev/render.rs` and `winit/render.rs`) asserted the opposite - "sit entirely outside geometry... no titlebar-style overlap... push order doesn't matter for these" - which was the actual reason this was never caught by reasoning about the code, only by an insistent live report and finally looking at raw pixels around the seam specifically rather than just "does the curve itself look right." Both comments corrected in place.
+
+Fixed on both backends: the side strips are now cropped by the same `extra = corner_radius.max(border_width) - border_width` amount at both their own top and bottom before fragment-splitting/rendering, so they only ever draw in the flat-edge middle region the top/bottom strip's own curve has finished resolving by. Full test suite green (190 core / 105 wayland / 10 x11, unchanged); built and installed, needs a restart to confirm live.
+
+## Architecture change: udev/Pixman rounded corners now mask the whole composited window, not one guessed-at subsurface (2026-08-23)
+
+Direct follow-on to the corner/border investigation above and the Firefox-titlebar regression it caused: asked outright why this codebase wasn't doing what other real compositors (niri, cosmic-comp) do. Answer, and the actual fix: those compositors round corners with a GPU fragment shader applied to the *whole already-composited window texture* - it never needs to know which subsurface holds "the real content", because by the time the shader runs there's only one flattened texture left. This backend's old approach (`rounded_corners_pixman::resolve_content_surface`) instead tried to *identify* one subsurface as the real content and mask that client buffer directly, skipping everything else in the tree - cheaper, but structurally wrong the moment a client (Firefox) paints real, visible chrome on a *different* surface than the one being masked.
+
+Rebuilt to match the shader-based approach's own shape instead: `rounded_corners_pixman::masked_content_buffer` now renders the window's entire surface tree (root plus every subsurface - exactly what the unmasked fallback already draws) into a private off-screen Pixman buffer (`PixmanRenderer`'s own `Offscreen`/`Bind<Image>` impls, the same `create_buffer`/`bind`/fresh-`OutputDamageTracker`/`copy_framebuffer`/`map_texture` pipeline `udev/capture.rs`'s workspace-thumbnail capture already uses), reads that back as plain bytes, and punches the four rounded corners into *that* composited result. Whatever the ordinary unmasked path can already draw, this can now mask - no more subsurface-count/format/transform restrictions (`Argb8888`/`Xrgb8888`-only, dmabuf needing its own read path, `Transform::Normal`-only), since none of that per-client-buffer machinery exists anymore. Deleted entirely: `resolve_content_surface`, the old `masked_content_buffer`'s shm/dmabuf split, `mask_and_repack`, `mask_dmabuf_content`, `force_opaque` - the whole "which surface is real content" question this session spent several rounds chasing bugs in.
+
+Cost: a full extra off-screen render pass per real content change (more expensive per rebuild than the old raw-memory-copy approach), still gated by the same `CompState::content_epoch` cache, so an idle window costs nothing extra per frame. `elements::rounded_content_buffer`'s cache key grew to include the render `loc`/`size` alongside `epoch`/`radius`, since those now also have to match for a cached mask to still be valid (a resize invalidates it, same as everything else keyed off geometry in this codebase). Full test suite green (190 core / 105 wayland - one fewer than before, `force_opaque`'s own now-deleted test); built and installed, needs a restart to confirm live. Should fix rounded corners uniformly for every window this backend draws, not just the specific Firefox/tmux cases already screenshotted during the investigation.
+
+## Real bug, reported by a peer session (aegis), root-caused and fixed: the X11 backend never read `_NET_WM_STRUT`/`_NET_WM_STRUT_PARTIAL`, so a dock/bar never shrank the usable monitor area (2026-08-23)
+
+Found and verified live by the `aegis-75` session building its own X11-backend bar (override-redirect window + EWMH struts, mirroring its Wayland layer-shell client): on an isolated `Xvfb :10` + `srdwm --x11`, a client mapped an override-redirect `800x32+0+0` window with `_NET_WM_WINDOW_TYPE_DOCK` and `_NET_WM_STRUT_PARTIAL = 0,0,32,0,0,0,0,0,0,799,0,0` (top=32, spanning x=0..799, confirmed correct via `xprop`) - `srd monitors` reported the same `x:0,y:0,width:800,height:600` usable rect before and after mapping, never shrinking to `y:32,height:568` the way the Wayland backend's layer-shell exclusive-zone handling already does. `grep -rl STRUT crates/x11/src/` found nothing at all -- the feature had simply never been built for this backend.
+
+Fixed with a new `crates/x11/src/platform/struts.rs`: `_NET_WM_STRUT_PARTIAL` is read (falling back to the older, span-free `_NET_WM_STRUT` for a client that only sets that), tracked per-window in a new `X11Platform::struts` map, kept live via `PropertyNotify`, and folded into `monitors()`'s own usable-rect computation the same way the Wayland backends already fold in a layer-shell surface's exclusive zone. Struts are watched via `MapNotify`, not `MapRequest` - a real panel/dock is typically override-redirect specifically to bypass window management, so it never reaches `manage_new_window` at all; `MapNotify` (already arriving, since `SUBSTRUCTURE_NOTIFY` was already selected on root) is the only event that fires for it regardless.
+
+Two real bugs found and fixed only by actually running this, not just reading it (matching this session's own established rule for exactly this class of mistake):
+- The shrink math's first version computed `top`/`bottom` in one combined tuple `let (top, bottom) = (top.min(...), bottom.max(...).max(top))` - the `top` on the right-hand side of the *second* tuple element reads the **pre-clamp** binding (a `let` only shadows once the whole statement finishes), so a strut taller than the monitor clamped `top` correctly but then clamped `bottom` against the wrong, oversized `top`, producing `height: 400` instead of the correct `0` - caught by a test asserting exactly that, not by inspection. Fixed by splitting into four sequential statements, each reading only already-clamped bindings.
+- Live end-to-end verification (see below) initially still showed no shrink even after the math was right and confirmed reading the strut correctly (logged live: `Strut { top: 32, top_end_x: 799, .. }`) - root cause: `_NET_WM_STRUT`-driven `monitors()` re-queries only run on `Event::MonitorAdded`/`MonitorRemoved` (`crates/srdwm/src/main.rs`'s own hotplug handler); nothing about mapping a strut window pushed either event, so the `WindowManager`-cached monitor list `srd monitors` actually reads never refreshed. Fixed by having `track_strut_window`/`update_strut_property`/`forget_strut_window` return whether the reservation actually changed, and firing the same zero-payload `Event::MonitorAdded` sentinel the Wayland backends' own layer-shell exclusive-zone-change handler already uses to force exactly this re-query - confirmed live: `srd monitors` now goes from `y:0,height:600` to `y:32,height:568` the instant a real override-redirect dock (a small custom Xlib client, `_NET_WM_WINDOW_TYPE_DOCK` + `_NET_WM_STRUT_PARTIAL`) maps on an isolated `Xvfb`+`srdwm --x11`, and back to `y:0,height:600` the instant it's killed.
+
+10 x11-crate tests (up from 5), full workspace suite green (190 core / 105 wayland / 10 x11); built and installed.
+
+## New feature: dialog windows show only a Close button, never traffic-light colours (2026-08-23)
+
+Requested live: a dialog shouldn't offer minimize/maximize at all (there is
+nothing to maximize or minimize - it has no independent taskbar presence),
+and shouldn't draw the coloured macOS-style traffic-light dots either,
+since those specifically signal "this is a real, independently
+manageable window" in a way a dialog isn't. `Window` gained an
+`is_dialog: bool` field, detected live via `xdg_toplevel.parent().
+is_some()` (a toplevel with a parent is a dialog by xdg-shell's own
+convention - a genuine "does another window own this" signal, not a
+heuristic on size/title) and set in `redraw_decoration_buffer` right
+before the titlebar buffer is rebuilt. `ResizeEdge::hit_test` and
+`render_titlebar` both take a new trailing `is_dialog` parameter: when
+set, the button cluster is forced to a single `Close` entry
+(`[TitlebarButton::Close; 3]` with `button_count`/`wanted_buttons`
+clamped to `1`) and `traffic_lights` is forced off regardless of the
+configured theme, so a dialog's one button always renders as a plain
+glyph, never a coloured dot. Both the core (`crates/core/src/window.rs`)
+and the render side (`crates/wayland/src/decoration.rs`, later split -
+see below) changed together; 3 new tests lock in that a dialog only ever
+recognizes the Close button, even with a `button_order` override that
+doesn't start with it. Built, tested, installed - not yet confirmed live
+(needs a real parented dialog, e.g. a GTK "Save As" prompt, to open and
+screenshot against).
+
+## New: `srd workspaces`/`srd monitors` now cross-reference which monitor shows which workspace (2026-08-23)
+
+Requested by an AGS peer session for their per-monitor workspace-pill work: `WorkspaceInfo` gained a `monitor: Option<MonitorId>` field (the monitor currently showing that workspace, `None` if it isn't visible anywhere), and `MonitorInfo` gained `active_workspace: usize` (the workspace id currently showing on that monitor) - the same fact from either direction, so a caller can look it up from whichever side (a workspace pill, or a per-monitor picker) it already has in hand. Both derive from the already-existing `WindowManager::workspace_for_monitor`, no new state. In shared mode (`workspace.per_monitor` off, the default) every monitor reports the same `active_workspace` (`current_workspace`), and at most one workspace ever carries a `monitor` value; per-monitor mode can have more than one of each simultaneously. A disabled-but-listed monitor (`MonitorInfo::enabled == false`) reports `active_workspace: 0` - an id that can never be real (workspace ids are 1-based), the same "obviously not a real value" sentinel `id: u32::MAX` already uses for that same entry, since a disabled output shows nothing.
+
+Coupling `WorkspaceInfo` to monitor state means a monitor being added/removed/enabled/disabled now also changes the workspace snapshot (the `monitor` field flips), so `IpcServer::poll` emits a `"workspaces"` event alongside the `"monitors"` one on exactly those changes - correct (a subscriber's workspace-to-monitor mapping did change), but it shifted one existing test's assumption that only a `"monitors"` event would follow a monitor change; fixed by draining the now-expected `"workspaces"` event first rather than weakening the assertion. New dedicated test (`workspaces_and_monitors_agree_on_which_monitor_shows_which_workspace`) locks in both fields' values together. Full workspace test suite green (29 platform-crate tests, up from 28); built and installed, needs a restart.
+
+## Real bug, root-caused and fixed: a decorated window's own top corners showed a square notch inside the border's own curve, because the titlebar band rendered on top of the border strip instead of under it (2026-08-23)
+
+Asked directly "how have you not noticed corners have these weird corner squares" - a zoomed screenshot of `tmux` (an SSD window, srdwm's own titlebar, no client content or masking involved at all) showed exactly that: a clean, correctly-sized purple border curve, with the dark titlebar band's own square corner poking through inside it rather than the two reading as one continuous curve. This is the same symptom an earlier, still-open TODO.md entry above ("curves for only ~border_width rows") already flagged from a different peer's own measurement - now with a clean repro and, this time, a root cause.
+
+By design (`render_border_top`/`border_top_visible_rows`'s own doc comments), the top border strip's buffer is deliberately taller than its nominal `border_width` whenever `corner_radius > border_width` (12 vs 4 by default) - the extra `corner_radius - border_width` rows extend the border element's own draw position *down into the titlebar band's own top rows*, so the one shared circle has room to finish rather than being cut off after only `border_width` rows. For that overlap to read as a single curve, the border element's own colour has to actually paint over whatever the titlebar drew at those same pixels - which only happens if the border pushes to `custom_elements` *before* the titlebar (this codebase's own established convention: earlier-pushed renders on top, confirmed by an identical comment already on the shadow-vs-border ordering nearby). It didn't: the titlebar was pushed first, so the titlebar's own (differently-centred, per `round_top_corners`' `center_row` shift) corner mask ended up on top instead, showing its own smaller curve-then-square shape rather than the border's.
+
+Fixed by splitting the single `if w.border_width > 0 { ... }` block in `udev/render.rs` in two: the top strip's own push now happens *before* the titlebar push (recomputing `strips` there instead of sharing one instance across both - a cheap, pure call, not worth restructuring the control flow to avoid); the bottom/side strips stay after, since they sit outside `geometry` with no such overlap (per their own doc comments, they either rely on content-masking already being transparent there, or never overlap the titlebar/content at all). Full workspace suite green - the existing `border_top_and_titlebar_corners_meet_without_a_seam` unit test still passed throughout, since it only exercises the *bitmap-generation* functions in isolation and has no way to see a compositing/z-order bug at all, which is exactly why this went unnoticed by the test suite despite being wrong on every real decorated window's top corners the whole time. Built and installed, needs a restart.
+
+## Real bug, root-caused and fixed: Chrome's window corners rendered completely square, because its content subsurface isn't at `(0, 0)` the way Firefox's is (2026-08-23)
+
+Asked directly "borders/corners still not perfectly rounded in all windows" - checked live rather than assuming the earlier dmabuf fix (below, 2026-08-21) covered every case: Firefox and srdwm's own titlebar round cleanly, Chrome's all four corners are flatly square. Debug logging for this exact path already existed and was, unexpectedly, already on by default in this session's own launcher (`~/.scripts/sys/session_manager.sh` sets `RUST_LOG=srdwm=debug,srdwm_wayland=debug,warn` unconditionally) - so the live, already-growing session log (`~/.local/state/wm-session-latest.log`) had the answer without needing a restart at all: `resolve_content_surface: child at Point { x: 10, y: 43 }, not (0,0) - giving up unmasked`, repeated for every one of Chrome's own content-mask attempts.
+
+Chrome's real content lives in a single child subsurface, the same GTK4/WebRender pattern Firefox uses - just inset at `(10, 43)` (its own CSD shadow-margin/toolbar offset) rather than sitting flush at the root's origin the way Firefox's does. `resolve_content_surface`'s own `child_location != (0, 0)` guard rejected this outright, unconditionally, even though the offset itself has no bearing on whether *masking* that child's buffer is valid - it only matters for *where the result gets drawn on screen*, a concern the caller already had a mechanism for (`content_offset`) that this code path just wasn't using.
+
+Fixed by removing the `(0, 0)`-only restriction and instead returning the child's own real offset alongside the resolved surface, threaded all the way through `masked_content_buffer` → `elements::rounded_content_buffer` → the `udev/render.rs` call site, which now adds it to the window's already-computed `pos` before placing the masked buffer (`rounded_content_buffers`' cache tuple gained a fourth `(i32, i32)` field to carry it). Firefox's own behaviour is unchanged by construction - its child sits at `(0, 0)`, so the added offset is always `(0, 0)` there too; this is strictly additive, not a rewrite of the working case. Full workspace suite green; built and installed, needs a restart.
+
+## Real bug, root-caused and fixed: `zwp_virtual_keyboard_manager_v1` was never implemented, so every synthetic-keystroke tool (`wtype`, `ydotool type`) silently did nothing (2026-08-23)
+
+Asked directly whether Chrome/Firefox's global menu was "fully supported" - checked the AGS side first (`widget/Bar/components/GlobalMenu/index.tsx`'s own extensive doc comments) rather than assuming: Firefox and Chrome structurally cannot export a *real, live* menu at all - Wayland has no general per-app menu-export protocol, GTK's own legacy mechanism (`appmenu-gtk-module`, X11-property-only) only reaches XWayland GTK3 apps that still build a traditional `GtkMenuBar`, and neither Firefox (no traditional GTK menu bar to begin with) nor Chrome (not a GTK app in the relevant sense) qualifies, confirmed already tested end-to-end by a prior AGS session pass. Not a bug anywhere in this stack - an upstream protocol gap no compositor or panel can route around.
+
+What AGS shows those two instead is a static, hand-written placeholder menu (`StaticMenuButton`), and *that* had a real, fixable bug: every keyboard-shortcut item on it is delivered via `wtype`, which needs `zwp_virtual_keyboard_manager_v1` - confirmed absent from this codebase entirely (no reference anywhere in `crates/wayland/src`). `wtype ""` failed outright (`Compositor does not support the virtual keyboard protocol`), and AGS's own call is fire-and-forget, so the failure was completely invisible - exactly matching an earlier live report, "most options in global menu don't work."
+
+Fixed using smithay 0.7.0's own turnkey `wayland::virtual_keyboard` module (a full protocol implementation, not hand-rolled) - routes a synthetic key straight through the same keyboard-focus/keymap pipeline a real physical key press already goes through, correctly reaching whatever's actually focused and reachable by every other compositor's own equivalent of this same tool. New `CompState::_virtual_keyboard_state` field (not `Option`-gated - injecting a key event has nothing GPU/DRM-specific about it, same reasoning `_appmenu_state` already established), constructed identically on both backends, `delegate_virtual_keyboard_manager!` added alongside the existing `delegate_input_method_manager!`/`delegate_text_input_manager!`. Full workspace suite green; built and installed, needs a restart.
+
+Separately, worth knowing but *not* the same bug: a different, real, already-open issue (`com.canonical.AppMenu.Registrar` owned by AGS instead of srdwm, see the entry below dated 2026-08-21) affects classic Qt/`appmenu-qt5` apps' menu registration, not Chrome/Firefox - those two never go through that registrar at all.
+
+## Real bug, root-caused (the visibility half) and partially fixed: XWayland silently never became ready in a real session, taking `com.canonical.AppMenu.Registrar` down with it (2026-08-21)
+
+A peer session (`dotfiles-04`) reported the classic-Qt appmenu registrar still unowned by srdwm despite their own D-Bus flag fix landing correctly on their side. Checked the obvious place first (is `AppmenuRegistrarState::new()` even running) by grepping the live session's own log for anything mentioning XWayland at all - found *nothing*, across a 300K+-line log: no "XWayland ready," no "XWayland unavailable," no `XwaylandEvent::Error`, nothing. `ps`/`pgrep` confirmed no `Xwayland` process running either. Since `appmenu_registrar` is only ever constructed inside the `XWaylandEvent::Ready` handler (`xwayland.rs`), XWayland never starting at all fully explains the registrar symptom - it isn't a D-Bus flag problem, the code that would even attempt to claim the name never runs.
+
+Narrowed further: a manual, standalone run of the real `Xwayland` binary, and of the `-shm` wrapper `ensure_shm_wrapper_on_path` installs on `PATH` for this exact purpose, both succeeded outside srdwm's own process - ruling out "the binary/wrapper is broken" as the cause. The remaining, most likely explanation: `XWayland::spawn`'s call in `xwayland.rs` passed `Stdio::null()` for both the child's stdout *and* stderr - whatever Xwayland itself would have printed about why it failed (confirmed live, manually, that a real run does print real diagnostic warnings) was being discarded before anyone could ever see it. `/tmp/.X0-lock` existing with srdwm's own pid inside it is *not* itself a bug - confirmed against smithay 0.7.0's own source (`xwayland/x11_sockets.rs`): the lock deliberately records the *compositor's* pid for as long as it holds display `:0`, by design, not the eventual X server's.
+
+Fixed the visibility gap, not (yet, confirmed) the underlying cause: `xwayland.rs::spawn` now redirects Xwayland's stdout/stderr to `$XDG_STATE_HOME/srd/xwayland.log` (appended, not truncated, so a restart doesn't erase the previous run's failure) instead of discarding them. Full test suite green; built and installed, needs a restart - and the *next* time this reproduces, that log file should finally say why, closing this out for real rather than leaving it as an educated guess.
+
+## Real bug, root-caused and fixed: rounded corners curved for only ~`border_width` rows, not the full configured radius (2026-08-23)
+
+Continuation of the investigation below: root-caused via the corner-mask diagnostic logging already in place (`RUST_LOG=debug`, no restart needed) against a real, currently-open Firefox window. The `corner-mask state` log line showed, on every single frame: `decorated=false content_will_be_masked=false border_curve_is_safe=false` - and the `rounded_corners_pixman` debug line directly underneath it explained why: `resolve_content_surface: child Size { w: 1551, h: 790 } smaller than root Size { w: 1571, h: 844 } - giving up unmasked`.
+
+Root cause: `resolve_content_surface` (`crates/wayland/src/rounded_corners_pixman.rs`) rejected a resolved content subsurface whenever it was smaller than its root surface on either axis, on the reasoning (from the function's own pre-existing doc comment) that a too-small child was probably some small decorative overlay rather than the real content. That guard predates this session and was never the target of either of this session's two earlier corner fixes (Firefox's dmabuf buffer type, Chrome's non-`(0, 0)` child offset) - but it silently rejects exactly the same shadow-margin-plus-toolbar inset pattern already confirmed and handled for Chrome (`(10, 43)`): a CSD client's root buffer padded for an invisible drop-shadow margin, with the real, *smaller* content subsurface sitting inset inside it. Firefox hit this specific shape live, permanently, on every frame - not the intermittent screen-edge cosmetic gap the investigation below first assumed, but the direct explanation for `border_curve_is_safe` being unconditionally `false`: `w.decorated || content_will_be_masked` with an undecorated CSD window whose masking can never succeed is `false || false`, which is exactly what routes both `border_top_visible_rows`/`border_bottom_visible_rows` down to their `border_width`-only branch instead of the full `corner_radius` one.
+
+Fixed by removing the size check entirely: the two structural checks already ahead of it (exactly one child subsurface, that child itself childless) are what actually establish "this is the content subsurface", not its size relative to the root - and `child_location` (already returned and already applied by every caller) already carries whatever inset a smaller child has, so nothing about a smaller child was ever unsafe to mask, just wrongly assumed to be. Full test suite green (190 core / 106 wayland tests, unchanged); built and installed, needs a restart to confirm live.
+
+## New: unfocused windows now get a fainter drop shadow, matching real desktop convention (2026-08-21)
+
+Asked directly to continue on borders/corners/shadows/effects and check similar projects' own docs, not just this codebase. `shadow_bitmap` (`crates/wayland/src/decoration.rs`) drew the exact same shadow - same `SHADOW_MAX_ALPHA`, no focus awareness at all - for a focused and an unfocused window alike. Checked two real compositors' own documented behaviour rather than assuming a convention: Hyprland's `decoration:shadow` config exposes `color` and `color_inactive` as two separate, independently configurable values (common real configs set `color_inactive` fully transparent - no shadow at all once a window loses focus); niri's own `layout.shadow.inactive-color` does the same, with niri's own docs stating outright that "by default, a more transparent color is used" for an inactive window's shadow. Two independent, actively-developed compositors agreeing on the same convention is a real pattern, not one project's stylistic choice.
+
+Fixed to match: `shadow_bitmap` takes a `max_alpha: u8` parameter instead of always reading the `SHADOW_MAX_ALPHA` constant directly, and `redraw_decoration_buffer` dims it for an unfocused window the exact same way `effective_border_color` already dims an unfocused window's border colour - reusing the existing, already-user-configurable `theme.border_inactive_dim` factor rather than adding a second, separately-configurable knob for what's really the same underlying question ("how much does losing focus fade this window's own chrome"). New test (`a_lower_max_alpha_produces_a_strictly_fainter_shadow_throughout`) locks in that a dimmed shadow is never darker than the focused one at any pixel. Full test suite green (103 wayland-crate tests, up from 102); built and installed, needs a restart.
+
+## Real bug, root-caused and fixed: rounded corners never actually applied to Firefox's content, because its buffer is dmabuf, not shm (2026-08-21)
+
+The user sent real screenshots of all four corners of a tmux window and a Firefox window: tmux's all rounded cleanly, Firefox's bottom-left and bottom-right were flatly square, no curve at all. Added targeted `debug`-level logging (off by default) at every early-return in the content-masking path and asked for a restart to get real data rather than guess further - confirmed on the very first read: `with_buffer_contents failed (NotManaged)`, repeated for every masking attempt on that window.
+
+Root cause: `masked_content_buffer` (`crates/wayland/src/rounded_corners_pixman.rs`) already correctly resolves Firefox's real content to its child subsurface (a fix from earlier in this session), but then reads that surface's buffer via `smithay::wayland::shm::with_buffer_contents` - an shm-only accessor. Firefox's WebRender content surface renders through GL even on this Pixman-only (CPU, no shader stage) backend - almost certainly software/llvmpipe GL rather than a real GPU, but still exported as a genuine dmabuf the same as any hardware-accelerated client's would be - so the shm-only read rejects it outright, every time, and the corner silently falls back to unrounded rather than the wedge-shaped artifact the fallback exists to avoid.
+
+Fixed by adding a dmabuf read path (`mask_dmabuf_content`), reached only once the shm read has confirmed the buffer genuinely isn't shm. Uses `get_dmabuf`/`Dmabuf::map_plane(DmabufMappingMode::READ)` - the read-mode mirror of the exact `map_plane(..WRITE)` pattern `screencopy.rs`'s `write_dmabuf` already proved works for writing a capture *into* a client's dmabuf, for the opposite direction. Scoped the same way that write path is: single-plane, `Linear`-modifier dmabufs only (what this compositor's own `dmabuf_formats()` ever advertises to a client in the first place, so nothing else should reach a real client's negotiated buffer here anyway). The actual masking math (repack to tight stride, force-opaque for X-format sources, punch the corner holes) was pulled out into a shared `mask_and_repack` helper so the shm and dmabuf paths don't duplicate it.
+
+Diagnostic logging kept at `debug` level (not removed) - same reasoning as the trace-level pointer-telemetry compromise earlier this session: it's the only way to tell exactly which check rejected a future client's content without another live debugging round, and `debug` costs nothing when `RUST_LOG` doesn't ask for it. Full test suite green; built and installed, needs a restart.
+
+## Real bug, root-caused and fixed: every new window opened on the primary monitor, regardless of which monitor the user was actually on (2026-08-21)
+
+Reported live, plainly: "why are all windows only opening in the first monitor." Root cause, `WindowManager::add_window` (`crates/core/src/manager/windows.rs`): the target monitor for a brand new window was resolved via `self.primary_monitor()` unconditionally - not "usually", not "as a fallback", the only path that ever ran, regardless of where the user's focus, workspace, or attention actually was.
+
+Fixed to resolve the target monitor from the *currently focused* window's own monitor first, falling back to primary only when nothing is focused yet (a fresh session's very first window, or every window having just closed) - matches the convention every mainstream desktop already follows (a new window opens where you're working), and needs no new state: `self.focused` already existed for exactly this question. New test (`a_new_window_lands_on_the_focused_windows_monitor_not_always_primary`) locks this in; the existing regression test for a *different* known gap (`a_window_whose_monitor_field_is_stale_is_still_rescued`, about a window placed by a rule keeping a stale `monitor` field) still passes unchanged, since its own scenario - nothing focused yet - is exactly this fix's fallback case. Full test suite green (183 core-crate tests, up from 182); built and installed, needs a restart.
+
+## Investigated, not a bug found: a reported delay before the pointer can reach a second monitor right after startup
+
+Reported alongside the monitor-layout-persistence work above: "it takes a while for me to drag mouse left to monitor since monitor layout prefs aren't loaded [at the] same time." Checked the actual mechanism this would have to go through: `UdevState::bounds()` (pointer-clamp bounding box) is computed fresh from `self.heads` on every single pointer-motion event, not cached anywhere - and `restore_monitor_layout` (see the persistence entry above) already runs before the Wayland socket even binds, so `head.location` should already reflect the *restored* arrangement before any pointer motion could possibly be processed at all. Confirmed via a real session's own log and its persisted `monitor-layout.json`: the heads' logical positions in the log already matched the remembered arrangement, correctly reversed from the plain left-to-right default. Nothing in this path shows an obvious source of a startup delay.
+
+Not closed out, though - this report may predate the layout-persistence fix (same message, adjacent topic, unclear which restart the user was describing), or the real cause may be something this code-only investigation can't see (DRM mode-setting/first-frame timing on the second output specifically, distinct from its *logical* position being correct from frame one - a monitor could be positioned correctly but still show no picture for a moment while its own CRTC comes up, which would look identical to "can't reach it" without actually being a pointer-clamping bug at all). Flagged rather than closed; needs a fresh, timed reproduction attributed to a specific restart to actually pin down.
+
+## New feature: srdwm persists and restores its own monitor layout, instead of relying on a panel (2026-08-21)
+
+Raised directly by the user: monitor knowledge is srdwm's logic and should be settled before any panel spawns, and since this compositor is meant to work with any panel or none, restore logic belongs here too, not assumed to exist somewhere else. Before this, whatever arranged outputs on a restart was whichever panel happened to be running - one peer session (AGS) measured 13.7s between its own startup and its remembered layout actually landing, and that number excludes however long the compositor itself is up and displaying before that panel even launches. Worse than slow: if the panel doesn't run, or loses its own store, the layout was never restored at all.
+
+New `crates/wayland/src/monitor_layout.rs`: a small `{connector_name: {x, y, enabled}}` JSON file at `$XDG_STATE_HOME/srd/monitor-layout.json` (`$SRDWM_STATE_PATH` override, `~/.local/state/srd` fallback - mirrors `srdwm/src/main.rs`'s own `config_dir()` shape). Written atomically (tmp file + rename, same pattern as `udev/capture.rs`'s `write_ppm`) on every live position/enabled change - hooked into `apply_output_position` (covers both `srd dispatch set output position` and a real `wlr-output-management-v1` client's apply request) and `disable_connector_by_name`/`enable_connector_by_name`. Read back and applied in a new `CompState::restore_monitor_layout`, called from `UdevPlatform::connect` **before the Wayland socket is even bound** - not just "early", but literally before any client could possibly connect, so no panel or client ever sees a pre-restore arrangement, not even for one frame. Disables are applied before position restores specifically, since `disable_connector_by_name` ends with its own default-layout `relayout_outputs()` call that would otherwise stomp an already-restored position for a different head.
+
+A connector with no remembered entry (first boot, or a monitor plugged in for the first time) is left exactly where the default left-to-right layout puts it - this only ever narrows toward a remembered position, never invents one for a monitor it's never seen before. Two new tests (pure JSON round-trip, corrupt-file-degrades-not-panics); the actual file I/O and env-var-driven path resolution are deliberately untested, same reasoning `config_dir()` already has no coverage for (parallel test execution can't safely share a mutated process-global env var). Full workspace suite green; built and installed, needs a restart.
+
+The AGS peer session's own `restoreRememberedLayout()` is expected to be retired once this is confirmed live - two things arranging the same outputs was exactly the shape of bug that produced the `border_width` mess earlier this session (also AGS pushing something srdwm should own), and there's no reason to keep that risk around once srdwm's own version exists and works.
+
+## Real bug, root-caused and fixed: `effective_frame_of` mixed logical and physical units, drawing an undecorated window's border detached from its real content (2026-08-21)
+
+The user pushed back, correctly, on an earlier "I checked, no gap" claim in this same session - a real screenshot sent directly showed Firefox's purple border sitting visibly to the east and south of the actual window content, unmistakable at a glance, not something needing pixel-scanning to argue about. My first measurement had sampled the wrong row and missed it; this is the real bug once found properly.
+
+Root cause: `effective_frame_of` (`crates/wayland/src/state/geometry.rs`) reads `dwindow.geometry()` - a client's own `xdg_surface::set_window_geometry`, specified to always carry *logical* points - and uses it directly as this compositor's own *physical* convention, with no conversion. `sync_geometry` (the function that originally *asks* a client to become a given size) already gets this right, converting physical to logical on the way out; `effective_frame_of` (which reads back what the client actually *committed*, per its own doc comment, for border/shadow/occlusion/resize-margin-hit-test purposes) never got the matching conversion on the way back in. Invisible at `scale == 1.0` (logical and physical are numerically identical there), which is every monitor this session had until the auto-scale feature gave one a real non-1.0 value.
+
+Fixed the same way `sync_geometry` does: multiply the client's committed logical size by the window's own monitor scale before building the returned physical `Rect`. Full test suite green; built and installed, needs a restart.
+
+## Real bug, root-caused and fixed: two monitors' *logical* rectangles overlapped whenever one had a non-1.0 scale, even though their *physical* placement was correct (2026-08-21)
+
+Found and precisely measured by a peer session reading straight from GTK (`Gdk.Display.get_monitors()`), independent of anything in this compositor's own logs: `HDMI-A-1` (1920 physical, scale ~0.843, so ~2276 *logical*) reported at logical `(0,0)`, and `eDP-1` (1920 physical, scale 1.0) reported at logical `(1920,0)` - inside `HDMI-A-1`'s own logical extent (`0..2276`), a ~356px logical overlap between two monitors that don't overlap physically at all. Any client asking "which monitor is this point on" in that band gets an ambiguous or wrong answer - among the concrete symptoms this produced on the AGS side: hit-testing resolving to the wrong output, and per-output `grim` captures bleeding pixels from the neighbouring output.
+
+Root cause, in two places that both had the same shape: `bring_up_head` (`crates/wayland/src/udev/drm.rs`) computed a head's own logical x-position as `x_offset / this_head's_own_scale` - correct only for the *first* head in a layout, or when every head shares one scale. For any later head, the *previous* heads' own (possibly different) scales are what actually determine how much logical space they occupy, not this head's own scale - so this consistently mis-placed every head after the first whenever scales differed across monitors. `relayout_outputs` (`crates/wayland/src/udev/outputs.rs`, the hotplug re-layout path) had it worse: it passed the raw *physical* accumulated offset straight into `change_current_state` with no scale conversion at all, unconditionally.
+
+Fixed both to track two separate running offsets - `x_offset` (physical, this compositor's own internal placement convention, unchanged, still what `UdevHead.location`/`Space`/`Monitor` rects use) and a new `logical_x` accumulated by adding each processed head's own *logical* width (`physical_width / that_head's_own_resolved_scale`) as it goes, used only for what's actually advertised to Wayland clients via `change_current_state`. `bring_up_head`'s signature gained a `logical_x: i32` parameter (computed by each caller, not derived internally from `x_offset` alone anymore); both hotplug call sites in `outputs.rs` pass `0` for it since `relayout_outputs` immediately re-derives and applies the real value for every head afterward, same as they already did for the physical offset. Full test suite green; built and installed, needs a restart. Not independently re-verified against GTK/AGS yet - that needs the peer session's own next check once this restart happens.
+
+## Real bug, root-caused, live-measured: a monitor auto-scaled below 1.0 breaks for any client that doesn't speak `wp-fractional-scale-v1` (2026-08-21)
+
+The second monitor came back this session (previously untestable), and the border/window gap the user kept reporting on it turned out to be real and measurable, not fixed by this session's earlier `sync_geometry` scale-conversion work. Reproduced directly: a tiled window on `HDMI-A-1` (auto-scaled to ~0.843 by this session's own PPI-based feature) reported geometry `x=186, width=1442` (physical, this compositor's own convention) - but a precise pixel scan of a real screenshot found the *titlebar* ending around x=1681 (roughly matching the reported edge) while the terminal's actual *content* kept going to x=1930 - content overflowing about 250px past where the frame/border actually is. Exactly the "border far from the edge of the window, see-through gap" the user described, and reproducible on demand by placing any window on that monitor.
+
+Root cause: `sync_geometry` (`crates/wayland/src/state/geometry.rs`) correctly computes a *logical* size to send via `xdg_toplevel::configure` (`physical / scale`) - for `scale=0.843` and `physical=1442`, that's a requested logical size of ~1710. A client that supports `wp-fractional-scale-v1` would render that many logical points at a 0.843 buffer scale, landing back at 1442 real pixels, matching what this compositor's own border/hit-testing expects. A client that *doesn't* - falling back to the legacy integer `wl_output.scale`, which cannot represent a value below 1 at all (protocol-level `uint`, and no real compositor rounds it to anything but the nearest sane integer, effectively `1` here) - renders its buffer at scale 1, meaning its buffer ends up sized directly by the *logical* number, ~1710 pixels, not 1442. The measured overflow (~250px) is in exactly the range that gap implies, once real animation/measurement slop is accounted for.
+
+This is a real architectural tension in the auto-scale-below-1.0 feature this session added earlier (deliberately built and tuned per direct request, to shrink oversized UI on physically-large, lower-density monitors), not a bug isolated to one code path: **any client on such a monitor that doesn't implement fractional-scale, and there's no guarantee every client does, will show this same content/frame mismatch.** `impl FractionalScaleHandler for CompState {}` is the smithay-default no-op handler - not customized, so this isn't a case of the fractional-scale side being half-wired either; the gap is squarely "not every client speaks the protocol this depends on," which srdwm has no way to fix client-side.
+
+Not fixed generically this session - the immediate, concrete mitigation the user asked for and already applied: `srd.monitor.scale("HDMI-A-1", 1.0)` added to `~/.config/srd/init.lua`, overriding the automatic value back to 1.0 for this specific monitor, which sidesteps the whole problem (no scale conversion needed at all when scale is 1.0). Config-only, needs a restart. Worth deciding, not decided here: whether `auto_scale_for` (`crates/core/src/monitor.rs`) should ever be allowed to compute a value below `1.0` at all, given this compatibility gap, or whether it should clamp its floor to `1.0` and only ever scale *up* for genuine HiDPI panels - matching what mainstream desktops (GNOME, KDE) actually ship, which generally treat fractional scaling as a HiDPI (>1.0) feature specifically for this reason, not a way to shrink a large low-density panel. Real trade-off either way: the auto-scale-DOWN feature only ever produces sub-1.0 values (it has no up-scale branch at all), so clamping at 1.0 doesn't refine the feature, it disables it outright - reverting the original "text/UI too big on the physically-larger monitor" complaint this was built to fix. Not something to decide unilaterally; needs the user's own call between the two.
+
+Second-order finding from a peer session verifying the above: `grim`'s own multi-output capture is *itself* affected by the same physical/logical confusion, independent of anything srdwm's compositor code does - capturing two 1920x1080-logical outputs (one at scale 1.0, one at ~0.843) produced a single stitched image sized `3840x1281`, not `3840x2160`(both at scale) or `3840x1080` cleanly, meaning the capture tool's own per-output stitching mixes physical and logical sizing across outputs of different scale. `srd clients`/`srd monitors` report physical throughout (this compositor's own established convention); a screenshot taken across a sub-1.0-scaled output can't be trusted to line up with those numbers pixel-for-pixel without correcting for whatever `grim` itself did - a testing-infrastructure gap on top of the client-rendering one, not fixable from srdwm's side either. One more argument for clamping the floor at 1.0, alongside the client-compatibility one above.
+
+## Real bug, root-caused, not yet fixed: `com.canonical.AppMenu.Registrar` is owned by AGS, not srdwm, despite srdwm's own code deliberately trying to claim it (2026-08-21)
+
+Flagged by a peer session (`dotfiles-04`): `busctl --user list` shows the classic Qt/`appmenu-qt5` global-menu registrar name owned by AGS's own `gjs` process, not srdwm - confirmed live (`OwnerUID` traced to the AGS pid). `AppmenuRegistrarState::new()` (`crates/platform/src/appmenu_registrar.rs`) is genuinely constructed at startup (`xwayland.rs`'s `XWaylandEvent::Ready` handler, alongside `EwmhState::connect`) and its own D-Bus name request sets `replace_existing_names(true)` - and srdwm's log has no warning from the `Err` branch that would fire if the connection/name request failed outright, meaning the `zbus` call chain reports success from srdwm's own side despite not actually owning the name afterward.
+
+Working theory, not yet confirmed against zbus's own source (not available locally to check directly): D-Bus name replacement is opt-in on *both* sides - a second requester's `replace_existing_names`/`DBUS_NAME_FLAG_REPLACE_EXISTING` only actually takes the name away from whoever currently holds it if that first owner *also* registered with `DBUS_NAME_FLAG_ALLOW_REPLACEMENT` set. If AGS's own name request didn't set that flag, srdwm's later replace-attempt would simply not succeed in taking over - and if `zbus`'s builder API doesn't surface "request queued behind an existing, non-replaceable owner" as an `Err`, that would explain both halves of what's observed: no warning logged, and the name still not actually owned.
+
+This plausibly shares a root cause with a separate ordering concern the user raised directly ("monitors etc is srdwm logic, should happen before ags spawns"): srdwm's registrar is only constructed once XWayland reports ready, which happens well after the compositor's core socket is already accepting client connections - if AGS connects and claims the D-Bus name before srdwm's XWayland/registrar startup completes, whichever of AGS's or srdwm's name requests happens to run first wins the name outright, independent of either side's own `replace_existing_names` intent. Not fixed this session - needs confirming the zbus replacement semantics first, and probably belongs together with the broader startup-ordering question (see the next entry) rather than as an isolated D-Bus fix.
+
+## Real bug, root-caused and fixed: centered titlebar text wasn't centered on the window, only on the space left after the buttons (2026-08-21)
+
+Reported live: "the ... font/placement of title text is wrong, not real center" - and measurable, not just a impression. `render_titlebar`'s centering formula (`crates/wayland/src/decoration.rs`) computed the midpoint of `text_start..text_limit`, which is the titlebar width *minus* the button reservation (90px for the usual 3-button, 30px-tall case) - not the midpoint of the titlebar itself. For a 300px-wide titlebar with buttons on the left, that put centered text at x=195, a full 45px right of the window's true center (x=150), a difference obvious at a glance, not a rounding-error-sized nitpick.
+
+Real macOS (the convention this titlebar otherwise follows - traffic-light colours, left-side default) does the opposite: it centers the title on the full window width and lets the traffic-light cluster sit wherever it lands, rather than adjusting the centered point to compensate for it. Fixed to match: the ideal centered position is now computed against the full `width`, then clamped into `text_start..text_limit` only to stop a long title from actually drawing under the buttons - so a short title centers on the true window center, and only a title long enough to reach the button zone gets pushed off that ideal point, same as before.
+
+New test: `centered_title_ignores_the_button_reservation_and_centers_on_the_whole_width`, using a titlebar wide enough to reserve button space and asserting the rendered midpoint lands within a few px of `width / 2`, not the old buggy sub-region's own center. Existing `centered_title_starts_further_right_than_left_aligned` (a no-button fixture, unaffected by this change either way) still passes unchanged. Full workspace suite green (100 wayland-crate tests, up from 99); built and installed, needs a restart.
+
+Separately reported in the same message: "windows like tmux[,] most options in global menu don't work/not real global menu... a lot of windows share this behavior." Checked `srd clients` directly - `global_menu: null` for a plain terminal (no app menu to export, correctly) - so whatever's showing an interactive-looking-but-non-functional menu for those windows is a panel-side (AGS) choice to render a placeholder rather than nothing when the data is null, not something srdwm is misreporting. Flagged to the AGS peer session (`dotfiles-04`) rather than chased here.
+
+## Cleanup: removed the temporary `POS-DIAG`/`CURSOR-DIAG` logging from `input.rs` (2026-08-21)
+
+Both mysteries this pre-existing diagnostic logging (predating this session) existed to chase are now resolved - the `resolved=None` resize-margin question (see the entry above) and, per a peer session's own live measurement, a cursor-icon "no visible effect" report that turned out to be a real UX gap already fixed (`CursorIcon::Pointer` for titlebar buttons, distinguishable from the baseline `Default`), not a logic bug. Left in place, this logging was pure cost: a peer session measured it at 35% of an 8898-line daily session log (2650 `CURSOR-DIAG force:` lines alone), burying real warnings. Removed every `log::warn!("POS-DIAG...")`/`log::warn!("CURSOR-DIAG...")` call and the "Temporary... Remove once resolved" comments around them from `crates/wayland/src/input.rs`, keeping the genuine design-rationale comments that were mixed in with them.
+
+Partial walk-back, same day: the same peer session pointed out that `POS-DIAG motion` was the *only* pointer-position telemetry this compositor exposed to anything outside itself - with it gone entirely, there is no way to answer "where is the pointer right now" at an arbitrary point, only corner-clamping (4 fixed points) or hover feedback (binary, only over a reactive widget). Restored a single, minimal line (`pointer motion pos=... hit=...`, unconditional - not just while over decoration, unlike the original) at `trace` level rather than `warn`: off by default (`RUST_LOG` reaches it the same as any other target here, see `main.rs`'s directive-syntax comment), so it costs nothing in normal use, but the debuggability isn't gone. Everything else removed above stays removed - only this one line came back, and at a level that can't repeat the 35%-of-the-log problem.
+
+One more thing this closes out: a peer session flagged `over_content=false` appearing in every logged `CURSOR-DIAG force:` line as a possible bug (pointer reported as not-over-content when it should have been). It wasn't one - by construction, the one branch where `over_content` is actually `true` (`update_cursor_shape`'s `None if over_content` arm) returns before ever reaching that log statement, most of the time completely silently (no log line at all) when there was nothing to reset. Every line that *did* log `over_content=false` was, definitionally, on a different code path that never had a chance to be `true` in the first place. A diagnostic-structure artifact, not a hit-testing bug - moot now that the logging is gone entirely.
+
+## Root-caused: ydotool's `--absolute` is unusable on this machine; relative motion works, but only correctly paced
+
+Every early synthetic `ydotool` resize/drag test this session silently misfired. Root cause for the absolute-positioning half: `ydotoold`'s virtual input device advertises `EV_REL` only (`/proc/bus/input/devices`: `B: REL=147`, no `B: ABS=` line at all) - `ydotool mousemove --absolute` still accepts absolute coordinates client-side, but with no `EV_ABS` capability on the actual kernel device there is nothing for those coordinates to attach to. `ydotoold --help` lists `-T`/`--touch-on` ("Enable touchscreen (EV_ABS)") as the fix - tried it (via a `~/.config/systemd/user/ydotool.service.d/override.conf` drop-in), and it does not work on this system's installed build (`ydotool 1.0.4-2`, Arch): accepted by argument parsing, no `EV_ABS` bit on the resulting device either way, and passing it bare made the daemon exit immediately with status 2. Reverted the override; not fixable by flag alone on this build. Use relative `mousemove` instead, always.
+
+Relative motion's own reliability comes down to **libinput pointer acceleration applied to synthetic `REL` events** - confirmed by two independent sessions converging on the same mechanism from different data: this session saw an unpaced burst of small steps land way off target (a requested (830,400) landed near (1602,684)); a peer session (`dotfiles-04`) separately measured error growing *with distance*, the actual signature of an acceleration curve, and found that neither pacing nor small step size fixes it on its own - large fast steps overshoot, single-pixel steps undershoot so hard the pointer barely moves. An earlier version of this entry claimed paced ~5px steps land within ~1px "repeatably"; that did not reproduce in the peer's own re-measurement and should not be trusted as a general rule - it happened to work once, for one real resize-drag test (window width 800->705 in `srd clients`, confirmed via ground truth, not by reading a log line), not proven as a formula. The one reliable primitive either session found: a large overshoot (+-3000 or more) reliably corner-clamps the pointer to a screen edge, useful for establishing a known reference point before walking toward an interior target. Treat any precision synthetic-pointer test as needing empirical verification against `srd clients`/`srd monitors` afterward, not as something that can be blindly calibrated in advance.
+
+With that methodology, a real end-to-end resize was finally exercised successfully: walked onto a live window's right resize margin (confirmed via the `POS-DIAG motion ... hit=Resize(Right)` log line), pressed, dragged 100px left in paced 5px steps, released - `srd clients` showed the window's width change from 800 to 705. Resize/drag genuinely works. See the next entry for what this also settled about the previously-open `resolved=None` mystery.
+
+## Real bug, root-caused and fixed: global menu missed any window whose D-Bus registration finished after its one focus-triggered read (2026-08-20)
+
+Reported live as "global menu doesn't show up for some windows" - intermittent, not tied to any one app. Root cause: `EwmhState::read_global_menu` (`crates/wayland/src/xwayland.rs`) only ever ran from `update_net_active_window`, itself only called on a focus *change*. Most toolkits set `_GTK_UNIQUE_BUS_NAME`/the menu-path atom once, shortly after mapping - for an already-focused window (the common case: a freshly launched app almost always opens focused), that registration can finish *after* the one focus-triggered read already ran, leaving `Window.global_menu` stuck at `None` until the user clicked away and back. smithay's own `XwmHandler::property_notify` can't see this either - its `WmWindowProperty` enum (`smithay::xwayland::xwm::surface`) is a closed set (`Title`/`Class`/`Protocols`/`Hints`/`NormalHints`/`TransientFor`/`WindowType`/`MotifHints`/`StartupId`/`Pid`) with no catch-all for an atom it doesn't recognize - confirmed by reading smithay 0.7.0's own `xwm/mod.rs`: `Event::PropertyNotify` is filtered down to that enum via `X11Surface::update_property` before ever reaching our handler, and the global-menu atoms all map to `None` there, so the event is dropped inside smithay, never surfaced to this codebase at all.
+
+Fixed by watching for it directly: `EwmhState` already holds its own independent X11 connection (for writing `_NET_ACTIVE_WINDOW`/`_NET_CLIENT_LIST`), previously write-only. Added `watch_property_changes` (selects `PropertyChangeMask` on a window right after its setup finishes) and `poll_property_events` (drains `PropertyNotify` non-blockingly, matched against the same eight global-menu atoms `read_global_menu` already reads). `CompState::poll_global_menu_properties` applies the result, called once per event-loop tick from `udev/platform.rs`'s main loop, same cadence as the existing `apply_registrar_events` (classic Qt `appmenu-qt5` registrar polling) it now sits next to. Not wired into the nested/winit backend - XWayland itself isn't started there at all (see `xwayland.rs`'s own module doc comment), so there is nothing for this to watch on that backend.
+
+Full workspace test suite green (1264+ tests across all crates, no regressions); built and installed, needs a restart.
+
+## Real bug, root-caused and fixed: any GTK4/libadwaita app not manually listed in `rules.lua` got a second, redundant titlebar (2026-08-20)
+
+`rules.lua` already had `decorated = false` entries for Firefox and Nemo, each with its own doc comment explaining why: both draw their own header bar (`GtkHeaderBar`/an embedded CSD row) unconditionally, regardless of what `xdg-decoration` actually negotiates - confirmed live for both via screenshot, two stacked title rows. That reasoning generalizes to every GNOME app, not just those two, but the fix so far was one hand-written rule per app as each was discovered live - anything not yet added still got srdwm's own server-side titlebar drawn on top of its own CSD row.
+
+Added a real, general fallback instead of only growing the list further: `srdwm_core::window::likely_draws_own_titlebar` treats any `org.gnome.*` app id as CSD-only by default - the GNOME HIG mandates every one of GNOME's own apps embed a header bar, with no exceptions, so the namespace alone is enough to know in advance rather than waiting to catch each one live. Deliberately narrow: left at `org.gnome.*` rather than also guessing at third-party `io.github.*`/other reverse-DNS libadwaita apps, which don't share GNOME's HIG mandate and would misclassify plenty of ordinary SSD apps that happen to use a similar id scheme - those still go through `rules.lua` as before. Wired into both `WindowManager::add_window` (X11 windows, whose `app_id` is already known at creation) and `reapply_rules_if_pending` (native Wayland windows, whose `app_id` usually lands after creation via `set_app_id`) - a rule's own explicit `decorated` action still wins over the heuristic in both places, unchanged.
+
+Full test suite green; built and installed, needs a restart.
+
+## Not a bug, a config mismatch: titlebar button side/alignment differs between srdwm's own windows and Firefox's CSD
+
+Looked real in a live screenshot - srdwm's own titlebar had macOS-style traffic lights on the *left* (red-close, yellow-minimize, green-maximize), title text centered; Firefox's CSD had them on the *right* (yellow-minimize, green-maximize, red-close), left-aligned. First guessed this was a stale pre-restart process, since source defaults (`ThemeConfig::default`: `buttons_left: false`, `title_centered: false`) already match this system's GTK convention (`gsettings get org.gnome.desktop.wm.preferences button-layout` -> `appmenu:minimize,maximize,close`, theme `WhiteSur-Dark`). That guess was wrong - re-checked after a real restart, same result, because the actual cause is `~/.config/srd/themes.lua`'s active preset: `catppuccin_mocha` (a straight port of the old Hyprland/Catppuccin config, applied at the bottom of that file) explicitly sets `title_bar.button_side = "left"` and `text_align = "center"`, overriding the source defaults deliberately. `themes.lua`'s other three presets (`nord`, `nord_light`, `gtk_match`) don't touch `button_side` at all, so any of them would already match Firefox/WhiteSur's convention without any code change - this is a one-line edit in a config file the user owns, not something to silently change on their behalf, since a left-side macOS-style titlebar independent of what GTK apps do may be the intended look. Surfaced to the user rather than assumed either way.
+
+## Real bug, root-caused and fixed: maximize ignored every bar/dock except a top one (2026-08-20)
+
+Reported live, twice, from two different angles that turned out to be
+the same bug: "AGS's dock isn't reappearing" and "parts of the current
+window are hidden, can't see its borders." dotfiles-04 (AGS peer
+session) found it precisely with a real measurement rather than
+guessing: `srd monitors` correctly reports a work area excluding *both*
+a 34px top bar and a 53px bottom dock, but a maximized Firefox window
+came back 1046px tall (screen height minus only the 34px top bar) --
+its own bottom edge and border ending up underneath the dock's surface,
+indistinguishable from the dock not rendering at all.
+
+Root cause: `maximize_geometry_for` (`crates/wayland/src/input.rs`) only
+ever subtracted a **top**-anchored bar's exclusive zone from the
+maximize target - a deliberate earlier design choice (own doc comment:
+"a dock anchored to any other edge is deliberately left alone"), reasoned
+through as "maximize should be able to go past a dock, fullscreen already
+covers wanting the screen entirely." In practice this doesn't match how
+any mainstream desktop actually treats a bottom dock - Windows, macOS
+and GNOME/KDE alike keep a maximized window clear of one - and reads as
+a bug, not a feature, the moment a real dock exists to be covered by it.
+
+Fixed: `maximize_geometry_for` now shrinks for a reservation on *any*
+edge (top, bottom, left, or right), not top only. Fullscreen is
+unaffected - it was never routed through this function and still isn't,
+so it remains the one deliberate "ignore every bar/dock, cover the whole
+screen" option. Full workspace test suite green (no existing test
+coverage for this function - needs real smithay layer-map state with no
+harness available, same limitation as this session's other real-
+renderer-only fixes); built and installed, needs a restart.
+
+## Resolved: resize/drag itself works fine; `resolved=None` on a resize-margin press is expected, not a bug
+
+Previously logged here as an open, unexplained mystery: a button press
+during a resize grab logging `POS-DIAG button-resolve pressed=true
+button=0x110 resolved=None client=None`, read at the time as "the resize
+grab had nothing to attach to and nothing happened." With `ydotool`
+usable again and a proper small-step, correctly-paced synthetic drag
+actually landing where intended (see the `ydotool` entry below), this was
+re-tested directly: pressed down at a confirmed `hit=Resize(Right)` point
+on a real window, dragged 100px, released - the window's width changed
+from 800 to 705 in `srd clients`, a genuine resize, while the *press*
+event still logged `resolved=None client=None` exactly as before.
+
+That's the resolution: `resolved=None` on a press over a resize margin is
+correct, not a failure. A resize margin is compositor-drawn decoration
+space (the border strip), not client surface space - there is no client
+`wl_surface` at that exact point for surface-resolution to find, by
+definition, regardless of whether the resize grab itself is about to
+work. The actual resize path is driven by the hit-test result
+(`hit=Resize(...)`) computed separately, before this logging point, not
+by whether surface-resolution succeeds. The earlier hypothesis (extreme-
+edge off-by-one) was chasing a symptom that was never actually broken.
+`POS-DIAG`/`CURSOR-DIAG` logging can be removed the next time this file
+is touched - kept for this entry's own record, not because anything is
+still open.
+
+## Real bug, root-caused and fixed: `srd capture workspace` wrote near-black or pure-black frames (2026-08-20)
+
+Long-standing report from dotfiles-04 (the AGS peer session), finally
+picked up: a workspace-switcher thumbnail captured via `srd capture
+workspace` came back at ~0.025 mean luminance for the current workspace
+(a real screenshot of the same instant: ~0.51) and *exactly* 0 mean and
+0 variance - literally every pixel pure black - for an inactive
+workspace with no windows on it.
+
+Root cause was exactly what it looked like: `capture_workspace`
+(`crates/wayland/src/udev/capture.rs`) only ever rendered window content,
+by design - its own module doc comment listed "no borders, shadows,
+titlebars, cursor or layer-shell surfaces" as deliberate simplifications,
+reasonable for the small window-switcher-tile decorations in that list
+but not for layer-shell, which is also where the *wallpaper* lives. A
+workspace capture with no windows and no wallpaper is indistinguishable
+from broken, because on a typical desktop the wallpaper is most of the
+frame.
+
+Fixed by rendering the background/bottom layer-shell surfaces too,
+matching `render_udev_frame`'s own real ordering convention (windows on
+top, wallpaper pushed last/bottommost). Required changing `capture_
+workspace`'s element list from the narrow `Vec<WaylandSurfaceRenderElement
+<PixmanRenderer>>` it only needed for window content to the same `Vec<
+crate::elements::OverlayElement<PixmanRenderer>>` the real render path
+already uses, since layer-shell elements aren't representable in the
+narrower type.
+
+Full workspace test suite green; built and installed, needs a restart.
+No new unit tests - same as this session's other real-renderer-only
+fixes, this needs live smithay/DRM state with no test harness available;
+worth a live `srd capture workspace <id> <path>` + `magick ... -format
+"%[fx:mean]" info:` check post-restart to confirm the luminance is back
+in line with a real screenshot, the same measurement dotfiles-04 already
+used to find this in the first place.
+
+## Real bug, root-caused and fixed: VT switch back left the screen black, unrecoverable (2026-08-20)
+
+Reported live: after switching away from srdwm's VT and back, the screen
+stayed black, and no further VT switch in either direction could recover
+it - eventually needing a hard restart. Confirmed **not** a srdwm crash
+(`coredumpctl` shows no srdwm entries ever, the process stays alive
+throughout) - a stuck/wrong DRM state, not a segfault.
+
+Root cause: `register_session_notifier`'s `ActivateSession` handler (VT
+switch back) reasserted every head with `card.set_crtc(head.crtc,
+Some(fb), (0, 0), &[], None)` - an **empty connector list and no mode**.
+That is DRM/KMS's own shape for *disabling* a CRTC, not restoring one;
+`bring_up_head`'s own original call (still correct) passes the real
+connector and mode. The resume path never had access to either - neither
+was stored anywhere per-head - so it was passing "nothing" and calling
+that a reassert.
+
+Fixed: `UdevHead` gained a `mode: DrmMode` field (set once in
+`bring_up_head` from `probe.mode`, alongside the `connector` field that
+already existed but wasn't being reused here either); the resume handler
+now calls `card.set_crtc(head.crtc, Some(fb), (0, 0), &[head.connector],
+Some(head.mode))` - the actual reassert the comment above it already
+claimed to be doing. Full workspace test suite green (no test coverage
+possible for this specific path - real DRM state, no harness); built and
+installed, needs a restart. **Not independently live-verified this
+session** - deliberately did not test a real VT switch to confirm the
+fix, given the user's own report that a failed attempt requires a hard
+restart; ask before testing this specific path live.
+
+## Real bug, root-caused and fixed: window geometry/border misaligned after a cross-monitor move (2026-08-20)
+
+Reported live: dragging a window from one monitor to the other (this
+machine's two outputs have different scales - `eDP-1` at `1.0`, `HDMI-
+A-1` at `~0.84`) leaves its border/decoration visibly detached from its
+real content, and resizing afterward doesn't work.
+
+Two live reproduction attempts (an IPC `dispatch move window <id> right`
+call, which turned out to be a directional tile-swap, not a drag; a
+synthetic `ydotool` titlebar-drag, which never registered as a real drag
+at all) both failed before a root cause was found by reading, not
+reproducing:
+
+`sync_geometry` (`crates/wayland/src/state/geometry.rs`) was sending
+`xdg_toplevel.configure`'s `size` directly from `geom.width`/`geom.
+height` - this compositor's own internal *physical*-pixel tracking (see
+`Platform::monitors()`'s own doc comment on that choice) - with zero
+conversion to the *logical* points `xdg_toplevel.configure` is specified
+to carry. Before this session's own auto-scale feature, every output was
+`1.0`, so physical and logical were numerically identical and the missing
+conversion was invisible.
+
+The reason this specifically shows up on a *move*, not just a resize: an
+ordinary drag never changes `geom.width`/`geom.height` at all, so at
+*first* glance there is nothing to convert - but the window's *logical*
+size (physical divided by scale) genuinely does change the moment it
+crosses onto a differently-scaled monitor, even though physical geometry
+didn't move. Before this fix, `sync_geometry`'s `size_changed` check
+compared physical values, saw no change, and sent no configure at all --
+the client kept rendering its old logical size against the new monitor's
+different scale, while this compositor's own border kept drawing at the
+physical rect it always had. Two things that used to agree (client
+content size, this compositor's own border) stopped agreeing the moment
+scale entered the picture, which is exactly "border far from the window."
+
+Fixed: `sync_geometry` now resolves the window's current monitor's
+`scale` and converts to logical points before anything downstream reads
+`size` - including the throttle/backlog bookkeeping
+(`last_synced_size`/`pending_size_configure`), which needed to move to
+logical too, since what they're compared against (`w.geometry()`, a
+client's own `xdg_surface::set_window_geometry`) is logical by the same
+specification `xdg_toplevel.configure` uses. This has the desired,
+niri/Windows/macOS-convention side effect: a window crossing to a
+different-scale monitor now genuinely gets a fresh configure asking it to
+resize, keeping its true on-screen (physical) footprint consistent across
+the DPI change, rather than silently drifting.
+
+Full workspace test suite green; built and installed, needs a restart.
+**Not independently live-verified this session** - both synthetic
+reproduction attempts failed before the fix, so there is no before/after
+comparison confirming this actually resolves the reported symptom; ask
+the user to check after their next restart rather than treating this as
+confirmed.
+
+## Prior-art research: titlebars, global menus, monitor/scale logic (2026-08-20)
+
+Two comparison passes against real source and real docs - niri, Mutter,
+KWin/Plasma, Hyprland, Awesome, Openbox, GlazeWM, plus macOS's own HIG for
+titlebars, and the same set (minus GlazeWM) for monitor/scale/placement
+logic. Full titlebar/global-menu report published as an artifact
+("Titlebars & Global Menus"); the monitor/sizing pass and open-questions
+follow-up were session-only. Concrete outcomes below; everything else
+(what each project does, sourced per-claim) lives in the artifact and the
+agent transcripts, not duplicated here.
+
+- **Corner-rounding scope validated, not found lacking.** KWin shipped
+  real, current (Plasma 6.5, July 2025) server-side rounded corners using
+  signed distance fields - and its own merge request explicitly states
+  "sub-surface corners are not rounded," with KDE's own developers noting
+  real support would need a *new Wayland protocol* letting a client
+  request its own subsurface rounding, not a compositor-side heuristic.
+  This directly validates srdwm's own narrow-scope limitation (this
+  session's own single-full-covering-child fix, `rounded_corners_pixman.rs
+  ::resolve_content_surface`) as already at the field's current state of
+  the art for a CPU-masking approach, not a gap to close further.
+- **niri's alternative (a per-element GLSL shader clip keyed to window
+  geometry, handling arbitrary subsurface trees with no special-casing)
+  is real and battle-tested**, not experimental - confirmed via niri's
+  own design-principles docs and a live GitHub discussion, with one known
+  minor artifact (niri#3476, a thin blending seam) as its only real flaw.
+  **Not portable to srdwm's real hardware backend**: `PixmanRenderer`
+  (udev/DRM, srdwm's actual production renderer) has no shader stage at
+  all, already established earlier this session - this technique could
+  only ever reach srdwm's separate GLES/winit backend, which is dev-only.
+  Deliberately not pursued this session for this reason, not for lack of
+  merit.
+- **Button-order convergence acted on** - see the button-order feature
+  entry below.
+- **The coordinate-unit bug class this session fixed has a more durable
+  architectural answer than the patch that shipped.** niri never hand-
+  tracks physical output geometry in its own struct at all - every
+  placement computation reads position/size through smithay's own typed
+  `Space<Output>`/`Size<i32, Physical>::to_logical(scale)`, one canonical
+  space, one conversion point. srdwm's own fix this session converted
+  correctly at each of several call sites individually
+  (`Platform::monitors()`, the disabled-output snapshot,
+  `maximize_geometry_for`, `apply_output_position`) rather than removing
+  the redundant hand-tracked physical copy (`UdevHead::location`/`size`)
+  that made each of those call sites necessary to fix separately in the
+  first place. **Not attempted this session** - a real, larger
+  refactor, flagged here for whoever picks up monitor/output code next,
+  not undertaken speculatively on top of an already-large session.
+- **`auto_scale_for`'s below-`1.0` scaling has no precedent** in either
+  real implementation checked (Mutter's original heuristic, niri's own
+  direct port of it) - both cap at scale ≥ 1. Confirmed as a deliberate
+  divergence from convention, made on direct user request earlier this
+  session, not an alignment with how anyone else does it. Worth knowing,
+  not necessarily worth reverting.
+- **Monitor-arrangement persistence across a restart has no solved
+  precedent either** - Hyprland's own community has built third-party
+  tools (`hyprland-monitor-fix`, `HyprDynamicMonitors`) specifically
+  because `hyprctl`-applied changes don't survive a restart there either.
+  srdwm's own already-known gap here isn't unusual for a bare compositor
+  - this class of feature is conventionally a desktop environment's
+  settings daemon's job (GNOME's `monitors.xml`, KDE's `kscreen`), not
+  the compositor's.
+- **KWin's button-layout config is real and more complete than assumed**:
+  `~/.config/kwinrc`'s `[org.kde.kdecoration2]` group's `ButtonsOnLeft`/
+  `ButtonsOnRight`, a 10-letter vocabulary (menu, on-all-desktops, keep-
+  above/below, shade, help, minimize, maximize, close, app-menu) - more
+  than srdwm needs (3 buttons only) but the same underlying idea directly
+  acted on below.
+- **GNOME/Adwaita's own button-layout convention was mischaracterized in
+  the first pass** - `AdwHeaderBar`'s `decoration-layout` property (a
+  real, colon-separated-by-side, comma-separated-by-button string,
+  falling back to the system `gtk-decoration-layout` GSetting) is exactly
+  as configurable as KWin's, not a fixed HIG mandate as first assumed
+  from Mutter's C source alone. The GNOME HIG's own header-bar page has
+  no window-control button conventions at all - confirmed by fetching it
+  directly.
+- **Plasma Global Menu's current maintenance state stayed genuinely
+  inconclusive** even after a real search pass - it ships and is
+  preinstalled in current Plasma 6, but has at least one real, reported
+  breaking regression in the last ~18 months (KDE Discuss). Treated as
+  unresolved either direction, not papered over with a confident guess.
+
+## New feature: `theme.decorations.title_bar.button_order` (2026-08-20)
+
+Direct response to the one finding above with a clear, safely-scoped
+path to action: KWin's `ButtonsOnLeft`/`ButtonsOnRight`, GNOME/Adwaita's
+`decoration-layout`, and Openbox's `titlelayout` all independently
+converged on the same idea - an ordered list of button names, not just a
+side toggle. srdwm's own existing `theme.decorations.title_bar.
+button_side` (a boolean-shaped left/right toggle) had deliberately chosen
+"one config value, not a bespoke per-button scheme" in an earlier
+session, before this comparison existed to inform that choice.
+
+Additive, not a reversal: `button_side` still exists and still means
+what it always did. New `button_order` (a comma-separated
+`"close,minimize,maximize"`-style string, `srdwm_core::window::
+parse_button_order`) optionally overrides the *relative order* of the
+three buttons on whichever side `button_side` already selects. Unset
+(the default) reproduces the exact same two built-in orders as before,
+byte-for-byte - confirmed by every pre-existing button/hit-test test in
+`crates/core/src/window.rs` passing completely unmodified.
+
+`ResizeEdge::hit_test` and `decoration::render_titlebar` both moved from
+two hardcoded three-way matches (one per side) to a shared, ordered
+`[TitlebarButton; 3]` walked by index - the two functions have to stay
+in exact agreement (a button that renders on one side/position but hit-
+tests on a different one is worse than no configurability at all, the
+same trap `buttons_left` itself already had to avoid), so both read the
+same resolved order the same way. 8 new unit tests (`parse_button_order`
+parsing/validation, plus two new hit-test-agreement tests); full 298-test
+workspace suite green; built and installed, needs a restart.
+
+## New feature: subsurface-aware rounded corners on undecorated windows (2026-08-20)
+
+What the user actually asked for, after a real correction to this
+session's own earlier investigation: I'd spent hours chasing Firefox's
+titlebar/button rendering as a srdwm bug before finally checking `~/
+.config/srd/rules.lua` and finding `srd.rule({ class = "firefox" }, {
+decorated = false })`, added deliberately in an earlier session (dated
+2026-08-19, comment explains why: Firefox draws its own titlebar row
+regardless of what srdwm offers, so forcing server-side decoration just
+stacked a second one on top). Firefox's titlebar/buttons are its own GTK
+chrome, not srdwm's - not fixable from this side without reverting that
+rule and reintroducing the double-titlebar bug it exists to prevent.
+
+The one part that genuinely was srdwm's own responsibility: content-
+masking (`general.rounded_corners`) rounding an *undecorated* window's
+own corners. `rounded_corners_pixman.rs::masked_content_buffer`
+deliberately bailed (`return None`, falling back to unrounded rendering)
+the moment a window's surface had any children at all - a real, narrow-
+scope limitation the module's own doc comment already documented, not
+something to guess around: Firefox (and most GTK4/WebRender apps) paints
+its actual content into a *child* subsurface, leaving the root surface
+holding only a blank/background buffer, so masking the root's own buffer
+produced a rounded rectangle of nothing.
+
+Fixed by widening the scope by exactly one level, not by attempting
+general subsurface compositing: new `resolve_content_surface` walks to a
+window's single child subsurface and masks *that* buffer instead, but
+only when the structure matches the one pattern this is safe for --
+exactly one child, positioned at `(0, 0)` relative to its parent, no
+children of its own, and large enough to cover the root's own buffer.
+Anything else (multiple children, an offset child, nested subsurfaces)
+still falls back to unrounded rendering exactly as before - real multi-
+subsurface compositing stays out of scope.
+
+Found and fixed a second, real bug while making sure this actually works
+rather than just compiles: the corner-mask cache invalidates on `CompState
+::content_epoch`, which only ever bumped on a commit to a window's own
+*root* surface (`crates/wayland/src/protocols.rs::commit`) - exactly the
+surface that, for Firefox's structure, almost never repaints, since the
+real content commits land on the child. Left as-is, the masked buffer
+would have rendered once, whatever was on screen at the moment the cache
+first populated, and then frozen - scrolling, page loads, video, would
+never show. Fixed by walking up a committing surface's parent chain (via
+`smithay::wayland::compositor::get_parent`, bounded to 8 hops) to find
+its tracked-window ancestor when the commit lands on a subsurface, and
+bumping that window's `content_epoch` too.
+
+Requires `general.rounded_corners = true` (already on in this machine's
+config) to have any visible effect at all - the feature this extends is
+opt-in by design on this backend, see `WindowManager::rounded_corners_
+enabled`'s own doc comment for the real per-commit CPU cost that's about.
+
+Full workspace test suite green; built and installed, needs a restart.
+No new unit tests - `resolve_content_surface`/the epoch-invalidation fix
+both need real smithay surface state (a live subsurface tree, real
+commits) that this codebase has no test harness for; verified by reading
+the actual call sites this session already established (`rounded_content_
+buffer`'s cache, `render_udev_frame`'s mutually-exclusive masked/unmasked
+branch), not by a live Firefox screenshot - worth doing that
+confirmation once this is actually running.
+
+## Real bug, root-caused and fixed: scaled outputs reported a work area larger than the output itself (2026-08-20)
+
+Found from two directions at once: this session's own live testing
+("Firefox maximized on one monitor also shows partially on the other",
+general visual glitching on the scaled monitor) and, independently,
+dotfiles-09 measuring `srd monitors` directly and finding a non-primary
+output's work area (`width`/`height`) *larger* than its own output size
+(`full_width`/`full_height`) - geometrically impossible for a rect
+that's supposed to be the full rect *shrunk* by a bar's reservation.
+
+Root cause: `layer_map_for_output(...).non_exclusive_zone()` - what a
+bar/dock's reservation is read from - returns a rect in *logical*
+(scale-divided) units, the same as every other layer-shell geometry a
+client reports. `UdevHead::location`/`size`, and everything downstream of
+them (`Platform::monitors()`'s `full`/`maximize` rects, the disabled-
+monitor snapshot in `crates/wayland/src/udev/outputs.rs`, and the top-bar
+shrink in `crate::input::maximize_geometry_for`) are raw *physical*
+pixels straight from the DRM mode, never divided by scale. Adding a
+logical rect to a physical one without converting first silently produced
+nonsense the moment a monitor's scale was anything other than exactly
+`1.0` - which every output was, unconditionally, before this session's
+own auto-scale feature existed. At scale `~0.85`, a 1920-physical-pixel-
+wide head's own logical zone width came back around `2276`: reported as
+this monitor's *usable* width, larger than its own *full* width, and
+large enough to overlap whichever real monitor sat next to it in the
+shared global coordinate space - which is why a window sized/positioned
+against it could visually spill onto the neighboring output at all.
+
+dotfiles-09's own initial theory (primary vs. non-primary) was a
+reasonable read of their one data point, but not the real distinguishing
+factor: their "correct" output (eDP-1) happened to be both primary *and*
+the one auto-scale left at `1.0` (high enough real PPI), masking the bug
+there specifically; their "broken" one (HDMI-A-1) happened to be both
+non-primary *and* the one that actually got scaled down. The fix is keyed
+on scale, not primary status, and applies per-head regardless of which
+one is primary.
+
+Fixed in three places, all with the same "scale the logical value into
+physical pixels before touching a physical rect with it" shape:
+- `crates/wayland/src/udev/platform.rs::monitors()` - the live `usable`
+  rect every `srd monitors` query and every real placement/tiling
+  decision reads.
+- `crates/wayland/src/udev/outputs.rs`'s disabled-output snapshot - same
+  computation, duplicated for the same reason `Platform::monitors()`'s own
+  doc comment already explains.
+- `crate::input::maximize_geometry_for` - a top-anchored bar's exclusive
+  zone shrinks a *physical* maximize-target rect by a *logical* amount
+  from the layer-shell surface's own cached state.
+Not touched: `crates/wayland/src/winit/nested_platform.rs`'s matching
+code has the same shape but is provably inert - that backend is dev-only
+and never gets a non-`1.0` scale from anywhere, so logical and physical
+already coincide there.
+
+Full workspace test suite green; built and installed, needs a restart to
+take effect. This should also fix a related report from dotfiles-09's own
+side: a layer-shell dock not appearing on the second monitor at all --
+its anchoring had nothing sane to resolve against once that monitor's own
+reported work area stopped making geometric sense.
+
+**Follow-up, same session: the same unit mismatch existed one layer up,
+in `srd dispatch set output position`.** dotfiles-09 asked directly,
+before guessing: their arrangement panel chains outputs by the physical
+size `srd monitors` now correctly reports, then writes positions back
+through `set output position` - correct only if that command's own space
+matches. It didn't: `apply_output_position`
+(`crates/wayland/src/output_management.rs`) passed whatever position it
+was given straight to `output.change_current_state`, whose position
+parameter is a real Wayland-protocol value - `wl_output`/`xdg_output`
+always report position to clients in *logical* points, not a choice this
+compositor makes. `srd`'s own IPC contract is physical (matching `full_x`/
+`full_y`), so passing that straight through told every real Wayland
+client the wrong logical position for any output scaled away from `1.0`
+- exactly the "384px dead gap" dotfiles-09 predicted before testing it,
+present since this session's own auto-scale feature landed, at startup
+(`crates/wayland/src/udev/drm.rs::bring_up_head`) as well as on a live
+`set output position` call.
+
+Fixed by converting only at the smithay/protocol boundary, in both
+places: `bring_up_head`'s own initial `change_current_state` call, and
+`apply_output_position` (now documented as taking physical input, with
+the one real `wlr-output-management-v1` client call site in `crates/
+wayland/src/output_management.rs::handle_apply_or_test` converting its
+own genuinely-logical request to physical before calling it). Everything
+this compositor tracks internally (`UdevHead::location`, `entry.location`,
+`srd monitors`' own `x/y/full_x/full_y`) stays physical throughout,
+matching `Platform::monitors()`'s own fix above - only the values hand
+ed to smithay's protocol-facing API get converted, and only right there.
+
+Also added, requested directly alongside the question: `scale` on
+`srdwm_core::monitor::Monitor` and on `MonitorInfo`/the `monitors` event,
+plus an explicit doc comment on `MonitorInfo` itself answering dotfiles-
+09's other question (yes, `x/y/width/height` and `full_*` are the same
+space as each other, and that space is physical) so the next client
+doesn't have to re-derive either answer.
+
+Full test suite green; built and installed, needs a restart.
+
+## Real bug, confirmed, not yet root-caused: Firefox's titlebar corners do not round (2026-08-20)
+
+Found during a live testing pass (screenshots, pixel-level crops) requested
+directly by the user, comparing Firefox against a plain SSD-decorated
+terminal window.
+
+Confirmed facts, in order:
+
+- Firefox's SSD titlebar shows a completely square top-left corner. Tested
+  at both the normal radius (11) and a deliberately large test radius (40,
+  set live via `srd set corner_radius 40` then reverted) - square either
+  way, ruling out "radius too small to see" as an explanation.
+- A tmux terminal window, decorated by the exact same code path
+  (`redraw_decoration_buffer` in `crates/wayland/src/state/lifecycle.rs`
+  is the only call site of `decoration::render_titlebar` in the whole
+  crate), shows a clean, correctly rounded corner at the same radius.
+- Ruled out: stale/cached decoration texture - toggling Firefox's
+  maximize state off and on again (forcing a real geometry change and a
+  fresh `redraw_decoration_buffer` call) did not change the result.
+- Ruled out: `border_curve_is_safe` gating (`crates/wayland/src/udev/
+  render.rs`, `let border_curve_is_safe = w.decorated || content_will_be_
+  masked;`) - Firefox is server-side decorated (confirmed: it renders
+  srdwm's own titlebar band and buttons at all, not its own GTK CSD row),
+  so this evaluates `true` regardless of content-masking, meaning the
+  border strip should draw its full curve either way.
+- Not yet checked: whether the square edge belongs to the titlebar
+  bitmap itself (`render_titlebar`'s own `round_top_corners` call not
+  actually clipping for this window's specific dimensions/`border_width`)
+  or to something else painted on top of an otherwise-correct rounded
+  titlebar in the same region.
+
+Also confirmed, while investigating the above, **not** to be bugs:
+
+- Firefox's titlebar buttons render minimize-maximize-close left to right
+  (yellow-green-red) when right-aligned (`theme.buttons_left = false`,
+  the default) - this is intentional, the Windows/GTK convention
+  documented directly in `crates/core/src/window.rs::hit_test` ("not a
+  mirror of the right-aligned order... which is the Windows/GTK
+  convention... for a reason"). A left-aligned window (`buttons_left =
+  true`) correctly shows the macOS close-minimize-maximize order instead.
+  Click targets match the visual position in both cases.
+- The thin purple/violet line above every titlebar is the configured
+  Catppuccin Mauve `border.active_color` (`cba6f7`) in `~/.config/srd/
+  themes.lua`, not a rendering defect.
+- Firefox's titlebar buttons appearing grey (unfocused color) despite
+  being the actual focused window, seen once before a restart this
+  session - not reproducible after the restart (`srd clients` confirmed
+  `focused: true`, buttons rendered in full color). Most likely a stale-
+  process artifact from a long-running pre-restart binary, not a bug in
+  current code; flag again if it recurs on a fresh process.
+
+## Connector names were wrong (reported by dotfiles-09, real bug, fixed 2026-08-20)
+
+`srd monitors` reported `HDMIA-1` and `EmbeddedDisplayPort-1`. Neither
+name exists anywhere else. The kernel, `ddcutil`, `/sys/class/drm`, and
+any config written for another compositor all say `HDMI-A-1` and `eDP-1`.
+
+Root cause: `probe_connected` (`crates/wayland/src/udev/drm.rs`) built the
+name with `format!("{:?}-{}", info.interface(), info.interface_id())`.
+`{:?}` prints the Rust enum variant name (`HDMIA`, `EmbeddedDisplayPort`),
+not the kernel's connector type string. `drm-rs`'s `Interface::as_str()`
+already returns the correct string, taken directly from the kernel's own
+`drm_connector_enum_list` - the fix replaces `{:?}` with `.as_str()`.
+
+This name is load-bearing, not cosmetic: it is the identifier `srd.
+monitor.split`, `srd.monitor.scale`, `set output position`, and `set
+output enabled` all key on. dotfiles-09 had added a workaround in the AGS
+panel (resolve srd's wrong name against `/sys/class/drm` for display,
+still dispatch with srd's own spelling) - safe to remove now.
+
+## `MonitorInfo.split` field added (requested by dotfiles-09, 2026-08-20)
+
+`srd monitors` and the `monitors` event now mark each split part (from
+`srd.monitor.split`) with `"split": true`. An ordinary output reports
+`"split": false`. `srdwm_core::monitor::Monitor` gained a `split: bool`
+field, set by `crates/wayland/src/udev/platform.rs::monitors()`; `srdwm_
+platform::ipc::monitor_snapshot` copies it into the wire format. 1 new
+IPC test. Requested directly: a display-arrangement UI needs to tell a
+split part apart from a genuinely independent output, so it does not
+offer to move, resize, or extend a physical arrangement onto one.
+
+## Multi-monitor/phone features - plan written, step 1 closed (2026-08-20)
+
+Full plan at `a local scratch directory`, covering the
+three features relayed via the AGS peer session: splitting one physical
+output into multiple logical monitors + per-monitor default layout,
+phone-monitor/VM-viewer workspace (simple window form now, real virtual
+output later), and phone-mode UI (automatic-by-shape + manual toggle).
+Recommended order: (1) per-monitor default layout, (2) core-side logical
+sub-monitor splitting, (3) simple VM-viewer window, (4) phone-mode layout
++ toggle, (5) real coexisting virtual output - deliberately last, deferred
+until a concrete VM/simulator integration target is known.
+
+- [x] **Step 1: `monitor.primary_layout`/`monitor.secondary_layout` wired
+      up for real.** Same dead-config shape as `general.default_layout`'s
+      own siblings - validated/defaulted since the config engine's
+      beginning, never read anywhere. **Deviated from the written plan**:
+      the plan's own Phase-2 validation pass (a Plan agent) found these
+      are flat global keys with no per-connector-name table anywhere in
+      the Lua engine, and recommended extending `srd.rule` with a
+      `monitor` matcher instead of inventing one - but on implementing,
+      wiring the two already-named keys directly turned out to need zero
+      new Lua API surface at all and matches exactly what those keys
+      already promised, so that's what shipped (`WindowManager::primary_
+      layout`/`secondary_layout`, applied by `apply_monitor_layouts` in
+      `crates/core/src/manager/monitors.rs`, called from `set_monitors`).
+      Only takes effect in `workspace.per_monitor` mode (still off by
+      default, still not recommended to turn on yet - AGS's own `active`-
+      flag handling isn't ready, see the per-monitor-workspaces entry
+      below) - in shared mode there is only one workspace, so a primary/
+      secondary split has nothing distinct to apply to and is skipped.
+      Applied on every `set_monitors` call (startup + hotplug), not on
+      every workspace switch, so it doesn't fight a workspace's own
+      manually-set layout every time a monitor switches back to it; a
+      non-primary monitor still showing the same fallback workspace as
+      the primary is skipped too, so `secondary_layout` can't clobber what
+      `primary_layout` just set on that shared workspace before any
+      monitor has actually split off. 3 new unit tests in `crates/core/
+      src/manager/tests.rs`.
+- [x] **Step 2: core-side logical sub-monitor splitting.** `srd.monitor.
+      split(name, parts[, "rows"])` - `WindowManager::monitor_splits`,
+      applied by `crates/wayland/src/udev/platform.rs::monitors()`
+      dividing one real head into N `Monitor` entries via the new pure
+      `srdwm_core::monitor::split_rect` (6 unit tests). Each sub-region
+      gets its own `full_geometry`/`maximize_geometry`, not just
+      `geometry` - the Plan agent's validation pass caught that the
+      naive version would have fullscreened a window across the *entire*
+      physical panel, erasing the split (see the plan file for detail).
+      No new `wl_output` per sub-region in this version, by design --
+      flagged as an accepted limitation in `MonitorSplit`'s own doc
+      comment, not silently under-delivered.
+- [x] **Unplanned, requested mid-session: automatic per-monitor scale.**
+      Before this change, srdwm set every real output to a fixed scale of
+      `1.0`. There was no way to change this. A user reported the problem
+      live: on a physically larger monitor, text and UI looked too big for
+      the amount of space available.
+
+      A first version added a manual `srd.monitor.scale(name, factor)`
+      config call, keyed by connector name. The user asked for less
+      hardcoding: no fixed connector name, and behavior based on the
+      monitor's real properties (their example: different behavior for a
+      27" screen versus a 24" one). The final version replaces the fixed-
+      name approach with an automatic one:
+
+      `srdwm_core::monitor::auto_scale_for` (`crates/core/src/monitor.rs`)
+      reads a monitor's real physical size and resolution from EDID,
+      computes its actual pixel density (PPI), and scales it down when
+      that density falls below a reference value (109 PPI, roughly a 24"
+      1080p or 27" 1440p monitor). It never scales a monitor above `1.0`
+      on its own. 5 unit tests cover the laptop panel (no change), a large
+      1080p monitor (scales down), a small 4K panel (stays at `1.0`, not
+      scaled up), an extreme case (clamps at the `0.5` floor), and a
+      monitor with no EDID physical size (returns `1.0`, since there is
+      nothing real to compute from).
+
+      `srd.monitor.scale(name, factor)` still exists, as an explicit
+      override for one connector. An explicit value always wins over the
+      automatic one. `~/.config/srd/init.lua` documents this with a
+      commented-out example rather than a live call, since the automatic
+      value already covers the reported case.
+
+      `WindowManager::monitor_scales` stores only explicit overrides.
+      `bring_up_head` (`crates/wayland/src/udev/drm.rs`) applies the
+      override if one exists for that connector, or the automatic value
+      otherwise, at startup, hotplug, and re-enable alike. **A scale
+      change needs a restart, or an unplug/replug of that connector, to
+      take effect** - it applies only when a head comes up, not on a
+      plain config reload against an already-running output.
+- [ ] Steps 3-5 (VM-viewer window, phone-mode layout/toggle, real virtual
+      output): not started.
+- [ ] **Persistent monitor state across restarts** - "remember states/
+      preference when reconnecting even after startup", asked alongside
+      the three planned features but tracked separately since it's
+      infrastructure (a state file + load/save), not one of the
+      architectural features the plan above covers. Not started, not yet
+      scoped.
+
+## Closed this session (2026-08-19, a later same-day session than the one that opened most items below)
+
+- **`activate_workspace` IPC command silently did nothing.** Root-caused:
+  `udev/platform.rs`/`winit/platform.rs` unconditionally re-ran the full
+  `focus_window()` (with its own workspace-follow side effect) after *any*
+  IPC mutation, silently reverting the very switch that mutation had just
+  made. Fixed by splitting out `raise_in_space` (z-order only, no
+  workspace-follow) for that re-sync path - see `crate::input::
+  raise_in_space`'s own doc comment. Confirmed fixed independently by two
+  separate live sessions (this one and the AGS-side peer session, via the
+  `WS-IPC-DIAG` log line - kept in place, still useful).
+- **Corner-seam fix, verified live.** Pixel-sampled a real `grim`
+  screenshot; the titlebar/border-top seam is a continuous curve, no
+  stepped notch.
+- **Firefox click-accuracy bug - found a *real*, different bug than the
+  one "fixed" before.** The prior `content_offset` fix in `input.rs`'s
+  `refresh_pointer_focus` double-applied an offset `sync_geometry`'s own
+  `map_element` call had already baked into `Space`'s tracked `loc` -
+  confirmed against `sync_geometry`'s own doc comment (which spells out
+  the correct formula, `win_relative = pos - loc`) and smithay 0.7.0's
+  real source (`Window::surface_under` hands a toplevel's point through
+  with a hardcoded `(0,0)` offset). Reverted the double-application.
+  **Not yet click-tested live** - `ydotool`'s absolute positioning isn't
+  reliable in this environment (confirmed twice: commanded position and
+  actual landing position disagreed by a non-constant factor), so this is
+  verified by source/contract, not by a live click. If you can get a real
+  physical click tested against it, do.
+- **Corner-radius-vs-border-strip gap - new bug, found and fixed.** Not
+  the same as the seam above: the left/right border strips are flat,
+  curve-blind rectangles (`border_side_render_element`), and when
+  `corner_radius > border_width` (true even at this project's own theme
+  defaults, 6 over 4), the top/bottom strips' own curve didn't have enough
+  buffer height to fully resolve before handing off to those flat strips -
+  leaving a real wedge of bare background between the straight border and
+  the window's own curve. Confirmed via direct pixel sampling of a live
+  screenshot (not eyeballed). Fixed by growing `render_border_top`/
+  `render_border_bottom` to `max(thickness, radius)` tall and letting them
+  draw over the flat strips (they're pushed first in the render list,
+  which is topmost). Also fixed `render_border_bottom`'s own pre-existing
+  `radius + thickness` bug (drew against an oversized, wrong circle -
+  same wrong shape the top-strip seam fix had already rejected for an
+  equivalent reason).
+- **Shadow didn't follow a window's rounded corner.** `shadow_bitmap` used
+  plain Chebyshev (square-ring) distance everywhere, by design (documented
+  as a deliberate cheapness trade-off) - but that means a rounded
+  window's shadow still had a hard square corner, visibly a different
+  shape sitting right next to the window's own curve. Fixed with a real
+  rounded-rectangle distance field in the corner quadrants only (flat
+  edges are unaffected, byte-identical to before); `radius = 0` is also
+  byte-identical to before.
+- **Firefox's own corners weren't rounding.** Not a bug - `general.
+  rounded_corners` (content-corner rounding for undecorated/CSD windows)
+  defaults to *off* specifically on the udev/Pixman backend (real,
+  documented, untested-on-real-hardware CPU cost for constantly
+  repainting content). Turned on in this user's `init.lua`; watch CPU
+  under heavy content (video, scrollback) since this is the first live
+  data point for that cost on real hardware.
+- **Firefox's titlebar looked nothing like every other window's.**
+  Researched rather than guessed: checked how niri negotiates
+  xdg-decoration (`~/reference-wms/niri/src/handlers/xdg_shell.rs`) -
+  offers ServerSide by default, *honors* whatever a client explicitly
+  requests, exactly like srdwm's own `XdgDecorationHandler` already does.
+  GNOME/Mutter is the outlier (never offers server-side, relies on every
+  GTK app sharing one CSD theme) and isn't applicable to a desktop mixing
+  GTK/Electron/terminal apps with no shared toolkit. Root cause was
+  Firefox's own `browser.tabs.inTitlebar` pref defaulting to CSD here -
+  set to `0` in its profile's `user.js` (takes effect on Firefox's next
+  restart, not yet confirmed live), and removed the now-unnecessary
+  `decorated = false` rule for it in `rules.lua`.
+- **Traffic-light titlebar buttons.** srdwm's own SSD titlebar drew plain
+  outline glyphs (X/square/dash) before - nothing like a real traffic
+  light, and nothing like Firefox's own CSD buttons (real macOS-style
+  dots via the WhiteSur GTK theme). Rewrote as filled, anti-aliased dots
+  (red/yellow/green when focused, flat grey when not, matching what
+  WhiteSur already does and what Firefox's own unfocused dots already
+  looked like).
+- **Switching workspace didn't move keyboard focus.** `switch_workspace`
+  only ever touched `current_workspace`, never `self.focused` - switching
+  to a workspace with an open window left that window unfocused while
+  whatever was focused *before* the switch (now invisible) kept receiving
+  real keystrokes. Fixed: switching now focuses the topmost window on the
+  destination workspace if the currently-focused one isn't there, or
+  clears focus if the workspace is empty. Guarded so it doesn't fight
+  `focus_window`'s own workspace-follow call into this same function.
+- **Workspace ids are 1-based, matching Hyprland's own convention and the
+  display name** (`workspace.names`, `apply_workspace_count`) - checked
+  AGS's own niri and Hyprland integrations before choosing this: neither
+  needs translation math the way srdwm's old 0-based scheme forced onto
+  `lib/srdwm.ts`. Rolling this out needs `crates/config`'s shipped
+  default, this user's `~/.config/srd/keybindings.lua`/`rules.lua`, and
+  AGS's `lib/srdwm.ts`/`service/wsPreview.ts` to all agree with core at
+  the same time - they can't update atomically with one srdwm restart, so
+  whichever side is running the *other* scheme during that window visibly
+  misbehaves (this was hit live: AGS's Overview picked up a phantom 7th
+  workspace slot during a brief skew). `~/.config/srd/rules.lua` also had
+  two stale 0-based workspace assignments (Firefox pinned to workspace 0,
+  which no longer exists at all; Discord/Spotify off by one) - fixed, and
+  the already-open windows they'd misplaced were moved to the right
+  workspace live.
+- **Dead config key: `general.border_width`.** Validated and defaulted
+  but never actually read anywhere - the real, working key is `theme.
+  decorations.border.width` (already correctly documented as such in
+  `docs/DEFAULTS.md`, which is how this was found). Removed the dead
+  key entirely from `crates/config`, the shipped default `init.lua`, and
+  this user's own `init.lua`.
+- **Poll-loop CPU throttle, re-measured.** ~15.4% of one core at idle
+  (instantaneous `/proc/<pid>/stat` delta, not the time-averaged `ps`
+  figure), down from the ~21-30% baseline documented for the pre-throttle
+  build. Real improvement, though not measured under identical idle
+  conditions (a running desktop, not a controlled bench), so treat as
+  directional rather than exact.
+- **Hover-state highlighting for titlebar buttons.** `CompState::
+  hovered_titlebar_button` now tracks which button (if any) is hovered,
+  set from `handle_pointer_position`'s own `hit_test` result and fed into
+  `DecorationSignature` so a hover change is a real cache-invalidating
+  event, not silently absorbed. `render_titlebar` brightens whichever
+  button is hovered (`decoration::brighten`, blends toward white) - close
+  gets "red on hover" for free from this same mechanism, since it's
+  already red at rest (focused); no special-cased hover colour was
+  needed. Not yet confirmed live (built and installed, no restart since).
+
+## Closed this session (2026-08-20)
+
+- **Titlebar cursor didn't change shape over the buttons.** `update_cursor_shape`
+  had no case for a titlebar-button hit at all - fell through to whatever the
+  surface underneath happened to want. Added a `CursorIcon::Pointer` case
+  specifically for Close/Minimize/Maximize hits.
+- **Titlebar text alignment/colour, config-driven.** `theme.decorations.
+  title_bar.text_align` (`"left"` default, `"center"` available) and the
+  existing focused/unfocused foreground colours (now grey by default in this
+  user's own theme preset) - wired through `ThemeConfig::title_centered`.
+- **Titlebar button side, config-driven.** `theme.decorations.title_bar.
+  button_side` (`"right"` default matches Windows/GTK ordering
+  minimize/maximize/close; `"left"` switches to macOS ordering close/
+  minimize/maximize) - threaded through both the renderer
+  (`button_box`/`BUTTON_MARGIN_LEFT`, bigger dots when left) and
+  `ResizeEdge::hit_test` (which corner gets resize-vs-button priority flips
+  to match), so the clickable zones and the drawn positions can't drift
+  apart.
+- **Animated glyph-reveal on titlebar-button hover, config-driven.**
+  `theme.decorations.title_bar.button_glyph`: `"hover"` (default - classic
+  macOS, glyph fades in from the button dot's own colour over 200ms
+  ease-out-cubic, chosen after comparing against real extracted libadwaita
+  CSS which does the opposite) or `"always"` (modern GNOME/Adwaita
+  convention, glyph always visible, left available and documented rather
+  than deleted per usual "comment out the alternative" convention here).
+  Ticked every frame via `tick_hover_glyph_animation` (only while a hover
+  animation is actually in flight and the config isn't already `"always"`,
+  so this costs nothing at rest).
+- **Multi-monitor drag couldn't cross onto a second screen at all.**
+  Root-caused: `update_drag` clamped to the *starting* monitor's bounds,
+  looked up once at drag-start and never revisited as the drag moved - so
+  a window could never be dragged past its own starting monitor's edge no
+  matter how far or fast the pointer moved, even with a second monitor
+  fully up and working at the compositor/DRM level. Reported live with a
+  real second monitor connected. Fixed with a new `all_monitors_bounds()`
+  (the union of every registered monitor's `full_geometry`) - see that
+  function's own doc comment in `crates/core/src/manager/monitors.rs`.
+- **Same drag also left `w.monitor` stale after crossing screens.**
+  `end_drag`'s snap-zone check used whatever `w.monitor` was set to at
+  drag-*start*, so a window actually now sitting on monitor 2 still had
+  its snap zones checked against monitor 1. Fixed by recomputing
+  `w.monitor` from the window's real post-drag geometry before the snap
+  check, in `crates/core/src/manager/dragresize.rs::end_drag` - the same
+  class of staleness `set_monitors`' own doc comment already documented
+  for the hotplug-rehoming case.
+- Full workspace test suite (284 tests across every crate) still green
+  with both of the above in place; installed via `cargo install --path
+  crates/srdwm --force` (no restart of the live process - not asked for).
+
+## Closed this session (2026-08-20, continued) - corner-mask alpha bug
+
+- **Undecorated-window content-mask corner fix, real bug found and fixed.**
+  Reported live as a solid grey wedge poking past the rounded-corner curve
+  on a real, running Firefox window (`decorated = false`), confirmed via a
+  zoomed `grim` crop, not eyeballed. Root cause, confirmed by reading
+  `crates/wayland/src/rounded_corners_pixman.rs::masked_content_buffer`:
+  the function accepts both `Argb8888` and `Xrgb8888` source buffers, but
+  always hands the result to `MemoryRenderBuffer` labelled `Argb8888`
+  (real, renderer-respected alpha) regardless of which the source actually
+  was. `Xrgb8888`'s fourth byte is the wire format's *unused* channel - no
+  producer is required to zero or otherwise canonicalize it - so whatever
+  a client (Firefox, live) happened to leave there became real, visible
+  transparency the instant the whole buffer got relabelled `Argb8888`,
+  anywhere in the window, not just the corner boxes the mask function
+  intentionally touches. Fixed with a new `force_opaque` step (byte 3 of
+  every pixel forced to `0xff`) run over `Xrgb8888` sources before the
+  corner mask itself runs. New unit test
+  (`force_opaque_overwrites_garbage_alpha_without_touching_colour`); full
+  285-test workspace suite green; built and installed.
+
+## macOS titlebar/corner/shadow proportions - partially applied, partially reverted per direct feedback
+
+Sourced from independent developer references, not guessed - Apple
+doesn't publish exact pixel specs and the real macOS screenshots this
+needed couldn't be fetched as savable binaries. Full notes and the live
+comparison screenshot saved to `a local scratch directory
+notes.md` and `a local scratch directory`.
+
+- [x] Corner radius: `theme.decorations.border.radius` default (and this
+      user's own theme presets) changed `6 → 11` (0.2 → 0.36 ratio,
+      matching real macOS's ~10pt/28pt), across `ThemeConfig::
+      default_corner_radius`, `crates/srdwm/src/main.rs`'s shipped
+      fallback, and `~/.config/srd/themes.lua`'s three presets.
+- [x] Left-side (`buttons_left`) button size: `BUTTON_MARGIN_LEFT` `0.18 →
+      0.25`, landing the macOS-authentic left-aligned layout on a true 0.5
+      diameter ratio. Right-aligned `BUTTON_MARGIN` deliberately left
+      untouched at `0.32` - it was never meant to mimic macOS, and
+      changing it would have undone the user's own earlier explicit
+      "bigger on the left" request.
+- [ ] **Reverted**: group hover-reveal (all three traffic-light buttons
+      brightening/revealing together, matching real macOS's own cluster
+      behaviour) was implemented, then explicitly reverted per direct
+      user feedback - "hover effect should apply to one at a time" is
+      this project's own convention here, despite real macOS itself doing
+      it differently. Back to per-button hover
+      (`hovering_the_close_button_brightens_only_that_dot`).
+- [ ] **Still open, reported live after the above landed**: title text
+      still not centred, button colours "not correct", decorations "far
+      apart and small". Root cause found separately: `~/.config/srd/
+      themes.lua`'s active preset never actually had `text_align`/
+      `button_side`/`button_glyph` fields at all (this session's earlier
+      claim of having set them was wrong/lost) and `foreground_focused`
+      was still the original purple, not the grey requested much earlier
+      - so the compositor had been running on `text_align="left"`,
+      `button_side="right"` (the small, unrevised margin), and the wrong
+      colour this whole time. Added `text_align="center"`,
+      `button_side="left"`, `button_glyph="hover"`,
+      `foreground_focused="#a6adc8"` to the live preset. **Not yet
+      confirmed live** - needs the pending restart plus real before/after
+      screenshots, not just a config-file read, given the last claim of
+      "done" here turned out to be wrong.
+- [ ] Shadow reads smaller/harder than real macOS's soft, wide shadow
+      (`SHADOW_SIZE=12px`, linear falloff) - qualitative only, no hard
+      reference number was retrievable, not yet touched.
+- Colours (aside from the grey-text miss above) and left-side button
+  ordering (close/minimize/maximize) already match real macOS correctly,
+  confirmed - no action needed there.
+
+**Module-organization survey vs. niri/mutter** (read-only, no code
+changed): srdwm's already-split files (`state/mod.rs` + `lifecycle.rs`/
+`geometry.rs`/`layers.rs`, the whole `udev/` split, `manager/mod.rs` +
+its own already-split files) are all *smaller and more modular* than
+niri's own real-world equivalents (niri's `niri.rs` alone is 6569 lines;
+its `backend/tty.rs` is bigger than srdwm's entire `udev/` directory
+combined) - no action needed on any of that, it's already ahead of the
+reference project it's modeled on. Concrete remaining splits, each
+modeled directly on a niri module boundary that already exists there:
+- [x] `crates/wayland/src/decoration.rs` (2172 lines) → split into
+      `decoration/{border,buttons,color,corners,font,shadow,titlebar}.rs`
+      plus `decoration/tests.rs`, matching niri's own `render_helpers/`
+      (one file per render-element concern); the root file now only holds
+      the module doc comment, the `mod`/`pub use` wiring, and the two
+      standalone popup renderers (`render_context_menu`/
+      `render_snap_flyout`) that don't belong to any single submodule.
+      198 root lines left, down from 2172. Verified zero behavior/coverage
+      loss: 190 core / 106 wayland tests, identical count before and after
+      (2026-08-23).
+- [x] `crates/wayland/src/protocols.rs` (936 lines) → finished the split;
+      one file per `impl ...Handler for CompState` block under
+      `protocols/`, matching niri's `handlers/` - `buffer.rs` groups
+      `ShmHandler`/`BufferHandler`/`DmabufHandler` and `misc.rs` groups
+      the three purely-default-impl stubs (`OutputHandler`/
+      `TabletSeatHandler`/`FractionalScaleHandler`), since none of those
+      five has more than a handful of lines on its own; every other
+      module is exactly one handler (`compositor`, `xdg_shell`,
+      `xdg_decoration`, `xdg_activation`, `input_method`, `seat`,
+      `layer_shell`, `selection`, `idle`). Root file now only holds the
+      module doc comment, `mod` declarations, and the `delegate_*!` macro
+      list - 58 lines, down from 936. No test module existed in the
+      original file, so nothing to redistribute; 190 core / 106 wayland
+      tests, identical count before and after (2026-08-23).
+- [x] `crates/wayland/src/input.rs` (1305 lines) → finished the split, one
+      file per input-event kind under `input/`: `layers.rs` (layer-shell
+      hit-testing, layer-driven maximize geometry), `focus.rs` (focusing/
+      raising/closing a window - needed by every other kind regardless of
+      what triggered the change), `pointer.rs` (motion, button, cursor
+      shape - the largest, at 683 lines, since it's also where drag/resize
+      *forwarding* lives, the pointer-driven titlebar hit-test dispatch
+      that starts/updates/ends a core drag or resize), `keyboard.rs` (key
+      events, keysym/modifier translation, VT switching), `gestures.rs`
+      (workspace scroll, touchpad swipe). Root file now only holds the
+      module doc comment, `mod` declarations, the two truly-cross-cutting
+      helpers every one of those five needs (`notify_idle_activity`,
+      `DRAG_MODIFIER`), and `last_pointer_pos` - 81 lines, down from 1305.
+      No test module existed in the original file, so nothing to
+      redistribute; 190 core / 106 wayland tests, identical count before
+      and after (2026-08-23). This was the last item on the module-split
+      list - `decoration.rs`, `protocols.rs`, and `input.rs` are all done.
+- Low priority: an `effects/` grouping for `blur.rs`/colour-filter code,
+  matching niri's `render_helpers/{xray,background_effect,
+  framebuffer_effect}.rs` - more a naming/grouping nicety than a real gap,
+  since these already exist as their own top-level files.
+
+## Closed this session (2026-08-20, continued further) - the real second-monitor root cause, a matching video-freeze bug, and per-monitor workspaces
+
+- **Second-monitor blank screen: real root cause found and fixed** (the
+  flip-watchdog from earlier the same session was a real, separate
+  robustness fix, but not this bug). Added a temporary diagnostic
+  (`LAYER-ELEMENTS-DIAG`, since removed) that logged real per-output
+  layer-map state after a live restart: both outputs showed identical,
+  fully-populated `layer_count=3 has_buffer=[true,true,true]` the whole
+  time - proving the surfaces were genuinely mapped, configured, and
+  holding real committed pixel data on both monitors equally. That ruled
+  out both AGS and the render/flip pipeline itself (also separately
+  confirmed alive on the affected head by moving the real cursor there and
+  watching it render correctly). Root cause: `output_layer_elements`
+  (`crates/wayland/src/elements.rs`) added a per-head `origin` (the head's
+  own position in the shared global desktop space, e.g. `(1920, 0)` for a
+  second monitor) to `LayerMap::layer_geometry`'s already-local
+  coordinates - confirmed against smithay 0.7.0's own source that layer
+  geometry carries no global offset at all. That silently shifted every
+  wallpaper/bar surface on any monitor whose `origin` wasn't `(0, 0)` --
+  every monitor except the first, left-to-right - clean off the right
+  edge of that head's own local framebuffer. Fixed by dropping the
+  `origin` parameter entirely; `output_layer_elements` never needed it.
+- **A second, same-family bug: video frozen on a monitor the user wasn't
+  actively using, audio still playing.** Reported live. Root cause:
+  `windows_touched_by_damage` (same file) compared a render pass's own
+  *local* damage rectangles directly against `Space::element_geometry`,
+  which is always *global* - the exact same local/global mismatch as the
+  bug above, one level deeper in the render pipeline. A window relying
+  solely on this path for its frame callbacks (any window not focused or
+  under the pointer - those get an unconditional fallback via a separate,
+  always-on pass) never received one on any monitor but the first, so a
+  video player left playing in the background on a second monitor
+  literally never got permission to submit another frame after its first,
+  while its own audio pipeline (PipeWire, entirely separate) kept running
+  underneath. Fixed the same way: `origin` now threaded through to shift
+  the comparison into a consistent space.
+- **Independent per-monitor workspaces, now a real configurable choice.**
+  Previously hardcoded to a single flat workspace shared by every
+  monitor. `workspace.per_monitor` (default `false`, preserving the
+  original design exactly) switches to Hyprland/niri-style independent
+  per-monitor workspace sets when set `true` - each monitor tracks and
+  displays its own current workspace, switchable via `srd dispatch
+  activate_workspace <id>` without affecting any other monitor (the IPC
+  handler now routes to whichever monitor the focused window is on,
+  falling back to the primary monitor). `WindowManager::
+  switch_workspace_on_monitor`/`workspace_for_monitor`/`is_workspace_
+  visible` are the new entry points; `visible_windows`/`workspace_
+  snapshot` (the `srd workspaces`/AGS wire format) both updated to use
+  them, with zero wire-format change needed - `WorkspaceInfo::active` was
+  already a plain per-workspace bool, so more than one workspace *can*
+  report `active: true` at once in per-monitor mode without needing a
+  schema change on this side. `workspace.count` has no hardcoded ceiling
+  in either mode (floor of 1 only) - purely config-driven, shipped
+  default is 10.
+  - **Do not turn `workspace.per_monitor` on yet.** Confirmed by the AGS
+    peer session against real code, not assumed: `lib/srdwm.ts`'s
+    `#syncWorkspaces` collapses every workspace's own `active` flag into
+    one `focusedWorkspace` (last-active-in-list-order wins), and every
+    widget (bar pills, Overview tiles) highlights by identity against
+    that single value - nothing actually reads the per-workspace
+    `active` bool srdwm now sends correctly. Turning the mode on before
+    that lands would render exactly one pill lit (whichever monitor's
+    workspace sorts last) and the other monitor's real current workspace
+    as merely "occupied" - not a crash, but visibly wrong. The AGS-side
+    fix is small (light a pill from the real per-workspace flag, falling
+    back to the identity check for Hyprland/niri, which have no such
+    flag) and is dotfiles-09's own call/scope, already flagged to their
+    user - not something to fix from this side.
+  - Not yet done: scroll/gesture-based relative workspace switching
+    (`switch_workspace_relative` in `crates/wayland/src/input.rs`) still
+    always targets the single shared `current_workspace`/`switch_
+    workspace`, not whichever monitor the pointer is actually over --
+    inert-ish for a monitor already showing its own independently-switched
+    workspace in per-monitor mode. Scoped out of this pass rather than
+    guessed at; needs "which monitor is the pointer over" plumbed through
+    from the backend-specific pointer state.
+- Full 289-test workspace suite (four new tests for the per-monitor
+  feature specifically) green; built and installed.
+
+## Closed this session (2026-08-20, continued yet further) - italic titlebar font, border/shadow wedge, resize lag, AGS monitor-layout panel backend
+
+- **Titlebar font was italic on this machine, for every window.**
+  `find_ttf_preferring_mono` picked whichever font file's name merely
+  *contained* "mono" first in directory-listing order, with nothing
+  excluding a styled (italic/bold/etc.) variant - live result:
+  `/usr/share/fonts/TTF/JetBrainsMonoNerdFontPropo-Italic.ttf`, confirmed
+  via the `wayland titlebar font:` log line, despite several regular-
+  weight JetBrains Mono files also being installed. Rewritten as
+  `font_rank`/`find_best_font`: ranks every candidate (mono+unstyled beats
+  mono+styled beats non-mono) and keeps scanning until it finds an actual
+  rank-0 match instead of stopping at the first mono-named file regardless
+  of style. Six new unit tests were not written for this specific
+  live-picked-file case (filesystem-dependent), but `font_rank` itself is
+  fully covered.
+- **A real border/shadow rendering bug, found while comparing screenshots
+  as asked: a solid, wrong-coloured wedge cut into an undecorated (CSD)
+  window's corners.** Reported live on a real Firefox window, both top-
+  left and bottom-left corners. Root-caused by elimination, not
+  guessed: toggled `general.rounded_corners` off live (`srd set
+  rounded_corners false`) and the wedge stayed, ruling out the content-
+  mask feature; the wedge's own colour matched `border.active_color`
+  exactly, not Firefox's own chrome colour, ruling out Firefox's own
+  rendering. That left `render_border_top`/`render_border_bottom`'s own
+  "extra" rows (added past `border_width` whenever `corner_radius >
+  border_width`, to give a corner's curve room to resolve) as the only
+  remaining source - correctly designed to overpaint a *decorated*
+  window's titlebar band, which safely absorbs them, but an undecorated
+  window has no such band, so the same colour-filled rows land on its
+  real content instead. Almost certainly always existed, just too subtle
+  to notice at the old default radius (6, a 2px extra) until this
+  session's own real-macOS-proportion fix (radius 11, a 7px extra) made
+  it obvious. Fixed with two new pure, tested functions (`decoration::
+  border_top_visible_rows`/`border_bottom_visible_rows`) that both real
+  backends (`udev/render.rs`, `winit/render.rs`) now call instead of each
+  hand-rolling their own position/crop math - crops to just the nominal
+  `border_width` rows for an undecorated window, skipping the
+  compensating shift too since there's nothing left to shift for. Ten new
+  unit tests.
+  - **Follow-up caught by actually looking at the pixels afterward, not
+    just trusting the fix:** cropping unconditionally whenever
+    `!w.decorated` closed the wedge but cost every such window its own
+    visible corner curve too, even on the (rarer) undecorated window
+    whose content-masking genuinely does succeed - reverting it to a
+    flat square corner instead of the intended rounded one, confirmed on
+    the same real Firefox window this was found on (masking bails for it
+    specifically, `masked_content_buffer`'s subsurface early-out). Fixed
+    on the `udev` backend by computing whether this window's content will
+    actually be masked *this frame* (a cheap cache-hit re-use of the same
+    `rounded_content_buffer` call the content-rendering step already
+    makes later in the same loop iteration, not a second real masking
+    pass) and using that - not the bare `decorated` flag - to decide
+    whether the border's extra rows are safe to show in full. The `winit`
+    (nested/dev-only) backend's masking is GPU-shader-based, not the
+    Pixman CPU path with the subsurface limitation, so it doesn't appear
+    to share this failure mode at all - left on its simpler unconditional
+    crop rather than adding matching complexity to a backend that isn't
+    what's actually running live.
+- **Resizing was "very laggy" - root-caused and fixed, not just
+  reported.** `general.rounded_corners` (content corner-masking) copies a
+  window's *entire* pixel buffer on the CPU on every single commit (see
+  `rounded_corners_pixman`'s own module doc comment, which already
+  predicted this exact cost and is why the feature defaults off) - a
+  resize reflows content on every single frame of the drag, so this was
+  the first real-hardware case that ever paid that cost continuously
+  rather than once per idle-window repaint. Fixed by skipping content
+  masking for specifically whichever window is being interactively
+  resized right now (`WindowManager::resizing_window`, new), not by
+  disabling the feature globally or during any other window's masking --
+  cosmetic, and the one moment its absence is least likely to be noticed
+  (attention is on the dragged edge, not the opposite corner).
+- **AGS's monitor-layout panel backend, built to a precise spec from the
+  AGS peer session rather than guessed.** New CLI: `srd dispatch set
+  output position <name|id> <x> <y>` (the existing `set_output_position`
+  IPC command had no CLI surface at all before this - AGS dispatches via
+  `Gio.Subprocess`/the `srd` binary, not the raw socket). Resolves a
+  monitor `name` server-side when no numeric `id` is given, matching what
+  `srd monitors` itself reports, so a caller that already has the name
+  doesn't need an extra round-trip. Explicitly *not* built this pass, on
+  purpose: real output enable/disable (needs actual DRM-level CRTC power
+  state, not a software flag, to mean what Hyprland's `disable`/niri's
+  `off` mean - too large a change to bolt onto an already-large restart
+  untested) and true multi-display content mirroring (corrected an
+  earlier same-session claim that positioning two outputs at identical
+  coordinates already mirrors content - it doesn't: each window has
+  exactly one `monitor` assignment, so nothing actually duplicates).
+  AGS's own panel self-detects via an `srd --help` regex probe at
+  startup, so landing this needed no further coordination once installed.
+- **`srd subscribe` now emits a `monitors` event on hotplug**, the AGS
+  session's own low-priority ask, so its "display connected" strip can
+  drop a 4-second poll of `srd monitors` (was working around
+  `hypr.connect("monitor-added", ...)` being a dead handler id on any
+  non-Hyprland backend). Fourth independently-diffed event alongside
+  `clients`/`workspaces`/`keyboard_layout`, same `MonitorInfo` shape the
+  one-shot `"monitors"` command already returned (pulled both into one
+  shared `monitor_snapshot` function so they can't drift apart). Two new
+  tests.
+- Full 298-test workspace suite green; both `srdwm` and `srd` (the CLI)
+  built and installed.
+- **Follow-up on the border-curve fix above, caught by actually looking at
+  the pixels afterward rather than trusting the fix as shipped:**
+  cropping unconditionally whenever `!w.decorated` closed the wedge but
+  also flattened the curve on the (rarer) undecorated window whose
+  content-masking genuinely does succeed - confirmed on the same real
+  Firefox window. Fixed on the `udev` backend by computing whether this
+  window's content will actually be masked *this frame* (a cheap
+  cache-hit re-use of the same `rounded_content_buffer` call the
+  content-rendering step already makes later in the same loop, not a
+  second real masking pass) and using that, not the bare `decorated`
+  flag, to decide whether the border's extra rows are safe to show in
+  full. `winit`'s masking is GPU-shader-based and doesn't appear to share
+  this failure mode, so left on its simpler unconditional crop.
+- **A real srdwm bug, not just a client-side trap: `set_output_position`
+  to a negative origin made that output's own region unreachable by the
+  pointer.** Flagged by the AGS peer session after their own monitor-
+  layout panel's "extend left"/"extend above" placed a head at negative
+  x/y and the user immediately hit "clicked it now I can't go to other
+  monitor at all". Root cause: `UdevState::bounds()` computed only the
+  max right/bottom edge across every head, never the minimum x/y, so both
+  pointer-motion paths clamped into a `(0, w) x (0, h)` box regardless of
+  where any head actually sat. Fixed: `bounds()` now returns the real
+  `(min_x, min_y, max_x, max_y)` box; the arithmetic itself pulled into a
+  plain, tested free function (`bounds_of`) since `UdevHead` needs a real
+  DRM handle to construct otherwise. Five new unit tests. AGS's own
+  client-side normalization (always placing the arrangement's own
+  top-left at (0,0)) stays in place as good practice, but is no longer
+  load-bearing for correctness.
+- **A decorated window's titlebar had no top-edge resize zone at all,
+  only the two tiny diagonal corners.** Reported live, exactly: "we can't
+  resize tmux's window from top but we can in Firefox" - true, because
+  an *undecorated* window already had its own (narrower)
+  `UNDECORATED_TOP_RESIZE_MARGIN`, but a decorated one's titlebar band
+  claimed every button-free pixel as `Drag` unconditionally. Fixed with a
+  new `DECORATED_TOP_RESIZE_MARGIN` (reuses `RESIZE_MARGIN` outright --
+  unlike the undecorated case, there's no client content here to avoid
+  stealing a click from, since the whole band is srdwm's own drawn UI).
+  Checked *after* the button x-range tests, not before, so a button
+  sitting within the first few rows of the titlebar (true for all of
+  them) still always wins there - addresses the "account for the
+  buttons... not swallowing" half of the same request directly. Four new
+  tests; two pre-existing tests whose own fixed y-coordinates predated
+  this zone existing at all were updated to probe past it, not deleted.
+- **Resize configure throttling, matching niri.** A background research
+  fork compared srdwm's resize handling against niri's and found a real,
+  concrete gap beyond the already-fixed content-masking cost: `sync_
+  geometry` sent a fresh size-changing `xdg_toplevel.configure` on every
+  single pointer-motion tick of an active resize, with no check on
+  whether the client had caught up to the *previous* one - niri
+  explicitly throttles this (`window/mapped.rs`'s `ConfigureIntent::
+  Throttled`, its own comment: "some clients do not batch size requests,
+  leading to bad behavior with very fast input devices... this throttling
+  also helps interactive resize transactions preserve visual
+  consistency"). Implemented the same idea: a new `pending_size_configure`
+  map tracks a sent-but-not-yet-caught-up-to size per window, checked
+  against the client's real last-committed content size
+  (`w.geometry().size`) before sending another; bounded by a 100ms
+  `CONFIGURE_THROTTLE_TIMEOUT` so a client that never catches up for any
+  reason can't wedge resizing shut, the same self-healing shape as this
+  session's own DRM flip-pending watchdog. Deliberately doesn't touch
+  `redraw_decoration_buffer`'s own cadence - srdwm's border/titlebar
+  still tracks the live requested geometry every frame regardless of
+  whether the client's own content is throttled, so the *decoration*
+  stays visually smooth while backpressure applies only to the client-
+  facing protocol negotiation.
+- Full 306-test workspace suite green (no dedicated unit test for the
+  throttle itself - `sync_geometry` needs a live smithay surface/
+  toplevel to exercise, same testability ceiling as the rest of this
+  file); built, installed.
+- **Monitor enable/disable, the real DRM-level work explicitly requested
+  ("i think we should also be able to disconnect/use only one monitor
+  from there/toggle") after being deliberately scoped out of the earlier
+  monitor-layout batch.** New: `srd dispatch set output enabled
+  <name|id> <true|false>`. Reuses this backend's own existing hotplug
+  removal/bring-up code (`reprobe_outputs`'s two halves, now `pub(crate)`
+  as `disable_connector_by_name`/`enable_connector_by_name`) rather than
+  inventing a new mechanism - disabling genuinely destroys the `wl_
+  output` global, unmaps it, frees its DRM buffers, and rehomes its
+  windows, exactly like a real unplug; enabling re-probes and brings it
+  back up exactly like a real hotplug reconnect, since nothing about the
+  underlying hardware actually changed. A new `UdevState::
+  disabled_connectors` (by name) stops an *unrelated* hotplug event from
+  resurrecting a deliberately-disabled output.
+  - Keyed by connector **name**, not `MonitorId`, throughout the queue/
+    IPC layer (unlike `set_output_position`) - disabling removes the
+    output from `monitors()` entirely, so its id has nothing left to mean
+    by the time a caller wants to re-enable it; the name is the only
+    identifier that survives the round trip. `id` is still accepted on
+    the wire and resolved against the live list, but that only ever works
+    for the *disable* direction (the output is still live when you ask to
+    turn it off) - re-enabling requires the name.
+  - **Not done, deliberately out of scope for this pass:** a disabled
+    output isn't listed anywhere (`MonitorInfo`/the `monitors` subscribe
+    event only ever show *connected and enabled* outputs), so a UI has no
+    way to discover "this output exists but is off" to offer re-enabling
+    it - it has to already know the name from before disabling. Adding
+    an `enabled` field to `MonitorInfo` (and deciding whether disabled
+    outputs should even be listed at all) is a real wire-format change
+    worth coordinating with the AGS side rather than adding unilaterally.
+  - Real DRM hardware operation, tested via source review and the exact
+    same code paths a genuine unplug/hotplug already exercises live this
+    session, but not yet exercised through this *specific* new entry
+    point against real hardware - flagged here rather than claimed done
+    without that test.
+- Full 309-test workspace suite green; both binaries built and installed.
+
+## Open question, not yet acted on: does a glitch report predate these fixes or not?
+
+Reported live, still vague: "it currently glitches out" when moving a
+window between workspaces, plus "cursor glitches out when near
+decorations" and "more... in the extra monitor" - worse on the second
+monitor specifically. Given how many second-monitor-specific rendering
+bugs this session already found and fixed (the layer-element coordinate
+bug, the frame-callback coordinate bug, the border-wedge bug), this may
+already be resolved by fixes already installed and just needs a fresh
+restart + re-check, or may be a genuinely separate, still-open issue --
+undetermined either way pending a live look with everything from this
+session's later fixes actually running, or a screenshot/recording if it
+persists.
+
+## Real bugs, currently open
+
+- [ ] **Dock intermittently slow to appear / unresponsive to clicks** -
+      compositor-side leads (layer-shell hit-testing, stuck pointer
+      grabs, frame-callback starvation) all checked and came up clean.
+      dotfiles peer session has a concrete AGS-side lead
+      (`updateInputRegion` possibly computing a stale/zero region
+      mid-animation) - status unknown as of this entry, ask before
+      assuming it's still open.
+- [ ] **`POS-DIAG` repro not yet pinned down** - a right-click during an
+      active edge-resize drag was seen to never reach pointer-event
+      delivery (only its release did), consistent with one of three
+      "swallow the press" branches in `input.rs` firing unexpectedly, but
+      which one wasn't confirmed before the pattern stopped recurring.
+      Diagnostic logging is in place; needs the exact repro (right-click
+      mid-resize-drag) again to pin down.
+- [ ] **Firefox click-accuracy fix, unverified against a real click** -
+      see "Closed this session" above: fixed and justified from source,
+      but no reliable way to synthesize a precise click in this
+      environment to confirm live. Needs an actual physical click test.
+
+## Explicitly requested, not yet started
+- [ ] **Right-click on bare desktop** - no handler exists at all
+      currently; requested, scope/design never discussed.
+- [ ] **Window-management-policy comparison vs. GlazeWM, Awesome,
+      Openbox, RagnarWM** - all four cloned to `~/reference-wms/` and
+      ready; the *rendering* comparison used niri and mutter (the only
+      two of the six that do their own compositing at all) plus, this
+      session, niri's xdg-decoration negotiation specifically. If the ask
+      is really about layout/rules/keybinding conventions rather than
+      rendering, these four are sitting untouched for that.
+- [ ] **Real per-app window-size memory that survives a restart** -
+      what's built (`remembered_sizes` in `crates/core`) is session-
+      lifetime only, in-memory. Persisting it across a compositor restart
+      would need a real config-file-backed store; deliberately not built
+      speculatively, see that field's own doc comment.
+
+## Render pipeline - researched, ranked, not started
+
+From an earlier niri/mutter comparison fork (full detail in
+`SESSION_HANDOFF.md`, if it still exists by the time you read this):
+
+- [ ] Hardware DRM cursor plane (currently always software-composited) -
+      medium-large; needs real `DrmCompositor` plane scaffolding this
+      backend doesn't have yet.
+- [ ] Direct scanout for fullscreen clients (currently always goes
+      through full Pixman composite) - large, the natural next big
+      structural investment given this whole project's video-performance
+      history, but genuine architectural work, not a tweak.
+- [ ] `wp_linux_dmabuf` feedback (format/modifier negotiation tranches) -
+      low priority until direct scanout exists to negotiate for.
+- [ ] Explicit sync / VRR / HDR - real gaps, ranked below the above three;
+      all need the same `DrmCompositor`-style layer the backend doesn't
+      have.
+
+## Protocol gaps (from `PANEL_SUPPORT_TODO.md`, still genuinely open)
+
+Everything else in that doc is done - these five are the actual
+remainder, none blocking for the desktop-shell use case that doc was
+originally scoped around:
+
+- [ ] `zwlr_virtual_pointer_manager_v1` + `zwp_virtual_keyboard_manager_v1`
+      - needed by `ydotool` and any automated UI testing. Directly
+      relevant now: this session's own attempts to synthesize precise
+      clicks for verification were unreliable specifically because
+      `ydotool` has no protocol path that actually works well here; this
+      protocol pair is the real fix for that, not a nice-to-have.
+- [ ] `zwp_pointer_constraints_v1` + `zwp_relative_pointer_manager_v1` -
+      games (pointer lock/relative motion).
+- [ ] `wp_presentation` - accurate frame timing; low value on a fixed-
+      refresh, always-CPU-composited session (see the render-pipeline
+      section above, item 4).
+- [ ] `wp_single_pixel_buffer_v1`, `xdg_foreign_v2`.
+- [ ] `zwlr_screencopy_manager_v1` fix needs a fresh `grim` retest against
+      the real DRM/udev session (was only verified on the nested winit
+      backend at the time).
+
+## Confirmed-fixed, unverified against a real client (nothing to build, just need the test subject)
+
+- [ ] Classic Qt `appmenu-qt5` global menu - code fixed
+      (`appmenu_registrar`), but `appmenu-qt5` isn't packaged for Arch at
+      all (checked official repos and AUR); no live client to verify
+      against without pulling in much larger KDE integration packages,
+      deliberately not installed without asking first.
+- [ ] KDE Plasma Qt global menu (`_KDE_NET_WM_APPMENU_*` atoms) - same
+      "fixed, no test client available" situation.
+
+## Confirmed not fixable / deliberately out of scope (documented, closed, listed here only for completeness)
+
+- Nemo and most modern GTK3/GTK4 apps' global menu - confirmed via direct
+  D-Bus introspection that there's genuinely nothing on the bus to read;
+  universal across every Wayland compositor, not an srdwm gap.
+- Nemo's own titlebar duplication - unlike Firefox, Nemo draws its own
+  CSD headerbar *unconditionally*, ignoring xdg-decoration negotiation
+  entirely (confirmed live via screenshot). The Firefox-style "fix the
+  client's own preference" approach this session used doesn't apply;
+  `decorated = false` for Nemo (telling srdwm not to draw a second one on
+  top) remains the only real fix.
+- `move_terminal`'s full port - architectural mismatch (srdwm has one
+  flat workspace list shared by every monitor; the Hyprland original
+  assumed per-monitor workspace sets).
+- Per-output enable/disable - real DRM mode-setting, hardware-dependent,
+  not attempted.
+- Multi-GPU - only the primary GPU's connectors are driven; a GPU
+  appearing/disappearing is logged and ignored.
+- A native GUI settings app - never existed even as working code in the
+  legacy C++ project, pure design doc there too; not revisited.
+
+## Source docs, for the full story behind any item above
+
+- `SESSION_HANDOFF.md` - a prior session's own work in full technical
+  depth (ephemeral, meant to get replaced by whichever session writes the
+  next one - check whether it still describes current reality before
+  trusting it).
+- `MISSING.md` (`~/.config/srd/`) - gaps found porting from the user's
+  old Hyprland config, organized by how much each is missed.
+- `PANEL_SUPPORT_TODO.md` - desktop-shell/panel protocol support,
+  originally scoped around getting a GTK4 AGS panel running at all (it
+  now does).
+- `IMPLEMENTATION_STATUS.md` - the permanent architecture reference;
+  read this one for what srdwm supports overall, not just what's pending.