@desklink/react-native 0.3.1 → 0.5.0

package/README.md

@@ -58,12 +58,12 @@ changes, and trackpad presses reach the desktop as touches.
 ## Use
 
 ```tsx
-import { DesktopView, useDesktopSession, CONTROL_PERMISSIONS } from '@desklink/react-native';
+import { DesktopView, useDesktopSession } from '@desklink/react-native';
 
 const desktop = useDesktopSession({
     authorize: async () => ({
         signaling,                                   // your authenticated channel to the host
-        session: { permissions: CONTROL_PERMISSIONS },
+        session: {},
     }),
 });
 
@@ -76,8 +76,17 @@ desktop.setInputEnabled(true);
 desktop.showKeyboard();
 desktop.setOrientation('landscape');   // Android only; iOS apps configure supported orientations themselves
 await desktop.pasteLocalToRemote(await Clipboard.getStringAsync());
+// Optional receiver evidence: codec, decoder and video counters; no ICE addresses.
+const stats = await desktop.getStats();
 ```
 
+Pairing is the only trust boundary. `authorize` is the app's pairing check: it
+returns a channel to a paired computer or throws, and it runs again on every
+reconnect, so a revoked pairing cannot reopen. A paired session has view,
+input and clipboard; there are no in-app grants, and `session.permissions` is
+ignored. Only the operating system's own consent (screen recording,
+accessibility, a screen-sharing prompt) still applies on the computer.
+
 A screen that only decides *whether* to offer a desktop does not need the
 session: import the flag from its own entry, which is a constant on web and a
 check for the platform module elsewhere, so the hook and the view stay out of
@@ -98,7 +107,7 @@ engine only produces frames on change.
 Keep the encoded picture inside a 1920×1080 box:
 
 ```tsx
-session: { permissions: CONTROL_PERMISSIONS, maxWidth: 1920, maxHeight: 1080 },
+session: { maxWidth: 1920, maxHeight: 1080 },
 ```
 
 The engine never upscales, so a smaller desktop is sent at its own size and a
@@ -120,15 +129,23 @@ heat and battery.
   so the iOS receiver asks for H.264 by putting it first in the offer it
   applies; a host with an H.264 encoder then sends H.264, and one without sends
   VP9. Neither platform links a second WebRTC stack.
-- **A sharp, zoomable picture.** The desktop fits the view by default; a pinch
-  zooms up to 2.5 view pixels per desktop pixel and one finger moves around the
-  zoomed desktop. On Android the decoded frame is copied once into the view's
+- **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
+  content; pinch to zoom before panning when the whole desktop already fits.
+  Pass the screen's safe-area `insets` (for example from
+  `react-native-safe-area-context`) so the default starts below the status bar
+  and beside a camera cutout. Panning brings each desktop edge inside the safe
+  area, while landscape coverage extends beneath the cutout and home indicator
+  to limit black bars. A pinch zooms up to 2.5 view
+  pixels per desktop pixel, or out to the whole desktop. On Android the decoded frame is copied once into the view's
   own texture and drawn with a multi-tap filter when it is shown smaller than
   its size, so a fitted 4K desktop does not alias and a pinch redraws at once.
   iOS uses `RTCView`'s native renderer. That renderer draws a frame only when
   its timestamp is new, and a receiver honouring the engine's zero playout delay
   stamps every frame alike, so the iOS peer declines that hint and keeps the
-  receiver's usual jitter buffer. `fitToView()` shows the whole desktop again.
+  receiver's usual jitter buffer. `fitToView()` shows the whole desktop; a new
+  desktop size or a rotation reapplies the orientation default from the top-left.
 - **A pointer a phone can see.** Once a touch has sent the desktop's pointer
   somewhere, the view draws an outlined arrow there at a readable size, over a
   picture whose own cursor is a few pixels tall or not captured at all. On iOS,
@@ -141,7 +158,7 @@ heat and battery.
   (`keyboardClearance`). Android follows the keyboard animation and keeps the
   pointer in sight; iOS follows the keyboard show/hide bounds.
 - **Contained geometry.** Touch maps through the picture's actual placement.
-  A one-finger drag starting in the letterbox does not move the pointer; a
+  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
   leaves the picture is held to its edge rather than released somewhere unseen.
 - **The gestures remote-desktop viewers settled on,** with a slop threshold:
@@ -212,11 +229,13 @@ heat and battery.
   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
-  after a deliberate action and must disable it on background or lost readiness;
-  a clipboard write already in flight may still finish.
+- **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
+  input, releases held keys and buttons, and resets pending gestures. The app
+  decides when to arm it after a deliberate action and must disarm it on
+  background or lost readiness; a clipboard write already in flight may still
+  finish.
 - **Released state.** The app disables input on background and unmount;
   session close and a lost control channel release what the desktop was holding.
 - **Explicit clipboard.** Two methods, called on a user action while control is
@@ -274,11 +293,16 @@ What the consuming app — not this package — must get right before review.
   disabling input on background; the engine releases held keys within
   seconds of the path dying, so nothing stays stuck.
 
-## iOS simulator proof
+## Example app proof
 
 `example/` is the smallest app that shows a desktop: a native (non-Expo Go)
 build with `react-native-webrtc`, connecting to `desklink-host bridge` with the
