@cplieger/web-terminal-ui 1.0.0

package/src/predict.ts

@@ -0,0 +1,183 @@
+// Predictive local echo (INPUT-01) — Mosh-style mini-VT that advances
+// a "predicted cursor" optimistically as the user types, before the
+// server's next screen frame confirms or contradicts the prediction.
+//
+// On the wire we still send everything through the connection module;
+// this is purely a local-render optimisation. The visible effect is
+// that the cursor moves immediately on each keystroke even on a 200 ms
+// link, so typing feels responsive instead of laggy.
+//
+// Scope (deliberately conservative — wrong predictions are worse than
+// missing predictions, since they look like the terminal is broken):
+//   - printable ASCII / UTF-8 codepoints: advance one cell per
+//     codepoint (approximate for fullwidth / combining marks; snaps
+//     to truth on next server frame).
+//   - Backspace (0x08) and DEL (0x7f): cursor back one cell.
+//   - CR (0x0d): col = 0.
+//   - LF (0x0a): row += 1 (clamped to height-1).
+//   - Anything else (ESC sequences, TAB, other C0): suspend prediction
+//     until the next server frame. Suspending hides the predicted
+//     cursor so the user sees only the server's truth.
+//
+// Each server screen frame resets the predicted cursor to the server's
+// reported position and re-arms prediction. So a wrong prediction is
+// at most one flushInterval (50 ms) old before correction.
+
+let predRow = 0;
+let predCol = 0;
+let predActive = false;
+let predPendingWrap = false; // matches server VT pendingWrap semantics
+let predFrozen = false; // true when server cursor is hidden (selection prompts)
+let cols = 80;
+let rows = 30;
+
+let onChange: (() => void) | null = null;
+
+/** Subscribe to predicted-cursor changes (the renderer registers
+ *  this so it can move its predicted-cursor overlay). */
+export function subscribe(cb: () => void): void {
+  onChange = cb;
+}
+
+/** Update the screen dimensions used for wrap calculations. Should be
+ *  called whenever the renderer learns a new size from the server. */
+export function setDimensions(c: number, r: number): void {
+  if (c > 0) {
+    cols = c;
+  }
+  if (r > 0) {
+    rows = r;
+  }
+  // Clamp predicted position to new bounds so a resize mid-typing
+  // doesn't leave predCol/predRow past the edge.
+  if (predCol >= cols) {
+    predCol = cols - 1;
+  }
+  if (predRow >= rows) {
+    predRow = rows - 1;
+  }
+}
+
+/** Reset all prediction state. Called on server restart to avoid
+ *  stale cursor overlay from the previous session. */
+export function reset(): void {
+  predRow = 0;
+  predCol = 0;
+  predActive = false;
+  predPendingWrap = false;
+  predFrozen = false;
+  if (onChange) {
+    onChange();
+  }
+}
+
+/** Reset prediction to the server's reported cursor and re-arm.
+ *  When the server cursor is hidden (e.g. during a selection prompt),
+ *  prediction is frozen — the ghost cursor disappears and typed input
+ *  doesn't move it. */
+export function onScreenFrame(serverRow: number, serverCol: number, cursorHidden?: boolean): void {
+  predRow = serverRow;
+  predCol = serverCol;
+  predPendingWrap = false;
+  predFrozen = cursorHidden ?? false;
+  predActive = !predFrozen;
+  if (onChange) {
+    onChange();
+  }
+}
+
+/** Apply locally-typed input bytes to the predicted cursor. Bails out
+ *  (suspending prediction) on the first byte we can't model. Also
+ *  bails when frozen (cursor hidden — user is in a selection prompt). */
+export function applyInput(bytes: Uint8Array): void {
+  if (!predActive || predFrozen) {
+    return;
+  }
+  let i = 0;
+  while (i < bytes.length) {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- index checked by loop condition
+    const b = bytes[i]!;
+    if (b === 0x1b) {
+      // ESC — start of an escape sequence. Don't try to model it.
+      predActive = false;
+      if (onChange) {
+        onChange();
+      }
+      return;
+    }
+    if (b === 0x08 || b === 0x7f) {
+      // BS / DEL — backspace one cell.
+      predPendingWrap = false;
+      if (predCol > 0) {
+        predCol--;
+      } else if (predRow > 0) {
+        // wrap to end of previous row (terminals typically don't,
+        // but kiro-cli's prompt frequently does on Backspace at col
+        // 0, so this is closer to expected behavior than staying put)
+        predRow--;
+        predCol = cols - 1;
+      }
+      i++;
+      continue;
+    }
+    if (b === 0x0d) {
+      // CR
+      predPendingWrap = false;
+      predCol = 0;
+      i++;
+      continue;
+    }
+    if (b === 0x0a) {
+      // LF
+      predPendingWrap = false;
+      predRow = Math.min(predRow + 1, rows - 1);
+      i++;
+      continue;
+    }
+    if (b < 0x20) {
+      // Other C0 — probably interpreted by the application; bail.
+      predActive = false;
+      if (onChange) {
+        onChange();
+      }
+      return;
+    }
+    // Printable ASCII or UTF-8 lead byte. Detect the codepoint length
+    // and advance one cell. Mirror the server's pendingWrap semantics
+    // so the predicted cursor matches the server VT exactly: when
+    // pendingWrap is set we wrap to (row+1, 0) BEFORE writing, then
+    // record pendingWrap if the new col is the last one.
+    let len = 1;
+    if (b >= 0xc0 && b < 0xe0) {
+      len = 2;
+    } else if (b >= 0xe0 && b < 0xf0) {
+      len = 3;
+    } else if (b >= 0xf0) {
+      len = 4;
+    }
+    i += len;
+    if (predPendingWrap) {
+      predCol = 0;
+      predRow = Math.min(predRow + 1, rows - 1);
+      predPendingWrap = false;
+    }
+    if (predCol >= cols - 1) {
+      // Last column: don't advance, set pendingWrap for the next char.
+      predCol = cols - 1;
+      predPendingWrap = true;
+    } else {
+      predCol++;
+    }
+  }
+  if (onChange) {
+    onChange();
+  }
+}
+
+/** Current predicted cursor state. `active` is false when prediction
+ *  is suspended (e.g. after an unmodelled byte). When the predicted
+ *  position equals the server's position, the renderer should hide
+ *  the overlay so the user sees only one cursor. */
+export function get(): { row: number; col: number; active: boolean } {
+  return { row: predRow, col: predCol, active: predActive };
+}

