@cplieger/web-terminal-ui 4.7.0 → 4.8.0

package/css/00-tokens.css

@@ -45,10 +45,24 @@
   ); /* subtle edge: the fill lightened + slightly desaturated, matching the inactive chip's faint border rather than a vivid accent outline */
 
   /* Status-dot palette (the activity vocabulary painted in 30-tabs.css; the
-     switcher notification dot reuses the same rules). The working and input
-     rings each derive from their own token in 30-tabs.css, so one override
-     recolors dot + ring together. */
-  --status-working: #d9f99d; /* agent working (pulses): pale lime */
+     switcher notification dot reuses the same rules). The working wave and the
+     input ring each derive from their own token in 30-tabs.css, so one override
+     recolors dot + surround together.
+
+     The trio is the conventional progress scheme — blue in flight, green
+     finished, orange waiting on you — which is why working is a LITERAL copy of
+     the default --accent blue rather than var(--accent): a consumer that
+     rethemes its brand accent to (say) a red should not have its "working" dot
+     follow, and a status vocabulary that shifts hue per consumer stops being a
+     vocabulary. The value being equal to the default accent is a deliberate
+     coincidence of taste, not a dependency.
+
+     Working shares the accent's hue family, so on the ACTIVE tab it sits on an
+     accent-derived fill (--tab-active-bg): measured 5.2:1 against it, and 8.0:1
+     against the bar, both clear of the 3:1 non-text minimum. Hue still never
+     carries state on its own (the wave's motion, and the donut it becomes under
+     prefers-reduced-motion, are the non-hue cues per WCAG 1.4.1). */
+  --status-working: #52a9fe; /* agent working (waves): the same blue as the default --accent */
   --status-done: #22c55e; /* turn finished: solid green */
   --status-input: #fb923c; /* action required: solid orange + ring */
   --radius: 0.75rem;

package/css/30-tabs.css

@@ -137,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. */
@@ -535,17 +555,18 @@
 /* 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
+   colors brighten mid-beat), while a ::after WAVE travels 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
-   COLORS, not element opacity. Server-side this is driven by the OSC 9;4
-   progress signal, so it tracks agent activity, not the user typing at the
-   prompt. */
+   the disc + live wave ARE the working read. The wave's soft feathered edge is
+   the second axis that separates working from input: input is a HARD-edged 2px
+   ring, held still (see input below), so the pair differs by both motion and
+   edge quality, and the presence of any surround 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 COLORS, not element opacity. Server-side this is driven by the
+   OSC 9;4 progress signal, so it tracks agent activity, not the user typing at
+   the prompt. */
 :where(.wt-root) .wt-status-dot[data-status="working"] {
   position: relative;
   background: var(--status-working);
@@ -553,40 +574,58 @@
   animation: wt-working-glow 1.2s ease-in-out infinite;
 }
 
-/* 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.) */
+/* The ripple layer: a feathered radial BAND (not a hairline border) that starts
+   hugging the disc's edge (inset -2px, the 9->13px box) and then travels
+   outward, dissolving. The band is painted as a radial-gradient — soft on both
+   edges, so it reads as a wave of light leaving the disc rather than a ring
+   outline shrinking in opacity; scaling the layer scales the feather with it,
+   which is what makes the wave visibly dissipate as it grows. transform +
+   opacity only, so it composites without repaints (a gradient background is
+   rasterized once, unlike an animated box-shadow spread, which repaints every
+   frame). 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.)
+
+   The final scale is deliberately capped at today's 27px footprint: the mobile
+   overview row (.wt-switcher-row-select) clips at overflow: hidden 12.5px from
+   the dot's center, and a wave wider than ~25px picks up a visible straight
+   edge there. Visibility comes from the band's weight and timing, not size. */
 :where(.wt-root) .wt-status-dot[data-status="working"]::after {
   content: "";
   position: absolute;
   inset: -2px;
-  border: 2px solid var(--status-working);
   border-radius: 50%;
-  animation: wt-working-ripple 1.2s ease-in-out infinite;
+  background: radial-gradient(
+    closest-side,
+    transparent 44%,
+    var(--status-working) 76%,
+    transparent 100%
+  );
+  animation: wt-working-ripple 1.2s linear infinite;
 }
 
 /* Agent done / ready: solid disc (--status-done), no motion. The default green
-   matches Kiro IDE's "Ready" (#22c55e), darker and more saturated than
-   working's default pale lime so the two states differ by lightness as well as
-   motion. */
+   matches Kiro IDE's "Ready" (#22c55e). It sits at almost exactly working's
+   default lightness now that working is the accent blue (both ~72% OKLab L), so
+   the pair separates by hue plus the wave's motion rather than by lightness —
+   and under prefers-reduced-motion by shape, since working becomes a donut. */
 :where(.wt-root) .wt-status-dot[data-status="done"] {
   background: var(--status-done);
   border-color: var(--status-done);
 }
 
