From 883d8554f30037e7bd512c76bc766a8732b74d93 Mon Sep 17 00:00:00 2001
From: Ryan Hughes <ryan@heyoodle.com>
Date: Thu, 14 May 2026 16:34:32 -0400
Subject: [PATCH] Polish first-party shell plugin docs, Hyprland rules, and
 bar-position seed

  - omarchy-bar-settings.lua is gone: the Hyprland rules it carried for
    the old standalone bar-settings window no longer match anything,
    since settings is now a panel plugin summoned via IPC. The still-
    needed "Widget settings" sub-dialog rules move into
    omarchy-shell.lua next to the existing "Omarchy Settings" rules.

  - plugins README documents the `bar` plugin kind so third-party
    plugin authors aren't surprised to see it on the first-party
    omarchy.bar manifest. The note also calls out that they should ship
    `bar-widget`s, not replace the host bar.

  - omarchy-style-bar-position seeds from shell-defaults.json before
    mutating, so a user without a shell.json (or with a malformed one)
    no longer ends up with a stub config that blanks the bar layout.
---
 bin/omarchy-style-bar-position             | 19 +++++++++++++------
 default/hypr/apps/omarchy-bar-settings.lua |  4 ----
 default/hypr/apps/omarchy-shell.lua        |  5 +++++
 default/quickshell/omarchy-shell/README.md |  1 +
 4 files changed, 19 insertions(+), 10 deletions(-)
 delete mode 100644 default/hypr/apps/omarchy-bar-settings.lua

diff --git a/bin/omarchy-style-bar-position b/bin/omarchy-style-bar-position
index af3a83e2..2ef44675 100755
--- a/bin/omarchy-style-bar-position
+++ b/bin/omarchy-style-bar-position
@@ -7,6 +7,7 @@
 set -e
 
 CONFIG_FILE="$HOME/.config/omarchy/shell.json"
+DEFAULTS_FILE="${OMARCHY_PATH:-$HOME/.local/share/omarchy}/default/quickshell/omarchy-shell/shell-defaults.json"
 position=$1
 
 if [[ ! $position =~ ^(top|bottom|left|right)$ ]]; then
@@ -17,14 +18,20 @@ fi
 mkdir -p "$(dirname "$CONFIG_FILE")"
 tmp=$(mktemp)
 
+# Seed from shell-defaults.json when the user has no shell.json yet (or it's
+# malformed). Writing just `{ bar: { position } }` would leave the bar with
+# no layout, since the shell treats any valid user config as authoritative
+# and does not deep-merge defaults.
 if [[ -s $CONFIG_FILE ]] && jq -e 'type == "object"' "$CONFIG_FILE" >/dev/null 2>&1; then
-  jq --arg position "$position" '
-    .version = 1 |
-    .bar = ((.bar // {}) | if type == "object" then . else {} end) |
-    .bar.position = $position
-  ' "$CONFIG_FILE" >"$tmp"
+  source="$CONFIG_FILE"
 else
-  jq -n --arg position "$position" '{ version: 1, bar: { position: $position } }' >"$tmp"
+  source="$DEFAULTS_FILE"
 fi
 
+jq --arg position "$position" '
+  .version = 1 |
+  .bar = ((.bar // {}) | if type == "object" then . else {} end) |
+  .bar.position = $position
+' "$source" >"$tmp"
+
 mv "$tmp" "$CONFIG_FILE"
diff --git a/default/hypr/apps/omarchy-bar-settings.lua b/default/hypr/apps/omarchy-bar-settings.lua
deleted file mode 100644
index 22728d23..00000000
--- a/default/hypr/apps/omarchy-bar-settings.lua
+++ /dev/null
@@ -1,4 +0,0 @@
-hl.window_rule({ match = { title = "^Omarchy bar settings$" }, tag = "+floating-window" })
-hl.window_rule({ match = { title = "^Omarchy bar settings$" }, size = { 720, 720 } })
-hl.window_rule({ match = { title = "^Widget settings " }, tag = "+floating-window" })
-hl.window_rule({ match = { title = "^Widget settings " }, size = { 380, 320 } })
diff --git a/default/hypr/apps/omarchy-shell.lua b/default/hypr/apps/omarchy-shell.lua
index 2623aab9..76576db6 100644
--- a/default/hypr/apps/omarchy-shell.lua
+++ b/default/hypr/apps/omarchy-shell.lua
@@ -13,3 +13,8 @@ hl.layer_rule({ match = { namespace = "omarchy-image-selector" }, no_anim = true
 hl.window_rule({ match = { class = "^org.quickshell$", title = "^Omarchy Settings$" }, float = true })
 hl.window_rule({ match = { class = "^org.quickshell$", title = "^Omarchy Settings$" }, center = true })
 hl.window_rule({ match = { class = "^org.quickshell$", title = "^Omarchy Settings$" }, size = { 960, 700 } })
+
+-- Per-widget settings dialog opens as a smaller FloatingWindow off the
+-- settings panel; keep it floating with its own default size.
+hl.window_rule({ match = { class = "^org.quickshell$", title = "^Widget settings " }, float = true })
+hl.window_rule({ match = { class = "^org.quickshell$", title = "^Widget settings " }, size = { 380, 320 } })
diff --git a/default/quickshell/omarchy-shell/README.md b/default/quickshell/omarchy-shell/README.md
index 1c40b759..947af156 100644
--- a/default/quickshell/omarchy-shell/README.md
+++ b/default/quickshell/omarchy-shell/README.md
@@ -72,6 +72,7 @@ Supported `kinds`:
 | `overlay`    | A fullscreen overlay (e.g. background switcher)              |
 | `menu`       | A summoned menu surface                                      |
 | `service`    | A headless singleton, no UI                                  |
+| `bar`        | Reserved for the first-party bar host (`omarchy.bar`). Third-party plugins should ship `bar-widget`s; they do not replace the host bar. |
 
 `activation` is either `persistent` (loaded on startup, never unloaded) or
 `on-demand` (loaded by `shell summon <id>` and unloaded by `shell hide`).