@desklink/react-native 0.4.0 → 0.5.0

package/README.md

@@ -76,6 +76,8 @@ 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
@@ -127,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,
@@ -148,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:
@@ -283,11 +293,12 @@ 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. Its status line shows plain messages: `Connected`
+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.
@@ -327,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.4.0",
+    "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/useDesktopSession.ts

@@ -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);
@@ -1072,6 +1080,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         releaseHeld,
         setInputEnabled,
         fitToView,
+        getStats,
         setOrientation,
         send,
         modifiers,
@@ -1089,6 +1098,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         releaseHeld,
         setInputEnabled,
         fitToView,
+        getStats,
         setOrientation,
         send,
         modifiers,

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);
+}