@cplieger/web-terminal-ui 3.3.1 → 3.4.0

package/src/input-placeholder.ts

@@ -1,5 +1,5 @@
 // Single source of truth for the hidden-textarea placeholder shared by
-// mount.ts and composition.ts.
+// kernel.ts and composition.ts.
 //
 // A single-character placeholder is kept in the hidden textarea so iOS soft
 // keyboards have something to "delete" when the user holds Backspace. iOS only
@@ -11,7 +11,7 @@
 // announcement of the input state stays empty-ish rather than "space".
 //
 // The constant AND the reset routine must stay in lockstep across the two
-// modules (mount.ts seeds + re-pads it; composition.ts restores it on
+// modules (kernel.ts seeds + re-pads it; composition.ts restores it on
 // compositionend / paste) or the iOS held-Backspace key-repeat silently breaks
 // with no compile error — which is why they live here in one place.
 export const INPUT_PLACEHOLDER = "\u00A0";

package/src/kernel/kernel.ts

@@ -248,6 +248,7 @@ export function createTerminal(
     compositionView: compositionViewEl,
     getCursorPx: render.getCursorPx,
     send: sendText,
+    paste,
   });
 
   scroll.init({
@@ -281,7 +282,13 @@ export function createTerminal(
       } else if (msg.type === "scroll") {
         render.handleScroll(msg);
       } else if (msg.type === "title") {
-        document.title = msg.title;
+        // Match the app's own title policy (tabs.ts wire:title / applyStatus,
+        // which ignore a blank OSC 0/2 title): a shell clears its window title
+        // when it redraws its prompt after idling, so hold the last-good browser
+        // title instead of flickering blank.
+        if (msg.title.trim() !== "") {
+          document.title = msg.title;
+        }
         bus.emit("wire:title", { session: activeSession?.id ?? "", title: msg.title });
       } else if (msg.type === "modes") {
         render.updateReverseVideo();
@@ -412,6 +419,17 @@ export function createTerminal(
   // touch and never clears a selection — a long-press to select a word, the OS
   // copy/paste callout, and drag-to-scroll are all left to the platform (the
   // research consensus: over text, allow the default and emit nothing).
+  // A fine pointer (mouse / trackpad) is available: a desktop, or a tablet with
+  // a trackpad / Magic Keyboard. Such a device has a hardware keyboard, so there
+  // is no soft keyboard to protect — focus should be eager and land in one tap.
+  // The bare-touch guards below bow out of focusing (to avoid popping the soft
+  // keyboard or stealing a selection); they are relaxed when a fine pointer
+  // exists. This is keyed off `any-pointer: fine` rather than the event's
+  // pointerType because iPadOS reports a COARSE primary pointer even with a
+  // trackpad attached, and its trackpad taps arrive inconsistently as "mouse" or
+  // "touch" — so pointerType alone made the terminal take several taps to focus.
+  const hasFinePointer = (): boolean =>
+    typeof window.matchMedia === "function" && window.matchMedia("(any-pointer: fine)").matches;
   let lastPointerType = "mouse";
   let pointerDownX = 0;
   let pointerDownY = 0;
@@ -459,6 +477,14 @@ export function createTerminal(
       const sel = window.getSelection();
       if (sel && !sel.isCollapsed) {
         sel.removeAllRanges();
+        // On a bare touchscreen a deselect tap must NOT also focus: that would
+        // pop the soft keyboard right after a copy. But with a fine pointer
+        // (a hardware keyboard is present) there is no soft keyboard to pop, so
+        // focus in the same tap rather than forcing the user to tap again — this
+        // is a large part of the "2-3 taps to focus" on an iPad + Magic Keyboard.
+        if (hasFinePointer()) {
+          focusTerminal();
+        }
         return;
       }
       // A clean tap with nothing selected focuses the input, synchronously (an
@@ -471,8 +497,11 @@ export function createTerminal(
     "mousedown",
     (e) => {
       // Cancel the synthetic mousedown after a touch tap so iOS keeps the
-      // keyboard up (xterm.js focus-preservation pattern, scoped to touch).
-      if (lastPointerType === "touch") {
+      // keyboard up (xterm.js focus-preservation pattern, scoped to touch). Skip
+      // it when a fine pointer is present (iPad + trackpad / Magic Keyboard):
+      // there is no soft keyboard to protect, and suppressing the mousedown was
+      // defeating the native focus, so the terminal needed several taps to focus.
+      if (lastPointerType === "touch" && !hasFinePointer()) {
         e.preventDefault();
       }
     },
@@ -487,7 +516,7 @@ export function createTerminal(
         window.open(link.href, "_blank", "noopener,noreferrer");
         return;
       }
-      if (lastPointerType === "touch") {
+      if (lastPointerType === "touch" && !hasFinePointer()) {
         return;
       }
       const sel = window.getSelection();
@@ -502,6 +531,7 @@ export function createTerminal(
   // --- Viewport ---
   viewport.init({
     termWrap,
+    suppressKeyboardInset: hasFinePointer,
     onSettled() {
       render.updateFontMetrics();
       if (fontsLoaded) {
@@ -636,6 +666,12 @@ export function createTerminal(
       },
       tablist: () => tablistController,
       notifySwitch(session) {
+        // A feature's un-cancelled async (tabs bootstrap/create()/pollOnce()) can
+        // resolve after destroy() and call this; ignore it so a torn-down terminal
+        // never re-points or reopens the socket (connection.setSession below).
+        if (isDestroyed()) {
+          return;
+        }
         // Detach (design 5.1): make input safe before the socket is re-pointed.
         // End any in-flight IME composition and clear the textarea so
         // half-composed text is not delivered to either session, and let every
@@ -674,6 +710,12 @@ export function createTerminal(
 
   // --- Feature lifecycle ---
   let destroyed = false;
+  // Live read of `destroyed` for the post-await re-check in setupFeatures():
+  // a plain `if (destroyed)` there is narrowed to always-false by TS CFA
+  // (it cannot model destroy() firing during the await), tripping
+  // @typescript-eslint/no-unnecessary-condition. A call defeats the stale
+  // narrowing with identical runtime behavior.
+  const isDestroyed = (): boolean => destroyed;
   function teardownFeatures(): void {
     for (let i = instances.length - 1; i >= 0; i--) {
       const entry = instances[i];
@@ -696,6 +738,19 @@ export function createTerminal(
       }
       try {
         const instance = await feature.setup(makeContext(feature.name));
+        // destroy() may have run during the await above; teardownFeatures() has already
+        // swept `instances`, and destroy() is one-shot, so a straight push here would
+        // leave this instance's listeners/timers/observers (tabs' SSE + poll + window/
+        // document listeners + ResizeObservers) alive forever. Tear it down instead of
+        // registering it.
+        if (isDestroyed()) {
+          try {
+            instance.teardown();
+          } catch (err) {
+            reportError(feature.name, err);
+          }
+          return;
+        }
         instances.push({ feature, instance });
         // Populate the feature value's readonly api (consumer pattern:
         // tabs.api?.create()) via a narrow cast, and the ctx.use lookup map.
@@ -714,12 +769,6 @@ export function createTerminal(
       }
     }
   }
-  // Features set up in the background; first paint is never gated on them.
-  void setupFeatures();
-
-  // --- Connect + focus ---
-  render.updateFontMetrics();
-  composition.positionCompositionView();
   // A session-managing feature (tabs) drives the first connect itself once it
   // has resolved a session id (ctx.notifySwitch -> connection.setSession, which
   // adds ?session=<id>). Connecting here first would open a bare /ws that a
@@ -727,6 +776,23 @@ export function createTerminal(
   // churning the reconnect backoff until the feature sets a session. So skip the
   // startup connect when managed; the single-terminal presets leave it to us.
   const sessionManaged = featureList.some((f) => f.managesSessions === true);
+
+  // Features set up in the background; first paint is never gated on them.
+  void setupFeatures().then(() => {
+    // A session-managing feature that finished setup WITHOUT initiating a
+    // connection means its bootstrap failed (no session could be listed or
+    // spawned) or its setup threw. markReady (needs a screen frame) and onGiveUp
+    // (needs the connect to be attempted and fail) then never fire, so the
+    // loading overlay would stay up forever, hiding the retry chrome the feature
+    // keeps alive (tabs' "+"). Dismiss it so the page shows its real state.
+    if (sessionManaged && !connectionInitiated && !destroyed) {
+      dismissLoadingOverlay();
+    }
+  });
+
+  // --- Connect + focus ---
+  render.updateFontMetrics();
+  composition.positionCompositionView();
   if (!sessionManaged) {
     connection.connect();
     connectionInitiated = true;
@@ -742,6 +808,12 @@ export function createTerminal(
       destroyed = true;
       teardownFeatures();
       kernelAbort.abort();
+      viewport.teardown();
+      // Reset the composition singleton (kernel-driven, no feature teardown): a
+      // destroy() mid-IME-composition otherwise leaves module-level `composing`
+      // stuck true, so a remounted terminal swallows every keydown until an IME
+      // cycle resets it; also neutralizes a pending compositionend setTimeout.
+      composition.teardown();
       connection.disconnect();
       connState.destroy();
       if (toastTimer !== null) {

package/src/presets.ts

@@ -4,13 +4,14 @@
 // lists (convenient, full UI); a consumer wanting a minimal footprint imports
 // individual features instead.
 //
-// The tabbed presets (presetTabbed / presetAgentTabbed) are now identical: both
-// include the activity monitor, because the per-tab activity dot reveals itself
-// only when a session reports activity (OSC 9;4 progress), so a plain shell
-// simply never shows one. The generic-vs-agent distinction is now purely
-// server-side — an agent server sets a status classifier that maps OSC 9
-// notifications to done/needs-input. presetAgentTabbed is kept as an alias for
-// its consumers (vibecli).
+// The tabbed presets (presetTabbed / presetAgentTabbed) share the same feature
+// set (both include the activity monitor, whose per-tab dot reveals itself only
+// on OSC 9;4 progress, so a plain shell never shows one). They differ in the
+// title source: presetAgentTabbed sets preferInputTitle (the agent's program
+// emits a useless OSC title, so the label follows the latest submitted line),
+// while presetTabbed is OSC-first. The generic-vs-agent STATUS distinction stays
+// server-side — an agent server sets a classifier mapping OSC 9 notifications to
+// done/needs-input.
 
 import type { TerminalFeature } from "./kernel/types.js";
 import { clipboard } from "./features/clipboard.js";
@@ -50,14 +51,14 @@ export function presetTouch(): TerminalFeature<unknown>[] {
 // per tab only when a session reports activity (OSC 9;4), so the monitor is
 // always included — a plain shell just never reveals a dot. The toolbar and
 // monitor are ordered before tabs because tabs reads their APIs via ctx.use.
-function buildTabbed(): TerminalFeature<unknown>[] {
+function buildTabbed(preferInputTitle: boolean): TerminalFeature<unknown>[] {
   const kb = mobileToolbar({ externalToggle: true });
   const monitor = activityMonitor();
   return [
     ...presetSingle(),
     kb,
     monitor,
-    tabs({ keyboardToggle: kb, activityMonitor: monitor }),
+    tabs({ keyboardToggle: kb, activityMonitor: monitor, preferInputTitle }),
     animations(),
   ];
 }
@@ -71,13 +72,15 @@ function buildTabbed(): TerminalFeature<unknown>[] {
  *  reports activity via OSC 9;4 progress (kiro-cli, Claude Code, …), so a plain
  *  bash/sh keeps clean, label-only tabs. */
 export function presetTabbed(): TerminalFeature<unknown>[] {
-  return buildTabbed();
+  return buildTabbed(false);
 }
 
-/** Alias of presetTabbed, kept for the agent-shell consumer (vibecli). The UI is
- *  identical — the generic-vs-agent distinction is now purely server-side: an
- *  agent server sets a status classifier (mapping OSC 9 notifications to
- *  done/needs-input), and each tab's dot reveals itself from OSC 9;4 either way. */
+/** Tabbed UI for an agent shell (vibecli). Same features as presetTabbed, but
+ *  with `preferInputTitle`: the agent's program (kiro-cli) emits a non-empty but
+ *  useless OSC 0/2 title, so each tab's label follows the latest submitted line
+ *  (persisted server-side and recovered on reload) and the OSC title is ignored.
+ *  The agent-vs-generic status distinction remains server-side (a status
+ *  classifier mapping OSC 9 notifications to done/needs-input). */
 export function presetAgentTabbed(): TerminalFeature<unknown>[] {
-  return buildTabbed();
+  return buildTabbed(true);
 }

package/src/viewport.ts

@@ -24,6 +24,15 @@ let onSettled: ((wasAtBottom: boolean) => void) | null = null;
 let inTransition = false;
 let wasAtBottomAtStart = true;
 let settleTimer: ReturnType<typeof setTimeout> | null = null;
+// When true, ignore the visualViewport keyboard geometry entirely (a hardware
+// keyboard/trackpad is present, so the soft keyboard never opens). Set at init
+// from the kernel's hasFinePointer; see the onChange note below.
+let suppressKeyboardInset: () => boolean = () => false;
+// Removals for every listener/observer init() attaches, so teardown() can
+// release them on kernel destroy(). Without it the window/visualViewport/
+// screen.orientation listeners and the ResizeObserver survive destroy() and a
+// re-created terminal double-binds them.
+let cleanup: (() => void)[] = [];
 
 function startTransition(): void {
   // Capture pre-transition scroll state at the *start* of the transition,
@@ -51,9 +60,14 @@ function startTransition(): void {
 export function init(opts: {
   termWrap: HTMLElement;
   onSettled: (wasAtBottom: boolean) => void;
+  /** Ignore the visualViewport keyboard geometry (a hardware-keyboard device
+   *  has no soft keyboard to accommodate); only reserved bottom chrome insets
+   *  the terminal. The kernel passes its hasFinePointer here. */
+  suppressKeyboardInset?: () => boolean;
 }): void {
   termWrap = opts.termWrap;
   onSettled = opts.onSettled;
+  suppressKeyboardInset = opts.suppressKeyboardInset ?? (() => false);
 
   // iOS soft keyboard. interactive-widget=resizes-content makes the
   // layout viewport shrink; we still apply a manual bottom inset as
@@ -72,15 +86,26 @@ export function init(opts: {
       // scroll" symptom). Driving top AND bottom from visualViewport keeps the
       // terminal exactly over the visible area in every browser, so nothing is
       // left behind the keyboard for iOS to scroll to.
-      const offsetTop = Math.max(0, Math.round(vv.offsetTop));
-      const bottomInset = Math.max(0, Math.round(window.innerHeight - vv.offsetTop - vv.height));
+      // suppressKeyboardInset (set at init from the kernel's hasFinePointer): on
+      // a device with a hardware keyboard/trackpad (a desktop, or an iPad with a
+      // Magic Keyboard) the on-screen keyboard never opens, so there is no
+      // keyboard geometry to accommodate. iPadOS has been seen to briefly report
+      // a keyboard-sized visualViewport shrink with no keyboard shown, which this
+      // handler then pinned as a bottom inset and left stuck (the terminal "moved
+      // up ~50%", black below, surviving tab switches because nothing recomputes
+      // it — only a reload cleared it). Ignore the keyboard geometry there and
+      // keep the terminal full-height; only the reserved bottom chrome applies.
+      const offsetTop = suppressKeyboardInset() ? 0 : Math.max(0, Math.round(vv.offsetTop));
+      const bottomInset = suppressKeyboardInset()
+        ? 0
+        : Math.max(0, Math.round(window.innerHeight - vv.offsetTop - vv.height));
       // Reserved bottom chrome (a bottom tab bar) the content must clear, on top
       // of the keyboard inset. A feature sets --wt-reserve-bottom (px) on the
       // root, 0 when none; viewport owns the terminal's fixed-box geometry, so it
       // folds the reserve into the bottom offset here. The reserve excludes the
       // keyboard (it is measured with the keyboard closed), so adding it to
       // bottomInset does not double-count.
-      const reserve = Math.max(
+      const rawReserve = Math.max(
         0,
         Math.round(
           parseFloat(
@@ -88,6 +113,12 @@ export function init(opts: {
           ) || 0,
         ),
       );
+      // Sanity cap: the reserve is bottom chrome (a tab bar), tens of px. A value
+      // near half the screen is a bad measurement — e.g. the switcher bar
+      // measured while a phantom keyboard inset had lifted it — that would
+      // otherwise strand the lower half of the terminal black. Never let it
+      // exceed a third of the viewport height.
+      const reserve = Math.min(rawReserve, Math.round(window.innerHeight / 3));
       const bottom = bottomInset + reserve;
       termWrap.style.top = offsetTop > 0 ? `${offsetTop}px` : "";
       termWrap.style.bottom = bottom > 0 ? `${bottom}px` : "";
@@ -102,6 +133,20 @@ export function init(opts: {
     };
     vv.addEventListener("resize", onChange);
     vv.addEventListener("scroll", onChange);
+    // Self-heal a stuck inset (see the fine-pointer note above): recompute when
+    // the window regains focus or is restored from the bfcache, so a one-off bad
+    // visualViewport reading that got pinned clears on the next natural
+    // interaction instead of surviving until a full page reload.
+    window.addEventListener("focus", onChange);
+    window.addEventListener("pageshow", onChange);
+    cleanup.push(() => {
+      window.removeEventListener("focus", onChange);
+      window.removeEventListener("pageshow", onChange);
+    });
+    cleanup.push(() => {
+      vv.removeEventListener("resize", onChange);
+      vv.removeEventListener("scroll", onChange);
+    });
     onChange();
   }
 
@@ -109,6 +154,10 @@ export function init(opts: {
   const ro = new ResizeObserver(startTransition);
   ro.observe(termWrap);
   window.addEventListener("resize", startTransition);
+  cleanup.push(() => {
+    ro.disconnect();
+    window.removeEventListener("resize", startTransition);
+  });
 
   // Orientation change on mobile. iOS Safari often emits the
   // window.resize event late or not at all on rotation while
@@ -120,7 +169,35 @@ export function init(opts: {
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard for older Safari without screen.orientation
   if (orientation) {
     orientation.addEventListener("change", startTransition);
+    cleanup.push(() => {
+      orientation.removeEventListener("change", startTransition);
+    });
   } else if ("onorientationchange" in window) {
     window.addEventListener("orientationchange", startTransition);
+    cleanup.push(() => {
+      window.removeEventListener("orientationchange", startTransition);
+    });
   }
 }
+
+// Release every listener/observer init() attached and stop the settle timer.
+// The kernel calls this from destroy() so a create->destroy->create remount
+// does not leave stale global listeners double-bound.
+export function teardown(): void {
+  for (const fn of cleanup) {
+    fn();
+  }
+  cleanup = [];
+  if (settleTimer !== null) {
+    clearTimeout(settleTimer);
+    settleTimer = null;
+  }
+  // Clear the global root CSS vars onChange published, so a destroy without
+  // a remount (which would recompute them) leaves no stale inset on :root.
+  const rootStyle = document.documentElement.style;
+  rootStyle.removeProperty("--kb-inset");
+  rootStyle.removeProperty("--vv-top");
+  inTransition = false;
+  onSettled = null;
+  suppressKeyboardInset = () => false;
+}