@cplieger/web-terminal-ui 4.7.1 → 4.8.1

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

@@ -555,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);
@@ -573,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);
@@ -641,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "4.7.1",
+  "version": "4.8.1",
   "type": "module",
   "description": "Reference touch-first browser UI for @cplieger/web-terminal-engine: a composable kernel + feature modules (tabs, activity monitor, mobile toolbar, context menu, IME, predictive echo, viewport handling) and CSS. One createTerminal() call.",
   "license": "GPL-3.0-or-later",

package/src/features/tabs/index.ts

@@ -79,7 +79,8 @@ const TAB_DRAG_TYPE = "application/x-web-terminal-tab";
 // terminal context menu (formerly two hand-synced copies of the same math).
 
 export interface TabsApi {
-  /** Spawn a fresh session and switch to it. */
+  /** Spawn a fresh session and switch to it. Calls made while a create is in
+   *  flight share that create, so one gesture opens exactly one terminal. */
   create(): Promise<void>;
   /** Close a session (kills its process) and drop its tab + cache. */
   close(id: string): Promise<void>;
@@ -297,7 +298,8 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         // the FIRST tap to blur the input (so "+" only fired create on the second
         // tap — the reported double-tap). preventDefault on pointerdown fires the
         // action on the first tap; switchTo then re-focuses the input for the new
-        // tab on a physical-keyboard device.
+        // tab (see focusAfterSwitch). It does NOT make one press one activation —
+        // that is create()'s in-flight coalescing, for the opposite failure.
         btn.addEventListener("pointerdown", (e) => {
           e.preventDefault();
         });
@@ -657,8 +659,58 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         }
       }
 
+      const termInput = (): HTMLElement | null =>
+        ctx.surface().querySelector<HTMLElement>(".term-input");
       function focusInput(): void {
-        ctx.surface().querySelector<HTMLElement>(".term-input")?.focus({ preventScroll: true });
+        termInput()?.focus({ preventScroll: true });
+      }
+
+      // Did the terminal input own the keyboard when the pointer press now being
+      // handled began? A press on tab chrome focuses the control it landed on
+      // (the browser's mousedown default action), so by the time the click
+      // handler runs the input is already blurred and only a pointerdown-time
+      // snapshot still knows where the keyboard came from. Recorded for the whole
+      // chrome by the two pointerdown listeners below (the strip and the
+      // switcher), not per control: chips come and go with sessions, and the fact
+      // belongs to the gesture rather than to what it hit.
+      let inputFocusedAtPress = false;
+      function noteChromePress(): void {
+        const el = termInput();
+        inputFocusedAtPress = el !== null && document.activeElement === el;
+      }
+      function keyboardParkedOnChrome(): boolean {
+        const active = document.activeElement;
+        return active !== null && (bar.contains(active) || switcher.contains(active));
+      }
+
+      // focusAfterSwitch applies the tab-switch focus rule. Two independent
+      // reasons to hand the keyboard to the terminal input:
+      //
+      //  - A physical keyboard is (likely) present, so a switch should leave you
+      //    able to type at once, with no extra tap (the iPad + Magic Keyboard
+      //    ask). Skipped on a keyboard-less touchscreen, or every switch would
+      //    pop the virtual keyboard (#7).
+      //  - The press that drove this switch took the keyboard OFF the terminal —
+      //    it focused the chip (or the x, or a switcher row) it pressed, and the
+      //    keyboard is still parked there. Handing it back is not NEW focus, so
+      //    it pops no soft keyboard: it restores what the press displaced. Both
+      //    halves are required for exactly that reason — a switch with no press
+      //    behind it (a remote adopt, ensureActive), or a press on a device where
+      //    the input was not focused to begin with, must not summon a keyboard.
+      //    Leaving the keyboard parked on a chip is not neutral either: the
+      //    strip's own keydown handling reads arrows as "switch tab" and Delete
+      //    as "close tab", so every keystroke meant for the terminal is eaten.
+      //
+      // Never while a rename field is open: it owns the keyboard until it closes,
+      // and a switch (the leading click of a double-click, a remote-driven
+      // ensureActive) would otherwise yank the caret out of the field.
+      function focusAfterSwitch(): void {
+        if (editingId !== null) {
+          return;
+        }
+        if (physicalKeyboardLikely() || (inputFocusedAtPress && keyboardParkedOnChrome())) {
+          focusInput();
+        }
       }
 
       // paintActive updates the desktop strip's active state. When the ACTIVE
