@desklink/react-native 0.1.1 → 0.2.0

package/README.md

@@ -70,7 +70,8 @@ import { desktopAvailable } from '@desklink/react-native/availability';
 - **A pointer a phone can see.** Once a touch has sent the desktop's pointer
   somewhere, the view draws it there at a readable size, over a picture whose
   own cursor is a few pixels tall or not captured at all. Android hides the
-  extra mark when a mouse is attached.
+  extra mark when a mouse is attached, and the `device` profile draws no mark
+  on any platform — the screen being 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
@@ -88,7 +89,14 @@ import { desktopAvailable } from '@desklink/react-native/availability';
   under the finger while the picture catches up; two fingers scroll the desktop
   under them, or pinch; a quick two-finger tap is a right click too. Scrolling
   is fractional wheel steps, smooth where the desktop supports high-resolution
-  wheels. Android coalesces pending pointer moves under congestion.
+  wheels. Android coalesces pending pointer moves under congestion. The
+  `gestures` prop reshapes one finger for what the picture shows, and can be
+  changed mid-session: `browser` scrolls the page under one finger (a tap
+  still clicks and a hold still right-clicks), `device` presses the screen —
+  the finger lands with the button down, drags with it held and lifts to
+  release, so a tap clicks and a hold holds with no long-press right click,
+  and no drawn pointer — while the default `desktop` is the trackpad above.
+  Two fingers scroll and pinch the same under every profile.
 - **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
@@ -96,6 +104,33 @@ import { desktopAvailable } from '@desklink/react-native/availability';
 - **Readiness is a rendered frame.** Android marks the first draw; iOS uses
   `RTCView`'s native video-dimensions callback, which fires after a decoded
   picture arrives. Neither 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`. `failed` stays terminal.
+  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
+  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.
+- **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. Only a terminal `failed` reopens the session, and those
+  reopens back off across ~60 s too instead of spending one attempt while the
+  network is still down. Renegotiation transients from a restart the session
+  asked for itself are expected, not a new outage: they neither flip the
+  status nor trigger another restart for a short grace window.
 - **Control starts off.** `setInputEnabled(true)` enables pointer, keyboard and
   clipboard input; `setInputEnabled(false)` blocks new input, releases held keys
   and buttons, and resets pending gestures. The app decides when to enable it
@@ -119,9 +154,9 @@ interface Signaling {
 ```
 
 `method` is one of `session.open`, `session.description`, `session.candidate`,
-`session.close`; `SessionEvent` is the engine's offer, candidates, state and
-revocation. Pixels and input do **not** use this channel — they are the
-desktop's own WebRTC session.
+`session.restart_ice`, `session.close`; `SessionEvent` is the engine's offer,
+candidates, state and revocation. Pixels and input do **not** use this
+channel — they are the desktop's own WebRTC session.
 
 ## Licence
 

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

@@ -126,6 +126,10 @@ class DesklinkModule : Module() {
         view.setKeyboardClearance(clearance ?: 0f)
       }
 
