refactor: drop milestone names + consolidate clients; loss-recovery & rumble fixes

Two bodies of work in one commit (the rename moved files the fixes also touched).

Naming/structure cleanup (pre-launch):
- Host modules m3.rs->punktfunk1.rs, m0.rs->spike.rs; CLI m3-host->punktfunk1-host,
  m0->spike; bare `punktfunk-host` now prints help. Types M3Options/M3Source->
  Punktfunk1Options/Punktfunk1Source.
- Clients consolidated out of crates/ into clients/: punktfunk-client-rs->
  clients/probe (crate punktfunk-probe), client-linux->clients/linux,
  client-windows->clients/windows, punktfunk-android->clients/android/native
  (crate punktfunk-client-android; kept [lib] name=punktfunk_android so the JNI
  contract is unchanged). crates/ now holds only core + host.
- Milestone codes M0-M4 purged from code/CLI/CLAUDE.md/README/docs/docs-site,
  kept only in docs/implementation-plan.md. docs/m2-plan.md->
  docs/gamestream-host-plan.md. CI/gradle/flatpak paths updated.

Client loss-recovery (video froze and never recovered after a brief drop):
- Export punktfunk_connection_frames_dropped through the C ABI (the core already
  tracked it for the client keyframe-recovery loop; it was never reachable from
  the ABI clients). Regenerated punktfunk_core.h.
- Apple (StreamPump + Stage2Pipeline) and Android (decode.rs) now poll
  frames_dropped and request a keyframe when it climbs -- the same loss-driven
  recovery Linux/Windows already had. Under infinite GOP the decoder silently
  conceals reference-missing frames, so the decode-error trigger rarely fires.

Apple rumble robustness (worked then went spotty -- DualSense + Xbox):
- Add CHHapticEngine stopped/reset handlers (rebuild on app background / audio
  interruption / server reset) and drop the permanent `broken` latch on a
  transient drive failure; latch only when the controller truly has no haptics.
- Surface swallowed SDL set_rumble errors on Linux/Windows + diagnostic logging.

Verified: cargo build/clippy/fmt --workspace, C-ABI harness, header drift.
Not runnable on this box (verify in CI): Gitea workflows, gradle/Android,
flatpak, Swift/decky.

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

clients/android/README.md

@@ -11,7 +11,7 @@ machine, trust logic) instead of re-porting it into Kotlin.
 
 | Side | Owns |
 |------|------|
-| **Rust** (`crates/punktfunk-android` → `libpunktfunk_android.so`) | the JNI seam, `NativeClient` (QUIC control + UDP data plane), AnnexB→`AMediaCodec` decode, Opus+Oboe audio, VK keymap, latency math, trust/pairing |
+| **Rust** (`clients/android/native` → `libpunktfunk_android.so`) | the JNI seam, `NativeClient` (QUIC control + UDP data plane), AnnexB→`AMediaCodec` decode, Opus+Oboe audio, VK keymap, latency math, trust/pairing |
 | **Kotlin** (`clients/android`) | Compose UI (host grid / settings / stream), `SurfaceView` lifecycle, input capture, `NsdManager` discovery, Keystore identity, permissions |
 
 The single seam is `io.unom.punktfunk.kit.NativeBridge` ⇄ `Java_io_unom_punktfunk_kit_NativeBridge_*`.
@@ -19,7 +19,7 @@ The single seam is `io.unom.punktfunk.kit.NativeBridge` ⇄ `Java_io_unom_punktf
 ## Layout
 
 ```
-crates/punktfunk-android/          Rust cdylib (workspace member)
+clients/android/native/          Rust cdylib (workspace member)
   src/lib.rs                       JNI_OnLoad + abiVersion/coreVersion (native-link proof)
   src/session.rs                   session handle lifecycle (connect/close); plane pumps = TODO
 
@@ -63,7 +63,7 @@ The debug APK lands in `app/build/outputs/apk/debug/`. The scaffold screen calls
 - **Scaffold (done):** Gradle modules, cargo-ndk wiring, JNI native-link proof, phone+TV-installable
   manifest. `crates/punktfunk-core` `rcgen` switched to the `ring` backend so the client `.so` is
   aws-lc-free.
-- **Next (M4 Android stage 1):** video decode (`AMediaCodec` async → `SurfaceView`), audio
+- **Next (Android stage 1):** video decode (`AMediaCodec` async → `SurfaceView`), audio
   (Opus + Oboe + jitter ring), input capture → `send_input`, pairing/identity (Keystore-wrapped),
   mDNS discovery, the phone/TV Compose UI. The Rust-side homes are stubbed in
-  `crates/punktfunk-android/src/session.rs` with port pointers to `crates/punktfunk-client-linux`.
+  `clients/android/native/src/session.rs` with port pointers to `clients/linux`.

clients/android/kit/build.gradle.kts

@@ -32,7 +32,7 @@ dependencies {
 }
 
 // ------------------------------------------------------------------------------------------------
-// cargo-ndk: cross-compile crates/punktfunk-android into this module's jniLibs/<abi>/ so the
+// cargo-ndk: cross-compile clients/android/native (punktfunk-client-android) into this module's jniLibs/<abi>/ so the
 // resulting libpunktfunk_android.so is packaged into the app (and any AAR this module produces).
 // NDK r28+ aligns to 16 KB pages by default — no extra linker flags. Prereqs (see clients/android
 // /README.md): `cargo install cargo-ndk` + `rustup target add aarch64-linux-android x86_64-linux-android`.