package/src/status.ts

@@ -0,0 +1,173 @@
+// 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).
+//
+// 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.)
+
+const CONNECTING_GRACE_MS = 600;
+
+type State = "open" | "connecting" | "reconnecting" | "offline" | "restarted";
+
+let banner: HTMLElement | null = null;
+let state: State = "connecting";
+let stableTimer: ReturnType<typeof setTimeout> | null = null;
+let consecutiveFailures = 0;
+
+/** Mark the connection as open. Hides the banner. */
+export function open(): void {
+  consecutiveFailures = 0;
+  setState("open", 0);
+}
+
+/** Mark a reconnect attempt in progress (after a close, before re-open). */
+export function reconnecting(): void {
+  if (document.getElementById("loading")) {
+    return;
+  }
+  setState("reconnecting", CONNECTING_GRACE_MS);
+}
+
+/** Mark the connection as closed; shows banner after grace period. */
+export function closed(): void {
+  consecutiveFailures++;
+  if (document.getElementById("loading")) {
+    return;
+  }
+  setState(consecutiveFailures > 3 ? "offline" : "reconnecting", CONNECTING_GRACE_MS);
+}
+
+/** Surface that the server has restarted (epoch mismatch). The
+ *  caller has already reset bytesSent/bytesAcked; this just shows
+ *  a brief banner so the user knows old input may have been lost. */
+export function restarted(): void {
+  setState("restarted", 0);
+  // Auto-clear the banner after a few seconds; "open" will re-arrive
+  // when the next screen frame renders, but we don't want to wait.
+  setTimeout(() => {
+    if (state === "restarted") {
+      setState("open", 0);
+    }
+  }, 4000);
+}
+
+function setState(next: State, delay: number): void {
+  if (stableTimer !== null) {
+    clearTimeout(stableTimer);
+    stableTimer = null;
+  }
+  if (delay === 0) {
+    state = next;
+    applyState();
+    return;
+  }
+  stableTimer = setTimeout(() => {
+    stableTimer = null;
+    state = next;
+    applyState();
+  }, delay);
+}
+
+/** Surface a brief transient message (e.g. "Copied") using the same
+ *  banner system as connection status. Auto-clears after `ms`. */
+export function toast(msg: string, ms = 3000): void {
+  if (!banner) {
+    return;
+  }
+  banner.textContent = msg;
+  banner.dataset["state"] = "toast";
+  banner.classList.add("visible");
+  scheduleToastDismiss(ms);
+}
+
+let toastDismissTimer: ReturnType<typeof setTimeout> | null = null;
+let toastDismissMs = 3000;
+
+function scheduleToastDismiss(ms: number): void {
+  toastDismissMs = ms;
+  if (toastDismissTimer !== null) {
+    clearTimeout(toastDismissTimer);
+  }
+  toastDismissTimer = setTimeout(dismissToast, ms);
+}
+
+function dismissToast(): void {
+  toastDismissTimer = null;
+  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 = "";
+  }
+}
+
+export function init(): void {
+  banner = document.getElementById("conn-banner");
+  applyState();
+
+  // Hover-pause: stop the auto-dismiss timer while the user hovers
+  // (gives them time to read longer messages or click actions).
+  banner?.addEventListener("mouseenter", () => {
+    if (toastDismissTimer !== null) {
+      clearTimeout(toastDismissTimer);
+      toastDismissTimer = null;
+    }
+  });
+  banner?.addEventListener("mouseleave", () => {
+    if (banner?.dataset["state"] === "toast" && banner.classList.contains("visible")) {
+      scheduleToastDismiss(toastDismissMs);
+    }
+  });
+
+  // Escape-dismiss: pressing Escape while a toast is visible clears it.
+  document.addEventListener("keydown", (ev) => {
+    if (
+      ev.key === "Escape" &&
+      banner?.classList.contains("visible") &&
+      banner.dataset["state"] === "toast"
+    ) {
+      if (toastDismissTimer !== null) {
+        clearTimeout(toastDismissTimer);
+      }
+      dismissToast();
+    }
+  });
+}
+
+function applyState(): void {
+  if (!banner) {
+    return;
+  }
+  switch (state) {
+    case "open":
+      banner.classList.remove("visible");
+      banner.textContent = "";
+      break;
+    case "connecting":
+    case "reconnecting":
+      banner.textContent = "Reconnecting…";
+      banner.dataset["state"] = "reconnecting";
+      banner.classList.add("visible");
+      break;
+    case "offline":
+      banner.textContent = "Offline";
+      banner.dataset["state"] = "offline";
+      banner.classList.add("visible");
+      break;
+    case "restarted":
+      banner.textContent = "Server restarted — recent input may have been lost";
+      banner.dataset["state"] = "restarted";
+      banner.classList.add("visible");
+      break;
+  }
+}

