@desklink/host 0.1.0 → 0.1.1

package/docs/PROTOCOL.md

@@ -1,12 +1,14 @@
-# desklink local control protocol (v2)
+# desklink local control protocol (v3)
 
 The host engine is a per-user, on-demand process. A consumer that already owns
 the user's session starts it and talks to it over an inherited private channel —
 the engine never opens a public listener, never runs as root, and never installs
 a service.
 
-This document is the engine's whole public surface. It contains no application
-concepts: no accounts, no chat, no machine ids, no pane ids.
+This document describes the shared Linux and macOS engine protocol. The macOS
+engine uses the same v3 stdio/WebRTC session path, with native display capture,
+input and clipboard adapters. The protocol contains no application concepts:
+no accounts, no chat, no machine ids, no pane ids.
 
 ## Starting the engine
 
@@ -55,13 +57,13 @@ Request parameters use the engine's own snake_case names (`session_id`,
 ## Handshake
 
 ```jsonc
-{"id":1,"method":"hello","params":{"protocol":2}}
+{"id":1,"method":"hello","params":{"protocol":3}}
 ```
 
 Result:
 
 ```jsonc
-{"protocol":2,"engine":"desklink-host/0.1.0","platform":"linux", /* the rest of Capabilities */ }
+{"protocol":3,"engine":"desklink-host/0.1.0","platform":"linux", /* the rest of Capabilities */ }
 ```
 
 The consumer must send `hello` first, and a version the engine does not speak is
@@ -69,6 +71,31 @@ refused with `error.code = "unsupported-protocol"`. Until a supported `hello`
 arrives, every other request is refused the same way; `capabilities` and
 `shutdown` are the two that answer without a handshake.
 
