@cplieger/web-terminal-ui 3.3.1 → 3.4.1

package/css/06-mobile.css

@@ -1,17 +1,20 @@
 /* ===== Mobile tab chrome (tabs feature, section 12) =====
    The bottom bar (switcher) is the mobile tab surface, the externally-driven key
    grid docks above it, and the overview sheet lists every tab. The desktop strip
-   is hidden on a coarse pointer and these appear instead; all motion (bar number
-   fade, sheet slide) lives in 07-animations.css. */
-
-/* The switcher is hidden on a fine pointer, where the top strip is used instead;
-   the top strip is correspondingly hidden on a coarse pointer so tabs live in
-   the thumb zone. */
+   is hidden only on a narrow coarse-pointer device (a phone) and these appear
+   instead; all motion (bar number fade, sheet slide) lives in 07-animations.css. */
+
+/* The switcher is used only on a NARROW coarse-pointer device (a phone), where
+   the top strip is hidden so tabs live in the thumb zone. A wide touchscreen (an
+   iPad) and any fine-pointer device keep the multi-tab top strip — a single
+   giant tab wastes a big screen. This media query MUST stay in lockstep with
+   SWITCHER_MEDIA in src/features/tabs.ts and the complementary strip clearance
+   in css/05-tabs.css. */
 .wt-switcher {
   display: none;
 }
 
