diff --git a/mobile/README.md b/mobile/README.md
index 64f1081b73cf..035c7d8df037 100644
--- a/mobile/README.md
+++ b/mobile/README.md
@@ -200,6 +200,26 @@ Read on every request, so behaviour can be flipped mid-session without a restart
2. In Orca, go to Settings > Mobile and scan the QR code with this app
3. The QR encodes the connection endpoint, device token, and TLS fingerprint
+## Samsung DeX / desktop mode
+
+Manifest changes require a native Android rebuild; Expo Go cannot validate them.
+
+```bash
+pnpm exec expo prebuild --platform android --clean
+cd android
+./gradlew assembleDebug
+```
+
+Use the manual DeX, multi-window, hardware-keyboard, and DPI checklist in
+[`docs/dex-mode-layout-design.md`](docs/dex-mode-layout-design.md#62-manual-dex-checklist).
+The native Activity display-metrics hook works around
+[React Native #55659](https://github.com/facebook/react-native/issues/55659), which otherwise uses
+the phone display's density for windows on a DeX monitor. A density-only change at identical pixel
+bounds may wait for the next geometry-driven layout; DeX enter, exit, resize, and maximize also
+change the window bounds.
+RN Android does not deliver every arrow/Ctrl/F-key event; the terminal accessory row remains the
+fallback until the planned native hardware-key module lands.
+
## Project Structure
```
diff --git a/mobile/app.json b/mobile/app.json
index d5a420cc74b9..173cad2be37e 100644
--- a/mobile/app.json
+++ b/mobile/app.json
@@ -80,6 +80,7 @@
"plugins": [
"expo-router",
"./plugins/android-respect-rotation-lock.js",
+ "./plugins/android-desktop-mode.js",
[
"expo-splash-screen",
{
diff --git a/mobile/app/_layout.tsx b/mobile/app/_layout.tsx
index 9080cdedcf95..b96d1d525d59 100644
--- a/mobile/app/_layout.tsx
+++ b/mobile/app/_layout.tsx
@@ -1,5 +1,5 @@
import { useCallback, useEffect, useRef } from 'react'
-import { View, StyleSheet } from 'react-native'
+import { StyleSheet } from 'react-native'
import { Stack, useRouter } from 'expo-router'
import { StatusBar } from 'expo-status-bar'
import * as SplashScreen from 'expo-splash-screen'
@@ -13,6 +13,7 @@ import { useOpenNotificationRoute } from '../src/notifications/use-open-notifica
import { loadHostCatalog } from '../src/transport/host-store'
import { extractPairingCodeFromUrl } from '../src/transport/pairing'
import { recoverMobileRelayPairing } from '../src/transport/mobile-relay-pairing-recovery'
+import { WindowBoundsProvider } from '../src/layout/window-bounds'
// Why: keeps the native splash screen visible until the React tree is mounted
// and ready to render. Without this the user sees a blank white/black frame
@@ -159,7 +160,7 @@ export default function RootLayout() {
return (
-
+
-
+
)
}
diff --git a/mobile/app/h/[hostId]/session/[worktreeId].tsx b/mobile/app/h/[hostId]/session/[worktreeId].tsx
index a34c8643ab0b..2e9a9758d0a8 100644
--- a/mobile/app/h/[hostId]/session/[worktreeId].tsx
+++ b/mobile/app/h/[hostId]/session/[worktreeId].tsx
@@ -4,7 +4,6 @@ import {
AppState,
Linking,
type AppStateStatus,
- BackHandler,
FlatList,
Image,
View,
@@ -133,6 +132,9 @@ import { isTerminalSendRpcAccepted } from '../../../../src/terminal/terminal-sen
import { sendMobileTerminalQueryReply } from '../../../../src/terminal/mobile-terminal-query-reply'
import { TERMINAL_QUERY_REPLY_INPUT_RUNTIME_CAPABILITY } from '../../../../../src/shared/protocol-version'
import { useTerminalLiveInputCommit } from '../../../../src/terminal/use-terminal-live-input-commit'
+import { useHardwareKeyboardAttached } from '../../../../src/platform/hardware-keyboard'
+import { useSessionBackHandler } from '../../../../src/session/use-session-back-handler'
+import { useTerminalFrameLayout } from '../../../../src/session/use-terminal-frame-layout'
import { resolveMobileTerminalInputGate } from '../../../../src/terminal/terminal-input-connection-gate'
import {
buildTerminalSendParams,
@@ -897,6 +899,8 @@ export default function SessionScreen() {
)
// Why: Expo SDK 55 edge-to-edge doesn't resize the window on IME open, so track keyboard height ourselves and lift the input without resizing the desktop PTY.
const [keyboardHeight, setKeyboardHeight] = useState(0)
+ const { hardwareKeyboard, notifyHardwareKeyEvent, notifyImeShown, notifyImeHidden } =
+ useHardwareKeyboardAttached()
// Why: server-authoritative display mode per terminal, populated from subscribe responses.
const [terminalModes, setTerminalModes] = useState