@desklink/react-native 0.4.0 → 0.5.1

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).
@@ -144,11 +266,29 @@ describe('DesktopView.ios parity with DesktopView.kt', () => {
         expect(sent.filter((message) => message.kind === 'pointer' && message.phase === 'move')).not.toEqual([]);
     });
 
+    it('carries a one-finger drag from the moment the picture exists, in portrait', async () => {
+        // The state a session starts in: the picture at its default fill, before
+        // anything has been zoomed. In portrait that fill is the fit, so the
+        // picture has nowhere to pan to and the finger belongs to the desktop.
+        const { sent, rtcStyle, grant, move, release } = await openView({ whole: false });
+        const before = rtcStyle();
+        grant([touch(100, 100)]);
+        move([touch(160, 120)]);
+        move([touch(220, 140)]);
+        release();
+        const moves = sent.filter((message) => message.kind === 'pointer' && message.phase === 'move');
+        expect(moves).toHaveLength(2);
+        expect(moves[1].x).toBeGreaterThan(moves[0].x);
+        expect(moves[1].y).toBeGreaterThan(moves[0].y);
+        expect(rtcStyle()).toEqual(before);
+    });
+
     it('zooms around the pinch focus and re-clamps after zooming out', async () => {
         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 +502,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', onPictureFrame }: DesktopViewProps) {
     const [revision, refresh] = React.useReducer((n: number) => n + 1, 0);
     const [bounds, setBounds] = React.useState({ width: 0, height: 0 });
     const [size, setSize] = React.useState(() => getDesktopSize(sessionId) ?? { width: 0, height: 0 });
     const [keyboardHeight, setKeyboardHeight] = React.useState(0);
-    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,24 @@ 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;
+    // An application's controls can sit under the picture instead of over it,
+    // so it needs to know where the picture ended. Reported only when the
+    // picture moved: the callback sets state, and a fresh callback each render
+    // would otherwise loop.
+    const frame = React.useRef({ top: -1, height: -1 });
+    React.useEffect(() => {
+        if (frame.current.top === originY && frame.current.height === pictureHeight) return;
+        frame.current = { top: originY, height: pictureHeight };
+        onPictureFrame?.(frame.current);
+    }, [onPictureFrame, originY, pictureHeight]);
     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 +222,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 +259,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 +281,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 +297,13 @@ 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 {
+                // A whole desktop has nowhere to move to, so the finger moves the
+                // desktop's pointer instead. It is the zoom over the fit, not the
+                // default fill, that says there is room to pan: a fill that landed
+                // on the fit has none.
+                g.mode = zoomed > 1.001 ? 'pan' : 'hover';
+            }
         }
         if (g.mode === 'scroll') {
             // Content follows the finger: moving it up scrolls the page down.
@@ -271,7 +316,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,11 +22,26 @@ 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).
      */
     gestures?: GestureProfile;
+    /**
+     * Where the picture ended, in the view's own points, whenever it moves.
+     * A wide desktop on a tall screen leaves a band under the picture; this is
+     * how an application lays its own controls into that band instead of
+     * guessing the desktop's aspect.
+     */
+    onPictureFrame?: (frame: { top: number; height: number }) => void;
 }
 
 interface NativeSurfaceProps {
@@ -32,6 +50,8 @@ interface NativeSurfaceProps {
     accessible?: boolean;
     accessibilityLabel?: string;
     keyboardClearance?: number;
+    /** `insets` as top, left, bottom, right. */
+    insets?: number[];
     gestures?: GestureProfile;
 }
 
@@ -49,7 +69,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 +77,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/ModifierKeys.tsx

@@ -0,0 +1,77 @@
+import * as React from 'react';
+import { Pressable, StyleSheet, Text, View, type StyleProp, type ViewStyle } from 'react-native';
+
+import type { StickyModifier, StickyModifiers, StickyState } from './stickyModifiers';
+
+export interface ModifierKeysProps {
+    /** The session's `modifiers`. */
+    modifiers: StickyModifiers;
+    /** The session's `tapModifier`. */
+    onTap: (name: StickyModifier) => void;
+    style?: StyleProp<ViewStyle>;
+    /**
+     * Tablet targets: the keys share the width and take the height the row is
+     * given, instead of sitting at 44 pt in a row of a phone's. A row shorter
+     * than the keys' minimum keeps the minimum.
+     */
+    grow?: boolean;
+}
+
+const LABELS: Record<StickyModifier, string> = { Control: 'Ctrl', Shift: 'Shift', Alt: 'Alt', Meta: 'Meta' };
+/** What a screen reader says for each state; "once" is the latch the user sees. */
+export const STATE_NAMES: Record<StickyState, string> = { off: 'off', once: 'latched', lock: 'locked' };
+
+/**
+ * The sticky modifier keys as a row the user can read at a glance.
+ *
+ * Off is an outlined dark key, latched is a filled key, and locked is a
+ * filled key with a white rim and a bar under its label, so the three differ
+ * in shape as well as colour. The row carries its own backing, so it reads
+ * the same over a light desktop as over a dark one.
+ */
+export function ModifierKeys({ modifiers, onTap, style, grow }: ModifierKeysProps) {
+    return (
+        <View style={[styles.row, grow && styles.grown, style]}>
+            {(['Control', 'Shift', 'Alt', 'Meta'] as const).map((name) => {
+                const state = modifiers[name];
+                return (
+                    <Pressable
+                        key={name}
+                        testID={`desklink-key-${name}`}
+                        accessibilityRole="button"
+                        accessibilityLabel={LABELS[name]}
+                        accessibilityState={{ selected: state !== 'off' }}
+                        accessibilityValue={{ text: STATE_NAMES[state] }}
+                        onPress={() => onTap(name)}
+                        style={[styles.key, grow && styles.keyGrown, state === 'off' ? styles.off : styles.on, state === 'lock' && styles.lock]}
+                    >
+                        <Text style={state === 'off' ? styles.offLabel : styles.onLabel}>{LABELS[name]}</Text>
+                        <View style={[styles.bar, state === 'lock' && styles.barShown]} />
+                    </Pressable>
+                );
+            })}
+        </View>
+    );
+}
+
+export const KEY_COLORS = {
+    backing: 'rgba(22, 23, 26, 0.94)',
+    off: '#2b2d33',
+    offLabel: '#c9ccd3',
+    on: '#2563eb',
+    onLabel: '#ffffff',
+};
+
+const styles = StyleSheet.create({
+    row: { flexDirection: 'row', flexWrap: 'wrap', gap: 8, padding: 8, backgroundColor: KEY_COLORS.backing },
+    grown: { width: '100%', flexGrow: 1, maxHeight: 160 },
+    key: { minWidth: 56, maxWidth: '100%', minHeight: 44, paddingHorizontal: 12, borderRadius: 8, borderWidth: 2, alignItems: 'center', justifyContent: 'center' },
+    keyGrown: { flexGrow: 1, minHeight: 96, paddingHorizontal: 24 },
+    off: { backgroundColor: KEY_COLORS.off, borderColor: '#4b4e57' },
+    on: { backgroundColor: KEY_COLORS.on, borderColor: KEY_COLORS.on },
+    lock: { borderColor: '#ffffff' },
+    offLabel: { color: KEY_COLORS.offLabel, fontSize: 15, fontWeight: '500' },
+    onLabel: { color: KEY_COLORS.onLabel, fontSize: 15, fontWeight: '700' },
+    bar: { marginTop: 3, width: 18, height: 3, borderRadius: 2, backgroundColor: 'transparent' },
+    barShown: { backgroundColor: '#ffffff' },
+});