@cplieger/web-terminal-ui 4.6.0 → 4.7.1

package/README.md

@@ -143,7 +143,7 @@ are importable from `…/features/<name>` (`clipboard`, `context-menu`,
 | `wsPath`       | `"/ws"`                    | WebSocket endpoint path the engine connects to.                                                                                                                                                                                                                                               |
 | `fontReady`    | `'14px "MonaspiceNe NFM"'` | CSS font shorthand awaited before the first resize, so the server is sized against the real web font's cell metrics rather than a fallback.                                                                                                                                                   |
 | `loading`      | _(none)_                   | A pre-JS loading overlay element (kept in your served HTML so it paints before this module loads); it is faded out and removed once the first frame renders.                                                                                                                                  |
-| `onFatalError` | _(built-in recovery)_      | Called with `{ phase, feature, cause }` after a fatal feature setup failure; behavior below.                                                                                                                                                                                                  |
+| `onFatalError` | _(built-in recovery)_      | Called with a `TerminalStartupFailure` after a fatal startup failure, in either phase (`feature-setup` or `kernel-init`); behavior below.                                                                                                                                                     |
 | `theme`        | _(none)_                   | Theme overrides (CSS custom properties on the terminal root): `--accent`, `--tab-bg`, `--tab-hover-bg`, `--tab-active-bg`, `--tab-active-fg`, `--tab-active-border`, plus the activity-dot palette `--status-working`, `--status-done`, `--status-input`. The library ships neutral defaults. |
 
 `createTerminal()` returns a handle: `focus()` re-focuses the terminal input
@@ -154,11 +154,19 @@ screen without injecting keystrokes (send a redraw keystroke yourself if you
 want one, for example Ctrl+L); and `destroy()` tears every feature down and
 releases the kernel.
 
-If a feature's setup throws or rejects, the kernel stops the connection, tears
-down every completed feature and core listener, clears the broken subtree, and
-shows a reload surface. The surface is modal when the terminal owns the
-viewport and non-modal when it fills an embedded container. `onFatalError`
-receives the failure after cleanup; return `true` only when the host has rendered
+Startup can fail in two phases, and both end at the same recovery surface. If a
+feature's setup throws or rejects (`phase: "feature-setup"`), the kernel stops the
+connection, tears down every completed feature and core listener, clears the
+broken subtree, and shows a reload surface. If `createTerminal` itself throws
+(`phase: "kernel-init"` — an invalid feature list, a DOM invariant), it shows the
+same surface, lowers your loading overlay so the surface is visible, and then
+rethrows, so a caller with its own error handling still sees the error. Either
+way the surface is modal when the terminal owns the viewport and non-modal when
+it fills an embedded container.
+
+`onFatalError` receives the failure after cleanup. Discriminate on `phase`:
+`feature-setup` names the offending `feature`, `kernel-init` does not, because
+feature composition never began. Return `true` only when the host has rendered
 replacement recovery UI into the terminal root.
 
 ## What ships

package/css/02-terminal.css

@@ -24,10 +24,15 @@
   scrollbar-gutter: stable;
   /* The scroll controller (vterm scroll.ts) is the single owner of
      scrollTop: it pins to the bottom only while the user is following,
-     and does nothing while they are scrolled up reading. New output
-     always appends at the tail (the absolute-index model never inserts
-     above the viewport), so native scroll anchoring is safe to leave on
-     and keeps the read position steady on the rare insert-above. */
+     and does nothing while they are scrolled up reading.
+     Content ABOVE the reading position DOES change: rows are evicted
+     from the top of history at the retention cap, and the trim marker
+     is inserted there. Native scroll anchoring compensates for that on
+     Chrome and Firefox, so it stays enabled here — but WebKit has never
+     implemented it, which is why the renderer also corrects the drift
+     itself (render.ts captureReadAnchor / restoreReadAnchor). That
+     correction measures residual drift, so it is a no-op wherever this
+     declaration already did the job. */
   overflow-anchor: auto;
   /* .term is the scroll container, so the touch-action intersection for a
      touch on the output stops here (the html/body pan-x pan-y does not reach

package/css/30-tabs.css

@@ -86,6 +86,12 @@
   cursor: pointer;
   white-space: nowrap;
   user-select: none;
+  /* Kills the 300ms double-tap-to-zoom delay, which is what makes a double-TAP
+     usable as the touch rename entry: on iPadOS a long-press on this chip starts
+     a reorder drag (it is draggable), so the context menu is unreachable by touch
+     and the double-tap is the only path in. Also removes the tap delay for the
+     ordinary switch tap. */
+  touch-action: manipulation;
 }
 
 /* Inactive tabs read as outlined chips with a subtle dark fill (so adjacent tabs
@@ -131,17 +137,37 @@
   overflow: hidden;
   white-space: nowrap;
   text-overflow: ellipsis;
-  /* Center the INK, not the line box: UI fonts carry more ascent than descent
-     (Noto Sans at 13px: 14px over / 4px under the baseline), so the flex-
-     centered line box leaves the visible text ~1.5px low — reading as
-     baseline-aligned with the activity dot's bottom instead of its center.
-     Trimming the box to the cap-height/alphabetic band makes flexbox center
-     the glyphs themselves, on every platform font. Descender ink still paints
-     (verified: ink overflow survives the overflow: hidden ellipsis clip).
-     Non-supporting browsers simply keep the untrimmed box. Shared by all
-     three chip labels (this one + the two switcher labels in
+  /* Center the INK, not the line box: UI fonts carry far more ascent than
+     descent (the -apple-system/Noto Sans stack at 13px: 14px over / 4px under
+     the baseline), so the flex-centered line box leaves the visible text ~1.5px
+     low — reading as baseline-aligned with the activity dot's bottom instead of
+     its center. Trimming the box makes flexbox center the glyph band instead of
+     the font's metrics box.
+
+     `ex`, not `cap`, is the over edge, because a tab title is sentence case and
+     lowercase-dominant ("workspace", "refactor the auth module"). Centering the
+     x-height/baseline band centers the total ink of such a string, since a
+     Latin font's ascender overshoot above x-height is about its descender depth
+     below the baseline (measured on this stack at 13px: 3.0px over vs 3.0px
+     under, ink center 0.02px off the chip's center). `cap alphabetic` — the
+     right choice for an ALL-CAPS label — leaves lowercase text 1.14px low,
+     which is the original complaint barely moved.
+
+     padding-block is LOAD-BEARING, not spacing: trimming puts the box's under
+     edge ON the baseline, and `overflow: hidden` clips at the padding edge, so
+     with no padding every descender and every tall diacritic is cut off (
+     measured: 3.3px of p/y/g/j tail and 2.3px of an acute accent, i.e. "pygmy
+     jaguar Ápple" rendered as "pyqmy iaquar Apple"). 0.5em restores the ink
+     overhang the trim removes from the box; being symmetric it does not move
+     the centered band, and being em-relative it tracks the font size. The
+     grown box (~20px) still sits inside the close button's 1.5rem, so the tab
+     height is unchanged. A browser without text-box support keeps the untrimmed
+     box, where the padding is harmless slack.
+
+     Shared by all three chip labels (this one + the two switcher labels in
      31-switcher.css). */
