feat: M4 groundwork — lumen/1 client connector in the C ABI + SwiftUI client scaffold

The shared-core architecture pays off: platform clients now link ONE Rust library that
does the entire lumen/1 protocol, and only add decode/present/input on top.

lumen-core:
- client.rs (quic feature): NativeClient — QUIC handshake + UDP data plane + input
  datagrams on internal threads; embedder surface = connect / next_frame / send_input.
- abi.rs: lumen_connect / lumen_connection_next_au (borrow-until-next-call, matching
  lumen_client_poll_frame semantics) / lumen_connection_send_input / lumen_connection_mode /
  lumen_connection_close. Guarded in the generated header by LUMEN_FEATURE_QUIC (cbindgen
  [defines] mapping), so the checked-in header is stable across feature sets.
- error.rs: append-only LumenStatus additions Timeout (-9) and Closed (-10).
- TESTED end-to-end through the C ABI: in-process lumen/1 host, lumen_connect pulls 25
  byte-verified frames, sends input, closes (m3.rs::c_abi_connection_roundtrip).

Apple client (clients/apple — SCAFFOLD, written on Linux, first Xcode build pending):
- scripts/build-xcframework.sh: cargo per Apple target → universal staticlib + header
  (LUMEN_FEATURE_QUIC pre-defined) + modulemap → LumenCore.xcframework.
- Package.swift (LumenKit) + Swift sources: LumenConnection (ABI wrapper), AnnexB
  (in-band VPS/SPS/PPS → CMVideoFormatDescription, Annex-B → AVCC CMSampleBuffers with
  DisplayImmediately), StreamView (SwiftUI over AVSampleBufferDisplayLayer — stage-1
  presenter that hardware-decodes compressed HEVC itself), InputCapture (GCMouse raw
  deltas + GCKeyboard HID→VK).
- README.md is the full handoff for the next (Mac-side) agent: build steps, ABI contract,
  first-light test recipe against the Linux host, stage-2 (VT+Metal pacing) plan, and the
  known host-side gaps (single-session m3-host, no lumen/1 audio yet, gamepad kinds not
  yet routed in m3's injector, seed-stage trust).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

crates/lumen-host/src/m3.rs

@@ -285,3 +285,76 @@ fn virtual_stream(
     tracing::info!(sent, "lumen/1 virtual stream complete");
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// End-to-end through the C ABI — the exact contract platform clients (Swift) link:
+    /// in-process lumen/1 host, `lumen_connect` → `lumen_connection_next_au` pulls verified
+    /// frames → `lumen_connection_send_input` enqueues → `lumen_connection_close`.
+    #[test]
+    fn c_abi_connection_roundtrip() {
+        use lumen_core::abi::{
+            lumen_connect, lumen_connection_close, lumen_connection_mode, lumen_connection_next_au,
+            lumen_connection_send_input,
+        };
+        use lumen_core::error::LumenStatus;
+
+        let host = std::thread::spawn(|| {
+            run(M3Options {
+                port: 19777,
+                source: M3Source::Synthetic,
+                seconds: 0,
+                frames: 25,
+            })
+        });
+        std::thread::sleep(std::time::Duration::from_millis(500));
+
+        let addr = std::ffi::CString::new("127.0.0.1").unwrap();
+        let conn = unsafe { lumen_connect(addr.as_ptr(), 19777, 1280, 720, 60, 10_000) };
+        assert!(!conn.is_null(), "lumen_connect failed");
+
+        let (mut w, mut h, mut hz) = (0u32, 0u32, 0u32);
+        assert_eq!(
+            unsafe { lumen_connection_mode(conn, &mut w, &mut h, &mut hz) },
+            LumenStatus::Ok
+        );
+        assert_eq!((w, h, hz), (1280, 720, 60));
+
+        let mut got = 0u32;
+        let mut frame = unsafe { std::mem::zeroed() };
+        while got < 25 {
+            match unsafe { lumen_connection_next_au(conn, &mut frame, 2000) } {
+                LumenStatus::Ok => {
+                    let data = unsafe { std::slice::from_raw_parts(frame.data, frame.len) };
+                    let idx = u32::from_le_bytes(data[0..4].try_into().unwrap());
+                    assert_eq!(
+                        data,
+                        &test_frame(idx, data.len())[..],
+                        "frame {idx} content"
+                    );
+                    got += 1;
+                }
+                LumenStatus::NoFrame => continue,
+                other => panic!("next_au: {other:?}"),
+            }
+        }
+
+        let ev = lumen_core::input::InputEvent {
+            kind: lumen_core::input::InputKind::MouseMove,
+            _pad: [0; 3],
+            code: 0,
+            x: 1,
+            y: 2,
+            flags: 0,
+        };
+        assert_eq!(
+            unsafe { lumen_connection_send_input(conn, &ev) },
+            LumenStatus::Ok
+        );
+
+        unsafe { lumen_connection_close(conn) };
+        host.join().unwrap().unwrap();
+    }
+}