@cplieger/web-terminal-ui 4.5.1 → 4.6.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 and input rings 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 `{ phase, feature, cause }` after a fatal feature setup failure; 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
@@ -178,10 +174,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.
 
@@ -190,6 +186,11 @@ Consumers that ship this UI:
 - [`vibekit`](https://github.com/cplieger/vibekit)
 - [`web-terminal-kiro`](https://github.com/cplieger/web-terminal-kiro)
 
+## Contributing
+
+Issues and PRs are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the
+conventions and how to run the checks locally.
+
 ## Disclaimer
 
 This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.
@@ -198,4 +199,4 @@ This project was built with AI-assisted tooling using [Claude](https://claude.co
 
 ## License
 
-GPL-3.0-or-later. See `LICENSE`.
+GPL-3.0-or-later. See [LICENSE](LICENSE).

package/css/30-tabs.css

@@ -104,6 +104,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). */
@@ -121,6 +131,17 @@
   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
+     31-switcher.css). */
+  text-box: trim-both cap alphabetic;
 }
 
 /* A little breathing room after the activity dot, before the label. */
@@ -155,6 +176,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 {
@@ -210,6 +238,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. */
@@ -329,6 +364,12 @@
   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;
@@ -401,15 +442,14 @@
   border: 1.5px solid color-mix(in oklch, var(--text) 45%, transparent);
 }
 
-/* Agent working: two INDEPENDENTLY animated layers on one element make the
-   "alive" read (the status-badge "processing" idiom — Ant Design's processing
-   badge, the classic CSS live-indicator ripple): the solid disc keeps full
-   opacity and gently GLOWS (its colors brighten mid-beat), while a ::after
-   ring — born exactly on the static 2px ring — RIPPLES outward and dissolves,
-   re-emitted each cycle. The static ring itself never moves, so working keeps
-   input's exact rest silhouette (a live turn ripples; a turn blocked on the
-   user is that same silhouette frozen — see input below). Motion separates
-   working from input; the ring separates both from done's bare disc. The old
+/* Agent working: a solid disc with two animated cues (the status-badge
+   "processing" idiom — Ant Design's processing badge, the classic CSS
+   live-indicator ripple): the disc keeps full opacity and gently GLOWS (its
+   colors brighten mid-beat), while a ::after ring RIPPLES outward off the
+   disc's edge and dissolves, re-emitted each cycle. No static ring at rest —
+   the disc + live ripple ARE the working read; input freezes that exact ping
+   at its birth frame (see input below), so motion separates working from
+   input, and the ring separates both from done's bare disc. The old
    single-layer pulse faded disc + ring together (opacity on the element),
    which read as a blink and coupled the layers — an element's opacity always
    multiplies onto its pseudos, so true independence requires animating disc
@@ -420,16 +460,15 @@
   position: relative;
   background: var(--status-working);
   border-color: var(--status-working);
-  box-shadow: 0 0 0 2px color-mix(in srgb, var(--status-working) 40%, transparent);
   animation: wt-working-glow 1.2s ease-in-out infinite;
 }
 
-/* The ripple layer: at scale(1) its 2px border overlays the static ring's
-   9->13px band exactly (inset -2px), then the wave detaches, expanding and
-   fading. transform + opacity only, so it composites without repaints. It
-   exists only in the working state — no stale layer to pin when a dot changes
-   status. (The switcher notification dot never shows working — input/done
-   only — so its position: absolute placement never meets this rule's
+/* The ripple layer: at scale(1) its 2px border hugs the disc's edge (inset
+   -2px, the 9->13px band), then the wave detaches, expanding and fading.
+   transform + opacity only, so it composites without repaints. It exists only
+   in the working state — no stale layer to pin when a dot changes status.
+   (The switcher notification dot never shows working — input/done only — so
+   its position: absolute placement never meets this rule's
    position: relative.) */
 :where(.wt-root) .wt-status-dot[data-status="working"]::after {
   content: "";
@@ -449,18 +488,19 @@
   border-color: var(--status-done);
 }
 
