azooz2003-bit · Oct 23, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026
diff --git a/.github/rust-workspaces.toml b/.github/rust-workspaces.toml
@@ -21,6 +21,10 @@
 #                          on its own paths; FILE must name the root.
 #   skip = "why"           nothing checks it, for the reason given.
 
+[[workspace]]
+root = "cmux-screen"
+skip = "standalone screen host on LiveKit's prebuilt libwebrtc; not linked into the app, which streams with CmuxScreenKit"
+
 [[workspace]]
 root = "cmux-tui"
 covered_by = ".github/workflows/cmux-tui-spec.yml"

@@ -0,0 +1,44 @@
+name: CmuxVNC
+
+# The shared RFB (VNC) client engine (Packages/Shared/CmuxVNC): protocol,
+# authentication and decoder unit tests, plus end-to-end runs against the
+# package's loopback demo server. The cmux-next app and the iOS demo
+# (experiments/cmux-vnc-ios) both link it.
+
+on:
+  pull_request:
+    paths:
+      - Packages/Shared/CmuxVNC/**
+      - scripts/select-ci-xcode.sh
+      - scripts/ci/xcode-pins.txt
+      - .xcode-version
+      - .github/workflows/cmux-vnc.yml
+  push:
+    branches: [main]
+    paths:
+      - Packages/Shared/CmuxVNC/**
+      - scripts/select-ci-xcode.sh
+      - scripts/ci/xcode-pins.txt
+      - .xcode-version
+      - .github/workflows/cmux-vnc.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: cmux-vnc-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  swift-test:
+    runs-on: ${{ github.repository_owner != 'manaflow-ai' && 'macos-26' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository && 'blacksmith-6vcpu-macos-15' || github.event_name == 'pull_request' && (vars.MACOS_RUNNER_PR || 'blacksmith-6vcpu-macos-15') || vars.CI_PAID_MACOS_OVERFLOW == '1' && vars.MACOS_RUNNER_15 || 'blacksmith-6vcpu-macos-15') }}
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - name: Select pinned Xcode
+        run: ./scripts/select-ci-xcode.sh
+      - name: Test the RFB engine
+        run: swift test --package-path Packages/Shared/CmuxVNC
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -158,7 +158,7 @@ using their commit email, link your PR from theirs and thank them. Let a human
 close it; never close an outside PR without a human-written explanation.
 
 The server directories listed in [LICENSE](LICENSE) (`web/`, `workers/ci-artifacts/`,
-`workers/iroh-v2/`, `workers/presence/`, `services/iroh-relay-minter/`,
+`workers/iroh-v2/`, `workers/presence/`, `workers/device-hub/`, `services/iroh-relay-minter/`,
 `cmux-tui/relays/cloudflare-do/`, `backend/`) use the Business Source License, which needs
 every outside author's CLA grant. Do not merge a PR that changes those
 directories while CLA Assistant is red, and do not copy an outside

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -170,5 +170,5 @@ Agents working in this repository also follow [CLAUDE.md](CLAUDE.md) (also `AGEN
 
 By contributing to this repository, you agree that:
 
-1. Your contributions are licensed under the license of the directory you contribute to: the Business Source License 1.1 (`BUSL-1.1`) for the server directories listed in [LICENSE](LICENSE) (`web/`, `workers/ci-artifacts/`, `workers/iroh-v2/`, `workers/presence/`, `services/iroh-relay-minter/`, `cmux-tui/relays/cloudflare-do/`), and the project's GNU General Public License v3.0 or later (`GPL-3.0-or-later`) everywhere else unless a file states otherwise.
+1. Your contributions are licensed under the license of the directory you contribute to: the Business Source License 1.1 (`BUSL-1.1`) for the server directories listed in [LICENSE](LICENSE) (`web/`, `workers/ci-artifacts/`, `workers/iroh-v2/`, `workers/presence/`, `workers/device-hub/`, `services/iroh-relay-minter/`, `cmux-tui/relays/cloudflare-do/`), and the project's GNU General Public License v3.0 or later (`GPL-3.0-or-later`) everywhere else unless a file states otherwise.
 2. You grant Manaflow, Inc. a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license to use, reproduce, modify, sublicense, and distribute your contributions under any license, including a commercial license offered to third parties.
diff --git a/LICENSE b/LICENSE
@@ -15,6 +15,7 @@ production use, including self-hosting:
   workers/ci-artifacts/
   workers/iroh-v2/
   workers/presence/
+  workers/device-hub/
   services/iroh-relay-minter/
   cmux-tui/relays/cloudflare-do/
   backend/

diff --git a/Packages/Shared/CmuxScreenKit/Package.swift b/Packages/Shared/CmuxScreenKit/Package.swift
@@ -0,0 +1,43 @@
+// swift-tools-version: 6.2
+
+import PackageDescription
+
+// CmuxScreenKit: see and control a computer's screen from an app.
+//
+// - CmuxScreenKit (iOS, macOS): `ScreenSession`, one live session to a Mac
+//   (a cmux screen stream over WebRTC, RFB over WebRTC, or a direct VNC
+//   server), with reconnects, quality, input and live stats.
+// - CmuxScreenKitUI (iOS): the opt-in screen UI: `ScreenView` (fitted mode,
+//   paging between displays, the single touch input model, keyboard) and
+//   `ScreenSessionView` (full-screen chrome whose parts are picked with
+//   `ScreenFeatures`), plus `MacShortcutsBar`, `ScreenOrientation` and
+//   `PairingScanner`.
+let swiftSettings: [SwiftSetting] = [
+    .swiftLanguageMode(.v6),
+]
+
+let package = Package(
+    name: "CmuxScreenKit",
+    platforms: [.macOS(.v14), .iOS(.v17)],
+    products: [
+        .library(name: "CmuxScreenKit", targets: ["CmuxScreenKit"]),
+        .library(name: "CmuxScreenKitUI", targets: ["CmuxScreenKitUI"]),
+    ],
+    dependencies: [
+        .package(path: "../CmuxVNC"),
+        .package(path: "../CmuxVNCWebRTC"),
+    ],
+    targets: [
+        .target(
+            name: "CmuxScreenKit",
+            dependencies: [
+                .product(name: "CmuxVNC", package: "CmuxVNC"),
+                .product(name: "CmuxVNCDemoServer", package: "CmuxVNC"),
+                .product(name: "CmuxVNCWebRTC", package: "CmuxVNCWebRTC"),
+            ],
+            swiftSettings: swiftSettings
+        ),
+        .target(name: "CmuxScreenKitUI", dependencies: ["CmuxScreenKit"], swiftSettings: swiftSettings),
+        .testTarget(name: "CmuxScreenKitTests", dependencies: ["CmuxScreenKit"], swiftSettings: swiftSettings),
+    ]
+)
diff --git a/Packages/Shared/CmuxScreenKit/README.md b/Packages/Shared/CmuxScreenKit/README.md
@@ -0,0 +1,172 @@
+# CmuxScreenKit
+
+See and control a Mac's screen from an iOS app. This is the library behind
+the cmux VNC demo apps (`experiments/cmux-vnc-ios`), which use it as their
+only screen code.
+
+| Product | Platforms | What it holds |
+| --- | --- | --- |
+| `CmuxScreenKit` | iOS 17, macOS 14 | `ScreenSession` (connect, reconnect, input, quality, stats), `ScreenPreferences`, `OrientationLock`, `ScreenPerfLog`; re-exports `CmuxVNC` and `CmuxVNCWebRTC` (`VNCPairing`, `VNCEndpoint`, `VNCKeysym`, `ScreenQuality`, …) |
+| `CmuxScreenKitUI` | iOS 17 | `ScreenSessionView` (full-screen, features opt-in), `ScreenView` / `ScreenViewController` (the screen alone), `MacShortcutsBar`, `ScreenOrientation`, `PairingScanner` |
+
+## Add it
+
+SwiftPM, local path (Xcode: Add Package → Add Local…):
+
+```swift
+.package(path: "<repo>/Packages/Shared/CmuxScreenKit")
+// target dependencies:
+.product(name: "CmuxScreenKit", package: "CmuxScreenKit"),
+.product(name: "CmuxScreenKitUI", package: "CmuxScreenKit"),
+```
+
+XcodeGen: see `experiments/cmux-vnc-ios/project.yml`.
+
+## Connect to a Mac
+
+A Mac runs a screen host and shows a pairing link (`cmux-vnc://pair?…`):
+the Swift host (`cmux-vnc-host --capture`, Packages/Shared/CmuxVNCWebRTC) or
+the Rust host (`cmux-screen/`). Both serve the same protocol over WebRTC,
+through the cmux-vnc-signal Worker, with Cloudflare TURN when there is no
+direct path.
+
+```swift
+import CmuxScreenKit
+import CmuxScreenKitUI
+
+let pairing = VNCPairing(link: URL(string: link)!)!     // nil for anything that is not a pairing link
+let session = ScreenSession(title: pairing.name, pairing: pairing)
+session.connect()
+```
+
+Other targets: `ScreenSession(title:endpoint:credentials:)` for a VNC server
+reached directly, `ScreenSession()` for the built-in demo desktop.
+
+## Show it: everything
+
+```swift
+@State private var session: ScreenSession?
+
+.fullScreenCover(item: $session) { session in
+    ScreenSessionView(session: session, features: .all) { self.session = nil }
+}
+```
+
+`ScreenSessionView` closes the session when it goes away.
+
+## Pick features
+
+`ScreenFeatures` is an option set. `.all` is the demo app; `.minimal` is the
+screen with a close button, state cards and display paging.
+
+| Feature | What the user gets |
+| --- | --- |
+| `.shortcutsBar` | One-tap Mac shortcuts under the toolbar: Spotlight, Mission Control, App Windows, Switch App, Copy, Paste, Undo, Select All, New Tab, Close Window, Quit App, Screenshot, Force Quit, Lock Screen. Change the row with `shortcuts:` (`MacShortcutsBar.Shortcut`). |
+| `.qualityMenu` | Quality in the options menu: Auto, Smooth Motion, Fixed Low (720p), Medium (1080p), High (full). |
+| `.orientationLock` | Auto-Rotate / Portrait / Landscape, remembered. **Needs the app delegate hook below.** |
+| `.fitToggle` | A Fit to Display toggle. Fitted mode itself (`preferences.fitToDisplay`, on by default) pins the view to one display: zoom out stops at its fit and panning stays inside it. |
+| `.displayPaging` | Swipe at fit, or tap the page dots, to move between the Mac's displays. |
+| `.stats` | The live line: path (Direct/Relay), fps, KB/s, round trip, codec, plus its toggle. |
+| `.keyboard` | The keyboard button: the software keyboard with an Esc, Tab, arrows, Home/End, ⌃ ⌥ ⌘ (sticky) and F-key bar. Hardware keyboards work without it. |
+| `.sendKeysMenu` | Send ⌃⌥⌦, ⌘⇥, ⌘Space and Esc from the options menu. |
+| `.refresh` | Refresh Screen. |
+| `.hideToolbar` | Hide the toolbar; a chevron brings it back. |
+| `.resumeOnForeground` | Reconnect at once when the app returns after the stream dropped. |
+
+```swift
+ScreenSessionView(session: session, features: [.displayPaging, .keyboard, .shortcutsBar, .resumeOnForeground]) { … }
+```
+
+Always on: the touch input model (tap clicks where you touch, press-and-hold
+then drag drags, two-finger tap right-clicks, two fingers scroll, pinch
+zooms, one finger pans a zoomed view) and the connecting, reconnecting,
+sign-in and error cards.
+
+Orientation lock needs one line in the app delegate:
+
+```swift
+func application(_ application: UIApplication,
+                 supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask {
+    MainActor.assumeIsolated { ScreenOrientation.shared.allowed }
+}
+```
+
+## Bring your own chrome
+
+`ScreenView(session:fitToDisplay:displayPaging:keyboardVisible:)` is the
+screen alone (SwiftUI). `ScreenViewController(session:)` is the same thing
+for UIKit. Drive everything else from `ScreenSession`:
+
+- state: `phase` (`.connecting`, `.connected`, `.failed(message:needsSignIn:)`, `.ended`), `isReconnecting`, `stats`, `streamPath`, `frameSize`;
+- input: `tap(_:modifiers:)`, `type(_:modifiers:)`, `key(_:down:)`, `click(_:)`, `movePointer(to:)`, `press(_:down:)`, `scroll(dx:dy:)`;
+- `relayOnly`: connect only through the relay server (for testing that path).
+- control: `selectDisplay(_:)`, `preferences.quality` + `applyQuality()`, `refresh()`, `resumeIfNeeded()`, `connect()`, `reconnect()` (connect again with retries), `close()`.
+
+`MacShortcutsBar(session:shortcuts:)` and `PairingScanner { link in … }`
+(VisionKit, QR; check `PairingScanner.isSupported`) also work on their own.
+
+## Behaviour
+
+- **Reconnects.** A dropped stream reconnects on its own: up to
+  `reconnectLimit` tries (default 5; 0 turns it off), after 0, 1, 2, 4 and
+  8 s. A drop in the room (signaling) connection never ends a running stream.
+- **Keep preferences per Mac.** `ScreenPreferences` is `Codable`. Store
+  `session.preferences` when the session closes; `session.hostID` is free
+  for your own key.
+- **Timing log.** `session.perf = ScreenPerfLog()` turns on the
+  input-to-frame log (Documents/perf.log). It is off by default.
+- **Threads.** `ScreenSession` and every view are main-actor.
+
+## Signaling: pairing rooms or the device hub
+
+`ScreenStreamViewer` and `ScreenStreamHost` (CmuxVNCWebRTC) reach each other
+through a `ScreenSignaling`: `send(_:)`, `messages()` (`ScreenSignal`:
+`hello`, `peerJoined`, `peerLeft`, `offer`, `answer`, `candidate`, `bye`),
+`iceServers()` and `close()`. Two implementations:
+
+- `RoomSignaling(pairing:role:)`: a pairing link's room on the
+  cmux-vnc-signal Worker. `ScreenStreamViewer(pairing:)` and
+  `ScreenStreamHost(pairing:…).run()` use it exactly as before: the room is
+  reopened when it drops and a connected stream outlives it.
+- `TicketSignaling(ticket:signalURL:signer:iceServers:expectedPeerKey:)`: one
+  device hub session (docs/device-hub/PROTOCOL.md). It opens
+  `signalURL?ticket=<jws>` with the device headers from a
+  `ScreenTicketSigner` (the app's Secure Enclave key), signs this side's DTLS
+  fingerprint into every offer and answer (`fpSig` over
+  `"<sid>|<role>|<fingerprint>"`, the `a=fingerprint:` values joined with
+  `,`), and verifies the peer's against the ticket's `peerKey`. A missing or
+  wrong `fpSig` aborts the session (`ScreenSignalingError`, `bye`, socket
+  closed). `iceServers` is the session's list: the ticket's cmux relay and
+  the user's relays. The ticket admits once, so the session ends with the
+  socket (`endsSessionOnClose`).
+
+```swift
+let signaling = try TicketSignaling(ticket: push.ticket, signalURL: push.signalURL, signer: signer,
+                                    iceServers: relays, expectedPeerKey: push.peer.signingKey)
+// Viewer:
+let viewer = ScreenStreamViewer(signaling: signaling)
+try await viewer.connect()
+// Host (a `view` session ignores all input but the display choice and refresh):
+let host = ScreenStreamHost(name: "Studio", viewOnly: push.scope == "view", backend: { ScreenCaptureBackend(log: log) })
+try await host.serve(signaling)
+```
+
+`ScreenStreamHost.disconnectViewer()` sends `bye` on a device hub session.
+`ICEServerConfig` (urls, username, credential) is public for building the
+list.
+
+`ScreenSession(title:preferences:signaling:)` is a stream session whose
+signaling the app supplies: each `connect()` asks the closure for the
+connection to use (a ticket's `TicketSignaling`, which admits once) and
+fails when it returns nil, so set `reconnectLimit = 0` and start a new
+session for a new ticket. Input, quality and stats work as for a pairing.
+
+`ICERelayCheck(servers:timeout:).run()` checks a TURN relay: a relay-only
+peer connection gathers candidates, and `.relayed` means the relay gave
+this device a `typ relay` address.
+
+## Tests
+
+`swift test` in this folder runs the tests that need no device. The UI target
+builds for iOS only, through the demo apps
+(`xcodebuild -project experiments/cmux-vnc-ios/CmuxVNCiOS.xcodeproj -scheme CmuxVNCiOS`).
diff --git a/Packages/Shared/CmuxScreenKit/Sources/CmuxScreenKit/Exports.swift b/Packages/Shared/CmuxScreenKit/Sources/CmuxScreenKit/Exports.swift
@@ -0,0 +1,4 @@
+// One import for consumers: the engine types (`VNCPairing`, `VNCEndpoint`,
+// `VNCCredentials`, `VNCKeysym`, `ScreenQuality`, …) come with CmuxScreenKit.
+@_exported import CmuxVNC
+@_exported import CmuxVNCWebRTC
diff --git a/Packages/Shared/CmuxScreenKit/Sources/CmuxScreenKit/ScreenPerfLog.swift b/Packages/Shared/CmuxScreenKit/Sources/CmuxScreenKit/ScreenPerfLog.swift
@@ -0,0 +1,65 @@
+import CmuxVNC
+import Foundation
+import QuartzCore
+
+/// Opt-in per-update and per-input timings, one JSON line each, appended to
+/// a file (default Documents/perf.log; pull it with `devicectl device copy from`).
+/// Set `ScreenSession.perf` to turn it on:
+/// - frame: server latency (request → first byte), receive+decode, pixels,
+///   bytes since the last frame, wait on the main queue, image copy, draw;
+/// - input: what was sent, and the time until the next frame shows (input → frame).
+@MainActor
+public final class ScreenPerfLog {
+    private let handle: FileHandle?
+    private let start = CACurrentMediaTime()
+    private var lastBytes = 0
+    private var pendingInput: (name: String, at: CFTimeInterval)?
+
+    public init(file: URL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0].appendingPathComponent("perf.log")) {
+        let url = file
+        if !FileManager.default.fileExists(atPath: url.path) { FileManager.default.createFile(atPath: url.path, contents: nil) }
+        handle = try? FileHandle(forWritingTo: url)
+        _ = try? handle?.seekToEnd()
+        write(["event": "session", "at": Date().ISO8601Format()])
+    }
+
+    public func input(_ name: String) {
+        if pendingInput == nil { pendingInput = (name, CACurrentMediaTime()) }
+        write(["event": "input", "t": ms(CACurrentMediaTime() - start), "name": name])
+    }
+
+    public func frame(_ frame: VNCFrame, stats: VNCSessionStats, copyMs: Double, drawMs: Double) {
+        let now = CACurrentMediaTime()
+        let queued = Double(DispatchTime.now().uptimeNanoseconds &- frame.publishedAt) / 1e6 - copyMs - drawMs
+        var line: [String: Any] = [
+            "event": "frame", "t": ms(now - start), "seq": frame.sequence,
+            "server_ms": stats.lastUpdateLatencyMs ?? -1, "recv_decode_ms": stats.lastDecodeMs ?? -1,
+            "pixels": stats.lastUpdatePixels, "bytes": stats.bytesReceived - lastBytes,
+            "main_wait_ms": max(0, queued), "copy_ms": copyMs, "draw_ms": drawMs,
+        ]
+        lastBytes = stats.bytesReceived
+        if let input = pendingInput {
+            line["input"] = input.name
+            line["input_to_frame_ms"] = ms(now - input.at)
+            pendingInput = nil
+        }
+        write(line)
+    }
+
+    /// Stream mode: a rendered video frame (WebRTC) — closes an input's
+    /// input → frame timing. Frames repeat while idle (refresh), so a
+    /// measurement is the first frame after the input, an upper bound.
+    public func streamFrame() {
+        guard let input = pendingInput else { return }
+        pendingInput = nil
+        write(["event": "frame", "t": ms(CACurrentMediaTime() - start), "input": input.name,
+               "input_to_frame_ms": ms(CACurrentMediaTime() - input.at), "stream": true])
+    }
+
+    private func ms(_ seconds: CFTimeInterval) -> Double { (seconds * 1000).rounded() }
+
+    private func write(_ line: [String: Any]) {
+        guard let data = try? JSONSerialization.data(withJSONObject: line, options: [.sortedKeys]) else { return }
+        handle?.write(data + Data("\n".utf8))
+    }
+}