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>

include/lumen_core.h

@@ -54,6 +54,8 @@ enum LumenStatus
     LUMEN_STATUS_UNSUPPORTED = -6,
     LUMEN_STATUS_IO = -7,
     LUMEN_STATUS_NULL_POINTER = -8,
+    LUMEN_STATUS_TIMEOUT = -9,
+    LUMEN_STATUS_CLOSED = -10,
     LUMEN_STATUS_PANIC = -99,
 };
 #ifndef __cplusplus
@@ -92,6 +94,12 @@ typedef uint8_t LumenInputKind;
 #endif // __STDC_VERSION__ >= 202311L
 #endif // __cplusplus
 
+#if defined(LUMEN_FEATURE_QUIC)
+// Opaque handle to a live `lumen/1` connection (QUIC control plane + UDP data plane, all
+// pumped on internal threads).
+typedef struct LumenConnection LumenConnection;
+#endif
+
 // Opaque session handle. Pointer-only from C.
 typedef struct LumenSession LumenSession;
 
@@ -230,6 +238,57 @@ int32_t lumen_host_poll_input(LumenSession *s);
 // `s` is a valid handle; `out` points to a writable `LumenStats`.
 LumenStatus lumen_get_stats(LumenSession *s, LumenStats *out);
 
+#if defined(LUMEN_FEATURE_QUIC)
+// Connect to a `lumen/1` host and start a session at `width`x`height`@`refresh_hz`.
+// Blocks up to `timeout_ms` for the handshake. Returns NULL on failure.
+//
+// # Safety
+// `host` is a NUL-terminated UTF-8 string (IP or hostname resolvable by the platform).
+LumenConnection *lumen_connect(const char *host,
+                               uint16_t port,
+                               uint32_t width,
+                               uint32_t height,
+                               uint32_t refresh_hz,
+                               uint32_t timeout_ms);
+#endif
+
+#if defined(LUMEN_FEATURE_QUIC)
+// Pull the next reassembled access unit, waiting up to `timeout_ms`. Returns
+// [`LumenStatus::NoFrame`] on timeout and [`LumenStatus::Closed`] once the session ended.
+// On `Ok`, `*out` borrows connection memory **until the next call** on this handle.
+//
+// # Safety
+// `c` is a valid connection handle used from a single thread; `out` is writable.
+LumenStatus lumen_connection_next_au(LumenConnection *c, LumenFrame *out, uint32_t timeout_ms);
+#endif
+
+#if defined(LUMEN_FEATURE_QUIC)
+// Send one input event to the host as a QUIC datagram (non-blocking enqueue).
+//
+// # Safety
+// `c` is a valid connection handle; `ev` points to a valid [`InputEvent`].
+LumenStatus lumen_connection_send_input(LumenConnection *c, const LumenInputEvent *ev);
+#endif
+
+#if defined(LUMEN_FEATURE_QUIC)
+// The host-confirmed session mode (from the Welcome). Safe any time after connect.
+//
+// # Safety
+// `c` is a valid connection handle; out pointers are writable (NULLs are skipped).
+LumenStatus lumen_connection_mode(const LumenConnection *c,
+                                  uint32_t *width,
+                                  uint32_t *height,
+                                  uint32_t *refresh_hz);
+#endif
+
+#if defined(LUMEN_FEATURE_QUIC)
+// Close the connection and free the handle (joins the internal threads). NULL is a no-op.
+//
+// # Safety
+// `c` was returned by [`lumen_connect`] and is not used after this call.
+void lumen_connection_close(LumenConnection *c);
+#endif
+
 #ifdef __cplusplus
 }  // extern "C"
 #endif  // __cplusplus