fix(web): scroll terminal output with touch gestures

[shivamhwp]

Closes #2141

Touch drags in the web terminal selected text instead of scrolling, leaving mobile browsers stuck at the newest output in #2141.

Route vertical touch drags through the terminal's existing wheel behavior. Scrollback moves in both directions, full-screen programs receive their existing scroll input, and taps still focus the terminal or open links. Pointer activation also selects the touched split pane.

59 focused terminal tests and web typecheck pass. Four new touch cases fail on the baseline; scoped lint reports seven existing drawer warnings. In the isolated Chromium client, the same gesture changes scrollback from 87 to 77 and back to 87 after the fix; it stays at 87 before. Tapping an inactive split selects and focuses it. Physical iOS/Android browsers, native mobile, and remote/relay sessions were not exercised. Web and desktop share this terminal; native mobile uses a separate client. There are no provider, wire-contract, or settings changes.

Rebased onto main, which includes the device-ticket correction from #11304.

Before:

After:

Touch scrolling in both directions:

t3-2141-touch-scroll.mp4

Model: GPT-6. Harness: Codex in T3 Code.

Rebased on main 6f00d3881a197dd33c2cb43c6a11a9e759e56089. The patch is unchanged. All 121 terminal tests, web typecheck, scoped lint and diff checks pass after rebasing. Existing browser evidence remains applicable; physical iOS/Android browser testing remains unverified.

Real-app testing (Oct 13, 2026)

Tested on a real POCO F4 (Android 14, Chrome) against a dev server on this branch and on main, with seq 1 500 in the terminal drawer. GIFs are sped up 3x to 4x.

Main: dragging down doesn't scroll, and one drag selects line 494	This PR: dragging down shows older lines, dragging up goes back

Line numbers on this PR: 488–500, then 479–493, 470–484, 461–475 after three drags down, then back to 470–484 and 479–493 after two drags up. All 5 drags scrolled; none were treated as a tap. The page itself doesn't move while dragging inside the terminal.

This PR: dragging inside less scrolls both ways	This PR: long-press opens the menu, but Copy is greyed out

Known gap: on main a touch drag selects text, which was the bug but also the only way to select terminal text by touch. On this PR every drag scrolls and long-press doesn't start a selection, so touch users can't select or copy terminal text.

Full recordings: main drag, PR drag, PR less, PR long-press.

[macroscopeapp]

Approvability

Verdict: Approved at de4886e

Macroscope's review found this PR approvable — This is a focused web-terminal bug fix that adds touch scrolling through the existing scroll paths and preserves tap, link, alternate-screen, and mouse-tracking behavior. The implementation is localized and covered by targeted tests, with no schema, deployment, security, billing, default, or static-analysis changes.

Notes:

• Diff unchanged. Approvability was decided on eligibility alone.

No code changes detected at e6ae306. Prior analysis still applies.

