feat(apple,android): three-way touch input — trackpad cursor (default), direct pointer, real multi-touch passthrough

The two touch clients had exactly complementary gaps: iOS forwarded fingers
ONLY as raw wire touches (no way to drive the host cursor from the touch
screen), Android had the two mouse modes but no passthrough. Both now share
one three-way "Touch input" setting: Trackpad (default) / Direct pointer /
Touch passthrough.

iOS/iPadOS: Input/TouchMouse.swift ports the Android gesture engine 1:1
(same px-based acceleration curve; tap=click, two-finger tap=right-click,
two-finger drag=scroll, tap-then-drag=held drag, three-finger tap=stats
HUD via the shared hudEnabled default); direct-pointer mode maps through
the aspect-fit letterbox; the previous always-on behavior lives on as the
passthrough option. The mode latches per gesture (a Settings change never
splits one gesture across models), touchesCancelled releases held state
without synthesizing a click, and session stop flushes a mid-drag button.
Settings picker on iPhone + iPad next to the iPad-only pointer-capture
toggle. Deliberate default change: trackpad, not passthrough.

Android: new nativeSendTouch JNI shim → wire TouchDown/Move/Up (the host
already injects real touch on every backend — libei touchscreen, wlroots,
KWin fake-input, SendInput); streamTouchPassthrough forwards every finger
with stable ids and lifts still-held contacts on teardown; the trackpadMode
Boolean becomes the TouchMode enum (old pref migrated on load, never
rewritten) with a Settings dropdown.

Verified: macOS swift build + full suite (incl. new TouchMouseTests), iOS
Simulator Swift compile, cargo check/fmt/clippy on the native crate, Kotlin
app+kit compile + unit tests. On-glass feel of the iOS ballistics and
Android passthrough against a touch-aware app still pending.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

clients/android/app/src/main/kotlin/io/unom/punktfunk/Settings.kt

@@ -33,13 +33,19 @@ data class Settings(
     /** Show the live stats overlay (FPS / throughput / latency) during a stream. */
     val statsHudEnabled: Boolean = true,
     /**
-     * Touch input model. `true` (default) = trackpad: the cursor stays put on touch-down and moves
-     * by the finger's relative delta (swipe to nudge, lift and re-swipe to walk it across), tap to
-     * click where it is. `false` = direct pointing: the cursor jumps to the finger (the old behaviour).
+     * Touch input model — how touchscreen fingers drive the host. [TouchMode.TRACKPAD] (default):
+     * the cursor stays put on touch-down and moves by the finger's relative delta (swipe to nudge,
+     * lift and re-swipe to walk it across), tap to click where it is. [TouchMode.POINTER]: the
+     * cursor jumps to the finger (direct pointing). [TouchMode.TOUCH]: real multi-touch
+     * passthrough — every finger reaches the host as a touchscreen contact, for apps/games that
+     * understand touch. Mirrors the Apple client's TouchInputMode.
      */
-    val trackpadMode: Boolean = true,
+    val touchMode: TouchMode = TouchMode.TRACKPAD,
 )
 