-URL it is launched with. `test/ios-flow.mjs` builds it for the iOS simulator on
+URL it is launched with on iOS, or the connection link it is opened with on
+Android. Its hidden accessibility status shows plain messages: `Connected`
+once a frame is presented, `Can’t reach your desktop. Reconnecting…` while
+retrying, and `Your desktop ended this session` after revocation. It never
+displays the bridge URL, pairing token, raw failure text or frame metrics.
+`test/ios-flow.mjs` builds it for the iOS simulator on
 a Mac over ssh, serves a private Xvfb desktop from this machine through the
 bridge, and checks that the first frame is presented, that the answer puts
 H.264 first with NACK when the host offers it (VP9 otherwise; both descriptions
@@ -314,6 +338,19 @@ To try the example by hand against any bridge:
 xcrun simctl launch <device> dev.desklink.example -desklinkUrl 'ws://HOST:PORT/desktop?token=TOKEN'
 ```
 
+On Android, build the same example with `npm run android` and open a connection
+link whose `url` query parameter is the URL-encoded bridge WebSocket address:
+`desklink-example://connect?url=ws%3A%2F%2FHOST%3APORT%2Fdesktop%3Ftoken%3DTOKEN`.
+The example allows the bridge's plaintext private-network connection; consumer
+apps choose their own transport policy. A new link replaces the open session.
+The live picture has no diagnostic overlay. Its accessibility status remains
+available as `desklink-status`.
+
+For device evidence, an optional `report` query parameter accepts a URL-encoded
+HTTP endpoint. While live, the example posts receiver statistics and connection
+and first-presentation timestamps once per second. Collection failures do not
+interrupt the session. Without that parameter, no evidence is posted.
+
 ## Licence
 
 Apache-2.0. See `NOTICE`.

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

@@ -5,6 +5,7 @@ import android.content.pm.ActivityInfo
 import android.content.res.Configuration
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
+import expo.modules.kotlin.Promise
 import java.util.concurrent.ConcurrentHashMap
 
 /**
@@ -113,6 +114,12 @@ class DesklinkModule : Module() {
 
     Function("isAvailable") { true }
 
+    AsyncFunction("getStats") { id: String, promise: Promise ->
+      val session = sessions[id]
+      if (session == null) promise.resolve("[]")
+      else session.getStats { promise.resolve(it) }
+    }
+
     View(DesktopView::class) {
       Name("DesklinkSurface")
 
@@ -126,6 +133,14 @@ class DesklinkModule : Module() {
         view.setKeyboardClearance(clearance ?: 0f)
       }
 
+      Prop("insets") { view: DesktopView, insets: List<Double>? ->
+        val edges = insets.orEmpty()
+        view.setInsets(
+          edges.getOrNull(0)?.toFloat() ?: 0f, edges.getOrNull(1)?.toFloat() ?: 0f,
+          edges.getOrNull(2)?.toFloat() ?: 0f, edges.getOrNull(3)?.toFloat() ?: 0f,
+        )
+      }
+
       Prop("gestures") { view: DesktopView, gestures: String? ->
         view.setGestures(gestures ?: "desktop")
       }

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

@@ -370,6 +370,33 @@ class DesktopSession(
     return servers
   }
 
+  /** A bounded diagnostics snapshot; never expose ICE addresses or control content. */
+  @Synchronized
+  fun getStats(done: (String) -> Unit) {
+    if (closed) {
+      done("[]")
+      return
+    }
+    io.execute {
+      val connection = peer
+      if (closed || connection == null) {
+        done("[]")
+        return@execute
+      }
+      connection.getStats { report ->
+        val fields = setOf("kind", "mediaType", "codecId", "mimeType", "clockRate", "payloadType",
+          "packetsReceived", "packetsLost", "bytesReceived", "framesReceived", "framesDecoded",
+          "keyFramesDecoded", "framesDropped", "framesPerSecond", "frameWidth", "frameHeight",
+          "nackCount", "pliCount", "firCount", "totalDecodeTime", "decoderImplementation", "jitterBufferDelay")
+        val stats = report.statsMap.values.filter { it.type == "inbound-rtp" || it.type == "codec" }
+          .map { stat -> JSONObject(stat.members.filterKeys { it in fields }).apply {
+            put("id", stat.id); put("type", stat.type); put("timestampUs", stat.timestampUs)
+          } }
+        done(org.json.JSONArray(stats).toString())
+      }
+    }
+  }
+
   private fun observer(target: Long) = object : PeerConnection.Observer {
     override fun onSignalingChange(state: PeerConnection.SignalingState?) = Unit
 

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

@@ -65,7 +65,8 @@ private const val MIN_WHEEL_STEP = 0.05f
  *  - tap: click where the finger lands; two taps: a double click on the same 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,
+ *  - one finger: move around a zoomed-in desktop — the picture starts filled,
+ *    covering the view, so this is the default; on the whole desktop,
  *    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;
@@ -102,11 +103,23 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
 
   // 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.
+  // was showing the whole desktop showing it when the view changes size;
+  // `filling` keeps the default, a picture covering the view, until the user
+  // zooms or asks for the whole desktop. `filledScale` is the fill it was last
+  // placed at, so a new fill (a rotation, a new surface) starts at the
+  // desktop's top-left corner again.
   private var scale = 1f
   private var originX = 0f
   private var originY = 0f
   private var fitted = true
+  private var filling = true
+  private var filledScale = 0f
+
+  /** What the system covers at each edge (bars, cutout), in pixels: left, top, right, bottom. */
+  private var insetLeft = 0f
+  private var insetTop = 0f
+  private var insetRight = 0f
+  private var insetBottom = 0f
 
   /**
    * How much of this view's bottom the phone's keyboard, and the app's own
@@ -254,6 +267,8 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
     surfaceWidth = width
     surfaceHeight = height
     fitted = true
+    filling = true
+    filledScale = 0f
     // A point on the old geometry says nothing about the new one.
     pointerAt = null
     layoutPicture()
@@ -296,6 +311,22 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
   /** Show the whole desktop again. */
   fun fitToView() {
     fitted = true
+    filling = false
+    layoutPicture()
+  }
+
+  /**
+   * What the system covers at each edge of the view, in points. The picture
+   * still reaches under it, but starts and pans inside it.
+   */
+  fun setInsets(top: Float, left: Float, bottom: Float, right: Float) {
+    val density = resources.displayMetrics.density
+    if (top * density == insetTop && left * density == insetLeft && bottom * density == insetBottom && right * density == insetRight) return
+    insetTop = top * density
+    insetLeft = left * density
+    insetBottom = bottom * density
+    insetRight = right * density
+    filledScale = 0f
     layoutPicture()
   }
 
@@ -347,9 +378,9 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
    */
   private fun coverBottom(next: Float) {
     if (abs(next - covered) < 0.5f) return
-    val before = visibleHeight()
+    val before = visibleBottom()
     covered = next
-    val visible = visibleHeight()
+    val visible = visibleBottom()
     val at = pointerAt
     if (at == null) {
       originY += (visible - before) / 2f
@@ -361,7 +392,13 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
     layoutPicture()
   }
 
-  private fun visibleHeight(): Float = max(1f, height - covered)
+  /** Where the uncovered part of the view ends: above the keyboard, or above what the system covers. */
+  private fun visibleBottom(): Float = max(insetTop + 1f, min(height - covered, height - insetBottom))
+
+  private fun safeWidth(): Float = max(1f, width - insetLeft - insetRight)
+
+  /** The whole uncovered height, keyboard or not: the keyboard moves the picture rather than shrinking it. */
+  private fun safeHeight(): Float = max(1f, height - insetTop - insetBottom)
 
   private fun inputMethods() = context.getSystemService(Context.INPUT_METHOD_SERVICE) as InputMethodManager
 
@@ -386,8 +423,10 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
 
   override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
     super.onSizeChanged(w, h, oldw, oldh)
-    // A rotation: keep what the user was looking at.
-    if (oldw > 0 && oldh > 0 && !fitted) {
+    // A rotation: a filled picture starts again at its top-left corner;
+    // a zoomed one keeps what the user was looking at.
+    if (filling) filledScale = 0f
+    else if (oldw > 0 && oldh > 0 && !fitted) {
       originX += (w - oldw) / 2f
       originY += (h - oldh) / 2f
     }
@@ -416,34 +455,54 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
    */
   private fun fitScale(): Float {
     if (width == 0 || height == 0 || surfaceWidth == 0 || surfaceHeight == 0) return 1f
-    return min(width.toFloat() / surfaceWidth, height.toFloat() / surfaceHeight)
+    return min(safeWidth() / surfaceWidth, safeHeight() / surfaceHeight)
+  }
+
+  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))
   }
 
-  /** Re-derive the placement from `fitted`, the zoom limits and the edges. */
+  /** Re-derive the placement from `filling`, `fitted`, the zoom limits and the edges. */
   private fun layoutPicture() {
     if (surfaceWidth == 0 || surfaceHeight == 0 || width == 0 || height == 0) return
     val fit = fitScale()
-    scale = if (fitted) fit else scale.coerceIn(fit, max(fit, MAX_SCALE))
+    if (filling) {
+      val fill = fillScale()
+      if (fill != filledScale) {
+        scale = fill
+        filledScale = fill
+        // The desktop's top-left corner, where a page's first words are.
+        originX = insetLeft
+        originY = insetTop
+      }
+    } else {
+      scale = if (fitted) fit else scale.coerceIn(fit, max(fit, MAX_SCALE))
+    }
     fitted = scale <= fit * 1.001f
     clampOrigin()
     publishTransform()
   }
 
   /**
-   * A picture smaller than what is visible is centred on that axis; a larger
-   * one covers it. Above the keyboard, only the uncovered part counts.
+   * A picture smaller than the uncovered part of the view is centred in it on
+   * that axis; a larger one can move until either edge reaches that part's
+   * edge. Above the keyboard, only the part above it counts.
    */
   private fun clampOrigin() {
     val pictureWidth = surfaceWidth * scale
     val pictureHeight = surfaceHeight * scale
-    val visible = visibleHeight()
-    originX = if (pictureWidth <= width) (width - pictureWidth) / 2f else originX.coerceIn(width - pictureWidth, 0f)
-    originY = if (pictureHeight <= visible) (visible - pictureHeight) / 2f else originY.coerceIn(visible - pictureHeight, 0f)
+    val right = width - insetRight
+    val bottom = visibleBottom()
+    originX = if (pictureWidth <= right - insetLeft) insetLeft + (right - insetLeft - pictureWidth) / 2f else originX.coerceIn(right - pictureWidth, insetLeft)
+    originY = if (pictureHeight <= bottom - insetTop) insetTop + (if (filling) 0f else (bottom - insetTop - pictureHeight) / 2f) else originY.coerceIn(bottom - pictureHeight, insetTop)
   }
 
   private fun zoomAround(focusX: Float, focusY: Float, factor: Float) {
     val fit = fitScale()
     val next = (scale * factor).coerceIn(fit, max(fit, MAX_SCALE))
+    filling = false
     val applied = next / scale
     originX = focusX - (focusX - originX) * applied
     originY = focusY - (focusY - originY) * applied
@@ -623,7 +682,7 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
           }
           // 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
+          gesture = if (filling || !fitted) Gesture.PAN else if (downOnPicture) Gesture.HOVER else Gesture.LETTERBOX
           lastX = event.x
           lastY = event.y
           if (gesture == Gesture.HOVER) hoverTo(active, event.x, event.y)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@desklink/react-native",
-    "version": "0.3.1",
+    "version": "0.5.0",
     "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

@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import React from 'react';
 import TestRenderer from 'react-test-renderer';
+import { pictureBox } from '../test/picture-box.mjs';
 
 /** `act` refuses to flush state updates unless React is told this is a test. */
 (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -57,14 +58,16 @@ const required: string[] = [];
 
 const BOUNDS = { width: 390, height: 844 };
 const DESKTOP = { width: 1280, height: 720 };
-// fit = min(390/1280, 844/720); the picture is 390 wide, centred vertically.
+// Most of this spec works on the whole desktop (`whole: true`, as after
+// `fitToView()`): fit = min(390/1280, 844/720); the picture is 390 wide,
+// centred vertically.
 const SCALE = Math.min(BOUNDS.width / DESKTOP.width, BOUNDS.height / DESKTOP.height);
 const ORIGIN_Y = (BOUNDS.height - DESKTOP.height * SCALE) / 2;
 
 type Touch = { locationX: number; locationY: number; timestamp?: number };
 function touch(x: number, y: number, timestamp?: number): Touch { return { locationX: x, locationY: y, timestamp }; }
 
-async function openView(options: { gestures?: 'desktop' | 'browser' | 'device'; accessibilityLabel?: string; native?: boolean } = {}) {
+async function openView(options: { gestures?: 'desktop' | 'browser' | 'device'; accessibilityLabel?: string; native?: boolean; whole?: boolean; desktop?: { width: number; height: number }; bounds?: { width: number; height: number }; insets?: { top: number; left: number; bottom: number; right: number } } = {}) {
     nativeInput.installed = options.native === true;
     const { desktopInputEnabled, nativeDesklink } = await import('./native.ios');
     const { DesktopView } = await import('./DesktopView.ios');
@@ -79,7 +82,7 @@ async function openView(options: { gestures?: 'desktop' | 'browser' | 'device';
     let renderer: TestRenderer.ReactTestRenderer | null = null;
     TestRenderer.act(() => {
         renderer = TestRenderer.create(
-            <DesktopView sessionId={id} gestures={options.gestures} accessibilityLabel={options.accessibilityLabel} />,
+            <DesktopView sessionId={id} gestures={options.gestures} accessibilityLabel={options.accessibilityLabel} insets={options.insets} />,
         );
     });
     const outer = () => renderer!.root.findByType(options.native ? 'DesklinkInput' as never : 'View').props as {
@@ -90,10 +93,11 @@ async function openView(options: { gestures?: 'desktop' | 'browser' | 'device';
         [key: string]: unknown;
     };
     TestRenderer.act(() => {
-        outer().onLayout({ nativeEvent: { layout: { ...BOUNDS } } });
-        nativeDesklink.setSurfaceSize(id, DESKTOP.width, DESKTOP.height);
+        outer().onLayout({ nativeEvent: { layout: { ...(options.bounds ?? BOUNDS) } } });
+        nativeDesklink.setSurfaceSize(id, (options.desktop ?? DESKTOP).width, (options.desktop ?? DESKTOP).height);
         peer.ontrack!({ track: { kind: 'video' }, streams: [] });
     });
+    if (options.whole ?? true) TestRenderer.act(() => { nativeDesklink.fitToView(id); });
     const grant = (at: Touch[]) => TestRenderer.act(() => { outer().onResponderGrant({ nativeEvent: { touches: at } }); });
     const move = (at: Touch[]) => TestRenderer.act(() => { outer().onResponderMove({ nativeEvent: { touches: at } }); });
     const release = (at: Touch[] = []) => TestRenderer.act(() => { outer().onResponderRelease({ nativeEvent: { touches: at } }); });
@@ -130,6 +134,124 @@ beforeEach(() => {
 afterEach(() => { vi.unstubAllGlobals(); });
 
 describe('DesktopView.ios parity with DesktopView.kt', () => {
+    it('fits portrait width, then zooms and pans without distorting the desktop', async () => {
+        const { sent, rtcStyle, grant, move, release } = await openView({ whole: false });
+        expect(rtcStyle()).toMatchObject({ left: 0, top: 0, width: BOUNDS.width });
+        expect(rtcStyle().height).toBeCloseTo(DESKTOP.height * SCALE, 5);
+        grant([touch(100, 100)]);
+        move([touch(100, 100), touch(140, 100)]);
+        move([touch(80, 100), touch(160, 100)]);
+        release();
+        const before = rtcStyle();
+        expect(before.width / before.height).toBeCloseTo(DESKTOP.width / DESKTOP.height, 5);
+        grant([touch(260, 400)]);
+        move([touch(200, 400)]);
+        release();
+        expect(sent.filter((message) => message.kind === 'pointer')).toEqual([]);
+        expect(rtcStyle().left).toBeCloseTo(before.left - 60, 5);
+        const at = rtcStyle();
+        grant([touch(100, 300)]);
+        release();
+        expect(sent.filter((message) => message.kind === 'pointer')).toMatchObject([
+            { kind: 'pointer', phase: 'down', x: Math.floor((100 - at.left) / (SCALE * 2)), y: Math.floor((300 - at.top) / (SCALE * 2)), button: 1 },
+            { kind: 'pointer', phase: 'up', x: Math.floor((100 - at.left) / (SCALE * 2)), y: Math.floor((300 - at.top) / (SCALE * 2)), button: 1 },
+        ]);
+    });
+
+    it('pans a tall portrait desktop to both vertical edges at fit-width', async () => {
+        const insets = { top: 47, left: 0, bottom: 21, right: 0 };
+        const { rtcStyle, grant, move, release } = await openView({ whole: false, insets, desktop: { width: 720, height: 1800 } });
+        expect(rtcStyle().width).toBeCloseTo(390, 5);
+        expect(rtcStyle().top).toBeCloseTo(47, 5);
+        grant([touch(200, 400)]);
+        move([touch(200, -2000)]);
+        release();
+        expect(rtcStyle().top + rtcStyle().height).toBeCloseTo(823, 5);
+        grant([touch(200, 400)]);
+        move([touch(200, 2000)]);
+        release();
+        expect(rtcStyle().top).toBeCloseTo(47, 5);
+    });
+
+    it('starts again at the top-left corner after a rotation, and keeps the whole desktop when the same size is reported again', async () => {
+        const { id, nativeDesklink, outer, rtcStyle, grant, move, release } = await openView({ whole: false });
+        grant([touch(260, 400)]);
+        move([touch(200, 400)]);
+        release();
+        expect(rtcStyle().left).toBeCloseTo(0, 5);
+        const layout = (bounds: { width: number; height: number }) => TestRenderer.act(() => {
+            (outer().onLayout as (event: unknown) => void)({ nativeEvent: { layout: bounds } });
+        });
+        layout({ width: BOUNDS.height, height: BOUNDS.width });
+        // Landscape crops the bottom, never the top.
+        expect(rtcStyle().top).toBeCloseTo(0, 5);
+        expect(rtcStyle().left).toBeCloseTo(0, 5);
+        layout(BOUNDS);
+        expect(rtcStyle().left).toBeCloseTo(0, 5);
+        TestRenderer.act(() => { nativeDesklink.fitToView(id); });
+        TestRenderer.act(() => { nativeDesklink.setSurfaceSize(id, DESKTOP.width, DESKTOP.height); });
+        expect(rtcStyle().width).toBeCloseTo(BOUNDS.width, 5);
+    });
+
+    it('resets both default offsets on equal-scale layout and inset changes', async () => {
+        const { DesktopView } = await import('./DesktopView.ios');
+        const insets = { top: 0, left: 47, bottom: 21, right: 47 };
+        const { id, renderer, outer, rtcStyle, grant, move, release } = await openView({ whole: false, bounds: { width: 844, height: 390 }, insets });
+        const pan = () => {
+            grant([touch(400, 200)]);
+            move([touch(340, 140)]);
+            release();
+        };
+        const width = rtcStyle().width;
+        pan();
+        expect(rtcStyle().left).toBeLessThan(47);
+        expect(rtcStyle().top).toBeLessThan(0);
+        TestRenderer.act(() => { outer().onLayout({ nativeEvent: { layout: { width: 844, height: 400 } } }); });
+        expect(rtcStyle()).toMatchObject({ left: 47, top: 0, width });
+        pan();
+        TestRenderer.act(() => { renderer.update(<DesktopView sessionId={id} insets={{ top: 10, left: 50, right: 44, bottom: 21 }} />); });
+        expect(rtcStyle()).toMatchObject({ left: 50, top: 10, width });
+    });
+
+    it('starts and pans inside the insets while the picture still reaches under them', async () => {
+        const landscape = { width: 844, height: 390 };
+        const insets = { top: 0, left: 47, bottom: 21, right: 47 };
+        const { rtcStyle, grant, move, release } = await openView({ whole: false, bounds: landscape, insets });
+        const fill = Math.max(landscape.width / DESKTOP.width, landscape.height / DESKTOP.height);
+        expect(rtcStyle().width).toBeCloseTo(DESKTOP.width * fill, 5);
+        // The desktop's top-left corner shows just inside the cutout's side.
+        expect(rtcStyle().left).toBeCloseTo(47, 5);
+        expect(rtcStyle().top).toBeCloseTo(0, 5);
+        // Panned all the way, the desktop's right and bottom edges reach the
+        // uncovered part's edges, not the screen's.
+        grant([touch(600, 300)]);
+        move([touch(-2000, -2000)]);
+        release();
+        expect(rtcStyle().left + rtcStyle().width).toBeCloseTo(landscape.width - 47, 5);
+        expect(rtcStyle().top + rtcStyle().height).toBeCloseTo(landscape.height - 21, 5);
+        for (const x of [-2000, 2000]) for (const y of [-2000, 2000]) {
+            grant([touch(400, 200)]);
+            move([touch(x, y)]);
+            release();
+            const box = rtcStyle();
+            const width = Math.min(landscape.width, box.left + box.width) - Math.max(0, box.left);
+            const height = Math.min(landscape.height, box.top + box.height) - Math.max(0, box.top);
+            expect(1 - width * height / (landscape.width * landscape.height)).toBeLessThan(0.15);
+            expect(box.width / box.height).toBeCloseTo(DESKTOP.width / DESKTOP.height, 5);
+        }
+
+    });
+
+    it('leaves no black bars on a landscape phone, and fitToView shows the whole desktop', async () => {
+        const landscape = { width: 844, height: 390 };
+        const { id, nativeDesklink, rtcStyle } = await openView({ whole: false, bounds: landscape });
+        expect(rtcStyle().width).toBeCloseTo(landscape.width, 5);
+        expect(rtcStyle().left).toBeCloseTo(0, 5);
+        TestRenderer.act(() => { nativeDesklink.fitToView(id); });
+        expect(rtcStyle().height).toBeCloseTo(landscape.height, 5);
+        expect(rtcStyle().width).toBeCloseTo(DESKTOP.width * landscape.height / DESKTOP.height, 5);
+    });
+
     it('ignores a one-finger drag that starts in the letterbox', async () => {
         const { sent, grant, move, release } = await openView();
         // y = 10 is above the fitted picture (it starts at ORIGIN_Y).
@@ -148,7 +270,8 @@ describe('DesktopView.ios parity with DesktopView.kt', () => {
         const { rtcStyle, grant, move } = await openView();
         grant([touch(100, 400)]);
         move([touch(100, 400), touch(140, 400)]);
-        move([touch(80, 400), touch(160, 400)]);
+        // A finger's pinch spreads a few points per move, each step under the slop.
+        for (let step = 2; step <= 20; step += 2) move([touch(100 - step, 400), touch(140 + step, 400)]);
         expect(rtcStyle().width).toBeCloseTo(DESKTOP.width * SCALE * 2, 0);
         // The desktop point under the focus (120, 400) stays under it.
         expect(rtcStyle().left).toBeCloseTo(-120, 0);
@@ -362,3 +485,28 @@ describe('DesktopView.ios hardware keyboard and pointer', () => {
         expect(wheels[1].dy).toBeCloseTo(0.01 / SCALE / 120, 5);
     });
 });
+
+
+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 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;
+                    png.data.set([251, 250, 247, 255], i);
+                }
+            };
+            paper(0, 47, 390, 266);
+            paper(125, 825, 265, 830);
+            expect(pictureBox(png, 390)).toEqual({ top: 47, left: 0, bottom: 266 });
+            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 });
+            png.data.fill(0);
+            paper(47, 0, 390, 844);
+            expect(pictureBox(png, 390)).toEqual({ top: 0, left: 47, bottom: 844 });
+        }
+    });
+});

package/src/DesktopView.ios.tsx

@@ -16,6 +16,8 @@ const MIN_WHEEL_STEP = 0.05;
 const MAX_WHEEL_STEP = 10;
 /** Desktop pixels one wheel detent stands for. */
 const PIXELS_PER_DETENT = 120;
+/** The closest the picture can be zoomed: view points per desktop pixel. */
+const MAX_SCALE = 2.5;
 /** Where the cursor mark's tip sits inside the mark, in points. */
 const CURSOR_HOTSPOT = 3;
 
@@ -62,13 +64,18 @@ function loadRTCView(): React.ComponentType<Record<string, unknown>> | null {
     }
 }
 
-export function DesktopView({ sessionId, style, placeholder, accessibilityLabel, keyboardClearance = 0, gestures = 'desktop' }: DesktopViewProps) {
+/** An offset that the edge clamp turns into the desktop's top-left corner. */
+const TOP_LEFT: Point = { x: Infinity, y: Infinity };
+
+export function DesktopView({ sessionId, style, placeholder, accessibilityLabel, keyboardClearance = 0, insets, gestures = 'desktop' }: DesktopViewProps) {
     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);
-    const [zoom, setZoom] = React.useState(1);
-    const [offset, setOffset] = React.useState<Point>({ x: 0, y: 0 });
+    /** 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. */
+    const [offset, setOffset] = React.useState<Point>(TOP_LEFT);
     const [cursor, setCursor] = React.useState<Point | null>(null);
     const [keyboardText, setKeyboardText] = React.useState('');
     const keyboardTextRef = React.useRef('');
@@ -123,13 +130,28 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
         });
     }, [sessionId]);
 
-    const visibleHeight = Math.max(1, bounds.height - (keyboardHeight ? keyboardHeight + keyboardClearance : 0));
-    const fit = size.width && size.height ? Math.min(bounds.width / size.width, visibleHeight / size.height) : 1;
-    const scale = fit * zoom;
+    // The uncovered part of the view: inside what the system covers, and above the keyboard.
+    const top = insets?.top ?? 0;
+    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 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
+        ? 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;
+    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.
+    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]);
     const pictureWidth = size.width * scale;
     const pictureHeight = size.height * scale;
