@desklink/react-native 0.5.0 → 0.5.2

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,6 +79,9 @@ 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();
@@ -120,6 +127,24 @@ the iOS receiver asks the engine for H.264, which iOS decodes in hardware
 iOS decodes in software — so a 1440p or 4K picture on such a host costs CPU,
 heat and battery.
 
+### Paths with no UDP route
+
+`session.loopbackTcp` asks the engine to also offer ICE over TCP on its own
+`127.0.0.1`, for a client whose only way to the computer is a forward of that
+loopback — an SSH tunnel, `adb reverse`:
+
+```tsx
+session: { loopbackTcp: true },
+```
+
+It is off by default, like the wire field it sets. A client with a UDP path
+keeps it: ICE prefers UDP whenever it has one. The engine picks that port per
+session, so the forward has to follow it (`adb reverse tcp:<port> tcp:<port>`,
+`ssh -L <port>:127.0.0.1:<port> <computer>`) with `<port>` from the
+`session.candidate` the engine offers. Without it a connection that never
+forms fails after 20 seconds with that reason, rather than sitting on an empty
+view.
+
 ### What the package guarantees
 
 - **Hardware decoding where the platform has it.** Android and web decode the
@@ -135,7 +160,9 @@ heat and battery.
   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. Panning brings each desktop edge inside the safe
+  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
@@ -155,8 +182,10 @@ heat and battery.
   touched shows the finger itself.
 - **The picture above the keyboard.** While the phone's keyboard is up, the
   picture sits above it and above the room the app keeps for its own controls
-  (`keyboardClearance`). Android follows the keyboard animation and keeps the
-  pointer in sight; iOS follows the keyboard show/hide bounds.
+  (`keyboardClearance`). Only the part of the view the keyboard really covers
+  counts, and a picture taller than what is left moves so the pointer, where
+  a tap just put the caret, stays in sight. Android also follows the keyboard
+  animation frame by frame; iOS moves once, as the keyboard shows or hides.
 - **Contained geometry.** Touch maps through the picture's actual placement.
   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
@@ -191,7 +220,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
@@ -201,25 +238,30 @@ heat and battery.
   peer's ICE state and the engine's `session.state` both feed it: a
   `disconnected` path reads as `reconnecting` within about a second of the
   drop — never a frozen picture that still says live — and a recovered path
-  reads as `live` again once ICE is `connected`. A path that reports
+  reads as `live` again once the picture is advancing again (ICE `connected`
+  alone does not restore `live` while the picture is frozen). A path that reports
   `failed` reopens the session with fresh authority instead of staying stuck.
   Every event carries its engine session id where the carrier preserves it,
   and the session ignores anything naming a session it no longer holds, so a
   previous generation's queued offer or revocation cannot corrupt or kill a
   healthy recovery.
-  Detection is two-layered: ICE and engine `session.state` events, plus the
+  Detection is three-layered: ICE and engine `session.state` events, the
   engine's twice-a-second control-channel heartbeat (`{"kind":"ping"}`) — a
   path that stops heartbeating reads as stalled within ~1.5 s even while ICE
   consent timers are still making up their minds, and resumed heartbeats read
-  as recovered. Clients on engines that predate the heartbeat simply never
-  arm that watchdog.
+  as recovered — and a half-second poll of the receiver's own video counters
+  while a picture is shown: a picture stopped for ~2 s reads as not `live`
+  even while signalling, ICE and control all answer. Clients on engines that
+  predate the heartbeat simply never arm that watchdog.
 - **ICE restarts before reopens.** When the path drops after frames were
   shown, the session asks the engine (`session.restart_ice`) to re-offer on
   the same peer connection: the fresh offer arrives as the usual
   `session.description` event and is answered as usual, all without reopening
   the session. The first restart waits ~2 s for blips that heal alone;
   retries back off across ~60 s, so a 30–60 s outage still recovers when the
-  network returns. When the restart schedule is spent without the peer
+  network returns — except while the picture is frozen, when the short ~2 s
+  retry keeps being spent without consuming the reopen budget until frames
+  move again. When the restart schedule is spent without the peer
   reporting `failed`, the session reopens instead of sitting in
   `reconnecting`. An engine revocation with code `transport` (the path was
   lost) also reopens the session; any other revocation code, or none, ends
@@ -240,6 +282,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`
 
@@ -308,28 +359,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:
@@ -344,7 +411,9 @@ link whose `url` query parameter is the URL-encoded bridge WebSocket address:
 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`.
+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

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/DesktopView.kt

@@ -681,8 +681,10 @@ 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.
-          gesture = if (filling || !fitted) Gesture.PAN else if (downOnPicture) Gesture.HOVER else Gesture.LETTERBOX
+          // 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
           if (gesture == Gesture.HOVER) hoverTo(active, event.x, event.y)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@desklink/react-native",
-    "version": "0.5.0",
+    "version": "0.5.2",
     "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' },
+});

package/src/DesktopView.ios.spec.tsx

@@ -266,6 +266,23 @@ describe('DesktopView.ios parity with DesktopView.kt', () => {
         expect(sent.filter((message) => message.kind === 'pointer' && message.phase === 'move')).not.toEqual([]);
     });
 
