@cplieger/web-terminal-ui 3.5.0 → 4.1.0

package/src/presets.ts

@@ -1,8 +1,11 @@
-// Feature presets (design section 22.6). Presets are plain feature-array
-// factories, so they are spreadable and editable: a consumer can drop or add a
-// feature with a filter/spread. Importing a preset pulls in every feature it
-// lists (convenient, full UI); a consumer wanting a minimal footprint imports
-// individual features instead.
+// Feature presets: the barrel. Presets are plain feature-array factories, so
+// they are spreadable and editable: a consumer can drop or add a feature with a
+// filter/spread. This barrel statically imports EVERY preset (and therefore
+// every feature); a consumer that wants the minimal delivered import graph for
+// its composition imports the per-preset entry module instead —
+// "@cplieger/web-terminal-ui/presets/single" | "/presets/touch" |
+// "/presets/tabbed" | "/presets/agent-tabbed" — or hand-picks individual
+// features from "@cplieger/web-terminal-ui/features/<name>".
 //
 // The tabbed presets (presetTabbed / presetAgentTabbed) share the same feature
 // set (both include the activity monitor, whose per-tab dot reveals itself only
@@ -13,74 +16,7 @@
 // server-side — an agent server sets a classifier mapping OSC 9 notifications to
 // done/needs-input.
 
-import type { TerminalFeature } from "./kernel/types.js";
-import { clipboard } from "./features/clipboard.js";
-import { contextMenu } from "./features/context-menu.js";
-import { scrollToBottom } from "./features/scroll-to-bottom.js";
-import { predictiveEcho } from "./features/predictive-echo.js";
-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 { animations } from "./features/animations.js";
-
-/** Single-pane desktop UI: context menu, clipboard, scroll-to-bottom, predictive
- *  echo, and the connection banner. No mobile toolbar, no tabs. */
-export function presetSingle(): TerminalFeature<unknown>[] {
-  // contextMenu offers Copy/Paste through the clipboard feature (ctx.use), so it
-  // holds the same clipboard value the array includes.
-  const clip = clipboard();
-  return [
-    contextMenu({ clipboard: clip }),
-    clip,
-    scrollToBottom(),
-    predictiveEcho(),
-    connectionBanner(),
-  ];
-}
-
-/** Touch-first UI: presetSingle plus the on-screen key toolbar. */
-export function presetTouch(): TerminalFeature<unknown>[] {
-  return [...presetSingle(), mobileToolbar()];
-}
-
-// 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(preferInputTitle: boolean): TerminalFeature<unknown>[] {
-  const kb = mobileToolbar({ externalToggle: true });
-  const monitor = activityMonitor();
-  return [
-    ...presetSingle(),
-    kb,
-    monitor,
-    tabs({ keyboardToggle: kb, activityMonitor: monitor, preferInputTitle }),
-    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 `web-terminal-kiro`. 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(false);
-}
-
-/** Tabbed UI for an agent shell (web-terminal-kiro). Same features as presetTabbed, but
- *  with `preferInputTitle`: the agent's program (kiro-cli) emits a non-empty but
- *  useless OSC 0/2 title, so each tab's label follows the latest submitted line
- *  (persisted server-side and recovered on reload) and the OSC title is ignored.
- *  The agent-vs-generic status distinction remains server-side (a status
- *  classifier mapping OSC 9 notifications to done/needs-input). */
-export function presetAgentTabbed(): TerminalFeature<unknown>[] {
-  return buildTabbed(true);
-}
+export { presetSingle } from "./presets/single.js";
+export { presetTouch } from "./presets/touch.js";
+export { presetTabbed } from "./presets/tabbed.js";
+export { presetAgentTabbed } from "./presets/agent-tabbed.js";

package/src/viewport.ts

@@ -20,6 +20,11 @@ import { scroll } from "@cplieger/web-terminal-engine";
 const SETTLE_MS = 350;
 
 let termWrap: HTMLElement;
+// The terminal root (.wt-root): the geometry CSS vars (--kb-inset, --vv-top)
+// are published here so the terminal subtree — and nothing else on the host
+// page — inherits them. Falls back to termWrap if init was somehow given no
+// root (never in practice; the kernel always passes it).
+let varTarget: HTMLElement;
 let onSettled: ((wasAtBottom: boolean) => void) | null = null;
 let inTransition = false;
 let wasAtBottomAtStart = true;
