@cplieger/web-terminal-ui 2.1.4 → 3.0.1

package/src/features/activity-monitor.ts

@@ -0,0 +1,64 @@
+// activityMonitor feature: subscribes to the server's status SSE
+// (/api/sessions/events via the engine's connectStatusStream) and exposes each
+// 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.
+
+import { connectStatusStream } from "@cplieger/web-terminal-engine";
+import type { SessionStatus } from "@cplieger/web-terminal-engine";
+import type { TerminalFeature, Unsubscribe } from "../kernel/types.js";
+
+const DEFAULT_EVENTS_PATH = "/api/sessions/events";
+
+export interface ActivityMonitorApi {
+  /** Subscribe to every status update (working/idle/input/exited, plus removed).
+   *  Fired for the initial snapshot and each change. */
+  onStatus(cb: (s: SessionStatus) => void): Unsubscribe;
+  /** The last known status for a session, or undefined. */
+  current(id: string): SessionStatus | undefined;
+}
+
+export function activityMonitor(
+  opts: { eventsPath?: string } = {},
+): TerminalFeature<ActivityMonitorApi> {
+  return {
+    name: "activityMonitor",
+    setup() {
+      const path = opts.eventsPath ?? DEFAULT_EVENTS_PATH;
+      const statuses = new Map<string, SessionStatus>();
+      const subs = new Set<(s: SessionStatus) => void>();
+
+      const stream = connectStatusStream(path, {
+        onStatus(s) {
+          if (s.removed) {
+            statuses.delete(s.id);
+          } else {
+            statuses.set(s.id, s);
+          }
+          for (const cb of [...subs]) {
+            cb(s);
+          }
+        },
+      });
+
+      return {
+        api: {
+          onStatus(cb) {
+            subs.add(cb);
+            return () => subs.delete(cb);
+          },
+          current(id) {
+            return statuses.get(id);
+          },
+        },
+        teardown() {
+          stream.close();
+          subs.clear();
+          statuses.clear();
+        },
+      };
+    },
+  };
+}

package/src/features/animations.ts

@@ -0,0 +1,29 @@
+// animations feature: opt-in motion (design sections 13, 22.4). Without it the
+// UI is instant (no transitions); with it, and when the user has not asked for
+// reduced motion, it enables the shared animation vocabulary by marking the
+// terminal root, which the feature stylesheets key their transitions off. It
+// tracks prefers-reduced-motion live so toggling the OS setting takes effect.
+
+import type { TerminalFeature } from "../kernel/types.js";
+
+export function animations(): TerminalFeature {
+  return {
+    name: "animations",
+    setup(ctx) {
+      // The root is the surface's parent (regions + surface are its children).
+      const root = ctx.surface().parentElement;
+      const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+      const apply = (): void => {
+        root?.classList.toggle("wt-animate", !mq.matches);
+      };
+      apply();
+      mq.addEventListener("change", apply);
+      return {
+        teardown() {
+          mq.removeEventListener("change", apply);
+          root?.classList.remove("wt-animate");
+        },
+      };
+    },
+  };
+}

package/src/features/clipboard.ts