+## macOS
+
+macOS speaks protocol 3 and shares the session lifecycle below. It captures the
+selected display with ScreenCaptureKit, encodes VP9, and uses the same WebRTC
+offer, ICE, control-channel, lease, and metrics flow as Linux. Capture currently
+uses one bounded ScreenCaptureKit stream (three-frame queue); the backend may
+supply fewer frames. Audio is not captured.
+
+`capabilities` is non-prompting and reports active displays (pixel and point
+dimensions, origin and scale), the current keyboard layout, console state, and
+Screen Recording/Accessibility grant states. A `display` source accepts an
+optional `display_id` from `capture.displays`; an absent ID selects the main
+display. Screen Recording consent is requested by `session.open` when capture
+is needed. Control may request Accessibility consent; if it remains unavailable,
+open fails with `input-unavailable`. TCC permissions attach to the responsible
+launching app (for example Terminal, iTerm, or the Node.js host), not to a
+separate DesklinkHost.app bundle. Enable that app in **System Settings → Privacy
+& Security → Screen & System Audio Recording** and **Accessibility**, then
+reconnect. No TCC state is pre-seeded or bypassed.
+
+macOS clipboard read/write is plain text and requires the session's `clipboard`
+permission. `restore_token` is not supported by this native backend; a new
+session may require fresh consent. The macOS engine requires a VP9-enabled build
+(`DESKLINK_VPX_STATIC_DIR`) for `serve`.
+
 ## Capabilities
 
 ```jsonc
@@ -77,7 +104,7 @@ arrives, every other request is refused the same way; `capabilities` and
 
 ```jsonc
 {
-  "protocol": 2,
+  "protocol": 3,
   "engine": "desklink-host/0.1.0",
   "platform": "linux",
   "session": {"kind": "wayland"},
@@ -117,7 +144,8 @@ without kernel input access a portal session may request `view`, but an open
 requesting `control` is refused. X display capture uses XTest instead and does
 not require that grant. The muxr host and WebSocket bridge report clipboard
 unavailable for an X display, regardless of the engine's Wayland clipboard
-probe. The engine never asks for privileges on its own.
+probe. On Linux the engine never asks for privileges on its own; macOS may
+request Screen Recording or Accessibility consent at `session.open`.
 
 `capabilities` is safe to call before any consent has been given and must not
 trigger a capture request.
@@ -127,6 +155,7 @@ trigger a capture request.
 ```jsonc
 {"id":4,"method":"session.open","params":{
   "source": {"kind":"portal"},          // or {"kind":"x11","display":":99"}
+                                           // macOS: {"kind":"display","display_id":123}
   "permissions": ["view","control","clipboard"],
   "max_width": 3840, "max_height": 2160, // encode box (default); never upscales
   "bitrate_kbps": 0,                    // 0 (default): sized to the encoded surface
@@ -134,7 +163,8 @@ trigger a capture request.
   "ice_servers": [{"urls":["stun:..."],"username":null,"credential":null}],
   "restore_token": null,                // from a previous session.restoreToken
   "ttl_seconds": 3600,                 // session lease; default 3600
-  "loopback_tcp": false                // also offer ICE over TCP on 127.0.0.1; default false
+  "loopback_tcp": false,               // also offer ICE over TCP on 127.0.0.1; default false
+  "agent_indicator": false             // local input feedback; default false (phone control)
 }}
 ```
 
@@ -150,20 +180,31 @@ Result:
 
 `source` selects the desktop. `portal` (or absent) asks the compositor for a
 screen cast, which is the only path that carries a Wayland user's consent;
-`x11` reads a named X display's root window and applies input through XTest. The
-choice is capability-based rather than a table of desktops: the portal when there
-is one, an X display otherwise. It is normally the *consumer's* decision, because
-a client is not in a position to know which of the two a machine can offer.
-
-`permissions` are the engine's authority for this session. The engine enforces
-them on every input and clipboard action and never infers them from a source, a
-peer or an SDP. `control` without a working input backend is refused at
-`session.open` with `error.code = "input-unavailable"` — the consumer must ask
-for `view` explicitly instead.
-
-`max_fps` defaults to 30. It caps the encoded frame rate and the X11 capture
-loop; portal capture offers it as the preferred PipeWire frame rate (clamped
-to the offered 0–1000 fps range). The source may still supply fewer frames.
+`x11` reads a named X display's root window and applies input through XTest;
+`display` selects a macOS display by the ID reported in capabilities (or the
+main display when omitted). The choice is normally the *consumer's* decision,
+because a client is not in a position to know which backend a machine can offer.
+
+`permissions` are the engine's authority for this session. `view` is required
+to open a session. The engine enforces the remaining scopes on every input and
+clipboard action and never infers them from a source, a peer or an SDP.
+`control` without a working input backend is refused at `session.open` with
+`error.code = "input-unavailable"` — the consumer must ask for `view` explicitly instead.
+
+`max_fps` defaults to 30 and is bounded to 1–60. It caps the encoded frame
+rate and X11 capture loop; portal capture offers it as the preferred PipeWire
+frame rate, and macOS sets its ScreenCaptureKit stream minimum frame interval.
+A source may still supply fewer frames.
+
+`agent_indicator` is opt-in local feedback for an agent controller; desklink-axi
+sets it for control sessions, never for view-only or human phone control. It
+adds an eased pointer halo, click ripple, and typing pulse. On Wayland it uses
+a click-through layer-shell surface with an edge glow; its bounded area is
+masked before capture/diff (pixels behind the effect can remain briefly stale).
+On bare X11 it replaces the pointer sprite instead, which XGetImage excludes:
+there is no edge glow on that path. macOS uses a nonactivating, click-through
+window excluded by the ScreenCaptureKit content filter. Closing the session
+fades and removes the indicator.
 
 `session.open` is where the capture request happens, which is where the user's
 consent appears. It is not implicit and it is not retried silently.
@@ -209,7 +250,7 @@ always does.
   "firstFrame":true}}                 // false until a frame has been encoded
 ```
 
-The `geometry` a client maps touch against is the one `session.open` returned,
+A stopped capture emits `{"event":"session.capture.stopped","params":{"sessionId":"…","reason":"SCStream stopped (SCStreamErrorDomain -3821): …"}}`. Frame requests then return `stream-stopped` rather than stale pixels. On macOS the engine retries opening the stream up to three times and emits `session.state` with `capture=streaming` on recovery; Linux capture errors also surface instead of serving an old frame.\n\nThe `geometry` a client maps touch against is the one `session.open` returned,
 and the one the control channel's `hello` repeats. A session keeps the one
 `generation` it was opened with: a different source or scale is a new
 `session.open`, not a generation change within a session.
@@ -289,7 +330,7 @@ are JSON, one per message:
 The engine answers on the same channel:
 
 ```jsonc
-{"kind":"hello","protocol":2,"geometry":{…}}     // once, when the channel opens
+{"kind":"hello","protocol":3,"geometry":{…}}     // once, when the channel opens
 {"kind":"ack","seq":44}
 {"kind":"rejected","seq":44,"code":"coordinates","message":"(9000,4) is outside the 1280x720 surface"}
 {"kind":"clipboard","request":"…","text":"…","truncated":false}   // an empty "text" with "error" when the read failed
