feat: M4 stage 1 — the SwiftUI client is real: compiles, tested, first light on glass

The clients/apple scaffold is now a working macOS client, validated live against this
repo's host across the LAN: gamescope virtual output → NVENC HEVC → lumen/1 (GF(2¹⁶) FEC +
AES-GCM over UDP, QUIC control) → VideoToolbox → AVSampleBufferDisplayLayer at 720p60,
mouse/keyboard flowing back as QUIC datagrams into the host's gamescope EIS injector
(~3.7k events injected in one session).

LumenKit:
- LumenConnection: the predicted cbindgen compile fixes (C17 header spells the typedefs as
  integers while the enum constants import as a distinct Swift type — bridge by rawValue);
  close() is now safe from any thread (a close flag + pumpLock held across the blocking
  poll enforce the C contract "never close with a next_au in flight"; flag prevents
  lock-starvation by back-to-back polls).
- StreamView: per-pump cancellation token (reconnects can't double-pump), flush + re-gate
  on the next in-band parameter sets when the layer fails, no stale enqueue after restart.
- InputCapture: fractional-delta accumulation (sub-pixel motion isn't truncated away),
  pressed-state tracking with release-all on focus loss and stop() (nothing sticks down
  host-side), global-singleton ownership guard (GC has one handler slot per process),
  X1/X2 buttons, horizontal scroll, full keypad/CapsLock/ISO-102nd/PrintScreen/Menu VKs.
- LumenClient app shell (swift run LumenClient): connect form, fps/Mb-s HUD,
  LUMEN_AUTOCONNECT/LUMEN_MODE for scripted first-light runs.
- Tests: Annex-B byte-level units; real-codec round trip (VTCompressionSession-encoded
  HEVC rebuilt as the host's wire shape → AnnexB → VTDecompressionSession → pixels);
  test-loopback.sh (Swift client vs a real local m3-host over loopback — the Swift twin of
  c_abi_connection_roundtrip); RemoteFirstLightTests (full pipeline over the LAN).

Host/build fixes that fell out:
- The workspace builds on non-Linux again: gamestream audio (opus) and sendmmsg batching
  are now platform-gated with stubs/fallback, per the crate's "compiles everywhere" rule.
- Horizontal scroll was inverted end-to-end: the injectors negated BOTH axes onto the
  ei/wl axes, but GameStream's horizontal convention is positive = right
  (moonlight-qt/Sunshine pass it through unnegated) — only vertical flips now. This also
  un-inverts real Moonlight clients.
- AnnexB drops all zeros preceding a start code (trailing_zero_8bits padding), ffmpeg's
  policy, instead of leaking them into the preceding NAL.
- build-xcframework.sh: deployment targets pinned to the package floor + an otool guard —
  cargo does not fingerprint MACOSX_DEPLOYMENT_TARGET, so warm caches can silently ship
  too-new minos objects.

Adversarially reviewed (5-dimension multi-agent pass, every finding refutation-verified):
14 confirmed findings, all fixed above; the send-while-polling core-contract gap flagged
here is closed by the lumen/1 session-planes work (&self pulls + per-plane borrow slots).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

clients/apple/Tests/LumenKitTests/RemoteFirstLightTests.swift

@@ -0,0 +1,80 @@
+// First light, headless: the full client pipeline against a REAL remote host — QUIC
+// handshake over the LAN, NVENC HEVC AUs through FEC + AES-GCM, AnnexB conversion, and a
+// real VTDecompressionSession turning them into pixels. Everything the GUI does except
+// putting the layer on glass.
+//
+// Run (host side, on the Linux box):
+//   LUMEN_COMPOSITOR=gamescope LUMEN_GAMESCOPE_APP=vkcube LUMEN_ZEROCOPY=1 \
+//   lumen-host m3-host --source virtual --seconds 120
+// Then here:
+//   LUMEN_REMOTE_HOST=192.168.1.70 swift test --filter RemoteFirstLightTests
+
+import CoreMedia
+import VideoToolbox
+import XCTest
+@testable import LumenKit
+
+final class RemoteFirstLightTests: XCTestCase {
+    func testRemoteStreamDecodesToPixels() throws {
+        guard let host = ProcessInfo.processInfo.environment["LUMEN_REMOTE_HOST"] else {
+            throw XCTSkip("set LUMEN_REMOTE_HOST (and start m3-host --source virtual there)")
+        }
+        let width: UInt32 = 1280
+        let height: UInt32 = 720
+
+        let conn = try LumenConnection(
+            host: host, width: width, height: height, refreshHz: 60)
+        defer { conn.close() }
+        XCTAssertEqual(conn.width, width)
+        XCTAssertEqual(conn.height, height)
+
+        var format: CMVideoFormatDescription?
+        var decoder: VTDecompressionSession?
+        defer { decoder.map { VTDecompressionSessionInvalidate($0) } }
+        var received = 0
+        var decoded = 0
+        var firstPtsNs: UInt64 = 0
+        var lastPtsNs: UInt64 = 0
+        let deadline = Date().addingTimeInterval(30)
+
+        while decoded < 60, Date() < deadline {
+            guard let au = try conn.nextAU(timeoutMs: 2000) else { continue }
+            received += 1
+            if firstPtsNs == 0 { firstPtsNs = au.ptsNs }
+            lastPtsNs = au.ptsNs
+
+            if let f = AnnexB.formatDescription(fromIDR: au.data) {
+                format = f
+                if decoder == nil {
+                    let dims = CMVideoFormatDescriptionGetDimensions(f)
+                    XCTAssertEqual(UInt32(dims.width), width)
+                    XCTAssertEqual(UInt32(dims.height), height)
+                    var session: VTDecompressionSession?
+                    XCTAssertEqual(
+                        VTDecompressionSessionCreate(
+                            allocator: nil, formatDescription: f, decoderSpecification: nil,
+                            imageBufferAttributes: nil, outputCallback: nil,
+                            decompressionSessionOut: &session),
+                        noErr)
+                    decoder = session
+                }
+            }
+            guard let f = format, let dec = decoder,
+                  let sample = AnnexB.sampleBuffer(au: au, format: f)
+            else { continue }
+
+            var gotPixels = false
+            VTDecompressionSessionDecodeFrame(
+                dec, sampleBuffer: sample, flags: [], infoFlagsOut: nil
+            ) { status, _, imageBuffer, _, _ in
+                gotPixels = status == noErr && imageBuffer != nil
+            }
+            if gotPixels { decoded += 1 }
+        }
+
+        XCTAssertGreaterThanOrEqual(decoded, 60, "decoded \(decoded)/\(received) received AUs")
+        // The host stamps pts with its capture wall clock — 60 frames should span ~1 s.
+        let spanMs = Double(lastPtsNs &- firstPtsNs) / 1_000_000
+        print("first light: \(decoded) frames decoded, \(received) received, pts span \(Int(spanMs)) ms")
+    }
+}