@@ -0,0 +1,98 @@
+// clipboard feature: copy/paste helpers, the desktop Ctrl+Shift+C/V shortcuts,
+// and OSC 52 mirroring (design section 22.4). Exposes a typed API so contextMenu
+// can offer Copy/Paste through it (ctx.use). With this feature absent, inbound
+// OSC 52 has no subscriber and is intentionally a no-op.
+
+import type { TerminalFeature } from "../kernel/types.js";
+
+export interface ClipboardApi {
+  /** Write text to the system clipboard (surfaces a toast on success/failure). */
+  copy(text: string): void;
+  /** Read the system clipboard and paste it through the sanitizing funnel. */
+  paste(): void;
+}
+
+export function clipboard(): TerminalFeature<ClipboardApi> {
+  return {
+    name: "clipboard",
+    setup(ctx) {
+      function copy(text: string): void {
+        // navigator.clipboard is undefined outside a secure context (plain-HTTP
+        // non-loopback host, a supported web-terminal-server deployment), where a
+        // property access on it throws synchronously. Feature-detect first.
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- undefined outside secure contexts
+        if (!navigator.clipboard) {
+          ctx.toast("Clipboard unavailable");
+          return;
+        }
+        navigator.clipboard
+          .writeText(text)
+          .then(() => {
+            ctx.toast("Copied");
+          })
+          .catch(() => {
+            ctx.toast("Copy failed");
+          });
+      }
+
+      function paste(): void {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- undefined outside secure contexts
+        if (!navigator.clipboard) {
+          ctx.toast("Clipboard unavailable");
+          return;
+        }
+        navigator.clipboard
+          .readText()
+          .then((text) => {
+            ctx.paste(text);
+          })
+          .catch(() => {
+            ctx.toast("Paste blocked");
+          });
+      }
+
+      // Desktop clipboard shortcuts, handled before the kernel's key mapping so
+      // they take the browser selection/clipboard rather than server-bound bytes.
+      const offKey = ctx.registerKeydown((ev) => {
+        if (ev.ctrlKey && ev.shiftKey && !ev.altKey && !ev.metaKey) {
+          if (ev.code === "KeyC") {
+            const sel = window.getSelection()?.toString();
+            if (sel) {
+              copy(sel);
+            }
+            ev.preventDefault();
+            return true;
+          }
+          if (ev.code === "KeyV") {
+            paste();
+            ev.preventDefault();
+            return true;
+          }
+        }
+        return false;
+      });
+
+      // Inbound OSC 52: an app copied; mirror it to the system clipboard. This
+      // is an async push (not a user gesture), so some browsers reject it and
+      // copy() surfaces "Copy failed".
+      const offClip = ctx.on("wire:clipboard", (text) => {
+        copy(text);
+      });
+
+      // Native copy (e.g. Cmd/Ctrl+C on a selection) feedback toast.
+      const onCopy = (): void => {
+        ctx.toast("Copied");
+      };
+      document.addEventListener("copy", onCopy);
+
+      return {
+        api: { copy, paste },
+        teardown() {
+          offKey();
+          offClip();
+          document.removeEventListener("copy", onCopy);
+        },
+      };
+    },
+  };
+}

package/src/features/connection-banner.ts

@@ -0,0 +1,53 @@
+// connectionBanner feature: renders the kernel's connection state as a visible
+// banner (design sections 22.3, 22.4). The state machine, the loading
+// lifecycle, and the give-up hook are kernel-owned; this feature is a pure
+// renderer subscribing to connection:state. It uses the kernel's single
+// announcer (ctx.announce) rather than spawning its own aria-live region.
+
+import type { ConnState, TerminalFeature } from "../kernel/types.js";
+
+const TEXT: Partial<Record<ConnState, string>> = {
+  connecting: "Reconnecting\u2026",
+  reconnecting: "Reconnecting\u2026",
+  offline: "Offline",
+  restarted: "Server restarted \u2014 recent input may have been lost",
+};
+
+export function connectionBanner(): TerminalFeature {
+  return {
+    name: "connectionBanner",
+    setup(ctx) {
+      const slot = ctx.region("banner", "status");
+      const banner = document.createElement("div");
+      banner.className = "wt-conn-banner";
+      banner.setAttribute("role", "status");
+      slot.appendChild(banner);
+
+      let last: ConnState | null = null;
+      const off = ctx.on("connection:state", (s) => {
+        const text = TEXT[s];
+        if (text !== undefined) {
+          banner.textContent = text;
+          banner.dataset["state"] = s;
+          banner.classList.add("visible");
+          // Announce only on a real change, so a flaky link does not spam the
+          // screen reader with repeated "Reconnecting" for the same state.
+          if (s !== last) {
+            ctx.announce(text);
+          }
+        } else {
+          banner.classList.remove("visible");
+          banner.textContent = "";
+        }
+        last = s;
+      });
+
+      return {
+        teardown() {
+          off();
+          banner.remove();
+        },
+      };
+    },
+  };
+}

