feat(ui-react): add inline error banner to terminal sessions

Replace raw ANSI error output with a structured inline banner that
appears at the top of the terminal area on connection failures.

- Add error map that resolves server error strings into user-friendly
  messages with contextual hints and navigation links
- Parse WebSocket JSON frames (kind:4) as structured error messages
- Show inline banner with title, message, hints, links, and retry
- Dim terminal and hide cursor when error is displayed
- Close terminal tab when clicking the X button or navigation links

Author: gustavosbarreto

ui-react/apps/admin/src/components/terminal/TerminalControls.tsx

@@ -11,7 +11,11 @@ import TerminalSettingsDrawer from "./TerminalSettingsDrawer";
 
 /** Terminal info shown on the left side of the AppBar */
 export function TerminalInfo({ session }: { session: TerminalSession }) {
-  const { connectionStatus: status } = session;
+  const status = useTerminalStore(
+    (s) =>
+      s.sessions.find((ss) => ss.id === session.id)?.connectionStatus ??
+      "disconnected",
+  );
 
   return (
     <div className="flex items-center gap-2.5 min-w-0">

ui-react/apps/admin/src/components/terminal/TerminalErrorBanner.tsx

@@ -0,0 +1,75 @@
+import { Link } from "react-router-dom";
+import { ExclamationCircleIcon, XMarkIcon } from "@heroicons/react/24/outline";
+import { useTerminalStore } from "../../stores/terminalStore";
+import type { TerminalError } from "./terminalErrors";
+
+interface TerminalErrorBannerProps {
+  error: TerminalError;
+  sessionId: string;
+}
+
+export default function TerminalErrorBanner({
+  error,
+  sessionId,
+}: TerminalErrorBannerProps) {
+  return (
+    <div
+      role="alert"
+      className="bg-accent-red/[0.08] border-b border-accent-red/20 px-5 py-3.5 flex items-start gap-3 animate-slide-down"
+    >
+      <ExclamationCircleIcon
+        className="w-4 h-4 text-accent-red shrink-0 mt-0.5"
+        strokeWidth={1.5}
+      />
+      <div className="flex-1 min-w-0">
+        <div className="flex items-baseline gap-2 mb-1">
+          <span className="text-sm font-semibold text-text-primary">
+            {error.title}
+          </span>
+          <span className="text-sm text-text-muted">{error.message}</span>
+        </div>
+        {error.hints.length > 0 && (
+          <p className="text-sm text-text-secondary leading-relaxed mb-1.5">
+            {error.hints.join(" ")}
+          </p>
+        )}
+        {(error.links.length > 0 || error.reconnect) && (
+          <div className="flex items-center gap-3">
+            {error.links.map((link) => (
+              <Link
+                key={link.to}
+                to={link.to}
+                onClick={() => useTerminalStore.getState().close(sessionId)}
+                className="text-sm text-primary hover:text-primary-600 font-medium transition-colors"
+              >
+                {link.label}
+              </Link>
+            ))}
+            {error.links.length > 0 && error.reconnect && (
+              <span className="w-px h-3.5 bg-border-light" />
+            )}
+            {error.reconnect && (
+              <button
+                type="button"
+                onClick={() => {
+                  useTerminalStore.getState().closeAndReconnect(sessionId);
+                }}
+                className="px-2.5 py-1 bg-primary hover:bg-primary-600 text-white rounded text-xs font-semibold transition-colors"
+              >
+                Retry
+              </button>
+            )}
+          </div>
+        )}
+      </div>
+      <button
+        type="button"
+        aria-label="Close"
+        onClick={() => useTerminalStore.getState().close(sessionId)}
+        className="text-text-muted hover:text-text-primary transition-colors p-0.5 shrink-0"
+      >
+        <XMarkIcon className="w-3.5 h-3.5" />
+      </button>
+    </div>
+  );
+}

ui-react/apps/admin/src/components/terminal/TerminalInstance.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useCallback } from "react";
+import { useEffect, useRef, useCallback, useState } from "react";
 import { Terminal } from "@xterm/xterm";
 import { FitAddon } from "@xterm/addon-fit";
 import { WebLinksAddon } from "@xterm/addon-web-links";
@@ -7,31 +7,52 @@ import apiClient from "../../api/client";
 import type { TerminalSession } from "../../stores/terminalStore";
 import { useTerminalStore } from "../../stores/terminalStore";
 import { useTerminalThemeStore } from "../../stores/terminalThemeStore";
+import type { TerminalError } from "./terminalErrors";
+import TerminalErrorBanner from "./TerminalErrorBanner";
+import {
+  WS_KIND,
+  HTTP_CONNECT_ERROR,
+  WS_CLOSE_ERROR,
+  WS_NETWORK_ERROR,
+  parseMessage,
+  resolveError,
+} from "./terminalErrors";
 
 interface TerminalInstanceProps {
   session: TerminalSession;
   visible: boolean;
 }
 
-export default function TerminalInstance({ session, visible }: TerminalInstanceProps) {
+export default function TerminalInstance({
+  session,
+  visible,
+}: TerminalInstanceProps) {
   const containerRef = useRef<HTMLDivElement>(null);
   const termRef = useRef<Terminal | null>(null);
   const fitRef = useRef<FitAddon | null>(null);
   const wsRef = useRef<WebSocket | null>(null);
   const observerRef = useRef<ResizeObserver | null>(null);
   const prevVisibleRef = useRef(visible);
+  const [error, setError] = useState<TerminalError | null>(null);
 
   const { theme, fontFamilyWithFallback, fontSize } = useTerminalThemeStore();
 
-  const updateStatus = useCallback((s: "connecting" | "connected" | "disconnected") => {
-    useTerminalStore.getState().setConnectionStatus(session.id, s);
-  }, [session.id]);
+  const updateStatus = useCallback(
+    (s: "connecting" | "connected" | "disconnected") => {
+      useTerminalStore.getState().setConnectionStatus(session.id, s);
+    },
+    [session.id],
+  );
 
   // Connect on mount, cleanup on unmount
   useEffect(() => {
     let cancelled = false;
-    const { theme: initTheme, fontFamilyWithFallback: initFont, fontSize: initSize } =
-      useTerminalThemeStore.getState();
+    let lastError = false;
+    const {
+      theme: initTheme,
+      fontFamilyWithFallback: initFont,
+      fontSize: initSize,
+    } = useTerminalThemeStore.getState();
 
     async function connect() {
       updateStatus("connecting");
@@ -45,7 +66,9 @@ export default function TerminalInstance({ session, visible }: TerminalInstanceP
         });
         token = res.data.token;
       } catch {
+        if (cancelled) return;
         updateStatus("disconnected");
+        setError(HTTP_CONNECT_ERROR);
         return;
       }
 
@@ -88,34 +111,49 @@ export default function TerminalInstance({ session, visible }: TerminalInstanceP
       };
 
       ws.onmessage = async (event) => {
+        if (cancelled) return;
         if (event.data instanceof Blob) {
           term.write(await event.data.text());
         } else {
-          term.write(event.data);
+          const msg = parseMessage(event.data);
+          if (msg?.kind === WS_KIND.ERROR) {
+            lastError = true;
+            updateStatus("disconnected");
+            setError(resolveError(msg.data, session.deviceUid));
+          } else if (!lastError) {
+            term.write(event.data);
+          }
         }
       };
 
       ws.onclose = () => {
         if (cancelled) return;
         updateStatus("disconnected");
-        term.write("\r\n\x1b[1;31mDisconnected.\x1b[0m\r\n");
+        if (!lastError) {
+          setError(WS_CLOSE_ERROR);
+        }
       };
 
       ws.onerror = () => {
         if (cancelled) return;
+        lastError = true;
         updateStatus("disconnected");
-        term.write("\r\n\x1b[1;31mConnection error.\x1b[0m\r\n");
+        setError(WS_NETWORK_ERROR);
       };
 
       term.onData((data) => {
         if (ws.readyState === WebSocket.OPEN) {
-          ws.send(JSON.stringify({ kind: 1, data: data.slice(0, 4096) }));
+          ws.send(
+            JSON.stringify({ kind: WS_KIND.INPUT, data: data.slice(0, 4096) }),
+          );
         }
       });
 
       term.onResize(({ cols, rows }) => {
         if (ws.readyState === WebSocket.OPEN) {
-          ws.send(JSON.stringify({ kind: 2, data: { cols, rows } }));
+          ws.send(
+            JSON.stringify({ kind: WS_KIND.RESIZE, data: { cols, rows } }),
+          );
         }
       });
 
@@ -135,15 +173,18 @@ export default function TerminalInstance({ session, visible }: TerminalInstanceP
       observerRef.current?.disconnect();
       observerRef.current = null;
       if (wsRef.current) {
+        wsRef.current.onopen = null;
         wsRef.current.onclose = null;
+        wsRef.current.onerror = null;
+        wsRef.current.onmessage = null;
         wsRef.current.close();
         wsRef.current = null;
       }
       termRef.current?.dispose();
       termRef.current = null;
       fitRef.current = null;
     };
-  // eslint-disable-next-line react-hooks/exhaustive-deps
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [session.id]);
 
   // Live theme/font updates
@@ -167,20 +208,35 @@ export default function TerminalInstance({ session, visible }: TerminalInstanceP
     fitRef.current?.fit();
   }, [fontSize]);
 
+  // Hide cursor on error
+  useEffect(() => {
+    const term = termRef.current;
+    if (!term || error === null) return;
+    term.options.cursorBlink = false;
+    term.blur();
+    term.write("\x1b[?25l"); // CSI sequence to hide cursor
+  }, [error]);
+
   // Handle visibility changes (minimize/restore)
   useEffect(() => {
-    if (!prevVisibleRef.current && visible) {
+    if (!prevVisibleRef.current && visible && error === null) {
       requestAnimationFrame(() => {
         fitRef.current?.fit();
         termRef.current?.focus();
       });
     }
     prevVisibleRef.current = visible;
-  }, [visible]);
+  }, [visible, error]);
 
   return (
-    <div className="flex-1 overflow-hidden">
-      <div ref={containerRef} className="w-full h-full" />
+    <div className="relative flex-1 flex flex-col overflow-hidden">
+      {error !== null && (
+        <TerminalErrorBanner error={error} sessionId={session.id} />
+      )}
+      <div
+        ref={containerRef}
+        className={`flex-1 ${error !== null ? "opacity-30 pointer-events-none" : ""}`}
+      />
     </div>
   );
 }

