@desklink/host 0.2.0 → 0.3.0

package/dist/resolveEngine.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolveEngine.js","sourceRoot":"","sources":["../src/resolveEngine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolveEngine.js","sourceRoot":"","sources":["../src/resolveEngine.ts"],"names":[],"mappings":"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"}

package/docs/BOUNDARY.md

@@ -20,8 +20,9 @@ apply authenticated input to the same desktop".
 - In: `session.open`, SDP/ICE, scoped WebRTC control-channel input, explicit
   clipboard read/write, close — and `session.feed`, which supplies the access
   units of a consumer-encoded `encoded` source. See `docs/PROTOCOL.md`.
-- Out: one video track — VP9 the engine encodes from a captured desktop, or
-  H.264 it only packetizes for a consumer-fed `encoded` source, whose control
+- Out: one video track — VP9 or H.264 (the receiver's answer picks) the engine
+  encodes from a captured desktop, or H.264 it only packetizes for a
+  consumer-fed `encoded` source, whose control
   messages are forwarded to the consumer instead of applied — and session
   notifications. Metrics are a request, not an event; the wire contract is in
   `docs/PROTOCOL.md`.
@@ -31,6 +32,9 @@ apply authenticated input to the same desktop".
 - Never: decides identity, installs rules, grants capabilities, carries audio,
   arbitrates two controllers, remembers a session across a restart.
 
+For prebuilt platform support and macOS installation, see the
+[host installation guide](../README.md#install-and-run).
+
 The public surface carries no consumer concepts. A machine id, a chat, a pane or
 an account never appears in the protocol or in the engine's state.
 
@@ -47,8 +51,10 @@ local gestures into that session's input".
 - `session.showKeyboard()/hideKeyboard()`,
   `session.copyRemoteToLocal()/pasteLocalToRemote()` are the control primitives
   the app mounts wherever it wants.
-- Native side owns the video decoder factory selection (hardware VP9 rather
-  than the underlying wrapper's software default), the renderer and the IME/text
+- Native side owns the video decoder factory selection (on Android, hardware
+  VP9 rather than the underlying wrapper's software default; on iOS, whose
+  WebRTC decodes VP9 only in software, the receiver asks for H.264, which it
+  decodes in hardware), the renderer and the IME/text
   connection. For input enablement and release on background/unmount, see the
   [client contract](../../desktop-client/README.md#what-the-package-guarantees).
 - The app supplies `authorize()` (a short-lived, engine-scoped capability plus
@@ -73,10 +79,9 @@ local gestures into that session's input".
 
 ## Reused, not rebuilt `[decided]`
 
-| Need | Already in this repository |
+| Need | Integration owner or consumer reference |
 |---|---|
-| Encrypted mobile → host request path, identity, grants | `packages/contract` control plane + `apps/host/src/requests` |
-| Relay stream channel (host joins as machine, client as client) | `packages/contract` `wsTickets` / preview channel pattern |
+| Authenticated request channel, identity, pairing, relay and reachable addresses | The consuming app's kits; see the [BYOKit integration guidance](../../../README.md#why-desklink-exists) |
 | A reference for a "live surface inside a conversation" | `apps/mobile/sources/desktop` |
 | Flow-test style for the packages | `apps/mobile/sources/catalog/application/sessionSync.integration.spec.ts` |
 
@@ -88,6 +93,9 @@ local gestures into that session's input".
 | Portal ScreenCast + PipeWire fd | `ashpd` (zbus) | MIT |
 | PipeWire stream client | `pipewire` | MIT |
 | VP9 encode | libvpx | BSD-3-Clause |
+| H.264 encode (macOS) | VideoToolbox (system framework) | Apple SDK |
+| H.264 encode (Linux GPU) | NVENC, VA-API — loaded at runtime from the driver | NVIDIA driver / libva MIT |
+| H.264 encode (Linux, no GPU encoder) | Cisco's prebuilt openh264, downloaded at runtime, never built or shipped | BSD-2-Clause (Cisco's binary licence) |
 | Virtual mouse/keyboard | inputtino (uinput/libevdev) | MIT |
 | Clipboard read/write | `wl-clipboard-rs` | MIT |
 | Keyboard layout mapping | `xkbcommon` | MIT |

package/docs/PROTOCOL.md

@@ -66,7 +66,7 @@ Request parameters use the engine's own snake_case names (`session_id`,
 Result:
 
 ```jsonc
-{"protocol":3,"engine":"desklink-host/0.2.0","platform":"linux", /* the rest of Capabilities */ }
+{"protocol":3,"engine":"desklink-host/0.3.0","platform":"linux", /* the rest of Capabilities */ }
 ```
 
 The consumer must send `hello` first, and a version the engine does not speak is
@@ -76,8 +76,12 @@ 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).
+
 macOS speaks protocol 3 and shares the session lifecycle below. It captures the
-selected display with ScreenCaptureKit, encodes VP9, and uses the same WebRTC
+selected display with ScreenCaptureKit, encodes VP9 (and H.264 through
+VideoToolbox, for a receiver that asks for it), 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.
@@ -108,7 +112,7 @@ session may require fresh consent. The macOS engine requires a VP9-enabled build
 ```jsonc
 {
   "protocol": 3,
-  "engine": "desklink-host/0.2.0",
+  "engine": "desklink-host/0.3.0",
   "platform": "linux",
   "session": {"kind": "wayland"},
   "x11": {"available": true, "size": [2560, 1440]},
@@ -119,7 +123,8 @@ session may require fresh consent. The macOS engine requires a VP9-enabled build
     "cursor": "embedded",
     "audio": false
   },
-  "encode": {"codecs": ["vp9"], "hardware": false},
+  "encode": {"codecs": ["vp9", "h264"], "hardware": false,
+             "h264": {"encoder": "vaapi", "hardware": true}},
   "input": {
     "mechanism": "inputtino/uinput",
     "pointer": true, "wheel": true, "keyboard": true,
@@ -133,6 +138,28 @@ session may require fresh consent. The macOS engine requires a VP9-enabled build
 }
 ```
 
+`encode` describes what the engine codes from a captured desktop. VP9 (libvpx,
+software; `hardware` describes it) is always there and is the default. `h264`
+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).
+
+openh264 is never part of this package: the engine loads only Cisco's own
+binary, checked against its published SHA-256, from
+`$XDG_CACHE_HOME/desklink/openh264/` (else `~/.cache/desklink/openh264/`). When a
+Linux machine has no hardware H.264 encoder and the library is not there yet,
+the first captured `session.open` downloads it from Cisco
+(`ciscobinary.openh264.org`) before making its offer; that session is offered
+VP9 alone if the download fails. `capabilities` itself never downloads.
+`DESKLINK_OPENH264=off` in the engine's environment disables openh264 (no
+download, no load); `DESKLINK_OPENH264=<path>` loads that file instead, still
+only if its hash is Cisco's. `DESKLINK_H264_ENCODER=<name>` restricts the engine
+to one H.264 encoder (`off` for none), for measuring one backend. Cisco's
+licence asks that this be stated: OpenH264 Video Codec provided by Cisco
+Systems, Inc.
+
 `encoded` lists the codecs this build will carry when the consumer supplies the
 video itself (see *Encoded sources*): a consumer reads it rather than inferring
 support from the engine's version string.
@@ -168,12 +195,13 @@ trigger a capture request.
   "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": 30,
+  "max_fps": 60,
   "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
-  "agent_indicator": false             // local input feedback; default false (phone control)
+  "agent_indicator": false,            // local input feedback; default false (phone control)
+  "local_frames": true                 // keep frames for session.frame; default true
 }}
 ```
 
@@ -201,7 +229,7 @@ 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
+`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
 frame rate, and macOS sets its ScreenCaptureKit stream minimum frame interval.
 A source may still supply fewer frames.
