@desklink/react-native 0.5.3 → 0.5.4

package/README.md

@@ -3,7 +3,7 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/@desklink/react-native"><img alt="npm" src="https://img.shields.io/npm/v/@desklink/react-native?style=flat&label=npm" /></a>
   <a href="https://github.com/umeranjum17/desklink/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/umeranjum17/desklink/ci.yml?style=flat&branch=main" /></a>
-  <a href="LICENSE"><img alt="Apache 2.0" src="https://img.shields.io/badge/license-Apache--2.0-666?style=flat" /></a>
+  <a href="https://github.com/umeranjum17/desklink/blob/main/packages/desktop-client/LICENSE"><img alt="Apache 2.0" src="https://img.shields.io/badge/license-Apache--2.0-666?style=flat" /></a>
   <img alt="Android, iOS and web" src="https://img.shields.io/badge/Android%20%7C%20iOS%20%7C%20web-111?style=flat" />
 </p>
 
@@ -20,7 +20,7 @@ the application.
 ## Install
 
 The npm badge at the top of this page tracks the registry version, and npm
-verifies package integrity on install. See the [changelog](../../CHANGELOG.md)
+verifies package integrity on install. See the [changelog](https://github.com/umeranjum17/desklink/blob/main/CHANGELOG.md)
 for release changes. Supported platforms: Android, iOS and web.
 
 The package contains native code and is not an Expo Go package. Inside this
@@ -241,8 +241,12 @@ view.
   `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 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.
+  alone does not restore `live` while the picture is frozen). The peer's own ICE
+  `failed` — a lost media path, not a verdict on the session — holds the session
+  and its handle for ~30 s (the engine keeps it for about 28 s after the path
+  dies), so a roam longer than the client's own ~15 s `failed` still returns to
+  the same session; an SDP or candidate failure, which means the negotiation
+  itself is broken, reopens 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
@@ -272,7 +276,28 @@ view.
   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.
+  status nor trigger another restart for a short grace window. A picture
+  that keeps moving holds off the heartbeat watchdog for up to ~20 s, since
+  the control channel lags the video after an outage.
+- **Roaming keeps the session.** The signalling carrier is not the session:
+  when it closes, or a restart request on it gets no reply within 1.5 s, the
+  session drops that carrier for good (calling its optional `close()`) and
+  keeps calling `authorize()` — one dial at a time, 250 ms after a failure,
+  5 s each, with no budget and no backoff. The lost carrier does not change the
+  status by itself: the status follows the picture and the peer's transport, so
+  it reads `reconnecting` only once the picture stops or the stall watchdog
+  fires. While the loop runs, a session that has shown a picture never reports
+  `failed` or a transport failure; one that never showed a picture reports the
+  first-frame transport failure after 20 s and the loop stops. A new carrier
+  picks up the same session after a 300 ms grace for the old ICE pair: if the
+  picture advanced during it, there is no restart (and a `reconnecting`
+  session returns to `live`); otherwise the session moves to `reconnecting`
+  and asks for an ICE restart. Failures caused
+  by the dead carrier wait for the next one rather than ending the session.
+  A carrier that comes back after the host's 30 s reattach window opens a new
+  session at once. A `session` or `generation` refusal (the desktop no longer
+  holds the session) also reopens at once. An `authorize()` refusal still ends
+  the session: a revoked pairing cannot roam back.
 - **Input starts disarmed.** This is a local arm against accidental touches,
   not a permission: the session already has input. `setInputEnabled(true)` arms
   pointer, keyboard and clipboard input; `setInputEnabled(false)` blocks new
@@ -299,7 +324,7 @@ view.
 The one thing the app must supply. It carries the engine's local protocol over
 whatever authenticated channel the app already has.
 
-See the [BYOKit integration guidance](../../README.md#why-desklink-exists)
+See the [BYOKit integration guidance](https://github.com/umeranjum17/desklink/blob/main/README.md#why-desklink-exists)
 for the application's pairing, identity and signaling transport.
 
 ```ts
@@ -315,9 +340,13 @@ 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
+its `Signaling`. It rejects with `code: 'transport'` for a network or carrier
+failure; any other rejection is a refusal that ends the session, so a roam only
+keeps the session when the adapter tags its outages. 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, and may
+offer `close()`, which the package calls on a carrier it has given up on. 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
@@ -334,7 +363,7 @@ What the consuming app — not this package — must get right before review.
   `NSBonjourServices` is only needed if the app adds its own Bonjour
   discovery — desklink discovers no hosts. Relay-only sessions never prompt.
   For app-supplied routes, see the
-  [BYOKit integration guidance](../../README.md#why-desklink-exists).
+  [BYOKit integration guidance](https://github.com/umeranjum17/desklink/blob/main/README.md#why-desklink-exists).
   See [TN3179](https://developer.apple.com/documentation/technotes/tn3179-understanding-local-network-privacy).
 - **Export compliance.** The viewer's DTLS-SRTP comes from libwebrtc bundled
   with `react-native-webrtc`, not from the OS, so the app must check the
@@ -395,7 +424,7 @@ the run builds or caches stays in `~/desklink-ios` there. The run creates a
 uniquely named simulator and deletes it during cleanup. Set
 `DESKLINK_IOS_DEVICE` to the name or udid of one of the Mac's own simulators to
 run on that instead and leave it in place. For host desktop isolation, see the
-[private-lab guidance](../../README.md#develop). When the selected
+[private-lab guidance](https://github.com/umeranjum17/desklink/blob/main/README.md#develop). When the selected
 Xcode has no simulator platform, point `DESKLINK_IOS_XCODE` at one that does;
 `DESKLINK_IOS_RUNTIME` picks the iOS version (for example `18.6`); the
 script's header lists the other settings. To capture the cursor tip proof, set

package/android/build.gradle

@@ -33,7 +33,6 @@ dependencies {
   implementation project(':expo-modules-core')
   implementation 'androidx.core:core-ktx:1.17.0'
   implementation "org.jetbrains.kotlin:kotlin-stdlib:${kotlinVersion}"
-  testImplementation 'junit:junit:4.13.2'
   // The app's existing WebRTC binding, so the org.webrtc classes and the single
   // native library are shared rather than a second copy being linked in. This
   // package never mutates that binding's global decoder factory.

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

@@ -111,7 +111,7 @@ class DesktopSession(
         emit("ready", emptyMap())
       } catch (error: Throwable) {
         Log.w(TAG, "Could not start the desktop session", error)
-        fail("transport", error.message ?: "the desktop session could not start")
+        fail("transport", error.message ?: "the desktop session could not start", "session")
       }
     }
   }
@@ -146,7 +146,7 @@ class DesktopSession(
       val connection = peer ?: return@execute
       val target = epoch
       if (type != "offer") {
-        fail("transport", "the engine must send an offer")
+        fail("transport", "the engine must send an offer", "sdp")
         return@execute
       }
       connection.setRemoteDescription(
@@ -171,23 +171,23 @@ class DesktopSession(
                         }
                       }
 
-                      override fun onCreateFailure(error: String?) = fail("transport", error)
-                      override fun onSetFailure(error: String?) = fail("transport", error)
+                      override fun onCreateFailure(error: String?) = fail("transport", error, "sdp")
+                      override fun onSetFailure(error: String?) = fail("transport", error, "sdp")
                     },
                     answer,
                   )
                 }
 
                 override fun onSetSuccess() = Unit
-                override fun onCreateFailure(error: String?) = fail("transport", error)
-                override fun onSetFailure(error: String?) = fail("transport", error)
+                override fun onCreateFailure(error: String?) = fail("transport", error, "sdp")
+                override fun onSetFailure(error: String?) = fail("transport", error, "sdp")
               },
               MediaConstraints(),
             )
           }
 