@@ -307,9 +348,36 @@ physical effect.
 The engine holds its own pressed-key/button state. `close`, `release_all`,
 control-channel loss and process exit all synthesize releases for exactly the
 keys and buttons this session pressed, so a dropped connection cannot leave a
-modifier stuck down on the desktop. `input.text` in `capabilities` states the
-characters the compiled layout can actually produce; anything else is refused
-with `text-unsupported` and the honest workaround is the explicit clipboard.
+modifier stuck down on the desktop. On Linux, `input.text` in `capabilities` states the characters the compiled
+layout can produce. macOS reports Unicode text support and currently maps
+`key.character` chords through a US ANSI virtual-key map; the reported keyboard
+layout is diagnostic, not proof that this map matches it. Anything outside the
+map is refused with `text-unsupported`.
+
+## Latest frame over the local protocol
+
+`session.frame` requires `view` permission. It writes the latest pre-encode frame as
+packed BGRX bytes to the caller's path, with optional `[x,y,w,h]` `region`.
+The directory must already exist and be private to the caller; pixels never
+travel through JSON. `seq` advances only when capture changes, `still_ms` is
+elapsed time since that capture, and `damage` bounds the changed 32-pixel
+tiles since `since` (full frame when the requested sequence is older than the
+previous capture). A request with the current sequence reports empty damage;
+omitting `path` requests metadata only (`written: false`). `after_seq` waits for
+`seq` to exceed that value; `still_ms` waits for that many milliseconds
+of stillness. When both are supplied, both conditions must hold.
+`timeout_ms` alone waits for 150 ms of stillness. The default deadline is 5 s;
+`timeout_ms` can extend it to at most 120 s. An unmet condition returns
+`frame-timeout`. Damage is grouped by connected 32-pixel tiles.
+Each changed capture emits a local `session.frame.changed` event with `sessionId`,
+`seq` and `damage`, allowing a co-located consumer to track animation across
+observations. Neither the event nor this file-writing method is forwarded by
+the remote WebSocket bridge.
+
+```json
+{"id":20,"method":"session.frame","params":{"session_id":"…","since":7,"path":"/run/user/1000/frame.raw"}}
+{"id":20,"result":{"seq":8,"still_ms":210,"width":1280,"height":720,"format":"bgrx","damage":[[32,32,32,32]],"written":true}}
+```
 
 ## Clipboard over the local protocol
 

package/engine/Cargo.lock

@@ -257,6 +257,15 @@ dependencies = [
  "generic-array",
 ]
 
+[[package]]
+name = "block2"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cdeb9d870516001442e364c5220d3574d2da8dc765554b4a617230d33fa58ef5"
+dependencies = [
+ "objc2",
+]
+
 [[package]]
 name = "bumpalo"
 version = "3.20.3"
@@ -508,16 +517,22 @@ checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
 
 [[package]]
 name = "desklink-host"