@@ -211,11 +239,19 @@ 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:
+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.
 
+`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
+protocol"). A consumer that only streams sets it to `false`: each captured
+frame is then converted once, for the encoder, no frame is kept, no
+`session.frame.changed` is emitted, and `session.frame` is refused with
+`error.code = "operation"`. The WebSocket bridge sets it to `false` unless its
+host listens to engine events, because neither travels past the socket.
+
 `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.
 
@@ -243,6 +279,36 @@ the SDP and candidates to the client and brings back the answer.
 
 A candidate that arrives before the remote description is buffered, not dropped.
 
+#### Codecs
+
+For a captured desktop the offer's video section lists VP9 (payload type 98)
+and, when `capabilities.encode.codecs` has `h264` and the encoded surface is
+within H.264 level 5.2 (at most 36864 16x16 macroblocks, e.g. 4096x2304 — a
+5K surface is offered VP9 alone), H.264 after it (payload type
+102, `packetization-mode=1`, Constrained Baseline, `profile-level-id=42e034`
+with `level-asymmetry-allowed=1`). The engine codes whichever of the two the
+answer lists first. A receiver that applies the offer as it comes answers in
+the offer's order and gets VP9, as before; a receiver that wants H.264 puts it
+first — with `setCodecPreferences` before `createAnswer`, or by moving its
+payload type to the front of the offer's `m=video` line before applying it.
+The iOS receiver in `@desklink/client` does the latter, because iOS decodes
+H.264 in hardware and VP9 in software; the web and Android receivers keep VP9.
+The choice is made by the first answer and kept for the session, ICE restarts
+included; the encoder starts after that answer, so the first frame sent is
+already in the chosen codec. H.264 is coded at the full encoded size throughout
+(no half-size motion), with an IDR carrying its SPS and PPS only for the first
+frame and on a receiver's request. An `encoded` source offers H.264 alone, as
+described under *Encoded sources*.
+
+The offer negotiates the `playout-delay` RTP header extension
+(`http://www.webrtc.org/experiments/rtp-hdrext/playout-delay`), and every video
+packet asks for a playout delay of 0: a receiver that honours it shows each
+frame when it is decoded instead of buffering frames to smooth playback. A
+receiver may decline the extension in its answer; its packets then carry no
+playout delay and it buffers as usual. The iOS receiver in
+`@desklink/react-native` declines it, because `RTCView` draws a frame only when
+its timestamp is new and zero-delay frames all carry the same one.
+
 A client whose ICE connection goes `disconnected` may restart ICE on the same
 peer connection instead of opening a new session: it sends
 `session.restart_ice` with the session's id and generation, and the engine
