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>

scripts/build-xcframework.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Build LumenCore.xcframework for the Apple clients — run ON A MAC with Xcode + rustup.
+#
+#   rustup target add aarch64-apple-darwin x86_64-apple-darwin   # + aarch64-apple-ios for iOS
+#   bash scripts/build-xcframework.sh
+#
+# Output: clients/apple/LumenCore.xcframework (consumed by clients/apple/Package.swift).
+# The library is built WITH the `quic` feature (the lumen/1 connection API), so the bundled
+# header gets LUMEN_FEATURE_QUIC pre-defined — Swift sees lumen_connect & co. unconditionally.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+TARGETS_MAC=(aarch64-apple-darwin x86_64-apple-darwin)
+BUILD_IOS="${BUILD_IOS:-0}" # BUILD_IOS=1 adds an iOS slice (requires the ios target installed)
+
+for t in "${TARGETS_MAC[@]}"; do
+    cargo build --release -p lumen-core --features quic --target "$t"
+done
+if [[ "$BUILD_IOS" == "1" ]]; then
+    cargo build --release -p lumen-core --features quic --target aarch64-apple-ios
+fi
+
+STAGE="$(mktemp -d)"
+trap 'rm -rf "$STAGE"' EXIT
+
+# Universal macOS static lib.
+mkdir -p "$STAGE/macos"
+lipo -create \
+    target/aarch64-apple-darwin/release/liblumen_core.a \
+    target/x86_64-apple-darwin/release/liblumen_core.a \
+    -output "$STAGE/macos/liblumen_core.a"
+
+# Headers dir: the generated C header (with the quic API force-enabled) + a modulemap so
+# Swift can `import LumenCore`.
+mkdir -p "$STAGE/include"
+{
+    echo "#define LUMEN_FEATURE_QUIC 1"
+    cat include/lumen_core.h
+} > "$STAGE/include/lumen_core.h"
+cat > "$STAGE/include/module.modulemap" <<'EOF'
+module LumenCore {
+    header "lumen_core.h"
+    export *
+}
+EOF
+
+ARGS=(-library "$STAGE/macos/liblumen_core.a" -headers "$STAGE/include")
+if [[ "$BUILD_IOS" == "1" ]]; then
+    ARGS+=(-library target/aarch64-apple-ios/release/liblumen_core.a -headers "$STAGE/include")
+fi
+
+rm -rf clients/apple/LumenCore.xcframework
+xcodebuild -create-xcframework "${ARGS[@]}" -output clients/apple/LumenCore.xcframework
+echo "OK: clients/apple/LumenCore.xcframework"