fix(stream-config): pin BGRA as default pixel format (#145)

Apple's stock SCStreamConfiguration() no longer guarantees a BGRA
default — on macOS 26 / Apple Silicon the runtime silently switched
to kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange ('420v') unless
the caller explicitly overrides pixelFormat. That broke consumers
that assumed packed BGRA samples (the long-standing documented
default for this crate) and produced unrecognisable images when
client code read the Y luma plane as if it were BGRA.

Pin pixelFormat = kCVPixelFormatType_32BGRA inside the Swift bridge
sc_stream_configuration_create so SCStreamConfiguration::new() and
::default() deliver a stable BGRA wire format across macOS versions.
The preset path (sc_stream_configuration_create_with_preset) is
intentionally untouched — presets pick their own pixel format
(e.g. HDR 10-bit formats).

Add test_default_pixel_format_is_bgra to lock the guarantee in, plus
docstrings on PixelFormat::BGRA and set_pixel_format describing the
new contract.

Fixes #145

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

Author: 1313

src/stream/configuration/colors.rs

@@ -24,6 +24,13 @@ use super::{internal::SCStreamConfiguration, pixel_format::PixelFormat};
 impl SCStreamConfiguration {
     /// Set the pixel format for captured frames
     ///
+    /// Streams created via [`Self::new`] / [`Self::default`] are pinned to
+    /// [`PixelFormat::BGRA`] at construction time, so calling this method is
+    /// only required when you want a non-BGRA format (e.g. YUV `420v` for
+    /// video encoding, or `l10r` for HDR). Apple's runtime default for
+    /// `SCStreamConfiguration()` varies by macOS release — see
+    /// [`PixelFormat::BGRA`] for context.
+    ///
     /// # Examples
     ///
     /// ```

src/stream/configuration/pixel_format.rs

@@ -47,7 +47,15 @@ use crate::utils::four_char_code::FourCharCode;
 #[derive(Debug, Clone, Copy, Default)]
 #[non_exhaustive]
 pub enum PixelFormat {
-    /// Packed little endian ARGB8888 (most common)
+    /// Packed little-endian 32-bit BGRA — the default pixel format for
+    /// streams created via [`crate::stream::configuration::SCStreamConfiguration::new`].
+    ///
+    /// The crate pins this format at construction time so that
+    /// `SCStreamConfiguration::new()` delivers a stable BGRA wire format
+    /// across macOS releases. Without the explicit pin Apple's runtime
+    /// chooses its own default, which on macOS 26 / Apple Silicon is
+    /// `420v` (bi-planar YCbCr) — silently breaking consumers that assume
+    /// packed BGRA samples. See issue #145.
     #[default]
     BGRA,
     /// Packed little endian ARGB2101010 (10-bit color)

swift-bridge/Sources/ScreenCaptureKitBridge/StreamConfiguration.swift

@@ -2,6 +2,7 @@
 
 import CoreGraphics
 import CoreMedia
+import CoreVideo
 import Foundation
 import ScreenCaptureKit
 
@@ -69,6 +70,16 @@ private func streamConfigurationState(for config: SCStreamConfiguration) -> Stre
 @_cdecl("sc_stream_configuration_create")
 public func createStreamConfiguration() -> OpaquePointer {
     let config = SCStreamConfiguration()
+    // Apple's stock `SCStreamConfiguration()` no longer guarantees a BGRA
+    // default — on macOS 26 / Apple Silicon the runtime delivers
+    // `kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange` ('420v') unless the
+    // caller explicitly overrides `pixelFormat`. That silently breaks
+    // consumers that assume 32-bit BGRA samples (the long-standing
+    // documented default for this crate). Pin BGRA at construction so
+    // `SCStreamConfiguration::new()` produces the same wire-level format
+    // across macOS versions. Callers who want YUV / HDR formats override
+    // this via `set_pixel_format` as before. See issue #145.
+    config.pixelFormat = kCVPixelFormatType_32BGRA
     retainStreamConfigurationState(for: config)
     return retain(config)
 }

tests/configuration_tests.rs

@@ -10,6 +10,24 @@ fn test_default_configuration() {
     // Just verify it doesn't crash
 }
 
+/// Regression test for issue #145.
+///
+/// Apple's stock `SCStreamConfiguration()` no longer defaults to BGRA on
+/// macOS 26 / Apple Silicon — the runtime delivers `420v` unless the caller
+/// overrides `pixelFormat`. The Swift bridge pins BGRA at construction time
+/// to restore the long-standing crate default; this test locks in that
+/// guarantee so a future regression in the bridge surfaces immediately.
+#[test]
+fn test_default_pixel_format_is_bgra() {
+    let config = SCStreamConfiguration::new();
+    assert_eq!(
+        config.pixel_format(),
+        PixelFormat::BGRA,
+        "SCStreamConfiguration::new() must default to BGRA across macOS \
+         versions (see issue #145)",
+    );
+}
+
 #[test]
 fn test_set_dimensions() {
     let mut config = SCStreamConfiguration::default();