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>
2026-06-15 01:37:46 +02:00
parent c9e90d4a59
commit 79217eb93d
24 changed files with 1040 additions and 15 deletions
@@ -0,0 +1,11 @@
+# Gradle / Android build artifacts
+.gradle/
+build/
+local.properties
+*.iml
+.idea/
+captures/
+.cxx/
+
+# Native libraries produced by cargo-ndk — regenerated by the :kit cargoNdk* tasks.
+**/src/main/jniLibs/
@@ -1,20 +1,69 @@
-# punktfunk Android client (later)
+# punktfunk Android client

-Kotlin UI + MediaCodec (decode) + a thin JNI layer over the `punktfunk-core` C ABI.
+Native Android client for **punktfunk/1**, targeting **phone + TV** (Compose, D-pad + touch).

-## Wiring
+## Architecture — Rust-heavy (like the Linux client, not thin-native like Apple)

-1. Build the core as a shared library per Android ABI:
-   ```sh
-   rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android
-   cargo build -p punktfunk-core --release --target aarch64-linux-android   # libpunktfunk_core.so
-   ```
-   (Use `cargo-ndk` to handle the NDK toolchain/linker.)
-2. JNI shim: small C/Rust glue mapping `punktfunk_*` to Kotlin `external fun`s, bundling
-   `libpunktfunk_core.so` into the APK's `jniLibs/`.
-3. Kotlin: client `PunktfunkSession` → `punktfunk_client_poll_frame` on a decode thread → feed
-   `MediaCodec` → render to a `SurfaceView` aligned to the display refresh.
+Kotlin cannot `import` the cbindgen C header the way Swift can, so a native bridge is unavoidable.
+We write it in **Rust** and link `punktfunk-core` directly — so the Android client reuses the Linux
+client's orchestration (audio jitter ring, VK keymap inverse, latency/skew math, capture state
+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 |
+| **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_*`.
+
+## Layout
+
+```
+crates/punktfunk-android/          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
+
+clients/android/                   Gradle project (this dir)
+  settings.gradle.kts · build.gradle.kts · gradle.properties · gradlew
+  app/                             :app — Compose application (MainActivity)
+  kit/                             :kit — Android library: NativeBridge + the cargo-ndk build
+    build.gradle.kts               cargoNdk{Debug,Release} → src/main/jniLibs/<abi>/*.so
+```
+
+## Prerequisites (already set up on the dev Mac)
+
+- Android SDK + **NDK r28 LTS** (`28.2.13676358`), `platforms;android-37.0`, `build-tools;37.0.0`
+- **JDK 21** for Gradle/AGP (the machine default JDK 25 is too new for AGP 9.2)
+- Rust + `rustup target add aarch64-linux-android x86_64-linux-android` + `cargo install cargo-ndk`
+
+Toolchain pinned: AGP 9.2.0 · Gradle 9.4.1 · Kotlin 2.3.21 · Compose BOM 2026.05.01 ·
+compileSdk 37 · targetSdk 36 · minSdk 31 · ABIs arm64-v8a + x86_64.
+
+## Build & run
+
+**Android Studio:** open `clients/android` — it uses its bundled JBR 21 automatically. The
+`cargoNdk*` task builds the `.so` as part of the normal build.
+
+**CLI** (the machine default is JDK 25, so point Gradle at JDK 21):
+
+```sh
+export JAVA_HOME="$(brew --prefix openjdk@21)/libexec/openjdk.jdk/Contents/Home"
+cd clients/android
+./gradlew :app:assembleDebug      # cargo-ndk cross-compiles libpunktfunk_android.so first
+./gradlew :app:installDebug       # onto a running emulator/device
+
+# Emulators (created during env setup):  emulator -avd pf_phone   |   emulator -avd pf_tv
+```
+
+The debug APK lands in `app/build/outputs/apk/debug/`. The scaffold screen calls
+`NativeBridge.abiVersion()` across JNI — a live ABI version proves the whole native stack is wired.

 ## Status

-Placeholder — scheduled after the Apple client (M5).
+- **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
+  (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`.
@@ -0,0 +1,67 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+plugins {
+    id("com.android.application")
+    // AGP 9 built-in Kotlin: NO org.jetbrains.kotlin.android. The Compose compiler plugin is
+    // supplied by AGP, so it's applied without a version.
+    id("org.jetbrains.kotlin.plugin.compose")
+}
+
+android {
+    namespace = "io.unom.punktfunk"
+    compileSdk = 37 // Android 17 — required by androidx.core 1.19.0; targetSdk stays 36 for now.
+
+    defaultConfig {
+        applicationId = "io.unom.punktfunk"
+        minSdk = 31
+        targetSdk = 36
+        versionCode = 1
+        versionName = "0.0.1"
+        ndk { abiFilters += listOf("arm64-v8a", "x86_64") }
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false // scaffold; enable R8 + shrinkResources later
+        }
+    }
+
+    buildFeatures { compose = true }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_21
+        targetCompatibility = JavaVersion.VERSION_21
+    }
+    packaging {
+        jniLibs {
+            useLegacyPackaging = false
+            // punktfunk-core is statically linked into libpunktfunk_android.so (rlib). Its standalone
+            // cdylib (built because the core crate also declares crate-type = cdylib) is never loaded
+            // by Kotlin — drop it from the APK rather than ship ~5–9 MB of dead code.
+            excludes += "**/libpunktfunk_core.so"
+        }
+    }
+}
+
+kotlin { compilerOptions { jvmTarget.set(JvmTarget.JVM_21) } }
+
+dependencies {
+    implementation(project(":kit"))
+
+    val composeBom = platform("androidx.compose:compose-bom:2026.05.01")
+    implementation(composeBom)
+
+    implementation("androidx.core:core-ktx:1.19.0")
+    implementation("androidx.activity:activity-compose:1.13.0")
+    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.10.0")
+
+    implementation("androidx.compose.ui:ui")
+    implementation("androidx.compose.ui:ui-tooling-preview")
+    implementation("androidx.compose.foundation:foundation")
+    implementation("androidx.compose.material3:material3")
+    debugImplementation("androidx.compose.ui:ui-tooling")
+
+    // Android TV components (we target phone + TV) land in the TV-UI milestone:
+    //   implementation("androidx.tv:tv-material:1.1.0")
+    // The manifest already declares leanback so the scaffold installs on TV.
+}
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- punktfunk/1 QUIC/UDP data plane. -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <!-- mDNS discovery of _punktfunk._udp on the LAN (NsdManager). -->
+    <uses-permission
+        android:name="android.permission.NEARBY_WIFI_DEVICES"
+        android:usesPermissionFlags="neverForLocation" />
+    <!-- Enforced from Android 17 (SDK 37) for ALL local-network traffic incl. the QUIC socket.
+         Harmless to declare on earlier releases. -->
+    <uses-permission android:name="android.permission.ACCESS_LOCAL_NETWORK" />
+    <!-- Mic uplink to the host's virtual microphone (requested at runtime). -->
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <!-- Gamepad rumble feedback. -->
+    <uses-permission android:name="android.permission.VIBRATE" />
+
+    <!-- We target phone + TV from day one: keep the app installable on TV (no touchscreen) and on
+         devices without a gamepad. -->
+    <uses-feature android:name="android.hardware.touchscreen" android:required="false" />
+    <uses-feature android:name="android.software.leanback" android:required="false" />
+    <uses-feature android:name="android.hardware.gamepad" android:required="false" />
+
+    <application
+        android:allowBackup="true"
+        android:icon="@android:drawable/sym_def_app_icon"
+        android:label="@string/app_name"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.PunktfunkAndroid">
+
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:configChanges="orientation|screenSize|keyboardHidden|screenLayout|density|navigation"
+            android:theme="@style/Theme.PunktfunkAndroid">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+                <!-- TV launcher entry. -->
+                <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+</manifest>
@@ -0,0 +1,59 @@
+package io.unom.punktfunk
+
+import android.os.Bundle
+import android.util.Log
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import io.unom.punktfunk.kit.NativeBridge
+
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        // Cross the JNI bridge into libpunktfunk_android.so → punktfunk-core. A live ABI version is
+        // the scaffold's proof the whole native stack is wired (cargo-ndk → jniLibs → APK →
+        // System.loadLibrary → JNI → core). Logged so it's verifiable headlessly via logcat.
+        val abi = runCatching { NativeBridge.abiVersion() }.getOrDefault(-1)
+        val core = runCatching { NativeBridge.coreVersion() }.getOrDefault("?")
+        Log.i("punktfunk", "native bridge: core ABI v$abi, core $core")
+
+        enableEdgeToEdge()
+        setContent {
+            MaterialTheme(colorScheme = darkColorScheme()) {
+                Surface(modifier = Modifier.fillMaxSize()) {
+                    ScaffoldScreen(abi, core)
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun ScaffoldScreen(abi: Int, core: String) {
+    Column(
+        modifier = Modifier.fillMaxSize().padding(24.dp),
+        horizontalAlignment = Alignment.CenterHorizontally,
+        verticalArrangement = Arrangement.Center,
+    ) {
+        Text("punktfunk", style = MaterialTheme.typography.headlineMedium)
+        Text("Android client — scaffold", style = MaterialTheme.typography.bodyMedium)
+        Text(
+            if (abi > 0) "✓ native bridge linked" else "✗ native bridge FAILED",
+            style = MaterialTheme.typography.titleMedium,
+        )
+        Text("core ABI v$abi · core $core", style = MaterialTheme.typography.bodySmall)
+    }
+}
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">punktfunk</string>
+</resources>
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- The Activity is pure Compose; this platform theme just provides a no-action-bar host.
+         Compose draws its own Material 3 surfaces over it. -->
+    <style name="Theme.PunktfunkAndroid" parent="android:Theme.Material.NoActionBar" />
+</resources>
@@ -0,0 +1,11 @@
+// Root build file. AGP 9.2.0 has BUILT-IN Kotlin support — modules do NOT apply
+// org.jetbrains.kotlin.android (it's an error under AGP 9). The Compose compiler plugin is declared
+// here (version + apply false) so modules can apply it version-less; its version pins the build's
+// Kotlin (compose-compiler and Kotlin release in lockstep), keeping them matched.
+// Toolchain: AGP 9.2.0 · Gradle 9.4.1 · Kotlin/Compose-compiler 2.3.21 · JDK 21 · Compose BOM
+// 2026.05.01 · compileSdk 37 · targetSdk 36 · minSdk 31.
+plugins {
+    id("com.android.application") version "9.2.0" apply false
+    id("com.android.library") version "9.2.0" apply false
+    id("org.jetbrains.kotlin.plugin.compose") version "2.3.21" apply false
+}
@@ -0,0 +1,16 @@
+org.gradle.jvmargs=-Xmx4g -Dfile.encoding=UTF-8
+org.gradle.caching=true
+# Configuration cache: off for now — the cargo-ndk Exec task graph is simpler to reason about
+# during the scaffold. Enable once the native-build wiring is stable.
+org.gradle.configuration-cache=false
+
+android.useAndroidX=true
+android.nonTransitiveRClass=true
+
+kotlin.code.style=official
+
+# Gradle/AGP 9.2 must RUN on JDK 17–21 — NOT this machine's default JDK 25.
+#  * Android Studio uses its bundled JBR 21 automatically (no config needed).
+#  * CLI builds: launch gradlew with JDK 21, e.g.
+#      JAVA_HOME="$(brew --prefix openjdk@21)/libexec/openjdk.jdk/Contents/Home" ./gradlew assembleDebug
+# Intentionally NOT setting org.gradle.java.home here — it would hardcode a machine-specific path.
@@ -0,0 +1,9 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.4.1-bin.zip
+networkTimeout=10000
+retries=0
+retryBackOffMs=500
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
@@ -0,0 +1,248 @@
+#!/bin/sh
+
+#
+# Copyright © 2015 the original authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+##############################################################################
+#
+#   Gradle start up script for POSIX generated by Gradle.
+#
+#   Important for running:
+#
+#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+#       noncompliant, but you have some other compliant shell such as ksh or
+#       bash, then to run this script, type that shell name before the whole
+#       command line, like:
+#
+#           ksh Gradle
+#
+#       Busybox and similar reduced shells will NOT work, because this script
+#       requires all of these POSIX shell features:
+#         * functions;
+#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+#         * compound commands having a testable exit status, especially «case»;
+#         * various built-in commands including «command», «set», and «ulimit».
+#
+#   Important for patching:
+#
+#   (2) This script targets any POSIX shell, so it avoids extensions provided
+#       by Bash, Ksh, etc; in particular arrays are avoided.
+#
+#       The "traditional" practice of packing multiple parameters into a
+#       space-separated string is a well documented source of bugs and security
+#       problems, so this is (mostly) avoided, by progressively accumulating
+#       options in "$@", and eventually passing that to Java.
+#
+#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+#       see the in-line comments for details.
+#
+#       There are tweaks for specific operating systems such as AIX, CygWin,
+#       Darwin, MinGW, and NonStop.
+#
+#   (3) This script is generated from the Groovy template
+#       https://github.com/gradle/gradle/blob/3d91ce3b8caaf77ad09f381f43615b715b53f72c/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       within the Gradle project.
+#
+#       You can find Gradle at https://github.com/gradle/gradle/.
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
+done
+
+# This is normally unused
+# shellcheck disable=SC2034
+APP_BASE_NAME=${0##*/}
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s\n' "$PWD" ) || exit
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+    echo "$*"
+} >&2
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
+esac
+
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD=$JAVA_HOME/jre/sh/java
+    else
+        JAVACMD=$JAVA_HOME/bin/java
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD=java
+    if ! command -v java >/dev/null 2>&1
+    then
+        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
+    esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                            # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                      #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -jar "$APP_HOME/gradle/wrapper/gradle-wrapper.jar" \
+        "$@"
+
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
+
+exec "$JAVACMD" "$@"
@@ -0,0 +1,82 @@
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
+
+@if "%DEBUG%"=="" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables, and ensure extensions are enabled
+setlocal EnableExtensions
+
+set DIRNAME=%~dp0
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if %ERRORLEVEL% equ 0 goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+"%COMSPEC%" /c exit 1
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+"%COMSPEC%" /c exit 1
+
+:execute
+@rem Setup the command line
+
+
+
+@rem Execute Gradle
+@rem endlocal doesn't take effect until after the line is parsed and variables are expanded
+@rem which allows us to clear the local environment before executing the java command
+endlocal & "%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -jar "%APP_HOME%\gradle\wrapper\gradle-wrapper.jar" %* & call :exitWithErrorLevel
+
+:exitWithErrorLevel
+@rem Use "%COMSPEC%" /c exit to allow operators to work properly in scripts
+"%COMSPEC%" /c exit %ERRORLEVEL%
@@ -0,0 +1,80 @@
+import java.io.File
+import java.util.Properties
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+plugins {
+    // AGP 9 built-in Kotlin compiles this module's Kotlin (NativeBridge) — no kotlin.android plugin.
+    id("com.android.library")
+}
+
+val ndkVer = "28.2.13676358" // r28 LTS — matches the SDK NDK installed for cargo-ndk
+
+android {
+    namespace = "io.unom.punktfunk.kit"
+    compileSdk = 37 // Android 17 — align with :app (androidx.core 1.19.0 requires it)
+    ndkVersion = ndkVer
+
+    defaultConfig {
+        minSdk = 31
+        ndk { abiFilters += listOf("arm64-v8a", "x86_64") }
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_21
+        targetCompatibility = JavaVersion.VERSION_21
+    }
+    packaging { jniLibs { useLegacyPackaging = false } } // 16 KB-page friendly
+}
+
+kotlin { compilerOptions { jvmTarget.set(JvmTarget.JVM_21) } }
+
+// ------------------------------------------------------------------------------------------------
+// cargo-ndk: cross-compile crates/punktfunk-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`.
+// ------------------------------------------------------------------------------------------------
+val repoRoot = rootDir.parentFile.parentFile // clients/android -> clients -> repo root
+val cargoBin = "${System.getProperty("user.home")}/.cargo/bin"
+
+// SDK location without depending on AGP's DSL (sdkDirectory isn't in AGP 9's library extension):
+// env first (set by Android Studio and by our CLI shell), then local.properties, then the default.
+fun androidSdkDir(): String {
+    System.getenv("ANDROID_HOME")?.let { return it }
+    System.getenv("ANDROID_SDK_ROOT")?.let { return it }
+    val lp = rootProject.file("local.properties")
+    if (lp.exists()) {
+        val props = Properties()
+        lp.inputStream().use { props.load(it) }
+        props.getProperty("sdk.dir")?.let { return it }
+    }
+    return "${System.getProperty("user.home")}/Library/Android/sdk"
+}
+
+fun registerCargoNdk(taskName: String, release: Boolean) =
+    tasks.register<Exec>(taskName) {
+        group = "rust"
+        description = "cargo-ndk build of punktfunk-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
+        // discoverable explicitly (works the same from a bare CLI).
+        environment("PATH", cargoBin + File.pathSeparator + System.getenv("PATH"))
+        environment("ANDROID_HOME", sdk)
+        environment("ANDROID_NDK_HOME", "$sdk/ndk/$ndkVer")
+        val cmd = mutableListOf(
+            "cargo", "ndk",
+            "-t", "arm64-v8a", "-t", "x86_64",
+            "-o", file("src/main/jniLibs").absolutePath,
+            "build", "-p", "punktfunk-android",
+        )
+        if (release) cmd += "--release"
+        commandLine(cmd)
+    }
+
+val cargoNdkDebug = registerCargoNdk("cargoNdkDebug", release = false)
+val cargoNdkRelease = registerCargoNdk("cargoNdkRelease", release = true)
+
+afterEvaluate {
+    tasks.named("preDebugBuild").configure { dependsOn(cargoNdkDebug) }
+    tasks.named("preReleaseBuild").configure { dependsOn(cargoNdkRelease) }
+}
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Library module manifest. The namespace lives in build.gradle.kts (AGP 9). -->
+<manifest />
@@ -0,0 +1,31 @@
+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 —
+ * all protocol logic lives in Rust (`punktfunk-core` + the connector); Kotlin only marshals.
+ */
+object NativeBridge {
+    init {
+        System.loadLibrary("punktfunk_android")
+    }
+
+    /** punktfunk-core C-ABI version. A successful call proves the native library is linked. */
+    external fun abiVersion(): Int
+
+    /** punktfunk-core crate version string. */
+    external fun coreVersion(): String
+
+    /**
+     * Connect to a host (trust-on-first-use, anonymous) and return an opaque session handle, or
+     * `0` on failure. Pair the handle with exactly one [nativeClose].
+     *
+     * TODO(M4): pin/identity/pairing, plane pumps (video/audio/rumble/HID), input, mode
+     * renegotiation — see `crates/punktfunk-android/src/session.rs`.
+     */
+    external fun nativeConnect(host: String, port: Int, width: Int, height: Int, refreshHz: Int): Long
+
+    /** Tear down a session handle returned by [nativeConnect]. No-op on `0`. */
+    external fun nativeClose(handle: Long)
+}
@@ -0,0 +1,17 @@
+pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+rootProject.name = "punktfunk-android"
+include(":app", ":kit")