@cplieger/web-terminal-ui 3.0.3 → 3.1.0

package/css/07-animations.css

@@ -0,0 +1,102 @@
+/* ===== Animations (animations feature) =====
+   Every bit of motion in the UI lives here, gated on the root .wt-animate class
+   that the animations feature sets only when the OS is not in reduced-motion.
+   Without the feature (or under prefers-reduced-motion) the UI is instant: base
+   rules in 03-06 carry the resting state, and these rules add the transitions
+   and keyframes on top. Keeping motion in one file is the design-system seam for
+   "does this UI animate, and how". */
+
+/* Fade transient surfaces in/out (display allow-discrete plays the fade before
+   the discrete display:none on hide). */
+.wt-animate .wt-toast,
+.wt-animate .wt-conn-banner,
+.wt-animate .wt-scroll-bottom,
+.wt-animate .wt-ctx-menu,
+.wt-animate .wt-tab-menu {
+  transition:
+    opacity var(--dur-standard) var(--ease-standard),
+    display var(--dur-standard) allow-discrete;
+}
+
+/* Tab chrome micro-transitions (hover/active color shifts). */
+.wt-animate .wt-tab,
+.wt-animate .wt-tab-close,
+.wt-animate .wt-tab-new {
+  transition:
+    background-color var(--dur-micro) var(--ease-standard),
+    color var(--dur-micro) var(--ease-standard);
+}
+
+/* New tab enters with a fade + scale-in. Only runtime-added tabs get
+   .wt-tab-enter (the tabs feature's `started` gate). A closing tab is removed
+   immediately with no exit animation, so the strip reflows in one frame (a
+   delayed exit made the "+" teleport and put a last-tab replacement in the wrong
+   slot). scale() is a transform, so the enter never shifts the "+". */
+.wt-animate .wt-tab-enter {
+  animation: wt-tab-in var(--dur-enter) var(--ease-enter);
+}
+
+@keyframes wt-tab-in {
+  from {
+    opacity: 0;
+    transform: scale(0.82);
+  }
+}
+
+/* Tab list expand/collapse: the mobile bar grows upward to reveal the other
+   tabs and shrinks back. max-height and the vertical padding animate together (0
+   to the expanded values and back), so the whole tray opens/closes as one motion
+   — animating only max-height let the padding snap away instantly at the start
+   of a collapse (a choppy, two-step close). The tabs feature clears the rows
+   after the collapse. */
+.wt-animate .wt-switcher-list {
+  transition:
+    max-height var(--dur-enter) var(--ease-standard),
+    padding var(--dur-enter) var(--ease-standard);
+}
+
+/* When the tab list expands, the keyboard button collapses to zero width and
+   fades (the key grid is closed in JS); the active row flex-grows into the freed
+   space in lockstep as the button's width animates. */
+.wt-animate .wt-switcher-kb {
+  transition:
+    width var(--dur-enter) var(--ease-standard),
+    margin var(--dur-enter) var(--ease-standard),
+    opacity var(--dur-standard) var(--ease-standard);
+}
+
+/* Switch motion: a subtle content fade on switch, so the cache-first repaint
+   reads as a change rather than a flicker. A swipe additionally slides the
+   content in from the swipe's direction (next from the right, prev from the
+   left, WS5). */
+.wt-animate .term.wt-switching .term-output {
+  animation: wt-switch-in var(--dur-standard) var(--ease-standard);
+}
+
+.wt-animate .term.wt-switching-next .term-output {
+  animation: wt-switch-next var(--dur-standard) var(--ease-standard);
+}
+
+.wt-animate .term.wt-switching-prev .term-output {
+  animation: wt-switch-prev var(--dur-standard) var(--ease-standard);
+}
+
+@keyframes wt-switch-in {
+  from {
+    opacity: 0.55;
+  }
+}
+
+@keyframes wt-switch-next {
+  from {
+    opacity: 0.3;
+    transform: translateX(18%);
+  }
+}
+
+@keyframes wt-switch-prev {
+  from {
+    opacity: 0.3;
+    transform: translateX(-18%);
+  }
+}

package/css/MANIFEST

@@ -1,6 +1,12 @@
 # web-terminal-ui CSS bundle manifest
 # Files concatenated in declared order to produce the served style.css.
+# The order IS the cascade: tokens + reset + terminal core, then the v3 design
+# system (shared primitives, then per-feature chrome), then all motion last.
 00-tokens.css
 01-reset.css
 02-app.css