-/* 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. */
+/* User action required (permission / approval): a solid dot inside a static,
+   HARD-edged 2px ring, motionless (--status-input; the default orange is
+   shifted away from the old amber so it separates from both blue working and
+   green done). The stillness plus the hard edge is the message: the
+   agent's turn is mid-flight but blocked on you, and the surround is a fixed
+   outline rather than working's soft travelling wave. (Before the wave landed,
+   working's ripple was a 2px ring too and this state was literally that ping
+   frozen at its birth frame; the two now differ by edge quality as well as
+   motion, which reads more distinctly at 9px.) The ring derives from the same
+   token as the dot, so a theme override recolors both 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);
@@ -621,13 +660,33 @@
 }
 
 /* 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. */
+   dissolving by ~2.1x. Two things are load-bearing and were both wrong in the
+   first version (the wave was there but nobody could see it):
+
+   - The travel is LINEAR while the opacity is shaped separately. An ease-in-out
+     shared by both properties spends the slow opening on top of the disc, where
+     the wave is indistinguishable from it, and then accelerates away exactly as
+     the opacity collapses — so the wave was only ever visible while it was
+     still merged with the disc. Constant-speed travel plus its own opacity
+     envelope keeps the wave legible across most of the cycle.
+   - The wave is BRIGHT at birth (0.95 after a 12% ramp-in, not 0.3) and holds
+     usable weight through the travel. The ramp-in is short enough to read as
+     instant while stopping the emission from popping in.
+
+   The disc's own glow shares this 1.2s period so the two cues stay phase-locked;
+   change both or neither. */
 @keyframes wt-working-ripple {
   0% {
     transform: scale(1);
-    opacity: 0.3;
+    opacity: 0.15;
+  }
+
+  12% {
+    opacity: 0.95;
+  }
+
+  70% {
+    opacity: 0.45;
   }
 
   100% {

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
@@ -429,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.7.0",
+  "version": "4.8.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",

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

package/src/features/tabs/index.ts

@@ -13,7 +13,7 @@ import type { SessionRef, TerminalContext, TerminalFeature } from "../../kernel/
 import type { ActivityMonitorApi } from "../activity-monitor.js";
 import type { MobileToolbarApi } from "../mobile-toolbar.js";
 import { fromHTML } from "../dom.js";
-import { placeMenuAt } from "../menu-position.js";
+import { createClickSwallow, placeMenuAt } from "../menu-position.js";
 import type { SessionInfo, Tab } from "./model.js";
 import {
   ACTIVE_TAB_KEY,
@@ -2029,6 +2029,27 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // the items for the target tab (disabled states reflect its position) and
       // clamps into the visible viewport, flipping above the pointer near the
       // bottom edge (mirrors context-menu.ts).
+      //
+      // menuSwallow covers the contextmenu-then-touchend race: iPadOS Safari
+      // raises a context menu from a LONG-PRESS, and the same gesture emits a
+      // click on release which onDocClickMenu would read as a click-away. The
+      // terminal menu has guarded this since it shipped; this one did not, so a
+      // long-pressed tab menu closed itself on release — on the one platform
+      // where the desktop strip is the chrome you touch. menuTouch records
+      // whether the press that raised the menu was a finger, since only touch
+      // emits that trailing click.
+      const menuSwallow = createClickSwallow();
+      let menuTouch = false;
+      // One listener on the bar rather than one per chip: chips are created and
+      // destroyed as sessions come and go, and the pointer type belongs to the
+      // gesture, not to a chip.
+      bar.addEventListener(
+        "pointerdown",
+        (e) => {
+          menuTouch = e.pointerType === "touch";
+        },
+        { passive: true },
+      );
       function hideTabMenu(): void {
         tabMenu.classList.remove("visible");
         tabMenu.replaceChildren();
@@ -2102,6 +2123,9 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // the visual viewport; flip above the pointer near the bottom edge).
         tabMenu.classList.add("visible");
         placeMenuAt(tabMenu, x, y);
+        if (menuTouch) {
+          menuSwallow.arm();
+        }
       }
 
       // One-time "swipe to switch" hint on first multi-tab state, mobile only.
@@ -2336,6 +2360,11 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       // Dismiss the tab context menu on an outside click, on Escape, and on
       // scroll (it is anchored to a viewport point, so a scroll would detach it).
       const onDocClickMenu = (): void => {
+        // The trailing click of the long-press that just opened the menu is that
+        // gesture's own release, not a click-away.
+        if (menuSwallow.swallowing()) {
+          return;
+        }
         hideTabMenu();
       };
       document.addEventListener("click", onDocClickMenu);