-version = "0.1.0"
+version = "0.1.1"
 dependencies = [
  "anyhow",
  "ashpd",
  "async-trait",
+ "block2",
  "bytes",
  "cc",
  "futures-util",
  "libc",
  "log",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-core-media",
+ "objc2-foundation",
+ "objc2-screen-capture-kit",
  "pipewire",
  "rand 0.8.8",
  "rtc",
@@ -541,6 +556,16 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "dispatch2"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e0e367e4e7da84520dedcac1901e4da967309406d1e51017ae1abfb97adbd38"
+dependencies = [
+ "bitflags 2.13.2",
+ "objc2",
+]
+
 [[package]]
 name = "displaydoc"
 version = "0.2.7"
@@ -1211,6 +1236,175 @@ dependencies = [
  "autocfg",
 ]
 
+[[package]]
+name = "objc2"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a12a8ed07aefc768292f076dc3ac8c48f3781c8f2d5851dd3d98950e8c5a89f"
+dependencies = [
+ "objc2-encode",
+]
+
+[[package]]
+name = "objc2-av-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "478ae33fcac9df0a18db8302387c666b8ef08a3e2d62b510ca4fc278a384b6c0"
+dependencies = [
+ "objc2",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-core-audio"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e1eebcea8b0dbff5f7c8504f3107c68fc061a3eb44932051c8cf8a68d969c3b2"
+dependencies = [
+ "dispatch2",
+ "objc2",
+ "objc2-core-audio-types",
+ "objc2-core-foundation",
+]
+
+[[package]]
+name = "objc2-core-audio-types"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a89f2ec274a0cf4a32642b2991e8b351a404d290da87bb6a9a9d8632490bd1c"
+dependencies = [
+ "bitflags 2.13.2",
+ "objc2",
+]
+
+[[package]]
+name = "objc2-core-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2",
+ "dispatch2",
+ "libc",
+ "objc2",
+]
+
+[[package]]
+name = "objc2-core-graphics"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e022c9d066895efa1345f8e33e584b9f958da2fd4cd116792e15e07e4720a807"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2",
+ "dispatch2",
+ "libc",
+ "objc2",
+ "objc2-core-foundation",
+ "objc2-io-surface",
+ "objc2-metal",
+]
+
+[[package]]
+name = "objc2-core-media"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05ec576860167a15dd9fce7fbee7512beb4e31f532159d3482d1f9c6caedf31d"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2",
+ "dispatch2",
+ "objc2",
+ "objc2-core-audio",
+ "objc2-core-audio-types",
+ "objc2-core-foundation",
+ "objc2-core-video",
+]
+
+[[package]]
+name = "objc2-core-video"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d425caf1df73233f29fd8a5c3e5edbc30d2d4307870f802d18f00d83dc5141a6"
+dependencies = [
+ "bitflags 2.13.2",
+ "objc2",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-io-surface",
+]
+
+[[package]]
+name = "objc2-encode"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef25abbcd74fb2609453eb695bd2f860d389e457f67dc17cafc8b8cbc89d0c33"
+
+[[package]]
+name = "objc2-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3e0adef53c21f888deb4fa59fc59f7eb17404926ee8a6f59f5df0fd7f9f3272"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2",
+ "libc",
+ "objc2",
+ "objc2-core-foundation",
+]
+
+[[package]]
+name = "objc2-io-surface"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "180788110936d59bab6bd83b6060ffdfffb3b922ba1396b312ae795e1de9d81d"
+dependencies = [
+ "bitflags 2.13.2",
+ "objc2",
+ "objc2-core-foundation",
+]
+
+[[package]]
+name = "objc2-metal"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a0125f776a10d00af4152d74616409f0d4a2053a6f57fa5b7d6aa2854ac04794"
+dependencies = [
+ "bitflags 2.13.2",
+ "objc2",
+ "objc2-foundation",
+]
+
+[[package]]
+name = "objc2-screen-capture-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "74b7c5390f477482f001bc354d6571a70db7e4f8d5288e860c45521fbce11394"
+dependencies = [
+ "bitflags 2.13.2",
+ "block2",
+ "dispatch2",
+ "libc",
+ "objc2",
+ "objc2-av-foundation",
+ "objc2-core-foundation",
+ "objc2-core-graphics",
+ "objc2-core-media",
+ "objc2-foundation",
+ "objc2-uniform-type-identifiers",
+]
+
+[[package]]
+name = "objc2-uniform-type-identifiers"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7902ac02859fc1f7045f8b598c63f1ae0cc7efeaa06a9bc9f3d9a3c955974fa4"
+dependencies = [
+ "objc2",
+ "objc2-foundation",
+]
+
 [[package]]
 name = "oid-registry"
 version = "0.7.1"

package/engine/Cargo.toml

@@ -1,7 +1,8 @@
 [package]
 name = "desklink-host"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2021"
+rust-version = "1.97.1"
 license = "Apache-2.0"
 description = "Per-user on-demand desktop capture, encode and input engine speaking a versioned local control protocol"
 publish = false
@@ -11,23 +12,42 @@ name = "desklink-host"
 path = "src/main.rs"
 
 [dependencies]
-anyhow = "1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+
+[target.'cfg(target_os = "linux")'.dependencies]
+anyhow = "1"
 tokio = { version = "1", features = ["rt-multi-thread", "macros", "io-util", "io-std", "sync", "time", "signal"] }
 futures-util = "0.3"
-ashpd = { version = "0.11", default-features = false, features = ["tokio"] }
-pipewire = { version = "0.10", features = ["v0_3_44"] }
 libc = "0.2"
 bytes = "1"
 webrtc = { version = "0.21", default-features = false, features = ["runtime-tokio", "crypto-ring"] }
 rtc = { version = "0.21", default-features = false, features = ["crypto-ring"] }
+log = "0.4"
+async-trait = "0.1"
+rand = "0.8"
+ashpd = { version = "0.11", default-features = false, features = ["tokio"] }
+pipewire = { version = "0.10", features = ["v0_3_44"] }
 xkbcommon = "0.8"
 x11rb = { version = "0.14", default-features = false, features = ["allow-unsafe-code", "xtest"] }
 wl-clipboard-rs = "0.9"
