@cplieger/web-terminal-ui 3.5.0 → 4.1.0

package/package.json

@@ -1,12 +1,25 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "3.5.0",
+  "version": "4.1.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",
   "exports": {
     ".": "./src/index.ts",
-    "./presets": "./src/presets.ts"
+    "./presets": "./src/presets.ts",
+    "./presets/single": "./src/presets/single.ts",
+    "./presets/touch": "./src/presets/touch.ts",
+    "./presets/tabbed": "./src/presets/tabbed.ts",
+    "./presets/agent-tabbed": "./src/presets/agent-tabbed.ts",
+    "./features/clipboard": "./src/features/clipboard.ts",
+    "./features/context-menu": "./src/features/context-menu.ts",
+    "./features/scroll-to-bottom": "./src/features/scroll-to-bottom.ts",
+    "./features/predictive-echo": "./src/features/predictive-echo.ts",
+    "./features/connection-banner": "./src/features/connection-banner.ts",
+    "./features/mobile-toolbar": "./src/features/mobile-toolbar.ts",
+    "./features/tabs": "./src/features/tabs/index.ts",
+    "./features/activity-monitor": "./src/features/activity-monitor.ts",
+    "./features/animations": "./src/features/animations.ts"
   },
   "sideEffects": [
     "**/*.css"
@@ -25,7 +38,7 @@
     "verify": "bash scripts/verify.sh"
   },
   "peerDependencies": {
-    "@cplieger/web-terminal-engine": ">=2.4.0"
+    "@cplieger/web-terminal-engine": "^3.0.0"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -38,13 +51,13 @@
     "eslint": "10.7.0",
     "fast-check": "4.9.0",
     "happy-dom": "20.10.6",
-    "html-validate": "11.5.5",
-    "knip": "6.26.0",
+    "html-validate": "11.5.6",
+    "knip": "6.27.0",
     "prettier": "3.9.5",
     "stylelint": "17.14.0",
     "stylelint-config-standard": "40.0.0",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.63.0",
+    "typescript-eslint": "8.64.0",
     "vitest": "4.1.10"
   },
   "publishConfig": {

package/scaffold/index.html

@@ -6,6 +6,11 @@
 <meta name="color-scheme" content="dark">
 <title>Web Terminal</title>
 <!-- App icons and web-app manifest are deployment-specific; add your own. -->
+<!-- /style.css = the package's css/MANIFEST concatenated: the reference
+     FULL-PAGE bundle (css/page.css — html/body reset + @font-face expecting
+     the font files at /vendor/fonts/ — plus the complete tabbed component
+     set). An embedder serves a per-preset manifest (css/MANIFEST.single/
+     .touch/.tabbed) instead and passes layout: "container". -->
 <link rel="stylesheet" href="/style.css">
 <!-- [html-validate-disable-next no-style-tag -- critical CSS for instant loading indicator] -->
 <style>

package/src/features/activity-monitor.ts

@@ -3,8 +3,11 @@
 // session's live status through its API (design sections 7, 22.4, 22.5). It is a
 // pure data source with no chrome of its own; the tabs feature consumes it via
 // ctx.use to render per-tab activity dots and drop exited/removed tabs. The
-// server pushes an initial snapshot on every (re)open, so no explicit resync is
-// needed here.
+// server pushes an initial snapshot on every (re)open — but the snapshot
+// carries no tombstones for sessions a REPLACEMENT server never knew (manager
+// restart), so the stream-open signal is surfaced via onStreamOpen and the
+// consumer (tabs) runs a one-shot GET /api/sessions reconcile there to drop
+// zombie tabs.
 
 import { connectStatusStream } from "@cplieger/web-terminal-engine";
 import type { SessionStatus } from "@cplieger/web-terminal-engine";
@@ -18,6 +21,13 @@ export interface ActivityMonitorApi {
   onStatus(cb: (s: SessionStatus) => void): Unsubscribe;
   /** The last known status for a session, or undefined. */
   current(id: string): SessionStatus | undefined;
+  /** Subscribe to stream (re)open events — fired on the initial SSE connect
+   *  and every reconnect (including the reopen against a restarted server,
+   *  whose fresh snapshot cannot tombstone sessions it never knew). A
+   *  subscriber attaching after an open has already happened is called
+   *  immediately (catch-up), so a late consumer never misses the initial
+   *  open. Optional so alternative monitor implementations remain valid. */
+  onStreamOpen?(cb: () => void): Unsubscribe;
 }
 
 export function activityMonitor(
@@ -29,8 +39,20 @@ export function activityMonitor(
       const path = opts.eventsPath ?? DEFAULT_EVENTS_PATH;
       const statuses = new Map<string, SessionStatus>();
       const subs = new Set<(s: SessionStatus) => void>();
+      const openSubs = new Set<() => void>();
+      let opens = 0;
 
       const stream = connectStatusStream(path, {
+        onOpen() {
+          opens++;
+          for (const cb of [...openSubs]) {
+            try {
+              cb();
+            } catch (err) {
+              console.error("web-terminal-ui: activityMonitor open subscriber threw", err);
+            }
+          }
+        },
         onStatus(s) {
           if (s.removed) {
             statuses.delete(s.id);
@@ -59,10 +81,18 @@ export function activityMonitor(
           current(id) {
             return statuses.get(id);
           },
+          onStreamOpen(cb) {
+            openSubs.add(cb);
+            if (opens > 0) {
+              cb(); // catch-up: the stream opened before this subscriber attached
+            }
+            return () => openSubs.delete(cb);
+          },
         },
         teardown() {
           stream.close();
           subs.clear();
+          openSubs.clear();
           statuses.clear();
         },
       };

package/src/features/connection-banner.ts

@@ -14,6 +14,7 @@ const TEXT: Partial<Record<ConnState, string>> = {
   // The session's process exited (definitive; nothing is retrying). The final
   // screen stays rendered behind the banner; open a new tab to keep working.
   ended: "Session ended",
+  incompatible: "Terminal protocol mismatch; update the server or reload this page",
 };
 
 export function connectionBanner(): TerminalFeature {

package/src/features/context-menu.ts

@@ -38,17 +38,15 @@
 
 import type { TerminalFeature } from "../kernel/types.js";
 import type { ClipboardApi } from "./clipboard.js";
+import { 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;
-const EDGE_MARGIN = 8;
-// When the menu can't fit below the anchor (a long-press near the bottom edge or
-// above the keyboard), it opens above the point. This gap lifts it clear of the
-// fingertip so the touch does not cover the menu items.
-const MENU_GAP = 16;
+// 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).
@@ -209,35 +207,10 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
           return; // nothing to offer
         }
         // Make visible (so it has measurable size), then place it within the
-        // VISIBLE viewport. position:fixed => x/y are viewport coordinates; the
-        // visual viewport (when present) is the area above the on-screen
-        // keyboard, so clamping to it keeps the menu off the keyboard too.
+        // visible viewport via the shared point-anchored positioner (clamp to
+        // the visual viewport; flip above the finger near the bottom edge).
         menu.classList.add("visible");
-        const vv = window.visualViewport;
-        const viewLeft = vv ? vv.offsetLeft : 0;
-        const viewTop = vv ? vv.offsetTop : 0;
-        const viewWidth = vv ? vv.width : window.innerWidth;
-        const viewHeight = vv ? vv.height : window.innerHeight;
-        const menuW = menu.offsetWidth;
-        const menuH = menu.offsetHeight;
-        const left = Math.max(
-          viewLeft + EDGE_MARGIN,
-          Math.min(x, viewLeft + viewWidth - menuW - EDGE_MARGIN),
-        );
-        // Open just below the point; but if that would overflow the visible
-        // bottom (a long-press near the bottom edge, where the user naturally
-        // taps), flip above the finger so the menu is neither clipped off-screen
-        // nor hidden under the fingertip.
-        let top = y;
-        if (y + menuH + EDGE_MARGIN > viewTop + viewHeight) {
-          top = y - menuH - MENU_GAP;
-        }
-        top = Math.max(
-          viewTop + EDGE_MARGIN,
-          Math.min(top, viewTop + viewHeight - menuH - EDGE_MARGIN),
-        );
-        menu.style.left = `${String(left)}px`;
-        menu.style.top = `${String(top)}px`;
+        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).
         if (touch) {

package/src/features/menu-position.ts

@@ -0,0 +1,50 @@
+// menu-position.ts — shared point-anchored placement for the fixed-position
+// menus (the terminal context menu and the tab-strip menu), which previously
+// carried two hand-synced copies of this exact clamp/flip math.
+//
+// position:fixed means x/y are viewport coordinates; the VISUAL viewport
+// (when present) is the area above the on-screen keyboard, so clamping to it
+// keeps a menu off the keyboard too.
+
+/** Clamp margin from the visible viewport edges (px). */
+const EDGE_MARGIN = 8;
+
+/** Gap between the pointer and a flipped-above menu (px), so the menu is not
+ *  hidden under the fingertip that long-pressed near the bottom edge. */
+const FLIP_GAP = 16;
+
+/** 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
+ *  against the terminal root (.wt-root), so the viewport-space result is
+ *  rebased onto its offsetParent's box — placement is identical whether the
+ *  root fills the viewport (wt-viewport) or an embedder's panel
+ *  (wt-container). The menu must be measurable (rendered, not display:none)
+ *  when called. */
+export function placeMenuAt(menu: HTMLElement, x: number, y: number): void {
+  const vv = window.visualViewport;
+  const viewLeft = vv ? vv.offsetLeft : 0;
+  const viewTop = vv ? vv.offsetTop : 0;
+  const viewWidth = vv ? vv.width : window.innerWidth;
+  const viewHeight = vv ? vv.height : window.innerHeight;
+  const menuW = menu.offsetWidth;
+  const menuH = menu.offsetHeight;
+  const left = Math.max(
+    viewLeft + EDGE_MARGIN,
+    Math.min(x, viewLeft + viewWidth - menuW - EDGE_MARGIN),
+  );
+  let top = y;
+  if (y + menuH + EDGE_MARGIN > viewTop + viewHeight) {
+    top = y - menuH - FLIP_GAP;
+  }
+  top = Math.max(viewTop + EDGE_MARGIN, Math.min(top, viewTop + viewHeight - menuH - EDGE_MARGIN));
+  // Rebase from viewport coordinates onto the positioned ancestor's box: left/
+  // top on an absolute element are offsets from the offsetParent's padding box,
+  // which for all terminal chrome is .wt-root (getBoundingClientRect is its
+  // viewport-space position; the root has no border, so border/padding offsets
+  // do not enter). A missing offsetParent (display:none ancestor — the menu is
+  // visible when called, so not in practice) falls back to (0,0) viewport base.
+  const base = menu.offsetParent?.getBoundingClientRect() ?? { left: 0, top: 0 };
+  menu.style.left = `${String(Math.round(left - base.left))}px`;
+  menu.style.top = `${String(Math.round(top - base.top))}px`;
+}

package/src/features/mobile-toolbar.ts

@@ -1,15 +1,16 @@
 // mobileToolbar feature: the on-screen key toolbar (Tab/Esc/arrows/Enter + a
 // collapse toggle and sticky-Ctrl) in the thumb-zone region (design section
-// 22.4). The engine's keyboard.bindMobileToolbar wires the buttons (DECCKM-aware
-// arrows, sticky-Ctrl state); this feature builds the toolbar chrome, routes its
+// 22.4). The engine's toolbar.bindMobileToolbar wires the buttons (DECCKM-aware
+// arrows, sticky-Ctrl state; engine >= v3, where the widget moved out of the
+// keyboard module); this feature builds the toolbar chrome, routes its
 // output through the kernel funnel, and registers sticky-Ctrl as an input
 // transform so a typed character is rewritten to its Ctrl byte when armed.
 
-import { keyboard } from "@cplieger/web-terminal-engine";
+import { toolbar } from "@cplieger/web-terminal-engine";
 import type { TerminalFeature } from "../kernel/types.js";
 import { fromHTML } from "./dom.js";
 
-const { bindMobileToolbar } = keyboard;
+const { bindMobileToolbar } = toolbar;
 
 /** mobileToolbar's public API, so a peer feature (tabs) can drive the key grid
  *  from a button it owns instead of the toolbar's own toggle. */