@cplieger/web-terminal-ui 8.0.1 → 8.1.1

package/src/kernel/pane.ts

@@ -6,7 +6,7 @@ import {
   type TerminalEngine,
 } from "@cplieger/web-terminal-engine";
 import { createComposition } from "../composition.js";
-import { createViewport } from "../viewport.js";
+import { createViewport, type KeyboardInsets } from "../viewport.js";
 import { INPUT_PLACEHOLDER, resetToPlaceholder } from "../input-placeholder.js";
 import { createBus } from "./bus.js";
 import { TAP_MAX_MS, TAP_MOVEMENT_PX, isLinkTarget } from "./gesture.js";
@@ -143,6 +143,9 @@ export interface PaneServices {
   /** The narrow classification for this pane (the shell root's width, this
    *  pane's height). */
   narrowProbe(): boolean;
+  /** The document's keyboard geometry, published on the shell root, which this
+   *  pane's root inherits rather than publishes. */
+  readonly keyboardInsets: KeyboardInsets;
   /** This pane's base title (the served `<title>`, or its program's OSC 0/2). */
   titleBase(text: string): void;
   readonly loading: PaneLoading;
@@ -209,6 +212,9 @@ export interface PaneKernel extends PaneHandle {
    *  from the moment the split closes rather than from the class the display
    *  gets when the closing transition ends. */
   setHidden(value: boolean): void;
+  /** The shell is about to slide this pane's box: nothing it measures from now
+   *  until its viewport settles is final, and the settle sends the size. */
+  holdGeometry(): void;
   /** Whether this pane's input is a stop in the document's Tab order. On while
    *  the split is open and the pane shows a tab, so Tab runs left input, divider,
    *  right input, chrome; off otherwise, where typing or a click enters the one
@@ -218,6 +224,13 @@ 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 {
@@ -456,7 +469,9 @@ function buildPaneInto(
     termWrap.classList.toggle("wt-mouse-app", engine.modes.getMouseMode() !== 0);
   }
   function measurableSize(): { cols: number; rows: number } | null {
-    if (!fontsLoaded || viewport.isInTransition()) {
+    // A pane hidden by a closed split is `display: none`: the cell width it would
+    // measure is 0, and the first render after a reveal would lay out on it.
+    if (!fontsLoaded || hidden || viewport.isInTransition()) {
       return null;
     }
     engine.renderer.updateFontMetrics();
@@ -764,10 +779,7 @@ function buildPaneInto(
 
   // On touch the output is the native text-selection surface, so this does the
   // MINIMUM: it opens the keyboard on a clean tap and otherwise gets out of the
-  // browser's way. `any-pointer: fine` rather than pointerType because iPadOS
-  // reports a COARSE primary pointer even with a trackpad attached.
-  const hasFinePointer = (): boolean =>
-    typeof win.matchMedia === "function" && win.matchMedia("(any-pointer: fine)").matches;
+  // browser's way.
   let lastPointerType = "mouse";
   let pointerDownX = 0;
   let pointerDownY = 0;
@@ -827,7 +839,7 @@ function buildPaneInto(
       const sel = doc.getSelection();
       if (sel && !sel.isCollapsed) {
         sel.removeAllRanges();
-        if (hasFinePointer()) {
+        if (hasFinePointer(win)) {
           focusTerminal();
         }
         return;
@@ -843,7 +855,7 @@ function buildPaneInto(
         // 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()) {
+        if (!hasFinePointer(win)) {
           e.preventDefault();
         }
         return;
@@ -872,7 +884,7 @@ function buildPaneInto(
         win.open(link.href, "_blank", "noopener,noreferrer");
         return;
       }
-      if (lastPointerType === "touch" && !hasFinePointer()) {
+      if (lastPointerType === "touch" && !hasFinePointer(win)) {
         return;
       }
       const sel = doc.getSelection();
@@ -956,9 +968,9 @@ function buildPaneInto(
 
   const viewport = createViewport({
     termWrap,
-    root,
+    box: root,
+    keyboard: services.keyboardInsets,
     scroll: engine.scroll,
-    suppressKeyboardInset: hasFinePointer,
     onSettled() {
       // The settle is the one resize a keyboard slide or rotation should cost;
       // sendResize deduplicates.
@@ -1157,10 +1169,13 @@ function buildPaneInto(
       return;
     }
     detachSession();
+    if (activeSession !== null) {
+      services.noteEpoch(activeSession.id, engine.connection.serverEpochOf(activeSession.id));
+    }
     activeSession = session;
-    // A session another pane forgot arrives with the epoch that pane knew, or the
-    // first resumeAck has nothing to compare against and a server restart between
-    // the two attaches goes undetected.
+    // A session that left another pane, emptied or replaced, arrives with the epoch
+    // that pane knew, or the first resumeAck has nothing to compare against and a
+    // server restart between the two attaches goes undetected.
     const epoch = services.knownEpoch(session.id);
     if (epoch !== 0) {
       engine.connection.adoptPersistedEpoch(session.id, epoch);
@@ -1398,6 +1413,11 @@ function buildPaneInto(
     setHidden(value) {
       hidden = value;
     },
+    holdGeometry() {
+      if (!destroyed) {
+        viewport.beginTransition();
+      }
+    },
     setTabStop(value) {
       input.tabIndex = value ? 0 : -1;
     },

package/src/kernel/shell.ts

@@ -6,6 +6,7 @@ import {
 import {
   applyTheme,
   buildPane,
+  hasFinePointer,
   type PaneKernel,
   type PaneServices,
   type StoreRegistry,
@@ -28,6 +29,7 @@ import { createRegions, type Regions } from "./regions.js";
 import { createAnnouncer, createTablist, type Announcer, type PaneTablist } from "./a11y.js";
 import { createSplitHandle, type SplitHandle } from "./split-handle.js";
 import { windowOf } from "./realm.js";
+import { createKeyboardInsets } from "../viewport.js";
 import type {
   AttentionOptions,
   AttentionReporter,
@@ -132,16 +134,19 @@ type PaneFailure =
   | { readonly phase: "kernel-init"; readonly cause: unknown }
   | { readonly phase: "feature-setup"; readonly feature: string; readonly cause: unknown };
 
-/** A close whose columns are still sliding: the model is closed already and the
- *  display finishes when the transition ends, on the fallback timer, or on
- *  `settle()`. */
-interface ClosingTransition {
-  /** The ratio the columns slide to: 1 when the left pane survives, 0 when the right does. */
-  readonly toward: 0 | 1;
+/** An open or a close whose columns are still sliding: the model is in its new
+ *  state already and the display finishes when the transition ends, on the
+ *  fallback timer, or on `settle()`. */
+interface Slide {
   /** Finish the display now. */
-  settle(): void;
+  readonly settle: () => void;
   /** Drop the pending finish without running it. */
-  abort(): void;
+  readonly abort: () => void;
+}
+
+interface ClosingTransition extends Slide {
+  /** The ratio the columns slide to: 1 when the left pane survives, 0 when the right does. */
+  readonly toward: 0 | 1;
 }
 
 /** A shell-scoped feature's registration on every built pane and on every pane
@@ -246,6 +251,7 @@ function createShellInto(
         "wt-narrow",
         "wt-split-open",
         "wt-split-collapsed",
+        "wt-split-opening",
         "wt-split-closing",
       );
       shellRoot.style.removeProperty("--wt-split-ratio");
@@ -263,6 +269,17 @@ function createShellInto(
     });
   }
   const paneOpts: CreateTerminalOptions = splitEnabled ? { ...opts, layout: "container" } : opts;
+  // 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),
+  });
+  held.push(() => {
+    keyboardInsets.teardown();
+  });
 
   const loadingStatus = attachLoadingStatus(opts.loading, {
     ...DEFAULT_LOADING_MESSAGES,
@@ -308,9 +325,11 @@ function createShellInto(
   const selectionListeners = new Set<(side: PaneSide) => void>();
   const panesListeners = new Set<() => void>();
   let closing: ClosingTransition | null = null;
+  let opening: Slide | null = null;
   held.push(() => {
     closing?.abort();
     closing = null;
+    opening?.abort();
   });
   const selectedPane = (): PaneKernel => {
     const p = paneAt(selectedSide) ?? slots[0]?.kernel ?? undefined;
@@ -420,20 +439,18 @@ function createShellInto(
   function applyRatioVar(): void {
     shellRoot.style.setProperty("--wt-split-ratio", String(closing?.toward ?? effectiveRatio()));
   }
-  /** How long a close slides, from the same token the stylesheet's transition
-   *  reads; 0 without `wt-animate`, and the change is then instant. */
-  function closingDurationMs(): number {
+  /** How long an open or a close slides, from the same token the stylesheet's
+   *  transition reads; 0 without `wt-animate`, and the change is then instant. */
+  function slideDurationMs(): number {
     if (!shellRoot.classList.contains("wt-animate")) {
       return 0;
     }
     return cssTimeMs(win.getComputedStyle(shellRoot).getPropertyValue("--dur-standard"));
   }
-  function beginClosing(toward: 0 | 1, durationMs: number, tail: () => void): void {
-    shellRoot.classList.add("wt-split-closing");
+  function slideFor(durationMs: number, tail: () => void): Slide {
     const stop = (): void => {
       win.clearTimeout(timer);
       shellRoot.removeEventListener("transitionend", onEnd);
-      closing = null;
     };
     const settle = (): void => {
       stop();
@@ -447,7 +464,52 @@ function createShellInto(
     shellRoot.addEventListener("transitionend", onEnd);
     // An engine that applies a track-list change at once fires no transitionend.
     const timer = win.setTimeout(settle, durationMs);
-    closing = { toward, settle, abort: stop };
+    return { settle, abort: stop };
+  }
+  function beginClosing(toward: 0 | 1, durationMs: number, tail: () => void): void {
+    shellRoot.classList.add("wt-split-closing");
+    const slide = slideFor(durationMs, () => {
+      closing = null;
+      tail();
+    });
+    closing = {
+      toward,
+      settle: slide.settle,
+      abort: () => {
+        slide.abort();
+        closing = null;
+      },
+    };
+  }
+  /** The divider comes in from the row's right edge to the share the model
+   *  already holds, and the sizes were announced at that share: the slide's
+   *  start shows the new pane 0 px wide, so the panes hold their geometry until
+   *  it is over, or a socket opening meanwhile would size its PTY to that. */
+  function beginOpening(durationMs: number): void {
+    for (const p of builtPanes()) {
+      p.holdGeometry();
+    }
+    shellRoot.style.setProperty("--wt-split-ratio", "1");
+    // The read commits the start as a style of its own; without it the slide
+    // would start from the closed view's single column.
+    shellRoot.getBoundingClientRect();
+    shellRoot.classList.add("wt-split-opening");
+    const slide = slideFor(durationMs, () => {
+      opening = null;
+      shellRoot.classList.remove("wt-split-opening");
+      for (const p of builtPanes()) {
+        p.announceSize();
+      }
+    });
+    opening = {
+      settle: slide.settle,
+      abort: () => {
+        slide.abort();
+        opening = null;
+        shellRoot.classList.remove("wt-split-opening");
+      },
+    };
+    applyRatioVar();
   }
   function fireSplitChange(): void {
     if (changeListeners.size === 0) {
@@ -745,6 +807,9 @@ function createShellInto(
       knownEpoch.delete(sessionId);
       keeper?.forget(sessionId);
     },
+    chromeResized() {
+      keyboardInsets.refresh();
+    },
     attention,
     subscribeStatus: (path, callbacks) => statusShare.subscribe(path, callbacks),
     notifications,
@@ -775,6 +840,7 @@ function createShellInto(
       managed,
       scrollbackLines,
       narrowProbe: () => isNarrow(shellRoot.clientWidth, slot.root.clientHeight),
+      keyboardInsets,
       titleBase(text) {
         slot.baseTitle = text;
         paintTitle();
@@ -1053,6 +1119,10 @@ function createShellInto(
     for (const p of builtPanes()) {
       p.announceSize();
     }
+    const slideMs = collapsed ? 0 : slideDurationMs();
+    if (slideMs > 0) {
+      beginOpening(slideMs);
+    }
     announcer?.announce("Split open");
     firePanesChange();
     fireSplitChange();
@@ -1065,7 +1135,10 @@ function createShellInto(
     keepFocusOn(survivor, (el) => leaving.root.contains(el) || isHandle(el));
     leaving.kernel?.clearActiveSession();
     leaving.kernel?.setHidden(true);
-    const durationMs = leaving.failed || collapsed ? 0 : closingDurationMs();
+    // The closing class carries the same transition, so a close during the
+    // open's slide turns it around from where the columns are.
+    opening?.abort();
+    const durationMs = leaving.failed || collapsed ? 0 : slideDurationMs();
     const tail = (): void => {
       if (leaving.failed) {
         teardownSlot(leaving);
@@ -1131,6 +1204,8 @@ function createShellInto(
     if (!isRatio(ratio) || !splitOpen || collapsed || destroyed) {
       return false;
     }
+    // A drag or a key moves the divider at once, not through the open's slide.
+    opening?.settle();
     if (commit) {
       committedRatio = ratio;
       previewRatio = null;

package/src/kernel/split-handle.ts

@@ -9,6 +9,9 @@ const DRAG_START_PX = 8;
 const RESIZE_INTERVAL_MS = 100;
 /** One arrow press moves the divider this far: two fallback cells of 8 px. */
 const KEY_STEP_PX = 16;
+/** Pointer travel past a pane's minimum width that holds the pane AT the
+ *  minimum, so a drag can set it; only past this does a release close. */
+const GRACE_PX = 120;
 
 const NUDGE_KEYS: ReadonlySet<string> = new Set(["ArrowLeft", "ArrowRight", "Home", "End"]);
 
@@ -31,12 +34,20 @@ interface Drag {
   readonly span: number;
   /** Whether the pointer has travelled DRAG_START_PX yet. */
   moving: boolean;
-  /** The pane under the minimum right now: dimmed, and closed on release. */
+  /** The pane past the grace zone right now: dimmed, and closed on release. */
   squeezed: PaneSide | null;
-  /** Whether any move of this drag put a pane under the minimum. */
+  /** Whether the divider is held at a pane's minimum right now. */
+  held: boolean;
+  /** Whether any move of this drag went past the grace zone. */
   dipped: boolean;
 }
 
+interface Placement {
+  readonly ratio: number;
+  readonly squeezed: PaneSide | null;
+  readonly held: boolean;
+}
+
 function clamp01(value: number): number {
   return Math.min(Math.max(value, 0), 1);
 }
@@ -107,12 +118,22 @@ export function createSplitHandle(shell: SplitHandleShell): SplitHandle {
     announceNow();
   }
 
-  function squeezedAt(ratio: number, span: number): PaneSide | null {
-    const leftPx = ratio * span;
-    if (leftPx < MIN_PANE_PX) {
-      return "left";
+  function placement(leftPx: number, span: number): Placement {
+    const leftPast = MIN_PANE_PX - leftPx;
+    const rightPast = MIN_PANE_PX - (span - leftPx);
+    if (leftPast > GRACE_PX) {
+      return { ratio: clamp01(leftPx / span), squeezed: "left", held: false };
+    }
+    if (rightPast > GRACE_PX) {
+      return { ratio: clamp01(leftPx / span), squeezed: "right", held: false };
+    }
+    if (leftPast > 0) {
+      return { ratio: MIN_PANE_PX / span, squeezed: null, held: true };
+    }
+    if (rightPast > 0) {
+      return { ratio: (span - MIN_PANE_PX) / span, squeezed: null, held: true };
     }
-    return span - leftPx < MIN_PANE_PX ? "right" : null;
+    return { ratio: leftPx / span, squeezed: null, held: false };
   }
   function paintSqueezed(side: PaneSide | null): void {
     for (const s of ["left", "right"] as const) {
@@ -156,6 +177,7 @@ export function createSplitHandle(shell: SplitHandleShell): SplitHandle {
       span,
       moving: false,
       squeezed: null,
+      held: false,
       dipped: false,
     };
     el.classList.add("wt-handle-held");
@@ -177,9 +199,10 @@ export function createSplitHandle(shell: SplitHandleShell): SplitHandle {
       }
       d.moving = true;
     }
-    const ratio = clamp01((d.startLeftPx + dx) / d.span);
+    const { ratio, squeezed, held } = placement(d.startLeftPx + dx, d.span);
     split.setRatio(ratio, false);
-    d.squeezed = squeezedAt(ratio, d.span);
+    d.squeezed = squeezed;
+    d.held = held;
     if (d.squeezed !== null) {
       d.dipped = true;
     }
@@ -200,11 +223,12 @@ export function createSplitHandle(shell: SplitHandleShell): SplitHandle {
     if (d.squeezed !== null && split.closeSide(d.squeezed)) {
       return;
     }
-    // A drag that dipped under the minimum was a close gesture, so releasing
-    // above it, or a close the split refuses, cancels the drag rather than
-    // committing a share at or past the threshold.
+    // A drag that went past the grace zone was a close gesture, so releasing
+    // above the minimum, or a close the split refuses, cancels the drag rather
+    // than committing a share at or past the threshold. A release held at the
+    // minimum sets it.
     const state = split.state();
-    split.setRatio(d.dipped ? state.committedRatio : state.ratio, true);
+    split.setRatio(d.dipped && !d.held ? state.committedRatio : state.ratio, true);
     announceNow();
   }
   let nudgePending = false;

package/src/kernel/types.ts

@@ -199,7 +199,9 @@ export interface SplitController {
   isOpen(): boolean;
   /** Enabled, closed, and the pane row is wide enough for two panes. */
   canOpen(): boolean;
-  /** True when the split is now open at a 50/50 share; false when nothing changed. */
+  /** True when the split is now open at a 50/50 share; false when nothing changed.
+   *  The state is open at once; with `wt-animate` on the shell root the divider
+   *  slides in from the right edge over `--dur-standard`. */
   open(): boolean;
   /** The selected pane fills the view; false when nothing changed. The state is
    *  closed at once; with `wt-animate` on the shell root the grid columns slide
@@ -303,6 +305,11 @@ export interface ShellContext {
    *  built pane's connection other than `side` (whose own `clearActiveSession()`
    *  already did it), and the scrollback keeper's forget. */
   dropSessionExcept(sessionId: string, side: PaneSide): void;
+  /** Call after changing what the panes' term wraps clear at the bottom (the
+   *  `--wt-tabbar-h` or `--wt-reserve-bottom` set on `root`): every pane re-pins
+   *  its term wrap and sends its size once it settles. Nothing observes a term
+   *  wrap, so this call is how such a change reaches the panes. */
+  chromeResized(): void;
   /** Bind the page's attention surfaces (the document-title prefix, the app
    *  badge, the icon links) and get the reporter that drives them. The terminal
    *  is the only writer of `document.title`: a program's OSC 0/2 title replaces