Files
fusion/docs/solutions/ui-bugs/android-mobile-terminal-visual-viewport-width.md
gsxdsm 8d7abb8c33 FN-7447: fix Android terminal mobile viewport sizing
Fix Android keyboard-open terminal layout by sizing mobile shells from the visual viewport.

- Track visualViewport width in the terminal modal and mobile keyboard detection.
- Apply keyboard-constrained mobile terminal sizing even when CSS media queries see a wider layout viewport.
- Cover Android visualViewport width behavior with modal, session terminal, and hook regressions.
- Document the fix pattern and add a patch changeset for the published Fusion package.

Files changed:
 .../fn-7447-android-mobile-terminal-spacing.md     |  7 ++
 ...ndroid-mobile-terminal-visual-viewport-width.md | 26 ++++++++
 .../dashboard/app/components/TerminalModal.css     | 21 +++++-
 .../dashboard/app/components/TerminalModal.tsx     |  8 +++
 .../__tests__/SessionTerminal.mobile.test.tsx      | 40 +++++++++++-
 .../components/__tests__/TerminalModal.test.tsx    | 76 ++++++++++++++++++++++
 .../app/hooks/__tests__/useMobileKeyboard.test.ts  | 38 +++++++++++
 packages/dashboard/app/hooks/useMobileKeyboard.ts  | 10 ++-
 8 files changed, 222 insertions(+), 4 deletions(-)

Fusion-Task-Id: FN-7447

Fusion-Task-Lineage: c01faf0f-842e-4632-bf8f-ae54070c3bf8

Co-authored-by: Fusion (runfusion.ai) <noreply@runfusion.ai>
2026-07-02 13:51:25 -07:00

1.5 KiB

category, module, tags, problem_type, applies_when
category module tags problem_type applies_when
ui-bug dashboard-terminal
android
mobile
visualViewport
xterm
keyboard
layout-regression Terminal or xterm surfaces render in a mobile shell while Android Chrome reports a visualViewport narrower than the layout viewport.

Android terminal spacing with keyboard-open visualViewport width

Problem

Android Chrome can keep window.innerWidth at a tablet/layout width while window.visualViewport.width is the narrow visible pane with the soft keyboard open. If a terminal switches to mobile UI from the visual viewport but sizes the modal or keyboard tracking from the layout viewport, xterm can fit against a stale wide box and render ASCII filenames with excessive spacing/wrapping at small persisted font sizes such as 10px.

Fix pattern

  • Treat touch-primary visualViewport.width as part of mobile detection for terminal keyboard handling.
  • Publish both --vv-height and --vv-width while keyboard overlap is present.
  • Apply keyboard-constrained terminal sizing on the explicit mobile class, not only inside @media (max-width: 768px), because CSS media queries still see the layout viewport.
  • Keep xterm's measured fontFamily symbols-free and verify 10px font preferences still trigger fit/resize/refresh.

Regression command

pnpm --filter @fusion/dashboard exec vitest run app/components/__tests__/TerminalModal.test.tsx app/components/__tests__/SessionTerminal.mobile.test.tsx app/hooks/__tests__/useMobileKeyboard.test.ts --silent=passed-only --reporter=dot