-          override fun onCreateFailure(error: String?) = fail("transport", error)
-          override fun onSetFailure(error: String?) = fail("transport", error)
+          override fun onCreateFailure(error: String?) = fail("transport", error, "sdp")
+          override fun onSetFailure(error: String?) = fail("transport", error, "sdp")
         },
         SessionDescription(SessionDescription.Type.OFFER, sdp),
       )
@@ -233,7 +233,7 @@ class DesktopSession(
       ByteBuffer.wrap(message.toString().toByteArray(StandardCharsets.UTF_8)), false,
     ))
     if (!sent) {
-      fail("transport", "the desktop control channel could not send")
+      fail("transport", "the desktop control channel could not send", "control")
       close()
     }
   }
@@ -425,7 +425,7 @@ class DesktopSession(
         ui.postDelayed(sample, 2000)
       }
       if (state == PeerConnection.IceConnectionState.FAILED) {
-        fail("transport", "the connection to the desktop was lost")
+        fail("transport", "the connection to the desktop was lost", "ice")
       }
     }
 
@@ -495,8 +495,16 @@ class DesktopSession(
     ui.post { onEvent(name, payload) }
   }
 
-  private fun fail(code: String, message: String?) {
-    ui.post { onEvent("failure", mapOf("code" to code, "message" to (message ?: "unknown"))) }
+  /**
+   * One native failure, with its `reason` so the hook can tell an ICE failure
+   * (the peer's path died, which the session can be held across) from an SDP,
+   * candidate or control failure (the session itself is broken, which stays
+   * terminal).
+   */
+  private fun fail(code: String, message: String?, reason: String? = null) {
+    val payload = mutableMapOf<String, Any?>("code" to code, "message" to (message ?: "unknown"))
+    if (reason != null) payload["reason"] = reason
+    ui.post { onEvent("failure", payload) }
   }
 
   companion object {

package/package.json

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

package/src/DesktopView.ios.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { Image, Keyboard, StyleSheet, TextInput, View, type GestureResponderEvent, type LayoutChangeEvent, type ViewProps } from 'react-native';
+import { Image, Keyboard, StyleSheet, TextInput, View, useWindowDimensions, type GestureResponderEvent, type LayoutChangeEvent, type ViewProps } from 'react-native';
 import pointerArrow from './pointer.png';
 import { requireNativeViewManager, requireOptionalNativeModule } from 'expo-modules-core';
 import type { DesktopViewProps } from './DesktopView';
@@ -155,11 +155,17 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
     const scale = zoom === null ? fill : fit * zoom;
     /** The zoom over the whole-desktop fit the picture is at now. */
     const zoomed = fit > 0 ? scale / fit : 1;
-    // A new desktop size fills the view again, and a new fill (a rotation)
-    // starts again, at the desktop's top-left corner, where a page's first words are.
+    // A new desktop size fills the view again, and a rotation starts again at
+    // the desktop's top-left corner, where a page's first words are. Only an
+    // orientation change resets it: the application making room for the
+    // keyboard also changes the view, by taking height away, and that must
+    // move the picture (below) rather than snap it back to the corner and
+    // leave the field the tap just put the caret in hidden under the keyboard.
+    const window = useWindowDimensions();
+    const portrait = window.width <= window.height;
     React.useEffect(() => { setZoom(null); setOffset(TOP_LEFT); }, [size.width, size.height]);
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    React.useEffect(() => { if (zoom === null) setOffset(TOP_LEFT); }, [fill, bounds.width, bounds.height, top, left, insets?.right, insets?.bottom]);
+    React.useEffect(() => { if (zoom === null) setOffset(TOP_LEFT); }, [portrait]);
     const pictureWidth = size.width * scale;
     const pictureHeight = size.height * scale;
     const point = (x: number, y: number, clamp = false): Point | null => {

package/src/native.ios.ts

@@ -95,8 +95,13 @@ export function preferH264(sdp: string): string {
     return lines.join('\r\n');
 }
 
-function failure(id: string, error: unknown) {
-    emit(id, 'failure', { code: 'transport', message: error instanceof Error ? error.message : String(error) });
+/**
+ * One native failure, with its `reason` so the hook can tell an ICE failure
+ * (the peer's path died, which the session can be held across) from an SDP or
+ * candidate failure (the negotiation itself is broken, which stays terminal).
+ */
+function failure(id: string, error: unknown, reason: 'ice' | 'sdp' | 'candidate' | 'control') {
+    emit(id, 'failure', { code: 'transport', reason, message: error instanceof Error ? error.message : String(error) });
 }
 
 export const nativeDesklink: NativeDesklinkModule = {
@@ -121,7 +126,7 @@ export const nativeDesklink: NativeDesklinkModule = {
             };
             peer.oniceconnectionstatechange = () => {
                 emit(id, 'ice', { state: peer.iceConnectionState.toUpperCase() });
-                if (peer.iceConnectionState === 'failed') failure(id, 'the connection to the desktop was lost');
+                if (peer.iceConnectionState === 'failed') failure(id, 'the connection to the desktop was lost', 'ice');
             };
             peer.ontrack = (event) => {
                 if (session.closed || event.track.kind !== 'video') return;
@@ -148,7 +153,7 @@ export const nativeDesklink: NativeDesklinkModule = {
     setRemoteDescription(id, type, sdp) {
         const session = sessions.get(id);
         if (!session) return false;
-        if (type !== 'offer') { failure(id, 'the engine must send an offer'); return false; }
+        if (type !== 'offer') { failure(id, 'the engine must send an offer', 'sdp'); return false; }
         void (async () => {
             try {
                 await session.peer.setRemoteDescription({ type: 'offer', sdp: preferH264(sdp.replace(PLAYOUT_DELAY, '')) });
@@ -158,7 +163,7 @@ export const nativeDesklink: NativeDesklinkModule = {
                 const answer = await session.peer.createAnswer();
                 await session.peer.setLocalDescription(answer);
                 if (!session.closed) emit(id, 'answer', { sdp: session.peer.localDescription?.sdp ?? answer.sdp });
-            } catch (error) { if (!session.closed) failure(id, error); }
+            } catch (error) { if (!session.closed) failure(id, error, 'sdp'); }
         })();
         return true;
     },
@@ -167,7 +172,7 @@ export const nativeDesklink: NativeDesklinkModule = {
         if (!session) return false;
         const ice = { candidate, sdpMid, sdpMLineIndex: sdpMLineIndex ?? 0 };
         if (!session.remoteSet) session.candidates.push(ice);
-        else void session.peer.addIceCandidate(ice).catch((error) => failure(id, error));
+        else void session.peer.addIceCandidate(ice).catch((error) => failure(id, error, 'candidate'));
         return true;
     },
     sendControl(id, message) {
@@ -178,7 +183,7 @@ export const nativeDesklink: NativeDesklinkModule = {
             if (!session.input && ['pointer', 'wheel', 'key', 'text', 'clipboard_read', 'clipboard_write'].includes(String(control.kind))) return false;
             session.channel.send(JSON.stringify({ ...control, seq: ++session.seq }));
             return true;
-        } catch (error) { failure(id, error); return false; }
+        } catch (error) { failure(id, error, 'control'); return false; }
     },
     setInputEnabled(id, enabled) {
         const session = sessions.get(id);

package/src/native.web.ts

@@ -1018,7 +1018,7 @@ export const nativeDesklink: NativeDesklinkModule = {
         peer.onconnectionstatechange = () => {
             if (sessions.get(id) !== session) return;
             if (peer.connectionState === 'failed') {
-                emit(id, 'failure', { code: 'transport', message: 'the connection to the desktop was lost' });
+                emit(id, 'failure', { code: 'transport', reason: 'ice', message: 'the connection to the desktop was lost' });
             }
         };
         peer.oniceconnectionstatechange = () => {
@@ -1035,7 +1035,7 @@ export const nativeDesklink: NativeDesklinkModule = {
         const session = sessions.get(id);
         if (session === undefined) return false;
         if (type !== 'offer') {
-            emit(id, 'failure', { code: 'transport', message: 'the engine must send an offer' });
+            emit(id, 'failure', { code: 'transport', reason: 'sdp', message: 'the engine must send an offer' });
             return false;
         }
         void (async () => {
@@ -1052,6 +1052,7 @@ export const nativeDesklink: NativeDesklinkModule = {
             } catch (error) {
                 emit(id, 'failure', {
                     code: 'transport',
+                    reason: 'sdp',
                     message: error instanceof Error ? error.message : 'the desktop refused our answer',
                 });
             }

package/src/protocol.ts

@@ -122,7 +122,8 @@ 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.
+ * The application's authorize() resolves only once this carrier is open. Its
+ * rejection rules (transport vs. refusal) are in the README's Signaling section.
  */
 export interface Signaling {
     /**
@@ -134,6 +135,8 @@ export interface Signaling {
      */
     request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
     subscribe(handler: (event: SessionEvent) => void): () => void;
+    /** Optional: end this carrier now. Called once the package has declared it dead. */
+    close?(): void;
 }
 
 export type SessionStatus =
@@ -178,7 +181,7 @@ export interface SessionSnapshot {
 }
 
 /**
- * Control-channel messages. `seq` is monotonic per generation; the engine
+ * Control-channel messages. `seq` is monotonic per session; the engine
  * refuses a repeat, so a replayed gesture cannot move the pointer twice.
  */
 export type ControlMessage =