@cplieger/web-terminal-ui 2.0.0 → 2.1.1

package/css/00-tokens.css

@@ -30,4 +30,5 @@
   --ease-exit: cubic-bezier(0.4, 0, 1, 1);
   --blur: blur(8px);
   --safe-top: env(safe-area-inset-top, 0px);
+  --safe-bottom: env(safe-area-inset-bottom, 0px);
 }

package/css/02-app.css

@@ -48,11 +48,10 @@
    client-side cap or a server-reported resume gap). A quiet, centered,
    non-selectable divider so the user knows scrollback doesn't go further up. */
 .term-trim-marker {
-  color: color-mix(in oklch, var(--text) 45%, transparent);
+  color: color-mix(in oklch, var(--text) 60%, transparent);
   font-size: 0.6875rem;
   text-align: center;
   padding: 2px 0;
-  opacity: 0.7;
   user-select: none;
   font-family: var(--font-ui);
 }
@@ -141,10 +140,11 @@
   display: block;
 }
 
-/* Connection-state banner: floats top-center with a subtle backdrop
-   blur. Hidden until status.ts sets `.visible`. Distinct from the
-   `.pill` family because it wants to span across the full top center
-   visually rather than dock to a corner. */
+/* Connection-state banner: bottom-center on touch (lifted above the
+   virtual keyboard via --kb-inset), top-center on desktop. Subtle
+   backdrop blur. Hidden until status.ts sets `.visible`. Distinct from
+   the `.pill` family because it wants to span the full width centrally
+   rather than dock to a corner. */
 .conn-banner {
   position: fixed;
   bottom: var(--sp-3);
@@ -208,6 +208,18 @@
   }
 }
 
+/* Desktop (pointer: fine): move the banner to top-center so it no longer
+   shares the bottom-center anchor with the scroll-to-bottom FAB
+   (.kb-scroll-bottom). Sharing it let the banner (pointer-events:auto,
+   z-index:20) render over the FAB and intercept its click. Touch keeps
+   the bottom placement and the --kb-inset keyboard lift above. */
+@media (pointer: fine) {
+  .conn-banner {
+    top: var(--sp-3);
+    bottom: auto;
+  }
+}
+
 /* Clickable URLs */
 .term-link {
   color: inherit;
@@ -430,7 +442,7 @@
   z-index: 10;
   transition:
     opacity var(--dur-standard) var(--ease-standard),
-    background-color 150ms var(--ease-standard),
+    background-color var(--dur-micro) var(--ease-standard),
     display var(--dur-standard) allow-discrete;
 }
 
@@ -696,9 +708,9 @@
   opacity: 0;
   scale: 0.95;
   transition:
-    opacity 0.15s ease,
-    scale 0.15s ease,
-    display 0.15s allow-discrete;
+    opacity var(--dur-exit) var(--ease-standard),
+    scale var(--dur-exit) var(--ease-standard),
+    display var(--dur-exit) allow-discrete;
 }
 
 .ctx-menu.visible {
@@ -728,3 +740,15 @@
 .ctx-menu button:active {
   background: var(--text-active);
 }
+
+/* Touch (long-press) menu: bump the rows to the 44px --touch-target
+   standard the rest of the touch UI uses (the key-toolbar grid is
+   repeat(4, var(--touch-target))). Desktop right-click keeps the
+   compact 24px menu. padding-block re-centres the label in the taller box. */
+@media (pointer: coarse) {
+  .ctx-menu button {
+    min-height: var(--touch-target);
+    padding-block: var(--sp-2);
+    touch-action: manipulation;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "type": "module",
   "description": "Reference touch-first browser UI for @cplieger/web-terminal-engine: textarea input model, mobile key toolbar, context menu, IME, predictive echo, viewport/keyboard-inset handling, and CSS. One mount() call.",
   "license": "GPL-3.0-or-later",
@@ -31,8 +31,8 @@
     "fast-check": "4.8.0",
     "happy-dom": "20.10.6",
     "html-validate": "11.5.3",
-    "knip": "6.21.0",
-    "prettier": "3.8.5",
+    "knip": "6.23.0",
+    "prettier": "3.9.1",
     "stylelint": "17.14.0",
     "stylelint-config-standard": "40.0.0",
     "typescript": "6.0.3",

package/src/composition.ts

@@ -27,14 +27,9 @@
 // for the same reason.
 
 import { keyboard } from "@cplieger/web-terminal-engine";
+import { resetToPlaceholder } from "./input-placeholder.js";
 const { bracketTextForPaste, prepareTextForTerminal } = keyboard;
 
-// Single-character invisible placeholder used by app.ts to keep the
-// iOS soft keyboard's held-Backspace auto-repeat firing. Composition
-// finalisation must restore the placeholder (and not empty the
-// textarea) for the same reason.
-const INPUT_PLACEHOLDER = "\u00A0";
-
 let textarea: HTMLTextAreaElement;
 let compositionView: HTMLElement;
 let getCursorPx: () => { left: number; top: number; cellH: number };
@@ -43,7 +38,6 @@ let send: (bytes: string) => void;
 let composing = false;
 let sendingComposition = false;
 let compositionStart = 0;
-let compositionEnd = 0;
 let compositionSuffix = "";
 
 export function init(opts: {
@@ -75,7 +69,7 @@ function onStart(): void {
   const start = textarea.selectionStart;
   const end = textarea.selectionEnd;
   compositionStart = Math.min(start, end);
-  compositionEnd = Math.max(start, end);
+  const compositionEnd = Math.max(start, end);
   compositionSuffix = textarea.value.substring(compositionEnd);
   compositionView.textContent = "";
   compositionView.classList.add("active");
@@ -88,12 +82,6 @@ function onUpdate(ev: CompositionEvent): void {
   // clipped at the start. Pattern from xterm.js.
   compositionView.textContent = `\u200E${ev.data}\u200E`;
   positionCompositionView();
-  // Schedule a microtask to refresh the end position after the
-  // textarea selection settles.
-  setTimeout(() => {
-    const end = textarea.selectionEnd;
-    compositionEnd = Math.max(compositionStart, end);
-  }, 0);
 }
 
 function onEnd(): void {
@@ -119,7 +107,7 @@ function onEnd(): void {
     if (composed.length > 0) {
       send(composed);
     }
-    resetTextareaToPlaceholder();
+    resetToPlaceholder(textarea);
   }, 0);
 }
 
@@ -140,17 +128,7 @@ function onPaste(ev: ClipboardEvent): void {
   // Restore the placeholder so the subsequent `input` event (some
   // browsers fire it after paste) and held-Backspace auto-repeat keep
   // working.
-  resetTextareaToPlaceholder();
-}
-
-function resetTextareaToPlaceholder(): void {
-  textarea.value = INPUT_PLACEHOLDER;
-  try {
-    textarea.setSelectionRange(INPUT_PLACEHOLDER.length, INPUT_PLACEHOLDER.length);
-  } catch {
-    // Some older WebKit builds throw on setSelectionRange against a
-    // visually-hidden textarea; ignore.
-  }
+  resetToPlaceholder(textarea);
 }
 
 /** Position the composition view (and the helper textarea, which

package/src/index.ts

@@ -1,6 +1,7 @@
 // @cplieger/web-terminal-ui — the reference touch-first browser UI built on
-// the @cplieger/web-terminal-engine engine. The public surface is a single mount()
-// call against the shipped scaffold (scaffold/index.html) + CSS (css/).
+// the @cplieger/web-terminal-engine engine. The public surface is a single
+// mount(root) call that builds the whole terminal subtree inside a
+// host-provided element; scaffold/index.html + css/ are a reference page to copy.
 //
 // Consumers who want a different UI should depend on @cplieger/web-terminal-engine
 // directly and wire the engine's render/scroll/connection/keyboard modules

package/src/input-placeholder.ts

@@ -0,0 +1,29 @@
+// Single source of truth for the hidden-textarea placeholder shared by
+// mount.ts and composition.ts.
+//
+// A single-character placeholder is kept in the hidden textarea so iOS soft
+// keyboards have something to "delete" when the user holds Backspace. iOS only
+// fires repeating `input` events with inputType="deleteContentBackward" when
+// the textarea has content to delete; with a perpetually empty textarea,
+// holding Backspace deletes one char and stops because iOS sees nothing more to
+// remove. The placeholder itself is invisible (textarea has opacity:0) and is
+// stripped out of every send. NBSP is chosen specifically so screen-reader
+// announcement of the input state stays empty-ish rather than "space".
+//
+// The constant AND the reset routine must stay in lockstep across the two
+// modules (mount.ts seeds + re-pads it; composition.ts restores it on
+// compositionend / paste) or the iOS held-Backspace key-repeat silently breaks
+// with no compile error — which is why they live here in one place.
+export const INPUT_PLACEHOLDER = "\u00A0";
+
+// Restore the placeholder and put the cursor at the end, so the next typed
+// character appends after it rather than before.
+export function resetToPlaceholder(textarea: HTMLTextAreaElement): void {
+  textarea.value = INPUT_PLACEHOLDER;
+  try {
+    textarea.setSelectionRange(INPUT_PLACEHOLDER.length, INPUT_PLACEHOLDER.length);
+  } catch {
+    // Some older WebKit builds throw on setSelectionRange against a
+    // visually-hidden textarea; ignore.
+  }
+}

package/src/mount.ts

@@ -18,6 +18,7 @@ import * as viewport from "./viewport.js";
 import * as composition from "./composition.js";
 import * as status from "./status.js";
 import * as predict from "./predict.js";
+import { INPUT_PLACEHOLDER, resetToPlaceholder } from "./input-placeholder.js";
 
 const { mapKeyboardEvent, bracketTextForPaste, prepareTextForTerminal } = keyboard;
 
@@ -44,34 +45,22 @@ export interface TerminalUI {
 const DEFAULT_WS_PATH = "/ws";
 const DEFAULT_FONT_READY = '14px "MonaspiceNe NFM"';
 
-// Single-character placeholder kept in the hidden textarea so iOS soft
-// keyboards have something to "delete" when the user holds Backspace.
-// iOS only fires repeating `input` events with
-// inputType="deleteContentBackward" when the textarea has content to
-// delete; with a perpetually empty textarea, holding Backspace deletes
-// one char and stops because iOS sees nothing more to remove. The
-// placeholder itself is invisible (textarea has opacity:0) and we strip
-// it out of every send. NBSP chosen specifically so screen-reader
-// announcement of the input state stays empty-ish rather than "space".
-const INPUT_PLACEHOLDER = "\u00A0";
-
 const TAP_MOVEMENT_PX = 10;
 const LONG_PRESS_MS = 500;
 const LONG_PRESS_MOVE_THRESHOLD_PX = 10;
 
 const encoder = new TextEncoder();
 
-// --- DOM refs (assigned in mount() from the scaffold) ---
+// --- DOM refs (picked by class from the subtree mount() builds) ---
 let outputEl!: HTMLElement;
 let termWrap!: HTMLElement;
 let input!: HTMLTextAreaElement;
-let compositionViewEl!: HTMLElement;
 let ctxMenu!: HTMLElement;
 
 // --- Mutable UI state ---
 // Sticky-Ctrl state + the C0 mapping table + the toolbar button wiring all
 // live in the engine's keyboard.bindMobileToolbar; mount() binds it against
-// the required #key-toolbar and keeps the controller so the input handler
+// the built .key-toolbar element and keeps the controller so the input handler
 // can route typed text through its applyStickyCtrl.
 let toolbarCtrl!: keyboard.MobileToolbarController;
 let fontsLoaded = false;
@@ -132,33 +121,83 @@ function pick(root: ParentNode, selector: string): HTMLElement {
 }
 
 function send(bytes: string): void {
-  // Suppress backspace (DEL) when the predicted cursor is at column 0
-  // — there's nothing left to delete. This mimics the natural brake
-  // that iOS's textarea provided (stops key-repeat when empty).
-  if (bytes === "\x7f" && predict.get().col === 0 && predict.get().active) {
+  // Suppress a lone Backspace (DEL) ONLY at the true origin (row 0, col 0):
+  // there's nothing left to delete on an empty line, and this preserves the
+  // brake iOS's textarea provided (stops held-Backspace key-repeat when empty).
+  // The row check matters: predict.applyInput models a col-0 DEL on a WRAPPED
+  // continuation row (row > 0) by wrapping to the end of the previous row, so a
+  // continuation-row backspace must cross that wrap and reach the server rather
+  // than being braked here (braking it would make backspace silently stick
+  // mid-line on a wrapped command line).
+  const p = predict.get();
+  if (bytes === "\x7f" && p.col === 0 && p.row === 0 && p.active) {
     return;
   }
   const buf = encoder.encode(bytes);
-  predict.applyInput(buf);
+  // sendBinary buffers while disconnected (resume layer) and returns false ONLY when the
+  // 1 MiB outbox is full -- the engine has already surfaced that via onOutboxFull ->
+  // status.closed(). Advancing the prediction for a dropped byte would paint a phantom
+  // char that never reaches the server, so only advance on accepted input.
   if (!connection.sendBinary(buf)) {
-    /* connection not ready — drop silently */
+    return;
   }
+  predict.applyInput(buf);
 }
 
-function resetInputPlaceholder(): void {
-  input.value = INPUT_PLACEHOLDER;
-  // Cursor at the end so the next typed char appends after the
-  // placeholder rather than before.
-  try {
-    input.setSelectionRange(INPUT_PLACEHOLDER.length, INPUT_PLACEHOLDER.length);
-  } catch {
-    // Ignore browsers that throw on setSelectionRange against a hidden
-    // input (some older WebKit builds).
+// Normalize iOS's NBSP-for-space quirk, apply sticky-Ctrl, then send.
+function sendTyped(text: string): void {
+  send(toolbarCtrl.applyStickyCtrl(text.replace(/\u00A0/g, " ")));
+}
+
+// Read the current predicted-cursor state and push it to the renderer.
+// Shared by render.init's onCursorMove (server cursor moved) and
+// predict.subscribe (prediction changed) so both push identically.
+function pushPredictedCursor(): void {
+  const p = predict.get();
+  render.setPredictedCursor(p.row, p.col, p.active);
+}
+
+// Clipboard helpers. navigator.clipboard is UNDEFINED outside a secure context
+// (plain-HTTP on a non-loopback host — a supported web-terminal-server
+// deployment), where a property access such as navigator.clipboard.writeText
+// throws a SYNCHRONOUS TypeError before any .then/.catch can guard it. Feature-
+// detect first so Copy/Paste surface a "Clipboard unavailable" toast instead of
+// throwing out of the handler (on Ctrl+Shift+C an uncaught throw would also skip
+// preventDefault and let the browser's native devtools shortcut fire).
+function copyToClipboard(text: string): void {
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- navigator.clipboard is undefined outside secure contexts (plain-HTTP host)
+  if (!navigator.clipboard) {
+    status.toast("Clipboard unavailable");
+    return;
   }
+  navigator.clipboard
+    .writeText(text)
+    .then(() => {
+      status.toast("Copied");
+    })
+    .catch(() => {
+      status.toast("Copy failed");
+    });
+}
+
+function pasteFromClipboard(): void {
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- navigator.clipboard is undefined outside secure contexts (plain-HTTP host)
+  if (!navigator.clipboard) {
+    status.toast("Clipboard unavailable");
+    return;
+  }
+  navigator.clipboard
+    .readText()
+    .then((text) => {
+      send(bracketTextForPaste(prepareTextForTerminal(text)));
+    })
+    .catch(() => {
+      status.toast("Paste blocked");
+    });
 }
 
 // Keydown handler — attached to the textarea (the single keyboard target,
-// desktop and touch alike); #term-output is display-only and never focused.
+// desktop and touch alike); .term-output is display-only and never focused.
 function handleKeydown(ev: KeyboardEvent): void {
   // While composing (IME), let the browser pump composition events;
   // keydown bytes during composition would duplicate the composed text.
@@ -166,6 +205,19 @@ function handleKeydown(ev: KeyboardEvent): void {
     return;
   }
 
+  // When the context menu is open, Escape dismisses it WITHOUT also sending an
+  // ESC byte to the PTY -- matching the no-side-effect outside-click dismiss
+  // (the document-level handler frames this as "parity"). This textarea keydown
+  // fires before that document-level handler bubbles, so without this guard
+  // mapKeyboardEvent would send ESC to the shell first (e.g. dropping vim out of
+  // insert mode) while the menu also closes. The document-level handler still
+  // covers the case where focus is on a menu button rather than the textarea.
+  if (ev.key === "Escape" && ctxMenu.classList.contains("visible")) {
+    ev.preventDefault();
+    hideCtxMenu();
+    return;
+  }
+
   // Ctrl+Shift+C / Ctrl+Shift+V — desktop clipboard shortcuts. Handled
   // before the generic mapper because they take browser-side selection
   // and clipboard, not server-bound key sequences.
@@ -173,22 +225,13 @@ function handleKeydown(ev: KeyboardEvent): void {
     if (ev.code === "KeyC") {
       const sel = window.getSelection()?.toString();
       if (sel) {
-        void navigator.clipboard.writeText(sel).catch(() => {
-          /* ignore */
-        });
+        copyToClipboard(sel);
       }
       ev.preventDefault();
       return;
     }
     if (ev.code === "KeyV") {
-      navigator.clipboard
-        .readText()
-        .then((text) => {
-          send(bracketTextForPaste(prepareTextForTerminal(text)));
-        })
-        .catch(() => {
-          /* ignore */
-        });
+      pasteFromClipboard();
       ev.preventDefault();
       return;
     }
@@ -237,8 +280,17 @@ function maybeSendFirstResize(): void {
 }
 
 function hideCtxMenu(): void {
+  // If focus is inside the menu (a keyboard user activated an item or pressed
+  // Escape on a focused button), return focus to the terminal input -- otherwise
+  // removing the focused button drops focus to <body> and the keyboard user can no
+  // longer type. On a pointer/outside-click dismiss focus is not in the menu, so
+  // this is a no-op and does not steal focus.
+  const refocus = ctxMenu.contains(document.activeElement);
   ctxMenu.classList.remove("visible");
-  ctxMenu.innerHTML = "";
+  ctxMenu.replaceChildren();
+  if (refocus) {
+    focusTerminal();
+  }
 }
 
 function showCtxMenu(x: number, y: number): void {
@@ -249,9 +301,7 @@ function showCtxMenu(x: number, y: number): void {
     const copyBtn = document.createElement("button");
     copyBtn.textContent = "Copy";
     copyBtn.addEventListener("click", () => {
-      void navigator.clipboard.writeText(sel).catch(() => {
-        /* ignore */
-      });
+      copyToClipboard(sel);
       hideCtxMenu();
     });
     ctxMenu.appendChild(copyBtn);
@@ -272,14 +322,7 @@ function showCtxMenu(x: number, y: number): void {
     const pasteBtn = document.createElement("button");
     pasteBtn.textContent = "Paste";
     pasteBtn.addEventListener("click", () => {
-      navigator.clipboard
-        .readText()
-        .then((text) => {
-          send(bracketTextForPaste(prepareTextForTerminal(text)));
-        })
-        .catch(() => {
-          /* ignore */
-        });
+      pasteFromClipboard();
       hideCtxMenu();
     });
     ctxMenu.appendChild(pasteBtn);
@@ -317,7 +360,7 @@ export function mount(root: HTMLElement, opts: MountOptions = {}): TerminalUI {
   termWrap = pick(root, ".term");
   outputEl = pick(root, ".term-output");
   input = pick(root, ".term-input") as HTMLTextAreaElement;
-  compositionViewEl = pick(root, ".composition-view");
+  const compositionViewEl = pick(root, ".composition-view");
   ctxMenu = pick(root, ".ctx-menu");
   const banner = pick(root, ".conn-banner");
   const toolbar = pick(root, ".key-toolbar");
@@ -331,23 +374,47 @@ export function mount(root: HTMLElement, opts: MountOptions = {}): TerminalUI {
   // may show reconnect state from here on) and fades out the consumer's
   // loading overlay if one was passed.
   let ready = false;
+  let firstFrameRendered = false;
+  let overlayDismissed = false;
+  // Fade out and remove the consumer-owned loading overlay (if one was passed).
+  // Extracted from markReady() so status.ts can also drive it via its give-up
+  // signal: on a socket that never connects no first screen frame ever arrives,
+  // so markReady never runs and nothing else would remove the opaque
+  // z-index:200 overlay -- it would occlude the "Offline" banner forever.
+  // status fires its onGiveUp on EVERY post-limit unloaded close against an
+  // unbounded reconnect loop, so the overlayDismissed one-shot guard makes the
+  // fade/remove and its transitionend listener + fallback timer register exactly
+  // once; later calls early-return rather than piling listeners and timers onto
+  // the (soon-detached) overlay node.
+  function dismissLoadingOverlay(): void {
+    const ld = opts.loading;
+    if (!ld || overlayDismissed) {
+      return;
+    }
+    overlayDismissed = true;
+    ld.classList.add("fade");
+    const removeOverlay = (): void => {
+      ld.remove();
+    };
+    // transitionend fires on the consumer-owned fade, but their overlay CSS may have
+    // no opacity transition (or it can be interrupted): then transitionend never fires
+    // and the now opacity:0 overlay -- still inset:0 / z-index:200 with no
+    // pointer-events:none in the reference scaffold -- keeps swallowing every tap and
+    // click over the terminal. Remove on a bounded fallback too.
+    ld.addEventListener("transitionend", removeOverlay, { once: true });
+    window.setTimeout(removeOverlay, 1500);
+  }
   function markReady(): void {
     if (ready) {
       return;
     }
     ready = true;
     status.setLoaded();
-    const ld = opts.loading;
-    if (ld) {
-      ld.classList.add("fade");
-      ld.addEventListener("transitionend", () => {
-        ld.remove();
-      });
-    }
+    dismissLoadingOverlay();
   }
 
   // --- Initialize layers ---
-  status.init({ banner });
+  status.init({ banner, onGiveUp: dismissLoadingOverlay });
 
   render.init({
     output: outputEl,
@@ -359,17 +426,13 @@ export function mount(root: HTMLElement, opts: MountOptions = {}): TerminalUI {
     // server cursor.
     onCursorMove: () => {
       composition.positionCompositionView();
-      const p = predict.get();
-      render.setPredictedCursor(p.row, p.col, p.active);
+      pushPredictedCursor();
     },
   });
   render.updateFontMetrics();
 
   // predict redraws on every change to its predicted-cursor state.
-  predict.subscribe(() => {
-    const p = predict.get();
-    render.setPredictedCursor(p.row, p.col, p.active);
-  });
+  predict.subscribe(pushPredictedCursor);
 
   composition.init({
     textarea: input,
@@ -395,6 +458,7 @@ export function mount(root: HTMLElement, opts: MountOptions = {}): TerminalUI {
     onMessage(msg) {
       if (msg.type === "screen") {
         render.handleScreen(msg);
+        firstFrameRendered = true;
         if (fontsLoaded) {
           markReady();
         }
@@ -411,7 +475,7 @@ export function mount(root: HTMLElement, opts: MountOptions = {}): TerminalUI {
       status.open();
       // Do NOT call render.resetScreen() here. resetScreen flips the
       // firstScreen flag, which causes the next screen frame to wipe
-      // the entire #term-output DOM (including all scrollback above
+      // the entire .term-output DOM (including all scrollback above
       // the live viewport). On reconnect (e.g. iPad screen dim/wake)
       // that destroys history the user could otherwise scroll up to.
       // The server forces a full repaint via builder.Reset() on resume,
@@ -448,7 +512,7 @@ export function mount(root: HTMLElement, opts: MountOptions = {}): TerminalUI {
   });
 
   // --- Input handling ---
-  resetInputPlaceholder();
+  resetToPlaceholder(input);
 
   input.addEventListener("input", (e: Event) => {
     // While IME composition is in progress, the textarea fires `input`
@@ -462,19 +526,15 @@ export function mount(root: HTMLElement, opts: MountOptions = {}): TerminalUI {
     const ev = e as InputEvent;
     const inputType = ev.inputType;
 
-    if (inputType === "deleteContentBackward") {
-      // Handled by keydown — just re-pad the placeholder so iOS
+    if (
+      inputType === "deleteContentBackward" ||
+      inputType === "deleteContentForward" ||
+      inputType === "deleteWordBackward" ||
+      inputType === "deleteWordForward"
+    ) {
+      // Deletion is handled by keydown — just re-pad the placeholder so iOS
       // key-repeat keeps firing (it needs content to delete).
-      resetInputPlaceholder();
-      return;
-    } else if (inputType === "deleteContentForward") {
-      resetInputPlaceholder();
-      return;
-    } else if (inputType === "deleteWordBackward") {
-      resetInputPlaceholder();
-      return;
-    } else if (inputType === "deleteWordForward") {
-      resetInputPlaceholder();
+      resetToPlaceholder(input);
       return;
     } else if (typeof ev.data === "string" && ev.data.length > 0) {
       // insertText / insertFromPaste / insertReplacementText etc. The
@@ -486,21 +546,29 @@ export function mount(root: HTMLElement, opts: MountOptions = {}): TerminalUI {
       // space byte. (Native paste is bracketed in composition.ts's paste
       // handler before this fires; the insertFromPaste data here is a
       // fallback for browsers that don't raise a separate paste event.)
-      send(toolbarCtrl.applyStickyCtrl(ev.data.replace(/\u00A0/g, " ")));
+      if (inputType === "insertFromPaste") {
+        // Paste arriving through `input` without a preceding `paste` event
+        // (composition.ts's onPaste handles + preventDefaults the normal
+        // case). Bracket + sanitize it exactly like the Ctrl+Shift+V,
+        // context-menu Paste, and composition.onPaste paths so embedded
+        // newlines / control bytes arrive as an inert bracketed paste
+        // instead of executing as typed shell commands (paste-jacking).
+        send(bracketTextForPaste(prepareTextForTerminal(ev.data)));
+      } else {
+        sendTyped(ev.data);
+      }
     } else {
       // Fallback: anything in the textarea past the placeholder is new
       // content. Covers browsers that don't populate inputType / data
       // (older WebKit).
       const v = input.value;
       if (v.length > INPUT_PLACEHOLDER.length && v.startsWith(INPUT_PLACEHOLDER)) {
-        send(
-          toolbarCtrl.applyStickyCtrl(v.slice(INPUT_PLACEHOLDER.length).replace(/\u00A0/g, " ")),
-        );
+        sendTyped(v.slice(INPUT_PLACEHOLDER.length));
       } else if (v !== INPUT_PLACEHOLDER && v.length > 0) {
-        send(toolbarCtrl.applyStickyCtrl(v.replace(/\u00A0/g, " ")));
+        sendTyped(v);
       }
     }
-    resetInputPlaceholder();
+    resetToPlaceholder(input);
   });
 
   // Focus state on the terminal element, for CSS targeting (e.g. dimming
@@ -512,16 +580,16 @@ export function mount(root: HTMLElement, opts: MountOptions = {}): TerminalUI {
     // Restore the placeholder so the held-Backspace iOS path stays
     // primed for the next focus. Also clears any leftover screen-reader
     // text (xterm.js convention).
-    resetInputPlaceholder();
+    resetToPlaceholder(input);
     termWrap.classList.remove("focus");
   });
 
   // The textarea is the single keyboard target (desktop and touch alike);
-  // #term-output is display-only and never focused.
+  // .term-output is display-only and never focused.
   input.addEventListener("keydown", handleKeydown);
 
   // --- Focus strategy ---
-  // One element, one job. #term-output is display + native selection only
+  // One element, one job. .term-output is display + native selection only
   // and is NEVER focused; the textarea owns the keyboard, the local typing
   // buffer, and IME. Because the editable element is never the scroll
   // content, the first touch-drag scrolls instead of placing a caret and a
@@ -557,6 +625,11 @@ export function mount(root: HTMLElement, opts: MountOptions = {}): TerminalUI {
       if (e.pointerType !== "touch") {
         return; // mouse/trackpad handled by the click listener below
       }
+      // A tap on a terminal link is opened by the click listener below; don't
+      // also focus the textarea (which pops the iOS soft keyboard) on the way.
+      if ((e.target as HTMLElement).closest(".term-link")) {
+        return;
+      }
       const dx = Math.abs(e.clientX - pointerDownX);
       const dy = Math.abs(e.clientY - pointerDownY);
       if (dx > TAP_MOVEMENT_PX || dy > TAP_MOVEMENT_PX) {
@@ -568,15 +641,36 @@ export function mount(root: HTMLElement, opts: MountOptions = {}): TerminalUI {
       }
       // Synchronous focus inside pointerup keeps us inside iOS's
       // user-gesture window even when the streaming flush queue is busy.
-      input.focus({ preventScroll: true });
+      focusTerminal();
     },
     { passive: true },
   );
+  // After a touch tap, iOS/WebKit dispatches a synthetic `mousedown` (following
+  // the `pointerup` above). Its default action moves focus to the nearest
+  // focusable ancestor of the tap point — but the input-model contract keeps
+  // `.term-output` and `.term` deliberately non-focusable (display-only) and the
+  // hidden textarea is `pointer-events: none`, so the tap never lands on a
+  // focusable node. With nothing focusable under the tap, that default blurs the
+  // textarea we just focused in `pointerup`, so iOS immediately dismisses the
+  // soft keyboard the tap had only just opened — the "keyboard flashes open then
+  // instantly closes" symptom on touch. Cancelling the synthetic mousedown's
+  // default keeps focus on the textarea, so the keyboard stays up. This is the
+  // xterm.js focus-preservation pattern, scoped to touch: a real mouse mousedown
+  // must keep its default so desktop drag-to-select text still works, and iOS
+  // text selection is long-press-driven (not this tap mousedown), so it is
+  // unaffected. Not passive — preventDefault must take effect.
+  termWrap.addEventListener("mousedown", (e) => {
+    if (lastPointerType === "touch") {
+      e.preventDefault();
+    }
+  });
   termWrap.addEventListener("click", (e) => {
-    // Terminal links: URLs detected by render.ts's linkifySpans are wrapped
-    // in <a class="term-link" target="_blank">. In a contenteditable element
-    // the browser treats link clicks as cursor-placement, not navigation.
-    // Intercept and open explicitly.
+    // Terminal links: URLs rendered by the engine are wrapped in
+    // <a class="term-link" target="_blank" rel="noopener noreferrer">. The
+    // output is display-only (never contenteditable -- see the input-model
+    // contract), so intercept the click to open with explicit
+    // noopener/noreferrer and to keep the focus handler below from running
+    // on a link tap.
     const link = (e.target as HTMLElement).closest<HTMLAnchorElement>(".term-link");
     if (link) {
       e.preventDefault();
@@ -623,15 +717,34 @@ export function mount(root: HTMLElement, opts: MountOptions = {}): TerminalUI {
 
   // Only wait for the Regular weight — it determines cell size.
   // Bold/Italic load lazily when first used; style pop is barely noticeable.
-  const regularFont = document.fonts.load(fontReady).then(() => {
-    /* discard result */
-  });
-  void regularFont.then(() => {
+  // A missing/slow font, or a malformed `fontReady` (FontFaceSet.load can throw
+  // synchronously on a bad shorthand), must NOT leave the terminal permanently
+  // unsized: degrade to fallback-font metrics so the first resize still fires
+  // and the loading overlay still dismisses.
+  const onFontSettled = (): void => {
     fontsLoaded = true;
+    if (firstFrameRendered) {
+      markReady();
+    }
     requestAnimationFrame(() => {
       maybeSendFirstResize();
     });
-  });
+  };
+  try {
+    void document.fonts
+      .load(fontReady)
+      .then(onFontSettled)
+      .catch((err: unknown) => {
+        console.warn(
+          `web-terminal-ui: web font ${fontReady} failed to load; using fallback metrics`,
+          err,
+        );
+        onFontSettled();
+      });
+  } catch (err) {
+    console.warn(`web-terminal-ui: invalid fontReady ${fontReady}; using fallback metrics`, err);
+    onFontSettled();
+  }
 
   // Connect immediately — the WS open triggers maybeSendFirstResize.
   render.updateFontMetrics();
@@ -753,6 +866,15 @@ export function mount(root: HTMLElement, opts: MountOptions = {}): TerminalUI {
     hideCtxMenu();
   });
 
+  // Escape dismisses the context menu (keyboard parity with the outside-click
+  // dismiss; the menu can be opened via the keyboard Menu key, which fires
+  // `contextmenu`). Without this an AT/keyboard user has no keyboard way to close it.
+  document.addEventListener("keydown", (e) => {
+    if (e.key === "Escape" && ctxMenu.classList.contains("visible")) {
+      hideCtxMenu();
+    }
+  });
+
   // --- Mobile key toolbar ---
   // The engine's keyboard.bindMobileToolbar wires the collapse toggle, the
   // arrows (DECCKM-aware — SS3 under application-cursor mode, matching

package/src/predict.ts

@@ -48,6 +48,8 @@ export function setDimensions(c: number, r: number): void {
   if (r > 0) {
     rows = r;
   }
+  const prevCol = predCol;
+  const prevRow = predRow;
   // Clamp predicted position to new bounds so a resize mid-typing
   // doesn't leave predCol/predRow past the edge.
   if (predCol >= cols) {
@@ -56,6 +58,12 @@ export function setDimensions(c: number, r: number): void {
   if (predRow >= rows) {
     predRow = rows - 1;
   }
+  // Notify subscribers when the clamp moved the predicted cursor, so the
+  // renderer's overlay doesn't show a stale (possibly off-screen) position
+  // until the next server frame arrives.
+  if (predCol !== prevCol || predRow !== prevRow) {
+    onChange?.();
+  }
 }
 
 /** Reset all prediction state. Called on server restart to avoid
@@ -66,9 +74,7 @@ export function reset(): void {
   predActive = false;
   predPendingWrap = false;
   predFrozen = false;
-  if (onChange) {
-    onChange();
-  }
+  onChange?.();
 }
 
 /** Reset prediction to the server's reported cursor and re-arm.
@@ -81,9 +87,7 @@ export function onScreenFrame(serverRow: number, serverCol: number, cursorHidden
   predPendingWrap = false;
   predFrozen = cursorHidden ?? false;
   predActive = !predFrozen;
-  if (onChange) {
-    onChange();
-  }
+  onChange?.();
 }
 
 /** Apply locally-typed input bytes to the predicted cursor. Bails out
@@ -100,9 +104,7 @@ export function applyInput(bytes: Uint8Array): void {
     if (b === 0x1b) {
       // ESC — start of an escape sequence. Don't try to model it.
       predActive = false;
-      if (onChange) {
-        onChange();
-      }
+      onChange?.();
       return;
     }
     if (b === 0x08 || b === 0x7f) {
@@ -137,9 +139,7 @@ export function applyInput(bytes: Uint8Array): void {
     if (b < 0x20) {
       // Other C0 — probably interpreted by the application; bail.
       predActive = false;
-      if (onChange) {
-        onChange();
-      }
+      onChange?.();
       return;
     }
     // Printable ASCII or UTF-8 lead byte. Detect the codepoint length
@@ -169,9 +169,7 @@ export function applyInput(bytes: Uint8Array): void {
       predCol++;
     }
   }
-  if (onChange) {
-    onChange();
-  }
+  onChange?.();
 }
 
 /** Current predicted cursor state. `active` is false when prediction

package/src/status.ts

@@ -1,20 +1,31 @@
-// Connection-state banner. Shows "Reconnecting…" / "Offline" / "Slow
-// connection" feedback so users on flaky links understand why typing
-// is unresponsive. Hidden by default; appears only when the
-// connection state diverges from "open" for more than a brief window
-// (debounced to avoid flicker on healthy networks).
+// Connection-state banner. Shows "Reconnecting…" / "Offline" / "Server
+// restarted" feedback so users on flaky links understand why typing is
+// unresponsive. Hidden by default; appears only when the connection
+// state diverges from "open" for more than a brief window (debounced to
+// avoid flicker on healthy networks). A "slow connection" indicator is
+// intentionally not implemented (see the state machine below).
 //
-// State machine:
-//   open      → no banner.
-//   closed    → "Reconnecting…" after CONNECTING_GRACE_MS, "Offline"
-//               after several backoff failures.
-//   reconnecting (during a connect retry) → "Reconnecting…".
-//   slow      → "Slow connection" overlaid on top of "open" when the
-//               server's pingstat reports a capped RTO. (Not wired
-//               yet; placeholder for a future ping-RTT feedback path.)
+// State machine (matches the `State` union below):
+//   open         → no banner.
+//   connecting   → "Reconnecting…" (initial connect, before first open).
+//   reconnecting → "Reconnecting…" (after a close, during retry);
+//                  escalates to offline after >3 consecutive failures.
+//   offline      → "Offline".
+//   restarted    → "Server restarted — recent input may have been lost".
+// A "slow connection" indicator is intentionally not implemented: it would
+// need an RTT signal the engine does not currently expose to consumers.
 
 const CONNECTING_GRACE_MS = 600;
 
+// Consecutive failed *initial* connection attempts (before the first screen
+// frame, i.e. while `loaded` is still false) after which the "Offline" banner
+// is allowed to render anyway. Below this we stay silent and defer to the
+// consumer's loading overlay, so a merely-slow first connect raises no false
+// alarm; this many failures in a row means the connection genuinely isn't
+// coming up and an indefinite silent "Loading…" would be worse than "Offline".
+// Aligned with the post-load escalation threshold (consecutiveFailures > 3).
+const INITIAL_FAILURE_LIMIT = 4;
+
 type State = "open" | "connecting" | "reconnecting" | "offline" | "restarted";
 
 let banner: HTMLElement | null = null;
@@ -26,6 +37,13 @@ let consecutiveFailures = 0;
 // reconnect/offline banner so the two don't stack — this replaces the old
 // `document.getElementById("loading")` probe.
 let loaded = false;
+// Optional callback supplied by init(): invoked once the initial-connect
+// failure limit is reached while still !loaded, so mount can fade its opaque
+// loading overlay and let the "Offline" banner underneath become visible.
+// mount always supplies this (its dismissLoadingOverlay self-guards when no
+// overlay was passed), so onGiveUp is null only when init() is called without
+// the callback (e.g. the status unit tests).
+let onGiveUp: (() => void) | null = null;
 
 /** Mark the connection as open. Hides the banner. */
 export function open(): void {
@@ -51,9 +69,21 @@ export function reconnecting(): void {
 /** Mark the connection as closed; shows banner after grace period. */
 export function closed(): void {
   consecutiveFailures++;
-  if (!loaded) {
+  // Before the first frame, stay suppressed (the loading overlay owns the
+  // screen) UNTIL we've failed to connect INITIAL_FAILURE_LIMIT times in a
+  // row — at that point the connection clearly isn't coming up, so let the
+  // "Offline" banner through rather than leave a silent "Loading…" forever.
+  if (!loaded && consecutiveFailures < INITIAL_FAILURE_LIMIT) {
     return;
   }
+  // Past the initial-failure limit while the loading overlay is still up: tell
+  // mount to fade it so the "Offline" banner below becomes visible rather than
+  // staying occluded behind the opaque overlay (which markReady would otherwise
+  // never remove on a never-connecting socket). Idempotent, so firing on each
+  // subsequent !loaded close is safe.
+  if (!loaded) {
+    onGiveUp?.();
+  }
   setState(consecutiveFailures > 3 ? "offline" : "reconnecting", CONNECTING_GRACE_MS);
 }
 
@@ -116,15 +146,17 @@ function dismissToast(): void {
   if (!banner) {
     return;
   }
-  // Only clear if still showing a toast (not overridden by connection state).
-  if (state === "open" && banner.dataset["state"] === "toast") {
-    banner.classList.remove("visible");
-    banner.textContent = "";
+  // Restore the live connection state. applyState() hides the banner when
+  // "open" (identical to the old clear) and re-renders "Offline"/"Reconnecting…"
+  // when a toast was shown over a non-open status, so the status is never stranded.
+  if (banner.dataset["state"] === "toast") {
+    applyState();
   }
 }
 
-export function init(opts: { banner: HTMLElement }): void {
+export function init(opts: { banner: HTMLElement; onGiveUp?: () => void }): void {
   banner = opts.banner;
+  onGiveUp = opts.onGiveUp ?? null;
   applyState();
 
   // Hover-pause: stop the auto-dismiss timer while the user hovers
@@ -160,6 +192,17 @@ function applyState(): void {
   if (!banner) {
     return;
   }
+  // Stay fully suppressed until the initial load is over (matches the
+  // `loaded` guard in reconnecting()/closed()): the loading overlay, when
+  // present, owns the screen until then and a bare page has nothing to show.
+  // Exception: once INITIAL_FAILURE_LIMIT consecutive initial connects have
+  // failed, let "Offline" through even while !loaded so a never-connecting
+  // page doesn't sit on a silent "Loading…" indefinitely.
+  if (!loaded && !(state === "offline" && consecutiveFailures >= INITIAL_FAILURE_LIMIT)) {
+    banner.classList.remove("visible");
+    banner.textContent = "";
+    return;
+  }
   switch (state) {
     case "open":
       banner.classList.remove("visible");