From c7053d427ff25eaa0faac6ec0570ef4b978cfdae Mon Sep 17 00:00:00 2001
From: Yixiang Zeng <blaksmatic@gmail.com>
Date: Fri, 17 Apr 2026 07:43:40 -0700
Subject: [PATCH 01/11] vcli-capture: crate scaffold + Capture trait +
 WindowDescriptor

Plan deviation: screencapturekit = "1.5.4" used (plan said "0.3" which does
not exist on crates.io; latest compatible major version chosen instead).
Stub files for permission.rs, mock.rs, macos/, windows/ included to allow
compilation; filled out in subsequent tasks.
---
 Cargo.toml                               |  8 +++
 crates/vcli-capture/Cargo.toml           | 25 +++++++
 crates/vcli-capture/src/capture.rs       | 89 ++++++++++++++++++++++++
 crates/vcli-capture/src/error.rs         | 10 +++
 crates/vcli-capture/src/lib.rs           | 33 +++++++++
 crates/vcli-capture/src/macos/convert.rs |  1 +
 crates/vcli-capture/src/macos/mod.rs     |  6 ++
 crates/vcli-capture/src/macos/sck.rs     | 43 ++++++++++++
 crates/vcli-capture/src/mock.rs          | 29 ++++++++
 crates/vcli-capture/src/permission.rs    | 32 +++++++++
 crates/vcli-capture/src/windows/mod.rs   | 37 ++++++++++
 11 files changed, 313 insertions(+)
 create mode 100644 crates/vcli-capture/Cargo.toml
 create mode 100644 crates/vcli-capture/src/capture.rs
 create mode 100644 crates/vcli-capture/src/error.rs
 create mode 100644 crates/vcli-capture/src/lib.rs
 create mode 100644 crates/vcli-capture/src/macos/convert.rs
 create mode 100644 crates/vcli-capture/src/macos/mod.rs
 create mode 100644 crates/vcli-capture/src/macos/sck.rs
 create mode 100644 crates/vcli-capture/src/mock.rs
 create mode 100644 crates/vcli-capture/src/permission.rs
 create mode 100644 crates/vcli-capture/src/windows/mod.rs

diff --git a/Cargo.toml b/Cargo.toml
index 6649def..bf760f9 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -2,6 +2,7 @@
 resolver = "2"
 members = [
     "crates/vcli-core",
+    "crates/vcli-capture",
 ]
 
 [workspace.package]
@@ -23,3 +24,10 @@ unicode-normalization = "0.1"
 
 # Dev-only
 proptest = "1"
+
+tracing = "0.1"
+# Platform-specific, referenced from vcli-capture only. Declaring here so
+# downstream crates that later depend on vcli-capture don't re-select versions.
+screencapturekit = "1"
+image = "0.25"
+tempfile = "3"
diff --git a/crates/vcli-capture/Cargo.toml b/crates/vcli-capture/Cargo.toml
new file mode 100644
index 0000000..fd3fb6a
--- /dev/null
+++ b/crates/vcli-capture/Cargo.toml
@@ -0,0 +1,25 @@
+[package]
+name = "vcli-capture"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+authors.workspace = true
+description = "Capture trait, macOS ScreenCaptureKit backend, mock, Windows stub, for vcli."
+
+[dependencies]
+vcli-core = { path = "../vcli-core" }
+thiserror = { workspace = true }
+tracing = { workspace = true }
+
+[target.'cfg(target_os = "macos")'.dependencies]
+screencapturekit = { workspace = true }
+
+[dev-dependencies]
+image = { workspace = true }
+tempfile = { workspace = true }
+
+[[example]]
+name = "capture_once"
+path = "examples/capture_once.rs"
diff --git a/crates/vcli-capture/src/capture.rs b/crates/vcli-capture/src/capture.rs
new file mode 100644
index 0000000..993c7a8
--- /dev/null
+++ b/crates/vcli-capture/src/capture.rs
@@ -0,0 +1,89 @@
+//! `Capture` trait and associated descriptor types.
+
+use vcli_core::frame::{Frame, FrameFormat};
+use vcli_core::geom::Rect;
+use vcli_core::region::WindowIndex;
+
+use crate::error::CaptureError;
+
+/// Opaque identifier for a display. v0 is single-display (primary) so this is
+/// effectively `DisplayId::PRIMARY`, but the type is here from day 1 to keep
+/// the trait stable when multi-display lands.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct DisplayId(pub u32);
+
+impl DisplayId {
+    /// The primary display. Backends may enumerate others in the future.
+    pub const PRIMARY: Self = Self(0);
+}
+
+/// A window known to the capture backend. Stable for the lifetime of the
+/// window; ordering matches the native enumeration order (macOS: oldest →
+/// newest per Decision F2).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WindowDescriptor {
+    /// Backend-assigned stable id. For macOS this is the AX window id (u32)
+    /// re-exposed. Opaque to callers.
+    pub id: u64,
+    /// App/owner name, e.g. "Safari".
+    pub app: String,
+    /// Window title string, possibly empty.
+    pub title: String,
+    /// Bounds in logical pixels, relative to the display origin.
+    pub bounds: Rect,
+    /// 0-based index within the (app, title-substring) group this window
+    /// belongs to in the current enumeration pass. The region resolver in
+    /// the perception lane uses this directly as `WindowIndex`.
+    pub window_index: WindowIndex,
+    /// Display the window is currently on.
+    pub display: DisplayId,
+}
+
+/// Capture backend. One capture per tick; frame is shared across programs.
+pub trait Capture: Send + Sync {
+    /// Pixel formats this backend can emit. First entry is the preferred one.
+    fn supported_formats(&self) -> &[FrameFormat];
+
+    /// Enumerate visible application windows on all displays. Excludes
+    /// off-screen and minimized windows. Stable ordering per backend.
+    fn enumerate_windows(&self) -> Result<Vec<WindowDescriptor>, CaptureError>;
+
+    /// Grab a full-screen frame of the primary display.
+    fn grab_screen(&mut self) -> Result<Frame, CaptureError>;
+
+    /// Grab a frame cropped to the given window's current bounds. Backend
+    /// may re-resolve the window by id; if the window has moved/resized
+    /// between enumeration and grab, the returned `Frame.bounds` reflects
+    /// the actual capture, not the stale descriptor bounds.
+    fn grab_window(&mut self, window: &WindowDescriptor) -> Result<Frame, CaptureError>;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn display_id_primary_is_zero() {
+        assert_eq!(DisplayId::PRIMARY, DisplayId(0));
+    }
+
+    #[test]
+    fn window_descriptor_is_clone_eq() {
+        let a = WindowDescriptor {
+            id: 42,
+            app: "Safari".into(),
+            title: "YouTube".into(),
+            bounds: Rect { x: 0, y: 0, w: 800, h: 600 },
+            window_index: WindowIndex(0),
+            display: DisplayId::PRIMARY,
+        };
+        let b = a.clone();
+        assert_eq!(a, b);
+    }
+
+    #[test]
+    fn capture_trait_is_object_safe() {
+        // If this compiles, `dyn Capture` works — required for scheduler injection.
+        fn _takes_dyn(_c: &mut dyn Capture) {}
+    }
+}
diff --git a/crates/vcli-capture/src/error.rs b/crates/vcli-capture/src/error.rs
new file mode 100644
index 0000000..59a3b10
--- /dev/null
+++ b/crates/vcli-capture/src/error.rs
@@ -0,0 +1,10 @@
+//! Error types for the capture crate. See Task 2 for the full enum.
+use thiserror::Error;
+
+/// Placeholder — real variants added in Task 2.
+#[derive(Debug, Error)]
+pub enum CaptureError {
+    /// Generic placeholder; replaced in Task 2.
+    #[error("capture error: {0}")]
+    Other(String),
+}
diff --git a/crates/vcli-capture/src/lib.rs b/crates/vcli-capture/src/lib.rs
new file mode 100644
index 0000000..82b29a0
--- /dev/null
+++ b/crates/vcli-capture/src/lib.rs
@@ -0,0 +1,33 @@
+//! vcli-capture — Capture trait, macOS ScreenCaptureKit backend, mock impl, Windows stub.
+//!
+//! See spec §v0 scope and §Architecture → crate responsibilities. All outputs
+//! use `vcli-core` types (`Frame`, `FrameFormat`, `Rect`, `WindowIndex`).
+//!
+//! # Coordinate model
+//!
+//! Per Decision F1/4.3 capture produces physical pixels internally and emits
+//! a `Frame` at logical (1x) resolution. AX coords, input coords, and DSL
+//! coords all live in logical space; the one physical → logical conversion
+//! happens inside this crate.
+
+#![forbid(unsafe_code)]
+#![deny(rust_2018_idioms)]
+#![warn(missing_docs)]
+#![warn(clippy::pedantic)]
+#![allow(clippy::module_name_repetitions)]
+
+pub mod capture;
+pub mod error;
+pub mod mock;
+pub mod permission;
+
+#[cfg(target_os = "macos")]
+pub mod macos;
+
+#[cfg(windows)]
+pub mod windows;
+
+pub use capture::{Capture, DisplayId, WindowDescriptor};
+pub use error::CaptureError;
+pub use mock::MockCapture;
+pub use permission::{PermissionStatus, check_screen_recording_permission};
diff --git a/crates/vcli-capture/src/macos/convert.rs b/crates/vcli-capture/src/macos/convert.rs
new file mode 100644
index 0000000..4ce645e
--- /dev/null
+++ b/crates/vcli-capture/src/macos/convert.rs
@@ -0,0 +1 @@
+//! Pure BGRA / physical → logical converters — stub.
diff --git a/crates/vcli-capture/src/macos/mod.rs b/crates/vcli-capture/src/macos/mod.rs
new file mode 100644
index 0000000..ece08ee
--- /dev/null
+++ b/crates/vcli-capture/src/macos/mod.rs
@@ -0,0 +1,6 @@
+//! macOS capture backend. Enabled on `target_os = "macos"` only.
+
+pub mod convert;
+pub mod sck;
+
+pub use sck::MacCapture;
diff --git a/crates/vcli-capture/src/macos/sck.rs b/crates/vcli-capture/src/macos/sck.rs
new file mode 100644
index 0000000..420b9da
--- /dev/null
+++ b/crates/vcli-capture/src/macos/sck.rs
@@ -0,0 +1,43 @@
+//! macOS ScreenCaptureKit backend — stub.
+
+use std::sync::Mutex;
+
+use vcli_core::frame::{Frame, FrameFormat};
+
+use crate::capture::{Capture, WindowDescriptor};
+use crate::error::CaptureError;
+
+/// macOS SCK-backed `Capture` implementation.
+pub struct MacCapture {
+    _inner: Mutex<()>,
+}
+
+impl MacCapture {
+    /// Construct.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`CaptureError`] if permission is denied.
+    pub fn new() -> Result<Self, CaptureError> {
+        Ok(Self { _inner: Mutex::new(()) })
+    }
+}
+
+impl Capture for MacCapture {
+    fn supported_formats(&self) -> &[FrameFormat] {
+        const FORMATS: &[FrameFormat] = &[FrameFormat::Bgra8];
+        FORMATS
+    }
+
+    fn enumerate_windows(&self) -> Result<Vec<WindowDescriptor>, CaptureError> {
+        Err(CaptureError::Other("stub".into()))
+    }
+
+    fn grab_screen(&mut self) -> Result<Frame, CaptureError> {
+        Err(CaptureError::Other("stub".into()))
+    }
+
+    fn grab_window(&mut self, _window: &WindowDescriptor) -> Result<Frame, CaptureError> {
+        Err(CaptureError::Other("stub".into()))
+    }
+}
diff --git a/crates/vcli-capture/src/mock.rs b/crates/vcli-capture/src/mock.rs
new file mode 100644
index 0000000..fada144
--- /dev/null
+++ b/crates/vcli-capture/src/mock.rs
@@ -0,0 +1,29 @@
+//! `MockCapture` — stub, filled out in Task 3.
+
+use vcli_core::frame::{Frame, FrameFormat};
+
+use crate::capture::{Capture, WindowDescriptor};
+use crate::error::CaptureError;
+
+/// Canned-data capture backend stub.
+#[derive(Debug)]
+pub struct MockCapture;
+
+impl Capture for MockCapture {
+    fn supported_formats(&self) -> &[FrameFormat] {
+        const DEFAULT: &[FrameFormat] = &[FrameFormat::Bgra8];
+        DEFAULT
+    }
+
+    fn enumerate_windows(&self) -> Result<Vec<WindowDescriptor>, CaptureError> {
+        Ok(vec![])
+    }
+
+    fn grab_screen(&mut self) -> Result<Frame, CaptureError> {
+        Err(CaptureError::Other("stub".into()))
+    }
+
+    fn grab_window(&mut self, _window: &WindowDescriptor) -> Result<Frame, CaptureError> {
+        Err(CaptureError::Other("stub".into()))
+    }
+}
diff --git a/crates/vcli-capture/src/permission.rs b/crates/vcli-capture/src/permission.rs
new file mode 100644
index 0000000..91f2d0c
--- /dev/null
+++ b/crates/vcli-capture/src/permission.rs
@@ -0,0 +1,32 @@
+//! Screen Recording (TCC) permission probe — stub, filled out in Task 4.
+
+use crate::error::CaptureError;
+
+/// Result of probing the OS for screen-recording permission.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PermissionStatus {
+    /// Permission granted — capture will succeed.
+    Granted,
+    /// Not yet granted.
+    Denied,
+    /// Backend is unable to determine the status.
+    Unknown,
+}
+
+/// Synchronously probe the OS for screen-recording permission.
+///
+/// # Errors
+///
+/// Returns [`CaptureError`] if the underlying FFI call fails.
+pub fn check_screen_recording_permission() -> Result<PermissionStatus, CaptureError> {
+    Ok(PermissionStatus::Granted)
+}
+
+/// Request the user grant screen-recording permission.
+///
+/// # Errors
+///
+/// Returns [`CaptureError`] if the request call fails.
+pub fn request_screen_recording_permission() -> Result<(), CaptureError> {
+    Ok(())
+}
diff --git a/crates/vcli-capture/src/windows/mod.rs b/crates/vcli-capture/src/windows/mod.rs
new file mode 100644
index 0000000..93ed3ac
--- /dev/null
+++ b/crates/vcli-capture/src/windows/mod.rs
@@ -0,0 +1,37 @@
+//! Windows capture backend — v0.4 stub.
+
+use vcli_core::frame::{Frame, FrameFormat};
+
+use crate::capture::{Capture, WindowDescriptor};
+use crate::error::CaptureError;
+
+/// Windows capture backend stub.
+#[derive(Debug, Default)]
+pub struct WindowsCapture;
+
+impl WindowsCapture {
+    /// Construct.
+    #[must_use]
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+impl Capture for WindowsCapture {
+    fn supported_formats(&self) -> &[FrameFormat] {
+        const FORMATS: &[FrameFormat] = &[FrameFormat::Bgra8];
+        FORMATS
+    }
+
+    fn enumerate_windows(&self) -> Result<Vec<WindowDescriptor>, CaptureError> {
+        Err(CaptureError::Other("stub".into()))
+    }
+
+    fn grab_screen(&mut self) -> Result<Frame, CaptureError> {
+        Err(CaptureError::Other("stub".into()))
+    }
+
+    fn grab_window(&mut self, _window: &WindowDescriptor) -> Result<Frame, CaptureError> {
+        Err(CaptureError::Other("stub".into()))
+    }
+}

From f7cbd6a1b40df98f6bf851e011c036eec37b3a54 Mon Sep 17 00:00:00 2001
From: Yixiang Zeng <blaksmatic@gmail.com>
Date: Fri, 17 Apr 2026 07:44:15 -0700
Subject: [PATCH 02/11] vcli-capture: CaptureError taxonomy + stable code()
 mapping

---
 crates/vcli-capture/src/error.rs       | 88 ++++++++++++++++++++++++--
 crates/vcli-capture/src/macos/sck.rs   |  6 +-
 crates/vcli-capture/src/mock.rs        |  6 +-
 crates/vcli-capture/src/windows/mod.rs |  6 +-
 4 files changed, 92 insertions(+), 14 deletions(-)

diff --git a/crates/vcli-capture/src/error.rs b/crates/vcli-capture/src/error.rs
index 59a3b10..bd5648a 100644
--- a/crates/vcli-capture/src/error.rs
+++ b/crates/vcli-capture/src/error.rs
@@ -1,10 +1,88 @@
-//! Error types for the capture crate. See Task 2 for the full enum.
+//! Error types for the capture crate.
+//!
+//! The runtime maps `PermissionDenied` to event `capture.permission_missing`
+//! (spec §Events) and `capture_failed` to the ipc error code of the same name.
+
 use thiserror::Error;
 
-/// Placeholder — real variants added in Task 2.
+/// All errors this crate produces.
 #[derive(Debug, Error)]
 pub enum CaptureError {
-    /// Generic placeholder; replaced in Task 2.
-    #[error("capture error: {0}")]
-    Other(String),
+    /// Screen Recording (TCC) permission is not granted. User must approve
+    /// in System Settings → Privacy & Security → Screen Recording.
+    #[error("screen recording permission not granted")]
+    PermissionDenied,
+
+    /// The named window was not found on any display.
+    #[error("window not found: id={id}")]
+    WindowNotFound {
+        /// Opaque backend id from the lost descriptor.
+        id: u64,
+    },
+
+    /// Backend returned a frame the converter couldn't interpret (bad stride,
+    /// bad pixel format, zero-sized plane, …).
+    #[error("malformed frame from backend: {reason}")]
+    MalformedFrame {
+        /// Human-readable reason string.
+        reason: String,
+    },
+
+    /// Backend call timed out or failed mid-operation. Wraps the backend-
+    /// specific message so the runtime can surface it in `vcli health`.
+    #[error("backend failure: {message}")]
+    Backend {
+        /// Backend-provided message (SCK error description, HRESULT, etc.).
+        message: String,
+    },
+
+    /// The backend does not implement this method on the current platform.
+    #[error("capture operation unsupported on this backend: {what}")]
+    Unsupported {
+        /// Short description of what was attempted.
+        what: &'static str,
+    },
+}
+
+impl CaptureError {
+    /// Stable short string suitable for the ipc layer's error `code` field.
+    #[must_use]
+    pub fn code(&self) -> &'static str {
+        match self {
+            Self::PermissionDenied => "permission_denied",
+            Self::WindowNotFound { .. } => "unknown_window",
+            Self::MalformedFrame { .. } | Self::Backend { .. } => "capture_failed",
+            Self::Unsupported { .. } => "unsupported",
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn display_messages_are_informative() {
+        let e = CaptureError::PermissionDenied;
+        assert_eq!(e.to_string(), "screen recording permission not granted");
+        let e = CaptureError::WindowNotFound { id: 77 };
+        assert_eq!(e.to_string(), "window not found: id=77");
+        let e = CaptureError::MalformedFrame { reason: "bad stride".into() };
+        assert!(e.to_string().contains("bad stride"));
+    }
+
+    #[test]
+    fn codes_are_stable() {
+        assert_eq!(CaptureError::PermissionDenied.code(), "permission_denied");
+        assert_eq!(CaptureError::WindowNotFound { id: 1 }.code(), "unknown_window");
+        assert_eq!(
+            CaptureError::Backend { message: "x".into() }.code(),
+            "capture_failed"
+        );
+        assert_eq!(
+            CaptureError::MalformedFrame { reason: "x".into() }.code(),
+            "capture_failed"
+        );
+        assert_eq!(CaptureError::Unsupported { what: "x" }.code(), "unsupported");
+    }
 }
diff --git a/crates/vcli-capture/src/macos/sck.rs b/crates/vcli-capture/src/macos/sck.rs
index 420b9da..469ed8c 100644
--- a/crates/vcli-capture/src/macos/sck.rs
+++ b/crates/vcli-capture/src/macos/sck.rs
@@ -30,14 +30,14 @@ impl Capture for MacCapture {
     }
 
     fn enumerate_windows(&self) -> Result<Vec<WindowDescriptor>, CaptureError> {
-        Err(CaptureError::Other("stub".into()))
+        Err(CaptureError::Unsupported { what: "stub" })
     }
 
     fn grab_screen(&mut self) -> Result<Frame, CaptureError> {
-        Err(CaptureError::Other("stub".into()))
+        Err(CaptureError::Unsupported { what: "stub" })
     }
 
     fn grab_window(&mut self, _window: &WindowDescriptor) -> Result<Frame, CaptureError> {
-        Err(CaptureError::Other("stub".into()))
+        Err(CaptureError::Unsupported { what: "stub" })
     }
 }
diff --git a/crates/vcli-capture/src/mock.rs b/crates/vcli-capture/src/mock.rs
index fada144..e4e8194 100644
--- a/crates/vcli-capture/src/mock.rs
+++ b/crates/vcli-capture/src/mock.rs
@@ -16,14 +16,14 @@ impl Capture for MockCapture {
     }
 
     fn enumerate_windows(&self) -> Result<Vec<WindowDescriptor>, CaptureError> {
-        Ok(vec![])
+        Ok(Vec::new())
     }
 
     fn grab_screen(&mut self) -> Result<Frame, CaptureError> {
-        Err(CaptureError::Other("stub".into()))
+        Err(CaptureError::Backend { message: "stub".into() })
     }
 
     fn grab_window(&mut self, _window: &WindowDescriptor) -> Result<Frame, CaptureError> {
-        Err(CaptureError::Other("stub".into()))
+        Err(CaptureError::Backend { message: "stub".into() })
     }
 }
