Merge pull request #51 from huggingface/mobile/reader-touch-and-keyboard

Reader on a phone: scroll the trace, and an instrument for the keyboard gap

web/src/App.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { lazy, Suspense, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import Sidebar from './components/Sidebar';
 import TerminalPane from './components/TerminalPane';
 import FilesPane from './components/FilesPane';
@@ -19,6 +19,12 @@ import { onPaneMode, readPaneMode, writePaneMode } from './lib/paneMode';
 import { isPassive, isRemote } from './types';
 import { GridGlyph, ListGlyph } from './components/icons';
 
+// `?vvdebug=1` — a phone has no devtools, and the keyboard layout is a guess
+// when the app is embedded cross-origin. Read once: it never changes mid-run,
+// and lazily imported so a debug surface is not part of the shipped bundle.
+const VV_DEBUG = new URLSearchParams(location.search).has('vvdebug');
+const ViewportDebug = lazy(() => import('./components/ViewportDebug'));
+
 // Phone-sized viewport: the app becomes two full-screen views (list ⇄ pane).
 function useIsMobile() {
   const [m, setM] = useState(() => window.matchMedia('(max-width: 720px)').matches);
@@ -111,10 +117,13 @@ export default function App() {
 
   // Track the visual viewport so the mobile layout can sit above the on-screen
   // keyboard (which shrinks visualViewport but not the layout viewport on iOS).
-  // The CSS variables pin the app to that viewport's exact rectangle. The Hub
-  // page embeds the app in a cross-origin iframe; mobile Safari leaves that
-  // child viewport unchanged when its keyboard opens. In that one no-signal
-  // case, fall back to a conservative focus-derived visible height.
+  // The CSS variables pin the app to that viewport's exact rectangle.
+  //
+  // Where there is no signal — the Hub page embeds the app in a cross-origin
+  // iframe, and mobile Safari leaves that child viewport unchanged when its
+  // keyboard opens — the app reports the viewport it can see and stops there.
+  // It does not estimate one. Nothing here knows how tall a keyboard is, and
+  // the browser that does already scrolls a focused field into view.
   useEffect(() => {
     const vv = window.visualViewport;
     type VirtualKeyboardLike = EventTarget & { boundingRect?: DOMRectReadOnly };
@@ -127,11 +136,12 @@ export default function App() {
     };
     const root = document.documentElement;
     const keyboardSignalThreshold = 80;
-    const embedded = window.self !== window.top;
-    let focusedInput: Element | null = null;
+    // The viewport as it was before a field took focus — the only thing left
+    // that needs remembering, because a keyboard is detected as the SHRINK from
+    // it (hasKeyboardGeometry), not as an absolute height. Since the estimate
+    // was deleted this feeds no layout at all: its one consumer is the
+    // keyboardLayout label, which only ?vvdebug=1 reads.
     let focusBaseline: ViewportBaseline | null = null;
-    let focusFallback = false;
-    let focusFallbackTimer: ReturnType<typeof setTimeout> | null = null;
 
     const acceptsKeyboardInput = (target: Element | null): target is HTMLElement => {
       if (!(target instanceof HTMLElement)) return false;
@@ -141,9 +151,6 @@ export default function App() {
       return !['button', 'checkbox', 'color', 'file', 'hidden', 'image', 'radio', 'range', 'reset', 'submit']
         .includes(target.type);
     };
-    const embeddedTouchLayout = () => embedded
-      && window.matchMedia('(max-width: 720px)').matches
-      && (navigator.maxTouchPoints > 0 || window.matchMedia('(pointer: coarse)').matches);
     const captureViewport = (): ViewportBaseline => ({
       width: vv?.width ?? document.documentElement.clientWidth,
       height: vv?.height ?? window.innerHeight,
@@ -172,20 +179,25 @@ export default function App() {
       if (keyboardRect && keyboardRect.height > 0 && keyboardRect.top > top) {
         height = Math.min(height, keyboardRect.top - top);
       }
-      if (hasKeyboardGeometry()) focusFallback = false;
-      if (focusFallback && focusBaseline && acceptsKeyboardInput(document.activeElement)) {
-        // The parent page owns the real visual viewport, but cross-origin frame
-        // isolation prevents us from reading it. A phone keyboard typically
-        // consumes roughly the lower half; 54% visible keeps the xterm prompt
-        // above it without disturbing direct-app browsers with real geometry.
-        const visibleRatio = focusBaseline.width > focusBaseline.height ? 0.48 : 0.54;
-        height = Math.min(height, Math.round(focusBaseline.height * visibleRatio));
-        root.dataset.keyboardLayout = 'focus-fallback';
-      } else if (hasKeyboardGeometry()) {
-        root.dataset.keyboardLayout = 'browser-geometry';
-      } else {
-        delete root.dataset.keyboardLayout;
-      }
+      // When the browser reports no keyboard geometry — a cross-origin frame on
+      // mobile Safari, which the Hub page is — the app does NOT invent a height.
+      // It used to assume a keyboard ate 46% and shrink to fit, and a guess that
+      // is wrong in the safe direction is still wrong: the abandoned strip does
+      // not stay hidden behind the keyboard, because the browser scroll-reveals
+      // a focused field and drags it back into view. That strip is the blank
+      // band under the reader's composer.
+      //
+      // What replaces it is the PARENT page's scroll, not ours: measured at
+      // 390x844, every box in this document — html, body, #root, .app, .main,
+      // .term-host, .pane-reader, .cxv — has a scroll range of exactly 0, so a
+      // scroll-into-view in here moves nothing. The reveal is entirely the
+      // embedder's, and this document's job is to not fight it by resizing
+      // itself against a keyboard it cannot see.
+      //
+      // Nothing below sizes anything: with the estimate gone, keyboardLayout is
+      // a label for ?vvdebug=1 to read. No CSS matches it.
+      if (hasKeyboardGeometry()) root.dataset.keyboardLayout = 'browser-geometry';
+      else delete root.dataset.keyboardLayout;
       root.style.setProperty('--vvw', `${Math.round(width)}px`);
       root.style.setProperty('--vvh', `${Math.round(height)}px`);
       root.style.setProperty('--vv-top', `${Math.round(top)}px`);
@@ -217,54 +229,29 @@ export default function App() {
         focusTimers.add(timer);
       }
     };
-    const scheduleEmbeddedFallback = () => {
-      if (focusFallbackTimer) clearTimeout(focusFallbackTimer);
-      focusFallbackTimer = null;
-      if (!embeddedTouchLayout() || !acceptsKeyboardInput(document.activeElement)) return;
-      focusFallbackTimer = setTimeout(() => {
-        focusFallbackTimer = null;
-        if (document.activeElement === focusedInput && !hasKeyboardGeometry()) {
-          focusFallback = true;
-          apply();
-        }
-      }, 500);
-    };
     const onFocusIn = (event: FocusEvent) => {
       const target = event.target instanceof Element ? event.target : null;
-      if (acceptsKeyboardInput(target)) {
-        focusedInput = target;
-        focusBaseline = captureViewport();
-        focusFallback = false;
-        stabilizeFocus();
-        scheduleEmbeddedFallback();
-        return;
-      }
+      // Only when there is no baseline yet: tapping from one field straight to
+      // another keeps the keyboard up, and re-reading here would take the
+      // shrunk viewport as the "before" — after which the shrink measures zero
+      // and a keyboard that is plainly up reads as absent. focusout clears it
+      // when focus really leaves, so this stays fresh without being re-taken.
+      if (acceptsKeyboardInput(target) && !focusBaseline) focusBaseline = captureViewport();
       stabilizeFocus();
     };
     const onFocusOut = () => {
-      if (focusFallbackTimer) clearTimeout(focusFallbackTimer);
-      focusFallbackTimer = null;
       const timer = setTimeout(() => {
         focusTimers.delete(timer);
         if (!acceptsKeyboardInput(document.activeElement)) {
-          focusedInput = null;
           focusBaseline = null;
-          focusFallback = false;
           apply();
         }
       }, 0);
       focusTimers.add(timer);
     };
     const onOrientationChange = () => {
-      if (focusFallbackTimer) clearTimeout(focusFallbackTimer);
-      focusFallbackTimer = null;
-      focusFallback = false;
-      if (acceptsKeyboardInput(document.activeElement)) {
-        focusedInput = document.activeElement;
-        focusBaseline = captureViewport();
-      }
+      if (acceptsKeyboardInput(document.activeElement)) focusBaseline = captureViewport();
       stabilizeFocus();
-      scheduleEmbeddedFallback();
     };
     apply();
     vv?.addEventListener('resize', onViewportChange);
@@ -278,7 +265,6 @@ export default function App() {
     return () => {
       for (const timer of settleTimers) clearTimeout(timer);
       for (const timer of focusTimers) clearTimeout(timer);
-      if (focusFallbackTimer) clearTimeout(focusFallbackTimer);
       vv?.removeEventListener('resize', onViewportChange);
       vv?.removeEventListener('scroll', onViewportChange);
       vv?.removeEventListener('scrollend', onViewportChange);
@@ -823,6 +809,10 @@ export default function App() {
         onToggleDemo={toggleDemo}
       />
       )}
+    {/* Outside .app: it reports where .app was put. That does not make it
+        immune — it is fixed too, so a displaced fixed subtree would carry it
+        along — but the history it keeps still shows the displacement happening. */}
+    {VV_DEBUG && <Suspense fallback={null}><ViewportDebug /></Suspense>}
     <div className={`app${settingsOpen ? ' app-suspended' : ''}${isMobile ? (mobileStage ? ' m-stage' : ' m-home') : ''}`}>
       {showWelcome && <Welcome onClose={dismissWelcome} />}
       {toast && <div className="toast mono" role="alert">{toast}</div>}

web/src/components/TerminalPane.tsx

@@ -208,6 +208,9 @@ export default function TerminalPane({
   const resyncRef = useRef<() => void>(() => {});
   const reconcileScrollRef = useRef<() => void>(() => {});
   const claimRef = useRef<() => void>(() => {});
+  // Reachable from the mode switch: a flick can still be coasting through the
+  // terminal's scrollback when the reader covers it.
+  const stopGlideRef = useRef<() => void>(() => {});
   const reconnectRef = useRef<() => void>(() => {});
   const controllerRef = useRef(false);
   const previousZoomRef = useRef(zoom);
@@ -624,16 +627,19 @@ export default function TerminalPane({
     // gesture without moving xterm's viewport, leaving no reliable way back
     // through history on touch-only devices. xterm 5.5 registers no touch
     // listeners of its own (verified against the bundled lib) and .term-host
-    // sets touch-action:none on mobile, so neither xterm nor the browser will
-    // pan: this is the only touch scrolling a phone has, in every pane.
+    // sets touch-action:none on mobile while the terminal is what you see, so
+    // neither xterm nor the browser will pan: this is the only touch scrolling
+    // a phone has, in every pane. Reader mode is the exception at both ends —
+    // it hands touch-action back (.term-host.reading) and these handlers stand
+    // down — because there the scroller you mean to drag is its own.
     //
     // Convert the drag to whole rows and carry the remainder in `residual`.
     // Quantising each event to a fixed notch instead silently drops whatever
     // does not fill one — a 96px drag moved the view 68px — and that shortfall
     // is what reads as lag, because the text trails the finger by design.
     // scrollLines moves ydisp, the authority the viewport follows.
-    // The frame, not the inner measurement box: .term-host is what carries
-    // touch-action:none and what the user actually drags, and it stays the
+    // The frame, not the inner measurement box: .term-host is what carries the
+    // touch-action rule and what the user actually drags, and it stays the
     // gesture target however the box inside it is nested.
     const frame = frameRef.current ?? host;
     const viewport = host.querySelector<HTMLElement>('.xterm-viewport');
@@ -656,7 +662,14 @@ export default function TerminalPane({
       return rows;
     };
     const stopGlide = () => { if (glideFrame) { cancelAnimationFrame(glideFrame); glideFrame = 0; } };
+    stopGlideRef.current = stopGlide;
+    // Reader mode covers this frame with its own scroller. These listeners sit
+    // on .term-host in CAPTURE and preventDefault, so without this guard every
+    // drag over the conversation was eaten here and spent on the hidden
+    // terminal's scrollback: the trace could not be scrolled back at all on a
+    // phone, which is the only place this gesture exists.
     const onTouchStart = (e: TouchEvent) => {
+      if (modeRef.current === 'reader') return;
       stopGlide();               // a new touch takes over from any coasting
       velocity = 0;
       residual = 0;
@@ -664,6 +677,7 @@ export default function TerminalPane({
       lastMoveAt = e.timeStamp;
     };
     const onTouchMove = (e: TouchEvent) => {
+      if (modeRef.current === 'reader') return;
       if (touchY == null || !e.touches.length) return;
       const y = e.touches[0].clientY;
       const deltaY = touchY - y;
@@ -691,6 +705,10 @@ export default function TerminalPane({
       touchY = null;
       const v0 = velocity;
       velocity = 0;
+      // A drag that began on the terminal and ended after the switch flipped
+      // must not launch anything: the mode is broadcast app-wide, so the flip
+      // can come from another pane rather than from this hand.
+      if (modeRef.current === 'reader') return;
       // Only a flick coasts. A slow, deliberate drag through history must land
       // exactly where the finger left it — drifting past the line someone was
       // reading is worse than having no momentum at all. 0.4px/ms is about
@@ -803,7 +821,10 @@ export default function TerminalPane({
   // with focus swallows every keystroke into the agent's TTY, invisibly. Hand
   // focus back when the terminal is on top again.
   useEffect(() => {
-    if (reading) termRef.current?.blur();
+    // The glide too: a flick left coasting under the reader keeps moving a
+    // viewport nobody can see, and no touch can catch it — the handler that
+    // would stop it now stands down in this mode.
+    if (reading) { termRef.current?.blur(); stopGlideRef.current(); }
     else if (focused) termRef.current?.focus();
   }, [reading, focused]);
 
@@ -849,7 +870,11 @@ export default function TerminalPane({
           <button className="mini-btn ph-close" title="Close" onClick={(e) => { e.stopPropagation(); onClose(); }}><CloseGlyph /></button>
         </div>
       </div>
-      <div className="term-host" ref={frameRef}>
+      {/* `reading` releases the frame's touch-action: the phone rule pins it to
+          `none` so the drag handler above owns terminal panning, and that also
+          forbids the browser from panning anything nested inside — including
+          the reader's own scroller. */}
+      <div className={`term-host${reading ? ' reading' : ''}`} ref={frameRef}>
         <div className="term-fill" ref={hostRef} />
         {/* Reader mode draws OVER the terminal rather than replacing it: xterm needs
             layout to fit, and detaching tmux costs a repaint and can trip the

web/src/components/ViewportDebug.tsx

@@ -0,0 +1,85 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * A readout of the numbers the mobile keyboard layout is computed from
+ * (App.tsx: the visualViewport effect). iOS Safari has no devtools and the Hub
+ * page embeds the app cross-origin, so when the layout lands in the wrong place
+ * on a phone there is otherwise nothing to read. Opt in with `?vvdebug=1`.
+ *
+ * It keeps a short history, not just a live line: the interesting moment is the
+ * keyboard animation, and by the time a phone can be screenshotted that is over.
+ * A row is recorded only when something changed, so the tail of the list IS the
+ * transition — which value moved, and which one failed to follow.
+ *
+ * Writes through textContent on a frame loop rather than setState: this exists
+ * to measure a layout animation, and re-rendering the app every frame would
+ * perturb the thing being measured.
+ */
+const ROWS = 10;
+
+export default function ViewportDebug() {
+  const out = useRef<HTMLPreElement | null>(null);
+
+  useEffect(() => {
+    let frame = 0;
+    let last = '';
+    const history: string[] = [];
+    // vv.height while nothing is focused. Nothing multiplies it any more — the
+    // estimate is gone — but it is still the number to compare against once a
+    // keyboard is up: unchanged here means this document got no signal at all,
+    // and inside an iframe it is the FRAME's height, not the screen's.
+    let baseline = window.visualViewport?.height ?? window.innerHeight;
+
+    const num = (n: number) => String(Math.round(n)).padStart(4);
+    const active = () => {
+      const el = document.activeElement;
+      if (!(el instanceof HTMLElement)) return '-';
+      const cls = (el.className || '').split(/\s+/)[0];
+      return `${el.tagName.toLowerCase()}${cls ? `.${cls}` : ''}`.slice(0, 18);
+    };
+    const edges = (sel: string) => {
+      const el = document.querySelector(sel);
+      if (!el) return '   -    ';
+      const r = el.getBoundingClientRect();
+      return `${num(r.top)}${num(r.bottom)}`;
+    };
+
+    const read = () => {
+      const vv = window.visualViewport;
+      const root = document.documentElement;
+      const focused = document.activeElement instanceof HTMLElement
+        && /^(input|textarea)$/.test(document.activeElement.tagName.toLowerCase());
+      if (!focused) baseline = vv?.height ?? window.innerHeight;
+
+      // One fixed-width row per sample so a column of them reads as a timeline.
+      const row = [
+        `vv${num(vv?.height ?? -1)}@${num(vv?.offsetTop ?? -1)}`,
+        `css${(root.style.getPropertyValue('--vvh').trim() || '-').padStart(5)}@${(root.style.getPropertyValue('--vv-top').trim() || '-').padStart(4)}`,
+        `scr${num(document.scrollingElement?.scrollTop ?? 0)}`,
+        `app${edges('.app')}`,
+        `box${edges('.cxv-live textarea')}`,
+        (root.dataset.keyboardLayout || 'none').slice(0, 8),
+      ].join(' ');
+      if (row !== last) {
+        last = row;
+        history.push(row);
+        if (history.length > ROWS) history.shift();
+      }
+
+      if (out.current) {
+        out.current.textContent = [
+          `base ${Math.round(baseline)}  inner ${window.innerHeight}  vvw ${Math.round(vv?.width ?? -1)}`,
+          `screen ${window.screen.width}x${window.screen.height}  embed ${window.self !== window.top ? 'y' : 'n'}`,
+          `focus ${active()}`,
+          '',
+          ...history,
+        ].join('\n');
+      }
+      frame = requestAnimationFrame(read);
+    };
+    frame = requestAnimationFrame(read);
+    return () => cancelAnimationFrame(frame);
+  }, []);
+
+  return <pre className="vvdebug" ref={out} />;
+}

web/src/conversation.css

@@ -163,7 +163,7 @@ mark.cx-hit.on { background: var(--accent); color: var(--panel); }
    you scan for — still spanned the full width, so the two disagreed about where
    the conversation began. The pane is the measure: make it narrow and the
    conversation is narrow. */
-.cxv-body { flex: 1; min-height: 0; overflow-y: auto; background: var(--panel); padding: 4px 14px 30px; }
+.cxv-body { flex: 1; min-height: 0; overflow-y: auto; overscroll-behavior: contain; background: var(--panel); padding: 4px 14px 30px; }
 .cxv-col { display: flex; flex-direction: column; min-width: 0; }
 .cxv-msg { font-size: 11px; color: var(--muted); padding: 6px 0; }
 .cxv-foot {
@@ -174,12 +174,14 @@ mark.cx-hit.on { background: var(--accent); color: var(--panel); }
 .cxv-foot .cxv-path { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .cxv-foot .spacer { flex: 1; min-width: 4px; }
 
-/* the prompt band sticks: deep inside a long turn, the thing you want overhead
-   is what you asked for — not a row of numbers */
-.cxv-col .cx-prompt {
-  position: sticky; top: 0; z-index: 2;
-  background: color-mix(in srgb, var(--accent) 7%, var(--panel));
-}
+/* The prompt band used to stick to the top of this scroller, on the theory that
+   deep inside a long turn you want what you asked for overhead. In a pane-sized
+   reader it reads as the message refusing to scroll away — and on a phone,
+   where the band can be a third of what you can see, that is most of the screen
+   held back. It scrolls with everything else now; the tint is what marks it.
+   The opaque background that came with it went too: it existed so scrolling
+   content would not show through a floating band, and over .cxv-body's --panel
+   the base transparent tint composites to the same colour. */
 
 /* ---------- phone ---------- */
 @media (max-width: 720px) {

web/src/styles.css

@@ -523,6 +523,14 @@ body {
 /* transient error toast */
 .toast { position: fixed; bottom: 16px; left: 50%; transform: translateX(-50%); z-index: 300; max-width: 90vw; padding: 9px 14px; background: color-mix(in srgb, var(--danger) 92%, #000); color: #fff; border-radius: var(--r-md); font-size: 12.5px; box-shadow: 0 8px 28px rgb(0 0 0 / 0.3); animation: rise-in 0.16s ease-out; }
 
+/* ?vvdebug=1 — the mobile viewport readout. Above everything, transparent to
+   touch so it never becomes the reason a gesture misbehaves. */
+.vvdebug {
+  position: fixed; top: 0; left: 0; z-index: 999; margin: 0; padding: 4px 6px;
+  pointer-events: none; font-family: var(--font-mono); font-size: 9px; line-height: 1.35;
+  white-space: pre; color: #9ff; background: rgb(0 0 0 / 0.72); border-bottom-right-radius: 4px;
+}
+
 /* first-run welcome card */
 .welcome-backdrop { position: fixed; inset: 0; z-index: 200; display: flex; align-items: center; justify-content: center; padding: 20px; background: color-mix(in srgb, #000 55%, transparent); backdrop-filter: blur(3px); animation: rise-in 0.16s ease-out; }
 .welcome-card { width: 100%; max-width: 560px; max-height: 88vh; overflow-y: auto; display: flex; flex-direction: column; gap: 16px; background: var(--panel); border: 1px solid var(--border); border-radius: var(--r-xl); padding: 22px; box-shadow: 0 24px 60px rgb(0 0 0 / 0.35); }
@@ -1094,6 +1102,13 @@ a.btn-ghost { text-decoration: none; }
     overflow: hidden;
   }
   .term-host { touch-action: none; overscroll-behavior: contain; }
+  /* touch-action is intersected down the ancestor chain, so `none` here would
+     also forbid panning anything nested inside — the reader's scroller, and the
+     code blocks and tables inside it, which are `overflow-x: auto`. Hence
+     `auto` and not `pan-y`: a trace holds wide output, and pinning the axis
+     here would leave that unreachable sideways, the same bug one axis over.
+     The terminal's own drag handler is inert in this mode. */
+  .term-host.reading { touch-action: auto; }
   /* 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. */