-log = "0.4"
+
+[target.'cfg(target_os = "macos")'.dependencies]
+anyhow = "1"
 async-trait = "0.1"
+bytes = "1"
+libc = "0.2"
+log = "0.4"
 rand = "0.8"
+rtc = { version = "0.21", default-features = false, features = ["crypto-ring"] }
+tokio = { version = "1", features = ["rt-multi-thread", "macros", "io-util", "io-std", "sync", "time", "signal"] }
+webrtc = { version = "0.21", default-features = false, features = ["runtime-tokio", "crypto-ring"] }
+objc2-screen-capture-kit = { version = "0.3.2", features = ["SCStream", "SCShareableContent", "SCError", "SCScreenshotManager", "block2", "dispatch2", "objc2-core-media", "objc2-core-graphics"] }
+objc2-foundation = { version = "0.3.2", features = ["NSArray", "NSError", "NSString"] }
+objc2-core-media = "0.3.2"
+objc2-core-foundation = "0.3.2"
+objc2-core-graphics = { version = "0.3.2", features = ["CGImage", "CGDataProvider"] }
+block2 = "0.6"
 
 [build-dependencies]
 cc = "1"

package/engine/build.rs

@@ -1,7 +1,8 @@
 //! Native dependencies of the engine.
 //!
-//! Two permissive C libraries, both built or linked from this machine's own
-//! sources — no prebuilt binary is fetched, and nothing is installed:
+//! The Linux build uses two permissive C libraries, both built or linked from
+//! this machine's own sources — no prebuilt binary is fetched, and nothing is
+//! installed:
 //!
 //! * libvpx (BSD-3-Clause) — VP9 encode, through `native/vpx_shim.c` so the
 //!   versioned encoder config struct is laid out by a C compiler.
@@ -9,9 +10,9 @@
 //!   over `uinput`/`libevdev`, built by its own CMake project into a static
 //!   library and called through its documented C API.
 //!
-//! Both are required to build the engine; the README lists the system packages
-//! they need. Whether input can actually be injected is a separate, runtime
-//! question the engine answers through its own `/dev/uinput` probe.
+//! macOS builds only the libvpx shim; ScreenCaptureKit, Quartz input and
+//! AppKit clipboard use native frameworks. Linux runtime input access is still
+//! checked through `/dev/uinput`.
 //!
 //! `DESKLINK_VPX_STATIC_DIR` names a libvpx install prefix (`include/`, `lib/`)
 //! to link statically instead. The prebuilt engine uses it, because libvpx's
@@ -21,40 +22,114 @@
 use std::path::{Path, PathBuf};
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
+    println!("cargo:rustc-check-cfg=cfg(desklink_vpx)");
+    println!("cargo:rustc-check-cfg=cfg(desklink_macos_cli)");
     println!("cargo:rerun-if-changed=native/vpx_shim.c");
     println!("cargo:rerun-if-changed=native/inputtino_shim.cpp");
+    println!("cargo:rerun-if-changed=native/mac_stream.mm");
+    println!("cargo:rerun-if-changed=native/agent_overlay_mac.m");
+    println!("cargo:rerun-if-changed=native/agent_overlay_x11.c");
+    println!("cargo:rerun-if-changed=native/agent_overlay_wayland.c");
+    println!("cargo:rerun-if-changed=Info.plist");
     println!("cargo:rerun-if-changed=vendor/inputtino/src/uinput/include/inputtino/keyboard.hpp");
     println!("cargo:rerun-if-changed=vendor/inputtino/include/inputtino/input.h");
     println!("cargo:rerun-if-changed=vendor/inputtino/CMakeLists.txt");
 
     println!("cargo:rerun-if-env-changed=DESKLINK_VPX_STATIC_DIR");
+    println!("cargo:rerun-if-env-changed=DESKLINK_MACOS_CLI");
 