-/* User action required (permission / approval): working's exact silhouette —
-   solid dot + 2px ring — frozen and recolored (--status-input; the default
-   orange is shifted away from the old amber so it separates from both
-   default-lime working and green done). The stillness is the message: the
-   agent's turn is mid-flight but blocked on you. The ring keeps it distinct
-   from done's bare disc without leaning on hue; it derives from the same token
-   at 40% alpha, so a theme override recolors dot + ring together. It persists
-   until you act on or switch into the tab. */
+/* User action required (permission / approval): the working ping frozen at
+   its birth frame — solid dot + the same 2px ring at the ripple's 30% birth
+   opacity, motionless (--status-input; the default orange is shifted away
+   from the old amber so it separates from both default-lime working and green
+   done). The stillness is the message: the agent's turn is mid-flight but
+   blocked on you. The ring keeps it distinct from done's bare disc without
+   leaning on hue; it derives from the same token, so a theme override
+   recolors dot + ring together. It persists until you act on or switch into
+   the tab. */
 :where(.wt-root) .wt-status-dot[data-status="input"] {
   background: var(--status-input);
   border-color: var(--status-input);
-  box-shadow: 0 0 0 2px color-mix(in srgb, var(--status-input) 40%, transparent);
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--status-input) 30%, transparent);
 }
 
 /* Exited: a dim hollow dot, static; distinct from idle by its lower opacity. */
@@ -490,13 +530,14 @@
   }
 }
 
-/* The ripple wave: one emission per cycle, launching off the static ring and
-   dissolving by ~2.1x. Opacity starts at the static ring's own 40% weight so
-   the wave reads as the ring letting go of a copy, not a new brighter object. */
+/* The ripple wave: one emission per cycle, launching off the disc's edge and
+   dissolving by ~2.1x. The 0.3 birth opacity matches the input ring's frozen
+   weight, so a live ping and a stuck one read as the same object — subtle
+   against the bar now that no static ring doubles it at birth. */
 @keyframes wt-working-ripple {
   0% {
     transform: scale(1);
-    opacity: 0.4;
+    opacity: 0.3;
   }
 
   100% {
@@ -509,13 +550,14 @@
 @media (prefers-reduced-motion: reduce) {
   :where(.wt-root) .wt-status-dot[data-status="working"] {
     animation: none;
-    /* Motion is what separates working from input's frozen silhouette; with
-       it removed, punch an inner hole (dot -> donut) so working differs from
-       input (solid ringed disc) and done (bare disc) by shape, not hue alone
-       (WCAG 1.4.1). The outer ring stays. */
+    /* Motion is what separates working from input's frozen ping; with it
+       removed, punch an inner hole (dot -> donut) and add a static ring so
+       working differs from input (solid ringed disc) and done (bare disc) by
+       shape, not hue alone (WCAG 1.4.1). The ring carries the same 30%
+       weight as input's. */
     box-shadow:
       inset 0 0 0 2px var(--bg),
-      0 0 0 2px color-mix(in srgb, var(--status-working) 40%, transparent);
+      0 0 0 2px color-mix(in srgb, var(--status-working) 30%, transparent);
   }
 
   /* The ripple layer disappears entirely (not just paused mid-wave). */

package/css/31-switcher.css

@@ -178,6 +178,8 @@
   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;
 }
 
 /* Keyboard button: hidden until a keyboardToggle is wired; filled while the key
@@ -418,6 +420,8 @@
   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;
 }
 
 /* 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.5.1",
+  "version": "4.6.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",
@@ -53,7 +53,7 @@
     "happy-dom": "20.11.0",
     "html-validate": "11.5.6",
     "knip": "6.27.0",
-    "prettier": "3.9.5",
+    "prettier": "3.9.6",
     "stylelint": "17.14.1",
     "stylelint-config-standard": "40.0.0",
     "typescript": "npm:@typescript/typescript6@6.0.2",