Pane(feat[capture_frame]): Add capture_frame() method

why: Enable capturing pane content as TextFrame for visualization
and snapshot testing. This bridges capture_pane() with the TextFrame
dataclass for a more ergonomic testing workflow.
what:
- Add capture_frame() method that wraps capture_pane()
- Default to pane dimensions when width/height not specified
- Default to truncate mode for robustness in CI environments
- Add comprehensive docstring with examples

Author: tony

src/libtmux/pane.py

@@ -31,6 +31,8 @@
     import types
 
     from libtmux._internal.types import StrPath
+    from libtmux.textframe import TextFrame
+    from libtmux.textframe.core import OverflowBehavior
 
     from .server import Server
     from .session import Session
@@ -357,6 +359,93 @@ def capture_pane(
             cmd.extend(["-E", str(end)])
         return self.cmd(*cmd).stdout
 
+    def capture_frame(
+        self,
+        start: t.Literal["-"] | int | None = None,
+        end: t.Literal["-"] | int | None = None,
+        *,
+        content_width: int | None = None,
+        content_height: int | None = None,
+        overflow_behavior: OverflowBehavior = "truncate",
+    ) -> TextFrame:
+        """Capture pane content as a TextFrame.
+
+        Combines :meth:`capture_pane` with :class:`~libtmux.textframe.TextFrame`
+        for visualization and snapshot testing.
+
+        Parameters
+        ----------
+        start : str | int, optional
+            Starting line number (same as :meth:`capture_pane`).
+            Zero is the first line of the visible pane.
+            Positive numbers are lines in the visible pane.
+            Negative numbers are lines in the history.
+            ``-`` is the start of the history.
+            Default: None
+        end : str | int, optional
+            Ending line number (same as :meth:`capture_pane`).
+            Zero is the first line of the visible pane.
+            Positive numbers are lines in the visible pane.
+            Negative numbers are lines in the history.
+            ``-`` is the end of the visible pane.
+            Default: None
+        content_width : int, optional
+            Frame width. Defaults to pane's current width.
+        content_height : int, optional
+            Frame height. Defaults to pane's current height.
+        overflow_behavior : OverflowBehavior, optional
+            How to handle content that exceeds frame dimensions.
+            Defaults to ``"truncate"`` since pane content may exceed
+            nominal dimensions during terminal transitions.
+
+        Returns
+        -------
+        :class:`~libtmux.textframe.TextFrame`
+            Frame containing captured pane content.
+
+        Examples
+        --------
+        >>> pane.send_keys('echo "Hello"', enter=True)
+        >>> import time; time.sleep(0.1)
+        >>> frame = pane.capture_frame(content_width=20, content_height=5)
+        >>> 'Hello' in frame.render()
+        True
+
+        >>> print(frame.render())  # doctest: +SKIP
+        +--------------------+
+        |$ echo "Hello"      |
+        |Hello               |
+        |$                   |
+        |                    |
+        |                    |
+        +--------------------+
+        """
+        from libtmux.textframe import TextFrame as TextFrameClass
+
+        # Capture content
+        lines = self.capture_pane(start=start, end=end)
+
+        # Use pane dimensions if not specified
+        self.refresh()
+        width = (
+            content_width if content_width is not None else int(self.pane_width or 80)
+        )
+        height = (
+            content_height
+            if content_height is not None
+            else int(self.pane_height or 24)
+        )
+
+        # Create and populate frame
+        frame = TextFrameClass(
+            content_width=width,
+            content_height=height,
+            overflow_behavior=overflow_behavior,
+        )
+        frame.set_content(lines)
+
+        return frame
+
     def send_keys(
         self,
         cmd: str,