@desklink/react-native 0.4.0 → 0.5.1

package/README.md

@@ -30,6 +30,9 @@ repository it resolves through the workspace; anywhere else, install it from npm
 npx expo install @desklink/react-native      # or yarn add, then prebuild/rebuild
 ```
 
+Expo SDK 55 and later are supported, including the SDK a fresh
+`npx create-expo-app` resolves today: no SDK pin is needed.
+
 Android uses an Expo native module; iOS uses the app's existing
 `react-native-webrtc` peer connection and `RTCView` from JavaScript, plus a small
 Expo module of its own for the hardware keyboard and an iPad pointer. Both need a
@@ -59,6 +62,7 @@ changes, and trackpad presses reach the desktop as touches.
 
 ```tsx
 import { DesktopView, useDesktopSession } from '@desklink/react-native';
+import * as Clipboard from 'expo-clipboard';
 
 const desktop = useDesktopSession({
     authorize: async () => ({
@@ -75,7 +79,12 @@ await desktop.connect();
 desktop.setInputEnabled(true);
 desktop.showKeyboard();
 desktop.setOrientation('landscape');   // Android only; iOS apps configure supported orientations themselves
+await desktop.copyRemoteToLocal(async (text) => {
+    if (!await Clipboard.setStringAsync(text)) throw new Error('Clipboard write refused');
+});
 await desktop.pasteLocalToRemote(await Clipboard.getStringAsync());
+// Optional receiver evidence: codec, decoder and video counters; no ICE addresses.
+const stats = await desktop.getStats();
 ```
 
 Pairing is the only trust boundary. `authorize` is the app's pairing check: it
@@ -127,15 +136,25 @@ heat and battery.
   so the iOS receiver asks for H.264 by putting it first in the offer it
   applies; a host with an H.264 encoder then sends H.264, and one without sends
   VP9. Neither platform links a second WebRTC stack.
-- **A sharp, zoomable picture.** The desktop fits the view by default; a pinch
-  zooms up to 2.5 view pixels per desktop pixel and one finger moves around the
-  zoomed desktop. On Android the decoded frame is copied once into the view's
+- **A sharp, zoomable picture.** In portrait the default is fit-width;
+  in landscape it covers the screen below the status bar (as far as the 2.5
+  zoom limit allows). The picture stays undistorted. One finger pans cropped
+  content; pinch to zoom before panning when the whole desktop already fits.
+  Pass the screen's safe-area `insets` (for example from
+  `react-native-safe-area-context`) so the default starts below the status bar
+  and beside a camera cutout. `onPictureFrame` reports where the picture
+  ended whenever it moves, so a tall screen's band below it can carry the
+  application's own controls instead of empty space. Panning brings each desktop edge inside the safe
+  area, while landscape coverage extends beneath the cutout and home indicator
+  to limit black bars. A pinch zooms up to 2.5 view
+  pixels per desktop pixel, or out to the whole desktop. On Android the decoded frame is copied once into the view's
   own texture and drawn with a multi-tap filter when it is shown smaller than
   its size, so a fitted 4K desktop does not alias and a pinch redraws at once.
   iOS uses `RTCView`'s native renderer. That renderer draws a frame only when
   its timestamp is new, and a receiver honouring the engine's zero playout delay
   stamps every frame alike, so the iOS peer declines that hint and keeps the
-  receiver's usual jitter buffer. `fitToView()` shows the whole desktop again.
+  receiver's usual jitter buffer. `fitToView()` shows the whole desktop; a new
+  desktop size or a rotation reapplies the orientation default from the top-left.
 - **A pointer a phone can see.** Once a touch has sent the desktop's pointer
   somewhere, the view draws an outlined arrow there at a readable size, over a
   picture whose own cursor is a few pixels tall or not captured at all. On iOS,
@@ -148,7 +167,7 @@ heat and battery.
   (`keyboardClearance`). Android follows the keyboard animation and keeps the
   pointer in sight; iOS follows the keyboard show/hide bounds.
 - **Contained geometry.** Touch maps through the picture's actual placement.
-  A one-finger drag starting in the letterbox does not move the pointer; a
+  On the whole desktop, a one-finger drag starting in the letterbox does not move the pointer; a
   second finger on the picture can still start a pinch or scroll. A drag that
   leaves the picture is held to its edge rather than released somewhere unseen.
 - **The gestures remote-desktop viewers settled on,** with a slop threshold:
@@ -181,7 +200,15 @@ heat and battery.
 - **The keys a phone lacks.** `modifiers`, `tapModifier` and `pressKey` give
   sticky Ctrl and Shift: tap arms one for the next key, tap again locks it.
   While one is armed, the next key or character the phone's keyboard types is
-  sent as that key's chord, so Ctrl then v is Ctrl+V. The app draws the keys.
+  sent as that key's chord, so Ctrl then v is Ctrl+V. `modifiers` holds each
+  key's state (`off`, `once` for latched, `lock`) for the app to read.
+  `<ModifierKeys modifiers={desktop.modifiers} onTap={desktop.tapModifier} />`
+  draws them as a backed key row: off is an outlined key, latched a filled
+  one, locked a filled one with a white rim and a bar under its label, and a
+  screen reader hears off, latched or locked. Its `grow` prop makes it a
+  tablet's row: the keys take the width and the height the row is given
+  instead of sitting at 44 pt. An app may draw its own keys
+  from `modifiers` instead.
 - **Readiness is a rendered frame.** Android marks the first draw; iOS marks
   the first `RTCView` video-dimensions callback and ignores later ones, so a
   resize or remount during a reconnect does not read as live. Neither marks
@@ -230,6 +257,15 @@ heat and battery.
   session close and a lost control channel release what the desktop was holding.
 - **Explicit clipboard.** Two methods, called on a user action while control is
   enabled. The package never polls the clipboard or uses it as a way to type.
+  `copyRemoteToLocal(writeLocal)` awaits the caller-owned local writer, which
+  must reject on failure or refusal, before recording completion. The returned
+  text and truncation flag describe what was written. `pasteLocalToRemote(text)`
+  records completion only after the desktop acknowledges the write.
+  `clipboard` is the last transfer that completed, and
+  `<ClipboardConfirmation transfer={desktop.clipboard} />` confirms each one
+  with a backed pill — where it went and the start of the text —
+  that ignores touches and leaves after 1.5 s. Place it in a reserved area
+  outside `DesktopView`, keeping that area present when the pill is dismissed.
 
 ### `Signaling`
 
@@ -283,11 +319,12 @@ What the consuming app — not this package — must get right before review.
   disabling input on background; the engine releases held keys within
   seconds of the path dying, so nothing stays stuck.
 
-## iOS simulator proof
+## Example app proof
 
 `example/` is the smallest app that shows a desktop: a native (non-Expo Go)
 build with `react-native-webrtc`, connecting to `desklink-host bridge` with the
-URL it is launched with. Its status line shows plain messages: `Connected`
+URL it is launched with on iOS, or the connection link it is opened with on
+Android. Its hidden accessibility status shows plain messages: `Connected`
 once a frame is presented, `Can’t reach your desktop. Reconnecting…` while
 retrying, and `Your desktop ended this session` after revocation. It never
 displays the bridge URL, pairing token, raw failure text or frame metrics.
@@ -297,28 +334,44 @@ bridge, and checks that the first frame is presented, that the answer puts
 H.264 first with NACK when the host offers it (VP9 otherwise; both descriptions
 are written out), that a tap clicks the host, that
 the picture keeps following the desktop afterwards, and that hardware keys
-pressed on the simulator reach the desktop. With `DESKLINK_IOS_IPAD=1` it runs on
+pressed on the simulator reach the desktop. It then drives the whole
+**phone-only control** journey from the phone's own screen, with no input sent
+to the desktop from this machine: a click, a drag that holds the button and
+selects, a two-finger scroll, typed text, a sticky modifier that chords the next
+key and clears, the clipboard in both directions, and the drawn pointer mark's
+shape and tip. Every step has its own capture, the journey is recorded as one
+screen recording on the simulator, and the phone's own screen is read to prove it
+carries no diagnostic text.
+With `DESKLINK_IOS_IPAD=1` it runs on
 an iPad simulator and also drives a trackpad through XCUITest
 (`test/ios-pointer/`): hover, a click-drag that selects text, a right click and
 a scroll:
 
 ```sh
 npm run build && cargo build --manifest-path packages/desktop-host/engine/Cargo.toml
-env -u DISPLAY -u WAYLAND_DISPLAY DESKLINK_IOS_MAC=user@mac npm run test:ios --workspace @desklink/react-native
+env -u DISPLAY -u WAYLAND_DISPLAY DESKLINK_IOS_MAC=user@mac \
+  DESKLINK_IOS_DEVICE='fm-iPhone 17 Pro' npm run test:ios --workspace @desklink/react-native
 ```
 
 The Mac needs Xcode with an iOS simulator runtime, CocoaPods, node and
 [`axe`](https://github.com/cameroncooke/AXe) on its login `PATH`; everything
 the run builds or caches stays in `~/desklink-ios` there. The run creates a
-uniquely named simulator and deletes it during cleanup. For host desktop isolation, see the
+uniquely named simulator and deletes it during cleanup. Set
+`DESKLINK_IOS_DEVICE` to the name or udid of one of the Mac's own simulators to
+run on that instead and leave it in place. For host desktop isolation, see the
 [private-lab guidance](../../README.md#develop). When the selected
 Xcode has no simulator platform, point `DESKLINK_IOS_XCODE` at one that does;
 `DESKLINK_IOS_RUNTIME` picks the iOS version (for example `18.6`); the
 script's header lists the other settings. To capture the cursor tip proof, set
 `DESKLINK_IOS_POINTER_PROOF=before` or `after`; the run writes a 4x crop, device
 frame, proof metadata, and host click log under `DESKLINK_IOS_OUT`. Set
-`DESKLINK_IOS_APP` to reuse an app bundle under `DESKLINK_IOS_DIR` when running
-with `DESKLINK_IOS_SKIP_BUILD=1`. Run once with `before` before the change and
+`DESKLINK_IOS_APP` to reuse an app bundle under the lane's directory when
+running with `DESKLINK_IOS_SKIP_BUILD=1`. `DESKLINK_IOS_DIR` is the shared Mac
+lab root (`fm-desklink-ios`) and `DESKLINK_IOS_LANE` names this lane's own
+subdirectory within it; the run deletes that subdirectory and nothing else when
+it finishes, so two lanes can build at once without one cleanup deleting the
+other's build. Set `DESKLINK_IOS_KEEP=1` to keep it. Run once with `before`
+before the change and
 once with `after` after it, on both iPhone and iPad simulators, to compare the
 pointer crop and verify the host click is within two desktop pixels of the tip.
 To try the example by hand against any bridge:
@@ -327,6 +380,21 @@ To try the example by hand against any bridge:
 xcrun simctl launch <device> dev.desklink.example -desklinkUrl 'ws://HOST:PORT/desktop?token=TOKEN'
 ```
 
+On Android, build the same example with `npm run android` and open a connection
+link whose `url` query parameter is the URL-encoded bridge WebSocket address:
+`desklink-example://connect?url=ws%3A%2F%2FHOST%3APORT%2Fdesktop%3Ftoken%3DTOKEN`.
+The example allows the bridge's plaintext private-network connection; consumer
+apps choose their own transport policy. A new link replaces the open session.
+The live picture has no diagnostic overlay. Its accessibility status remains
+available as `desklink-status`. The key row (`Ctrl`, `Shift`, `Alt`, `Meta`) and
+the `Copy` and `Paste` buttons are the app's own chrome over the picture, and a
+clipboard transfer is confirmed by a pill above them.
+
+For device evidence, an optional `report` query parameter accepts a URL-encoded
+HTTP endpoint. While live, the example posts receiver statistics and connection
+and first-presentation timestamps once per second. Collection failures do not
+interrupt the session. Without that parameter, no evidence is posted.
+
 ## Licence
 
 Apache-2.0. See `NOTICE`.

package/android/build.gradle

@@ -1,9 +1,21 @@
 apply plugin: 'com.android.library'
-apply plugin: 'kotlin-android'
+// expo-modules-core's own Kotlin API is reified through the `pika` compiler
+// plugin, and this plugin is what applies it. Building with a bare
+// `kotlin-android` leaves those reified calls un-inlined, and the app then
+// throws "This function has a reified type parameter ..." out of
+// DesklinkModule.definition() on startup. Expo's plugin covers every SDK, and
+// applies kotlin-android and the default Expo module dependencies itself.
+apply plugin: 'expo-module-gradle-plugin'
 
 group = 'expo.modules.desklink'
 version = '0.1.1'
 
+// This package ships from npm, not from Expo's Maven repository, so the
+// plugin's publishing task has nothing to publish.
+expoModule {
+  canBePublished = false
+}
+
 android {
   namespace 'expo.modules.desklink'
   compileSdk rootProject.ext.has('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36

package/android/src/main/java/expo/modules/desklink/DesklinkModule.kt

@@ -5,6 +5,7 @@ import android.content.pm.ActivityInfo
 import android.content.res.Configuration
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
+import expo.modules.kotlin.Promise
 import java.util.concurrent.ConcurrentHashMap
 
 /**
@@ -113,6 +114,12 @@ class DesklinkModule : Module() {
 
     Function("isAvailable") { true }
 
+    AsyncFunction("getStats") { id: String, promise: Promise ->
+      val session = sessions[id]
+      if (session == null) promise.resolve("[]")
+      else session.getStats { promise.resolve(it) }
+    }
+
     View(DesktopView::class) {
       Name("DesklinkSurface")
 
@@ -126,6 +133,14 @@ class DesklinkModule : Module() {
         view.setKeyboardClearance(clearance ?: 0f)
       }
 
+      Prop("insets") { view: DesktopView, insets: List<Double>? ->
+        val edges = insets.orEmpty()
+        view.setInsets(
+          edges.getOrNull(0)?.toFloat() ?: 0f, edges.getOrNull(1)?.toFloat() ?: 0f,
+          edges.getOrNull(2)?.toFloat() ?: 0f, edges.getOrNull(3)?.toFloat() ?: 0f,
+        )
+      }
+
       Prop("gestures") { view: DesktopView, gestures: String? ->
         view.setGestures(gestures ?: "desktop")
       }

package/android/src/main/java/expo/modules/desklink/DesktopSession.kt

@@ -370,6 +370,33 @@ class DesktopSession(
     return servers
   }
 
+  /** A bounded diagnostics snapshot; never expose ICE addresses or control content. */
+  @Synchronized
+  fun getStats(done: (String) -> Unit) {
+    if (closed) {
+      done("[]")
+      return
+    }
+    io.execute {
+      val connection = peer
+      if (closed || connection == null) {
+        done("[]")
+        return@execute
+      }
+      connection.getStats { report ->
+        val fields = setOf("kind", "mediaType", "codecId", "mimeType", "clockRate", "payloadType",
+          "packetsReceived", "packetsLost", "bytesReceived", "framesReceived", "framesDecoded",
+          "keyFramesDecoded", "framesDropped", "framesPerSecond", "frameWidth", "frameHeight",
+          "nackCount", "pliCount", "firCount", "totalDecodeTime", "decoderImplementation", "jitterBufferDelay")
+        val stats = report.statsMap.values.filter { it.type == "inbound-rtp" || it.type == "codec" }
+          .map { stat -> JSONObject(stat.members.filterKeys { it in fields }).apply {
+            put("id", stat.id); put("type", stat.type); put("timestampUs", stat.timestampUs)
+          } }
+        done(org.json.JSONArray(stats).toString())
+      }
+    }
+  }
+
   private fun observer(target: Long) = object : PeerConnection.Observer {
     override fun onSignalingChange(state: PeerConnection.SignalingState?) = Unit
 

package/android/src/main/java/expo/modules/desklink/DesktopView.kt

@@ -65,7 +65,8 @@ private const val MIN_WHEEL_STEP = 0.05f
  *  - tap: click where the finger lands; two taps: a double click on the same spot;
  *  - press and hold: a right click on release, or drag after it to hold the left
  *    button (select text, move a window);
- *  - one finger: move around a zoomed-in desktop; on the whole desktop,
+ *  - one finger: move around a zoomed-in desktop — the picture starts filled,
+ *    covering the view, so this is the default; on the whole desktop,
  *    move its pointer, which follows the finger without pressing a button —
  *    unless `gestures` is `browser`, where it scrolls the page, or `device`,
  *    where it lands with the button down and drags with it held;
@@ -102,11 +103,23 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
 
   // The picture's placement: surface pixels per desktop pixel, and where the
   // desktop's top-left corner sits in this view. `fitted` keeps a picture that
-  // was showing the whole desktop showing it when the view changes size.
+  // was showing the whole desktop showing it when the view changes size;
+  // `filling` keeps the default, a picture covering the view, until the user
+  // zooms or asks for the whole desktop. `filledScale` is the fill it was last
+  // placed at, so a new fill (a rotation, a new surface) starts at the
+  // desktop's top-left corner again.
   private var scale = 1f
   private var originX = 0f
   private var originY = 0f
   private var fitted = true
+  private var filling = true
+  private var filledScale = 0f
+
+  /** What the system covers at each edge (bars, cutout), in pixels: left, top, right, bottom. */
+  private var insetLeft = 0f
+  private var insetTop = 0f
+  private var insetRight = 0f
+  private var insetBottom = 0f
 
   /**
    * How much of this view's bottom the phone's keyboard, and the app's own
@@ -254,6 +267,8 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
     surfaceWidth = width
     surfaceHeight = height
     fitted = true
+    filling = true
+    filledScale = 0f
     // A point on the old geometry says nothing about the new one.
     pointerAt = null
     layoutPicture()
@@ -296,6 +311,22 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
   /** Show the whole desktop again. */
   fun fitToView() {
     fitted = true
+    filling = false
+    layoutPicture()
+  }
+
+  /**
+   * What the system covers at each edge of the view, in points. The picture
+   * still reaches under it, but starts and pans inside it.
+   */
+  fun setInsets(top: Float, left: Float, bottom: Float, right: Float) {
+    val density = resources.displayMetrics.density
+    if (top * density == insetTop && left * density == insetLeft && bottom * density == insetBottom && right * density == insetRight) return
+    insetTop = top * density
+    insetLeft = left * density
+    insetBottom = bottom * density
+    insetRight = right * density
+    filledScale = 0f
     layoutPicture()
   }
 
@@ -347,9 +378,9 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
    */
   private fun coverBottom(next: Float) {
     if (abs(next - covered) < 0.5f) return
-    val before = visibleHeight()
+    val before = visibleBottom()
     covered = next
-    val visible = visibleHeight()
+    val visible = visibleBottom()
     val at = pointerAt
     if (at == null) {
       originY += (visible - before) / 2f
@@ -361,7 +392,13 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
     layoutPicture()
   }
 
-  private fun visibleHeight(): Float = max(1f, height - covered)
+  /** Where the uncovered part of the view ends: above the keyboard, or above what the system covers. */
+  private fun visibleBottom(): Float = max(insetTop + 1f, min(height - covered, height - insetBottom))
+
+  private fun safeWidth(): Float = max(1f, width - insetLeft - insetRight)
+
+  /** The whole uncovered height, keyboard or not: the keyboard moves the picture rather than shrinking it. */
+  private fun safeHeight(): Float = max(1f, height - insetTop - insetBottom)
 
   private fun inputMethods() = context.getSystemService(Context.INPUT_METHOD_SERVICE) as InputMethodManager
 
@@ -386,8 +423,10 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
 
   override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
     super.onSizeChanged(w, h, oldw, oldh)
-    // A rotation: keep what the user was looking at.
-    if (oldw > 0 && oldh > 0 && !fitted) {
+    // A rotation: a filled picture starts again at its top-left corner;
+    // a zoomed one keeps what the user was looking at.
+    if (filling) filledScale = 0f
+    else if (oldw > 0 && oldh > 0 && !fitted) {
       originX += (w - oldw) / 2f
       originY += (h - oldh) / 2f
     }
@@ -416,34 +455,54 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
    */
   private fun fitScale(): Float {
     if (width == 0 || height == 0 || surfaceWidth == 0 || surfaceHeight == 0) return 1f
-    return min(width.toFloat() / surfaceWidth, height.toFloat() / surfaceHeight)
+    return min(safeWidth() / surfaceWidth, safeHeight() / surfaceHeight)
+  }
+
+  private fun fillScale(): Float {
+    val cover = if (width <= height) safeWidth() / surfaceWidth
+      else max(width.toFloat() / surfaceWidth, (height - insetTop) / surfaceHeight)
+    return max(fitScale(), min(cover, MAX_SCALE))
   }
 
-  /** Re-derive the placement from `fitted`, the zoom limits and the edges. */
+  /** Re-derive the placement from `filling`, `fitted`, the zoom limits and the edges. */
   private fun layoutPicture() {
     if (surfaceWidth == 0 || surfaceHeight == 0 || width == 0 || height == 0) return
     val fit = fitScale()
-    scale = if (fitted) fit else scale.coerceIn(fit, max(fit, MAX_SCALE))
+    if (filling) {
+      val fill = fillScale()
+      if (fill != filledScale) {
+        scale = fill
+        filledScale = fill
+        // The desktop's top-left corner, where a page's first words are.
+        originX = insetLeft
+        originY = insetTop
+      }
+    } else {
+      scale = if (fitted) fit else scale.coerceIn(fit, max(fit, MAX_SCALE))
+    }
     fitted = scale <= fit * 1.001f
     clampOrigin()
     publishTransform()
   }
 
   /**
-   * A picture smaller than what is visible is centred on that axis; a larger
-   * one covers it. Above the keyboard, only the uncovered part counts.
+   * A picture smaller than the uncovered part of the view is centred in it on
+   * that axis; a larger one can move until either edge reaches that part's
+   * edge. Above the keyboard, only the part above it counts.
    */
   private fun clampOrigin() {
     val pictureWidth = surfaceWidth * scale
     val pictureHeight = surfaceHeight * scale
-    val visible = visibleHeight()
-    originX = if (pictureWidth <= width) (width - pictureWidth) / 2f else originX.coerceIn(width - pictureWidth, 0f)
-    originY = if (pictureHeight <= visible) (visible - pictureHeight) / 2f else originY.coerceIn(visible - pictureHeight, 0f)
+    val right = width - insetRight
+    val bottom = visibleBottom()
+    originX = if (pictureWidth <= right - insetLeft) insetLeft + (right - insetLeft - pictureWidth) / 2f else originX.coerceIn(right - pictureWidth, insetLeft)
+    originY = if (pictureHeight <= bottom - insetTop) insetTop + (if (filling) 0f else (bottom - insetTop - pictureHeight) / 2f) else originY.coerceIn(bottom - pictureHeight, insetTop)
   }
 
   private fun zoomAround(focusX: Float, focusY: Float, factor: Float) {
     val fit = fitScale()
     val next = (scale * factor).coerceIn(fit, max(fit, MAX_SCALE))
+    filling = false
     val applied = next / scale
     originX = focusX - (focusX - originX) * applied
     originY = focusY - (focusY - originY) * applied
@@ -622,7 +681,9 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
             return true
           }
           // The whole desktop has nowhere to move to, so the finger moves the
-          // desktop's pointer instead, without a button.
+          // desktop's pointer instead, without a button. A fill that landed on
+          // the fit scale has nowhere to move to either, portrait most of all,
+          // and it is `fitted`, not the fill, that says there is room.
           gesture = if (!fitted) Gesture.PAN else if (downOnPicture) Gesture.HOVER else Gesture.LETTERBOX
           lastX = event.x
           lastY = event.y

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@desklink/react-native",
-    "version": "0.4.0",
+    "version": "0.5.1",
     "license": "Apache-2.0",
     "description": "Render and drive a desktop session from a React Native app",
     "main": "index.ts",

package/src/ClipboardConfirmation.tsx

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import { StyleSheet, Text, View, type StyleProp, type ViewStyle } from 'react-native';
+
+import type { ClipboardTransfer } from './useDesktopSession';
+
+export interface ClipboardConfirmationProps {
+    /** The session's `clipboard`. */
+    transfer: ClipboardTransfer | null;
+    style?: StyleProp<ViewStyle>;
+}
+
+/** How long a confirmation stays up. */
+export const CLIPBOARD_CONFIRMATION_MS = 1500;
+const PREVIEW_CHARS = 24;
+
+/**
+ * A short pill confirming each clipboard transfer: where it went and the start
+ * of the text. Place it in reserved space outside the desktop
+ * surface. It ignores touches and goes away on its own.
+ */
+export function ClipboardConfirmation({ transfer, style }: ClipboardConfirmationProps) {
+    const [shown, setShown] = React.useState<ClipboardTransfer | null>(null);
+    const seenId = React.useRef<number | null>(transfer?.id ?? null);
+    React.useEffect(() => {
+        if (transfer == null) return;
+        if (transfer.id === seenId.current) return;
+        seenId.current = transfer.id;
+        setShown(transfer);
+        const timer = setTimeout(() => setShown(null), CLIPBOARD_CONFIRMATION_MS);
+        return () => clearTimeout(timer);
+    }, [transfer?.id]);
+    if (shown == null) return null;
+    return (
+        <View pointerEvents="none" style={[styles.place, style]}>
+            <View testID="desklink-clipboard" accessibilityLiveRegion="polite" style={styles.pill}>
+                <Text numberOfLines={1} style={styles.text}>{describeTransfer(shown)}</Text>
+            </View>
+        </View>
+    );
+}
+
+/** "Copied to phone · “first words…”" */
+export function describeTransfer({ direction, text }: ClipboardTransfer): string {
+    const where = direction === 'to-phone' ? 'Copied to phone' : 'Sent to desktop';
+    const flat = text.replace(/\s+/g, ' ').trim();
+    const chars = [...flat];
+    const preview = chars.length > PREVIEW_CHARS ? `${chars.slice(0, PREVIEW_CHARS).join('')}…` : flat;
+    return preview === '' ? `${where}` : `${where} · “${preview}”`;
+}
+
+export const PILL_COLORS = { backing: 'rgba(17, 18, 20, 0.94)', text: '#ffffff' };
+
+const styles = StyleSheet.create({
+    place: { paddingHorizontal: 16, alignItems: 'center' },
+    pill: { maxWidth: '100%', paddingHorizontal: 14, paddingVertical: 8, borderRadius: 999, backgroundColor: PILL_COLORS.backing },
+    text: { color: PILL_COLORS.text, fontSize: 14, fontWeight: '600' },
+});