feat(async)!: propagate stop errors in AsyncSCStream; consolidate stop delegate

Async completeness:
- AsyncSCStream now installs a delegate that, on an error stop (display
  disconnected, permission revoked, ...), closes the sample iterator so
  next().await resolves to None instead of pending forever, and records the
  SCError. Add AsyncSCStream::take_error() to retrieve it after the loop.
- AsyncSCStream::new no longer silently swallows a failed output-handler
  registration: it closes the stream and records the error.

Callback ergonomics:
- The stream engine now dispatches only the canonical did_stop_with_error on an
  error stop instead of also firing stream_did_stop for the same event.
- Deprecate SCStreamDelegateTrait::stream_did_stop (ScreenCaptureKit reports
  stops only via didStopWithError). StreamCallbacks::on_stop keeps working,
  now driven by did_stop_with_error.

All 821 tests pass; clippy clean. Updated CHANGELOG and tests.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 1313

CHANGELOG.md

@@ -22,10 +22,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   blocking call, use the synchronous `SCStream` directly via
   `stream.inner().start_capture()`.
 
+- `AsyncSCStream` now installs a stream delegate so that when `ScreenCaptureKit`
+  stops the stream with an error (display disconnected, permission revoked, …)
+  the sample iterator is closed — `next().await` resolves to `None` instead of
+  pending forever — and the error is recorded (see `take_error`). `AsyncSCStream::new`
+  likewise no longer silently swallows a failed output-handler registration: it
+  closes the stream and records the error.
+
+- The stream engine now dispatches a single canonical stop callback,
+  `SCStreamDelegateTrait::did_stop_with_error`, on an error stop. It no longer
+  also calls `stream_did_stop` for the same event (the previous behavior fired
+  both). `StreamCallbacks::on_stop` keeps working (it is now driven by
+  `did_stop_with_error`).
+
 ### Added
 
 - `async_api::StreamControlFuture` — the `Send` future returned by the
   `AsyncSCStream` lifecycle methods.
+- `AsyncSCStream::take_error` — returns the `SCError` that stopped the stream,
+  if any, after `next()` reports the iterator closed.
+
+### Deprecated
+
+- `SCStreamDelegateTrait::stream_did_stop` — `ScreenCaptureKit` only reports
+  stops via `did_stop_with_error`, which is now the single source of truth;
+  the engine no longer invokes `stream_did_stop`. Implement `did_stop_with_error`
+  instead.
 
 ## [7.0.1](https://github.com/doom-fish/screencapturekit-rs/compare/v7.0.0...v7.0.1) - 2026-06-06
 

src/async_api.rs

@@ -308,6 +308,7 @@ struct AsyncSampleIteratorState {
     waker: Option<Waker>,
     closed: bool,
     capacity: usize,
+    stop_error: Option<SCError>,
 }
 
 /// Internal sender for async sample iterator
@@ -399,6 +400,37 @@ impl Future for NextSample<'_> {
 unsafe impl Send for AsyncSampleSender {}
 unsafe impl Sync for AsyncSampleSender {}
 
+/// Stream delegate for [`AsyncSCStream`] that closes the sample iterator when
+/// `ScreenCaptureKit` stops the stream with an error.
+///
+/// Without this, a stream that fails mid-capture (captured display
+/// disconnected, permission revoked, …) would leave [`NextSample`] pending
+/// forever. On an error stop this records the [`SCError`], marks the iterator
+/// closed (so `next()` resolves to `None` once buffered frames drain), and
+/// wakes any parked task. The error is retrievable via
+/// [`AsyncSCStream::take_error`].
+struct AsyncStreamDelegate {
+    state: Arc<Mutex<AsyncSampleIteratorState>>,
+}
+
+impl crate::stream::delegate_trait::SCStreamDelegateTrait for AsyncStreamDelegate {
+    fn did_stop_with_error(&self, error: SCError) {
+        if let Ok(mut state) = self.state.lock() {
+            state.stop_error = Some(error);
+            state.closed = true;
+            if let Some(waker) = state.waker.take() {
+                waker.wake();
+            }
+        }
+    }
+}
+
+// SAFETY: mirrors `AsyncSampleSender` — `AsyncStreamDelegate` holds the same
+// `Arc<Mutex<AsyncSampleIteratorState>>`, whose contents (`CMSampleBuffer`,
+// `Waker`, `SCError`) are all safe to send and share across threads.
+unsafe impl Send for AsyncStreamDelegate {}
+unsafe impl Sync for AsyncStreamDelegate {}
+
 // ----------------------------------------------------------------------------
 // Stream lifecycle control futures (start / stop / update)
 // ----------------------------------------------------------------------------
