@cplieger/web-terminal-ui 3.0.4 → 3.2.0

package/README.md

@@ -85,26 +85,33 @@ render/connection/scroll modules are single-instance per page (tabs multiplex
 sessions over the one kernel). `scaffold/index.html` is a complete reference page
 to copy and adapt.
 
-Three presets are provided (import from `@cplieger/web-terminal-ui/presets`); each
+Four presets are provided (import from `@cplieger/web-terminal-ui/presets`); each
 is a plain feature-array factory, so you can spread and edit it, or hand-pick
 individual features instead:
 
 - `presetSingle()` — single-pane desktop UI (context menu, clipboard,
   scroll-to-bottom, predictive echo, connection banner).
 - `presetTouch()` — `presetSingle()` plus the mobile key toolbar.
-- `presetTabbed()` — the full reference UI: `presetTouch()` plus tabs, the
-  activity monitor, and animations. Requires a server that speaks the session
-  API (`/api/sessions`, the status SSE, and `/ws?session=`), such as
-  `web-terminal-server` or `vibecli`.
+- `presetTabbed()` — the generic tabbed UI: `presetTouch()` plus tabs and
+  animations. Tabs are label-only (no activity dots); each tab's title follows
+  the process window title (OSC 0/2) when the program sets one and keeps it
+  updated, otherwise the last command submitted. Requires a server that speaks
+  the session API (`/api/sessions` and `/ws?session=`), such as
+  `web-terminal-server`.
+- `presetAgentTabbed()` — `presetTabbed()` plus the activity monitor, so each
+  tab carries a live status dot (idle / working / done / needs-input) from the
+  server's status SSE. Same title behavior as `presetTabbed`. For an agent shell
+  such as `vibecli`.
 
 ### 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.                               |
-| `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. |
+| 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.                                        |
+| `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.          |
+| `theme`     | _(none)_                   | Theme overrides (CSS custom properties on the terminal root): `--accent`, `--tab-hover-bg`, `--tab-active-bg`, `--tab-active-fg`. The library ships neutral defaults. |
 
 `createTerminal()` returns a handle: `focus()` re-focuses the terminal input
 (and opens the soft keyboard on touch), and `destroy()` tears every feature down