@@ -1249,6 +1301,17 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
 
       function switchTo(id: string, dir?: "next" | "prev"): void {
         if (id === activeId) {
+          // Already active, so there is no switch to perform — but the FOCUS rule
+          // still owes an answer, because the press that delivered this click has
+          // already moved the keyboard onto the chip. Two pointer paths land here:
+          // clicking the tab that is already active, and the SECOND activation of
+          // one press on another tab (see create() for the evidence that this
+          // device delivers those). The first activation switches and focuses the
+          // terminal; the second one's mousedown re-focuses the chip and then fell
+          // out here with the keyboard stranded on it — the reported "the
+          // invisible input loses focus when I click another tab", and the same
+          // hole a plain mouse click on the active tab hit on every platform.
+          focusAfterSwitch();
           return;
         }
         const next = tabList.find((t) => t.id === id);
@@ -1339,16 +1402,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           }
         });
         ctx.announce(`Switched to ${next.display}`);
-        if (physicalKeyboardLikely() && editingId === null) {
-          // A physical keyboard is (likely) present, so focus the input on
-          // switch — switch and type immediately (the iPad + Magic Keyboard
-          // ask). On a keyboard-less touchscreen this is skipped, or every
-          // switch would pop the virtual keyboard (#7). Skipped entirely while a
-          // rename field is open: a switch (e.g. the leading click of a
-          // double-click, or a remote-driven ensureActive) would otherwise yank
-          // the caret out of the field the user is typing in.
-          focusInput();
-        }
+        focusAfterSwitch();
       }
 
       // armCatchup shows the "catching up" cue only if the resume delta has not
@@ -1590,7 +1644,28 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         }
       }
 
-      async function create(): Promise<void> {
+      // create is the coalesced door: while one create is in flight, every caller
+      // asking for another gets THAT one, so a single gesture can only ever open
+      // one terminal. Spawning a session is expensive and non-idempotent, and one
+      // press does not reliably arrive as one activation — the web-terminal-kiro
+      // server logged two POST /api/sessions 0-3ms apart (three times in one
+      // afternoon, both answered 201) for single "+" taps from an iPad + Magic
+      // Keyboard, so the user got two terminals and had to close one. Sharing the
+      // in-flight promise needs no threshold to make that decision, unlike a
+      // click-level debounce: a duplicate activation lands while the POST is still
+      // open and collapses into it, while a deliberate second tap (the POST
+      // resolves in milliseconds) still opens a second terminal. It also stops "+"
+      // mashing from queueing sessions across the server's 503 install window,
+      // where createSessionHonouringRetry legitimately waits minutes.
+      let creating: Promise<void> | null = null;
+      function create(): Promise<void> {
+        creating ??= openNewSession().finally(() => {
+          creating = null;
+        });
+        return creating;
+      }
+
+      async function openNewSession(): Promise<void> {
         let info: SessionInfo;
         try {
           info = await createSessionHonouringRetry(api, ctx, () => tornDown);
@@ -2041,15 +2116,20 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       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.
+      // destroyed as sessions come and go, and both facts recorded here (the
+      // gesture's pointer type, and whether it took the keyboard off the
+      // terminal) belong to the gesture, not to a chip.
       bar.addEventListener(
         "pointerdown",
         (e) => {
           menuTouch = e.pointerType === "touch";
+          noteChromePress();
         },
         { passive: true },
       );
+      // The switcher's half of that snapshot (its rows and the x are buttons, so
+      // pressing one focuses it and blurs the terminal exactly as a chip does).
+      switcher.addEventListener("pointerdown", noteChromePress, { passive: true });
       function hideTabMenu(): void {
         tabMenu.classList.remove("visible");
         tabMenu.replaceChildren();