@cplieger/web-terminal-ui 3.0.4 → 3.2.0

package/src/kernel/kernel.ts

@@ -44,6 +44,11 @@ const DEFAULT_WS_PATH = "/ws";
 const DEFAULT_FONT_READY = '14px "MonaspiceNe NFM"';
 const TOAST_MS = 3000;
 const TAP_MOVEMENT_PX = 10;
+// A touch that focuses the input (opens the soft keyboard) must be a genuine
+// tap: short and low-movement. A longer hold is a long-press, which belongs to
+// native text selection / the context menu — so tap-to-focus bows out above
+// this duration and never steals a long-press or a selection.
+const TAP_MAX_MS = 500;
 
 // Kernel-owned core subtree: the display-only output, the hidden textarea (the
 // single keyboard target), and the IME composition view. No chrome; features
@@ -74,6 +79,18 @@ export function createTerminal(
   const kernelAbort = new AbortController();
   const { signal } = kernelAbort;
 
+  // Apply consumer theme overrides as CSS custom properties on the root, so the
+  // whole terminal subtree inherits them. The library ships the token defaults
+  // (css/00-tokens.css); these override them for this instance. Only custom
+  // properties (leading "--") are set.
+  if (opts.theme) {
+    for (const [key, value] of Object.entries(opts.theme)) {
+      if (key.startsWith("--")) {
+        root.style.setProperty(key, value);
+      }
+    }
+  }
+
   // --- Build the core subtree ---
   const tpl = document.createElement("template");
   tpl.innerHTML = CORE_TEMPLATE;
@@ -157,6 +174,16 @@ export function createTerminal(
 
   // --- Active session (SessionView + onSwitch fan-out) ---
   let activeSession: SessionRef | null = null;
+  // Whether the first connection has been kicked off. The wake-reconnect
+  // handlers (visibilitychange/pageshow/online) must not open a socket before
+  // it has: a session-managing feature (tabs) drives the first connect via
+  // notifySwitch once it resolves a session id, and connecting to the bare
+  // wsPath before then hits a session-gated endpoint (the SessionManager 404s a
+  // /ws with no ?session=). pageshow fires on the initial load, so without this
+  // gate a slow session list lets pageshow's reconnectNow open a bare /ws that
+  // 404s (seen in Firefox, where the list loses the race). Flips true on the
+  // startup connect (unmanaged) or the first setSession (managed).
+  let connectionInitiated = false;
 
   // --- Loading lifecycle ---
   let ready = false;
@@ -368,9 +395,16 @@ export function createTerminal(
   );
 
   // --- Focus strategy (the touch focus dance; see the input-model contract) ---
+  // On touch, the terminal output is the native text-selection surface, so this
+  // handler deliberately does the MINIMUM: it opens the keyboard on a clean tap
+  // and otherwise gets out of the browser's way. It never preventDefaults a
+  // touch and never clears a selection — a long-press to select a word, the OS
+  // copy/paste callout, and drag-to-scroll are all left to the platform (the
+  // research consensus: over text, allow the default and emit nothing).
   let lastPointerType = "mouse";
   let pointerDownX = 0;
   let pointerDownY = 0;
+  let pointerDownTime = 0;
   function focusTerminal(): void {
     input.focus({ preventScroll: true });
   }
@@ -380,6 +414,7 @@ export function createTerminal(
       lastPointerType = e.pointerType;
       pointerDownX = e.clientX;
       pointerDownY = e.clientY;
+      pointerDownTime = e.timeStamp;
     },
     { passive: true, signal },
   );
@@ -394,13 +429,29 @@ export function createTerminal(
       }
       const dx = Math.abs(e.clientX - pointerDownX);
       const dy = Math.abs(e.clientY - pointerDownY);
+      // A drag (scroll / selection-extend) or a long-press (native word-select /
+      // context menu) is not a tap-to-focus: bow out and let the browser own it.
       if (dx > TAP_MOVEMENT_PX || dy > TAP_MOVEMENT_PX) {
         return;
       }
+      if (e.timeStamp - pointerDownTime > TAP_MAX_MS) {
+        return;
+      }
+      // A clean tap while text is selected means "done selecting": clear the
+      // selection (and dismiss the OS callout with it). This is our deselect —
+      // iOS otherwise leaves the selection stuck, because the synthetic mousedown
+      // we preventDefault to preserve the keyboard also suppresses the platform's
+      // own tap-to-deselect. Do NOT also focus: a deselect tap should not pop the
+      // keyboard; the next clean tap (nothing selected) opens it. The long-press
+      // that MADE the selection is filtered out above by the duration/movement
+      // guards, so only a deliberate later tap reaches here.
       const sel = window.getSelection();
-      if (sel && sel.toString().length > 0) {
+      if (sel && !sel.isCollapsed) {
+        sel.removeAllRanges();
         return;
       }
+      // A clean tap with nothing selected focuses the input, synchronously (an
+      // async focus would not raise the iOS soft keyboard).
       focusTerminal();
     },
     { passive: true, signal },
@@ -477,7 +528,9 @@ export function createTerminal(
     "visibilitychange",
     () => {
       if (document.visibilityState === "visible") {
-        connection.reconnectNow();
+        if (connectionInitiated) {
+          connection.reconnectNow();
+        }
         focusTerminal();
       }
     },
@@ -486,7 +539,9 @@ export function createTerminal(
   window.addEventListener(
     "pageshow",
     () => {
-      connection.reconnectNow();
+      if (connectionInitiated) {
+        connection.reconnectNow();
+      }
       focusTerminal();
     },
     { signal },
@@ -494,7 +549,9 @@ export function createTerminal(
   window.addEventListener(
     "online",
     () => {
-      connection.reconnectNow();
+      if (connectionInitiated) {
+        connection.reconnectNow();
+      }
     },
     { signal },
   );
@@ -584,6 +641,9 @@ export function createTerminal(
         // Reconnect the terminal WS to this session using its per-tab resume
         // state; the renderer was already pointed at its store by tabs.
         connection.setSession(session.id);
+        // The managed first connect has happened (session id is now on the WS
+        // URL); wake-reconnect handlers may fire from here on.
+        connectionInitiated = true;
         for (const { instance } of instances) {
           if (instance.onSwitch) {
             instance.onSwitch(session);
@@ -658,6 +718,7 @@ export function createTerminal(
   const sessionManaged = featureList.some((f) => f.managesSessions === true);
   if (!sessionManaged) {
     connection.connect();
+    connectionInitiated = true;
   }
   focusTerminal();
 

package/src/kernel/types.ts

@@ -272,6 +272,14 @@ export interface CreateTerminalOptions {
   fontReady?: string;
   /** Optional pre-JS loading overlay the kernel fades out on first paint. */
   loading?: HTMLElement;
+  /** Theme overrides: CSS custom properties set on the terminal root so a
+   *  consumer recolors the UI (accent, tab hover/active) without shipping CSS.
+   *  Keys must be CSS custom-property names (start with "--"); values are any
+   *  CSS value. The library ships the defaults (css/00-tokens.css) — the
+   *  "template"; these are the consumer's "settings" and override them for this
+   *  instance. Known tokens: --accent, --tab-hover-bg, --tab-active-bg,
+   *  --tab-active-fg. */
+  theme?: Readonly<Record<string, string>>;
 }
 
 /** The handle createTerminal returns. Feature APIs are not materialized here

package/src/presets.ts

@@ -4,7 +4,13 @@
 // lists (convenient, full UI); a consumer wanting a minimal footprint imports
 // individual features instead.
 //
-// presetTabbed (tabs + activityMonitor) is added once those features land.
+// The tabbed presets (presetTabbed / presetAgentTabbed) are now identical: both
+// include the activity monitor, because the per-tab activity dot reveals itself
+// only when a session reports activity (OSC 9;4 progress), so a plain shell
+// simply never shows one. The generic-vs-agent distinction is now purely
+// server-side — an agent server sets a status classifier that maps OSC 9
+// notifications to done/needs-input. presetAgentTabbed is kept as an alias for
+// its consumers (vibecli).
 
 import type { TerminalFeature } from "./kernel/types.js";
 import { clipboard } from "./features/clipboard.js";
@@ -37,10 +43,41 @@ export function presetTouch(): TerminalFeature<unknown>[] {
   return [...presetSingle(), mobileToolbar()];
 }
 
-/** Full reference UI: presetTouch plus tabs, the activity monitor, and
- *  animations. activityMonitor is ordered before tabs because tabs reads its
- *  API via ctx.use during setup (to wire status dots). */
-export function presetTabbed(): TerminalFeature<unknown>[] {
+// buildTabbed composes the tabbed UI: the single-pane touch features, an
+// externally-driven mobile toolbar (its grid is opened from a keyboard button in
+// the tab bar, not its own toggle), the activity monitor (the status-SSE data
+// source), tabs wired to both, and animations. The activity dot reveals itself
+// per tab only when a session reports activity (OSC 9;4), so the monitor is
+// always included — a plain shell just never reveals a dot. The toolbar and
+// monitor are ordered before tabs because tabs reads their APIs via ctx.use.
+function buildTabbed(): TerminalFeature<unknown>[] {
+  const kb = mobileToolbar({ externalToggle: true });
   const monitor = activityMonitor();
-  return [...presetTouch(), monitor, tabs({ activityMonitor: monitor }), animations()];
+  return [
+    ...presetSingle(),
+    kb,
+    monitor,
+    tabs({ keyboardToggle: kb, activityMonitor: monitor }),
+    animations(),
+  ];
+}
+
+/** Tabbed UI: the touch features, tabs, the mobile keyboard bar, the activity
+ *  monitor, and animations. Requires a server that speaks the session API
+ *  (`/api/sessions`, `/ws?session=`, and the status SSE `/api/sessions/events`),
+ *  such as `web-terminal-server` or `vibecli`. Each tab's title follows the
+ *  process OSC 0/2 window title when the program sets one, else the last
+ *  submitted line; each tab's activity dot stays hidden until its session
+ *  reports activity via OSC 9;4 progress (kiro-cli, Claude Code, …), so a plain
+ *  bash/sh keeps clean, label-only tabs. */
+export function presetTabbed(): TerminalFeature<unknown>[] {
+  return buildTabbed();
+}
+
+/** Alias of presetTabbed, kept for the agent-shell consumer (vibecli). The UI is
+ *  identical — the generic-vs-agent distinction is now purely server-side: an
+ *  agent server sets a status classifier (mapping OSC 9 notifications to
+ *  done/needs-input), and each tab's dot reveals itself from OSC 9;4 either way. */
+export function presetAgentTabbed(): TerminalFeature<unknown>[] {
+  return buildTabbed();
 }

package/src/viewport.ts

@@ -74,8 +74,23 @@ export function init(opts: {
       // left behind the keyboard for iOS to scroll to.
       const offsetTop = Math.max(0, Math.round(vv.offsetTop));
       const bottomInset = Math.max(0, Math.round(window.innerHeight - vv.offsetTop - vv.height));
+      // Reserved bottom chrome (a bottom tab bar) the content must clear, on top
+      // of the keyboard inset. A feature sets --wt-reserve-bottom (px) on the
+      // root, 0 when none; viewport owns the terminal's fixed-box geometry, so it
+      // folds the reserve into the bottom offset here. The reserve excludes the
+      // keyboard (it is measured with the keyboard closed), so adding it to
+      // bottomInset does not double-count.
+      const reserve = Math.max(
+        0,
+        Math.round(
+          parseFloat(
+            getComputedStyle(document.documentElement).getPropertyValue("--wt-reserve-bottom"),
+          ) || 0,
+        ),
+      );
+      const bottom = bottomInset + reserve;
       termWrap.style.top = offsetTop > 0 ? `${offsetTop}px` : "";
-      termWrap.style.bottom = bottomInset > 0 ? `${bottomInset}px` : "";
+      termWrap.style.bottom = bottom > 0 ? `${bottom}px` : "";
       // Expose the same geometry as CSS vars for the sibling fixed chrome:
       // --kb-inset lifts the bottom banner above the keyboard; --vv-top lets the
       // top key toolbar follow the visual viewport's offset (otherwise it