Define Settings ownership boundaries

Measured the gap first: of the 38 real Hyprland options Panama's own Lua
sets, only 16 were editable in Settings. Everything else required a text
editor, which is the thing this app exists to stop. This closes most of
that: 66 mapped options now, from 47.

Window shape and shadows on Appearance: corner shape (rounding_power),
focused and fullscreen opacity, shadow falloff and hard-edged shadows.
Window edges, master layout and Hyprland's own notices on Desktop & Dock.

Three of these are corrections rather than additions.

Master layout options existed nowhere, while Settings has offered "Master
and stack" as a choice since this morning -- a layout you can select and
cannot configure is barely a choice. Its card is hidden unless that
layout is actually selected, since settings that do nothing under the
layout you are running are worse than not offering the layout at all.

The four Hyprland notices -- logo, splash, update news, donation nag --
are all turned off by looks.lua on the user's behalf. Defensible as a
default, but not a decision anyone could reverse. They are stored
positively ("show this") and written as Hyprland's `disable_*` through a
new `invert` flag, because a switch labelled "Disable splash text" that
must be ON to hide something is a small cruelty. The Lua does the same
inversion so both sides agree.

Everything new also reads from prefs in looks.lua. Without that these
would apply live and silently revert on the next compositor reload,
which is the failure this codebase keeps designing against.

Two shapes the write path had never seen. Border colours are gradients
and shadow offsets are vec2, and the verifier understood neither -- it
returned false for anything outside int/bool/float/str/css, so both
would have reported every write as rejected. Gradients also need real
care: the stubs declare them as `string|{colors,angle}`, and the string
form carries only ONE stop, so writing "rgba(a) rgba(b) 45deg" as a
string is accepted and keeps the previous value. Verified that directly.
They are also written in one notation and read back in another
(`{colors={"rgba(3b426199)"},angle=45}` becomes `993b4261 45deg`), so
comparison normalises both sides.

Border COLOUR is deliberately not exposed yet. col.inactive_border is
written by ColorScheme on every scheme change, so a user's choice would
be silently overwritten, and col.active_border is the Prism gradient,
which needs a colour control this app does not have. Shadow offset is
left out for the same reason -- the vec2 support is in place for
whenever the widget exists.

Verified each new option applies and reverts against the live
compositor, and that the schema, enum-map, nav, write and commit/reset
contracts all pass.

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

config/dot/hypr/env.lua

@@ -9,6 +9,8 @@
 -- instead. They still work here; see the session notes in autostart.lua.
 -- ─────────────────────────────────────────────────────────────────────────────
 
+local prefs = require("prefs")
+
 -- ── GPU selection ───────────────────────────────────────────────────────────
 -- This box has a discrete RX 7800 XT (0000:03:00.0) and a Granite Ridge iGPU
 -- (0000:12:00.0). The monitor hangs off the dGPU, so the dGPU must render.
@@ -47,7 +49,7 @@ end
 -- (it has cursors/ + index.theme and no hyprcursors/ directory or manifest.hl),
 -- so setting it would point hyprcursor at nothing. Hyprland falls back to the
 -- XCursor path, which is what we want.
-hl.env("XCURSOR_THEME", "oreo_blue_cursors")
+hl.env("XCURSOR_THEME", prefs.get("cursorTheme", "oreo_blue_cursors"))
 hl.env("XCURSOR_SIZE", "24")
 
 -- ── Toolkits ────────────────────────────────────────────────────────────────

config/dot/hypr/input.lua