-  text-box: trim-both cap alphabetic;
+  text-box: trim-both ex alphabetic;
+  padding-block: 0.5em;
 }
 
 /* A little breathing room after the activity dot, before the label. */
@@ -294,6 +320,20 @@
   margin-left: auto;
 }
 
+/* Hover wash, matching every other bar control (.wt-tab-new, the switcher's
+   buttons) — without it this was the one control in the chrome that gave no
+   pointer feedback at all. Gated to real hover pointers because the button only
+   SHOWS on a coarse pointer (the iPad strip): a plain touchscreen has no
+   pointer-leave, so :hover would stick after a tap and the wash would linger;
+   the feedback there is :active, from .wt-btn. Before .wt-active / .wt-armed so
+   those toggled fills win on a hovered button (equal specificity, source order
+   decides). */
+@media (hover: hover) {
+  :where(.wt-root) .wt-tab-kb:hover {
+    background: var(--tab-hover-bg);
+  }
+}
+
 /* Grid open: filled so the toggled state reads at a glance (mirrors the
    switcher keyboard button). */
 :where(.wt-root) .wt-tab-kb.wt-active {
@@ -322,6 +362,66 @@
   opacity: 0.5;
 }
 
+/* ===== Inline rename (tabs feature) =====
+   The edit surface is the LABEL's own box, so the width the user types into is
+   the width the label will have. The field takes the label's flex slot exactly;
+   the label is [hidden] and the close button is hidden for the duration (a 44px
+   destructive target next to a live text field is a mis-click waiting to happen,
+   and the freed width goes to the field). */
+:where(.wt-root) .wt-tab-rename {
+  flex: 1 1 auto;
+  min-width: 0;
+  background: transparent;
+  border: none;
+  padding: 0;
+  color: var(--tab-active-fg);
+  font: inherit;
+  /* .wt-tab sets user-select: none, and WebKit CASCADES that into descendants
+     even though the property is non-inherited per spec (the same deviation the
+     touch model documents for .term-output). Without this, caret placement and
+     text selection break inside the field in Safari — i.e. on the iPad. */
+  user-select: text;
+  /* The chip is cursor: pointer; a text field must not inherit that. */
+  cursor: text;
+}
+
+/* The family focus ring is scoped to button:focus-visible in 10-primitives.css,
+   so the field needs its own. It is focused programmatically the instant it
+   appears, so :focus (not :focus-visible) is correct here — the ring IS the
+   affordance that says "type here". */
+:where(.wt-root) .wt-tab-rename:focus {
+  outline: 2px solid var(--accent);
+  outline-offset: 1px;
+}
+
+/* While editing, hide the close button: a 44px destructive target adjacent to a
+   live text field is a mis-click waiting to happen, and the freed width goes to
+   the field.
+
+   The chip is NOT widened. An earlier draft gave the edited chip its full 300px
+   so a crowded strip (tabs shrink toward a 100px floor) would not offer a 100px
+   edit box — but nothing in this design system transitions `width` on a tab, so
+   that was an instant ~200px shove of every neighbouring tab plus a scroll jump,
+   at the exact moment the user is trying to read what they are typing. A cramped
+   field on a crowded strip is the lesser problem. */
+:where(.wt-root) .wt-tab-editing .wt-tab-close {
+  display: none;
+}
+
+/* The drag preview clone (setDragGhost): a full-opacity copy of the chip parked
+   under .wt-root — OUTSIDE the bar's backdrop-filter, which is what stops WebKit
+   from rendering the automatic drag image (webkit.org/b/22787) — and laid exactly
+   over the real chip via inline left/top/width/height. It exists for less than a
+   frame (the browser snapshots it, then a rAF removes it), so it must not be
+   hidden (an invisible element makes no snapshot) and must not intercept the
+   pointer. z-index clears the bar so the copy, not the dimmed original, is what
+   would show if it ever painted. */
+:where(.wt-root) .wt-tab-ghost {
+  position: absolute;
+  z-index: 16;
+  pointer-events: none;
+}
+
 /* Tab context menu (tabs feature, desktop right-click): Close / Close others /
    Close to the right / Close to the left / Close all. Replaces the old bar
    "Close all" button. Mirrors .wt-ctx-menu (a fixed surface popover, clamped
@@ -375,6 +475,16 @@
   cursor: default;
 }
 
+/* Group separator: the naming pair (Rename / Use automatic name) sits above the
+   move and close groups, so a hairline keeps the non-destructive actions visually
+   apart from the destructive ones. The menu is otherwise a flat flex column of
+   buttons with no separator vocabulary. */
+:where(.wt-root) .wt-tab-menu-sep {
+  height: 1px;
+  margin: var(--sp-1) 0;
+  background: var(--border);
+}
+
 /* Pull the terminal surface up off the docked BOTTOM tab strip so it does not
    overlap the last rows (a mirror of the old top offset). The tabs feature
    marks the surface (.wt-with-tabbar) and keeps the measured strip height in

package/css/31-switcher.css

@@ -178,8 +178,11 @@
   text-overflow: ellipsis;
   white-space: nowrap;
   text-align: left;
-  /* Ink-centering trim, same as .wt-tab-label (see 30-tabs.css). */
-  text-box: trim-both cap alphabetic;
+  /* Ink-centering trim + its mandatory descender allowance, same as
+     .wt-tab-label (see 30-tabs.css for why `ex` and why the padding is not
+     optional). */
+  text-box: trim-both ex alphabetic;
+  padding-block: 0.5em;
 }
 
 /* Keyboard button: hidden until a keyboardToggle is wired; filled while the key
@@ -208,6 +211,15 @@
   overflow: hidden;
 }
 
+/* Hover wash like the switch and "+" buttons beside it; gated to real hover
+   pointers for the same reason they are (a sticky :hover after a tap). Before
+   .wt-active / .wt-armed so those fills win on a hovered button. */
+@media (hover: hover) {
+  :where(.wt-root) .wt-switcher-kb:hover {
+    background: var(--tab-hover-bg);
+  }
+}
+
 :where(.wt-root) .wt-switcher-kb[hidden] {
   display: none;
 }