diff --git a/crates/vcli-capture/src/windows/mod.rs b/crates/vcli-capture/src/windows/mod.rs
index 93ed3ac..679cebd 100644
--- a/crates/vcli-capture/src/windows/mod.rs
+++ b/crates/vcli-capture/src/windows/mod.rs
@@ -24,14 +24,14 @@ impl Capture for WindowsCapture {
     }
 
     fn enumerate_windows(&self) -> Result<Vec<WindowDescriptor>, CaptureError> {
-        Err(CaptureError::Other("stub".into()))
+        Err(CaptureError::Unsupported { what: "stub" })
     }
 
     fn grab_screen(&mut self) -> Result<Frame, CaptureError> {
-        Err(CaptureError::Other("stub".into()))
+        Err(CaptureError::Unsupported { what: "stub" })
     }
 
     fn grab_window(&mut self, _window: &WindowDescriptor) -> Result<Frame, CaptureError> {
-        Err(CaptureError::Other("stub".into()))
+        Err(CaptureError::Unsupported { what: "stub" })
     }
 }

From b6741b5b6e2f27c411a67d9f8b9951622c7c5ba5 Mon Sep 17 00:00:00 2001
From: Yixiang Zeng <blaksmatic@gmail.com>
Date: Fri, 17 Apr 2026 07:45:09 -0700
Subject: [PATCH 03/11] vcli-capture: MockCapture with cycling frames + armed
 errors

---
 crates/vcli-capture/src/mock.rs | 247 ++++++++++++++++++++++++++++++--
 1 file changed, 239 insertions(+), 8 deletions(-)

diff --git a/crates/vcli-capture/src/mock.rs b/crates/vcli-capture/src/mock.rs
index e4e8194..283321d 100644
--- a/crates/vcli-capture/src/mock.rs
+++ b/crates/vcli-capture/src/mock.rs
@@ -1,29 +1,260 @@
-//! `MockCapture` — stub, filled out in Task 3.
+//! `MockCapture` — canned frames + windows for deterministic tests.
+//!
+//! Used by vcli-runtime scenario harness, vcli-perception evaluator tests,
+//! and the vcli-daemon ipc handler in its test suite.
+
+use std::sync::{Arc, Mutex};
 
 use vcli_core::frame::{Frame, FrameFormat};
+use vcli_core::geom::Rect;
+use vcli_core::region::WindowIndex;
 
-use crate::capture::{Capture, WindowDescriptor};
+use crate::capture::{Capture, DisplayId, WindowDescriptor};
 use crate::error::CaptureError;
 
-/// Canned-data capture backend stub.
+/// Canned-data capture backend. Cycles through `screen_frames` on each
+/// `grab_screen()`. `window_frames` lookup by window id. `enumerate_windows`
+/// returns a clone of the configured list. Thread-safe via `Mutex`.
 #[derive(Debug)]
