@desklink/react-native 0.5.1 → 0.5.3

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
@@ -138,7 +156,8 @@ heat and battery.
   VP9. Neither platform links a second WebRTC stack.
 - **A sharp, zoomable picture.** In portrait the default is fit-width;
   in landscape it covers the screen below the status bar (as far as the 2.5
-  zoom limit allows). The picture stays undistorted. One finger pans cropped
+  zoom limit allows). The `cover` prop opts portrait into the same
+  coverage, cropping the overflowing sides instead of letterboxing. The picture stays undistorted. One finger pans cropped
   content; pinch to zoom before panning when the whole desktop already fits.
   Pass the screen's safe-area `insets` (for example from
   `react-native-safe-area-context`) so the default starts below the status bar
@@ -164,8 +183,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
@@ -210,33 +231,39 @@ heat and battery.
   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
-  a track or ICE connection as live.
+  the first `RTCView` video-dimensions callback and ignores later ones; web
+  marks the first presented frame and ignores later repaints, so a resize,
+  remount, or renegotiation repaint during a reconnect does not read as live.
+  No platform marks a track or ICE connection as live.
 - **Connection states, as they happen.** The session status is `idle`,
   `opening`, `connecting`, `live`, `reconnecting`, `ended` or `failed`. The
   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
@@ -287,6 +314,15 @@ interface Signaling {
 candidates, state and revocation. Pixels and input do **not** use this
 channel — they are the desktop's own WebRTC session.
 
+`authorize()` must wait for the authenticated carrier to open before returning
+its `Signaling`. When that carrier is gone, reject pending and future requests
+with `code: 'transport'`; do not queue them indefinitely. An adapter may emit
+`{ kind: 'carrier-closed' }` once to notify subscribers of that loss. This is
+not the native peer's `closed` event or an engine revocation. Preserve the
+engine's `session.revoked` code: `transport` indicates path loss; other codes
+(or no code) are final. The demo adapter bounds connection setup to five seconds
+and closes its socket and pending queue when disposed.
+
 ## Shipping on iOS
 
 What the consuming app — not this package — must get right before review.

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

@@ -145,6 +145,10 @@ class DesklinkModule : Module() {
         view.setGestures(gestures ?: "desktop")
       }
 
+      Prop("cover") { view: DesktopView, cover: Boolean? ->
+        view.setCover(cover ?: false)
+      }
+
       OnViewDestroys { view: DesktopView -> view.release() }
 
       OnViewDidUpdateProps { view: DesktopView ->

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

@@ -114,6 +114,19 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
   private var fitted = true
   private var filling = true
   private var filledScale = 0f
+  /**
+   * Opt-in cover: the picture covers the view in every orientation, cropping
+   * the overflowing axis, instead of fitting the portrait width. Off by
+   * default; the default path below is untouched.
+   */
+  private var cover = false
+
+  fun setCover(value: Boolean) {
+    if (value == cover) return
+    cover = value
+    filledScale = 0f
+    layoutPicture()
+  }
 
   /** What the system covers at each edge (bars, cutout), in pixels: left, top, right, bottom. */
   private var insetLeft = 0f
@@ -459,9 +472,11 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
   }
 
   private fun fillScale(): Float {
-    val cover = if (width <= height) safeWidth() / surfaceWidth
-      else max(width.toFloat() / surfaceWidth, (height - insetTop) / surfaceHeight)
-    return max(fitScale(), min(cover, MAX_SCALE))
+    // Portrait fits the width unless the app opted into cover; landscape
+    // covers. Either way the fill never goes below the fit or above the zoom cap.
+    val wide = if (width <= height && !cover) safeWidth() else width.toFloat()
+    val fill = max(wide / surfaceWidth, (height - insetTop) / surfaceHeight)
+    return max(fitScale(), min(fill, MAX_SCALE))
   }
 
   /** Re-derive the placement from `filling`, `fitted`, the zoom limits and the edges. */

package/app.plugin.js

@@ -7,10 +7,233 @@
  * without it.
  *
  *   "plugins": ["@desklink/react-native"]
+ *
+ * The plugin also repairs `expo-modules-jsi` 57.x for Xcode 26 (Swift 6.2).
+ * Two defects, both fatal, both fixed upstream in expo-modules-jsi 58 (SDK 58
+ * is out of scope and the 57 line has no fixed patch release):
+ *
+ * 1. `RuntimeScheduler.h` annotates two C++ constructors with
+ *    `SWIFT_RETURNS_RETAINED`, which Swift 6.2 rejects as a hard error
+ *    ("not returning a SWIFT_SHARED_REFERENCE type"), so no 57-line app
+ *    compiles. Mirrored from 58: private constructors plus static `create`
+ *    factories carrying the annotation, with the Swift call sites moved over.
+ * 2. `JavaScriptRuntime.swift` captures raw JSI pointers through
+ *    `nonisolated(unsafe)` locals into `JavaScriptActor.assumeIsolated`
+ *    closures, which Swift 6.2 rejects ("sending ... risks causing data
+ *    races") now that `assumeIsolated` takes a `sending` closure. Mirrored
+ *    from 58: an `UncheckedSendable` box plus `.value` at the use sites.
+ *
+ * Applied to the installed package at prebuild time, before `pod install`
+ * compiles it. Scoped to the 57 line: other versions skip untouched.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const JSI_HEADER = 'apple/Sources/ExpoModulesJSI-Cxx/include/RuntimeScheduler.h';
+const JSI_SWIFT = 'apple/Sources/ExpoModulesJSI/Runtime/JavaScriptRuntime.swift';
+const JSI_BOX = 'apple/Sources/ExpoModulesJSI/Utilities/UncheckedSendable.swift';
+
+// The exact 57.x constructor block: constructors carrying the annotation that
+// Swift 6.2 rejects. (\u2014 is the em dash in the original comment.)
+const BROKEN_CONSTRUCTORS = `public:
+  /**
+   Constructs a scheduler bound to a host-provided native RuntimeScheduler.
+   \`scheduleTask\` dispatches through \`fn\`, which the host implements against
+   the real react::RuntimeScheduler.
+   */
+  SWIFT_RETURNS_RETAINED RuntimeScheduler(void *scheduler, ScheduleFn fn) noexcept
+      : nativeScheduler(scheduler), scheduleFn(fn) {}
+
+  /**
+   Constructs a no-op scheduler. Scheduled tasks run synchronously on the
+   caller's thread \u2014 intended for standalone runtimes (e.g. tests) that have
+   no React scheduler.
+   */
+  SWIFT_RETURNS_RETAINED RuntimeScheduler() {}`;
+
+// The 58-shaped replacement: unannotated private constructors plus annotated
+// static factories, which every Swift version accepts.
+const FIXED_CONSTRUCTORS = `  RuntimeScheduler(void *scheduler, ScheduleFn fn) noexcept
+      : nativeScheduler(scheduler), scheduleFn(fn) {}
+
+  RuntimeScheduler() noexcept {}
+
+public:
+  // Swift creates instances through the static \`create\` functions below, not
+  // the constructors: \`SWIFT_RETURNS_RETAINED\` on a constructor is a hard
+  // error on Swift 6.2 (Xcode 26), while a static function returning the shared
+  // reference accepts the annotation on every Swift version. This mirrors the
+  // fix Expo ships in expo-modules-jsi 58; the 57 line has no such release.
+
+  /**
+   Creates a scheduler bound to a host-provided native RuntimeScheduler.
+   \`scheduleTask\` dispatches through \`fn\`, which the host implements against
+   the real react::RuntimeScheduler.
+   */
+  static RuntimeScheduler *create(void *scheduler, ScheduleFn fn) noexcept SWIFT_RETURNS_RETAINED {
+    return new RuntimeScheduler(scheduler, fn);
+  }
+
+  /**
+   Creates a no-op scheduler. Scheduled tasks run synchronously on the
+   caller's thread \u2014 intended for standalone runtimes (e.g. tests) that have
+   no React scheduler.
+   */
+  static RuntimeScheduler *create() noexcept SWIFT_RETURNS_RETAINED {
+    return new RuntimeScheduler();
+  }`;
+
+// Verbatim from expo-modules-jsi 58's Utilities/UncheckedSendable.swift: an
+// allocation-free `@unchecked Sendable` box. Swift 6.2 still reports
+// "sending ... risks causing data races" for `nonisolated(unsafe)` locals
+// captured by a `sending` closure, while a captured `Sendable` value passes.
+const UNCHECKED_SENDABLE = `/// Immutable wrapper that makes a non-Sendable value capturable by a \`@Sendable\` closure without compiler enforcement.
+/// Unlike \`NonisolatedUnsafeVar\`, it is a struct, so wrapping a value doesn't allocate.
+///
+/// Use it instead of a \`nonisolated(unsafe) let\` local captured by such a closure: Swift 6.2 still reports
+/// "sending '...' risks causing data races" for those, while a capture of a \`Sendable\` value passes on every version.
+/// The caller is responsible for making sure the value is never accessed concurrently.
+internal struct UncheckedSendable<Value>: @unchecked Sendable {
+  let value: Value
+
+  init(_ value: Value) {
+    self.value = value
+  }
+}
+`;
+
+function countOf(text, snippet) {
+    return text.split(snippet).length - 1;
+}
+
+function replaceOnceOrThrow(text, oldText, newText, what) {
+    if (countOf(text, oldText) !== 1) {
+        throw new Error('[desklink] expo-modules-jsi ' + what + ': expected one match, refusing to patch.');
+    }
+    return text.replace(oldText, newText);
+}
+
+/**
+ * Apply the 58-shaped Xcode 26 fixes to the installed expo-modules-jsi.
+ * Idempotent: a second prebuild (or an upstream-fixed copy) is a no-op.
+ * Scoped to the 57 line; anything else is left untouched. Throws on an
+ * unrecognised 57 layout rather than shipping a guess.
  */
-module.exports = function withDesklinkPointer(config) {
+function patchExpoModulesJsi(projectRoot) {
+    const root = path.join(projectRoot, 'node_modules/expo-modules-jsi');
+    const header = path.join(root, JSI_HEADER);
+    if (!fs.existsSync(header)) {
+        console.log('[desklink] expo-modules-jsi header not installed, skipping Xcode 26 fix');
+        return;
+    }
+    let version = '';
+    try {
+        version = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version ?? '';
+    } catch { /* unknown version: the layout checks below decide */ }
+    if (!version.startsWith('57.')) {
+        if (version === '') {
+            throw new Error('[desklink] expo-modules-jsi has no readable version; refusing to patch blind.');
+        }
+        console.log(`[desklink] expo-modules-jsi ${version} is not a 57 release, skipping Xcode 26 fix`);
+        return;
+    }
+    const before = fs.readFileSync(header, 'utf8');
+    if (!before.includes('static RuntimeScheduler *create(')) {
+        if (countOf(before, BROKEN_CONSTRUCTORS) !== 1) {
+            throw new Error(
+                '[desklink] expo-modules-jsi ' + version + ' RuntimeScheduler.h has an unrecognised layout; ' +
+                'refusing to patch. Update this plugin workaround for the installed version.'
+            );
+        }
+        fs.writeFileSync(header, before.replace(BROKEN_CONSTRUCTORS, FIXED_CONSTRUCTORS));
+    }
+
+    // The header's only constructor callers are the Swift file beside it:
+    // point them at the factories. Member accesses (`.Priority(`, `.ScheduleFn`)
+    // never match `RuntimeScheduler(`.
+    const swift = path.join(root, JSI_SWIFT);
+    if (!fs.existsSync(swift)) {
+        throw new Error('[desklink] expo-modules-jsi ' + version + ' ships no ' + JSI_SWIFT + '.');
+    }
+    let swiftText = fs.readFileSync(swift, 'utf8');
+    if (!swiftText.includes('expo.RuntimeScheduler.create(')) {
+        const migrated = swiftText.replace(/expo\.RuntimeScheduler\(/g, 'expo.RuntimeScheduler.create(');
+        if (migrated === swiftText || /expo\.RuntimeScheduler\(/.test(migrated)) {
+            throw new Error('[desklink] expo-modules-jsi JavaScriptRuntime.swift call sites not fully migrated.');
+        }
+        swiftText = migrated;
+    }
+
+    // Capture the JSI pointers through UncheckedSendable instead of
+    // `nonisolated(unsafe)`, which Swift 6.2 rejects at `sending` closures.
+    if (!swiftText.includes('resultPtr.value')) {
+        if (countOf(swiftText, 'nonisolated(unsafe) let resultPtr = resultPtr') !== 3) {
+            throw new Error('[desklink] expo-modules-jsi JavaScriptRuntime.swift pointer captures have an unrecognised layout.');
+        }
+        swiftText = replaceOnceOrThrow(swiftText,
+            'let propertyName = String(cString: propertyName)\n      nonisolated(unsafe) let resultPtr = resultPtr',
+            'let propertyName = String(cString: propertyName)\n      let resultPtr = UncheckedSendable(resultPtr)',
+            'getter capture');
+        swiftText = swiftText.split(
+            '    nonisolated(unsafe) let thisPtr = thisPtr\n' +
+            '    nonisolated(unsafe) let argumentsPtr = argumentsPtr\n' +
+            '    nonisolated(unsafe) let resultPtr = resultPtr').join(
+            '    let thisPtr = UncheckedSendable(thisPtr)\n' +
+            '    let argumentsPtr = UncheckedSendable(argumentsPtr)\n' +
+            '    let resultPtr = UncheckedSendable(resultPtr)');
+        if (countOf(swiftText, 'let thisPtr = UncheckedSendable(thisPtr)') !== 2) {
+            throw new Error('[desklink] expo-modules-jsi JavaScriptRuntime.swift trampoline captures not fully migrated.');
+        }
+        const writes = countOf(swiftText, 'writeJSIValue(to: resultPtr)');
+        if (writes !== 3) {
+            throw new Error('[desklink] expo-modules-jsi JavaScriptRuntime.swift result writes have an unrecognised layout.');
+        }
+        swiftText = swiftText.replace(/writeJSIValue\(to: resultPtr\)/g, 'writeJSIValue(to: resultPtr.value)');
+        swiftText = replaceOnceOrThrow(swiftText,
+            'UnsafeMutablePointer(mutating: thisPtr)', 'UnsafeMutablePointer(mutating: thisPtr.value)',
+            'owning-this use');
+        const starts = countOf(swiftText, 'start: argumentsPtr, count:');
+        if (starts !== 2) {
+            throw new Error('[desklink] expo-modules-jsi JavaScriptRuntime.swift buffer starts have an unrecognised layout.');
+        }
+        swiftText = swiftText.replace(/start: argumentsPtr, count:/g, 'start: argumentsPtr.value, count:');
+        swiftText = replaceOnceOrThrow(swiftText,
+            'JavaScriptUnownedValue(runtime.pointee, thisPtr)', 'JavaScriptUnownedValue(runtime.pointee, thisPtr.value)',
+            'unowned-this use');
+        swiftText = replaceOnceOrThrow(swiftText,
+            'so the `nonisolated(unsafe)` capture is sound.', 'so capturing them through `UncheckedSendable` is sound.',
+            'trampoline comment');
+        fs.writeFileSync(swift, swiftText);
+    }
+
+    const box = path.join(root, JSI_BOX);
+    if (!fs.existsSync(box)) {
+        fs.writeFileSync(box, UNCHECKED_SENDABLE);
+    }
+    console.log('[desklink] patched expo-modules-jsi ' + version + ' for Xcode 26');
+}
+
+function withDesklinkPointer(config) {
     return {
         ...config,
         ios: { ...config.ios, infoPlist: { ...config.ios?.infoPlist, UIApplicationSupportsIndirectInputEvents: true } },
     };
+}
+
+function withExpoJsiSwiftFix(config) {
+    let withDangerousMod;
+    try {
+        withDangerousMod = require('expo/config-plugins').withDangerousMod;
+    } catch {
+        throw new Error('[desklink] expo/config-plugins is required to apply the Xcode 26 patch.');
+    }
+    return withDangerousMod(config, ['ios', async (config) => {
+        patchExpoModulesJsi(config.modRequest.projectRoot);
+        return config;
+    }]);
+}
+
+module.exports = function withDesklink(config) {
+    return withExpoJsiSwiftFix(withDesklinkPointer(config));
 };
+module.exports.patchExpoModulesJsi = patchExpoModulesJsi;

package/package.json

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

package/src/DesktopView.ios.spec.tsx

@@ -508,6 +508,7 @@ describe('iOS proof picture bounds', () => {
     it('measures contiguous paper without including the disconnected home indicator', () => {
         for (const density of [1, 3]) {
             const png = { width: 390 * density, height: 844 * density, data: new Uint8Array(390 * 844 * density * density * 4) };
+            const right = (390 * density - 1) / density;
             const paper = (left: number, top: number, right: number, bottom: number) => {
                 for (let y = top * density; y < bottom * density; y++) for (let x = left * density; x < right * density; x++) {
                     const i = (y * png.width + x) * 4;
@@ -516,14 +517,14 @@ describe('iOS proof picture bounds', () => {
             };
             paper(0, 47, 390, 266);
             paper(125, 825, 265, 830);
-            expect(pictureBox(png, 390)).toEqual({ top: 47, left: 0, bottom: 266 });
+            expect(pictureBox(png, 390)).toEqual({ top: 47, left: 0, bottom: 266, right });
             png.data.fill(0);
             paper(0, 203, 390, 642);
             paper(125, 825, 265, 830);
-            expect(pictureBox(png, 390)).toEqual({ top: 203, left: 0, bottom: 642 });
+            expect(pictureBox(png, 390)).toEqual({ top: 203, left: 0, bottom: 642, right });
             png.data.fill(0);
             paper(47, 0, 390, 844);
-            expect(pictureBox(png, 390)).toEqual({ top: 0, left: 47, bottom: 844 });
+            expect(pictureBox(png, 390)).toEqual({ top: 0, left: 47, bottom: 844, right });
         }
     });
 });

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', onPictureFrame }: DesktopViewProps) {
+export function DesktopView({ sessionId, style, placeholder, accessibilityLabel, keyboardClearance = 0, insets, gestures = 'desktop', cover = false, 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,10 +142,13 @@ 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
+    // Portrait fits the width unless the app opted into cover, when it covers
+    // like landscape does (as `DesktopView.kt` does); either way the fill never
+    // goes below the fit or above the zoom cap.
+    const defaultScale = bounds.width <= bounds.height && !cover
         ? safeWidth / size.width
         : Math.max(bounds.width / size.width, (bounds.height - top) / size.height);
     const fill = size.width && size.height ? Math.max(fit, Math.min(MAX_SCALE, defaultScale)) : 1;
@@ -169,6 +179,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 +214,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 +452,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,11 @@ export interface DesktopViewProps {
      * (one finger scrolls), or a device screen (one finger presses and drags).
      */
     gestures?: GestureProfile;
+    /**
+     * Cover the view in every orientation, cropping the overflowing axis,
+     * instead of fitting the portrait width. Off by default.
+     */
+    cover?: boolean;
     /**
      * 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
@@ -53,6 +58,7 @@ interface NativeSurfaceProps {
     /** `insets` as top, left, bottom, right. */
     insets?: number[];
     gestures?: GestureProfile;
+    cover?: boolean;
 }
 
 // The Expo view is resolved at module load; on a platform without it the
@@ -69,7 +75,7 @@ const NativeSurface: React.ComponentType<NativeSurfaceProps> | null = desktopAva
  * belong to the application, which mounts this wherever it wants the desktop
  * to appear.
  */
-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', cover = false }: DesktopViewProps) {
     if (NativeSurface == null || sessionId == null) {
         return (
             <View style={[styles.surface, style]}>
@@ -78,7 +84,7 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
         );
     }
     return <NativeSurface style={[styles.surface, style]} sessionId={sessionId} accessible={accessibilityLabel !== undefined} accessibilityLabel={accessibilityLabel} keyboardClearance={keyboardClearance}
-        insets={[insets?.top ?? 0, insets?.left ?? 0, insets?.bottom ?? 0, insets?.right ?? 0]} gestures={gestures} />;
+        insets={[insets?.top ?? 0, insets?.left ?? 0, insets?.bottom ?? 0, insets?.right ?? 0]} gestures={gestures} cover={cover} />;
 }
 
 const styles = StyleSheet.create({

package/src/native.web.ts

@@ -127,6 +127,8 @@ interface WebSession {
     chordsDown: Set<string>;
     /** Re-measure what the keyboard covers; null until a surface is attached. */
     followKeyboard: (() => void) | null;
+    /** Whether the first frame was already reported; renegotiation must not re-mark a stale picture. */
+    presented: boolean;
     /** Candidates that arrived before the offer; applied once it is set. */
     remoteDescriptionSet: boolean;
     pendingCandidates: RTCIceCandidateInit[];
@@ -960,6 +962,7 @@ export const nativeDesklink: NativeDesklinkModule = {
             compositionSent: '',
             composing: false,
             chordsDown: new Set<string>(),
+            presented: false,
             remoteDescriptionSet: false,
             pendingCandidates: [],
             detach: null,
@@ -982,6 +985,12 @@ export const nativeDesklink: NativeDesklinkModule = {
             // track and produce nothing.
             const presented = (): void => {
                 if (sessions.get(id) !== session) return;
+                // Readiness is the first frame. Renegotiation re-fires ontrack
+                // and the compositor repaints the frame it already holds, and a
+                // repaint is not a new frame: a second mark would read a stale
+                // picture as live and reset the recovery budget mid-outage.
+                if (session.presented) return;
+                session.presented = true;
                 video.style.opacity = '1';
                 emit(id, 'presented', {});
             };

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 {
@@ -96,6 +103,8 @@ export interface CursorSample {
  * the new session corrupts or kills a healthy recovery.
  */
 export type SessionEvent =
+    /** Optional carrier notification, distinct from the native peer's `closed`. */
+    | { kind: 'carrier-closed'; sessionId?: never }
     | { kind: 'description'; description: RtcDescription; sessionId?: string }
     | { kind: 'candidate'; candidate: RtcCandidate; sessionId?: string }
     | ({ kind: 'cursor' } & CursorSample)
@@ -113,10 +122,13 @@ export type SessionEvent =
  * The package calls these and nothing else, so an application can carry them
  * over its existing encrypted request path, a socket, or an in-process bridge.
  * `subscribe` delivers engine notifications until the returned function runs.
+ * The application's authorize() resolves only once this carrier is open.
  */
 export interface Signaling {
     /**
-     * Send one request. A rejection may carry a stable `code` — the engine's or
+     * Send one request. Reject pending and future requests with `code: 'transport'`
+     * once the carrier is gone; never queue requests on a dead carrier.
+     * A rejection may carry a stable `code` — the engine's or
      * the host's own token — which the package reads to classify a refusal, so a
      * refusal is not retried as though it were a network failure.
      */

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;
@@ -651,7 +804,8 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         try {
             authorization = await optionsRef.current.authorize();
         } catch (error) {
-            refuse(error instanceof Error ? error.message : 'the desktop was not authorized', 'permission');
+            const code = (error as { code?: unknown } | null)?.code === 'transport' ? 'transport' : 'permission';
+            refuse(error instanceof Error ? error.message : 'the desktop was not authorized', code);
             return;
         }
         if (token !== generationToken.current) return;
@@ -751,6 +905,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 +923,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 +967,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
@@ -865,11 +1024,18 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                         // Readiness is not "a track arrived": it is a frame on screen.
                         return;
                     case 'presented':
+                        // One mark per session: a producer that re-marks (a repaint
+                        // after renegotiation) must not read a stale picture as live.
+                        if (presentedRef.current) return;
                         attempts.current = 0;
                         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 +1121,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 +1197,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;