+/** [Settings.touchMode] values; persisted by name. */
+enum class TouchMode { TRACKPAD, POINTER, TOUCH }
+
 /** Loads/saves [Settings] in the app-private `punktfunk_settings` prefs. */
 class SettingsStore(context: Context) {
     private val prefs =
@@ -57,7 +63,10 @@ class SettingsStore(context: Context) {
         codec = prefs.getString(K_CODEC, "auto") ?: "auto",
         micEnabled = prefs.getBoolean(K_MIC, false),
         statsHudEnabled = prefs.getBoolean(K_HUD, true),
-        trackpadMode = prefs.getBoolean(K_TRACKPAD, true),
+        touchMode = prefs.getString(K_TOUCH_MODE, null)
+            ?.let { name -> TouchMode.entries.firstOrNull { it.name == name } }
+            // Migration: the pre-enum Boolean "trackpad_mode" (true = trackpad, false = direct).
+            ?: if (prefs.getBoolean(K_TRACKPAD, true)) TouchMode.TRACKPAD else TouchMode.POINTER,
     )
 
     fun save(s: Settings) {
@@ -73,7 +82,7 @@ class SettingsStore(context: Context) {
             .putString(K_CODEC, s.codec)
             .putBoolean(K_MIC, s.micEnabled)
             .putBoolean(K_HUD, s.statsHudEnabled)
-            .putBoolean(K_TRACKPAD, s.trackpadMode)
+            .putString(K_TOUCH_MODE, s.touchMode.name)
             .apply()
     }
 
@@ -89,6 +98,9 @@ class SettingsStore(context: Context) {
         const val K_CODEC = "codec"
         const val K_MIC = "mic_enabled"
         const val K_HUD = "stats_hud_enabled"
+        const val K_TOUCH_MODE = "touch_mode"
+
+        /** Legacy Boolean the enum replaced — read once as the migration default, never written. */
         const val K_TRACKPAD = "trackpad_mode"
     }
 }
@@ -195,6 +207,13 @@ val COMPOSITOR_OPTIONS = listOf(
     "gamescope",
 )
 
+/** (mode, label) for the touch-input model. */
+val TOUCH_MODE_OPTIONS = listOf(
+    TouchMode.TRACKPAD to "Trackpad",
+    TouchMode.POINTER to "Direct pointer",
+    TouchMode.TOUCH to "Touch passthrough",
+)
+
 /** index = GamepadPref wire byte (0=Auto 1=Xbox360 2=DualSense 3=XboxOne 4=DualShock4). */
 val GAMEPAD_OPTIONS = listOf(
     "Automatic",

clients/android/app/src/main/kotlin/io/unom/punktfunk/SettingsScreen.kt

@@ -165,13 +165,21 @@ fun SettingsScreen(initial: Settings, onChange: (Settings) -> Unit, onBack: () -
             )
         }
 
-        SettingsGroup("Pointer") {
-            ToggleRow(
-                title = "Trackpad mode",
-                subtitle = "Relative cursor like a laptop touchpad — swipe to nudge, tap to click. " +
-                    "Off = the cursor jumps to your finger.",
-                checked = s.trackpadMode,
-                onCheckedChange = { on -> update(s.copy(trackpadMode = on)) },
+        SettingsGroup("Touch input") {
+            SettingDropdown(
+                label = "Touch input",
+                options = TOUCH_MODE_OPTIONS,
+                selected = s.touchMode,
+                onSelect = { mode -> update(s.copy(touchMode = mode)) },
+            )
+            Text(
+                "Trackpad: relative cursor like a laptop touchpad — tap to click, two-finger " +
+                    "tap right-clicks, two fingers scroll, tap-then-drag holds the button. " +
+                    "Direct pointer: the cursor jumps to your finger. Touch passthrough: real " +
+                    "multi-touch reaches the host, for apps that understand touch.",
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier.padding(top = 6.dp),
             )
         }
 

clients/android/app/src/main/kotlin/io/unom/punktfunk/StreamScreen.kt

@@ -57,7 +57,7 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
     var stats by remember { mutableStateOf<DoubleArray?>(null) }
     var showStats by remember { mutableStateOf(initialSettings.statsHudEnabled) }
     // Touch model is fixed per session (re-keys the gesture handler below if it ever changes).
-    val trackpad = initialSettings.trackpadMode
+    val touchMode = initialSettings.touchMode
     LaunchedEffect(handle, showStats) {
         NativeBridge.nativeSetVideoStatsEnabled(handle, showStats)
         if (showStats) {
@@ -148,11 +148,18 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
         if (showStats) {
             stats?.let { StatsOverlay(it, Modifier.align(Alignment.TopStart).padding(12.dp)) }
         }
-        // Touch → mouse (trackpad vs. direct pointing + the shared gesture vocabulary — see
-        // streamTouchInput in TouchInput.kt).
+        // Touch input per the Settings model: trackpad/direct-pointer mouse (the shared gesture
+        // vocabulary) or real multi-touch passthrough — see TouchInput.kt.
         Box(
-            Modifier.fillMaxSize().pointerInput(handle, trackpad) {
-                streamTouchInput(handle, trackpad, onToggleStats = { showStats = !showStats })
+            Modifier.fillMaxSize().pointerInput(handle, touchMode) {
+                when (touchMode) {
+                    TouchMode.TOUCH -> streamTouchPassthrough(handle)
+                    else -> streamTouchInput(
+                        handle,
+                        trackpad = touchMode == TouchMode.TRACKPAD,
+                        onToggleStats = { showStats = !showStats },
+                    )
+                }
             },
         )
     }

clients/android/app/src/main/kotlin/io/unom/punktfunk/TouchInput.kt

@@ -2,7 +2,11 @@ package io.unom.punktfunk
 
 import androidx.compose.foundation.gestures.awaitEachGesture
 import androidx.compose.foundation.gestures.awaitFirstDown
+import androidx.compose.ui.input.pointer.PointerId
 import androidx.compose.ui.input.pointer.PointerInputScope
+import androidx.compose.ui.input.pointer.changedToDownIgnoreConsumed
+import androidx.compose.ui.input.pointer.changedToUpIgnoreConsumed
+import androidx.compose.ui.input.pointer.positionChanged
 import io.unom.punktfunk.kit.NativeBridge
 import kotlin.math.abs
 import kotlin.math.hypot
@@ -38,6 +42,54 @@ private const val ACCEL_MAX = 3.0f
  * two-finger drag = scroll; tap-then-press-and-drag = left-drag (text selection / moving
  * windows); three-finger tap = [onToggleStats] (the stats HUD).
  */
+/**
+ * Real multi-touch passthrough ([TouchMode.TOUCH]): every finger forwards as a host touchscreen
+ * contact (down/move/up with a stable per-finger id), with NO gesture interpretation — taps,
+ * drags and multi-finger input mean whatever the remote app decides. Coordinates are overlay
+ * pixels with the overlay size as the surface, exactly like the absolute-mouse path (the host
+ * normalizes and maps into the output). On teardown (stream leaves composition) every still-held
+ * contact is lifted so nothing stays stuck on the host.
+ */
+internal suspend fun PointerInputScope.streamTouchPassthrough(handle: Long) {
+    val ids = mutableMapOf<PointerId, Int>()
+    fun alloc(p: PointerId): Int {
+        var id = 0
+        while (ids.containsValue(id)) id++
+        ids[p] = id
+        return id
+    }
+    try {
+        awaitPointerEventScope {
+            while (true) {
+                val ev = awaitPointerEvent()
+                val sw = size.width
+                val sh = size.height
+                if (sw <= 0 || sh <= 0) continue
+                for (c in ev.changes) {
+                    val x = c.position.x.roundToInt().coerceIn(0, sw - 1)
+                    val y = c.position.y.roundToInt().coerceIn(0, sh - 1)
+                    when {
+                        c.changedToDownIgnoreConsumed() ->
+                            NativeBridge.nativeSendTouch(handle, alloc(c.id), 0, x, y, sw, sh)
+                        c.changedToUpIgnoreConsumed() ->
+                            ids.remove(c.id)?.let {
+                                NativeBridge.nativeSendTouch(handle, it, 2, 0, 0, sw, sh)
+                            }
+                        c.positionChanged() ->
+                            ids[c.id]?.let {
+                                NativeBridge.nativeSendTouch(handle, it, 1, x, y, sw, sh)
+                            }
+                    }
+                    c.consume()
+                }
+            }
+        }
+    } finally {
+        // Lift anything still down (composition/session teardown mid-touch).
+        ids.values.forEach { NativeBridge.nativeSendTouch(handle, it, 2, 0, 0, 1, 1) }
+    }
+}
+
 internal suspend fun PointerInputScope.streamTouchInput(
     handle: Long,
     trackpad: Boolean,

clients/android/app/src/test/kotlin/io/unom/punktfunk/screenshots/ShotScenes.kt

@@ -27,6 +27,7 @@ import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.unit.dp
 import io.unom.punktfunk.BrandDark
 import io.unom.punktfunk.Settings
+import io.unom.punktfunk.TouchMode
 import io.unom.punktfunk.SettingsScreen
 import io.unom.punktfunk.StatsOverlay
 import io.unom.punktfunk.components.HostCard
@@ -109,7 +110,7 @@ internal fun SettingsScene() {
                 gamepad = 2,
                 micEnabled = true,
                 statsHudEnabled = true,
-                trackpadMode = true,
+                touchMode = TouchMode.TRACKPAD,
             ),
             onChange = {},
             onBack = {},