package/src/viewport.ts

@@ -0,0 +1,98 @@
+// Viewport stability tracker.
+//
+// Coordinates iOS keyboard transitions, window resizes, font-load reflows,
+// and ResizeObserver fires into a single "transition → settle" lifecycle
+// so the rest of the app can act on stable viewport state without each
+// piece reinventing its own debounce/suppress timers.
+//
+// Behavior:
+//   1. Any viewport-affecting event marks "in transition".
+//   2. While in transition: autoscroll is suppressed, input dimensions
+//      may shift, no resize is sent to the server.
+//   3. After SETTLE_MS of no further events, fire onSettled — the caller
+//      then sends the final size, snaps to bottom if was-at-bottom, etc.
+
+import { scroll } from "@cplieger/web-terminal-engine";
+
+// Time to wait after the last viewport-changing event before declaring
+// the viewport "settled". Long enough to bridge the iOS keyboard slide
+// (~250ms) with margin for fonts and reflow.
+const SETTLE_MS = 350;
+
+let termWrap: HTMLElement;
+let onSettled: ((wasAtBottom: boolean) => void) | null = null;
+let inTransition = false;
+let wasAtBottomAtStart = true;
+let settleTimer: ReturnType<typeof setTimeout> | null = null;
+
+function startTransition(): void {
+  // Capture pre-transition scroll state at the *start* of the transition,
+  // not on every event in the burst.
+  if (!inTransition) {
+    inTransition = true;
+    wasAtBottomAtStart = !scroll.isUserScrolledUp();
+  }
+
+  if (settleTimer !== null) {
+    clearTimeout(settleTimer);
+  }
+  settleTimer = setTimeout(() => {
+    settleTimer = null;
+    inTransition = false;
+    if (wasAtBottomAtStart) {
+      scroll.scrollToBottom();
+    }
+    if (onSettled) {
+      onSettled(wasAtBottomAtStart);
+    }
+  }, SETTLE_MS);
+}
+
+export function init(opts: {
+  termWrap: HTMLElement;
+  onSettled: (wasAtBottom: boolean) => void;
+}): void {
+  termWrap = opts.termWrap;
+  onSettled = opts.onSettled;
+
+  // iOS soft keyboard. interactive-widget=resizes-content makes the
+  // layout viewport shrink; we still apply a manual bottom inset as
+  // fallback for older iOS / other mobile browsers.
+  if (window.visualViewport) {
+    const vv = window.visualViewport;
+    const onChange = (): void => {
+      const inset = Math.max(0, Math.round(window.innerHeight - vv.height));
+      termWrap.style.bottom = inset > 0 ? `${inset}px` : "";
+      // Expose viewport geometry as CSS vars so fixed chrome stays in view:
+      // --kb-inset lifts the bottom banner above the keyboard; --vv-top lets
+      // the top toolbar counter iOS shifting content up to reveal the
+      // bottom-pinned input (otherwise the toolbar scrolls off the top).
+      const root = document.documentElement.style;
+      root.setProperty("--kb-inset", `${inset}px`);
+      root.setProperty("--vv-top", `${Math.max(0, Math.round(vv.offsetTop))}px`);
+      startTransition();
+    };
+    vv.addEventListener("resize", onChange);
+    vv.addEventListener("scroll", onChange);
+    onChange();
+  }
+
+  // Term wrap dimension changes: window resize, font load, devtools dock.
+  const ro = new ResizeObserver(startTransition);
+  ro.observe(termWrap);
+  window.addEventListener("resize", startTransition);
+
+  // Orientation change on mobile. iOS Safari often emits the
+  // window.resize event late or not at all on rotation while
+  // visualViewport.resize fires reliably; screen.orientation.change is
+  // the canonical signal that survives both. Modern browsers expose it
+  // on screen.orientation; older Safari falls back to the deprecated
+  // window.orientationchange event.
+  const orientation = (screen as Screen & { orientation?: ScreenOrientation }).orientation;
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime guard for older Safari without screen.orientation
+  if (orientation) {
+    orientation.addEventListener("change", startTransition);
+  } else if ("onorientationchange" in window) {
+    window.addEventListener("orientationchange", startTransition);
+  }
+}