Handle mobile keyboard viewport signals

server/mobile.test.mjs

@@ -146,6 +146,15 @@ try {
     Object.defineProperty(window, 'visualViewport', {
       configurable: true, value: viewport,
     });
+    const virtualKeyboard = new EventTarget();
+    virtualKeyboard.boundingRect = new DOMRect(0, 667, 375, 0);
+    Object.defineProperty(navigator, 'virtualKeyboard', {
+      configurable: true, value: virtualKeyboard,
+    });
+    window.__setVirtualKeyboard = (top, height, width = viewport.width) => {
+      virtualKeyboard.boundingRect = new DOMRect(0, top, width, height);
+      virtualKeyboard.dispatchEvent(new Event('geometrychange'));
+    };
     window.__setVisualViewport = (height, offsetTop, width = viewport.width) => {
       viewport.width = width;
       viewport.height = height;
@@ -154,6 +163,18 @@ try {
       viewport.dispatchEvent(new Event('resize'));
       viewport.dispatchEvent(new Event('scroll'));
     };
+    // Safari can fire with the final height but a stale zero offset, then update
+    // offsetTop without another event. Focus stabilization must catch that.
+    window.__setVisualViewportLate = (height, offsetTop, delay = 80) => {
+      viewport.height = height;
+      viewport.offsetTop = 0;
+      viewport.pageTop = 0;
+      viewport.dispatchEvent(new Event('resize'));
+      setTimeout(() => {
+        viewport.offsetTop = offsetTop;
+        viewport.pageTop = offsetTop;
+      }, delay);
+    };
   });
   const page = await context.newPage();
   await page.goto(WEB, { waitUntil: 'domcontentloaded' });
@@ -261,9 +282,44 @@ try {
     Math.abs(returnedScroll.top - returnedScroll.max) < 2,
     JSON.stringify(returnedScroll));
 
-  const beforeKeyboardGrid = latestGrid();
+  const fullKeyboardGrid = latestGrid();
   await page.locator('.term-host').click();