+    it('carries a one-finger drag from the moment the picture exists, in portrait', async () => {
+        // The state a session starts in: the picture at its default fill, before
+        // anything has been zoomed. In portrait that fill is the fit, so the
+        // picture has nowhere to pan to and the finger belongs to the desktop.
+        const { sent, rtcStyle, grant, move, release } = await openView({ whole: false });
+        const before = rtcStyle();
+        grant([touch(100, 100)]);
+        move([touch(160, 120)]);
+        move([touch(220, 140)]);
+        release();
+        const moves = sent.filter((message) => message.kind === 'pointer' && message.phase === 'move');
+        expect(moves).toHaveLength(2);
+        expect(moves[1].x).toBeGreaterThan(moves[0].x);
+        expect(moves[1].y).toBeGreaterThan(moves[0].y);
+        expect(rtcStyle()).toEqual(before);
+    });
+
     it('zooms around the pinch focus and re-clamps after zooming out', async () => {
         const { rtcStyle, grant, move } = await openView();
         grant([touch(100, 400)]);

package/src/DesktopView.ios.tsx

@@ -67,11 +67,16 @@ function loadRTCView(): React.ComponentType<Record<string, unknown>> | null {
 /** An offset that the edge clamp turns into the desktop's top-left corner. */
 const TOP_LEFT: Point = { x: Infinity, y: Infinity };
 
-export function DesktopView({ sessionId, style, placeholder, accessibilityLabel, keyboardClearance = 0, insets, gestures = 'desktop' }: DesktopViewProps) {
+export function DesktopView({ sessionId, style, placeholder, accessibilityLabel, keyboardClearance = 0, insets, gestures = 'desktop', onPictureFrame }: DesktopViewProps) {
     const [revision, refresh] = React.useReducer((n: number) => n + 1, 0);
     const [bounds, setBounds] = React.useState({ width: 0, height: 0 });
     const [size, setSize] = React.useState(() => getDesktopSize(sessionId) ?? { width: 0, height: 0 });
-    const [keyboardHeight, setKeyboardHeight] = React.useState(0);
+    /** How much of the view's bottom the keyboard covers, measured against where the view is on screen. */
+    const [keyboardOverlap, setKeyboardOverlap] = React.useState(0);
+    /** The keyboard's top on screen while it is up. */
+    const keyboardTop = React.useRef<number | null>(null);
+    /** Where the desktop's pointer was last sent, in desktop pixels: where a tap just put the caret. */
+    const pointerAt = React.useRef<Point | null>(null);
     /** Zoom over the whole-desktop fit; null fills the view, the default. */
     const [zoom, setZoom] = React.useState<number | null>(null);
     /** From the middle of the uncovered part of the view; clamped to the picture's edges when shown. */
@@ -100,9 +105,11 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
         return observeDesktopSurface(() => { refresh(); setEnabled(desktopInputEnabled(sessionId)); });
     }, [sessionId]);
     React.useEffect(() => {
-        const show = Keyboard.addListener('keyboardWillShow', (event) => setKeyboardHeight(event.endCoordinates.height));
-        const hide = Keyboard.addListener('keyboardWillHide', () => setKeyboardHeight(0));
+        const show = Keyboard.addListener('keyboardWillShow', (event) => { keyboardTop.current = event.endCoordinates.screenY; measureKeyboard(); });
+        const hide = Keyboard.addListener('keyboardWillHide', () => { keyboardTop.current = null; setKeyboardOverlap(0); });
         return () => { show.remove(); hide.remove(); };
+        // `measureKeyboard` reads refs only.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
     React.useEffect(() => {
         // A held drag belongs to the old meaning: let go of the button rather
@@ -135,7 +142,7 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
     const left = insets?.left ?? 0;
     const safeWidth = Math.max(1, bounds.width - left - (insets?.right ?? 0));
     const safeHeight = Math.max(1, bounds.height - top - (insets?.bottom ?? 0));
-    const visibleBottom = Math.min(top + safeHeight, bounds.height - (keyboardHeight ? keyboardHeight + keyboardClearance : 0));
+    const visibleBottom = Math.min(top + safeHeight, bounds.height - (keyboardOverlap ? keyboardOverlap + keyboardClearance : 0));
     const visibleHeight = Math.max(1, visibleBottom - top);
     const fit = size.width && size.height ? Math.min(safeWidth / size.width, visibleHeight / size.height) : 1;
     const defaultScale = bounds.width <= bounds.height
@@ -169,6 +176,31 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
     const shown = clampOffset(offset.x, offset.y);
     const originX = left + (safeWidth - pictureWidth) / 2 + shown.x;
     const originY = top + (zoom === null && pictureHeight <= visibleHeight ? 0 : (visibleHeight - pictureHeight) / 2) + shown.y;
+    // The keyboard took (or gave back) the bottom of the view. A picture taller
+    // than what is left is moved so the pointer, where a tap just put the
+    // caret, stays in sight, as `DesktopView.kt` does.
+    const shownBottom = React.useRef(visibleBottom);
+    React.useLayoutEffect(() => {
+        const before = shownBottom.current;
+        shownBottom.current = visibleBottom;
+        const at = pointerAt.current;
+        if (Math.abs(visibleBottom - before) < 0.5 || !at) return;
+        const y = originY + (at.y + 0.5) * scale;
+        const margin = Math.min(56, visibleBottom / 4);
+        if (y > visibleBottom - margin) setOffset(clampOffset(shown.x, shown.y - (y - (visibleBottom - margin))));
+        // Only a change in what the keyboard covers moves the picture.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [visibleBottom]);
+    // An application's controls can sit under the picture instead of over it,
+    // so it needs to know where the picture ended. Reported only when the
+    // picture moved: the callback sets state, and a fresh callback each render
+    // would otherwise loop.
+    const frame = React.useRef({ top: -1, height: -1 });
+    React.useEffect(() => {
+        if (frame.current.top === originY && frame.current.height === pictureHeight) return;
+        frame.current = { top: originY, height: pictureHeight };
+        onPictureFrame?.(frame.current);
+    }, [onPictureFrame, originY, pictureHeight]);
     const send = (control: Record<string, unknown>) => { if (sessionId) nativeDesklink.sendControl(sessionId, JSON.stringify(control)); };
     const flushWheel = (force: boolean) => {
         const { x, y } = wheel.current;
@@ -179,6 +211,7 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
     };
     const pointer = (phase: string, at: Point, button?: number, mark = true) => {
         send({ kind: 'pointer', phase, x: at.x, y: at.y, ...(button ? { button } : {}) });
+        pointerAt.current = at;
         // A device screen shows the touch itself; a cursor would be a second finger that lies.
         // A trackpad or mouse has the system's own pointer on screen.
         if (!mark) setCursor(null);
@@ -287,7 +320,13 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
                 g.mode = 'scroll';
                 const under = point(at.x, at.y);
                 if (under) pointer('move', under);
-            } else g.mode = zoom === null || zoomed > 1.001 ? 'pan' : 'hover';
+            } else {
+                // A whole desktop has nowhere to move to, so the finger moves the
+                // desktop's pointer instead. It is the zoom over the fit, not the
+                // default fill, that says there is room to pan: a fill that landed
+                // on the fit has none.
+                g.mode = zoomed > 1.001 ? 'pan' : 'hover';
+            }
         }
         if (g.mode === 'scroll') {
             // Content follows the finger: moving it up scrolls the page down.
@@ -410,7 +449,19 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
         wheel.current.y += -dy / scale / PIXELS_PER_DETENT;
         flushWheel(false);
     };
-    const onLayout = (event: LayoutChangeEvent) => setBounds(event.nativeEvent.layout);
+    /**
+     * The keyboard covers only the part of the view below its top: the view can
+     * end above the screen's bottom. The hidden input sits at the view's bottom
+     * edge, so it says where that edge is on screen.
+     */
+    const measureKeyboard = () => {
+        const keyboardAt = keyboardTop.current;
+        if (keyboardAt === null) return;
+        input.current?.measureInWindow((_x, y, _width, height) => {
+            if (keyboardTop.current === keyboardAt) setKeyboardOverlap(Math.max(0, y + height - keyboardAt));
+        });
+    };
+    const onLayout = (event: LayoutChangeEvent) => { setBounds(event.nativeEvent.layout); measureKeyboard(); };
     const surface: ViewProps = {
         style: [styles.surface, style], onLayout, accessible: accessibilityLabel !== undefined, accessibilityLabel,
         onStartShouldSetResponder: () => enabled, onMoveShouldSetResponder: () => enabled,

package/src/DesktopView.tsx

@@ -35,6 +35,13 @@ export interface DesktopViewProps {
      * (one finger scrolls), or a device screen (one finger presses and drags).
      */
     gestures?: GestureProfile;
+    /**
+     * Where the picture ended, in the view's own points, whenever it moves.
+     * A wide desktop on a tall screen leaves a band under the picture; this is
+     * how an application lays its own controls into that band instead of
+     * guessing the desktop's aspect.
+     */
+    onPictureFrame?: (frame: { top: number; height: number }) => void;
 }
 
 interface NativeSurfaceProps {

package/src/ModifierKeys.tsx

@@ -0,0 +1,77 @@
+import * as React from 'react';
+import { Pressable, StyleSheet, Text, View, type StyleProp, type ViewStyle } from 'react-native';
+
+import type { StickyModifier, StickyModifiers, StickyState } from './stickyModifiers';
+
+export interface ModifierKeysProps {
+    /** The session's `modifiers`. */
+    modifiers: StickyModifiers;
+    /** The session's `tapModifier`. */
+    onTap: (name: StickyModifier) => void;
+    style?: StyleProp<ViewStyle>;
+    /**
+     * Tablet targets: the keys share the width and take the height the row is
+     * given, instead of sitting at 44 pt in a row of a phone's. A row shorter
+     * than the keys' minimum keeps the minimum.
+     */
+    grow?: boolean;
+}
+
+const LABELS: Record<StickyModifier, string> = { Control: 'Ctrl', Shift: 'Shift', Alt: 'Alt', Meta: 'Meta' };
+/** What a screen reader says for each state; "once" is the latch the user sees. */
+export const STATE_NAMES: Record<StickyState, string> = { off: 'off', once: 'latched', lock: 'locked' };
+
+/**
+ * The sticky modifier keys as a row the user can read at a glance.
+ *
+ * Off is an outlined dark key, latched is a filled key, and locked is a
+ * filled key with a white rim and a bar under its label, so the three differ
+ * in shape as well as colour. The row carries its own backing, so it reads
+ * the same over a light desktop as over a dark one.
+ */
+export function ModifierKeys({ modifiers, onTap, style, grow }: ModifierKeysProps) {
+    return (
+        <View style={[styles.row, grow && styles.grown, style]}>
+            {(['Control', 'Shift', 'Alt', 'Meta'] as const).map((name) => {
+                const state = modifiers[name];
+                return (
+                    <Pressable
+                        key={name}
+                        testID={`desklink-key-${name}`}
+                        accessibilityRole="button"
+                        accessibilityLabel={LABELS[name]}
+                        accessibilityState={{ selected: state !== 'off' }}
+                        accessibilityValue={{ text: STATE_NAMES[state] }}
+                        onPress={() => onTap(name)}
+                        style={[styles.key, grow && styles.keyGrown, state === 'off' ? styles.off : styles.on, state === 'lock' && styles.lock]}
+                    >
+                        <Text style={state === 'off' ? styles.offLabel : styles.onLabel}>{LABELS[name]}</Text>
+                        <View style={[styles.bar, state === 'lock' && styles.barShown]} />
+                    </Pressable>
+                );
+            })}
+        </View>
+    );
+}
+
+export const KEY_COLORS = {
+    backing: 'rgba(22, 23, 26, 0.94)',
+    off: '#2b2d33',
+    offLabel: '#c9ccd3',
+    on: '#2563eb',
+    onLabel: '#ffffff',
+};
+
+const styles = StyleSheet.create({
+    row: { flexDirection: 'row', flexWrap: 'wrap', gap: 8, padding: 8, backgroundColor: KEY_COLORS.backing },
+    grown: { width: '100%', flexGrow: 1, maxHeight: 160 },
+    key: { minWidth: 56, maxWidth: '100%', minHeight: 44, paddingHorizontal: 12, borderRadius: 8, borderWidth: 2, alignItems: 'center', justifyContent: 'center' },
+    keyGrown: { flexGrow: 1, minHeight: 96, paddingHorizontal: 24 },
+    off: { backgroundColor: KEY_COLORS.off, borderColor: '#4b4e57' },
+    on: { backgroundColor: KEY_COLORS.on, borderColor: KEY_COLORS.on },
+    lock: { borderColor: '#ffffff' },
+    offLabel: { color: KEY_COLORS.offLabel, fontSize: 15, fontWeight: '500' },
+    onLabel: { color: KEY_COLORS.onLabel, fontSize: 15, fontWeight: '700' },
+    bar: { marginTop: 3, width: 18, height: 3, borderRadius: 2, backgroundColor: 'transparent' },
+    barShown: { backgroundColor: '#ffffff' },
+});

package/src/controls.spec.tsx

@@ -0,0 +1,205 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import React from 'react';
+import TestRenderer, { act } from 'react-test-renderer';
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+/** The key row and the clipboard pill, rendered with `react-native` primitives as host strings. */
+vi.mock('react-native', () => ({
+    StyleSheet: { create: (styles: unknown) => styles, absoluteFill: {} },
+    Linking: { getInitialURL: async () => null, addEventListener: () => ({ remove: () => undefined }) },
+    Platform: { OS: 'ios' },
+    Pressable: 'Pressable',
+    ScrollView: 'ScrollView',
+    StatusBar: 'StatusBar',
+    Text: 'Text',
+    View: 'View',
+    Settings: { get: () => 'ws://localhost/desktop?token=test' },
+}));
+
+vi.mock('react-native-safe-area-context', () => ({
+    SafeAreaProvider: ({ children }: { children: React.ReactNode }) => children,
+    useSafeAreaInsets: () => ({ top: 0, left: 0, bottom: 0, right: 0 }),
+}));
+
+const example = vi.hoisted(() => ({
+    write: vi.fn(),
+    copy: vi.fn(),
+    connect: vi.fn(),
+}));
+vi.mock('expo-clipboard', () => ({ setStringAsync: example.write }));
+vi.mock('@desklink/react-native', async () => ({
+    CONTROL_PERMISSIONS: ['view', 'control', 'clipboard'],
+    ClipboardConfirmation: (await import('./ClipboardConfirmation')).ClipboardConfirmation,
+    ModifierKeys: (await import('./ModifierKeys')).ModifierKeys,
+    DesktopView: 'DesktopView',
+    useDesktopSession: () => ({
+        snapshot: { status: 'live' },
+        nativeId: 'example-session',
+        modifiers: { Control: 'off', Shift: 'off', Alt: 'off', Meta: 'off' },
+        clipboard: null,
+        connect: example.connect,
+        setInputEnabled: vi.fn(),
+        copyRemoteToLocal: example.copy,
+        tapModifier: vi.fn(),
+    }),
+}));
+
+import { KEY_COLORS, ModifierKeys } from './ModifierKeys';
+import { CLIPBOARD_CONFIRMATION_MS, ClipboardConfirmation, PILL_COLORS, describeTransfer } from './ClipboardConfirmation';
+import { NO_MODIFIERS } from './stickyModifiers';
+import type { ClipboardTransfer } from './useDesktopSession';
+import App from '../example/App';
+
+type Style = Record<string, unknown>;
+const flatten = (style: unknown): Style =>
+    Array.isArray(style) ? Object.assign({}, ...style.map(flatten)) : style ? (style as Style) : {};
+
+/** WCAG contrast of two colours, the first drawn with its alpha over `under`. */
+function contrast(top: string, bottom: string, under = '#000000'): number {
+    const rgba = (c: string) => {
+        const m = c.match(/rgba?\(([^)]+)\)/);
+        if (m) { const [r, g, b, a = 1] = m[1].split(',').map(Number); return [r, g, b, a]; }
+        return [1, 3, 5].map((i) => parseInt(c.slice(i, i + 2), 16)).concat(1);
+    };
+    const over = (c: string) => {
+        const [r, g, b, a] = rgba(c);
+        const [ur, ug, ub] = rgba(under);
+        return [r * a + ur * (1 - a), g * a + ug * (1 - a), b * a + ub * (1 - a)];
+    };
+    const lum = (rgb: number[]) => {
+        const [r, g, b] = rgb.map((v) => { const s = v / 255; return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; });
+        return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    };
+    const [l1, l2] = [lum(over(top)), lum(over(bottom))].sort((a, b) => b - a);
+    return (l1 + 0.05) / (l2 + 0.05);
+}
+
+describe('ModifierKeys', () => {
+    function render(modifiers = NO_MODIFIERS, onTap = vi.fn()) {
+        let tree!: TestRenderer.ReactTestRenderer;
+        act(() => { tree = TestRenderer.create(<ModifierKeys modifiers={modifiers} onTap={onTap} />); });
+        const key = (name: string) => tree.root.find((node) => node.props.testID === `desklink-key-${name}`);
+        return { key, onTap };
+    }
+
+    it('draws off, latched and locked as three different keys and names each state', () => {
+        const { key } = render({ Control: 'off', Shift: 'once', Alt: 'lock', Meta: 'off' });
+        const look = (name: string) => {
+            const node = key(name);
+            const [, bar] = node.props.children;
+            return { key: flatten(node.props.style), bar: flatten(bar.props.style), said: node.props.accessibilityValue.text };
+        };
+        const off = look('Control');
+        const latched = look('Shift');
+        const locked = look('Alt');
+        expect([off.said, latched.said, locked.said]).toEqual(['off', 'latched', 'locked']);
+        expect(off.key.backgroundColor).not.toBe(latched.key.backgroundColor);
+        // Latched and locked share a fill and differ in shape: the rim and the bar.
+        expect(locked.key.borderColor).not.toBe(latched.key.borderColor);
+        expect(locked.bar.backgroundColor).not.toBe(latched.bar.backgroundColor);
+        expect(key('Control').props.accessibilityState).toEqual({ selected: false });
+        expect(key('Shift').props.accessibilityState).toEqual({ selected: true });
+    });
+
+    it('hands a tap to the session', () => {
+        const { key, onTap } = render();
+        key('Control').props.onPress();
+        expect(onTap).toHaveBeenCalledWith('Control');
+    });
+
+    it('keeps every label at 4.5:1 or better', () => {
+        expect(contrast(KEY_COLORS.offLabel, KEY_COLORS.off)).toBeGreaterThanOrEqual(4.5);
+        expect(contrast(KEY_COLORS.onLabel, KEY_COLORS.on)).toBeGreaterThanOrEqual(4.5);
+    });
+});
+
+describe('ClipboardConfirmation', () => {
+    beforeEach(() => { vi.useFakeTimers(); });
+    afterEach(() => { vi.useRealTimers(); });
+
+    const transfer = (id: number, text = 'hello world'): ClipboardTransfer => ({ id, direction: 'to-desktop', text, truncated: false });
+
+    it('shows each transfer, ignores touches, and goes away after about 1.5 s', () => {
+        let tree!: TestRenderer.ReactTestRenderer;
+        act(() => { tree = TestRenderer.create(<ClipboardConfirmation transfer={null} />); });
+        expect(tree.toJSON()).toBeNull();
+
+        act(() => { tree.update(<ClipboardConfirmation transfer={transfer(1)} />); });
+        const place = tree.toJSON() as TestRenderer.ReactTestRendererJSON;
+        expect(place.props.pointerEvents).toBe('none');
+        expect(flatten(place.props.style).position).toBeUndefined();
+        expect(JSON.stringify(place)).toContain('Sent to desktop · “hello world”');
+
+        act(() => { vi.advanceTimersByTime(CLIPBOARD_CONFIRMATION_MS - 1); });
+        expect(tree.toJSON()).not.toBeNull();
+        act(() => { vi.advanceTimersByTime(1); });
+        expect(tree.toJSON()).toBeNull();
+
+        // The same text again is a new transfer and is confirmed again.
+        act(() => { tree.update(<ClipboardConfirmation transfer={transfer(2)} />); });
+        expect(tree.toJSON()).not.toBeNull();
+    });
+
+    it('describes where the text went and how it starts, with no byte count', () => {
+        expect(describeTransfer({ id: 1, direction: 'to-phone', text: 'a\n  b', truncated: false })).toBe('Copied to phone · “a b”');
+        expect(describeTransfer({ id: 1, direction: 'to-phone', text: 'x'.repeat(2048), truncated: true })).toBe(`Copied to phone · “${'x'.repeat(24)}…”`);
+        expect(describeTransfer({ id: 1, direction: 'to-desktop', text: ' ', truncated: false })).toBe('Sent to desktop');
+    });
+
+    it('reads at 4.5:1 or better over a white or a black desktop', () => {
+        expect(contrast(PILL_COLORS.text, PILL_COLORS.backing, '#ffffff')).toBeGreaterThanOrEqual(4.5);
+        expect(contrast(PILL_COLORS.text, PILL_COLORS.backing, '#000000')).toBeGreaterThanOrEqual(4.5);
+    });
+});
+
+describe('example Copy', () => {
+    it('writes only on a tap and retains a backed accessible failure until the next tap', async () => {
+        example.write.mockReset();
+        example.copy.mockReset();
+        example.copy.mockImplementation(async (write: (text: string) => Promise<void>) => { await write('desktop text'); });
+        let tree!: TestRenderer.ReactTestRenderer;
+        await act(async () => { tree = TestRenderer.create(<App />); });
+        expect(example.write).not.toHaveBeenCalled();
+        const tap = () => tree.root.findByProps({ testID: 'desklink-copy' }).props.onPress();
+
+        example.copy.mockRejectedValueOnce(new Error('clipboard is unavailable for this desktop source'));
+        await act(async () => { tap(); });
+        expect(tree.root.findByProps({ testID: 'desklink-copy-error' }).findByType('Text').props.children)
+            .toBe('Clipboard failed: clipboard is unavailable for this desktop source');
+        expect(example.write).not.toHaveBeenCalled();
+
+        example.write.mockResolvedValue(false);
+        await act(async () => { tap(); });
+        expect(example.write).toHaveBeenCalledWith('desktop text');
+        const error = tree.root.findByProps({ testID: 'desklink-copy-error' });
+        expect(error.props.accessible).toBe(true);
+        expect(error.props.accessibilityRole).toBe('alert');
+        expect(error.props.accessibilityLiveRegion).toBe('polite');
+        const style = flatten(error.props.style);
+        expect(style.paddingHorizontal).toBeGreaterThan(0);
+        expect(style.paddingVertical).toBeGreaterThan(0);
+        expect(contrast('#ffffff', style.backgroundColor as string)).toBeGreaterThanOrEqual(4.5);
+        expect(error.findByType('Text').props.children).toBe('Clipboard failed: The phone refused the clipboard write.');
+        expect(tree.root.findAllByProps({ testID: 'desklink-clipboard' })).toHaveLength(0);
+
+        vi.useFakeTimers();
+        try {
+            act(() => { vi.advanceTimersByTime(5000); });
+            expect(tree.root.findAllByProps({ testID: 'desklink-copy-error' })).toHaveLength(1);
+        } finally { vi.useRealTimers(); }
+
+        example.write.mockRejectedValue(new Error('native write refused'));
+        await act(async () => { tap(); });
+        expect(tree.root.findByProps({ testID: 'desklink-copy-error' }).findByType('Text').props.children).toBe('Clipboard failed: native write refused');
+
+        let finish!: (written: boolean) => void;
+        example.write.mockImplementation(() => new Promise<boolean>((resolve) => { finish = resolve; }));
+        await act(async () => { tap(); });
+        expect(tree.root.findAllByProps({ testID: 'desklink-copy-error' })).toHaveLength(0);
+        expect(tree.root.findAllByProps({ testID: 'desklink-clipboard' })).toHaveLength(0);
+        await act(async () => { finish(true); });
+        expect(tree.root.findAllByProps({ testID: 'desklink-copy-error' })).toHaveLength(0);
+        act(() => { tree.unmount(); });
+    });
+});

package/src/index.ts

@@ -13,9 +13,12 @@ export { desktopAvailable } from './availability';
 export { DesktopView, type DesktopViewProps, type EdgeInsets } from './DesktopView';
 export { observeWebKeyboardMotion } from './webKeyboardMotion';
 export type { StickyModifier, StickyModifiers, StickyState } from './stickyModifiers';
+export { ModifierKeys, type ModifierKeysProps } from './ModifierKeys';
+export { ClipboardConfirmation, type ClipboardConfirmationProps } from './ClipboardConfirmation';
 export {
     useDesktopSession,
     CONTROL_PERMISSIONS,
+    type ClipboardTransfer,
     type DesktopSession,
     type DesktopSessionOptions,
 } from './useDesktopSession';

package/src/protocol.ts

@@ -56,10 +56,17 @@ export interface SessionOpenRequest {
     iceServers?: IceServerConfig[];
     restoreToken?: string;
     ttlSeconds?: number;
+    /**
+     * Ask the engine to also offer ICE over TCP on its own loopback, for a
+     * client whose only way to this computer is a forward of that loopback
+     * (an SSH tunnel, `adb reverse`). A client with a UDP path keeps it: ICE
+     * prefers UDP whenever it has one.
+     */
+    loopbackTcp?: boolean;
 }
 
 export interface SessionOpenResult {
-    cursor?: { mode: 'embedded' | 'hidden' | 'metadata' | 'unavailable'; positions: boolean };
+    cursor?: { mode: 'embedded' | 'hidden' | 'metadata' | 'unavailable'; positions: boolean; source?: 'ext-image-copy-capture-v1'; limitation?: string };
     sessionId: string;
     generation: number;
     source: { kind: string; width: number; height: number; origin: { x: number; y: number } };
@@ -83,6 +90,7 @@ export interface CursorSample {
     y: number;
     visible: boolean;
     timestamp_us: number;
+    hotspot?: { x: number; y: number };
 }
 
 /**

package/src/useDesktopSession.ts

@@ -25,6 +25,14 @@ import {
     type StickyModifiers,
 } from './stickyModifiers';
 
+/** One clipboard transfer that reached its destination; `id` tells two equal transfers apart. */
+export interface ClipboardTransfer {
+    id: number;
+    direction: 'to-phone' | 'to-desktop';
+    text: string;
+    truncated: boolean;
+}
+
 /** How long a clipboard round trip may take before it is reported as lost. */
 const CLIPBOARD_TIMEOUT_MS = 4000;
 
@@ -49,6 +57,35 @@ const STALL_AFTER_MS = 1200;
 const RESTART_GRACE_MS = 2500;
 /** How long a restart offer may go unanswered before the next attempt. */
 const RESTART_REPLY_MS = 5000;
+/**
+ * How long the media path may carry nothing at all before a session that says
+ * `live` stops saying so. The engine's transport state reaches the client over
+ * the signalling channel, which is not part of the media path, so a dead link
+ * with signalling up reads as `connected` over a picture that has stopped: live
+ * has to mean the picture is advancing, not that someone answered.
+ */
+const FROZEN_AFTER_MS = 2000;
+/** How often the media path is read while the session claims to be live. */
+const MEDIA_POLL_MS = 500;
+
+/**
+ * What the receiver has taken in, summed over its video streams: new decoded
+ * frames, and packets that arrived at all. Either moving means the picture is
+ * advancing; a still screen that keeps no frames moving is not a dead path, so
+ * both counts are read rather than frames alone.
+ */
+function mediaCounts(rows: Array<Record<string, unknown>>): { frames: number; packets: number } | null {
+    let frames = 0;
+    let packets = 0;
+    let streams = 0;
+    for (const row of rows) {
+        if (row.mediaType !== undefined && row.mediaType !== 'video') continue;
+        streams += 1;
+        frames += typeof row.framesDecoded === 'number' ? row.framesDecoded : 0;
+        packets += typeof row.packetsReceived === 'number' ? row.packetsReceived : 0;
+    }
+    return streams === 0 ? null : { frames, packets };
+}
 /**
  * Full session reopens back off across about a minute, holding at patient
  * 8 s retries: a return must never wait out a 32 s gap, and an attempt every
@@ -86,13 +123,17 @@ export type ConnectionStateName =
  * What one ICE/engine-transport state means for the session status, or null
  * when it changes nothing. `disconnected` surfaces as `reconnecting` at once —
  * event-driven, so within about a second of the drop — and `connected` moves a
- * session that had shown frames back to `live`. `failed` is terminal and is
- * handled by the failure path, not here.
+ * session whose picture is advancing back to `live`. `failed` is terminal and
+ * is handled by the failure path, not here.
+ *
+ * `advancing` is the media path, not the transport: a transport that answers
+ * with a still image is not a live desktop, so a session whose picture has
+ * stopped stays out of `live` whatever the transport reports.
  */
 export function connectionStatusFor(
     state: string,
     status: SessionSnapshot['status'],
-    presented: boolean,
+    advancing: boolean,
 ): SessionSnapshot['status'] | null {
     switch (state) {
         case 'disconnected':
@@ -100,9 +141,9 @@ export function connectionStatusFor(
         case 'connected':
         case 'completed':
             if (status !== 'reconnecting') return null;
-            // Frames were never shown: this is still the first connection, not
-            // a recovery, so it stays `connecting` until a frame renders.
-            return presented ? 'live' : 'connecting';
+            // No picture is moving: this is still the first connection, not a
+            // recovery, so it stays `connecting` until frames advance again.
+            return advancing ? 'live' : 'connecting';
         default:
             return null;
     }
@@ -116,6 +157,15 @@ export function connectionStatusFor(
 const UNREACHABLE_DESKTOP =
     'The phone must reach the desktop directly, on the same network or its tailnet. Other networks need a relay route supplied by the app.';
 
+/**
+ * A connection that never shows a frame is a connection that never formed, and
+ * saying so beats an empty picture: on a path that only reaches the desktop
+ * through a tunnel or a USB forward, the app has to ask for the loopback route.
+ */
+export const FIRST_FRAME_AFTER_MS = 20_000;
+const NO_PICTURE =
+    'The desktop never sent a picture. On a path that only reaches the desktop through a tunnel or a USB forward, open the session with loopbackTcp: true.';
+
 /**
  * The engine's and host's own refusal tokens, mapped to this package's failure
  * codes. A token the engine did not send is a deliberate refusal, not a network
@@ -199,8 +249,8 @@ export interface DesktopSession {
     close: (reason?: string) => Promise<void>;
     showKeyboard: () => void;
     hideKeyboard: () => void;
-    /** Copy the desktop's clipboard to the phone; the caller places it locally. */
-    copyRemoteToLocal: () => Promise<{ text: string; truncated: boolean }>;
+    /** Copy using the caller's local writer, which must reject if the write fails. */
+    copyRemoteToLocal: (writeLocal: (text: string) => Promise<void>) => Promise<{ text: string; truncated: boolean }>;
     /** Send the phone's clipboard text to the desktop. */
     pasteLocalToRemote: (text: string) => Promise<void>;
     /** Release anything the desktop is holding, without ending the session. */
@@ -221,6 +271,8 @@ export interface DesktopSession {
      * because the engine lets go of exactly the modifiers the message names.
      */
     pressKey: (name: string) => () => void;
+    /** The last clipboard transfer that completed, for the app to confirm; null until one does. */
+    clipboard: ClipboardTransfer | null;
 }
 
 const IDLE: SessionSnapshot = {
@@ -245,6 +297,8 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     const [modifiers, setModifiers] = useState<StickyModifiers>(NO_MODIFIERS);
     /** Read by input as it arrives, which can be faster than a render. */
     const modifiersRef = useRef<StickyModifiers>(NO_MODIFIERS);
+    const [clipboard, setClipboard] = useState<ClipboardTransfer | null>(null);
+    const clipboardCount = useRef(0);
 
     const opened = useRef<SessionOpenResult | null>(null);
     const signaling = useRef<Signaling | null>(null);
@@ -270,8 +324,18 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     const restartTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
     /** The pending stall watchdog, armed by heartbeats. */
     const stallTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+    /** Armed while a first connection waits for its first frame. */
+    const firstFrameTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
     /** When the last heartbeat arrived, or 0 before the first one. */
     const lastPingAt = useRef(0);
+    /** The pending media read, armed while the session claims to be live. */
+    const mediaTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+    /** The receiver's counts at the last media read, to see the next one move. */
+    const mediaRef = useRef<{ frames: number; packets: number } | null>(null);
+    /** When the media path last moved, or null while it has never moved. */
+    const mediaMovingAt = useRef<number | null>(null);
+    /** Whether the picture of an open session has stopped advancing. */
+    const frozen = useRef(false);
     /** Renegotiation transients are not a new outage before this time. */
     const restartGraceUntil = useRef(0);
     /** ICE-restart attempts spent on the current drop. */
@@ -343,6 +407,24 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         stallTimer.current = null;
     }, []);
 
+    const cancelFirstFrame = useCallback(() => {
+        if (firstFrameTimer.current !== null) clearTimeout(firstFrameTimer.current);
+        firstFrameTimer.current = null;
+    }, []);
+
+    /**
+     * A first connection that stays frameless for this long is not going to
+     * arrive: report why instead of leaving an empty picture on screen.
+     */
+    const armFirstFrame = useCallback(() => {
+        cancelFirstFrame();
+        firstFrameTimer.current = setTimeout(() => {
+            firstFrameTimer.current = null;
+            if (presentedRef.current || statusRef.current !== 'connecting') return;
+            transportFailed(NO_PICTURE);
+        }, FIRST_FRAME_AFTER_MS);
+    }, [cancelFirstFrame, transportFailed]);
+
     const scheduleRestartRef = useRef<(delay: number) => void>(() => undefined);
 
     /**
@@ -352,7 +434,11 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
      */
     const spendRestartAttempt = useCallback((): void => {
         if (statusRef.current !== 'reconnecting' || nativeRef.current == null) return;
-        const wait = backoffDelay(RESTART_BACKOFF_MS, restartAttempts.current);
+        // A frozen picture is the media path itself, and a restart is what
+        // rebuilds it, so the short delay keeps being spent until frames move
+        // again. Backing off to half a minute while the picture is stopped
+        // leaves the user looking at a still image long after the link is back.
+        const wait = frozen.current ? RESTART_AFTER_MS : backoffDelay(RESTART_BACKOFF_MS, restartAttempts.current);
         if (wait === null) {
             transportFailed('the desktop did not come back; reopening the session');
             return;
@@ -400,7 +486,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                 // the session itself is wedged and only a reopen heals it.
                 // (While ICE is down, patience: the network may still come
                 // back, and the backoff schedule owns that case.)
-                if (restartCycles.current >= 2 && iceConnected.current) {
+                if (restartCycles.current >= 2 && iceConnected.current && !frozen.current) {
                     transportFailed('the desktop stopped responding; reopening the session');
                     return;
                 }
@@ -408,7 +494,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                 // which the session answers as usual; without recovery by the
                 // reply deadline, spend the next attempt. A live transport
                 // answers in milliseconds, so hold it to a short leash.
-                const replyMs = iceConnected.current ? 2000 : RESTART_REPLY_MS;
+                const replyMs = frozen.current ? RESTART_AFTER_MS : iceConnected.current ? 2000 : RESTART_REPLY_MS;
                 restartTimer.current = setTimeout(() => {
                     restartTimer.current = null;
                     spendRestartAttempt();
@@ -420,22 +506,36 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     useEffect(() => {
         scheduleRestartRef.current = scheduleRestart;
         checkStallRef.current = checkStall;
+        mediaWatchRef.current = checkMedia;
     });
 
     const checkStallRef = useRef(() => {});
+    const mediaWatchRef = useRef<() => void>(() => undefined);
+
+    /** Arm one media read; each tick decides whether to arm another. */
+    const armMedia = useCallback((): void => {
+        if (mediaTimer.current !== null) return;
+        mediaTimer.current = setTimeout(() => mediaWatchRef.current(), MEDIA_POLL_MS);
+    }, []);
 
     /**
      * One ICE or engine-transport state, from either reporter. The mapping is
      * idempotent, so the peer's event and the engine's `session.state` telling
      * the same story neither double-counts nor fights.
      */
-    const onTransportState = useCallback((state: string, trackIce = true) => {
+    const onTransportState = useCallback((state: string, trackIce = true, skipGrace = false) => {
         // Synthetic stall reports say nothing about ICE itself.
         if (trackIce) iceConnected.current = state === 'connected' || state === 'completed';
-        const next = connectionStatusFor(state, statusRef.current, presentedRef.current);
-        if (next === null) return;
+        const mapped = connectionStatusFor(state, statusRef.current, presentedRef.current && !frozen.current);
+        if (mapped === null) return;
+        // A transport that answers while the picture is frozen is not a
+        // recovery. For a session that has shown frames that stays `reconnecting`,
+        // rather than falling back to the first connection it has left behind.
+        const next = mapped === 'connecting' && statusRef.current === 'reconnecting' && presentedRef.current
+            ? 'reconnecting'
+            : mapped;
         // Our own restart's transients are expected, not a new outage.
-        if (next === 'reconnecting' && Date.now() < restartGraceUntil.current) return;
+        if (!skipGrace && next === 'reconnecting' && Date.now() < restartGraceUntil.current) return;
         update({ status: next });
         if (next === 'reconnecting') {
             // Only a path that once carried frames is worth restarting: an
@@ -451,9 +551,66 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                 // from here is a stalled session, not a healthy idle one.
                 cancelStall();
                 stallTimer.current = setTimeout(() => checkStallRef.current(), STALL_AFTER_MS);
+                // And the picture is what says live, so it is watched from here.
+                armMedia();
             }
         }
-    }, [cancelRestart, cancelStall, scheduleRestart, update]);
+    }, [cancelRestart, cancelStall, scheduleRestart, update, armMedia]);
+
+    /**
+     * One read of the receiver's own counts: is the picture actually advancing?
+     *
+     * The engine's transport state arrives over the signalling channel, which
+     * is not the media path, so a link that carries nothing while signalling
+     * answers can hand the session a `connected` it must not believe. This is
+     * the check that keeps `live` honest, and the one that ends the freeze:
+     * frames moving again put the session back to `live` on the same session.
+     */
+    const checkMedia = useCallback((): void => {
+        mediaTimer.current = null;
+        // A session that has shown a picture is watched for as long as it has
+        // one: a freeze that arrives while the session is already reconnecting
+        // is exactly the case where waiting for the transport to say so would
+        // say it for the rest of the outage.
+        if (!presentedRef.current) return;
+        armMedia();
+        const id = nativeRef.current;
+        if (id == null || nativeDesklink?.getStats == null) return;
+        const token = generationToken.current;
+        void nativeDesklink.getStats(id).then((raw) => {
+            if (token !== generationToken.current || nativeRef.current !== id) return;
+            let counts: { frames: number; packets: number } | null;
+            try {
+                counts = mediaCounts(JSON.parse(raw));
+            } catch {
+                return;
+            }
+            // No video stats yet: there is nothing here to judge a picture by.
+            if (counts === null) return;
+            const previous = mediaRef.current;
+            mediaRef.current = counts;
+            const moving = previous === null
+                || counts.frames > previous.frames
+                || counts.packets > previous.packets;
+            if (moving) {
+                mediaMovingAt.current = Date.now();
+                if (!frozen.current) return;
+                frozen.current = false;
+                // The picture advances again, so the transport can be believed
+                // for this session: live returns without waiting for it to say so.
+                if (statusRef.current === 'reconnecting') onTransportState('connected', false);
+                return;
+            }
+            if (mediaMovingAt.current === null) return;
+            if (Date.now() - mediaMovingAt.current < FROZEN_AFTER_MS) return;
+            if (frozen.current) return;
+            frozen.current = true;
+            // The picture has stopped, so the session is not live whatever the
+            // transport reports. When the transport has already said so, there
+            // is nothing to change: the recovery it started is the right one.
+            if (statusRef.current === 'live' || statusRef.current === 'connecting') onTransportState('disconnected', false, true);
+        }, () => undefined);
+    }, [armMedia, onTransportState]);
 
     /**
      * One stall check: quiet too long while the session should be talking
@@ -586,6 +743,13 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         pendingCursorEvents.current = [];
         restartGraceUntil.current = 0;
         restartCycles.current = 0;
+        // A new session has its own media path: the last one's counts and its
+        // freeze say nothing about this one.
+        if (mediaTimer.current !== null) clearTimeout(mediaTimer.current);
+        mediaTimer.current = null;
+        mediaRef.current = null;
+        mediaMovingAt.current = null;
+        frozen.current = false;
         opened.current = null;
         signaling.current = null;
         setNativeId(null);
@@ -615,6 +779,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         cancelReconnect();
         cancelRestart();
         cancelStall();
+        cancelFirstFrame();
         restoreToken.current = null;
         const openedRef = opened.current;
         const owner = signaling.current;
@@ -622,7 +787,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         if (closeRemote) await endRemote(openedRef, owner);
         update({ status: 'ended', presented: false, failure: null });
         void reason;
-    }, [cancelReconnect, cancelRestart, cancelStall, endRemote, discardSession, update]);
+    }, [cancelReconnect, cancelRestart, cancelStall, cancelFirstFrame, endRemote, discardSession, update]);
 
     const establish = useCallback(async () => {
         if (nativeRef.current != null) return;
@@ -739,6 +904,10 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                 // reopen; the app's own grant wins when it names one.
                 restore_token: authorization.session.restoreToken ?? restoreToken.current ?? undefined,
                 ttl_seconds: authorization.session.ttlSeconds,
+                // A TCP-only path (an SSH tunnel, `adb reverse`) can only be
+                // reached on the engine's loopback, which the engine offers
+                // only when the app asks. Off by default, as on the wire.
+                ...(authorization.session.loopbackTcp ? { loopback_tcp: true } : {}),
             });
         } catch (error) {
             const message = error instanceof Error ? error.message : 'the desktop could not start';
@@ -753,6 +922,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                 if (sample.sessionId === openedResult.sessionId) optionsRef.current.onCursor?.(sample);
             }
             update({ geometry: openedResult.geometry, status: 'connecting' });
+            armFirstFrame();
             if (token !== generationToken.current) return;
 
             const platform = nativeDesklink;
@@ -796,7 +966,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                 await endRemote(openedResult, authorization.signaling);
             }
         }
-    }, [discardSession, endRemote, refuse, teardown, transportFailed, update, onTransportState]);
+    }, [armFirstFrame, discardSession, endRemote, refuse, teardown, transportFailed, update, onTransportState]);
 
     /**
      * Open (or reopen) the session with fresh authority. A deliberate call
@@ -857,7 +1027,11 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                         restartAttempts.current = 0;
                         restartCycles.current = 0;
                         cancelRestart();
+                        cancelFirstFrame();
                         update({ status: 'live', presented: true, failure: null });
+                        // A first frame is a picture, so from here the client
+                        // watches that the picture keeps coming.
+                        armMedia();
                         return;
                     case 'control': {
                         const reply = parseControlReply(String(event.payload.message ?? ''));
@@ -887,6 +1061,14 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                             return;
                         }
                         if (reply.kind === 'rejected') {
+                            // These session-wide clipboard refusals have no request ID.
+                            // A generic permission rejection can belong to other input.
+                            if (reply.seq === 0 && (reply.code === 'clipboard-unsupported' || reply.code === 'session')) {
+                                for (const resolve of pendingClipboard.current.values()) {
+                                    resolve({ text: '', truncated: false, error: reply.message });
+                                }
+                                pendingClipboard.current.clear();
+                            }
                             diagnostics.current.lastRejection = `${reply.code}: ${reply.message}`;
                             update({ diagnostics: { ...diagnostics.current } });
                             optionsRef.current.onRejected?.({ code: reply.code, message: reply.message });
@@ -935,9 +1117,9 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
             dropped = true;
             subscription?.remove();
         };
-    }, [transportFailed, onTransportState, cancelRestart, spendRestartAttempt, notePing, teardown, update, pressKey, typeText]);
+    }, [transportFailed, onTransportState, cancelRestart, spendRestartAttempt, notePing, teardown, update, pressKey, typeText, armMedia]);
 
-    const copyRemoteToLocal = useCallback(async () => {
+    const copyRemoteToLocal = useCallback(async (writeLocal: (text: string) => Promise<void>) => {
         if (!inputEnabled.current) throw new Error('Desktop control is off.');
         const id = nativeRef.current;
         if (id == null || nativeDesklink == null) throw new Error('No desktop session is open.');
@@ -951,6 +1133,8 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         nativeDesklink.sendControl(id, JSON.stringify({ kind: 'clipboard_read', request }));
         const reply = await answer;
         if (reply.error != null) throw new Error(reply.error);
+        await writeLocal(reply.text);
+        setClipboard({ id: ++clipboardCount.current, direction: 'to-phone', text: reply.text, truncated: reply.truncated });
         return { text: reply.text, truncated: reply.truncated };
     }, []);
 
@@ -968,6 +1152,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         nativeDesklink.sendControl(id, JSON.stringify({ kind: 'clipboard_write', request, text }));
         const reply = await answer;
         if (reply.error != null) throw new Error(reply.error);
+        setClipboard({ id: ++clipboardCount.current, direction: 'to-desktop', text, truncated: false });
     }, []);
 
     const close = useCallback(async (reason = 'closed by the user') => {
@@ -1008,6 +1193,9 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         cancelReconnect();
         cancelRestart();
         cancelStall();
+        cancelFirstFrame();
+        if (mediaTimer.current !== null) clearTimeout(mediaTimer.current);
+        mediaTimer.current = null;
         generationToken.current += 1;
         const id = nativeRef.current;
         nativeRef.current = null;
@@ -1086,6 +1274,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         modifiers,
         tapModifier,
         pressKey,
+        clipboard,
     }), [
         snapshot,
         nativeId,
@@ -1104,6 +1293,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         modifiers,
         tapModifier,
         pressKey,
+        clipboard,
     ]);
 }