@@ -278,8 +344,9 @@ always does.
 
 `disconnected` is ICE losing the path: the picture is frozen but the session
 is alive, and a client should show reconnecting and may restart ICE (above)
-rather than open a new session. `failed` is terminal: the engine revokes and
-closes the session, and only a new `session.open` recovers it.
+rather than open a new session. `failed` is terminal: the engine revokes the
+session with code `transport` and closes it, and only a new `session.open`
+recovers it.
 
 While its control channel is open the engine also sends a heartbeat twice a
 second, `{"kind":"ping"}`. It lets a client notice a stalled path within
@@ -310,10 +377,26 @@ picker; restoration is silent only where the backend supports it. Cancellation
 is an error, not a reason to retry or bypass consent.
 
 ```jsonc
-{"event":"session.revoked","params":{"sessionId":"…","reason":"…"}}
+{"event":"session.revoked","params":{"sessionId":"…","reason":"…",
+  "code":"transport"}}                // transport|lease|error
 ```
 
 The session ended on the engine's side; there is nothing further to drain.
+`reason` is prose for people; `code` is what a client acts on:
+
+| `code` | Meaning | A client should |
+|---|---|---|
+| `transport` | The path to the client's peer was lost (ICE `failed`, or the track refused a frame) | open a new session with fresh authority; the desktop is still available |
+| `lease` | The session's `ttl_seconds` ran out | end; the grant is spent |
+| `error` | The engine could not keep serving it, such as an encoder refusing a frame | end and report |
+
+A session the consumer closes or replaces (`session.close`, a new
+`session.open`, the consumer leaving) sends no `session.revoked`: the consumer
+asked for it, and signaling sees `session.state` with `capture` `ended`. Only
+its control channel is told, with code `closed` (below).
+
+A code a client does not know is terminal. Engines before this field sent no
+`code`; treat its absence as terminal too.
 
 Metrics are a request, not a notification:
 
