feat: add --idle-pause <time> to set the max time before idle frame optimization. Can improve readability. (#267)

* feat: add --idle-pause parameter for idle frame timing control

- Add -i/--idle-pause CLI parameter accepting duration values (s, ms, m)
- Replace frame counting with duration-based idle detection
- Allow specifying a minimum idle display time before optimization begins
- Add test coverage with conditional compilation for faster execution
- Update README documentation with usage examples

Gives viewers time to read text on screen before the animation advances
to the next change, making demos easier to follow.

* feat: -i --idle-pause clearer help message in cli.rs README.md

* fix(capture): correct idle period timeline compression for accurate duration control

Previous behavior: The idle_pause feature saved idle frames up to the threshold, then skipped the remaining idle frames. The skipped time remained in the timestamps, creating large gaps between consecutive frames during playback that exceeded the specified threshold (e.g., 10+ seconds instead of 3 seconds).

What changed:
- Refactored frame decision logic to maintain the timeline compression invariant
- Modified idle frame handling to compress the timeline for skipped frames beyond the threshold
- Preserved natural pauses up to the idle_pause duration while compressing excess time
- Enhanced compression state tracking for smooth playback timing
- Added comprehensive test coverage for multiple idle period scenarios

Technical implementation:
- Maintains compressed timestamps (effective_now = now - idle_duration) for all saved frames
- Skips frames when current_idle_period >= threshold and adds duration to idle_duration
- Preserves backward compatibility when idle_pause = None (maximum compression mode)
- Timeline compression eliminates gaps preventing jarring playback issues

Files affected:
- src/capture.rs: Complete fix for idle period duration control with timeline compression
  - Updated capture_thread() function with corrected frame decision logic
  - Enhanced documentation explaining terminal recording quality goals
  - Added 9 comprehensive test cases covering edge cases and multiple idle periods

Testable: Run capture tests to verify idle periods are compressed to exact threshold durations

* test(capture): consolidate idle pause tests into single parameterized test

Refactored capture module tests for better maintainability:

- Merged 12 individual test functions into 1 table-driven test
- Extracted reusable test infrastructure (TestApi, helper functions)
- Replaced magic numbers with meaningful variable names
- Added docstrings to all test functions and structs
- Created frame sequence generation using simple number arrays
- Improved test stability by allowing for timing variations
- Made test descriptions more specific about expected behavior

The single parameterized test runs all previous test scenarios through
a test_cases array, reducing code duplication while maintaining the
same test coverage.

Files changed:
- src/capture.rs: Consolidated test functions, added documentation

* test(capture): replace create_frames() with inline test data and improve documentation

Previous behavior: Tests used create_frames() function with string patterns. Frame numbering and test format were undocumented.

What changed: Removed create_frames() function and used inline test data arrays. Added documentation explaining that numbers represent pixel values simulating terminal activity. Made frames() generic. Documented the 5-element tuple format and [..] slice syntax.

Why: Direct inline test data is clearer than string pattern matching. Documentation helps future maintainers understand the test framework.

Files affected:
- src/capture.rs: Simplified test structure and added comprehensive documentation

Testable: cargo test test_idle_pause

* style(capture): apply cargo fmt formatting

Apply rustfmt to maintain consistent code style. Removes extra blank lines in documentation comments and reformats long function calls.

Files affected:
- src/capture.rs: Format documentation and function calls
- src/main.rs: Reformat capture_thread call parameters

* docs(capture): fix documentation accuracy and grammar

Previous behavior: Documentation contained vague terms, grammatical errors, and incorrectly stated files were saved as TGA format.

What changed:
- src/capture.rs: Fixed file format documentation (TGA → BMP)
- Simplified verbose comments while preserving technical accuracy
- Clarified how idle pause parameter controls frame compression
- Fixed grammar issues throughout function and test documentation

Why: Documentation must accurately describe code behavior and maintain clarity for future developers.

Files affected:
- src/capture.rs: Updated capture_thread() and test documentation

* chore: adjustment to trigger CI

* fix formatting issue

* adjust the test a bit

Signed-off-by: Sven Kanoldt <sven@d34dl0ck.me>

* add e2e tests feature to avoid ci failing, locally they work fine

Signed-off-by: Sven Kanoldt <sven@d34dl0ck.me>

---------

Signed-off-by: Sven Kanoldt <sven@d34dl0ck.me>
Co-authored-by: Sven Kanoldt <sven@d34dl0ck.me>

Author: ahundt

README.md

@@ -49,7 +49,7 @@ sudo port install t-rec
 **NOTE** `t-rec` depends on `imagemagick`.
 ```sh
 brew install imagemagick
-cargo install -f t-rec 
+cargo install -f t-rec
 ```
 **NOTE** `-f` just makes sure the latest version is installed
 
@@ -113,11 +113,11 @@ cargo install -f t-rec
 |-------------------------|
 | ubuntu 20.10 on GNOME |
 | ![demo-ubuntu](./docs/demo-ubuntu.gif) |
-| ubuntu 20.10 on i3wm | 
+| ubuntu 20.10 on i3wm |
 | ![demo-ubuntu-i3wm](./docs/demo-ubuntu-i3wm.gif) |
-| linux mint 20 on cinnamon | 
+| linux mint 20 on cinnamon |
 | ![demo-mint](./docs/demo-mint.gif) |
-| ArcoLinux 5.4 on Xfwm4 | 
+| ArcoLinux 5.4 on Xfwm4 |
 | ![demo-arco](./docs/demo-arco-xfwm4.gif) |
 
 ## Usage
@@ -150,7 +150,7 @@ Options:
                                   'Press Ctrl+D to end recording'
   -m, --video                     Generates additionally to the gif a mp4 video of the recording
   -M, --video-only                Generates only a mp4 video and not gif
-  -d, --decor <decor>             Decorates the animation with certain, mostly border effects 
+  -d, --decor <decor>             Decorates the animation with certain, mostly border effects
                                   [default: none] [possible values: shadow, none]
   -b, --bg <bg>                   Background color when decors are used [default: transparent]
                                   [possible values: white, black, transparent]
@@ -165,6 +165,8 @@ Options:
                                   the gif will show the last frame
   -s, --start-pause <s | ms | m>  to specify the pause time at the start of the animation, that time
                                   the gif will show the first frame
+  -i, --idle-pause <s | ms | m>   to preserve natural pauses up to a maximum duration by overriding
+                                  idle detection. Can enhance readability.
   -o, --output <file>             to specify the output file (without extension) [default: t-rec]
   -h, --help                      Print help
   -V, --version                   Print version
@@ -173,12 +175,19 @@ Options:
 ### Disable idle detection & optimization
 
 If you are not happy with the idle detection and optimization, you can disable it with the `-n` or `--natural` parameter.
-By doing so, you would get the very natural timeline of typing and recording as you do it. 
+By doing so, you would get the very natural timeline of typing and recording as you do it.
 In this case there will be no optimizations performed.
 
+Alternatively, you can keep recording idle time before optimization kicks in with the `--idle-pause` parameter.
+This gives viewers time to read the text on screen before the animation jumps to the next change:
+```sh
+t-rec --idle-pause 1s        # Show 1 second of unchanged content before optimization
+t-rec --idle-pause 500ms     # Show 500ms of idle time
+```
+
 ### Enable shadow border decor
 
-In order to enable the drop shadow border decor you have to pass `-d shadow` as an argument. If you only want to change 
+In order to enable the drop shadow border decor you have to pass `-d shadow` as an argument. If you only want to change
 the color of the background you can use `-b black` for example to have a black background.
 
 ### Record Arbitrary windows
@@ -190,7 +199,7 @@ You can record not only the terminal but also every other window. There 3 ways t
 t-rec --ls-win | grep -i calc
 Calculator | 45007
 
-t-rec -w 45007 
+t-rec -w 45007
 ```
 
 2) use the env var `TERM_PROGRAM` like this:
@@ -210,7 +219,7 @@ this is how it looks then:
 
 3) use the env var `WINDOWID` like this:
 - for example let's record a `VSCode` window
-- figure out the window id program, and make it 
+- figure out the window id program, and make it
 - make sure the window is visible on screen
 - set the variable and run `t-rec`