^{You can add or adjust custom eligibility rules. Learn more.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	20.9 KiB	20.9 KiB	0 B (0.0%)	29.3 KiB	✅
Codex	Live turn messages	2	2	0 (0.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Claude	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.2 KiB	21.2 KiB	0 B (0.0%)	29.3 KiB	✅
Claude	Live turn messages	2	2	0 (0.0%)	8	✅

Baseline: 9c9ae43 · PR result: e6ae306 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Advanced
• Run ID: 835065c1-87c2-4d1e-9222-58bd6498a1b8

📥 Commits

Reviewing files that changed from the base of the PR and between de4886e and 9f78b49.

📒 Files selected for processing (3)

• apps/web/src/components/ThreadTerminalDrawer.tsx
• apps/web/src/terminal/ghostty/surface.test.ts
• apps/web/src/terminal/ghostty/surface.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review.

📝 Walkthrough

The terminal surface now supports touch-drag scrolling and touch-aware link and mouse-reporting behavior. Wheel and touch scrolling use a shared dispatch path. Terminal panes activate on pointer-down. Tests cover touch gestures, scrolling, and cancellation.

Changes: Terminal touch support

Layer / File(s)	Summary
Touch gesture lifecycle apps/web/src/terminal/ghostty/surface.ts, apps/web/src/components/ThreadTerminalDrawer.tsx, apps/web/src/terminal/ghostty/surface.test.ts	The surface tracks the primary touch pointer, captures events, and distinguishes taps, drags, and cancellations. Terminal panes activate on pointer-down. Tests cover link activation and multi-touch behavior.
Shared touch and wheel scrolling apps/web/src/terminal/ghostty/surface.ts, apps/web/src/terminal/ghostty/surface.test.ts	Wheel and touch scrolling use scrollRows. The shared path handles mouse reporting, alternate-screen cursor sequences, and scrollback. Tests cover scrolling in these modes.

Priority: ⬆️ High

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant TouchPointer
  participant GhosttyTerminalSurface
  participant TerminalBehavior
  TouchPointer->>GhosttyTerminalSurface: Send touch pointerdown
  GhosttyTerminalSurface->>GhosttyTerminalSurface: Track primary pointer
  TouchPointer->>GhosttyTerminalSurface: Send pointermove
  GhosttyTerminalSurface->>TerminalBehavior: Route whole scroll rows
  TouchPointer->>GhosttyTerminalSurface: Send pointerup
  GhosttyTerminalSurface->>TerminalBehavior: Handle tap if gesture did not move

Loading

Suggested reviewers: stienswout

Merge Risk: ⚪ Minimal · up to 9f78b

No merge-blocking issue is identified. Physical mobile-browser behavior remains untested, but that alone does not establish a defect.

Security architecture risk: 🔵 Low · up to 9f78b

Existing permissions and session routing remain in place. However, a touch tap can activate a link that changed while the finger was down, creating a limited risk of opening a destination the user did not intend.

Retained concerns

• Low · security · inferred: The touch path records pointer identity and movement but not the initial link. An unmoved release activates whichever permitted link is then under the finger. Terminal output replaced between press and release can therefore substitute a destination, unlike the base mouse path, which records and revalidates the original link. Existing authorization limits the outcome but does not preserve the user's initial target.

Security review details

Security Blast Radius

• inferred — The supported link-substitution scenario affects a user's tap on an output-influenced terminal surface. Its downstream effects are bounded by the existing URL-opening and path-opening permissions. Terminal writes remain bound to the viewport's environment, thread, and terminal identifiers; no cross-session authority expansion was established.

Security Findings and Attack Paths

• inferred — An output producer could replace a displayed link while a user holds a stationary touch. Release then selects the replacement destination without comparing it with the initial target. This is a source-supported action-binding concern, not a demonstrated exploit or a bypass of destination permissions.

Trust Boundaries and Controls

• observed — The existing mouse path stores the initial link and requires matching text and cell range at release. Touch preserves pointer ownership and cancellation controls but does not carry that initial link identity into its activation decision.

Resilience and Maintainability Implications

• observed — Disposal removes event listeners before disposing the terminal core and removing its DOM elements. Thus, uncleared touch state at disposal does not by itself establish later input or link activation through the installed handlers.

Pre-merge checks: 4

Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check		Issue #2141 requires touch scrolling in the mobile web terminal. surface.ts handles primary touch drags, converts vertical movement to terminal row scrolling, and reuses scrollRows for scrollback,…
Out of Scope Changes check		The diff is limited to web terminal touch handling, focused terminal tests, and split-pane pointer activation. These changes directly support issue #2141. No provider, wire-contract, settings, or unre…
Title check		The title is concise, specific, and accurately describes the primary change: enabling terminal output scrolling with touch gestures.
Description check		The description explains the problem, implementation, scope, verification results, known limitations, and includes before/after evidence. It also references the linked issue and identifies the model a…

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

_{Comment @coderabbitai help to get the list of available commands.}

Dismissing prior approval to re-evaluate de4886e