@tablestore/tablestore-agent-cli 0.1.8 → 0.1.9

package/dist/dashboard-runtime/dashboard/src/components/documents/doc-upload-dialog.tsx

@@ -487,13 +487,37 @@ export function DocUploadDialog({
     }
 
     try {
-      await uploadDocuments.mutateAsync({
+      const result = await uploadDocuments.mutateAsync({
         knowledgeBaseName,
         files: effectiveFiles,
         subspace: subspace || undefined,
         metadata,
       });
-      toast.success(`成功上传 ${effectiveFiles.length} 个文档`);
+
+      // Classify per-file results when available.
+      const details = result.documentDetails ?? [];
+      const failed = details.filter((d) => d.status.toLowerCase() === "failed");
+
+      if (failed.length === 0) {
+        toast.success(`成功上传 ${effectiveFiles.length} 个文档`);
+      } else if (failed.length < details.length) {
+        const reasons = [...new Set(failed.map((d) => d.failureReason).filter(Boolean))];
+        toast.warning(
+          `${details.length - failed.length} 个文档上传成功，${failed.length} 个失败`,
+          { description: reasons.length > 0 ? reasons.slice(0, 3).join("; ") : undefined },
+        );
+      } else {
+        toast.error(`全部 ${failed.length} 个文档上传失败`);
+      }
+
+      // Also surface batch-level errors collected during upload.
+      const batchErrors = uploadDocuments.progress?.errors ?? [];
+      if (batchErrors.length > 0) {
+        toast.warning(`${batchErrors.length} 个批次请求出错`, {
+          description: batchErrors.slice(0, 2).join("; "),
+        });
+      }
+
       resetForm();
       onOpenChange(false);
     } catch (error) {
@@ -809,6 +833,42 @@ export function DocUploadDialog({
           )}
         </div>
 
+        {/* Upload progress bar */}
+        {uploadDocuments.isPending && uploadDocuments.progress && (
+          <div className="space-y-1.5">
+            <div className="flex items-center justify-between text-xs text-[hsl(var(--muted-foreground))]">
+              <span>
+                批次 {uploadDocuments.progress.completedBatches}/{uploadDocuments.progress.totalBatches}
+              </span>
+              <span>
+                {uploadDocuments.progress.completedFiles}/{uploadDocuments.progress.totalFiles} 个文件
+              </span>
+            </div>
+            <div className="h-1.5 w-full overflow-hidden rounded-full bg-[hsl(var(--secondary))]">
+              <div
+                className="h-full rounded-full bg-[hsl(var(--primary))] transition-all duration-300"
+                style={{
+                  width: `${Math.round((uploadDocuments.progress.completedFiles / uploadDocuments.progress.totalFiles) * 100)}%`,
+                }}
+              />
+            </div>
+            {uploadDocuments.progress.errors.length > 0 && (
+              <div className="space-y-1">
+                <p className="text-xs font-medium text-[hsl(var(--destructive))]">
+                  {uploadDocuments.progress.errors.length} 个批次出错
+                </p>
+                <div className="max-h-20 overflow-y-auto rounded-md border border-[hsl(var(--destructive))]/20 bg-[hsl(var(--destructive))]/5 px-2.5 py-1.5 space-y-0.5">
+                  {uploadDocuments.progress.errors.map((err, i) => (
+                    <p key={i} className="text-xs text-[hsl(var(--destructive))]/80 break-words">
+                      {err}
+                    </p>
+                  ))}
+                </div>
+              </div>
+            )}
+          </div>
+        )}
+
         <DialogFooter>
           <Button
             variant="outline"
@@ -816,6 +876,7 @@ export function DocUploadDialog({
               resetForm();
               onOpenChange(false);
             }}
+            disabled={uploadDocuments.isPending}
           >
             取消
           </Button>
@@ -824,7 +885,9 @@ export function DocUploadDialog({
             disabled={effectiveFiles.length === 0 || uploadDocuments.isPending}
           >
             {uploadDocuments.isPending
-              ? "上传中..."
+              ? uploadDocuments.progress
+                ? `上传中 ${uploadDocuments.progress.completedFiles}/${uploadDocuments.progress.totalFiles}`
+                : "准备上传..."
               : `上传 ${effectiveFiles.length} 个文件`}
           </Button>
         </DialogFooter>

package/dist/dashboard-runtime/dashboard/src/components/instance/connect-instance-form.tsx

@@ -35,6 +35,7 @@ import type {
   ConnectInstancePayload,
   ImportInstancePayload,
 } from "@/types/instance";
+import { stripBucketPrefix } from "@/lib/normalize-oss-endpoint";
 
 /**
  * Reuse the canonical schemas from `@/schemas/instance` so the form inherits
@@ -155,10 +156,17 @@ export function ConnectInstanceForm({
   });
 
   async function handleManualSubmit(values: ConnectInstancePayload) {
+    let ossEndpoint = values.ossEndpoint?.trim() || undefined;
+    const ossBucketName = values.ossBucketName?.trim() || undefined;
+
+    if (ossEndpoint && ossBucketName) {
+      ossEndpoint = stripBucketPrefix(ossEndpoint, ossBucketName);
+    }
+
     const normalized: ConnectInstancePayload = {
       ...values,
-      ossEndpoint: values.ossEndpoint?.trim() || undefined,
-      ossBucketName: values.ossBucketName?.trim() || undefined,
+      ossEndpoint,
+      ossBucketName,
     };
     await onSubmit(normalized);
   }

package/dist/dashboard-runtime/dashboard/src/components/instance/edit-instance-dialog.tsx

@@ -53,8 +53,12 @@ export function EditInstanceDialog({
       ...credentialPatch,
       otsEndpoint: manual.otsEndpoint,
       otsInstanceName: manual.otsInstanceName,
-      ossEndpoint: manual.ossEndpoint,
-      ossBucketName: manual.ossBucketName,
+      // The form normalizes empty inputs to `undefined` (optional field).
+      // In edit mode we need to forward an explicit empty string so the
+      // server-side PATCH treats it as "clear this field" instead of
+      // "leave unchanged".
+      ossEndpoint: manual.ossEndpoint ?? "",
+      ossBucketName: manual.ossBucketName ?? "",
       region: manual.region,
     };
     const result = (await update.mutateAsync(

package/dist/dashboard-runtime/dashboard/src/components/instance/project-card.tsx

@@ -0,0 +1,195 @@
+"use client";
+
+import {
+  ArrowRightLeft,
+  Check,
+  Copy,
+  Database,
+  MoreHorizontal,
+  Pencil,
+  Trash2,
+} from "lucide-react";
+
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent } from "@/components/ui/card";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { cn } from "@/lib/utils";
+import type { InstanceSummary } from "@/types/instance";
+
+interface ProjectCardProps {
+  item: InstanceSummary;
+  isActive: boolean;
+  isSwitching: boolean;
+  isExporting: boolean;
+  onSwitch: () => void;
+  onEdit: () => void;
+  onExport: () => void;
+  onDelete: () => void;
+  index?: number;
+}
+
+export function ProjectCard({
+  item,
+  isActive,
+  isSwitching,
+  isExporting,
+  onSwitch,
+  onEdit,
+  onExport,
+  onDelete,
+  index = 0,
+}: ProjectCardProps) {
+  return (
+    <Card
+      className={cn(
+        "group relative overflow-hidden",
+        "transition-[transform,box-shadow,border-color,background-color] duration-200 ease-[cubic-bezier(0.34,1.56,0.64,1)]",
+        "animate-in fade-in slide-in-from-bottom-2",
+        isActive
+          ? [
+              "border-[hsl(var(--primary)/0.45)]",
+              "shadow-[0_10px_28px_-14px_hsl(var(--primary)/0.4)]",
+              "bg-[radial-gradient(circle_at_0%_0%,hsl(var(--primary)/0.08),transparent_55%)]",
+            ]
+          : [
+              "hover:-translate-y-0.5",
+              "hover:border-primary/30",
+              "hover:shadow-md",
+            ],
+      )}
+      style={{
+        animationDelay: `${index * 70}ms`,
+        animationDuration: "480ms",
+      }}
+    >
+      {isActive && (
+        <span
+          aria-hidden
+          className="pointer-events-none absolute left-0 top-0 h-full w-[3px] bg-gradient-to-b from-[hsl(var(--primary)/0.55)] via-primary to-[hsl(var(--primary)/0.55)]"
+        />
+      )}
+
+      <CardContent className="flex flex-col p-5">
+        <div className="flex items-start justify-between gap-3">
+          <div className="flex min-w-0 items-center gap-2">
+            <Database
+              className={cn(
+                "h-4 w-4 shrink-0 transition-colors duration-200",
+                isActive
+                  ? "text-primary"
+                  : "text-muted-foreground group-hover:text-primary",
+              )}
+            />
+            <h3 className="truncate text-base font-semibold tracking-tight text-foreground">
+              {item.name}
+            </h3>
+          </div>
+
+          <div className="flex shrink-0 items-center gap-1">
+            {isActive ? (
+              <Badge
+                variant="secondary"
+                className="gap-1.5 border-0 bg-[hsl(var(--primary-50))] px-2 py-0.5 text-[11px] font-medium text-[hsl(var(--primary-700))]"
+              >
+                <span className="relative flex h-1.5 w-1.5" aria-hidden>
+                  <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-emerald-400 opacity-75" />
+                  <span className="relative inline-flex h-1.5 w-1.5 rounded-full bg-emerald-500" />
+                </span>
+                活跃中
+              </Badge>
+            ) : null}
+
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <Button
+                  variant="ghost"
+                  size="icon"
+                  className="h-7 w-7 text-muted-foreground hover:text-foreground"
+                  aria-label={`更多操作:${item.name}`}
+                >
+                  <MoreHorizontal className="h-4 w-4" />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end" className="w-40">
+                <DropdownMenuItem onClick={onEdit}>
+                  <Pencil className="mr-2 h-4 w-4" />
+                  编辑
+                </DropdownMenuItem>
+                <DropdownMenuItem onClick={onExport} disabled={isExporting}>
+                  <Copy className="mr-2 h-4 w-4" />
+                  导出 Token
+                </DropdownMenuItem>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem
+                  onClick={onDelete}
+                  className="text-[hsl(var(--destructive))] focus:bg-[hsl(var(--destructive)/0.1)] focus:text-[hsl(var(--destructive))]"
+                >
+                  <Trash2 className="mr-2 h-4 w-4" />
+                  删除
+                </DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </div>
+        </div>
+
+        <p className="mt-1 truncate pl-6 text-xs text-muted-foreground">
+          {item.otsInstanceName ?? "--"}
+          {item.region ? ` · ${item.region}` : ""}
+        </p>
+
+        <div className="mt-3 flex flex-wrap gap-1.5 pl-6">
+          <Badge
+            variant="secondary"
+            className="rounded-md border-0 bg-[hsl(var(--primary-50))] px-2 py-0.5 text-[11px] font-normal text-[hsl(var(--primary-700))]"
+          >
+            OTS
+          </Badge>
+          {item.hasOss ? (
+            <Badge
+              variant="secondary"
+              className="rounded-md border-0 bg-[hsl(var(--primary-50))] px-2 py-0.5 text-[11px] font-normal text-[hsl(var(--primary-700))]"
+            >
+              OSS
+            </Badge>
+          ) : null}
+        </div>
+
+        <div className="my-4 h-px bg-[hsl(var(--border))]" />
+
+        {isActive ? (
+          <Button
+            size="sm"
+            variant="secondary"
+            disabled
+            className={cn(
+              "w-full justify-center gap-2",
+              "bg-[hsl(var(--primary-50))] text-[hsl(var(--primary-700))]",
+              "disabled:opacity-100",
+            )}
+          >
+            <Check className="h-3.5 w-3.5" />
+            当前项目
+          </Button>
+        ) : (
+          <Button
+            size="sm"
+            variant="default"
+            disabled={isSwitching}
+            onClick={onSwitch}
+            className="w-full justify-center gap-2"
+          >
+            <ArrowRightLeft className="h-3.5 w-3.5" />
+            {isSwitching ? "切换中..." : "切换为当前"}
+          </Button>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

package/dist/dashboard-runtime/dashboard/src/components/knowledge-base/kb-list.tsx

@@ -7,6 +7,7 @@ import { Button } from "@/components/ui/button";
 import { Skeleton } from "@/components/ui/skeleton";
 import { SearchInput } from "@/components/shared/search-input";
 import { EmptyState } from "@/components/shared/empty-state";
+import { ErrorState } from "@/components/shared/error-state";
 import { useKnowledgeBases } from "@/hooks/use-knowledge-bases";
 import { useDebounce } from "@/hooks/use-debounce";
 import { KBCard } from "./kb-card";
@@ -16,7 +17,7 @@ import type { KnowledgeBase } from "@/types/knowledge-base";
 type SortOption = "updatedAt" | "createdAt" | "name";
 
 export function KBList() {
-  const { data, isLoading } = useKnowledgeBases();
+  const { data, isLoading, error, refetch } = useKnowledgeBases();
   const [searchQuery, setSearchQuery] = useState("");
   const [sortBy] = useState<SortOption>("updatedAt");
   const [deleteTarget, setDeleteTarget] = useState<string | null>(null);
@@ -69,6 +70,10 @@ export function KBList() {
     );
   }
 
+  if (error) {
+    return <ErrorState error={error} onRetry={() => refetch()} />;
+  }
+
   if (!data?.items?.length) {
     return (
       <EmptyState

package/dist/dashboard-runtime/dashboard/src/components/layout/sidebar.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+import Link from "next/link";
+import { ChevronLeft, ChevronRight, Database } from "lucide-react";
+import { sidebarNav, sidebarResources } from "@/config/navigation";
+import { useSidebarCollapsed } from "@/hooks/use-sidebar-collapsed";
+import { cn } from "@/lib/utils";
+import { SidebarItem } from "./sidebar-item";
+
+export function Sidebar() {
+  const { collapsed, toggle } = useSidebarCollapsed();
+  const width = collapsed ? "w-16" : "w-[220px]";
+
+  return (
+    <aside
+      data-collapsed={collapsed}
+      className={cn(
+        "fixed left-0 top-0 bottom-0 z-40 hidden flex-col border-r border-[hsl(var(--sidebar-border))] bg-[hsl(var(--sidebar-bg))] transition-[width] duration-200 ease-out md:flex",
+        width,
+      )}
+    >
+      {/* Logo */}
+      <Link
+        href="/"
+        className={cn(
+          "flex h-16 items-center gap-2 border-b border-[hsl(var(--sidebar-border))] px-4 transition-opacity hover:opacity-80",
+          collapsed && "justify-center px-0",
+        )}
+      >
+        <span className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-primary text-primary-foreground shadow-sm">
+          <Database className="h-4 w-4" />
+        </span>
+        {!collapsed && (
+          <span className="font-display text-[15px] font-semibold tracking-tight text-foreground">
+            Agent Storage
+          </span>
+        )}
+      </Link>
+
+      {/* Main navigation */}
+      <nav className={cn("flex-1 overflow-y-auto px-3 py-4", collapsed && "px-2")}>
+        <div className="space-y-1">
+          {sidebarNav.map((item) => (
+            <SidebarItem key={item.title} item={item} collapsed={collapsed} />
+          ))}
+        </div>
+
+        {sidebarResources.length > 0 && (
+          <>
+            <div
+              className={cn(
+                "mt-6 mb-2 px-3 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground/70",
+                collapsed && "px-0 text-center",
+              )}
+            >
+              {collapsed ? "···" : "资源"}
+            </div>
+            <div className="space-y-1">
+              {sidebarResources.map((item) => (
+                <SidebarItem key={item.title} item={item} collapsed={collapsed} />
+              ))}
+            </div>
+          </>
+        )}
+      </nav>
+
+      {/* Footer: collapse toggle */}
+      <div className="border-t border-[hsl(var(--sidebar-border))] p-3">
+        <button
+          type="button"
+          onClick={toggle}
+          aria-label={collapsed ? "展开侧边栏" : "收起侧边栏"}
+          className={cn(
+            "flex h-9 w-full items-center gap-2 rounded-lg px-3 text-sm text-muted-foreground transition-colors hover:bg-accent hover:text-foreground",
+            collapsed && "justify-center px-0",
+          )}
+        >
+          {collapsed ? (
+            <ChevronRight className="h-4 w-4" />
+          ) : (
+            <>
+              <ChevronLeft className="h-4 w-4" />
+              <span>收起</span>
+            </>
+          )}
+        </button>
+      </div>
+    </aside>
+  );
+}

package/dist/dashboard-runtime/dashboard/src/components/logging/client-error-reporter.tsx

@@ -0,0 +1,59 @@
+"use client";
+
+import { useEffect } from "react";
+
+const ENDPOINT = "/api/v1/logs/client";
+
+export function reportClientError(payload: Record<string, unknown>) {
+  try {
+    const body = JSON.stringify({
+      ...payload,
+      url: typeof window !== "undefined" ? window.location.href : undefined,
+    });
+    if (navigator.sendBeacon) {
+      const blob = new Blob([body], { type: "application/json" });
+      navigator.sendBeacon(ENDPOINT, blob);
+      return;
+    }
+    void fetch(ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+      keepalive: true,
+    });
+  } catch {
+    // Logging must never affect the dashboard itself.
+  }
+}
+
+export function ClientErrorReporter() {
+  useEffect(() => {
+    const onError = (event: ErrorEvent) => {
+      reportClientError({
+        event: "browser.error",
+        message: event.message,
+        name: event.error instanceof Error ? event.error.name : "Error",
+        stack: event.error instanceof Error ? event.error.stack : undefined,
+      });
+    };
+
+    const onUnhandledRejection = (event: PromiseRejectionEvent) => {
+      const reason = event.reason;
+      reportClientError({
+        event: "browser.unhandled_rejection",
+        message: reason instanceof Error ? reason.message : String(reason),
+        name: reason instanceof Error ? reason.name : "UnhandledRejection",
+        stack: reason instanceof Error ? reason.stack : undefined,
+      });
+    };
+
+    window.addEventListener("error", onError);
+    window.addEventListener("unhandledrejection", onUnhandledRejection);
+    return () => {
+      window.removeEventListener("error", onError);
+      window.removeEventListener("unhandledrejection", onUnhandledRejection);
+    };
+  }, []);
+
+  return null;
+}

package/dist/dashboard-runtime/dashboard/src/components/memory/memory-store-list.tsx

@@ -6,6 +6,7 @@ import { Brain, Plus } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { Skeleton } from "@/components/ui/skeleton";
 import { EmptyState } from "@/components/shared/empty-state";
+import { ErrorState } from "@/components/shared/error-state";
 import { SearchInput } from "@/components/shared/search-input";
 import { useDebounce } from "@/hooks/use-debounce";
 import { useMemoryStores } from "@/hooks/use-memory-stores";
@@ -14,7 +15,7 @@ import { MemoryDeleteDialog } from "./memory-delete-dialog";
 import { MemoryStoreCard } from "./memory-store-card";
 
 export function MemoryStoreList() {
-  const { data, isLoading } = useMemoryStores();
+  const { data, isLoading, error, refetch } = useMemoryStores();
   const [searchQuery, setSearchQuery] = useState("");
   const [deleteTarget, setDeleteTarget] = useState<string | null>(null);
   const debouncedQuery = useDebounce(searchQuery, 300);
@@ -43,6 +44,10 @@ export function MemoryStoreList() {
     );
   }
 
+  if (error) {
+    return <ErrorState error={error} onRetry={() => refetch()} />;
+  }
+
   if (!data?.items?.length) {
     return (
       <EmptyState

package/dist/dashboard-runtime/dashboard/src/components/qa/markdown.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import { code } from "@streamdown/code";
+import { Streamdown, type UrlTransform } from "streamdown";
+
+import { cn } from "@/lib/utils";
+
+import { CodeBlock } from "./code-block";
+
+const ALLOWED_LINK_PREFIXES = ["https://", "http://", "mailto:", "#", "/"];
+const ALLOWED_IMAGE_PREFIXES = ["https://", "data:image/"];
+
+/**
+ * Whitelist URL scheme to mitigate XSS via javascript:/data: links while
+ * keeping inline fragments and relative paths usable inside the dashboard.
+ */
+const safeUrlTransform: UrlTransform = (url, key) => {
+  const lower = url.toLowerCase();
+  const allowList =
+    key === "src" ? ALLOWED_IMAGE_PREFIXES : ALLOWED_LINK_PREFIXES;
+  return allowList.some((prefix) => lower.startsWith(prefix)) ? url : "";
+};
+
+interface MarkdownProps {
+  children: string;
+  className?: string;
+}
+
+/**
+ * Thin wrapper around Streamdown that applies our shadcn-friendly typography
+ * and a conservative URL whitelist. Streamdown ships KaTeX, Shiki and GFM out
+ * of the box and repairs partial Markdown during streaming.
+ */
+export function Markdown({ children, className }: MarkdownProps) {
+  return (
+    <div
+      className={cn(
+        "text-sm leading-relaxed text-foreground/90",
+        "[&_p]:my-2 [&_ul]:my-2 [&_ol]:my-2 [&_li]:my-0.5",
+        "[&_ul]:list-disc [&_ul]:pl-5 [&_ol]:list-decimal [&_ol]:pl-5",
+        "[&_h1]:mt-4 [&_h1]:mb-2 [&_h1]:text-lg [&_h1]:font-semibold",
+        "[&_h2]:mt-3 [&_h2]:mb-2 [&_h2]:text-base [&_h2]:font-semibold",
+        "[&_h3]:mt-3 [&_h3]:mb-1.5 [&_h3]:text-sm [&_h3]:font-semibold",
+        "[&_a]:text-primary [&_a]:underline [&_a]:underline-offset-2",
+        // Inline code (not inside <pre>) keeps the subtle chip look. Block
+        // code is fully owned by the CodeBlock component below.
+        "[&_:not(pre)>code]:rounded [&_:not(pre)>code]:bg-[hsl(var(--muted))] [&_:not(pre)>code]:px-1 [&_:not(pre)>code]:py-0.5 [&_:not(pre)>code]:text-[0.85em]",
+        "[&_table]:my-2 [&_table]:w-full [&_table]:border-collapse",
+        "[&_th]:border [&_th]:border-[hsl(var(--border))] [&_th]:px-2 [&_th]:py-1 [&_th]:text-left [&_th]:font-semibold",
+        "[&_td]:border [&_td]:border-[hsl(var(--border))] [&_td]:px-2 [&_td]:py-1",
+        "[&_blockquote]:my-2 [&_blockquote]:border-l-2 [&_blockquote]:border-[hsl(var(--border))] [&_blockquote]:pl-3 [&_blockquote]:text-muted-foreground",
+        "[&_hr]:my-3 [&_hr]:border-[hsl(var(--border))]",
+        className,
+      )}
+    >
+      <Streamdown
+        parseIncompleteMarkdown
+        // Disable raw HTML rendering. Combined with the URL whitelist
+        // above, this closes the last XSS vector where a crafted
+        // assistant reply could embed a `<script>` or inline event
+        // handler that the Markdown → HTML path would pass through
+        // verbatim.
+        skipHtml
+        urlTransform={safeUrlTransform}
+        plugins={{ code }}
+        components={{ pre: CodeBlock }}
+        controls={{
+          code: false,
+          table: false,
+          mermaid: false,
+        }}
+      >
+        {children}
+      </Streamdown>
+    </div>
+  );
+}

package/dist/dashboard-runtime/dashboard/src/components/shared/error-state.tsx

@@ -0,0 +1,54 @@
+import { AlertTriangle, RefreshCw } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { ApiClientError } from "@/services/api-client";
+
+interface ErrorStateProps {
+  error: Error;
+  onRetry?: () => void;
+}
+
+function getHint(error: Error): string | null {
+  if (!(error instanceof ApiClientError)) return null;
+  const { status } = error;
+  if (status === 401 || status === 403) {
+    return "Please check your AccessKey credentials in the project settings.";
+  }
+  if (status === 503 || error.code === "NETWORK_ERROR") {
+    return "The service may be unreachable. Verify the endpoint address and network connectivity.";
+  }
+  return null;
+}
+
+export function ErrorState({ error, onRetry }: ErrorStateProps) {
+  const hint = getHint(error);
+
+  return (
+    <div className="flex flex-col items-center justify-center py-16 px-4 text-center">
+      <div className="mb-5 flex h-20 w-20 items-center justify-center rounded-full bg-destructive/10 ring-8 ring-destructive/5">
+        <AlertTriangle
+          className="text-destructive"
+          size={36}
+          strokeWidth={1.75}
+        />
+      </div>
+      <h3 className="mb-2 font-display text-lg font-semibold text-foreground">
+        Failed to load data
+      </h3>
+      <p className="mb-1 max-w-md text-sm text-muted-foreground">
+        {error.message}
+      </p>
+      {hint && (
+        <p className="mb-6 max-w-md text-xs text-muted-foreground/80">
+          {hint}
+        </p>
+      )}
+      {!hint && <div className="mb-6" />}
+      {onRetry && (
+        <Button variant="outline" size="sm" onClick={onRetry}>
+          <RefreshCw className="mr-2 h-4 w-4" />
+          Retry
+        </Button>
+      )}
+    </div>
+  );
+}