From 88334201cbfe97053c8716f702df85dc638cefa5 Mon Sep 17 00:00:00 2001
From: Alex Ostrovski <ostrovski.alex@gmail.com>
Date: Fri, 13 Feb 2026 22:05:56 +0200
Subject: [PATCH 1/9] Fix script permissions

---
 crates/term-transcript-cli/package.sh | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 mode change 100644 => 100755 crates/term-transcript-cli/package.sh

diff --git a/crates/term-transcript-cli/package.sh b/crates/term-transcript-cli/package.sh
old mode 100644
new mode 100755

From 3e7b612bbd6b17c6387e1eb800baaa444f73ede2 Mon Sep 17 00:00:00 2001
From: Alex Ostrovski <ostrovski.alex@gmail.com>
Date: Tue, 17 Feb 2026 16:31:48 +0200
Subject: [PATCH 2/9] Fix doc nits

---
 crates/term-transcript-cli/README.md | 2 +-
 docs/src/cli/build.md                | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/crates/term-transcript-cli/README.md b/crates/term-transcript-cli/README.md
index 0b2cdd16..b13d761d 100644
--- a/crates/term-transcript-cli/README.md
+++ b/crates/term-transcript-cli/README.md
@@ -65,7 +65,7 @@ shall be dual licensed as above, without any additional terms or conditions.
 
 [`term-transcript`]: https://crates.io/crates/term-transcript
 [fmt-subscriber]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/index.html
-[rainbow-script-link]: ../e2e-tests/rainbow/bin/rainbow
+[rainbow-script-link]: ../../e2e-tests/rainbow/bin/rainbow
 [test-snapshot-link]: tests/snapshots/test.svg
 [test-color-snapshot-link]: tests/snapshots/test-fail.svg
 [test-link]: tests/e2e.rs
diff --git a/docs/src/cli/build.md b/docs/src/cli/build.md
index f9e7e86f..9181503e 100644
--- a/docs/src/cli/build.md
+++ b/docs/src/cli/build.md
@@ -14,12 +14,12 @@ term-transcript --help
 
 This requires a Rust toolchain locally installed.
 
-### Minimum supported Rust version
+## Minimum supported Rust version
 
 The crate supports the latest stable Rust version. It may support previous stable Rust versions,
 but this is not guaranteed.
 