ui-react/apps/admin/src/components/terminal/TerminalManager.tsx

@@ -1,12 +1,38 @@
-import { useEffect, useRef } from "react";
+import { useEffect, useRef, useState } from "react";
 import { useLocation } from "react-router-dom";
 import { useTerminalStore } from "../../stores/terminalStore";
+import { useNamespacesStore } from "../../stores/namespacesStore";
+import ConnectDrawer from "../ConnectDrawer";
 import TerminalInstance from "./TerminalInstance";
 import TerminalTaskbar from "./TerminalTaskbar";
 
 export default function TerminalManager() {
   const sessions = useTerminalStore((s) => s.sessions);
   const minimizeAll = useTerminalStore((s) => s.minimizeAll);
+  const reconnectTarget = useTerminalStore((s) => s.reconnectTarget);
+  const currentNamespace = useNamespacesStore((s) => s.currentNamespace);
+
+  const [connectTarget, setConnectTarget] = useState<{
+    uid: string;
+    name: string;
+    sshid: string;
+  } | null>(null);
+
+  // Open ConnectDrawer when a reconnect is requested (works from any page)
+  useEffect(() => {
+    if (!reconnectTarget) return;
+    useTerminalStore.getState().clearReconnect();
+    const nsName = currentNamespace?.name;
+    const sshid = nsName
+      ? `${nsName}.${reconnectTarget.deviceName}@${nsName}`
+      : reconnectTarget.deviceUid;
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setConnectTarget({
+      uid: reconnectTarget.deviceUid,
+      name: reconnectTarget.deviceName,
+      sshid,
+    });
+  }, [reconnectTarget, currentNamespace]);
 
   // Auto-minimize terminal when navigating to another page
   const location = useLocation();
@@ -20,6 +46,16 @@ export default function TerminalManager() {
 
   return (
     <>
+      {connectTarget && (
+        <ConnectDrawer
+          open
+          onClose={() => setConnectTarget(null)}
+          deviceUid={connectTarget.uid}
+          deviceName={connectTarget.name}
+          sshid={connectTarget.sshid}
+        />
+      )}
+
       {sessions.map((s) => {
         const isVisible = s.state !== "minimized";
         const isFullscreen = s.state === "fullscreen";