@cplieger/web-terminal-ui 4.5.2 → 4.7.0

package/README.md

@@ -8,15 +8,14 @@
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/cplieger/web-terminal-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/cplieger/web-terminal-ui)
 
 The reference touch-first browser UI for
-[`@cplieger/web-terminal-engine`](https://github.com/cplieger/web-terminal-engine) — the part
-that turns the engine's render/scroll/connection/keyboard modules into a
-usable terminal on a phone as well as a desktop.
+[`@cplieger/web-terminal-engine`](https://github.com/cplieger/web-terminal-engine).
+It turns the engine's render/scroll/connection/keyboard modules into a usable
+terminal on a phone as well as a desktop.
 
 One `createTerminal(root, { features })` call builds the entire terminal UI
 inside a single container element you provide. A small always-present kernel
-(the display output, the hidden keyboard textarea, IME, engine wiring, the
-sanitizing input funnel, connection-state, and named layout regions) composes
-with opt-in feature modules that own everything above the raw terminal:
+composes with opt-in feature modules that own everything above the raw
+terminal:
 
 - a **display-only** terminal output (native text selection survives redraws)
   and a hidden `<textarea>` that owns the keyboard and IME (the kernel)
@@ -44,7 +43,7 @@ depend on the engine directly and skip this package.
 npm install @cplieger/web-terminal-ui @cplieger/web-terminal-engine
 ```
 
-`@cplieger/web-terminal-engine` is a peer dependency — the UI is built on the
+`@cplieger/web-terminal-engine` is a peer dependency: the UI is built on the
 engine, so the consumer pins the engine version explicitly. Pairing compatibility
 is governed by the engine's
 [directional wire contract](https://github.com/cplieger/web-terminal-engine#wire-protocol),
@@ -57,14 +56,14 @@ Serve a CSS bundle matching how you embed the terminal, plus a minimal HTML
 page that has one empty container element, then call
 `createTerminal(root, { features })` from your entry module.
 
-**Full-page host** (the terminal IS the page — `web-terminal-server`,
+**Full-page host** (the terminal IS the page, as in `web-terminal-server` and
 `web-terminal-kiro`): concatenate `css/MANIFEST` into the `style.css` your page
 links. That reference bundle is `css/page.css` (the page kit: `html/body`
 reset + the terminal web font's `@font-face`, expecting the font files at
 `/vendor/fonts/`) plus the complete component set.
 
-**Embedder** (the terminal lives inside your app's layout — a panel, a pane):
-concatenate the per-preset manifest matching your composition instead —
+**Embedder** (the terminal lives inside your app's layout, as a panel or pane):
+concatenate the per-preset manifest matching your composition instead:
 `css/MANIFEST.single`, `css/MANIFEST.touch`, or `css/MANIFEST.tabbed`. These
 contain ONLY root-scoped component styles: no page reset, no fonts, no
 document-level rules, nothing to quarantine. Pass `layout: "container"` so the
@@ -99,7 +98,7 @@ entry modules beside it:
 ```
 
 `createTerminal(root, opts?)` builds the entire terminal subtree (the kernel
-plus every feature's chrome) inside `root` itself — there is no element-id
+plus every feature's chrome) inside `root` itself. There is no element-id
 contract for the host page to reproduce, and every style and CSS custom
 property is scoped to the `wt-root` class it stamps on your element (removed
 again by `destroy()`). Call it exactly once; the engine's
@@ -109,46 +108,43 @@ to copy and adapt.
 
 Four presets are provided; each is a plain feature-array factory, so you can
 spread and edit it. Import the barrel (`@cplieger/web-terminal-ui/presets`) for
-convenience, or a per-preset entry module for the minimal delivered import
-graph — `…/presets/single`, `…/presets/touch`, `…/presets/tabbed`,
-`…/presets/agent-tabbed` (the barrel statically reaches every feature; the
-touch entry, for example, never imports the tabs module). Individual features
+convenience, or a per-preset entry module (`…/presets/single`, `…/presets/touch`,
+`…/presets/tabbed`, `…/presets/agent-tabbed`) for the minimal delivered import
+graph; the barrel statically reaches every feature, while the touch entry, for
+example, never imports the tabs module. Individual features
 are importable from `…/features/<name>` (`clipboard`, `context-menu`,
 `scroll-to-bottom`, `predictive-echo`, `connection-banner`, `mobile-toolbar`,
 `tabs`, `activity-monitor`, `animations`) for hand-picked compositions:
 
-- `presetSingle()` — single-pane desktop UI (context menu, clipboard,
+- `presetSingle()`: single-pane desktop UI (context menu, clipboard,
   scroll-to-bottom, predictive echo, connection banner).
-- `presetTouch()` — `presetSingle()` plus the mobile key toolbar.
-- `presetTabbed()` — the generic tabbed UI: `presetTouch()` plus tabs, the
-  activity monitor, and animations. Each tab's title is OSC-first — it follows
+- `presetTouch()`: `presetSingle()` plus the mobile key toolbar.
+- `presetTabbed()`: the generic tabbed UI, `presetTouch()` plus tabs, the
+  activity monitor, and animations. Each tab's title is OSC-first: it follows
   the process window title (OSC 0/2) when the program sets one and keeps it
   updated, otherwise the last command submitted. The per-tab activity dot
   reveals itself only when a session reports OSC 9;4 progress, so a plain shell
   keeps clean, label-only tabs. Requires a server that speaks the session API
   (`/api/sessions` and `/ws?session=`), such as `web-terminal-server`.
-- `presetAgentTabbed()` — the same feature set as `presetTabbed()` (activity
-  monitor included), tuned for an agent shell such as `web-terminal-kiro`: with
-  `preferInputTitle`, each tab's label follows the latest submitted line
-  (persisted server-side and recovered on reload) and the program's non-empty
-  but useless OSC 0/2 title is ignored; and with `presumeReports`, the idle
-  activity dot shows from tab creation instead of waiting for the session's
-  first OSC 9;4 signal — every session is an agent, so there is nothing to
-  prove. Its status dots (idle / working / done / needs-input) come from the
-  same activity monitor, driven by the server's status SSE and its OSC-9
-  classifier.
+- `presetAgentTabbed()`: the same feature set as `presetTabbed()`, tuned for an
+  agent shell such as `web-terminal-kiro`. With `preferInputTitle`, each tab's
+  label follows the latest submitted line (persisted server-side and recovered
+  on reload) and the program's OSC 0/2 title is ignored. With `presumeReports`,
+  the idle activity dot shows from tab creation instead of waiting for the
+  session's first OSC 9;4 signal. Its status dots (idle / working / done /
+  needs-input) come from the same activity monitor.
 
 ### Options
 
-| Option         | Default                    | Purpose                                                                                                                                                                                                                                                                                                                                                            |
-| -------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `features`     | _(none — bare kernel)_     | The feature list. Omitted or empty builds only the terminal (no chrome). Use a preset from `./presets` or a hand-picked array.                                                                                                                                                                                                                                     |
-| `layout`       | `"viewport"`               | How the terminal claims space. `"viewport"`: the root becomes a fixed full-viewport box (the full-page product). `"container"`: the root fills your container element, which becomes the styling and positioning boundary (the embedded case).                                                                                                                     |
-| `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 after a fatal feature setup failure has stopped the connection, released the terminal runtime, and cleared the root. It receives `{ phase, feature, cause }`. Return `true` only after rendering replacement recovery UI into the root; otherwise the kernel shows its Reload page surface.                                                                 |
-| `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 working ripple and the input ring derive from their own tokens). The library ships neutral defaults. |
+| Option         | Default                    | Purpose                                                                                                                                                                                                                                                                                       |
+| -------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `features`     | _(none; bare kernel)_      | The feature list. Omitted or empty builds only the terminal (no chrome). Use a preset from `./presets` or a hand-picked array.                                                                                                                                                                |
+| `layout`       | `"viewport"`               | How the terminal claims space. `"viewport"`: the root becomes a fixed full-viewport box (the full-page product). `"container"`: the root fills your container element, which becomes the styling and positioning boundary (the embedded case).                                                |
+| `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 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
 (and opens the soft keyboard on touch); `send(bytes)` sends bytes to the active
@@ -158,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
@@ -178,10 +182,10 @@ replacement recovery UI into the terminal root.
 
 The web-terminal family:
 
-- [`web-terminal-engine`](https://github.com/cplieger/web-terminal-engine) — the
+- [`web-terminal-engine`](https://github.com/cplieger/web-terminal-engine): the
   Go session engine + TypeScript browser renderer this UI is built on (peer
   dependency).
-- [`web-terminal-server`](https://github.com/cplieger/web-terminal-server) — a
+- [`web-terminal-server`](https://github.com/cplieger/web-terminal-server): a
   ready-to-run container that serves this UI over HTTP + WebSocket for any
   command.
 

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
@@ -104,6 +110,16 @@
   color: var(--tab-active-fg);
 }
 
+/* Press (mousedown / touch-hold): one rung past the hover lift — same recipe,
+   deeper mix — so hover -> press reads as a single dimension. After the hover
+   rule so it wins while both apply. Scoped like hover: clicking the active tab
+   selects nothing (it is already active), so it presses like the static surface
+   it is. */
+:where(.wt-root) .wt-tab:not(.wt-tab-active):active {
+  background: color-mix(in oklch, var(--tab-bg), var(--text) 25%);
+  color: var(--tab-active-fg);
+}
+
 /* The active tab reads clearly above the inactive chips: a stronger fill plus an
    accent-coloured edge (inactive chips carry a faint white --border; the active
    one gets the accent equivalent). Themeable via --accent (web-terminal-kiro -> purple). */
@@ -166,6 +182,13 @@
   color: var(--text);
 }
 
+/* Press: deepen the hover box (--text-active is a 15% --text wash; press doubles
+   it to 30%) so mousedown visibly registers before the tab disappears. */
+:where(.wt-root) .wt-tab-close:active {
+  background: color-mix(in oklch, var(--text) 30%, transparent);
+  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 {
@@ -221,6 +244,13 @@
   background: var(--tab-active-bg);
 }
 
+/* Press: brighten the hover fill with the active-tab fg (the
+   .wt-switcher-current press recipe — a lighter press over an already-filled
+   control), keeping the accent glyph. */
+:where(.wt-root) .wt-tab-new:active {
+  background: color-mix(in oklch, var(--tab-active-bg), var(--tab-active-fg) 12%);
+}
+
 /* The +/x icons are inline SVG so they center exactly in their flex-centered
    button and stay symmetric regardless of the UI font (fixes the off-center
    glyph and the lopsided "+"). The + is a touch larger and bolder than the x. */
@@ -270,6 +300,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 {
@@ -298,6 +342,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
@@ -340,11 +444,27 @@
   background: var(--text-active);
 }
 
+/* Press: deepen the hover wash to 30% --text (the .wt-tab-close press rung) so
+   the click registers before the menu closes. */
+:where(.wt-root) .wt-tab-menu button:enabled:active {
+  background: color-mix(in oklch, var(--text) 30%, transparent);
+}
+
 :where(.wt-root) .wt-tab-menu button:disabled {
   color: color-mix(in oklch, var(--text) 35%, transparent);
   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

@@ -208,6 +208,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;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "4.5.2",
+  "version": "4.7.0",
   "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",