@@ -134,6 +141,12 @@ Consumers that ship this UI:
 - [`vibekit`](https://github.com/cplieger/vibekit)
 - [`vibecli`](https://github.com/cplieger/vibecli)
 
+## 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.
+
+This project was built with AI-assisted tooling using [Claude Opus](https://www.anthropic.com/claude) and [Kiro](https://kiro.dev). The human maintainer defines architecture, supervises implementation, and makes all final decisions.
+
 ## License
 
 GPL-3.0-or-later. See `LICENSE`.

package/css/00-tokens.css

@@ -7,13 +7,25 @@
   --border: oklch(100% 0 0deg / 15%);
   --text: oklch(90% 0.005 280deg);
   --text-active: color-mix(in oklch, var(--text) 15%, transparent);
+  /* ===== Themeable tokens (the consumer-configurable "template") =====
+     These default to the neutral built-in look; a consumer recolors the UI by
+     overriding them via createTerminal's `theme` option (which sets them on the
+     terminal root) or its own CSS. vibecli sets a purple palette. Everything
+     above is the fixed design palette; everything here is the public theme API. */
+  --accent: #a78bfa; /* accent action colour (mobile "+", toggled key button) */
+  --tab-hover-bg: var(--text-active); /* hovered inactive tab / pressed controls */
+  --tab-active-bg: color-mix(in oklch, var(--text) 22%, var(--surface)); /* active tab fill */
+  --tab-active-fg: var(--text); /* active tab text */
   --radius: 0.75rem;
   --radius-inner: 0.5rem;
   --touch-target: 2.75rem; /* 44px — Apple HIG minimum */
   --pill-outer: calc(
     var(--touch-target) + 2 * var(--sp-1) + 2px
   ); /* touch-target + 2×padding + 2×border */
-
+  /* Mobile bottom bar height (a 44px control + the bar's 2×sp-2 padding + its
+     1px top border). Bottom-anchored chrome (banner, toast, scroll-to-bottom,
+     key grid) lifts by this so it clears the bar. */
+  --wt-switcher-h: calc(var(--touch-target) + 2 * var(--sp-2) + 1px);
   --icon: 1.125rem; /* 18px */
   --icon-desktop: 1rem; /* 16px */
   --sp-1: 0.25rem;

package/css/02-app.css

@@ -10,6 +10,15 @@
      above the viewport), so native scroll anchoring is safe to leave on
      and keeps the read position steady on the rare insert-above. */
   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
+     inside a nested scroller). Declare it here too: native one/two-finger
+     scroll is allowed, double-tap-zoom is blocked (snappy taps, no 300ms
+     delay), and — critically — this does NOT affect native long-press text
+     selection (touch-action governs scroll/zoom, not selection). Avoid the
+     `manipulation` alias: it breaks pointercancel-on-scroll in Safari
+     (WebKit bug 240917), which the switcher-bar gesture relies on. */
+  touch-action: pan-x pan-y;
   font-family: var(--font-mono);
   font-size: 14px;
   line-height: 17px;
@@ -94,8 +103,22 @@
      textarea owns input, the keyboard, and IME. Keeping the editable
      element off the scroll content is what lets the first touch-drag
      scroll instead of placing a caret (bug 6), and not re-rendering it
-     as an editable keeps a selection alive across redraws (bug 1). */
+     as an editable keeps a selection alive across redraws (bug 1).
+
+     The two selection properties below are load-bearing on touch: the
+     browser's native long-press-to-select-a-word + OS copy/paste callout
+     (iOS Safari and Android Chrome) is our selection UX, so we opt IN
+     explicitly and must never let an ancestor override them. `user-select`
+     is spec'd as non-inherited but WebKit/Chromium treat it as inherited,
+     so a stray `user-select: none` on html/body/.term would silently kill
+     selection here; keep it `text` (modern Safari honors the unprefixed
+     form, so no `-webkit-` pair is needed). `-webkit-touch-callout: default`
+     keeps the iOS callout (a page-level `none` suppresses it) and has no
+     standard equivalent. No JS may `preventDefault` a touch/pointer/
+     contextmenu over this element or the native selection dies (see the
+     kernel focus handling + contextMenu feature). */
   user-select: text;
+  -webkit-touch-callout: default;
 }
 
 /* IME composition view: floating overlay positioned at the cursor
@@ -417,70 +440,6 @@
   display: none;
 }
 
-/* Desktop: scroll-to-bottom is still genuinely useful for jumping back
-   after scrolling up to read history, so it surfaces here as a
-   bottom-center pill with a label. .key-toolbar.scrolled-up is
-   toggled by app.ts, same as on touch. The display+opacity transition
-   uses allow-discrete so the fade-out plays cleanly when the user
-   clicks (scroll-to-bottom clears .scrolled-up, reverting display:none
-   after the opacity has gone to 0). */
-.kb-scroll-bottom {
-  position: fixed;
-  left: 50%;
-  bottom: calc(var(--safe-bottom, 0px) + var(--sp-3));
-  transform: translateX(-50%);
-  display: none;
-  opacity: 0;
-  align-items: center;
-  gap: var(--sp-1);
-  padding: var(--sp-2) var(--sp-3);
-  background: var(--surface);
-  backdrop-filter: var(--blur);
-  border: 1px solid var(--border);
-  border-radius: var(--radius);
-  color: var(--text);
-  font: inherit;
-  font-size: 0.875rem;
-  font-weight: 500;
-  cursor: pointer;
-  z-index: 10;
-  transition:
-    opacity var(--dur-standard) var(--ease-standard),
-    background-color var(--dur-micro) var(--ease-standard),
-    display var(--dur-standard) allow-discrete;
-}
-
-.kb-scroll-bottom::after {
-  content: "Scroll to bottom";
-}
-
-.kb-scroll-bottom svg {
-  width: var(--icon);
-  height: var(--icon);
-  stroke: currentcolor;
-  fill: none;
-  stroke-width: 2;
-  stroke-linecap: round;
-  stroke-linejoin: round;
-}
-
-.kb-scroll-bottom:hover {
-  background: color-mix(in oklch, var(--text) 8%, var(--surface));
-}
-
-.kb-scroll-bottom:active {
-  background: var(--text-active);
-}
-
-.key-toolbar.scrolled-up .kb-scroll-bottom {
-  display: inline-flex;
-  opacity: 1;
-
-  @starting-style {
-    opacity: 0;
-  }
-}
-
 @media (pointer: coarse) {
   .key-toolbar {
     position: fixed;
@@ -516,11 +475,6 @@
     height: var(--pill-outer);
   }
 
-  /* Collapsed + scrolled up: 2 buttons tall (+2px border). */
-  .key-toolbar.collapsed.scrolled-up {
-    height: calc(2 * var(--touch-target) + var(--sp-1) + 2 * var(--sp-1) + 2px);
-  }
-
   /* Grid placement: toggle at col 5 row 1 (top-right). */
   .kb-toggle {
     grid-area: 1 / 5;
@@ -551,55 +505,6 @@
     grid-area: 2 / 4;
   }
 
-  /* Scroll-bottom: col 5 row 2 (below toggle). Resets the desktop
-     FAB-specific properties (fixed position, pill padding, surface
-     background, label) so the button collapses back to a grid-area
-     icon-only key. */
-  .key-toolbar .kb-scroll-bottom {
-    position: static;
-    transform: none;
-    bottom: auto;
-    left: auto;
-    grid-area: 2 / 5;
-    display: none;
-    opacity: 0;
-    padding: 0;
-    background: transparent;
-    backdrop-filter: none;
-    border: none;
-    border-radius: var(--radius-inner);
-    font-size: inherit;
-    /* Touch override drops the desktop label (::after content: "")
-       so only the SVG remains. The base rule sets align-items:center
-       but inherits justify-content:flex-start, which would push the
-       lone icon to the left edge of the touch-target-sized cell —
-       same unequal-padding issue as the toolbar toggle. Center it. */
-    justify-content: center;
-    transition:
-      opacity var(--dur-standard) var(--ease-standard),
-      display var(--dur-standard) allow-discrete;
-  }
-
-  .kb-scroll-bottom::after {
-    /* No label on touch. Remove the box entirely (not just its text) so
-       it isn't an empty flex item — combined with the base rule's
-       gap:var(--sp-1) it would shove the lone icon half a gap off-centre. */
-    content: "";
-    display: none;
-  }
-  .kb-scroll-bottom:hover {
-    background: transparent;
-  }
-
-  .key-toolbar.scrolled-up .kb-scroll-bottom {
-    display: flex;
-    opacity: 1;
-
-    @starting-style {
-      opacity: 0;
-    }
-  }
-
   /* Keys fade in/out during open/close. The container's width/height
      transition handles the background slide; opacity handles the
      individual button appearance. Stagger the fade slightly after
@@ -691,7 +596,6 @@
 
   /* No-transition on first render */
   .key-toolbar.no-transition,
-  .key-toolbar.no-transition .kb-scroll-bottom,
   .key-toolbar.no-transition .kb-toggle .icon-hamburger,
   .key-toolbar.no-transition .kb-toggle .icon-close {
     transition: none;

package/css/03-primitives.css

@@ -0,0 +1,82 @@
+/* ===== web-terminal-ui design system: primitives =====
+   The v3 kernel builds named layout regions (wt-region-*) as siblings of the
+   terminal surface (.term, styled in 02-app.css); features mount chrome into
+   region slots. The regions are transparent groupings (display: contents) so
+   each feature's element floats over the fixed-inset terminal, and an absent
+   feature contributes nothing.
+
+   The stylesheet is layered by concern and concatenated in css/MANIFEST order:
+   tokens (00) -> reset (01) -> terminal core + legacy key toolbar (02) -> these
+   shared primitives (03) -> per-feature chrome (04 feedback, 05 tabs, 06 mobile)
+   -> animations (07, where every .wt-animate-gated transition/keyframe lives, so
+   motion is opt-in from one place). Cascade order is the file order here.
+
+   Primitives are the building blocks every feature reuses: the transparent
+   layout regions, the 44px touch button, and the toast surface. */
+
+.wt-region,
+.wt-slot {
+  display: contents;
+}
+
+/* ===== Shared button primitive (44px touch target) ===== */
+.wt-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: var(--touch-target);
+  min-height: var(--touch-target);
+  background: transparent;
+  color: var(--text);
+  border: none;
+  border-radius: var(--radius-inner);
+  font: inherit;
+  cursor: pointer;
+  touch-action: manipulation;
+  user-select: none;
+}
+
+.wt-btn:active {
+  background: var(--text-active);
+}
+
+.wt-btn svg {
+  width: var(--icon);
+  height: var(--icon);
+  stroke: currentcolor;
+  fill: none;
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+/* ===== Toast (kernel shared primitive) =====
+   Top-centre on every form factor (both desktop and the tabbed mobile UI dock a
+   bar at the bottom, so a bottom toast would collide with it; top-centre is
+   clear and the same everywhere). The vv-top/safe-top offset keeps it below the
+   notch and follows iOS's visual-viewport shift. */
+.wt-toast {
+  position: fixed;
+  top: calc(var(--safe-top, 0px) + var(--vv-top, 0px) + var(--sp-3));
+  left: 50%;
+  transform: translateX(-50%);
+  max-width: calc(100% - 2 * var(--sp-3));
+  padding: var(--sp-1) var(--sp-3);
+  background: var(--surface);
+  backdrop-filter: var(--blur);
+  border: 1px solid oklch(70% 0.1 160deg / 30%);
+  border-radius: var(--radius);
+  color: var(--text);
+  font-family: var(--font-ui);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  text-align: center;
+  z-index: 40;
+  display: none;
+  opacity: 0;
+}
+
+.wt-toast.visible {
+  display: block;
+  opacity: 1;
+}

package/css/04-feedback.css

@@ -0,0 +1,166 @@
+/* ===== Feedback + overlay chrome =====
+   Transient, non-tab feature surfaces: the connection banner, the
+   scroll-to-bottom control, the right-click/long-press context menu, and the
+   tab catching-up cue. Grouped because they are all fixed, floating, and
+   short-lived; their motion lives in 07-animations.css. */
+
+/* ===== Connection banner (connectionBanner feature) =====
+   Top-centre on every form factor (same rationale as the toast: a bottom bar is
+   always docked now). */
+.wt-conn-banner {
+  position: fixed;
+  top: calc(var(--safe-top, 0px) + var(--vv-top, 0px) + var(--sp-3));
+  left: 50%;
+  transform: translateX(-50%);
+  max-width: calc(100% - 2 * var(--sp-3));
+  padding: var(--sp-1) var(--sp-3);
+  background: var(--surface);
+  backdrop-filter: var(--blur);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  color: var(--text);
+  font-family: var(--font-ui);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  text-align: center;
+  z-index: 20;
+  display: none;
+}
+
+.wt-conn-banner.visible {
+  display: block;
+}
+
+.wt-conn-banner[data-state="reconnecting"] {
+  border-color: oklch(70% 0.15 60deg / 40%);
+}
+
+.wt-conn-banner[data-state="offline"] {
+  color: #f55;
+  border-color: oklch(60% 0.2 25deg / 50%);
+}
+
+.wt-conn-banner[data-state="restarted"] {
+  color: #fa5;
+  border-color: oklch(70% 0.15 60deg / 40%);
+}
+
+/* ===== Scroll-to-bottom (scrollToBottom feature) =====
+   A compact floating icon button docked in the bottom-right corner, shown only
+   while the user has scrolled up. Same button on both form factors (the old
+   desktop bottom-centre text pill was dropped in the design-system switch, and
+   its dead CSS removed from 02-app.css); each form factor just lifts it above
+   its own bottom bar. Size + icon centering come from the .wt-btn primitive (a
+   44px icon button); this rule adds only the floating chrome and placement. */
+.wt-scroll-bottom {
+  position: fixed;
+  right: var(--sp-3);
+  bottom: calc(var(--safe-bottom, 0px) + var(--sp-3) + var(--kb-inset, 0px));
+  background: var(--surface);
+  backdrop-filter: var(--blur);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  color: color-mix(in oklch, var(--text) 70%, transparent);
+  z-index: 10;
+  display: none;
+}
+
+/* The scroll slot gets .scrolled-up toggled by the feature; show the button. */
+.wt-slot-scroll.scrolled-up .wt-scroll-bottom {
+  display: inline-flex;
+}
+
+/* Hover brightens the icon + border; press fills the background (the .wt-btn
+   :active fill would otherwise be masked by this button's own surface fill). */
+.wt-scroll-bottom:hover {
+  border-color: color-mix(in oklch, var(--text) 35%, transparent);
+  color: var(--text);
+}
+
+.wt-scroll-bottom:active {
+  background: var(--text-active);
+}
+
+/* Mobile + tabbed: lift above the switcher bar and the keyboard (WS3). */
+@media (pointer: coarse) {
+  .wt-tabbed .wt-scroll-bottom {
+    bottom: calc(
+      var(--wt-switcher-h) + var(--safe-bottom, 0px) + var(--kb-inset, 0px) + var(--sp-2)
+    );
+  }
+}
+
+/* Desktop + tabbed: the tab strip docks at the bottom, so lift the button above
+   it with a clear gap. */
+@media (pointer: fine) {
+  .wt-tabbed .wt-scroll-bottom {
+    bottom: calc(var(--wt-tabbar-h, 44px) + var(--sp-3));
+  }
+}
+
+/* ===== Context menu (contextMenu feature) ===== */
+.wt-ctx-menu {
+  position: fixed;
+  display: none;
+  flex-direction: column;
+  background: var(--surface);
+  backdrop-filter: var(--blur);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: var(--sp-1);
+  z-index: 30;
+}
+
+.wt-ctx-menu.visible {
+  display: flex;
+}
+
+.wt-ctx-menu button {
+  background: transparent;
+  color: var(--text);
+  border: none;
+  border-radius: var(--radius-inner);
+  font-family: var(--font-ui);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  padding: var(--sp-1) var(--sp-3);
+  cursor: pointer;
+  text-align: left;
+}
+
+.wt-ctx-menu button:active {
+  background: var(--text-active);
+}
+
+@media (pointer: coarse) {
+  .wt-ctx-menu button {
+    min-height: var(--touch-target);
+    padding-block: var(--sp-2);
+    touch-action: manipulation;
+  }
+}
+
+/* ===== Catching-up cue (tabs feature, sections 12/13) =====
+   A switched-into tab's cached screen is stale until its resume delta lands, so
+   it must not read as live. This unobtrusive cue shows only if the delta has not
+   arrived shortly after the switch, and clears on the first screen frame. */
+.wt-catchup {
+  position: fixed;
+  top: calc(var(--safe-top, 0px) + var(--vv-top, 0px) + 44px);
+  left: 50%;
+  transform: translateX(-50%);
+  padding: 2px var(--sp-2);
+  background: var(--surface);
+  backdrop-filter: var(--blur);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  color: color-mix(in oklch, var(--text) 75%, transparent);
+  font-family: var(--font-ui);
+  font-size: 0.75rem;
+  z-index: 24;
+  display: none;
+}
+
+.wt-catchup.visible {
+  display: block;
+}