@cplieger/web-terminal-ui 7.0.5 → 7.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "7.0.5",
+  "version": "7.0.6",
   "type": "module",
   "description": "Reference touch-first browser UI for @cplieger/web-terminal-engine: a composable kernel + feature modules (tabs, activity monitor, mobile toolbar, context menu, IME, predictive echo, viewport handling) and CSS. One createTerminal() call.",
   "license": "MPL-2.0",
@@ -52,12 +52,12 @@
     "@stryker-mutator/vitest-runner": "10.0.0",
     "@types/node": "26.4.1",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/browser": "4.1.11",
-    "@vitest/browser-playwright": "4.1.11",
-    "@vitest/coverage-v8": "4.1.11",
+    "@vitest/browser": "5.0.0",
+    "@vitest/browser-playwright": "5.0.0",
+    "@vitest/coverage-v8": "5.0.0",
     "eslint": "10.9.1",
     "fast-check": "4.9.0",
-    "html-validate": "11.12.0",
+    "html-validate": "11.14.0",
     "knip": "6.34.0",
     "playwright": "1.62.1",
     "prettier": "3.9.6",
@@ -65,7 +65,7 @@
     "stylelint-config-standard": "40.0.0",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.69.0",
-    "vitest": "4.1.11"
+    "vitest": "5.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/composition.ts

@@ -39,30 +39,38 @@ let sendingComposition = false;
 let compositionStart = 0;
 let compositionSuffix = "";
 
-// A soft keyboard may announce its composition only at COMMIT time: the
-// per-character `input` events arrive with no composition in progress, the
-// kernel sends each keystroke as typed, and then the keyboard fires
-// compositionstart + compositionend back-to-back on the committing key while
-// writing the WHOLE accumulated word into the textarea. The deferred read below
-// then sends that word a second time — reported on Android Chrome with
-// SwiftKey, where typing "hello" and pressing space produced "hellohello  ".
+// A composition that never ENDS used to stop the terminal accepting input at
+// all. `composing` gates both the kernel's `input` and `keydown` listeners, and
+// nothing cleared it: no blur handler, no timer. So a keyboard that opened a
+// composition and never closed it left every subsequent keystroke, Enter
+// included, dropped on the floor — reported on Android Chrome with SwiftKey as
+// "typing does not work", recoverable only by tapping a word suggestion, which
+// is what finally fired compositionend.
 //
-// The terminal has already been given the literal keystrokes and cannot be
-// asked to retract them, so a commit that only repeats them is a no-op.
-// `noteDirectSend` records what the kernel sent with no composition running;
-// the finaliser drops a commit that matches it.
+// Not a SwiftKey quirk to special-case. Chromium has a filed defect for
+// compositionend going missing (crbug 446714223, in EditContext rather than a
+// textarea, so it is adjacent evidence and not proof of this exact path), and
+// CodeMirror synthesises the event outright for Safari dead keys, which is a
+// working implementation treating the same absence as real.
 //
-// Unreachable on a keyboard that announces its composition BEFORE the
-// keystrokes (every desktop IME, iOS, Android's own keyboard): there the
-// kernel's `input` listener returns early while composing, so nothing is
-// recorded and there is nothing for a commit to match.
-const ECHO_TAIL_MAX = 64;
-const ECHO_WINDOW_MS = 1500;
-const ECHO_MAX_COMPOSE_MS = 60;
+// The fix is a STALENESS READ rather than a timer. A composition the user is
+// typing into keeps firing compositionupdate, so its clock keeps refreshing; an
+// abandoned one stops and ages out, releasing the gate. UI Events promises one
+// or more compositionupdate events and one whenever the DOM is updated as part
+// of the composition, not strictly one per key, so this is a heuristic about
+// activity rather than a guaranteed per-keystroke signal. Deliberately NOT
+// refreshed by `input` events: in this failure the user IS typing and those
+// events ARE arriving, so refreshing there would defeat the mechanism.
+//
+// Five seconds is the number Slate's android-input-manager uses for its own
+// composition-gone-quiet bound (a DOM flush decision, not an input gate, so the
+// value is borrowed and the job is not the same). It is generous because the
+// residual risk runs the other way: a composition paused longer than this and
+// then resumed can duplicate its first character. That trade is deliberate —
+// the failure being replaced loses ALL input until an unrelated event fires.
+const COMPOSITION_IDLE_MS = 5000;
 
