From afc13003b30c31d1bfb494a3b5e50d223e6d0eeb Mon Sep 17 00:00:00 2001
From: Karn <mail@karngyan.com>
Date: Wed, 12 Aug 2026 18:13:47 +0530
Subject: [PATCH] fix(web): make mobile terminals reliable

---
 web/src/components/key-bar.tsx               | 20 ++++-
 web/src/components/session-switcher.test.tsx | 20 ++++-
 web/src/components/session-switcher.tsx      | 29 +++++--
 web/src/components/terminal.test.tsx         | 88 +++++++++++++++++++-
 web/src/components/terminal.tsx              | 85 +++++++++++++++----
 web/src/components/theme-menu.tsx            |  2 +-
 web/src/emulator/emulator.test.ts            | 32 +++++++
 web/src/emulator/types.ts                    |  9 ++
 web/src/emulator/xterm.ts                    |  5 ++
 web/src/hooks/use-mobile.ts                  |  8 +-
 web/src/lib/viewport.test.ts                 |  5 +-
 web/src/lib/viewport.ts                      |  6 +-
 web/src/styles.css                           |  6 ++
 web/src/testing/emulator.ts                  |  9 ++
 14 files changed, 290 insertions(+), 34 deletions(-)

diff --git a/web/src/components/key-bar.tsx b/web/src/components/key-bar.tsx
index 4af1d45..cf8adee 100644
--- a/web/src/components/key-bar.tsx
+++ b/web/src/components/key-bar.tsx
@@ -32,13 +32,15 @@ export function KeyBar(props: {
   ctrl: boolean
   onCtrl: () => void
   onKey: (key: BarKey) => void
+  onPaste: () => void
 }) {
-  const chip = 'rounded-md px-2.5 py-1.5 font-mono text-sm/4 transition-colors select-none'
+  const chip =
+    'min-h-12 shrink-0 rounded-md px-3 py-1.5 font-mono text-sm/4 transition-colors select-none'
   return (
     <div
       data-flue-keybar=""
       className={cn(
-        'absolute bottom-3 left-1/2 z-10 flex -translate-x-1/2 items-center gap-x-1',
+        'absolute bottom-3 left-1/2 z-10 flex max-w-[calc(100%-1.5rem)] -translate-x-1/2 items-center gap-x-1 overflow-x-auto overscroll-x-contain',
         'rounded-lg bg-(--chip-bg) p-1 shadow-lg ring-1 ring-(--chip-ring) backdrop-blur-sm',
       )}
     >
@@ -62,6 +64,20 @@ export function KeyBar(props: {
       >
         ctrl
       </button>
+      <button
+        type="button"
+        title="Paste from clipboard"
+        onPointerDown={(e) => {
+          e.preventDefault()
+          props.onPaste()
+        }}
+        onClick={(e) => {
+          if (e.detail === 0) props.onPaste()
+        }}
+        className={cn(chip, 'text-(--chip-dim) hover:text-(--chip-fg) active:bg-(--chip-wash)')}
+      >
+        paste
+      </button>
       {KEYS.map((k) => (
         <button
           key={k.key}
diff --git a/web/src/components/session-switcher.test.tsx b/web/src/components/session-switcher.test.tsx
index b2a7d7f..1a10bf4 100644
--- a/web/src/components/session-switcher.test.tsx
+++ b/web/src/components/session-switcher.test.tsx
@@ -1,6 +1,6 @@
 import { render, screen, waitFor, within } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import type { FleetSession } from '@/fleet/types'
 import type { RecentVisit } from '@/switcher/recents'
@@ -88,6 +88,10 @@ describe('SessionSwitcher', () => {
     )
   })
 
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
   it('shows nothing at all while shut', () => {
     mount({ open: false })
     expect(screen.queryByRole('combobox')).toBeNull()
@@ -105,6 +109,20 @@ describe('SessionSwitcher', () => {
     expect(screen.queryByText(/loading/i)).toBeNull()
   })
 
+  it('does not summon the keyboard when opened on mobile', async () => {
+    vi.stubGlobal('innerWidth', 390)
+    mount()
+
+    const dialog = screen.getByRole('dialog')
+    await waitFor(() => expect(document.activeElement).toBe(dialog))
+    expect(dialog.className).toContain('max-md:max-w-none')
+    expect(screen.getByRole('listbox').parentElement!.className).toContain('min-w-0')
+
+    // Search remains available by explicit intent.
+    await userEvent.setup().click(field())
+    expect(document.activeElement).toBe(field())
+  })
+
   it('reads pinned first, under its own heading, with the chord on the row', () => {
     mount({ sessions: [s({ id: 'a', name: 'loose' }), s({ id: 'p', name: 'kept', pinned: true })] })
     expect(screen.getByText('Pinned')).toBeTruthy()
diff --git a/web/src/components/session-switcher.tsx b/web/src/components/session-switcher.tsx
index b3e29ef..26f22fc 100644
--- a/web/src/components/session-switcher.tsx
+++ b/web/src/components/session-switcher.tsx
@@ -91,6 +91,7 @@ export function SessionSwitcher({
 }: SessionSwitcherProps) {
   const [search, setSearch] = useState('')
   const [highlight, setHighlight] = useState<string | null>(null)
+  const dialogRef = useRef<HTMLDivElement>(null)
   const mobile = useIsMobile()
   const apple = useMemo(() => isApplePlatform(), [])
 
@@ -225,15 +226,25 @@ export function SessionSwitcher({
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContent
+        ref={dialogRef}
         showCloseButton={false}
         aria-describedby={undefined}
+        onOpenAutoFocus={(e) => {
+          // Opening the switcher from its touch control is for choosing a row,
+          // not an implicit request to search. Keep the software keyboard down
+          // until the person explicitly taps the field.
+          if (mobile) {
+            e.preventDefault()
+            dialogRef.current?.focus({ preventScroll: true })
+          }
+        }}
         // Anchored high rather than centred: a palette grows downwards as it
         // fills, and one pinned to the middle of the window would slide its own
         // search field up the screen while somebody types into it.
         className={cn(
-          'top-[12vh] w-[56rem] translate-y-0 gap-0 overflow-hidden p-0 sm:max-w-[calc(100vw-2rem)]',
-          'max-h-[76vh] max-md:top-auto max-md:bottom-0 max-md:h-[85vh] max-md:max-h-none',
-          'max-md:w-full max-md:rounded-b-none',
+          'top-[12vh] w-[56rem] grid-rows-[auto_minmax(0,1fr)_auto] translate-y-0 gap-0 overflow-hidden p-0 sm:max-w-[calc(100vw-2rem)]',
+          'max-h-[76vh] max-md:top-auto max-md:bottom-0 max-md:h-[85dvh] max-md:max-h-none',
+          'max-md:w-full max-md:max-w-none max-md:rounded-b-none',
         )}
       >
         <DialogTitle className="sr-only">Switch session</DialogTitle>
@@ -241,7 +252,7 @@ export function SessionSwitcher({
         <div className="flex items-center gap-x-2.5 border-b border-hairline px-3.5">
           <MagnifyingGlassIcon aria-hidden="true" className="size-4 shrink-0 text-muted-foreground" />
           <input
-            autoFocus
+            autoFocus={!mobile}
             type="text"
             role="combobox"
             aria-expanded="true"
@@ -258,10 +269,10 @@ export function SessionSwitcher({
           />
         </div>
 
-        <div className="flex min-h-0 flex-1">
+        <div className="flex min-h-0 min-w-0 flex-1">
           <div
             className={cn(
-              'min-h-0 flex-1 overflow-y-auto py-1.5',
+              'min-h-0 min-w-0 flex-1 overflow-y-auto overscroll-contain py-1.5',
               // The pane beside it only exists where there is width for one.
               'md:w-[24rem] md:flex-none md:border-r md:border-hairline',
             )}
@@ -328,7 +339,7 @@ export function SessionSwitcher({
           </div>
         </div>
 
-        <div className="flex flex-wrap items-center gap-x-4 gap-y-1 border-t border-hairline bg-muted/40 px-3.5 py-2 text-[0.6875rem] text-muted-foreground">
+        <div className="hidden flex-wrap items-center gap-x-4 gap-y-1 border-t border-hairline bg-muted/40 px-3.5 py-2 text-[0.6875rem] text-muted-foreground md:flex">
           <Hint keys="↑↓" what="move" />
           <Hint keys="↵" what="open" />
           <Hint keys={apple ? '⌃⇧1-9' : 'Ctrl+Shift+1-9'} what="pinned" />
@@ -386,7 +397,7 @@ function Row({
       onPointerMove={onHighlight}
       onClick={onPick}
       className={cn(
-        'relative flex h-8 cursor-pointer items-center gap-x-2.5 px-3.5 text-control',
+        'relative flex h-12 cursor-pointer items-center gap-x-2.5 px-3.5 text-base md:h-8 md:text-control',
         active && 'bg-row-hover',
       )}
     >
@@ -408,7 +419,7 @@ function Row({
       >
         {rowLabel(row)}
       </span>
-      <span className="truncate font-mono text-xs text-muted-foreground">{rowCwd(row)}</span>
+      <span className="hidden truncate font-mono text-xs text-muted-foreground sm:inline">{rowCwd(row)}</span>
       <span className="ml-auto flex shrink-0 items-center gap-x-2 pl-2">
         {row.current && <span className="text-xs text-muted-foreground">current</span>}
         <span className="font-mono text-xs text-muted-foreground">{rowMachine(row)}</span>
diff --git a/web/src/components/terminal.test.tsx b/web/src/components/terminal.test.tsx
index 3f8e01a..7a5a29a 100644
--- a/web/src/components/terminal.test.tsx
+++ b/web/src/components/terminal.test.tsx
@@ -10,6 +10,8 @@ import { createFakeEmulator, type FakeEmulator } from '@/testing/emulator'
 import { attached, fakeClient, sizeChanged, type FakeSocket } from '@/testing/socket'
 import { RESIZE_SETTLE_MS, Terminal, TERMINAL_SHORTCUT_HINT } from './terminal'
 
+const REAL_CLIPBOARD = Object.getOwnPropertyDescriptor(navigator, 'clipboard')
+
 /**
  * One emulator per mount, all of them kept.
  *
@@ -117,6 +119,8 @@ afterEach(() => {
   document.documentElement.style.backgroundColor = ''
   document.body.style.backgroundColor = ''
   localStorage.clear()
+  if (REAL_CLIPBOARD) Object.defineProperty(navigator, 'clipboard', REAL_CLIPBOARD)
+  else Reflect.deleteProperty(navigator, 'clipboard')
 })
 
 /**
@@ -636,6 +640,33 @@ describe('Terminal', () => {
       expect(move.defaultPrevented).toBe(true)
     })
 
+    it('scrolls when the gesture starts in usable pane space outside xterm', () => {
+      // A cross-device screen can be scaled smaller than its inset, and the
+      // inset itself has breathing room around the cells. The whole terminal
+      // area must scroll; whether the first pixel hit xterm cannot decide it.
+      const { em } = mountDraggable()
+
+      act(() => void inset().dispatchEvent(touch('touchstart', [200])))
+      const move = touch('touchmove', [166])
+      act(() => void inset().dispatchEvent(move))
+
+      expect(em.live().scrolled).toBe(2)
+      expect(move.defaultPrevented).toBe(true)
+    })
+
+    it('does not resume a one-finger drag after a second finger interrupts it', () => {
+      const { em } = mountDraggable()
+      const surface = surfaceEl()
+
+      act(() => {
+        surface.dispatchEvent(touch('touchstart', [200]))
+        surface.dispatchEvent(touch('touchmove', [166, 240]))
+        surface.dispatchEvent(touch('touchmove', [140]))
+      })
+
+      expect(em.live().scrolled).toBe(0)
+    })
+
     it('leaves the gesture to the browser while the page is pinch-zoomed', () => {
       // Releasing touch-action cannot deliver this on its own. It only tells
       // the browser it *may* pan; the preventDefault() above cancels that pan
@@ -1430,6 +1461,61 @@ describe('Terminal', () => {
       expect(key('ctrl').getAttribute('aria-pressed')).toBe('false')
     })
 
+    it('pastes through the emulator from the mobile clipboard', async () => {
+      coarsePointer()
+      const readText = vi.fn().mockResolvedValue('git status\n')
+      Object.defineProperty(navigator, 'clipboard', {
+        configurable: true,
+        value: { readText },
+      })
+      const { sock, em } = mountTerminal((e) => (
+        <Terminal sessionId="s1" createEmulator={e.create} />
+      ))
+      act(() => sock.emitControl(attached({ ref: 1, id: 's1' })))
+
+      fireEvent.pointerDown(key('paste'))
+
+      await waitFor(() => expect(em.live().pasted).toEqual(['git status\n']))
+      expect(readText).toHaveBeenCalledTimes(1)
+      expect(sock.input()).toEqual([{ ref: 1, text: 'git status\n' }])
+    })
+
+    it('does not apply the latched Ctrl modifier to a one-character paste', async () => {
+      coarsePointer()
+      Object.defineProperty(navigator, 'clipboard', {
+        configurable: true,
+        value: { readText: vi.fn().mockResolvedValue('c') },
+      })
+      const { sock } = mountTerminal((e) => (
+        <Terminal sessionId="s1" createEmulator={e.create} />
+      ))
+      act(() => sock.emitControl(attached({ ref: 1, id: 's1' })))
+
+      fireEvent.pointerDown(key('ctrl'))
+      fireEvent.pointerDown(key('paste'))
+
+      await waitFor(() => expect(sock.input()).toEqual([{ ref: 1, text: 'c' }]))
+      expect(key('ctrl').getAttribute('aria-pressed')).toBe('false')
+    })
+
+    it('explains when the browser refuses the clipboard', async () => {
+      coarsePointer()
+      Object.defineProperty(navigator, 'clipboard', {
+        configurable: true,
+        value: { readText: vi.fn().mockRejectedValue(new Error('denied')) },
+      })
+      const { sock } = mountTerminal((e) => (
+        <Terminal sessionId="s1" createEmulator={e.create} />
+      ))
+      act(() => sock.emitControl(attached({ ref: 1, id: 's1' })))
+
+      fireEvent.pointerDown(key('paste'))
+
+      expect((await screen.findByRole('alert')).textContent).toBe(
+        'This browser would not hand flue the clipboard.',
+      )
+    })
+
     it('drops bar keys pressed before the attach comes back', () => {
       coarsePointer()
       const { sock } = mountTerminal((e) => <Terminal sessionId="s1" createEmulator={e.create} />)
@@ -1440,7 +1526,7 @@ describe('Terminal', () => {
     it('reserves bottom room in the inset so the bar covers no rows', () => {
       coarsePointer()
       mountTerminal((e) => <Terminal sessionId="s1" createEmulator={e.create} />)
-      expect(inset().className).toContain('bottom-16')
+      expect(inset().className).toContain('bottom-20')
     })
   })
 })
diff --git a/web/src/components/terminal.tsx b/web/src/components/terminal.tsx
index de6af04..8c82b5d 100644
--- a/web/src/components/terminal.tsx
+++ b/web/src/components/terminal.tsx
@@ -169,6 +169,7 @@ export function Terminal({
   const ctrlArmedRef = useRef(ctrlArmed)
   ctrlArmedRef.current = ctrlArmed
   const [exitCode, setExitCode] = useState<number | null>(null)
+  const [pasteProblem, setPasteProblem] = useState<string | null>(null)
   // This session's directory, for Restart and the new-session link. From the
   // session list, because `attached` does not carry it.
   const [cwd, setCwd] = useState<string | null>(null)
@@ -194,6 +195,7 @@ export function Terminal({
     restart: (dir: string | null) => void
     applyTheme: (id: string) => void
     sendKey: (key: BarKey) => void
+    paste: () => void
   } | null>(null)
   // The latest onRestarted, readable from inside the effect without putting
   // a prop identity in its dependency array.
@@ -244,6 +246,7 @@ export function Terminal({
 
     const palette = resolveTheme(themeIdRef.current, prefersDark())
     const emulator = createEmulator({ cols: 80, rows: 24, theme: palette })
+    let alive = true
     emulator.attachTo(surface)
     emulator.focus()
     paintGround(palette.background)
@@ -461,6 +464,8 @@ export function Terminal({
       // it says. So while zoomed this takes no gesture at all.
       if (e.touches.length !== 1 || zoomedIn(window.visualViewport)) {
         touchY = null
+        touchCarry = 0
+        flick = []
         return
       }
       touchY = e.touches[0]!.clientY
@@ -472,7 +477,13 @@ export function Terminal({
       flick.push({ t: e.timeStamp, y: touchY })
     }
     const touchMove = (e: TouchEvent) => {
-      if (touchY === null || e.touches.length !== 1) return
+      if (e.touches.length !== 1) {
+        touchY = null
+        touchCarry = 0
+        flick = []
+        return
+      }
+      if (touchY === null) return
       // The zoom can arrive after the finger is already down, so the same
       // question is asked again here. Dropping the anchor rather than merely
       // returning keeps a later unzoom from scrolling by the whole distance
@@ -532,10 +543,10 @@ export function Terminal({
       touchCarry = 0
       flick = []
     }
-    surface.addEventListener('touchstart', touchStart, { passive: true })
-    surface.addEventListener('touchmove', touchMove, { passive: false })
-    surface.addEventListener('touchend', touchEnd, { passive: true })
-    surface.addEventListener('touchcancel', touchCancel, { passive: true })
+    inner.addEventListener('touchstart', touchStart, { passive: true })
+    inner.addEventListener('touchmove', touchMove, { passive: false })
+    inner.addEventListener('touchend', touchEnd, { passive: true })
+    inner.addEventListener('touchcancel', touchCancel, { passive: true })
 
     // The pane hugs the visual viewport: a phone keyboard shrinks it and the
     // ResizeObserver below refits the terminal above the keyboard. While
@@ -543,6 +554,7 @@ export function Terminal({
     const untrackViewport = trackVisualViewport({
       pane,
       surface,
+      gestureArea: inner,
       viewport: window.visualViewport,
     })
 
@@ -754,6 +766,37 @@ export function Terminal({
         }
         client.sendInput(ref, bytes)
       },
+      paste: () => {
+        if (ref === null || consumed < muteUntil) {
+          setPasteProblem('The terminal is not ready for input yet.')
+          return
+        }
+        const clipboard = navigator.clipboard
+        if (!clipboard?.readText) {
+          setPasteProblem('This browser does not allow reading the clipboard here.')
+          return
+        }
+        // A latched hardware modifier does not alter a clipboard paste. Clear
+        // ours before xterm emits the prepared text through onData, or a
+        // one-character paste such as "c" could turn into Ctrl+C.
+        ctrlArmedRef.current = false
+        setCtrlArmed(false)
+        void clipboard.readText().then(
+          (text) => {
+            if (!alive) return
+            if (text === '') {
+              setPasteProblem('The clipboard is empty.')
+              return
+            }
+            setPasteProblem(null)
+            emulator.paste(text)
+            emulator.focus()
+          },
+          () => {
+            if (alive) setPasteProblem('This browser would not hand flue the clipboard.')
+          },
+        )
+      },
     }
 
     // Another tab choosing a theme lands here: the preference is global, and
@@ -774,12 +817,13 @@ export function Terminal({
     client.list()
 
     return () => {
+      alive = false
       actionsRef.current = null
       for (const off of offs) off()
-      surface.removeEventListener('touchstart', touchStart)
-      surface.removeEventListener('touchmove', touchMove)
-      surface.removeEventListener('touchend', touchEnd)
-      surface.removeEventListener('touchcancel', touchCancel)
+      inner.removeEventListener('touchstart', touchStart)
+      inner.removeEventListener('touchmove', touchMove)
+      inner.removeEventListener('touchend', touchEnd)
+      inner.removeEventListener('touchcancel', touchCancel)
       glide?.()
       untrackViewport()
       window.removeEventListener('storage', onStorage)
@@ -848,8 +892,8 @@ export function Terminal({
         ref={innerRef}
         data-flue-inset=""
         className={cn(
-          'absolute inset-3 transition-opacity',
-          coarse && 'bottom-16',
+          'flue-term-gesture absolute inset-3 transition-opacity',
+          coarse && 'bottom-20',
           phase === 'exited' && 'opacity-60',
         )}
       >
@@ -864,12 +908,21 @@ export function Terminal({
           ctrl={ctrlArmed}
           onCtrl={() => setCtrlArmed((v) => !v)}
           onKey={(k) => actionsRef.current?.sendKey(k)}
+          onPaste={() => actionsRef.current?.paste()}
         />
       )}
+      {pasteProblem !== null && (
+        <p
+          role="alert"
+          className="absolute right-3 bottom-20 left-3 z-20 rounded-md bg-(--chip-bg) px-3 py-2 text-center text-sm text-(--chip-fg) shadow-lg ring-1 ring-(--chip-ring)"
+        >
+          {pasteProblem}
+        </p>
+      )}
       {/* z-10: xterm's own layers carry z-indexes, and an unindexed sibling
           loses to them — the controls must win the stack or the scrollbar
           eats their clicks. */}
-      <div className="absolute top-3 right-3 z-10 flex items-start gap-x-2">
+      <div className="absolute top-3 right-3 z-10 flex max-w-[calc(100%-1.5rem)] items-start gap-x-2 overflow-x-auto overscroll-x-contain">
         <ThemeMenu value={themeId} dark={dark} onChange={handleTheme} />
         {/*
           The way to another session without leaving this one.
@@ -886,7 +939,7 @@ export function Terminal({
           onClick={() => switcher.open()}
           title={`Switch session · ${chordLabel}`}
           className={cn(
-            'rounded-lg px-2.5 py-1.5',
+            'inline-flex size-12 shrink-0 items-center justify-center rounded-lg sm:size-auto sm:px-2.5 sm:py-1.5',
             'bg-(--chip-bg) text-(--chip-dim) shadow-lg ring-1 ring-(--chip-ring) backdrop-blur-sm',
             'transition-colors hover:text-(--chip-fg)',
           )}
@@ -906,7 +959,7 @@ export function Terminal({
           rel="noopener"
           title="Open the dashboard"
           className={cn(
-            'rounded-lg px-2.5 py-1.5',
+            'inline-flex size-12 shrink-0 items-center justify-center rounded-lg sm:size-auto sm:px-2.5 sm:py-1.5',
             'bg-(--chip-bg) text-(--chip-dim) shadow-lg ring-1 ring-(--chip-ring) backdrop-blur-sm',
             'transition-colors hover:text-(--chip-fg)',
           )}
@@ -930,7 +983,7 @@ export function Terminal({
           onClick={() => onNewSession?.(cwd)}
           title="New session here"
           className={cn(
-            'rounded-lg px-2.5 py-1.5',
+            'inline-flex size-12 shrink-0 items-center justify-center rounded-lg sm:size-auto sm:px-2.5 sm:py-1.5',
             'bg-(--chip-bg) text-(--chip-dim) shadow-lg ring-1 ring-(--chip-ring) backdrop-blur-sm',
             'transition-colors hover:text-(--chip-fg)',
           )}
@@ -951,7 +1004,7 @@ export function Terminal({
             className={cn(
               // /4 line-height: 16px text box + py-1.5 = the same 28px as the
               // icon buttons beside it (size-4 in py-1.5), one strip height.
-              'rounded-lg px-3 py-1.5 text-base/4 font-medium sm:text-sm/4',
+              'shrink-0 rounded-lg px-3 py-1.5 text-base/4 font-medium sm:text-sm/4',
               'bg-(--chip-bg) text-(--chip-fg) shadow-lg ring-1 ring-(--chip-ring) backdrop-blur-sm',
             )}
           >
diff --git a/web/src/components/theme-menu.tsx b/web/src/components/theme-menu.tsx
index d7187c9..53df0c2 100644
--- a/web/src/components/theme-menu.tsx
+++ b/web/src/components/theme-menu.tsx
@@ -48,7 +48,7 @@ export function ThemeMenu({
           title="Terminal theme"
           style={chipStyle}
           className={cn(
-            'rounded-lg px-2.5 py-1.5',
+            'inline-flex size-12 shrink-0 items-center justify-center rounded-lg sm:size-auto sm:px-2.5 sm:py-1.5',
             'bg-(--chip-bg) text-(--chip-dim) shadow-lg ring-1 ring-(--chip-ring) backdrop-blur-sm',
             'transition-colors hover:text-(--chip-fg) data-[state=open]:text-(--chip-fg)',
           )}
diff --git a/web/src/emulator/emulator.test.ts b/web/src/emulator/emulator.test.ts
index 02a1c98..cf93d9c 100644
--- a/web/src/emulator/emulator.test.ts
+++ b/web/src/emulator/emulator.test.ts
@@ -123,6 +123,37 @@ describe('Emulator interface', () => {
     em.dispose()
   })
 
+  it('normalises pasted newlines through xterm', () => {
+    const el = document.createElement('div')
+    document.body.appendChild(el)
+    const em = createXtermEmulator({ cols: 10, rows: 4 })
+    em.attachTo(el)
+    const seen: string[] = []
+    em.onData((b) => seen.push(new TextDecoder().decode(b)))
+
+    em.paste('one\ntwo\r\nthree')
+
+    expect(seen.join('')).toBe('one\rtwo\rthree')
+    em.dispose()
+    el.remove()
+  })
+
+  it('honours a program that enabled bracketed-paste mode', async () => {
+    const el = document.createElement('div')
+    document.body.appendChild(el)
+    const em = createXtermEmulator({ cols: 10, rows: 4 })
+    em.attachTo(el)
+    const seen: string[] = []
+    em.onData((b) => seen.push(new TextDecoder().decode(b)))
+    await settled(em, '\x1b[?2004h')
+
+    em.paste('safe')
+
+    expect(seen.join('')).toBe('\x1b[200~safe\x1b[201~')
+    em.dispose()
+    el.remove()
+  })
+
   it('reports no measurement before it is mounted', () => {
     // The sizing policy divides by whatever this returns. A zero-sized answer
     // dressed up as a real one becomes an Infinity one line later; jsdom lays
@@ -156,6 +187,7 @@ describe('Emulator interface', () => {
     em.dispose()
 
     expect(() => em.focus()).not.toThrow()
+    expect(() => em.paste('ignored')).not.toThrow()
     expect(() => em.setTheme({ background: '#000000' })).not.toThrow()
     expect(em.contentSize()).toBeNull()
     expect(() => em.answerQueries(true)).not.toThrow()
diff --git a/web/src/emulator/types.ts b/web/src/emulator/types.ts
index ddf955a..4c5d010 100644
--- a/web/src/emulator/types.ts
+++ b/web/src/emulator/types.ts
@@ -106,6 +106,15 @@ export interface Emulator {
    * destination rather than registering a second callback.
    */
   onData(cb: (bytes: Uint8Array) => void): void
+  /**
+   * Paste text as terminal input.
+   *
+   * This is distinct from feeding raw bytes: a terminal normalises pasted
+   * newlines and wraps the text when the program has enabled bracketed-paste
+   * mode. Mobile clipboard controls must go through the emulator so they keep
+   * those semantics.
+   */
+  paste(text: string): void
   /**
    * Mount into the DOM.
    *
diff --git a/web/src/emulator/xterm.ts b/web/src/emulator/xterm.ts
index fe45c64..43c257c 100644
--- a/web/src/emulator/xterm.ts
+++ b/web/src/emulator/xterm.ts
@@ -171,6 +171,11 @@ export function createXtermEmulator(opts: XtermOptions = {}): Emulator {
       term.onData((data) => cb(encoder.encode(data)))
     },
 
+    paste(text: string) {
+      if (disposed) return
+      term.paste(text)
+    },
+
     attachTo(el: HTMLElement) {
       term.open(el)
       // Best-effort GPU rendering; the DOM renderer is a fine fallback, and
diff --git a/web/src/hooks/use-mobile.ts b/web/src/hooks/use-mobile.ts
index 2b0fe1d..5c4a812 100644
--- a/web/src/hooks/use-mobile.ts
+++ b/web/src/hooks/use-mobile.ts
@@ -3,7 +3,11 @@ import * as React from "react"
 const MOBILE_BREAKPOINT = 768
 
 export function useIsMobile() {
-  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+  // The first render matters for focus policy: a dialog can run its opening
+  // autofocus before this hook's effect. Starting at a desktop-shaped false
+  // would briefly focus a mobile input and summon the keyboard before the
+  // viewport listener had a chance to correct the answer.
+  const [isMobile, setIsMobile] = React.useState(() => window.innerWidth < MOBILE_BREAKPOINT)
 
   React.useEffect(() => {
     const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
@@ -15,5 +19,5 @@ export function useIsMobile() {
     return () => mql.removeEventListener("change", onChange)
   }, [])
 
-  return !!isMobile
+  return isMobile
 }
diff --git a/web/src/lib/viewport.test.ts b/web/src/lib/viewport.test.ts
index f20b1fb..fdd4c02 100644
--- a/web/src/lib/viewport.test.ts
+++ b/web/src/lib/viewport.test.ts
@@ -90,7 +90,8 @@ describe('trackVisualViewport', () => {
 
   it('releases the surface to the browser while pinch-zoomed', () => {
     const vv = fakeViewport({ height: 700 })
-    trackVisualViewport({ pane, surface, viewport: vv })
+    const gestureArea = document.createElement('div')
+    trackVisualViewport({ pane, surface, gestureArea, viewport: vv })
 
     vv.scale = 2
     vv.height = 350
@@ -101,12 +102,14 @@ describe('trackVisualViewport', () => {
     // a zoom is not a layout change: the pane keeps its unzoomed size, so the
     // pty never refits on a pinch.
     expect(surface.style.touchAction).toBe('auto')
+    expect(gestureArea.style.touchAction).toBe('auto')
     expect(pane.style.height).toBe('700px')
 
     vv.scale = 1
     vv.height = 700
     vv.fire()
     expect(surface.style.touchAction).toBe('')
+    expect(gestureArea.style.touchAction).toBe('')
     expect(pane.style.height).toBe('700px')
   })
 
diff --git a/web/src/lib/viewport.ts b/web/src/lib/viewport.ts
index d982e29..e5cce40 100644
--- a/web/src/lib/viewport.ts
+++ b/web/src/lib/viewport.ts
@@ -55,17 +55,20 @@ export function zoomedIn(viewport: ViewportLike | null | undefined): boolean {
 export function trackVisualViewport(opts: {
   pane: HTMLElement
   surface: HTMLElement
+  gestureArea?: HTMLElement
   viewport: ViewportLike | null
 }): () => void {
-  const { pane, surface, viewport } = opts
+  const { pane, surface, gestureArea = surface, viewport } = opts
   if (!viewport) return () => {}
 
   const apply = () => {
     if (zoomedIn(viewport)) {
       surface.style.touchAction = 'auto'
+      gestureArea.style.touchAction = 'auto'
       return
     }
     surface.style.touchAction = ''
+    gestureArea.style.touchAction = ''
     pane.style.height = `${viewport.height}px`
     pane.style.translate = `0px ${viewport.offsetTop}px`
   }
@@ -83,6 +86,7 @@ export function trackVisualViewport(opts: {
     if (viewport.onresize === apply) viewport.onresize = null
     if (viewport.onscroll === apply) viewport.onscroll = null
     surface.style.touchAction = ''
+    gestureArea.style.touchAction = ''
     pane.style.height = ''
     pane.style.translate = ''
   }
diff --git a/web/src/styles.css b/web/src/styles.css
index b594cec..318aeab 100644
--- a/web/src/styles.css
+++ b/web/src/styles.css
@@ -424,6 +424,12 @@
 @utility flue-term-surface {
   block-size: 100%;
   inline-size: 100%;
+}
+
+/* The inset is the gesture surface, including any blank space beside a
+ * cross-device scaled screen. Keeping this on the full usable pane means a
+ * scroll does not depend on whether the first pixel happened to hit xterm. */
+@utility flue-term-gesture {
   /* Single-finger gestures are ours: touches become scrollLines() calls
    * (terminal.tsx), and a browser allowed to pan the page would eat them
    * first. The pinch stays with the browser — `none` here once made the
diff --git a/web/src/testing/emulator.ts b/web/src/testing/emulator.ts
index 2aada1f..d1f9aed 100644
--- a/web/src/testing/emulator.ts
+++ b/web/src/testing/emulator.ts
@@ -27,6 +27,8 @@ export interface FakeEmulator extends Emulator {
   appCursor: boolean
   /** Simulate the user typing. */
   send(text: string): void
+  /** Text handed to paste(), in order. */
+  readonly pasted: string[]
 }
 
 /**
@@ -45,11 +47,13 @@ export function createFakeEmulator(opts: FakeEmulatorOptions = {}): FakeEmulator
   const written: string[] = []
   const themes: TerminalTheme[] = []
   const queryAnswers: boolean[] = []
+  const pasted: string[] = []
 
   const self: FakeEmulator = {
     written,
     themes,
     queryAnswers,
+    pasted,
     cols: opts.cols ?? 80,
     rows: opts.rows ?? 24,
     mountedOn: null,
@@ -90,6 +94,11 @@ export function createFakeEmulator(opts: FakeEmulatorOptions = {}): FakeEmulator
       listeners.push(cb)
     },
 
+    paste(text: string) {
+      pasted.push(text)
+      self.send(text)
+    },
+
     attachTo(el: HTMLElement) {
       mutable(self).mountedOn = el
     },