@cplieger/web-terminal-ui 8.2.1 → 8.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/web-terminal-ui",
-  "version": "8.2.1",
+  "version": "8.3.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": "MPL-2.0",
@@ -52,20 +52,20 @@
     "@stryker-mutator/vitest-runner": "10.0.0",
     "@types/node": "26.6.3",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/browser": "5.0.2",
-    "@vitest/browser-playwright": "5.0.2",
-    "@vitest/coverage-v8": "5.0.2",
+    "@vitest/browser": "5.0.3",
+    "@vitest/browser-playwright": "5.0.3",
+    "@vitest/coverage-v8": "5.0.3",
     "eslint": "10.11.0",
     "fast-check": "4.10.2",
     "html-validate": "11.16.1",
-    "knip": "6.38.0",
+    "knip": "6.39.0",
     "playwright": "1.63.0",
     "prettier": "3.9.9",
     "stylelint": "17.15.0",
     "stylelint-config-standard": "40.0.0",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.71.0",
-    "vitest": "5.0.2"
+    "vitest": "5.0.3"
   },
   "publishConfig": {
     "access": "public"

package/src/features/tabs/index.ts

@@ -281,27 +281,6 @@ interface ShowOptions {
 type SplitOpening =
   { readonly by: "button" } | { readonly by: "snap"; readonly id: string; readonly side: PaneSide };
 
-function looksLikeHardwareKey(ev: KeyboardEvent): boolean {
-  if (ev.ctrlKey || ev.metaKey || ev.altKey) {
-    return true;
-  }
-  switch (ev.key) {
-    case "ArrowUp":
-    case "ArrowDown":
-    case "ArrowLeft":
-    case "ArrowRight":
-    case "Escape":
-    case "Tab":
-    case "Home":
-    case "End":
-    case "PageUp":
-    case "PageDown":
-      return true;
-    default:
-      return /^F\d{1,2}$/.test(ev.key); // F1–F12
-  }
-}
-
 /** Build the tabs feature.
  *  Requires a server that speaks the session API (`GET`/`POST`/`DELETE` on
  *  `/api/sessions`, `?session=<id>` on the WebSocket, ideally the status SSE).
@@ -852,13 +831,6 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
       let creatingTab = false;
       let collapseClearTimer: number | null = null;
       let hintShown = false;
-      // No web API reports a hardware keyboard, so two proxies: a fine pointer
-      // (read live, since a keyboard folio with a trackpad can be detached) and a
-      // keydown only a hardware keyboard emits (a trackpad-less folio).
-      let sawHardwareKey = false;
-      const hasFinePointer = (): boolean =>
-        typeof win.matchMedia === "function" && win.matchMedia("(any-pointer: fine)").matches;
-      const physicalKeyboardLikely = (): boolean => sawHardwareKey || hasFinePointer();
       const prefersReduce = (): boolean =>
         win.matchMedia("(prefers-reduced-motion: reduce)").matches;
 
@@ -984,7 +956,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           return;
         }
         if (
-          physicalKeyboardLikely() ||
+          ctx.shell.keyboard.likely() ||
           (inputFocusedAtPress && keyboardParkedOnChrome()) ||
           keyboardInOtherPane()
         ) {
@@ -2729,7 +2701,7 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
           el.focus();
           return;
         }
-        if (physicalKeyboardLikely()) {
+        if (ctx.shell.keyboard.likely()) {
           focusInput();
         }
       }
@@ -3374,14 +3346,6 @@ export function tabs(opts: TabsOptions = {}): TerminalFeature<TabsApi> {
         });
       }
 
-      // A hardware-only key latches sawHardwareKey, which upgrades focus-on-switch
-      // for a keyboard folio with no trackpad.
-      ctx.registerKeydown((ev) => {
-        if (!sawHardwareKey && looksLikeHardwareKey(ev)) {
-          sawHardwareKey = true;
-        }
-        return false;
-      });
       bar.addEventListener("dragover", (e) => {
         if (!draggingEl) {
           return;

package/src/index.ts

@@ -17,6 +17,7 @@ export type {
   PaneSide,
   PaneHandle,
   ShellContext,
+  KeyboardPresence,
   AttentionOptions,
   AttentionState,
   AttentionReporter,

package/src/kernel/keyboard-presence.ts

@@ -0,0 +1,112 @@
+// No web API reports a hardware keyboard, so the shell infers one from the keys
+// it sees and keeps that inference in one place for every pane and feature.
+
+import type { KeyboardPresence } from "./types.js";
+
+/** An on-screen keyboard at least this tall is docked; the hardware-keyboard
+ *  shortcut bar iPadOS shows is well under it. */
+const SOFT_KEYBOARD_MIN_PX = 150;
+
+/** Whether the PRIMARY pointer is fine. False on every iPad and iPhone whatever
+ *  is attached, true on a desktop (`pointerCharacteristicsOfPrimaryPointingDevice`,
+ *  https://github.com/WebKit/WebKit/blob/main/Source/WebKit/WebProcess/WebPage/ios/WebPageIOS.mm). */
+export function primaryPointerFine(win: Window): boolean {
+  return typeof win.matchMedia === "function" && win.matchMedia("(pointer: fine)").matches;
+}
+
+/** Whether a mouse or trackpad is attached; a Pencil never answers it, unlike
+ *  `any-pointer: fine` (`hoverSupportedByAnyAvailablePointingDevice`, same file). */
+function accessoryMouse(win: Window): boolean {
+  return typeof win.matchMedia === "function" && win.matchMedia("(any-hover: hover)").matches;
+}
+
+export interface KeyboardPresenceTracker extends KeyboardPresence {
+  /** Whether the visual-viewport keyboard inset is to be ignored. */
+  insetSuppressed(): boolean;
+  noteKeydown(ev: KeyboardEvent): void;
+  noteSoftKeyboard(heightPx: number, editableFocused: boolean): void;
+}
+
+export interface KeyboardPresenceOptions {
+  readonly win: Window & typeof globalThis;
+  /** Never the suppressed inset: the suppression itself reads this tracker. */
+  readonly softKeyboardHeight: () => number;
+}
+
+/** A key that is not text: a modifier chord, navigation, Escape, Tab or a
+ *  function key. An on-screen keyboard can send some of these too (Android's
+ *  `InputConnection.sendKeyEvent`, https://developer.android.com/reference/android/view/inputmethod/InputConnection#sendKeyEvent(android.view.KeyEvent)),
+ *  which the empty `code`, the height gate and `isOnScreenTab` answer. */
+function looksLikeHardwareKey(ev: KeyboardEvent): boolean {
+  if (ev.ctrlKey || ev.metaKey || ev.altKey) {
+    return true;
+  }
+  switch (ev.key) {
+    case "ArrowUp":
+    case "ArrowDown":
+    case "ArrowLeft":
+    case "ArrowRight":
+    case "Escape":
+    case "Tab":
+    case "Home":
+    case "End":
+    case "PageUp":
+    case "PageDown":
+      return true;
+    default:
+      return /^F\d{1,2}$/.test(ev.key);
+  }
+}
+
+/** An unmodified Tab: the one hardware-only key on the iPad's full on-screen
+ *  keyboard, which reports no inset while undocked or split (`_keyboardChangedWithInfo:`,
+ *  https://github.com/WebKit/WebKit/blob/main/Source/WebKit/UIProcess/API/ios/WKWebViewIOS.mm).
+ *  Its code cannot tell: WebKit derives a soft key's code from its character
+ *  (`initWithKeyEventType:`, https://github.com/WebKit/WebKit/blob/main/Source/WebCore/platform/ios/WebEvent.mm). */
+function isOnScreenTab(ev: KeyboardEvent): boolean {
+  return ev.key === "Tab" && !ev.ctrlKey && !ev.metaKey && !ev.altKey;
+}
+
+export function createKeyboardPresence(opts: KeyboardPresenceOptions): KeyboardPresenceTracker {
+  const { win } = opts;
+  let seen = false;
+  const isEditable = (target: EventTarget | null): boolean =>
+    target instanceof win.HTMLElement &&
+    (target.isContentEditable ||
+      target instanceof win.HTMLInputElement ||
+      target instanceof win.HTMLTextAreaElement);
+  return {
+    hardwareSeen: () => seen,
+    likely: () => seen || primaryPointerFine(win),
+    // createKeyboardInsets owns the phantom iPad inset this defends against; it
+    // comes with a Magic Keyboard, whose trackpad any-hover sees.
+    insetSuppressed: () => seen || primaryPointerFine(win) || accessoryMouse(win),
+    noteKeydown(ev) {
+      // An on-screen key has no physical key, so Chromium Android leaves `code`
+      // empty (it fills it from the scan code alone:
+      // https://chromium.googlesource.com/chromium/src/+/main/components/input/web_input_event_builders_android.cc),
+      // and any such key clears a latch. A keyboard app that stamps a real scan
+      // code on its own arrow can latch until its next letter. WebKit never
+      // reports an empty code (`codeForKeyEvent`,
+      // https://github.com/WebKit/WebKit/blob/main/Source/WebCore/platform/ios/PlatformEventFactoryIOS.mm),
+      // so on iOS "Unidentified", the height gate and the Tab rule below decide.
+      if (ev.code === "" || ev.key === "Unidentified") {
+        seen = false;
+        return;
+      }
+      if (
+        looksLikeHardwareKey(ev) &&
+        (!isEditable(ev.target) ||
+          (opts.softKeyboardHeight() < SOFT_KEYBOARD_MIN_PX && !isOnScreenTab(ev)))
+      ) {
+        seen = true;
+      }
+    },
+    noteSoftKeyboard(heightPx, editableFocused) {
+      // With a mouse or trackpad attached the reading may be that phantom.
+      if (heightPx >= SOFT_KEYBOARD_MIN_PX && editableFocused && !accessoryMouse(win)) {
+        seen = false;
+      }
+    },
+  };
+}

package/src/kernel/pane.ts

@@ -14,6 +14,7 @@ import { createRegions } from "./regions.js";
 import { createAnnouncer, createPaneTablist, type PaneTablist } from "./a11y.js";
 import { createConnState } from "./conn-state.js";
 import { selectionTextWithin } from "./selection.js";
+import { primaryPointerFine } from "./keyboard-presence.js";
 import { windowOf } from "./realm.js";
 import {
   createCleanupScope,
@@ -23,6 +24,7 @@ import {
 } from "./feature-host.js";
 import type {
   CreateTerminalOptions,
+  KeyboardPresence,
   PaneHandle,
   PaneSide,
   SessionRef,
@@ -148,6 +150,9 @@ export interface PaneServices {
   /** The document's keyboard geometry, published on the shell root, which this
    *  pane's root inherits rather than publishes. */
   readonly keyboardInsets: KeyboardInsets;
+  readonly keyboard: KeyboardPresence;
+  /** The document's last press landed inside the shell root. */
+  pressedInsideShell(): boolean;
   /** This pane's base title (the served `<title>`, or its program's OSC 0/2). */
   titleBase(text: string): void;
   readonly loading: PaneLoading;
@@ -226,13 +231,6 @@ export interface PaneKernel extends PaneHandle {
   destroy(): void;
 }
 
-/** Whether `win` has a fine pointer, and with it a hardware keyboard. Read as
- *  `any-pointer: fine` rather than from pointerType because iPadOS reports a
- *  COARSE primary pointer even with a trackpad attached. */
-export function hasFinePointer(win: Window): boolean {
-  return typeof win.matchMedia === "function" && win.matchMedia("(any-pointer: fine)").matches;
-}
-
 /** The consumer's theme as custom properties on `root`, so the whole subtree
  *  inherits them over the token defaults of css/00-tokens.css. */
 export function applyTheme(root: HTMLElement, theme: CreateTerminalOptions["theme"]): void {
@@ -808,12 +806,49 @@ function buildPaneInto(
   let pointerDownX = 0;
   let pointerDownY = 0;
   let pointerDownTime = 0;
+  let pressMadeSelection = false;
+  const ownsSelection = (): boolean => selectionTextWithin(outputEl) !== "";
   function focusTerminal(): void {
     if (destroyed) {
       return;
     }
     input.focus({ preventScroll: true });
   }
+  /** A gesture's focus, never over a selection: iOS refuses every selection
+   *  gesture outside a focused editable (`textInteractionGesture:shouldBeginAtPoint:`,
+   *  https://github.com/WebKit/WebKit/blob/main/Source/WebKit/UIProcess/ios/WKContentViewInteraction.mm). */
+  function focusFromGesture(): void {
+    if (pressMadeSelection || ownsSelection()) {
+      return;
+    }
+    focusTerminal();
+  }
+  // At the PRESS, not the tap: WebKit decides about 500ms into a long-press
+  // whether it may select (focusFromGesture), and the input must be gone by then.
+  function releaseFocusOnPress(e: PointerEvent): void {
+    if (!services.keyboard.hardwareSeen() || doc.activeElement !== input) {
+      return;
+    }
+    if (e.pointerType !== "touch" && primaryPointerFine(win)) {
+      return;
+    }
+    if (!(e.target instanceof win.Node) || !outputEl.contains(e.target)) {
+      return;
+    }
+    if (isLinkTarget(win, e.target)) {
+      return;
+    }
+    input.blur();
+  }
+  doc.addEventListener(
+    "selectionchange",
+    () => {
+      if (pressHoldsFocus && ownsSelection()) {
+        pressMadeSelection = true;
+      }
+    },
+    { signal },
+  );
   // A passive listener on the pane root: a touch that starts a native selection
   // never focuses the textarea, so focus alone would leave the touched pane
   // unselected.
@@ -832,6 +867,8 @@ function buildPaneInto(
       pointerDownY = e.clientY;
       pointerDownTime = e.timeStamp;
       pressHoldsFocus = true;
+      pressMadeSelection = false;
+      releaseFocusOnPress(e);
     },
     { passive: true, signal },
   );
@@ -841,7 +878,9 @@ function buildPaneInto(
   termWrap.addEventListener(
     "pointerup",
     (e) => {
-      if (e.pointerType !== "touch") {
+      // With a hardware keyboard seen, a tap is the platform's: the press already
+      // released focus, and the uncancelled mousedown lets it deselect natively.
+      if (e.pointerType !== "touch" || services.keyboard.hardwareSeen()) {
         return;
       }
       if (isLinkTarget(win, e.target)) {
@@ -856,19 +895,15 @@ function buildPaneInto(
       if (e.timeStamp - pointerDownTime > TAP_MAX_MS) {
         return;
       }
-      // A clean tap while text is selected means "done selecting": iOS otherwise
-      // leaves the selection stuck, because the synthetic mousedown cancelled
-      // below also suppresses the platform's own tap-to-deselect. A deselect tap
-      // must not pop the soft keyboard, unless a hardware keyboard is present.
+      // A clean tap while text is selected means "done selecting": the synthetic
+      // mousedown cancelled below also suppresses iOS's own tap-to-deselect. It
+      // does not pop the soft keyboard.
       const sel = doc.getSelection();
       if (sel && !sel.isCollapsed) {
         sel.removeAllRanges();
-        if (hasFinePointer(win)) {
-          focusTerminal();
-        }
         return;
       }
-      focusTerminal();
+      focusFromGesture();
     },
     { passive: true, signal },
   );
@@ -876,10 +911,10 @@ function buildPaneInto(
     "mousedown",
     (e) => {
       if (lastPointerType === "touch") {
-        // Cancel the synthetic mousedown after a touch tap so iOS keeps the
-        // keyboard up, except with a fine pointer, where suppressing it defeated
-        // the native focus.
-        if (!hasFinePointer(win)) {
+        // Cancelling the synthetic mousedown after a tap keeps the soft keyboard
+        // up. With a hardware keyboard likely there is none to keep, and the
+        // uncancelled default is what moves focus off the textarea.
+        if (!services.keyboard.likely()) {
           e.preventDefault();
         }
         return;
@@ -908,23 +943,30 @@ function buildPaneInto(
         win.open(link.href, "_blank", "noopener,noreferrer");
         return;
       }
-      if (lastPointerType === "touch" && !hasFinePointer(win)) {
+      // A touch's synthetic click: the pointerup handler owned that gesture.
+      if (lastPointerType === "touch") {
+        return;
+      }
+      // An iPad trackpad click releases focus as a tap does once a hardware
+      // keyboard is seen; a desktop mouse keeps click-to-focus.
+      if (services.keyboard.hardwareSeen() && !primaryPointerFine(win)) {
         return;
       }
       const sel = doc.getSelection();
       if (sel && sel.toString().length > 0) {
         return;
       }
-      focusTerminal();
+      focusFromGesture();
     },
     { signal },
   );
 
-  // A mouse gesture over `.term-output` leaves focus on the body, so typing
-  // silently does nothing (and the two shortcuts on the keydown chain with it).
-  // Focusing on the press would collapse the selection, so the browser's model
+  const keysUnclaimed = (): boolean =>
+    (doc.getSelection()?.toString() ?? "") === "" &&
+    services.shell.selected() === services.side &&
+    services.pressedInsideShell();
+  // Focusing on the press would collapse a selection, so the browser's model
   // stands and typing takes the keyboard back, as Windows Terminal does.
-  const ownsSelection = (): boolean => selectionTextWithin(outputEl) !== "";
   doc.addEventListener(
     "keydown",
     (ev: KeyboardEvent) => {
@@ -945,7 +987,7 @@ function buildPaneInto(
       if (composition.isComposing()) {
         return;
       }
-      if (!ownsSelection()) {
+      if (!ownsSelection() && !keysUnclaimed()) {
         return;
       }
       // Features while the selection is STILL INTACT and before the modifier
@@ -953,6 +995,24 @@ function buildPaneInto(
       if (runKeydownChain(ev)) {
         return;
       }
+      // Composition happens only in a focused editable (a body target gets no
+      // beforeinput or input, `_tryToHandlePressesEvent:` in
+      // https://github.com/WebKit/WebKit/blob/main/Source/WebKit/UIProcess/ios/WKContentViewInteraction.mm),
+      // so a dead key or an IME takes focus and passes through, ahead of the
+      // modifier gate that would keep Option+e.
+      if (
+        ev.key === "Dead" ||
+        ev.key === "Process" ||
+        ev.isComposing ||
+        // eslint-disable-next-line @typescript-eslint/no-deprecated -- the only carrier of the IME-commit fact; see IME_COMMIT_KEYCODE
+        ev.keyCode === IME_COMMIT_KEYCODE
+      ) {
+        if (ownsSelection()) {
+          doc.getSelection()?.removeAllRanges();
+        }
+        focusTerminal();
+        return;
+      }
       // Decided before taking focus, because a bare modifier press (Shift on its
       // way to Shift+click) must leave the selection alone. Computed only for an
       // "ignore", so the encoder always wins a key it maps.
@@ -980,7 +1040,9 @@ function buildPaneInto(
       }
       if (char !== null) {
         // No `input` event is coming for a key that targeted the body, so send it
-        // here; preventDefault makes that exactly once BY SPEC.
+        // here. Cancelling the keydown cancels its insertion
+        // (https://w3c.github.io/uievents/#event-type-keydown), which Chromium
+        // would otherwise route into the textarea just focused: one copy, not two.
         ev.preventDefault();
         sendText(normalizeTypedText(char));
         return;
@@ -1143,7 +1205,7 @@ function buildPaneInto(
           engine.connection.reconnectNow();
         }
         if (services.shell.selected() === services.side) {
-          focusTerminal();
+          focusFromGesture();
         }
         return;
       }
@@ -1158,7 +1220,7 @@ function buildPaneInto(
         engine.connection.reconnectNow();
       }
       if (services.shell.selected() === services.side) {
-        focusTerminal();
+        focusFromGesture();
       }
     },
     { signal },

package/src/kernel/shell.ts

@@ -6,11 +6,11 @@ import {
 import {
   applyTheme,
   buildPane,
-  hasFinePointer,
   type PaneKernel,
   type PaneServices,
   type StoreRegistry,
 } from "./pane.js";
+import { createKeyboardPresence } from "./keyboard-presence.js";
 import { createStatusShare } from "./status-share.js";
 import { browserNotifierEnv, createNotifier } from "./notify.js";
 import { attachLoadingStatus, DEFAULT_LOADING_MESSAGES } from "./loading-status.js";
@@ -269,17 +269,54 @@ function createShellInto(
     });
   }
   const paneOpts: CreateTerminalOptions = splitEnabled ? { ...opts, layout: "container" } : opts;
+  // Called only from a keydown, so keyboardInsets below exists by then.
+  const keyboardPresence = createKeyboardPresence({
+    win,
+    softKeyboardHeight: () => keyboardInsets.softKeyboardHeight(),
+  });
+  const paneInputFocused = (): boolean => {
+    const active = doc.activeElement;
+    return (
+      active instanceof win.HTMLTextAreaElement &&
+      active.classList.contains("term-input") &&
+      shellRoot.contains(active)
+    );
+  };
   // The visual viewport is the document's, so its geometry is read once and
   // published on the outermost root, which the shell's chrome and every pane
   // inherit; published on a pane root it would never reach the chrome beside
   // the panes.
   const keyboardInsets = createKeyboardInsets({
     root: shellRoot,
-    suppressKeyboardInset: () => hasFinePointer(win),
+    suppressKeyboardInset: () => keyboardPresence.insetSuppressed(),
+    onSoftKeyboard(heightPx) {
+      keyboardPresence.noteSoftKeyboard(heightPx, paneInputFocused());
+    },
   });
   held.push(() => {
     keyboardInsets.teardown();
   });
+  const docListeners = new AbortController();
+  held.push(() => {
+    docListeners.abort();
+  });
+  doc.addEventListener(
+    "keydown",
+    (ev) => {
+      keyboardPresence.noteKeydown(ev);
+    },
+    { capture: true, signal: docListeners.signal },
+  );
+  // A press in the host page leaves the keys with the host, so the panes' body
+  // keydown path arms only after a press inside the terminal.
+  let pressedInsideShell = false;
+  doc.addEventListener(
+    "pointerdown",
+    (ev) => {
+      pressedInsideShell = ev.target instanceof win.Node && shellRoot.contains(ev.target);
+    },
+    { capture: true, passive: true, signal: docListeners.signal },
+  );
 
   const loadingStatus = attachLoadingStatus(opts.loading, {
     ...DEFAULT_LOADING_MESSAGES,
@@ -785,6 +822,10 @@ function createShellInto(
     : disabledSplit();
   const shellContext: ShellContext = {
     root: shellRoot,
+    keyboard: {
+      hardwareSeen: () => keyboardPresence.hardwareSeen(),
+      likely: () => keyboardPresence.likely(),
+    },
     pane: (side) => paneAt(side) ?? null,
     panes: builtPanes,
     selected: () => selectedSide,
@@ -841,6 +882,8 @@ function createShellInto(
       scrollbackLines,
       narrowProbe: () => isNarrow(shellRoot.clientWidth, slot.root.clientHeight),
       keyboardInsets,
+      keyboard: shellContext.keyboard,
+      pressedInsideShell: () => pressedInsideShell,
       titleBase(text) {
         slot.baseTitle = text;
         paintTitle();

package/src/kernel/types.ts

@@ -280,11 +280,20 @@ export interface Notifier {
   forget(id: string): void;
 }
 
+/** Whether the page has a hardware keyboard, as far as its key events tell. */
+export interface KeyboardPresence {
+  /** A key no on-screen keyboard produces is the latest keyboard evidence seen. */
+  hardwareSeen(): boolean;
+  /** `hardwareSeen()`, or the primary pointer is fine. */
+  likely(): boolean;
+}
+
 /** The shell a feature reaches through `ctx.shell`: the pane kernels and the
  *  facts shared between them. */
 export interface ShellContext {
   /** The shell root; the pane root in the direct-root topology. */
   readonly root: HTMLElement;
+  readonly keyboard: KeyboardPresence;
   /** Null while that side has no built kernel. */
   pane(side: PaneSide): PaneHandle | null;
   /** Built panes, left first. */

package/src/viewport.ts

@@ -27,12 +27,17 @@ export interface KeyboardInsetsOptions {
   /** Ignore the visualViewport keyboard geometry (a hardware-keyboard device
    *  has no soft keyboard to accommodate). */
   suppressKeyboardInset?: () => boolean;
+  /** Called with `softKeyboardHeight()` at every reading, before
+   *  `suppressKeyboardInset` is consulted for it. */
+  onSoftKeyboard?: (heightPx: number) => void;
 }
 
 /** The document's one reading of its visual viewport. */
 export interface KeyboardInsets {
   /** The latest geometry; zero where the window has no visual viewport. */
   current(): KeyboardGeometry;
+  /** The visual-viewport keyboard inset now in CSS px, never suppressed. */
+  softKeyboardHeight(): number;
   /** Call `fn` with the geometry on every visual-viewport resize and scroll, on
    *  every window focus and bfcache restore, and on every `refresh()`; returns
    *  the release. */
@@ -110,16 +115,21 @@ export function createKeyboardInsets(opts: KeyboardInsetsOptions): KeyboardInset
     root.style.removeProperty("--vv-top");
   }
 
+  function readVisual(): KeyboardGeometry {
+    return vv
+      ? {
+          top: Math.max(0, Math.round(vv.offsetTop)),
+          bottom: Math.max(0, Math.round(win.innerHeight - vv.offsetTop - vv.height)),
+        }
+      : { top: 0, bottom: 0 };
+  }
+
   function update(): void {
+    const raw = readVisual();
+    opts.onSoftKeyboard?.(raw.bottom);
     // iPadOS has been seen to report a keyboard-sized shrink with no keyboard
     // shown and pin it, which is what suppressKeyboardInset defends against.
-    geometry =
-      !vv || suppressKeyboardInset()
-        ? { top: 0, bottom: 0 }
-        : {
-            top: Math.max(0, Math.round(vv.offsetTop)),
-            bottom: Math.max(0, Math.round(win.innerHeight - vv.offsetTop - vv.height)),
-          };
+    geometry = suppressKeyboardInset() ? { top: 0, bottom: 0 } : raw;
     root.style.setProperty("--kb-inset", `${geometry.bottom}px`);
     root.style.setProperty("--vv-top", `${geometry.top}px`);
     for (const fn of [...subscribers]) {
@@ -144,6 +154,7 @@ export function createKeyboardInsets(opts: KeyboardInsetsOptions): KeyboardInset
 
   return {
     current: () => geometry,
+    softKeyboardHeight: () => readVisual().bottom,
     onChange(fn) {
       subscribers.add(fn);
       return () => {