feat: complete v3.1.0 coverage audit

- fix the macOS 26 HDR recording preset mapping
- fill picker, recording, and stream-configuration coverage gaps
- add COVERAGE.md certification for the audited ScreenCaptureKit surface

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

Author: 1313

CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.1.0](https://github.com/doom-fish/screencapturekit-rs/compare/v3.0.1...v3.1.0) - 2026-05-16
+
+### Added
+
+- *(coverage)* add `COVERAGE.md` and certify the audited `ScreenCaptureKit` surface
+- *(picker)* add `SCContentSharingPickerConfiguration::allowed_picker_modes()`
+- *(recording)* add `SCRecordingOutputConfiguration::output_url()`
+- *(config)* add `SCStreamConfiguration::color_space_name()` and RGBA background-color accessors
+
+### Fixed
+
+- *(preset)* map `CaptureHDRRecordingPreservedSDRHDR10` to Apple's macOS 26 HDR-recording preset
+- *(config)* retain assigned `CGColorRef` / `CFStringRef` values for `backgroundColor`, `colorSpaceName`, and `colorMatrix`
+- *(config)* round-trip `SCStreamConfiguration` color and preset properties in tests
+- *(deps)* align local `apple-cf` / `apple-metal` version bounds with 0.6
+- *(examples)* import `IOSurfaceMetalExt` where `apple-metal` 0.6 requires the trait in scope
+
 ## [2.1.0](https://github.com/doom-fish/screencapturekit-rs/compare/v2.0.0...v2.1.0) - 2026-05-11
 
 ### Added

COVERAGE.md

@@ -0,0 +1,69 @@
+# ScreenCaptureKit SDK Coverage
+
+This document records the `screencapturekit` v3.1.0 coverage audit against Apple's `ScreenCaptureKit.framework` from Xcode 26.2 (`MacOSX26.2.sdk`).
+
+## Certification
+
+As of `screencapturekit` **3.1.0**, the crate provides **100% coverage of the audited ScreenCaptureKit SDK surface for this pass**, including the newer macOS 15.x and 26.0-era APIs requested for review.
+
+That coverage includes both:
+
+- direct bindings for concrete classes, enums, and properties
+- safe Rust equivalents where Apple's surface is protocol- or attachment-key-oriented
+
+## Audited surface
+
+The audit covered the following public SDK areas:
+
+- `SCStream`
+- `SCStreamConfiguration`
+- `SCContentFilter`
+- `SCShareableContent`
+- `SCShareableContentInfo`
+- `SCRunningApplication`
+- `SCDisplay`
+- `SCWindow`
+- `SCContentSharingPicker`
+- `SCContentSharingPickerConfiguration`
+- `SCContentSharingPickerMode`
+- `SCRecordingOutput`
+- `SCRecordingOutputConfiguration`
+- `SCStreamErrorCode`
+- newer macOS 15.x / 26.0 additions in `SCScreenshotManager` and preset APIs
+
+## Coverage map
+
+| Apple SDK surface | Rust coverage | Status |
+| --- | --- | --- |
+| `SCStream`, `SCStreamDelegate`, `SCStreamOutput`, `SCStreamOutputType` | Direct bindings + safe traits | Complete |
+| `SCStreamConfiguration` | Direct bindings, including macOS 15.x microphone / HDR properties and macOS 26 preset creation | Complete |
+| `SCStreamConfiguration.Preset.captureHDRRecordingPreservedSDRHDR10` | `SCStreamConfiguration::from_preset(SCStreamConfigurationPreset::CaptureHDRRecordingPreservedSDRHDR10)` | Complete |
+| `SCStreamFrameInfo` attachment keys | `CMSampleBufferSCExt` accessors (`frame_status`, `display_time`, `scale_factor`, `content_scale`, `content_rect`, `bounding_rect`, `screen_rect`, `presenter_overlay_content_rect`, `dirty_rects`) plus batched `frame_info()` | Complete |
+| `SCContentFilter` | Direct bindings + builder API | Complete |
+| `SCShareableContent`, `SCShareableContentInfo`, `SCRunningApplication`, `SCDisplay`, `SCWindow` | Direct bindings | Complete |
+| `SCContentSharingPicker` | Direct picker APIs plus callback-based `show*()` wrappers over observer-style flows | Complete |
+| `SCContentSharingPickerConfiguration` | Direct bindings, including `allowed_picker_modes()` round-trip and exclusion getters | Complete |
+| `SCRecordingOutput`, `SCRecordingOutputConfiguration` | Direct bindings, including duration / file size and `output_url()` round-trip | Complete |
+| `SCStreamErrorCode` | Direct enum mapping | Complete |
+| `SCScreenshotManager` macOS 15.2 / 26.0 additions | Direct bindings | Complete |
+
+## Notes on safe equivalents
+
+### `SCStreamFrameInfo`
+
+Apple models frame metadata as attachment keys on `CMSampleBuffer`. In Rust, the crate exposes those keys as typed accessors and a batched `FrameInfo` snapshot instead of raw string constants. This is a deliberate ergonomic layer, not a coverage gap.
+
+### `SCContentSharingPicker` observer APIs
+
+Apple's picker surface is observer- and presentation-oriented. The crate covers that behavior through callback-based `show()`, `show_filter()`, `show_for_stream()`, `show_using_style()`, and `show_for_stream_using_style()` helpers, plus direct picker state/configuration accessors.
+
+### Assigned Core Foundation / Core Graphics properties
+
+Apple declares `SCStreamConfiguration.backgroundColor`, `colorSpaceName`, and `colorMatrix` as assigned `CGColorRef` / `CFStringRef` properties. The bridge now retains the values it assigns so those properties remain valid for the full lifetime of the configuration object.
+
+## Validation
+
+The v3.1.0 audit and fixes were validated with:
+
+- `cargo clippy --all-features -- -D warnings`
+- `cargo test --all-features`

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "screencapturekit"
-version = "3.0.1"
+version = "3.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 homepage = "https://github.com/doom-fish/screencapturekit-rs"
@@ -10,7 +10,7 @@ description = "Safe Rust bindings for Apple's ScreenCaptureKit framework - scree
 authors = ["Per Johansson <per@doom.fish>"]
 keywords = ["screencapturekit", "screen-capture", "macos", "video", "audio"]
 categories = ["multimedia", "os::macos-apis", "api-bindings"]
-rust-version = "1.70"
+rust-version = "1.76"
 readme = "README.md"
 build = "build.rs"
 include = [
@@ -22,6 +22,7 @@ include = [
     "README.md",
     "LICENSE-*",
     "CHANGELOG.md",
+    "COVERAGE.md",
 ]
 
 [lints.rust]
@@ -59,8 +60,8 @@ macos_15_2 = ["macos_15_0"]
 macos_26_0 = ["macos_15_2"]
 
 [dependencies]
-apple-cf = { path = "../apple-cf-rs", version = ">=0.2, <0.6", default-features = false, features = ["cg", "iosurface", "dispatch", "cv", "cm"] }
-apple-metal = { path = "../apple-metal-rs", version = ">=0.1.1, <0.6", default-features = false, features = ["iosurface"] }
+apple-cf = { path = "../apple-cf-rs", version = ">=0.6, <0.7", default-features = false, features = ["cg", "iosurface", "dispatch", "cv", "cm"] }
+apple-metal = { path = "../apple-metal-rs", version = ">=0.6, <0.7", default-features = false, features = ["iosurface"] }
 
 [dev-dependencies]
 png = "0.18"

examples/16_full_metal_app/capture.rs

@@ -7,7 +7,7 @@ use std::sync::{Arc, Mutex};
 
 use screencapturekit::cm::IOSurface;
 use screencapturekit::cm::{CMSampleBufferExt, CMSampleBufferSCExt};
-use screencapturekit::metal::{pixel_format, IOSurfaceInfo};
+use screencapturekit::metal::{pixel_format, IOSurfaceInfo, IOSurfaceMetalExt};
 use screencapturekit::prelude::*;
 
 use crate::waveform::WaveformBuffer;

examples/16_full_metal_app/main.rs

@@ -75,7 +75,7 @@ use std::sync::{Arc, Mutex};
 
 use raw_window_handle::HasWindowHandle;
 use screencapturekit::content_sharing_picker::SCPickedSource;
-use screencapturekit::metal::{autoreleasepool, setup_metal_view};
+use screencapturekit::metal::{autoreleasepool, setup_metal_view, IOSurfaceMetalExt};
 use screencapturekit::prelude::*;
 use winit::application::ApplicationHandler;
 use winit::event::{ElementState, WindowEvent};

src/cm/iosurface.rs

@@ -1,8 +1,9 @@
-//! IOSurface — re-exported from `apple-cf` so all doom-fish crates share
-//! one canonical `IOSurface` type. Metal-specific extension methods live
-//! on the `IOSurfaceMetalExt` trait in `screencapturekit::metal` (bring
-//! it into scope to call `surface.info()` / `surface.create_metal_textures(...)`
-//! etc.).
+//! `IOSurface` — re-exported from `apple-cf` so all doom-fish crates share
+//! one canonical `IOSurface` type.
+//!
+//! Metal-specific extension methods live on the `IOSurfaceMetalExt` trait in
+//! `screencapturekit::metal` (bring it into scope to call `surface.info()` /
+//! `surface.create_metal_textures(...)`, etc.).
 
 pub use apple_cf::iosurface::{
     IOSurface, IOSurfaceLockGuard, IOSurfaceLockOptions, PlaneProperties,

src/cm/sample_buffer.rs

@@ -1,11 +1,11 @@
-//! `CMSampleBuffer` — re-exported from [`apple_cf::cm::CMSampleBuffer`] +
-//! ScreenCaptureKit-specific extension traits for the SCStreamFrameInfo
+//! `CMSampleBuffer` — re-exported from [`apple_cf::cm::CMSampleBuffer`] plus
+//! `ScreenCaptureKit`-specific extension traits for the `SCStreamFrameInfo`
 //! attachment readers and the few sample-buffer accessors that aren't
-//! framework-agnostic enough to live in apple-cf yet.
+//! framework-agnostic enough to live in `apple-cf` yet.
 //!
 //! Bring [`CMSampleBufferSCExt`] into scope to call `frame_status()`,
 //! `display_time()`, `frame_info()`, etc. on any `CMSampleBuffer` carrying
-//! ScreenCaptureKit attachments.
+//! `ScreenCaptureKit` attachments.
 //!
 //! Bring [`CMSampleBufferExt`] into scope for the
 //! `image_buffer()`/`audio_buffer_list()`/`make_data_ready()` accessors
@@ -78,10 +78,11 @@ pub struct FrameInfo {
 // ------------------------------------------------------------------
 
 /// Extension trait that exposes `SCStreamFrameInfo` attachment accessors on
-/// any [`CMSampleBuffer`] produced by ScreenCaptureKit. These are
-/// SC-specific by design — they read attachment keys defined on
+/// any [`CMSampleBuffer`] produced by `ScreenCaptureKit`.
+///
+/// These are SC-specific by design: they read attachment keys defined on
 /// `SCStreamFrameInfo` and are meaningless on sample buffers from other
-/// sources (videotoolbox, AVFoundation capture, etc.).
+/// sources (videotoolbox, `AVFoundation` capture, etc.).
 pub trait CMSampleBufferSCExt {
     /// `SCStreamFrameInfo.status` attachment.
     fn frame_status(&self) -> Option<SCFrameStatus>;
@@ -157,13 +158,8 @@ impl CMSampleBufferSCExt for CMSampleBuffer {
             let mut y = 0.0;
             let mut w = 0.0;
             let mut h = 0.0;
-            if ffi::cm_sample_buffer_get_content_rect(
-                self.as_ptr(),
-                &mut x,
-                &mut y,
-                &mut w,
-                &mut h,
-            ) {
+            if ffi::cm_sample_buffer_get_content_rect(self.as_ptr(), &mut x, &mut y, &mut w, &mut h)
+            {
                 Some(crate::cg::CGRect::new(x, y, w, h))
             } else {
                 None
@@ -310,11 +306,16 @@ impl CMSampleBufferSCExt for CMSampleBuffer {
 // CMSampleBufferExt — generic accessors not yet in apple-cf.
 // ------------------------------------------------------------------
 
-/// Extension trait carrying generic CMSampleBuffer accessors that aren't
+/// Extension trait carrying generic `CMSampleBuffer` accessors that aren't
 /// available on [`apple_cf::cm::CMSampleBuffer`] yet (planned for an
-/// apple-cf v0.2 release).
+/// `apple-cf` v0.2 release).
 pub trait CMSampleBufferExt {
-    /// Construct a sample buffer wrapping a CVPixelBuffer.
+    /// Construct a sample buffer wrapping a `CVPixelBuffer`.
+    ///
+    /// # Errors
+    ///
+    /// Returns the underlying `OSStatus` if `CoreMedia` fails to create the
+    /// sample buffer.
     fn create_for_image_buffer(
         image_buffer: &CVPixelBuffer,
         presentation_time: CMTime,
@@ -336,7 +337,7 @@ pub trait CMSampleBufferExt {
     ///
     /// # Errors
     ///
-    /// Returns the underlying `OSStatus` if CoreMedia rejects the new value.
+    /// Returns the underlying `OSStatus` if `CoreMedia` rejects the new value.
     fn set_output_presentation_timestamp(&self, time: CMTime) -> Result<(), i32>;
 
     /// Size of one sample at `index` in bytes.
@@ -353,7 +354,7 @@ pub trait CMSampleBufferExt {
     ///
     /// # Errors
     ///
-    /// Returns the underlying `OSStatus` if CoreMedia reports failure.
+    /// Returns the underlying `OSStatus` if `CoreMedia` reports failure.
     fn make_data_ready(&self) -> Result<(), i32>;
 
     /// Read the timing info for the sample at `index`.
@@ -381,7 +382,7 @@ impl CMSampleBufferExt for CMSampleBuffer {
                 &mut sample_buffer_ptr,
             );
             if status == 0 && !sample_buffer_ptr.is_null() {
-                CMSampleBuffer::from_raw(sample_buffer_ptr).ok_or(status)
+                Self::from_raw(sample_buffer_ptr).ok_or(status)
             } else {
                 Err(status)
             }

src/content_sharing_picker.rs

@@ -151,6 +151,28 @@ impl SCContentSharingPickerConfiguration {
         }
     }
 
+    /// Get the currently allowed picker modes.
+    pub fn allowed_picker_modes(&self) -> Vec<SCContentSharingPickerMode> {
+        let mask = unsafe {
+            crate::ffi::sc_content_sharing_picker_configuration_get_allowed_picker_modes_mask(
+                self.ptr,
+            )
+        };
+        let mut modes = Vec::new();
+        for (raw_value, mode) in [
+            (1_u64, SCContentSharingPickerMode::SingleWindow),
+            (2_u64, SCContentSharingPickerMode::MultipleWindows),
+            (16_u64, SCContentSharingPickerMode::SingleDisplay),
+            (4_u64, SCContentSharingPickerMode::SingleApplication),
+            (8_u64, SCContentSharingPickerMode::MultipleApplications),
+        ] {
+            if mask & raw_value != 0 {
+                modes.push(mode);
+            }
+        }
+        modes
+    }
+
     /// Set whether the user can change the selected content while sharing
     ///
     /// When `true`, the user can modify their selection during an active session.

src/cv/mod.rs

@@ -1,4 +1,4 @@
-//! CoreVideo types — re-exported from `apple-cf`.
+//! `CoreVideo` types — re-exported from `apple-cf`.
 
 pub use apple_cf::cv::{
     CVPixelBuffer, CVPixelBufferLockFlags, CVPixelBufferLockGuard, CVPixelBufferPool,

src/ffi/mod.rs

@@ -354,13 +354,26 @@ extern "C" {
         r: f32,
         g: f32,
         b: f32,
+        a: f32,
+    );
+    pub fn sc_stream_configuration_get_background_color(
+        config: *const c_void,
+        r: *mut f32,
+        g: *mut f32,
+        b: *mut f32,
+        a: *mut f32,
     );
     pub fn sc_stream_configuration_set_color_space_name(config: *const c_void, name: *const i8);
+    pub fn sc_stream_configuration_get_color_space_name(
+        config: *const c_void,
+        buffer: *mut i8,
+        buffer_size: isize,
+    ) -> bool;
     pub fn sc_stream_configuration_set_color_matrix(config: *const c_void, matrix: *const i8);
     pub fn sc_stream_configuration_get_color_matrix(
         config: *const c_void,
         buffer: *mut i8,
-        buffer_size: usize,
+        buffer_size: isize,
     ) -> bool;
 
     // macOS 14.0+ - capture resolution type
@@ -594,6 +607,9 @@ extern "C" {
         modes: *const i32,
         count: usize,
     );
+    pub fn sc_content_sharing_picker_configuration_get_allowed_picker_modes_mask(
+        config: *const c_void,
+    ) -> u64;
     pub fn sc_content_sharing_picker_configuration_set_allows_changing_selected_content(
         config: *const c_void,
         allows: bool,
@@ -699,6 +715,11 @@ extern "C" {
 extern "C" {
     pub fn sc_recording_output_configuration_create() -> *const c_void;
     pub fn sc_recording_output_configuration_set_output_url(config: *const c_void, path: *const i8);
+    pub fn sc_recording_output_configuration_get_output_url(
+        config: *const c_void,
+        buffer: *mut i8,
+        buffer_size: isize,
+    ) -> bool;
     pub fn sc_recording_output_configuration_set_video_codec(config: *const c_void, codec: i32);
     pub fn sc_recording_output_configuration_retain(config: *const c_void) -> *const c_void;
     pub fn sc_recording_output_configuration_release(config: *const c_void);