feat(android): shared clipboard (text) — device↔host sync while streaming

The desktop clients' clipboard protocol, adopted on Android (text-only v1):
opt-in ClipControl at stream start when the host advertises HOST_CAP_CLIPBOARD
and the new "Shared clipboard" setting (default on) allows.

Device → host: local copies (primary-clip listener + a probe at start) are
announced as lazy format-list offers; the text crosses only when the host
actually pastes (FetchRequest → served from the live clipboard). Host →
device: a host copy's offer is fetched eagerly and lands in the system
clipboard (Android has no practical lazy-paste provider), with an echo guard
so the resulting clip-changed callback doesn't bounce it back as a new offer.

Native side: session/clipboard.rs JNI shims over NativeClient's clip_*
surface; events cross to Kotlin as compact strings from a blocking
nativeNextClip poll on a dedicated thread (the nativeNextRumble pattern),
joined before the session handle is freed.

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

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

@@ -0,0 +1,107 @@
+package io.unom.punktfunk
+
+import android.content.ClipData
+import android.content.ClipboardManager
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import io.unom.punktfunk.kit.NativeBridge
+
+/**
+ * Text clipboard sync for the active session (the desktop-client model, text-only v1):
+ *  * **Device → host**: a local copy (the primary-clip listener, plus one probe at start) is
+ *    announced as a lazy offer — the text crosses only when the host actually pastes (a
+ *    `fetch:` event, answered with the clipboard's current content).
+ *  * **Host → device**: a host copy arrives as an `offer:` event and is fetched eagerly into
+ *    the system clipboard (Android apps can't lazily materialize a paste from the network
+ *    without a content-provider round-trip that isn't worth it here).
+ *
+ * Loop guard: text set from a host fetch is remembered ([lastFromHost]) so the resulting
+ * primary-clip-changed callback doesn't bounce it straight back as a new offer. Clipboard reads
+ * happen while the stream is foreground (Android only allows focused-app reads). The native
+ * events are drained on a dedicated thread and applied on the main thread; [stop] joins it.
+ */
+class ClipboardSync(
+    private val context: Context,
+    private val handle: Long,
+) {
+    private val main = Handler(Looper.getMainLooper())
+    private val cm = context.getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
+
+    @Volatile private var running = true
+    private var seq = 0
+    private var lastOffered: String? = null
+    private var lastFromHost: String? = null
+    private var pendingFetch = -1
+    private var thread: Thread? = null
+
+    private val clipListener = ClipboardManager.OnPrimaryClipChangedListener { offerLocal() }
+
+    fun start() {
+        NativeBridge.nativeClipControl(handle, true)
+        cm.addPrimaryClipChangedListener(clipListener)
+        thread = Thread({ pollLoop() }, "pf-clipboard").also { it.start() }
+        offerLocal() // whatever is already on the clipboard is pasteable host-side right away
+    }
+
+    fun stop() {
+        running = false
+        cm.removePrimaryClipChangedListener(clipListener)
+        thread?.join(600) // one poll timeout (250 ms) + slack
+        thread = null
+    }
+
+    /** Announce the current local text (if it's new and not an echo of a host copy). */
+    private fun offerLocal() {
+        if (!running) return
+        val text = currentClipText() ?: return
+        if (text == lastOffered || text == lastFromHost) return
+        lastOffered = text
+        seq += 1
+        NativeBridge.nativeClipOfferText(handle, seq)
+    }
+
+    private fun currentClipText(): String? = runCatching {
+        cm.primaryClip?.takeIf { it.itemCount > 0 }?.getItemAt(0)
+            ?.coerceToText(context)?.toString()?.takeIf { it.isNotEmpty() }
+    }.getOrNull()
+
+    private fun pollLoop() {
+        while (running) {
+            val ev = NativeBridge.nativeNextClip(handle) ?: continue
+            if (ev == "closed") return
+            main.post { handleEvent(ev) }
+        }
+    }
+
+    private fun handleEvent(ev: String) {
+        if (!running) return
+        val parts = ev.split(":", limit = 3)
+        when (parts[0]) {
+            "offer" -> {
+                val offerSeq = parts.getOrNull(1)?.toIntOrNull() ?: return
+                if (parts.getOrNull(2) == "1") {
+                    pendingFetch = NativeBridge.nativeClipFetchText(handle, offerSeq)
+                }
+            }
+            "fetch" -> {
+                val req = parts.getOrNull(1)?.toIntOrNull() ?: return
+                val text = currentClipText()
+                if (text != null) {
+                    NativeBridge.nativeClipServeText(handle, req, text)
+                } else {
+                    NativeBridge.nativeClipCancel(handle, req)
+                }
+            }
+            "data" -> {
+                val xfer = parts.getOrNull(1)?.toIntOrNull() ?: return
+                if (xfer != pendingFetch) return // stale/unknown transfer
+                pendingFetch = -1
+                val text = parts.getOrNull(2)?.takeIf { it.isNotEmpty() } ?: return
+                lastFromHost = text
+                runCatching { cm.setPrimaryClip(ClipData.newPlainText("Punktfunk", text)) }
+            }
+            // "state"/"cancel"/"error": nothing to drive in the text-only v1.
+        }
+    }
+}

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