@@ -57,7 +57,7 @@ fun androidSdkDir(): String {
 fun registerCargoNdk(taskName: String, release: Boolean) =
     tasks.register<Exec>(taskName) {
         group = "rust"
-        description = "cargo-ndk build of punktfunk-android (${if (release) "release" else "debug"})"
+        description = "cargo-ndk build of punktfunk-client-android (${if (release) "release" else "debug"})"
         workingDir = repoRoot
         val sdk = androidSdkDir()
         // A GUI Android Studio launch does not source the login shell, so make cargo, the NDK, and
@@ -84,7 +84,7 @@ fun registerCargoNdk(taskName: String, release: Boolean) =
             // Link against the minSdk-31 sysroot so libaaudio (API 26+) is found.
             "--platform", "31",
             "-o", file("src/main/jniLibs").absolutePath,
-            "build", "-p", "punktfunk-android",
+            "build", "-p", "punktfunk-client-android",
         )
         if (release) cmd += "--release"
         commandLine(cmd)

clients/android/kit/src/main/kotlin/io/unom/punktfunk/kit/NativeBridge.kt

@@ -3,7 +3,7 @@ package io.unom.punktfunk.kit
 /**
  * The single JNI seam to `libpunktfunk_android.so` (the Rust-heavy client core).
  *
- * Symbols are implemented in `crates/punktfunk-android`. This object is intentionally thin —
+ * Symbols are implemented in `clients/android/native`. This object is intentionally thin —
  * all protocol logic lives in Rust (`punktfunk-core` + the connector); Kotlin only marshals.
  */
 object NativeBridge {

clients/android/native/Cargo.toml

@@ -0,0 +1,35 @@
+[package]
+name = "punktfunk-client-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 = "../../../crates/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"
+# NDK bindings. "media" = AMediaCodec/ANativeWindow (video); "audio" = AAudio (audio playback).
+# Pure-Rust FFI to libmediandk/libnativewindow/libaaudio — no C++/libc++_shared to bundle. Decode +
+# audio run entirely in Rust on native threads (the "no async on the hot path" invariant).
+ndk = { version = "0.9", features = ["media", "audio"] }
+# Opus decode for the host→client audio plane (0xC9: 48 kHz stereo, 5 ms frames). Same crate the
+# host + Linux client use. audiopus_sys vendors libopus (pure C) and builds it static via cmake —
+# the cargo-ndk build sets LIBOPUS_STATIC=1/LIBOPUS_NO_PKG=1 so it links the bundled lib, not the host's.
+opus = "0.3"

clients/android/native/src/audio.rs

@@ -0,0 +1,196 @@
+//! Android audio playback (android-only): pull Opus packets from the connector, decode to
+//! interleaved f32 stereo, and feed AAudio (LowLatency) via its realtime data callback through a
+//! jitter ring. Mirrors [`crate::decode`]: one thread we own (the Opus decode producer) plus a
+//! shutdown flag; the realtime callback thread is owned by AAudio. Ring logic ported from
+//! `punktfunk-client-linux/src/audio.rs` (prime ~3 quanta, drop-oldest cap, re-prime on drain).
+
+use ndk::audio::{
+    AudioCallbackResult, AudioDirection, AudioFormat, AudioPerformanceMode, AudioSharingMode,
+    AudioStream, AudioStreamBuilder,
+};
+use punktfunk_core::client::NativeClient;
+use punktfunk_core::error::PunktfunkError;
+use std::collections::VecDeque;
+use std::ffi::c_void;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::mpsc::{sync_channel, SyncSender, TrySendError};
+use std::sync::Arc;
+use std::time::Duration;
+
+const CHANNELS: usize = 2;
+const SAMPLE_RATE: i32 = 48_000;
+/// Decoded-chunk hand-off depth: 64 × 5 ms = 320 ms slack (matches the core's AUDIO_QUEUE).
+const RING_CHUNKS: usize = 64;
+/// Opus decode scratch: worst-case 120 ms stereo frame (5760 samples/ch × 2 ch).
+const PCM_SCRATCH: usize = 5760 * CHANNELS;
+
+/// Diagnostics — written by the decode thread + the realtime callback, logged periodically. The
+/// audio analogue of the video `fed`/`rendered` counters (we can't "screenshot" sound).
+#[derive(Default)]
+struct Counters {
+    opus_decoded: AtomicU64, // Opus packets decoded OK (~200/s at 5 ms frames)
+    pcm_written: AtomicU64,  // PCM frames copied out to AAudio (device clock is pulling)
+    underruns: AtomicU64,    // callbacks that emitted silence (ring not primed / drained)
+    ring_depth: AtomicU64,   // ring sample count at the last callback
+}
+
+/// Owned by [`crate::session::SessionHandle`]: the live AAudio stream + the decode thread.
+pub struct AudioPlayback {
+    _stream: AudioStream, // dropping it stops + closes the AAudio stream
+    shutdown: Arc<AtomicBool>,
+    join: Option<std::thread::JoinHandle<()>>,
+}
+
+impl AudioPlayback {
+    /// Open AAudio (LowLatency, 48 kHz/stereo/f32) with a realtime callback draining a jitter ring,
+    /// then spawn the Opus decode thread. `None` on failure (the caller leaves video streaming).
+    pub fn start(client: Arc<NativeClient>) -> Option<AudioPlayback> {
+        let counters = Arc::new(Counters::default());
+        let (tx, rx) = sync_channel::<Vec<f32>>(RING_CHUNKS);
+
+        // Realtime consumer state, owned by the callback (FnMut) — no lock: AAudio calls it from a
+        // single high-priority thread, and the decode thread only touches `tx`.
+        let cb_counters = counters.clone();
+        let mut ring: VecDeque<f32> = VecDeque::with_capacity(PCM_SCRATCH);
+        let mut primed = false;
+        let callback = move |_s: &AudioStream, data: *mut c_void, num_frames: i32| {
+            let want = num_frames as usize * CHANNELS;
+            // SAFETY: AAudio provides `num_frames * channel_count` F32 slots at `data`.
+            let out = unsafe { std::slice::from_raw_parts_mut(data as *mut f32, want) };
+            while let Ok(chunk) = rx.try_recv() {
+                ring.extend(chunk);
+            }
+            // Prime to ~3 quanta (15 ms; floor 15 ms / ceiling 200 ms); drop OLDEST above the cap.
+            let target = (3 * want).clamp(720 * CHANNELS, 9600 * CHANNELS);
+            while ring.len() > target.max(want) + want {
+                ring.pop_front();
+            }
+            if !primed && ring.len() >= target {
+                primed = true;
+            }
+            if primed {
+                for slot in out.iter_mut() {
+                    *slot = ring.pop_front().unwrap_or(0.0);
+                }
+                cb_counters
+                    .pcm_written
+                    .fetch_add(num_frames as u64, Ordering::Relaxed);
+            } else {
+                out.fill(0.0);
+                cb_counters.underruns.fetch_add(1, Ordering::Relaxed);
+            }
+            if ring.is_empty() {
+                primed = false; // re-prime after a genuine drain (avoids sustained crackle on loss)
+            }
+            cb_counters
+                .ring_depth
+                .store(ring.len() as u64, Ordering::Relaxed);
+            AudioCallbackResult::Continue
+        };
+
+        let stream = AudioStreamBuilder::new()
+            .map_err(|e| log::error!("audio: AudioStreamBuilder::new: {e}"))
+            .ok()?
+            .direction(AudioDirection::Output)
+            .sample_rate(SAMPLE_RATE)
+            .channel_count(CHANNELS as i32)
+            .format(AudioFormat::PCM_Float)
+            .performance_mode(AudioPerformanceMode::LowLatency)
+            .sharing_mode(AudioSharingMode::Shared)
+            .data_callback(Box::new(callback))
+            .error_callback(Box::new(|_s, e| {
+                log::warn!("audio: AAudio error (device reroute/disconnect?): {e:?}");
+            }))
+            .open_stream()
+            .map_err(|e| log::error!("audio: open_stream: {e}"))
+            .ok()?;
+
+        if let Err(e) = stream.request_start() {
+            log::error!("audio: request_start: {e}");
+            return None;
+        }
+        log::info!(
+            "audio: AAudio started rate={} ch={} fmt={:?} burst={}",
+            stream.sample_rate(),
+            stream.channel_count(),
+            stream.format(),
+            stream.frames_per_burst(),
+        );
+
+        let shutdown = Arc::new(AtomicBool::new(false));
+        let sd = shutdown.clone();
+        let join = std::thread::Builder::new()
+            .name("pf-audio".into())
+            .spawn(move || decode_loop(client, tx, sd, counters))
+            .ok();
+
+        Some(AudioPlayback {
+            _stream: stream,
+            shutdown,
+            join,
+        })
+    }
+}
+
+impl Drop for AudioPlayback {
+    fn drop(&mut self) {
+        self.shutdown.store(true, Ordering::SeqCst);
+        if let Some(j) = self.join.take() {
+            let _ = j.join();
+        }
+        // `_stream` drops here → AAudio request_stop + close.
+    }
+}
+
+/// Producer: `next_audio` → Opus `decode_float` → push interleaved f32 into the ring channel.
+fn decode_loop(
+    client: Arc<NativeClient>,
+    tx: SyncSender<Vec<f32>>,
+    shutdown: Arc<AtomicBool>,
+    counters: Arc<Counters>,
+) {
+    let mut dec = match opus::Decoder::new(SAMPLE_RATE as u32, opus::Channels::Stereo) {
+        Ok(d) => d,
+        Err(e) => {
+            log::error!("audio: opus decoder init: {e} — audio disabled");
+            return;
+        }
+    };
+    let mut pcm = vec![0f32; PCM_SCRATCH];
+    let mut window_peak = 0f32; // loudest |sample| since the last log — tells a tone from silence
+    while !shutdown.load(Ordering::Relaxed) {
+        match client.next_audio(Duration::from_millis(5)) {
+            Ok(pkt) => match dec.decode_float(&pkt.data, &mut pcm, false) {
+                Ok(samples) => {
+                    let n = samples * CHANNELS;
+                    for &s in &pcm[..n] {
+                        window_peak = window_peak.max(s.abs());
+                    }
+                    let count = counters.opus_decoded.fetch_add(1, Ordering::Relaxed) + 1;
+                    match tx.try_send(pcm[..n].to_vec()) {
+                        Ok(()) | Err(TrySendError::Full(_)) => {} // drop-newest under backpressure
+                        Err(TrySendError::Disconnected(_)) => break,
+                    }
+                    if count % 600 == 0 {
+                        log::info!(
+                            "audio: opus={count} pcm_frames={} underruns={} ring={} peak={window_peak:.3}",
+                            counters.pcm_written.load(Ordering::Relaxed),
+                            counters.underruns.load(Ordering::Relaxed),
+                            counters.ring_depth.load(Ordering::Relaxed),
+                        );
+                        window_peak = 0.0;
+                    }
+                }
+                Err(e) => log::debug!("audio: opus decode: {e}"),
+            },
+            Err(PunktfunkError::NoFrame) => {} // timeout
+            Err(_) => break,                   // session closed
+        }
+    }
+    log::info!(
+        "audio: stopped (opus={} pcm_frames={} underruns={})",
+        counters.opus_decoded.load(Ordering::Relaxed),
+        counters.pcm_written.load(Ordering::Relaxed),
+        counters.underruns.load(Ordering::Relaxed),
+    );
+}

clients/android/native/src/decode.rs

@@ -0,0 +1,160 @@
+//! Android video decode (android-only): pull HEVC access units from the connector and render them
+//! to the SurfaceView via NDK `AMediaCodec` — hardware decode, zero per-frame JNI.
+//!
+//! One-in/one-out: the host opens every stream with an IDR carrying VPS/SPS/PPS **in-band**, so the
+//! decoder needs no out-of-band codec-specific data — we configure with mime + the negotiated
+//! WxH (from [`NativeClient::mode`]) and feed each access unit as it arrives. The decode thread owns
+//! the codec + window for its whole life; [`crate::session`] signals it to stop via the shared flag.
+
+use ndk::media::media_codec::{
+    DequeuedInputBufferResult, DequeuedOutputBufferInfoResult, MediaCodec, MediaCodecDirection,
+};
+use ndk::media::media_format::MediaFormat;
+use ndk::native_window::NativeWindow;
+use punktfunk_core::client::NativeClient;
+use punktfunk_core::error::PunktfunkError;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+/// The decode loop. Runs on the `pf-decode` thread until `shutdown` is set or the session closes.
+pub fn run(client: Arc<NativeClient>, window: NativeWindow, shutdown: Arc<AtomicBool>) {
+    let mode = client.mode();
+    let codec = match MediaCodec::from_decoder_type("video/hevc") {
+        Some(c) => c,
+        None => {
+            log::error!("decode: no HEVC decoder on this device");
+            return;
+        }
+    };
+
+    let mut format = MediaFormat::new();
+    format.set_str("mime", "video/hevc");
+    format.set_i32("width", mode.width as i32);
+    format.set_i32("height", mode.height as i32);
+    // Generous input buffer so a large keyframe AU is never truncated.
+    format.set_i32(
+        "max-input-size",
+        (mode.width * mode.height).max(2_000_000) as i32,
+    );
+    // Ask for the low-latency decode path where the decoder supports it (no reordering buffer).
+    format.set_i32("low-latency", 1);
+
+    if let Err(e) = codec.configure(&format, Some(&window), MediaCodecDirection::Decoder) {
+        log::error!("decode: configure failed: {e}");
+        return;
+    }
+    if let Err(e) = codec.start() {
+        log::error!("decode: start failed: {e}");
+        return;
+    }
+    log::info!(
+        "decode: HEVC decoder started at {}x{}",
+        mode.width,
+        mode.height
+    );
+
+    let mut fed: u64 = 0;
+    let mut rendered: u64 = 0;
+    // Loss recovery: watch the host→client unrecoverable-drop count and ask for an IDR when it
+    // climbs.
+    let mut last_dropped = client.frames_dropped();
+    let mut last_kf_req: Option<Instant> = None;
+    while !shutdown.load(Ordering::Relaxed) {
+        match client.next_frame(Duration::from_millis(5)) {
+            Ok(frame) => {
+                if fed == 0 {
+                    let p = &frame.data;
+                    log::info!(
+                        "decode: first AU {} bytes, head {:02x?}",
+                        p.len(),
+                        &p[..p.len().min(6)]
+                    );
+                }
+                fed += 1;
+                feed(&codec, &frame.data, frame.pts_ns / 1000);
+            }
+            Err(PunktfunkError::NoFrame) => {} // timeout — still drain output below
+            Err(_) => break,                   // session closed
+        }
+        rendered += drain(&codec);
+
+        // Loss recovery: under infinite GOP the only recovery keyframe is one we request. The
+        // reassembler drops unrecoverable AUs (frames_dropped); the decoder then conceals the
+        // reference-missing delta frames that follow and renders them without error, so keying off
+        // a decode error rarely fires. Request an IDR when the drop count climbs, throttled — the
+        // decode stays wedged for several frames until the IDR lands, so requesting every frame
+        // would flood the control stream.
+        let dropped = client.frames_dropped();
+        if dropped > last_dropped {
+            last_dropped = dropped;
+            let now = Instant::now();
+            if last_kf_req.is_none_or(|t| now.duration_since(t) >= Duration::from_millis(100)) {
+                last_kf_req = Some(now);
+                let _ = client.request_keyframe();
+                log::debug!("decode: requested keyframe (loss recovery, dropped={dropped})");
+            }
+        }
+
+        if fed > 0 && fed % 300 == 0 {
+            log::info!("decode: fed={fed} rendered={rendered}");
+        }
+    }
+
+    let _ = codec.stop();
+    log::info!("decode: stopped (fed={fed} rendered={rendered})");
+}
+
+/// Copy one access unit into a codec input buffer and queue it.
+fn feed(codec: &MediaCodec, au: &[u8], pts_us: u64) {
+    match codec.dequeue_input_buffer(Duration::from_millis(10)) {
+        Ok(DequeuedInputBufferResult::Buffer(mut buf)) => {
+            let n = {
+                let dst = buf.buffer_mut();
+                let n = au.len().min(dst.len());
+                if n < au.len() {
+                    log::warn!(
+                        "decode: AU {} > input buffer {}, truncated",
+                        au.len(),
+                        dst.len()
+                    );
+                }
+                for (slot, &b) in dst.iter_mut().zip(&au[..n]) {
+                    slot.write(b);
+                }
+                n
+            };
+            if let Err(e) = codec.queue_input_buffer(buf, 0, n, pts_us, 0) {
+                log::warn!("decode: queue_input_buffer: {e}");
+            }
+        }
+        Ok(DequeuedInputBufferResult::TryAgainLater) => {
+            // No input buffer free right now; the AU is dropped (FEC/keyframes recover).
+        }
+        Err(e) => log::warn!("decode: dequeue_input_buffer: {e}"),
+    }
+}
+
+/// Release any ready output buffers to the surface (render = true), latency-first. Returns the
+/// number of frames presented.
+fn drain(codec: &MediaCodec) -> u64 {
+    let mut n = 0;
+    loop {
+        match codec.dequeue_output_buffer(Duration::from_millis(0)) {
+            Ok(DequeuedOutputBufferInfoResult::Buffer(buf)) => {
+                if let Err(e) = codec.release_output_buffer(buf, true) {
+                    log::warn!("decode: release_output_buffer: {e}");
+                    break;
+                }
+                n += 1;
+            }
+            // TryAgainLater / OutputFormatChanged / OutputBuffersChanged — nothing to render now.
+            Ok(_) => break,
+            Err(e) => {
+                log::warn!("decode: dequeue_output_buffer: {e}");
+                break;
+            }
+        }
+    }
+    n
+}

clients/android/native/src/feedback.rs

@@ -0,0 +1,114 @@
+//! Host→client gamepad feedback pulls (Option B): blocking JNI shims that forward to the connector's
+//! rumble (0xCA) / HID-output (0xCD) planes and return one decoded event. Kotlin owns the poll
+//! threads + the Android Vibrator/Lights rendering (see `GamepadFeedback.kt`) — no JNI upcalls, no
+//! `JavaVM` attach, no cached method ids. Mirrors the audio plane's one-thread-per-plane contract,
+//! except the thread lives in Kotlin and we just expose the blocking pull.
+//!
+//! Not android-gated: `next_rumble`/`next_hidout` are pure-Rust on the `quic` feature, so these
+//! compile on the host build too (parity with the input shims in [`crate::session`]).
+
+use crate::session::SessionHandle;
+use jni::objects::{JByteBuffer, JObject};
+use jni::sys::{jint, jlong};
+use jni::JNIEnv;
+use punktfunk_core::quic::HidOutput;
+use std::time::Duration;
+
+/// Short blocking timeout: long enough not to busy-spin, short enough that the Kotlin poll thread
+/// observes its `running=false` flag promptly on teardown.
+const PULL_TIMEOUT: Duration = Duration::from_millis(100);
+
+// HID-output kind tags written into the returned ByteBuffer (Kotlin reads them back).
+const TAG_LED: u8 = 0x01;
+const TAG_PLAYER_LEDS: u8 = 0x02;
+const TAG_TRIGGER: u8 = 0x03;
+
+/// `NativeBridge.nativeNextRumble(handle): Long` — block up to ~100 ms for the next rumble update.
+/// Returns `(low << 16) | high` (each 0..=0xFFFF; `0` = stop), or `-1` on timeout / session closed.
+/// Pad index is dropped (single-pad model). Run from a dedicated Kotlin poll thread.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextRumble(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) -> jlong {
+    if handle == 0 {
+        return -1;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract; next_rumble is &self on the
+    // Sync connector — safe alongside the decode/audio/input threads. Kotlin stops these poll
+    // threads (and joins them) before nativeClose frees the handle.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    match h.client.next_rumble(PULL_TIMEOUT) {
+        Ok((_pad, low, high)) => (jlong::from(low) << 16) | jlong::from(high),
+        Err(_) => -1, // NoFrame (timeout) or Closed — Kotlin loops on its running flag
+    }
+}
+
+/// `NativeBridge.nativeNextHidout(handle, buf): Int` — block up to ~100 ms for the next DualSense
+/// HID-output event, written into the caller's direct ByteBuffer as `[kind][fields…]`:
+///   Led        → `[0x01][r][g][b]`         (len 4)
+///   PlayerLeds → `[0x02][bits]`            (len 2)
+///   Trigger    → `[0x03][which][effect…]`  (len 2 + effect.len())
+/// Returns the byte count written, or `-1` on timeout / session closed / buffer too small.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeNextHidout(
+    env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    buf: JByteBuffer,
+) -> jint {
+    if handle == 0 {
+        return -1;
+    }
+    // SAFETY: live handle per the contract; next_hidout is &self on the Sync connector.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let ev = match h.client.next_hidout(PULL_TIMEOUT) {
+        Ok(ev) => ev,
+        Err(_) => return -1, // timeout or closed — Kotlin loops
+    };
+
+    // The caller passes a direct ByteBuffer (allocateDirect) so we write its backing store directly.
+    let cap = match env.get_direct_buffer_capacity(&buf) {
+        Ok(c) => c,
+        Err(_) => return -1,
+    };
+    let ptr = match env.get_direct_buffer_address(&buf) {
+        Ok(p) if !p.is_null() => p,
+        _ => return -1,
+    };
+    // SAFETY: `ptr`/`cap` describe the direct ByteBuffer's backing store, valid for this call.
+    let out = unsafe { std::slice::from_raw_parts_mut(ptr, cap) };
+
+    let n = match ev {
+        HidOutput::Led { r, g, b, .. } => {
+            if cap < 4 {
+                return -1;
+            }
+            out[0] = TAG_LED;
+            out[1] = r;
+            out[2] = g;
+            out[3] = b;
+            4
+        }
+        HidOutput::PlayerLeds { bits, .. } => {
+            if cap < 2 {
+                return -1;
+            }
+            out[0] = TAG_PLAYER_LEDS;
+            out[1] = bits;
+            2
+        }
+        HidOutput::Trigger { which, effect, .. } => {
+            let n = 2 + effect.len();
+            if cap < n {
+                return -1; // the raw DS5 trigger block is ~11 bytes; Kotlin allocates 64
+            }
+            out[0] = TAG_TRIGGER;
+            out[1] = which;
+            out[2..n].copy_from_slice(&effect);
+            n
+        }
+    };
+    n as jint
+}