@@ -420,8 +432,11 @@
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
-  /* Ink-centering trim, same as .wt-tab-label (see 30-tabs.css). */
-  text-box: trim-both cap alphabetic;
+  /* Ink-centering trim + its mandatory descender allowance, same as
+     .wt-tab-label (see 30-tabs.css for why `ex` and why the padding is not
+     optional). */
+  text-box: trim-both ex alphabetic;
+  padding-block: 0.5em;
 }
 
 /* The close sits flush at the row's right edge (no gap), vertically centered. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "4.6.0",
+  "version": "4.7.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",
@@ -38,7 +38,10 @@
     "verify": "bash scripts/verify.sh"
   },
   "peerDependencies": {
-    "@cplieger/web-terminal-engine": "^3.0.0"
+    "@cplieger/web-terminal-engine": "^3.2.0"
+  },
+  "overrides": {
+    "qs": "^6.15.2"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -50,9 +53,9 @@
     "@vitest/coverage-v8": "4.1.10",
     "eslint": "10.7.0",
     "fast-check": "4.9.0",
-    "happy-dom": "20.11.0",
+    "happy-dom": "20.11.1",
     "html-validate": "11.5.6",
-    "knip": "6.27.0",
+    "knip": "6.29.0",
     "prettier": "3.9.6",
     "stylelint": "17.14.1",
     "stylelint-config-standard": "40.0.0",

package/src/features/context-menu.ts

@@ -38,19 +38,16 @@
 
 import type { TerminalFeature } from "../kernel/types.js";
 import type { ClipboardApi } from "./clipboard.js";
-import { placeMenuAt } from "./menu-position.js";
+import { createClickSwallow, placeMenuAt } from "./menu-position.js";
 
 // Slightly longer than the browser's ~500ms native long-press so a native word
 // selection (which we defer to) has registered — and fired selectionchange —
 // before this fires.
 const LONG_PRESS_MS = 550;
 const LONG_PRESS_MOVE_PX = 10;
-// Viewport clamping + the flip-above-the-fingertip gap live in the shared
-// point-anchored positioner (menu-position.ts), shared with the tab menu.
-// After a touch long-press opens the menu, swallow the trailing click/tap that
-// the same gesture emits on finger-release for this window, so the menu does not
-// immediately dismiss itself (the classic contextmenu-then-touchend race).
-const SWALLOW_MS = 350;
+// Viewport clamping, the flip-above-the-fingertip gap, and the trailing-click
+// swallow all live in the shared point-anchored menu module (menu-position.ts),
+// shared with the tab menu.
 
 export interface ContextMenuOptions {
   /** The clipboard feature value, so the menu can offer Copy/Paste through its
@@ -98,8 +95,8 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
       // 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;
+      // Swallows the trailing click a touch long-press emits on release.
+      const swallow = createClickSwallow();
       // A native selection was made during the current touch press (tracked via
       // selectionchange). Gates the touch menu: a selected long-press belongs to
       // the native callout, an empty one to us (Paste).
@@ -212,9 +209,9 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
         menu.classList.add("visible");
         placeMenuAt(menu, x, y);
         // A touch long-press is immediately followed by a synthetic click on
-        // release; swallow it so the menu stays open (see SWALLOW_MS).
+        // release; swallow it so the menu stays open.
         if (touch) {
-          swallowUntil = performance.now() + SWALLOW_MS;
+          swallow.arm();
         }
       }
 
@@ -295,7 +292,7 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
 
       const onDocClick = (): void => {
         // Swallow the release click of the long-press that just opened the menu.
-        if (performance.now() < swallowUntil) {
+        if (swallow.swallowing()) {
           return;
         }
         hide();

package/src/features/menu-position.ts

@@ -13,6 +13,35 @@ const EDGE_MARGIN = 8;
  *  hidden under the fingertip that long-pressed near the bottom edge. */
 const FLIP_GAP = 16;
 
