From 8074f67c6a57286196796246a782924dc44cf29a Mon Sep 17 00:00:00 2001
From: Codeman maintainer <noreply@anthropic.com>
Date: Wed, 28 Oct 2026 09:35:20 +0100
Subject: [PATCH] fix: keep the soft-keyboard recovery on Android with a fine
 pointer (release review, #726)

#726 attaches the keyCode 229 recovery only when (pointer: coarse)
matches, which keeps a desktop dead key from arriving twice. Chromium
reports the PRIMARY pointer as fine once a mouse, a trackpad cover or a
stylus is attached, so on such an Android device the module was off
while the text still came from the soft keyboard, and the #441 dropped
last character and the #541 autocorrect duplication came back.

The gate is now a coarse pointer OR an Android user agent. Android ran
the recovery unconditionally before #726, so this only keeps that; a
desktop (fine pointer, not Android) and a touchscreen laptop stay off.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/web/CLAUDE.md                             |  2 +-
 .../public/terminal-keycode229-recovery.js    | 22 +++++++++------
 test/terminal-keycode229-recovery.test.ts     | 28 +++++++++++++++++--
 3 files changed, 41 insertions(+), 11 deletions(-)

diff --git a/src/web/CLAUDE.md b/src/web/CLAUDE.md
index c04ac9c4..ed210de6 100644
--- a/src/web/CLAUDE.md
+++ b/src/web/CLAUDE.md
@@ -30,7 +30,7 @@
 
 ## Frontend modules and UI subsystems
 
-Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order is the `<script>` order in `index.html` (each module's `@loadorder` tag mirrors it). `i18n.js` translates static + newly inserted application DOM while skipping terminal/response/file/user-name surfaces; `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData). `terminal-keycode229-recovery.js` forwards a committed `input` event that xterm's `_inputEvent` guard drops (Chrome-on-Android soft keyboards send `composed: true` after a keydown), and only when xterm emitted no canonical data for that keystroke. ⚠️ **That decision is settled at the NEXT keydown as well as on its own zero-delay timer** (#441): the drain runs from xterm's custom key handler, which fires BEFORE xterm processes that key, so a soft keyboard that commits the last character and sends Enter in one InputConnection transaction puts the character on the wire ahead of the `\r`. On the timer alone that character is not merely late, it is LOST: xterm emits the `\r` first and bumps the canonical counter past the candidate's snapshot, so the candidate stands down (measured, `hell\r` where the user typed `hello`). The edit-based diff described below is settled first at that keydown, so the drain decides with the evidence the timer had and Enter's textarea clear cannot turn the pending line into DELs. Ordering is pinned by `test/terminal-keycode229-recovery.browser.test.ts`, which the CI gate does NOT run. The same module replaces xterm's `_handleAnyTextareaChanges` (an append-only `newValue.replace(oldValue, '')` diff) with an edit-based one, so an Android autocorrect on space (delete + insert) reaches the PTY once instead of duplicating the line; ⚠️ that diff is settled at the NEXT keydown, before xterm handles that key, because xterm clears the textarea for Enter and a pending diff would then send one DEL per character ahead of the submitted line (except a composition xterm finalizes synchronously at that key, which stays xterm's). ⚠️ Every xterm that takes keyboard input wires its OWN controller from this module (`create()` returns null unless `matchMedia('(pointer: coarse)')` matches, so a desktop dead key is not forwarded twice, #716): the primary pane (terminal-ui.js `initTerminal()`) and each `TerminalTile` (terminal-tile.js `_createKeyCode229Recovery()`, so every grid tile and the split's Pane B, which a wide Android tablet reaches), each on its own textarea, composition helper and session; in both, `handleKeyEvent` must run ABOVE the custom key handler's keyCode-229 early return, and `notifyCanonicalData` sits in the onData lambda, never in the send path the recovered bytes also take. `mobile-ime-preview.js` (iOS WebKit only) paints the text an IME is composing: an iOS IME commit is routed into the local-echo overlay through the ordinary printable/paste branch and then `_transferMobileImeCommitToLocalEcho`, and without local echo the preview clears only on output parsed AFTER the commit (or its 2 s fallback). ⚠️ It watches keydown in the capture phase on `terminal.element`, never on the textarea, because xterm finalizes the composition and emits the commit in its own capture listener on the textarea.
+Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. Load order is the `<script>` order in `index.html` (each module's `@loadorder` tag mirrors it). `i18n.js` translates static + newly inserted application DOM while skipping terminal/response/file/user-name surfaces; `input-cjk.js` handles CJK IME composition via an always-visible textarea below the terminal (`window.cjkActive` blocks xterm's onData). `terminal-keycode229-recovery.js` forwards a committed `input` event that xterm's `_inputEvent` guard drops (Chrome-on-Android soft keyboards send `composed: true` after a keydown), and only when xterm emitted no canonical data for that keystroke. ⚠️ **That decision is settled at the NEXT keydown as well as on its own zero-delay timer** (#441): the drain runs from xterm's custom key handler, which fires BEFORE xterm processes that key, so a soft keyboard that commits the last character and sends Enter in one InputConnection transaction puts the character on the wire ahead of the `\r`. On the timer alone that character is not merely late, it is LOST: xterm emits the `\r` first and bumps the canonical counter past the candidate's snapshot, so the candidate stands down (measured, `hell\r` where the user typed `hello`). The edit-based diff described below is settled first at that keydown, so the drain decides with the evidence the timer had and Enter's textarea clear cannot turn the pending line into DELs. Ordering is pinned by `test/terminal-keycode229-recovery.browser.test.ts`, which the CI gate does NOT run. The same module replaces xterm's `_handleAnyTextareaChanges` (an append-only `newValue.replace(oldValue, '')` diff) with an edit-based one, so an Android autocorrect on space (delete + insert) reaches the PTY once instead of duplicating the line; ⚠️ that diff is settled at the NEXT keydown, before xterm handles that key, because xterm clears the textarea for Enter and a pending diff would then send one DEL per character ahead of the submitted line (except a composition xterm finalizes synchronously at that key, which stays xterm's). ⚠️ Every xterm that takes keyboard input wires its OWN controller from this module (`create()` returns null unless `matchMedia('(pointer: coarse)')` matches or the user agent is Android, so a desktop dead key is not forwarded twice, #716, while an Android device whose mouse, trackpad cover or stylus Chromium reports as the fine primary pointer keeps the soft-keyboard recovery): the primary pane (terminal-ui.js `initTerminal()`) and each `TerminalTile` (terminal-tile.js `_createKeyCode229Recovery()`, so every grid tile and the split's Pane B, which a wide Android tablet reaches), each on its own textarea, composition helper and session; in both, `handleKeyEvent` must run ABOVE the custom key handler's keyCode-229 early return, and `notifyCanonicalData` sits in the onData lambda, never in the send path the recovered bytes also take. `mobile-ime-preview.js` (iOS WebKit only) paints the text an IME is composing: an iOS IME commit is routed into the local-echo overlay through the ordinary printable/paste branch and then `_transferMobileImeCommitToLocalEcho`, and without local echo the preview clears only on output parsed AFTER the commit (or its 2 s fallback). ⚠️ It watches keydown in the capture phase on `terminal.element`, never on the textarea, because xterm finalizes the composition and emits the commit in its own capture listener on the textarea.
 
 **Entrance animations** (`entrance-animations.js`, all OFF by default): opt-in animations for tabs, terminal, windows, connection lines and tile-grid tiles, chosen via `data-tab-anim` / `data-term-anim` / `data-win-anim` / `data-line-anim` / `data-tile-anim` on `<html>`; the default `legacy` theme short-circuits every hook (tiles keep the grid's own `settle`). ⚠️ Tabs and lines are destroyed mid-animation on re-render, so re-apply to the fresh element by id with a negative `animation-delay` (resume, never restart). ⚠️ Terminal-pane styles may animate only transform / opacity / clip-path (anything else resizes the PTY via FitAddon); `blur` is the ONE sanctioned `filter` exception, do not generalise it. ⚠️ Line glow lives in `--line-glow` so blur keyframes interpolate. Every animation setting lives in App Settings → **Animations** (`#settings-animations`); put new ones there. ⚠️ Tiles are OFF by default (Animations → Tile Animations, default `settle` = the grid's own fade, no screen beat); a theme only presets it. A tile's FRAME animates transform/opacity only (six at once, no filter) with `tile-enter*`/`tile-leave*` keyframe names (what the mount and the still copy listen for); its SCREEN replays the pane style on `.tile-body.term-enter`; a reload's restore always settles. Persisted per-device in `codeman:*Anim` localStorage keys, never in `SettingsUpdateSchema`; lab at `?animlab=1`. Test: `test/entrance-animations.test.ts`. → [architecture-invariants#entrance-animations](../../docs/architecture-invariants.md#entrance-animations)
 
diff --git a/src/web/public/terminal-keycode229-recovery.js b/src/web/public/terminal-keycode229-recovery.js
index 43d84ddb..d3fd3dfc 100644
--- a/src/web/public/terminal-keycode229-recovery.js
+++ b/src/web/public/terminal-keycode229-recovery.js
@@ -9,10 +9,14 @@
  *
  * ⚠ Desktop fine pointers must not run this (#716). xterm already forwards the
  * composed character, and a second forward doubles a dead-key backtick.
- * `create()` returns null unless `matchMedia('(pointer: coarse)')` matches, so
- * soft keyboards keep the recovery and a desktop does not attach it. A missing
- * or throwing `matchMedia` stands down: a missed recovery is acceptable, a
- * duplicated keystroke is not.
+ * `create()` returns null unless `matchMedia('(pointer: coarse)')` matches or
+ * the browser is Android, so soft keyboards keep the recovery and a desktop
+ * does not attach it. Android is checked by user agent because Chromium reports
+ * its PRIMARY pointer as fine once a mouse, a trackpad cover or a stylus is
+ * attached, while the text still comes from the soft keyboard (#441, #541 were
+ * measured there); Android always ran this before #716, so the check keeps it.
+ * A missing or throwing `matchMedia` stands down elsewhere: a missed recovery is
+ * acceptable, a duplicated keystroke is not.
  *
  * ⚠ The gap is NARROWER than "keyCode 229", and assuming otherwise produces a
  * controller that looks useful while doing nothing. For a keydown that really
@@ -72,11 +76,13 @@
   }
 
   /**
-   * Touch / coarse pointer only. See the file header: on a fine pointer this
-   * forward runs on top of xterm's own composition handling.
+   * Touch / coarse pointer, or any Android browser. See the file header: on a
+   * desktop fine pointer this forward runs on top of xterm's own composition
+   * handling.
    */
-  function isCoarsePointer() {
+  function isSoftKeyboardPlatform() {
     try {
+      if (/Android/i.test(global.navigator?.userAgent || '')) return true;
       return global.matchMedia?.('(pointer: coarse)')?.matches === true;
     } catch {
       return false;
@@ -84,7 +90,7 @@
   }
 
   function create(options) {
-    if (!isCoarsePointer()) return null;
+    if (!isSoftKeyboardPlatform()) return null;
     const textarea = options?.textarea;
     const emitRecovered = options?.emitRecovered;
     if (!textarea?.addEventListener || !textarea?.removeEventListener || typeof emitRecovered !== 'function') {
diff --git a/test/terminal-keycode229-recovery.test.ts b/test/terminal-keycode229-recovery.test.ts
index 57bb72cc..bf029e36 100644
--- a/test/terminal-keycode229-recovery.test.ts
+++ b/test/terminal-keycode229-recovery.test.ts
@@ -46,9 +46,9 @@ function inputEvent(data: string, overrides: Record<string, unknown> = {}) {
   return { data, inputType: 'insertText', isComposing: false, ...overrides };
 }
 
-function harness({ screenReader = false, coarse = true, matchMedia = true } = {}) {
+function harness({ screenReader = false, coarse = true, matchMedia = true, userAgent = '' } = {}) {
   const source = readFileSync(new URL('../src/web/public/terminal-keycode229-recovery.js', import.meta.url), 'utf8');
-  const exposed: Record<string, any> = {};
+  const exposed: Record<string, any> = { navigator: { userAgent } };
   if (matchMedia) {
     // create() attaches only for a coarse pointer (#716). The recovery cases
     // below are the soft-keyboard behaviour, so they opt in. A fine pointer
@@ -136,6 +136,30 @@ describe('orphaned terminal input recovery', () => {
     expect(h.textarea.listenerCount()).toBe(0);
   });
 
+  it('attaches on Android even when the primary pointer reports fine (a mouse or stylus attached)', () => {
+    // Chromium makes a mouse, a trackpad cover or an S Pen the primary pointer, but the text still comes
+    // from the soft keyboard, so the #441/#541 recovery must stay on there.
+    const h = harness({
+      coarse: false,
+      userAgent:
+        'Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Mobile Safari/537.36',
+    });
+    expect(h.controller).not.toBeNull();
+    h.keydown();
+    h.input('`');
+    h.flushTimers();
+    expect(h.emitted).toEqual(['`']);
+  });
+
+  it('stays off on a desktop fine pointer that is not Android', () => {
+    const h = harness({
+      coarse: false,
+      userAgent:
+        'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36',
+    });
+    expect(h.controller).toBeNull();
+  });
+
   it('still recovers a dropped insertText on a coarse pointer', () => {
     const h = harness({ coarse: true });
     h.keydown();