@cplieger/web-terminal-ui 7.0.3 → 7.0.5

package/css/30-tabs.css

@@ -355,27 +355,6 @@
   color: var(--text);
 }
 
-/* On an inactive tab the close appears only on hover, kept in the layout via
-   visibility so the tab width never jumps; on the active tab it is always shown. */
-:where(.wt-root) .wt-tab:not(.wt-tab-active) .wt-tab-close {
-  visibility: hidden;
-}
-
-:where(.wt-root) .wt-tab:not(.wt-tab-active):hover .wt-tab-close {
-  visibility: visible;
-}
-
-/* Coarse pointer (an iPad using the strip): no hover fires, so an inactive tab's close
-   would be unreachable without first activating the tab. Reveal every tab's close there,
-   matching the always-visible mobile switcher closes. No narrow gate needed: on the
-   narrow-coarse phone the whole strip is display:none (31-switcher.css), so this rule
-   is moot there. */
-@media (pointer: coarse) {
-  :where(.wt-root) .wt-tab:not(.wt-tab-active) .wt-tab-close {
-    visibility: visible;
-  }
-}
-
 /* The add-tab (+) button: a fixed bar item OUTSIDE the tab scroller (it never
    scrolls away with an overflowing list; the shrink-wrapped scroller keeps it
    visually trailing the last tab while the tabs fit — see .wt-tab-scroll). Its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "7.0.3",
+  "version": "7.0.5",
   "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,19 +50,21 @@
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/typescript-checker": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
-    "@types/node": "26.2.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",
-    "eslint": "10.8.1",
+    "eslint": "10.9.1",
     "fast-check": "4.9.0",
-    "happy-dom": "20.11.6",
-    "html-validate": "11.8.0",
-    "knip": "6.32.2",
+    "html-validate": "11.12.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.67.0",
+    "typescript-eslint": "8.69.0",
     "vitest": "4.1.11"
   },
   "publishConfig": {

package/src/composition.ts

@@ -39,6 +39,31 @@ 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  ".
+//
+// 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.
+//
+// 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;
+
+let directTail = "";
+let directTailAt = 0;
+let compositionStartedAt: number | null = null;
+
 export function init(opts: {
   textarea: HTMLTextAreaElement;
   compositionView: HTMLElement;
@@ -67,6 +92,42 @@ 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;
+  }
+  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 === "") {
+    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;
+  }
+  // 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);
+}
+
 /** 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
@@ -77,6 +138,8 @@ export function isComposing(): boolean {
 export function cancelComposition(): void {
   composing = false;
   sendingComposition = false;
+  compositionStartedAt = null;
+  directTail = "";
   compositionView.textContent = "";
   compositionView.classList.remove("active");
   resetToPlaceholder(textarea);
@@ -104,6 +167,7 @@ export function teardown(): void {
 
 function onStart(): void {
   composing = true;
+  compositionStartedAt = Date.now();
   const start = textarea.selectionStart;
   const end = textarea.selectionEnd;
   compositionStart = Math.min(start, end);
@@ -131,6 +195,9 @@ function onEnd(): void {
   sendingComposition = true;
   const startSnapshot = compositionStart;
   const suffixSnapshot = compositionSuffix;
+  const startedAt = compositionStartedAt;
+  const endedAt = Date.now();
+  compositionStartedAt = null;
   setTimeout(() => {
     if (!sendingComposition) {
       return;
@@ -144,9 +211,10 @@ function onEnd(): void {
     const composed = value
       .substring(startSnapshot, Math.max(startSnapshot, valueEnd))
       .replace(/\u00A0/g, " ");
-    if (composed.length > 0) {
+    if (composed.length > 0 && !repeatsDirectSends(composed, startedAt, endedAt)) {
       send(composed);
     }
+    directTail = "";
     resetToPlaceholder(textarea);
   }, 0);
 }

package/src/features/context-menu.ts

@@ -75,6 +75,16 @@ export interface ContextMenuOptions {
  *  opens, so a wrong answer here costs at most a duplicated menu on an unusual
  *  device, never a broken selection and never a lost paste. */
 function isAppleTouchDevice(): boolean {
+  // Dead in every runtime that reaches this, and left in place deliberately.
+  // Measured on this repo's Node (v24.18.0, the version ts-ci pins): `typeof
+  // navigator` is "object", with userAgent "Node.js/24", platform
+  // "Linux x86_64" and maxTouchPoints undefined — so the fall-through already
+  // answers false there, by the same route a browser on a non-Apple device
+  // takes. A Web Worker has a WorkerNavigator, so it does not reach this
+  // either. What the guard still buys is totality: without it the bare
+  // `navigator` reads below would throw a ReferenceError in a runtime that has
+  // no navigator at all. It answers the same `false` the fall-through would, so
+  // nothing depends on reaching it, and no test can reach it without stubbing.
   if (typeof navigator === "undefined") {
     return false;
   }

package/src/features/tabs/attention.ts

@@ -19,10 +19,25 @@
 // the switcher's aggregate dot about what wants the user; the fold and the raise
 // share isUnseenCue (model.ts).
 //
-// DOM-free and global-free by construction, like notify.ts: every capability
-// arrives through AttentionEnv, so the decisions are unit-testable with no
-// document, no navigator and no icon assets, and browserAttentionEnv() below is
-// the one place that touches globals.
+// DOM-free by construction, like notify.ts: every capability arrives through
+// AttentionEnv, so the fold, the idempotence and the degradation paths are driven
+// in the tests by plain recorder functions, and browserAttentionEnv() below is the
+// only function here that reads a global (globalThis.navigator, document).
+//
+// That last clause is a reading of the source, and nothing enforces it — on
+// purpose, not by omission. An ambient-absence test would assert the RUNTIME
+// rather than this module: the only importer is tabs/index.ts, the node project
+// holds one file and it reads stylesheets off disk, so nothing here loads this
+// module outside a browser and no test can observe an absent `document` without
+// passing for a third wrong reason (.kiro/steering/testing-ts.md,
+// "Capability-absence is NOT a project selection"). The half that does ship IS
+// enforced, and at the site: attention.test.ts shadows the whole `navigator`
+// object and drives the real browserAttentionEnv through it. The mechanism that
+// could enforce the load-time half is an AST scan of this file's top-level
+// statements — vibekit carries one for its ported copy, where a node-project test
+// statically imports the module and a module-scope global read really does break
+// something. Copy it here the day anything needs this module to load without a
+// document.
 
 import { type CueStatus, cueIconName, isUnseenCue, worseCue } from "./model.js";
 

package/src/features/tabs/index.ts

@@ -1007,8 +1007,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // sync, so a user browsing a scrolled strip is never yanked back by an
       // unrelated repaint), the newly active chip is brought into view in the
       // overflowed scroller; inline: "nearest" is a no-op when it is already
-      // visible. The typeof guard covers happy-dom, which lacks
-      // scrollIntoView.
+      // visible. The typeof guard covers an environment without scrollIntoView.
       let lastRevealedActive = "";
       function paintActive(): void {
         for (const t of tabList) {
@@ -2247,7 +2246,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           }
         }
         if (invert.size === 0) {
-          return; // nothing moved on screen (a zero-rect DOM: happy-dom)
+          return; // nothing moved on screen (every box measured zero)
         }
         applyShift(invert, "none");
         // The read forces the reflow that COMMITS the from-state. Without it the
@@ -2537,8 +2536,8 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // Reordering re-appends every chip, and reparenting the focused field blurs
         // it — so an open edit would be committed as a side effect of moving some
         // OTHER tab, via a blur the user never performed. Resolve it here instead,
-        // so the outcome is chosen and testable rather than emergent (happy-dom
-        // does not reproduce the reparent-blur, so no test could catch it).
+        // so the outcome is chosen rather than emergent: a blur that arrives as a
+        // side effect of reparenting is not a decision anyone made.
         resolveEdit("blur", false);
         const from = tabList.findIndex((t) => t.id === id);
         const to = from + delta;

package/src/features/tabs/ink-centre.ts

@@ -249,9 +249,9 @@ export function centreChipLabels(
   };
 
   remeasure(false);
-  // The DOM lib types document.fonts as always present; happy-dom ships no
-  // FontFaceSet at all, and neither does any engine without the CSS Font
-  // Loading API, so the honest type is the optional one.
+  // The DOM lib types document.fonts as always present; an engine without the CSS
+  // Font Loading API ships no FontFaceSet at all, so the honest type is the
+  // optional one.
   const fonts = document.fonts as FontFaceSet | undefined;
   // `ready` settles the initial load (including a failed one); `loadingdone`
   // covers a face the host page adds afterwards, which `ready` never reports.

package/src/features/tabs/notify.ts

@@ -48,7 +48,7 @@ export type NotificationCtorLike = new (
  *  not recognise must degrade rather than be asserted. */
 export interface NotifierEnv {
   /** The Notification constructor, or undefined where the API does not exist
-   *  (iOS Safari outside an installed PWA, a non-secure context, happy-dom). */
+   *  (iOS Safari outside an installed PWA, a non-secure context). */
   ctor: NotificationCtorLike | undefined;
   /** Current permission: "default" | "granted" | "denied" (or anything else). */
   permission: () => string;

package/src/features/tabs/switch-anim.ts

@@ -10,7 +10,7 @@
 // on the 360 ms fallback timer instead of the animation's own end, and every test
 // still passes because the tests dispatch the JS constant.
 //
-// Living here rather than inside the feature is what lets `css-contract.test.ts`
+// Living here rather than inside the feature is what lets `css-contract.node.test.ts`
 // import it and assert the CSS agrees. Same reason `input-placeholder.ts` and
 // `kernel/gesture.ts` exist: a constant two places must keep in lockstep gets its
 // own module. NOT part of the package's `exports` map, so it is internal and can

package/src/kernel/kernel.ts

@@ -40,6 +40,7 @@ import { createConnState } from "./conn-state.js";
 import { createScrollbackKeeper } from "./scrollback.js";
 import { STARTUP_FAILURE_COPY } from "./startup-copy.js";
 import { attachLoadingStatus, DEFAULT_LOADING_MESSAGES } from "./loading-status.js";
+import { reloadPage } from "./navigation.js";
 import type {
   CreateTerminalOptions,
   FeatureInstance,
@@ -184,7 +185,7 @@ function renderFatalStartupInto(
   reloadButton.type = "button";
   reloadButton.textContent = STARTUP_FAILURE_COPY.reloadLabel;
   reloadButton.addEventListener("click", () => {
-    window.location.reload();
+    reloadPage();
   });
   card.append(title, messageEl, reloadButton);
   surface.appendChild(card);
@@ -389,6 +390,14 @@ 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).
@@ -762,14 +771,14 @@ function buildTerminal(
           paste(ev.data);
         } else {
           // Normalize iOS's NBSP-for-space quirk, then send through the funnel.
-          sendText(normalizeTypedText(ev.data));
+          sendTyped(ev.data);
         }
       } else {
         const v = input.value;
         if (v.length > INPUT_PLACEHOLDER.length && v.startsWith(INPUT_PLACEHOLDER)) {
-          sendText(normalizeTypedText(v.slice(INPUT_PLACEHOLDER.length)));
+          sendTyped(v.slice(INPUT_PLACEHOLDER.length));
         } else if (v !== INPUT_PLACEHOLDER && v.length > 0) {
-          sendText(normalizeTypedText(v));
+          sendTyped(v);
         }
       }
       resetToPlaceholder(input);
@@ -1170,7 +1179,7 @@ function buildTerminal(
         // an uncanceled keydown's insertion target after a listener moved focus
         // mid-dispatch. Chromium does; no specification requires it.
         ev.preventDefault();
-        sendText(normalizeTypedText(char));
+        sendTyped(char);
         return;
       }
       applyMappedKey(ev, result);

package/src/kernel/navigation.ts

@@ -0,0 +1,19 @@
+// navigation.ts — the library's one page-navigation call, behind its own module.
+//
+// `window.location.reload` cannot be substituted in a real browser: `reload` is
+// an own, sealed property of the location instance (`configurable: false`,
+// `writable: false`), `Location.prototype` carries no `reload` to spy on, and
+// `window`, `globalThis.window` and `globalThis.location` are all
+// non-configurable. So a test cannot redefine it, assign over it, or stub the
+// global, and letting the real call run navigates the test runner's own frame
+// and takes the whole run down with it.
+//
+// A separate module is the seam that works: a caller's import is a live binding
+// the test framework can replace, which an intra-module call is not. Keeping the
+// call here also means there is exactly one place in the library that navigates,
+// so the next one has to be added deliberately.
+
+/** Reload the current page. The only navigation this library performs. */
+export function reloadPage(): void {
+  window.location.reload();
+}

package/src/kernel/style-contract.ts

@@ -25,7 +25,7 @@
 // These lists are HAND-WRITTEN on purpose. They are the public contract — a
 // decision about what this library promises to support — not a fact derived
 // from the stylesheets. What IS derived from the stylesheets is the
-// verification that the promise holds: `src/css-contract.test.ts` generates the
+// verification that the promise holds: `src/css-contract.node.test.ts` generates the
 // declared/referenced token inventory from the CSS itself and fails if any
 // token named here is not both DECLARED and READ by a rule. A token that is
 // declared but never read is the silent-no-op case above, reached from the

package/src/presets/tabbed.ts

@@ -10,6 +10,18 @@ import { activityMonitor } from "../features/activity-monitor.js";
 import { animations } from "../features/animations.js";
 import { presetSingle } from "./single.js";
 
+/** Options shared by the two tabbed presets, passed through to the tabs feature.
+ *  A preset that takes arguments is called as `features: () =>
+ *  presetTabbed({...})`, which keeps the call inside createTerminal's failure
+ *  boundary (see CreateTerminalOptions.features). */
+export interface TabbedPresetOptions {
+  /** Swap the page's icon links to a status variant while a background session
+   *  wants the user. Off by default, and enabling it is a promise that the
+   *  variant assets are served — see TabsOptions.attentionIcons for the naming
+   *  contract and .kiro/scripts/gen-attention-icons.py, which writes them. */
+  attentionIcons?: boolean;
+}
+
 /** buildTabbed composes the tabbed UI: the single-pane touch features, an
  *  externally-driven mobile toolbar (its grid is opened from a keyboard button
  *  in the tab bar, not its own toggle), the activity monitor (the status-SSE
@@ -27,18 +39,6 @@ import { presetSingle } from "./single.js";
  *  foreground-process/cwd inference — and both presets render what it reports. A
  *  browser that re-derived any of that could only disagree with the server and
  *  with every other client attached to the same session. */
-/** Options shared by the two tabbed presets, passed through to the tabs feature.
- *  A preset that takes arguments is called as `features: () =>
- *  presetTabbed({...})`, which keeps the call inside createTerminal's failure
- *  boundary (see CreateTerminalOptions.features). */
-export interface TabbedPresetOptions {
-  /** Swap the page's icon links to a status variant while a background session
-   *  wants the user. Off by default, and enabling it is a promise that the
-   *  variant assets are served — see TabsOptions.attentionIcons for the naming
-   *  contract and .kiro/scripts/gen-attention-icons.py, which writes them. */
-  attentionIcons?: boolean;
-}
-
 export function buildTabbed(
   agentShell: boolean,
   opts: TabbedPresetOptions = {},
@@ -59,12 +59,8 @@ export function buildTabbed(
   ];
 }
 
-/** Tabbed UI: the touch features, tabs, the mobile keyboard bar, the activity
- *  monitor, and animations. Each tab's title follows the process OSC 0/2 window
- *  title when the program sets one, else the last submitted line; each tab's
- *  activity dot stays hidden until its session reports activity via OSC 9;4
- *  progress (kiro-cli, Claude Code, …), so a plain bash/sh keeps clean,
- *  label-only tabs. */
+/** Tabbed UI: buildTabbed with agent activity presumed off (see buildTabbed for
+ *  title and activity-dot sourcing). */
 export function presetTabbed(opts: TabbedPresetOptions = {}): TerminalFeature<unknown>[] {
   return buildTabbed(false, opts);
 }