Fix/explorer backend failure states

explorer/src/App.tsx

@@ -67,6 +67,14 @@ type GraphStatsPayload = {
   edges?: number;
 };
 
+type ConnectionStatus = 'checking' | 'online' | 'offline';
+
+const CONNECTION_STATUS_LABEL: Record<ConnectionStatus, string> = {
+  checking: 'Connecting…',
+  online: 'System Online',
+  offline: 'Backend Unreachable',
+};
+
 const queryClient = new QueryClient();
 
 const PREVIEW_DOTS = Array.from({ length: 42 }, (_, i) => ({
@@ -719,19 +727,34 @@ const shellStyles = `
     align-items: center;
     gap: 10px;
     margin-bottom: 24px;
+    --status-color: #4cc38a;
+    --status-shadow-a: 0 0 0 3px rgba(76, 195, 138, 0.22), 0 0 12px rgba(76, 195, 138, 0.5);
+    --status-shadow-b: 0 0 0 5px rgba(76, 195, 138, 0.1), 0 0 20px rgba(76, 195, 138, 0.35);
+  }
+
+  .landing-status-bar[data-status='checking'] {
+    --status-color: #f2b66d;
+    --status-shadow-a: 0 0 0 3px rgba(242, 182, 109, 0.22), 0 0 12px rgba(242, 182, 109, 0.5);
+    --status-shadow-b: 0 0 0 5px rgba(242, 182, 109, 0.1), 0 0 20px rgba(242, 182, 109, 0.35);
+  }
+
+  .landing-status-bar[data-status='offline'] {
+    --status-color: #ff7b72;
+    --status-shadow-a: 0 0 0 3px rgba(255, 123, 114, 0.22), 0 0 12px rgba(255, 123, 114, 0.5);
+    --status-shadow-b: 0 0 0 5px rgba(255, 123, 114, 0.1), 0 0 20px rgba(255, 123, 114, 0.35);
   }
 
   .landing-status-dot {
     width: 8px;
     height: 8px;
     border-radius: 999px;
-    background: #4cc38a;
-    box-shadow: 0 0 0 3px rgba(76, 195, 138, 0.22), 0 0 12px rgba(76, 195, 138, 0.5);
+    background: var(--status-color);
+    box-shadow: var(--status-shadow-a);
     animation: landing-pulse 2.4s ease-in-out infinite;
   }
 
   .landing-status-text {
-    color: #4cc38a;
+    color: var(--status-color);
     font: 700 11px/1 "JetBrains Mono", monospace;
     letter-spacing: 0.1em;
     text-transform: uppercase;
@@ -1323,8 +1346,8 @@ const shellStyles = `
   }
 
   @keyframes landing-pulse {
-    0%, 100% { box-shadow: 0 0 0 3px rgba(76, 195, 138, 0.22), 0 0 12px rgba(76, 195, 138, 0.5); }
-    50% { box-shadow: 0 0 0 5px rgba(76, 195, 138, 0.1), 0 0 20px rgba(76, 195, 138, 0.35); }
+    0%, 100% { box-shadow: var(--status-shadow-a); }
+    50% { box-shadow: var(--status-shadow-b); }
   }
 
   .workspace-loading {
@@ -1494,10 +1517,10 @@ function WelcomeScreen({
   onOpenDecisions: () => void;
   onOpenManage: () => void;
 }) {
-  const [stats, setStats] = useState<{ nodes: number | null; edges: number | null; ready: boolean }>({
+  const [stats, setStats] = useState<{ nodes: number | null; edges: number | null; status: ConnectionStatus }>({
     nodes: null,
     edges: null,
-    ready: false,
+    status: 'checking',
   });
 
   useEffect(() => {
@@ -1507,31 +1530,32 @@ function WelcomeScreen({
       .then((response) => (response.ok ? response.json() as Promise<GraphStatsPayload> : null))
       .then((payload) => {
         if (!payload) {
-          setStats((current) => ({ ...current, ready: false }));
+          setStats((current) => ({ ...current, status: 'offline' }));
           return;
         }
 
         setStats({
           nodes: getNumberStat(payload, ['node_count', 'nodeCount', 'nodes']),
           edges: getNumberStat(payload, ['edge_count', 'edgeCount', 'edges']),
-          ready: true,
+          status: 'online',
         });
       })
       .catch((error: unknown) => {
         if (error instanceof DOMException && error.name === 'AbortError') {
           return;
         }
-        setStats((current) => ({ ...current, ready: false }));
+        setStats((current) => ({ ...current, status: 'offline' }));
       });
 
     return () => controller.abort();
   }, []);
 
+  const isOnline = stats.status === 'online';
   const metrics: LandingMetric[] = [
     { label: 'Knowledge nodes', value: formatMetric(stats.nodes, 'Live'), tone: 'cyan' },
     { label: 'Relationships mapped', value: formatMetric(stats.edges, 'Ready'), tone: 'mint' },
     { label: 'Graph modes', value: '3', tone: 'amber' },
-    { label: stats.ready ? 'Dataset online' : 'Ready to explore', value: stats.ready ? 'Active' : 'Standby', tone: 'rose' },
+    { label: isOnline ? 'Dataset online' : 'Ready to explore', value: isOnline ? 'Active' : 'Standby', tone: 'rose' },
   ];
 
   const secondaryLaunchers: LandingAction[] = [
@@ -1574,9 +1598,9 @@ function WelcomeScreen({
         {/* ── Hero ── */}
         <section className="landing-hero">
           <div className="landing-copy">
-            <div className="landing-status-bar">
+            <div className="landing-status-bar" data-status={stats.status}>
               <div className="landing-status-dot" />
-              <span className="landing-status-text">System Online</span>
+              <span className="landing-status-text">{CONNECTION_STATUS_LABEL[stats.status]}</span>
               <div className="landing-status-divider" />
               <span className="landing-status-version">Semantica v2 · Semantic Intelligence</span>
             </div>

explorer/src/workspaces/GraphWorkspace/GraphLoadingOverlay.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState, type CSSProperties } from "react";
+import { AlertTriangle, RefreshCw } from "lucide-react";
 
 import { GRAPH_THEME, withAlpha } from "./graphTheme";
 import { GRAPH_LOAD_STAGE_SEQUENCE, createGraphLoadProgress, getGraphLoadStageLabel } from "./graphLoading";
@@ -121,6 +122,58 @@ const LOADING_OVERLAY_CSS = `
     0% { transform: translateX(-120%); }
     100% { transform: translateX(360%); }
   }
+  .graph-stage-loader-card[data-error="true"] {
+    pointer-events: auto;
+    border-color: rgba(255, 123, 114, 0.32);
+    background:
+      radial-gradient(circle at top left, rgba(255, 123, 114, 0.12), transparent 32%),
+      linear-gradient(145deg, rgba(7, 17, 31, 0.96), rgba(24, 14, 18, 0.86));
+  }
+  .graph-stage-loader-error-mark {
+    width: 38px;
+    height: 38px;
+    flex: 0 0 auto;
+    border-radius: 12px;
+    display: grid;
+    place-items: center;
+    color: #ff9e97;
+    background: rgba(255, 123, 114, 0.12);
+    border: 1px solid rgba(255, 123, 114, 0.28);
+  }
+  .graph-stage-loader-error-detail {
+    padding: 10px 12px;
+    border-radius: 10px;
+    background: rgba(0, 0, 0, 0.32);
+    border: 1px solid rgba(255, 123, 114, 0.18);
+    color: #ffb4ae;
+    font-family: "JetBrains Mono", "Fira Code", Consolas, monospace;
+    font-size: 12px;
+    line-height: 1.55;
+    word-break: break-word;
+  }
+  .graph-stage-loader-retry {
+    display: inline-flex;
+    align-items: center;
+    gap: 7px;
+    padding: 9px 16px;
+    border-radius: 8px;
+    font-size: 13px;
+    font-weight: 700;
+    cursor: pointer;
+    border: 1px solid rgba(127, 208, 255, 0.4);
+    background: linear-gradient(135deg, rgba(74, 163, 255, 0.28), rgba(56, 210, 160, 0.16));
+    color: #e8f6ff;
+    transition: 160ms ease;
+  }
+  .graph-stage-loader-retry:hover {
+    border-color: rgba(127, 208, 255, 0.62);
+    background: linear-gradient(135deg, rgba(74, 163, 255, 0.4), rgba(56, 210, 160, 0.24));
+    transform: translateY(-1px);
+  }
+  .graph-stage-loader-retry:focus-visible {
+    outline: 2px solid #7fd0ff;
+    outline-offset: 2px;
+  }
 `;
 
 function formatLayoutSource(source: GraphLoadProgress["layoutSource"]) {
@@ -170,10 +223,14 @@ export function GraphLoadingOverlay({
   progress,
   visible,
   showGraphBehind,
+  error = null,
+  onRetry,
 }: {
   progress: GraphLoadProgress | null;
   visible: boolean;
   showGraphBehind: boolean;
+  error?: string | null;
+  onRetry?: () => void;
 }) {
   const [renderVisible, setRenderVisible] = useState(visible);
   const [exiting, setExiting] = useState(false);
@@ -226,6 +283,44 @@ export function GraphLoadingOverlay({
     return null;
   }
 
+  if (error) {
+    return (
+      <div
+        className="graph-stage-loader"
+        data-exiting={exiting}
+        style={{ background: "linear-gradient(180deg, rgba(1,4,9,0.22), rgba(1,4,9,0.5))" }}
+      >
+        <style>{LOADING_OVERLAY_CSS}</style>
+        <div className="graph-stage-loader-card" data-error="true" role="alert">
+          <div style={{ display: "flex", alignItems: "flex-start", gap: 14, marginBottom: 14 }}>
+            <div className="graph-stage-loader-error-mark" aria-hidden="true">
+              <AlertTriangle size={18} strokeWidth={2.2} />
+            </div>
+            <div style={{ minWidth: 0 }}>
+              <div style={{ color: "#ffffff", fontSize: 20, fontWeight: 700, letterSpacing: "-0.03em", marginBottom: 6 }}>
+                Could not load the graph
+              </div>
+              <div style={{ color: "#8fa8c6", fontSize: 13, lineHeight: 1.5 }}>
+                The Explorer API did not return graph data. Check that the backend is running and reachable, then try again.
+              </div>
+            </div>
+          </div>
+
+          <div className="graph-stage-loader-error-detail">{error}</div>
+
+          {onRetry ? (
+            <div style={{ display: "flex", gap: 10, marginTop: 16 }}>
+              <button type="button" className="graph-stage-loader-retry" onClick={onRetry}>
+                <RefreshCw size={14} strokeWidth={2.2} aria-hidden />
+                Retry
+              </button>
+            </div>
+          ) : null}
+        </div>
+      </div>
+    );
+  }
+
   const activeProgress = progress ?? displayProgress;
   const isLiveStage = activeProgress.phase === "stabilizing_layout" || activeProgress.showGraphBehind || showGraphBehind;
   const overlayBackground = isLiveStage