+      Prop("gestures") { view: DesktopView, gestures: String? ->
+        view.setGestures(gestures ?: "desktop")
+      }
+
       OnViewDestroys { view: DesktopView -> view.release() }
 
       OnViewDidUpdateProps { view: DesktopView ->

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

@@ -66,7 +66,9 @@ private const val MIN_WHEEL_STEP = 0.05f
  *  - press and hold: a right click on release, or drag after it to hold the left
  *    button (select text, move a window);
  *  - one finger: move around a zoomed-in desktop; on the whole desktop,
- *    move its pointer, which follows the finger without pressing a button;
+ *    move its pointer, which follows the finger without pressing a button —
+ *    unless `gestures` is `browser`, where it scrolls the page, or `device`,
+ *    where it lands with the button down and drags with it held;
  *  - two fingers: scroll the desktop under them, or pinch to zoom (and move) the
  *    picture; a quick two-finger tap is a right click.
  */
@@ -81,6 +83,23 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
   private var surfaceWidth = 0
   private var surfaceHeight = 0
 
+  /** Which touch meaning this surface uses; a browser page and a device screen answer one finger differently. */
+  var gestures = "desktop"
+    private set
+
+  fun setGestures(value: String) {
+    if (value == gestures) return
+    // A held drag belongs to the old meaning: let go rather than release the
+    // button somewhere the finger never meant.
+    if (gesture == Gesture.DRAG) session?.sendCancel()
+    cancelGesture()
+    gestures = value
+    if (value == "device" && pointerAt != null) {
+      pointerAt = null
+      placePointer()
+    }
+  }
+
   // The picture's placement: surface pixels per desktop pixel, and where the
   // desktop's top-left corner sits in this view. `fitted` keeps a picture that
   // was showing the whole desktop showing it when the view changes size.
@@ -449,7 +468,8 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
   /** Send the desktop's pointer somewhere, and show it there. */
   private fun pointerTo(active: DesktopSession, phase: String, at: Pair<Int, Int>, withButton: Boolean = false) {
     active.sendPointer(phase, at.first, at.second, withButton)
-    if (!mouseInput) showPointer(at)
+    // A device screen shows the touch itself; a mark would be a second finger that lies.
+    if (!mouseInput && gestures != "device") showPointer(at)
   }
 
   private fun showPointer(at: Pair<Int, Int>) {
@@ -519,6 +539,25 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
     }
     when (event.actionMasked) {
       MotionEvent.ACTION_DOWN -> {
+        // A device screen is pressed, not pointed at: the finger lands with the
+        // button down, drags with it held, and lifts to release. A tap is the
+        // same down and up with no move, so it clicks for free, and a hold
+        // holds for free — there is no long press to arm.
+        if (gestures == "device") {
+          downX = event.x
+          downY = event.y
+          lastX = event.x
+          lastY = event.y
+          val at = point(event.x, event.y)
+          if (at == null) {
+            gesture = Gesture.LETTERBOX
+          } else {
+            gesture = Gesture.DRAG
+            lastTapPoint = null
+            pointerTo(active, "down", at)
+          }
+          return true
+        }
         downOnPicture = point(event.x, event.y) != null
         gesture = if (fitted && !downOnPicture) Gesture.LETTERBOX else Gesture.PENDING
         downX = event.x
@@ -573,6 +612,15 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
         Gesture.PENDING -> if (hypot(event.x - downX, event.y - downY) > touchSlop) {
           removeCallbacks(longPress)
           lastTapPoint = null
+          // A page scrolls under one finger; the desktop's pointer rides along
+          // so the scroll lands where the finger is.
+          if (gestures == "browser") {
+            gesture = Gesture.SCROLL
+            lastX = event.x
+            lastY = event.y
+            point(event.x, event.y)?.let { pointerTo(active, "move", it) }
+            return true
+          }
           // The whole desktop has nowhere to move to, so the finger moves the
           // desktop's pointer instead, without a button.
           gesture = if (!fitted) Gesture.PAN else if (downOnPicture) Gesture.HOVER else Gesture.LETTERBOX
@@ -599,6 +647,15 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
         Gesture.DRAG -> dragTo(active, event.x, event.y)
 
         Gesture.TWO, Gesture.PINCH, Gesture.SCROLL -> if (event.pointerCount >= 2) twoFingers(active, event)
+        else if (gesture == Gesture.SCROLL && gestures == "browser") {
+          // One finger dragging a page: content follows it, in pixel deltas
+          // turned to detents like the two-finger scroll.
+          wheelX -= (event.x - lastX) / scale / PIXELS_PER_DETENT
+          wheelY -= (event.y - lastY) / scale / PIXELS_PER_DETENT
+          lastX = event.x
+          lastY = event.y
+          flushWheel(active, force = false)
+        }
 
         else -> {}
       }
@@ -618,6 +675,7 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
         removeCallbacks(longPress)
         when (gesture) {
           Gesture.PENDING -> tap(active, event.x, event.y)
+          Gesture.SCROLL -> flushWheel(active, force = true)
           Gesture.HOVER -> hoverTo(active, event.x, event.y)
           Gesture.ARMED -> point(downX, downY)?.let { rightClick(active, it) }
           Gesture.DRAG -> endDrag(active, event.x, event.y)
@@ -669,7 +727,7 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
 
   private fun rightClick(active: DesktopSession, at: Pair<Int, Int>) {
     active.sendRightClick(at.first, at.second)
-    if (!mouseInput) showPointer(at)
+    if (!mouseInput && gestures != "device") showPointer(at)
   }
 
   private fun twoFingers(active: DesktopSession, event: MotionEvent) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@desklink/react-native",
-    "version": "0.1.1",
+    "version": "0.2.0",
     "license": "Apache-2.0",
     "description": "Render and drive a desktop session from a React Native app",
     "main": "index.ts",
@@ -29,5 +29,8 @@
         "react": ">=19",
         "react-native": ">=0.83",
         "react-native-webrtc": ">=124"
+    },
+    "scripts": {
+        "test:reconnect": "node test/reconnect-flow.mjs"
     }
 }

package/src/DesktopView.ios.tsx

@@ -8,7 +8,7 @@ import { desktopInputEnabled, emitDesktopKeyboard, getDesktopSize, getDesktopStr
 type Point = { x: number; y: number };
 type Gesture = { start: Point; last: Point; time: number; mode: 'pending' | 'hover' | 'pan' | 'armed' | 'drag' | 'two' | 'scroll' | 'pinch' | 'spent'; span: number; focus: Point };
 
-export function DesktopView({ sessionId, style, placeholder, accessibilityLabel, keyboardClearance = 0 }: DesktopViewProps) {
+export function DesktopView({ sessionId, style, placeholder, accessibilityLabel, keyboardClearance = 0, gestures = 'desktop' }: 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 });
@@ -36,6 +36,15 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
         const hide = Keyboard.addListener('keyboardWillHide', () => setKeyboardHeight(0));
         return () => { show.remove(); hide.remove(); };
     }, []);
+    React.useEffect(() => {
+        if (gestures !== 'device') return;
+        setCursor(null);
+        const held = gesture.current;
+        if (held && (held.mode === 'pending' || held.mode === 'armed')) {
+            stopTimer();
+            held.mode = 'spent';
+        }
+    }, [gestures]);
     React.useEffect(() => {
         if (!sessionId) return;
         return registerDesktopView(sessionId, {
@@ -65,7 +74,8 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
     const send = (control: Record<string, unknown>) => { if (sessionId) nativeDesklink.sendControl(sessionId, JSON.stringify(control)); };
     const pointer = (phase: string, at: Point, button?: number) => {
         send({ kind: 'pointer', phase, x: at.x, y: at.y, ...(button ? { button } : {}) });
-        setCursor(at);
+        // A device screen shows the touch itself; a cursor would be a second finger that lies.
+        if (gestures !== 'device') setCursor(at);
     };
     const click = (at: Point, button = 1) => { pointer('down', at, button); pointer('up', at, button); };
     const stopTimer = () => { if (longPress.current) clearTimeout(longPress.current); longPress.current = null; };
@@ -79,6 +89,15 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
         const touches = event.nativeEvent.touches;
         if (touches.length !== 1) return;
         const at = { x: touches[0].locationX, y: touches[0].locationY };
+        // A device screen is pressed, not pointed at: the finger lands with the
+        // button down. A tap is the same press lifted without moving, and a
+        // hold holds — there is no long press to arm.
+        if (gestures === 'device') {
+            const from = point(at.x, at.y);
+            gesture.current = { start: at, last: at, time: Date.now(), mode: from ? 'drag' : 'spent', span: 0, focus: at };
+            if (from) pointer('down', from, 1);
+            return;
+        }
         gesture.current = { start: at, last: at, time: Date.now(), mode: 'pending', span: 0, focus: at };
         stopTimer();
         longPress.current = setTimeout(() => {
@@ -108,14 +127,26 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
             } else if (g.mode === 'scroll') {
                 send({ kind: 'wheel', dx: -(center.x - g.focus.x) / scale / 120, dy: -(center.y - g.focus.y) / scale / 120 });
             }
-            g.span = distance; g.focus = center;
+            g.span = distance; g.focus = center; g.last = center;
             return;
         }
-        if (touches.length !== 1 || g.mode === 'spent' || g.mode === 'two' || g.mode === 'pinch' || g.mode === 'scroll') return;
+        if (touches.length !== 1 || g.mode === 'spent' || g.mode === 'two' || g.mode === 'pinch' || (g.mode === 'scroll' && gestures !== 'browser')) return;
         const at = { x: touches[0].locationX, y: touches[0].locationY };
         if (g.mode === 'pending' && Math.hypot(at.x - g.start.x, at.y - g.start.y) > 8) {
             stopTimer();
-            g.mode = zoom > 1 ? 'pan' : 'hover';
+            // A page scrolls under one finger; the desktop's pointer rides along
+            // so the scroll lands where the finger is.
+            if (gestures === 'browser') {
+                g.mode = 'scroll';
+                const under = point(at.x, at.y);
+                if (under) pointer('move', under);
+            } else g.mode = zoom > 1 ? 'pan' : 'hover';
+        }
+        if (g.mode === 'scroll') {
+            // Content follows the finger: moving it up scrolls the page down.
+            send({ kind: 'wheel', dx: -(at.x - g.last.x) / scale / 120, dy: -(at.y - g.last.y) / scale / 120 });
+            g.last = at; g.focus = at;
+            return;
         }
         if (g.mode === 'pan') {
             const dx = at.x - g.last.x;

package/src/DesktopView.tsx

@@ -3,6 +3,7 @@ import * as React from 'react';
 import { StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
 
 import { desktopAvailable } from './native';
+import type { GestureProfile } from './protocol';
 
 export interface DesktopViewProps {
     /** The session handle from `useDesktopSession`. */
@@ -18,6 +19,11 @@ export interface DesktopViewProps {
      * following the keyboard as it moves.
      */
     keyboardClearance?: number;
+    /**
+     * Which touch meaning the surface uses: a desktop pointer, a browser page
+     * (one finger scrolls), or a device screen (one finger presses and drags).
+     */
+    gestures?: GestureProfile;
 }
 
 interface NativeSurfaceProps {
@@ -26,6 +32,7 @@ interface NativeSurfaceProps {
     accessible?: boolean;
     accessibilityLabel?: string;
     keyboardClearance?: number;
+    gestures?: GestureProfile;
 }
 
 // The Expo view is resolved at module load; on a platform without it the
@@ -42,7 +49,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 }: DesktopViewProps) {
+export function DesktopView({ sessionId, style, placeholder, accessibilityLabel, keyboardClearance = 0, gestures = 'desktop' }: DesktopViewProps) {
     if (NativeSurface == null || sessionId == null) {
         return (
             <View style={[styles.surface, style]}>
@@ -50,7 +57,7 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
             </View>
         );
     }
-    return <NativeSurface style={[styles.surface, style]} sessionId={sessionId} accessible={accessibilityLabel !== undefined} accessibilityLabel={accessibilityLabel} keyboardClearance={keyboardClearance} />;
+    return <NativeSurface style={[styles.surface, style]} sessionId={sessionId} accessible={accessibilityLabel !== undefined} accessibilityLabel={accessibilityLabel} keyboardClearance={keyboardClearance} gestures={gestures} />;
 }
 
 const styles = StyleSheet.create({

package/src/DesktopView.web.tsx

@@ -1,6 +1,8 @@
 import * as React from 'react';
 import { StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
 
+import type { GestureProfile } from './protocol';
+
 export interface DesktopViewProps {
     /** The session handle from `useDesktopSession`. */
     sessionId: string | null;
@@ -14,6 +16,11 @@ export interface DesktopViewProps {
      * controls, in points. While the keyboard is up the picture sits above both.
      */
     keyboardClearance?: number;
+    /**
+     * Which touch meaning the surface uses: a desktop pointer, a browser page
+     * (one finger scrolls), or a device screen (one finger presses and drags).
+     */
+    gestures?: GestureProfile;
 }
 
 /**
@@ -25,19 +32,24 @@ export interface DesktopViewProps {
  * actually mounted rather than at module load, so an application that never
  * opens a desktop does not carry one in its first paint.
  */
-export function DesktopView({ sessionId, style, placeholder, accessibilityLabel, keyboardClearance = 0 }: DesktopViewProps) {
+export function DesktopView({ sessionId, style, placeholder, accessibilityLabel, keyboardClearance = 0, gestures = 'desktop' }: DesktopViewProps) {
     const mounted = React.useCallback(
         (node: unknown) => {
             const element = (node as HTMLElement | null) ?? null;
             if (sessionId === null) return;
             void import('./native').then((platform) => {
                 if (element === null || !platform.desktopAvailable) return;
-                platform.attachSurface(sessionId, element);
+                platform.attachSurface(sessionId, element, gestures);
             });
         },
         [sessionId],
     );
 
+    React.useEffect(() => {
+        if (sessionId === null) return;
+        void import('./native').then((platform) => platform.setGestures(sessionId, gestures));
+    }, [sessionId, gestures]);
+
     React.useEffect(() => {
         if (sessionId === null) return;
         void import('./native').then((platform) => platform.setKeyboardClearance(sessionId, keyboardClearance));

package/src/native.web.ts

@@ -1,4 +1,5 @@
 import type { NativeDesklinkModule, NativeEventName, NativeSessionEvent } from './native';
+import type { GestureProfile } from './protocol';
 import { observeWebKeyboardMotion } from './webKeyboardMotion';
 
 /**
@@ -114,6 +115,8 @@ interface WebSession {
     longPress: ReturnType<typeof setTimeout> | null;
     /** While a sticky modifier waits for its key, typing is the session's to chord. */
     captured: boolean;
+    /** Which touch meaning this surface uses; a browser page and a device screen answer one finger differently. */
+    gestures: GestureProfile;
     inputEnabled: boolean;
     /** The word the keyboard is composing, and how much of it has already gone. */
     composition: string;
@@ -378,8 +381,9 @@ function cancelLongPress(session: WebSession): void {
 function pointer(session: WebSession, phase: 'move' | 'down' | 'up' | 'cancel', at: { x: number; y: number }, button?: number): void {
     control(session, { kind: 'pointer', phase, x: at.x, y: at.y, ...(button === undefined ? {} : { button }), seq: seq(session) });
     // A mouse brings its own cursor; a finger leaves nothing on the glass to
-    // show where the desktop's pointer went, so the mark does.
-    if (session.mouse || phase === 'cancel') return;
+    // show where the desktop's pointer went, so the mark does. A device screen
+    // shows the touch itself, so a mark would be a second finger that lies.
+    if (session.mouse || phase === 'cancel' || session.gestures === 'device') return;
     session.pointerAt = { x: at.x, y: at.y };
     placePointer(session);
 }
@@ -391,13 +395,15 @@ function click(session: WebSession, at: { x: number; y: number }, button: number
 
 /**
  * Touch gestures, the ones mature remote-desktop viewers settled on — the same
- * as the native view's:
+ * as the native view's. The profile reshapes one finger only:
  *
  *  - tap: click where the finger lands; two taps: a double click on one spot;
  *  - press and hold: a right click on release, or drag after it to hold the
  *    left button (select text, move a window);
  *  - one finger: move around a zoomed-in desktop; on the whole desktop,
- *    move its pointer, which follows the finger without pressing a button;
+ *    move its pointer, which follows the finger without pressing a button —
+ *    unless the profile is `browser`, where it scrolls the page, or `device`,
+ *    where it lands with the button down and drags with it held;
  *  - two fingers: scroll the desktop under them, or pinch to zoom (and move)
  *    the picture; a quick two-finger tap is a right click.
  *
@@ -534,6 +540,27 @@ function attachGestures(session: WebSession): () => void {
         }
         session.touches.set(event.pointerId, { x, y });
         if (session.touches.size === 1) {
+            // A device screen is pressed, not pointed at: the finger lands with
+            // the button down, drags with it held, and lifts to release. A tap
+            // is the same down and up with no move, so it clicks for free, and
+            // a hold holds for free — there is no long press to arm.
+            if (session.gestures === 'device') {
+                session.downX = x;
+                session.downY = y;
+                session.lastX = x;
+                session.lastY = y;
+                const at = desktopPoint(session, x, y);
+                if (at === null) {
+                    session.gesture = 'letterbox';
+                    return;
+                }
+                session.gesture = 'drag';
+                session.lastTap = null;
+                pointer(session, 'down', at, 1);
+                session.dragX = at.x;
+                session.dragY = at.y;
+                return;
+            }
             session.downOnPicture = desktopPoint(session, x, y) !== null;
             session.gesture = session.view.fitted && !session.downOnPicture ? 'letterbox' : 'pending';
             session.downX = x;
@@ -586,6 +613,16 @@ function attachGestures(session: WebSession): () => void {
                 if (Math.hypot(x - session.downX, y - session.downY) > TOUCH_SLOP) {
                     cancelLongPress(session);
                     session.lastTap = null;
+                    // A page scrolls under one finger; the desktop's pointer
+                    // rides along so the scroll lands where the finger is.
+                    if (session.gestures === 'browser') {
+                        session.gesture = 'scroll';
+                        session.lastX = x;
+                        session.lastY = y;
+                        const at = desktopPoint(session, x, y);
+                        if (at !== null) pointer(session, 'move', at);
+                        return;
+                    }
                     // The whole desktop has nowhere to move to, so the finger
                     // moves the desktop's pointer instead, without a button.
                     session.gesture = session.view.fitted
@@ -620,6 +657,15 @@ function attachGestures(session: WebSession): () => void {
             case 'pinch':
             case 'scroll':
                 if (session.touches.size >= 2) twoFingers();
+                else if (session.gesture === 'scroll' && session.gestures === 'browser') {
+                    // One finger dragging a page: content follows it, in pixel
+                    // deltas turned to detents like the two-finger scroll.
+                    session.wheelX -= (x - session.lastX) / session.view.scale / PIXELS_PER_DETENT;
+                    session.wheelY -= (y - session.lastY) / session.view.scale / PIXELS_PER_DETENT;
+                    session.lastX = x;
+                    session.lastY = y;
+                    flushWheel(false);
+                }
                 return;
             default:
                 return;
@@ -662,6 +708,7 @@ function attachGestures(session: WebSession): () => void {
             return;
         }
         if (gesture === 'pending') tap(x, y);
+        else if (gesture === 'scroll') flushWheel(true);
         else if (gesture === 'hover') hoverTo(x, y);
         else if (gesture === 'armed') {
             const at = desktopPoint(session, session.downX, session.downY);
@@ -902,6 +949,7 @@ export const nativeDesklink: NativeDesklinkModule = {
             lastTap: null,
             longPress: null,
             captured: false,
+            gestures: 'desktop',
             inputEnabled: false,
             composition: '',
             compositionSent: '',
@@ -959,6 +1007,13 @@ export const nativeDesklink: NativeDesklinkModule = {
                 emit(id, 'failure', { code: 'transport', message: 'the connection to the desktop was lost' });
             }
         };
+        peer.oniceconnectionstatechange = () => {
+            if (sessions.get(id) !== session) return;
+            // Surfaced as it happens — upstream of any failure timeout — so a
+            // short drop reads as reconnecting within about a second, not as
+            // a frozen picture that still says live.
+            emit(id, 'ice', { state: peer.iceConnectionState.toUpperCase() });
+        };
         return id;
     },
 
@@ -1130,9 +1185,35 @@ export const nativeDesklink: NativeDesklinkModule = {
  * surface, and removing the old one is what keeps a re-render from leaving two
  * live videos behind.
  */
-export function attachSurface(id: string, container: HTMLElement | null): void {
+/** Which touch meaning a surface uses; changing it mid-session is safe. */
+export function setGestures(id: string, gestures: GestureProfile): void {
+    const session = sessions.get(id);
+    if (session === undefined) return;
+    if (session.gestures === gestures) return;
+    // A held drag belongs to the old meaning: let go rather than release the
+    // button somewhere the finger never meant.
+    if (session.gesture === 'drag' || session.gesture === 'mouse') endGestureDrag(session);
+    cancelLongPress(session);
+    session.gesture = 'none';
+    session.touches.clear();
+    session.gestures = gestures;
+    // A device screen shows the touch itself: a mark left over from another
+    // profile would be a finger that is not there.
+    if (gestures === 'device' && session.pointerAt !== null) {
+        session.pointerAt = null;
+        placePointer(session);
+    }
+}
+
+/** Release a held button at the last desktop point it was sent to. */
+function endGestureDrag(session: WebSession): void {
+    pointer(session, 'up', { x: session.dragX, y: session.dragY }, 1);
+}
+
+export function attachSurface(id: string, container: HTMLElement | null, gestures: GestureProfile = 'desktop'): void {
     const session = sessions.get(id);
     if (session === undefined) return;
+    session.gestures = gestures;
     session.detach?.();
     session.detach = null;
     if (session.surface !== null) session.surface.remove();

package/src/protocol.ts

@@ -18,6 +18,14 @@ export const PROTOCOL_VERSION = 3;
 
 export type Permission = 'view' | 'control' | 'clipboard';
 
+/**
+ * Which touch meaning a surface uses. `desktop` is the trackpad-shaped
+ * default; `browser` scrolls a page with one finger; `device` presses the
+ * screen with one finger, like the finger itself was there. The wire messages
+ * are the same under all three — only which gesture sends which changes.
+ */
+export type GestureProfile = 'desktop' | 'browser' | 'device';
+
 export interface IceServerConfig {
     urls: string[];
     username?: string;
@@ -61,13 +69,21 @@ export interface RtcCandidate {
     sdpMLineIndex?: number | null;
 }
 
-/** Engine → client lifecycle events, already unwrapped from the local protocol. */
+/**
+ * Engine → client lifecycle events, already unwrapped from the local protocol.
+ *
+ * `sessionId` names the engine session the event belongs to, when the
+ * carrier preserves it. The hook ignores an event whose id does not match
+ * the session it holds: after an outage, a previous session's queued offer
+ * or revocation can arrive beside the new session's, and applying those to
+ * the new session corrupts or kills a healthy recovery.
+ */
 export type SessionEvent =
-    | { kind: 'description'; description: RtcDescription }
-    | { kind: 'candidate'; candidate: RtcCandidate }
-    | { kind: 'state'; capture: string; transport: string; firstFrame: boolean }
-    | { kind: 'restoreToken'; token: string }
-    | { kind: 'revoked'; reason: string };
+    | { kind: 'description'; description: RtcDescription; sessionId?: string }
+    | { kind: 'candidate'; candidate: RtcCandidate; sessionId?: string }
+    | { kind: 'state'; capture: string; transport: string; firstFrame: boolean; sessionId?: string }
+    | { kind: 'restoreToken'; token: string; sessionId?: string }
+    | { kind: 'revoked'; reason: string; sessionId?: string };
 
 /**
  * The application's own authenticated channel to the host engine.
@@ -139,7 +155,14 @@ export type ControlReply =
     | { kind: 'ack'; seq: number }
     | { kind: 'rejected'; seq: number; code: string; message: string }
     | { kind: 'clipboard'; request: string; text: string; truncated?: boolean; error?: string }
-    | { kind: 'revoked'; reason: string };
+    | { kind: 'revoked'; reason: string }
+    /**
+     * The engine's heartbeat, twice a second while the control channel is
+     * open. A client that has seen one and then sees none for a while reads
+     * the path as stalled, long before ICE consent timers notice. Clients that
+     * predate it simply ignore it.
+     */
+    | { kind: 'ping' };
 
 export function parseControlReply(raw: string): ControlReply | null {
     try {

package/src/useDesktopSession.ts

@@ -27,8 +27,73 @@ import {
 /** How long a clipboard round trip may take before it is reported as lost. */
 const CLIPBOARD_TIMEOUT_MS = 4000;
 
-/** One reconnect attempt per session; beyond that the caller must ask again. */
-const MAX_RECONNECT_ATTEMPTS = 1;
+/**
+ * A drop heals on its own more often than not, so the first ICE restart waits
+ * out brief blips; the retries then back off. The whole schedule spans about a
+ * minute, so a 30–60 s outage still recovers when the network comes back.
+ */
+const RESTART_AFTER_MS = 2000;
+export const RESTART_BACKOFF_MS = [2000, 4000, 8000, 16000, 30000];
+/**
+ * A heartbeat missed this long means the path is stalled, even when ICE has
+ * not said so yet. Twice the engine's ping interval, with room for jitter.
+ */
+const STALL_AFTER_MS = 1200;
+/**
+ * After the session itself asks for a restart, renegotiation transients are
+ * expected: ICE may flap and heartbeats may pause while the new generation
+ * comes up. These are not a new outage, so they neither flip the status nor
+ * trigger another restart while the window lasts.
+ */
+const RESTART_GRACE_MS = 2500;
+/** How long a restart offer may go unanswered before the next attempt. */
+const RESTART_REPLY_MS = 5000;
+/**
+ * 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
+ * 8 s costs nothing next to a live desktop.
+ */
+export const REOPEN_BACKOFF_MS = [1000, 2000, 4000, 8000, 8000, 8000, 8000, 8000];
+
+/** The delay before attempt `n` (0-based), or null when the schedule is spent. */
+export function backoffDelay(schedule: readonly number[], attempt: number): number | null {
+    return attempt < schedule.length ? schedule[attempt]! : null;
+}
+
+export type ConnectionStateName =
+    | 'new'
+    | 'checking'
+    | 'connected'
+    | 'completed'
+    | 'disconnected'
+    | 'failed'
+    | 'closed';
+
+/**
+ * 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.
+ */
+export function connectionStatusFor(
+    state: string,
+    status: SessionSnapshot['status'],
+    presented: boolean,
+): SessionSnapshot['status'] | null {
+    switch (state) {
+        case 'disconnected':
+            return status === 'live' || status === 'connecting' ? 'reconnecting' : null;
+        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';
+        default:
+            return null;
+    }
+}
 
 /**
  * Without a relay there is no route between two networks: ICE only ever finds
@@ -58,9 +123,14 @@ const OPEN_FAILURE_CODES: Record<string, SessionFailure['code']> = {
     transport: 'transport',
 };
 
-function classifyOpenFailure(error: unknown): SessionFailure['code'] {
+export function classifyOpenFailure(error: unknown): SessionFailure['code'] {
     const code = (error as { code?: unknown } | null)?.code;
-    if (typeof code === 'string') return OPEN_FAILURE_CODES[code] ?? 'platform';
+    if (typeof code === 'string') {
+        // An engine that never answers — stopped, wedged, or unreachable — is
+        // a transport problem a retry may fix, not a platform verdict.
+        if (code === 'engine' || code === 'timeout') return 'transport';
+        return OPEN_FAILURE_CODES[code] ?? 'platform';
+    }
     // No token at all: fall back to the message, treating anything that is not a
     // permission refusal as a transport failure a retry may fix.
     const message = error instanceof Error ? error.message : '';
@@ -165,6 +235,13 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     const nativeRef = useRef<string | null>(null);
     const inputEnabled = useRef(false);
     const pendingClipboard = useRef(new Map<string, (reply: { text: string; truncated: boolean; error?: string }) => void>());
+    /**
+     * The engine's offer and candidates can beat the open result back: the
+     * subscription starts before `session.open`, so anything that arrives
+     * before the native session exists waits here and is replayed into it.
+     */
+    const pendingOffer = useRef<{ sdp: string; sessionId?: string } | null>(null);
+    const pendingCandidates = useRef<Array<{ candidate: string; sdpMid: string | null; sdpMLineIndex: number | null; sessionId?: string }>>([]);
     const attempts = useRef(0);
     /**
      * The pending reconnect attempt. It lives here rather than in the effect
@@ -172,6 +249,31 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
      * its dependencies, so React would run its cleanup and cancel the retry.
      */
     const reconnectTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+    /** The pending ICE-restart attempt; cancelled on recovery or failure. */
+    const restartTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+    /** The pending stall watchdog, armed by heartbeats. */
+    const stallTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+    /** When the last heartbeat arrived, or 0 before the first one. */
+    const lastPingAt = useRef(0);
+    /** Renegotiation transients are not a new outage before this time. */
+    const restartGraceUntil = useRef(0);
+    /** ICE-restart attempts spent on the current drop. */
+    const restartAttempts = useRef(0);
+    /**
+     * Successful restarts since the last heartbeat: when ICE is up but the
+     * path stays quiet, enough of these in a row means the session itself is
+     * wedged and only a reopen heals it.
+     */
+    const restartCycles = useRef(0);
+    /** The last ICE state the peer or the engine reported. */
+    const iceConnected = useRef(false);
+    /** The engine's restore token, for a consent-free reopen. Unset by hand. */
+    const restoreToken = useRef<string | null>(null);
+    /** The latest status and presentation, read by event handlers. */
+    const statusRef = useRef<SessionSnapshot['status']>('idle');
+    const presentedRef = useRef(false);
+    /** The latest snapshot; mirrored eagerly so timers read exact state. */
+    const snapshotRef = useRef<SessionSnapshot>(IDLE);
     const diagnostics = useRef<Record<string, string | number | boolean>>({});
     /** Guards every asynchronous callback against a session that already ended. */
     const generationToken = useRef(0);
@@ -179,11 +281,15 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     optionsRef.current = options;
 
     const update = useCallback((patch: Partial<SessionSnapshot>) => {
-        setSnapshot((current) => {
-            const next = { ...current, ...patch };
-            optionsRef.current.onStateChange?.(next);
-            return next;
-        });
+        // Mirrored eagerly: timers read these between renders, and React may
+        // defer the render itself. (Calling onStateChange here also keeps it
+        // to one call per update, where the updater form could double-fire.)
+        const next = { ...snapshotRef.current, ...patch };
+        snapshotRef.current = next;
+        statusRef.current = next.status;
+        presentedRef.current = next.presented;
+        setSnapshot(next);
+        optionsRef.current.onStateChange?.(next);
     }, []);
 
     const fail = useCallback((failure: SessionFailure) => {
@@ -195,6 +301,177 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         fail({ code, message });
     }, [fail]);
 
+    /** A transport loss is one event no matter how many sides report it: the
+     * peer's `failed` state and its `failure` event would otherwise spend the
+     * reopen budget twice for the same outage. */
+    const transportFailed = useCallback((message: string = UNREACHABLE_DESKTOP) => {
+        if (statusRef.current === 'failed') return;
+        refuse(message, 'transport');
+    }, [refuse]);
+
+    const cancelRestart = useCallback(() => {
+        if (restartTimer.current !== null) clearTimeout(restartTimer.current);
+        restartTimer.current = null;
+    }, []);
+
+    const cancelReconnect = useCallback(() => {
+        if (reconnectTimer.current !== null) clearTimeout(reconnectTimer.current);
+        reconnectTimer.current = null;
+    }, []);
+
+    const cancelStall = useCallback(() => {
+        if (stallTimer.current !== null) clearTimeout(stallTimer.current);
+        stallTimer.current = null;
+    }, []);
+
+    const scheduleRestartRef = useRef<(delay: number) => void>(() => undefined);
+
+    /**
+     * Spend one restart from the backoff schedule, or stop asking when the
+     * schedule is spent: ICE's own failure then moves the session to a full
+     * reopen. Only refs and module constants, so stable callbacks may hold it.
+     */
+    const spendRestartAttempt = useCallback((): void => {
+        if (statusRef.current !== 'reconnecting' || nativeRef.current == null) return;
+        const wait = backoffDelay(RESTART_BACKOFF_MS, restartAttempts.current);
+        if (wait === null) return;
+        restartAttempts.current += 1;
+        scheduleRestartRef.current(wait);
+    }, []);
+
+    /**
+     * Queue the next ICE restart after `delay`, or do nothing when an attempt
+     * is already queued or the session is gone. The status is validated when
+     * the timer fires rather than here: the caller just moved the session to
+     * `reconnecting` and that update has not been processed yet.
+     *
+     * A restart asks the engine to re-offer on the same peer connection; the
+     * offer arrives as the usual description event and is answered as usual.
+     * The session never reopens for it.
+     */
+    const scheduleRestart = useCallback((delay: number) => {
+        if (restartTimer.current !== null) return;
+        if (nativeRef.current == null) return;
+        restartTimer.current = setTimeout(() => {
+            restartTimer.current = null;
+            if (statusRef.current !== 'reconnecting') return;
+            const openedRef = opened.current;
+            const channel = signaling.current;
+            if (openedRef == null || channel == null) {
+                spendRestartAttempt();
+                return;
+            }
+            void (async () => {
+                try {
+                    await channel.request('session.restart_ice', {
+                        session_id: openedRef.sessionId,
+                        generation: openedRef.generation,
+                    });
+                } catch {
+                    spendRestartAttempt();
+                    return;
+                }
+                if (statusRef.current !== 'reconnecting') return;
+                restartGraceUntil.current = Date.now() + RESTART_GRACE_MS;
+                restartCycles.current += 1;
+                // Media is up but the path stays quiet after clean restarts:
+                // 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) {
+                    transportFailed('the desktop stopped responding; reopening the session');
+                    return;
+                }
+                // The engine re-offers through the usual description event,
+                // 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;
+                restartTimer.current = setTimeout(() => {
+                    restartTimer.current = null;
+                    spendRestartAttempt();
+                }, replyMs);
+            })();
+        }, delay);
+    }, [spendRestartAttempt, transportFailed]);
+
+    useEffect(() => {
+        scheduleRestartRef.current = scheduleRestart;
+        checkStallRef.current = checkStall;
+    });
+
+    const checkStallRef = useRef(() => {});
+
+    /**
+     * 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) => {
+        // 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;
+        // Our own restart's transients are expected, not a new outage.
+        if (next === 'reconnecting' && Date.now() < restartGraceUntil.current) return;
+        update({ status: next });
+        if (next === 'reconnecting') {
+            // Only a path that once carried frames is worth restarting: an
+            // initial connection that never got there has nothing to save.
+            if (presentedRef.current) {
+                restartAttempts.current = 0;
+                scheduleRestart(RESTART_AFTER_MS);
+            }
+        } else {
+            cancelRestart();
+            if (next === 'live') {
+                // The path is back but may be quiet: a missing heartbeat
+                // from here is a stalled session, not a healthy idle one.
+                cancelStall();
+                stallTimer.current = setTimeout(() => checkStallRef.current(), STALL_AFTER_MS);
+            }
+        }
+    }, [cancelRestart, cancelStall, scheduleRestart, update]);
+
+    /**
+     * One stall check: quiet too long while the session should be talking
+     * means the path is stalled, even when ICE has not said so yet. Only
+     * refs and module constants, so stable callbacks may hold it.
+     */
+    const checkStall = useCallback((): void => {
+        stallTimer.current = null;
+        if (lastPingAt.current === 0) return;
+        // A timer that fires a shade early re-arms for the remainder rather
+        // than dying: a one-shot watchdog must not miss by milliseconds.
+        const quietMs = Date.now() - lastPingAt.current;
+        if (quietMs < STALL_AFTER_MS) {
+            stallTimer.current = setTimeout(() => checkStallRef.current(), STALL_AFTER_MS - quietMs);
+            return;
+        }
+        const status = statusRef.current;
+        if (status !== 'live' && status !== 'connecting' && status !== 'reconnecting') return;
+        if (Date.now() < restartGraceUntil.current) {
+            // Our own restart's transients: recheck when the grace ends.
+            stallTimer.current = setTimeout(() => checkStallRef.current(), restartGraceUntil.current - Date.now());
+            return;
+        }
+        onTransportState('disconnected', false);
+    }, [onTransportState]);
+
+    /**
+     * One engine heartbeat: the path works. It clears a stall the watchdog
+     * saw, then rearms the watchdog — which stays disarmed on engines that
+     * predate heartbeats, since `lastPingAt` never leaves 0 for them.
+     */
+    const notePing = useCallback(() => {
+        lastPingAt.current = Date.now();
+        restartCycles.current = 0;
+        cancelStall();
+        // A heartbeat is the engine alive and the path working.
+        if (statusRef.current === 'reconnecting') onTransportState('connected');
+        stallTimer.current = setTimeout(checkStall, STALL_AFTER_MS);
+    }, [cancelStall, checkStall, onTransportState]);
+
     const send = useCallback((message: ControlMessage) => {
         const id = nativeRef.current;
         if (id == null || nativeDesklink === null || (!inputEnabled.current && message.kind !== 'release_all')) return;
@@ -276,6 +553,10 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         inputEnabled.current = false;
         for (const resolve of pendingClipboard.current.values()) resolve({ text: '', truncated: false, error: 'the session ended' });
         pendingClipboard.current.clear();
+        pendingOffer.current = null;
+        pendingCandidates.current = [];
+        restartGraceUntil.current = 0;
+        restartCycles.current = 0;
         opened.current = null;
         signaling.current = null;
         setNativeId(null);
@@ -302,15 +583,19 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     }, []);
 
     const teardown = useCallback(async (reason: string, closeRemote: boolean) => {
+        cancelReconnect();
+        cancelRestart();
+        cancelStall();
+        restoreToken.current = null;
         const openedRef = opened.current;
         const owner = signaling.current;
         discardSession();
         if (closeRemote) await endRemote(openedRef, owner);
         update({ status: 'ended', presented: false, failure: null });
         void reason;
-    }, [endRemote, discardSession, update]);
+    }, [cancelReconnect, cancelRestart, cancelStall, endRemote, discardSession, update]);
 
-    const connect = useCallback(async () => {
+    const establish = useCallback(async () => {
         if (nativeRef.current != null) return;
         const token = ++generationToken.current;
         if (!(await loadPlatform())) {
@@ -330,6 +615,69 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         if (token !== generationToken.current) return;
         signaling.current = authorization.signaling;
 
+        // Subscribed before the open, because the engine's offer and its first
+        // candidates can beat the open result back. Anything that arrives
+        // before the native session exists is stashed and replayed into it.
+        authorization.signaling.subscribe((event) => {
+            if (token !== generationToken.current) return;
+            const native = nativeRef.current;
+            const held = opened.current;
+            const current = event.sessionId === undefined || held == null || held.sessionId === event.sessionId;
+            switch (event.kind) {
+                case 'description':
+                    if (event.description.type !== 'offer') return;
+                    if (native == null || held == null) {
+                        pendingOffer.current = { sdp: event.description.sdp, sessionId: event.sessionId };
+                        return;
+                    }
+                    if (!current) return;
+                    // A mid-session re-offer is a restart this session asked
+                    // for, through its policy or directly: renegotiation
+                    // transients after it are expected, not a new outage.
+                    if (presentedRef.current) restartGraceUntil.current = Date.now() + RESTART_GRACE_MS;
+                    nativeDesklink?.setRemoteDescription(native, 'offer', event.description.sdp);
+                    return;
+                case 'candidate':
+                    if (native == null || held == null) {
+                        pendingCandidates.current.push({
+                            candidate: event.candidate.candidate,
+                            sdpMid: event.candidate.sdpMid ?? null,
+                            sdpMLineIndex: event.candidate.sdpMLineIndex ?? null,
+                            sessionId: event.sessionId,
+                        });
+                        return;
+                    }
+                    if (!current) return;
+                    nativeDesklink?.addRemoteCandidate(
+                        native,
+                        event.candidate.candidate,
+                        event.candidate.sdpMid ?? null,
+                        event.candidate.sdpMLineIndex ?? null,
+                    );
+                    return;
+                case 'state':
+                    if (!current) return;
+                    diagnostics.current.transport = event.transport;
+                    // Before the session exists there is nothing to map onto.
+                    if (held != null) onTransportState(String(event.transport ?? '').toLowerCase());
+                    update({ diagnostics: { ...diagnostics.current } });
+                    return;
+                case 'restoreToken':
+                    // The live session's grant for a consent-free reopen.
+                    if (current && held != null) restoreToken.current = event.token;
+                    return;
+                case 'revoked':
+                    // Nothing held: the reopen policy owns recovery, and a
+                    // dead session's late revocation must not end it.
+                    if (held == null || !current) return;
+                    void teardown(event.reason, false);
+                    update({ status: 'ended', failure: { code: 'revoked', message: event.reason } });
+                    return;
+                default:
+                    return;
+            }
+        });
+
         let openedResult: SessionOpenResult;
         try {
             openedResult = await authorization.signaling.request<SessionOpenResult>('session.open', {
@@ -339,7 +687,9 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                 bitrate_kbps: authorization.session.bitrateKbps,
                 max_fps: authorization.session.maxFps,
                 ice_servers: serializeIceServers(authorization.session.iceServers),
-                restore_token: authorization.session.restoreToken,
+                // A restore token the live session earned buys a consent-free
+                // reopen; the app's own grant wins when it names one.
+                restore_token: authorization.session.restoreToken ?? restoreToken.current ?? undefined,
                 ttl_seconds: authorization.session.ttlSeconds,
             });
         } catch (error) {
@@ -370,35 +720,20 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
             platform?.setInputEnabled(id, inputEnabled.current);
             setNativeId(id);
 
-            authorization.signaling.subscribe((event) => {
-                if (token !== generationToken.current) return;
-                const native = nativeRef.current;
-                if (native == null) return;
-                switch (event.kind) {
-                    case 'description':
-                        if (event.description.type !== 'offer') return;
-                        nativeDesklink?.setRemoteDescription(native, 'offer', event.description.sdp);
-                        return;
-                    case 'candidate':
-                        nativeDesklink?.addRemoteCandidate(
-                            native,
-                            event.candidate.candidate,
-                            event.candidate.sdpMid ?? null,
-                            event.candidate.sdpMLineIndex ?? null,
-                        );
-                        return;
-                    case 'state':
-                        diagnostics.current.transport = event.transport;
-                        update({ diagnostics: { ...diagnostics.current } });
-                        return;
-                    case 'revoked':
-                        void teardown(event.reason, false);
-                        update({ status: 'ended', failure: { code: 'revoked', message: event.reason } });
-                        return;
-                    default:
-                        return;
-                }
-            });
+            // Anything the engine sent before the native session existed.
+            // A stashed message naming another session is a previous
+            // generation's leftover and is dropped, not replayed.
+            const stashedOffer = pendingOffer.current;
+            pendingOffer.current = null;
+            if (stashedOffer !== null
+                && (stashedOffer.sessionId === undefined || stashedOffer.sessionId === openedResult.sessionId)) {
+                platform?.setRemoteDescription(id, 'offer', stashedOffer.sdp);
+            }
+            for (const candidate of pendingCandidates.current.splice(0)) {
+                if (candidate.sessionId !== undefined && candidate.sessionId !== openedResult.sessionId) continue;
+                platform?.addRemoteCandidate(id, candidate.candidate, candidate.sdpMid, candidate.sdpMLineIndex);
+            }
+
             if (token === generationToken.current) established = true;
         } catch (error) {
             if (token === generationToken.current) {
@@ -410,7 +745,20 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                 await endRemote(openedResult, authorization.signaling);
             }
         }
-    }, [discardSession, endRemote, refuse, teardown, update]);
+    }, [discardSession, endRemote, refuse, teardown, update, onTransportState]);
+
+    /**
+     * Open (or reopen) the session with fresh authority. A deliberate call
+     * starts a fresh reopen budget; the automatic retry calls `establish`
+     * directly so its budget survives.
+     */
+    const connect = useCallback(async () => {
+        attempts.current = 0;
+        restartAttempts.current = 0;
+        restartCycles.current = 0;
+        cancelRestart();
+        await establish();
+    }, [cancelRestart, establish]);
 
     // Native events: answer, candidates, control replies, presentation, failure.
     useEffect(() => {
@@ -455,11 +803,18 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                         return;
                     case 'presented':
                         attempts.current = 0;
+                        restartAttempts.current = 0;
+                        restartCycles.current = 0;
+                        cancelRestart();
                         update({ status: 'live', presented: true, failure: null });
                         return;
                     case 'control': {
                         const reply = parseControlReply(String(event.payload.message ?? ''));
                         if (reply == null) return;
+                        if (reply.kind === 'ping') {
+                            notePing();
+                            return;
+                        }
                         if (reply.kind === 'hello') {
                             diagnostics.current.protocol = reply.protocol;
                             if (reply.protocol !== PROTOCOL_VERSION) {
@@ -496,13 +851,21 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                         }
                         return;
                     }
+                    case 'ice': {
+                        // The peer's connection state, as it happens: Android
+                        // and iOS already emit this, and web matches them.
+                        const state = String(event.payload.state ?? '').toLowerCase();
+                        if (state === 'failed') transportFailed();
+                        else onTransportState(state);
+                        return;
+                    }
                     case 'keyboard':
                         // Typing the platform held back for an armed modifier.
                         if (typeof event.payload.key === 'string') pressKey(event.payload.key)();
                         else if (typeof event.payload.text === 'string') typeText(event.payload.text);
                         return;
                     case 'failure':
-                        refuse(UNREACHABLE_DESKTOP, 'transport');
+                        transportFailed();
                         return;
                     case 'closed':
                         return;
@@ -516,7 +879,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
             dropped = true;
             subscription?.remove();
         };
-    }, [refuse, teardown, update, pressKey, typeText]);
+    }, [transportFailed, onTransportState, cancelRestart, spendRestartAttempt, notePing, teardown, update, pressKey, typeText]);
 
     const copyRemoteToLocal = useCallback(async () => {
         if (!inputEnabled.current) throw new Error('Desktop control is off.');
@@ -551,19 +914,18 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         if (reply.error != null) throw new Error(reply.error);
     }, []);
 
-    const cancelReconnect = useCallback(() => {
-        if (reconnectTimer.current !== null) clearTimeout(reconnectTimer.current);
-        reconnectTimer.current = null;
-    }, []);
-
     const close = useCallback(async (reason = 'closed by the user') => {
         cancelReconnect();
         attempts.current = 0;
+        restartAttempts.current = 0;
+        restartCycles.current = 0;
         await teardown(reason, true);
     }, [cancelReconnect, teardown]);
 
-    // Reconnect once after a transport failure, with fresh authority: a session
-    // that was revoked must not be reopened on the strength of the old grant.
+    // Reopen with fresh authority after a transport failure, backing off
+    // across about a minute: a session that was revoked must not be reopened
+    // on the strength of the old grant, and an outage that outlasts one
+    // attempt must not spend the whole budget while the network is still down.
     useEffect(() => {
         if (snapshot.status !== 'failed') return;
         if (snapshot.failure?.code !== 'transport') return;
@@ -575,17 +937,20 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         const openedRef = opened.current;
         discardSession();
         void endRemote(openedRef, owner);
-        if (attempts.current >= MAX_RECONNECT_ATTEMPTS) return;
+        const wait = backoffDelay(REOPEN_BACKOFF_MS, attempts.current);
+        if (wait === null) return;
         attempts.current += 1;
         update({ status: 'reconnecting' });
         reconnectTimer.current = setTimeout(() => {
             reconnectTimer.current = null;
-            void connect();
-        }, 800);
-    }, [connect, discardSession, endRemote, snapshot.status, snapshot.failure, update]);
+            void establish();
+        }, wait);
+    }, [establish, discardSession, endRemote, snapshot.status, snapshot.failure, update]);
 
     useEffect(() => () => {
         cancelReconnect();
+        cancelRestart();
+        cancelStall();
         generationToken.current += 1;
         const id = nativeRef.current;
         nativeRef.current = null;