@@ -123,6 +123,13 @@ data class Settings(
      * the Apple/GTK clients' "Invert scroll direction".
      */
     val invertScroll: Boolean = false,
+
+    /**
+     * Sync text copied on this device to the host and vice versa while streaming (the desktop
+     * clients' shared clipboard, text-only here). Only effective when the host advertises the
+     * clipboard capability; the protocol is opt-in per session either way.
+     */
+    val clipboardSync: Boolean = true,
 )
 
 /** [Settings.touchMode] values; persisted by name. */
@@ -188,6 +195,7 @@ class SettingsStore(context: Context) {
         sc2Capture = prefs.getBoolean(K_SC2_CAPTURE, true),
         pointerCapture = prefs.getBoolean(K_POINTER_CAPTURE, false),
         invertScroll = prefs.getBoolean(K_INVERT_SCROLL, false),
+        clipboardSync = prefs.getBoolean(K_CLIPBOARD_SYNC, true),
     )
 
     fun save(s: Settings) {
@@ -213,6 +221,7 @@ class SettingsStore(context: Context) {
             .putBoolean(K_SC2_CAPTURE, s.sc2Capture)
             .putBoolean(K_POINTER_CAPTURE, s.pointerCapture)
             .putBoolean(K_INVERT_SCROLL, s.invertScroll)
+            .putBoolean(K_CLIPBOARD_SYNC, s.clipboardSync)
             .apply()
     }
 
@@ -253,6 +262,7 @@ class SettingsStore(context: Context) {
         const val K_SC2_CAPTURE = "sc2_capture"
         const val K_POINTER_CAPTURE = "pointer_capture"
         const val K_INVERT_SCROLL = "invert_scroll"
+        const val K_CLIPBOARD_SYNC = "clipboard_sync"
 
         /** Legacy Boolean the enum replaced — read once as the migration default, never written. */
         const val K_TRACKPAD = "trackpad_mode"

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

@@ -426,6 +426,13 @@ private fun ControlsSettings(s: Settings, update: (Settings) -> Unit, onOpenCont
             checked = s.invertScroll,
             onCheckedChange = { on -> update(s.copy(invertScroll = on)) },
         )
+        ToggleRow(
+            title = "Shared clipboard",
+            subtitle = "Text copied here pastes on the host and vice versa (hosts with " +
+                "clipboard sharing enabled)",
+            checked = s.clipboardSync,
+            onCheckedChange = { on -> update(s.copy(clipboardSync = on)) },
+        )
     }
     SettingsCard {
         SettingDropdown(

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

@@ -270,6 +270,13 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
             null
         }
         activity?.remotePointer = remote
+        // Shared clipboard (text v1): only when the user setting is on AND the host has a
+        // working clipboard service. Protocol-level opt-in + the poll thread live in the sync.
+        val clip = if (initialSettings.clipboardSync && NativeBridge.nativeClipSupported(handle)) {
+            ClipboardSync(context, handle).also { it.start() }
+        } else {
+            null
+        }
         activity?.setConsoleHighRefreshRate(false) // let the decoder's setFrameRate pick the panel rate
         // Host→client feedback (rumble + DualSense lightbar/LEDs), routed to each controller by pad
         // index via the router; poll threads stopped + joined before the router is released and the
@@ -335,6 +342,7 @@ fun StreamScreen(handle: Long, micEnabled: Boolean, onDisconnect: () -> Unit) {
         }
         onDispose {
             closed.set(true) // from here the handle gets freed; surfaceDestroyed must not touch it
+            clip?.stop() // stop + join the clipboard poll thread BEFORE the handle is freed
             feedback.onHidRaw = null
             feedback.stop() // stop + join the poll threads BEFORE the router is released / handle freed
             sc2UsbReceiver?.let { runCatching { context.unregisterReceiver(it) } }