package/src/features/context-menu.ts

@@ -0,0 +1,207 @@
+// contextMenu feature: the right-click / long-press menu (Copy, Select All,
+// Paste) rendered into the overlay region (design section 22.4). Copy/Paste are
+// offered only when the clipboard feature is present (ctx.use), routing Paste
+// through the kernel's sanitizing funnel. Escape-to-close goes through the
+// kernel keydown intercept; outside-click and long-press are surface gestures.
+//
+// Touch long-press opens this menu on every touch platform, iOS included. The
+// terminal's keyboard target is a 1x1, pointer-events:none textarea, so iOS's
+// own long-press callout never lands on an editable field and no native "Paste"
+// ever appears (the reason tap-and-hold-to-paste felt broken). This menu is
+// therefore the paste path on touch; Paste reads the system clipboard via the
+// Clipboard API, which needs a secure context, so serve vibecli over HTTPS for
+// touch paste.
+
+import type { TerminalFeature } from "../kernel/types.js";
+import type { ClipboardApi } from "./clipboard.js";
+
+const LONG_PRESS_MS = 500;
+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;
+
+export interface ContextMenuOptions {
+  /** The clipboard feature value, so the menu can offer Copy/Paste through its
+   *  API (ctx.use). Omitted: the menu shows only Select All. */
+  clipboard?: TerminalFeature<ClipboardApi>;
+}
+
+export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
+  return {
+    name: "contextMenu",
+    setup(ctx) {
+      const surface = ctx.surface();
+      const menu = document.createElement("div");
+      menu.className = "wt-ctx-menu";
+      ctx.region("overlay", "menu").appendChild(menu);
+
+      let longPressTimer = 0;
+      let longPressOrigin = { x: 0, y: 0 };
+
+      const clip = (): ClipboardApi | undefined =>
+        opts.clipboard ? ctx.use(opts.clipboard) : undefined;
+
+      function focusInput(): void {
+        surface.querySelector<HTMLElement>(".term-input")?.focus({ preventScroll: true });
+      }
+
+      function hide(): void {
+        const refocus = menu.contains(document.activeElement);
+        menu.classList.remove("visible");
+        menu.replaceChildren();
+        if (refocus) {
+          focusInput();
+        }
+      }
+
+      function addButton(label: string, onClick: () => void): void {
+        const b = document.createElement("button");
+        b.type = "button";
+        b.textContent = label;
+        b.addEventListener("click", () => {
+          onClick();
+          hide();
+        });
+        menu.appendChild(b);
+      }
+
+      function show(x: number, y: number): void {
+        hide();
+        const clipboard = clip();
+        const sel = window.getSelection()?.toString();
+        if (sel) {
+          addButton("Copy", () => {
+            clipboard?.copy(sel);
+          });
+        }
+        addButton("Select All", () => {
+          const s = window.getSelection();
+          const output = surface.querySelector(".term-output");
+          if (s && output) {
+            s.selectAllChildren(output);
+          }
+        });
+        // Paste needs the clipboard feature. Offered on touch too (see the header
+        // note): the hidden textarea means iOS's native paste callout never
+        // appears, so this is the paste path there.
+        if (clipboard) {
+          addButton("Paste", () => {
+            clipboard.paste();
+          });
+        }
+        if (menu.childElementCount === 0) {
+          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.
+        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`;
+      }
+
+      const onContextMenu = (e: MouseEvent): void => {
+        e.preventDefault();
+        show(e.clientX, e.clientY);
+      };
+      surface.addEventListener("contextmenu", onContextMenu);
+
+      // Escape closes the menu without also sending ESC to the PTY.
+      const offKey = ctx.registerKeydown((ev) => {
+        if (ev.key === "Escape" && menu.classList.contains("visible")) {
+          ev.preventDefault();
+          hide();
+          return true;
+        }
+        return false;
+      });
+
+      const onDocClick = (): void => {
+        hide();
+      };
+      document.addEventListener("click", onDocClick);
+
+      // Long-press opens the menu on touch, all platforms (see the header note).
+      const clearLongPress = (): void => {
+        if (longPressTimer) {
+          clearTimeout(longPressTimer);
+          longPressTimer = 0;
+        }
+      };
+      const onTouchStart = (e: TouchEvent): void => {
+        if (e.touches.length !== 1) {
+          clearLongPress();
+          return;
+        }
+        const t = e.touches[0];
+        if (!t) {
+          return;
+        }
+        longPressOrigin = { x: t.clientX, y: t.clientY };
+        longPressTimer = window.setTimeout(() => {
+          longPressTimer = 0;
+          show(longPressOrigin.x, longPressOrigin.y);
+        }, LONG_PRESS_MS);
+      };
+      const onTouchMove = (e: TouchEvent): void => {
+        if (!longPressTimer || e.touches.length !== 1) {
+          return;
+        }
+        const t = e.touches[0];
+        if (!t) {
+          return;
+        }
+        const dx = t.clientX - longPressOrigin.x;
+        const dy = t.clientY - longPressOrigin.y;
+        if (dx * dx + dy * dy > LONG_PRESS_MOVE_PX * LONG_PRESS_MOVE_PX) {
+          clearLongPress();
+        }
+      };
+      surface.addEventListener("touchstart", onTouchStart, { passive: true });
+      surface.addEventListener("touchmove", onTouchMove, { passive: true });
+      surface.addEventListener("touchend", clearLongPress, { passive: true });
+      surface.addEventListener("touchcancel", clearLongPress, { passive: true });
+
+      return {
+        teardown() {
+          clearLongPress();
+          offKey();
+          surface.removeEventListener("contextmenu", onContextMenu);
+          document.removeEventListener("click", onDocClick);
+          surface.removeEventListener("touchstart", onTouchStart);
+          surface.removeEventListener("touchmove", onTouchMove);
+          surface.removeEventListener("touchend", clearLongPress);
+          surface.removeEventListener("touchcancel", clearLongPress);
+          menu.remove();
+        },
+      };
+    },
+  };
+}

package/src/features/dom.ts

@@ -0,0 +1,15 @@
+// Small shared helper for features: build a chrome element from a static,
+// trusted HTML string (icons, buttons) via a <template> clone, the same pattern
+// the kernel uses for its core subtree. No interpolation ever passes through
+// here, so it carries no injection surface.
+
+/** Parse a static HTML string and return its first element. */
+export function fromHTML(html: string): HTMLElement {
+  const tpl = document.createElement("template");
+  tpl.innerHTML = html.trim();
+  const el = tpl.content.firstElementChild;
+  if (!(el instanceof HTMLElement)) {
+    throw new Error("web-terminal-ui: fromHTML produced no element");
+  }
+  return el;
+}

package/src/features/mobile-toolbar.ts

@@ -0,0 +1,82 @@
+// 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
+// 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 type { TerminalFeature } from "../kernel/types.js";
+import { fromHTML } from "./dom.js";
+
+const { bindMobileToolbar } = keyboard;
+
+// The key grid, without the scroll-to-bottom button (that is the scrollToBottom
+// feature, composed into the same region's "scroll" slot).
+const TOOLBAR_HTML = `
+<div class="key-toolbar collapsed no-transition" aria-label="Navigation keys" role="toolbar">
+  <button type="button" id="kb-toggle" class="kb-toggle" aria-label="Toggle key toolbar"><svg class="icon-hamburger" viewBox="0 0 24 24"><line x1="4" y1="6" x2="20" y2="6"/><line x1="4" y1="12" x2="20" y2="12"/><line x1="4" y1="18" x2="20" y2="18"/></svg><svg class="icon-close" viewBox="0 0 24 24"><line x1="6" y1="6" x2="18" y2="18"/><line x1="18" y1="6" x2="6" y2="18"/></svg></button>
+  <button type="button" id="kb-tab" class="kb-key kb-r1c1" aria-label="Tab">TAB</button>
+  <button type="button" id="kb-esc" class="kb-key kb-r1c2" aria-label="Escape">ESC</button>
+  <button type="button" id="kb-up" class="kb-key kb-r1c3" aria-label="Up"><svg viewBox="0 0 24 24"><polyline points="6 15 12 9 18 15"/></svg></button>
+  <button type="button" id="kb-enter" class="kb-key kb-r1c4" aria-label="Enter"><svg viewBox="0 0 24 24"><polyline points="9 10 4 15 9 20"/><polyline points="20 4 20 15 4 15"/></svg></button>
+  <button type="button" id="kb-ctrl" class="kb-key kb-r2c1" aria-label="Sticky Ctrl modifier" aria-pressed="false">CTRL</button>
+  <button type="button" id="kb-left" class="kb-key kb-r2c2" aria-label="Left"><svg viewBox="0 0 24 24"><polyline points="15 6 9 12 15 18"/></svg></button>
+  <button type="button" id="kb-down" class="kb-key kb-r2c3" aria-label="Down"><svg viewBox="0 0 24 24"><polyline points="6 9 12 15 18 9"/></svg></button>
+  <button type="button" id="kb-right" class="kb-key kb-r2c4" aria-label="Right"><svg viewBox="0 0 24 24"><polyline points="9 6 15 12 9 18"/></svg></button>
+</div>`;
+
+export function mobileToolbar(): TerminalFeature {
+  return {
+    name: "mobileToolbar",
+    setup(ctx) {
+      const encoder = new TextEncoder();
+      const decoder = new TextDecoder();
+      const toolbar = fromHTML(TOOLBAR_HTML);
+      ctx.region("bottom-inset-end", "keys").appendChild(toolbar);
+
+      const ctrl = bindMobileToolbar({
+        toolbar,
+        send: (bytes) => {
+          ctx.send(encoder.encode(bytes));
+        },
+      });
+
+      // Sticky-Ctrl as an outbound-byte transform: when armed, a single typed
+      // character is rewritten to its Ctrl byte (and disarms). The toolbar's own
+      // arrow/Tab/Enter/Esc sends disarm before sending, so they pass through.
+      const offTransform = ctx.registerInputTransform((bytes) => {
+        if (!ctrl.isCtrlArmed()) {
+          return bytes;
+        }
+        const text = decoder.decode(bytes);
+        const mapped = ctrl.applyStickyCtrl(text);
+        return mapped === text ? bytes : encoder.encode(mapped);
+      });
+
+      // Prime the slide transition off for the first paint (no initial flash),
+      // then enable it after two frames.
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          toolbar.classList.remove("no-transition");
+        });
+      });
+
+      return {
+        onDetach() {
+          // A tab switch disarms a latched sticky-Ctrl so a pending Ctrl does
+          // not fire against the incoming session (e.g. an accidental Ctrl+C to
+          // the wrong agent, design 5.1 / ui-ux review D).
+          if (ctrl.isCtrlArmed()) {
+            ctrl.setCtrlArmed(false);
+          }
+        },
+        teardown() {
+          offTransform();
+          ctrl.dispose();
+          toolbar.remove();
+        },
+      };
+    },
+  };
+}

package/src/features/predictive-echo.ts

@@ -0,0 +1,63 @@
+// predictiveEcho feature: Mosh-style local echo (design section 22.4). Wires the
+// predict.ts mini-VT to the kernel input funnel: it advances a predicted cursor
+// on accepted input (an input observer) and owns the col-0 backspace brake (an
+// input transform that drops a lone DEL at the true origin, since the predicted
+// cursor is the authoritative position for that decision). It re-pushes the
+// predicted-cursor overlay on prediction changes and after each render flush.
+
+import * as predict from "../predict.js";
+import type { TerminalFeature } from "../kernel/types.js";
+
+export function predictiveEcho(): TerminalFeature {
+  return {
+    name: "predictiveEcho",
+    setup(ctx) {
+      function push(): void {
+        const p = predict.get();
+        ctx.render.setPredictedCursor(p.row, p.col, p.active);
+      }
+      predict.subscribe(push);
+
+      // Col-0 backspace brake: suppress a lone DEL at the true origin (row 0,
+      // col 0) so held-Backspace on an empty line does not flood the server.
+      // Owned here because the predicted cursor is the position it keys off.
+      const offTransform = ctx.registerInputTransform((bytes) => {
+        const p = predict.get();
+        if (bytes.length === 1 && bytes[0] === 0x7f && p.active && p.row === 0 && p.col === 0) {
+          return new Uint8Array(0);
+        }
+        return bytes;
+      });
+      const offObserver = ctx.registerInputObserver((bytes) => {
+        predict.applyInput(bytes);
+      });
+
+      const offCursor = ctx.on("render:cursor", () => {
+        push();
+      });
+      const offScreen = ctx.on("wire:screen", (msg) => {
+        const sz = ctx.session.size();
+        predict.setDimensions(sz.cols, sz.rows);
+        predict.onScreenFrame(msg.cursor[0], msg.cursor[1], msg.cursorHidden);
+      });
+      const offState = ctx.on("connection:state", (s) => {
+        if (s === "restarted") {
+          predict.reset();
+        }
+      });
+
+      return {
+        teardown() {
+          offTransform();
+          offObserver();
+          offCursor();
+          offScreen();
+          offState();
+          // Hide the overlay and drop stale prediction state.
+          predict.reset();
+          ctx.render.setPredictedCursor(0, 0, false);
+        },
+      };
+    },
+  };
+}

package/src/features/scroll-to-bottom.ts

@@ -0,0 +1,49 @@
+// scrollToBottom feature: a scroll-to-bottom control in the thumb-zone region,
+// shown only while the user has scrolled up (design section 22.4). The
+// scroll-state signal comes from the kernel's scroll:state event (the kernel
+// owns scroll.init); this feature just renders the affordance and drives
+// scroll.scrollToBottom.
+
+import type { TerminalFeature } from "../kernel/types.js";
+import { fromHTML } from "./dom.js";
+
+const BUTTON_HTML = `
+<button type="button" class="wt-btn wt-scroll-bottom" aria-label="Scroll to bottom">
+  <svg viewBox="0 0 24 24" aria-hidden="true"><path fill="none" d="M7 13l5 5 5-5M7 6l5 5 5-5"/></svg>
+</button>`;
+
+export function scrollToBottom(): TerminalFeature {
+  return {
+    name: "scrollToBottom",
+    setup(ctx) {
+      const slot = ctx.region("bottom-inset-end", "scroll");
+      const btn = fromHTML(BUTTON_HTML);
+      slot.appendChild(btn);
+
+      // pointerdown (like the toolbar keys) so touch devices show press
+      // feedback; preventDefault keeps focus on the terminal. click is kept for
+      // keyboard activation. scrollToBottom is idempotent, so the pair is safe.
+      const onDown = (e: PointerEvent): void => {
+        e.preventDefault();
+        ctx.scroll.scrollToBottom();
+      };
+      const onClick = (): void => {
+        ctx.scroll.scrollToBottom();
+      };
+      btn.addEventListener("pointerdown", onDown);
+      btn.addEventListener("click", onClick);
+
+      // Visible only while scrolled up; the region reflects it via a class.
+      const off = ctx.on("scroll:state", ({ scrolledUp }) => {
+        slot.classList.toggle("scrolled-up", scrolledUp);
+      });
+
+      return {
+        teardown() {
+          off();
+          btn.remove();
+        },
+      };
+    },
+  };
+}