-### Crate feature: `portable-pty`
+## Crate feature: `portable-pty`
 
 Specify `--features portable-pty` in the installation command
 to enable the pseudo-terminal (PTY) support (note that PTY capturing still needs
@@ -29,7 +29,7 @@ which means that programs dependent on [`isatty`] checks
 or getting term size can produce different output than if launched in an actual shell
 (no coloring, no line wrapping etc.).
 
-### Crate feature: `tracing`
+## Crate feature: `tracing`
 
 Specify `--features tracing` in the installation command to enable tracing
 of the main performed operations. This could be useful for debugging purposes.

From 1bcafdd1ee7a7ba60b580e6866b8d18f9e8d10ac Mon Sep 17 00:00:00 2001
From: Alex Ostrovski <ostrovski.alex@gmail.com>
Date: Sun, 22 Feb 2026 10:20:38 +0200
Subject: [PATCH 3/9] Implement `start_with` / `ends_with`

---
 crates/styled-str/src/tests.rs       | 30 ++++++++++++++++++++++++
 crates/styled-str/src/types/slice.rs | 34 ++++++++++++++++++++++++++++
 crates/styled-str/src/types/str.rs   | 10 ++++++++
 crates/styled-str/tests/proptests.rs | 24 ++++++++++++++++++++
 4 files changed, 98 insertions(+)

diff --git a/crates/styled-str/src/tests.rs b/crates/styled-str/src/tests.rs
index 7a2e7089..894273e8 100644
--- a/crates/styled-str/src/tests.rs
+++ b/crates/styled-str/src/tests.rs
@@ -483,3 +483,33 @@ fn debugging_strings() {
     let debug = format!("{styled:?}");
     assert_eq!(debug, r#""[[red on white!]]Hello,\n\"world[[italic]]!\"""#);
 }
+
+#[test]
+fn starts_with_basics() {
+    let styled = styled!("[[green]]Hello, [[inverted]]world[[/]]!");
+    assert!(styled.starts_with(StyledStr::default()));
+    assert!(styled.starts_with(styled));
+
+    assert!(styled.starts_with(styled!("[[green]]Hell")));
+    assert!(!styled.starts_with(styled!("Hell")));
+    assert!(!styled.starts_with(styled!("[[red]]H")));
+    assert!(styled.starts_with(styled!("[[green]]Hello, ")));
+    assert!(styled.starts_with(styled!("[[green]]Hello, [[inverted]]w")));
+    assert!(!styled.starts_with(styled!("[[green]]Hello, w")));
+    assert!(styled.starts_with(styled!("[[green]]Hello, [[inverted]]world")));
+}
+
+#[test]
+fn ends_with_basics() {
+    let styled = styled!("[[green]]Hello, [[inverted]]world[[/]]!");
+    assert!(styled.ends_with(StyledStr::default()));
+    assert!(styled.ends_with(styled));
+
+    assert!(styled.ends_with(styled!("!")));
+    assert!(!styled.ends_with(styled!("d!")));
+    assert!(!styled.ends_with(styled!("[[invert]]!")));
+    assert!(styled.ends_with(styled!("[[invert]]d[[/]]!")));
+    assert!(styled.ends_with(styled!("[[inverted]]world[[/]]!")));
+    assert!(!styled.ends_with(styled!("[[inverted]], world[[/]]!")));
+    assert!(styled.ends_with(styled!("[[green]]o, [[inverted]]world[[/]]!")));
+}
diff --git a/crates/styled-str/src/types/slice.rs b/crates/styled-str/src/types/slice.rs
index 2e278286..20dc9dee 100644
--- a/crates/styled-str/src/types/slice.rs
+++ b/crates/styled-str/src/types/slice.rs
@@ -158,6 +158,40 @@ impl<'a> SpansSlice<'a> {
         }
     }
 
+    pub(crate) fn start_with(&self, needle: &SpansSlice<'_>) -> bool {
+        let needle_len = needle.len();
+        if needle_len > self.len() {
+            return false;
+        }
+
+        needle
+            .iter()
+            .zip(self.iter())
+            .enumerate()
+            .all(|(i, (needle_span, this_span))| {
+                this_span.style == needle_span.style && {
+                    let cmp = this_span.len.cmp(&needle_span.len);
+                    cmp.is_eq() || (i + 1 == needle_len && cmp.is_gt())
+                }
+            })
+    }
+
+    pub(crate) fn end_with(&self, needle: &SpansSlice<'_>) -> bool {
+        let needle_len = needle.len();
+        if needle_len > self.len() {
+            return false;
+        }
+
+        needle.iter().rev().zip(self.iter().rev()).enumerate().all(
+            |(i, (needle_span, this_span))| {
+                this_span.style == needle_span.style && {
+                    let cmp = this_span.len.cmp(&needle_span.len);
+                    cmp.is_eq() || (i + 1 == needle_len && cmp.is_gt())
+                }
+            },
+        )
+    }
+
     pub(crate) const fn split_at(&self, mid: usize) -> (Self, Self) {
         assert!(
             mid <= self.text_end - self.text_start,
diff --git a/crates/styled-str/src/types/str.rs b/crates/styled-str/src/types/str.rs
index 1cc52a9a..2e47563c 100644
--- a/crates/styled-str/src/types/str.rs
+++ b/crates/styled-str/src/types/str.rs
@@ -133,6 +133,16 @@ impl<'a> StyledStr<'a> {
         (start, end)
     }
 
+    /// Checks whether this string starts with a `needle`, matching both its text and styling.
+    pub fn starts_with(&self, needle: StyledStr<'_>) -> bool {
+        self.text.starts_with(needle.text) && self.spans.start_with(&needle.spans)
+    }
+
+    /// Checks whether this string ends with a `needle`, matching both its text and styling.
+    pub fn ends_with(&self, needle: StyledStr<'_>) -> bool {
+        self.text.ends_with(needle.text) && self.spans.end_with(&needle.spans)
+    }
+
     /// Iterates over spans contained in this string.
     ///
     /// # Examples
diff --git a/crates/styled-str/tests/proptests.rs b/crates/styled-str/tests/proptests.rs
index 92a33f88..d325575e 100644
--- a/crates/styled-str/tests/proptests.rs
+++ b/crates/styled-str/tests/proptests.rs
@@ -303,4 +303,28 @@ proptest! {
     ) {
         test_string_slice(styled.as_str(), start..end)?;
     }
+
+    #[test]
+    fn starts_with_positive(styled in styled_string(VISIBLE_ASCII, 1..=5)) {
+        let styled = styled.as_str();
+        for end in 0..=styled.text().len() {
+            let prefix = styled.get(..end).unwrap();
+            prop_assert!(styled.starts_with(prefix), "end={end}");
+            if end < styled.text().len() {
+                prop_assert!(!prefix.starts_with(styled), "end={end}");
+            }
+        }
+    }
+
+    #[test]
+    fn ends_with_positive(styled in styled_string(VISIBLE_ASCII, 1..=5)) {
+        let styled = styled.as_str();
+        for start in 0..=styled.text().len() {
+            let suffix = styled.get(start..).unwrap();
+            prop_assert!(styled.ends_with(suffix), "start={start}");
+            if start > 0 {
+                prop_assert!(!suffix.ends_with(styled), "start={start}");
+            }
+        }
+    }
 }

From 32fec17e7d5bfcdf11f496fec851e736838cbae4 Mon Sep 17 00:00:00 2001
From: Alex Ostrovski <ostrovski.alex@gmail.com>
Date: Sun, 22 Feb 2026 10:28:07 +0200
Subject: [PATCH 4/9] Implement `AddAssign` for `StyledStringBuilder`

---
 crates/styled-str/src/types/string.rs | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/crates/styled-str/src/types/string.rs b/crates/styled-str/src/types/string.rs
index 13ba1f28..cd20f805 100644
--- a/crates/styled-str/src/types/string.rs
+++ b/crates/styled-str/src/types/string.rs
@@ -28,9 +28,10 @@ use crate::{
 /// builder.push_style(AnsiColor::BrightGreen.on(AnsiColor::White).bold());
 /// builder.push_text("Hello");
 /// builder.push_text(",");
-/// builder.push_style(Style::new());
+/// // It's possible to use `+=` as syntactic sugar for `push_str()` / `push_style()`.
+/// builder += Style::new();
 /// builder.push_text(" world");
-/// builder.push_str(styled!("[[it, dim]]!"));
+/// builder += styled!("[[it, dim]]!");
 ///
 /// let s = builder.build();
 /// assert_eq!(
@@ -123,6 +124,20 @@ impl From<StyledString> for StyledStringBuilder {
     }
 }
 
+impl ops::AddAssign<Style> for StyledStringBuilder {
+    fn add_assign(&mut self, rhs: Style) {
+        self.push_style(rhs);
+    }
+}
+
+impl ops::AddAssign<StyledStr<'_>> for StyledStringBuilder {
+    fn add_assign(&mut self, rhs: StyledStr<'_>) {
+        self.push_str(rhs);
+    }
+}
+
+// We don't implement `AddAssign<&str>` for `StyledStringBuilder` to avoid ambiguity what the string represents.
+
 /// Heap-allocated styled string.
 ///
 /// `StyledString` represents the owned string variant in contrast to [`StyledStr`], which is borrowed.

From 902645c631ff658f23a0e198885e97c2e8a94e05 Mon Sep 17 00:00:00 2001
From: Alex Ostrovski <ostrovski.alex@gmail.com>
Date: Sun, 22 Feb 2026 10:31:20 +0200
Subject: [PATCH 5/9] Add doc tests for `starts_with` / `ends_with`

---
 crates/styled-str/src/types/str.rs | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/crates/styled-str/src/types/str.rs b/crates/styled-str/src/types/str.rs
index 2e47563c..62125592 100644
--- a/crates/styled-str/src/types/str.rs
+++ b/crates/styled-str/src/types/str.rs
@@ -134,11 +134,31 @@ impl<'a> StyledStr<'a> {
     }
 
     /// Checks whether this string starts with a `needle`, matching both its text and styling.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use styled_str::styled;
+    /// let styled = styled!("[[green]]Hello, [[* bold]]world");
+    /// assert!(styled.starts_with(styled!("[[green]]Hello")));
+    /// // Styling is taken into account
+    /// assert!(!styled.starts_with(styled!("Hello")));
+    /// ```
     pub fn starts_with(&self, needle: StyledStr<'_>) -> bool {
         self.text.starts_with(needle.text) && self.spans.start_with(&needle.spans)
     }
 
     /// Checks whether this string ends with a `needle`, matching both its text and styling.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use styled_str::styled;
+    /// let styled = styled!("[[green]]Hello, [[* bold]]world");
+    /// assert!(styled.ends_with(styled!("[[green bold]]ld")));
+    /// // Styling is taken into account
+    /// assert!(!styled.ends_with(styled!("world")));
+    /// ```
     pub fn ends_with(&self, needle: StyledStr<'_>) -> bool {
         self.text.ends_with(needle.text) && self.spans.end_with(&needle.spans)
     }

From 18f01a3bbd656cfae7a69252698f7b821612eded Mon Sep 17 00:00:00 2001
From: Alex Ostrovski <ostrovski.alex@gmail.com>
Date: Sun, 22 Feb 2026 10:33:44 +0200
Subject: [PATCH 6/9] Trim ending newlines in `Interaction` output

---
 crates/term-transcript/src/types.rs | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/crates/term-transcript/src/types.rs b/crates/term-transcript/src/types.rs
index e21bbe70..82a432be 100644
--- a/crates/term-transcript/src/types.rs
+++ b/crates/term-transcript/src/types.rs
@@ -185,7 +185,10 @@ impl Interaction {
     }
 
     /// Sets the output for this interaction.
-    pub fn set_output(&mut self, output: StyledString) {
+    pub fn set_output(&mut self, mut output: StyledString) {
+        while output.text().ends_with('\n') {
+            output.pop();
+        }
         self.output = output;
     }
 

From aab3b4e02d5a47c6f7759b652079f2a0872de244 Mon Sep 17 00:00:00 2001
From: Alex Ostrovski <ostrovski.alex@gmail.com>
Date: Sun, 22 Feb 2026 15:22:44 +0200
Subject: [PATCH 7/9] Implement `find()` / `contains()`

---
 crates/styled-str/src/types/spans.rs |  4 ++
 crates/styled-str/src/types/str.rs   | 78 ++++++++++++++++++++++++++++
 crates/styled-str/src/utils.rs       |  2 +-
 3 files changed, 83 insertions(+), 1 deletion(-)

diff --git a/crates/styled-str/src/types/spans.rs b/crates/styled-str/src/types/spans.rs
index f63a092f..0b064894 100644
--- a/crates/styled-str/src/types/spans.rs
+++ b/crates/styled-str/src/types/spans.rs
@@ -35,6 +35,10 @@ impl StyledSpan {
         let new_len = self.len.get().checked_sub(sub).expect("length underflow");
         self.len = NonZeroUsize::new(new_len).expect("length underflow");
     }
+
+    pub(crate) fn can_contain(&self, needle: &Self) -> bool {
+        self.style == needle.style && self.len >= needle.len
+    }
 }
 
 /// Text with a uniform [`Style`] attached to it. Returned by the [`StyledStr::spans()`](crate::StyledStr::spans()) iterator.
diff --git a/crates/styled-str/src/types/str.rs b/crates/styled-str/src/types/str.rs
index 62125592..585eecf2 100644
--- a/crates/styled-str/src/types/str.rs
+++ b/crates/styled-str/src/types/str.rs
@@ -163,6 +163,84 @@ impl<'a> StyledStr<'a> {
         self.text.ends_with(needle.text) && self.spans.end_with(&needle.spans)
     }
 
+    /// Checks whether `needle` is contained in this string, matching both by text and styling.
+    pub fn contains(&self, needle: StyledStr<'_>) -> bool {
+        self.find(needle).is_some()
+    }
+
+    /// Finds the first byte position of `needle` in this string from the string start, matching both by text and styling.
+    #[allow(clippy::missing_panics_doc)] // Internal check that should never be triggered
+    pub fn find(&self, needle: StyledStr<'_>) -> Option<usize> {
+        let Some(first_needle_span) = needle.spans.iter().next() else {
+            // `needle` is empty
+            return Some(0);
+        };
+        let needle_has_multiple_spans = needle.spans.len() > 1;
+
+        let mut text_matched_on_prev_iteration = false;
+        let mut start_pos = 0;
+        loop {
+            // First, find a candidate by styling by considering the starting span.
+            // This is efficient if the styled string doesn't contain many styles.
+            let spans_suffix = self
+                .spans
+                .get_by_text_range((ops::Bound::Included(start_pos), ops::Bound::Unbounded));
+            let offset_by_spans = spans_suffix.iter().find_map(|span| {
+                span.can_contain(&first_needle_span).then(|| {
+                    let mut offset = span.start;
+                    if needle_has_multiple_spans {
+                        // Need to align the span end.
+                        offset += span.len.get() - first_needle_span.len.get();
+                    }
+                    offset
+                })
+            });
+            let Some(offset_by_spans) = offset_by_spans else {
+                // No matching style spans
+                return None;
+            };
+            start_pos += offset_by_spans;
+            // We cannot guarantee that `start_pos` is at the char boundary, and the code below demands it.
+            start_pos = utils::ceil_char_boundary(self.text.as_bytes(), start_pos);
+
+            let offset_by_text = if offset_by_spans == 0 && text_matched_on_prev_iteration {
+                // Can reuse the text match found on the previous iteration
+                0
+            } else {
+                let Some(offset_by_text) = self.text[start_pos..].find(needle.text) else {
+                    // No text mentions
+                    return None;
+                };
+                offset_by_text
+            };
+            start_pos += offset_by_text;
+
+            if offset_by_text == 0 {
+                // The text match *may* correspond to the style match; check the spans slice completely.
+                let range = (
+                    ops::Bound::Included(start_pos),
+                    ops::Bound::Excluded(start_pos + needle.text.len()),
+                );
+                let spans_slice = self.spans.get_by_text_range(range);
+                if spans_slice == needle.spans {
+                    return Some(start_pos);
+                }
+
+                // We guarantee that the first style span matches, so this case can only happen if the needle
+                // contains multiple spans. Because the first and second span styles differ, we can advance
+                // the search position by first + second span lengths (i.e., at least 2).
+                assert!(needle_has_multiple_spans);
+                let second_span_len = needle.spans.get(1).unwrap().len;
+                let offset = first_needle_span.len.get() + second_span_len.get();
+                start_pos += offset;
+                start_pos = utils::ceil_char_boundary(self.text.as_bytes(), start_pos);
+            }
+            // Otherwise, the text match is somewhere after the found style match, so we refine the style match
+            // on the next loop iteration.
+            text_matched_on_prev_iteration = offset_by_text != 0;
+        }
+    }
+
     /// Iterates over spans contained in this string.
     ///
     /// # Examples
diff --git a/crates/styled-str/src/utils.rs b/crates/styled-str/src/utils.rs
index 9c9e6b51..1fe807a4 100644
--- a/crates/styled-str/src/utils.rs
+++ b/crates/styled-str/src/utils.rs
@@ -113,7 +113,7 @@ const fn is_same_color(lhs: Color, rhs: Color) -> bool {
 const UTF8_CONTINUATION_MASK: u8 = 0b1100_0000;
 const UTF8_CONTINUATION_MARKER: u8 = 0b1000_0000;
 
-const fn ceil_char_boundary(bytes: &[u8], mut pos: usize) -> usize {
+pub(crate) const fn ceil_char_boundary(bytes: &[u8], mut pos: usize) -> usize {
     assert!(pos <= bytes.len());
 
     while pos < bytes.len() && bytes[pos] & UTF8_CONTINUATION_MASK == UTF8_CONTINUATION_MARKER {

From 7c1bf495413886ac6535333ac2e55d926b247e73 Mon Sep 17 00:00:00 2001
From: Alex Ostrovski <ostrovski.alex@gmail.com>
Date: Sun, 22 Feb 2026 15:23:09 +0200
Subject: [PATCH 8/9] Prop-test `find()`

---
 crates/styled-str/src/tests.rs       |  26 ++++
 crates/styled-str/tests/proptests.rs | 214 +++++++++++++++++++++++----
 2 files changed, 209 insertions(+), 31 deletions(-)

diff --git a/crates/styled-str/src/tests.rs b/crates/styled-str/src/tests.rs
index 894273e8..9d560d6f 100644
--- a/crates/styled-str/src/tests.rs
+++ b/crates/styled-str/src/tests.rs
@@ -513,3 +513,29 @@ fn ends_with_basics() {
     assert!(!styled.ends_with(styled!("[[inverted]], world[[/]]!")));
     assert!(styled.ends_with(styled!("[[green]]o, [[inverted]]world[[/]]!")));
 }
+
+#[test]
+fn find_basics() {
+    let styled = styled!("[[green]]Hello, [[inverted]]world[[/]]!");
+    assert_eq!(styled.find(StyledStr::default()), Some(0));
+    assert_eq!(styled.find(styled!("H")), None);
+    assert_eq!(styled.find(styled!("[[red]]H")), None);
+
+    // Single span in needle
+    assert_eq!(styled.find(styled!("[[green]]l")), Some(2));
+    assert_eq!(styled.find(styled!("[[green]], ")), Some(5));
+    assert_eq!(styled.find(styled!("[[invert]]w")), Some(7));
+    assert_eq!(styled.find(styled!("[[inverted]]world!")), None);
+
+    // Multiple spans in needle
+    assert_eq!(styled.find(styled!("[[green]], [[invert]]w")), Some(5));
+    assert_eq!(styled.find(styled!("[[inverted]]world[[/]]!")), Some(7));
+    assert_eq!(styled.find(styled!("[[inverted]]world[[bold]]!")), None);
+}
+
+#[test]
+fn find_proptest_regression() {
+    let haystack = styled!("ллллл[[bold]]ллллaaлaaлaaaлллaллaaлл[[/]]a[[bold]]aaл");
+    let needle = styled!("[[bold]]лa[[/]]a");
+    assert_eq!(haystack.find(needle), None);
+}
diff --git a/crates/styled-str/tests/proptests.rs b/crates/styled-str/tests/proptests.rs
index d325575e..e8d948fa 100644
--- a/crates/styled-str/tests/proptests.rs
+++ b/crates/styled-str/tests/proptests.rs
@@ -1,12 +1,12 @@
 //! Property testing for styled strings.
 
-use std::{fmt::Write as _, num::NonZeroUsize, ops};
+use std::{cell::Cell, fmt::Write as _, num::NonZeroUsize, ops};
 
 use anstyle::{Ansi256Color, AnsiColor, Color, Effects, RgbColor, Style};
 use proptest::{num, prelude::*};
 use styled_str::{StyledStr, StyledString};
 
-fn effects() -> impl Strategy<Value = Effects> {
+fn effects() -> impl Strategy<Value = Effects> + Clone {
     proptest::bits::u8::between(0, 6).prop_map(|val| {
         let mut this = Effects::new();
         if val & 1 != 0 {
@@ -55,7 +55,7 @@ fn ansi_color() -> impl Strategy<Value = AnsiColor> {
     ]
 }
 
-fn color() -> impl Strategy<Value = Color> {
+fn color() -> impl Strategy<Value = Color> + Clone {
     prop_oneof![
         ansi_color().prop_map(Color::Ansi),
         num::u8::ANY.prop_map(|idx| Ansi256Color(idx).into()),
@@ -64,7 +64,7 @@ fn color() -> impl Strategy<Value = Color> {
     ]
 }
 
-fn style() -> impl Strategy<Value = Style> {
+fn any_style() -> impl Strategy<Value = Style> + Clone {
     let effects_and_color = (
         effects(),
         proptest::option::of(color()),
@@ -74,6 +74,10 @@ fn style() -> impl Strategy<Value = Style> {
         .prop_map(|(effects, fg, bg)| Style::new().effects(effects).fg_color(fg).bg_color(bg))
 }
 
+fn limited_style() -> impl Strategy<Value = Style> + Clone {
+    prop_oneof![Just(Style::new()), Just(Style::new().bold()),]
+}
+
 const UTF8_CONTINUATION_MASK: u8 = 0b1100_0000;
 const UTF8_CONTINUATION_MARKER: u8 = 0b1000_0000;
 
@@ -96,6 +100,7 @@ struct StyleAndLen {
 
 fn span_lengths(
     text: String,
+    style: impl Strategy<Value = Style> + Clone + 'static,
     span_count: ops::RangeInclusive<usize>,
 ) -> impl Strategy<Value = Vec<StyleAndLen>> {
     assert!(!span_count.is_empty());
@@ -122,9 +127,9 @@ fn span_lengths(
     });
 
     lengths
-        .prop_flat_map(|lengths| {
+        .prop_flat_map(move |lengths| {
             (
-                proptest::collection::vec(style(), lengths.len()),
+                proptest::collection::vec(style.clone(), lengths.len()),
                 Just(lengths),
             )
         })
@@ -139,20 +144,26 @@ fn span_lengths(
 
 fn styled_string(
     text: impl Strategy<Value = String>,
+    style: impl Strategy<Value = Style> + Clone + 'static,
     span_count: ops::RangeInclusive<usize>,
 ) -> impl Strategy<Value = StyledString> {
-    text.prop_flat_map(move |text| (span_lengths(text.clone(), span_count.clone()), Just(text)))
-        .prop_map(|(spans, text)| {
-            let mut builder = StyledString::builder();
-            let mut pos = 0;
-            for span in spans {
-                builder.push_style(span.style);
-                let end_pos = pos + span.len.get();
-                builder.push_text(&text[pos..end_pos]);
-                pos = end_pos;
-            }
-            builder.build()
-        })
+    text.prop_flat_map(move |text| {
+        (
+            span_lengths(text.clone(), style.clone(), span_count.clone()),
+            Just(text),
+        )
+    })
+    .prop_map(|(spans, text)| {
+        let mut builder = StyledString::builder();
+        let mut pos = 0;
+        for span in spans {
+            builder.push_style(span.style);
+            let end_pos = pos + span.len.get();
+            builder.push_text(&text[pos..end_pos]);
+            pos = end_pos;
+        }
+        builder.build()
+    })
 }
 
 fn assert_spans_iterator(styled: StyledStr<'_>) -> Result<(), TestCaseError> {
@@ -177,6 +188,13 @@ fn test_string_slice(styled: StyledStr<'_>, range: ops::Range<usize>) -> Result<
         let slice = slice.unwrap();
         prop_assert_eq!(slice.text(), text_slice);
 
+        let pos = styled.find(slice).unwrap();
+        prop_assert!(pos <= range.start);
+        if pos < range.start {
+            let found_slice = styled.get(pos..pos + slice.text().len()).unwrap();
+            prop_assert_eq!(found_slice, slice);
+        }
+
         let before = styled.get(..range.start).unwrap();
         let after = styled.get(range.end..).unwrap();
         let concat: StyledString = [before, slice, after].into_iter().collect();
@@ -192,42 +210,42 @@ const ANY_CHARS: &str = r"[^\x1b\r]{1,32}";
 
 proptest! {
     #[test]
-    fn styled_ascii_string_roundtrip(styled in styled_string(VISIBLE_ASCII, 1..=5)) {
+    fn styled_ascii_string_roundtrip(styled in styled_string(VISIBLE_ASCII, any_style(), 1..=5)) {
         let rich_str = styled.to_string();
         let parsed: StyledString = rich_str.parse()?;
         prop_assert_eq!(styled, parsed);
     }
 
     #[test]
-    fn styled_ascii_string_roundtrip_via_ansi(styled in styled_string(VISIBLE_ASCII, 1..=5)) {
+    fn styled_ascii_string_roundtrip_via_ansi(styled in styled_string(VISIBLE_ASCII, any_style(), 1..=5)) {
         let ansi_str = styled.as_str().ansi().to_string();
         let parsed: StyledString = StyledString::from_ansi(&ansi_str)?;
         prop_assert_eq!(styled, parsed);
     }
 
     #[test]
-    fn styled_string_roundtrip(styled in styled_string(ANY_CHARS, 1..=5)) {
+    fn styled_string_roundtrip(styled in styled_string(ANY_CHARS, any_style(), 1..=5)) {
         let rich_str = styled.to_string();
         let parsed: StyledString = rich_str.parse()?;
         prop_assert_eq!(styled, parsed);
     }
 
     #[test]
-    fn styled_string_roundtrip_via_ansi(styled in styled_string(ANY_CHARS, 1..=5)) {
+    fn styled_string_roundtrip_via_ansi(styled in styled_string(ANY_CHARS, any_style(), 1..=5)) {
         let ansi_str = styled.as_str().ansi().to_string();
         let parsed: StyledString = StyledString::from_ansi(&ansi_str)?;
         prop_assert_eq!(styled, parsed);
     }
 
     #[test]
-    fn styles_are_optimized(styled in styled_string(r"[\n\t\x20-\x7e]{32}", 2..=5)) {
+    fn styles_are_optimized(styled in styled_string(r"[\n\t\x20-\x7e]{32}", any_style(), 2..=5)) {
         assert_spans_iterator(styled.as_str())?;
     }
 
     #[test]
     fn concatenating_styled_strings(
-        start in styled_string(r"[^\x1b\r]{32}", 1..=5),
-        end in styled_string(r"[^\x1b\r]{32}", 1..=5),
+        start in styled_string(r"[^\x1b\r]{32}", any_style(), 1..=5),
+        end in styled_string(r"[^\x1b\r]{32}", any_style(), 1..=5),
     ) {
         let mut concat = start.clone();
         concat.push_str(end.as_str());
@@ -243,7 +261,7 @@ proptest! {
 
     #[test]
     fn splitting_styled_string(
-        (pos, styled) in styled_string(r"[\x20-\x7e]{32}", 1..=5).prop_flat_map(|string| {
+        (pos, styled) in styled_string(r"[\x20-\x7e]{32}", any_style(), 1..=5).prop_flat_map(|string| {
             (0..=string.text().len(), Just(string))
         })
     ) {
@@ -257,7 +275,7 @@ proptest! {
     }
 
     #[test]
-    fn lines_in_styled_string(styled in styled_string(VISIBLE_ASCII, 1..=5)) {
+    fn lines_in_styled_string(styled in styled_string(VISIBLE_ASCII, any_style(), 1..=5)) {
         let mut builder = StyledString::builder();
         let mut ansi_str = String::new();
         for line in styled.as_str().lines() {
@@ -278,7 +296,7 @@ proptest! {
     }
 
     #[test]
-    fn looking_up_spans(styled in styled_string(VISIBLE_ASCII, 1..=5)) {
+    fn looking_up_spans(styled in styled_string(VISIBLE_ASCII, any_style(), 1..=5)) {
         let styled = styled.as_str();
         let mut spans_iter = styled.spans().peekable();
         let mut span_start = 0;
@@ -296,7 +314,7 @@ proptest! {
 
     #[test]
     fn slicing_string(
-        (styled, start, end) in styled_string(VISIBLE_ASCII, 1..=5).prop_flat_map(|string| {
+        (styled, start, end) in styled_string(VISIBLE_ASCII, any_style(), 1..=5).prop_flat_map(|string| {
             let text_len = string.text().len();
             (Just(string), 0..=text_len, 0..=text_len)
         })
@@ -305,7 +323,7 @@ proptest! {
     }
 
     #[test]
-    fn starts_with_positive(styled in styled_string(VISIBLE_ASCII, 1..=5)) {
+    fn starts_with_positive(styled in styled_string(VISIBLE_ASCII, any_style(), 1..=5)) {
         let styled = styled.as_str();
         for end in 0..=styled.text().len() {
             let prefix = styled.get(..end).unwrap();
@@ -317,7 +335,7 @@ proptest! {
     }
 
     #[test]
-    fn ends_with_positive(styled in styled_string(VISIBLE_ASCII, 1..=5)) {
+    fn ends_with_positive(styled in styled_string(VISIBLE_ASCII, any_style(), 1..=5)) {
         let styled = styled.as_str();
         for start in 0..=styled.text().len() {
             let suffix = styled.get(start..).unwrap();
@@ -328,3 +346,137 @@ proptest! {
         }
     }
 }
+
+fn test_starts_with_random(
+    haystack: StyledStr<'_>,
+    needle: StyledStr<'_>,
+) -> Result<bool, TestCaseError> {
+    if haystack.starts_with(needle) {
+        prop_assert!(haystack.text().starts_with(needle.text()));
+        let end = needle.text().len();
+        prop_assert_eq!(haystack.get(..end).unwrap(), needle);
+
+        for (pos, _) in haystack.text().char_indices().rev() {
+            if pos < end {
+                break;
+            }
+            let haystack_prefix = haystack.get(..pos).unwrap();
+            prop_assert!(haystack_prefix.starts_with(needle));
+        }
+        Ok(true)
+    } else {
+        prop_assert!(
+            haystack
+                .get(..needle.text().len())
+                .is_none_or(|prefix| prefix != needle)
+        );
+        Ok(false)
+    }
+}
+
+#[test]
+fn starts_with_random() {
+    let positive_count = Cell::new(0);
+
+    proptest!(|(
+        // Restrict the alphabet so that there's a non-zero chance to hit the positive case
+        haystack in styled_string("[aл]{32}", limited_style(), 1..=5),
+        needle in styled_string("[aл]{3}", limited_style(), 1..=3),
+    )| {
+        if test_starts_with_random(haystack.as_str(), needle.as_str())? {
+            positive_count.update(|count| count + 1);
+        }
+    });
+
+    println!("Positive count: {}", positive_count.get());
+}
+
+fn test_ends_with_random(
+    haystack: StyledStr<'_>,
+    needle: StyledStr<'_>,
+) -> Result<bool, TestCaseError> {
+    let possible_start = haystack.text().len().checked_sub(needle.text().len());
+    if haystack.ends_with(needle) {
+        prop_assert!(haystack.text().ends_with(needle.text()));
+        let start = possible_start.unwrap();
+        prop_assert_eq!(haystack.get(start..).unwrap(), needle);
+
+        for (pos, _) in haystack.text().char_indices() {
+            if pos > start {
+                break;
+            }
+            let haystack_suffix = haystack.get(pos..).unwrap();
+            prop_assert!(haystack_suffix.ends_with(needle));
+        }
+        Ok(true)
+    } else if let Some(possible_start) = possible_start {
+        prop_assert!(
+            haystack
+                .get(possible_start..)
+                .is_none_or(|prefix| prefix != needle)
+        );
+        Ok(false)
+    } else {
+        Ok(false)
+    }
+}
+
+#[test]
+fn ends_with_random() {
+    let positive_count = Cell::new(0);
+
+    proptest!(|(
+        // Restrict the alphabet so that there's a non-zero chance to hit the positive case
+        haystack in styled_string("[aл]{32}", limited_style(), 1..=5),
+        needle in styled_string("[aл]{3}", limited_style(), 1..=3),
+    )| {
+        if test_ends_with_random(haystack.as_str(), needle.as_str())? {
+            positive_count.update(|count| count + 1);
+        }
+    });
+
+    println!("Positive count: {}", positive_count.get());
+}
+
+fn test_find_random(haystack: StyledStr<'_>, needle: StyledStr<'_>) -> Result<bool, TestCaseError> {
+    if let Some(pos) = haystack.find(needle) {
+        prop_assert_eq!(
+            haystack.get(pos..pos + needle.text().len()).unwrap(),
+            needle
+        );
+
+        for prev_pos in 0..pos {
+            if let Some(substr) = haystack.get(prev_pos..prev_pos + needle.text().len()) {
+                prop_assert_ne!(substr, needle);
+            }
+            if let Some(suffix) = haystack.get(prev_pos..) {
+                prop_assert_eq!(suffix.find(needle), Some(pos - prev_pos));
+            }
+        }
+        Ok(true)
+    } else {
+        for pos in 0..haystack.text().len() {
+            if let Some(substr) = haystack.get(pos..pos + needle.text().len()) {
+                prop_assert_ne!(substr, needle);
+            }
+        }
+        Ok(false)
+    }
+}
+
+#[test]
+fn find_random() {
+    let positive_count = Cell::new(0);
+
+    proptest!(|(
+        // Restrict the alphabet so that there's a non-zero chance to hit the positive case
+        haystack in styled_string("[aл]{32}", limited_style(), 1..=5),
+        needle in styled_string("[aл]{3}", limited_style(), 1..=3),
+    )| {
+        if test_find_random(haystack.as_str(), needle.as_str())? {
+            positive_count.update(|count| count + 1);
+        }
+    });
+
+    println!("Positive count: {}", positive_count.get());
+}

From a5fe6a90090dfae6ae1d73a92cfdc481961e35f9 Mon Sep 17 00:00:00 2001
From: Alex Ostrovski <ostrovski.alex@gmail.com>
Date: Sun, 22 Feb 2026 15:27:55 +0200
Subject: [PATCH 9/9] Add doc tests for `find` / `contains`

---
 crates/styled-str/src/types/str.rs | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/crates/styled-str/src/types/str.rs b/crates/styled-str/src/types/str.rs
index 585eecf2..530d4255 100644
--- a/crates/styled-str/src/types/str.rs
+++ b/crates/styled-str/src/types/str.rs
@@ -164,11 +164,32 @@ impl<'a> StyledStr<'a> {
     }
 
     /// Checks whether `needle` is contained in this string, matching both by text and styling.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use styled_str::styled;
+    /// let styled = styled!("[[green]]Hello, [[* bold]]world");
+    /// assert!(styled.contains(styled!("[[green]]lo, [[* bold]]w")));
+    /// assert!(!styled.contains(styled!("lo")));
+    /// ```
     pub fn contains(&self, needle: StyledStr<'_>) -> bool {
         self.find(needle).is_some()
     }
 
     /// Finds the first byte position of `needle` in this string from the string start, matching both by text and styling.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use styled_str::styled;
+    /// let styled = styled!("[[green]]Hello, [[* bold]]world");
+    /// assert_eq!(
+    ///     styled.find(styled!("[[green]]lo, [[* bold]]w")),
+    ///     Some(3)
+    /// );
+    /// assert_eq!(styled.find(styled!("lo")), None);
+    /// ```
     #[allow(clippy::missing_panics_doc)] // Internal check that should never be triggered
     pub fn find(&self, needle: StyledStr<'_>) -> Option<usize> {
         let Some(first_needle_span) = needle.spans.iter().next() else {