@@ -539,14 +571,28 @@ impl AsyncSCStream {
             waker: None,
             closed: false,
             capacity: buffer_capacity,
+            stop_error: None,
         }));
 
         let sender = AsyncSampleSender {
             inner: Arc::clone(&state),
         };
 
-        let mut stream = crate::stream::SCStream::new(filter, config);
-        stream.add_output_handler(sender, output_type);
+        let delegate = AsyncStreamDelegate {
+            state: Arc::clone(&state),
+        };
+
+        let mut stream = crate::stream::SCStream::new_with_delegate(filter, config, delegate);
+        if stream.add_output_handler(sender, output_type).is_none() {
+            // Registration failed: close the iterator immediately so `next()`
+            // resolves to `None` instead of pending forever, and record why.
+            if let Ok(mut s) = state.lock() {
+                s.closed = true;
+                s.stop_error = Some(SCError::StreamError(
+                    "failed to register stream output handler".to_string(),
+                ));
+            }
+        }
 
         Self {
             stream,
@@ -570,11 +616,41 @@ impl AsyncSCStream {
     }
 
     /// Check if the stream has been closed
+    ///
+    /// Returns `true` once the stream has stopped — either because this
+    /// `AsyncSCStream` was dropped or because `ScreenCaptureKit` stopped it
+    /// with an error (see [`take_error`](Self::take_error)).
     #[must_use]
     pub fn is_closed(&self) -> bool {
         self.iterator_state.lock().map_or(true, |s| s.closed)
     }
 
+    /// Take the error that stopped the stream, if any.
+    ///
+    /// When `ScreenCaptureKit` stops the stream with an error (e.g. the
+    /// captured display is disconnected or screen-recording permission is
+    /// revoked), the sample iterator is closed — [`next`](Self::next) resolves
+    /// to `None` after any buffered frames drain — and the [`SCError`] is stored
+    /// here. Call this once the iteration loop ends to distinguish an error stop
+    /// from a normal end of stream:
+    ///
+    /// ```no_run
+    /// # async fn example(stream: screencapturekit::async_api::AsyncSCStream) {
+    /// while let Some(_frame) = stream.next().await {
+    ///     // process frames …
+    /// }
+    /// if let Some(err) = stream.take_error() {
+    ///     eprintln!("capture stopped with error: {err}");
+    /// }
+    /// # }
+    /// ```
+    ///
+    /// The stored error is cleared once taken.
+    #[must_use]
+    pub fn take_error(&self) -> Option<SCError> {
+        self.iterator_state.lock().ok()?.stop_error.take()
+    }
+
     /// Get the number of buffered samples
     #[must_use]
     pub fn buffered_count(&self) -> usize {

src/stream/delegate_trait.rs

@@ -23,16 +23,8 @@ use crate::error::SCError;
 /// struct MyDelegate;
 ///
 /// impl SCStreamDelegateTrait for MyDelegate {
-///     fn stream_did_stop(&self, error: Option<String>) {
-///         if let Some(err) = error {
-///             eprintln!("Stream stopped with error: {}", err);
-///         } else {
-///             println!("Stream stopped normally");
-///         }
-///     }
-///
 ///     fn did_stop_with_error(&self, error: SCError) {
-///         eprintln!("Stream error: {}", error);
+///         eprintln!("Stream stopped with error: {}", error);
 ///     }
 /// }
 /// ```
@@ -88,14 +80,28 @@ pub trait SCStreamDelegateTrait: Send + Sync {
     /// This callback occurs for all content filter types.
     fn stream_did_become_inactive(&self) {}
 
-    /// Called when stream stops with an error
+    /// Called when the stream stops with an error.
+    ///
+    /// This is the canonical stop notification and mirrors Apple's
+    /// `stream(_:didStopWithError:)` — the *only* way `ScreenCaptureKit`
+    /// reports a stop to the delegate. It fires when the stream stops
+    /// unexpectedly (the captured window/display goes away, screen-recording
+    /// permission is revoked, the system tears the stream down, …).
+    ///
+    /// A *clean* stop that you requested via
+    /// [`SCStream::stop_capture`](crate::stream::SCStream::stop_capture) is
+    /// **not** reported here — observe it through that method's return value.
     fn did_stop_with_error(&self, _error: SCError) {}
 
-    /// Called when stream stops
+    /// Called when stream stops.
     ///
     /// # Parameters
     ///
     /// - `error`: Optional error message if the stream stopped due to an error
+    #[deprecated(
+        note = "ScreenCaptureKit reports stops only via `did_stop_with_error`; the stream \
+                engine no longer invokes this method. Implement `did_stop_with_error` instead."
+    )]
     fn stream_did_stop(&self, _error: Option<String>) {}
 }
 
