@cplieger/web-terminal-ui 7.0.4 → 7.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "7.0.4",
+  "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",
@@ -50,22 +50,22 @@
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/typescript-checker": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
-    "@types/node": "26.4.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.10.0",
-    "knip": "6.33.0",
+    "html-validate": "11.14.0",
+    "knip": "6.34.0",
     "playwright": "1.62.1",
     "prettier": "3.9.6",
     "stylelint": "17.14.1",
     "stylelint-config-standard": "40.0.0",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.68.0",
-    "vitest": "4.1.11"
+    "typescript-eslint": "8.69.0",
+    "vitest": "5.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/composition.ts

@@ -39,6 +39,39 @@ let sendingComposition = false;
 let compositionStart = 0;
 let compositionSuffix = "";
 
+// 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.
+//
+// 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.
+//
+// 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 lastCompositionActivity = 0;
+
 export function init(opts: {
   textarea: HTMLTextAreaElement;
   compositionView: HTMLElement;
@@ -60,23 +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 {
+  if (sendingComposition) {
+    return true;
+  }
+  if (!composing) {
+    return false;
+  }
+  if (Date.now() - lastCompositionActivity <= COMPOSITION_IDLE_MS) {
+    return true;
+  }
+  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;
+  lastCompositionActivity = 0;
   compositionView.textContent = "";
   compositionView.classList.remove("active");
   resetToPlaceholder(textarea);
@@ -104,6 +175,7 @@ export function teardown(): void {
 
 function onStart(): void {
   composing = true;
+  lastCompositionActivity = Date.now();
   const start = textarea.selectionStart;
   const end = textarea.selectionEnd;
   compositionStart = Math.min(start, end);
@@ -115,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.
@@ -125,6 +201,7 @@ 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.

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) {
@@ -758,6 +768,30 @@ 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);
@@ -788,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 },
@@ -838,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;
       }