Use waiter 2.0

.cursor/rules/dev-loop.mdc

@@ -16,7 +16,7 @@ uv run mypy
 Lint:
 
 ```
-uv run ruff check . --fix; uv run ruff format .;
+uv run ruff check . --fix --show-fixes; uv run ruff format .;
 ```
 
 Check tests:

.cursor/rules/git-commits.mdc

@@ -2,81 +2,93 @@
 description: git-commits: Git commit message standards and AI assistance
 globs: git-commits: Git commit message standards and AI assistance | *.git/* .gitignore .github/* CHANGELOG.md CHANGES.md
 ---
-# Git Commit Standards
+# Optimized Git Commit Standards
 
-## Format
+## Commit Message Format
 ```
-type(scope[component]): concise description
+Component/File(commit-type[Subcomponent/method]): Concise description
 
-why: explanation of necessity/impact
-what: 
-- technical changes made
-- keep focused on single topic
+why: Explanation of necessity or impact.
+what:
+- Specific technical changes made
+- Focused on a single topic
 
-refs: #issue-number, breaking changes, links
+refs: #issue-number, breaking changes, or relevant links
 ```
 
-## Commit Types
-- `feat`: New features/enhancements
-- `fix`: Bug fixes
-- `refactor`: Code restructuring
-- `docs`: Documentation changes
-- `chore`: Maintenance tasks (deps, tooling)
-- `test`: Test-related changes
-- `style`: Code style/formatting
-
-## Guidelines
-- Subject line: max 50 chars
-- Body lines: max 72 chars
-- Use imperative mood ("Add" not "Added")
-- Single topic per commit
-- Blank line between subject and body
-- Mark breaking changes with "BREAKING:"
-- Use "See also:" for external links
-
-## AI Assistance in Cursor
-- Stage changes with `git add`
-- Use `@commit` to generate initial message
-- Review and adjust the generated message
-- Ensure it follows format above
-
-## Examples
-
-Good commit:
+## Component Patterns
+### General Code Changes
+```
+Component/File(feat[method]): Add feature
+Component/File(fix[method]): Fix bug
+Component/File(refactor[method]): Code restructure
 ```
-feat(subprocess[run]): Switch to unicode-only text handling
 
-why: Improve consistency and type safety in subprocess handling
-what:
-- BREAKING: Changed run() to use text=True by default
-- Removed console_to_str() helper and encoding logic
-- Simplified output handling
-- Updated type hints for better safety
+### Packages and Dependencies
+| Language   | Standard Packages                  | Dev Packages                  | Extras / Sub-packages                          |
+|------------|------------------------------------|-------------------------------|-----------------------------------------------|
+| General    | `lang(deps):`                      | `lang(deps[dev]):`            |                                               |
+| Python     | `py(deps):`                        | `py(deps[dev]):`              | `py(deps[extra]):`                            |
+| JavaScript | `js(deps):`                        | `js(deps[dev]):`              | `js(deps[subpackage]):`, `js(deps[dev{subpackage}]):` |
 
-refs: #485
-See also: https://docs.python.org/3/library/subprocess.html
+#### Examples
+- `py(deps[dev]): Update pytest to v8.1`
+- `js(deps[ui-components]): Upgrade Button component package`
+- `js(deps[dev{linting}]): Add ESLint plugin`
+
+### Documentation Changes
+Prefix with `docs:`
+```
+docs(Component/File[Subcomponent/method]): Update API usage guide
 ```
 
-Bad commit:
+### Test Changes
+Prefix with `tests:`
 ```
-updated some stuff and fixed bugs
+tests(Component/File[Subcomponent/method]): Add edge case tests
 ```
 
-Cursor Rules: Add development QA and git commit standards (#cursor-rules)
+## Commit Types Summary
+- **feat**: New features or enhancements
+- **fix**: Bug fixes
+- **refactor**: Code restructuring without functional change
+- **docs**: Documentation updates
+- **chore**: Maintenance (dependencies, tooling, config)
+- **test**: Test-related updates
+- **style**: Code style and formatting
+
+## General Guidelines
+- Subject line: Maximum 50 characters
+- Body lines: Maximum 72 characters
+- Use imperative mood (e.g., "Add", "Fix", not "Added", "Fixed")
+- Limit to one topic per commit
+- Separate subject from body with a blank line
+- Mark breaking changes clearly: `BREAKING:`
+- Use `See also:` to provide external references
+
+## AI Assistance Workflow in Cursor
+- Stage changes with `git add`
+- Use `@commit` to generate initial commit message
+- Review and refine generated message
+- Ensure adherence to these standards
+
+## Good Commit Example
+```
+Pane(feat[capture_pane]): Add screenshot capture support
 
-- Add dev-loop.mdc: QA process for code edits
-  - Type checking with mypy
-  - Linting with ruff
-  - Test validation with pytest
-  - Ensures edits are validated before commits
+why: Provide visual debugging capability
+what:
+- Implement capturePane method with image export
+- Integrate with existing Pane component logic
+- Document usage in Pane README
 
-- Add git-commits.mdc: Commit message standards
-  - Structured format with why/what sections
-  - Defined commit types and guidelines
-  - Examples of good/bad commits
-  - AI assistance instructions
+refs: #485
+See also: https://example.com/docs/pane-capture
+```
 
-Note: These rules help maintain code quality and commit history
-consistency across the project.
+## Bad Commit Example
+```
+fixed stuff and improved some functions
+```
 
-See also: https://docs.cursor.com/context/rules-for-ai
+These guidelines ensure clear, consistent commit histories, facilitating easier code review and maintenance.

CHANGES

@@ -15,6 +15,18 @@ $ pip install --user --upgrade --pre libtmux
 
 - _Future release notes will be placed here_
 
+### New features
+
+#### Waiting (#582)
+
+Added experimental `waiter.py` module for polling for terminal content in tmux panes:
+
+- Fluent API inspired by Playwright for better readability and chainable options
+- Support for multiple pattern types (exact text, contains, regex, custom predicates)
+- Composable waiting conditions with `wait_for_any_content` and `wait_for_all_content`
+- Enhanced error handling with detailed timeouts and match information
+- Robust shell prompt detection
+
 ## libtmux 0.46.0 (2025-02-25)
 
 ### Breaking

docs/internals/index.md

@@ -11,6 +11,7 @@ If you need an internal API stabilized please [file an issue](https://github.com
 ```{toctree}
 dataclasses
 query_list
+waiter
 ```
 
 ## Environmental variables

docs/internals/waiter.md

@@ -0,0 +1,135 @@
+(waiter)=
+
+# Waiters - `libtmux._internal.waiter`
+
+The waiter module provides utilities for waiting on specific content to appear in tmux panes, making it easier to write reliable tests that interact with terminal output.
+
+## Key Features
+
+- **Fluent API**: Playwright-inspired chainable API for expressive, readable test code
+- **Multiple Match Types**: Wait for exact matches, substring matches, regex patterns, or custom predicate functions
+- **Composable Waiting**: Wait for any of multiple conditions or all conditions to be met
+- **Flexible Timeout Handling**: Configure timeout behavior and error handling to suit your needs
+- **Shell Prompt Detection**: Easily wait for shell readiness with built-in prompt detection
+- **Robust Error Handling**: Improved exception handling and result reporting
+- **Clean Code**: Well-formatted, linted code with proper type annotations
+
+## Basic Concepts
+
+When writing tests that interact with tmux sessions and panes, it's often necessary to wait for specific content to appear before proceeding with the next step. The waiter module provides a set of functions to help with this.
+
+There are multiple ways to match content:
+- **Exact match**: The content exactly matches the specified string
+- **Contains**: The content contains the specified string
+- **Regex**: The content matches the specified regular expression
+- **Predicate**: A custom function that takes the pane content and returns a boolean
+
+## Quick Start Examples
+
+### Simple Waiting
+
+Wait for specific text to appear in a pane:
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_wait_for_text.py
+:language: python
+```
+
+### Advanced Matching
+
+Use regex patterns or custom predicates for more complex matching:
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_wait_for_regex.py
+:language: python
+```
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_custom_predicate.py
+:language: python
+```
+
+### Timeout Handling
+
+Control how long to wait and what happens when a timeout occurs:
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_timeout_handling.py
+:language: python
+```
+
+### Waiting for Shell Readiness
+
+A common use case is waiting for a shell prompt to appear, indicating the command has completed. The example below uses a regular expression to match common shell prompt characters (`$`, `%`, `>`, `#`):
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_wait_until_ready.py
+:language: python
+```
+
+> Note: This test is skipped in CI environments due to timing issues but works well for local development.
+
+## Fluent API (Playwright-inspired)
+
+For a more expressive and chainable API, you can use the fluent interface provided by the `PaneContentWaiter` class:
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_fluent_basic.py
+:language: python
+```
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_fluent_chaining.py
+:language: python
+```
+
+## Multiple Conditions
+
+The waiter module also supports waiting for multiple conditions at once:
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_wait_for_any_content.py
+:language: python
+```
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_wait_for_all_content.py
+:language: python
+```
+
+```{literalinclude} ../../tests/examples/_internal/waiter/test_mixed_pattern_types.py
+:language: python
+```
+
+## Implementation Notes
+
+### Error Handling
+
+The waiting functions are designed to be robust and handle timing and error conditions gracefully:
+
+- All wait functions properly calculate elapsed time for performance tracking
+- Functions handle exceptions consistently and provide clear error messages
+- Proper handling of return values ensures consistent behavior whether or not raises=True
+
+### Type Safety
+
+The waiter module is fully type-annotated to ensure compatibility with static type checkers:
+
+- All functions include proper type hints for parameters and return values
+- The ContentMatchType enum ensures that only valid match types are used
+- Combined with runtime checks, this prevents type-related errors during testing
+
+### Example Usage in Documentation
+
+All examples in this documentation are actual test files from the libtmux test suite. The examples are included using `literalinclude` directives, ensuring that the documentation remains synchronized with the actual code.
+
+## API Reference
+
+```{eval-rst}
+.. automodule:: libtmux._internal.waiter
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :member-order: bysource
+```
+
+## Extended Retry Functionality
+
+```{eval-rst}
+.. automodule:: libtmux.test.retry_extended
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :member-order: bysource
+```

docs/test-helpers/constants.md

@@ -1,3 +1,5 @@
+(test_helpers_constants)=
+
 # Constants
 
 Test-related constants used across libtmux test helpers.
@@ -7,4 +9,5 @@ Test-related constants used across libtmux test helpers.
    :members:
    :undoc-members:
    :show-inheritance:
-``` 
+   :member-order: bysource
+``` 

docs/test-helpers/environment.md

@@ -1,3 +1,5 @@
+(test_helpers_environment)=
+
 # Environment
 
 Environment variable mocking utilities for tests.
@@ -7,4 +9,5 @@ Environment variable mocking utilities for tests.
    :members:
    :undoc-members:
    :show-inheritance:
-``` 
+   :member-order: bysource
+``` 

docs/test-helpers/index.md

@@ -8,10 +8,11 @@ Test helpers for libtmux and downstream libraries.
 constants
 environment
 random
+retry
 temporary
 ```
 
 ```{eval-rst}
 .. automodule:: libtmux.test
    :members:
-``` 
+``` 

docs/test-helpers/random.md

@@ -1,3 +1,5 @@
+(test_helpers_random)=
+
 # Random
 
 Random string generation utilities for test names.
@@ -7,4 +9,5 @@ Random string generation utilities for test names.
    :members:
    :undoc-members:
    :show-inheritance:
-``` 
+   :member-order: bysource
+``` 

docs/test-helpers/retry.md

@@ -0,0 +1,15 @@
+(test_helpers_retry)=
+
+# Retry Utilities
+
+Retry helper functions for libtmux test utilities. These utilities help manage testing operations that may require multiple attempts before succeeding.
+
+## Basic Retry Functionality
+
+```{eval-rst}
+.. automodule:: libtmux.test.retry
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :member-order: bysource
+```