@@ -216,7 +222,15 @@ impl StreamCallbacks {
         }
     }
 
-    /// Set the callback for when the stream stops
+    /// Set the callback for when the stream stops.
+    ///
+    /// The closure receives `Some(message)` describing the error that stopped
+    /// the stream. Because `ScreenCaptureKit` only reports *error* stops to the
+    /// delegate, this fires alongside [`on_error`](Self::on_error) on an error
+    /// stop; a clean stop you requested via
+    /// [`SCStream::stop_capture`](crate::stream::SCStream::stop_capture) is not
+    /// delivered here. Prefer [`on_error`](Self::on_error) when you want the
+    /// typed [`SCError`].
     #[must_use]
     pub fn on_stop<F>(mut self, f: F) -> Self
     where
@@ -300,13 +314,22 @@ impl std::fmt::Debug for StreamCallbacks {
 }
 
 impl SCStreamDelegateTrait for StreamCallbacks {
+    // Retained so direct/manual callers (and legacy code) that still invoke
+    // `stream_did_stop` continue to route to `on_stop`. The stream engine no
+    // longer calls this; error stops flow through `did_stop_with_error` below.
+    #[allow(deprecated)]
     fn stream_did_stop(&self, error: Option<String>) {
         if let Some(ref f) = self.on_stop {
             f(error);
         }
     }
 
     fn did_stop_with_error(&self, error: SCError) {
+        // ScreenCaptureKit only reports error stops, so drive both `on_error`
+        // (typed) and `on_stop` (message) from this single engine callback.
+        if let Some(ref f) = self.on_stop {
+            f(Some(error.to_string()));
+        }
         if let Some(ref f) = self.on_error {
             f(error);
         }

src/stream/sc_stream.rs

@@ -170,7 +170,7 @@ extern "C" fn delegate_error_callback(context: *mut c_void, error_code: i32, msg
             },
         )
     } else {
-        SCError::StreamError(message.clone())
+        SCError::StreamError(message)
     };
 
     // Take a read lock and dispatch under it. Multiple delegate callbacks