clients/android/native/src/lib.rs

@@ -0,0 +1,74 @@
+//! 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;
+
+#[cfg(target_os = "android")]
+mod audio;
+#[cfg(target_os = "android")]
+mod decode;
+mod feedback;
+#[cfg(target_os = "android")]
+mod mic;
+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(),
+    }
+}

clients/android/native/src/mic.rs

@@ -0,0 +1,174 @@
+//! Android microphone uplink (android-only): capture mic PCM via AAudio (LowLatency **input**),
+//! Opus-encode 20 ms stereo frames, and push them to the host over the connector's mic plane
+//! (`send_mic` → 0xCB datagram). The mirror of [`crate::audio`] in reverse: AAudio's realtime input
+//! callback hands captured interleaved f32 to a channel; a worker thread we own does the Opus encode
+//! + send (encoding is too heavy for the realtime callback, exactly as decode is on the playback
+//! side). Format matches the host decoder + the Linux client: 48 kHz **stereo**, 20 ms, Opus VOIP.
+
+use ndk::audio::{
+    AudioCallbackResult, AudioDirection, AudioFormat, AudioPerformanceMode, AudioSharingMode,
+    AudioStream, AudioStreamBuilder,
+};
+use punktfunk_core::client::NativeClient;
+use std::collections::VecDeque;
+use std::ffi::c_void;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::mpsc::{sync_channel, Receiver, RecvTimeoutError, TrySendError};
+use std::sync::Arc;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+const CHANNELS: usize = 2;
+const SAMPLE_RATE: i32 = 48_000;
+/// 20 ms per channel @ 48 kHz — the Linux client's frame; the host accepts ≤ 120 ms.
+const FRAME_SAMPLES: usize = 960;
+/// Captured-chunk hand-off depth (each ~ one burst); drops on overflow (best-effort uplink).
+const RING_CHUNKS: usize = 64;
+/// Opus VOIP target bitrate (speech; tunable).
+const MIC_BITRATE: i32 = 64_000;
+
+/// Owned by [`crate::session::SessionHandle`]: the live AAudio input stream + the encode thread.
+pub struct MicCapture {
+    _stream: AudioStream, // dropping it stops + closes the AAudio input stream
+    shutdown: Arc<AtomicBool>,
+    join: Option<std::thread::JoinHandle<()>>,
+}
+
+impl MicCapture {
+    /// Open AAudio (LowLatency, 48 kHz/stereo/f32) for **input** with a realtime callback that
+    /// forwards captured PCM to a channel, then spawn the Opus encode + uplink thread. `None` on
+    /// failure (the caller leaves the rest of the session streaming).
+    pub fn start(client: Arc<NativeClient>) -> Option<MicCapture> {
+        let (tx, rx) = sync_channel::<Vec<f32>>(RING_CHUNKS);
+        let captured = Arc::new(AtomicU64::new(0));
+        let cb_captured = captured.clone();
+
+        let callback = move |_s: &AudioStream, data: *mut c_void, num_frames: i32| {
+            let n = num_frames as usize * CHANNELS;
+            // SAFETY: for an input stream AAudio provides `num_frames * channel_count` captured F32
+            // samples at `data` (read-only for us).
+            let inp = unsafe { std::slice::from_raw_parts(data as *const f32, n) };
+            match tx.try_send(inp.to_vec()) {
+                Ok(()) | Err(TrySendError::Full(_)) => {} // drop-newest if the encoder lags
+                Err(TrySendError::Disconnected(_)) => return AudioCallbackResult::Stop,
+            }
+            cb_captured.fetch_add(num_frames as u64, Ordering::Relaxed);
+            AudioCallbackResult::Continue
+        };
+
+        let stream = AudioStreamBuilder::new()
+            .map_err(|e| log::error!("mic: AudioStreamBuilder::new: {e}"))
+            .ok()?
+            .direction(AudioDirection::Input)
+            .sample_rate(SAMPLE_RATE)
+            .channel_count(CHANNELS as i32)
+            .format(AudioFormat::PCM_Float)
+            .performance_mode(AudioPerformanceMode::LowLatency)
+            .sharing_mode(AudioSharingMode::Shared)
+            .data_callback(Box::new(callback))
+            .error_callback(Box::new(|_s, e| {
+                log::warn!("mic: AAudio error (device reroute/disconnect?): {e:?}");
+            }))
+            .open_stream()
+            .map_err(|e| log::error!("mic: open_stream (RECORD_AUDIO granted?): {e}"))
+            .ok()?;
+
+        if let Err(e) = stream.request_start() {
+            log::error!("mic: request_start: {e}");
+            return None;
+        }
+        log::info!(
+            "mic: AAudio input started rate={} ch={} fmt={:?}",
+            stream.sample_rate(),
+            stream.channel_count(),
+            stream.format(),
+        );
+
+        let shutdown = Arc::new(AtomicBool::new(false));
+        let sd = shutdown.clone();
+        let join = std::thread::Builder::new()
+            .name("pf-mic".into())
+            .spawn(move || encode_loop(client, rx, sd, captured))
+            .ok();
+
+        Some(MicCapture {
+            _stream: stream,
+            shutdown,
+            join,
+        })
+    }
+}
+
+impl Drop for MicCapture {
+    fn drop(&mut self) {
+        self.shutdown.store(true, Ordering::SeqCst);
+        if let Some(j) = self.join.take() {
+            let _ = j.join();
+        }
+        // `_stream` drops here → AAudio request_stop + close.
+    }
+}
+
+/// Consumer: drain captured f32 → accumulate → Opus `encode_float` 20 ms stereo frames → `send_mic`.
+fn encode_loop(
+    client: Arc<NativeClient>,
+    rx: Receiver<Vec<f32>>,
+    shutdown: Arc<AtomicBool>,
+    captured: Arc<AtomicU64>,
+) {
+    let mut enc = match opus::Encoder::new(
+        SAMPLE_RATE as u32,
+        opus::Channels::Stereo,
+        opus::Application::Voip,
+    ) {
+        Ok(e) => e,
+        Err(e) => {
+            log::error!("mic: opus encoder init: {e} — mic disabled");
+            return;
+        }
+    };
+    let _ = enc.set_bitrate(opus::Bitrate::Bits(MIC_BITRATE));
+
+    let frame = FRAME_SAMPLES * CHANNELS;
+    let mut ring: VecDeque<f32> = VecDeque::with_capacity(frame * 4);
+    let mut out = vec![0u8; 4000]; // max Opus packet for a 20 ms frame fits easily
+    let mut seq: u32 = 0;
+    let mut sent: u64 = 0;
+    let mut peak = 0f32; // loudest |sample| since the last log — tells speech from silence
+
+    while !shutdown.load(Ordering::Relaxed) {
+        match rx.recv_timeout(Duration::from_millis(100)) {
+            Ok(chunk) => ring.extend(chunk),
+            Err(RecvTimeoutError::Timeout) => continue, // wake to re-check shutdown
+            Err(RecvTimeoutError::Disconnected) => break,
+        }
+        while ring.len() >= frame {
+            let pcm: Vec<f32> = ring.drain(..frame).collect();
+            for &s in &pcm {
+                peak = peak.max(s.abs());
+            }
+            match enc.encode_float(&pcm, &mut out) {
+                Ok(len) => {
+                    let pts = SystemTime::now()
+                        .duration_since(UNIX_EPOCH)
+                        .map(|d| d.as_nanos() as u64)
+                        .unwrap_or(0);
+                    let _ = client.send_mic(seq, pts, out[..len].to_vec());
+                    seq = seq.wrapping_add(1);
+                    sent += 1;
+                    if sent % 250 == 0 {
+                        log::info!(
+                            "mic: sent={sent} captured_frames={} peak={peak:.3}",
+                            captured.load(Ordering::Relaxed),
+                        );
+                        peak = 0.0;
+                    }
+                }
+                Err(e) => log::debug!("mic: opus encode: {e}"),
+            }
+        }
+    }
+    log::info!(
+        "mic: stopped (sent={sent} captured_frames={})",
+        captured.load(Ordering::Relaxed),
+    );
+}

