@desklink/host 0.3.0 → 0.4.0

package/docs/PROTOCOL.md

@@ -5,10 +5,14 @@ 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 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.
+This document describes the Linux, macOS, and Windows engine protocol. The
+macOS engine uses the same v3 stdio/WebRTC session path, with native display
+capture, input and clipboard adapters. A Windows build with static libvpx
+(`DESKLINK_VPX_STATIC_DIR`) also serves consumer-fed H.264 encoded sources over
+the shared session path. Native desktop capture, input and clipboard are not
+implemented on Windows; optional agent feedback is unavailable there. Without static libvpx, the Windows compile seam
+reports encoding unavailable and refuses `serve`. The protocol contains no
+application concepts: no accounts, no chat, no machine ids, no pane ids.
 
 ## Starting the engine
 
@@ -77,7 +81,7 @@ arrives, every other request is refused the same way; `capabilities` and
 ## macOS
 
 For engine installation and the macOS resolution opt-out, see the
-[host installation guide](../README.md#macos).
+[host installation guide](../README.md#macos-preview).
 
 macOS speaks protocol 3 and shares the session lifecycle below. It captures the
 selected display with ScreenCaptureKit, encodes VP9 (and H.264 through
@@ -91,16 +95,16 @@ 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
+is needed. Input may request Accessibility consent; if it remains unavailable,
+the session still opens and input actions are refused 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
+macOS clipboard read/write is plain text and available to paired consumers.
+`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
@@ -121,6 +125,8 @@ session may require fresh consent. The macOS engine requires a VP9-enabled build
     "backends": ["portal-screencast+pipewire", "x11-root"],
     "formats": ["bgrx", "bgra", "rgbx", "rgba"],
     "cursor": "embedded",
+    "cursor_modes": ["embedded", "hidden"],
+    "cursor_positions": {"x11": true, "portal": "negotiated"},
     "audio": false
   },
   "encode": {"codecs": ["vp9", "h264"], "hardware": false,
@@ -144,7 +150,11 @@ appears in `codecs` when an H.264 encoder starts on this machine right now, and
 `encode.h264.encoder` names it: `videotoolbox` on macOS; on Linux `nvenc` or
 `vaapi` when the GPU has an H.264 encoder, else `openh264`, Cisco's prebuilt
 library. `encoder` is `null` when there is none. The answer to the offer picks
-between them (see *Codecs* below).
+between them (see *Codecs* below). Windows with static libvpx reports VP9 in
+`encode.codecs`, but has no native desktop capture; without static libvpx its
+`encode.codecs` is empty. On Windows, `encoded.codecs` reports H.264 only when
+static libvpx is linked, for consumer-fed sources; it does not mean the engine
+can encode H.264 itself.
 
 openh264 is never part of this package: the engine loads only Cisco's own
 binary, checked against its published SHA-256, from
@@ -175,12 +185,17 @@ desktop is visible here rather than silent. `capture.backends` lists what this
 build has, not what this machine can necessarily use.
 
 `input.unavailable_reason` and `input.grant` describe the portal/uinput path:
-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. On Linux the engine never asks for privileges on its own; macOS may
-request Screen Recording or Accessibility consent at `session.open`.
+without kernel input access a portal session opens and captures, but input
+messages are refused with `input-unavailable`. X display capture uses XTest
+instead and does not require that grant. The engine probes XTest on that named
+display; if it is unavailable, capture and clipboard still open, and input
+messages are refused with `input-unavailable`. X11 clipboard uses CLIPBOARD on the
+session's named display; the WebSocket bridge reports it independently of the
+engine's ambient Wayland clipboard probe. The engine's Linux `clipboard.read`
+reports the Wayland session environment; `clipboard.write` additionally requires
+`wl-copy`. A portal bridge preserves those flags even when Xwayland is reachable.
+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.
@@ -192,7 +207,6 @@ trigger a capture request.
   "source": {"kind":"portal"},          // or {"kind":"x11","display":":99"}
                                            // macOS: {"kind":"display","display_id":123}
                                            // or {"kind":"encoded","codec":"h264","width":486,"height":1080}
-  "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
   "max_fps": 60,
@@ -212,7 +226,7 @@ Result:
  "source":{"kind":"monitor","width":2560,"height":1440,"origin":{"x":0,"y":0}},
  "geometry":{"source":{"width":2560,"height":1440},
              "encoded":{"width":2560,"height":1440},
-             "origin":{"x":0,"y":0}}}
+             "origin":{"x":0,"y":0}},"agentIndicator":false}
 ```
 
 `source` selects the desktop. `portal` (or absent) asks the compositor for a
@@ -223,11 +237,12 @@ main display when omitted); `encoded` carries video the consumer encoded itself.
 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.
+There are no per-session permissions: whoever holds the channel is paired and
+gets all available view, input and clipboard access. The `permissions` field
+from 0.3 clients is accepted and ignored, including unknown scope names.
+Missing input or clipboard backends fail per action, not at open. The
+`permission` refusal code is reserved for 0.3 peers and is no longer emitted by
+this engine.
 
 `max_fps` defaults to 60 and is bounded to 1–60. It caps the encoded frame
 rate and X11 capture loop; portal capture offers it as the preferred PipeWire
@@ -235,14 +250,29 @@ 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
+sets it for sessions it drives (except Windows); human phone control omits it. On
+Linux it adds an eased arrow inside a halo that brightens on clicks and keys,
+animating in and out, with light and dark keylines so it reads on any content.
+On Wayland it uses a click-through layer-shell surface with an edge glow, drawn
+at the highest announced output integer scale, capped at 4; 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 the X11 grab 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.
+On bare X11 it is an override-redirect, click-through window that follows the
+pointer, so it stays
+visible over windows that set their own cursor and never replaces the cursor.
+Its size follows `Xft.dpi` from 96–384 DPI, defaulting to 1x otherwise;
+the shaped cue reveals outward from the tip and retracts inward, while a
+compositing manager with alpha enables fading instead. The helper announces each
+state before drawing it, and X11 capture restores just
+the pixels the cue covers from the previous frame, so the halo's interior stays
+live; changes under the arrow and ring show once the cue moves away. Click and
+key feedback only recolour the cue, so a still cue never changes what is
+restored. There is no edge glow on that path.
+macOS adds an eased arrow and halo, click ripple, and typing pulse in a
+nonactivating, click-through window excluded by the ScreenCaptureKit content
+filter. Closing the session animates out and removes the indicator.
+Indicator startup is best-effort on every platform; a missing helper or overlay
+backend does not refuse the session. The open result reports `agentIndicator:
+true` only when the helper started.
 
 `local_frames` keeps the latest pre-encode frame and its tile hashes for
 `session.frame` and `session.frame.changed` (see "Latest frame over the local
@@ -457,11 +487,113 @@ named beside it for the per-frame mean:
 frame within measurement noise; a stage that will not reconcile is a stage
 whose accounting is wrong.
 
+## Cursor-free capture
+
+`session.open` accepts `cursor: "hidden"` (default `"embedded"`). Existing
+callers keep their capture behavior. Linux hidden capture requires portal
+**Metadata** so cursor positions remain available while cursor pixels are
+omitted. A portal without Metadata returns the typed
+`cursor_positions_unavailable` refusal. Successful open returns
+`cursor: {"mode":"metadata"|"hidden"|"embedded"|"unavailable",
+"positions":true|false}`; `mode` names the portal mode accepted by the portal,
+not just the requested option.
+
+Linux capabilities advertise `capture.cursor_modes: ["embedded","hidden"]`
+and `capture.cursor_positions: {"x11":true,"portal":"negotiated"}`. Portal
+support is resolved at open: hidden capture requires Metadata and an observed
+SPA cursor metadata buffer. A portal that offers only Hidden refuses open with
+`cursor_positions_unavailable`; accepted hidden sessions report `positions:true`.
+Metadata-mode buffers that contain no new cursor data do not fabricate a move
+or a visibility change.
+
+Hidden sessions with positions emit local protocol events independently of
+pixel damage, including on a still X11 desktop:
+
+```json
+{"event":"session.cursor","params":{"sessionId":"…","x":400,"y":300,"visible":true,"timestamp_us":123456}}
+```
+
+`x,y` name the pointer hotspot in the selected source's coordinates
+(`geometry.source`), before video scaling, without the desktop origin added.
+Portal buffer coordinates are mapped to that geometry. `visible` is false
+outside the source or when SPA supplies an invisible cursor bitmap.
+`timestamp_us` is a monotonic engine-process clock in microseconds, sampled
+when the capture thread observes the pointer. The same clock stamps
+`session.frame.changed` and `session.frame` metadata, so local recording
+consumers can compare cursor samples to frame handoff times. These are not
+wall-clock or RTP timestamps. SPA cursor updates accompany PipeWire buffers;
+X11 pointer queries run at the session frame cap even with no pixel damage.
+Repeated identical positions/visibility are suppressed.
+
+X11 root GetImage/MIT-SHM never contains the server cursor and this engine
+never composites it, including for existing embedded-default callers. Its
+open reply therefore reports `mode:"hidden"`; positions are enabled only by
+an explicit `cursor:"hidden"`. macOS and Windows refuse hidden capture with
+`cursor-unavailable` in this build. Consumer-fed encoded sources refuse it too:
+the engine cannot remove pixels the consumer already encoded. Unknown cursor
+options are `malformed`.
+
+`@desklink/host` exposes `openSession({cursor:'hidden'})`
+and typed `session.cursor` events through `onEvent`/`drainEvents`. The client
+capture request also accepts `cursor`, and AXI accepts `start --cursor hidden`.
+
+## Point on the host desktop
+
+A local consumer can guide the person without taking control of their pointer
+or keyboard. `session.point` requires an open session and is independent
+of `agent_indicator`. It draws one blue ring centered at `x,y`, with an optional
+label. A new point replaces the previous one and restarts its timer.
+
+```jsonc
+{"id":30,"method":"session.point","params":{"session_id":"…","x":400,"y":300,"label":"Here","timeout_ms":3000}}
+{"id":30,"result":{"shown":true}}
+{"id":31,"method":"session.point","params":{"session_id":"…","clear":true}}
+{"id":31,"result":{"shown":false}}
+```
+
+Coordinates are integers in the **selected desktop's original pixels**, top-left
+origin, before video scaling (`geometry.source`, not `geometry.encoded`). On X11
+this is the root screen; on macOS it is the selected display, with native pixels
+converted to display points. Both coordinates must be within its bounds. The
+ring may clip at an edge; its label stays inside the display. `timeout_ms`
+defaults to 3000 and must be an integer from 1 to 120000. Labels are at most 96
+printable ASCII bytes, including spaces; other labels are refused rather than
+rendered incorrectly by the X server's core font. A clear request has no
+coordinates, label or timeout, and is idempotent. Invalid requests do not alter
+an existing marker. Replies acknowledge submission to the local overlay helper,
+not that a person has seen it. Timeout hides it; clear, session replacement,
+lease expiry, close and consumer disconnection remove and reap the helper.
+
+X11 uses an override-redirect, shaped window with an empty input shape. It never
+warps the pointer, changes the cursor, requests focus or injects events. macOS
+reuses the nonactivating, mouse-transparent indicator window in a separate
+helper. **Point cues intentionally appear in local frames and outgoing video**:
+the person and observer can see the same cue. They are separate from the
+capture-excluded input activity indicator. Consumers reading frame differences
+should allow for the point's appearance/disappearance.
+
+Wayland portal sessions use a wlr-layer-shell overlay with no keyboard
+interactivity and an empty input region. The selected monitor is matched by its
+portal origin against compositor logical output geometry (xdg-output); with one
+output, no origin is needed. Points map from the selected source to that output.
+An ambiguous or missing selected output returns `indicator-unavailable`.
+Compositors without layer-shell return `point_unsupported` with reason
+`layer_shell_unavailable` (including GNOME Mutter). Consumer-fed encoded sources return `operation`
+because they have no host desktop overlay target. Other refusals are `session`,
+`coordinates`, `malformed`, and `indicator-unavailable` (including unavailable
+X Shape support). Unknown fields are refused. No control-channel or remote
+bridge forwarding is added; the consumer chooses when to request a local cue.
+
+`@desklink/host` exposes `EngineClient.point(sessionId, {x, y, label?, timeoutMs?})`
+and `EngineClient.point(sessionId, {clear: true})`. `@desklink/axi` exposes
+`desklink-axi point 400,300 --label "Here" --timeout 3000` and
+`desklink-axi point --clear`.
+
 ## Input and clipboard: the session's control channel
 
 Input does **not** travel the local protocol. It rides the WebRTC data channel
 the engine creates for the session, which is inside the DTLS/SRTP session that
-was opened for one authorized grant: it inherits that session's identity and dies
+was opened by a paired consumer: it inherits that session's identity and dies
 with it, so a client that kept a socket open cannot keep driving a session that
 was revoked, and the consumer's request path never carries a pointer move.
 
@@ -498,12 +630,12 @@ The engine answers on the same channel, and sends two things unprompted:
 {"kind":"revoked","reason":"…","code":"closed"}  // closed, or a session.revoked code
 ```
 
-Refusal codes: `permission`, `session`, `input-replay`, `coordinates`,
-`text-too-large`, `text-unsupported`, `input-unavailable`, `operation`.
+Refusal codes: `session`, `input-replay`, `coordinates`, `text-too-large`,
+`text-unsupported`, `input-unavailable`, `clipboard-unsupported`, `operation`.
 
 `seq` is monotonic per session. A repeat or a lower value is refused with
 `input-replay` and **no side effect**, so a replayed message cannot move the
-pointer twice. Validation, permission and ordering checks all run before any
+pointer twice. Validation and ordering checks all run before any
 physical effect.
 
 The engine holds its own pressed-key/button state. `close`, `release_all`,
@@ -534,8 +666,7 @@ WebRTC, congestion and teardown logic that is already proven on this path.
 it is the only party that knows them (`1..7680` by `1..4320`). Nothing is scaled:
 `geometry.source` and `geometry.encoded` are both that size, the client aims at
 those pixels, and the consumer maps them to its device. `max_width`/
-`max_height`/`bitrate_kbps` are ignored for this source, and `permissions` works
-as it does anywhere else — with one difference: `control` needs no local input
+`max_height`/`bitrate_kbps` are ignored for this source. Input needs no local
 backend, because nothing is applied locally.
 
 `session.open` returns before any offer exists. The offer must name the profile
@@ -606,7 +737,7 @@ pixels, exactly as a client sends them.
 ```
 
 The event carries the control message as it arrived. The engine still validates
-permission, ordering and replay before forwarding, so the client keeps the same
+ordering and replay before forwarding, so the client keeps the same
 `ack`/`rejected` behaviour and a replayed gesture still cannot be delivered
 twice. `ack` means "accepted for this session", not "applied to a desktop" —
 `session.metrics.input_forwarded` counts what was handed on, and `input_applied`
@@ -625,7 +756,7 @@ because packetization is the only stage the engine itself runs.
 
 ## Latest frame over the local protocol
 
-`session.frame` requires `view` permission. It writes the latest pre-encode frame as
+`session.frame` 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
@@ -662,9 +793,17 @@ instead; both reach the same clipboard:
 {"id":10,"result":{"written":true}}
 ```
 
-Refused with `error.code = "clipboard"` when the session lacks `clipboard`, or
-when the desktop's clipboard has no text. A read is bounded by
-`capabilities.clipboard.maxBytes`; when the desktop's text is longer, `truncated`
+Refused with `error.code = "clipboard"` when the desktop has no text or a
+clipboard operation fails. Encoded sources have no desktop clipboard; their
+control channel answers with an empty clipboard reply and an explanatory error.
+X11 uses a fresh connection to the session's selected display for each operation.
+Writes verify CLIPBOARD ownership before succeeding and serve TARGETS,
+UTF8_STRING and TEXT; reads request UTF8_STRING. Writes are limited to 256 KiB
+and the server's single request limit; the text lives until another client takes ownership, the engine
+exits, or the display dies. Reads wait at most 2.5 seconds for the owner.
+INCR transfers are refused explicitly as unsupported, not reported as success;
+STRING, PRIMARY and persistence after engine exit are not implemented.
+A read is bounded by `capabilities.clipboard.maxBytes`; when the desktop's text is longer, `truncated`
 is true and the text is cut on a character boundary, so the returned text is
 still valid.
 
@@ -740,8 +879,9 @@ anything to show.
 
 ## What the engine deliberately does not do
 
-- It does not decide *who* the user is. It trusts the consumer's local
-  permission decision and enforces the resulting scope; there is no second
+- It does not decide *who* the user is. Whoever holds stdio (or an authenticated
+  bridge socket) is paired; pairing, identity and revocation are the consumer's.
+  Revocation must end both live sessions and future access. There is no second
   account, token or pairing ceremony. For consumer integration, see the
   [BYOKit guidance](../../../README.md#why-desklink-exists).
 - It does not open ports, register a service, install udev rules, join groups or

package/engine/Cargo.lock

@@ -536,7 +536,7 @@ checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
 
 [[package]]
 name = "desklink-host"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -546,7 +546,6 @@ dependencies = [
  "bytes",
  "bzip2-rs",
  "cc",
- "futures-util",
  "libc",
  "log",
  "objc2-core-foundation",
@@ -565,6 +564,7 @@ dependencies = [
  "wayland-client",
  "wayland-protocols",
  "webrtc",
+ "windows-sys 0.61.2",
  "wl-clipboard-rs",
  "x11rb",
  "xkbcommon",

package/engine/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "desklink-host"
-version = "0.3.0"
+version = "0.4.0"
 edition = "2021"
 rust-version = "1.97.1"
 license = "Apache-2.0"
@@ -16,10 +16,9 @@ serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 base64 = "0.22"
 
-[target.'cfg(target_os = "linux")'.dependencies]
+[target.'cfg(any(target_os = "linux", target_os = "macos", target_os = "windows"))'.dependencies]
 anyhow = "1"
 tokio = { version = "1", features = ["rt-multi-thread", "macros", "io-util", "io-std", "sync", "time", "signal"] }
-futures-util = "0.3"
 libc = "0.2"
 bytes = "1"
 webrtc = { version = "0.21", default-features = false, features = ["runtime-tokio", "crypto-ring"] }
@@ -27,6 +26,8 @@ rtc = { version = "0.21", default-features = false, features = ["crypto-ring"] }
 log = "0.4"
 async-trait = "0.1"
 rand = "0.8"
+
+[target.'cfg(target_os = "linux")'.dependencies]
 ashpd = { version = "0.11", default-features = false, features = ["tokio"] }
 pipewire = { version = "0.10", features = ["v0_3_44"] }
 xkbcommon = "0.8"
@@ -43,16 +44,10 @@ bzip2-rs = "0.1.2"
 wayland-client = "0.31"
 wayland-protocols = { version = "0.32", features = ["client"] }
 
+[target.'cfg(target_os = "windows")'.dependencies]
+windows-sys = "0.61.2"
+
 [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"

package/engine/build.rs

@@ -1,8 +1,8 @@
 //! Native dependencies of the engine.
 //!
-//! The Linux build uses two permissive C libraries, both built or linked from
-//! this machine's own sources — no prebuilt binary is fetched at build time, and
-//! nothing is installed:
+//! The Linux build compiles its native adapters from local sources and links
+//! system libraries for desktop overlays — no prebuilt binary is fetched at
+//! build time, 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.
@@ -38,6 +38,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     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_indicator.h");
     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");
@@ -48,6 +49,44 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     println!("cargo:rerun-if-env-changed=DESKLINK_MACOS_CLI");
 
     let target_os = std::env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
+    if target_os == "windows" {
+        if let Some(prefix) = std::env::var_os("DESKLINK_VPX_STATIC_DIR").map(PathBuf::from) {
+            if std::env::var("CARGO_CFG_TARGET_ENV")? != "msvc"
+                || std::env::var("CARGO_CFG_TARGET_ARCH")? != "x86_64"
+            {
+                return Err("Windows libvpx requires x86_64-pc-windows-msvc".into());
+            }
+            if !std::env::var("CARGO_CFG_TARGET_FEATURE")?
+                .split(',')
+                .any(|f| f == "crt-static")
+            {
+                return Err(
+                    "Windows static libvpx requires RUSTFLAGS=-Ctarget-feature=+crt-static (/MT)"
+                        .into(),
+                );
+            }
+            if !prefix.join("include/vpx/vp8cx.h").is_file()
+                || !prefix.join("lib/vpx.lib").is_file()
+            {
+                return Err(
+                    "DESKLINK_VPX_STATIC_DIR must contain include/vpx/vp8cx.h and lib/vpx.lib"
+                        .into(),
+                );
+            }
+            cc::Build::new()
+                .file("native/vpx_shim.c")
+                .include(prefix.join("include"))
+                .static_crt(true)
+                .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");
+        }
+        return Ok(());
+    }
     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());
@@ -90,11 +129,29 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
             .include("vendor/libva")
             .compile("dlvaapi");
         println!("cargo:rustc-link-lib=dl");
-        cc::Build::new()
+        let mut overlay = cc::Build::new();
+        let includes = std::process::Command::new("pkg-config")
+            .args(["--cflags", "freetype2", "fontconfig"])
+            .output()?;
+        if !includes.status.success() {
+            return Err("FreeType and Fontconfig development headers are required".into());
+        }
+        for flag in String::from_utf8(includes.stdout)?.split_whitespace() {
+            overlay.flag(flag);
+        }
+        overlay
             .file("native/agent_overlay_x11.c")
             .file("native/agent_overlay_wayland.c")
             .compile("dlagentoverlay");
-        for lib in ["X11", "Xcursor", "wayland-client", "m"] {
+        for lib in [
+            "X11",
+            "Xext",
+            "Xcursor",
+            "wayland-client",
+            "fontconfig",
+            "freetype",
+            "m",
+        ] {
             println!("cargo:rustc-link-lib={lib}");
         }
         cc::Build::new()

package/engine/native/agent_indicator.h

@@ -0,0 +1,57 @@
+// Shared Linux agent cue, in logical pixels. The arrow follows the Mac outline;
+// light and dark keylines keep it visible on both bright and dark desktops.
+#ifndef DESKLINK_AGENT_INDICATOR_H
+#define DESKLINK_AGENT_INDICATOR_H
+#include <math.h>
+#include <stdint.h>
+
+static double indicator_segment(double x, double y, double ax, double ay, double bx, double by) {
+    double dx=bx-ax, dy=by-ay;
+    double t=fmax(0,fmin(1,((x-ax)*dx+(y-ay)*dy)/(dx*dx+dy*dy)));
+    return hypot(x-ax-t*dx,y-ay-t*dy);
+}
+static uint32_t indicator_over(uint32_t dst, double coverage, unsigned rgb) {
+    unsigned a=(unsigned)(255*fmax(0,fmin(1,coverage))), inverse=255-a;
+    unsigned da=dst>>24, r=(dst>>16)&255, g=(dst>>8)&255, b=dst&255;
+    return ((a+da*inverse/255)<<24) |
+        ((((rgb>>16)&255)*a/255+r*inverse/255)<<16) |
+        ((((rgb>>8)&255)*a/255+g*inverse/255)<<8) |
+        ((rgb&255)*a/255+b*inverse/255);
+}
+// Recolour without changing coverage, so feedback on a still cue never
+// changes which pixels capture has to restore.
+static uint32_t indicator_tint(uint32_t c, double amount, unsigned rgb) {
+    double keep=1-fmax(0,fmin(1,amount)), a=(c>>24)/255.0;
+    return (c&0xff000000) |
+        ((unsigned)(((c>>16)&255)*keep+((rgb>>16)&255)*a*(1-keep))<<16) |
+        ((unsigned)(((c>>8)&255)*keep+((rgb>>8)&255)*a*(1-keep))<<8) |
+        (unsigned)((c&255)*keep+(rgb&255)*a*(1-keep));
+}
+static uint32_t indicator_pixel(double x, double y, double opacity, double click, double typed) {
+    double radius=hypot(x,y);
+    uint32_t color=0;
+    // 62 logical px halo: a blue band, wide white keyline and dark rim, so the
+    // ring keeps >=2px of contrast after a 2:1 downscale. Inside the band only
+    // the arrow is opaque, so capture can keep the click area live.
+    color=indicator_over(color,fmax(0,fmin(1,2.5-fabs(radius-28.5)))*opacity,0x123047);
+    color=indicator_over(color,fmax(0,fmin(1,2.5-fabs(radius-24)))*opacity,0xffffff);
+    color=indicator_over(color,fmax(0,fmin(1,1.5-fabs(radius-20)))*0.95*opacity,0x2999ff);
+    static const double arrow[][2]={{0,0},{2,24},{8,18},{15,31},{21,28},{14,15},{24,14}};
+    double distance=1000; int inside=0;
+    for(int i=0,j=6;i<7;j=i++) {
+        double ax=arrow[j][0],ay=arrow[j][1],bx=arrow[i][0],by=arrow[i][1];
+        distance=fmin(distance,indicator_segment(x,y,ax,ay,bx,by));
+        if((ay>y)!=(by>y) && x<(bx-ax)*(y-ay)/(by-ay)+ax)inside=!inside;
+    }
+    double signed_distance=inside?-distance:distance;
+    color=indicator_over(color,fmax(0,fmin(1,3-signed_distance))*opacity,0x123047);
+    color=indicator_over(color,fmax(0,fmin(1,2-signed_distance))*opacity,0xffffff);
+    color=indicator_over(color,fmax(0,fmin(1,-signed_distance))*opacity,0x2999ff);
+    // A click sweeps a bright wave out through the cue; a key flashes it.
+    if(click>=0 && click<1)
+        color=indicator_tint(color,fmax(0,1-fabs(radius-(4+32*click))/5)*0.9*(1-click),0x9fdcff);
+    if(typed>=0 && typed<1)
+        color=indicator_tint(color,0.6*(1-typed),0xc8ecff);
+    return color;
+}
+#endif