From ecf12392cbacacaa2af34c46281df626ea16be27 Mon Sep 17 00:00:00 2001
From: mrsibe <mrsibe@qq.com>
Date: Thu, 24 Sep 2026 18:17:51 +0800
Subject: [PATCH] fix(ui): add a top-level renderer error boundary

Any render-phase exception unmounted the whole React tree and left a
blank window with no on-screen clue. The "Add to Note" crash was the
latest example of that failure mode.

Wrap <App /> in an error boundary that keeps the error on screen, logs
the original error and component stack, and offers a reload.
---
 .../components/common/AppErrorBoundary.tsx    | 63 +++++++++++++++++++
 src/renderer/src/locales/en-US/common.json    |  3 +
 src/renderer/src/locales/zh-CN/common.json    |  3 +
 src/renderer/src/main.tsx                     |  5 +-
 4 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 src/renderer/src/components/common/AppErrorBoundary.tsx

diff --git a/src/renderer/src/components/common/AppErrorBoundary.tsx b/src/renderer/src/components/common/AppErrorBoundary.tsx
new file mode 100644
index 0000000..d5620db
--- /dev/null
+++ b/src/renderer/src/components/common/AppErrorBoundary.tsx
@@ -0,0 +1,63 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react'
+import i18n from '../../i18n'
+
+interface AppErrorBoundaryProps {
+  children: ReactNode
+}
+
+interface AppErrorBoundaryState {
+  error: Error | null
+}
+
+/**
+ * 顶层错误边界。
+ *
+ * 没有它时，任何渲染期异常都会让 React 卸载整棵组件树，窗口直接变白，用户和日志都
+ * 拿不到线索。这里把异常收敛成一个可恢复的错误页，并把原始错误写进控制台。
+ *
+ * 用 i18n 实例而不是 useTranslation：错误页必须能在 React 上下文之外渲染。
+ */
+export default class AppErrorBoundary extends Component<
+  AppErrorBoundaryProps,
+  AppErrorBoundaryState
+> {
+  state: AppErrorBoundaryState = { error: null }
+
+  static getDerivedStateFromError(error: Error): AppErrorBoundaryState {
+    return { error }
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo): void {
+    console.error('[AppErrorBoundary] Uncaught render error:', error, info.componentStack)
+  }
+
+  private handleReload = (): void => {
+    window.location.reload()
+  }
+
+  render(): ReactNode {
+    const { error } = this.state
+    if (!error) {
+      return this.props.children
+    }
+
+    return (
+      <div className="flex min-h-screen flex-col items-center justify-center gap-4 bg-surface-base p-8 text-center text-foreground">
+        <h1 className="text-lg font-medium">{i18n.t('common:errorTitle')}</h1>
+        <p className="max-w-md text-sm text-muted-foreground">
+          {i18n.t('common:errorDescription')}
+        </p>
+        <pre className="max-w-md overflow-auto rounded-md border border-border bg-surface-sunken p-3 text-left text-xs text-subtle-foreground">
+          {error.message}
+        </pre>
+        <button
+          type="button"
+          onClick={this.handleReload}
+          className="rounded-md border border-border px-3 py-1.5 text-sm hover:bg-surface-hover"
+        >
+          {i18n.t('common:reload')}
+        </button>
+      </div>
+    )
+  }
+}
diff --git a/src/renderer/src/locales/en-US/common.json b/src/renderer/src/locales/en-US/common.json
index 4cb23e4..d812378 100644
--- a/src/renderer/src/locales/en-US/common.json
+++ b/src/renderer/src/locales/en-US/common.json
@@ -32,6 +32,9 @@
   "about": "About",
   "version": "Version",
   "error": "Error",
+  "errorTitle": "Something went wrong",
+  "errorDescription": "An unexpected error occurred. Reload to continue.",
+  "reload": "Reload",
   "warning": "Warning",
   "info": "Info",
   "success": "Success"
diff --git a/src/renderer/src/locales/zh-CN/common.json b/src/renderer/src/locales/zh-CN/common.json
index 9b2633c..6b425e9 100644
--- a/src/renderer/src/locales/zh-CN/common.json
+++ b/src/renderer/src/locales/zh-CN/common.json
@@ -8,5 +8,8 @@
   "edit": "编辑",
   "loading": "加载中...",
   "error": "错误",
+  "errorTitle": "出错了",
+  "errorDescription": "发生了意外错误，请重新加载以继续。",
+  "reload": "重新加载",
   "success": "成功"
 }
diff --git a/src/renderer/src/main.tsx b/src/renderer/src/main.tsx
index 799f35d..21f6ac2 100644
--- a/src/renderer/src/main.tsx
+++ b/src/renderer/src/main.tsx
@@ -3,10 +3,13 @@ import './assets/theme.css'
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import App from './App'
+import AppErrorBoundary from './components/common/AppErrorBoundary'
 import './i18n'
 
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
-    <App />
+    <AppErrorBoundary>
+      <App />
+    </AppErrorBoundary>
   </StrictMode>
 )