feat(android): scaffold the native Android client (Rust-heavy JNI bridge)

Rust-heavy client model (like punktfunk-client-linux): a new cdylib crate
crates/punktfunk-android links punktfunk-core and exposes the JNI seam;
Kotlin (clients/android) owns only the Android-framework surface. Kotlin can't
import the C header the way Swift can, so the bridge is written in Rust to reuse
the Linux client's orchestration rather than re-port it.

- crates/punktfunk-android: JNI bridge — abiVersion/coreVersion native-link
  proof + session connect/close handle; plane pumps stubbed for M4 stage 1.
- clients/android: Gradle project — :app (Compose) + :kit (Android library with
  a cargo-ndk Exec task -> jniLibs). AGP 9.2 / Gradle 9.4.1 / Kotlin 2.3.21 /
  Compose BOM 2026.05.01 / compileSdk 37 / targetSdk 36 / minSdk 31, shipping
  arm64-v8a + x86_64. Phone + TV (leanback) installable. README rewritten.
- .gitea/workflows/android.yml: CI mirroring apple.yml on a Linux runner.
- punktfunk-core: switch rcgen to the ring backend so the whole quic tree is
  aws-lc-free (smaller client .so, cmake-free cross-compile; a win for all targets).

Validated on this box: :app:assembleDebug -> APK with both ABIs; emulator
first-light renders the bridge linked (core ABI v2) with logcat confirmation;
clippy -D warnings + cargo fmt clean; core tests green on the ring backend.

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

crates/punktfunk-android/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "punktfunk-android"
+description = "punktfunk Android client — JNI bridge ('nativecore') over punktfunk-core (Rust-heavy client model)"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+
+[lib]
+# `libpunktfunk_android.so` — loaded by Kotlin via `System.loadLibrary("punktfunk_android")`.
+name = "punktfunk_android"
+crate-type = ["cdylib"]
+
+[dependencies]
+# The whole protocol/transport/FEC/crypto + the embeddable NativeClient connector. `quic` pulls
+# the punktfunk/1 control plane (now ring-only — no aws-lc, see punktfunk-core/Cargo.toml).
+punktfunk-core = { path = "../punktfunk-core", features = ["quic"] }
+jni = "0.21"
+log = "0.4"
+
+# Android-only deps. Gated so `cargo build --workspace` on the Linux/macOS dev boxes + CI still
+# compiles this crate (as a host cdylib) — the Android-framework glue (logging now; AMediaCodec via
+# `ndk` and Oboe/Opus audio later) is only pulled in for the real `*-linux-android` targets.
+[target.'cfg(target_os = "android")'.dependencies]
+android_logger = "0.14"

crates/punktfunk-android/src/lib.rs

@@ -0,0 +1,67 @@
+//! punktfunk Android client — the JNI bridge ("nativecore") over `punktfunk-core`.
+//!
+//! Architecture: the **Rust-heavy** client model (like `punktfunk-client-linux`, *not* the
+//! thin-native-over-C-ABI Apple model). This `cdylib` links `punktfunk-core` directly and drives
+//! the whole `punktfunk/1` protocol through [`punktfunk_core::client::NativeClient`]; Kotlin owns
+//! only the Android-framework surface (Compose UI, `SurfaceView` lifecycle, input capture,
+//! `NsdManager` discovery, Keystore). The JNI seam below is the one place the two languages meet.
+//!
+//! Why Rust-heavy: Kotlin cannot `import` the cbindgen C header the way Swift can, so a native
+//! bridge is unavoidable. Writing it in Rust lets the Android client reuse the Linux client's
+//! orchestration verbatim — audio jitter ring, the VK keymap inverse, latency/skew math, the
+//! input capture state machine, trust/pairing logic — instead of re-porting it into Kotlin.
+//!
+//! JNI symbols map to `io.unom.punktfunk.kit.NativeBridge` in the `:kit` Gradle module
+//! (`clients/android`). The current surface is the scaffold's native-link proof
+//! (`abiVersion`/`coreVersion`) plus the session handle lifecycle in [`session`]; the per-plane
+//! pumps (video → AMediaCodec, audio → Oboe), input, audio, pairing and mode renegotiation are
+//! the next milestone (see the TODOs in [`session`]).
+
+use jni::objects::JObject;
+use jni::sys::jint;
+use jni::JNIEnv;
+
+mod session;
+
+/// Initialize `android_logger` once when the JVM loads the library. Logs land in logcat under the
+/// `punktfunk` tag. Android-only — there is no JVM (and no logcat) on the host build.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn JNI_OnLoad(
+    _vm: *mut jni::sys::JavaVM,
+    _reserved: *mut std::ffi::c_void,
+) -> jint {
+    android_logger::init_once(
+        android_logger::Config::default()
+            .with_max_level(log::LevelFilter::Info)
+            .with_tag("punktfunk"),
+    );
+    log::info!(
+        "punktfunk_android loaded (core ABI v{})",
+        punktfunk_core::ABI_VERSION
+    );
+    jni::sys::JNI_VERSION_1_6
+}
+
+/// `NativeBridge.abiVersion(): Int` — the core's C-ABI version. A non-error return is the
+/// scaffold's proof that `System.loadLibrary` found the `.so`, the JNI symbol resolved, and the
+/// linked `punktfunk-core` is the one we expect.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_abiVersion(
+    _env: JNIEnv,
+    _this: JObject,
+) -> jint {
+    punktfunk_core::ABI_VERSION as jint
+}
+
+/// `NativeBridge.coreVersion(): String` — the crate version, proving JNI string marshaling works.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_coreVersion<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+) -> jni::sys::jstring {
+    match env.new_string(env!("CARGO_PKG_VERSION")) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}

