@desklink/react-native 0.5.1 → 0.5.2

package/README.md

@@ -127,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
@@ -164,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
@@ -218,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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@desklink/react-native",
-    "version": "0.5.1",
+    "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/DesktopView.ios.tsx

@@ -71,7 +71,12 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
     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,21 @@ 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
@@ -189,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);
@@ -426,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/protocol.ts

@@ -56,6 +56,13 @@ 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 {

package/src/useDesktopSession.ts

@@ -57,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
@@ -94,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':
@@ -108,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;
     }
@@ -124,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
@@ -282,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. */
@@ -355,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);
 
     /**
@@ -364,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;
@@ -412,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;
                 }
@@ -420,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();
@@ -432,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
@@ -463,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
@@ -598,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);
@@ -627,6 +779,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         cancelReconnect();
         cancelRestart();
         cancelStall();
+        cancelFirstFrame();
         restoreToken.current = null;
         const openedRef = opened.current;
         const owner = signaling.current;
@@ -634,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;
@@ -751,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';
@@ -765,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;
@@ -808,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
@@ -869,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 ?? ''));
@@ -955,7 +1117,7 @@ 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 (writeLocal: (text: string) => Promise<void>) => {
         if (!inputEnabled.current) throw new Error('Desktop control is off.');
@@ -1031,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;