-let directTail = "";
-let directTailAt = 0;
-let compositionStartedAt: number | null = null;
+let lastCompositionActivity = 0;
 
 export function init(opts: {
   textarea: HTMLTextAreaElement;
@@ -85,61 +93,61 @@ export function init(opts: {
   textarea.addEventListener("paste", onPaste);
 }
 
-/** True while an IME composition is in progress. Caller's keydown
- *  listener must early-return on true to avoid sending raw key bytes
- *  during composition. */
+/** True while an IME composition is in progress, RECONCILED first: a composition
+ *  whose clock has not been refreshed for COMPOSITION_IDLE_MS is expired here,
+ *  clearing the latch, the clock and the overlay, so a keyboard that never fires
+ *  compositionend cannot strand the terminal or leave a stale panel on screen.
+ *  A late compositionend still delivers its text — `onEnd` snapshots what it
+ *  needs and does not require `composing` to have stayed true.
+ *
+ *  `sendingComposition` is exempt: that window is bounded by a setTimeout(0)
+ *  this module owns. */
 export function isComposing(): boolean {
-  return composing || sendingComposition;
-}
-
-/** Record text the kernel put on the wire with no composition running, so a
- *  keyboard that announces its composition only at commit time cannot have the
- *  same keystrokes delivered twice (see the ECHO_* note above). Typed text
- *  only — a paste is never re-committed by a keyboard. */
-export function noteDirectSend(text: string): void {
-  if (text === "") {
-    return;
+  if (sendingComposition) {
+    return true;
   }
-  const now = Date.now();
-  if (now - directTailAt > ECHO_WINDOW_MS) {
-    directTail = "";
-  }
-  directTail = (directTail + text).slice(-ECHO_TAIL_MAX);
-  directTailAt = now;
-}
-
-/** Whether this commit merely repeats keystrokes already delivered literally. */
-function repeatsDirectSends(composed: string, startedAt: number | null, endedAt: number): boolean {
-  if (directTail === "") {
+  if (!composing) {
     return false;
   }
-  // A composition the user typed INTO spans human time; a commit-time
-  // announcement starts and ends inside one keystroke.
-  if (startedAt !== null && endedAt - startedAt > ECHO_MAX_COMPOSE_MS) {
-    return false;
+  if (Date.now() - lastCompositionActivity <= COMPOSITION_IDLE_MS) {
+    return true;
   }
-  // Only the burst still being typed can be a re-commit of itself.
-  if (endedAt - directTailAt > ECHO_WINDOW_MS) {
-    return false;
-  }
-  // The committing key (space, tab) is delivered as its own `input` event, so
-  // what has to match is the WORD the keyboard is re-committing.
-  const word = composed.replace(/[ \t]+$/u, "");
-  return word !== "" && directTail.endsWith(word);
+  expireComposition();
+  return false;
+}
+
+/** The RAW latch: is a composition open at all, regardless of whether it has
+ *  gone quiet. Read before the reconciling `isComposing()` by the keydown guard,
+ *  because the keyCode 229 signal only means "an IME claimed this key" while a
+ *  composition is genuinely open — on Android it is the value for nearly every
+ *  soft-keyboard key. */
+export function isCompositionOpen(): boolean {
+  return composing || sendingComposition;
+}
+
+/** Drop a composition that has gone quiet: the latch, the clock and the visible
+ *  overlay together. Without the overlay half the gate would say no composition
+ *  while `.composition-view.active` still said there was one, leaving a stale
+ *  panel over the terminal for as long as the missing compositionend never
+ *  arrived. Does NOT touch the textarea: a late compositionend still reads it. */
+function expireComposition(): void {
+  composing = false;
+  lastCompositionActivity = 0;
+  compositionView.textContent = "";
+  compositionView.classList.remove("active");
 }
 
 /** Abort any in-flight composition without sending, and clear the textarea.
- *  The kernel calls this on a tab switch (detach): committing half-composed IME
- *  text to either the outgoing or the incoming session is wrong, so we discard
- *  it (design 5.1, "end any composition ... or cancel"). Clearing
- *  sendingComposition also neutralizes a just-fired compositionend whose
- *  deferred send is still pending on the microtask/timeout queue, so it cannot
- *  land on whoever is active after the switch. */
+ *  The kernel calls this on a tab switch (detach) and on blur: committing
+ *  half-composed IME text to either the outgoing or the incoming session is
+ *  wrong, so we discard it (design 5.1, "end any composition ... or cancel").
+ *  Clearing sendingComposition also neutralizes a just-fired compositionend
+ *  whose deferred send is still pending on the microtask/timeout queue, so it
+ *  cannot land on whoever is active after the switch. */
 export function cancelComposition(): void {
   composing = false;
   sendingComposition = false;
-  compositionStartedAt = null;
-  directTail = "";
+  lastCompositionActivity = 0;
   compositionView.textContent = "";
   compositionView.classList.remove("active");
   resetToPlaceholder(textarea);
@@ -167,7 +175,7 @@ export function teardown(): void {
 
 function onStart(): void {
   composing = true;
-  compositionStartedAt = Date.now();
+  lastCompositionActivity = Date.now();
   const start = textarea.selectionStart;
   const end = textarea.selectionEnd;
   compositionStart = Math.min(start, end);
@@ -179,6 +187,10 @@ function onStart(): void {
 }
 
 function onUpdate(ev: CompositionEvent): void {
+  // Every keystroke of a live composition lands here, which is what keeps its
+  // staleness clock fresh (see COMPOSITION_IDLE_MS). An abandoned composition
+  // stops firing this and ages out of the gate.
+  lastCompositionActivity = Date.now();
   // \u200E (LTR mark) wrappers + CSS direction:rtl on the view make
   // long compositions show their trailing edge instead of being
   // clipped at the start. Pattern from xterm.js.
@@ -189,15 +201,13 @@ function onUpdate(ev: CompositionEvent): void {
 function onEnd(): void {
   compositionView.classList.remove("active");
   composing = false;
+  lastCompositionActivity = 0;
   // The compositionend event fires before the textarea reflects the
   // final value on most browsers (Chromium especially). Defer one tick
   // and read the textarea then; xterm.js's pattern.
   sendingComposition = true;
   const startSnapshot = compositionStart;
   const suffixSnapshot = compositionSuffix;
-  const startedAt = compositionStartedAt;
-  const endedAt = Date.now();
-  compositionStartedAt = null;
   setTimeout(() => {
     if (!sendingComposition) {
       return;
@@ -211,10 +221,9 @@ function onEnd(): void {
     const composed = value
       .substring(startSnapshot, Math.max(startSnapshot, valueEnd))
       .replace(/\u00A0/g, " ");
-    if (composed.length > 0 && !repeatsDirectSends(composed, startedAt, endedAt)) {
+    if (composed.length > 0) {
       send(composed);
     }
-    directTail = "";
     resetToPlaceholder(textarea);
   }, 0);
 }

package/src/kernel/kernel.ts

@@ -120,6 +120,16 @@ function normalizeTypedText(text: string): string {
   return text.replace(/\u00A0/g, " ");
 }
 
+/** `KeyboardEvent.keyCode` for a key an IME has claimed. Windows' VK_PROCESS,
+ *  reported by Blink and WebKit for the key that commits a composition, and by
+ *  Android for essentially every soft-keyboard key — which is why every read of
+ *  it is gated on a composition being open.
+ *
+ *  Deprecated and nonetheless the only carrier of this fact: for that commit key
+ *  both engines report `key` as the ordinary `"Enter"`, and Safari reports
+ *  `isComposing` false, so neither the modern flag nor `key` distinguishes it. */
+const IME_COMMIT_KEYCODE = 229;
+
 function pick(root: ParentNode, selector: string): HTMLElement {
   const el = root.querySelector<HTMLElement>(selector);
   if (!el) {
@@ -390,14 +400,6 @@ function buildTerminal(
   function sendText(text: string): void {
     sendBytes(encoder.encode(text));
   }
-  /** A keystroke the user typed with no composition running. Recorded so a
-   *  keyboard that announces its composition only at commit time cannot have
-   *  the same characters delivered twice (composition.ts, the ECHO_* note). */
-  function sendTyped(text: string): void {
-    const out = normalizeTypedText(text);
-    sendText(out);
-    composition.noteDirectSend(out);
-  }
   function paste(text: string): void {
     // The one bracketed-paste + newline-normalize funnel; every feature and the
     // kernel's own paste paths route through here (paste-jacking defense).
@@ -766,19 +768,43 @@ function buildTerminal(
       ) {
         resetToPlaceholder(input);
         return;
+      } else if (inputType === "insertReplacementText") {
+        // A spellcheck / autocorrect / autofill REWRITE of text already typed.
+        // The bytes it is correcting have already gone to the pty and a terminal
+        // cannot retract them: 0x7f means whatever the remote application decides
+        // it means, so a pager, vim, a y/n prompt and a no-echo password prompt
+        // each read it as their own input. Applying the rewrite forward instead
+        // duplicates — measured on xterm.js's value-diff, where `helo` corrected
+        // to `hello` puts `helohello` on the wire (its issue #3600). So drop it
+        // and leave the typed text standing, which is also what a shell wants:
+        // `cd /usr` silently becoming `cd /use` is worse than no autocorrect.
+        //
+        // The spec's own signal for this, so no length heuristic is needed: a
+        // max-one-character rule would break glide typing (a whole word in one
+        // event, and SwiftKey's flagship input method) while still admitting
+        // CJK's one-for-one in-place replacement. Cancelling is not an option
+        // either — preventDefault on beforeinput is a no-op in Chrome, per
+        // CodeMirror's own note — but declining to SEND is entirely ours.
+        //
+        // Reachable on more than Android: WebKit fires this type for a spelling
+        // suggestion and for a macOS system text substitution whatever
+        // autocorrect="off" says. Dropping is right wherever it fires, because
+        // what it carries is always a replacement for bytes the pty already has.
+        resetToPlaceholder(input);
+        return;
       } else if (typeof ev.data === "string" && ev.data.length > 0) {
         if (inputType === "insertFromPaste") {
           paste(ev.data);
         } else {
           // Normalize iOS's NBSP-for-space quirk, then send through the funnel.
-          sendTyped(ev.data);
+          sendText(normalizeTypedText(ev.data));
         }
       } else {
         const v = input.value;
         if (v.length > INPUT_PLACEHOLDER.length && v.startsWith(INPUT_PLACEHOLDER)) {
-          sendTyped(v.slice(INPUT_PLACEHOLDER.length));
+          sendText(normalizeTypedText(v.slice(INPUT_PLACEHOLDER.length)));
         } else if (v !== INPUT_PLACEHOLDER && v.length > 0) {
-          sendTyped(v);
+          sendText(normalizeTypedText(v));
         }
       }
       resetToPlaceholder(input);
@@ -796,7 +822,12 @@ function buildTerminal(
   input.addEventListener(
     "blur",
     () => {
-      resetToPlaceholder(input);
+      // cancelComposition, not just resetToPlaceholder: `composing` gates both
+      // input listeners, so a composition abandoned by losing focus would
+      // otherwise keep the gate shut and the terminal would take no input when
+      // focus came back. The staleness read covers a keyboard that strands us
+      // while still focused; this covers the case with a definite signal.
+      composition.cancelComposition();
       termWrap.classList.remove("focus");
     },
     { signal },
@@ -846,6 +877,33 @@ function buildTerminal(
   input.addEventListener(
     "keydown",
     (ev: KeyboardEvent) => {
+      // Three gates, and the order is the design. The spec signal first: UI
+      // Events requires a key event inside a composition session to carry
+      // isComposing, which covers every engine except one case.
+      //
+      // That case is the key which COMMITS a composition: Chrome and Safari both
+      // report keyCode 229 for it and Safari reports isComposing false (measured
+      // in quill PR #3445), so a second signal is needed. It is read against the
+      // RAW latch, before the reconciling isComposing() below, and both halves of
+      // that matter. Gated, because on Android 229 is the value for nearly every
+      // soft-keyboard key, so an unconditional check swallows ordinary Backspace
+      // and Enter — found in review after exactly that shipped here. Before the
+      // reconcile, because reconciling clears the latch, and a CJK user who left
+      // a candidate window open past the idle bound is still committing a real
+      // composition: taking this key as an ordinary Enter would send a carriage
+      // return before the composed phrase and execute a half-typed line.
+      //
+      // The consequence to know: in a stranded composition on Android, Enter and
+      // Backspace stay blocked until a character arrives (which reconciles the
+      // latch and releases them) or focus is lost. That is the deliberate side
+      // of the trade, because the alternative costs desktop and iOS correctness.
+      if (ev.isComposing) {
+        return;
+      }
+      // eslint-disable-next-line @typescript-eslint/no-deprecated -- see above
+      if (composition.isCompositionOpen() && ev.keyCode === IME_COMMIT_KEYCODE) {
+        return;
+      }
       if (composition.isComposing()) {
         return;
       }
@@ -1179,7 +1237,7 @@ function buildTerminal(
         // an uncanceled keydown's insertion target after a listener moved focus
         // mid-dispatch. Chromium does; no specification requires it.
         ev.preventDefault();
-        sendTyped(char);
+        sendText(normalizeTypedText(char));
         return;
       }
       applyMappedKey(ev, result);