Merge pull request #674: fix(mobile): give a sideways drag on the terminal to the session swipe alone

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

src/web/CLAUDE.md

@@ -14,7 +14,7 @@
 
 **Tile grid** (`showTileGridButton`, header Tiles button + `Ctrl+Shift+G`, default ON on desktop and OFF on handhelds and touch-primary tablets (primary pointer coarse, `getDefaultSettings()`; a touchscreen laptop keeps ON), desktop-only at 1180px, per-device; tile-grid.js, design `docs/tile-grid-plan.md`): 1 to 6 live sessions side by side (the cap is ONE constant, `TILE_GRID_MAX` in constants.js, owner decision; the layout table still covers 7 to 9, unreachable), each a `TerminalTile` with a header (state dot, harness logo, name, model, menu, zoom, ×; no +, owner decision), laid out by count (`CodemanTileGrid`, constants.js) with draggable column/row dividers, zoom (tmux-style), an Attach overlay, and per-browser persistence (`codeman:tile-grid`, localStorage only: cells with `null` holes, `count`, focus, user zoom, divider fractions, never content; written on every change, kept by EVERY close, restored INSIDE `handleInit` in place of the single-view select, so the main terminal never loads on that page load). While the grid is open the main terminal is PARKED: `activeSessionId` is the focused tile's session, and every main-terminal path that would write, fetch, resize or reconnect stands aside through `_tilesOwnTerminal()` (the WebGL long-task observer included). ⚠️ Every capture a tile fetches (initial, reconnect refresh, `{t:'r'}`, history pull) goes through ONE `TileLoadQueue` (concurrency 1, a deadline covering the body), because each is a synchronous tmux call on the server. ⚠️ Only a USER-initiated pick of a non-tiled session (or `leaveTiles`, a followed link) leaves the grid; an `auto` selection never collapses it, and every app-driven fallback (close, delete, restore) picks a tile. A caller of `closeTileGrid({ reselect: false })` must null `activeSessionId` before any `_cleanupPreviousSession`, or the parked terminal's stale content is saved as a snapshot. ⚠️ The grid and the split are never open together. ⚠️ Tile chords go through `tileShortcutFor` and are swallowed in every xterm key handler BEFORE the Shift+Enter gate; the toggle follows `showTileGridButton` (owner decision: OFF makes the chord inert, it passes through like any unbound key). ⚠️ The Tiles button's click and Ctrl+Shift+G are ONE function, `toggleTileGrid` (owner decision): they open the grid AT ONCE on `tileGridOpenSet` (constants.js): the stored grid EXACTLY as the user left it (owner decision 11: `restoreTileGridCells`, never filled to the count nor trimmed to the window; a cell whose session is gone since is filled from the ranking, a hole the user made stays), else an open split's two, else the open sessions as `rankTileSessions` orders them (working first, keyed off `lastSubmitAt` ONLY, then needing input, then most recent; `_mobileOverviewState`'s states), the active one focused, filled to the remembered count (`codeman:tile-count`, default 6, at most `_tileGridLimit()`) by `tileGridSetForCount`, never a menu. ⚠️ `removeTile(..., { gone: true })` (a session deleted, popped out or refused) keeps the stored `count` so the next open refills that cell; a removal by hand lowers it. Right-click is the 2 / 4 / 6 count menu (`openTileCountMenu`, owner decision 10), which owns its Escape. The button has no native title: its hover card (`_installTileGridHint`, `#tileGridHint`) says it, is its `aria-describedby` (always present, hidden, kept current) and hides in the capture phase on any press, click or right-click, so the menu never opens beside it. ⚠️ The open, the count menu and the toggle's close animate opacity and transform only (the close leaves an inert cloned still copy until the single view's selection settles, at most 700 ms); nothing moves under `prefers-reduced-motion`. ⚠️ Opening builds one tile terminal per frame (`_connectTilesPaced`), so `openTileGrid` returns before the terminals exist: focus is handed over in `_connectTile` (`focusOnConnect`). ⚠️ A divider drag reflows locally per frame and sends ONE resize per affected tile at pointer-up. ⚠️ The grid is CELLS (owner: an empty cell can be any cell): `grid.cells` (id or `null`) is the one source of truth, `grid.ids` a derived getter, never written; the shape still comes from the tile count, a shape change goes through `fitTileCells`, and the stored `ids` carry the cells with `null` holes. ⚠️ A tile moves (its header dragged or its tab dropped onto another tile or an empty cell, `Ctrl+Shift+Arrows`) ONLY through `_reorderTiles`: never a remount, reconnect or reload, and since sizes belong to the cells only a tile whose cell size changed fits; off while a tile is zoomed. The header drag carries its own type, never text, and is not `draggedTabId`; the header focuses on click, never on press, so a cancelled drag changes nothing. The arrow chords skip text fields. ⚠️ Sessions Run from this tab join the open grid (`_joinTileGridFromRun`, called from `_ensureCreatedSessionVisible`); sessions created elsewhere never do. SuchLine truncated
 
-**Terminal touch gestures: link taps and text selection**: on touch devices xterm's linkifier and SelectionService never see the gesture, so both are driven explicitly (terminal-ui.js). ⚠️ A tap activates the link under it through the SAME provider as the hover linkifier (`_terminalLinkAtPoint`), synchronously inside `touchend` (keeps the user gesture `window.open` needs) and BEFORE any mouse report; the caret's logical line (`_tapIsOnCaretLine`) and TUI-owned rows (`_isActionableMobileTerminalTap`) keep their meaning. ⚠️ Gate on the caret line, never on tap intent (a shell calls every tap `'input'`). ⚠️ Long-press selects via xterm's public `select()`; keep the three guards: suppress the compat mouse pair after `touchend`, the bounded focus guard + `contextmenu` suppression for the platform long-press, and no closing `terminal.focus()` on phones. Tests: `test/terminal-touch-tap.test.ts`. → [architecture-invariants#terminal-touch-gestures-link-taps-and-text-selection](../../docs/architecture-invariants.md#terminal-touch-gestures-link-taps-and-text-selection)
+**Terminal touch gestures: link taps and text selection**: on touch devices xterm's linkifier and SelectionService never see the gesture, so both are driven explicitly (terminal-ui.js). ⚠️ A tap activates the link under it through the SAME provider as the hover linkifier (`_terminalLinkAtPoint`), synchronously inside `touchend` (keeps the user gesture `window.open` needs) and BEFORE any mouse report; the caret's logical line (`_tapIsOnCaretLine`) and TUI-owned rows (`_isActionableMobileTerminalTap`) keep their meaning. ⚠️ Gate on the caret line, never on tap intent (a shell calls every tap `'input'`). ⚠️ Long-press selects via xterm's public `select()`; keep the three guards: suppress the compat mouse pair after `touchend`, the bounded focus guard + `contextmenu` suppression for the platform long-press, and no closing `terminal.focus()` on phones. ⚠️ A sideways drag belongs to the session swipe (`SwipeHandler`, mobile-handlers.js): the touch handler locks the dominant axis on the first travel past the tap slop (`panAxis`: `y` scrolls, `x` pans a terminal wider than its box, `swipe` otherwise) and publishes it as `app._terminalGestureAxis`; a `swipe` drag neither scrolls nor ends as a tap on the session being left until it passes the swipe's own vertical drift limit (`SwipeHandler.maxVerticalDrift`), where it is handed back to the scroll as `y` (a scroll that opens on a thumb arc), and the swipe stands aside for `x`/`y`, a touch selection, a second finger and surfaces with controls of their own (`IGNORE_SELECTOR`; the phone overview and welcome screen are deliberately not listed). A swipe is 80 px within 500 ms with at most 50 px of vertical drift at any point; a touch starting outside the terminal (the home screen) resets the published axis, and a lift the terminal consumed (`defaultPrevented`, its selection gesture) is never a swipe (`test/session-swipe-gesture.test.ts`). Tests: `test/terminal-touch-tap.test.ts`. → [architecture-invariants#terminal-touch-gestures-link-taps-and-text-selection](../../docs/architecture-invariants.md#terminal-touch-gestures-link-taps-and-text-selection)
 
 **Auto Copy (copy-on-select)** (`autoCopySelection`, per-device, default OFF): a finished terminal selection lands on the clipboard with no keystroke. ⚠️ Copy at the END of a gesture, never in `onSelectionChange` (per-cell); it only arms `_autoCopyPending` and a document-level `mouseup` flushes. ⚠️ The flush must be SYNCHRONOUS in the handler (both clipboard paths need user activation); never defer it to a timer. ⚠️ Touch needs its own calls from `_endTouchSelectionGesture()`/`_selectTouchSelectionLine()` (no mouseup arrives). ⚠️ Unlike `copyTerminalSelection()`, never clear the selection or focus the terminal; restore prior focus. Guards are pure in `decideAutoCopy()` (constants.js, 1M-char cap, refused not truncated). Tests: `test/terminal-auto-copy.test.ts`. → [architecture-invariants#auto-copy-copy-on-select](../../docs/architecture-invariants.md#auto-copy-copy-on-select)
 

src/web/public/mobile-handlers.js

@@ -9,7 +9,7 @@
  *   toolbar/accessory bar repositioning, terminal resize on keyboard open/close,
  *   and input scroll-into-view. Uses 100px threshold for iOS address bar drift.
  * - SwipeHandler — Horizontal swipe detection on the terminal area for session switching.
- *   80px minimum distance, 300ms maximum time, 100px max vertical drift.
+ *   80px minimum distance, 500ms maximum time, 50px max vertical drift.
  *
  * All three have init()/cleanup() lifecycle methods. They are re-initialized after SSE
  * reconnect (in handleInit) to prevent stale closures.
@@ -758,14 +758,24 @@ const SwipeHandler = {
   startY: 0,
   startTime: 0,
   minSwipeDistance: 80, // Minimum pixels for a valid swipe
-  maxSwipeTime: 300, // Maximum ms for a swipe gesture
-  maxVerticalDrift: 100, // Max vertical movement allowed
+  // 300ms rejected an unhurried but deliberate swipe outright, which read as an
+  // unresponsive gesture rather than as "too slow".
+  maxSwipeTime: 500, // Maximum ms for a swipe gesture
+  maxVerticalDrift: 50, // Max vertical movement allowed, at any point of the gesture
 
   _touchStartHandler: null,
+  _touchMoveHandler: null,
   _touchEndHandler: null,
   _element: null,
   _ignoreGesture: false,
 
+  /**
+   * Surfaces inside `.main` that own their own gestures or controls: a swipe
+   * there must not switch sessions. The phone overview and welcome screen are
+   * deliberately NOT listed: swiping from home into a session is a feature.
+   */
+  IGNORE_SELECTOR: '.tile-grid, .term-select-bar, #cjkInput, .history-trunc-bar',
+
   /** Initialize swipe handling */
   init() {
     // Only on touch devices
@@ -776,8 +786,10 @@ const SwipeHandler = {
 
     this._element = terminal;
     this._touchStartHandler = (e) => this.onTouchStart(e);
+    this._touchMoveHandler = (e) => this.onTouchMove(e);
     this._touchEndHandler = (e) => this.onTouchEnd(e);
     terminal.addEventListener('touchstart', this._touchStartHandler, { passive: true });
+    terminal.addEventListener('touchmove', this._touchMoveHandler, { passive: true });
     terminal.addEventListener('touchend', this._touchEndHandler, { passive: true });
   },
 
@@ -785,9 +797,11 @@ const SwipeHandler = {
   cleanup() {
     if (this._element && this._touchStartHandler) {
       this._element.removeEventListener('touchstart', this._touchStartHandler);
+      this._element.removeEventListener('touchmove', this._touchMoveHandler);
       this._element.removeEventListener('touchend', this._touchEndHandler);
     }
     this._touchStartHandler = null;
+    this._touchMoveHandler = null;
     this._touchEndHandler = null;
     this._element = null;
   },
@@ -797,20 +811,43 @@ const SwipeHandler = {
     // here. Swiping across the open session drawer — the natural "dismiss it"
     // gesture — would otherwise fire nextSession() and drop the user into a
     // session they never tapped.
+    // The terminal's touch handler publishes the axis it locks for a gesture
+    // that starts on it; a touch that starts elsewhere in `.main` (the home
+    // screen) must not inherit the last one, or a terminal scroll a moment
+    // earlier vetoes a swipe from home. Reset before any early return.
+    if (typeof app !== 'undefined') app._terminalGestureAxis = null;
     this._ignoreGesture = !!e.target?.closest?.('.session-sidebar');
     if (this._ignoreGesture) return;
-    if (!e.touches || e.touches.length !== 1) return;
+    // A second finger makes this a different gesture (pinch, two-finger scroll):
+    // never measure a later lift against the first finger's start. Stays set
+    // until the next touchstart, so the first finger's lift cannot clear it.
+    if (!e.touches || e.touches.length !== 1) {
+      this._ignoreGesture = true;
+      return;
+    }
+    this._ignoreGesture = !!e.target?.closest?.(this.IGNORE_SELECTOR);
     this.startX = e.touches[0].clientX;
     this.startY = e.touches[0].clientY;
     this.startTime = Date.now();
   },
 
+  onTouchMove(e) {
+    if (this._ignoreGesture || !e.touches || e.touches.length !== 1) return;
+    if (Math.abs(e.touches[0].clientY - this.startY) > this.maxVerticalDrift) this._ignoreGesture = true;
+  },
+
   onTouchEnd(e) {
-    if (this._ignoreGesture) {
-      this._ignoreGesture = false;
-      return;
-    }
+    if (this._ignoreGesture) return;
     if (!e.changedTouches || e.changedTouches.length !== 1) return;
+    if (typeof app === 'undefined') return;
+    // The terminal's own touch handler (terminal-ui.js) runs first, on the same
+    // gesture: a drag it locked as a scroll or a pan is not a session swipe,
+    // and neither is a lift it consumed (its long-press selection gesture
+    // preventDefaults the touchend, even on blank space where no selection
+    // survives the lift). A swipe must not extend or drop a touch selection.
+    if (e.defaultPrevented) return;
+    if (app._terminalGestureAxis === 'y' || app._terminalGestureAxis === 'x') return;
+    if (app._touchSelecting || app._touchSelectionActive) return;
 
     const endX = e.changedTouches[0].clientX;
     const endY = e.changedTouches[0].clientY;
@@ -824,13 +861,8 @@ const SwipeHandler = {
     if (deltaY > this.maxVerticalDrift) return; // Too much vertical movement
     if (Math.abs(deltaX) < this.minSwipeDistance) return; // Too short
 
-    // Valid swipe detected
-    if (deltaX > 0) {
-      // Swipe right -> previous session
-      if (typeof app !== 'undefined') app.prevSession();
-    } else {
-      // Swipe left -> next session
-      if (typeof app !== 'undefined') app.nextSession();
-    }
+    // Valid swipe detected. Swipe right -> previous session, left -> next.
+    if (deltaX > 0) app.prevSession();
+    else app.nextSession();
   },
 };

src/web/public/terminal-ui.js

@@ -1200,8 +1200,13 @@ Object.assign(CodemanApp.prototype, {
       let longPressStartY = 0;
       let touchStartY = 0;
       let touchStartX = 0;
-      // 'x' | 'y' | null — locked on the first travel past the tap slop, so a
-      // diagonal drag cannot pan and scroll at the same time.
+      // 'x' | 'y' | 'swipe' | null — locked on the first travel past the tap
+      // slop, so a diagonal drag cannot pan and scroll at the same time. 'swipe'
+      // is a sideways drag on a terminal that cannot pan: it is the session
+      // swipe's (SwipeHandler, mobile-handlers.js), so it neither scrolls nor
+      // ends as a tap on the session being left. Published per gesture as
+      // `this._terminalGestureAxis`, which SwipeHandler reads to stand aside
+      // for a scroll or a pan.
       let panAxis = null;
       /**
        * Can this gesture pan sideways? Only while the terminal is wider than
@@ -1246,6 +1251,7 @@ Object.assign(CodemanApp.prototype, {
             touchStartY = touchLastY;
             touchStartX = touchLastX;
             panAxis = null;
+            this._terminalGestureAxis = null;
             velocity = 0;
             pixelAccum = 0;
             isTouching = true;
@@ -1319,10 +1325,10 @@ Object.assign(CodemanApp.prototype, {
             if (!didScroll) {
               const travelY = Math.abs(touchY - touchStartY);
               const travelX = Math.abs(touchX - touchStartX);
-              const sideways = canPanHorizontally() && travelX >= TAP_THRESHOLD;
-              if (travelY >= TAP_THRESHOLD || sideways) {
+              if (travelY >= TAP_THRESHOLD || travelX >= TAP_THRESHOLD) {
                 didScroll = true;
-                panAxis = sideways && travelX > travelY ? 'x' : 'y';
+                panAxis = travelX > travelY ? (canPanHorizontally() ? 'x' : 'swipe') : 'y';
+                this._terminalGestureAxis = panAxis;
               }
             }
             // Below the tap threshold, treat the gesture as a potential tap:
@@ -1333,6 +1339,17 @@ Object.assign(CodemanApp.prototype, {
             // fling, so a jittery tap would both position the cursor AND scroll.
             if (!didScroll) return;
             ev.preventDefault();
+            if (panAxis === 'swipe') {
+              // Past the swipe's own vertical drift limit the session swipe has
+              // given up, so the drag is a scroll after all: hand it to 'y'.
+              const drift = typeof SwipeHandler !== 'undefined' ? SwipeHandler.maxVerticalDrift : 50;
+              if (Math.abs(touchY - touchStartY) <= drift) return;
+              panAxis = 'y';
+              this._terminalGestureAxis = 'y';
+              touchLastX = touchX;
+              touchLastY = touchY;
+              return;
+            }
             if (panAxis === 'x') {
               // Pan the container, and touch nothing the vertical path owns —
               // no pixelAccum, no velocity, so touchend cannot turn a sideways