Window(feat[select_layout]): add spread, next, and previous flags

why: select-layout supports flags for spreading panes evenly and cycling
through layouts that were not exposed in the Python API.
what:
- Add spread (-E), next_layout (-n), previous_layout (-o) parameters
- Validate mutual exclusion between layout string and flag parameters
- Add tests for spread, next/previous cycling, and mutual exclusion

Author: tony

src/libtmux/window.py

@@ -406,7 +406,14 @@ def last_pane(self) -> Pane | None:
         """Return last pane."""
         return self.select_pane("-l")
 
-    def select_layout(self, layout: str | None = None) -> Window:
+    def select_layout(
+        self,
+        layout: str | None = None,
+        *,
+        spread: bool | None = None,
+        next_layout: bool | None = None,
+        previous_layout: bool | None = None,
+    ) -> Window:
         """Select layout for window.
 
         Wrapper for ``$ tmux select-layout <layout>``.
@@ -436,6 +443,18 @@ def select_layout(self, layout: str | None = None) -> Window:
                 both rows and columns.
             'custom'
                 Custom dimensions (see :term:`tmux(1)` manpages).
+        spread : bool, optional
+            Spread panes out evenly (``-E`` flag).
+
+            .. versionadded:: 0.45
+        next_layout : bool, optional
+            Move to the next layout (``-n`` flag).
+
+            .. versionadded:: 0.45
+        previous_layout : bool, optional
+            Move to the previous layout (``-o`` flag).
+
+            .. versionadded:: 0.45
 
         Returns
         -------
@@ -446,9 +465,26 @@ def select_layout(self, layout: str | None = None) -> Window:
         ------
         :exc:`libtmux.exc.LibTmuxException`
             If tmux returns an error.
+        ValueError
+            If both *layout* and a flag (*spread*, *next_layout*,
+            *previous_layout*) are specified.
         """
+        flags = (spread, next_layout, previous_layout)
+        if layout and any(flags):
+            msg = "Cannot specify both layout and spread/next_layout/previous_layout"
+            raise ValueError(msg)
+
         cmd = ["select-layout"]
 
+        if spread:
+            cmd.append("-E")
+
+        if next_layout:
+            cmd.append("-n")
+
+        if previous_layout:
+            cmd.append("-o")
+
         if layout:  # tmux allows select-layout without args
             cmd.append(layout)
 

tests/test_window.py

@@ -770,3 +770,52 @@ def test_deprecated_window_methods_emit_warning(
 
     with pytest.warns(DeprecationWarning, match=test_case.expected_error_match):
         method(*test_case.args, **test_case.kwargs)
+
+
+def test_select_layout_spread(session: Session) -> None:
+    """Test Window.select_layout() with spread flag."""
+    window = session.new_window(window_name="test_layout_spread")
+    window.resize(height=40, width=80)
+    pane = window.active_pane
+    assert pane is not None
+    pane.split()
+    pane.split()
+    assert len(window.panes) == 3
+
+    # Spread panes evenly — verify no error
+    window.select_layout(spread=True)
+
+
+def test_select_layout_next_previous(session: Session) -> None:
+    """Test Window.select_layout() with next/previous flags."""
+    window = session.new_window(window_name="test_layout_cycle")
+    window.resize(height=40, width=80)
+    pane = window.active_pane
+    assert pane is not None
+    pane.split()
+
+    # Set a known layout
+    window.select_layout("even-horizontal")
+    window.refresh()
+    layout_before = window.window_layout
+
+    # Cycle to next layout
+    window.select_layout(next_layout=True)
+    window.refresh()
+    layout_after_next = window.window_layout
+
+    assert layout_before != layout_after_next
+
+    # Cycle back to previous
+    window.select_layout(previous_layout=True)
+    window.refresh()
+    layout_after_prev = window.window_layout
+
+    assert layout_after_prev == layout_before
+
+
+def test_select_layout_mutual_exclusion(session: Session) -> None:
+    """Test that layout string and flags are mutually exclusive."""
+    window = session.new_window(window_name="test_layout_mutex")
+    with pytest.raises(ValueError, match="Cannot specify both"):
+        window.select_layout("tiled", spread=True)