-pub struct MockCapture;
+pub struct MockCapture {
+    inner: Arc<Mutex<MockInner>>,
+}
+
+#[derive(Debug)]
+struct MockInner {
+    #[allow(dead_code)] // stored for future multi-format support
+    formats: Vec<FrameFormat>,
+    windows: Vec<WindowDescriptor>,
+    screen_frames: Vec<Frame>,
+    screen_cursor: usize,
+    window_frame_map: Vec<(u64, Vec<Frame>)>,
+    window_cursors: Vec<usize>,
+    next_error: Option<CaptureError>,
+}
+
+impl MockCapture {
+    /// Empty mock — all calls return default / empty. For the "no programs,
+    /// nothing to capture" path.
+    #[must_use]
+    pub fn empty() -> Self {
+        Self::new(vec![FrameFormat::Bgra8], vec![], vec![])
+    }
+
+    /// Full constructor.
+    #[must_use]
+    pub fn new(
+        formats: Vec<FrameFormat>,
+        windows: Vec<WindowDescriptor>,
+        screen_frames: Vec<Frame>,
+    ) -> Self {
+        let window_cursors = vec![0; windows.len()];
+        Self {
+            inner: Arc::new(Mutex::new(MockInner {
+                formats,
+                windows,
+                screen_frames,
+                screen_cursor: 0,
+                window_frame_map: Vec::new(),
+                window_cursors,
+                next_error: None,
+            })),
+        }
+    }
+
+    /// Set canned frames for a particular window id. Subsequent calls to
+    /// `grab_window` with that descriptor cycle through these frames.
+    pub fn set_window_frames(&self, window_id: u64, frames: Vec<Frame>) {
+        let mut g = self.inner.lock().unwrap();
+        if let Some((_, slot)) =
+            g.window_frame_map.iter_mut().find(|(id, _)| *id == window_id)
+        {
+            *slot = frames;
+        } else {
+            g.window_frame_map.push((window_id, frames));
+        }
+    }
+
+    /// Arm the next call to any grab/enumerate method to fail with `e`. Used
+    /// to exercise error paths in consumer tests. Consumed by one failing call.
+    pub fn arm_error(&self, e: CaptureError) {
+        self.inner.lock().unwrap().next_error = Some(e);
+    }
+
+    fn take_armed_error(inner: &mut MockInner) -> Option<CaptureError> {
+        inner.next_error.take()
+    }
+}
 
 impl Capture for MockCapture {
     fn supported_formats(&self) -> &[FrameFormat] {
+        // Safety-ish: we hand out a leaked static slice derived from the
+        // current config by cloning into a boxed leak only once. To keep this
+        // simple and allocation-free on the hot path, we return a constant
+        // slice with the default format.
         const DEFAULT: &[FrameFormat] = &[FrameFormat::Bgra8];
         DEFAULT
     }
 
     fn enumerate_windows(&self) -> Result<Vec<WindowDescriptor>, CaptureError> {
-        Ok(Vec::new())
+        let mut g = self.inner.lock().unwrap();
+        if let Some(e) = Self::take_armed_error(&mut g) {
+            return Err(e);
+        }
+        Ok(g.windows.clone())
     }
 
     fn grab_screen(&mut self) -> Result<Frame, CaptureError> {
-        Err(CaptureError::Backend { message: "stub".into() })
+        let mut g = self.inner.lock().unwrap();
+        if let Some(e) = Self::take_armed_error(&mut g) {
+            return Err(e);
+        }
+        if g.screen_frames.is_empty() {
+            return Err(CaptureError::Backend {
+                message: "MockCapture has no screen frames configured".into(),
+            });
+        }
+        let idx = g.screen_cursor % g.screen_frames.len();
+        g.screen_cursor = g.screen_cursor.wrapping_add(1);
+        Ok(g.screen_frames[idx].clone())
+    }
+
+    fn grab_window(&mut self, window: &WindowDescriptor) -> Result<Frame, CaptureError> {
+        let mut g = self.inner.lock().unwrap();
+        if let Some(e) = Self::take_armed_error(&mut g) {
+            return Err(e);
+        }
+        let pos = g.window_frame_map.iter().position(|(id, _)| *id == window.id);
+        let Some(pos) = pos else {
+            return Err(CaptureError::WindowNotFound { id: window.id });
+        };
+        let frames_len = g.window_frame_map[pos].1.len();
+        if frames_len == 0 {
+            return Err(CaptureError::Backend {
+                message: format!("no frames for window id={}", window.id),
+            });
+        }
+        while g.window_cursors.len() <= pos {
+            g.window_cursors.push(0);
+        }
+        let cursor = g.window_cursors[pos];
+        let idx = cursor % frames_len;
+        g.window_cursors[pos] = cursor.wrapping_add(1);
+        Ok(g.window_frame_map[pos].1[idx].clone())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::Arc;
+
+    use super::*;
+
+    fn tiny(format: FrameFormat, value: u8) -> Frame {
+        let bytes: Arc<[u8]> = vec![value; 4 * 4 * 2].into();
+        Frame::new(format, Rect { x: 0, y: 0, w: 4, h: 2 }, 4 * 4, bytes, 0)
+    }
+
+    #[test]
+    fn empty_mock_returns_empty_windows() {
+        let m = MockCapture::empty();
+        assert!(m.enumerate_windows().unwrap().is_empty());
+    }
+
+    #[test]
+    fn empty_mock_screen_grab_errors() {
+        let mut m = MockCapture::empty();
+        let e = m.grab_screen().unwrap_err();
+        assert_eq!(e.code(), "capture_failed");
+    }
+
+    #[test]
+    fn screen_frames_cycle_in_order() {
+        let frames = vec![tiny(FrameFormat::Bgra8, 1), tiny(FrameFormat::Bgra8, 2)];
+        let mut m = MockCapture::new(vec![FrameFormat::Bgra8], vec![], frames);
+        let a = m.grab_screen().unwrap();
+        let b = m.grab_screen().unwrap();
+        let c = m.grab_screen().unwrap();
+        assert_eq!(a.pixels[0], 1);
+        assert_eq!(b.pixels[0], 2);
+        assert_eq!(c.pixels[0], 1); // wraps
+    }
+
+    #[test]
+    fn enumerate_returns_configured_windows() {
+        let w = WindowDescriptor {
+            id: 9,
+            app: "Finder".into(),
+            title: "Downloads".into(),
+            bounds: Rect { x: 0, y: 0, w: 1000, h: 600 },
+            window_index: WindowIndex(0),
+            display: DisplayId::PRIMARY,
+        };
+        let m = MockCapture::new(vec![FrameFormat::Bgra8], vec![w.clone()], vec![]);
+        let got = m.enumerate_windows().unwrap();
+        assert_eq!(got, vec![w]);
+    }
+
+    #[test]
+    fn grab_window_uses_configured_frames() {
+        let w = WindowDescriptor {
+            id: 7,
+            app: "Safari".into(),
+            title: "YT".into(),
+            bounds: Rect { x: 0, y: 0, w: 4, h: 2 },
+            window_index: WindowIndex(0),
+            display: DisplayId::PRIMARY,
+        };
+        let m = MockCapture::new(vec![FrameFormat::Bgra8], vec![w.clone()], vec![]);
+        m.set_window_frames(7, vec![tiny(FrameFormat::Bgra8, 42)]);
+        let mut m2 = m;
+        let f = m2.grab_window(&w).unwrap();
+        assert_eq!(f.pixels[0], 42);
+    }
+
+    #[test]
+    fn grab_window_unknown_id_errors() {
+        let w = WindowDescriptor {
+            id: 100,
+            app: "X".into(),
+            title: "Y".into(),
+            bounds: Rect { x: 0, y: 0, w: 4, h: 2 },
+            window_index: WindowIndex(0),
+            display: DisplayId::PRIMARY,
+        };
+        let mut m = MockCapture::new(vec![FrameFormat::Bgra8], vec![], vec![]);
+        let e = m.grab_window(&w).unwrap_err();
+        assert_eq!(e.code(), "unknown_window");
+    }
+
+    #[test]
+    fn armed_error_is_returned_once() {
+        let mut m = MockCapture::new(
+            vec![FrameFormat::Bgra8],
+            vec![],
+            vec![tiny(FrameFormat::Bgra8, 0)],
+        );
+        m.arm_error(CaptureError::PermissionDenied);
+        assert_eq!(m.grab_screen().unwrap_err().code(), "permission_denied");
+        // Second call succeeds because error was consumed.
+        assert!(m.grab_screen().is_ok());
+    }
+
+    #[test]
+    fn mock_is_send_sync() {
+        fn assert_send_sync<T: Send + Sync>() {}
+        assert_send_sync::<MockCapture>();
     }
 
-    fn grab_window(&mut self, _window: &WindowDescriptor) -> Result<Frame, CaptureError> {
-        Err(CaptureError::Backend { message: "stub".into() })
+    #[test]
+    fn mock_works_through_dyn_capture() {
+        use crate::capture::Capture;
+        let mut m = MockCapture::new(
+            vec![FrameFormat::Bgra8],
+            vec![],
+            vec![tiny(FrameFormat::Bgra8, 9)],
+        );
+        let dyn_cap: &mut dyn Capture = &mut m;
+        let f = dyn_cap.grab_screen().unwrap();
+        assert_eq!(f.pixels[0], 9);
     }
 }

From 6350f54bd7ffb0f0ec47b3eb5c752f33c3885908 Mon Sep 17 00:00:00 2001
From: Yixiang Zeng <blaksmatic@gmail.com>
Date: Fri, 17 Apr 2026 07:46:08 -0700
Subject: [PATCH 04/11] vcli-capture: TCC permission probe with
 PermissionStatus enum

Plan deviation: screencapturekit v1.5.4 has no util::has_permission.
Used extern "C" links to CGPreflightScreenCaptureAccess /
CGRequestScreenCaptureAccess from CoreGraphics framework directly (via
build.rs rustc-link-lib). Changed #![forbid(unsafe_code)] to
#![deny(unsafe_code)] + #[allow(unsafe_code)] on permission module to
permit the two extern "C" call sites.
---
 crates/vcli-capture/build.rs          |   6 ++
 crates/vcli-capture/src/lib.rs        |   2 +-
 crates/vcli-capture/src/permission.rs | 107 ++++++++++++++++++++++++--
 3 files changed, 106 insertions(+), 9 deletions(-)
 create mode 100644 crates/vcli-capture/build.rs

diff --git a/crates/vcli-capture/build.rs b/crates/vcli-capture/build.rs
new file mode 100644
index 0000000..e11f7f3
--- /dev/null
+++ b/crates/vcli-capture/build.rs
@@ -0,0 +1,6 @@
+fn main() {
+    // Link CoreGraphics framework for CGPreflightScreenCaptureAccess and
+    // CGRequestScreenCaptureAccess used in permission.rs on macOS.
+    #[cfg(target_os = "macos")]
+    println!("cargo:rustc-link-lib=framework=CoreGraphics");
+}
diff --git a/crates/vcli-capture/src/lib.rs b/crates/vcli-capture/src/lib.rs
index 82b29a0..13e1aa7 100644
--- a/crates/vcli-capture/src/lib.rs
+++ b/crates/vcli-capture/src/lib.rs
@@ -10,7 +10,7 @@
 //! coords all live in logical space; the one physical → logical conversion
 //! happens inside this crate.
 
-#![forbid(unsafe_code)]
+#![deny(unsafe_code)]
 #![deny(rust_2018_idioms)]
 #![warn(missing_docs)]
 #![warn(clippy::pedantic)]
diff --git a/crates/vcli-capture/src/permission.rs b/crates/vcli-capture/src/permission.rs
index 91f2d0c..3f0c687 100644
--- a/crates/vcli-capture/src/permission.rs
+++ b/crates/vcli-capture/src/permission.rs
@@ -1,4 +1,15 @@
-//! Screen Recording (TCC) permission probe — stub, filled out in Task 4.
+//! Screen Recording (TCC) permission probe.
+#![allow(unsafe_code)] // Required for CGPreflightScreenCaptureAccess / CGRequestScreenCaptureAccess extern "C" links on macOS.
+//!
+//! On macOS this calls `CGPreflightScreenCaptureAccess` and
+//! `CGRequestScreenCaptureAccess` from the Core Graphics framework directly
+//! via `extern "C"` links. On other OSes the result is always `Granted`
+//! because there is no equivalent gating.
+//!
+//! Note: `screencapturekit` v1.5.4 (the actual published version; plan cited
+//! "0.3" which does not exist on crates.io) does not expose a
+//! `util::has_permission` helper. We link the Core Graphics symbols directly
+//! instead, which is the idiomatic macOS approach.
 
 use crate::error::CaptureError;
 
@@ -7,26 +18,106 @@ use crate::error::CaptureError;
 pub enum PermissionStatus {
     /// Permission granted — capture will succeed.
     Granted,
-    /// Not yet granted.
+    /// Not yet granted. On macOS the daemon should emit
+    /// `capture.permission_missing { backend: "macos" }` per spec §Events.
     Denied,
-    /// Backend is unable to determine the status.
+    /// Backend is unable to determine the status (e.g., running under `nohup`
+    /// with no window server). Treated as denied by the scheduler but
+    /// surfaces to the user as a more specific diagnostic.
     Unknown,
 }
 
 /// Synchronously probe the OS for screen-recording permission.
 ///
+/// - macOS: calls `CGPreflightScreenCaptureAccess()`. Does not prompt.
+///   Use `request_screen_recording_permission()` to trigger the system prompt.
+/// - Other OSes: always returns `Granted`.
+///
 /// # Errors
 ///
-/// Returns [`CaptureError`] if the underlying FFI call fails.
+/// Returns [`CaptureError::Backend`] only if the underlying FFI call fails
+/// in a way that is not "permission denied" (very rare — e.g., window server
+/// unreachable).
 pub fn check_screen_recording_permission() -> Result<PermissionStatus, CaptureError> {
-    Ok(PermissionStatus::Granted)
+    #[cfg(target_os = "macos")]
+    {
+        // CGPreflightScreenCaptureAccess is a Core Graphics function available
+        // since macOS 10.15. It returns true if permission is granted, false
+        // otherwise, without prompting the user.
+        extern "C" {
+            fn CGPreflightScreenCaptureAccess() -> bool;
+        }
+        // SAFETY: CGPreflightScreenCaptureAccess is a stable macOS framework
+        // symbol with no preconditions beyond the process having a window
+        // server connection. It is safe to call from any thread.
+        let granted = unsafe { CGPreflightScreenCaptureAccess() };
+        return Ok(if granted {
+            PermissionStatus::Granted
+        } else {
+            PermissionStatus::Denied
+        });
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    {
+        Ok(PermissionStatus::Granted)
+    }
 }
 
-/// Request the user grant screen-recording permission.
+/// Request the user grant screen-recording permission. Triggers the macOS
+/// system prompt if currently Denied. No-op on other OSes.
 ///
 /// # Errors
 ///
-/// Returns [`CaptureError`] if the request call fails.
+/// Returns [`CaptureError::Backend`] if the request call fails.
 pub fn request_screen_recording_permission() -> Result<(), CaptureError> {
-    Ok(())
+    #[cfg(target_os = "macos")]
+    {
+        extern "C" {
+            fn CGRequestScreenCaptureAccess() -> bool;
+        }
+        // SAFETY: CGRequestScreenCaptureAccess is a stable macOS framework
+        // symbol. We ignore the return value — the prompt is async from the
+        // user's perspective; the caller should re-probe after user action.
+        let _ = unsafe { CGRequestScreenCaptureAccess() };
+        return Ok(());
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    {
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn permission_status_is_copy_eq() {
+        let a = PermissionStatus::Granted;
+        let b = a;
+        assert_eq!(a, b);
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    #[test]
+    fn non_macos_always_granted() {
+        let s = check_screen_recording_permission().unwrap();
+        assert_eq!(s, PermissionStatus::Granted);
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    #[test]
+    fn non_macos_request_is_no_op() {
+        request_screen_recording_permission().unwrap();
+    }
+
+    #[cfg(target_os = "macos")]
+    #[test]
+    fn macos_probe_does_not_panic() {
+        // Doesn't assert Granted/Denied — that's environment-dependent.
+        // Just ensures the FFI call wiring works without unwind.
+        let _ = check_screen_recording_permission().unwrap();
+    }
 }

From a412f954b15984d8b632109c48603bfd6fd4a33b Mon Sep 17 00:00:00 2001
From: Yixiang Zeng <blaksmatic@gmail.com>
Date: Fri, 17 Apr 2026 07:46:57 -0700
Subject: [PATCH 05/11] =?UTF-8?q?vcli-capture:=20macos::convert=20?=
 =?UTF-8?q?=E2=80=94=20BGRA=20physical=20=E2=86=92=20logical=20Frame?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 crates/vcli-capture/src/macos/convert.rs | 230 ++++++++++++++++++++++-
 1 file changed, 229 insertions(+), 1 deletion(-)

diff --git a/crates/vcli-capture/src/macos/convert.rs b/crates/vcli-capture/src/macos/convert.rs
index 4ce645e..9d54dc0 100644
--- a/crates/vcli-capture/src/macos/convert.rs
+++ b/crates/vcli-capture/src/macos/convert.rs
@@ -1 +1,229 @@
-//! Pure BGRA / physical → logical converters — stub.
+//! Pure BGRA / physical → logical converters. No FFI. Unit-tested with
+//! synthetic buffers so platform-free CI exercises the pixel math.
+
+use std::sync::Arc;
+
+use vcli_core::frame::{Frame, FrameFormat};
+use vcli_core::geom::Rect;
+
+use crate::error::CaptureError;
+
+/// Parameters for a raw BGRA8 buffer emitted by a backend.
+#[derive(Debug, Clone)]
+pub struct RawBgra {
+    /// Physical-pixel width.
+    pub width_px: u32,
+    /// Physical-pixel height.
+    pub height_px: u32,
+    /// Row stride in bytes. May exceed `width_px * 4` for alignment padding.
+    pub stride: usize,
+    /// Physical pixel bytes. Length must be ≥ `stride * height_px`.
+    pub pixels: Vec<u8>,
+    /// Monotonic ns timestamp.
+    pub captured_at_ns: u64,
+    /// Factor to downsample to logical 1x. 2.0 for Retina, 1.0 for non-HiDPI.
+    pub scale: f32,
+    /// Logical origin (top-left of the captured region in logical desktop coords).
+    pub logical_origin_x: i32,
+    /// Logical origin y.
+    pub logical_origin_y: i32,
+}
+
+/// Convert a raw BGRA physical-pixel buffer into a logical-resolution `Frame`.
+///
+/// For `scale == 1.0` the bytes are wrapped with no copying aside from the
+/// `Arc`. For `scale == 2.0` (Retina) we perform a simple 2:1 box-filter
+/// downsample so templates authored at logical resolution match.
+///
+/// # Errors
+///
+/// Returns [`CaptureError::MalformedFrame`] if:
+/// - `pixels.len() < stride * height_px`
+/// - `stride < width_px * 4`
+/// - `scale` not in {1.0, 2.0} (v0 supported scales; fractional DPI deferred)
+pub fn bgra_to_frame(raw: RawBgra) -> Result<Frame, CaptureError> {
+    let need = raw
+        .stride
+        .checked_mul(raw.height_px as usize)
+        .ok_or_else(|| CaptureError::MalformedFrame {
+            reason: "stride * height overflow".into(),
+        })?;
+    if raw.pixels.len() < need {
+        return Err(CaptureError::MalformedFrame {
+            reason: format!(
+                "buffer len {} < stride*height {}",
+                raw.pixels.len(),
+                need
+            ),
+        });
+    }
+    if raw.stride < (raw.width_px as usize) * 4 {
+        return Err(CaptureError::MalformedFrame {
+            reason: format!(
+                "stride {} less than width*4 {}",
+                raw.stride,
+                raw.width_px * 4
+            ),
+        });
+    }
+
+    let scale = raw.scale;
+    let (out_w, out_h, out_stride, out_pixels) = if (scale - 1.0_f32).abs() < f32::EPSILON {
+        (
+            raw.width_px as i32,
+            raw.height_px as i32,
+            raw.stride,
+            raw.pixels,
+        )
+    } else if (scale - 2.0_f32).abs() < f32::EPSILON {
+        downsample_2x(&raw)
+    } else {
+        return Err(CaptureError::MalformedFrame {
+            reason: format!("unsupported scale {scale}"),
+        });
+    };
+
+    let bounds = Rect {
+        x: raw.logical_origin_x,
+        y: raw.logical_origin_y,
+        w: out_w,
+        h: out_h,
+    };
+
+    let bytes: Arc<[u8]> = out_pixels.into();
+    Ok(Frame::new(
+        FrameFormat::Bgra8,
+        bounds,
+        out_stride,
+        bytes,
+        raw.captured_at_ns,
+    ))
+}
+
+/// 2:1 box-filter downsample of a BGRA buffer. Returns
+/// `(out_w, out_h, out_stride, out_pixels)`. Output stride = out_w * 4.
+fn downsample_2x(raw: &RawBgra) -> (i32, i32, usize, Vec<u8>) {
+    let out_w = (raw.width_px / 2) as usize;
+    let out_h = (raw.height_px / 2) as usize;
+    let out_stride = out_w * 4;
+    let mut out = vec![0u8; out_stride * out_h];
+    for y in 0..out_h {
+        let src_y0 = y * 2;
+        let src_y1 = src_y0 + 1;
+        let row0 = &raw.pixels
+            [src_y0 * raw.stride..src_y0 * raw.stride + raw.width_px as usize * 4];
+        let row1 = &raw.pixels
+            [src_y1 * raw.stride..src_y1 * raw.stride + raw.width_px as usize * 4];
+        for x in 0..out_w {
+            let sx = x * 2 * 4;
+            let idx = y * out_stride + x * 4;
+            // Box average 4 source pixels per channel.
+            for c in 0..4 {
+                let sum = u32::from(row0[sx + c])
+                    + u32::from(row0[sx + 4 + c])
+                    + u32::from(row1[sx + c])
+                    + u32::from(row1[sx + 4 + c]);
+                #[allow(clippy::cast_possible_truncation)]
+                {
+                    out[idx + c] = (sum / 4) as u8;
+                }
+            }
+        }
+    }
+    (out_w as i32, out_h as i32, out_stride, out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn raw(width: u32, height: u32, stride: usize, fill: u8, scale: f32) -> RawBgra {
+        RawBgra {
+            width_px: width,
+            height_px: height,
+            stride,
+            pixels: vec![fill; stride * height as usize],
+            captured_at_ns: 1,
+            scale,
+            logical_origin_x: 0,
+            logical_origin_y: 0,
+        }
+    }
+
+    #[test]
+    fn scale_1_passes_through_dims() {
+        let r = raw(8, 4, 32, 0xAB, 1.0);
+        let f = bgra_to_frame(r).unwrap();
+        assert_eq!(f.width(), 8);
+        assert_eq!(f.height(), 4);
+        assert_eq!(f.stride, 32);
+        assert_eq!(f.format, FrameFormat::Bgra8);
+        assert_eq!(f.pixels[0], 0xAB);
+    }
+
+    #[test]
+    fn scale_2_halves_dims_and_preserves_uniform_color() {
+        let r = raw(8, 4, 32, 0x7F, 2.0);
+        let f = bgra_to_frame(r).unwrap();
+        assert_eq!(f.width(), 4);
+        assert_eq!(f.height(), 2);
+        assert_eq!(f.stride, 16);
+        // Box-filter of constant color is the same color.
+        for b in f.pixels.iter() {
+            assert_eq!(*b, 0x7F);
+        }
+    }
+
+    #[test]
+    fn scale_2_averages_two_different_pixels() {
+        // 4x2 physical, 2x1 logical. Left column = 100, right column = 200.
+        let mut buf = vec![0u8; 4 * 2 * 4];
+        for y in 0..2 {
+            for x in 0..4 {
+                let v = if x < 2 { 100 } else { 200 };
+                for c in 0..4 {
+                    buf[y * 16 + x * 4 + c] = v;
+                }
+            }
+        }
+        let r = RawBgra {
+            width_px: 4,
+            height_px: 2,
+            stride: 16,
+            pixels: buf,
+            captured_at_ns: 0,
+            scale: 2.0,
+            logical_origin_x: 0,
+            logical_origin_y: 0,
+        };
+        let f = bgra_to_frame(r).unwrap();
+        // Output is 2x1. Left output pixel averages 4 physical pixels of value 100.
+        // Right output pixel averages 4 physical pixels of value 200.
+        assert_eq!(f.width(), 2);
+        assert_eq!(f.height(), 1);
+        assert_eq!(f.pixels[0], 100);
+        assert_eq!(f.pixels[4], 200);
+    }
+
+    #[test]
+    fn too_small_buffer_errors() {
+        let mut r = raw(100, 100, 400, 0, 1.0);
+        r.pixels.truncate(50);
+        let e = bgra_to_frame(r).unwrap_err();
+        assert_eq!(e.code(), "capture_failed");
+    }
+
+    #[test]
+    fn stride_less_than_width_times_4_errors() {
+        let r = raw(10, 2, 20, 0, 1.0); // stride 20 < 10*4 = 40
+        let e = bgra_to_frame(r).unwrap_err();
+        assert_eq!(e.code(), "capture_failed");
+    }
+
+    #[test]
+    fn fractional_scale_unsupported() {
+        let r = raw(10, 10, 40, 0, 1.5);
+        let e = bgra_to_frame(r).unwrap_err();
+        assert_eq!(e.code(), "capture_failed");
+    }
+}

From 92b15fafa25c47e5cd2bdd77ce28cf27d1e7d20e Mon Sep 17 00:00:00 2001
From: Yixiang Zeng <blaksmatic@gmail.com>
Date: Fri, 17 Apr 2026 07:51:48 -0700
Subject: [PATCH 06/11] vcli-capture: MacCapture::enumerate_windows via
 SCShareableContent

Plan deviation: screencapturekit v1.5.4 API differs from plan's v0.3 assumptions.
Key adaptations:
- SCContentFilter::create() builder pattern (not direct ctor)
- CGRect has flat fields .x/.y/.width/.height (not .origin.x/.size.width)
- application_name() returns String directly
- window_id() returns u32, converted to u64 via From<u32>
- CGDisplayScaleFactor via extern "C" (no display.scale_factor() method)
- build.rs adds rpath to Xcode swift-5.5/macosx for libswift_Concurrency.dylib
  (macOS 26 moved this dylib out of the dyld cache path screencapturekit expects)
- assign_window_indices() extracted as pub(crate) for unit testing
---
 crates/vcli-capture/build.rs         |  14 +-
 crates/vcli-capture/src/macos/sck.rs | 348 ++++++++++++++++++++++++++-
 2 files changed, 350 insertions(+), 12 deletions(-)

diff --git a/crates/vcli-capture/build.rs b/crates/vcli-capture/build.rs
index e11f7f3..748e185 100644
--- a/crates/vcli-capture/build.rs
+++ b/crates/vcli-capture/build.rs
@@ -2,5 +2,17 @@ fn main() {
     // Link CoreGraphics framework for CGPreflightScreenCaptureAccess and
     // CGRequestScreenCaptureAccess used in permission.rs on macOS.
     #[cfg(target_os = "macos")]
-    println!("cargo:rustc-link-lib=framework=CoreGraphics");
+    {
+        println!("cargo:rustc-link-lib=framework=CoreGraphics");
+
+        // The screencapturekit crate (v1.5.4) uses a Swift bridge that references
+        // libswift_Concurrency.dylib. On macOS 26+ this dylib is not a physical
+        // file but lives in the dyld shared cache. On older macOS it lives in
+        // the Swift toolchain (e.g., Xcode's swift-5.5 directory). Add the
+        // Xcode toolchain path to rpath so the loader finds it on both.
+        let xcode_swift55_path =
+            "/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain\
+             /usr/lib/swift-5.5/macosx";
+        println!("cargo:rustc-link-arg=-Wl,-rpath,{xcode_swift55_path}");
+    }
 }
diff --git a/crates/vcli-capture/src/macos/sck.rs b/crates/vcli-capture/src/macos/sck.rs
index 469ed8c..96b2403 100644
--- a/crates/vcli-capture/src/macos/sck.rs
+++ b/crates/vcli-capture/src/macos/sck.rs
@@ -1,43 +1,369 @@
-//! macOS ScreenCaptureKit backend — stub.
+//! macOS ScreenCaptureKit backend. Synchronous facade over the
+//! `screencapturekit` crate (v1.5.4 on crates.io; plan cited "0.3" which does
+//! not exist). SCShareableContent::get() is a blocking synchronous call; no
+//! tokio runtime is needed.
+//!
+//! ## API wiring notes (v1.5.4 vs plan assumptions)
+//!
+//! | Plan assumption | Actual v1.5.4 API |
+//! |---|---|
+//! | `screencapturekit::util::has_permission()` | Does not exist; see `permission.rs` for CG extern |
+//! | `SCContentFilter::new_with_display_excluding_windows` | `SCContentFilter::create().with_display(d).with_excluding_windows(&[]).build()` |
+//! | `SCContentFilter::new_with_desktop_independent_window` | `SCContentFilter::create().with_window(w).build()` |
+//! | `SCStreamConfiguration::new()` + setters returning `Result` | Builder pattern: `.with_width()`, `.with_height()`, `.with_pixel_format()` (infallible) |
+//! | `SCScreenshotManager::capture_image_with_filter` | `SCScreenshotManager::capture_image(&filter, &config)` |
+//! | `image.bgra_bytes()` | `image.rgba_data()` → RGBA Vec<u8> (we store as Rgba8 frame) |
+//! | `image.bytes_per_row()` | Not available; computed as `width * 4` |
+//! | `display.scale_factor()` | Not available; use `CGDisplayScaleFactor` via extern "C" |
+//! | `CGRect.origin.x`, `.size.width` | `CGRect.x`, `.width` (flat struct) |
+//! | `window.owning_application()?.application_name().ok()` | `.application_name()` returns `String` directly |
+//!
+//! Coordinate model (Decision F1, 4.3):
+//!   SCK reports `CGRect` in logical points. We treat logical points == logical
+//!   pixels for v0 (macOS). Physical pixel downsample happens in `convert.rs`
+//!   using the display's scale factor.
 
+#![allow(unsafe_code)] // Required for CGDisplayScaleFactor extern "C".
+
+use std::collections::HashMap;
 use std::sync::Mutex;
 
+use screencapturekit::{
+    screenshot_manager::SCScreenshotManager,
+    shareable_content::{SCDisplay, SCShareableContent, SCWindow},
+    stream::{
+        configuration::{PixelFormat, SCStreamConfiguration},
+        content_filter::SCContentFilter,
+    },
+};
+
 use vcli_core::frame::{Frame, FrameFormat};
+use vcli_core::geom::Rect;
+use vcli_core::region::WindowIndex;
 
-use crate::capture::{Capture, WindowDescriptor};
+use crate::capture::{Capture, DisplayId, WindowDescriptor};
 use crate::error::CaptureError;
+use crate::macos::convert::{bgra_to_frame, RawBgra};
+use crate::permission::{check_screen_recording_permission, PermissionStatus};
 
 /// macOS SCK-backed `Capture` implementation.
 pub struct MacCapture {
-    _inner: Mutex<()>,
+    /// Cached `SCShareableContent` refreshed per-call. Behind a `Mutex`
+    /// because SCK types are `!Sync` on some versions.
+    last_content: Mutex<Option<SCShareableContent>>,
 }
 
 impl MacCapture {
-    /// Construct.
+    /// Construct. Does NOT probe permission (permission check is explicit
+    /// via `check_screen_recording_permission`).
     ///
     /// # Errors
     ///
-    /// Returns [`CaptureError`] if permission is denied.
+    /// Returns [`CaptureError::PermissionDenied`] if at construction time the
+    /// TCC probe reports `Denied`, so the daemon can emit the correct event
+    /// before ever attempting a grab.
     pub fn new() -> Result<Self, CaptureError> {
-        Ok(Self { _inner: Mutex::new(()) })
+        match check_screen_recording_permission()? {
+            PermissionStatus::Granted => Ok(Self {
+                last_content: Mutex::new(None),
+            }),
+            PermissionStatus::Denied | PermissionStatus::Unknown => {
+                Err(CaptureError::PermissionDenied)
+            }
+        }
+    }
+
+    /// Refresh cached `SCShareableContent`.
+    fn refresh_content(&self) -> Result<SCShareableContent, CaptureError> {
+        let content = SCShareableContent::get().map_err(|e| CaptureError::Backend {
+            message: format!("SCShareableContent::get: {e}"),
+        })?;
+        *self.last_content.lock().unwrap() = Some(content.clone());
+        Ok(content)
+    }
+
+    /// Primary display — first in the enumerated list.
+    fn primary_display(content: &SCShareableContent) -> Result<SCDisplay, CaptureError> {
+        content
+            .displays()
+            .into_iter()
+            .next()
+            .ok_or_else(|| CaptureError::Backend {
+                message: "no displays reported by SCShareableContent".into(),
+            })
+    }
+
+    /// Locate a window by its stable AX id in a fresh enumeration.
+    fn locate_window(&self, id: u64) -> Result<SCWindow, CaptureError> {
+        let content = self.refresh_content()?;
+        content
+            .windows()
+            .into_iter()
+            .find(|w| u64::from(w.window_id()) == id)
+            .ok_or(CaptureError::WindowNotFound { id })
+    }
+}
+
+/// Compute `window_index` by grouping windows by `(app, title)`.
+/// Exported for unit testing of the pure indexing logic.
+pub(crate) fn assign_window_indices(
+    raw: Vec<(u64, String, String, Rect)>,
+) -> Vec<WindowDescriptor> {
+    let mut counters: HashMap<(String, String), u32> = HashMap::new();
+    let mut out = Vec::with_capacity(raw.len());
+    for (id, app, title, bounds) in raw {
+        let idx = counters
+            .entry((app.clone(), title.clone()))
+            .and_modify(|n| *n += 1)
+            .or_insert(0);
+        out.push(WindowDescriptor {
+            id,
+            app,
+            title,
+            bounds,
+            window_index: WindowIndex(*idx),
+            display: DisplayId::PRIMARY,
+        });
     }
+    out
+}
+
+/// Build `WindowDescriptor` list from SCK windows using `assign_window_indices`.
+fn build_descriptors(windows: Vec<SCWindow>) -> Vec<WindowDescriptor> {
+    let raw: Vec<(u64, String, String, Rect)> = windows
+        .into_iter()
+        .map(|w| {
+            let app = w
+                .owning_application()
+                .map(|a| a.application_name())
+                .unwrap_or_default();
+            let title = w.title().unwrap_or_default();
+            let rect = w.frame();
+            let bounds = Rect {
+                x: rect.x as i32,
+                y: rect.y as i32,
+                w: rect.width as i32,
+                h: rect.height as i32,
+            };
+            (u64::from(w.window_id()), app, title, bounds)
+        })
+        .collect();
+    assign_window_indices(raw)
+}
+
+/// Get the scale factor for the primary display.
+/// Falls back to 1.0 if unavailable.
+fn primary_scale_factor(display: &SCDisplay) -> f32 {
+    extern "C" {
+        fn CGDisplayScaleFactor(display_id: u32) -> f64;
+    }
+    // SAFETY: CGDisplayScaleFactor is a stable CoreGraphics symbol. The
+    // display_id is obtained from SCDisplay::display_id() which is valid.
+    let factor = unsafe { CGDisplayScaleFactor(display.display_id()) };
+    if factor > 0.0 {
+        factor as f32
+    } else {
+        1.0
+    }
+}
+
+/// Return current monotonic-ish timestamp in nanoseconds.
+fn monotonic_ns() -> u64 {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_nanos() as u64)
+        .unwrap_or(0)
 }
 
 impl Capture for MacCapture {
     fn supported_formats(&self) -> &[FrameFormat] {
-        const FORMATS: &[FrameFormat] = &[FrameFormat::Bgra8];
+        // ScreenCaptureKit v1.5.4 capture_image returns RGBA data.
+        // We store it as Rgba8.
+        const FORMATS: &[FrameFormat] = &[FrameFormat::Rgba8];
         FORMATS
     }
 
     fn enumerate_windows(&self) -> Result<Vec<WindowDescriptor>, CaptureError> {
-        Err(CaptureError::Unsupported { what: "stub" })
+        let content = self.refresh_content()?;
+        let mut windows = content.windows();
+        // Stable ordering: sort by window_id ascending (AX order ≈ creation time).
+        windows.sort_by_key(|w| w.window_id());
+        Ok(build_descriptors(windows))
     }
 
     fn grab_screen(&mut self) -> Result<Frame, CaptureError> {
-        Err(CaptureError::Unsupported { what: "stub" })
+        let content = self.refresh_content()?;
+        let display = Self::primary_display(&content)?;
+
+        let cfg = SCStreamConfiguration::new()
+            .with_width(display.width())
+            .with_height(display.height())
+            .with_pixel_format(PixelFormat::BGRA);
+
+        let filter = SCContentFilter::create()
+            .with_display(&display)
+            .with_excluding_windows(&[])
+            .build();
+
+        let image =
+            SCScreenshotManager::capture_image(&filter, &cfg).map_err(|e| match &e {
+                screencapturekit::error::SCError::PermissionDenied(_) => {
+                    CaptureError::PermissionDenied
+                }
+                screencapturekit::error::SCError::NoShareableContent(_) => {
+                    CaptureError::PermissionDenied
+                }
+                _ => CaptureError::Backend {
+                    message: format!("SCScreenshotManager::capture_image: {e}"),
+                },
+            })?;
+
+        let width_px = image.width() as u32;
+        let height_px = image.height() as u32;
+        // rgba_data() returns raw RGBA bytes; stride = width * 4.
+        let pixels = image.rgba_data().map_err(|e| CaptureError::MalformedFrame {
+            reason: format!("CGImage::rgba_data: {e}"),
+        })?;
+        let stride = (width_px as usize) * 4;
+
+        let scale = primary_scale_factor(&display);
+
+        // rgba_data returns RGBA; we treat it as Bgra8-shaped but mark correctly.
+        // convert.rs accepts a RawBgra struct for stride/downsample math —
+        // the bytes are RGBA but the layout logic (stride, scale) is identical.
+        let raw = RawBgra {
+            width_px,
+            height_px,
+            stride,
+            pixels,
+            captured_at_ns: monotonic_ns(),
+            scale,
+            logical_origin_x: 0,
+            logical_origin_y: 0,
+        };
+
+        // bgra_to_frame produces FrameFormat::Bgra8, but since rgba_data
+        // gives us RGBA bytes, we override the format to Rgba8.
+        let mut frame = bgra_to_frame(raw)?;
+        frame.format = FrameFormat::Rgba8;
+        Ok(frame)
+    }
+
+    fn grab_window(&mut self, window: &WindowDescriptor) -> Result<Frame, CaptureError> {
+        let sck_window = self.locate_window(window.id)?;
+        let frame_rect = sck_window.frame();
+        let width_px = frame_rect.width as u32;
+        let height_px = frame_rect.height as u32;
+
+        let cfg = SCStreamConfiguration::new()
+            .with_width(width_px)
+            .with_height(height_px)
+            .with_pixel_format(PixelFormat::BGRA);
+
+        let filter = SCContentFilter::create().with_window(&sck_window).build();
+
+        let image =
+            SCScreenshotManager::capture_image(&filter, &cfg).map_err(|e| match &e {
+                screencapturekit::error::SCError::PermissionDenied(_) => {
+                    CaptureError::PermissionDenied
+                }
+                screencapturekit::error::SCError::NoShareableContent(_) => {
+                    CaptureError::PermissionDenied
+                }
+                _ => CaptureError::Backend {
+                    message: format!("capture_image: {e}"),
+                },
+            })?;
+
+        let img_w = image.width() as u32;
+        let img_h = image.height() as u32;
+        let pixels = image.rgba_data().map_err(|e| CaptureError::MalformedFrame {
+            reason: format!("CGImage::rgba_data: {e}"),
+        })?;
+        let stride = (img_w as usize) * 4;
+
+        let content = self.refresh_content()?;
+        let display = Self::primary_display(&content)?;
+        let scale = primary_scale_factor(&display);
+
+        let raw = RawBgra {
+            width_px: img_w,
+            height_px: img_h,
+            stride,
+            pixels,
+            captured_at_ns: monotonic_ns(),
+            scale,
+            logical_origin_x: frame_rect.x as i32,
+            logical_origin_y: frame_rect.y as i32,
+        };
+
+        let mut frame = bgra_to_frame(raw)?;
+        frame.format = FrameFormat::Rgba8;
+        Ok(frame)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn build_descriptors_assigns_indices_per_app_title() {
+        // We can't construct real SCWindows in unit tests; cover the pure
+        // index-assignment logic instead.
+        let a: Vec<WindowDescriptor> = Vec::new();
+        assert!(a.is_empty());
+    }
+
+    #[test]
+    fn supported_formats_contains_rgba8() {
+        let m = MacCapture {
+            last_content: Mutex::new(None),
+        };
+        assert_eq!(m.supported_formats(), &[FrameFormat::Rgba8]);
+    }
+
+    #[test]
+    fn indices_are_sequential_per_app_title() {
+        let raw = vec![
+            (
+                1,
+                "Safari".into(),
+                "YouTube".into(),
+                Rect { x: 0, y: 0, w: 10, h: 10 },
+            ),
+            (
+                2,
+                "Safari".into(),
+                "YouTube".into(),
+                Rect { x: 10, y: 0, w: 10, h: 10 },
+            ),
+            (
+                3,
+                "Safari".into(),
+                "Mail".into(),
+                Rect { x: 20, y: 0, w: 10, h: 10 },
+            ),
+            (
+                4,
+                "Finder".into(),
+                "YouTube".into(),
+                Rect { x: 30, y: 0, w: 10, h: 10 },
+            ),
+        ];
+        let d = assign_window_indices(raw);
+        assert_eq!(d[0].window_index, WindowIndex(0));
+        assert_eq!(d[1].window_index, WindowIndex(1));
+        assert_eq!(d[2].window_index, WindowIndex(0));
+        assert_eq!(d[3].window_index, WindowIndex(0));
     }
 
-    fn grab_window(&mut self, _window: &WindowDescriptor) -> Result<Frame, CaptureError> {
-        Err(CaptureError::Unsupported { what: "stub" })
+    #[test]
+    fn monotonic_ns_advances() {
+        let a = monotonic_ns();
+        std::thread::sleep(std::time::Duration::from_millis(2));
+        let b = monotonic_ns();
+        assert!(b > a);
     }
 }

From 024de88a10ebf7124c418df686dcbf147d60b960 Mon Sep 17 00:00:00 2001
From: Yixiang Zeng <blaksmatic@gmail.com>
Date: Fri, 17 Apr 2026 07:54:29 -0700
Subject: [PATCH 07/11] vcli-capture: TCC-gated integration smoke tests for SCK
 backend

Also: refine MacCapture to remove CGDisplayScaleFactor (not in macOS 26 SDK).
SCDisplay.width()/height() already report logical pixels, so scale=1.0 is correct.
Fix mock.rs unused-import warnings by moving Rect/WindowIndex/DisplayId to
the test submodule where they are used. Fix rpath for libswift_Concurrency.dylib
(macOS 26 moved it; added Xcode swift-5.5/macosx to rpath in build.rs).
---
 crates/vcli-capture/src/macos/sck.rs         | 35 +++------------
 crates/vcli-capture/src/mock.rs              |  9 ++--
 crates/vcli-capture/tests/macos_sck_smoke.rs | 46 ++++++++++++++++++++
 3 files changed, 58 insertions(+), 32 deletions(-)
 create mode 100644 crates/vcli-capture/tests/macos_sck_smoke.rs

diff --git a/crates/vcli-capture/src/macos/sck.rs b/crates/vcli-capture/src/macos/sck.rs
index 96b2403..5a29156 100644
--- a/crates/vcli-capture/src/macos/sck.rs
+++ b/crates/vcli-capture/src/macos/sck.rs
@@ -14,7 +14,7 @@
 //! | `SCScreenshotManager::capture_image_with_filter` | `SCScreenshotManager::capture_image(&filter, &config)` |
 //! | `image.bgra_bytes()` | `image.rgba_data()` → RGBA Vec<u8> (we store as Rgba8 frame) |
 //! | `image.bytes_per_row()` | Not available; computed as `width * 4` |
-//! | `display.scale_factor()` | Not available; use `CGDisplayScaleFactor` via extern "C" |
+//! | `display.scale_factor()` | Not available; scale is always 1.0 (SCK gives logical px) |
 //! | `CGRect.origin.x`, `.size.width` | `CGRect.x`, `.width` (flat struct) |
 //! | `window.owning_application()?.application_name().ok()` | `.application_name()` returns `String` directly |
 //!
@@ -23,7 +23,6 @@
 //!   pixels for v0 (macOS). Physical pixel downsample happens in `convert.rs`
 //!   using the display's scale factor.
 
-#![allow(unsafe_code)] // Required for CGDisplayScaleFactor extern "C".
 
 use std::collections::HashMap;
 use std::sync::Mutex;
@@ -151,22 +150,6 @@ fn build_descriptors(windows: Vec<SCWindow>) -> Vec<WindowDescriptor> {
     assign_window_indices(raw)
 }
 
-/// Get the scale factor for the primary display.
-/// Falls back to 1.0 if unavailable.
-fn primary_scale_factor(display: &SCDisplay) -> f32 {
-    extern "C" {
-        fn CGDisplayScaleFactor(display_id: u32) -> f64;
-    }
-    // SAFETY: CGDisplayScaleFactor is a stable CoreGraphics symbol. The
-    // display_id is obtained from SCDisplay::display_id() which is valid.
-    let factor = unsafe { CGDisplayScaleFactor(display.display_id()) };
-    if factor > 0.0 {
-        factor as f32
-    } else {
-        1.0
-    }
-}
-
 /// Return current monotonic-ish timestamp in nanoseconds.
 fn monotonic_ns() -> u64 {
     use std::time::{SystemTime, UNIX_EPOCH};
@@ -227,18 +210,15 @@ impl Capture for MacCapture {
         })?;
         let stride = (width_px as usize) * 4;
 
-        let scale = primary_scale_factor(&display);
-
-        // rgba_data returns RGBA; we treat it as Bgra8-shaped but mark correctly.
-        // convert.rs accepts a RawBgra struct for stride/downsample math —
-        // the bytes are RGBA but the layout logic (stride, scale) is identical.
+        // SCDisplay.width()/height() report logical pixels; scale = 1.0.
+        // CGDisplayScaleFactor was removed from macOS 26 SDK.
         let raw = RawBgra {
             width_px,
             height_px,
             stride,
             pixels,
             captured_at_ns: monotonic_ns(),
-            scale,
+            scale: 1.0,
             logical_origin_x: 0,
             logical_origin_y: 0,
         };
@@ -283,17 +263,14 @@ impl Capture for MacCapture {
         })?;
         let stride = (img_w as usize) * 4;
 
-        let content = self.refresh_content()?;
-        let display = Self::primary_display(&content)?;
-        let scale = primary_scale_factor(&display);
-
+        // display_scale is always 1.0 for SCK (logical px). No content refresh needed.
         let raw = RawBgra {
             width_px: img_w,
             height_px: img_h,
             stride,
             pixels,
             captured_at_ns: monotonic_ns(),
-            scale,
+            scale: 1.0,
             logical_origin_x: frame_rect.x as i32,
             logical_origin_y: frame_rect.y as i32,
         };
diff --git a/crates/vcli-capture/src/mock.rs b/crates/vcli-capture/src/mock.rs
index 283321d..0938b30 100644
--- a/crates/vcli-capture/src/mock.rs
+++ b/crates/vcli-capture/src/mock.rs
@@ -6,10 +6,8 @@
 use std::sync::{Arc, Mutex};
 
 use vcli_core::frame::{Frame, FrameFormat};
-use vcli_core::geom::Rect;
-use vcli_core::region::WindowIndex;
 
-use crate::capture::{Capture, DisplayId, WindowDescriptor};
+use crate::capture::{Capture, WindowDescriptor};
 use crate::error::CaptureError;
 
 /// Canned-data capture backend. Cycles through `screen_frames` on each
@@ -147,6 +145,11 @@ impl Capture for MockCapture {
 mod tests {
     use std::sync::Arc;
 
+    use vcli_core::geom::Rect;
+    use vcli_core::region::WindowIndex;
+
+    use crate::capture::DisplayId;
+
     use super::*;
 
     fn tiny(format: FrameFormat, value: u8) -> Frame {
diff --git a/crates/vcli-capture/tests/macos_sck_smoke.rs b/crates/vcli-capture/tests/macos_sck_smoke.rs
new file mode 100644
index 0000000..e0f40c9
--- /dev/null
+++ b/crates/vcli-capture/tests/macos_sck_smoke.rs
@@ -0,0 +1,46 @@
+//! macOS-only smoke test that actually touches ScreenCaptureKit.
+//!
+//! Requires Screen Recording permission for the running process. Gated
+//! behind `#[ignore]` so `cargo test` does not run it by default. Enable
+//! manually with:  `cargo test -p vcli-capture --test macos_sck_smoke -- --ignored`
+
+#![cfg(target_os = "macos")]
+
+use vcli_capture::{
+    capture::Capture,
+    macos::MacCapture,
+    permission::{check_screen_recording_permission, PermissionStatus},
+};
+
+#[test]
+#[ignore]
+fn enumerates_at_least_one_window() {
+    assert_eq!(
+        check_screen_recording_permission().unwrap(),
+        PermissionStatus::Granted,
+        "grant Screen Recording permission to the binary before running"
+    );
+    let c = MacCapture::new().expect("construct MacCapture");
+    let windows = c.enumerate_windows().expect("enumerate");
+    // A running GUI macOS session always has the Dock / menubar process, so
+    // at least one window is guaranteed.
+    assert!(!windows.is_empty(), "expected at least one window");
+}
+
+#[test]
+#[ignore]
+fn grabs_a_nonempty_screen_frame() {
+    assert_eq!(
+        check_screen_recording_permission().unwrap(),
+        PermissionStatus::Granted
+    );
+    let mut c = MacCapture::new().expect("construct MacCapture");
+    let frame = c.grab_screen().expect("grab_screen");
+    assert!(frame.width() > 0);
+    assert!(frame.height() > 0);
+    assert!(!frame.pixels.is_empty());
+    assert!(
+        frame.pixels.iter().any(|b| *b != 0),
+        "captured a fully-black frame — usually means TCC is silently denying"
+    );
+}

From 5a9af7ea3d30875a3d5bc0c699a1e2ab55167c8d Mon Sep 17 00:00:00 2001
From: Yixiang Zeng <blaksmatic@gmail.com>
Date: Fri, 17 Apr 2026 07:54:48 -0700
Subject: [PATCH 08/11] vcli-capture: WindowsCapture stub returning Unsupported
 (v0.4)

---
 crates/vcli-capture/src/windows/mod.rs | 38 +++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/crates/vcli-capture/src/windows/mod.rs b/crates/vcli-capture/src/windows/mod.rs
index 679cebd..f65ad2b 100644
--- a/crates/vcli-capture/src/windows/mod.rs
+++ b/crates/vcli-capture/src/windows/mod.rs
@@ -1,4 +1,5 @@
-//! Windows capture backend — v0.4 stub.
+//! Windows capture backend — v0.4 stub. Compiles so the workspace builds on
+//! Windows CI, but every operation returns `Unsupported` with a clear message.
 
 use vcli_core::frame::{Frame, FrameFormat};
 
@@ -24,14 +25,43 @@ impl Capture for WindowsCapture {
     }
 
     fn enumerate_windows(&self) -> Result<Vec<WindowDescriptor>, CaptureError> {
-        Err(CaptureError::Unsupported { what: "stub" })
+        Err(CaptureError::Unsupported {
+            what: "WindowsCapture::enumerate_windows (v0.4)",
+        })
     }
 
     fn grab_screen(&mut self) -> Result<Frame, CaptureError> {
-        Err(CaptureError::Unsupported { what: "stub" })
+        Err(CaptureError::Unsupported {
+            what: "WindowsCapture::grab_screen (v0.4)",
+        })
     }
 
     fn grab_window(&mut self, _window: &WindowDescriptor) -> Result<Frame, CaptureError> {
-        Err(CaptureError::Unsupported { what: "stub" })
+        Err(CaptureError::Unsupported {
+            what: "WindowsCapture::grab_window (v0.4)",
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn enumerate_reports_unsupported() {
+        let w = WindowsCapture::new();
+        assert_eq!(w.enumerate_windows().unwrap_err().code(), "unsupported");
+    }
+
+    #[test]
+    fn grab_screen_reports_unsupported() {
+        let mut w = WindowsCapture::new();
+        assert_eq!(w.grab_screen().unwrap_err().code(), "unsupported");
+    }
+
+    #[test]
+    fn formats_always_includes_bgra() {
+        let w = WindowsCapture::new();
+        assert!(w.supported_formats().contains(&FrameFormat::Bgra8));
     }
 }

From 633786d2c13dc073b786da0a9d3fa0fda59e0afa Mon Sep 17 00:00:00 2001
From: Yixiang Zeng <blaksmatic@gmail.com>
Date: Fri, 17 Apr 2026 07:55:11 -0700
Subject: [PATCH 09/11] vcli-capture: capture_once example for manual TCC/SCK
 verification

---
 crates/vcli-capture/examples/capture_once.rs | 99 ++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 crates/vcli-capture/examples/capture_once.rs

diff --git a/crates/vcli-capture/examples/capture_once.rs b/crates/vcli-capture/examples/capture_once.rs
new file mode 100644
index 0000000..db1204a
--- /dev/null
+++ b/crates/vcli-capture/examples/capture_once.rs
@@ -0,0 +1,99 @@
+//! capture_once — grab one screen frame, print dimensions + permission status.
+//!
+//! Useful for manually verifying macOS Screen Recording permission and the
+//! SCK wiring without running the whole daemon.
+//!
+//! Usage:  cargo run -p vcli-capture --example capture_once
+//!         cargo run -p vcli-capture --example capture_once -- --save /tmp/out.png
+
+use std::env;
+use std::process::ExitCode;
+
+fn main() -> ExitCode {
+    match run() {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(e) => {
+            eprintln!("error: {e}");
+            ExitCode::from(2)
+        }
+    }
+}
+
+#[cfg(target_os = "macos")]
+fn run() -> Result<(), Box<dyn std::error::Error>> {
+    use vcli_capture::{
+        capture::Capture,
+        macos::MacCapture,
+        permission::{
+            check_screen_recording_permission, request_screen_recording_permission,
+            PermissionStatus,
+        },
+    };
+
+    let args: Vec<String> = env::args().collect();
+    let save_to = args
+        .iter()
+        .position(|a| a == "--save")
+        .and_then(|i| args.get(i + 1).cloned());
+
+    match check_screen_recording_permission()? {
+        PermissionStatus::Granted => {
+            println!("permission: granted");
+        }
+        PermissionStatus::Denied => {
+            println!("permission: denied — prompting user");
+            request_screen_recording_permission()?;
+            println!(
+                "re-run after granting in System Settings → Privacy & Security → Screen Recording"
+            );
+            return Ok(());
+        }
+        PermissionStatus::Unknown => {
+            println!("permission: unknown — attempting capture anyway");
+        }
+    }
+
+    let mut cap = MacCapture::new()?;
+    let frame = cap.grab_screen()?;
+    println!(
+        "captured {}x{} @ stride {} bytes, format {:?}",
+        frame.width(),
+        frame.height(),
+        frame.stride,
+        frame.format
+    );
+
+    if let Some(path) = save_to {
+        use image::{ImageBuffer, Rgba};
+        let w = frame.width() as u32;
+        let h = frame.height() as u32;
+        let mut img: ImageBuffer<Rgba<u8>, Vec<u8>> = ImageBuffer::new(w, h);
+        for (x, y, px) in img.enumerate_pixels_mut() {
+            let off = (y as usize) * frame.stride + (x as usize) * 4;
+            // RGBA → store as RGBA (frame.format == Rgba8)
+            let r = frame.pixels[off];
+            let g = frame.pixels[off + 1];
+            let b = frame.pixels[off + 2];
+            let a = frame.pixels[off + 3];
+            *px = Rgba([r, g, b, a]);
+        }
+        img.save(&path)?;
+        println!("saved: {path}");
+    }
+
+    let windows = cap.enumerate_windows()?;
+    println!("windows visible: {}", windows.len());
+    for w in windows.iter().take(10) {
+        println!(
+            "  id={} app={:?} title={:?} bounds={}x{}@({},{})",
+            w.id, w.app, w.title, w.bounds.w, w.bounds.h, w.bounds.x, w.bounds.y
+        );
+    }
+    Ok(())
+}
+
+#[cfg(not(target_os = "macos"))]
+fn run() -> Result<(), Box<dyn std::error::Error>> {
+    eprintln!("capture_once is only implemented for macOS in v0");
+    Ok(())
+}

From 0850b7f6482ae5cb1f3c2873a190f5e5e616edda Mon Sep 17 00:00:00 2001
From: Yixiang Zeng <blaksmatic@gmail.com>
Date: Fri, 17 Apr 2026 08:00:18 -0700
Subject: [PATCH 10/11] vcli-capture: dyn-Capture test + clippy/fmt clean

All clippy::pedantic warnings resolved, cargo fmt applied, dyn
Capture roundtrip test added to MockCapture test suite.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 Cargo.lock                               | 785 ++++++++++++++++++++++-
 crates/vcli-capture/src/capture.rs       |  19 +-
 crates/vcli-capture/src/error.rs         |  19 +-
 crates/vcli-capture/src/lib.rs           |   4 +-
 crates/vcli-capture/src/macos/convert.rs |  18 +-
 crates/vcli-capture/src/macos/sck.rs     | 138 ++--
 crates/vcli-capture/src/mock.rs          |  53 +-
 crates/vcli-capture/src/permission.rs    |  77 +--
 8 files changed, 998 insertions(+), 115 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index ebff385..646266f 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2,18 +2,117 @@
 # It is not intended for manual editing.
 version = 3
 
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
+[[package]]
+name = "aligned"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee4508988c62edf04abd8d92897fca0c2995d907ce1dfeaf369dac3716a40685"
+dependencies = [
+ "as-slice",
+]
+
+[[package]]
+name = "aligned-vec"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc890384c8602f339876ded803c97ad529f3842aba97f6392b3dba0dd171769b"
+dependencies = [
+ "equator",
+]
+
 [[package]]
 name = "anyhow"
 version = "1.0.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 
+[[package]]
+name = "arbitrary"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3d036a3c4ab069c7b410a2ce876bd74808d2d0888a82667669f8e783a898bf1"
+
+[[package]]
+name = "arg_enum_proc_macro"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ae92a5119aa49cdbcf6b9f893fe4e1d98b04ccbf82ee0584ad948a44a734dea"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "arrayvec"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50"
+
+[[package]]
+name = "as-slice"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "516b6b4f0e40d50dcda9365d53964ec74560ad4284da2e7fc97122cd83174516"
+dependencies = [
+ "stable_deref_trait",
+]
+
 [[package]]
 name = "autocfg"
 version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
 
+[[package]]
+name = "av-scenechange"
+version = "0.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0f321d77c20e19b92c39e7471cf986812cbb46659d2af674adc4331ef3f18394"
+dependencies = [
+ "aligned",
+ "anyhow",
+ "arg_enum_proc_macro",
+ "arrayvec",
+ "log",
+ "num-rational",
+ "num-traits",
+ "pastey",
+ "rayon",
+ "thiserror",
+ "v_frame",
+ "y4m",
+]
+
+[[package]]
+name = "av1-grain"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8cfddb07216410377231960af4fcab838eaa12e013417781b78bd95ee22077f8"
+dependencies = [
+ "anyhow",
+ "arrayvec",
+ "log",
+ "nom",
+ "num-rational",
+ "v_frame",
+]
+
+[[package]]
+name = "avif-serialize"
+version = "0.8.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "375082f007bd67184fb9c0374614b29f9aaa604ec301635f72338bb65386a53d"
+dependencies = [
+ "arrayvec",
+]
+
 [[package]]
 name = "bit-set"
 version = "0.8.0"
@@ -29,24 +128,141 @@ version = "0.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7"
 
+[[package]]
+name = "bit_field"
+version = "0.10.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e4b40c7323adcfc0a41c4b88143ed58346ff65a288fc144329c5c45e05d70c6"
+
 [[package]]
 name = "bitflags"
 version = "2.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
 
+[[package]]
+name = "bitstream-io"
+version = "4.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7eff00be299a18769011411c9def0d827e8f2d7bf0c3dbf53633147a8867fd1f"
+dependencies = [
+ "no_std_io2",
+]
+
+[[package]]
+name = "built"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f4ad8f11f288f48ca24471bbd51ac257aaeaaa07adae295591266b792902ae64"
+
 [[package]]
 name = "bumpalo"
 version = "3.20.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb"
 
+[[package]]
+name = "bytemuck"
+version = "1.25.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8efb64bd706a16a1bdde310ae86b351e4d21550d98d056f22f8a7f7a2183fec"
+
+[[package]]
+name = "byteorder-lite"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
+
+[[package]]
+name = "cc"
+version = "1.2.60"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43c5703da9466b66a946814e1adf53ea2c90f10063b86290cc9eb67ce3478a20"
+dependencies = [
+ "find-msvc-tools",
+ "jobserver",
+ "libc",
+ "shlex",
+]
+
 [[package]]
 name = "cfg-if"
 version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
+[[package]]
+name = "color_quant"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b"
+
+[[package]]
+name = "crc32fast"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dd111b7b7f7d55b72c0a6ae361660ee5853c9af73f70c3c2ef6858b950e2e51"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
+
+[[package]]
+name = "crunchy"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
+
+[[package]]
+name = "either"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+
+[[package]]
+name = "equator"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4711b213838dfee0117e3be6ac926007d7f433d7bbe33595975d4190cb07e6fc"
+dependencies = [
+ "equator-macro",
+]
+
+[[package]]
+name = "equator-macro"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "44f23cf4b44bfce11a86ace86f8a73ffdec849c9fd00a386a53d278bd9e81fb3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "equivalent"
 version = "1.0.2"
@@ -63,12 +279,72 @@ dependencies = [
  "windows-sys",
 ]
 
+[[package]]
+name = "exr"
+version = "1.74.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4300e043a56aa2cb633c01af81ca8f699a321879a7854d3896a0ba89056363be"
+dependencies = [
+ "bit_field",
+ "half",
+ "lebe",
+ "miniz_oxide",
+ "rayon-core",
+ "smallvec",
+ "zune-inflate",
+]
+
 [[package]]
 name = "fastrand"
 version = "2.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 
+[[package]]
+name = "fax"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f05de7d48f37cd6730705cbca900770cab77a89f413d23e100ad7fad7795a0ab"
+dependencies = [
+ "fax_derive",
+]
+
+[[package]]
+name = "fax_derive"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a0aca10fb742cb43f9e7bb8467c91aa9bcb8e3ffbc6a6f7389bb93ffc920577d"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+
+[[package]]
+name = "flate2"
+version = "1.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide",
+]
+
 [[package]]
 name = "fnv"
 version = "1.0.7"
@@ -106,6 +382,27 @@ dependencies = [
  "wasip3",
 ]
 
+[[package]]
+name = "gif"
+version = "0.14.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ee8cfcc411d9adbbaba82fb72661cc1bcca13e8bba98b364e62b2dba8f960159"
+dependencies = [
+ "color_quant",
+ "weezl",
+]
+
+[[package]]
+name = "half"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"
+dependencies = [
+ "cfg-if",
+ "crunchy",
+ "zerocopy",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.15.5"
@@ -133,6 +430,46 @@ version = "2.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954"
 
+[[package]]
+name = "image"
+version = "0.25.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104"
+dependencies = [
+ "bytemuck",
+ "byteorder-lite",
+ "color_quant",
+ "exr",
+ "gif",
+ "image-webp",
+ "moxcms",
+ "num-traits",
+ "png",
+ "qoi",
+ "ravif",
+ "rayon",
+ "rgb",
+ "tiff",
+ "zune-core",
+ "zune-jpeg",
+]
+
+[[package]]
+name = "image-webp"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "525e9ff3e1a4be2fbea1fdf0e98686a6d98b4d8f937e1bf7402245af1909e8c3"
+dependencies = [
+ "byteorder-lite",
+ "quick-error 2.0.1",
+]
+
+[[package]]
+name = "imgref"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7c5cedc30da3a610cac6b4ba17597bdf7152cf974e8aab3afb3d54455e371c8"
+
 [[package]]
 name = "indexmap"
 version = "2.14.0"
@@ -145,12 +482,42 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "interpolate_name"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c34819042dc3d3971c46c2190835914dfbe0c3c13f61449b2997f4e9722dfa60"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "itertools"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b192c782037fadd9cfa75548310488aabdbf3d2da73885b31bd0abd03351285"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "itoa"
 version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
+[[package]]
+name = "jobserver"
+version = "0.1.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9afb3de4395d6b3e67a780b6de64b51c978ecf11cb9a462c66be7d4ca9039d33"
+dependencies = [
+ "getrandom 0.3.4",
+ "libc",
+]
+
 [[package]]
 name = "js-sys"
 version = "0.3.95"
@@ -167,12 +534,28 @@ version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
+[[package]]
+name = "lebe"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7a79a3332a6609480d7d0c9eab957bca6b455b91bb84e66d19f5ff66294b85b8"
+
 [[package]]
 name = "libc"
 version = "0.2.185"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f"
 
+[[package]]
+name = "libfuzzer-sys"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f12a681b7dd8ce12bff52488013ba614b869148d54dd79836ab85aafdd53f08d"
+dependencies = [
+ "arbitrary",
+ "cc",
+]
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
@@ -185,12 +568,122 @@ version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
+[[package]]
+name = "loop9"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fae87c125b03c1d2c0150c90365d7d6bcc53fb73a9acaef207d2d065860f062"
+dependencies = [
+ "imgref",
+]
+
+[[package]]
+name = "maybe-rayon"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ea1f30cedd69f0a2954655f7188c6a834246d2bcf1e315e2ac40c4b24dc9519"
+dependencies = [
+ "cfg-if",
+ "rayon",
+]
+
 [[package]]
 name = "memchr"
 version = "2.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "moxcms"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb85c154ba489f01b25c0d36ae69a87e4a1c73a72631fc6c0eb6dde34a73e44b"
+dependencies = [
+ "num-traits",
+ "pxfm",
+]
+
+[[package]]
+name = "new_debug_unreachable"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "650eef8c711430f1a879fdd01d4745a7deea475becfb90269c06775983bbf086"
+
+[[package]]
+name = "no_std_io2"
+version = "0.9.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b51ed7824b6e07d354605f4abb3d9d300350701299da96642ee084f5ce631550"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "nom"
+version = "8.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df9761775871bdef83bee530e60050f7e54b1105350d6884eb0fb4f46c2f9405"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "noop_proc_macro"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0676bb32a98c1a483ce53e500a81ad9c3d5b3f7c920c28c24e9cb0980d0b5bc8"
+
+[[package]]
+name = "num-bigint"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a5e44f723f1133c9deac646763579fdb3ac745e418f2a7af9cd0c431da1f20b9"
+dependencies = [
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "num-derive"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed3955f1a9c7c0c15e092f9c887db08b1fc683305fdf6eb6684f22555355e202"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "num-integer"
+version = "0.1.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-rational"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f83d14da390562dca69fc84082e73e548e1ad308d24accdedd2720017cb37824"
+dependencies = [
+ "num-bigint",
+ "num-integer",
+ "num-traits",
+]
+
 [[package]]
 name = "num-traits"
 version = "0.2.19"
@@ -206,6 +699,37 @@ version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
+[[package]]
+name = "paste"
+version = "1.0.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
+
+[[package]]
+name = "pastey"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "35fb2e5f958ec131621fdd531e9fc186ed768cbe395337403ae56c17a74c68ec"
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "png"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
+dependencies = [
+ "bitflags",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide",
+]
+
 [[package]]
 name = "ppv-lite86"
 version = "0.2.21"
@@ -234,6 +758,25 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "profiling"
+version = "1.0.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eb8486b569e12e2c32ad3e204dbaba5e4b5b216e9367044f25f1dba42341773"
+dependencies = [
+ "profiling-procmacros",
+]
+
+[[package]]
+name = "profiling-procmacros"
+version = "1.0.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52717f9a02b6965224f95ca2a81e2e0c5c43baacd28ca057577988930b6c3d5b"
+dependencies = [
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "proptest"
 version = "1.11.0"
@@ -253,12 +796,33 @@ dependencies = [
  "unarray",
 ]
 
+[[package]]
+name = "pxfm"
+version = "0.1.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e0c5ccf5294c6ccd63a74f1565028353830a9c2f5eb0c682c355c471726a6e3f"
+
+[[package]]
+name = "qoi"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f6d64c71eb498fe9eae14ce4ec935c555749aef511cca85b5568910d6e48001"
+dependencies = [
+ "bytemuck",
+]
+
 [[package]]
 name = "quick-error"
 version = "1.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0"
 
+[[package]]
+name = "quick-error"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
+
 [[package]]
 name = "quote"
 version = "1.0.45"
@@ -318,12 +882,88 @@ dependencies = [
  "rand_core",
 ]
 
+[[package]]
+name = "rav1e"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43b6dd56e85d9483277cde964fd1bdb0428de4fec5ebba7540995639a21cb32b"
+dependencies = [
+ "aligned-vec",
+ "arbitrary",
+ "arg_enum_proc_macro",
+ "arrayvec",
+ "av-scenechange",
+ "av1-grain",
+ "bitstream-io",
+ "built",
+ "cfg-if",
+ "interpolate_name",
+ "itertools",
+ "libc",
+ "libfuzzer-sys",
+ "log",
+ "maybe-rayon",
+ "new_debug_unreachable",
+ "noop_proc_macro",
+ "num-derive",
+ "num-traits",
+ "paste",
+ "profiling",
+ "rand",
+ "rand_chacha",
+ "simd_helpers",
+ "thiserror",
+ "v_frame",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "ravif"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e52310197d971b0f5be7fe6b57530dcd27beb35c1b013f29d66c1ad73fbbcc45"
+dependencies = [
+ "avif-serialize",
+ "imgref",
+ "loop9",
+ "quick-error 2.0.1",
+ "rav1e",
+ "rayon",
+ "rgb",
+]
+
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
 [[package]]
 name = "regex-syntax"
 version = "0.8.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
 
+[[package]]
+name = "rgb"
+version = "0.8.53"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47b34b781b31e5d73e9fbc8689c70551fd1ade9a19e3e28cfec8580a79290cc4"
+
 [[package]]
 name = "rustix"
 version = "1.1.4"
@@ -350,7 +990,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cc6bf79ff24e648f6da1f8d1f011e9cac26491b619e6b9280f2b47f1774e6ee2"
 dependencies = [
  "fnv",
- "quick-error",
+ "quick-error 1.2.3",
  "tempfile",
  "wait-timeout",
 ]
@@ -361,6 +1001,12 @@ version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
 
+[[package]]
+name = "screencapturekit"
+version = "1.5.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "99b732b2db50b25cfbcb171e1b7abda06e77873aeef493e635eb209482fdd149"
+
 [[package]]
 name = "semver"
 version = "1.0.28"
@@ -411,6 +1057,39 @@ dependencies = [
  "zmij",
 ]
 
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
+[[package]]
+name = "simd-adler32"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "703d5c7ef118737c72f1af64ad2f6f8c5e1921f818cdcb97b8fe6fc69bf66214"
+
+[[package]]
+name = "simd_helpers"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95890f873bec569a0362c235787f3aca6e1e887302ba4840839bcc6459c42da6"
+dependencies = [
+ "quote",
+]
+
+[[package]]
+name = "smallvec"
+version = "1.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
+
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
 [[package]]
 name = "syn"
 version = "2.0.117"
@@ -455,6 +1134,20 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "tiff"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b63feaf3343d35b6ca4d50483f94843803b0f51634937cc2ec519fc32232bc52"
+dependencies = [
+ "fax",
+ "flate2",
+ "half",
+ "quick-error 2.0.1",
+ "weezl",
+ "zune-jpeg",
+]
+
 [[package]]
 name = "tinyvec"
 version = "1.11.0"
@@ -470,6 +1163,37 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
+[[package]]
+name = "tracing"
+version = "0.1.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
+dependencies = [
+ "pin-project-lite",
+ "tracing-attributes",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-attributes"
+version = "0.1.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tracing-core"
+version = "0.1.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+]
+
 [[package]]
 name = "unarray"
 version = "0.1.4"
@@ -509,6 +1233,29 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "v_frame"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "666b7727c8875d6ab5db9533418d7c764233ac9c0cff1d469aec8fa127597be2"
+dependencies = [
+ "aligned-vec",
+ "num-traits",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "vcli-capture"
+version = "0.0.1"
+dependencies = [
+ "image",
+ "screencapturekit",
+ "tempfile",
+ "thiserror",
+ "tracing",
+ "vcli-core",
+]
+
 [[package]]
 name = "vcli-core"
 version = "0.0.1"
@@ -628,6 +1375,12 @@ dependencies = [
  "semver",
 ]
 
+[[package]]
+name = "weezl"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a28ac98ddc8b9274cb41bb4d9d4d5c425b6020c50c46f25559911905610b4a88"
+
 [[package]]
 name = "windows-link"
 version = "0.2.1"
@@ -731,6 +1484,12 @@ dependencies = [
  "wasmparser",
 ]
 
+[[package]]
+name = "y4m"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7a5a4b21e1a62b67a2970e6831bc091d7b87e119e7f9791aef9702e3bef04448"
+
 [[package]]
 name = "zerocopy"
 version = "0.8.48"
@@ -756,3 +1515,27 @@ name = "zmij"
 version = "1.0.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+
+[[package]]
+name = "zune-core"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb8a0807f7c01457d0379ba880ba6322660448ddebc890ce29bb64da71fb40f9"
+
+[[package]]
+name = "zune-inflate"
+version = "0.2.54"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73ab332fe2f6680068f3582b16a24f90ad7096d5d39b974d1c0aff0125116f02"
+dependencies = [
+ "simd-adler32",
+]
+
+[[package]]
+name = "zune-jpeg"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296"
+dependencies = [
+ "zune-core",
+]
diff --git a/crates/vcli-capture/src/capture.rs b/crates/vcli-capture/src/capture.rs
index 993c7a8..1bd9da4 100644
--- a/crates/vcli-capture/src/capture.rs
+++ b/crates/vcli-capture/src/capture.rs
@@ -46,15 +46,27 @@ pub trait Capture: Send + Sync {
 
     /// Enumerate visible application windows on all displays. Excludes
     /// off-screen and minimized windows. Stable ordering per backend.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`CaptureError`] if the backend fails to enumerate windows.
     fn enumerate_windows(&self) -> Result<Vec<WindowDescriptor>, CaptureError>;
 
     /// Grab a full-screen frame of the primary display.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`CaptureError`] if the backend fails to capture the screen.
     fn grab_screen(&mut self) -> Result<Frame, CaptureError>;
 
     /// Grab a frame cropped to the given window's current bounds. Backend
     /// may re-resolve the window by id; if the window has moved/resized
     /// between enumeration and grab, the returned `Frame.bounds` reflects
     /// the actual capture, not the stale descriptor bounds.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`CaptureError`] if the window is not found or capture fails.
     fn grab_window(&mut self, window: &WindowDescriptor) -> Result<Frame, CaptureError>;
 }
 
@@ -73,7 +85,12 @@ mod tests {
             id: 42,
             app: "Safari".into(),
             title: "YouTube".into(),
-            bounds: Rect { x: 0, y: 0, w: 800, h: 600 },
+            bounds: Rect {
+                x: 0,
+                y: 0,
+                w: 800,
+                h: 600,
+            },
             window_index: WindowIndex(0),
             display: DisplayId::PRIMARY,
         };
diff --git a/crates/vcli-capture/src/error.rs b/crates/vcli-capture/src/error.rs
index bd5648a..5efee7f 100644
--- a/crates/vcli-capture/src/error.rs
+++ b/crates/vcli-capture/src/error.rs
@@ -67,22 +67,33 @@ mod tests {
         assert_eq!(e.to_string(), "screen recording permission not granted");
         let e = CaptureError::WindowNotFound { id: 77 };
         assert_eq!(e.to_string(), "window not found: id=77");
-        let e = CaptureError::MalformedFrame { reason: "bad stride".into() };
+        let e = CaptureError::MalformedFrame {
+            reason: "bad stride".into(),
+        };
         assert!(e.to_string().contains("bad stride"));
     }
 
     #[test]
     fn codes_are_stable() {
         assert_eq!(CaptureError::PermissionDenied.code(), "permission_denied");
-        assert_eq!(CaptureError::WindowNotFound { id: 1 }.code(), "unknown_window");
         assert_eq!(
-            CaptureError::Backend { message: "x".into() }.code(),
+            CaptureError::WindowNotFound { id: 1 }.code(),
+            "unknown_window"
+        );
+        assert_eq!(
+            CaptureError::Backend {
+                message: "x".into()
+            }
+            .code(),
             "capture_failed"
         );
         assert_eq!(
             CaptureError::MalformedFrame { reason: "x".into() }.code(),
             "capture_failed"
         );
-        assert_eq!(CaptureError::Unsupported { what: "x" }.code(), "unsupported");
+        assert_eq!(
+            CaptureError::Unsupported { what: "x" }.code(),
+            "unsupported"
+        );
     }
 }
diff --git a/crates/vcli-capture/src/lib.rs b/crates/vcli-capture/src/lib.rs
index 13e1aa7..67232e2 100644
--- a/crates/vcli-capture/src/lib.rs
+++ b/crates/vcli-capture/src/lib.rs
@@ -1,4 +1,4 @@
-//! vcli-capture — Capture trait, macOS ScreenCaptureKit backend, mock impl, Windows stub.
+//! vcli-capture — Capture trait, macOS `ScreenCaptureKit` backend, mock impl, Windows stub.
 //!
 //! See spec §v0 scope and §Architecture → crate responsibilities. All outputs
 //! use `vcli-core` types (`Frame`, `FrameFormat`, `Rect`, `WindowIndex`).
@@ -30,4 +30,4 @@ pub mod windows;
 pub use capture::{Capture, DisplayId, WindowDescriptor};
 pub use error::CaptureError;
 pub use mock::MockCapture;
-pub use permission::{PermissionStatus, check_screen_recording_permission};
+pub use permission::{check_screen_recording_permission, PermissionStatus};
diff --git a/crates/vcli-capture/src/macos/convert.rs b/crates/vcli-capture/src/macos/convert.rs
index 9d54dc0..7bfa2da 100644
--- a/crates/vcli-capture/src/macos/convert.rs
+++ b/crates/vcli-capture/src/macos/convert.rs
@@ -50,11 +50,7 @@ pub fn bgra_to_frame(raw: RawBgra) -> Result<Frame, CaptureError> {
         })?;
     if raw.pixels.len() < need {
         return Err(CaptureError::MalformedFrame {
-            reason: format!(
-                "buffer len {} < stride*height {}",
-                raw.pixels.len(),
-                need
-            ),
+            reason: format!("buffer len {} < stride*height {}", raw.pixels.len(), need),
         });
     }
     if raw.stride < (raw.width_px as usize) * 4 {
@@ -69,6 +65,7 @@ pub fn bgra_to_frame(raw: RawBgra) -> Result<Frame, CaptureError> {
 
     let scale = raw.scale;
     let (out_w, out_h, out_stride, out_pixels) = if (scale - 1.0_f32).abs() < f32::EPSILON {
+        #[allow(clippy::cast_possible_wrap)]
         (
             raw.width_px as i32,
             raw.height_px as i32,
@@ -101,7 +98,7 @@ pub fn bgra_to_frame(raw: RawBgra) -> Result<Frame, CaptureError> {
 }
 
 /// 2:1 box-filter downsample of a BGRA buffer. Returns
-/// `(out_w, out_h, out_stride, out_pixels)`. Output stride = out_w * 4.
+/// `(out_w, out_h, out_stride, out_pixels)`. Output stride = `out_w * 4`.
 fn downsample_2x(raw: &RawBgra) -> (i32, i32, usize, Vec<u8>) {
     let out_w = (raw.width_px / 2) as usize;
     let out_h = (raw.height_px / 2) as usize;
@@ -110,10 +107,10 @@ fn downsample_2x(raw: &RawBgra) -> (i32, i32, usize, Vec<u8>) {
     for y in 0..out_h {
         let src_y0 = y * 2;
         let src_y1 = src_y0 + 1;
-        let row0 = &raw.pixels
-            [src_y0 * raw.stride..src_y0 * raw.stride + raw.width_px as usize * 4];
-        let row1 = &raw.pixels
-            [src_y1 * raw.stride..src_y1 * raw.stride + raw.width_px as usize * 4];
+        let row0 =
+            &raw.pixels[src_y0 * raw.stride..src_y0 * raw.stride + raw.width_px as usize * 4];
+        let row1 =
+            &raw.pixels[src_y1 * raw.stride..src_y1 * raw.stride + raw.width_px as usize * 4];
         for x in 0..out_w {
             let sx = x * 2 * 4;
             let idx = y * out_stride + x * 4;
@@ -130,6 +127,7 @@ fn downsample_2x(raw: &RawBgra) -> (i32, i32, usize, Vec<u8>) {
             }
         }
     }
+    #[allow(clippy::cast_possible_truncation, clippy::cast_possible_wrap)]
     (out_w as i32, out_h as i32, out_stride, out)
 }
 
diff --git a/crates/vcli-capture/src/macos/sck.rs b/crates/vcli-capture/src/macos/sck.rs
index 5a29156..15f1394 100644
--- a/crates/vcli-capture/src/macos/sck.rs
+++ b/crates/vcli-capture/src/macos/sck.rs
@@ -1,6 +1,6 @@
-//! macOS ScreenCaptureKit backend. Synchronous facade over the
+//! macOS `ScreenCaptureKit` backend. Synchronous facade over the
 //! `screencapturekit` crate (v1.5.4 on crates.io; plan cited "0.3" which does
-//! not exist). SCShareableContent::get() is a blocking synchronous call; no
+//! not exist). `SCShareableContent::get()` is a blocking synchronous call; no
 //! tokio runtime is needed.
 //!
 //! ## API wiring notes (v1.5.4 vs plan assumptions)
@@ -10,20 +10,19 @@
 //! | `screencapturekit::util::has_permission()` | Does not exist; see `permission.rs` for CG extern |
 //! | `SCContentFilter::new_with_display_excluding_windows` | `SCContentFilter::create().with_display(d).with_excluding_windows(&[]).build()` |
 //! | `SCContentFilter::new_with_desktop_independent_window` | `SCContentFilter::create().with_window(w).build()` |
-//! | `SCStreamConfiguration::new()` + setters returning `Result` | Builder pattern: `.with_width()`, `.with_height()`, `.with_pixel_format()` (infallible) |
+//! | `SCStreamConfiguration::new()` + setters returning `Result` | Builder pattern (infallible) |
 //! | `SCScreenshotManager::capture_image_with_filter` | `SCScreenshotManager::capture_image(&filter, &config)` |
-//! | `image.bgra_bytes()` | `image.rgba_data()` → RGBA Vec<u8> (we store as Rgba8 frame) |
+//! | `image.bgra_bytes()` | `image.rgba_data()` → RGBA `Vec<u8>` (stored as `Rgba8` frame) |
 //! | `image.bytes_per_row()` | Not available; computed as `width * 4` |
-//! | `display.scale_factor()` | Not available; scale is always 1.0 (SCK gives logical px) |
+//! | `display.scale_factor()` | Not available; scale is always 1.0 (`SCK` gives logical px) |
 //! | `CGRect.origin.x`, `.size.width` | `CGRect.x`, `.width` (flat struct) |
 //! | `window.owning_application()?.application_name().ok()` | `.application_name()` returns `String` directly |
 //!
 //! Coordinate model (Decision F1, 4.3):
-//!   SCK reports `CGRect` in logical points. We treat logical points == logical
+//!   `SCK` reports `CGRect` in logical points. We treat logical points == logical
 //!   pixels for v0 (macOS). Physical pixel downsample happens in `convert.rs`
 //!   using the display's scale factor.
 
-
 use std::collections::HashMap;
 use std::sync::Mutex;
 
@@ -45,7 +44,7 @@ use crate::error::CaptureError;
 use crate::macos::convert::{bgra_to_frame, RawBgra};
 use crate::permission::{check_screen_recording_permission, PermissionStatus};
 
-/// macOS SCK-backed `Capture` implementation.
+/// macOS `SCK`-backed `Capture` implementation.
 pub struct MacCapture {
     /// Cached `SCShareableContent` refreshed per-call. Behind a `Mutex`
     /// because SCK types are `!Sync` on some versions.
@@ -138,6 +137,7 @@ fn build_descriptors(windows: Vec<SCWindow>) -> Vec<WindowDescriptor> {
                 .unwrap_or_default();
             let title = w.title().unwrap_or_default();
             let rect = w.frame();
+            #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
             let bounds = Rect {
                 x: rect.x as i32,
                 y: rect.y as i32,
@@ -153,16 +153,31 @@ fn build_descriptors(windows: Vec<SCWindow>) -> Vec<WindowDescriptor> {
 /// Return current monotonic-ish timestamp in nanoseconds.
 fn monotonic_ns() -> u64 {
     use std::time::{SystemTime, UNIX_EPOCH};
+    // The cast from u128 to u64 is intentional: we only need nanoseconds since
+    // the Unix epoch modulo 2^64, which won't wrap for ~584 years from 1970.
+    #[allow(clippy::cast_possible_truncation)]
     SystemTime::now()
         .duration_since(UNIX_EPOCH)
-        .map(|d| d.as_nanos() as u64)
-        .unwrap_or(0)
+        .map_or(0, |d| d.as_nanos() as u64)
+}
+
+/// Map a `screencapturekit` error to a `CaptureError`.
+fn map_sck_error(e: &screencapturekit::error::SCError, context: &str) -> CaptureError {
+    use screencapturekit::error::SCError;
+    match e {
+        SCError::PermissionDenied(_) | SCError::NoShareableContent(_) => {
+            CaptureError::PermissionDenied
+        }
+        _ => CaptureError::Backend {
+            message: format!("{context}: {e}"),
+        },
+    }
 }
 
 impl Capture for MacCapture {
     fn supported_formats(&self) -> &[FrameFormat] {
-        // ScreenCaptureKit v1.5.4 capture_image returns RGBA data.
-        // We store it as Rgba8.
+        // `ScreenCaptureKit` v1.5.4 `capture_image` returns RGBA data.
+        // We store it as `Rgba8`.
         const FORMATS: &[FrameFormat] = &[FrameFormat::Rgba8];
         FORMATS
     }
@@ -171,7 +186,7 @@ impl Capture for MacCapture {
         let content = self.refresh_content()?;
         let mut windows = content.windows();
         // Stable ordering: sort by window_id ascending (AX order ≈ creation time).
-        windows.sort_by_key(|w| w.window_id());
+        windows.sort_by_key(SCWindow::window_id);
         Ok(build_descriptors(windows))
     }
 
@@ -189,29 +204,23 @@ impl Capture for MacCapture {
             .with_excluding_windows(&[])
             .build();
 
-        let image =
-            SCScreenshotManager::capture_image(&filter, &cfg).map_err(|e| match &e {
-                screencapturekit::error::SCError::PermissionDenied(_) => {
-                    CaptureError::PermissionDenied
-                }
-                screencapturekit::error::SCError::NoShareableContent(_) => {
-                    CaptureError::PermissionDenied
-                }
-                _ => CaptureError::Backend {
-                    message: format!("SCScreenshotManager::capture_image: {e}"),
-                },
-            })?;
+        let image = SCScreenshotManager::capture_image(&filter, &cfg)
+            .map_err(|e| map_sck_error(&e, "SCScreenshotManager::capture_image"))?;
 
+        #[allow(clippy::cast_possible_truncation)]
         let width_px = image.width() as u32;
+        #[allow(clippy::cast_possible_truncation)]
         let height_px = image.height() as u32;
-        // rgba_data() returns raw RGBA bytes; stride = width * 4.
-        let pixels = image.rgba_data().map_err(|e| CaptureError::MalformedFrame {
-            reason: format!("CGImage::rgba_data: {e}"),
-        })?;
+        // `rgba_data()` returns raw RGBA bytes; stride = width * 4.
+        let pixels = image
+            .rgba_data()
+            .map_err(|e| CaptureError::MalformedFrame {
+                reason: format!("CGImage::rgba_data: {e}"),
+            })?;
         let stride = (width_px as usize) * 4;
 
-        // SCDisplay.width()/height() report logical pixels; scale = 1.0.
-        // CGDisplayScaleFactor was removed from macOS 26 SDK.
+        // `SCDisplay.width()`/`height()` report logical pixels; scale = 1.0.
+        // `CGDisplayScaleFactor` was removed from macOS 26 SDK.
         let raw = RawBgra {
             width_px,
             height_px,
@@ -223,8 +232,8 @@ impl Capture for MacCapture {
             logical_origin_y: 0,
         };
 
-        // bgra_to_frame produces FrameFormat::Bgra8, but since rgba_data
-        // gives us RGBA bytes, we override the format to Rgba8.
+        // `bgra_to_frame` produces `FrameFormat::Bgra8`, but since `rgba_data`
+        // gives us RGBA bytes, we override the format to `Rgba8`.
         let mut frame = bgra_to_frame(raw)?;
         frame.format = FrameFormat::Rgba8;
         Ok(frame)
@@ -233,7 +242,13 @@ impl Capture for MacCapture {
     fn grab_window(&mut self, window: &WindowDescriptor) -> Result<Frame, CaptureError> {
         let sck_window = self.locate_window(window.id)?;
         let frame_rect = sck_window.frame();
+        #[allow(
+            clippy::cast_possible_truncation,
+            clippy::cast_sign_loss,
+            clippy::cast_precision_loss
+        )]
         let width_px = frame_rect.width as u32;
+        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
         let height_px = frame_rect.height as u32;
 
         let cfg = SCStreamConfiguration::new()
@@ -243,27 +258,22 @@ impl Capture for MacCapture {
 
         let filter = SCContentFilter::create().with_window(&sck_window).build();
 
-        let image =
-            SCScreenshotManager::capture_image(&filter, &cfg).map_err(|e| match &e {
-                screencapturekit::error::SCError::PermissionDenied(_) => {
-                    CaptureError::PermissionDenied
-                }
-                screencapturekit::error::SCError::NoShareableContent(_) => {
-                    CaptureError::PermissionDenied
-                }
-                _ => CaptureError::Backend {
-                    message: format!("capture_image: {e}"),
-                },
-            })?;
+        let image = SCScreenshotManager::capture_image(&filter, &cfg)
+            .map_err(|e| map_sck_error(&e, "capture_image"))?;
 
+        #[allow(clippy::cast_possible_truncation)]
         let img_w = image.width() as u32;
+        #[allow(clippy::cast_possible_truncation)]
         let img_h = image.height() as u32;
-        let pixels = image.rgba_data().map_err(|e| CaptureError::MalformedFrame {
-            reason: format!("CGImage::rgba_data: {e}"),
-        })?;
+        let pixels = image
+            .rgba_data()
+            .map_err(|e| CaptureError::MalformedFrame {
+                reason: format!("CGImage::rgba_data: {e}"),
+            })?;
         let stride = (img_w as usize) * 4;
 
-        // display_scale is always 1.0 for SCK (logical px). No content refresh needed.
+        // `display_scale` is always 1.0 for SCK (logical px).
+        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
         let raw = RawBgra {
             width_px: img_w,
             height_px: img_h,
@@ -287,7 +297,7 @@ mod tests {
 
     #[test]
     fn build_descriptors_assigns_indices_per_app_title() {
-        // We can't construct real SCWindows in unit tests; cover the pure
+        // We can't construct real `SCWindows` in unit tests; cover the pure
         // index-assignment logic instead.
         let a: Vec<WindowDescriptor> = Vec::new();
         assert!(a.is_empty());
@@ -308,25 +318,45 @@ mod tests {
                 1,
                 "Safari".into(),
                 "YouTube".into(),
-                Rect { x: 0, y: 0, w: 10, h: 10 },
+                Rect {
+                    x: 0,
+                    y: 0,
+                    w: 10,
+                    h: 10,
+                },
             ),
             (
                 2,
                 "Safari".into(),
                 "YouTube".into(),
-                Rect { x: 10, y: 0, w: 10, h: 10 },
+                Rect {
+                    x: 10,
+                    y: 0,
+                    w: 10,
+                    h: 10,
+                },
             ),
             (
                 3,
                 "Safari".into(),
                 "Mail".into(),
-                Rect { x: 20, y: 0, w: 10, h: 10 },
+                Rect {
+                    x: 20,
+                    y: 0,
+                    w: 10,
+                    h: 10,
+                },
             ),
             (
                 4,
                 "Finder".into(),
                 "YouTube".into(),
-                Rect { x: 30, y: 0, w: 10, h: 10 },
+                Rect {
+                    x: 30,
+                    y: 0,
+                    w: 10,
+                    h: 10,
+                },
             ),
         ];
         let d = assign_window_indices(raw);
diff --git a/crates/vcli-capture/src/mock.rs b/crates/vcli-capture/src/mock.rs
index 0938b30..f89e462 100644
--- a/crates/vcli-capture/src/mock.rs
+++ b/crates/vcli-capture/src/mock.rs
@@ -61,10 +61,16 @@ impl MockCapture {
 
     /// Set canned frames for a particular window id. Subsequent calls to
     /// `grab_window` with that descriptor cycle through these frames.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the internal mutex is poisoned.
     pub fn set_window_frames(&self, window_id: u64, frames: Vec<Frame>) {
         let mut g = self.inner.lock().unwrap();
-        if let Some((_, slot)) =
-            g.window_frame_map.iter_mut().find(|(id, _)| *id == window_id)
+        if let Some((_, slot)) = g
+            .window_frame_map
+            .iter_mut()
+            .find(|(id, _)| *id == window_id)
         {
             *slot = frames;
         } else {
@@ -74,6 +80,10 @@ impl MockCapture {
 
     /// Arm the next call to any grab/enumerate method to fail with `e`. Used
     /// to exercise error paths in consumer tests. Consumed by one failing call.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the internal mutex is poisoned.
     pub fn arm_error(&self, e: CaptureError) {
         self.inner.lock().unwrap().next_error = Some(e);
     }
@@ -121,7 +131,10 @@ impl Capture for MockCapture {
         if let Some(e) = Self::take_armed_error(&mut g) {
             return Err(e);
         }
-        let pos = g.window_frame_map.iter().position(|(id, _)| *id == window.id);
+        let pos = g
+            .window_frame_map
+            .iter()
+            .position(|(id, _)| *id == window.id);
         let Some(pos) = pos else {
             return Err(CaptureError::WindowNotFound { id: window.id });
         };
@@ -154,7 +167,18 @@ mod tests {
 
     fn tiny(format: FrameFormat, value: u8) -> Frame {
         let bytes: Arc<[u8]> = vec![value; 4 * 4 * 2].into();
-        Frame::new(format, Rect { x: 0, y: 0, w: 4, h: 2 }, 4 * 4, bytes, 0)
+        Frame::new(
+            format,
+            Rect {
+                x: 0,
+                y: 0,
+                w: 4,
+                h: 2,
+            },
+            4 * 4,
+            bytes,
+            0,
+        )
     }
 
     #[test]
@@ -188,7 +212,12 @@ mod tests {
             id: 9,
             app: "Finder".into(),
             title: "Downloads".into(),
-            bounds: Rect { x: 0, y: 0, w: 1000, h: 600 },
+            bounds: Rect {
+                x: 0,
+                y: 0,
+                w: 1000,
+                h: 600,
+            },
             window_index: WindowIndex(0),
             display: DisplayId::PRIMARY,
         };
@@ -203,7 +232,12 @@ mod tests {
             id: 7,
             app: "Safari".into(),
             title: "YT".into(),
-            bounds: Rect { x: 0, y: 0, w: 4, h: 2 },
+            bounds: Rect {
+                x: 0,
+                y: 0,
+                w: 4,
+                h: 2,
+            },
             window_index: WindowIndex(0),
             display: DisplayId::PRIMARY,
         };
@@ -220,7 +254,12 @@ mod tests {
             id: 100,
             app: "X".into(),
             title: "Y".into(),
-            bounds: Rect { x: 0, y: 0, w: 4, h: 2 },
+            bounds: Rect {
+                x: 0,
+                y: 0,
+                w: 4,
+                h: 2,
+            },
             window_index: WindowIndex(0),
             display: DisplayId::PRIMARY,
         };
diff --git a/crates/vcli-capture/src/permission.rs b/crates/vcli-capture/src/permission.rs
index 3f0c687..219ac88 100644
--- a/crates/vcli-capture/src/permission.rs
+++ b/crates/vcli-capture/src/permission.rs
@@ -1,5 +1,4 @@
 //! Screen Recording (TCC) permission probe.
-#![allow(unsafe_code)] // Required for CGPreflightScreenCaptureAccess / CGRequestScreenCaptureAccess extern "C" links on macOS.
 //!
 //! On macOS this calls `CGPreflightScreenCaptureAccess` and
 //! `CGRequestScreenCaptureAccess` from the Core Graphics framework directly
@@ -10,6 +9,7 @@
 //! "0.3" which does not exist on crates.io) does not expose a
 //! `util::has_permission` helper. We link the Core Graphics symbols directly
 //! instead, which is the idiomatic macOS approach.
+#![allow(unsafe_code)] // Required for CGPreflightScreenCaptureAccess / CGRequestScreenCaptureAccess extern "C" links on macOS.
 
 use crate::error::CaptureError;
 
@@ -39,29 +39,30 @@ pub enum PermissionStatus {
 /// in a way that is not "permission denied" (very rare — e.g., window server
 /// unreachable).
 pub fn check_screen_recording_permission() -> Result<PermissionStatus, CaptureError> {
-    #[cfg(target_os = "macos")]
-    {
-        // CGPreflightScreenCaptureAccess is a Core Graphics function available
-        // since macOS 10.15. It returns true if permission is granted, false
-        // otherwise, without prompting the user.
-        extern "C" {
-            fn CGPreflightScreenCaptureAccess() -> bool;
-        }
-        // SAFETY: CGPreflightScreenCaptureAccess is a stable macOS framework
-        // symbol with no preconditions beyond the process having a window
-        // server connection. It is safe to call from any thread.
-        let granted = unsafe { CGPreflightScreenCaptureAccess() };
-        return Ok(if granted {
-            PermissionStatus::Granted
-        } else {
-            PermissionStatus::Denied
-        });
-    }
+    cfg_if_macos()
+}
 
-    #[cfg(not(target_os = "macos"))]
-    {
-        Ok(PermissionStatus::Granted)
+#[cfg(target_os = "macos")]
+#[allow(clippy::unnecessary_wraps)]
+fn cfg_if_macos() -> Result<PermissionStatus, CaptureError> {
+    extern "C" {
+        fn CGPreflightScreenCaptureAccess() -> bool;
     }
+    // SAFETY: CGPreflightScreenCaptureAccess is a stable macOS framework
+    // symbol with no preconditions beyond the process having a window
+    // server connection. It is safe to call from any thread.
+    let granted = unsafe { CGPreflightScreenCaptureAccess() };
+    Ok(if granted {
+        PermissionStatus::Granted
+    } else {
+        PermissionStatus::Denied
+    })
+}
+
+#[cfg(not(target_os = "macos"))]
+#[allow(clippy::unnecessary_wraps)]
+fn cfg_if_macos() -> Result<PermissionStatus, CaptureError> {
+    Ok(PermissionStatus::Granted)
 }
 
 /// Request the user grant screen-recording permission. Triggers the macOS
@@ -71,22 +72,26 @@ pub fn check_screen_recording_permission() -> Result<PermissionStatus, CaptureEr
 ///
 /// Returns [`CaptureError::Backend`] if the request call fails.
 pub fn request_screen_recording_permission() -> Result<(), CaptureError> {
-    #[cfg(target_os = "macos")]
-    {
-        extern "C" {
-            fn CGRequestScreenCaptureAccess() -> bool;
-        }
-        // SAFETY: CGRequestScreenCaptureAccess is a stable macOS framework
-        // symbol. We ignore the return value — the prompt is async from the
-        // user's perspective; the caller should re-probe after user action.
-        let _ = unsafe { CGRequestScreenCaptureAccess() };
-        return Ok(());
-    }
+    do_request()
+}
 
-    #[cfg(not(target_os = "macos"))]
-    {
-        Ok(())
+#[cfg(target_os = "macos")]
+#[allow(clippy::unnecessary_wraps)]
+fn do_request() -> Result<(), CaptureError> {
+    extern "C" {
+        fn CGRequestScreenCaptureAccess() -> bool;
     }
+    // SAFETY: CGRequestScreenCaptureAccess is a stable macOS framework
+    // symbol. We ignore the return value — the prompt is async from the
+    // user's perspective; the caller should re-probe after user action.
+    let _granted = unsafe { CGRequestScreenCaptureAccess() };
+    Ok(())
+}
+
+#[cfg(not(target_os = "macos"))]
+#[allow(clippy::unnecessary_wraps)]
+fn do_request() -> Result<(), CaptureError> {
+    Ok(())
 }
 
 #[cfg(test)]

From ae70eb5e61f09a4ecbc47cd4276c282ed24fd5e0 Mon Sep 17 00:00:00 2001
From: Yixiang Zeng <blaksmatic@gmail.com>
Date: Fri, 17 Apr 2026 08:18:08 -0700
Subject: [PATCH 11/11] vcli-capture: move std::env use inside macOS run()
 branch

The module-level `use std::env;` was unused on non-macOS targets
because `env::args()` is only called from the macOS `run()` function.
Under `-D warnings` on Ubuntu this failed the build.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 crates/vcli-capture/examples/capture_once.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/vcli-capture/examples/capture_once.rs b/crates/vcli-capture/examples/capture_once.rs
index db1204a..fe4c8ab 100644
--- a/crates/vcli-capture/examples/capture_once.rs
+++ b/crates/vcli-capture/examples/capture_once.rs
@@ -6,7 +6,6 @@
 //! Usage:  cargo run -p vcli-capture --example capture_once
 //!         cargo run -p vcli-capture --example capture_once -- --save /tmp/out.png
 
-use std::env;
 use std::process::ExitCode;
 
 fn main() -> ExitCode {
@@ -21,6 +20,7 @@ fn main() -> ExitCode {
 
 #[cfg(target_os = "macos")]
 fn run() -> Result<(), Box<dyn std::error::Error>> {
+    use std::env;
     use vcli_capture::{
         capture::Capture,
         macos::MacCapture,