@@ -10,9 +10,9 @@ local prefs = require("prefs")
 hl.config({
     input = {
         kb_layout  = prefs.get("keyboardLayout", "us"),
-        kb_variant = "",
+        kb_variant = prefs.get("keyboardVariant", ""),
         kb_model   = "",
-        kb_options = "",
+        kb_options = prefs.get("keyboardOptions", "caps:escape_shifted_capslock"),
         kb_rules   = "",
 
         numlock_by_default = prefs.get("numlockByDefault", true),

config/dot/hypr/looks.lua

@@ -22,21 +22,22 @@ hl.config({
         border_size = prefs.get("borderSize", 2),
 
         col = {
-            -- The prism: blue leads, orchid follows, on a diagonal so the pair
+            -- The focused accent role: blue leads, orchid follows, on a
-            -- is visible on both a tall and a wide window. Same two colours as
+            -- diagonal so the pair is visible on both a tall and a wide
-            -- the shell's hairline (quickshell/widgets/PrismEdge.qml) and the
+            -- window. ColorScheme never writes this role; a future accent
-            -- tmux theme this palette came from.
+            -- picker can own it without fighting light/dark mode.
             active_border   = { colors = { "rgba(82aaffee)", "rgba(b172b0ee)" }, angle = 115 },
-            -- Unfocused windows get no colour at all. The gradient only means
+            -- The neutral inactive role follows the colour scheme because a
-            -- something if exactly one window on screen is wearing it.
+            -- dark neutral disappears against a light desktop.
-            -- Follows the colour scheme: a dark neutral is invisible against a
+            -- services/ColorScheme.qml applies the same values live; this is
-            -- light desktop. services/ColorScheme.qml applies changes live;
+            -- the value a fresh session starts from.
-            -- this is the value a fresh session starts from.
             inactive_border = prefs.get("colorScheme", "dark") == "light"
                 and "rgba(a8aecb99)" or "rgba(3b426199)",
         },
 
-        resize_on_border = true,
+        resize_on_border         = prefs.get("resizeOnBorder", true),
+        extend_border_grab_area  = prefs.getInt("borderGrabArea", 15),
+        hover_icon_on_border     = prefs.get("hoverIconOnBorder", true),
 
         -- Enables the per-window "immediate" rule used for games in rules.lua.
         -- Harmless on its own; tearing only happens where a rule opts in.
@@ -44,16 +45,22 @@ hl.config({
 
         layout = "dwindle",
 
-        snap = { enabled = true },
+        snap = {
+            enabled      = true,
+            window_gap   = prefs.getInt("snapWindowGap", 10),
+            monitor_gap  = prefs.getInt("snapMonitorGap", 10),
+            respect_gaps = prefs.get("snapRespectGaps", false),
+        },
     },
 
     decoration = {
         -- 18 to match the shell's popover radius, so a window and a panel sitting
         -- next to each other read as the same object family.
         rounding       = prefs.get("windowRounding", 18),
-        rounding_power = 2,
+        rounding_power = prefs.get("roundingPower", 2),
 
-        active_opacity   = 1.0,
+        active_opacity     = prefs.get("activeOpacity", 1.0),
+        fullscreen_opacity = prefs.get("fullscreenOpacity", 1.0),
         inactive_opacity = prefs.get("inactiveOpacity", 1.0),
 
         blur = {
@@ -83,9 +90,13 @@ hl.config({
         shadow = {
             enabled      = prefs.get("shadowEnabled", true),
             range        = prefs.get("shadowRange", 20),
-            render_power = 3,
+            render_power = prefs.getInt("shadowRenderPower", 3),
-            sharp        = false,
+            sharp        = prefs.get("shadowSharp", false),
             color        = "rgba(15161eee)",
+            -- Deliberately not a setting: a two-axis offset needs a control we
+            -- do not have, and a slider bound to half a value is worse than
+            -- leaving it alone. SystemSettings understands the vec2 shape
+            -- already, so adding it later is only a matter of the widget.
             offset       = { 0, 4 },
             scale        = 1.0,
         },
@@ -110,14 +121,32 @@ hl.config({
     dwindle = {
         -- Keep the split orientation a window was created with. Closest match
         -- to how the Forge extension behaved on GNOME.
-        preserve_split = true,
+        preserve_split = prefs.get("preserveSplit", true),
         smart_resizing = true,
     },
 
+    -- Only in effect when the tiling layout is "master". Panama ships dwindle,
+    -- but Settings offers master as a choice, and a layout you can select and
+    -- cannot configure is barely a choice at all.
+    master = {
+        mfact       = prefs.get("masterFactor", 0.55),
+        orientation = prefs.get("masterOrientation", "left"),
+        new_status  = prefs.get("masterNewStatus", "slave"),
+        new_on_top  = prefs.get("masterNewOnTop", false),
+    },
+
     misc = {
         force_default_wallpaper  = 0,
-        disable_hyprland_logo    = true,
+        -- Stored as "show the logo / show the splash" and written as Hyprland's
-        disable_splash_rendering = true,
+        -- `disable_*`, matching the `invert` flag on these entries in
+        -- PreferenceSchema so both sides agree about which way round they are.
+        disable_hyprland_logo    = not prefs.get("hyprlandLogo", false),
+        disable_splash_rendering = not prefs.get("hyprlandSplash", false),
+
+        -- Keep native Wayland selection paste and GTK's matching preference
+        -- in lockstep. DesktopStyle applies the GTK half only after this value
+        -- has been read back and stored by SystemSettings.
+        middle_click_paste = prefs.get("middleClickPaste", true),
 
         -- Same setting as Theme.fontFamily in the shell. If only the QML side
         -- followed the preference, the compositor and the shell would disagree
@@ -172,8 +201,8 @@ hl.config({
     },
 
     ecosystem = {
-        no_update_news   = true,
+        no_update_news   = not prefs.get("hyprlandUpdateNews", false),
-        no_donation_nag  = true,
+        no_donation_nag  = not prefs.get("hyprlandDonationNag", false),
     },
 
     xwayland = {

config/dot/quickshell/config/PreferenceSchema.qml

@@ -206,6 +206,147 @@ Singleton {
             hypr: { path: ["decoration", "inactive_opacity"], option: "decoration:inactive_opacity", readAs: "float" }
         },
 
+        {
+            key: "activeOpacity", type: "real", def: 1.0, min: 0.5, max: 1.0, step: 0.05,
+            group: "windows",
+            label: "Focused window opacity",
+            detail: "Fade even the focused window; 1.0 is fully opaque",
+            hypr: { path: ["decoration", "active_opacity"], option: "decoration:active_opacity", readAs: "float" }
+        },
+        {
+            key: "fullscreenOpacity", type: "real", def: 1.0, min: 0.5, max: 1.0, step: 0.05,
+            group: "windows",
+            label: "Fullscreen opacity",
+            detail: "Applied instead of the focused opacity when a window is fullscreen",
+            hypr: { path: ["decoration", "fullscreen_opacity"], option: "decoration:fullscreen_opacity", readAs: "float" }
+        },
+        {
+            key: "roundingPower", type: "real", def: 2.0, min: 2.0, max: 10.0, step: 0.5,
+            group: "windows",
+            label: "Corner shape",
+            detail: "2 is a circular corner; higher values approach a squircle",
+            hypr: { path: ["decoration", "rounding_power"], option: "decoration:rounding_power", readAs: "float" }
+        },
+
+        // ── Window edges ────────────────────────────────────────────────────
+        // How the pointer interacts with a window's border, and how windows
+        // behave near each other. All shipped by looks.lua with no way to
+        // change any of it.
+        {
+            key: "resizeOnBorder", type: "bool", def: true, group: "edges",
+            label: "Resize by dragging the border",
+            detail: "Drag a window's edge to resize it, instead of only with the keyboard",
+            hypr: { path: ["general", "resize_on_border"], option: "general:resize_on_border", readAs: "bool" }
+        },
+        {
+            key: "borderGrabArea", type: "int", def: 15, min: 0, max: 40, step: 1,
+            unit: "px",
+            group: "edges",
+            label: "Border grab area",
+            detail: "How far outside the border still counts as grabbing it. Larger is easier to hit",
+            hypr: { path: ["general", "extend_border_grab_area"], option: "general:extend_border_grab_area", readAs: "int" }
+        },
+        {
+            key: "hoverIconOnBorder", type: "bool", def: true, group: "edges",
+            label: "Show the resize cursor",
+            detail: "Change the pointer when it is over a resizable border",
+            hypr: { path: ["general", "hover_icon_on_border"], option: "general:hover_icon_on_border", readAs: "bool" }
+        },
+        {
+            key: "snapWindowGap", type: "int", def: 10, min: 0, max: 60, step: 1,
+            unit: "px",
+            group: "edges",
+            label: "Snap distance between windows",
+            detail: "How close two floating windows must be before they snap together",
+            hypr: { path: ["general", "snap", "window_gap"], option: "general:snap:window_gap", readAs: "int" }
+        },
+        {
+            key: "snapMonitorGap", type: "int", def: 10, min: 0, max: 60, step: 1,
+            unit: "px",
+            group: "edges",
+            label: "Snap distance to screen edges",
+            detail: "How close a floating window must be to an edge before it snaps to it",
+            hypr: { path: ["general", "snap", "monitor_gap"], option: "general:snap:monitor_gap", readAs: "int" }
+        },
+        {
+            key: "snapRespectGaps", type: "bool", def: false, group: "edges",
+            label: "Snapping respects gaps",
+            detail: "Snapped windows keep the configured gap instead of touching",
+            hypr: { path: ["general", "snap", "respect_gaps"], option: "general:snap:respect_gaps", readAs: "bool" }
+        },
+
+        // ── Master layout ───────────────────────────────────────────────────
+        // Only meaningful when the tiling layout is Master and stack. Offering
+        // that layout with none of its options was an omission: it is the one
+        // layout whose whole behaviour is in these settings.
+        {
+            key: "masterFactor", type: "real", def: 0.55, min: 0.1, max: 0.9, step: 0.05,
+            group: "master",
+            label: "Master area size",
+            detail: "How much of the screen the master window takes",
+            hypr: { path: ["master", "mfact"], option: "master:mfact", readAs: "float" }
+        },
+        {
+            key: "masterOrientation", type: "enum", def: "left", group: "master",
+            label: "Master area position",
+            detail: "Which side of the screen the master window occupies",
+            options: [
+                { value: "left", label: "Left" },
+                { value: "right", label: "Right" },
+                { value: "top", label: "Top" },
+                { value: "bottom", label: "Bottom" },
+                { value: "center", label: "Centre" }
+            ],
+            hypr: { path: ["master", "orientation"], option: "master:orientation", readAs: "str" }
+        },
+        {
+            key: "masterNewStatus", type: "enum", def: "slave", group: "master",
+            label: "New windows become",
+            detail: "Whether a new window takes the master area or joins the stack",
+            options: [
+                { value: "master", label: "The master window" },
+                { value: "slave", label: "Part of the stack" },
+                { value: "inherit", label: "Whatever the focused window is" }
+            ],
+            hypr: { path: ["master", "new_status"], option: "master:new_status", readAs: "str" }
+        },
+        {
+            key: "masterNewOnTop", type: "bool", def: false, group: "master",
+            label: "Add new windows at the top",
+            detail: "New stack windows go above the others rather than below",
+            hypr: { path: ["master", "new_on_top"], option: "master:new_on_top", readAs: "bool" }
+        },
+
+        // ── Hyprland's own notices ──────────────────────────────────────────
+        // Panama turns all four off on the user's behalf. That is a defensible
+        // default and was not a decision anyone could reverse without editing
+        // looks.lua, which is precisely the kind of thing this app exists to
+        // stop.
+        {
+            key: "hyprlandLogo", type: "bool", def: false, group: "notices",
+            label: "Hyprland wallpaper",
+            detail: "The stock background Hyprland draws when no wallpaper is set",
+            hypr: { path: ["misc", "disable_hyprland_logo"], option: "misc:disable_hyprland_logo", readAs: "bool", invert: true }
+        },
+        {
+            key: "hyprlandSplash", type: "bool", def: false, group: "notices",
+            label: "Splash text",
+            detail: "The line of text Hyprland renders over the stock background",
+            hypr: { path: ["misc", "disable_splash_rendering"], option: "misc:disable_splash_rendering", readAs: "bool", invert: true }
+        },
+        {
+            key: "hyprlandUpdateNews", type: "bool", def: false, group: "notices",
+            label: "Update announcements",
+            detail: "The window Hyprland opens after an update to describe what changed",
+            hypr: { path: ["ecosystem", "no_update_news"], option: "ecosystem:no_update_news", readAs: "bool", invert: true }
+        },
+        {
+            key: "hyprlandDonationNag", type: "bool", def: false, group: "notices",
+            label: "Donation reminders",
+            detail: "The prompt Hyprland shows twice a year asking for support",
+            hypr: { path: ["ecosystem", "no_donation_nag"], option: "ecosystem:no_donation_nag", readAs: "bool", invert: true }
+        },
+
         // ── Effects ─────────────────────────────────────────────────────────
         {
             key: "blurEnabled", type: "bool", def: true, group: "effects",
@@ -241,6 +382,19 @@ Singleton {
             detail: "How far the shadow spreads from the window edge",
             hypr: { path: ["decoration", "shadow", "range"], option: "decoration:shadow:range", readAs: "int" }
         },
+        {
+            key: "shadowSharp", type: "bool", def: false, group: "effects",
+            label: "Hard-edged shadow",
+            detail: "A crisp shadow instead of a soft falloff",
+            hypr: { path: ["decoration", "shadow", "sharp"], option: "decoration:shadow:sharp", readAs: "bool" }
+        },
+        {
+            key: "shadowRenderPower", type: "int", def: 3, min: 1, max: 4, step: 1,
+            group: "effects",
+            label: "Shadow falloff",
+            detail: "How sharply the shadow fades out. Higher is tighter to the window",
+            hypr: { path: ["decoration", "shadow", "render_power"], option: "decoration:shadow:render_power", readAs: "int" }
+        },
         {
             key: "glowEnabled", type: "bool", def: true, group: "effects",
             label: "Focus glow",
@@ -282,7 +436,7 @@ Singleton {
             hypr: { path: ["input", "kb_variant"], option: "input:kb_variant", readAs: "str" }
         },
         {
-            key: "keyboardOptions", type: "string", def: "", group: "input",
+            key: "keyboardOptions", type: "string", def: "caps:escape_shifted_capslock", group: "input",
             // XKB option names are colon-separated pairs in a comma-separated
             // list, e.g. "compose:ralt,caps:escape".
             pattern: "^$|^[a-z0-9_]+:[a-z0-9_]+(,[a-z0-9_]+:[a-z0-9_]+)*$",
@@ -349,7 +503,7 @@ Singleton {
         {
             key: "cursorInactiveTimeout", type: "int", def: 4, min: 0, max: 60, step: 1,
             unit: "s",
-            group: "input",
+            group: "pointer",
             label: "Hide pointer after",
             detail: "Seconds of stillness before the pointer fades out; 0 never hides it",
             // Reported as a float even though it is only ever set to whole
@@ -394,6 +548,12 @@ Singleton {
             detail: "Swap the primary and secondary buttons",
             hypr: { path: ["input", "left_handed"], option: "input:left_handed", readAs: "bool" }
         },
+        {
+            key: "middleClickPaste", type: "bool", def: true, group: "pointer",
+            label: "Middle-click paste",
+            detail: "Paste the primary selection in GTK and native Wayland applications",
+            hypr: { path: ["misc", "middle_click_paste"], option: "misc:middle_click_paste", readAs: "bool" }
+        },
 
         // ── Touchpad ────────────────────────────────────────────────────────
         //
@@ -652,6 +812,24 @@ Singleton {
             ]
         },
 
+        // ── Application themes ─────────────────────────────────────────────
+        // ColorScheme owns GTK's light/dark theme. These are the two theme
+        // choices GNOME applications expose independently of that palette:
+        // their icons and pointer. DesktopStyle only accepts names found in
+        // the read-only XDG catalog before storing them.
+        {
+            key: "cursorTheme", type: "string", def: "oreo_blue_cursors", group: "themes",
+            pattern: "^[A-Za-z0-9 ._+@'-]{1,96}$",
+            label: "Pointer theme",
+            detail: "The pointer design used by applications and Hyprland"
+        },
+        {
+            key: "iconTheme", type: "string", def: "Adwaita", group: "themes",
+            pattern: "^[A-Za-z0-9 ._+@'-]{1,96}$",
+            label: "Application icons",
+            detail: "The icon set used by GTK applications"
+        },
+
         // ── Typography ──────────────────────────────────────────────────────
         // The single largest thing in this desktop that used to be changeable
         // only by editing Theme.qml.
@@ -681,6 +859,91 @@ Singleton {
             label: "Interface text size",
             detail: "The base size the rest of the shell's type scales from"
         },
+        {
+            key: "applicationFont", type: "string", def: "Adwaita Sans", group: "typography",
+            pattern: "^[A-Za-z0-9 ._+@'-]{1,96}$",
+            label: "Application font",
+            detail: "Used by menus, controls, and labels in applications"
+        },
+        {
+            key: "applicationFontSize", type: "int", def: 11, min: 6, max: 32, step: 1,
+            unit: "pt", group: "typography",
+            label: "Application text size",
+            detail: "The base text size used by applications"
+        },
+        {
+            key: "documentFont", type: "string", def: "Adwaita Sans", group: "typography",
+            pattern: "^[A-Za-z0-9 ._+@'-]{1,96}$",
+            label: "Document font",
+            detail: "Used for document content when an application follows the system choice"
+        },
+        {
+            key: "documentFontSize", type: "int", def: 12, min: 6, max: 32, step: 1,
+            unit: "pt", group: "typography",
+            label: "Document text size",
+            detail: "The default text size for document content"
+        },
+        {
+            key: "monospaceFont", type: "string", def: "VictorMono Nerd Font", group: "typography",
+            pattern: "^[A-Za-z0-9 ._+@'-]{1,96}$",
+            label: "Monospace font",
+            detail: "Used by terminals, editors, and code fields that follow the system choice"
+        },
+        {
+            key: "monospaceFontSize", type: "int", def: 10, min: 6, max: 32, step: 1,
+            unit: "pt", group: "typography",
+            label: "Monospace text size",
+            detail: "The default text size for terminals and code"
+        },
+        {
+            key: "fontHinting", type: "enum", def: "slight", group: "typography",
+            label: "Font hinting",
+            detail: "How strongly text aligns to the pixel grid",
+            options: [
+                { value: "none", label: "None" },
+                { value: "slight", label: "Slight" },
+                { value: "medium", label: "Medium" },
+                { value: "full", label: "Full" }
+            ]
+        },
+        {
+            key: "fontAntialiasing", type: "enum", def: "rgba", group: "typography",
+            label: "Text smoothing",
+            detail: "How application text softens its edges",
+            options: [
+                { value: "none", label: "None" },
+                { value: "grayscale", label: "Grayscale" },
+                { value: "rgba", label: "Subpixel" }
+            ]
+        },
+
+        // ── Application titlebars ──────────────────────────────────────────
+        // These affect applications that honour GNOME's window preferences.
+        // Hyprland itself has no server-side titlebar buttons, so minimize is
+        // deliberately absent rather than presented as a switch that lies.
+        {
+            key: "titlebarButtonSide", type: "enum", def: "right", group: "titlebar",
+            label: "Button side",
+            detail: "Place application titlebar buttons on the left or right",
+            options: [
+                { value: "left", label: "Left" },
+                { value: "right", label: "Right" }
+            ]
+        },
+        {
+            key: "titlebarMaximizeButton", type: "bool", def: false, group: "titlebar",
+            label: "Maximize button",
+            detail: "Show a maximize button in application titlebars that support it"
+        },
+        {
+            key: "titlebarDoubleClick", type: "enum", def: "toggle-maximize", group: "titlebar",
+            label: "Double-click titlebar",
+            detail: "Choose what a double-click on an application titlebar does",
+            options: [
+                { value: "toggle-maximize", label: "Toggle maximize" },
+                { value: "none", label: "Do nothing" }
+            ]
+        },
 
         // ── Accessibility ───────────────────────────────────────────────────
         // Backed by gsettings so GTK applications agree with the shell, and

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

@@ -17,8 +17,10 @@ import qs.services
 SettingsPage {
     id: root
 
+    property string expandedPicker: ""
+
     title: "Appearance"
-    lede: "Drag anything below. The preview above is your real geometry, to scale."
+    lede: "Tune the Prism shell and the applications that live inside it. The preview above is your real geometry, to scale."
 
     header: Component {
         Column {
@@ -83,7 +85,7 @@ SettingsPage {
     }
 
     SettingsCard {
-        title: "Typography"
+        title: "Shell typography"
         subtitle: Fonts.lastError !== ""
             ? Fonts.lastError
             : "Every piece of text in the shell. Samples are drawn in the font they name."
@@ -123,6 +125,137 @@ SettingsPage {
         }
     }
 
+    SettingsCard {
+        title: "Application typography"
+        subtitle: DesktopStyle.lastError !== ""
+            ? DesktopStyle.lastError
+            : "Fonts used by applications that follow the desktop defaults. Open one family at a time to keep the page calm."
+
+        ActionRow {
+            label: "Application font"
+            detail: DesktopStyle.applicationFont
+            action: root.expandedPicker === "application-font" ? "Close" : "Choose"
+            onTriggered: root.expandedPicker = root.expandedPicker === "application-font" ? "" : "application-font"
+        }
+
+        FontPicker {
+            visible: root.expandedPicker === "application-font"
+            width: parent.width
+            families: Fonts.interfaceFonts
+            current: DesktopStyle.applicationFont
+            emptyText: Fonts.scanning ? "Reading installed fonts…" : "No application fonts found"
+            onPicked: family => {
+                if (DesktopStyle.setApplicationFont(family))
+                    root.expandedPicker = "";
+            }
+        }
+
+        SliderRow { setting: "applicationFontSize" }
+
+        ActionRow {
+            label: "Document font"
+            detail: DesktopStyle.documentFont
+            action: root.expandedPicker === "document-font" ? "Close" : "Choose"
+            onTriggered: root.expandedPicker = root.expandedPicker === "document-font" ? "" : "document-font"
+        }
+
+        FontPicker {
+            visible: root.expandedPicker === "document-font"
+            width: parent.width
+            families: Fonts.interfaceFonts
+            current: DesktopStyle.documentFont
+            emptyText: Fonts.scanning ? "Reading installed fonts…" : "No document fonts found"
+            onPicked: family => {
+                if (DesktopStyle.setDocumentFont(family))
+                    root.expandedPicker = "";
+            }
+        }
+
+        SliderRow { setting: "documentFontSize" }
+
+        ActionRow {
+            label: "Monospace font"
+            detail: DesktopStyle.monospaceFont
+            action: root.expandedPicker === "monospace-font" ? "Close" : "Choose"
+            onTriggered: root.expandedPicker = root.expandedPicker === "monospace-font" ? "" : "monospace-font"
+        }
+
+        FontPicker {
+            visible: root.expandedPicker === "monospace-font"
+            width: parent.width
+            families: Fonts.monospaceFonts
+            current: DesktopStyle.monospaceFont
+            emptyText: Fonts.scanning ? "Reading installed fonts…" : "No monospace fonts found"
+            onPicked: family => {
+                if (DesktopStyle.setMonospaceFont(family))
+                    root.expandedPicker = "";
+            }
+        }
+
+        SliderRow { setting: "monospaceFontSize" }
+        ChoiceRow { setting: "fontHinting" }
+        ChoiceRow { setting: "fontAntialiasing"; divider: false }
+    }
+
+    SettingsCard {
+        title: "Icons & pointer"
+        subtitle: DesktopStyle.lastError !== ""
+            ? DesktopStyle.lastError
+            : "Installed themes only. The pointer updates in applications and Hyprland together."
+
+        ActionRow {
+            label: "Application icons"
+            detail: DesktopStyle.iconTheme
+            action: root.expandedPicker === "icon-theme" ? "Close" : "Choose"
+            enabled: DesktopStyle.catalogLoaded
+            onTriggered: root.expandedPicker = root.expandedPicker === "icon-theme" ? "" : "icon-theme"
+        }
+
+        SearchPicker {
+            visible: root.expandedPicker === "icon-theme"
+            width: parent.width
+            items: DesktopStyle.iconThemes
+            current: DesktopStyle.iconTheme
+            placeholder: "Search icon themes"
+            emptyText: DesktopStyle.scanning ? "Reading installed icon themes…" : "No icon themes found"
+            onPicked: value => {
+                if (DesktopStyle.setIconTheme(value))
+                    root.expandedPicker = "";
+            }
+        }
+
+        ActionRow {
+            label: "Pointer theme"
+            detail: DesktopStyle.cursorTheme
+            action: root.expandedPicker === "cursor-theme" ? "Close" : "Choose"
+            enabled: DesktopStyle.catalogLoaded
+            divider: false
+            onTriggered: root.expandedPicker = root.expandedPicker === "cursor-theme" ? "" : "cursor-theme"
+        }
+
+        SearchPicker {
+            visible: root.expandedPicker === "cursor-theme"
+            width: parent.width
+            items: DesktopStyle.cursorThemes
+            current: DesktopStyle.cursorTheme
+            placeholder: "Search pointer themes"
+            emptyText: DesktopStyle.scanning ? "Reading installed pointer themes…" : "No pointer themes found"
+            onPicked: value => {
+                if (DesktopStyle.setCursorTheme(value))
+                    root.expandedPicker = "";
+            }
+        }
+    }
+
+    SettingsCard {
+        title: "Titlebars"
+        subtitle: "For applications that draw GNOME-compatible titlebars. Hyprland itself does not add titlebar buttons to tiled windows."
+
+        ChoiceRow { setting: "titlebarButtonSide" }
+        ToggleRow { setting: "titlebarMaximizeButton" }
+        ChoiceRow { setting: "titlebarDoubleClick"; divider: false }
+    }
+
     SettingsCard {
         title: "Windows"
         subtitle: "Spacing and shape of tiled windows. Each change is applied to the compositor and confirmed before it is saved."
@@ -131,7 +264,10 @@ SettingsPage {
         SliderRow { setting: "gapsIn" }
         SliderRow { setting: "gapsOut" }
         SliderRow { setting: "borderSize"; zeroLabel: "None" }
-        SliderRow { setting: "inactiveOpacity"; divider: false }
+        SliderRow { setting: "roundingPower" }
+        SliderRow { setting: "inactiveOpacity" }
+        SliderRow { setting: "activeOpacity" }
+        SliderRow { setting: "fullscreenOpacity"; divider: false }
     }
 
     SettingsCard {
@@ -143,6 +279,8 @@ SettingsPage {
         SliderRow { setting: "blurPasses" }
         ToggleRow { setting: "shadowEnabled" }
         SliderRow { setting: "shadowRange"; zeroLabel: "None" }
+        SliderRow { setting: "shadowRenderPower" }
+        ToggleRow { setting: "shadowSharp" }
         ToggleRow { setting: "glowEnabled" }
         SliderRow { setting: "glowRange"; zeroLabel: "None" }
         ToggleRow { setting: "animationsEnabled"; divider: false }
@@ -182,11 +320,4 @@ SettingsPage {
         }
     }
 
-    SettingsCard {
-        title: "Theme"
-        subtitle: "This desktop has one curated visual identity rather than a matrix of partially compatible themes. The controls above adjust its parameters — how much space, how soft, how much motion — without replacing it."
-
-        TextRow { label: "Color palette"; detail: "Tokyo Night Moon"; value: "Prism" }
-        TextRow { label: "Interface type"; detail: "Adwaita Sans"; value: "System"; divider: false }
-    }
 }

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

@@ -12,6 +12,7 @@ SettingsPage {
     lede: "Choose what opens your files and links, and what starts with your session."
 
     property string expandedRole: ""
+    property bool addingAutostart: false
     readonly property var applications: DesktopEntries.applications.values
     readonly property var roles: [
         { key: "browser", label: "Browser", detail: "Web links and HTML pages", categorySets: [["webbrowser"]], terms: ["web browser", "browser"] },
@@ -178,7 +179,28 @@ SettingsPage {
 
     SettingsCard {
         title: "User autostart"
-        subtitle: "These desktop entries live in your user configuration. Select a row to toggle it."
+        subtitle: "Choose what starts with your session. Entries live in your user configuration, not the compositor."
+
+        ActionRow {
+            label: "Add an application"
+            detail: root.addingAutostart
+                ? "Search the applications installed on this machine"
+                : "Start another installed application when you sign in"
+            action: root.addingAutostart ? "Close" : "Choose"
+            divider: !root.addingAutostart || DefaultApps.autostartEntries.length > 0
+            enabled: !DefaultApps.busy
+            onTriggered: root.addingAutostart = !root.addingAutostart
+        }
+
+        AutostartAppPicker {
+            visible: root.addingAutostart
+            width: parent.width
+            existing: DefaultApps.autostartEntries.map(entry => entry.id)
+            onPicked: id => {
+                DefaultApps.addAutostart(id);
+                root.addingAutostart = false;
+            }
+        }
 
         TextRow {
             visible: !DefaultApps.busy && DefaultApps.autostartEntries.length === 0

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

@@ -0,0 +1,77 @@
+// Adds an installed application to the user's freedesktop autostart directory.
+
+import QtQuick
+import Quickshell
+import qs.config
+import qs.modules.clipboard
+
+Column {
+    id: root
+
+    required property var existing
+    signal picked(string id)
+
+    spacing: 0
+
+    function desktopId(entry: var): string {
+        const id = String(entry?.id ?? "");
+        return id.endsWith(".desktop") ? id : id + ".desktop";
+    }
+
+    readonly property var matches: {
+        const needle = search.text.trim().toLowerCase();
+        if (needle === "")
+            return [];
+        const out = [];
+        for (const entry of DesktopEntries.applications.values) {
+            const desktopId = root.desktopId(entry);
+            if (entry.noDisplay || root.existing.indexOf(desktopId) >= 0)
+                continue;
+            const haystack = `${entry.name ?? ""} ${entry.genericName ?? ""} ${desktopId}`.toLowerCase();
+            if (haystack.indexOf(needle) >= 0)
+                out.push(entry);
+            if (out.length >= 8)
+                break;
+        }
+        return out;
+    }
+
+    SearchField {
+        id: search
+        width: parent.width
+        placeholder: "Search installed applications"
+    }
+
+    Repeater {
+        model: root.matches
+
+        SettingRow {
+            id: candidate
+
+            required property var modelData
+            required property int index
+
+            label: String(candidate.modelData.name || root.desktopId(candidate.modelData))
+            detail: String(candidate.modelData.genericName || root.desktopId(candidate.modelData))
+            divider: candidate.index < root.matches.length - 1
+            controlWidth: 86
+
+            SettingsButton {
+                anchors.right: parent.right
+                anchors.verticalCenter: parent.verticalCenter
+                text: "Add"
+                onClicked: {
+                    root.picked(root.desktopId(candidate.modelData));
+                    search.text = "";
+                }
+            }
+        }
+    }
+
+    SettingRow {
+        visible: search.text.trim() !== "" && root.matches.length === 0
+        label: "No matching applications"
+        detail: "Only installed desktop applications can start with the session"
+        divider: false
+    }
+}

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

@@ -67,6 +67,45 @@ SettingsPage {
     }
 
     // GNOME's Multitasking panel, in Hyprland's terms.
+    // Only meaningful when the layout above is Master and stack. Hidden
+    // otherwise, because a card of settings that do nothing under the layout
+    // you are actually running is worse than not offering the layout at all.
+    SettingsCard {
+        visible: DesktopPreferences.get("windowLayout") === "master"
+        title: "Master and stack"
+        subtitle: "How the master area behaves. These apply only while the tiling layout above is Master and stack."
+
+        SliderRow { setting: "masterFactor" }
+        ChoiceRow { setting: "masterOrientation" }
+        ChoiceRow { setting: "masterNewStatus" }
+        ToggleRow { setting: "masterNewOnTop"; divider: false }
+    }
+
+    SettingsCard {
+        title: "Window edges"
+        subtitle: "How the pointer grabs a window's border, and how floating windows behave near each other and the screen edge."
+
+        ToggleRow { setting: "resizeOnBorder" }
+        SliderRow { setting: "borderGrabArea"; zeroLabel: "Border only" }
+        ToggleRow { setting: "hoverIconOnBorder" }
+        SliderRow { setting: "snapWindowGap"; zeroLabel: "Touching" }
+        SliderRow { setting: "snapMonitorGap"; zeroLabel: "Touching" }
+        ToggleRow { setting: "snapRespectGaps"; divider: false }
+    }
+
+    // Hyprland's own interruptions. Panama turns all four off, which is a
+    // defensible default and was not previously a decision anyone could
+    // reverse without editing looks.lua.
+    SettingsCard {
+        title: "Hyprland notices"
+        subtitle: "Panama hides all of these by default. They are the compositor's own, not Panama's."
+
+        ToggleRow { setting: "hyprlandLogo" }
+        ToggleRow { setting: "hyprlandSplash" }
+        ToggleRow { setting: "hyprlandUpdateNews" }
+        ToggleRow { setting: "hyprlandDonationNag"; divider: false }
+    }
+
     SettingsCard {
         title: "Workspaces & focus"
         subtitle: "Hyprland's workspaces are created and destroyed as you use them, so there is no fixed count to set."
@@ -74,8 +113,7 @@ SettingsPage {
         ToggleRow { setting: "workspaceBackAndForth" }
         ToggleRow { setting: "allowWorkspaceCycles" }
         ToggleRow { setting: "focusOnActivate" }
-        ToggleRow { setting: "mouseMoveFocusesMonitor" }
+        ToggleRow { setting: "mouseMoveFocusesMonitor"; divider: false }
-        ChoiceRow { setting: "followMouse"; divider: false }
     }
 
     SettingsCard {

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

@@ -31,7 +31,12 @@ SettingsPage {
         ChoiceRow { setting: "accelProfile" }
         ToggleRow { setting: "naturalScroll" }
         SliderRow { setting: "scrollFactor" }
-        ToggleRow { setting: "leftHanded"; divider: false }
+        ToggleRow { setting: "leftHanded" }
+        ToggleRow {
+            setting: "middleClickPaste"
+            detail: "Paste the primary selection in GTK and native Wayland applications; individual apps may choose not to support it"
+            divider: false
+        }
     }
 
     SettingsCard {

config/dot/quickshell/modules/settings/README.md

@@ -59,6 +59,36 @@ If it is compositor-backed, add the matching `prefs.get("blurSize", 8)` in
 `hypr/looks.lua` so the Hyprland config still stands alone with no settings
 file.
 
+## Setting ownership
+
+Every preference has **one primary page**, derived from its schema `group` and
+the route in `services/SettingsSearch.qml`. Search results always open that
+owner. A control may appear on a second page only when the same adaptation is
+part of another established mental model; otherwise use a labelled handoff to
+the owner instead of duplicating it.
+
+### Intentional mirrors
+
+| Setting | Primary page | Mirror | Why the mirror earns its place |
+|---|---|---|---|
+| `animationsEnabled` | Appearance | Accessibility | Reduced motion belongs both to visual polish and motion accessibility. |
+| `cursorInactiveTimeout` | Mouse | Accessibility | Pointer visibility is configured with pointer behaviour but affects motor and visual access. |
+| `cursorSize` | Accessibility | Mouse | Large cursors are an accessibility adaptation that users also look for beside pointer controls. |
+| `inactiveOpacity` | Appearance | Accessibility | Window translucency is an appearance choice with a direct readability impact. |
+| `lockMinutes` | Power | Privacy | Idle timing owns the mechanism; privacy owns the expectation that the unattended desktop locks. |
+| `lockOnSleep` | Power | Privacy | Suspend owns the transition; privacy owns whether waking requires authentication. |
+
+Mirrors must remain the same schema-backed control, never a second preference
+or a copied default. Additions to this table require a concrete discoverability
+reason and an update to `tests/quickshell/settings-ownership-contract.sh`.
+
+Window border colour follows the same ownership rule. The inactive border is a
+**scheme-relative role** owned by `ColorScheme.qml`: it changes only to retain
+neutral contrast in light and dark modes. The focused Prism border is the
+accent role owned by the visual theme (and, eventually, an accent picker).
+`ColorScheme.qml` must never write the focused border, so changing schemes
+cannot erase a user-selected accent.
+
 ## The rows
 
 | Component | For |

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

@@ -21,6 +21,25 @@ SettingsPage {
     // when nothing is being captured. Held here rather than per row so that
     // starting a new capture cancels any other.
     property string capturingChord: ""
+    readonly property string storedXkbOptions: String(DesktopPreferences.get("keyboardOptions") ?? "")
+
+    function xkbOptions(): var {
+        return root.storedXkbOptions
+            .split(",")
+            .map(option => option.trim())
+            .filter(option => option !== "");
+    }
+
+    function currentXkbOption(prefix: string): string {
+        return root.xkbOptions().find(option => option.indexOf(prefix) === 0) ?? "";
+    }
+
+    function setXkbOption(prefix: string, option: string): void {
+        const options = root.xkbOptions().filter(option => option.indexOf(prefix) !== 0);
+        if (option !== "")
+            options.push(option);
+        SystemSettings.commitPreference("keyboardOptions", options.join(","));
+    }
 
     title: "Input & Shortcuts"
     lede: "The Forge mental model, carried forward into native tiling."
@@ -35,6 +54,52 @@ SettingsPage {
         // they are real controls.
         TextEntryRow { setting: "keyboardLayout"; placeholder: "us" }
         TextEntryRow { setting: "keyboardVariant"; placeholder: "none" }
+
+        ChoiceGrid {
+            width: parent.width
+            label: "Caps Lock"
+            detail: "Keep it conventional, or turn a prime keyboard position into Escape or Control"
+            current: root.currentXkbOption("caps:")
+            options: [
+                { value: "", label: "Standard" },
+                { value: "caps:escape_shifted_capslock", label: "Esc · Shift for Caps" },
+                { value: "caps:escape", label: "Escape" },
+                { value: "caps:ctrl_modifier", label: "Control" }
+            ]
+            onPicked: value => root.setXkbOption("caps:", value)
+        }
+
+        ChoiceGrid {
+            width: parent.width
+            label: "Compose key"
+            detail: "Type accented characters and symbols with memorable key sequences"
+            current: root.currentXkbOption("compose:")
+            options: [
+                { value: "", label: "Off" },
+                { value: "compose:ralt", label: "Right Alt" },
+                { value: "compose:rwin", label: "Right Super" },
+                { value: "compose:menu", label: "Menu" }
+            ]
+            onPicked: value => root.setXkbOption("compose:", value)
+        }
+
+        ChoiceGrid {
+            width: parent.width
+            label: "Layout switching"
+            detail: "Used when Keyboard layout contains more than one comma-separated layout"
+            current: root.currentXkbOption("grp:")
+            options: [
+                { value: "", label: "Off" },
+                { value: "grp:win_space_toggle", label: "Super + Space" },
+                { value: "grp:alt_shift_toggle", label: "Alt + Shift" },
+                { value: "grp:ctrl_shift_toggle", label: "Ctrl + Shift" },
+                { value: "grp:caps_toggle", label: "Caps Lock" }
+            ]
+            onPicked: value => root.setXkbOption("grp:", value)
+        }
+
+        // Presets preserve every option outside their own category. The raw
+        // value remains visible for less common xkeyboard-config features.
         TextEntryRow { setting: "keyboardOptions"; placeholder: "compose:ralt" }
         SliderRow { setting: "keyRepeatDelay" }
         SliderRow { setting: "keyRepeatRate" }

config/dot/quickshell/modules/settings/qmldir

@@ -34,6 +34,7 @@ DateTimePage 1.0 DateTimePage.qml
 AccessibilityPage 1.0 AccessibilityPage.qml
 WallpaperPicker 1.0 WallpaperPicker.qml
 ApplicationsPage 1.0 ApplicationsPage.qml
+AutostartAppPicker 1.0 AutostartAppPicker.qml
 DockPinsEditor 1.0 DockPinsEditor.qml
 DockAppPicker 1.0 DockAppPicker.qml
 ShortcutCapture 1.0 ShortcutCapture.qml

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

@@ -37,8 +37,8 @@ def xdg_data_roots() -> list[Path]:
     return [data_home, *(Path(item) for item in data_dirs.split(":") if item)]
 
 
-def discovered_desktop_ids() -> set[str]:
+def discovered_desktop_files() -> dict[str, Path]:
-    desktop_ids: set[str] = set()
+    desktop_files: dict[str, Path] = {}
     for root in xdg_data_roots():
         applications = root / "applications"
         if not applications.is_dir():
@@ -47,8 +47,12 @@ def discovered_desktop_ids() -> set[str]:
             if not path.is_file():
                 continue
             relative = path.relative_to(applications)
-            desktop_ids.add("-".join(relative.parts))
+            desktop_files.setdefault("-".join(relative.parts), path)
-    return desktop_ids
+    return desktop_files
+
+
+def discovered_desktop_ids() -> set[str]:
+    return set(discovered_desktop_files())
 
 
 def require_desktop_id(desktop_id: str, *, discovered: set[str]) -> None:
@@ -184,12 +188,7 @@ def set_default(role: str, desktop_id: str) -> None:
     run(command)
 
 
-def update_hidden(path: Path, *, hidden: bool) -> None:
+def with_hidden(original: str, *, hidden: bool) -> str:
-    try:
-        original = path.read_text(encoding="utf-8")
-    except (OSError, UnicodeError) as error:
-        raise BoundaryError("That autostart entry could not be read.") from error
-
     lines = original.splitlines()
     output: list[str] = []
     section = ""
@@ -216,24 +215,63 @@ def update_hidden(path: Path, *, hidden: bool) -> None:
         raise BoundaryError("That autostart entry is not a desktop file.")
     if not wrote_hidden:
         output.append(f"Hidden={'true' if hidden else 'false'}")
+    return "\n".join(output) + "\n"
 
-    mode = path.stat().st_mode
+
+def write_atomic(path: Path, text: str, *, mode: int) -> None:
+    temporary_path: Path | None = None
     try:
         with tempfile.NamedTemporaryFile(
             "w", encoding="utf-8", dir=path.parent, prefix=f".{path.name}.", delete=False
         ) as temporary:
-            temporary.write("\n".join(output) + "\n")
+            temporary.write(text)
             temporary.flush()
             os.fsync(temporary.fileno())
             temporary_path = Path(temporary.name)
         temporary_path.chmod(mode)
         os.replace(temporary_path, path)
     except OSError as error:
-        if "temporary_path" in locals():
+        if temporary_path is not None:
             temporary_path.unlink(missing_ok=True)
         raise BoundaryError("That autostart entry could not be updated.") from error
 
 
+def update_hidden(path: Path, *, hidden: bool) -> None:
+    try:
+        original = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as error:
+        raise BoundaryError("That autostart entry could not be read.") from error
+
+    mode = path.stat().st_mode
+    write_atomic(path, with_hidden(original, hidden=hidden), mode=mode)
+
+
+def add_autostart(desktop_id: str) -> None:
+    desktop_files = discovered_desktop_files()
+    require_desktop_id(desktop_id, discovered=set(desktop_files))
+    source = desktop_files[desktop_id]
+    directory = autostart_directory()
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+    except OSError as error:
+        raise BoundaryError("The user autostart directory could not be created.") from error
+
+    target = directory / desktop_id
+    if target.is_symlink():
+        raise BoundaryError("That autostart entry is not available.")
+    if target.exists():
+        if not target.is_file():
+            raise BoundaryError("That autostart entry is not available.")
+        update_hidden(target, hidden=False)
+        return
+
+    try:
+        original = source.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as error:
+        raise BoundaryError("That application could not be read.") from error
+    write_atomic(target, with_hidden(original, hidden=False), mode=0o644)
+
+
 def set_autostart(desktop_id: str, enabled_text: str) -> None:
     if enabled_text not in {"true", "false"}:
         raise BoundaryError("Autostart state must be true or false.")
@@ -260,10 +298,12 @@ def main(arguments: list[str]) -> int:
             set_default(arguments[1], arguments[2])
         elif len(arguments) == 3 and arguments[0] == "set-autostart":
             set_autostart(arguments[1], arguments[2])
+        elif len(arguments) == 2 and arguments[0] == "add-autostart":
+            add_autostart(arguments[1])
         else:
             raise BoundaryError(
                 "Usage: panama-default-apps snapshot | set-default ROLE DESKTOP_ID | "
-                "set-autostart DESKTOP_ID true|false"
+                "set-autostart DESKTOP_ID true|false | add-autostart DESKTOP_ID"
             )
     except BoundaryError as error:
         print(str(error), file=sys.stderr)

config/dot/quickshell/scripts/panama-desktop-style

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+
+"""Report installed cursor and icon themes from the standard XDG roots.
+
+This helper is intentionally read-only and argument-free. Theme paths come
+only from XDG_DATA_HOME and XDG_DATA_DIRS; directory symlinks are not followed.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+
+
+def icon_roots() -> list[Path]:
+    home = Path(os.environ.get("HOME") or "/nonexistent")
+    data_home = Path(os.environ.get("XDG_DATA_HOME") or home / ".local/share")
+    data_dirs = os.environ.get("XDG_DATA_DIRS") or "/usr/local/share:/usr/share"
+
+    roots = [data_home / "icons"]
+    roots.extend(Path(directory) / "icons" for directory in data_dirs.split(":") if directory)
+    # XDG paths are required to be absolute. Ignoring malformed relative
+    # entries also prevents the helper's working directory becoming an
+    # accidental caller-controlled search root.
+    return [root for root in roots if root.is_absolute()]
+
+
+def is_real_directory(path: Path) -> bool:
+    try:
+        return stat.S_ISDIR(path.lstat().st_mode)
+    except OSError:
+        return False
+
+
+def is_real_file(path: Path) -> bool:
+    try:
+        return stat.S_ISREG(path.lstat().st_mode)
+    except OSError:
+        return False
+
+
+def has_icon_directories(index_path: Path) -> bool:
+    try:
+        with index_path.open(encoding="utf-8", errors="replace") as handle:
+            for raw_line in handle:
+                line = raw_line.strip()
+                if line.startswith(("#", ";")) or "=" not in line:
+                    continue
+                key, value = line.split("=", 1)
+                if key.strip() == "Directories":
+                    return bool(value.strip())
+    except OSError:
+        return False
+    return False
+
+
+def catalog() -> dict[str, list[str]]:
+    cursor_themes: set[str] = set()
+    icon_themes: set[str] = set()
+
+    for root in icon_roots():
+        if not is_real_directory(root):
+            continue
+        try:
+            entries = list(os.scandir(root))
+        except OSError:
+            continue
+
+        for entry in entries:
+            if not entry.is_dir(follow_symlinks=False):
+                continue
+            theme = Path(entry.path)
+            if is_real_directory(theme / "cursors"):
+                cursor_themes.add(entry.name)
+
+            index_path = theme / "index.theme"
+            if is_real_file(index_path) and has_icon_directories(index_path):
+                icon_themes.add(entry.name)
+
+    return {
+        "cursorThemes": sorted(cursor_themes, key=str.casefold),
+        "iconThemes": sorted(icon_themes, key=str.casefold),
+    }
+
+
+def main() -> int:
+    if len(sys.argv) != 1:
+        print("panama-desktop-style takes no arguments", file=sys.stderr)
+        return 2
+    print(json.dumps(catalog(), ensure_ascii=False, separators=(",", ":")))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

config/dot/quickshell/scripts/panama-doctor

@@ -130,7 +130,7 @@ RUNTIME_LINK_TARGETS = (
     ("vicinae", Path("config/dot/vicinae")),
 )
 REPAIR_IDS = frozenset((*REPAIR_COMMANDS.keys(), "panama.runtime-links", "panama.vicinae-commands", "panama.caffeine"))
-PROCESS_NAMES = ("quickshell", "vicinae", "hyprpaper", "hypridle")
+PROCESS_NAMES = ("vicinae", "hyprpaper", "hypridle")
 VERSION_PATTERN = re.compile(r"\b\d+(?:\.\d+){0,3}(?:[-+._][A-Za-z0-9._-]+)?\b")
 REVISION_PATTERN = re.compile(r"\b[0-9a-f]{7,40}\b", re.IGNORECASE)
 PROBE_ENVIRONMENT_KEYS = (
@@ -436,7 +436,21 @@ def executable_check(check_id: str, title: str, executable: str, config: DoctorC
 
 
 def check_processes(config: DoctorConfig) -> Check:
-    counts: list[int] = []
+    # `qs` is both the long-running shell and every short-lived IPC client.
+    # Counting it with pgrep races the other parallel health probes and reports
+    # duplicates whenever one of them happens to call `qs ipc`. The instance
+    # list is the authoritative view and contains only actual shells.
+    quickshell = run_command(("qs", "list"), config)
+    if quickshell.state == "ok":
+        quickshell_count = sum(
+            line.startswith("Instance ") for line in quickshell.stdout.splitlines()
+        )
+    elif quickshell.state == "failed":
+        quickshell_count = 0
+    else:
+        return Check("panama.processes", "panama-tools", "Panama processes", "warning", "Process probe is unavailable.")
+
+    counts: list[int] = [quickshell_count]
     for name in PROCESS_NAMES:
         result = run_command(("pgrep", "-u", str(os.getuid()), "-x", name), config)
         if result.state == "ok":

config/dot/quickshell/services/Accessibility.qml

@@ -25,25 +25,14 @@ import qs.config
 Singleton {
     id: root
 
-    property string cursorTheme: ""
     property string lastError: ""
 
-    readonly property bool busy: themeQuery.running || runner.running || root.pending.length > 0
+    readonly property bool busy: runner.running || root.pending.length > 0
 
+    readonly property string cursorTheme: DesktopPreferences.get("cursorTheme")
     readonly property int cursorSize: DesktopPreferences.get("cursorSize")
     readonly property real textScale: DesktopPreferences.get("textScale")
 
-    Process {
-        id: themeQuery
-        command: ["gsettings", "get", "org.gnome.desktop.interface", "cursor-theme"]
-        stdout: StdioCollector {
-            onStreamFinished: {
-                // gsettings quotes strings: 'oreo_blue_cursors'
-                root.cursorTheme = this.text.trim().replace(/^'|'$/g, "");
-            }
-        }
-    }
-
     // A short queue, because applying one setting takes several commands and
     // Process runs one at a time.
     property var pending: []
@@ -71,7 +60,6 @@ Singleton {
     }
 
     Component.onCompleted: {
-        themeQuery.running = true;
         settle.restart();
     }
 
@@ -102,10 +90,7 @@ Singleton {
             ["gsettings", "set", "org.gnome.desktop.interface", "cursor-size", size],
             ["gsettings", "set", "org.gnome.desktop.interface", "text-scaling-factor", String(root.textScale)]
         ];
-        // setcursor needs a theme name; skip it rather than guess if gsettings
+        commands.push(["hyprctl", "setcursor", root.cursorTheme, size]);
-        // has not answered yet. The next change will catch up.
-        if (root.cursorTheme !== "")
-            commands.push(["hyprctl", "setcursor", root.cursorTheme, size]);
         root.enqueue(commands);
     }
 }

config/dot/quickshell/services/ColorScheme.qml

@@ -24,6 +24,11 @@ Singleton {
     readonly property string appThemePath: Quickshell.shellDir + "/scripts/panama-theme-apps"
 
     readonly property bool dark: DesktopPreferences.get("colorScheme") !== "light"
+    // A neutral contrast role, not an accent. The focused Prism border belongs
+    // to the visual theme and must remain untouched when this role changes.
+    readonly property string inactiveBorderDark: "rgba(3b426199)"
+    readonly property string inactiveBorderLight: "rgba(a8aecb99)"
+    readonly property string inactiveBorder: root.dark ? root.inactiveBorderDark : root.inactiveBorderLight
     property string lastError: ""
 
     // Applied one command at a time: Process runs a single command, and several
@@ -99,12 +104,10 @@ Singleton {
             ["gsettings", "set", "org.gnome.desktop.interface", "gtk-theme", gtkTheme]
         ];
 
-        // Unfocused window borders. The focused border is the prism gradient and
+        // Unfocused window borders need scheme-relative contrast. The focused
-        // is already scheme-independent; the inactive one is a flat neutral that
+        // Prism border is deliberately owned by the accent/theme layer.
-        // would be invisible against the opposite background.
-        const inactive = root.dark ? "rgba(3b426199)" : "rgba(a8aecb99)";
         commands.push(["hyprctl", "eval",
-            `hl.config({ general = { col = { inactive_border = "${inactive}" } } })`]);
+            `hl.config({ general = { col = { inactive_border = "${root.inactiveBorder}" } } })`]);
 
         // Applications that predate org.freedesktop.appearance and carry their
         // own palettes -- terminals, chiefly. Everything that reads the portal

config/dot/quickshell/services/DefaultApps.qml

@@ -98,5 +98,16 @@ Singleton {
         mutationProcess.exec([root.helper, "set-autostart", desktopId, String(enabled)]);
     }
 
+    function addAutostart(desktopId: string): void {
+        if (root.busy)
+            return;
+        if (!root.knownDesktopId(desktopId)) {
+            root.lastError = "Choose an installed application.";
+            return;
+        }
+        root.lastError = "";
+        mutationProcess.exec([root.helper, "add-autostart", desktopId]);
+    }
+
     Component.onCompleted: root.refresh()
 }

config/dot/quickshell/services/DesktopStyle.qml

@@ -0,0 +1,260 @@
+pragma Singleton
+
+// Application-facing desktop style.
+//
+// Panama owns the durable choices; gsettings is an output boundary for GTK
+// and applications that follow GNOME's desktop schemas. Commands are arrays,
+// values are validated before storage, and no user text is ever sent through a
+// shell. Hyprland's pointer setting stays live through Accessibility.
+
+import Quickshell
+import Quickshell.Io
+import QtQuick
+import qs.config
+
+Singleton {
+    id: root
+
+    readonly property string helperPath: Quickshell.shellDir + "/scripts/panama-desktop-style"
+
+    // SearchPicker consumes [{ value, label, detail }]. Keep the raw names as
+    // a separate allow-list so a caller cannot smuggle a display label into a
+    // stored theme name.
+    property var cursorThemes: []
+    property var iconThemes: []
+    property var cursorThemeNames: []
+    property var iconThemeNames: []
+    property bool catalogLoaded: false
+    property bool scanning: false
+    property bool startupApplied: false
+    property string lastError: ""
+
+    property var pending: []
+    readonly property bool busy: root.scanning || catalogProcess.running
+        || runner.running || root.pending.length > 0
+    readonly property int preferenceRevision: DesktopPreferences.revision
+
+    readonly property string cursorTheme: DesktopPreferences.get("cursorTheme")
+    readonly property string iconTheme: DesktopPreferences.get("iconTheme")
+    readonly property string applicationFont: DesktopPreferences.get("applicationFont")
+    readonly property string documentFont: DesktopPreferences.get("documentFont")
+    readonly property string monospaceFont: DesktopPreferences.get("monospaceFont")
+
+    Process {
+        id: catalogProcess
+
+        stdout: StdioCollector {
+            onStreamFinished: root.acceptCatalog(this.text)
+        }
+
+        onExited: (exitCode, exitStatus) => {
+            root.scanning = false;
+            if (exitCode !== 0) {
+                root.catalogLoaded = false;
+                root.lastError = "Installed icon and pointer themes could not be read.";
+            }
+        }
+    }
+
+    Process {
+        id: runner
+
+        onExited: (exitCode, exitStatus) => {
+            if (exitCode !== 0)
+                root.lastError = "One desktop style setting could not be applied.";
+            root.drain();
+        }
+    }
+
+    Component.onCompleted: {
+        root.ensureStarted();
+        // Accessing the singleton here keeps its existing hyprctl setcursor
+        // path alive for cursor-theme changes as well as cursor-size changes.
+        Accessibility.applyAll();
+    }
+
+    Timer {
+        id: startupApply
+        interval: 1200
+        onTriggered: {
+            root.startupApplied = true;
+            root.applyAll();
+        }
+    }
+
+    Connections {
+        target: DesktopPreferences
+        function onRevisionChanged(): void { applyCoalesce.restart(); }
+    }
+
+    Timer {
+        id: applyCoalesce
+        interval: 180
+        onTriggered: root.applyAll()
+    }
+
+    function ensureStarted(): void {
+        if (!root.catalogLoaded && !root.scanning)
+            root.refreshCatalog();
+        if (!root.startupApplied && !startupApply.running)
+            startupApply.restart();
+    }
+
+    function refreshCatalog(): void {
+        if (catalogProcess.running)
+            return;
+        root.scanning = true;
+        catalogProcess.exec([root.helperPath]);
+    }
+
+    function acceptCatalog(text: string): void {
+        try {
+            const parsed = JSON.parse(text);
+            if (!parsed || !Array.isArray(parsed.cursorThemes) || !Array.isArray(parsed.iconThemes))
+                throw new Error("invalid catalog shape");
+
+            const cursors = parsed.cursorThemes.filter(name =>
+                typeof name === "string" && PreferenceSchema.coerce("cursorTheme", name) !== undefined);
+            const icons = parsed.iconThemes.filter(name =>
+                typeof name === "string" && PreferenceSchema.coerce("iconTheme", name) !== undefined);
+            root.cursorThemeNames = cursors;
+            root.iconThemeNames = icons;
+            root.cursorThemes = cursors.map(name => ({
+                value: name,
+                label: name,
+                detail: "Pointer theme"
+            }));
+            root.iconThemes = icons.map(name => ({
+                value: name,
+                label: name,
+                detail: "Application icon theme"
+            }));
+            root.catalogLoaded = true;
+            root.lastError = "";
+        } catch (error) {
+            root.cursorThemes = [];
+            root.iconThemes = [];
+            root.cursorThemeNames = [];
+            root.iconThemeNames = [];
+            root.catalogLoaded = false;
+            root.lastError = "Installed icon and pointer themes could not be read.";
+        }
+        root.scanning = false;
+    }
+
+    function drain(): void {
+        if (runner.running || root.pending.length === 0)
+            return;
+        const next = root.pending[0];
+        root.pending = root.pending.slice(1);
+        runner.exec(next);
+    }
+
+    function enqueue(commands: var): void {
+        // A fresh revision supersedes commands that have not started yet. The
+        // currently running command is allowed to finish, then the newest full
+        // state is replayed in a deterministic order.
+        root.pending = commands;
+        root.drain();
+    }
+
+    // GVariant accepts JSON-style quoted strings. JSON.stringify escapes every
+    // quote, backslash, and control character, and the schema patterns further
+    // constrain stored font/theme names. Arguments still travel directly to
+    // gsettings rather than through a shell.
+    function gvariant(value: var): string {
+        if (typeof value === "boolean")
+            return value ? "true" : "false";
+        if (typeof value === "number")
+            return String(value);
+        return JSON.stringify(String(value));
+    }
+
+    function fontName(familyKey: string, sizeKey: string): string {
+        return `${DesktopPreferences.get(familyKey)} ${DesktopPreferences.get(sizeKey)}`;
+    }
+
+    function buttonLayout(): string {
+        const side = DesktopPreferences.get("titlebarButtonSide");
+        const maximize = DesktopPreferences.get("titlebarMaximizeButton") === true;
+
+        // Tokens are fixed. Only their side and whether maximize is present
+        // vary, so preference data can never become command syntax.
+        if (side === "left")
+            return (maximize ? "close,maximize" : "close") + ":appmenu";
+        return "appmenu:" + (maximize ? "maximize,close" : "close");
+    }
+
+    function setting(schema: string, key: string, value: var): var {
+        return ["gsettings", "set", schema, key, root.gvariant(value)];
+    }
+
+    function applyAll(): void {
+        root.lastError = "";
+        root.enqueue([
+            root.setting("org.gnome.desktop.interface", "icon-theme", root.iconTheme),
+            root.setting("org.gnome.desktop.interface", "cursor-theme", root.cursorTheme),
+            root.setting("org.gnome.desktop.interface", "font-name",
+                         root.fontName("applicationFont", "applicationFontSize")),
+            root.setting("org.gnome.desktop.interface", "document-font-name",
+                         root.fontName("documentFont", "documentFontSize")),
+            root.setting("org.gnome.desktop.interface", "monospace-font-name",
+                         root.fontName("monospaceFont", "monospaceFontSize")),
+            root.setting("org.gnome.desktop.interface", "font-hinting",
+                         DesktopPreferences.get("fontHinting")),
+            root.setting("org.gnome.desktop.interface", "font-antialiasing",
+                         DesktopPreferences.get("fontAntialiasing")),
+            root.setting("org.gnome.desktop.interface", "gtk-enable-primary-paste",
+                         DesktopPreferences.get("middleClickPaste")),
+            root.setting("org.gnome.desktop.wm.preferences", "button-layout", root.buttonLayout()),
+            root.setting("org.gnome.desktop.wm.preferences", "action-double-click-titlebar",
+                         DesktopPreferences.get("titlebarDoubleClick"))
+        ]);
+    }
+
+    function storeCatalogChoice(key: string, value: string, allowed: var, kind: string): bool {
+        if (!root.catalogLoaded || allowed.indexOf(value) < 0) {
+            root.lastError = `That ${kind} theme is not installed.`;
+            return false;
+        }
+        if (!DesktopPreferences.set(key, value)) {
+            root.lastError = `That ${kind} theme name could not be saved.`;
+            return false;
+        }
+        root.lastError = "";
+        return true;
+    }
+
+    function setCursorTheme(value: string): bool {
+        return root.storeCatalogChoice("cursorTheme", value, root.cursorThemeNames, "pointer");
+    }
+
+    function setIconTheme(value: string): bool {
+        return root.storeCatalogChoice("iconTheme", value, root.iconThemeNames, "icon");
+    }
+
+    function storeFont(key: string, family: string, allowed: var, kind: string): bool {
+        if (allowed.indexOf(family) < 0) {
+            root.lastError = `That ${kind} font is not installed.`;
+            return false;
+        }
+        if (!DesktopPreferences.set(key, family)) {
+            root.lastError = `That ${kind} font name could not be saved.`;
+            return false;
+        }
+        root.lastError = "";
+        return true;
+    }
+
+    function setApplicationFont(family: string): bool {
+        return root.storeFont("applicationFont", family, Fonts.interfaceFonts, "application");
+    }
+
+    function setDocumentFont(family: string): bool {
+        return root.storeFont("documentFont", family, Fonts.interfaceFonts, "document");
+    }
+
+    function setMonospaceFont(family: string): bool {
+        return root.storeFont("monospaceFont", family, Fonts.monospaceFonts, "monospace");
+    }
+}

config/dot/quickshell/services/SettingsSearch.qml

@@ -17,12 +17,20 @@ import qs.config
 Singleton {
     id: root
 
+    // SettingsSearch is part of the always-constructed sidebar. Touching the
+    // desktop-style service here gives application preferences their startup
+    // replay even when Appearance is not the page that opens first.
+    Component.onCompleted: DesktopStyle.ensureStarted()
+
     // Which page shows the settings in a given schema group. A group with no
     // entry here still appears in results and routes to Home rather than being
     // dropped, so adding a group can never make a setting unreachable.
     readonly property var groupPages: ({
         "clock": "appearance",
         "vitals": "appearance",
+        "typography": "appearance",
+        "themes": "appearance",
+        "titlebar": "appearance",
         "windows": "appearance",
         "effects": "appearance",
         "wallpaper": "appearance",
@@ -36,6 +44,9 @@ Singleton {
         "pointer": "mouse",
         "touchpad": "mouse",
         "multitasking": "desktop",
+        "edges": "desktop",
+        "master": "desktop",
+        "notices": "desktop",
         "weather": "appearance",
         "notifications": "notifications",
         "capture": "screen-intelligence"

config/dot/quickshell/services/SystemSettings.qml

@@ -273,6 +273,15 @@ Singleton {
     // decides, and config/dot/hypr/prefs.lua does the same conversion via
     // prefs.getInt so both sides agree.
     function hyprValue(entry: var, value: var): var {
+        // Some options are phrased as a negative by the compositor -- the four
+        // Hyprland notices are all `disable_x` -- while the setting reads as
+        // "show x", because a switch labelled "Disable splash text" that must
+        // be ON to hide something is a small cruelty. `invert` bridges the two,
+        // in exactly one place, so nothing downstream has to remember which
+        // options are backwards.
+        if (entry.hypr.invert === true && typeof value === "boolean")
+            value = !value;
+
         if (typeof value === "boolean" && entry.hypr.readAs !== "bool")
             return value ? 1 : 0;
         return value;
@@ -300,6 +309,24 @@ Singleton {
             return value ? "true" : "false";
         if (typeof value === "number")
             return String(value);
+
+        // A gradient is the one setting whose Lua form is not a scalar. The
+        // stubs declare it as `string|{colors:string[], angle?:number}`, and
+        // the string form only ever carries ONE stop -- writing
+        // "rgba(a) rgba(b) 45deg" as a string is accepted and silently keeps
+        // the previous value, which is how a two-stop write looks like it
+        // worked and did nothing. Multi-stop must be the table form.
+        if (value && typeof value === "object" && Array.isArray(value.colors)) {
+            const stops = value.colors
+                .map(stop => `"${String(stop).replace(/["\\]/g, "")}"`)
+                .join(", ");
+            const angle = Number(value.angle);
+            return `{ colors = { ${stops} }` + (isFinite(angle) ? `, angle = ${angle} }` : ` }`);
+        }
+
+        // A vec2 reaches Lua as a two-element table.
+        if (Array.isArray(value) && value.length === 2)
+            return `{ ${Number(value[0])}, ${Number(value[1])} }`;
         // Strings only reach here after the schema's pattern check; quoting is
         // belt-and-braces rather than the primary defence.
         return `"${String(value).replace(/["\\]/g, "")}"`;
@@ -309,7 +336,15 @@ Singleton {
         const parts = [];
         for (const name in node) {
             const child = node[name];
-            parts.push(`${name} = ${typeof child === "string" ? child : root.serialiseTable(child)}`);
+            // A leaf arrives pre-serialised as a string; anything else is
+            // either a nested section or a structured value (gradient, vec2)
+            // that serialiseValue knows how to render.
+            const rendered = typeof child === "string"
+                ? child
+                : (Array.isArray(child) || (child && child.colors !== undefined)
+                    ? root.serialiseValue(child)
+                    : root.serialiseTable(child));
+            parts.push(`${name} = ${rendered}`);
         }
         return `{ ${parts.join(", ")} }`;
     }
@@ -353,6 +388,59 @@ Singleton {
         root.drainQueue();
     }
 
+    // Gradients are written in one notation and read back in another, so they
+    // cannot be compared directly the way every other type can.
+    //
+    //   written:  { colors = { "rgba(3b426199)" }, angle = 45 }
+    //   read:     "993b4261 45deg"
+    //
+    // The stops swap to AARRGGBB order, lose their wrapper, and the angle is
+    // always appended even when it was never given. Comparing the raw strings
+    // reports every gradient write as rejected, which is what would have
+    // happened had this been added with readAs: "str".
+    function gradientMatches(expected: var, observed: string): bool {
+        if (typeof observed !== "string")
+            return false;
+        return root.normaliseGradient(expected) === root.normaliseGradient(observed);
+    }
+
+    // Both notations reduced to "aarrggbb aarrggbb Ndeg".
+    function normaliseGradient(value: var): string {
+        const stops = [];
+        let angle = 0;
+
+        const readStop = function (text: string): void {
+            const rgba = String(text).match(/rgba?\(\s*([0-9a-fA-F]{6,8})\s*\)/);
+            if (rgba) {
+                let hex = rgba[1].toLowerCase();
+                // rgb() has no alpha; the compositor reports it as fully opaque.
+                if (hex.length === 6)
+                    hex = hex + "ff";
+                // RRGGBBAA in, AARRGGBB out.
+                stops.push(hex.slice(6, 8) + hex.slice(0, 6));
+                return;
+            }
+            const bare = String(text).match(/^([0-9a-fA-F]{8})$/);
+            if (bare) {
+                stops.push(bare[1].toLowerCase());
+                return;
+            }
+            const deg = String(text).match(/^(-?[0-9.]+)deg$/);
+            if (deg)
+                angle = Number(deg[1]);
+        };
+
+        if (value && typeof value === "object" && Array.isArray(value.colors)) {
+            value.colors.forEach(readStop);
+            if (value.angle !== undefined && isFinite(Number(value.angle)))
+                angle = Number(value.angle);
+        } else {
+            String(value).trim().split(/\s+/).forEach(readStop);
+        }
+
+        return stops.join(" ") + " " + angle + "deg";
+    }
+
     function matchesObserved(entry: var, value: var, answer: var): bool {
         if (!answer)
             return false;
@@ -370,6 +458,12 @@ Singleton {
         case "css":
             // Gaps read back as a box, e.g. "10 10 10 10".
             return Number(String(answer.css).trim().split(/\s+/)[0]) === expected;
+        case "gradient":
+            return root.gradientMatches(expected, answer.gradient);
+        case "vec2":
+            return Array.isArray(answer.vec2) && Array.isArray(expected)
+                && Number(answer.vec2[0]) === Number(expected[0])
+                && Number(answer.vec2[1]) === Number(expected[1]);
         }
         return false;
     }

config/dot/quickshell/shell.qml

@@ -165,6 +165,23 @@ ShellRoot {
         function repair(id: string): bool { return Health.repair(id, true); }
     }
 
+    // Health checks the wallpaper service through the same typed IPC boundary
+    // as capture and clipboard. This is deliberately read-only: choosing an
+    // image remains an explicit Settings action.
+    IpcHandler {
+        target: "wallpaper"
+
+        function refresh(): void { Wallpaper.refreshActive(); }
+        function status(): string {
+            return JSON.stringify({
+                active: Wallpaper.active,
+                configured: Wallpaper.configured,
+                availableCount: Wallpaper.available.length,
+                lastError: Wallpaper.lastError
+            });
+        }
+    }
+
     // A small diagnostics surface doubles as a deterministic contract harness.
     // Real producers call StatusEvents.publish() directly; fixtures never run
     // unless explicitly requested over IPC by the test suite.

tests/quickshell/applications-settings-contract.sh

@@ -33,6 +33,9 @@ done
 assert_contains 'title: "Default applications"'
 assert_contains 'title: "User autostart"'
 assert_contains 'title: "Compositor autostart"'
+assert_contains 'AutostartAppPicker {'
+assert_contains 'DefaultApps.addAutostart('
+assert_contains 'label: "Add an application"'
 assert_contains 'categories'
 assert_contains 'genericName'
 assert_contains '.sort('
@@ -123,4 +126,14 @@ fi
 [[ "$(rg --count 'activatable:' "$page")" -ge 2 ]] \
     || fail 'default and autostart rows are not both whole-row activatable'
 
+picker="$project_root/config/dot/quickshell/modules/settings/AutostartAppPicker.qml"
+qmldir="$project_root/config/dot/quickshell/modules/settings/qmldir"
+[[ -f "$picker" ]] || fail 'autostart application picker is missing'
+rg -Fq 'required property var existing' "$picker" \
+    || fail 'autostart picker cannot exclude existing entries'
+rg -Fq 'signal picked(string id)' "$picker" \
+    || fail 'autostart picker does not emit a validated desktop id'
+rg -q '^AutostartAppPicker 1\.0 AutostartAppPicker\.qml$' "$qmldir" \
+    || fail 'autostart picker is not registered in the Settings module'
+
 printf 'applications settings contract: PASS\n'

tests/quickshell/default-apps-contract.sh

@@ -29,6 +29,7 @@ assert_service_contains 'property string lastError'
 assert_service_contains 'function refresh(): void'
 assert_service_contains 'function setDefault(role: string, desktopId: string): void'
 assert_service_contains 'function setAutostart(desktopId: string, enabled: bool): void'
+assert_service_contains 'function addAutostart(desktopId: string): void'
 assert_service_contains 'DesktopEntries.applications.values'
 if rg --quiet 'command\s*:\s*"' "$service"; then
     fail 'Process command must be an argument array'
@@ -227,4 +228,27 @@ if $helper set-autostart 'hyprland:1' false >/dev/null 2>&1; then
     fail 'read-only compositor entry was accepted for mutation'
 fi
 
+$helper add-autostart org.mozilla.firefox.desktop
+firefox_autostart="$config_home/autostart/org.mozilla.firefox.desktop"
+[[ -f "$firefox_autostart" && ! -L "$firefox_autostart" ]] \
+    || fail 'adding an installed application did not create a regular user autostart entry'
+rg --quiet '^Name=Firefox$' "$firefox_autostart" \
+    || fail 'adding an application did not preserve its desktop entry'
+rg --quiet '^Hidden=false$' "$firefox_autostart" \
+    || fail 'a newly added application was not enabled'
+[[ "$(rg --count '^Hidden=' "$firefox_autostart")" == "1" ]] \
+    || fail 'adding an application wrote more than one Hidden key'
+
+$helper set-autostart org.mozilla.firefox.desktop false
+$helper add-autostart org.mozilla.firefox.desktop
+rg --quiet '^Hidden=false$' "$firefox_autostart" \
+    || fail 'adding an existing disabled application did not re-enable it'
+
+if $helper add-autostart org.example.Missing.desktop >/dev/null 2>&1; then
+    fail 'an undiscovered application was accepted for autostart'
+fi
+if $helper add-autostart ../escape.desktop >/dev/null 2>&1; then
+    fail 'an unsafe desktop id was accepted for autostart'
+fi
+
 printf 'default apps contract: PASS\n'

tests/quickshell/desktop-style-contract.sh

@@ -0,0 +1,210 @@
+#!/usr/bin/env bash
+
+# Desktop style stays split across three boundaries that can all be checked
+# without starting the shell: the read-only icon catalog, the preference/schema
+# wiring, and the QML surfaces that consume it. The catalog runs only against
+# disposable XDG roots so this contract never reads or changes the live desktop.
+
+set -euo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+helper="$repo_dir/config/dot/quickshell/scripts/panama-desktop-style"
+service="$repo_dir/config/dot/quickshell/services/DesktopStyle.qml"
+schema="$repo_dir/config/dot/quickshell/config/PreferenceSchema.qml"
+appearance="$repo_dir/config/dot/quickshell/modules/settings/AppearancePage.qml"
+mouse="$repo_dir/config/dot/quickshell/modules/settings/MousePage.qml"
+accessibility="$repo_dir/config/dot/quickshell/services/Accessibility.qml"
+search="$repo_dir/config/dot/quickshell/services/SettingsSearch.qml"
+env_lua="$repo_dir/config/dot/hypr/env.lua"
+looks_lua="$repo_dir/config/dot/hypr/looks.lua"
+
+fail() {
+    printf 'desktop style contract: %s\n' "$1" >&2
+    exit 1
+}
+
+for file in "$helper" "$service" "$schema" "$appearance" "$mouse" \
+    "$accessibility" "$search" "$env_lua" "$looks_lua"; do
+    [[ -f "$file" ]] || fail "missing ${file#"$repo_dir/"}"
+done
+[[ -x "$helper" ]] || fail 'desktop-style catalog is not executable'
+
+# ── Read-only catalog semantics ─────────────────────────────────────────────
+fixture="$(mktemp -d /tmp/panama-desktop-style.XXXXXX)"
+trap 'rm -rf "$fixture"' EXIT
+
+home="$fixture/home"
+data_home="$fixture/data-home"
+data_one="$fixture/data-one"
+data_two="$fixture/data-two"
+mkdir -p "$home" \
+    "$data_home/icons/CursorOnly/cursors" \
+    "$data_one/icons/IconOnly/16x16/apps" \
+    "$data_one/icons/Both/cursors" \
+    "$data_one/icons/Both/scalable/apps" \
+    "$data_one/icons/EmptyDirectories" \
+    "$data_two/icons/Both/cursors" \
+    "$data_two/icons/Both/scalable/apps" \
+    "$data_two/icons/NoIndex/16x16/apps"
+
+cat >"$data_home/icons/CursorOnly/index.theme" <<'EOF'
+[Icon Theme]
+Name=Cursor only
+Directories=
+EOF
+cat >"$data_one/icons/IconOnly/index.theme" <<'EOF'
+[Icon Theme]
+Name=Icon only
+Directories=16x16/apps
+EOF
+cat >"$data_one/icons/Both/index.theme" <<'EOF'
+[Icon Theme]
+Name=Both
+Directories=scalable/apps
+EOF
+cat >"$data_one/icons/EmptyDirectories/index.theme" <<'EOF'
+[Icon Theme]
+Name=Not an icon catalog entry
+Directories=
+EOF
+cp "$data_one/icons/Both/index.theme" "$data_two/icons/Both/index.theme"
+
+catalog="$(
+    HOME="$home" \
+    XDG_DATA_HOME="$data_home" \
+    XDG_DATA_DIRS="$data_one:$data_two" \
+        "$helper"
+)" || fail 'catalog helper failed against disposable XDG roots'
+
+jq -e '
+    type == "object"
+    and (keys | sort) == ["cursorThemes", "iconThemes"]
+    and .cursorThemes == ["Both", "CursorOnly"]
+    and .iconThemes == ["Both", "IconOnly"]
+    and (all(.cursorThemes[]; type == "string" and length > 0))
+    and (all(.iconThemes[]; type == "string" and length > 0))
+' <<<"$catalog" >/dev/null \
+    || fail "catalog JSON shape or theme classification is wrong: $catalog"
+
+if HOME="$home" XDG_DATA_HOME="$data_home" XDG_DATA_DIRS="$data_one:$data_two" \
+    "$helper" "$fixture/not-an-xdg-root" >/dev/null 2>&1; then
+    fail 'catalog accepted a caller-supplied path'
+fi
+
+# ── Schema, compositor replay, service, and UI wiring ───────────────────────
+python3 - "$schema" <<'PY' || fail 'desktop-style schema entries are missing or malformed'
+import re
+import sys
+
+text = open(sys.argv[1], encoding="utf-8").read()
+
+expected = {
+    "cursorTheme": ("string", '"oreo_blue_cursors"', "themes"),
+    "iconTheme": ("string", '"Adwaita"', "themes"),
+    "applicationFont": ("string", '"Adwaita Sans"', "typography"),
+    "applicationFontSize": ("int", "11", "typography"),
+    "documentFont": ("string", '"Adwaita Sans"', "typography"),
+    "documentFontSize": ("int", "12", "typography"),
+    "monospaceFont": ("string", '"VictorMono Nerd Font"', "typography"),
+    "monospaceFontSize": ("int", "10", "typography"),
+    "fontHinting": ("enum", '"slight"', "typography"),
+    "fontAntialiasing": ("enum", '"rgba"', "typography"),
+    "titlebarButtonSide": ("enum", '"right"', "titlebar"),
+    "titlebarMaximizeButton": ("bool", "false", "titlebar"),
+    "titlebarDoubleClick": ("enum", '"toggle-maximize"', "titlebar"),
+    "middleClickPaste": ("bool", "true", "pointer"),
+}
+
+def block_for(key: str) -> str:
+    match = re.search(r"\{\s*\n\s*key:\s*\"" + re.escape(key) + r"\".*?\n\s{8}\}", text, re.S)
+    if not match:
+        raise SystemExit(f"missing {key}")
+    return match.group(0)
+
+for key, (kind, default, group) in expected.items():
+    block = block_for(key)
+    if not re.search(rf'type:\s*"{re.escape(kind)}"', block):
+        raise SystemExit(f"{key} has wrong type")
+    if not re.search(rf'def:\s*{re.escape(default)}', block):
+        raise SystemExit(f"{key} has wrong default")
+    if not re.search(rf'group:\s*"{re.escape(group)}"', block):
+        raise SystemExit(f"{key} has wrong group")
+
+enum_values = {
+    "fontHinting": ["none", "slight", "medium", "full"],
+    "fontAntialiasing": ["none", "grayscale", "rgba"],
+    "titlebarButtonSide": ["left", "right"],
+    "titlebarDoubleClick": ["toggle-maximize", "none"],
+}
+for key, values in enum_values.items():
+    block = block_for(key)
+    actual = re.findall(r'value:\s*"([^"]+)"', block)
+    if actual != values:
+        raise SystemExit(f"{key} options are {actual}, expected {values}")
+
+middle = block_for("middleClickPaste")
+for fragment in (
+    'path: ["misc", "middle_click_paste"]',
+    'option: "misc:middle_click_paste"',
+    'readAs: "bool"',
+):
+    if fragment not in middle:
+        raise SystemExit(f"middleClickPaste is missing {fragment}")
+PY
+
+rg -q 'prefs\.get\("cursorTheme", "oreo_blue_cursors"\)' "$env_lua" \
+    || fail 'Hyprland environment does not replay cursorTheme'
+rg -q 'middle_click_paste\s*=\s*prefs\.get\("middleClickPaste", true\)' "$looks_lua" \
+    || fail 'Hyprland misc does not replay middleClickPaste'
+
+rg -q 'DesktopPreferences\.get\("cursorTheme"\)' "$accessibility" \
+    || fail 'Accessibility does not use the stored cursor theme'
+! rg -q 'gsettings.*cursor-theme|themeQuery' "$accessibility" \
+    || fail 'Accessibility still queries cursor-theme from gsettings'
+
+for needle in \
+    'property var cursorThemes' \
+    'property var iconThemes' \
+    'DesktopPreferences.revision' \
+    'Fonts.interfaceFonts' \
+    'Fonts.monospaceFonts' \
+    'gtk-enable-primary-paste' \
+    'button-layout' \
+    'action-double-click-titlebar'; do
+    rg -Fq "$needle" "$service" || fail "DesktopStyle is missing $needle"
+done
+! rg -q 'sh -c|bash -c' "$service" \
+    || fail 'DesktopStyle routes gsettings through a shell'
+
+for group in typography themes titlebar; do
+    rg -q "\"$group\": \"appearance\"" "$search" \
+        || fail "settings search does not route $group to Appearance"
+done
+rg -q '"pointer": "mouse"' "$search" \
+    || fail 'settings search no longer routes pointer controls to Mouse'
+
+for needle in \
+    'title: "Application typography"' \
+    'setting: "applicationFontSize"' \
+    'setting: "documentFontSize"' \
+    'setting: "monospaceFontSize"' \
+    'setting: "fontHinting"' \
+    'setting: "fontAntialiasing"' \
+    'title: "Icons & pointer"' \
+    'DesktopStyle.cursorThemes' \
+    'DesktopStyle.iconThemes' \
+    'title: "Titlebars"' \
+    'setting: "titlebarButtonSide"' \
+    'setting: "titlebarMaximizeButton"' \
+    'setting: "titlebarDoubleClick"'; do
+    rg -Fq "$needle" "$appearance" || fail "Appearance is missing $needle"
+done
+! rg -q 'setting: "titlebarMinimize|GTK theme|Shell theme' "$appearance" \
+    || fail 'Appearance exposes an inert or separately-owned theme control'
+
+rg -q 'setting: "middleClickPaste"' "$mouse" \
+    || fail 'Mouse does not expose middle-click paste'
+rg -q 'GTK.*Wayland|Wayland.*GTK' "$mouse" \
+    || fail 'Mouse does not explain the GTK and Wayland scope honestly'
+
+printf 'desktop style contract: PASS\n'

tests/quickshell/fixtures/doctor/bin/qs

@@ -4,6 +4,13 @@ set -euo pipefail
 
 case "${1:-}" in
     --version) printf '%s\n' "${PANAMA_DOCTOR_FIXTURE_QS_VERSION:-Quickshell 0.2.0}" ;;
+    list)
+        case ",${PANAMA_DOCTOR_FIXTURE_PROCESSES:-}," in
+            *,qs:duplicate,*) printf '%s\n' 'Instance fixture-one:' 'Instance fixture-two:' ;;
+            *,qs:missing,*) ;;
+            *) printf '%s\n' 'Instance fixture-one:' ;;
+        esac
+        ;;
     ipc)
         if [[ "${PANAMA_DOCTOR_FIXTURE_QS:-ready}" == "malformed" ]]; then
             printf 'fixture-secret-token AA:BB:CC:DD:EE:FF\n'

tests/quickshell/health-service-contract.sh

@@ -47,6 +47,8 @@ fail() {
 [[ -f "$service" ]] || fail 'Health.qml is missing'
 [[ -f "$source_harness" ]] || fail 'health harness is missing'
 [[ -f "$shell" ]] || fail 'shell.qml is missing'
+rg -q 'target: "wallpaper"' "$shell" \
+    || fail 'wallpaper health target is not exported by the shell'
 
 # shell.qml is not started here: it is the active desktop shell. Keep this
 # contract static while pinning the typed, redacted IPC boundary it exports.

tests/quickshell/panama-doctor-contract.sh

@@ -216,11 +216,14 @@ jq -e '.checks[] | select(.id == "panama.caffeine")
     || fail 'Caffeine detail exposed inhibitor PIDs'
 
 # Process counts use only exact authored names and never expose command lines or PIDs.
-duplicated_processes="$(PANAMA_DOCTOR_FIXTURE_PROCESSES=quickshell:duplicate run_doctor --json)"
+duplicated_processes="$(PANAMA_DOCTOR_FIXTURE_PROCESSES=qs:duplicate run_doctor --json)"
 check_status "$duplicated_processes" panama.processes warning
 ! jq -r '.checks[] | select(.id == "panama.processes") | .detail' <<<"$duplicated_processes" | grep -Eq '[0-9]{3,}' \
     || fail 'process detail exposed a PID'
 
+missing_quickshell_process="$(PANAMA_DOCTOR_FIXTURE_PROCESSES=qs:missing run_doctor --json)"
+check_status "$missing_quickshell_process" panama.processes error
+
 # Invalid output for a non-Quickshell authored process is not a normal zero
 # count that can be hidden by the running Quickshell process.
 malformed_processes="$(PANAMA_DOCTOR_FIXTURE_PROCESSES=hyprpaper:malformed run_doctor --json)"

tests/quickshell/settings-ownership-contract.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+
+# A setting has one schema-routed owner. A second page may mirror it only when
+# this contract names the exact owner and mirror set. The same ownership rule
+# keeps colour scheme propagation away from the focused Prism border.
+
+set -euo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+pages_dir="$repo_dir/config/dot/quickshell/modules/settings"
+schema="$repo_dir/config/dot/quickshell/config/PreferenceSchema.qml"
+search="$repo_dir/config/dot/quickshell/services/SettingsSearch.qml"
+scheme="$repo_dir/config/dot/quickshell/services/ColorScheme.qml"
+looks="$repo_dir/config/dot/hypr/looks.lua"
+readme="$pages_dir/README.md"
+
+fail() {
+    printf 'settings ownership contract: %s\n' "$1" >&2
+    exit 1
+}
+
+python3 - "$pages_dir" "$schema" "$search" <<'PY' \
+    || fail 'page ownership or intentional mirrors drifted'
+from __future__ import annotations
+
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+pages_dir = Path(sys.argv[1])
+schema_text = Path(sys.argv[2]).read_text(encoding="utf-8")
+search_text = Path(sys.argv[3]).read_text(encoding="utf-8")
+
+expected = {
+    "animationsEnabled": {"owner": "appearance", "mirrors": {"accessibility"}},
+    "cursorInactiveTimeout": {"owner": "mouse", "mirrors": {"accessibility"}},
+    "cursorSize": {"owner": "accessibility", "mirrors": {"mouse"}},
+    "inactiveOpacity": {"owner": "appearance", "mirrors": {"accessibility"}},
+    "lockMinutes": {"owner": "power", "mirrors": {"privacy"}},
+    "lockOnSleep": {"owner": "power", "mirrors": {"privacy"}},
+}
+
+
+def strip_comments(text: str) -> str:
+    return re.sub(r"//.*", "", text)
+
+
+def page_name(path: Path) -> str:
+    stem = path.stem.removesuffix("Page")
+    return re.sub(r"(?<!^)(?=[A-Z])", "-", stem).lower()
+
+
+rows: dict[str, list[str]] = defaultdict(list)
+row_pattern = re.compile(
+    r"(?:ToggleRow|SliderRow|ChoiceRow|TextEntryRow|TimeOfDayRow)\s*\{(?P<body>.*?)\}",
+    re.S,
+)
+for page_path in pages_dir.glob("*Page.qml"):
+    text = strip_comments(page_path.read_text(encoding="utf-8"))
+    for match in row_pattern.finditer(text):
+        setting = re.search(r'setting\s*:\s*"([^"]+)"', match.group("body"))
+        if setting:
+            rows[setting.group(1)].append(page_name(page_path))
+
+duplicates = {key: set(pages) for key, pages in rows.items() if len(pages) > 1}
+if set(duplicates) != set(expected):
+    raise SystemExit(
+        f"duplicate keys are {sorted(duplicates)}, expected {sorted(expected)}"
+    )
+
+group_pages = dict(re.findall(r'"([^"]+)"\s*:\s*"([^"]+)"', search_text))
+for key, policy in expected.items():
+    wanted_pages = {policy["owner"], *policy["mirrors"]}
+    if duplicates[key] != wanted_pages:
+        raise SystemExit(f"{key} appears on {sorted(duplicates[key])}, expected {sorted(wanted_pages)}")
+
+    block = re.search(
+        r'\{\s*\n\s*key:\s*"' + re.escape(key) + r'"(?P<body>.*?)\n\s*\}',
+        schema_text,
+        re.S,
+    )
+    if not block:
+        raise SystemExit(f"schema entry missing for {key}")
+    group = re.search(r'group:\s*"([^"]+)"', block.group("body"))
+    if not group:
+        raise SystemExit(f"schema group missing for {key}")
+    routed = group_pages.get(group.group(1))
+    if routed != policy["owner"]:
+        raise SystemExit(
+            f"{key} routes to {routed!r}, expected primary owner {policy['owner']!r}"
+        )
+PY
+
+for needle in \
+    '## Setting ownership' \
+    'one primary page' \
+    'Intentional mirrors' \
+    '`animationsEnabled`' \
+    '`cursorInactiveTimeout`' \
+    '`cursorSize`' \
+    '`inactiveOpacity`' \
+    '`lockMinutes`' \
+    '`lockOnSleep`' \
+    'scheme-relative role'; do
+    rg -Fq "$needle" "$readme" || fail "README is missing $needle"
+done
+
+python3 - "$scheme" "$looks" <<'PY' \
+    || fail 'scheme-relative border ownership drifted'
+import re
+import sys
+
+scheme = open(sys.argv[1], encoding="utf-8").read()
+looks = open(sys.argv[2], encoding="utf-8").read()
+
+dark = re.search(r'property string inactiveBorderDark:\s*"([^"]+)"', scheme)
+light = re.search(r'property string inactiveBorderLight:\s*"([^"]+)"', scheme)
+effective = re.search(r'property string inactiveBorder:\s*root\.dark\s*\?\s*root\.inactiveBorderDark\s*:\s*root\.inactiveBorderLight', scheme)
+if not dark or not light or not effective:
+    raise SystemExit("ColorScheme does not expose the two inactive-border roles")
+if dark.group(1) not in looks or light.group(1) not in looks:
+    raise SystemExit("Hyprland startup values disagree with the live scheme roles")
+
+without_comments = re.sub(r"//.*", "", scheme)
+if re.search(r"(?<![A-Za-z_])active_border\b", without_comments):
+    raise SystemExit("ColorScheme writes the focused border")
+if 'inactive_border = "${root.inactiveBorder}"' not in scheme:
+    raise SystemExit("ColorScheme does not apply its effective inactive role")
+PY
+
+printf 'settings ownership contract: PASS\n'

tests/quickshell/xkb-presets-contract.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+
+# Common XKB behavior should be discoverable without hiding the raw option
+# string from advanced users. This is source-only so it never remaps the live
+# keyboard while the desktop is in use.
+
+set -euo pipefail
+
+repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+page="$repo_dir/config/dot/quickshell/modules/settings/ShortcutsPage.qml"
+input="$repo_dir/config/dot/hypr/input.lua"
+schema="$repo_dir/config/dot/quickshell/config/PreferenceSchema.qml"
+
+fail() {
+    printf 'xkb presets contract: %s\n' "$1" >&2
+    exit 1
+}
+
+for needle in \
+    'function currentXkbOption(prefix: string): string' \
+    'function setXkbOption(prefix: string, option: string): void' \
+    'label: "Caps Lock"' \
+    'value: "caps:escape_shifted_capslock"' \
+    'value: "caps:ctrl_modifier"' \
+    'label: "Compose key"' \
+    'value: "compose:ralt"' \
+    'label: "Layout switching"' \
+    'value: "grp:win_space_toggle"' \
+    'SystemSettings.commitPreference("keyboardOptions"' \
+    'TextEntryRow { setting: "keyboardOptions"'; do
+    rg -Fq "$needle" "$page" || fail "Shortcuts is missing $needle"
+done
+
+# Picking one category must replace only that category, preserving advanced
+# options from every other group.
+rg -Fq 'option.indexOf(prefix) !== 0' "$page" \
+    || fail 'preset updates do not preserve unrelated XKB options'
+
+rg -Fq 'kb_variant = prefs.get("keyboardVariant", "")' "$input" \
+    || fail 'Hyprland does not replay the stored keyboard variant'
+rg -Fq 'key: "keyboardOptions", type: "string", def: "caps:escape_shifted_capslock"' "$schema" \
+    || fail 'the shipped XKB default no longer matches the migrated GNOME behavior'
+rg -Fq 'kb_options = prefs.get("keyboardOptions", "caps:escape_shifted_capslock")' "$input" \
+    || fail 'Hyprland does not replay the stored keyboard options'
+
+printf 'xkb presets contract: PASS\n'