@cplieger/web-terminal-ui 3.5.0 → 4.1.0

package/src/kernel/conn-state.ts

@@ -38,6 +38,9 @@ export interface ConnStateMachine {
    *  the state shows immediately and persists until open() (a switch to a
    *  live session) replaces it. */
   ended(): void;
+  /** The engine refused an explicitly incompatible wire revision. This
+   *  terminal state bypasses the loading gate and persists until open(). */
+  incompatible(): void;
   /** First screen frame rendered: the loading overlay is done, so the banner
    *  may show reconnect state from here on. */
   setLoaded(): void;
@@ -59,13 +62,14 @@ export function createConnState(opts: {
 
   function emit(): void {
     // Suppress transient states until the initial load is over (the loading
-    // overlay owns the screen), with two exceptions that must show through:
-    // "offline" once the initial-failure limit is reached, and "ended" (a
-    // definitive process exit — nothing further will ever fire, so suppressing
-    // it would hide the only explanation the page will get). connectionBanner
-    // renders "open" as hidden.
+    // overlay owns the screen). Terminal states ("ended" and "incompatible")
+    // must pass through because no later frame or reconnect will explain the
+    // failure; "offline" also passes once the initial-failure limit is reached.
+    // connectionBanner renders "open" as hidden.
     const passesLoadingGate =
-      state === "ended" || (state === "offline" && consecutiveFailures >= INITIAL_FAILURE_LIMIT);
+      state === "ended" ||
+      state === "incompatible" ||
+      (state === "offline" && consecutiveFailures >= INITIAL_FAILURE_LIMIT);
     if (!loaded && !passesLoadingGate) {
       opts.onState("open"); // nothing to show yet
       return;
@@ -130,6 +134,12 @@ export function createConnState(opts: {
       consecutiveFailures = 0;
       setState("ended", 0);
     },
+    incompatible(): void {
+      // Wire refusal is terminal for this page instance. Like ended, it is not
+      // part of the failure ladder and must remain visible without a timer.
+      consecutiveFailures = 0;
+      setState("incompatible", 0);
+    },
     setLoaded(): void {
       loaded = true;
     },

package/src/kernel/kernel.ts

@@ -49,6 +49,24 @@ const TAP_MOVEMENT_PX = 10;
 // 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;
+// The narrow-layout breakpoints, in ROOT pixels. The single source of the
+// numbers: the kernel mirrors the resulting fact into the .wt-narrow root
+// class for CSS (paired there with pointer-coarseness media queries where
+// touch matters) and features read the same fact via ctx.layout(). Root
+// dimensions — not viewport dimensions — so an embedded terminal in a narrow
+// panel counts as narrow. For every full-page consumer root size equals
+// viewport size, so the width half matches the old (max-width: 600px) media
+// queries exactly.
+const NARROW_MAX_PX = 600;
+// A root can be compact by HEIGHT as well as width: a large phone rotated to
+// landscape (e.g. an iPhone 14 Pro Max at 932x430) is wider than
+// NARROW_MAX_PX, but its short viewport is still a phone in the hand — the
+// thumb-reach switcher bar is the right UX and the desktop strip wastes
+// scarce rows. Tablets are never this short (the smallest iPad is 744 CSS px
+// tall in landscape), so height <= 500 cleanly separates "landscape phone"
+// from "tablet/desktop" with margin on both sides (the tallest current
+// phones are ~440 in landscape, less with browser chrome).
+const SHORT_MAX_PX = 500;
 
 // Kernel-owned core subtree: the display-only output, the hidden textarea (the
 // single keyboard target), and the IME composition view. No chrome; features
@@ -75,6 +93,16 @@ export function createTerminal(
   const wsPath = opts.wsPath ?? DEFAULT_WS_PATH;
   const fontReady = opts.fontReady ?? DEFAULT_FONT_READY;
   const featureList = opts.features ?? [];
+  // At most one feature owns session selection (fail fast, before any DOM
+  // work): the kernel drives the first connect through its registration.
+  const owners = featureList.filter((f) => f.sessionOwner !== undefined);
+  if (owners.length > 1) {
+    throw new Error(
+      `web-terminal-ui: multiple session-owning features: ${owners.map((f) => f.name).join(", ")}`,
+    );
+  }
+  const sessionOwner = owners[0]?.sessionOwner;
+  const sessionOwnerName = owners[0]?.name ?? "";
   const encoder = new TextEncoder();
   const kernelAbort = new AbortController();
   const { signal } = kernelAbort;
@@ -91,6 +119,15 @@ export function createTerminal(
     }
   }
 
+  // Stamp the boundary classes: .wt-root scopes every library token and style
+  // rule to this subtree, and the layout-mode class decides how the root claims
+  // space — wt-viewport pins the root itself to the full viewport (the
+  // full-page product), wt-container fills the parent element (the embedded
+  // case). All chrome positions against the root, never the page. destroy()
+  // removes them.
+  const layoutMode = opts.layout ?? "viewport";
+  root.classList.add("wt-root", layoutMode === "container" ? "wt-container" : "wt-viewport");
+
   // --- Build the core subtree ---
   const tpl = document.createElement("template");
   tpl.innerHTML = CORE_TEMPLATE;
@@ -106,6 +143,22 @@ export function createTerminal(
   const announcer = createAnnouncer(root);
   const tablistController = createTablist(outputEl);
 
+  // --- Narrow-layout driver (.wt-narrow mirrors root size for CSS) ---
+  // Narrow = compact in EITHER dimension: skinny (a phone in portrait, a
+  // narrow embedded panel) or short (a phone in landscape). The one
+  // ResizeObserver below fires on both width and height changes.
+  const isNarrow = (): boolean =>
+    root.clientWidth <= NARROW_MAX_PX || root.clientHeight <= SHORT_MAX_PX;
+  function updateNarrow(): void {
+    root.classList.toggle("wt-narrow", isNarrow());
+  }
+  updateNarrow();
+  let narrowObserver: ResizeObserver | null = null;
+  if (typeof ResizeObserver === "function") {
+    narrowObserver = new ResizeObserver(updateNarrow);
+    narrowObserver.observe(root);
+  }
+
   // Toast surface (kernel-owned shared primitive, section 22.3).
   const toastEl = document.createElement("div");
   toastEl.className = "wt-toast";
@@ -187,13 +240,13 @@ export function createTerminal(
   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).
+  // it has: under a session owner the kernel drives the first connect only
+  // once resolveInitialSession() returns 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 (no owner) or the first setSession (owned).
   let connectionInitiated = false;
 
   // --- Loading lifecycle ---
@@ -326,6 +379,13 @@ export function createTerminal(
       markReady();
       connState.ended();
     },
+    onWireIncompatible() {
+      // Compatibility refusal is terminal for this page instance. Lower the
+      // pre-JS overlay even if no screen frame arrived, then leave the
+      // actionable banner visible while the engine suppresses reconnects.
+      markReady();
+      connState.incompatible();
+    },
     onServerRestart() {
       render.resetScrollback();
       render.resetScreen();
@@ -544,6 +604,7 @@ export function createTerminal(
   // --- Viewport ---
   viewport.init({
     termWrap,
+    root,
     suppressKeyboardInset: hasFinePointer,
     onSettled() {
       render.updateFontMetrics();
@@ -615,6 +676,42 @@ export function createTerminal(
   const apiMap = new Map<TerminalFeature<unknown>, unknown>();
   const instances: { feature: TerminalFeature<unknown>; instance: FeatureInstance<unknown> }[] = [];
 
+  // The one switch path: ctx.notifySwitch (tab switches) and the kernel's own
+  // owner-resolved first connect both land here.
+  function performSwitch(session: SessionRef): void {
+    // A feature's un-cancelled async (tabs create()/pollOnce()) can resolve
+    // after destroy() and request a switch; ignore it so a torn-down terminal
+    // never re-points or reopens the socket (connection.setSession below).
+    if (isDestroyed()) {
+      return;
+    }
+    // Detach (design 5.1): make input safe before the socket is re-pointed.
+    // End any in-flight IME composition and clear the textarea so
+    // half-composed text is not delivered to either session, and let every
+    // feature disarm latched input state (mobileToolbar's sticky-Ctrl) so it
+    // cannot fire against the incoming session. This all runs before
+    // setSession, and the switch is synchronous, so input is inert between
+    // detach here and the onSwitch attach below.
+    composition.cancelComposition();
+    resetToPlaceholder(input);
+    for (const { instance } of instances) {
+      instance.onDetach?.();
+    }
+    activeSession = session;
+    // Reconnect the terminal WS to this session using its per-tab resume
+    // state; the renderer was already pointed at its store by the owner.
+    connection.setSession(session.id);
+    // The owned 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);
+      }
+    }
+    bus.emit("session:switch", session);
+  }
+
   function makeContext(featureName: string): TerminalContext {
     return {
       region: (name, slot) => regions.region(name, slot),
@@ -678,38 +775,13 @@ export function createTerminal(
         announcer.announce(message, politeness);
       },
       tablist: () => tablistController,
+      layout: () => ({
+        narrow: isNarrow(),
+        coarse:
+          typeof window.matchMedia === "function" && window.matchMedia("(pointer: coarse)").matches,
+      }),
       notifySwitch(session) {
-        // A feature's un-cancelled async (tabs bootstrap/create()/pollOnce()) can
-        // resolve after destroy() and call this; ignore it so a torn-down terminal
-        // never re-points or reopens the socket (connection.setSession below).
-        if (isDestroyed()) {
-          return;
-        }
-        // Detach (design 5.1): make input safe before the socket is re-pointed.
-        // End any in-flight IME composition and clear the textarea so
-        // half-composed text is not delivered to either session, and let every
-        // feature disarm latched input state (mobileToolbar's sticky-Ctrl) so it
-        // cannot fire against the incoming session. This all runs before
-        // setSession, and the switch is synchronous, so input is inert between
-        // detach here and the onSwitch attach below.
-        composition.cancelComposition();
-        resetToPlaceholder(input);
-        for (const { instance } of instances) {
-          instance.onDetach?.();
-        }
-        activeSession = session;
-        // 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);
-          }
-        }
-        bus.emit("session:switch", session);
+        performSwitch(session);
       },
       dropSession(id) {
         connection.forgetSession(id);
@@ -744,10 +816,14 @@ export function createTerminal(
     instances.length = 0;
   }
 
-  async function setupFeatures(): Promise<void> {
+  // Resolves true when every feature set up; false when setup was aborted (a
+  // feature threw and everything rolled back, or destroy() ran mid-setup). The
+  // session-owner first connect below runs only on true — a resolver must never
+  // run against torn-down chrome.
+  async function setupFeatures(): Promise<boolean> {
     for (const feature of featureList) {
       if (destroyed) {
-        return;
+        return false;
       }
       try {
         const instance = await feature.setup(makeContext(feature.name));
@@ -762,7 +838,7 @@ export function createTerminal(
           } catch (err) {
             reportError(feature.name, err);
           }
-          return;
+          return false;
         }
         instances.push({ feature, instance });
         // Populate the feature value's readonly api (consumer pattern:
@@ -778,27 +854,47 @@ export function createTerminal(
           `web-terminal-ui: feature "${feature.name}" setup failed; terminal has no chrome`,
           err,
         );
-        return;
+        return false;
       }
     }
+    return true;
   }
-  // A session-managing feature (tabs) drives the first connect itself once it
-  // has resolved a session id (ctx.notifySwitch -> connection.setSession, which
-  // adds ?session=<id>). Connecting here first would open a bare /ws that a
-  // SessionManager 404s (no ?session=), flashing a disconnect banner and
-  // churning the reconnect backoff until the feature sets a session. So skip the
-  // startup connect when managed; the single-terminal presets leave it to us.
-  const sessionManaged = featureList.some((f) => f.managesSessions === true);
-
   // Features set up in the background; first paint is never gated on them.
-  void setupFeatures().then(() => {
-    // A session-managing feature that finished setup WITHOUT initiating a
-    // connection means its bootstrap failed (no session could be listed or
-    // spawned) or its setup threw. markReady (needs a screen frame) and onGiveUp
-    // (needs the connect to be attempted and fail) then never fire, so the
-    // loading overlay would stay up forever, hiding the retry chrome the feature
-    // keeps alive (tabs' "+"). Dismiss it so the page shows its real state.
-    if (sessionManaged && !connectionInitiated && !destroyed) {
+  // Under a session owner the kernel then drives the first connect itself:
+  // await the owner's resolveInitialSession() and switch to the session it
+  // returns through the same path a tab switch uses. Connecting to the bare
+  // wsPath first would open a /ws that a SessionManager 404s (no ?session=),
+  // flashing a disconnect banner and churning the reconnect backoff — hence no
+  // startup connect below when an owner is registered. A null (or thrown)
+  // resolution means the bootstrap failed: the owner keeps its retry chrome
+  // alive, and the kernel — which now SEES the failure instead of inferring it
+  // from a missing side effect — dismisses the loading overlay so that chrome
+  // is visible instead of an eternal spinner.
+  void setupFeatures().then(async (ok) => {
+    if (!ok) {
+      // Setup aborted (rolled back or destroyed). Under a session owner no
+      // connect will ever be attempted, so nothing else can lower the loading
+      // overlay — dismiss it so the page shows its real state.
+      if (!connectionInitiated && !destroyed) {
+        dismissLoadingOverlay();
+      }
+      return;
+    }
+    if (!sessionOwner || isDestroyed()) {
+      return;
+    }
+    let resolved: SessionRef | null = null;
+    try {
+      resolved = await sessionOwner.resolveInitialSession();
+    } catch (err) {
+      reportError(sessionOwnerName, err);
+    }
+    if (isDestroyed()) {
+      return;
+    }
+    if (resolved) {
+      performSwitch(resolved);
+    } else if (!connectionInitiated) {
       dismissLoadingOverlay();
     }
   });
@@ -806,7 +902,7 @@ export function createTerminal(
   // --- Connect + focus ---
   render.updateFontMetrics();
   composition.positionCompositionView();
-  if (!sessionManaged) {
+  if (!sessionOwner) {
     connection.connect();
     connectionInitiated = true;
   }
@@ -814,6 +910,19 @@ export function createTerminal(
 
   return {
     focus: focusTerminal,
+    send(bytes) {
+      if (destroyed) {
+        return;
+      }
+      sendBytes(bytes);
+    },
+    reset() {
+      if (destroyed) {
+        return;
+      }
+      render.resetScrollback();
+      render.resetScreen();
+    },
     destroy() {
       if (destroyed) {
         return;
@@ -821,6 +930,7 @@ export function createTerminal(
       destroyed = true;
       teardownFeatures();
       kernelAbort.abort();
+      narrowObserver?.disconnect();
       viewport.teardown();
       // Reset the composition singleton (kernel-driven, no feature teardown): a
       // destroy() mid-IME-composition otherwise leaves module-level `composing`
@@ -839,6 +949,7 @@ export function createTerminal(
       bus.clear();
       announcer.destroy();
       regions.destroy();
+      root.classList.remove("wt-root", "wt-viewport", "wt-container", "wt-narrow");
       root.replaceChildren();
     },
   };

package/src/kernel/types.ts

@@ -60,7 +60,10 @@ export type ConnState =
   // The active session's process has EXITED (the engine's definitive 4001
   // close): not a connectivity problem, so no reconnect is coming. Cleared
   // only by connecting somewhere live (a tab switch / a new session).
-  | "ended";
+  | "ended"
+  // The engine refused an explicitly incompatible wire revision. This is a
+  // terminal state, not a transient disconnect; page reload/update is required.
+  | "incompatible";
 
 // --- Engine drive handles ---
 //
@@ -89,6 +92,13 @@ export interface RenderHandle {
 export interface ScrollHandle {
   scrollToBottom(): void;
   isUserScrolledUp(): boolean;
+  /** The viewport's current scroll offset — the read half of per-tab scroll
+   *  memory. The engine's scroll controller owns the container's scrollTop;
+   *  features go through this seam, never the DOM element (engine >= v3). */
+  currentScrollTop(): number;
+  /** Restore a saved offset; follow/hold re-derives from the resulting scroll
+   *  event exactly as for a user scroll — the write half of scroll memory. */
+  restoreScrollTop(top: number): void;
 }
 
 // --- Typed event bus payloads (section 22.4) ---
@@ -110,9 +120,6 @@ export interface TerminalEvents {
   "wire:modes": ModesMessage;
   /** A screen frame (first-paint / activity hooks). */
   "wire:screen": ScreenMessage;
-  /** The layout breakpoint changed (desktop <-> mobile), so a feature re-homes
-   *  its chrome across regions (section 22.13). */
-  "layout:change": { mobile: boolean };
   /** The user scrolled away from / back to the bottom (drives the
    *  scroll-to-bottom affordance). */
   "scroll:state": { scrolledUp: boolean };
@@ -204,6 +211,16 @@ export interface TerminalContext {
   /** The kernel's tablist/tabpanel ARIA controller (used by tabs). */
   tablist(): TablistController;
 
+  /** The current layout facts a feature keys touch-vs-desktop behavior on.
+   *  `narrow` is a ROOT compact in EITHER dimension against the kernel's
+   *  breakpoints: skinny (width, a portrait phone or a narrow embedded panel)
+   *  or short (height, a landscape phone) — the same fact the .wt-narrow root
+   *  class exposes to CSS; root size, not viewport size, so an embedded
+   *  terminal in a narrow panel counts as narrow. `coarse` is the primary
+   *  pointer's coarseness (a live media-query read). Read lazily at
+   *  interaction time. */
+  layout(): { narrow: boolean; coarse: boolean };
+
   /** Switch the live terminal to a session. tabs binds the renderer to the
    *  session's cached store (ctx.render.bind) first, then calls this; the kernel
    *  reconnects the terminal WS to that session (connection.setSession, using
@@ -236,15 +253,32 @@ export interface TerminalFeature<Api = void> {
    *  Readonly so a feature is covariant in Api (a TerminalFeature<X> is a
    *  TerminalFeature<unknown>); the kernel sets it through a narrow cast. */
   readonly api?: Api;
-  /** True if this feature owns session selection and drives the first
-   *  connection itself (via ctx.notifySwitch once it has resolved a session id).
-   *  The kernel reads this synchronously from the feature list and, when any
-   *  feature sets it, SKIPS its own startup connect: connecting to the bare
-   *  wsPath before a session exists would hit a session-gated /ws (the
-   *  SessionManager 404s a /ws with no ?session=) and churn the reconnect
-   *  backoff until the feature set a session. `tabs` sets this; single-terminal
-   *  presets leave it unset so the kernel connects to the bare wsPath as before. */
-  readonly managesSessions?: boolean;
+  /** Present on the ONE feature that owns session selection (at most one per
+   *  terminal; createTerminal throws when two features register). Its presence
+   *  makes the kernel SKIP the startup connect to the bare wsPath (which a
+   *  session-gated server 404s, churning the reconnect backoff); the kernel
+   *  instead drives the first connect through resolveInitialSession() once
+   *  feature setup completes. Single-terminal presets leave it unset so the
+   *  kernel connects to the bare wsPath at startup. */
+  readonly sessionOwner?: SessionOwnerRegistration;
+}
+
+/** The session-owner registration: how the one session-owning feature and the
+ *  kernel split the first connect. The feature owns session selection (list /
+ *  spawn / pick) and its own bootstrap state; the kernel owns the connect
+ *  itself, so a failed bootstrap is SEEN by the kernel (which dismisses the
+ *  loading overlay) instead of inferred from a missing side effect. */
+export interface SessionOwnerRegistration {
+  /** Resolve the initial session: list (or spawn) one, build per-session
+   *  state, and bind the renderer to the session's store (ctx.render.bind) —
+   *  but do NOT call ctx.notifySwitch for it. The kernel performs the switch
+   *  with the returned ref through the same path notifySwitch uses. Return
+   *  null when no session could be resolved (the bootstrap failed): the
+   *  feature keeps its retry chrome alive, and the kernel dismisses the
+   *  loading overlay so that chrome is visible. A throw is treated as null
+   *  (and reported through the feature-error channel). Called exactly once,
+   *  after every feature's setup has resolved. */
+  resolveInitialSession(): Promise<SessionRef | null>;
 }
 
 /** What a feature's setup returns: its optional typed API, a teardown, and an
@@ -275,6 +309,14 @@ export interface CreateTerminalOptions {
    *  Heterogeneous feature APIs are held as unknown here; a consumer reads a
    *  specific feature's api off the feature value it holds. */
   features?: readonly TerminalFeature<unknown>[];
+  /** How the terminal claims space (default "viewport").
+   *  "viewport": the root becomes a fixed full-viewport box — the full-page
+   *  product (web-terminal-server, web-terminal-kiro, the scaffold page).
+   *  "container": the root fills its parent element, which becomes the
+   *  boundary — the embedded case (vibekit's panel). Either way the kernel
+   *  stamps the matching class (wt-viewport / wt-container) on the root and
+   *  every piece of chrome positions against the root, never the page. */
+  layout?: "viewport" | "container";
   /** WebSocket endpoint path (default "/ws"). */
   wsPath?: string;
   /** CSS font shorthand awaited before the first resize. */
@@ -286,8 +328,8 @@ export interface CreateTerminalOptions {
    *  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. */
+   *  instance. Known tokens: --accent, --tab-bg, --tab-hover-bg,
+   *  --tab-active-bg, --tab-active-fg, --tab-active-border. */
   theme?: Readonly<Record<string, string>>;
 }
 
@@ -297,6 +339,17 @@ export interface CreateTerminalOptions {
 export interface TerminalHandle {
   /** Focus the terminal input (opens the soft keyboard on touch). */
   focus(): void;
+  /** Send bytes to the active session through the kernel's sanitizing,
+   *  session-routed input funnel — the same path features use: input
+   *  transforms apply, and the view snaps to the bottom exactly like typed
+   *  input. The supported host path for "type this command" affordances
+   *  (a run-in-shell button). No-op after destroy(). */
+  send(bytes: Uint8Array): void;
+  /** Reset the LOCAL display: drop the client-side scrollback and screen (the
+   *  same reset the engine performs on a server restart). Deliberately injects
+   *  no keystroke — a host that wants a freshly drawn prompt sends one itself
+   *  (e.g. Ctrl+L via send()). No-op after destroy(). */
+  reset(): void;
   /** Tear down every feature in reverse order, dispose all subscriptions, and
    *  release the kernel's DOM and engine wiring. */
   destroy(): void;

package/src/presets/agent-tabbed.ts

@@ -0,0 +1,15 @@
+// presetAgentTabbed: the tabbed composition tuned for an agent shell.
+
+import type { TerminalFeature } from "../kernel/types.js";
+import { buildTabbed } from "./tabbed.js";
+
+/** 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);
+}

package/src/presets/single.ts

@@ -0,0 +1,27 @@
+// presetSingle: the single-pane desktop composition. Its own entry module so a
+// consumer importing "@cplieger/web-terminal-ui/presets/single" pulls in ONLY
+// this feature graph — none of the toolbar/tabs modules (the ./presets barrel
+// statically reaches everything; these per-preset entries are the
+// graph-minimal imports).
+
+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";
+
+/** 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(),
+  ];
+}

package/src/presets/tabbed.ts

@@ -0,0 +1,42 @@
+// presetTabbed (and the shared tabbed composition builder): the full
+// multi-session UI. 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`.
+
+import type { TerminalFeature } from "../kernel/types.js";
+import { mobileToolbar } from "../features/mobile-toolbar.js";
+import { tabs } from "../features/tabs/index.js";
+import { activityMonitor } from "../features/activity-monitor.js";
+import { animations } from "../features/animations.js";
+import { presetSingle } from "./single.js";
+
+/** 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 shows a dot. The
+ *  toolbar and monitor are ordered before tabs because tabs reads their APIs
+ *  via ctx.use. Shared by presetTabbed and presetAgentTabbed (agent-tabbed.ts),
+ *  which differ only in the title source. */
+export 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. 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);
+}

package/src/presets/touch.ts

@@ -0,0 +1,13 @@
+// presetTouch: the touch-first composition (single + the on-screen key
+// toolbar). Its own entry module so a touch consumer's delivered import graph
+// excludes the tabs/activity/animations modules entirely (vibekit's embedded
+// panel imports exactly this).
+
+import type { TerminalFeature } from "../kernel/types.js";
+import { mobileToolbar } from "../features/mobile-toolbar.js";
+import { presetSingle } from "./single.js";
+
+/** Touch-first UI: presetSingle plus the on-screen key toolbar. */
+export function presetTouch(): TerminalFeature<unknown>[] {
+  return [...presetSingle(), mobileToolbar()];
+}