@@ -323,17 +406,56 @@ Metrics are a request, not a notification:
 
 ```jsonc
 {"id":7,"result":{"captured_frames":812,"dropped_frames":3,"encoded_frames":809,
-  "encoded_bytes":12345678,"key_frames":1,"refined_frames":37,
+  "encoded_bytes":12345678,"key_frames":1,"refined_frames":37,"halved_frames":0,"motion_frames":770,
   "encode_micros":7390000,"target_kbps":16430,"input_applied":44,"input_rejected":0,
-  "fed_frames":0,"input_forwarded":0}}
+  "fed_frames":0,"input_forwarded":0,"codec":"vp9","encoder":"libvpx",
+  "capture_micros":14100000,"convert_micros":3200000,
+  "queue_micros":410000,"send_micros":180000}}
 ```
 
 `dropped_frames` counts frames superseded by a newer one before they were coded;
-the newest frame is always coded. `refined_frames` counts refinement passes: a
+the newest frame is always coded. That includes frames that arrived while a
+large one (a key frame, a refinement) was still crossing the link: the stream
+runs at most about 60 ms of its rate target ahead of it, so frames never queue
+behind a burst. `refined_frames` counts refinement passes: a
 desktop that stops changing is coded once more at a fine quantizer, so it reads
-sharp. Key frames are sent only for the first frame and when the receiver asks
-(RTCP PLI or FIR). `target_kbps` is the current rate target after any back-off
-for loss the receiver reported.
+sharp. `halved_frames` counts motion frames coded at half width and height: when
+full-size frames that change much of the picture take longer to code than a
+frame interval while a newer frame is already waiting, several frames in a row,
+motion is coded at half size until the desktop stops or its changes shrink to
+small ones that code in time; the refinement pass is always full size. Key
+frames are sent only for the first frame, when the receiver asks (RTCP PLI or
+FIR), and when the coded size changes that way, so a receiver never has to scale
+references across a size change. `target_kbps` is the current rate target after
+any back-off: for a standing queue on the path, measured from the receiver's
+transport-wide congestion feedback (RTP `transport-cc`), and for the loss
+its receiver reports carry. `codec` is what frames go out in
+(`vp9` or `h264`) and `encoder` what codes them (`libvpx`, `videotoolbox`,
+`nvenc`, `vaapi` or `openh264`); both are empty for an encoded source.
+
+Per-stage timings (the L0 lab harness reads these, and every later lane cites
+them). Each is a cumulative microsecond counter; divide by the frame count
+named beside it for the per-frame mean:
+
+- `capture_micros` / `captured_frames`: grabbing a frame and converting it on
+  the capture thread (on X11: an MIT-SHM grab, falling back to socket
+  `GetImage` where the server lacks MIT-SHM, plus the downscale to I420), over
+  forwarded (changed) frames only — unchanged polls are excluded.
+- `convert_micros` / `captured_frames`: tile hashing and damage computation on
+  the capture thread, after the grab; the hash branch runs only with
+  `local_frames` on.
+- `queue_micros` / `motion_frames`: how long a freshly captured frame waited
+  between the capture handoff and the start of its encode. Refinement,
+  keepalive and receiver-requested re-encodes re-code a picture that was
+  already sent; they queue nothing and stay out of this mean.
+- `send_micros` / `encoded_frames`: packetizing a frame and handing it to the
+  transport.
+- `encode_micros` / `encoded_frames`: the encoder alone.
+
+`capture + convert` per captured frame plus `queue` per motion-coded frame and
+`encode + send` per encoded frame reconciles against engine-side wall time per
+frame within measurement noise; a stage that will not reconcile is a stage
+whose accounting is wrong.
 
 ## Input and clipboard: the session's control channel
 
