Cleanup previous PR

docs/changelog.rst

@@ -190,6 +190,12 @@ Detailed list of changes
 
 - Wayland: Fix first OS window being a few cells too small when ``initial_window_width/initial_window_height`` are set in cells and a fractional display scale is in use (:iss:`10146`)
 
+- macOS: New option :opt:`macos_ns_window_layer` to more precisely control what
+  layer panel OS windows are placed on (:pull:`10116`)
+
+- macOS: New option :opt:`macos_use_physical_screen_frame` to allow panel OS
+  Windows to cover the macOS global dock bar (:pull:`10116`)
+
 - kitty binary builds are now built on Ubuntu 22 upgraded from Ubuntu 18 for improved performance from better compilers
 
 - macOS: Fix incorrect horizontal alignment when using text sizing protocol (:iss:`10179`)

kitty/options/definition.py

@@ -2733,24 +2733,22 @@ full display frame instead of leaving space for the notch area.
 '''
     )
 
-opt('macos_use_physical_screen_frame', 'no',
-    option_type='to_bool', ctype='bool',
-    long_text='''
+opt('macos_use_physical_screen_frame', 'no', option_type='to_bool', ctype='bool', long_text='''
 Use the physical screen frame instead of the visible frame when placing macOS
 desktop panels such as those created by :code:`kitty +kitten panel`. This allows
 panels to draw in areas normally reserved for the native menu bar or Dock.
+See also :opt:`macos_ns_window_layer`.
 '''
     )
 
-opt('macos_ns_window_layer', 'unset',
-    option_type='str', ctype='!macos_ns_window_layer',
-    long_text='''
-Set the macOS NSWindow level for newly created OS windows. The default value
-:code:`unset` leaves kitty's normal window-level handling unchanged. Values can
+opt('macos_ns_window_layer', 'unset', option_type='str', ctype='!macos_ns_window_layer', long_text='''
+Set the macOS NSWindow level for newly created panel OS windows such
+as with the :doc:`panel kitten </kittens/panel>`. The default value
+:code:`unset` leaves normal level handling unchanged. Values can
 be integer window levels, AppKit/CoreGraphics window-level constant names, or
 simple arithmetic expressions combining them with integers. For example:
 :code:`NSFloatingWindowLevel`, :code:`kCGBackstopMenuLevel`,
-:code:`NSPopUpMenuWindowLevel - 1`.
+:code:`NSPopUpMenuWindowLevel - 1`. See also :macos_use_physical_screen_frame`.
 '''
     )
 

kitty/simple_cli_definitions.py

@@ -644,7 +644,9 @@ default={layer}
 On a Wayland compositor that supports the wlr layer shell protocol, specifies the layer
 on which the panel should be drawn. This parameter is ignored and set to
 :code:`background` if :option:`--edge` is set to :code:`background`. On macOS, maps
-these to appropriate NSWindow *levels*.
+these to appropriate NSWindow *levels*. Note that on macOS, you can use :opt:`macos_ns_window_layer`
+for more fine control over the layer, using the :code:`--override` flag, for example:
+:code:`--override macos_ns_window_layer=NSPopUpMenuWindowLevel`.
 
 
 --config -c