-@media (pointer: coarse) {
+@media (pointer: coarse) and (width <= 600px) {
   .wt-tab-bar,
   .wt-tab-new {
     display: none;
@@ -57,7 +60,11 @@
   padding: 0 var(--sp-2);
   display: flex;
   flex-direction: column;
-  gap: 2px;
+  /* A touch more room than the desktop strip's --sp-1: vertical touch rows read
+     better with a bit more separation, and this equals the bar's --sp-2 bottom
+     padding so the active-tab -> first-row seam matches the inter-row gap (see
+     the expanded-list padding-top: 0 below). */
+  gap: var(--sp-2);
   max-height: 0;
   overflow: hidden;
   /* max-height caps the whole box (incl. the expanded padding) so an interactive
@@ -67,9 +74,14 @@
 }
 
 .wt-switcher-expanded .wt-switcher-list {
-  max-height: 50vh;
+  /* Cap against the DYNAMIC viewport so a shown mobile browser toolbar can't push the list
+     (and the bar above it) off the top; the switcher's own bottom: kb-inset already lifts it
+     clear of the soft keyboard. */
+  max-height: var(--wt-list-h, 50dvh);
   overflow-y: auto;
-  padding-top: var(--sp-1);
+  /* No top padding: the bar's --sp-2 bottom padding already sits between the
+     active tab and the first row, so the seam equals the --sp-2 inter-row gap. */
+  padding-top: 0;
   padding-bottom: var(--sp-1);
 }
 
@@ -102,7 +114,7 @@
      fill/foreground the desktop strip uses (themeable; purple in vibecli). */
   background: var(--tab-active-bg);
   color: var(--tab-active-fg);
-  border: none;
+  border: 1px solid var(--tab-active-border);
   border-radius: var(--radius-inner);
   font-family: var(--font-ui);
   font-size: 0.875rem;
@@ -167,6 +179,13 @@
    button collapses to zero width and fades out (the key grid is closed too, in
    JS), and the active row flex-grows to fill the freed space. */
 .wt-switcher-kb {
+  /* Rigid 44px box like the "+" and switch buttons (flex: none), so a long
+     active-tab title that overflows the bar is absorbed entirely by the
+     ellipsizing active-tab field, not shared with this button. It is otherwise
+     the only bar control with flex-shrink, so it squished (≈28px, non-square) on
+     long-title tabs while staying square on short ones. The `width` below still
+     drives the expand-collapse animation; flex: none honours it. */
+  flex: none;
   width: var(--touch-target);
   /* Override .wt-btn's min-width (the 44px tap floor). min-width is NOT
      transitioned, so on collapse it would revert to 44px instantly and clamp the
@@ -206,6 +225,61 @@
   pointer-events: none;
 }
 
+/* Tab-switcher button: toggles the list open/closed, sitting between the
+   keyboard and "+" buttons. position: relative anchors its notification dot,
+   absolutely placed in the top-right corner. It only earns its place with ≥2
+   tabs (a single tab has nothing to switch to), so it is COLLAPSED to zero width
+   by default and revealed by .wt-switcher-multi (the tabs feature sets it on tab
+   count); the appear/collapse is animated in 07-animations.css and the active
+   chip shrinks/grows to fill the freed space in lockstep (flex layout). */
+.wt-switcher-switch {
+  position: relative;
+  flex: none;
+  width: 0;
+  min-width: 0;
+  padding: 0;
+  opacity: 0;
+  overflow: hidden;
+  pointer-events: none;
+  /* Absorb the flex gap the zero-width button would otherwise leave between the
+     active row and the "+". */
+  margin-inline-start: calc(-1 * var(--sp-1));
+}
+
+/* Revealed once a second tab exists: full 44px box, interactive, no gap eat. */
+.wt-switcher-multi .wt-switcher-switch {
+  width: var(--touch-target);
+  opacity: 1;
+  pointer-events: auto;
+  margin-inline-start: 0;
+}
+
+@media (hover: hover) {
+  .wt-switcher-switch:hover {
+    background: var(--tab-hover-bg);
+  }
+}
+
+/* Latest-wins background-tab notification dot on the switch button — the moved
+   attention cue. Amber = a background terminal needs input, green = a background
+   turn finished. Reuses the exact .wt-status-dot colours (05-tabs.css) so it
+   matches the per-tab dots. Hidden until the tabs feature sets data-status;
+   cleared when the list opens (expandSwitcher). */
+.wt-switcher-switch-dot {
+  position: absolute;
+  top: 6px;
+  right: 6px;
+}
+
+/* The dot carries the .wt-status-dot class, so its size, shape, and colour come
+   straight from the shared .wt-status-dot[data-status="input"|"done"] rules
+   (05-tabs.css) — the SAME dot colours every tab already uses, defined once.
+   .wt-status-dot is display:none by default; force it visible only while a
+   notification is set (data-status present). */
+.wt-switcher-switch-dot[data-status] {
+  display: block;
+}
+
 /* Mobile "+": the primary action, carried in the accent colour so it reads as
    permanent and prominent. Hover fill is gated to real hover pointers: on touch,
    :hover sticks after a tap (no pointer-leave), so the purple would linger — the
@@ -225,31 +299,12 @@
   background: var(--tab-hover-bg);
 }
 
-/* Aggregate needs-input attention now rides the active surface (the separate
-   overview button is gone): a background tab is blocked on you, and a tap /
-   swipe-up here opens the overview to resolve it. Shape + color (an inset ring
-   plus a corner glyph), never hue alone (WCAG 1.4.1). */
-.wt-switcher-current[data-attention="input"] {
-  box-shadow: inset 0 0 0 2px oklch(70% 0.18 25deg / 45%);
-}
-
-.wt-switcher-current[data-attention="input"]::after {
-  content: "";
-  position: absolute;
-  top: 4px;
-  right: 4px;
-  width: 8px;
-  height: 8px;
-  border-radius: 50%;
-  background: oklch(70% 0.18 25deg);
-}
-
 /* ===== Externally-driven key grid (tabbed presets, WS3) =====
    In the tabbed presets the mobile toolbar hides its own toggle (the tab bar's
    keyboard button drives it) and the grid docks above the bar on the right, to
    the left of where scroll-to-bottom sits. It collapses to fully hidden, since
    there is no in-grid toggle to keep visible. */
-@media (pointer: coarse) {
+@media (pointer: coarse) and (width <= 600px) {
   .wt-toolbar-external .kb-toggle {
     display: none;
   }
@@ -268,6 +323,36 @@
   }
 }
 
+/* Desktop tab strip on a WIDE touchscreen (an iPad): the mobile switcher is
+   gone, so the desktop strip carries its OWN keyboard button (.wt-tab-kb, built
+   by the same factory as the switcher's — see css/05-tabs.css + tabs.ts) to open
+   the key grid. So, exactly like switcher mode, the toolbar's own toggle is
+   hidden and the collapsed grid fully hidden — the tab-strip keyboard button is
+   the sole control (this replaces the old CSS-only workaround that un-hid the
+   toolbar's own toggle here). The grid still docks bottom-right ABOVE the strip:
+   above the tabs (never overlapping them, even when many are open and the strip
+   scrolls) and to the left of the scroll-to-bottom FAB (same right offset as
+   switcher mode). Complements the strip-shown breakpoint in css/05-tabs.css;
+   keep in lockstep with SWITCHER_MEDIA in src/features/tabs.ts. */
+@media (pointer: coarse) and (width >= 601px) {
+  .wt-toolbar-external .kb-toggle {
+    display: none;
+  }
+
+  .key-toolbar.wt-toolbar-external {
+    top: auto;
+    right: calc(var(--sp-3) + var(--touch-target) + var(--sp-2));
+    bottom: calc(
+      var(--wt-tabbar-h, 44px) + var(--safe-bottom, 0px) + var(--kb-inset, 0px) + var(--sp-2)
+    );
+    grid-template-columns: repeat(4, var(--touch-target));
+  }
+
+  .key-toolbar.wt-toolbar-external.collapsed {
+    display: none;
+  }
+}
+
 /* ===== Expanded tab-list rows (tabs feature) =====
    One row per OTHER tab in the expanded list: a stretched select target (dot +
    label) with the close (x) laid inside at the right, mirroring the desktop
@@ -285,9 +370,9 @@
   min-height: var(--touch-target);
   /* Right padding reserves room for the close (x) overlaid inside the box. */
   padding: 0 var(--touch-target) 0 var(--sp-2);
-  background: transparent;
+  background: var(--tab-bg);
   color: var(--text);
-  border: none;
+  border: 1px solid var(--border);
   border-radius: var(--radius-inner);
   font-family: var(--font-ui);
   font-size: 0.875rem;
@@ -298,15 +383,16 @@
 
 @media (hover: hover) {
   .wt-switcher-row-select:hover {
-    background: var(--tab-hover-bg);
+    background: color-mix(in oklch, var(--tab-bg), var(--text) 15%);
   }
 }
 
-/* Press / touch-hold feedback on a listed (inactive) tab: the same subtle fill
-   the "+" button uses (--tab-hover-bg), NOT the stronger active-tab fill, so an
-   inactive row never looks like the active one. */
+/* Press / touch-hold feedback on a listed (inactive) tab: a solid lift over the
+   chip (the same 15% --text lift the desktop tabs use), not the translucent
+   --tab-hover-bg wash that would erase the chip fill. The active tab is set apart
+   by its accent border, so a lit inactive row is never mistaken for it. */
 .wt-switcher-row-select:active {
-  background: var(--tab-hover-bg);
+  background: color-mix(in oklch, var(--tab-bg), var(--text) 15%);
 }
 
 .wt-switcher-row-label {

package/css/07-animations.css

@@ -1,18 +1,27 @@
 /* ===== Animations (animations feature) =====
-   Every bit of motion in the UI lives here, gated on the root .wt-animate class
-   that the animations feature sets only when the OS is not in reduced-motion.
-   Without the feature (or under prefers-reduced-motion) the UI is instant: base
-   rules in 03-06 carry the resting state, and these rules add the transitions
-   and keyframes on top. Keeping motion in one file is the design-system seam for
-   "does this UI animate, and how". */
+   Chrome-surface motion is centralized here, gated on the root .wt-animate class
+   that the animations feature sets only when the OS is not in reduced-motion:
+   base rules in 03-06 carry the resting state, and these rules add the
+   transitions and keyframes on top. A few pieces of motion are intentionally NOT
+   gated on .wt-animate and animate unconditionally: terminal-core motion (cursor
+   and SGR blink) and the mobile key toolbar open/close in 02-app.css, plus the
+   working-status-dot pulse in 05-tabs.css (motion is its only non-hue cue, per
+   WCAG 1.4.1). prefers-reduced-motion still defeats all of it via the reset in
+   01-reset.css. Keeping the chrome-surface motion in one file is the
+   design-system seam for "does this chrome animate, and how". */
 
-/* Fade transient surfaces in/out (display allow-discrete plays the fade before
-   the discrete display:none on hide). */
-.wt-animate .wt-toast,
-.wt-animate .wt-conn-banner,
-.wt-animate .wt-scroll-bottom,
-.wt-animate .wt-ctx-menu,
-.wt-animate .wt-tab-menu {
+/* Fade the toast OUT on hide (display allow-discrete holds display:block for
+   the fade, then flips to display:none). It appears INSTANTLY on show: a
+   transition out of display:none does not animate without a matching
+   @starting-style rule (none is defined in css/), so opacity snaps 0->1 on
+   show. Only the toast sets opacity in its base and
+   .visible rules, so only it can interpolate. The other transient surfaces
+   (connection banner, scroll-to-bottom, context menu, tab menu) toggle `display`
+   only and never set opacity, so they are intentionally not listed here: a
+   shared opacity transition would be inert while the `display allow-discrete`
+   half held them fully visible for --dur-standard before popping out on hide.
+   They show and hide instantly. */
+.wt-animate .wt-toast {
   transition:
     opacity var(--dur-standard) var(--ease-standard),
     display var(--dur-standard) allow-discrete;
@@ -65,6 +74,17 @@
     opacity var(--dur-standard) var(--ease-standard);
 }
 
+/* The dedicated switch button appears when a second tab opens and collapses back
+   at one tab (.wt-switcher-multi, tabs feature). Animate its width + margin +
+   opacity so it slides in from zero width — the active-tab chip shrinks to make
+   room in lockstep (flex) — rather than popping. Mirrors the keyboard button. */
+.wt-animate .wt-switcher-switch {
+  transition:
+    width var(--dur-enter) var(--ease-standard),
+    margin var(--dur-enter) var(--ease-standard),
+    opacity var(--dur-standard) var(--ease-standard);
+}
+
 /* Switch motion: a subtle content fade on switch, so the cache-first repaint
    reads as a change rather than a flicker. A swipe additionally slides the
    content in from the swipe's direction (next from the right, prev from the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "3.3.1",
+  "version": "3.4.1",
   "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": "GPL-3.0-or-later",

package/src/composition.ts

@@ -26,14 +26,13 @@
 // uses the textarea as its anchor; we move the textarea to the cursor
 // for the same reason.
 
-import { keyboard } from "@cplieger/web-terminal-engine";
 import { resetToPlaceholder } from "./input-placeholder.js";
-const { bracketTextForPaste, prepareTextForTerminal } = keyboard;
 
 let textarea: HTMLTextAreaElement;
 let compositionView: HTMLElement;
 let getCursorPx: () => { left: number; top: number; cellH: number };
 let send: (bytes: string) => void;
+let paste: (text: string) => void;
 
 let composing = false;
 let sendingComposition = false;
@@ -45,11 +44,15 @@ export function init(opts: {
   compositionView: HTMLElement;
   getCursorPx: () => { left: number; top: number; cellH: number };
   send: (bytes: string) => void;
+  /** The kernel's single bracketed-paste+normalize funnel; the native iOS-callout
+   *  paste routes through it rather than re-composing the funnel here. */
+  paste: (text: string) => void;
 }): void {
   textarea = opts.textarea;
   compositionView = opts.compositionView;
   getCursorPx = opts.getCursorPx;
   send = opts.send;
+  paste = opts.paste;
 
   textarea.addEventListener("compositionstart", onStart);
   textarea.addEventListener("compositionupdate", onUpdate);
@@ -79,6 +82,26 @@ export function cancelComposition(): void {
   resetToPlaceholder(textarea);
 }
 
+/** Release init()-attached listeners and drop the captured kernel closures on kernel
+ *  destroy(), so a destroy without a remount does not retain the old textarea + the
+ *  kernel send/paste closure graph. Mirrors viewport.teardown(). */
+export function teardown(): void {
+  cancelComposition(); // neutralize a pending finalizer + reset composing state
+  textarea.removeEventListener("compositionstart", onStart);
+  textarea.removeEventListener("compositionupdate", onUpdate);
+  textarea.removeEventListener("compositionend", onEnd);
+  textarea.removeEventListener("paste", onPaste);
+  // Drop references to the old kernel instance so its closure graph is GC-eligible
+  // (the detached textarea/compositionView are overwritten on the next init()).
+  send = () => {
+    /* no-op after teardown */
+  };
+  paste = () => {
+    /* no-op after teardown */
+  };
+  getCursorPx = () => ({ left: 0, top: 0, cellH: 0 });
+}
+
 function onStart(): void {
   composing = true;
   const start = textarea.selectionStart;
@@ -118,7 +141,9 @@ function onEnd(): void {
       suffixSnapshot.length > 0 && value.endsWith(suffixSnapshot)
         ? value.length - suffixSnapshot.length
         : value.length;
-    const composed = value.substring(startSnapshot, Math.max(startSnapshot, valueEnd));
+    const composed = value
+      .substring(startSnapshot, Math.max(startSnapshot, valueEnd))
+      .replace(/\u00A0/g, " ");
     if (composed.length > 0) {
       send(composed);
     }
@@ -139,7 +164,7 @@ function onPaste(ev: ClipboardEvent): void {
   }
   ev.preventDefault();
   ev.stopPropagation();
-  send(bracketTextForPaste(prepareTextForTerminal(raw)));
+  paste(raw);
   // Restore the placeholder so the subsequent `input` event (some
   // browsers fire it after paste) and held-Backspace auto-repeat keep
   // working.

package/src/features/activity-monitor.ts

@@ -38,7 +38,14 @@ export function activityMonitor(
             statuses.set(s.id, s);
           }
           for (const cb of [...subs]) {
-            cb(s);
+            try {
+              cb(s);
+            } catch (err) {
+              // Isolate a throwing subscriber so it neither skips the
+              // remaining subscribers nor propagates into the engine's
+              // SSE reader (mirrors the kernel bus's ctx.on wrapping).
+              console.error("web-terminal-ui: activityMonitor subscriber threw", err);
+            }
           }
         },
       });

package/src/features/animations.ts

@@ -1,8 +1,13 @@
-// animations feature: opt-in motion (design sections 13, 22.4). Without it the
-// UI is instant (no transitions); with it, and when the user has not asked for
-// reduced motion, it enables the shared animation vocabulary by marking the
-// terminal root, which the feature stylesheets key their transitions off. It
-// tracks prefers-reduced-motion live so toggling the OS setting takes effect.
+// animations feature: opt-in motion for the chrome surfaces (design sections
+// 13, 22.4). Without it the chrome surfaces are instant (no transitions); with
+// it, and when the user has not asked for reduced motion, it enables the shared
+// animation vocabulary by marking the terminal root, which the feature
+// stylesheets key their transitions off. A few pieces of motion animate
+// unconditionally regardless of this feature (terminal-core cursor/SGR blink and
+// the mobile key toolbar open/close in 02-app.css, plus the working-status-dot
+// pulse in 05-tabs.css, its WCAG non-hue cue), though prefers-reduced-motion
+// still defeats all of it. It tracks prefers-reduced-motion live so toggling the
+// OS setting takes effect.
 
 import type { TerminalFeature } from "../kernel/types.js";
 

package/src/features/clipboard.ts

@@ -89,9 +89,15 @@ export function clipboard(): TerminalFeature<ClipboardApi> {
         copy(text);
       });
 
-      // Native copy (e.g. Cmd/Ctrl+C on a selection) feedback toast.
+      // Native copy (e.g. Cmd/Ctrl+C on a selection) feedback toast, scoped to a
+      // selection inside the terminal surface so an embedding host's copies of
+      // its own (non-terminal) content do not raise a spurious "Copied".
+      const surface = ctx.surface();
       const onCopy = (): void => {
-        ctx.toast("Copied");
+        const node = window.getSelection()?.anchorNode ?? null;
+        if (node && surface.contains(node)) {
+          ctx.toast("Copied");
+        }
       };
       document.addEventListener("copy", onCopy);
 

package/src/features/connection-banner.ts

@@ -20,7 +20,6 @@ export function connectionBanner(): TerminalFeature {
       const slot = ctx.region("banner", "status");
       const banner = document.createElement("div");
       banner.className = "wt-conn-banner";
-      banner.setAttribute("role", "status");
       slot.appendChild(banner);
 
       let last: ConnState | null = null;

package/src/features/context-menu.ts

@@ -53,6 +53,28 @@ export interface ContextMenuOptions {
   clipboard?: TerminalFeature<ClipboardApi>;
 }
 
+/** iPhone/iPad/iPod, including iPadOS Safari's default "desktop mode" (which
+ *  reports platform MacIntel but with a touch screen). On these, a long-press on
+ *  text fires `contextmenu` slightly BEFORE the native word-selection registers,
+ *  so hasNativeSelection() is still false at that instant and the Android
+ *  empty-space branch would wrongly open our menu and preventDefault the native
+ *  selection. Deferring on any Apple touch device lets iOS/iPadOS run its own
+ *  text selection + drag handles (bug: an iPad long-press opened the custom menu
+ *  instead of native selection, leaving Select All the only way to select). */
+function isAppleTouchDevice(): boolean {
+  if (typeof navigator === "undefined") {
+    return false;
+  }
+  const ua = navigator.userAgent || "";
+  const platform = navigator.platform || "";
+  if (/iP(hone|ad|od)/.test(ua) || /iP(hone|ad|od)/.test(platform)) {
+    return true;
+  }
+  // iPadOS 13+ Safari defaults to desktop mode: platform "MacIntel" but a touch
+  // screen (maxTouchPoints > 1). A real trackpad Mac reports maxTouchPoints 0.
+  return platform === "MacIntel" && navigator.maxTouchPoints > 1;
+}
+
 export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
   return {
     name: "contextMenu",
@@ -68,6 +90,9 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
       // desktop right-click AND on Android long-press, so its handler branches
       // on this to tell them apart.
       let lastPointerType = "mouse";
+      // Computed once: on an Apple touch device, defer a touch contextmenu to
+      // native text selection (see isAppleTouchDevice).
+      const appleTouch = isAppleTouchDevice();
       // Timestamp until which a document click is swallowed (see SWALLOW_MS).
       let swallowUntil = 0;
       // A native selection was made during the current touch press (tracked via
@@ -220,6 +245,13 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
         if (hasNativeSelection()) {
           return; // native selection toolbar owns Copy over text
         }
+        if (appleTouch) {
+          // iOS/iPadOS fires contextmenu a beat before the native word-select
+          // registers, so hasNativeSelection() can still be false here. Defer
+          // anyway so the platform's own selection wins instead of our
+          // empty-space menu (which would preventDefault and suppress it).
+          return;
+        }
         e.preventDefault();
         clearLongPress();
         show(e.clientX, e.clientY, true);

package/src/features/predictive-echo.ts

@@ -47,6 +47,16 @@ export function predictiveEcho(): TerminalFeature {
       });
 
       return {
+        // A tab switch (kernel notifySwitch -> onDetach) must drop the predicted
+        // cursor, so the outgoing session's ghost cursor does not paint on the
+        // incoming session's freshly-bound screen until its first server frame
+        // re-arms prediction. Mirrors composition.cancelComposition on the same
+        // detach: both local-echo paths reset on switch. predict.reset() hides the
+        // overlay (its onChange -> push -> setPredictedCursor(0,0,false)); the next
+        // wire:screen re-arms via onScreenFrame.
+        onDetach() {
+          predict.reset();
+        },
         teardown() {
           offTransform();
           offObserver();