@@ -373,7 +495,7 @@ The engine answers on the same channel, and sends two things unprompted:
 {"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
-{"kind":"revoked","reason":"…"}
+{"kind":"revoked","reason":"…","code":"closed"}  // closed, or a session.revoked code
 ```
 
 Refusal codes: `permission`, `session`, `input-replay`, `coordinates`,
@@ -494,9 +616,12 @@ is the consumer's to carry.
 
 `session.frame` and `session.wait_frame` are refused with `error.code =
 "operation"` — there is no lossless frame to read — and `captured_frames`,
-`refined_frames` and `target_kbps` stay at zero while `fed_frames` counts what
-the consumer handed over and `encoded_frames`, `encoded_bytes`, `key_frames`
-and `encode_micros` describe what was packetized and sent.
+`refined_frames`, `halved_frames`, `motion_frames`, `target_kbps`, `capture_micros`,
+`convert_micros`, `queue_micros` and `send_micros` stay at zero while
+`fed_frames` counts what the consumer handed over and `encoded_frames`,
+`encoded_bytes`, `key_frames` and `encode_micros` describe what was packetized
+and sent — on this path `encode_micros` covers packetizing and sending too,
+because packetization is the only stage the engine itself runs.
 
 ## Latest frame over the local protocol
 
@@ -516,7 +641,8 @@ of stillness. When both are supplied, both conditions must hold.
 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.
+the remote WebSocket bridge. A session opened with `local_frames: false` keeps
+no frame: both are refused with `error.code = "operation"` (see `session.open`).
 
 ```json
 {"id":20,"method":"session.frame","params":{"session_id":"…","since":7,"path":"/run/user/1000/frame.raw"}}
@@ -616,7 +742,8 @@ anything to show.
 
 - 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
-  account, token or pairing ceremony.
+  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
   raise capabilities. Kernel input access is a separate, explicit, guided step
   (`desklink-host setup-input` reports what is missing; it does not change it).

package/engine/Cargo.lock

@@ -307,6 +307,16 @@ version = "1.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 
+[[package]]
+name = "bzip2-rs"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "beeb59e7e4c811ab37cc73680c798c7a5da77fc9989c62b09138e31ee740f735"
+dependencies = [
+ "crc32fast",
+ "tinyvec",
+]
+
 [[package]]
 name = "cc"
 version = "1.4.7"
@@ -449,6 +459,15 @@ dependencies = [
  "rustc_version",
 ]
 
+[[package]]
+name = "crc32fast"
+version = "1.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "01a7799fd6b852db0e61728dde9a204c423b44d689dbd432522543614b490e78"
+dependencies = [
+ "cfg-if",
+]
+
 [[package]]
 name = "crossbeam-utils"
 version = "0.8.23"
@@ -517,7 +536,7 @@ checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
 
 [[package]]
 name = "desklink-host"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "anyhow",
  "ashpd",
@@ -525,6 +544,7 @@ dependencies = [
  "base64 0.22.1",
  "block2",
  "bytes",
+ "bzip2-rs",
  "cc",
  "futures-util",
  "libc",
@@ -534,12 +554,16 @@ dependencies = [
  "objc2-core-media",
  "objc2-foundation",
  "objc2-screen-capture-kit",
+ "openh264-sys2",
  "pipewire",
  "rand 0.8.8",
  "rtc",
  "serde",
  "serde_json",
+ "sha2",
  "tokio",
+ "wayland-client",
+ "wayland-protocols",
  "webrtc",
  "wl-clipboard-rs",
  "x11rb",
@@ -1430,6 +1454,16 @@ version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
+[[package]]
+name = "openh264-sys2"
+version = "0.9.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ada29a4cadc13d4d326737af87c13e224210d7d99fe47594e9f3f9b0102fd70"
+dependencies = [
+ "libloading",
+ "sha2",
+]
+
 [[package]]
 name = "ordered-stream"
 version = "0.2.0"
@@ -2239,6 +2273,17 @@ dependencies = [
  "digest",
 ]
 
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "digest",
+]
+
 [[package]]
 name = "shlex"
 version = "1.3.0"

package/engine/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "desklink-host"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 rust-version = "1.97.1"
 license = "Apache-2.0"
@@ -30,8 +30,18 @@ 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"] }
+x11rb = { version = "0.14", default-features = false, features = ["allow-unsafe-code", "xtest", "shm", "damage"] }
 wl-clipboard-rs = "0.9"
+# H.264 fallback: Cisco's prebuilt openh264, loaded at runtime (never built
+# from source), fetched once as bzip2 and checked against a pinned sha256.
+openh264-sys2 = { version = "0.9.8", default-features = false, features = ["libloading"] }
+sha2 = "0.10"
+bzip2-rs = "0.1.2"
+
+[target.'cfg(target_os = "linux")'.dev-dependencies]
+# The Wayland stamp example only; already in the tree through wl-clipboard-rs.
+wayland-client = "0.31"
+wayland-protocols = { version = "0.32", features = ["client"] }
 
 [target.'cfg(target_os = "macos")'.dependencies]
 anyhow = "1"

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, and nothing is
-//! installed:
+//! this machine's own sources — 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.
@@ -10,6 +10,12 @@
 //!   over `uinput`/`libevdev`, built by its own CMake project into a static
 //!   library and called through its documented C API.
 //!
+//! H.264 encoding adds no link-time dependency: NVENC and VA-API are loaded with
+//! `dlopen` from the machine's driver at run time, compiled against vendored
+//! MIT headers (`vendor/nv-codec-headers`, `vendor/libva`); openh264 is Cisco's
+//! prebuilt library, fetched by the engine at run time (see `src/h264.rs`). The
+//! macOS build links the VideoToolbox system framework.
+//!
 //! 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`.
@@ -25,6 +31,9 @@ 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/nvenc_shim.c");
+    println!("cargo:rerun-if-changed=native/vaapi_shim.c");
+    println!("cargo:rerun-if-changed=native/vt_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");
@@ -69,6 +78,18 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     }
 
     if target_os == "linux" {
+        // H.264 through NVENC and VA-API: the driver libraries are dlopen'd at
+        // run time, so building needs only their vendored MIT headers, and a
+        // machine without them still runs the engine.
+        cc::Build::new()
+            .file("native/nvenc_shim.c")
+            .include("vendor/nv-codec-headers/include")
+            .compile("dlnvenc");
+        cc::Build::new()
+            .file("native/vaapi_shim.c")
+            .include("vendor/libva")
+            .compile("dlvaapi");
+        println!("cargo:rustc-link-lib=dl");
         cc::Build::new()
             .file("native/agent_overlay_x11.c")
             .file("native/agent_overlay_wayland.c")
@@ -114,6 +135,11 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
             );
             println!("cargo:rustc-link-lib=static=vpx");
             println!("cargo:rustc-cfg=desklink_vpx");
+            // H.264 for receivers that decode it in hardware; VideoToolbox is a
+            // system framework, so linking it adds no dependency.
+            cc::Build::new().file("native/vt_shim.c").compile("dlvt");
+            println!("cargo:rustc-link-lib=framework=VideoToolbox");
+            println!("cargo:rustc-link-lib=framework=CoreFoundation");
         }
         println!("cargo:rustc-link-lib=framework=CoreGraphics");
         println!("cargo:rustc-link-lib=framework=ApplicationServices");