@cplieger/web-terminal-ui 1.0.1 → 2.1.0

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,26 +1,49 @@
-// 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;
 let state: State = "connecting";
 let stableTimer: ReturnType<typeof setTimeout> | null = null;
 let consecutiveFailures = 0;
+// True once the first screen frame has rendered (mount calls setLoaded()).
+// Until then the initial loading overlay is up and we suppress the
+// 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 {
@@ -28,9 +51,16 @@ export function open(): void {
   setState("open", 0);
 }
 
+/** Mark the terminal as past its initial load (first screen frame rendered).
+ *  Until this is called the connection banner stays suppressed so it never
+ *  stacks on top of the consumer's loading overlay. */
+export function setLoaded(): void {
+  loaded = true;
+}
+
 /** Mark a reconnect attempt in progress (after a close, before re-open). */
 export function reconnecting(): void {
-  if (document.getElementById("loading")) {
+  if (!loaded) {
     return;
   }
   setState("reconnecting", CONNECTING_GRACE_MS);
@@ -39,9 +69,21 @@ export function reconnecting(): void {
 /** Mark the connection as closed; shows banner after grace period. */
 export function closed(): void {
   consecutiveFailures++;
-  if (document.getElementById("loading")) {
+  // 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);
 }
 
@@ -104,26 +146,28 @@ 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(): void {
-  banner = document.getElementById("conn-banner");
+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
   // (gives them time to read longer messages or click actions).
-  banner?.addEventListener("mouseenter", () => {
+  banner.addEventListener("mouseenter", () => {
     if (toastDismissTimer !== null) {
       clearTimeout(toastDismissTimer);
       toastDismissTimer = null;
     }
   });
-  banner?.addEventListener("mouseleave", () => {
+  banner.addEventListener("mouseleave", () => {
     if (banner?.dataset["state"] === "toast" && banner.classList.contains("visible")) {
       scheduleToastDismiss(toastDismissMs);
     }
@@ -148,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");