-03-v3.css
+03-primitives.css
+04-feedback.css
+05-tabs.css
+06-mobile.css
+07-animations.css

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "3.0.3",
+  "version": "3.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",
@@ -34,7 +34,7 @@
     "eslint": "10.6.0",
     "fast-check": "4.8.0",
     "happy-dom": "20.10.6",
-    "html-validate": "11.5.3",
+    "html-validate": "11.5.5",
     "knip": "6.23.0",
     "prettier": "3.9.4",
     "stylelint": "17.14.0",

package/src/features/clipboard.ts

@@ -54,6 +54,16 @@ export function clipboard(): TerminalFeature<ClipboardApi> {
       // 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) => {
+        // Plain Ctrl+V: let the browser's NATIVE paste event flow into the
+        // hidden textarea (the kernel's insertFromPaste path sends it through the
+        // sanitizing funnel). Consuming the key WITHOUT preventDefault stops the
+        // kernel mapping Ctrl+V to \x16 while leaving the native paste intact — so
+        // no navigator.clipboard.readText(), hence no Firefox clipboard-read
+        // popup. (Cmd+V on macOS already pastes natively and never reached the
+        // \x16 mapping.)
+        if (ev.ctrlKey && !ev.shiftKey && !ev.altKey && !ev.metaKey && ev.code === "KeyV") {
+          return true; // do NOT preventDefault — the browser pastes natively
+        }
         if (ev.ctrlKey && ev.shiftKey && !ev.altKey && !ev.metaKey) {
           if (ev.code === "KeyC") {
             const sel = window.getSelection()?.toString();

package/src/features/connection-banner.ts

@@ -10,7 +10,7 @@ const TEXT: Partial<Record<ConnState, string>> = {
   connecting: "Reconnecting\u2026",
   reconnecting: "Reconnecting\u2026",
   offline: "Offline",
-  restarted: "Server restarted \u2014 recent input may have been lost",
+  restarted: "Server restarted; recent input may be lost",
 };
 
 export function connectionBanner(): TerminalFeature {

package/src/features/context-menu.ts

@@ -2,26 +2,50 @@
 // 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.
+// kernel keydown intercept; outside-click is a document gesture.
 //
-// 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.
+// TOUCH MODEL (best-practice, cross-platform iOS + Android):
+// The terminal output is the browser's native text-selection surface, so a
+// touch long-press ON TEXT is left to the platform: it selects a word and shows
+// the OS copy callout. We do NOT stack a custom menu on that (it fought native
+// selection and, since the long-press is immediately followed by a touchend,
+// closed the instant the finger lifted). The custom menu opens on touch ONLY
+// when the long-press selected nothing (empty space) — its job there is Paste,
+// which the native callout cannot offer because our keyboard target is a 1x1,
+// pointer-events:none textarea (no editable surface under the finger for the OS
+// paste item). Paste reads the clipboard via the Clipboard API (secure context
+// required, so serve over HTTPS for touch paste). Desktop is the ordinary
+// right-click menu (Copy / Select All / Paste).
+//
+// Deciding "did the long-press select text?" is the crux — a naive
+// getSelection() read at a fixed delay races the native selection and caused the
+// reported flakiness (sometimes native, sometimes custom, sometimes both). So we
+// TRACK whether a selection is made during THIS press via a selectionchange
+// listener armed only while a touch is down: the moment one appears we cancel
+// the pending menu and, if it already opened, close it — native always wins over
+// text. The platforms deliver the long-press differently: iOS fires NO
+// contextmenu (a hold timer detects it), Android DOES (we handle it and
+// preventDefault it when showing our own, so Android's native menu doesn't also
+// appear — the "both menus" case). Both paths are gated by the same selection
+// check, so the outcome is consistent across platforms.
 
 import type { TerminalFeature } from "../kernel/types.js";
 import type { ClipboardApi } from "./clipboard.js";
 
-const LONG_PRESS_MS = 500;
+// 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;
+// 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).
+const SWALLOW_MS = 350;
 
 export interface ContextMenuOptions {
   /** The clipboard feature value, so the menu can offer Copy/Paste through its
@@ -40,6 +64,18 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
 
       let longPressTimer = 0;
       let longPressOrigin = { x: 0, y: 0 };
+      // The device that started the current interaction: contextmenu fires on
+      // desktop right-click AND on Android long-press, so its handler branches
+      // on this to tell them apart.
+      let lastPointerType = "mouse";
+      // Timestamp until which a document click is swallowed (see SWALLOW_MS).
+      let swallowUntil = 0;
+      // A native selection was made during the current touch press (tracked via
+      // selectionchange). Gates the touch menu: a selected long-press belongs to
+      // the native callout, an empty one to us (Paste).
+      let pressSelectedText = false;
+      // A touch press is in progress, so selectionchange is relevant (armed).
+      let touchActive = false;
 
       const clip = (): ClipboardApi | undefined =>
         opts.clipboard ? ctx.use(opts.clipboard) : undefined;
@@ -48,45 +84,74 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
         surface.querySelector<HTMLElement>(".term-input")?.focus({ preventScroll: true });
       }
 
-      function hide(): void {
-        const refocus = menu.contains(document.activeElement);
+      const clearLongPress = (): void => {
+        if (longPressTimer) {
+          clearTimeout(longPressTimer);
+          longPressTimer = 0;
+        }
+      };
+
+      // True when text is (or just got) selected, so the OS callout owns Copy and
+      // our menu stays out of the way. pressSelectedText catches a native
+      // selection the instant it happens (selectionchange), avoiding a race with
+      // a fixed-delay read; the live check is the fallback for when selectionchange
+      // did not arm (a desktop right-click on an existing selection).
+      const hasNativeSelection = (): boolean => {
+        if (pressSelectedText) {
+          return true;
+        }
+        const s = window.getSelection();
+        return s !== null && !s.isCollapsed && s.toString().length > 0;
+      };
+
+      function hide(refocus = true): void {
+        const shouldRefocus = refocus && menu.contains(document.activeElement);
         menu.classList.remove("visible");
         menu.replaceChildren();
-        if (refocus) {
+        if (shouldRefocus) {
           focusInput();
         }
       }
 
-      function addButton(label: string, onClick: () => void): void {
+      // refocus=false suppresses the return-focus-to-input step: Select All must
+      // NOT refocus the textarea, or Firefox collapses the just-made selection
+      // when focus leaves the output.
+      function addButton(label: string, onClick: () => void, refocus = true): void {
         const b = document.createElement("button");
         b.type = "button";
         b.textContent = label;
         b.addEventListener("click", () => {
           onClick();
-          hide();
+          hide(refocus);
         });
         menu.appendChild(b);
       }
 
-      function show(x: number, y: number): void {
+      function show(x: number, y: number, touch: boolean): 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);
+        // On touch we only reach here over empty space (no selection), so Copy
+        // has nothing to act on; the native callout owns Copy over selected
+        // text. On desktop, offer Copy when there is a selection.
+        if (!touch) {
+          const sel = window.getSelection()?.toString();
+          if (sel) {
+            addButton("Copy", () => {
+              clipboard?.copy(sel);
+            });
           }
-        });
-        // 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.
+        }
+        addButton(
+          "Select All",
+          () => {
+            const s = window.getSelection();
+            const output = surface.querySelector(".term-output");
+            if (s && output) {
+              s.selectAllChildren(output);
+            }
+          },
+          false,
+        );
         if (clipboard) {
           addButton("Paste", () => {
             clipboard.paste();
@@ -125,14 +190,61 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
         );
         menu.style.left = `${String(left)}px`;
         menu.style.top = `${String(top)}px`;
+        // 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) {
+          swallowUntil = performance.now() + SWALLOW_MS;
+        }
       }
 
+      const onPointerDown = (e: PointerEvent): void => {
+        lastPointerType = e.pointerType;
+      };
+      surface.addEventListener("pointerdown", onPointerDown, { passive: true });
+
+      // contextmenu fires on desktop right-click AND on Android long-press (iOS
+      // fires none). Desktop: always our menu. Touch (Android): our menu only
+      // when nothing is selected — and preventDefault so Android's native menu
+      // does not ALSO appear (the "both menus" bug); with a selection, defer to
+      // the native selection toolbar (don't preventDefault).
       const onContextMenu = (e: MouseEvent): void => {
+        if (lastPointerType !== "touch") {
+          e.preventDefault();
+          show(e.clientX, e.clientY, false);
+          return;
+        }
+        if (menu.classList.contains("visible")) {
+          e.preventDefault(); // the hold timer already opened it; just suppress native
+          return;
+        }
+        if (hasNativeSelection()) {
+          return; // native selection toolbar owns Copy over text
+        }
         e.preventDefault();
-        show(e.clientX, e.clientY);
+        clearLongPress();
+        show(e.clientX, e.clientY, true);
       };
       surface.addEventListener("contextmenu", onContextMenu);
 
+      // Track a native selection made during the current touch press, so the
+      // long-press decision never races a fixed-delay read. Armed only while a
+      // touch is down (touchActive) so unrelated selection changes (Select All,
+      // typing) don't trip it.
+      const onSelectionChange = (): void => {
+        if (!touchActive) {
+          return;
+        }
+        const s = window.getSelection();
+        if (s && !s.isCollapsed && s.toString().length > 0) {
+          pressSelectedText = true;
+          clearLongPress(); // native selection is happening; don't open our menu
+          if (menu.classList.contains("visible")) {
+            hide(false); // a native selection appeared after we opened; native wins
+          }
+        }
+      };
+      document.addEventListener("selectionchange", onSelectionChange);
+
       // Escape closes the menu without also sending ESC to the PTY.
       const offKey = ctx.registerKeydown((ev) => {
         if (ev.key === "Escape" && menu.classList.contains("visible")) {
@@ -144,17 +256,26 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
       });
 
       const onDocClick = (): void => {
+        // Swallow the release click of the long-press that just opened the menu.
+        if (performance.now() < swallowUntil) {
+          return;
+        }
         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;
+      // A right-click outside the terminal surface (a tab, its menu, elsewhere,
+      // or a native browser menu) dismisses this menu. A right-click on the
+      // surface is handled by onContextMenu (which reopens it) and fires first.
+      const onDocContextMenu = (e: MouseEvent): void => {
+        if (!surface.contains(e.target as Node)) {
+          hide();
         }
       };
+      document.addEventListener("contextmenu", onDocContextMenu);
+
+      // Touch long-press — the iOS path (iOS fires no contextmenu). Open the menu
+      // only when nothing got natively selected during the hold; if a word/line
+      // was selected, the OS callout owns it and we stay out.
       const onTouchStart = (e: TouchEvent): void => {
         if (e.touches.length !== 1) {
           clearLongPress();
@@ -164,10 +285,14 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
         if (!t) {
           return;
         }
+        touchActive = true;
+        pressSelectedText = false;
         longPressOrigin = { x: t.clientX, y: t.clientY };
         longPressTimer = window.setTimeout(() => {
           longPressTimer = 0;
-          show(longPressOrigin.x, longPressOrigin.y);
+          if (!hasNativeSelection()) {
+            show(longPressOrigin.x, longPressOrigin.y, true);
+          }
         }, LONG_PRESS_MS);
       };
       const onTouchMove = (e: TouchEvent): void => {
@@ -184,21 +309,28 @@ export function contextMenu(opts: ContextMenuOptions = {}): TerminalFeature {
           clearLongPress();
         }
       };
+      const onTouchEnd = (): void => {
+        clearLongPress();
+        touchActive = false;
+      };
       surface.addEventListener("touchstart", onTouchStart, { passive: true });
       surface.addEventListener("touchmove", onTouchMove, { passive: true });
-      surface.addEventListener("touchend", clearLongPress, { passive: true });
-      surface.addEventListener("touchcancel", clearLongPress, { passive: true });
+      surface.addEventListener("touchend", onTouchEnd, { passive: true });
+      surface.addEventListener("touchcancel", onTouchEnd, { passive: true });
 
       return {
         teardown() {
           clearLongPress();
           offKey();
+          surface.removeEventListener("pointerdown", onPointerDown);
           surface.removeEventListener("contextmenu", onContextMenu);
+          document.removeEventListener("selectionchange", onSelectionChange);
           document.removeEventListener("click", onDocClick);
+          document.removeEventListener("contextmenu", onDocContextMenu);
           surface.removeEventListener("touchstart", onTouchStart);
           surface.removeEventListener("touchmove", onTouchMove);
-          surface.removeEventListener("touchend", clearLongPress);
-          surface.removeEventListener("touchcancel", clearLongPress);
+          surface.removeEventListener("touchend", onTouchEnd);
+          surface.removeEventListener("touchcancel", onTouchEnd);
           menu.remove();
         },
       };

package/src/features/mobile-toolbar.ts

@@ -11,6 +11,31 @@ import { fromHTML } from "./dom.js";
 
 const { bindMobileToolbar } = keyboard;
 
+/** 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. */
+export interface MobileToolbarApi {
+  /** Show/hide the key grid (flips the toolbar's collapsed state). */
+  toggle(): void;
+  /** Whether the key grid is currently open. */
+  isOpen(): boolean;
+  /** Whether sticky-Ctrl is currently armed (a pending Ctrl press). */
+  isCtrlArmed(): boolean;
+  /** Subscribe to sticky-Ctrl arm/disarm; returns an unsubscribe. Lets a peer
+   *  (the tab bar's keyboard button) surface the pending modifier even while the
+   *  key grid — and its own Ctrl button — is closed. */
+  onCtrlArmedChange(fn: (armed: boolean) => void): () => void;
+}
+
+/** Options for the mobileToolbar feature. */
+export interface MobileToolbarOptions {
+  /** When true, the toolbar hides its own top-right toggle button and positions
+   *  the key grid to open above the mobile tab bar. The grid is then driven
+   *  externally through the returned API (tabs renders a keyboard button in the
+   *  switcher bar and calls toggle()). The tabbed presets set this; presetTouch
+   *  leaves it off and keeps the self-contained top-right toggle. */
+  externalToggle?: boolean;
+}
+
 // 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 = `
@@ -26,20 +51,34 @@ const TOOLBAR_HTML = `
   <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 {
+export function mobileToolbar(opts: MobileToolbarOptions = {}): TerminalFeature<MobileToolbarApi> {
   return {
     name: "mobileToolbar",
     setup(ctx) {
       const encoder = new TextEncoder();
       const decoder = new TextDecoder();
       const toolbar = fromHTML(TOOLBAR_HTML);
+      // Externally-driven mode (the tabbed presets): the toolbar hides its own
+      // toggle and opens the grid above the mobile tab bar; tabs drives it via
+      // the returned API. The class gates both behaviors in CSS.
+      if (opts.externalToggle) {
+        toolbar.classList.add("wt-toolbar-external");
+      }
       ctx.region("bottom-inset-end", "keys").appendChild(toolbar);
 
+      // Fan sticky-Ctrl arm/disarm out to subscribers (the tab bar's keyboard
+      // button mirrors it, so a pending Ctrl is visible with the grid closed).
+      const armedListeners = new Set<(armed: boolean) => void>();
       const ctrl = bindMobileToolbar({
         toolbar,
         send: (bytes) => {
           ctx.send(encoder.encode(bytes));
         },
+        onCtrlChange: (armed) => {
+          for (const fn of [...armedListeners]) {
+            fn(armed);
+          }
+        },
       });
 
       // Sticky-Ctrl as an outbound-byte transform: when armed, a single typed
@@ -63,6 +102,24 @@ export function mobileToolbar(): TerminalFeature {
       });
 
       return {
+        // Expose grid open/close so a peer (tabs) can drive it from the tab bar.
+        // Toggling the same `.collapsed` class the engine's own kb-toggle flips
+        // keeps a single source of truth for the grid's visibility.
+        api: {
+          toggle() {
+            toolbar.classList.toggle("collapsed");
+          },
+          isOpen() {
+            return !toolbar.classList.contains("collapsed");
+          },
+          isCtrlArmed() {
+            return ctrl.isCtrlArmed();
+          },
+          onCtrlArmedChange(fn) {
+            armedListeners.add(fn);
+            return () => armedListeners.delete(fn);
+          },
+        },
         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
@@ -73,6 +130,7 @@ export function mobileToolbar(): TerminalFeature {
         },
         teardown() {
           offTransform();
+          armedListeners.clear();
           ctrl.dispose();
           toolbar.remove();
         },

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

@@ -20,18 +20,34 @@ export function scrollToBottom(): TerminalFeature {
       const btn = fromHTML(BUTTON_HTML);
       slot.appendChild(btn);
 
+      // Jump to the bottom. With motion allowed, smooth-scroll the surface so
+      // the jump is animated rather than an instant teleport; the engine's
+      // scroll controller re-derives its follow state from the scroll position
+      // (its listener sees the animation land at the bottom), so following
+      // re-engages with no programmatic flag, consistent with the engine's
+      // position-only model. Under prefers-reduced-motion, fall back to the
+      // engine's instant scrollToBottom (which re-engages following synchronously).
+      const jump = (): void => {
+        const reduce =
+          typeof window.matchMedia === "function" &&
+          window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+        if (reduce) {
+          ctx.scroll.scrollToBottom();
+          return;
+        }
+        const surface = ctx.surface();
+        surface.scrollTo({ top: surface.scrollHeight, behavior: "smooth" });
+      };
+
       // 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.
+      // keyboard activation. jump is idempotent, so the pair is safe.
       const onDown = (e: PointerEvent): void => {
         e.preventDefault();
-        ctx.scroll.scrollToBottom();
-      };
-      const onClick = (): void => {
-        ctx.scroll.scrollToBottom();
+        jump();
       };
       btn.addEventListener("pointerdown", onDown);
-      btn.addEventListener("click", onClick);
+      btn.addEventListener("click", jump);
 
       // Visible only while scrolled up; the region reflects it via a class.
       const off = ctx.on("scroll:state", ({ scrolledUp }) => {