+/** After a touch long-press opens a menu, the SAME gesture emits a click on
+ *  finger-release, and an outside-click dismiss reads that click as "the user
+ *  clicked away" — the classic contextmenu-then-touchend race. Swallow document
+ *  clicks for this window after a touch-opened menu. 350ms comfortably covers
+ *  the release without eating a deliberate follow-up tap. */
+const SWALLOW_MS = 350;
+
+/** createClickSwallow returns the two halves a point-anchored menu needs to
+ *  survive the contextmenu-then-touchend race: `arm()` right after a TOUCH-opened
+ *  menu becomes visible, and `swallowing()` as the first guard in the
+ *  outside-click dismiss.
+ *
+ *  It lives here, beside the shared placement math, because both point-anchored
+ *  menus need it and a hand-synced second copy is what this module was extracted
+ *  to stop. The tab menu shipped without the guard entirely, so on iPadOS Safari
+ *  — which fires `contextmenu` on a long-press, and where the desktop tab strip
+ *  is the chrome that shows — a long-pressed tab menu dismissed itself on
+ *  release. Arm it only for touch: a mouse right-click emits no trailing click,
+ *  and swallowing there would eat a genuine dismiss. */
+export function createClickSwallow(): { arm: () => void; swallowing: () => boolean } {
+  let until = 0;
+  return {
+    arm: (): void => {
+      until = performance.now() + SWALLOW_MS;
+    },
+    swallowing: (): boolean => performance.now() < until,
+  };
+}
+
 /** Place an already-visible `menu` at viewport point (x, y): open just below
  *  the point, flip above it when that would overflow the visible bottom, and
  *  clamp into the visual viewport on both axes. The menu is absolute-positioned