-    const originX = (bounds.width - pictureWidth) / 2 + offset.x;
-    const originY = (visibleHeight - pictureHeight) / 2 + offset.y;
     const point = (x: number, y: number, clamp = false): Point | null => {
         if (!size.width || !size.height || !scale) return null;
         const px = Math.floor((x - originX) / scale);
@@ -139,10 +161,14 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
     };
     /** Hold the offset to the picture's edges at a zoom level. */
     const clampOffset = (x: number, y: number, atScale: number = scale): Point => {
-        const maxX = Math.max(0, (size.width * atScale - bounds.width) / 2);
+        const maxX = Math.max(0, (size.width * atScale - safeWidth) / 2);
         const maxY = Math.max(0, (size.height * atScale - visibleHeight) / 2);
         return { x: Math.max(-maxX, Math.min(maxX, x)), y: Math.max(-maxY, Math.min(maxY, y)) };
     };
+    // A rotation or the keyboard can leave the offset past the picture's new edges.
+    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;
     const send = (control: Record<string, unknown>) => { if (sessionId) nativeDesklink.sendControl(sessionId, JSON.stringify(control)); };
     const flushWheel = (force: boolean) => {
         const { x, y } = wheel.current;
@@ -186,7 +212,7 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
         // second one, and one finger alone is ignored. A zoomed picture pans
         // from anywhere, clamped to its edges.
         const onPicture = point(at.x, at.y) !== null;
-        gesture.current = { stamp, start: at, last: at, time: Date.now(), mode: onPicture || zoom > 1 ? 'pending' : 'letterbox', span: 0, focus: at };
+        gesture.current = { stamp, start: at, last: at, time: Date.now(), mode: onPicture || zoomed > 1.001 ? 'pending' : 'letterbox', span: 0, focus: at };
         stopTimer();
         longPress.current = setTimeout(() => {
             if (gesture.current?.mode === 'pending' && point(at.x, at.y)) gesture.current.mode = 'armed';
@@ -223,16 +249,16 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
                 }
             }
             if (g.mode === 'pinch' && g.span) {
-                const maxZoom = fit > 0 ? 2.5 / fit : 2.5;
-                const next = Math.max(1, Math.min(maxZoom, zoom * distance / g.span));
-                const applied = zoom > 0 ? next / zoom : 1;
+                const maxZoom = fit > 0 ? Math.max(1, MAX_SCALE / fit) : MAX_SCALE;
+                const next = Math.max(1, Math.min(maxZoom, zoomed * distance / g.span));
+                const applied = zoomed > 0 ? next / zoomed : 1;
                 // The desktop point under the focus stays under it while the
                 // offset follows the fingers, then everything clamps back.
                 const nextScale = fit * next;
-                const ox = (bounds.width - size.width * scale) / 2 + offset.x;
-                const oy = (visibleHeight - size.height * scale) / 2 + offset.y;
-                const baseX = (bounds.width - size.width * nextScale) / 2;
-                const baseY = (visibleHeight - size.height * nextScale) / 2;
+                const ox = originX;
+                const oy = originY;
+                const baseX = left + (safeWidth - size.width * nextScale) / 2;
+                const baseY = top + (visibleHeight - size.height * nextScale) / 2;
                 setZoom(next);
                 setOffset(clampOffset(
                     center.x - (center.x - ox) * applied - baseX + (center.x - g.focus.x),
@@ -245,7 +271,10 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
                 wheel.current.y += -(center.y - g.focus.y) / scale / PIXELS_PER_DETENT;
                 flushWheel(false);
             }
-            g.span = distance; g.focus = center; g.last = center;
+            // Undecided, the spread is measured from where the fingers landed:
+            // a slow pinch crosses the slop over many small moves.
+            if (g.mode !== 'two') g.span = distance;
+            g.focus = center; g.last = center;
             return;
         }
         if (touches.length !== 1 || g.mode === 'spent' || g.mode === 'letterbox' || g.mode === 'two' || g.mode === 'pinch' || (g.mode === 'scroll' && gestures !== 'browser')) return;
@@ -258,7 +287,7 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
                 g.mode = 'scroll';
                 const under = point(at.x, at.y);
                 if (under) pointer('move', under);
-            } else g.mode = zoom > 1 ? 'pan' : 'hover';
+            } else g.mode = zoom === null || zoomed > 1.001 ? 'pan' : 'hover';
         }
         if (g.mode === 'scroll') {
             // Content follows the finger: moving it up scrolls the page down.
@@ -271,7 +300,7 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
         if (g.mode === 'pan') {
             const dx = at.x - g.last.x;
             const dy = at.y - g.last.y;
-            setOffset((current) => clampOffset(current.x + dx, current.y + dy));
+            setOffset((current) => { const from = clampOffset(current.x, current.y); return clampOffset(from.x + dx, from.y + dy); });
         }
         if (g.mode === 'armed' && Math.hypot(at.x - g.start.x, at.y - g.start.y) > 8) {
             const from = point(g.start.x, g.start.y, true);

package/src/DesktopView.tsx

@@ -5,6 +5,9 @@ import { StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
 import { desktopAvailable } from './native';
 import type { GestureProfile } from './protocol';
 
+/** Room at each edge of the view, in points; a missing edge is 0. */
+export type EdgeInsets = { top?: number; left?: number; bottom?: number; right?: number };
+
 export interface DesktopViewProps {
     /** The session handle from `useDesktopSession`. */
     sessionId: string | null;
@@ -19,6 +22,14 @@ export interface DesktopViewProps {
      * following the keyboard as it moves.
      */
     keyboardClearance?: number;
+    /**
+     * What the system covers at each edge of the view — status and navigation
+     * bars, a camera cutout, the home indicator — in points, as a safe-area
+     * library reports it. The picture still reaches under these edges, but it
+     * starts and pans inside them: its top-left corner first shows just inside,
+     * and every edge of the desktop can be brought into the uncovered part.
+     */
+    insets?: EdgeInsets;
     /**
      * Which touch meaning the surface uses: a desktop pointer, a browser page
      * (one finger scrolls), or a device screen (one finger presses and drags).
@@ -32,6 +43,8 @@ interface NativeSurfaceProps {
     accessible?: boolean;
     accessibilityLabel?: string;
     keyboardClearance?: number;
+    /** `insets` as top, left, bottom, right. */
+    insets?: number[];
     gestures?: GestureProfile;
 }
 
@@ -49,7 +62,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, gestures = 'desktop' }: DesktopViewProps) {
+export function DesktopView({ sessionId, style, placeholder, accessibilityLabel, keyboardClearance = 0, insets, gestures = 'desktop' }: DesktopViewProps) {
     if (NativeSurface == null || sessionId == null) {
         return (
             <View style={[styles.surface, style]}>
@@ -57,7 +70,8 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
             </View>
         );
     }
-    return <NativeSurface style={[styles.surface, style]} sessionId={sessionId} accessible={accessibilityLabel !== undefined} accessibilityLabel={accessibilityLabel} keyboardClearance={keyboardClearance} gestures={gestures} />;
+    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} />;
 }
 
 const styles = StyleSheet.create({

package/src/DesktopView.web.tsx

@@ -3,6 +3,9 @@ import { StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
 
 import type { GestureProfile } from './protocol';
 
+/** Room at each edge of the view, in points; a missing edge is 0. */
+export type EdgeInsets = { top?: number; left?: number; bottom?: number; right?: number };
+
 export interface DesktopViewProps {
     /** The session handle from `useDesktopSession`. */
     sessionId: string | null;
@@ -16,6 +19,15 @@ export interface DesktopViewProps {
      * controls, in points. While the keyboard is up the picture sits above both.
      */
     keyboardClearance?: number;
+    /**
+     * What the system covers at each edge of the view — status and navigation
+     * bars, a camera cutout, the home indicator — in points, as a safe-area
+     * library reports it. The picture still reaches under these edges, but it
+     * starts and pans inside them: its top-left corner first shows just inside,
+     * and every edge of the desktop can be brought into the uncovered part.
+     */
+    /** The browser surface fits its own box and ignores this. */
+    insets?: EdgeInsets;
     /**
      * Which touch meaning the surface uses: a desktop pointer, a browser page
      * (one finger scrolls), or a device screen (one finger presses and drags).

package/src/index.ts

@@ -10,7 +10,7 @@ export * from './protocol';
  */
 export type { NativeDesklinkModule, NativeSessionEvent } from './native';
 export { desktopAvailable } from './availability';
-export { DesktopView, type DesktopViewProps } from './DesktopView';
+export { DesktopView, type DesktopViewProps, type EdgeInsets } from './DesktopView';
 export { observeWebKeyboardMotion } from './webKeyboardMotion';
 export type { StickyModifier, StickyModifiers, StickyState } from './stickyModifiers';
 export {

package/src/native.ios.ts

@@ -1,6 +1,7 @@
 import type { MediaStream, RTCPeerConnection } from 'react-native-webrtc';
 import type { NativeDesklinkModule, NativeSessionEvent } from './native';
 import { requireWebRTC } from './webrtc.ios';
+import { videoStats } from './videoStats';
 
 /** The WebRTC stack, loaded the first time a session opens rather than with this module. */
 function loadWebRTC(): { RTCPeerConnection: new (config: unknown) => RTCPeerConnection; MediaStream: new () => MediaStream } | null {
@@ -99,6 +100,10 @@ function failure(id: string, error: unknown) {
 }
 
 export const nativeDesklink: NativeDesklinkModule = {
+    async getStats(id) {
+        const session = sessions.get(id);
+        return session ? videoStats(await session.peer.getStats()) : '[]';
+    },
     createSession(iceServersJson) {
         const id = `desklink-${++nextId}`;
         try {

package/src/native.ts

@@ -45,6 +45,8 @@ export interface NativeDesklinkModule {
     /** Hold the screen in landscape while the desktop is shown, or follow the phone again. */
     setOrientation(mode: 'landscape' | 'auto'): boolean;
     closeSession(id: string): boolean;
+    /** Video reception and codec statistics, excluding network addresses and credentials. */
+    getStats?(id: string): Promise<string>;
     isAvailable(): boolean;
     addListener?(name: 'onSessionEvent', handler: (event: NativeSessionEvent) => void): { remove: () => void };
 }
@@ -57,4 +59,3 @@ export const nativeDesklink: NativeDesklinkModule | null = native;
 
 /** True when this build can show a live desktop surface at all. */
 export const desktopAvailable = native !== null;
-

package/src/native.web.ts

@@ -1,4 +1,5 @@
 import type { NativeDesklinkModule, NativeEventName, NativeSessionEvent } from './native';
+import { videoStats } from './videoStats';
 import type { GestureProfile } from './protocol';
 import { observeWebKeyboardMotion } from './webKeyboardMotion';
 
@@ -898,6 +899,10 @@ const sequence = new Map<string, number>();
 export const desktopAvailable = true;
 
 export const nativeDesklink: NativeDesklinkModule = {
+    async getStats(id) {
+        const session = sessions.get(id);
+        return session ? videoStats(await session.peer.getStats()) : '[]';
+    },
     isAvailable: () => true,
 
     createSession(iceServersJson: string): string | null {

package/src/protocol.ts

@@ -16,6 +16,11 @@
 
 export const PROTOCOL_VERSION = 3;
 
+/**
+ * @deprecated Pairing is the only trust boundary: a paired session always has
+ * view, input and clipboard, so there is nothing to ask for. Kept so 0.3 code
+ * compiles; removed at 1.0.
+ */
 export type Permission = 'view' | 'control' | 'clipboard';
 
 /**
@@ -42,7 +47,8 @@ export interface SurfaceGeometry {
 
 export interface SessionOpenRequest {
     cursor?: 'embedded' | 'hidden';
-    permissions: Permission[];
+    /** @deprecated Ignored: a paired session always has view, input and clipboard. */
+    permissions?: Permission[];
     maxWidth?: number;
     maxHeight?: number;
     bitrateKbps?: number;
@@ -127,6 +133,7 @@ export type SessionStatus =
     | 'failed';
 
 export type SessionFailure =
+    /** The app's `authorize()` refused, or the host did: not paired, or the pairing was revoked. */
     | { code: 'permission'; message: string }
     /** Nobody approved the desktop's own screen-sharing prompt in time. */
     | { code: 'consent'; message: string }
@@ -146,6 +153,12 @@ export interface SessionSnapshot {
     geometry: SurfaceGeometry | null;
     /** True once an authorized, current-generation frame has actually rendered. */
     presented: boolean;
+    /**
+     * `message` is free text from the app's `authorize()`, the host or the
+     * engine and may contain a bridge URL or pairing token. Never display it
+     * to people; redact sensitive data before logging it. Choose user-facing
+     * text from the session state and `code` instead.
+     */
     failure: SessionFailure | null;
     /** Redacted diagnostics: codec, route, counters. Never identities. */
     diagnostics: Record<string, string | number | boolean>;

package/src/useDesktopSession.ts

@@ -172,10 +172,10 @@ async function loadPlatform(): Promise<boolean> {
 
 export interface DesktopSessionOptions {
     /**
-     * Ask the owning application for a fresh, short-lived authorization and the
-     * authenticated channel to the host engine. Called for the first connection
-     * and again for a reconnect: the package never reuses authority it was not
-     * granted again.
+     * The app's pairing check: return the authenticated channel to the host
+     * engine of a paired computer, or throw. Pairing is the only trust
+     * boundary, so a paired session has view, input and clipboard. Called again
+     * on every reconnect, so a revoked pairing cannot reopen.
      */
     authorize: () => Promise<{ signaling: Signaling; session: SessionOpenRequest }>;
     onStateChange?: (snapshot: SessionSnapshot) => void;
@@ -191,6 +191,8 @@ export interface DesktopSessionOptions {
 
 export interface DesktopSession {
     snapshot: SessionSnapshot;
+    /** Video reception and codec diagnostics, without network addresses. */
+    getStats: () => Promise<Array<Record<string, unknown>>>;
     /** The native session handle, or null when nothing is open. */
     nativeId: string | null;
     connect: () => Promise<void>;
@@ -556,6 +558,12 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         if (id != null) nativeDesklink?.hideKeyboard(id);
     }, []);
 
+    const getStats = useCallback(async (): Promise<Array<Record<string, unknown>>> => {
+        const id = nativeRef.current;
+        if (id == null || !nativeDesklink?.getStats) return [];
+        return JSON.parse(await nativeDesklink.getStats(id));
+    }, []);
+
     const fitToView = useCallback(() => {
         const id = nativeRef.current;
         if (id != null) nativeDesklink?.fitToView(id);
@@ -717,7 +725,10 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         let openedResult: SessionOpenResult;
         try {
             openedResult = await authorization.signaling.request<SessionOpenResult>('session.open', {
-                permissions: authorization.session.permissions,
+                // Ignored by 0.4+ engines, whatever the app asked for. A 0.3
+                // engine refuses an open without `view`, so the full set stays
+                // on the wire until 0.3 hosts leave support.
+                permissions: ['view', 'control', 'clipboard'],
                 max_width: authorization.session.maxWidth,
                 ...(authorization.session.cursor === undefined ? {} : { cursor: authorization.session.cursor }),
                 max_height: authorization.session.maxHeight,
@@ -1069,6 +1080,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         releaseHeld,
         setInputEnabled,
         fitToView,
+        getStats,
         setOrientation,
         send,
         modifiers,
@@ -1086,6 +1098,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         releaseHeld,
         setInputEnabled,
         fitToView,
+        getStats,
         setOrientation,
         send,
         modifiers,
@@ -1106,5 +1119,5 @@ function randomId(): string {
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
 
-/** The permissions a normal remote-control session asks for. */
+/** @deprecated Ignored: a paired session always has view, input and clipboard. Removed at 1.0. */
 export const CONTROL_PERMISSIONS: Permission[] = ['view', 'control', 'clipboard'];

package/src/videoStats.ts

@@ -0,0 +1,16 @@
+/** Keep receiver diagnostics useful without disclosing ICE addresses or credentials. */
+export function videoStats(report: { forEach(callback: (stat: Record<string, unknown>) => void): void }): string {
+    const fields = new Set([
+        'id', 'type', 'timestamp', 'kind', 'mediaType', 'codecId', 'mimeType', 'clockRate', 'payloadType',
+        'packetsReceived', 'packetsLost', 'bytesReceived', 'framesReceived', 'framesDecoded',
+        'keyFramesDecoded', 'framesDropped', 'framesPerSecond', 'frameWidth', 'frameHeight',
+        'nackCount', 'pliCount', 'firCount', 'totalDecodeTime', 'decoderImplementation', 'jitterBufferDelay',
+    ]);
+    const stats: Array<Record<string, unknown>> = [];
+    report.forEach((stat) => {
+        if (stat.type === 'inbound-rtp' || stat.type === 'codec') {
+            stats.push(Object.fromEntries(Object.entries(stat).filter(([key]) => fields.has(key))));
+        }
+    });
+    return JSON.stringify(stats);
+}