@@ -183,13 +183,14 @@ extern "C" fn delegate_error_callback(context: *mut c_void, error_code: i32, msg
         .unwrap_or_else(std::sync::PoisonError::into_inner);
 
     if let Some(ref delegate) = *delegate_guard {
-        // Wrap user code in catch_unwind so panics never propagate into Swift.
+        // ScreenCaptureKit reports stops only through `stream(_:didStopWithError:)`,
+        // so we dispatch the single canonical `did_stop_with_error` callback.
+        // The deprecated `stream_did_stop` is intentionally NOT invoked here — it
+        // would double-notify for one event. Wrap user code in catch_unwind so a
+        // panic never propagates into Swift.
         catch_user_panic("delegate.did_stop_with_error", || {
             delegate.did_stop_with_error(error);
         });
-        catch_user_panic("delegate.stream_did_stop", || {
-            delegate.stream_did_stop(Some(message));
-        });
         return;
     }
 
@@ -362,9 +363,12 @@ impl SCStream {
 
     /// Create a new stream with a content filter, configuration, and delegate
     ///
-    /// The delegate receives callbacks for stream lifecycle events:
-    /// - `did_stop_with_error` - Called when the stream stops due to an error
-    /// - `stream_did_stop` - Called when the stream stops (with optional error message)
+    /// The delegate receives callbacks for stream lifecycle events. The key
+    /// one is [`did_stop_with_error`](crate::stream::delegate_trait::SCStreamDelegateTrait::did_stop_with_error),
+    /// invoked when `ScreenCaptureKit` stops the stream with an error (e.g. the
+    /// captured window closes or permission is revoked). A *clean* stop you
+    /// requested via [`stop_capture`](Self::stop_capture) is observed through
+    /// that call's return value, not the delegate.
     ///
     /// # Examples
     ///
@@ -384,12 +388,7 @@ impl SCStream {
     ///     .with_height(1080);
     ///
     /// let delegate = StreamCallbacks::new()
-    ///     .on_error(|e| eprintln!("Stream error: {}", e))
-    ///     .on_stop(|err| {
-    ///         if let Some(msg) = err {
-    ///             eprintln!("Stream stopped with error: {}", msg);
-    ///         }
-    ///     });
+    ///     .on_error(|e| eprintln!("Stream stopped with error: {}", e));
     ///
     /// let stream = SCStream::new_with_delegate(&filter, &config, delegate);
     /// stream.start_capture()?;

tests/async_api_tests.rs

@@ -336,6 +336,28 @@ fn test_async_stream_output_type() {
     assert!(debug_audio.contains("Audio"));
 }
 
+#[test]
+fn test_async_stream_take_error_initially_none() {
+    use screencapturekit::shareable_content::SCShareableContent;
+    use screencapturekit::stream::configuration::SCStreamConfiguration;
+    use screencapturekit::stream::content_filter::SCContentFilter;
+
+    if let Ok(content) = SCShareableContent::get() {
+        if let Some(display) = content.displays().first() {
+            let filter = SCContentFilter::create()
+                .with_display(display)
+                .with_excluding_windows(&[])
+                .build();
+            let config = SCStreamConfiguration::new().with_width(100).with_height(100);
+            let stream = AsyncSCStream::new(&filter, &config, 4, SCStreamOutputType::Screen);
+
+            // A freshly created stream is open and has no stop error.
+            assert!(!stream.is_closed());
+            assert!(stream.take_error().is_none());
+        }
+    }
+}
+
 #[cfg(feature = "macos_14_0")]
 mod macos_14_tests {
     use super::*;
@@ -1228,4 +1250,10 @@ async fn test_async_frame_delivery_assertive() {
     assert!(second.is_some(), "expected continuous frame delivery");
 
     stream.stop_capture().await.expect("stop_capture failed");
+
+    // A clean stop must not surface a stop error.
+    assert!(
+        stream.take_error().is_none(),
+        "clean capture should leave no stop error"
+    );
 }

tests/delegate_trait_tests.rs

@@ -1,6 +1,9 @@
 //! `SCStreamDelegateTrait` tests
 
 #![allow(clippy::struct_field_names)]
+// Several tests still exercise the deprecated `stream_did_stop` directly to
+// keep its routing covered; suppress the deprecation lint for the whole file.
+#![allow(deprecated)]
 
 use screencapturekit::error::SCError;
 use screencapturekit::stream::delegate_trait::{