-  await page.evaluate(() => window.__setVisualViewport(360, 118));
+  const mobileInputAnchor = await page.evaluate(() => {
+    const host = document.querySelector('.term-host').getBoundingClientRect();
+    const node = document.querySelector('.term-host .xterm-helper-textarea');
+    const input = node.getBoundingClientRect();
+    return {
+      ok: input.width >= 1 && input.height >= 1
+        && input.top >= host.bottom - 5 && input.left > host.left && input.right < host.right,
+      host: { top: host.top, right: host.right, bottom: host.bottom, left: host.left },
+      input: { top: input.top, right: input.right, bottom: input.bottom, left: input.left,
+        width: input.width, height: input.height },
+      style: node.getAttribute('style'),
+    };
+  });
+  check('the focused xterm input is anchored at the mobile terminal bottom',
+    mobileInputAnchor.ok, JSON.stringify(mobileInputAnchor));
+
+  // Embedded Chromium can leave the child visual viewport unchanged but expose
+  // the OSK rectangle. Ensure that independent signal clips the app and PTY.
+  await page.evaluate(() => window.__setVirtualKeyboard(430, 237));
+  const geometryResized = await waitFor(() => latestGrid()?.rows < fullKeyboardGrid.rows);
+  const geometryLayout = await page.locator('.app').evaluate((node) => {
+    const box = node.getBoundingClientRect();
+    const keybar = document.querySelector('.term-keybar')?.getBoundingClientRect();
+    return { top: box.top, bottom: box.bottom, height: box.height, keybarBottom: keybar?.bottom ?? null };
+  });
+  check('keyboard geometry resizes an embedded mobile terminal without viewport changes',
+    geometryResized && Math.abs(geometryLayout.height - 430) < 1
+      && geometryLayout.keybarBottom <= 430,
+    JSON.stringify({ geometryResized, geometryLayout, grid: latestGrid() }));
+  await page.evaluate(() => window.__setVirtualKeyboard(667, 0));
+  const geometryClosed = await waitFor(() => latestGrid()?.rows >= fullKeyboardGrid.rows);
+  check('clearing embedded keyboard geometry restores the terminal', geometryClosed,
+    JSON.stringify(latestGrid()));
+
+  const beforeKeyboardGrid = latestGrid();
+  await page.evaluate(() => window.__setVisualViewportLate(360, 118));
   const keyboardResized = await waitFor(() => {
     const frame = latestGrid();
     return frame?.controller === false && frame?.rows < beforeKeyboardGrid.rows;

web/src/App.tsx

@@ -106,20 +106,66 @@ export default function App() {
   // The CSS variables pin the app to that viewport's exact rectangle.
   useEffect(() => {
     const vv = window.visualViewport;
-    if (!vv) return;
+    type VirtualKeyboardLike = EventTarget & { boundingRect?: DOMRectReadOnly };
+    const keyboard = (navigator as Navigator & { virtualKeyboard?: VirtualKeyboardLike }).virtualKeyboard;
+    if (!vv && !keyboard) return;
     const apply = () => {
+      const keyboardRect = keyboard?.boundingRect;
+      const left = vv?.offsetLeft ?? 0;
+      const top = vv?.offsetTop ?? 0;
+      const width = vv?.width ?? document.documentElement.clientWidth;
+      let height = vv?.height ?? window.innerHeight;
+      // Chromium can expose keyboard geometry even when an embedded document's
+      // visual viewport is unchanged. Never grow the visual viewport from it;
+      // only clip an actually overlapping keyboard.
+      if (keyboardRect && keyboardRect.height > 0 && keyboardRect.top > top) {
+        height = Math.min(height, keyboardRect.top - top);
+      }
       const root = document.documentElement.style;
-      root.setProperty('--vvw', `${Math.round(vv.width)}px`);
-      root.setProperty('--vvh', `${Math.round(vv.height)}px`);
-      root.setProperty('--vv-top', `${Math.round(vv.offsetTop)}px`);
-      root.setProperty('--vv-left', `${Math.round(vv.offsetLeft)}px`);
+      root.setProperty('--vvw', `${Math.round(width)}px`);
+      root.setProperty('--vvh', `${Math.round(height)}px`);
+      root.setProperty('--vv-top', `${Math.round(top)}px`);
+      root.setProperty('--vv-left', `${Math.round(left)}px`);
+    };
+
+    // WebKit may dispatch the keyboard viewport event before offsetTop has its
+    // final value, then correct the property without another event. Re-read at
+    // the end of the event turn and while the focus animation settles.
+    let settleTimer: ReturnType<typeof setTimeout> | null = null;
+    const focusTimers = new Set<ReturnType<typeof setTimeout>>();
+    const onViewportChange = () => {
+      apply();
+      if (settleTimer) clearTimeout(settleTimer);
+      settleTimer = setTimeout(() => { settleTimer = null; apply(); }, 80);
+    };
+    const stabilizeFocus = () => {
+      for (const timer of focusTimers) clearTimeout(timer);
+      focusTimers.clear();
+      for (const delay of [0, 50, 150, 300, 500, 800]) {
+        const timer = setTimeout(() => { focusTimers.delete(timer); apply(); }, delay);
+        focusTimers.add(timer);
+      }
     };
     apply();
-    vv.addEventListener('resize', apply);
-    vv.addEventListener('scroll', apply);
+    vv?.addEventListener('resize', onViewportChange);
+    vv?.addEventListener('scroll', onViewportChange);
+    vv?.addEventListener('scrollend', onViewportChange);
+    keyboard?.addEventListener('geometrychange', onViewportChange);
+    window.addEventListener('resize', onViewportChange);
+    window.addEventListener('orientationchange', stabilizeFocus);
+    document.addEventListener('focusin', stabilizeFocus);
+    document.addEventListener('focusout', stabilizeFocus);
     return () => {
-      vv.removeEventListener('resize', apply);
-      vv.removeEventListener('scroll', apply);
+      if (settleTimer) clearTimeout(settleTimer);
+      for (const timer of focusTimers) clearTimeout(timer);
+      vv?.removeEventListener('resize', onViewportChange);
+      vv?.removeEventListener('scroll', onViewportChange);
+      vv?.removeEventListener('scrollend', onViewportChange);
+      keyboard?.removeEventListener('geometrychange', onViewportChange);
+      window.removeEventListener('resize', onViewportChange);
+      window.removeEventListener('orientationchange', stabilizeFocus);
+      document.removeEventListener('focusin', stabilizeFocus);
+      document.removeEventListener('focusout', stabilizeFocus);
       document.documentElement.style.removeProperty('--vvw');
       document.documentElement.style.removeProperty('--vvh');
       document.documentElement.style.removeProperty('--vv-top');

web/src/components/TerminalPane.tsx

@@ -235,6 +235,24 @@ export default function TerminalPane({
     term.loadAddon(new (ClipboardAddon as unknown as new (b: Base64, p: typeof clipboardProvider) => ClipboardAddon)(new Base64(), clipboardProvider));
     term.open(hostRef.current!);
     termRef.current = term;
+    const host = hostRef.current!;
+
+    // xterm deliberately parks its real textarea far off-screen. That is fine
+    // with a hardware keyboard, but a mobile browser (especially a Space inside
+    // a cross-origin iframe) has no visible focus target to pan above the OSK.
+    // Keep the still-transparent 1px input at the bottom of the terminal so the
+    // browser's native focused-element avoidance can cross the iframe boundary.
+    const mobileInput = isMobile
+      ? host.querySelector<HTMLTextAreaElement>('.xterm-helper-textarea')
+      : null;
+    const anchorMobileInput = () => {
+      if (!mobileInput) return;
+      // xterm rewrites left/top whenever its cursor moves. Custom properties
+      // survive those writes and feed the mobile !important rules in CSS.
+      mobileInput.style.setProperty('--am-input-left', `${Math.max(1, Math.round(host.clientWidth / 2))}px`);
+      mobileInput.style.setProperty('--am-input-top', `${Math.max(1, host.clientHeight - 12)}px`);
+    };
+    anchorMobileInput();
 
     // Track the user's semantic scroll state independently of the viewport's
     // pixel scrollTop. During a row-count change xterm can transiently report
@@ -253,7 +271,6 @@ export default function TerminalPane({
       const text = term.hasSelection() ? selectionText(term) : lastSelection;
       if (text) copyText(text);
     };
-    const host = hostRef.current!;
     const onCopy = (e: ClipboardEvent) => {
       if (!term.hasSelection()) return;
       const text = selectionText(term);
@@ -452,6 +469,7 @@ export default function TerminalPane({
     // ResizeObserver fires every frame while a window is dragged or the sidebar
     // animates. Ask once, when it stops.
     const resync = () => {
+      anchorMobileInput();
       if (resyncTimer) clearTimeout(resyncTimer);
       resyncTimer = setTimeout(() => { resyncTimer = null; requestSize(); }, 80);
     };

web/src/styles.css

@@ -1045,6 +1045,15 @@ a.btn-ghost { text-decoration: none; }
     overflow: hidden;
   }
   .term-host { touch-action: none; overscroll-behavior: contain; }
+  /* Keep xterm's transparent real input at the visible prompt edge. xterm
+     normally parks/moves it for desktop IME behavior; on phones this element
+     is also the browser's only clue about what must remain above the OSK. */
+  .term-host .xterm-helper-textarea {
+    left: var(--am-input-left, 50%) !important;
+    top: var(--am-input-top, calc(100% - 2px)) !important;
+    width: 1px !important;
+    height: 1px !important;
+  }
   .app.m-home .main { display: none; }
   .app.m-home .sidebar { width: 100%; border-right: none; }
   .app.m-stage .sidebar { display: none; }