clients/android/native/src/session.rs

@@ -0,0 +1,610 @@
+//! Session lifecycle + plane wiring over JNI.
+//!
+//! A connected session is a [`SessionHandle`] — an `Arc<NativeClient>` plus the decode thread it
+//! feeds — boxed and handed to Kotlin as an opaque `jlong`. The connector is `Sync`, so the decode
+//! thread pulls the video plane (`next_frame`) directly while Kotlin still holds the handle.
+//!
+//! Wired: connect/close, the video plane (HEVC `next_frame` → NDK AMediaCodec → the SurfaceView's
+//! `ANativeWindow`, see [`crate::decode`]), host→client audio ([`crate::audio`]), input
+//! (`send_input` — mouse/keyboard/gamepad), rumble/DualSense HID feedback ([`crate::feedback`]),
+//! and the trust surface: `nativeGenerateIdentity` (persistent identity, Keystore-wrapped on the
+//! Kotlin side), `nativeConnect` with identity + pin (TOFU / pinned), and `nativePair` (SPAKE2 PIN).
+//!
+//! TODO(M4 Android stage 1): client→host DualSense rich input (`send_rich_input`), mode
+//! renegotiation. Port the remaining orchestration from `clients/linux`.
+
+use jni::objects::{JObject, JString};
+use jni::sys::{jboolean, jint, jlong};
+use jni::JNIEnv;
+use punktfunk_core::client::NativeClient;
+use punktfunk_core::config::{CompositorPref, GamepadPref, Mode};
+use punktfunk_core::input::{InputEvent, InputKind};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use std::thread::JoinHandle;
+use std::time::Duration;
+
+/// A live session behind the `jlong` handle: the connector + the decode thread it feeds.
+pub(crate) struct SessionHandle {
+    // Read only by the android decode path (`nativeStartVideo` → `crate::decode`); on the host
+    // build (CI's workspace clippy/build) those readers are cfg'd out, so it's intentionally unused.
+    #[cfg_attr(not(target_os = "android"), allow(dead_code))]
+    pub client: Arc<NativeClient>,
+    video: Mutex<Option<VideoThread>>,
+    #[cfg(target_os = "android")]
+    audio: Mutex<Option<crate::audio::AudioPlayback>>,
+    #[cfg(target_os = "android")]
+    mic: Mutex<Option<crate::mic::MicCapture>>,
+}
+
+struct VideoThread {
+    shutdown: Arc<AtomicBool>,
+    join: Option<JoinHandle<()>>,
+}
+
+impl SessionHandle {
+    /// Signal the decode thread to stop and join it. Idempotent.
+    fn stop_video(&self) {
+        if let Some(mut vt) = self.video.lock().unwrap().take() {
+            vt.shutdown.store(true, Ordering::SeqCst);
+            if let Some(j) = vt.join.take() {
+                let _ = j.join();
+            }
+        }
+    }
+
+    /// Stop + close audio playback. Dropping the [`crate::audio::AudioPlayback`] joins its decode
+    /// thread and closes the AAudio stream. Idempotent.
+    #[cfg(target_os = "android")]
+    fn stop_audio(&self) {
+        let _ = self.audio.lock().unwrap().take();
+    }
+
+    /// Stop mic uplink. Dropping the [`crate::mic::MicCapture`] joins its encode thread and closes
+    /// the AAudio input stream. Idempotent.
+    #[cfg(target_os = "android")]
+    fn stop_mic(&self) {
+        let _ = self.mic.lock().unwrap().take();
+    }
+}
+
+impl Drop for SessionHandle {
+    fn drop(&mut self) {
+        self.stop_video();
+        #[cfg(target_os = "android")]
+        self.stop_audio();
+        #[cfg(target_os = "android")]
+        self.stop_mic();
+    }
+}
+
+/// SHA-256 fingerprint → 64 lowercase hex chars (matches the host log + client-rs).
+fn hex32(fp: &[u8; 32]) -> String {
+    use std::fmt::Write;
+    fp.iter().fold(String::with_capacity(64), |mut s, b| {
+        let _ = write!(s, "{b:02x}");
+        s
+    })
+}
+
+/// 64-hex → [u8; 32]; `None` on bad length/char.
+fn parse_hex32(s: &str) -> Option<[u8; 32]> {
+    if s.len() != 64 {
+        return None;
+    }
+    let mut out = [0u8; 32];
+    for (i, b) in out.iter_mut().enumerate() {
+        *b = u8::from_str_radix(&s[2 * i..2 * i + 2], 16).ok()?;
+    }
+    Some(out)
+}
+
+/// `NativeBridge.nativeGenerateIdentity(): String` — mint a fresh persistent self-signed identity.
+/// Returns `"<certPem>\n-----PUNKTFUNK-KEY-----\n<keyPem>"`, or `""` on failure (logged). Kotlin
+/// persists it (Keystore-wrapped) and only calls this again when the store is genuinely empty.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeGenerateIdentity<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+) -> jni::sys::jstring {
+    let out = match punktfunk_core::quic::endpoint::generate_identity() {
+        Ok((cert, key)) => format!("{cert}\n-----PUNKTFUNK-KEY-----\n{key}"),
+        Err(e) => {
+            log::error!("nativeGenerateIdentity failed: {e}");
+            String::new()
+        }
+    };
+    match env.new_string(out) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}
+
+/// `NativeBridge.nativeConnect(host, port, w, h, hz, certPem, keyPem, pinHex, bitrateKbps,
+/// compositorPref, gamepadPref): Long`. `certPem`/`keyPem` empty = anonymous, else presented as the
+/// persistent identity. `pinHex` empty = TOFU (read `nativeHostFingerprint` after), else 64-hex
+/// SHA-256 to pin the host (mismatch → 0). `bitrateKbps` 0 = host default. `compositorPref`/
+/// `gamepadPref` are `CompositorPref`/`GamepadPref` wire bytes (0 = Auto; unknown → Auto).
+/// Returns an opaque handle, or 0 on failure (logged).
+#[no_mangle]
+#[allow(clippy::too_many_arguments)]
+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,
+    cert_pem: JString<'local>,
+    key_pem: JString<'local>,
+    pin_hex: JString<'local>,
+    bitrate_kbps: jint,
+    compositor_pref: jint,
+    gamepad_pref: jint,
+) -> jlong {
+    let host: String = match env.get_string(&host) {
+        Ok(s) => s.into(),
+        Err(_) => return 0,
+    };
+    let cert: String = env
+        .get_string(&cert_pem)
+        .map(Into::into)
+        .unwrap_or_default();
+    let key: String = env.get_string(&key_pem).map(Into::into).unwrap_or_default();
+    let pin_hex: String = env.get_string(&pin_hex).map(Into::into).unwrap_or_default();
+
+    let identity: Option<(String, String)> = if cert.is_empty() || key.is_empty() {
+        None
+    } else {
+        Some((cert, key))
+    };
+    let pin: Option<[u8; 32]> = if pin_hex.is_empty() {
+        None
+    } else {
+        match parse_hex32(&pin_hex) {
+            Some(fp) => Some(fp),
+            None => {
+                log::error!("nativeConnect: bad pin hex (len {})", pin_hex.len());
+                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::from_u8(compositor_pref.clamp(0, u8::MAX as jint) as u8),
+        GamepadPref::from_u8(gamepad_pref.clamp(0, u8::MAX as jint) as u8),
+        bitrate_kbps.max(0) as u32, // 0 = host default
+        0,                          // video_caps: 8-bit only on Android for now
+        None,                       // launch: default app
+        pin,                        // Some → Crypto on host-fp mismatch
+        identity,                   // owned (cert, key) PEM, or None (anonymous)
+        Duration::from_secs(10),
+    ) {
+        Ok(client) => {
+            let handle = SessionHandle {
+                client: Arc::new(client),
+                video: Mutex::new(None),
+                #[cfg(target_os = "android")]
+                audio: Mutex::new(None),
+                #[cfg(target_os = "android")]
+                mic: Mutex::new(None),
+            };
+            Box::into_raw(Box::new(handle)) as jlong
+        }
+        Err(e) => {
+            log::error!("nativeConnect to {host}:{port} failed: {e}");
+            0
+        }
+    }
+}
+
+/// `NativeBridge.nativeClose(handle)` — drop the session (stops the decode thread, then RAII-tears
+/// down the connector). No-op on `0`.
+///
+/// # Safety contract
+/// `handle` must be `0` or a live handle from [`Java_io_unom_punktfunk_kit_NativeBridge_nativeConnect`],
+/// closed exactly once and not concurrently with other calls on the same handle (Kotlin owns this).
+#[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, `handle` is a live `Box<SessionHandle>` pointer.
+        unsafe { drop(Box::from_raw(handle as *mut SessionHandle)) };
+    }
+}
+
+/// `NativeBridge.nativeHostFingerprint(handle): String` — the SHA-256 (64-hex) of the cert the host
+/// presented on this connection. Valid after a successful `nativeConnect`; Kotlin pins it on a TOFU
+/// connect. `""` on a `0` handle.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeHostFingerprint<'local>(
+    env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    handle: jlong,
+) -> jni::sys::jstring {
+    let out = if handle == 0 {
+        String::new()
+    } else {
+        // SAFETY: live handle per the nativeConnect/nativeClose contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        hex32(&h.client.host_fingerprint)
+    };
+    match env.new_string(out) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}
+
+/// `NativeBridge.nativePair(host, port, certPem, keyPem, pin, name): String` — run the SPAKE2 PIN
+/// ceremony, presenting our persistent identity. On success returns the host's verified fingerprint
+/// (64-hex) to persist + pin; on any failure (wrong PIN / MITM / host reject / unreachable) returns
+/// `""` (logged). Blocking — Kotlin calls it off the UI thread.
+#[no_mangle]
+#[allow(clippy::too_many_arguments)]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativePair<'local>(
+    mut env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    host: JString<'local>,
+    port: jint,
+    cert_pem: JString<'local>,
+    key_pem: JString<'local>,
+    pin: JString<'local>,
+    name: JString<'local>,
+) -> jni::sys::jstring {
+    let g = |e: &mut JNIEnv<'local>, j: &JString<'local>| -> String {
+        e.get_string(j).map(Into::into).unwrap_or_default()
+    };
+    let host = g(&mut env, &host);
+    let cert = g(&mut env, &cert_pem);
+    let key = g(&mut env, &key_pem);
+    let pin = g(&mut env, &pin);
+    let name = g(&mut env, &name);
+
+    let out = if host.is_empty() || cert.is_empty() || key.is_empty() {
+        log::error!("nativePair: missing host/identity");
+        String::new()
+    } else {
+        match NativeClient::pair(
+            &host,
+            port as u16,
+            (&cert, &key), // borrowed identity
+            &pin,
+            &name,
+            Duration::from_secs(60),
+        ) {
+            Ok(host_fp) => hex32(&host_fp),
+            Err(e) => {
+                // Crypto error == wrong PIN / MITM; anything else == transport/host reject.
+                log::error!("nativePair to {host}:{port} failed: {e}");
+                String::new()
+            }
+        }
+    };
+    match env.new_string(out) {
+        Ok(s) => s.into_raw(),
+        Err(_) => JObject::null().into_raw(),
+    }
+}
+
+/// `NativeBridge.nativeStartVideo(handle, surface)` — wrap the SurfaceView's `Surface` as an
+/// `ANativeWindow` and start the HEVC decode thread rendering onto it. No-op if already started.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartVideo(
+    env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    surface: JObject,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let mut guard = h.video.lock().unwrap();
+    if guard.is_some() {
+        return; // already streaming
+    }
+    // SAFETY: `env`/`surface` are valid JNI pointers for this call. `as *mut _` bridges any
+    // jni-sys version skew between the `jni` and `ndk` crates (both are raw `*mut _` pointers).
+    let window = match unsafe {
+        ndk::native_window::NativeWindow::from_surface(
+            env.get_native_interface() as *mut _,
+            surface.as_raw() as *mut _,
+        )
+    } {
+        Some(w) => w,
+        None => {
+            log::error!("nativeStartVideo: no ANativeWindow from Surface");
+            return;
+        }
+    };
+    let shutdown = Arc::new(AtomicBool::new(false));
+    let client = h.client.clone();
+    let sd = shutdown.clone();
+    let join = std::thread::Builder::new()
+        .name("pf-decode".into())
+        .spawn(move || crate::decode::run(client, window, sd))
+        .ok();
+    *guard = Some(VideoThread { shutdown, join });
+}
+
+/// `NativeBridge.nativeStopVideo(handle)` — stop + join the decode thread (without closing the
+/// session). No-op on `0`.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopVideo(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle != 0 {
+        // SAFETY: live handle per the contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        h.stop_video();
+    }
+}
+
+/// `NativeBridge.nativeStartAudio(handle)` — start the Opus→AAudio playback thread. No-op if already
+/// started or on a `0` handle. Best-effort: a failure leaves video streaming.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartAudio(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let mut guard = h.audio.lock().unwrap();
+    if guard.is_some() {
+        return; // already playing
+    }
+    match crate::audio::AudioPlayback::start(h.client.clone()) {
+        Some(p) => *guard = Some(p),
+        None => log::error!("nativeStartAudio: playback init failed (video unaffected)"),
+    }
+}
+
+/// `NativeBridge.nativeStopAudio(handle)` — stop + join the audio thread and close AAudio (without
+/// closing the session). No-op on `0`.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopAudio(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle != 0 {
+        // SAFETY: live handle per the contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        h.stop_audio();
+    }
+}
+
+/// `NativeBridge.nativeStartMic(handle)` — start mic capture (AAudio input → Opus → host `send_mic`).
+/// No-op if already running or on a `0` handle. Caller MUST hold RECORD_AUDIO; a failure (e.g. no
+/// permission) leaves the rest of the session streaming.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStartMic(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let mut guard = h.mic.lock().unwrap();
+    if guard.is_some() {
+        return; // already capturing
+    }
+    match crate::mic::MicCapture::start(h.client.clone()) {
+        Some(m) => *guard = Some(m),
+        None => log::error!("nativeStartMic: mic init failed (RECORD_AUDIO? — session unaffected)"),
+    }
+}
+
+/// `NativeBridge.nativeStopMic(handle)` — stop + join the mic thread and close the AAudio input
+/// stream (without closing the session). No-op on `0`.
+#[cfg(target_os = "android")]
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeStopMic(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+) {
+    if handle != 0 {
+        // SAFETY: live handle per the contract.
+        let h = unsafe { &*(handle as *const SessionHandle) };
+        h.stop_mic();
+    }
+}
+
+// ---- Input plane: Kotlin capture → NativeClient::send_input ----------------------------------
+// All four are `&self` on the `Sync` connector (send_input is a non-blocking datagram push), safe
+// from the Kotlin UI thread. NOT android-gated — send_input exists on the host build too, so these
+// compile everywhere (parity with nativeConnect/nativeClose). The wire codes are the GameStream
+// conventions: buttons 1=left/2=middle/3=right/4=X1/5=X2; scroll axis 0=vertical/1=horizontal,
+// signed 120-unit delta, +=up/right; keys are Windows VK (mapped from KEYCODE_* on the Kotlin side).
+
+/// `NativeBridge.nativeSendPointerMove(handle, dx, dy)` — relative mouse motion (screen +y down).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerMove(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    dx: jint,
+    dy: jint,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the nativeConnect/nativeClose contract; send_input is &self.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: InputKind::MouseMove,
+        _pad: [0; 3],
+        code: 0,
+        x: dx,
+        y: dy,
+        flags: 0,
+    });
+}
+
+/// `NativeBridge.nativeSendPointerButton(handle, button, down)` — one button transition.
+/// `button`: GameStream id (1=left, 2=middle, 3=right, 4=X1, 5=X2). `down`: 1=press, 0=release.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendPointerButton(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    button: jint,
+    down: jboolean,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: if down != 0 {
+            InputKind::MouseButtonDown
+        } else {
+            InputKind::MouseButtonUp
+        },
+        _pad: [0; 3],
+        code: button as u32,
+        x: 0,
+        y: 0,
+        flags: 0,
+    });
+}
+
+/// `NativeBridge.nativeSendScroll(handle, axis, delta)` — one scroll step. `axis`: 0=vertical,
+/// 1=horizontal. `delta`: signed, WHEEL_DELTA(120)-scaled, +=up/right.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendScroll(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    axis: jint,
+    delta: jint,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: InputKind::MouseScroll,
+        _pad: [0; 3],
+        code: axis as u32,
+        x: delta,
+        y: 0,
+        flags: 0,
+    });
+}
+
+/// `NativeBridge.nativeSendKey(handle, vk, down, mods)` — one key transition. `vk`: Windows
+/// Virtual-Key code (0 = unmapped → dropped). `down`: 1=press, 0=release. `mods`: VK modifier
+/// bitmask (0 for now — the host folds modifiers from the L/R modifier key events themselves).
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendKey(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    vk: jint,
+    down: jboolean,
+    mods: jint,
+) {
+    if handle == 0 || vk == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: if down != 0 {
+            InputKind::KeyDown
+        } else {
+            InputKind::KeyUp
+        },
+        _pad: [0; 3],
+        code: vk as u32,
+        x: 0,
+        y: 0,
+        flags: mods as u32,
+    });
+}
+
+// ---- Gamepad: Kotlin captures (KeyEvent/MotionEvent) → NativeClient::send_input ---------------
+// Single-pad model: exactly one controller, forwarded as pad 0 (flags = 0). Buttons carry the
+// gamepad::BTN_* bit in `code` and pressed/released in `x` (1/0); axes carry the gamepad::AXIS_* id
+// in `code` and the value in `x` (sticks i16 −32768..32767, +y = up; triggers 0..255). The host
+// accumulates the incremental events into its virtual xpad. Wire contract: input.rs::gamepad.
+
+/// `NativeBridge.nativeSendGamepadButton(handle, bit, down)` — one gamepad button transition.
+/// `bit`: a `gamepad::BTN_*` bit (e.g. BTN_A = 0x1000). `down`: 1=press, 0=release.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadButton(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    bit: jint,
+    down: jboolean,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: InputKind::GamepadButton,
+        _pad: [0; 3],
+        code: bit as u32,
+        x: i32::from(down != 0),
+        y: 0,
+        flags: 0, // pad index 0 — single-pad model
+    });
+}
+
+/// `NativeBridge.nativeSendGamepadAxis(handle, axisId, value)` — one gamepad axis update.
+/// `axisId`: a `gamepad::AXIS_*` id (LS_X=0..RT=5). `value`: stick i16 (−32768..32767, +y=up) or
+/// trigger 0..255.
+#[no_mangle]
+pub extern "system" fn Java_io_unom_punktfunk_kit_NativeBridge_nativeSendGamepadAxis(
+    _env: JNIEnv,
+    _this: JObject,
+    handle: jlong,
+    axis_id: jint,
+    value: jint,
+) {
+    if handle == 0 {
+        return;
+    }
+    // SAFETY: live handle per the contract.
+    let h = unsafe { &*(handle as *const SessionHandle) };
+    let _ = h.client.send_input(&InputEvent {
+        kind: InputKind::GamepadAxis,
+        _pad: [0; 3],
+        code: axis_id as u32,
+        x: value,
+        y: 0,
+        flags: 0, // pad index 0 — single-pad model
+    });
+}