docs: update README and MIGRATION for 2.x

- Bump install snippets from version "1" to "2"
- Document 2.0 breaking changes: Send + Sync handlers, #[non_exhaustive]
  PixelFormat / SCStreamErrorCode, PixelFormat::Unknown(FourCharCode)
- Add 2.1 buffer-reuse APIs (bgra_data_into / rgba_data_into) and the
  native-BGRA fast-path note to the Performance section
- Surface ContentSnapshot, AudioInputDevice, FourCharCode in API tables
- Mention the new presenter_overlay_content_rect frame-info attachment
- Add a 1.x -> 2.0 and 2.0 -> 2.1 migration section to MIGRATION.md

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

Author: 1313

README.md

@@ -59,23 +59,30 @@ Add to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-screencapturekit = "1"
+screencapturekit = "2"
 ```
 
 For async support:
 
 ```toml
 [dependencies]
-screencapturekit = { version = "1", features = ["async"] }
+screencapturekit = { version = "2", features = ["async"] }
 ```
 
 For latest macOS features:
 
 ```toml
 [dependencies]
-screencapturekit = { version = "1", features = ["macos_26_0"] }
+screencapturekit = { version = "2", features = ["macos_26_0"] }
 ```
 
+> **Upgrading from 1.x?** See [`docs/MIGRATION.md`](docs/MIGRATION.md#migrating-from-1x-to-20)
+> for the full list of 2.0 breaking changes — most notable are the new
+> `Send + Sync` bound on output / delegate traits, the `#[non_exhaustive]`
+> attribute on `PixelFormat` and `SCStreamErrorCode`, and the new
+> `PixelFormat::Unknown(FourCharCode)` variant for codes the binding does
+> not yet name.
+
 ## 🚀 Quick Start
 
 ### Basic Screen Capture
@@ -91,6 +98,10 @@ impl SCStreamOutputTrait for Handler {
     }
 }
 
+// Note: as of 2.0, `SCStreamOutputTrait` (and `SCStreamDelegateTrait`)
+// require `Send + Sync` — handlers run on Apple's dispatch queues and may
+// be invoked concurrently from arbitrary threads.
+
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Get available displays
     let content = SCShareableContent::get()?;
@@ -463,6 +474,8 @@ config.set_should_be_opaque(true);
 | `SCDisplay` | Display information (resolution, ID, frame) |
 | `SCWindow` | Window information (title, bounds, owner, layer) |
 | `SCRunningApplication` | Application information (name, bundle ID, PID) |
+| `ContentSnapshot` | Plain-data batch of all displays, windows, applications (one FFI round-trip) |
+| `AudioInputDevice` | Microphone enumeration via `AVFoundation` (used with `with_microphone_capture_device_id`) |
 
 ### Media Types
 
@@ -491,12 +504,16 @@ config.set_should_be_opaque(true);
 
 | Type | Description |
 |------|-------------|
-| `PixelFormat` | BGRA, `YCbCr420v`, `YCbCr420f`, l10r (10-bit) |
+| `PixelFormat` | BGRA, `YCbCr420v`, `YCbCr420f`, l10r (10-bit), `Unknown(FourCharCode)` for forward-compat |
+| `FourCharCode` | Apple OSType four-char code helper used by `PixelFormat::Unknown` |
 | `SCPresenterOverlayAlertSetting` | Privacy alert behavior |
 | `SCCaptureDynamicRange` | HDR/SDR modes (macOS 15.0+) |
 | `SCScreenshotConfiguration` | Advanced screenshot config (macOS 26.0+) |
 | `SCScreenshotDynamicRange` | SDR/HDR screenshot output (macOS 26.0+) |
 
+> **2.0 note:** `PixelFormat` and `SCStreamErrorCode` are `#[non_exhaustive]`.
+> `match` arms over either of them must include a wildcard `_ => …` arm.
+
 ## 🏃 Examples
 
 The [`examples/`](examples/) directory contains focused API demonstrations:
@@ -744,14 +761,16 @@ for w in &windows {
 ```
 
 Same idea on a video sample buffer — read every attachment in one CF→Swift
-bridge cast instead of one cast per attribute:
+bridge cast instead of one cast per attribute (this includes the new-in-2.0
+`presenter_overlay_content_rect` field for Presenter Overlay layouts):
 
 ```rust,no_run
 # use screencapturekit::cm::CMSampleBuffer;
 # fn example(sample: &CMSampleBuffer) {
 if let Some(info) = sample.frame_info() {
-    println!("status={:?} time={:?} content={:?}",
-             info.frame_status, info.display_time, info.content_rect);
+    println!("status={:?} time={:?} content={:?} overlay={:?}",
+             info.frame_status, info.display_time, info.content_rect,
+             info.presenter_overlay_content_rect);
 }
 # }
 ```
@@ -774,17 +793,46 @@ let pixels = img.bgra_data()?;   // ~5% faster than rgba_data() at 1080p
 # }
 ```
 
+For sustained screenshot loops, the new (2.1+) `*_data_into` variants
+write into a caller-supplied buffer so you only pay the
+`width × height × 4` byte allocation once instead of per frame
+(~33 MB / call at 4K):
+
+```rust,no_run
+# #[cfg(feature = "macos_14_0")]
+# fn example(
+#     filter: &screencapturekit::stream::content_filter::SCContentFilter,
+#     config: &screencapturekit::stream::configuration::SCStreamConfiguration,
+# ) -> Result<(), Box<dyn std::error::Error>> {
+use screencapturekit::screenshot_manager::SCScreenshotManager;
+let mut buffer: Vec<u8> = vec![0; 1920 * 1080 * 4];
+for _ in 0..100 {
+    let img = SCScreenshotManager::capture_image(filter, config)?;
+    img.bgra_data_into(&mut buffer)?;     // reuse the same allocation
+    // ... process `buffer` ...
+}
+# Ok(())
+# }
+```
+
 See [`examples/24_batched_apis_showcase.rs`](examples/24_batched_apis_showcase.rs)
 for a side-by-side comparison that benchmarks all three APIs against the
 legacy per-element pattern on your machine.
 
 ## 🔄 Migration
 
 Upgrading from an older version? See [`docs/MIGRATION.md`](docs/MIGRATION.md) for:
-- API changes between versions
+- API changes between versions (including the **1.x → 2.0** upgrade path)
 - Code examples for common migrations
 - Deprecated API replacements
 
+**Highlights of 2.0 breaking changes:**
+- `SCStreamOutputTrait` and `SCStreamDelegateTrait` now require `Send + Sync`
+- `PixelFormat` is `#[non_exhaustive]` and gained a `Unknown(FourCharCode)` variant
+- `SCStreamErrorCode` is `#[non_exhaustive]`
+- `PartialEq` / `Hash` for `PixelFormat` now normalise through `FourCharCode`
+- Every `macos_*` Cargo feature now propagates to the Swift bridge build (build will fail loudly if SDK detection fails)
+
 ## 🤝 Contributing
 
 Contributions welcome! Please:

docs/MIGRATION.md

@@ -2,6 +2,130 @@
 
 This guide helps you migrate between major versions of `screencapturekit-rs`.
 
+## Migrating from 1.x to 2.0
+
+Version 2.0 hardens the FFI boundary. Most projects can upgrade by
+bumping the dependency and addressing a handful of compile errors —
+no design-level rework is required.
+
+### Cargo.toml
+
+```diff
+ [dependencies]
+-screencapturekit = "1"
++screencapturekit = "2"
+```
+
+### `Send + Sync` bound on output / delegate traits
+
+`SCStreamOutputTrait` and `SCStreamDelegateTrait` (and the `Fn(...)` closure
+overloads) now require `Send + Sync`. Apple's dispatch queues may invoke the
+handler concurrently from arbitrary threads, so any state owned by the
+handler must be thread-safe.
+
+**Before (1.x):**
+```rust,ignore
+struct Handler { count: std::cell::Cell<usize> }   // !Sync — compiles in 1.x
+impl SCStreamOutputTrait for Handler { /* ... */ }
+```
+
+**After (2.0):**
+```rust,ignore
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+struct Handler { count: AtomicUsize }              // Send + Sync
+impl SCStreamOutputTrait for Handler {
+    fn did_output_sample_buffer(&self, _: CMSampleBuffer, _: SCStreamOutputType) {
+        self.count.fetch_add(1, Ordering::Relaxed);
+    }
+}
+```
+
+For closures: replace `Cell` / `Rc` with `Arc<Atomic*>` /
+`Arc<Mutex<...>>` / `Arc<RwLock<...>>`.
+
+### `PixelFormat::Unknown(FourCharCode)`
+
+`PixelFormat` is now `#[non_exhaustive]` and surfaces unrecognised codes
+via a new `Unknown(FourCharCode)` variant instead of mapping them to
+`BGRA`. This means **every `match` over `PixelFormat` must include a
+wildcard arm**:
+
+**Before (1.x):**
+```rust,ignore
+match config.pixel_format() {
+    PixelFormat::BGRA => { /* ... */ }
+    PixelFormat::YCbCr420v => { /* ... */ }
+    PixelFormat::YCbCr420f => { /* ... */ }
+    PixelFormat::L10R => { /* ... */ }
+}
+```
+
+**After (2.0):**
+```rust,ignore
+match config.pixel_format() {
+    PixelFormat::BGRA => { /* ... */ }
+    PixelFormat::YCbCr420v => { /* ... */ }
+    PixelFormat::YCbCr420f => { /* ... */ }
+    PixelFormat::L10R => { /* ... */ }
+    PixelFormat::Unknown(code) => eprintln!("unrecognised pixel format: {code}"),
+    _ => { /* future variants */ }
+}
+```
+
+`PartialEq` / `Hash` are now normalised through `FourCharCode`, so two
+representations of the same OSType (e.g. `PixelFormat::BGRA` vs
+`PixelFormat::Unknown(FourCharCode::from_bytes(*b"BGRA"))`) compare equal.
+
+### `SCStreamErrorCode` is `#[non_exhaustive]`
+
+`match` arms over `SCStreamErrorCode` (typically inside an
+`SCError::StreamError { code, .. }` arm) now require a wildcard:
+
+```rust,ignore
+match err_code {
+    SCStreamErrorCode::UserStopped => { /* graceful */ }
+    SCStreamErrorCode::UserDeclined => { /* permission */ }
+    _ => { /* anything Apple adds in a future macOS */ }
+}
+```
+
+### Build-time SDK enforcement
+
+The build script no longer silently degrades when xcrun / SDK detection
+fails — it bails with a clear error pointing at `xcode-select`. Make sure
+Xcode Command Line Tools are installed and selected:
+
+```bash
+xcode-select --install
+sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
+```
+
+Every `macos_*` Cargo feature is also forwarded to the Swift compile, so
+a feature only enabled on the Rust side (which used to silently miss the
+matching Swift symbols) will now produce a coherent linker error.
+
+### New APIs you can opt into
+
+- `SCContentSharingPicker::is_active()` / `set_is_active()` — query and
+  toggle the picker's idle state without recreating it.
+- `SCContentSharingPicker::default_configuration()` — read the system
+  default `SCContentSharingPickerConfiguration` so user-facing pickers
+  match macOS defaults.
+- `CMSampleBuffer::presenter_overlay_content_rect()` (and the matching
+  field on `frame_info()`) — the new Presenter Overlay layout rect.
+
+## Migrating from 2.0 to 2.1
+
+2.1 is fully backwards-compatible with 2.0 — no source changes required.
+New optional APIs:
+
+- `CGImage::rgba_data_into(&mut [u8])` and `bgra_data_into(&mut [u8])` —
+  render into a caller-supplied buffer to amortise the per-call
+  `width*height*4` byte allocation across many screenshots.
+- Native-BGRA fast path in `SCScreenshotManager` skips the channel swap
+  for downstreams that accept BGRA directly (Metal / wgpu / ffmpeg).
+
 ## Migrating from 0.x to 1.0
 
 Version 1.0 introduced a complete API redesign with builder patterns, async support, and new macOS features.