crates/punktfunk-android/src/session.rs

@@ -0,0 +1,86 @@
+//! Session handle lifecycle over JNI.
+//!
+//! A connected [`NativeClient`] is boxed and handed to Kotlin as an opaque `jlong`; [`nativeClose`]
+//! drops it, and the connector's `Drop` tears down the worker thread + QUIC connection (RAII). The
+//! client is `Sync`, so the Kotlin side is free to pull each plane from its own thread later.
+//!
+//! TODO(M4 Android stage 1): build out the plane pumps + IO on top of this handle. Port the
+//! orchestration from `crates/punktfunk-client-linux`:
+//!
+//! - video: `next_frame` → AnnexB access unit → `AMediaCodec` (NDK, async) → `SurfaceView`
+//! - audio: `next_audio` → Opus decode → jitter ring → Oboe (port `client-linux/src/audio.rs`)
+//! - input: Kotlin capture → `send_input` / `send_rich_input` (VK keymap from `keymap.rs`)
+//! - rumble/HID feedback: `next_rumble` / `next_hidout` → VibratorManager / LightsManager
+//! - trust: `generate_identity` + `pair` + pin (Keystore-wrapped), then pass `pin`/`identity` here
+//!
+//! The signatures below are deliberately minimal (TOFU, anonymous) so the scaffold can already
+//! stand up a session against a host that does not require pairing.
+
+use jni::objects::{JObject, JString};
+use jni::sys::{jint, jlong};
+use jni::JNIEnv;
+use punktfunk_core::client::NativeClient;
+use punktfunk_core::config::{CompositorPref, GamepadPref, Mode};
+use std::time::Duration;
+
+/// `NativeBridge.nativeConnect(host, port, width, height, refreshHz): Long`.
+///
+/// Trust-on-first-use (no pin) and anonymous (no client identity) — enough to bring up a stream
+/// against a host that does not require pairing. Returns an opaque session handle, or `0` on
+/// failure (the cause is logged to logcat).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect<'local>(
+    mut env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    host: JString<'local>,
+    port: jint,
+    width: jint,
+    height: jint,
+    refresh_hz: jint,
+) -> jlong {
+    let host: String = match env.get_string(&host) {
+        Ok(s) => s.into(),
+        Err(_) => return 0,
+    };
+    let mode = Mode {
+        width: width as u32,
+        height: height as u32,
+        refresh_hz: refresh_hz as u32,
+    };
+    match NativeClient::connect(
+        &host,
+        port as u16,
+        mode,
+        CompositorPref::Auto,
+        GamepadPref::Auto,
+        0,    // bitrate_kbps: let the host choose its default
+        None, // launch: default app
+        None, // pin: trust on first use
+        None, // identity: anonymous (TODO: Keystore-backed identity + pairing)
+        Duration::from_secs(10),
+    ) {
+        Ok(client) => Box::into_raw(Box::new(client)) as jlong,
+        Err(e) => {
+            log::error!("nativeConnect to {host}:{port} failed: {e}");
+            0
+        }
+    }
+}
+
+/// `NativeBridge.nativeClose(handle)` — drop the boxed [`NativeClient`] (RAII shutdown of the
+/// worker thread + QUIC connection). No-op on a `0` handle.
+///
+/// # Safety contract
+/// `handle` must be either `0` or a value previously returned by [`Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect`]
+/// and not already closed. Kotlin owns this invariant (one `nativeClose` per non-zero `nativeConnect`).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeClose(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle != 0 {
+        // SAFETY: per the contract above, `handle` is a live `Box<NativeClient>` pointer.
+        unsafe { drop(Box::from_raw(handle as *mut NativeClient)) };
+    }
+}

crates/punktfunk-core/Cargo.toml

@@ -39,7 +39,11 @@ zeroize = "1"
 
 quinn = { version = "0.11", optional = true }
 rustls = { version = "0.23", optional = true, default-features = false, features = ["ring", "std"] }
-rcgen = { version = "0.13", optional = true, default-features = false, features = ["aws_lc_rs", "pem"] }
+# Crypto backend pinned to `ring` (matching rustls/quinn above) so the whole quic tree is
+# ring-only: no aws-lc-rs/aws-lc-sys (heavy C dep, needs cmake) is pulled in. Keeps the
+# Android/iOS cdylib lean and the cross-compile cmake-free. `generate_simple_self_signed`
+# is backend-agnostic, so the swap is transparent.
+rcgen = { version = "0.13", optional = true, default-features = false, features = ["ring", "pem"] }
 rustls-pki-types = { version = "1", optional = true }
 sha2 = { version = "0.10", optional = true }
 hmac = { version = "0.12", optional = true }