@desklink/react-native 0.5.0 → 0.5.1

package/README.md

@@ -30,6 +30,9 @@ repository it resolves through the workspace; anywhere else, install it from npm
 npx expo install @desklink/react-native      # or yarn add, then prebuild/rebuild
 ```
 
+Expo SDK 55 and later are supported, including the SDK a fresh
+`npx create-expo-app` resolves today: no SDK pin is needed.
+
 Android uses an Expo native module; iOS uses the app's existing
 `react-native-webrtc` peer connection and `RTCView` from JavaScript, plus a small
 Expo module of its own for the hardware keyboard and an iPad pointer. Both need a
@@ -59,6 +62,7 @@ changes, and trackpad presses reach the desktop as touches.
 
 ```tsx
 import { DesktopView, useDesktopSession } from '@desklink/react-native';
+import * as Clipboard from 'expo-clipboard';
 
 const desktop = useDesktopSession({
     authorize: async () => ({
@@ -75,6 +79,9 @@ await desktop.connect();
 desktop.setInputEnabled(true);
 desktop.showKeyboard();
 desktop.setOrientation('landscape');   // Android only; iOS apps configure supported orientations themselves
+await desktop.copyRemoteToLocal(async (text) => {
+    if (!await Clipboard.setStringAsync(text)) throw new Error('Clipboard write refused');
+});
 await desktop.pasteLocalToRemote(await Clipboard.getStringAsync());
 // Optional receiver evidence: codec, decoder and video counters; no ICE addresses.
 const stats = await desktop.getStats();
@@ -135,7 +142,9 @@ heat and battery.
   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
+  and beside a camera cutout. `onPictureFrame` reports where the picture
+  ended whenever it moves, so a tall screen's band below it can carry the
+  application's own controls instead of empty space. 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
@@ -191,7 +200,15 @@ heat and battery.
 - **The keys a phone lacks.** `modifiers`, `tapModifier` and `pressKey` give
   sticky Ctrl and Shift: tap arms one for the next key, tap again locks it.
   While one is armed, the next key or character the phone's keyboard types is
-  sent as that key's chord, so Ctrl then v is Ctrl+V. The app draws the keys.
+  sent as that key's chord, so Ctrl then v is Ctrl+V. `modifiers` holds each
+  key's state (`off`, `once` for latched, `lock`) for the app to read.
+  `<ModifierKeys modifiers={desktop.modifiers} onTap={desktop.tapModifier} />`
+  draws them as a backed key row: off is an outlined key, latched a filled
+  one, locked a filled one with a white rim and a bar under its label, and a
+  screen reader hears off, latched or locked. Its `grow` prop makes it a
+  tablet's row: the keys take the width and the height the row is given
+  instead of sitting at 44 pt. An app may draw its own keys
+  from `modifiers` instead.
 - **Readiness is a rendered frame.** Android marks the first draw; iOS marks
   the first `RTCView` video-dimensions callback and ignores later ones, so a
   resize or remount during a reconnect does not read as live. Neither marks
@@ -240,6 +257,15 @@ heat and battery.
   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
   enabled. The package never polls the clipboard or uses it as a way to type.
+  `copyRemoteToLocal(writeLocal)` awaits the caller-owned local writer, which
+  must reject on failure or refusal, before recording completion. The returned
+  text and truncation flag describe what was written. `pasteLocalToRemote(text)`
+  records completion only after the desktop acknowledges the write.
+  `clipboard` is the last transfer that completed, and
+  `<ClipboardConfirmation transfer={desktop.clipboard} />` confirms each one
+  with a backed pill — where it went and the start of the text —
+  that ignores touches and leaves after 1.5 s. Place it in a reserved area
+  outside `DesktopView`, keeping that area present when the pill is dismissed.
 
 ### `Signaling`
 
@@ -308,28 +334,44 @@ 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
 are written out), that a tap clicks the host, that
 the picture keeps following the desktop afterwards, and that hardware keys
-pressed on the simulator reach the desktop. With `DESKLINK_IOS_IPAD=1` it runs on
+pressed on the simulator reach the desktop. It then drives the whole
+**phone-only control** journey from the phone's own screen, with no input sent
+to the desktop from this machine: a click, a drag that holds the button and
+selects, a two-finger scroll, typed text, a sticky modifier that chords the next
+key and clears, the clipboard in both directions, and the drawn pointer mark's
+shape and tip. Every step has its own capture, the journey is recorded as one
+screen recording on the simulator, and the phone's own screen is read to prove it
+carries no diagnostic text.
+With `DESKLINK_IOS_IPAD=1` it runs on
 an iPad simulator and also drives a trackpad through XCUITest
 (`test/ios-pointer/`): hover, a click-drag that selects text, a right click and
 a scroll:
 
 ```sh
 npm run build && cargo build --manifest-path packages/desktop-host/engine/Cargo.toml
-env -u DISPLAY -u WAYLAND_DISPLAY DESKLINK_IOS_MAC=user@mac npm run test:ios --workspace @desklink/react-native
+env -u DISPLAY -u WAYLAND_DISPLAY DESKLINK_IOS_MAC=user@mac \
+  DESKLINK_IOS_DEVICE='fm-iPhone 17 Pro' npm run test:ios --workspace @desklink/react-native
 ```
 
 The Mac needs Xcode with an iOS simulator runtime, CocoaPods, node and
 [`axe`](https://github.com/cameroncooke/AXe) on its login `PATH`; everything
 the run builds or caches stays in `~/desklink-ios` there. The run creates a
-uniquely named simulator and deletes it during cleanup. For host desktop isolation, see the
+uniquely named simulator and deletes it during cleanup. Set
+`DESKLINK_IOS_DEVICE` to the name or udid of one of the Mac's own simulators to
+run on that instead and leave it in place. For host desktop isolation, see the
 [private-lab guidance](../../README.md#develop). When the selected
 Xcode has no simulator platform, point `DESKLINK_IOS_XCODE` at one that does;
 `DESKLINK_IOS_RUNTIME` picks the iOS version (for example `18.6`); the
 script's header lists the other settings. To capture the cursor tip proof, set
 `DESKLINK_IOS_POINTER_PROOF=before` or `after`; the run writes a 4x crop, device
 frame, proof metadata, and host click log under `DESKLINK_IOS_OUT`. Set
-`DESKLINK_IOS_APP` to reuse an app bundle under `DESKLINK_IOS_DIR` when running
-with `DESKLINK_IOS_SKIP_BUILD=1`. Run once with `before` before the change and
+`DESKLINK_IOS_APP` to reuse an app bundle under the lane's directory when
+running with `DESKLINK_IOS_SKIP_BUILD=1`. `DESKLINK_IOS_DIR` is the shared Mac
+lab root (`fm-desklink-ios`) and `DESKLINK_IOS_LANE` names this lane's own
+subdirectory within it; the run deletes that subdirectory and nothing else when
+it finishes, so two lanes can build at once without one cleanup deleting the
+other's build. Set `DESKLINK_IOS_KEEP=1` to keep it. Run once with `before`
+before the change and
 once with `after` after it, on both iPhone and iPad simulators, to compare the
 pointer crop and verify the host click is within two desktop pixels of the tip.
 To try the example by hand against any bridge:
@@ -344,7 +386,9 @@ link whose `url` query parameter is the URL-encoded bridge WebSocket address:
 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`.
+available as `desklink-status`. The key row (`Ctrl`, `Shift`, `Alt`, `Meta`) and
+the `Copy` and `Paste` buttons are the app's own chrome over the picture, and a
+clipboard transfer is confirmed by a pill above them.
 
 For device evidence, an optional `report` query parameter accepts a URL-encoded
 HTTP endpoint. While live, the example posts receiver statistics and connection

package/android/build.gradle

@@ -1,9 +1,21 @@
 apply plugin: 'com.android.library'
-apply plugin: 'kotlin-android'
+// expo-modules-core's own Kotlin API is reified through the `pika` compiler
+// plugin, and this plugin is what applies it. Building with a bare
+// `kotlin-android` leaves those reified calls un-inlined, and the app then
+// throws "This function has a reified type parameter ..." out of
+// DesklinkModule.definition() on startup. Expo's plugin covers every SDK, and
+// applies kotlin-android and the default Expo module dependencies itself.
+apply plugin: 'expo-module-gradle-plugin'
 
 group = 'expo.modules.desklink'
 version = '0.1.1'
 
+// This package ships from npm, not from Expo's Maven repository, so the
+// plugin's publishing task has nothing to publish.
+expoModule {
+  canBePublished = false
+}
+
 android {
   namespace 'expo.modules.desklink'
   compileSdk rootProject.ext.has('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36

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

@@ -681,8 +681,10 @@ class DesktopView(context: Context, appContext: AppContext) : ExpoView(context,
             return true
           }
           // The whole desktop has nowhere to move to, so the finger moves the
-          // desktop's pointer instead, without a button.
-          gesture = if (filling || !fitted) Gesture.PAN else if (downOnPicture) Gesture.HOVER else Gesture.LETTERBOX
+          // desktop's pointer instead, without a button. A fill that landed on
+          // the fit scale has nowhere to move to either, portrait most of all,
+          // and it is `fitted`, not the fill, that says there is room.
+          gesture = if (!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.5.0",
+    "version": "0.5.1",
     "license": "Apache-2.0",
     "description": "Render and drive a desktop session from a React Native app",
     "main": "index.ts",

package/src/ClipboardConfirmation.tsx

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import { StyleSheet, Text, View, type StyleProp, type ViewStyle } from 'react-native';
+
+import type { ClipboardTransfer } from './useDesktopSession';
+
+export interface ClipboardConfirmationProps {
+    /** The session's `clipboard`. */
+    transfer: ClipboardTransfer | null;
+    style?: StyleProp<ViewStyle>;
+}
+
+/** How long a confirmation stays up. */
+export const CLIPBOARD_CONFIRMATION_MS = 1500;
+const PREVIEW_CHARS = 24;
+
+/**
+ * A short pill confirming each clipboard transfer: where it went and the start
+ * of the text. Place it in reserved space outside the desktop
+ * surface. It ignores touches and goes away on its own.
+ */
+export function ClipboardConfirmation({ transfer, style }: ClipboardConfirmationProps) {
+    const [shown, setShown] = React.useState<ClipboardTransfer | null>(null);
+    const seenId = React.useRef<number | null>(transfer?.id ?? null);
+    React.useEffect(() => {
+        if (transfer == null) return;
+        if (transfer.id === seenId.current) return;
+        seenId.current = transfer.id;
+        setShown(transfer);
+        const timer = setTimeout(() => setShown(null), CLIPBOARD_CONFIRMATION_MS);
+        return () => clearTimeout(timer);
+    }, [transfer?.id]);
+    if (shown == null) return null;
+    return (
+        <View pointerEvents="none" style={[styles.place, style]}>
+            <View testID="desklink-clipboard" accessibilityLiveRegion="polite" style={styles.pill}>
+                <Text numberOfLines={1} style={styles.text}>{describeTransfer(shown)}</Text>
+            </View>
+        </View>
+    );
+}
+
+/** "Copied to phone · “first words…”" */
+export function describeTransfer({ direction, text }: ClipboardTransfer): string {
+    const where = direction === 'to-phone' ? 'Copied to phone' : 'Sent to desktop';
+    const flat = text.replace(/\s+/g, ' ').trim();
+    const chars = [...flat];
+    const preview = chars.length > PREVIEW_CHARS ? `${chars.slice(0, PREVIEW_CHARS).join('')}…` : flat;
+    return preview === '' ? `${where}` : `${where} · “${preview}”`;
+}
+
+export const PILL_COLORS = { backing: 'rgba(17, 18, 20, 0.94)', text: '#ffffff' };
+
+const styles = StyleSheet.create({
+    place: { paddingHorizontal: 16, alignItems: 'center' },
+    pill: { maxWidth: '100%', paddingHorizontal: 14, paddingVertical: 8, borderRadius: 999, backgroundColor: PILL_COLORS.backing },
+    text: { color: PILL_COLORS.text, fontSize: 14, fontWeight: '600' },
+});

package/src/DesktopView.ios.spec.tsx

@@ -266,6 +266,23 @@ 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)]);

package/src/DesktopView.ios.tsx

@@ -67,7 +67,7 @@ function loadRTCView(): React.ComponentType<Record<string, unknown>> | null {
 /** 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) {
+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 });
@@ -169,6 +169,16 @@ export function DesktopView({ sessionId, style, placeholder, accessibilityLabel,
     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;
@@ -287,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 === null || zoomed > 1.001 ? '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.

package/src/DesktopView.tsx

@@ -35,6 +35,13 @@ export interface DesktopViewProps {
      * (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 {

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

package/src/controls.spec.tsx

@@ -0,0 +1,205 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import React from 'react';
+import TestRenderer, { act } from 'react-test-renderer';
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+/** The key row and the clipboard pill, rendered with `react-native` primitives as host strings. */
+vi.mock('react-native', () => ({
+    StyleSheet: { create: (styles: unknown) => styles, absoluteFill: {} },
+    Linking: { getInitialURL: async () => null, addEventListener: () => ({ remove: () => undefined }) },
+    Platform: { OS: 'ios' },
+    Pressable: 'Pressable',
+    ScrollView: 'ScrollView',
+    StatusBar: 'StatusBar',
+    Text: 'Text',
+    View: 'View',
+    Settings: { get: () => 'ws://localhost/desktop?token=test' },
+}));
+
+vi.mock('react-native-safe-area-context', () => ({
+    SafeAreaProvider: ({ children }: { children: React.ReactNode }) => children,
+    useSafeAreaInsets: () => ({ top: 0, left: 0, bottom: 0, right: 0 }),
+}));
+
+const example = vi.hoisted(() => ({
+    write: vi.fn(),
+    copy: vi.fn(),
+    connect: vi.fn(),
+}));
+vi.mock('expo-clipboard', () => ({ setStringAsync: example.write }));
+vi.mock('@desklink/react-native', async () => ({
+    CONTROL_PERMISSIONS: ['view', 'control', 'clipboard'],
+    ClipboardConfirmation: (await import('./ClipboardConfirmation')).ClipboardConfirmation,
+    ModifierKeys: (await import('./ModifierKeys')).ModifierKeys,
+    DesktopView: 'DesktopView',
+    useDesktopSession: () => ({
+        snapshot: { status: 'live' },
+        nativeId: 'example-session',
+        modifiers: { Control: 'off', Shift: 'off', Alt: 'off', Meta: 'off' },
+        clipboard: null,
+        connect: example.connect,
+        setInputEnabled: vi.fn(),
+        copyRemoteToLocal: example.copy,
+        tapModifier: vi.fn(),
+    }),
+}));
+
+import { KEY_COLORS, ModifierKeys } from './ModifierKeys';
+import { CLIPBOARD_CONFIRMATION_MS, ClipboardConfirmation, PILL_COLORS, describeTransfer } from './ClipboardConfirmation';
+import { NO_MODIFIERS } from './stickyModifiers';
+import type { ClipboardTransfer } from './useDesktopSession';
+import App from '../example/App';
+
+type Style = Record<string, unknown>;
+const flatten = (style: unknown): Style =>
+    Array.isArray(style) ? Object.assign({}, ...style.map(flatten)) : style ? (style as Style) : {};
+
+/** WCAG contrast of two colours, the first drawn with its alpha over `under`. */
+function contrast(top: string, bottom: string, under = '#000000'): number {
+    const rgba = (c: string) => {
+        const m = c.match(/rgba?\(([^)]+)\)/);
+        if (m) { const [r, g, b, a = 1] = m[1].split(',').map(Number); return [r, g, b, a]; }
+        return [1, 3, 5].map((i) => parseInt(c.slice(i, i + 2), 16)).concat(1);
+    };
+    const over = (c: string) => {
+        const [r, g, b, a] = rgba(c);
+        const [ur, ug, ub] = rgba(under);
+        return [r * a + ur * (1 - a), g * a + ug * (1 - a), b * a + ub * (1 - a)];
+    };
+    const lum = (rgb: number[]) => {
+        const [r, g, b] = rgb.map((v) => { const s = v / 255; return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; });
+        return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    };
+    const [l1, l2] = [lum(over(top)), lum(over(bottom))].sort((a, b) => b - a);
+    return (l1 + 0.05) / (l2 + 0.05);
+}
+
+describe('ModifierKeys', () => {
+    function render(modifiers = NO_MODIFIERS, onTap = vi.fn()) {
+        let tree!: TestRenderer.ReactTestRenderer;
+        act(() => { tree = TestRenderer.create(<ModifierKeys modifiers={modifiers} onTap={onTap} />); });
+        const key = (name: string) => tree.root.find((node) => node.props.testID === `desklink-key-${name}`);
+        return { key, onTap };
+    }
+
+    it('draws off, latched and locked as three different keys and names each state', () => {
+        const { key } = render({ Control: 'off', Shift: 'once', Alt: 'lock', Meta: 'off' });
+        const look = (name: string) => {
+            const node = key(name);
+            const [, bar] = node.props.children;
+            return { key: flatten(node.props.style), bar: flatten(bar.props.style), said: node.props.accessibilityValue.text };
+        };
+        const off = look('Control');
+        const latched = look('Shift');
+        const locked = look('Alt');
+        expect([off.said, latched.said, locked.said]).toEqual(['off', 'latched', 'locked']);
+        expect(off.key.backgroundColor).not.toBe(latched.key.backgroundColor);
+        // Latched and locked share a fill and differ in shape: the rim and the bar.
+        expect(locked.key.borderColor).not.toBe(latched.key.borderColor);
+        expect(locked.bar.backgroundColor).not.toBe(latched.bar.backgroundColor);
+        expect(key('Control').props.accessibilityState).toEqual({ selected: false });
+        expect(key('Shift').props.accessibilityState).toEqual({ selected: true });
+    });
+
+    it('hands a tap to the session', () => {
+        const { key, onTap } = render();
+        key('Control').props.onPress();
+        expect(onTap).toHaveBeenCalledWith('Control');
+    });
+
+    it('keeps every label at 4.5:1 or better', () => {
+        expect(contrast(KEY_COLORS.offLabel, KEY_COLORS.off)).toBeGreaterThanOrEqual(4.5);
+        expect(contrast(KEY_COLORS.onLabel, KEY_COLORS.on)).toBeGreaterThanOrEqual(4.5);
+    });
+});
+
+describe('ClipboardConfirmation', () => {
+    beforeEach(() => { vi.useFakeTimers(); });
+    afterEach(() => { vi.useRealTimers(); });
+
+    const transfer = (id: number, text = 'hello world'): ClipboardTransfer => ({ id, direction: 'to-desktop', text, truncated: false });
+
+    it('shows each transfer, ignores touches, and goes away after about 1.5 s', () => {
+        let tree!: TestRenderer.ReactTestRenderer;
+        act(() => { tree = TestRenderer.create(<ClipboardConfirmation transfer={null} />); });
+        expect(tree.toJSON()).toBeNull();
+
+        act(() => { tree.update(<ClipboardConfirmation transfer={transfer(1)} />); });
+        const place = tree.toJSON() as TestRenderer.ReactTestRendererJSON;
+        expect(place.props.pointerEvents).toBe('none');
+        expect(flatten(place.props.style).position).toBeUndefined();
+        expect(JSON.stringify(place)).toContain('Sent to desktop · “hello world”');
+
+        act(() => { vi.advanceTimersByTime(CLIPBOARD_CONFIRMATION_MS - 1); });
+        expect(tree.toJSON()).not.toBeNull();
+        act(() => { vi.advanceTimersByTime(1); });
+        expect(tree.toJSON()).toBeNull();
+
+        // The same text again is a new transfer and is confirmed again.
+        act(() => { tree.update(<ClipboardConfirmation transfer={transfer(2)} />); });
+        expect(tree.toJSON()).not.toBeNull();
+    });
+
+    it('describes where the text went and how it starts, with no byte count', () => {
+        expect(describeTransfer({ id: 1, direction: 'to-phone', text: 'a\n  b', truncated: false })).toBe('Copied to phone · “a b”');
+        expect(describeTransfer({ id: 1, direction: 'to-phone', text: 'x'.repeat(2048), truncated: true })).toBe(`Copied to phone · “${'x'.repeat(24)}…”`);
+        expect(describeTransfer({ id: 1, direction: 'to-desktop', text: ' ', truncated: false })).toBe('Sent to desktop');
+    });
+
+    it('reads at 4.5:1 or better over a white or a black desktop', () => {
+        expect(contrast(PILL_COLORS.text, PILL_COLORS.backing, '#ffffff')).toBeGreaterThanOrEqual(4.5);
+        expect(contrast(PILL_COLORS.text, PILL_COLORS.backing, '#000000')).toBeGreaterThanOrEqual(4.5);
+    });
+});
+
+describe('example Copy', () => {
+    it('writes only on a tap and retains a backed accessible failure until the next tap', async () => {
+        example.write.mockReset();
+        example.copy.mockReset();
+        example.copy.mockImplementation(async (write: (text: string) => Promise<void>) => { await write('desktop text'); });
+        let tree!: TestRenderer.ReactTestRenderer;
+        await act(async () => { tree = TestRenderer.create(<App />); });
+        expect(example.write).not.toHaveBeenCalled();
+        const tap = () => tree.root.findByProps({ testID: 'desklink-copy' }).props.onPress();
+
+        example.copy.mockRejectedValueOnce(new Error('clipboard is unavailable for this desktop source'));
+        await act(async () => { tap(); });
+        expect(tree.root.findByProps({ testID: 'desklink-copy-error' }).findByType('Text').props.children)
+            .toBe('Clipboard failed: clipboard is unavailable for this desktop source');
+        expect(example.write).not.toHaveBeenCalled();
+
+        example.write.mockResolvedValue(false);
+        await act(async () => { tap(); });
+        expect(example.write).toHaveBeenCalledWith('desktop text');
+        const error = tree.root.findByProps({ testID: 'desklink-copy-error' });
+        expect(error.props.accessible).toBe(true);
+        expect(error.props.accessibilityRole).toBe('alert');
+        expect(error.props.accessibilityLiveRegion).toBe('polite');
+        const style = flatten(error.props.style);
+        expect(style.paddingHorizontal).toBeGreaterThan(0);
+        expect(style.paddingVertical).toBeGreaterThan(0);
+        expect(contrast('#ffffff', style.backgroundColor as string)).toBeGreaterThanOrEqual(4.5);
+        expect(error.findByType('Text').props.children).toBe('Clipboard failed: The phone refused the clipboard write.');
+        expect(tree.root.findAllByProps({ testID: 'desklink-clipboard' })).toHaveLength(0);
+
+        vi.useFakeTimers();
+        try {
+            act(() => { vi.advanceTimersByTime(5000); });
+            expect(tree.root.findAllByProps({ testID: 'desklink-copy-error' })).toHaveLength(1);
+        } finally { vi.useRealTimers(); }
+
+        example.write.mockRejectedValue(new Error('native write refused'));
+        await act(async () => { tap(); });
+        expect(tree.root.findByProps({ testID: 'desklink-copy-error' }).findByType('Text').props.children).toBe('Clipboard failed: native write refused');
+
+        let finish!: (written: boolean) => void;
+        example.write.mockImplementation(() => new Promise<boolean>((resolve) => { finish = resolve; }));
+        await act(async () => { tap(); });
+        expect(tree.root.findAllByProps({ testID: 'desklink-copy-error' })).toHaveLength(0);
+        expect(tree.root.findAllByProps({ testID: 'desklink-clipboard' })).toHaveLength(0);
+        await act(async () => { finish(true); });
+        expect(tree.root.findAllByProps({ testID: 'desklink-copy-error' })).toHaveLength(0);
+        act(() => { tree.unmount(); });
+    });
+});

package/src/index.ts

@@ -13,9 +13,12 @@ export { desktopAvailable } from './availability';
 export { DesktopView, type DesktopViewProps, type EdgeInsets } from './DesktopView';
 export { observeWebKeyboardMotion } from './webKeyboardMotion';
 export type { StickyModifier, StickyModifiers, StickyState } from './stickyModifiers';
+export { ModifierKeys, type ModifierKeysProps } from './ModifierKeys';
+export { ClipboardConfirmation, type ClipboardConfirmationProps } from './ClipboardConfirmation';
 export {
     useDesktopSession,
     CONTROL_PERMISSIONS,
+    type ClipboardTransfer,
     type DesktopSession,
     type DesktopSessionOptions,
 } from './useDesktopSession';

package/src/protocol.ts

@@ -59,7 +59,7 @@ export interface SessionOpenRequest {
 }
 
 export interface SessionOpenResult {
-    cursor?: { mode: 'embedded' | 'hidden' | 'metadata' | 'unavailable'; positions: boolean };
+    cursor?: { mode: 'embedded' | 'hidden' | 'metadata' | 'unavailable'; positions: boolean; source?: 'ext-image-copy-capture-v1'; limitation?: string };
     sessionId: string;
     generation: number;
     source: { kind: string; width: number; height: number; origin: { x: number; y: number } };
@@ -83,6 +83,7 @@ export interface CursorSample {
     y: number;
     visible: boolean;
     timestamp_us: number;
+    hotspot?: { x: number; y: number };
 }
 
 /**

package/src/useDesktopSession.ts

@@ -25,6 +25,14 @@ import {
     type StickyModifiers,
 } from './stickyModifiers';
 
+/** One clipboard transfer that reached its destination; `id` tells two equal transfers apart. */
+export interface ClipboardTransfer {
+    id: number;
+    direction: 'to-phone' | 'to-desktop';
+    text: string;
+    truncated: boolean;
+}
+
 /** How long a clipboard round trip may take before it is reported as lost. */
 const CLIPBOARD_TIMEOUT_MS = 4000;
 
@@ -199,8 +207,8 @@ export interface DesktopSession {
     close: (reason?: string) => Promise<void>;
     showKeyboard: () => void;
     hideKeyboard: () => void;
-    /** Copy the desktop's clipboard to the phone; the caller places it locally. */
-    copyRemoteToLocal: () => Promise<{ text: string; truncated: boolean }>;
+    /** Copy using the caller's local writer, which must reject if the write fails. */
+    copyRemoteToLocal: (writeLocal: (text: string) => Promise<void>) => Promise<{ text: string; truncated: boolean }>;
     /** Send the phone's clipboard text to the desktop. */
     pasteLocalToRemote: (text: string) => Promise<void>;
     /** Release anything the desktop is holding, without ending the session. */
@@ -221,6 +229,8 @@ export interface DesktopSession {
      * because the engine lets go of exactly the modifiers the message names.
      */
     pressKey: (name: string) => () => void;
+    /** The last clipboard transfer that completed, for the app to confirm; null until one does. */
+    clipboard: ClipboardTransfer | null;
 }
 
 const IDLE: SessionSnapshot = {
@@ -245,6 +255,8 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
     const [modifiers, setModifiers] = useState<StickyModifiers>(NO_MODIFIERS);
     /** Read by input as it arrives, which can be faster than a render. */
     const modifiersRef = useRef<StickyModifiers>(NO_MODIFIERS);
+    const [clipboard, setClipboard] = useState<ClipboardTransfer | null>(null);
+    const clipboardCount = useRef(0);
 
     const opened = useRef<SessionOpenResult | null>(null);
     const signaling = useRef<Signaling | null>(null);
@@ -887,6 +899,14 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
                             return;
                         }
                         if (reply.kind === 'rejected') {
+                            // These session-wide clipboard refusals have no request ID.
+                            // A generic permission rejection can belong to other input.
+                            if (reply.seq === 0 && (reply.code === 'clipboard-unsupported' || reply.code === 'session')) {
+                                for (const resolve of pendingClipboard.current.values()) {
+                                    resolve({ text: '', truncated: false, error: reply.message });
+                                }
+                                pendingClipboard.current.clear();
+                            }
                             diagnostics.current.lastRejection = `${reply.code}: ${reply.message}`;
                             update({ diagnostics: { ...diagnostics.current } });
                             optionsRef.current.onRejected?.({ code: reply.code, message: reply.message });
@@ -937,7 +957,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         };
     }, [transportFailed, onTransportState, cancelRestart, spendRestartAttempt, notePing, teardown, update, pressKey, typeText]);
 
-    const copyRemoteToLocal = useCallback(async () => {
+    const copyRemoteToLocal = useCallback(async (writeLocal: (text: string) => Promise<void>) => {
         if (!inputEnabled.current) throw new Error('Desktop control is off.');
         const id = nativeRef.current;
         if (id == null || nativeDesklink == null) throw new Error('No desktop session is open.');
@@ -951,6 +971,8 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         nativeDesklink.sendControl(id, JSON.stringify({ kind: 'clipboard_read', request }));
         const reply = await answer;
         if (reply.error != null) throw new Error(reply.error);
+        await writeLocal(reply.text);
+        setClipboard({ id: ++clipboardCount.current, direction: 'to-phone', text: reply.text, truncated: reply.truncated });
         return { text: reply.text, truncated: reply.truncated };
     }, []);
 
@@ -968,6 +990,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         nativeDesklink.sendControl(id, JSON.stringify({ kind: 'clipboard_write', request, text }));
         const reply = await answer;
         if (reply.error != null) throw new Error(reply.error);
+        setClipboard({ id: ++clipboardCount.current, direction: 'to-desktop', text, truncated: false });
     }, []);
 
     const close = useCallback(async (reason = 'closed by the user') => {
@@ -1086,6 +1109,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         modifiers,
         tapModifier,
         pressKey,
+        clipboard,
     }), [
         snapshot,
         nativeId,
@@ -1104,6 +1128,7 @@ export function useDesktopSession(options: DesktopSessionOptions): DesktopSessio
         modifiers,
         tapModifier,
         pressKey,
+        clipboard,
     ]);
 }