feat: implement error handling and UI for RPC errors

ui/components/ActivityBubble.tsx

@@ -2,10 +2,12 @@
 
 import { type ReactNode, useEffect } from 'react'
 import { useTranslation } from 'react-i18next'
+import { CircleXIcon } from 'lucide-react'
 import { useDownloadStore } from '@/lib/downloads'
 import { Button } from '@/components/ui/button'
 import { type OperationState } from '@/lib/operations'
 import { useOperationStore } from '@/lib/stores/operationStore'
+import { useUiErrorStore } from '@/lib/stores/uiErrorStore'
 import { useDocumentMutations } from '@/lib/query/mutations'
 
 type TranslateFunc = ReturnType<typeof useTranslation>['t']
@@ -72,6 +74,47 @@ function DownloadCard({
   )
 }
 
+function ErrorCard({
+  message,
+  onDismiss,
+  t,
+}: {
+  message: string
+  onDismiss: () => void
+  t: TranslateFunc
+}) {
+  return (
+    <div className='bg-card/95 rounded-2xl border border-red-200/80 p-4 shadow-[0_15px_60px_rgba(0,0,0,0.12)] backdrop-blur dark:border-red-900/80'>
+      <div className='flex items-start gap-3'>
+        <div className='mt-0.5 flex h-8 w-8 items-center justify-center rounded-full bg-red-100 text-red-600 dark:bg-red-950/70 dark:text-red-400'>
+          <CircleXIcon className='size-4' />
+        </div>
+        <div className='min-w-0 flex-1'>
+          <div className='flex items-start justify-between gap-3'>
+            <div className='min-w-0'>
+              <div className='text-sm font-semibold text-red-700 dark:text-red-300'>
+                {t('errors.title')}
+              </div>
+              <div className='mt-1 break-words border-l-2 border-red-500 pl-3 text-xs text-red-700/90 dark:text-red-200/90'>
+                {message}
+              </div>
+            </div>
+            <Button
+              variant='ghost'
+              size='icon-xs'
+              onClick={onDismiss}
+              className='text-red-700 hover:bg-red-50 hover:text-red-800 dark:text-red-300 dark:hover:bg-red-950/60'
+              aria-label={t('errors.dismiss')}
+            >
+              <CircleXIcon className='size-3.5' />
+            </Button>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
 function OperationCard({
   operation,
   onCancel,
@@ -204,6 +247,8 @@ function OperationCard({
 export function ActivityBubble() {
   const { t } = useTranslation()
   const operation = useOperationStore((state) => state.operation)
+  const error = useUiErrorStore((state) => state.error)
+  const clearError = useUiErrorStore((state) => state.clearError)
   const { cancelOperation } = useDocumentMutations()
   const downloads = useDownloadStore((s) => s.downloads)
   const ensureSubscribed = useDownloadStore((s) => s.ensureSubscribed)
@@ -216,10 +261,11 @@ export function ActivityBubble() {
     (d) => d.status === 'started' || d.status === 'downloading',
   )
 
-  if (!operation && activeDownloads.length === 0) return null
+  if (!error && !operation && activeDownloads.length === 0) return null
 
   return (
     <div className='pointer-events-auto fixed right-6 bottom-6 z-100 flex w-80 max-w-[calc(100%-1.5rem)] flex-col gap-3'>
+      {error && <ErrorCard message={error.message} onDismiss={clearError} t={t} />}
       {operation && (
         <OperationCard operation={operation} onCancel={cancelOperation} t={t} />
       )}

ui/lib/backend.ts

@@ -3,6 +3,7 @@
 import { WsRpcClient } from './ws'
 import { fileOpen, fileSave } from 'browser-fs-access'
 import { toArrayBuffer } from './util'
+import { reportRpcError } from './errors'
 import type { RpcMethodMap, RpcNotificationMap, FileResult } from './rpc-types'
 
 // --- Singleton client ---
@@ -162,15 +163,25 @@ export async function invoke<M extends keyof RpcMethodMap>(
 
   // Special file-save flow for save_documents / export_document
   if (method === 'save_documents' || method === 'export_document') {
-    const result = await getClient().invoke<FileResult>(method, params)
-    const blob = new Blob([toArrayBuffer(result.data)])
     try {
-      await fileSave(blob, { fileName: result.filename })
-    } catch {}
-    return undefined as RpcMethodMap[M][1]
+      const result = await getClient().invoke<FileResult>(method, params)
+      const blob = new Blob([toArrayBuffer(result.data)])
+      try {
+        await fileSave(blob, { fileName: result.filename })
+      } catch {}
+      return undefined as RpcMethodMap[M][1]
+    } catch (error) {
+      reportRpcError(method, error)
+      throw error
+    }
   }
 
-  return getClient().invoke<RpcMethodMap[M][1]>(method, params)
+  try {
+    return await getClient().invoke<RpcMethodMap[M][1]>(method, params)
+  } catch (error) {
+    reportRpcError(method, error)
+    throw error
+  }
 }
 
 async function openDocumentsRpc(

ui/lib/errors.ts

@@ -0,0 +1,38 @@
+'use client'
+
+import { useUiErrorStore } from '@/lib/stores/uiErrorStore'
+
+const SURFACED_RPC_METHODS = new Set([
+  'open_documents',
+  'add_documents',
+  'save_documents',
+  'export_document',
+  'detect',
+  'ocr',
+  'inpaint',
+  'update_inpaint_mask',
+  'update_brush_layer',
+  'inpaint_partial',
+  'render',
+  'update_text_blocks',
+  'llm_load',
+  'llm_offload',
+  'llm_generate',
+  'process',
+])
+
+export const normalizeErrorMessage = (error: unknown) => {
+  if (error instanceof Error) {
+    return error.message
+  }
+  if (typeof error === 'string') {
+    return error
+  }
+  return 'Unexpected error'
+}
+
+export const reportRpcError = (method: string, error: unknown) => {
+  if (!SURFACED_RPC_METHODS.has(method)) return
+  const message = normalizeErrorMessage(error)
+  useUiErrorStore.getState().showError(message)
+}

ui/lib/stores/uiErrorStore.ts

@@ -0,0 +1,45 @@
+'use client'
+
+import { create } from 'zustand'
+
+type UiError = {
+  id: number
+  message: string
+}
+
+type UiErrorStoreState = {
+  error?: UiError
+  showError: (message: string) => void
+  clearError: () => void
+}
+
+const ERROR_AUTO_DISMISS_MS = 8000
+
+let dismissTimer: ReturnType<typeof setTimeout> | null = null
+
+const clearDismissTimer = () => {
+  if (!dismissTimer) return
+  clearTimeout(dismissTimer)
+  dismissTimer = null
+}
+
+export const useUiErrorStore = create<UiErrorStoreState>((set) => ({
+  error: undefined,
+  showError: (message) => {
+    clearDismissTimer()
+    set({
+      error: {
+        id: Date.now(),
+        message,
+      },
+    })
+    dismissTimer = setTimeout(() => {
+      dismissTimer = null
+      set({ error: undefined })
+    }, ERROR_AUTO_DISMISS_MS)
+  },
+  clearError: () => {
+    clearDismissTimer()
+    set({ error: undefined })
+  },
+}))

ui/public/locales/en-US/translation.json

@@ -153,6 +153,10 @@
   "download": {
     "title": "Downloading"
   },
+  "errors": {
+    "title": "Error",
+    "dismiss": "Dismiss"
+  },
   "settings": {
     "title": "Settings",
     "appearance": "Appearance",

ui/public/locales/es-ES/translation.json

@@ -153,6 +153,10 @@
   "download": {
     "title": "Descargando"
   },
+  "errors": {
+    "title": "Error",
+    "dismiss": "Cerrar"
+  },
   "settings": {
     "title": "Configuración",
     "appearance": "Apariencia",

ui/public/locales/ja-JP/translation.json

@@ -153,6 +153,10 @@
   "download": {
     "title": "ダウンロード中"
   },
+  "errors": {
+    "title": "エラー",
+    "dismiss": "閉じる"
+  },
   "settings": {
     "title": "設定",
     "appearance": "外観",

ui/public/locales/ru-RU/translation.json

@@ -153,6 +153,10 @@
   "download": {
     "title": "Загрузка"
   },
+  "errors": {
+    "title": "Ошибка",
+    "dismiss": "Закрыть"
+  },
   "settings": {
     "title": "Настройки",
     "appearance": "Внешний вид",

ui/public/locales/zh-CN/translation.json

@@ -153,6 +153,10 @@
   "download": {
     "title": "下载中"
   },
+  "errors": {
+    "title": "错误",
+    "dismiss": "关闭"
+  },
   "settings": {
     "title": "设置",
     "appearance": "外观",

ui/public/locales/zh-TW/translation.json

@@ -153,6 +153,10 @@
   "download": {
     "title": "下載中"
   },
+  "errors": {
+    "title": "錯誤",
+    "dismiss": "關閉"
+  },
   "settings": {
     "title": "設定",
     "appearance": "外觀",