@@ -59,6 +64,10 @@ function startTransition(): void {
 
 export function init(opts: {
   termWrap: HTMLElement;
+  /** The terminal root (.wt-root): receives the geometry CSS vars the sibling
+   *  chrome reads (--kb-inset, --vv-top), so they scope to the terminal
+   *  subtree instead of leaking onto the host document. */
+  root?: HTMLElement;
   onSettled: (wasAtBottom: boolean) => void;
   /** Ignore the visualViewport keyboard geometry (a hardware-keyboard device
    *  has no soft keyboard to accommodate); only reserved bottom chrome insets
@@ -66,6 +75,7 @@ export function init(opts: {
   suppressKeyboardInset?: () => boolean;
 }): void {
   termWrap = opts.termWrap;
+  varTarget = opts.root ?? opts.termWrap;
   onSettled = opts.onSettled;
   suppressKeyboardInset = opts.suppressKeyboardInset ?? (() => false);
 
@@ -105,12 +115,13 @@ export function init(opts: {
       // 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.
+      // Read the reserve off the terminal itself: tabs publishes it on the
+      // root (.wt-root), and termWrap inherits it — nothing terminal-scoped
+      // lives on the document root anymore.
       const rawReserve = Math.max(
         0,
         Math.round(
-          parseFloat(
-            getComputedStyle(document.documentElement).getPropertyValue("--wt-reserve-bottom"),
-          ) || 0,
+          parseFloat(getComputedStyle(termWrap).getPropertyValue("--wt-reserve-bottom")) || 0,
         ),
       );
       // Sanity cap: the reserve is bottom chrome (a tab bar), tens of px. A value
@@ -122,13 +133,13 @@ export function init(opts: {
       const bottom = bottomInset + reserve;
       termWrap.style.top = offsetTop > 0 ? `${offsetTop}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
-      // scrolls off the top when iOS shifts the layout up).
-      const root = document.documentElement.style;
-      root.setProperty("--kb-inset", `${bottomInset}px`);
-      root.setProperty("--vv-top", `${offsetTop}px`);
+      // Expose the same geometry as CSS vars for the sibling chrome, on the
+      // terminal ROOT (scoped: the host page never sees them): --kb-inset
+      // lifts the bottom banner above the keyboard; --vv-top lets the top key
+      // toolbar follow the visual viewport's offset (otherwise it scrolls off
+      // the top when iOS shifts the layout up).
+      varTarget.style.setProperty("--kb-inset", `${bottomInset}px`);
+      varTarget.style.setProperty("--vv-top", `${offsetTop}px`);
       startTransition();
     };
     vv.addEventListener("resize", onChange);
@@ -192,11 +203,13 @@ export function teardown(): void {
     clearTimeout(settleTimer);
     settleTimer = null;
   }
-  // Clear the global root CSS vars onChange published, so a destroy without
-  // a remount (which would recompute them) leaves no stale inset on :root.
-  const rootStyle = document.documentElement.style;
-  rootStyle.removeProperty("--kb-inset");
-  rootStyle.removeProperty("--vv-top");
+  // Clear the CSS vars onChange published on the terminal root, so a destroy
+  // without a remount (which would recompute them) leaves no stale inset.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- teardown may run before any init in tests
+  if (varTarget) {
+    varTarget.style.removeProperty("--kb-inset");
+    varTarget.style.removeProperty("--vv-top");
+  }
   inTransition = false;
   onSettled = null;
   suppressKeyboardInset = () => false;

package/css/03-primitives.css

@@ -1,83 +0,0 @@
-/* ===== 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;
-  pointer-events: none; /* passive status surface: never steal taps from the terminal beneath */
-  display: none;
-  opacity: 0;
-}
-
-.wt-toast.visible {
-  display: block;
-  opacity: 1;
-}

package/css/04-feedback.css

@@ -1,180 +0,0 @@
-/* ===== 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;
-  pointer-events: none; /* passive status surface: never steal taps from the terminal beneath */
-  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);
-  /* Match the tab "+" buttons (and every other .wt-btn), which round to
-     --radius-inner. Both are 44px boxes, so matching the corner radius makes
-     the FAB read as the same-sized button as the new-tab "+" beside/above it
-     rather than a rounder, different-looking control. */
-  border-radius: var(--radius-inner);
-  /* Full --text icon, matching the switcher's keyboard/switch/"+" icons (which
-     use .wt-btn's default color). Was a muted 70% mix that read as grey next to
-     those white bar icons. */
-  color: var(--text);
-  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 border; press fills the background (the .wt-btn :active
-   fill would otherwise be masked by this button's own surface fill). The icon
-   is already full --text, so hover no longer needs to change it. */
-.wt-scroll-bottom:hover {
-  border-color: color-mix(in oklch, var(--text) 35%, transparent);
-}
-
-.wt-scroll-bottom:active {
-  background: var(--text-active);
-}
-
-/* Mobile + tabbed: lift above the switcher bar and the keyboard (WS3), and pull
-   the right edge in to --sp-2 so the button sits directly above the switcher's
-   "+" (whose right edge is inset by the bar's --sp-2 padding). Both are 44px
-   border-box boxes, so matching the right inset lines them up in one vertical
-   column (they were 4px out: the FAB's base --sp-3 vs the "+"'s --sp-2). */
-@media (pointer: coarse) {
-  .wt-tabbed .wt-scroll-bottom {
-    right: var(--sp-2);
-    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;
-  pointer-events: none; /* passive status surface: never steal taps from the terminal beneath */
-  display: none;
-}
-
-.wt-catchup.visible {
-  display: block;
-}