@cplieger/web-terminal-ui 3.0.4 → 3.1.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,11 @@
 // 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 split by consumer: presetTabbed is the generic label-only
+// tabbed UI (a plain bash/sh terminal, the first-class experience); the derived
+// presetAgentTabbed layers the activity monitor on top, so an agent shell like
+// vibecli gets per-tab status dots. The split keeps agent semantics out of the
+// generic terminal (design "generic first, vibecli is a derivation").
 
 import type { TerminalFeature } from "./kernel/types.js";
 import { clipboard } from "./features/clipboard.js";
@@ -15,6 +19,7 @@ import { connectionBanner } from "./features/connection-banner.js";
 import { mobileToolbar } from "./features/mobile-toolbar.js";
 import { tabs } from "./features/tabs.js";
 import { activityMonitor } from "./features/activity-monitor.js";
+import type { ActivityMonitorApi } from "./features/activity-monitor.js";
 import { animations } from "./features/animations.js";
 
 /** Single-pane desktop UI: context menu, clipboard, scroll-to-bottom, predictive
@@ -37,10 +42,35 @@ 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). */
+// buildTabbed composes the tabbed UI shared by both tabbed presets: 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), tabs wired
+// to that toolbar, and animations. An optional activity monitor adds per-tab
+// status dots (the agent variant). The toolbar and monitor are ordered before
+// tabs because tabs reads their APIs via ctx.use.
+function buildTabbed(monitor?: TerminalFeature<ActivityMonitorApi>): TerminalFeature<unknown>[] {
+  const kb = mobileToolbar({ externalToggle: true });
+  return [
+    ...presetSingle(),
+    kb,
+    ...(monitor ? [monitor] : []),
+    tabs({ keyboardToggle: kb, ...(monitor ? { activityMonitor: monitor } : {}) }),
+    animations(),
+  ];
+}
+
+/** Generic tabbed UI: touch features, label-only tabs, the mobile keyboard bar,
+ *  and animations. No activity monitor, so tabs carry no status dots. This is
+ *  the first-class experience for a plain terminal (bash/sh) where "agent
+ *  activity" has no meaning. An agent shell wants presetAgentTabbed instead. */
 export function presetTabbed(): TerminalFeature<unknown>[] {
-  const monitor = activityMonitor();
-  return [...presetTouch(), monitor, tabs({ activityMonitor: monitor }), animations()];
+  return buildTabbed();
+}
+
+/** Agent-shell tabbed UI: presetTabbed plus the activity monitor, so each tab
+ *  shows a live status dot (idle / working / done / needs-input) from the
+ *  server's status SSE. vibecli composes this; a generic terminal composes
+ *  presetTabbed. */
+export function presetAgentTabbed(): TerminalFeature<unknown>[] {
+  return buildTabbed(activityMonitor());
 }

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