-    let static_vpx = std::env::var_os("DESKLINK_VPX_STATIC_DIR").map(PathBuf::from);
-    let mut shim = cc::Build::new();
-    shim.file("native/vpx_shim.c")
-        .flag_if_supported("-Wno-unused-parameter");
-    if let Some(prefix) = &static_vpx {
-        shim.include(prefix.join("include"));
+    let target_os = std::env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
+    if let Some(prefix) = std::env::var_os("DESKLINK_VPX_STATIC_DIR").map(PathBuf::from) {
+        if !prefix.join("include/vpx/vp8cx.h").exists() || !prefix.join("lib/libvpx.a").exists() {
+            return Err(format!("DESKLINK_VPX_STATIC_DIR must be the libvpx install prefix containing include/vpx/vp8cx.h and lib/libvpx.a, not its lib directory: {}", prefix.display()).into());
+        }
+    }
+    if target_os == "macos" && std::env::var_os("DESKLINK_MACOS_CLI").is_some() {
+        println!("cargo:rustc-cfg=desklink_macos_cli");
+    }
+    if target_os == "linux" {
+        let static_vpx = std::env::var_os("DESKLINK_VPX_STATIC_DIR").map(PathBuf::from);
+        let mut shim = cc::Build::new();
+        shim.file("native/vpx_shim.c")
+            .flag_if_supported("-Wno-unused-parameter");
+        if let Some(prefix) = &static_vpx {
+            shim.include(prefix.join("include"));
+        }
+        shim.compile("dlvpx");
+        match &static_vpx {
+            Some(prefix) => {
+                println!(
+                    "cargo:rustc-link-search=native={}",
+                    prefix.join("lib").display()
+                );
+                println!("cargo:rustc-link-lib=static=vpx");
+            }
+            None => println!("cargo:rustc-link-lib=vpx"),
+        }
     }
-    shim.compile("dlvpx");
-    match &static_vpx {
-        Some(prefix) => {
+
+    if target_os == "linux" {
+        cc::Build::new()
+            .file("native/agent_overlay_x11.c")
+            .file("native/agent_overlay_wayland.c")
+            .compile("dlagentoverlay");
+        for lib in ["X11", "Xcursor", "wayland-client", "m"] {
+            println!("cargo:rustc-link-lib={lib}");
+        }
+        cc::Build::new()
+            .cpp(true)
+            .std("c++17")
+            .include("vendor/inputtino/src/uinput/include")
+            .file("native/inputtino_shim.cpp")
+            .compile("dlinputkey");
+        build_inputtino(&PathBuf::from(std::env::var("OUT_DIR")?))?;
+    } else if target_os == "macos" {
+        cc::Build::new()
+            .cpp(true)
+            .file("native/mac_stream.mm")
+            .flag("-fobjc-arc")
+            .compile("dlmacstream");
+        cc::Build::new()
+            .file("native/agent_overlay_mac.m")
+            .flag("-fobjc-arc")
+            .compile("dlagentoverlay");
+        for framework in [
+            "ScreenCaptureKit",
+            "CoreVideo",
+            "CoreMedia",
+            "Foundation",
+            "AppKit",
+            "QuartzCore",
+        ] {
+            println!("cargo:rustc-link-lib=framework={framework}");
+        }
+        if let Some(prefix) = std::env::var_os("DESKLINK_VPX_STATIC_DIR").map(PathBuf::from) {
+            cc::Build::new()
+                .file("native/vpx_shim.c")
+                .include(prefix.join("include"))
+                .compile("dlvpx");
             println!(
                 "cargo:rustc-link-search=native={}",
                 prefix.join("lib").display()
             );
             println!("cargo:rustc-link-lib=static=vpx");
+            println!("cargo:rustc-cfg=desklink_vpx");
+        }
+        println!("cargo:rustc-link-lib=framework=CoreGraphics");
+        println!("cargo:rustc-link-lib=framework=ApplicationServices");
+        println!("cargo:rustc-link-lib=framework=Carbon");
+        // The dev harness embeds its bundle identity for local TCC qualification.
+        // The published CLI must inherit the responsible app's TCC identity instead.
+        if std::env::var_os("DESKLINK_MACOS_CLI").is_none() {
+            println!("cargo:rustc-link-arg-bins=-sectcreate");
+            println!("cargo:rustc-link-arg-bins=__TEXT");
+            println!("cargo:rustc-link-arg-bins=__info_plist");
+            println!(
+                "cargo:rustc-link-arg-bins={}",
+                Path::new("Info.plist").canonicalize()?.display()
+            );
         }
-        None => println!("cargo:rustc-link-lib=vpx"),
     }
-
-    cc::Build::new()
-        .cpp(true)
-        .std("c++17")
-        .include("vendor/inputtino/src/uinput/include")
-        .file("native/inputtino_shim.cpp")
-        .compile("dlinputkey");
-    build_inputtino(&PathBuf::from(std::env::var("OUT_DIR")?))?;
     Ok(())
 }