Python 耗时可视化分析

+ + ) +} + +/** + * 用 ResizeObserver 跟踪元素当前 contentRect 的 width 或 height，返回 0 直到首次挂载后量到值。 + * 用于 splitter 把「像素 delta」换算成「fraction 增量」时拿分母 —— 容器尺寸变化（窗口 resize、 + * DevTools 开关、字号变更）都要跟上，不能依赖 mount 时的 getBoundingClientRect 一次性快照。 + */ +function useElementSize(ref: RefObject, axis: 'width' | 'height'): number { + const [size, setSize] = useState(0) + useEffect(() => { + const el = ref.current + if (!el) return + setSize(el.getBoundingClientRect()[axis]) + const ro = new ResizeObserver((entries) => { + const entry = entries[0] + if (entry) setSize(entry.contentRect[axis]) + }) + ro.observe(el) + return () => ro.disconnect() + }, [ref, axis]) + return size +} + +export default function App() { + // I18nProvider + ThemeProvider 套在 App 外面，让 App 内部所有 useT / useTheme 都拿到上下文 + return ( + + + + ) +} + +function AppInner() { + const t = useT() + const [code, setCode] = useState(DEMO_CODE) + const [selectedFuncId, setSelectedFuncId] = useState() + // 缓存最近一次运行的参数：失败页「再试一次」直接复用，不再 hack 触发隐藏按钮 + const [lastOpts, setLastOpts] = useState(null) + // SettingsModal open state —— 用 prop drilling 而非 Context，因为只 TopBar 和 Modal 两个消费点 + const [settingsOpen, setSettingsOpen] = useState(false) + const editorRef = useRef(null) + const runConfigRef = useRef(null) + const mainAreaRef = useRef(null) + // 编辑器 + 运行输出面板这一列的总高（高度方向 splitter 用）。贴在外层 wrapper 上, + // —— 因为高度 splitter 的像素 delta 需要除以「这一列的总高度」才能换算成 fraction。 + // 不贴在 #pyrof-editor-pane 上是因为它还要管宽度,语义上不如单独一个 ref 干净。 + const consoleAreaRef = useRef(null) + const { + result, + state, + progress, + errorMessage, + stderrTail, + stdout, + clearStdout, + resultScope, + run, + cancel, + reset + } = useAnalysis() + // 解释器列表提到 App 顶层：MinimalRunConfig mount 时取，不要每次 mount 重 detect + const interpreters = useInterpreters() + // 主题：useTheme 内部已经和同步 + const { theme, setTheme } = useTheme() + // 剖析范围：useScope 内部已经持久化到 localStorage.pyrof.scope + const { scope, toggle: toggleScope } = useScope() + // 打开系统终端时用的 shell（Windows: cmd / PowerShell）;非 Win 不生效 + const { shell, setShell } = useShellPreference() + + // 外部文件 tab 状态（stdlib / 第三方包热点打开的源码 tab）。 + // 用户代码 tab **不**在这里 —— 是 code state 单独持有。 + const { + externalTabs, + activeExternalId, + openFile: openExternalFile, + closeFile, + setActive: setActiveExternal, + consumePendingReveal, + closeAll: closeAllExternal + } = useExternalFiles() + + // —— 区域尺寸（编辑器 ↔ 结果区） —— + // 用 ResizeObserver 跟踪主区宽度，拖拽时按「像素 delta / 主区宽度」换算成比例 + // （窗口尺寸变化或 DevTools 开关 / 字号变更都会让宽度变；不是 mount 时一次性 getBoundingClientRect） + const mainAreaWidth = useElementSize(mainAreaRef, 'width') + const { fraction: leftFrac, applyDelta: applyLeftDelta } = useResizableFraction('pyrof.split.main', { + default: 0.5, + min: 0.2, + max: 0.8 + }) + + // —— 区域尺寸（编辑器 ↔运行输出面板） —— + // 同样的 fraction + ResizeObserver 模式,跟主区 splitter 完全对称。min=0 是因为 + // 用户可能想把输出区拖到完全消失(隐藏),最大留 60% 是因为太高会挤压编辑器。 + // consoleFraction 是「console 高度 / 该列总高」,applyDelta(dy, height) 拿 + // 像素增量除以总高换算成 fraction。 + const consoleAreaHeight = useElementSize(consoleAreaRef, 'height') + const { fraction: consoleFrac, applyDelta: applyConsoleDelta } = useResizableFraction( + 'pyrof.split.console', + { + default: 0.25, + min: 0, + max: 0.6 + } + ) + // 「收起」按钮的折叠状态：放在 App 里是为了让 wrapper 高度跟着收缩 —— 只藏 body 的话 + // consoleFrac * 100% 还占着列高,header 下面会留一大块空白,看起来没收完。 + // 高度降到 auto 让 wrapper 只剩 header(≈44px),editor 段在 flex-1 里把多出来的空间拿走。 + const [consoleCollapsed, setConsoleCollapsed] = useState(false) + + // 全局快捷键：Ctrl/Cmd+Enter 运行；Esc 取消 + // state 通过 ref 引用：避免每次 state 变化都 remove + addEventListener（每帧 rebuild 监听是浪费）。 + const stateRef = useRef(state) + stateRef.current = state + + // 编辑器内 Ctrl+Enter：Monaco 会拦截这个键（默认行为是「下方插入新行」），必须通过 addCommand 接管； + // 走 window keydown 收不到，因为 Monaco 在 capture 阶段 stopPropagation 了。 + const triggerRun = useCallback(() => { + if (stateRef.current === 'running') void cancel() + else runConfigRef.current?.run() + }, [cancel]) + + useEffect(() => { + const onKey = (e: KeyboardEvent) => { + // SettingsModal 打开时，Esc 已经被 Modal 在 capture 阶段 stopPropagation 截走， + // 不会到这里取消运行（保留 Esc 取消运行的语义由 Modal 决定）。 + const cmdKey = e.metaKey || e.ctrlKey + const target = e.target as HTMLElement | null + const inMonaco = !!target?.closest('.monaco-editor') + if (cmdKey && e.key === 'Enter') { + if (inMonaco) return + e.preventDefault() + triggerRun() + } else if (e.key === 'Escape' && stateRef.current === 'running') { + e.preventDefault() + void cancel() + } + } + window.addEventListener('keydown', onKey) + return () => window.removeEventListener('keydown', onKey) + }, [cancel, triggerRun]) + + const selectHotspot = useCallback( + (fn: FunctionNode) => { + setSelectedFuncId(fn.id) + const origin = resolveOrigin(fn) + // 路由按 origin 分流： + // - user: 文件路径已不存在（profiler-service 在 tmpdir 建的脚本被 rm 掉）， + // 只能 highlight 当前用户代码编辑器里的行。 + // - builtin / frozen: cProfile 给的是虚拟帧，没有源文件。静默 no-op + // —— toast 太吵，每次 run 都有几条。 + // - stdlib / third_party / other: 打开对应文件 tab，编辑器只读 + reveal line。 + if (origin === 'user') { + editorRef.current?.revealLine(fn.line) + return + } + if (origin === 'builtin' || origin === 'frozen') return + if (!fn.file) return + openExternalFile(fn.file, fn.line, origin) + }, + [openExternalFile] + ) + + const onRun = useCallback( + (opts: RunOptions) => { + setLastOpts(opts) + setSelectedFuncId(undefined) + editorRef.current?.clearHighlight() + // 注意：不清外部 tab —— 用户可能正在读源文件比对，新一轮结果不影响已开的源文件。 + void run(opts) + }, + [run] + ) + + // 「范围已切换」提示条上的「以新范围重跑」按钮 —— 用最近一次 run 的 opts + // 把 scope 换成当前的,然后再跑一次。不在 onRun 里偷换 scope 是为了不让 + // 普通 Retry 路径跟着 scope toggle 走（错误页 Retry 应当 100% 复用旧参数）。 + const onRerunWithCurrentScope = useCallback(() => { + if (!lastOpts) return + void onRun({ ...lastOpts, scope }) + }, [lastOpts, scope, onRun]) + + // 「加载示例 / 新建空白」共用一条复位通道 —— 这两个动作是"重置整个工作区"语义， + // 顺手把外部 tab 也清空（用户切到完全不同的代码，原来开的 numpy / json tab 也没用了）。 + // 用工厂函数接受目标 code,deps 只跟 reset 走,避免两个 callback 各持一份 closure。 + // 完全空串而不是 '\n'：'\n' 会让 Monaco 渲染一个 phantom 行（视觉上「两行空着」）， + // 且 Monaco 对 '' 的处理已经合理——光标落在 line 1 column 1，行号正常。 + const resetWorkspace = useCallback( + (nextCode: string) => { + setCode(nextCode) + editorRef.current?.clearHighlight() + setSelectedFuncId(undefined) + setLastOpts(null) + closeAllExternal() + reset() + }, + [reset, closeAllExternal] + ) + const onLoadSample = useCallback(() => resetWorkspace(DEMO_CODE), [resetWorkspace]) + const onNewBlank = useCallback(() => resetWorkspace(''), [resetWorkspace]) + + // aria-live 状态播报 + const liveMessage = + state === 'running' + ? t('app.live.running', { pct: progress?.pct ?? 0 }) + : state === 'done' && result?.status === 'ok' + ? t('app.live.done') + : state === 'error' + ? t('app.live.error', { message: errorMessage ?? t('errorBanner.unknown') }) + : '' + + // 派生给 EditorTabs / CodePanel 的状态。 + // editorTabId: null 时 = 用户 tab，否则是外部 tab id。 + const editorTabId = activeExternalId ?? 'user' + // knownTabIds: CodePanel 用来 dispose 不再存在的 tab 对应的 model。 + const knownTabIds = useMemo(() => ['user', ...externalTabs.map((tb) => tb.id)], [externalTabs]) + // modelContentByTabId: CodePanel 重建外部 tab model 用的内容快照。 + // 只在 ready 时塞（loading 状态 model 内部用 '' 占位，empty content 也合理）。 + const modelContentByTabId = useMemo>(() => { + const out: Record = {} + for (const tb of externalTabs) { + // 即使 status=error 也把 message 塞进去 —— tab 内显示的「错误」只是 banner， + // Monaco 区域仍然用 message 占位（避免模型换空字符串让 cursor 跳 line 1）。 + out[tb.id] = tb.content + } + return out + }, [externalTabs]) + // 活跃 tab 应展示的内容（外部触发 setValue 时用）。 + // 用户 tab：等于 code。外部 tab：等于该 tab 的 content。 + const activeContent = editorTabId === 'user' ? code : (modelContentByTabId[editorTabId] ?? '') + // 只读条件：外部 tab 一律只读；运行中所有 tab 都只读。 + const isReadOnly = editorTabId !== 'user' || state === 'running' + + // 外部 tab 从 loading → ready 时，调 revealLine 把光标移到对应行。 + // useExternalFiles.openFile 时已经把 {tabId, line} 暂存到 pendingRevealRef， + // 这里把 ref 里的最新一条拿出来 revealLine（多次点击同一 tab → 只有最新的 line）。 + // 依赖 externalTabs 而不是 [status] 是为了在 effect 里能遍历到最新列表。 + useEffect(() => { + const reveal = consumePendingReveal() + if (!reveal) return + // 只对当前 active tab 的 reveal 感兴趣 —— 如果用户已经切到别的 tab， + // 暂存的 revealLine 属于旧 tab，不该在新 tab 强制跳行 + if (reveal.tabId !== editorTabId) return + editorRef.current?.revealLine(reveal.line) + }, [externalTabs, editorTabId, consumePendingReveal]) + + // 切到用户 tab 时，如果 pending reveal 暂存的是 user tab 的 line（理论上不会）也走 reveal。 + // 实际场景是「已经在 user tab 高亮状态下，点 user 热点」—— 但 selectHotspot 走的是 + // editorRef.current?.revealLine（不走 openFile），所以 pendingReveal 不会被填 user tab。 + // 这条 effect 仍然是兜底：用户代码状态从 loading 过渡的极端场景（理论上不存在）。 + useEffect(() => { + if (editorTabId !== 'user') return + const reveal = consumePendingReveal() + if (!reveal) return + if (reveal.tabId === 'user') { + editorRef.current?.revealLine(reveal.line) + } + // user tab 的 reveal 在 selectHotspot 里同步触发，这里只兜底； + // 如果 reveal.tabId 是某个外部 tab 但当前 editorTabId === 'user'，丢弃即可。 + }, [editorTabId, consumePendingReveal]) + + // FileReadErrorKind → i18n key 后缀。放在模块作用域（不依赖任何 state）避免每次渲染 + // 重新建一次表 —— 'unknown' 走不同分支（catch 兜底 message），不在表里。 + const editorTabs: EditorTabView[] = useMemo(() => { + const userTab: EditorTabView = { + id: 'user', + displayName: t('editorTab.user'), + origin: 'user', + closable: false + } + const ext: EditorTabView[] = externalTabs.map((tb) => ({ + id: tb.id, + displayName: tb.displayName, + origin: tb.origin, + closable: true, + status: tb.status, + errorTitle: errorTitleForTab(tb, t) + })) + return [userTab, ...ext] + }, [externalTabs, t]) + + // EditorTabs onSelect 收到 tabId；如果是 null（关掉最后一个外部 tab 后 user tab 仍 active）， + // 永远走 user。EditorTabs 当前不传 null —— active 切到 user 就是 onSelect('user')。 + const onEditorTabSelect = useCallback( + (tabId: string) => { + if (tabId === 'user') setActiveExternal(null) + else setActiveExternal(tabId) + }, + [setActiveExternal] + ) + + // 关外部 tab 时，如果关的是 active —— useExternalFiles.closeFile 会自动把 activeExternalId + // 置 null（App 这边等价于切回 user）。这里只需要原样转发。 + const onEditorTabClose = useCallback( + (tabId: string) => { + closeFile(tabId) + }, + [closeFile] + ) + + return ( +

+ setSettingsOpen(true)} + theme={theme} + setTheme={setTheme} + onOpenTerminal={() => void window.api.openTerminal(undefined, shell)} + /> + + setSettingsOpen(false)} + interpreters={interpreters} + shell={shell} + setShell={setShell} + /> + +

+ {/* mainArea:内层 flex row,管理编辑器 ↔ 结果区的宽度分配（v-splitter）。 + ResizeObserver 绑在这里——拖拽时用它换算像素 delta 到 fraction */} +

+ {/* Left: editor with its own header. + flexShrink:0 让左栏不被压扁,左宽由 leftFrac 决定;右栏 flex-1 拿剩余空间 */} +

+ + {/* + consoleAreaRef:水平 splitter + RunConsole 共用这一列的高度作为 fraction 分母。 + 编辑器段在 flex-1 上自适应剩余空间,RunConsole 段取 consoleFrac 占比的固定高度—— + 两条路径一起让"拖到顶就只剩编辑器,拖到底底就只剩 console"成为一条简单的不变量。 + consoleHeight=0 时 consoleFrac*100%=0%,wrapper 高度为 0,splitter 紧贴编辑器底边, + 视觉上等同于「运行输出完全收起」(但 splitter 仍在,方便拖回来)。 + */} +

+ +

+ }> + + +

+ applyConsoleDelta(dy, consoleAreaHeight)} + ariaLabel={t('splitter.console.aria')} + ariaControls={['pyrof-editor-panel', 'pyrof-console']} + // ariaValue 用像素单位，跟主 splitter 一致：applyDelta 用的 dy 同单位， + // 这样 Home/End 才能一次推到 min=0 / max=0.6，否则 pixel fraction 算出来 + // 太小被 clamp 到边界时键盘步进没反应 + ariaValueNow={consoleAreaHeight > 0 ? Math.round(consoleFrac * consoleAreaHeight) : undefined} + ariaValueMin={0} + ariaValueMax={consoleAreaHeight > 0 ? Math.round(0.6 * consoleAreaHeight) : undefined} + /> +

+ +

+ + applyLeftDelta(dx, mainAreaWidth)} + ariaLabel={t('splitter.main.aria')} + ariaControls={['pyprof-editor-pane', 'pyprof-results']} + // ariaValue 用像素单位 —— 跟 applyLeftDelta(dx, width) 里 dx 同单位, + // Splitter 的 Home/End 才会真的推到 min/max;否则 fraction*100 / width + // 算出来的 fraction delta 太小,clamp 到不到边界 + ariaValueNow={mainAreaWidth > 0 ? Math.round(leftFrac * mainAreaWidth) : undefined} + ariaValueMin={mainAreaWidth > 0 ? Math.round(0.2 * mainAreaWidth) : undefined} + ariaValueMax={mainAreaWidth > 0 ? Math.round(0.8 * mainAreaWidth) : undefined} + /> + + {/* Right: results or empty state */} +

+ {state === 'error' ? ( + + ) : result && result.status !== 'ok' ? ( + + ) : result && result.status === 'ok' ? ( + + ) : ( + setSettingsOpen(true)} + /> + )} +

+ + {/* aria-live 状态播报 */} +

+ {liveMessage} +

+ ) +} diff --git a/src/renderer/src/__tests__/App.test.tsx b/src/renderer/src/__tests__/App.test.tsx new file mode 100644 index 0000000..9140e8a --- /dev/null +++ b/src/renderer/src/__tests__/App.test.tsx @@ -0,0 +1,549 @@ +import { forwardRef, useImperativeHandle } from 'react' +import { act, fireEvent, render, screen, waitFor } from '@testing-library/react' +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import App from '../App' +import type { AnalysisResult, ProgressEvent } from '../../../shared/analysis' + +/** + * Mock CodePanelLazy — 真实 CodePanel 拉 Monaco 会拖垮 jsdom（10+ MB）。 + * 这里用一个 stub forwardRef 暴露 CodePanelHandle 接口：revealLine / clearHighlight / getValue。 + * App 顶层 editorRef.current?.xxx() 全部走这条路。 + */ +vi.mock('../components/CodePanelLazy', () => ({ + default: forwardRef< + { revealLine: (n: number) => void; clearHighlight: () => void; getValue: () => string }, + { + value: string + onChange: (v: string) => void + disabled?: boolean + onCtrlEnter?: () => void + } + >(function CodePanelStub({ value, onChange, onCtrlEnter }, ref) { + useImperativeHandle(ref, () => ({ + revealLine: () => {}, + clearHighlight: () => {}, + getValue: () => value + })) + return ( +

onChange(e.target.value)} />
+        <button data-testid="ctrl-enter-stub" onClick={onCtrlEnter}>
+          Ctrl+Enter
+        </button>
+      </div>
+    )
+  })
+}))
+
+const SAMPLE_INTERP = {
+  path: 'C:/python/python.exe',
+  version: '3.11.0'
+}
+
+const FAKE_OK: AnalysisResult = {
+  schemaVersion: 2,
+  environment: { python: '3.11', platform: 'win32', processor: 'x86_64', timerResolution: 1e-7 },
+  config: {},
+  status: 'ok',
+  wallTime: { seconds: 0.42, unit: 's' },
+  functions: [
+    {
+      id: 'a.py:1:foo',
+      file: 'a.py',
+      line: 1,
+      name: 'foo',
+      module: '<user>',
+      cumtime: 0.5,
+      tottime: 0.3,
+      ncalls: 10,
+      percallTot: 0.03
+    }
+  ],
+  flame: null
+}
+
+const FAKE_SYNTAX_ERROR: AnalysisResult = {
+  schemaVersion: 2,
+  environment: { python: '3.11', platform: 'win32', processor: 'x86_64', timerResolution: 1e-7 },
+  config: {},
+  status: 'syntax_error',
+  error: { type: 'SyntaxError', message: 'unexpected EOF while parsing (<unknown>, line 3)' },
+  wallTime: null,
+  functions: [],
+  flame: null
+}
+
+const FAKE_RUNTIME_ERROR: AnalysisResult = {
+  schemaVersion: 2,
+  environment: { python: '3.11', platform: 'win32', processor: 'x86_64', timerResolution: 1e-7 },
+  config: {},
+  status: 'runtime_error',
+  error: {
+    type: 'RuntimeError',
+    message: 'ZeroDivisionError: division by zero',
+    traceback: 'Traceback...\n  File "user_script.py", line 2, in <module>'
+  },
+  wallTime: null,
+  functions: [],
+  flame: null
+}
+
+const FAKE_TIMEOUT: AnalysisResult = {
+  schemaVersion: 2,
+  environment: { python: '3.11', platform: 'win32', processor: 'x86_64', timerResolution: 1e-7 },
+  config: {},
+  status: 'timeout',
+  error: { type: 'Timeout', message: '运行超过 30s 已终止', stderrTail: '...' },
+  wallTime: null,
+  functions: [],
+  flame: null
+}
+
+/**
+ * 多 origin 结果：user + stdlib + third_party。
+ * 用于「点 stdlib 热点 → 开新 tab」路由测试 —— FAKE_OK 只有 user 起源点
+ * 触发不出读文件路径。
+ */
+const FAKE_OK_MULTI_ORIGIN: AnalysisResult = {
+  schemaVersion: 2,
+  environment: { python: '3.11', platform: 'win32', processor: 'x86_64', timerResolution: 1e-7 },
+  config: {},
+  status: 'ok',
+  wallTime: { seconds: 0.42, unit: 's' },
+  functions: [
+    {
+      id: 'user:1:main',
+      file: 'a.py',
+      line: 1,
+      name: 'main',
+      module: 'a',
+      cumtime: 0.5,
+      tottime: 0.05,
+      ncalls: 1,
+      percallTot: 0.05
+    },
+    {
+      id: 'stdlib-json-loads:355:loads',
+      file: 'C:\\Python311\\Lib\\json\\decoder.py',
+      line: 355,
+      name: 'loads',
+      module: 'json',
+      cumtime: 0.3,
+      tottime: 0.25,
+      ncalls: 5,
+      percallTot: 0.05
+    },
+    {
+      id: 'stdlib-json-scanstring:355:scanstring',
+      file: 'C:\\Python311\\Lib\\json\\decoder.py',
+      line: 100,
+      name: 'scanstring',
+      module: 'json',
+      cumtime: 0.1,
+      tottime: 0.05,
+      ncalls: 50,
+      percallTot: 0.001
+    },
+    {
+      id: 'numpy-sum:42:sum',
+      file: 'C:\\Python311\\Lib\\site-packages\\numpy\\core\\fromnumeric.py',
+      line: 42,
+      name: 'sum',
+      module: 'numpy',
+      cumtime: 0.1,
+      tottime: 0.08,
+      ncalls: 1,
+      percallTot: 0.08
+    }
+  ],
+  flame: null
+}
+
+interface FakeApi {
+  analyze: ReturnType<typeof vi.fn>
+  cancel: ReturnType<typeof vi.fn>
+  detectInterpreters: ReturnType<typeof vi.fn>
+  pickInterpreter: ReturnType<typeof vi.fn>
+  readFile: ReturnType<typeof vi.fn>
+  onProgress: (cb: (e: ProgressEvent) => void) => () => void
+  emit: (e: ProgressEvent) => void
+  // 顶栏 Logo 通过 IPC 取 icon.ico data URL。null 让 Logo 走 SVG fallback，
+  // 单测不依赖真实图标渲染
+  getAppIcon: ReturnType<typeof vi.fn>
+  // useAnalysis 在 mount 时订阅 stdout chunk —— 测试不验 stdout 累积,
+  // 只给个 noop unsubscribe 防止"is not a function" 报错让 React 报错。
+  onStdout: (cb: (chunk: string) => void) => () => void
+  // 自定义窗口控制：测试里不触发实际 IPC,提供 noop stub 防止 WindowControls
+  // mount 时调用 isMaximized 报 "undefined" 错。返回 false 模拟默认未最大化。
+  windowControls: {
+    minimize: ReturnType<typeof vi.fn>
+    toggleMaximize: ReturnType<typeof vi.fn>
+    close: ReturnType<typeof vi.fn>
+    isMaximized: ReturnType<typeof vi.fn>
+    onMaximizeChanged: (cb: (isMaximized: boolean) => void) => () => void
+  }
+}
+
+let handlers: Array<(e: ProgressEvent) => void> = []
+let stdoutHandlers: Array<(chunk: string) => void> = []
+let maximizeHandlers: Array<(isMaximized: boolean) => void> = []
+
+function installFakeApi(): FakeApi {
+  handlers = []
+  stdoutHandlers = []
+  maximizeHandlers = []
+  const api: FakeApi = {
+    analyze: vi.fn().mockResolvedValue(FAKE_OK),
+    cancel: vi.fn().mockResolvedValue(undefined),
+    detectInterpreters: vi.fn().mockResolvedValue([SAMPLE_INTERP]),
+    pickInterpreter: vi.fn().mockResolvedValue(null),
+    readFile: vi.fn(),
+    onProgress: (cb) => {
+      handlers.push(cb)
+      return () => {
+        const i = handlers.indexOf(cb)
+        if (i >= 0) handlers.splice(i, 1)
+      }
+    },
+    emit: (e) => {
+      for (const h of handlers.slice()) h(e)
+    },
+    getAppIcon: vi.fn().mockResolvedValue(null),
+    onStdout: (cb) => {
+      stdoutHandlers.push(cb)
+      return () => {
+        const i = stdoutHandlers.indexOf(cb)
+        if (i >= 0) stdoutHandlers.splice(i, 1)
+      }
+    },
+    windowControls: {
+      minimize: vi.fn().mockResolvedValue(undefined),
+      toggleMaximize: vi.fn().mockResolvedValue({ isMaximized: false }),
+      close: vi.fn().mockResolvedValue(undefined),
+      isMaximized: vi.fn().mockResolvedValue(false),
+      onMaximizeChanged: (cb) => {
+        maximizeHandlers.push(cb)
+        return () => {
+          const i = maximizeHandlers.indexOf(cb)
+          if (i >= 0) maximizeHandlers.splice(i, 1)
+        }
+      }
+    }
+  }
+  ;(window as unknown as { api: FakeApi }).api = api
+  return api
+}
+
+beforeEach(() => {
+  window.localStorage.clear()
+  installFakeApi()
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('App', () => {
+  it('首次启动显示 EmptyState', async () => {
+    render(<App />)
+    expect(await screen.findByText(/粘贴代码，马上知道慢在哪/)).toBeInTheDocument()
+  })
+
+  it('Ctrl+Enter 触发运行（window keydown，非编辑器区域）', async () => {
+    const api = installFakeApi()
+    let resolveAnalyze!: (r: AnalysisResult) => void
+    api.analyze.mockImplementationOnce(() => new Promise<AnalysisResult>((r) => (resolveAnalyze = r)))
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    // 焦点不在 Monaco — window keydown 应该被处理。
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    expect(api.analyze).toHaveBeenCalled()
+    await act(async () => {
+      resolveAnalyze(FAKE_OK)
+    })
+    // 跑完后：state='done' + result=FAKE_OK → 渲染 ResultsPanel（含 RunSummaryLite）
+    expect(await screen.findByText(/本次耗时/)).toBeInTheDocument()
+  })
+
+  it('Esc 在 running 时取消', async () => {
+    const api = installFakeApi()
+    let resolveAnalyze!: (r: AnalysisResult) => void
+    api.analyze.mockImplementationOnce(() => new Promise<AnalysisResult>((r) => (resolveAnalyze = r)))
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    fireEvent.keyDown(document.body, { key: 'Escape' })
+    expect(api.cancel).toHaveBeenCalled()
+    await act(async () => {
+      resolveAnalyze(FAKE_OK)
+    })
+  })
+
+  it('运行成功后展示 ResultsPanel + 热点表', async () => {
+    const api = installFakeApi()
+    api.analyze.mockResolvedValueOnce(FAKE_OK)
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    // RunSummaryLite 显示「本次耗时」
+    expect(await screen.findByText(/本次耗时/)).toBeInTheDocument()
+  })
+
+  it('result.status === syntax_error 渲染 FailureResult + 标题「语法错误」', async () => {
+    const api = installFakeApi()
+    api.analyze.mockResolvedValueOnce(FAKE_SYNTAX_ERROR)
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    expect(await screen.findByText(/语法错误/)).toBeInTheDocument()
+    expect(screen.getByText(/unexpected EOF/)).toBeInTheDocument()
+  })
+
+  it('runtime_error 渲染 FailureResult + traceback', async () => {
+    const api = installFakeApi()
+    api.analyze.mockResolvedValueOnce(FAKE_RUNTIME_ERROR)
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    expect(await screen.findByText(/ZeroDivisionError/)).toBeInTheDocument()
+  })
+
+  it('timeout 走 FailureResult', async () => {
+    const api = installFakeApi()
+    api.analyze.mockResolvedValueOnce(FAKE_TIMEOUT)
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    expect(await screen.findByText(/超时/)).toBeInTheDocument()
+  })
+
+  it('IPC 抛错（state === error）渲染 ErrorBanner', async () => {
+    const api = installFakeApi()
+    api.analyze.mockImplementationOnce(() => Promise.reject(new Error('boom from ipc')))
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    expect(await screen.findByRole('button', { name: /再试一次/ })).toBeInTheDocument()
+  })
+
+  it('ErrorBanner 的「再试一次」用最近一次 opts 触发 run', async () => {
+    const api = installFakeApi()
+    api.analyze
+      .mockImplementationOnce(() => Promise.reject(new Error('first fail')))
+      .mockImplementationOnce(() => Promise.resolve(FAKE_OK))
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    const retryBtn = await screen.findByRole('button', { name: /再试一次/ })
+    expect(api.analyze).toHaveBeenCalledTimes(1)
+    await act(async () => {
+      fireEvent.click(retryBtn)
+    })
+    expect(api.analyze).toHaveBeenCalledTimes(2)
+  })
+
+  it('加载示例 → useAnalysis.reset → 清掉旧 result', async () => {
+    const api = installFakeApi()
+    api.analyze.mockResolvedValueOnce(FAKE_OK)
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    await screen.findByText(/本次耗时/)
+    const sampleBtns = screen.getAllByRole('button', { name: /加载示例/ })
+    fireEvent.click(sampleBtns[0])
+    expect(await screen.findByText(/粘贴代码，马上知道慢在哪/)).toBeInTheDocument()
+  })
+
+  it('result 出来后 <result> 区有 id="pyprof-results"', async () => {
+    const api = installFakeApi()
+    api.analyze.mockResolvedValueOnce(FAKE_OK)
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    await screen.findByText(/本次耗时/)
+    expect(document.getElementById('pyprof-results')).toBeInTheDocument()
+  })
+
+  it('默认 scope=all 透传到 analyze；点 toggle 后 scope=user', async () => {
+    const api = installFakeApi()
+    api.analyze.mockResolvedValue(FAKE_OK)
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    // 第一次 Ctrl+Enter：默认 scope=all（含库函数）
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    await waitFor(() => {
+      expect(api.analyze).toHaveBeenCalled()
+    })
+    const firstCall = api.analyze.mock.calls[0]?.[0] as { scope?: string } | undefined
+    expect(firstCall?.scope).toBe('all')
+
+    // 点 toggle 开关（默认展示「含库函数」，点一下变成「仅用户代码」）
+    const toggleBtn = await screen.findByRole('switch', { name: /剖析范围.*点击切换/ })
+    fireEvent.click(toggleBtn)
+
+    // 第二次 Ctrl+Enter：scope=user
+    api.analyze.mockClear()
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    await waitFor(() => {
+      expect(api.analyze).toHaveBeenCalled()
+    })
+    const secondCall = api.analyze.mock.calls[0]?.[0] as { scope?: string } | undefined
+    expect(secondCall?.scope).toBe('user')
+  })
+
+  // —— 外部文件 tab 路由：selectHotspot 按 origin 分流 ——
+  it('点 user 热点：不开新 tab，不调 readFile（revealLine 用户代码即可）', async () => {
+    const api = installFakeApi()
+    api.analyze.mockResolvedValueOnce(FAKE_OK)
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    await screen.findByText(/本次耗时/)
+
+    // tablist 只有一个 user tab
+    expect(screen.getAllByRole('tab')).toHaveLength(1)
+    expect(screen.getByRole('tab', { name: '你的代码' })).toBeInTheDocument()
+
+    // 点 user 热点行 → onSelectHotspot(fn) → revealLine，不发 IPC
+    // HotspotTable 的 aria-label 形如: foo（用户代码） 第 1 行 · 自耗时 ...
+    fireEvent.click(screen.getByRole('button', { name: /foo.*第 1 行/ }))
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(api.readFile).not.toHaveBeenCalled()
+    expect(screen.getAllByRole('tab')).toHaveLength(1)
+  })
+
+  it('点 stdlib 热点：调 readFile + 新 tab 出现（displayName=json/decoder.py）', async () => {
+    const api = installFakeApi()
+    api.analyze.mockResolvedValueOnce(FAKE_OK_MULTI_ORIGIN)
+    api.readFile.mockResolvedValueOnce({
+      kind: 'ok',
+      content: 'def loads(s, ...):\n    ...\n',
+      size: 28
+    })
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    await screen.findByText(/本次耗时/)
+
+    // 默认 scope=all —— stdlib / numpy 直接就在 result.functions 里,无需切 toggle
+    const loadsRow = await screen.findByRole('button', { name: /loads.*第 355 行/ })
+    await act(async () => {
+      fireEvent.click(loadsRow)
+    })
+    // IPC 调用
+    await waitFor(() => {
+      expect(api.readFile).toHaveBeenCalledWith({
+        filePath: 'C:\\Python311\\Lib\\json\\decoder.py'
+      })
+    })
+    // 新 tab 出现，displayName 应该是 json/decoder.py
+    expect(await screen.findByRole('tab', { name: 'json/decoder.py' })).toBeInTheDocument()
+    // tablist 现在有 user + ext 两个 tab
+    expect(screen.getAllByRole('tab')).toHaveLength(2)
+  })
+
+  it('点同一 stdlib 热点两次：去重生效,不重复调 readFile,只切 active', async () => {
+    const api = installFakeApi()
+    api.analyze.mockResolvedValueOnce(FAKE_OK_MULTI_ORIGIN)
+    api.readFile.mockResolvedValueOnce({
+      kind: 'ok',
+      content: 'def loads(...): ...\n',
+      size: 22
+    })
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    await screen.findByText(/本次耗时/)
+
+    // 默认 scope=all —— stdlib / numpy 直接就在 result.functions 里,无需切 toggle
+    const loadsRow = await screen.findByRole('button', { name: /loads.*第 355 行/ })
+    // 第一次点
+    await act(async () => {
+      fireEvent.click(loadsRow)
+    })
+    await waitFor(() => {
+      expect(api.readFile).toHaveBeenCalledTimes(1)
+    })
+    expect(screen.getAllByRole('tab')).toHaveLength(2)
+
+    // 切回 user tab（不关 ext）
+    await act(async () => {
+      fireEvent.click(screen.getByRole('tab', { name: '你的代码' }))
+    })
+
+    // 第二次点同一个 stdlib 热点 → 应该激活已有 tab,不重复 IPC
+    await act(async () => {
+      fireEvent.click(loadsRow)
+    })
+    // 等 IPC promise 链跑完
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 0))
+    })
+    expect(api.readFile).toHaveBeenCalledTimes(1)
+    expect(screen.getAllByRole('tab')).toHaveLength(2)
+  })
+
+  it('加载示例 → 外部 tab 全部清空(reset 工作区语义)', async () => {
+    const api = installFakeApi()
+    api.analyze.mockResolvedValueOnce(FAKE_OK_MULTI_ORIGIN)
+    api.readFile.mockResolvedValueOnce({
+      kind: 'ok',
+      content: 'def loads(...): ...\n',
+      size: 22
+    })
+    render(<App />)
+    await waitFor(() => {
+      expect(api.detectInterpreters.mock.calls.length).toBeGreaterThan(0)
+    })
+    fireEvent.keyDown(document.body, { key: 'Enter', ctrlKey: true })
+    await screen.findByText(/本次耗时/)
+
+    // 默认 scope=all —— stdlib / numpy 直接就在 result.functions 里,无需切 toggle
+    // 点 stdlib 热点 → 开 tab
+    const loadsRow = await screen.findByRole('button', { name: /loads.*第 355 行/ })
+    await act(async () => {
+      fireEvent.click(loadsRow)
+    })
+    await waitFor(() => {
+      expect(screen.getAllByRole('tab')).toHaveLength(2)
+    })
+
+    // 加载示例 → 外部 tab 应清空
+    const sampleBtns = screen.getAllByRole('button', { name: /加载示例/ })
+    await act(async () => {
+      fireEvent.click(sampleBtns[0])
+    })
+    // tablist 只剩 user tab
+    expect(screen.getAllByRole('tab')).toHaveLength(1)
+  })
+})
diff --git a/src/renderer/src/components/CodePanel.tsx b/src/renderer/src/components/CodePanel.tsx
new file mode 100644
index 0000000..d97bfa9
--- /dev/null
+++ b/src/renderer/src/components/CodePanel.tsx
@@ -0,0 +1,326 @@
+import { forwardRef, useEffect, useImperativeHandle, useRef } from 'react'
+import type { OnMount } from '@monaco-editor/react'
+import Editor, { type Monaco } from '@monaco-editor/react'
+import type { editor as MonacoEditor } from 'monaco-editor'
+import type { Theme } from '../hooks/useTheme'
+
+export interface CodePanelHandle {
+  revealLine: (line: number) => void
+  clearHighlight: () => void
+  getValue: () => string
+}
+
+interface Props {
+  /**
+   * 当前活跃 tab 的 id。`'user'` 是用户代码 tab（唯一一个可写的），
+   * 其他值是外部文件 tab 的 id（useExternalFiles 分配）。
+   * CodePanel 用它决定切到哪个 model。
+   */
+  activeTabId: string
+  /**
+   * 当前活跃 tab 应显示的内容。
+   * - 用户 tab：等于 App.tsx 的 code state（外部触发 setValue 用）
+   * - 外部 tab：等于该 tab 的 content（loading 时是 ''）
+   *
+   * CodePanel 不 watch 这条 prop 的变化来 setValue —— 用户 tab 走 onChange 双向绑定，
+   * 外部 tab 走 modelContentByTabId 缓存。activeContent 只用于 revealLine 后让 getValue
+   * 拿到的内容跟 UI 一致。
+   */
+  activeContent: string
+  /** true 时禁用编辑（外部文件 tab）。跟 disabled（运行中）取或。 */
+  readOnly: boolean
+  /** 外部文件 tab 的内容缓存：tabId → content。切回时拿到之前的内容重建 model。 */
+  modelContentByTabId: Record<string, string>
+  /**
+   * 仍然存在的 tab id 列表（user + 所有外部 tab）。
+   * CodePanel 在 effect 里 reconcile：列表外的 model 会被 dispose，避免关 tab 漏 model。
+   * App.tsx 从 useExternalFiles 拿到 externalTabs 后拼上 'user' 传进来。
+   */
+  knownTabIds: readonly string[]
+  /**
+   * 用户编辑触发。**只在 activeTabId === 'user' 时**由 Monaco onChange 回调；
+   * 外部 tab 是 read-only，Monaco 不会触发 onChange，但仍传入以防未来扩展。
+   * 把 user / external 分流是为了让 App.tsx 只在「用户改自己代码」时更新 code state。
+   */
+  onUserEdit?: (v: string) => void
+  /** 编辑器内 Ctrl+Enter 触发的回调（Monaco 自带 Ctrl+Enter 默认行为是「在下方插入新行」，
+   *  会 stopPropagation 拦截 window 级别监听，必须在 Monaco 命令系统里绑定） */
+  onCtrlEnter?: () => void
+  /** 应用层主题，跟 useTheme 同步：dark → 'vs-dark'，light → 'vs'。默认 dark。 */
+  editorTheme?: Theme
+}
+
+/** 把应用层 Theme 映射到 Monaco 内置主题 id。Monaco 没有跟随系统 token 的概念，
+ *  只能选两个内置主题之一切换；编辑器自身的背景色 / 语法色由 Monaco 负责，
+ *  外层 wrapper 的 bg-bg 仍然走 CSS var，保证容器底色与整体协调。 */
+export const toMonacoTheme = (t: Theme): 'vs' | 'vs-dark' => (t === 'light' ? 'vs' : 'vs-dark')
+
+/**
+ * Monaco 编辑器选项（不含 readOnly）。
+ * hoist 到模块作用域，避免每次 render 重建一个新对象触发 Monaco 内部
+ * 「配置对象 reference 不同 → 重新 apply options」的开销。disabled / readOnly 状态切换
+ * 走 updateOptions 路径（见下方 effect），不在这里覆盖。
+ */
+const MONACO_OPTIONS = {
+  // 系统等宽字体栈（替代之前的 JetBrains Mono）：离线可用
+  fontFamily: 'Cascadia Code, SF Mono, Menlo, Consolas, "Courier New", monospace',
+  fontSize: 13,
+  lineHeight: 20,
+  minimap: { enabled: false },
+  scrollBeyondLastLine: false,
+  automaticLayout: true,
+  tabSize: 4,
+  padding: { top: 12, bottom: 12 },
+  renderLineHighlight: 'gutter' as const,
+  scrollbar: { verticalScrollbarSize: 8, horizontalScrollbarSize: 8 },
+  overviewRulerBorder: false,
+  hideCursorInOverviewRuler: true
+}
+
+/** 内部 helper：用 tabId 生成 monaco model 的 URI（每个 tab 一个独立 model）。
+ *  path 里塞 tabId 而不是 filePath —— 多个 user 刷新可能用同一 filePath（不该冲突）。
+ *  scheme 用 'file' 让 Monaco 高亮按文件类型走，跟我们手动设 defaultLanguage='python' 不冲突。 */
+function modelUriForTab(tabId: string): string {
+  return `inmemory://pyrof/${encodeURIComponent(tabId)}.py`
+}
+
+const CodePanel = forwardRef<CodePanelHandle, Props>(
+  (
+    {
+      activeTabId,
+      activeContent,
+      readOnly,
+      modelContentByTabId,
+      knownTabIds,
+      onUserEdit,
+      onCtrlEnter,
+      editorTheme = 'dark'
+    },
+    ref
+  ) => {
+    const editorRef = useRef<MonacoEditor.IStandaloneCodeEditor | null>(null)
+    const monacoRef = useRef<Monaco | null>(null)
+    /** 每个 tab 一个 model，懒创建。卸载 tab 时 dispose。 */
+    const modelsRef = useRef<Map<string, MonacoEditor.ITextModel>>(new Map())
+    /**
+     * 每个 tab 的视图状态（cursor + scroll + folding 等）。
+     * 切走时 saveViewState 存到这里，切回来时 restoreViewState 取出。
+     * 用外置 Map 而不是 Monaco 自带的 model-attached view state —— 切换瞬间
+     * saveViewState → setModel 之间存在一帧 race，显式缓存更稳。
+     */
+    const viewStatesRef = useRef<Map<string, MonacoEditor.ICodeEditorViewState>>(new Map())
+    /** 上次切换 tab 时的 activeTabId，用来在 effect 里决定「这次切换是切走了还是首次」。 */
+    const lastActiveIdRef = useRef<string | null>(null)
+    /** 上次 setValue 时的内容，避免相同内容触发 Monaco 的 contentChange 事件链。 */
+    const lastSetValueRef = useRef<Map<string, string>>(new Map())
+    const decorationsRef = useRef<string[]>([])
+    // 把 props 存到 ref 避免 useImperativeHandle 闭包过期
+    const onCtrlEnterRef = useRef(onCtrlEnter)
+    useEffect(() => {
+      onCtrlEnterRef.current = onCtrlEnter
+    }, [onCtrlEnter])
+
+    useImperativeHandle(
+      ref,
+      () => ({
+        revealLine: (line: number) => {
+          const editor = editorRef.current
+          const monaco = monacoRef.current
+          // `!line` 会把 line 0 也当无效（用户脚本可写 `def f(): ...` 然后跑过 line 1 的「空行」，
+          // 但 line 0 不存在），实际不可能是 0；保留对 NaN / 负数 / 小数 1.5 的严格过滤
+          if (!editor || !monaco || !Number.isInteger(line) || line < 1) return
+          editor.revealLineInCenter(line)
+          editor.setPosition({ lineNumber: line, column: 1 })
+          // 只在编辑器可写时才抢焦点：运行中 disabled（pointer-events:none + readOnly），
+          // 此时聚焦反而把屏幕阅读器朗读焦点从按钮挪到代码，用户体验诡异。
+          // readOnly 的外部 tab 也跳过 focus —— focus 到一个用户没法改的编辑器没意义。
+          if (!readOnly) editor.focus()
+          decorationsRef.current = editor.deltaDecorations(decorationsRef.current, [
+            {
+              range: new monaco.Range(line, 1, line, 1),
+              options: {
+                isWholeLine: true,
+                className: 'pyprof-line-highlight',
+                linesDecorationsClassName: 'pyprof-line-gutter'
+              }
+            }
+          ])
+        },
+        clearHighlight: () => {
+          const editor = editorRef.current
+          if (!editor) return
+          decorationsRef.current = editor.deltaDecorations(decorationsRef.current, [])
+        },
+        getValue: () => editorRef.current?.getValue() ?? activeContent
+      }),
+      // 把 readOnly / activeContent 加进 deps —— 没有 deps 时工厂每次 render 都跑,
+      // ref.current 指向新对象,App 的 ref 闭包永远是最新;但代价是每次 render 都重建
+      // handle 对象 + 把方法重新绑到 ref.current,代码上看不出副作用,React DevTools 也
+      // 容易误报「ref 变了」。明确 deps 让 handle 在 readOnly/activeContent 真变时才重建。
+      [readOnly, activeContent]
+    )
+
+    const handleMount: OnMount = (editor, monaco) => {
+      editorRef.current = editor
+      monacoRef.current = monaco
+      // 注册第一个 model：当前 activeTabId 对应的内容。
+      // 用户 tab 用 activeContent（App 的 code state），外部 tab 用 modelContentByTabId 缓存。
+      const initialContent = activeTabId === 'user' ? activeContent : (modelContentByTabId[activeTabId] ?? '')
+      const initialModel = monaco.editor.createModel(
+        initialContent,
+        'python',
+        monaco.Uri.parse(modelUriForTab(activeTabId))
+      )
+      modelsRef.current.set(activeTabId, initialModel)
+      lastSetValueRef.current.set(activeTabId, initialContent)
+      editor.setModel(initialModel)
+      // Ctrl+Enter 命令绑定
+      if (onCtrlEnter) {
+        editor.addCommand(monaco.KeyMod.CtrlCmd | monaco.KeyCode.Enter, () => {
+          onCtrlEnterRef.current?.()
+        })
+      }
+    }
+
+    // 切 tab：保存旧 model 的视图状态 → 切到新 model → 恢复视图状态。
+    // 用 Map<tabId, viewState> 而不是直接靠 Monaco 自带的 model-attached 视图状态，
+    // 是因为切换瞬间的 saveViewState → setModel 之间存在一帧 race（Monaco 内部）。
+    // 显式缓存更稳。
+    useEffect(() => {
+      const editor = editorRef.current
+      if (!editor) return // onMount 还没跑
+      if (lastActiveIdRef.current === activeTabId) return
+      const prevId = lastActiveIdRef.current
+      const newId = activeTabId
+      // 保存当前 model 的视图状态
+      if (prevId !== null) {
+        const state = editor.saveViewState()
+        if (state) {
+          // 存到 model 自身的 _viewStates（用一个临时 Map）
+          // —— 用一个外置 Map 更可控，不依赖 Monaco 内部约定
+          viewStatesRef.current.set(prevId, state)
+        }
+      }
+      // 取或建新 model
+      let model = modelsRef.current.get(newId)
+      if (!model) {
+        const content = newId === 'user' ? activeContent : (modelContentByTabId[newId] ?? '')
+        model = monacoRef.current!.editor.createModel(
+          content,
+          'python',
+          monacoRef.current!.Uri.parse(modelUriForTab(newId))
+        )
+        modelsRef.current.set(newId, model)
+        lastSetValueRef.current.set(newId, content)
+      }
+      editor.setModel(model)
+      // 恢复视图状态
+      const saved = viewStatesRef.current.get(newId)
+      if (saved) editor.restoreViewState(saved)
+      lastActiveIdRef.current = newId
+    }, [activeTabId, activeContent, modelContentByTabId])
+
+    // 外部 tab 内容从 loading → ready 时，content 变化要 sync 到 model。
+    // 用户 tab 走 onChange 双向绑定，**不**通过这条 effect 同步（避免覆盖用户编辑）。
+    useEffect(() => {
+      const editor = editorRef.current
+      if (!editor || !monacoRef.current) return
+      const model = modelsRef.current.get(activeTabId)
+      if (!model) return
+      if (activeTabId === 'user') {
+        // 用户 tab：只在「外部触发」（比如 onLoadSample / onNewBlank 通过 App 改了 code）
+        // 时同步。判断「外部触发」比较 tricky —— 最简单的办法：跟 activeContent 比较，
+        // 如果 activeContent 跟 model 当前 value 不同，而 model 又没在 onChange 里被
+        // 改过（这里没法判断），就 sync。
+        // 简化策略：activeContent 跟 lastSetValueRef 不同时，sync。但 lastSetValueRef
+        // 在 setValue 后会被更新，所以这条只会捕到「外部修改」的情况。
+        const last = lastSetValueRef.current.get(activeTabId) ?? ''
+        if (last !== activeContent) {
+          model.setValue(activeContent)
+          lastSetValueRef.current.set(activeTabId, activeContent)
+        }
+      } else {
+        // 外部 tab：用 modelContentByTabId 缓存里的最新内容 sync（覆盖 setValue）。
+        // 同一 tab 多次 IPC ready（理论上不会，但防御）以最新为准。
+        const content = modelContentByTabId[activeTabId] ?? ''
+        const last = lastSetValueRef.current.get(activeTabId) ?? ''
+        if (last !== content) {
+          model.setValue(content)
+          lastSetValueRef.current.set(activeTabId, content)
+        }
+      }
+    }, [activeTabId, activeContent, modelContentByTabId])
+
+    // 切换 readOnly（外部 tab / 运行中）
+    useEffect(() => {
+      const editor = editorRef.current
+      if (!editor) return
+      editor.updateOptions?.({ readOnly })
+    }, [readOnly])
+
+    // 关 tab 时 dispose 对应的 model：列表外的 tab id 走 dispose + 清理 view state。
+    // 必须跳过当前 activeTabId —— 否则快速切走再被关的边界会撞上「model 已被 dispose」
+    // 的 warning（先 dispose 再 setModel 是异步的）。
+    useEffect(() => {
+      const valid = new Set(knownTabIds)
+      for (const [tabId, model] of modelsRef.current) {
+        if (!valid.has(tabId) && tabId !== activeTabId) {
+          model.dispose()
+          modelsRef.current.delete(tabId)
+          viewStatesRef.current.delete(tabId)
+          lastSetValueRef.current.delete(tabId)
+        }
+      }
+    }, [knownTabIds, activeTabId])
+
+    // 卸载时 dispose 所有 model。HMR / 路由切换时也走这条。
+    useEffect(() => {
+      const models = modelsRef.current
+      const viewStates = viewStatesRef.current
+      const lastSetValue = lastSetValueRef.current
+      return () => {
+        for (const model of models.values()) {
+          model.dispose()
+        }
+        models.clear()
+        viewStates.clear()
+        lastSetValue.clear()
+      }
+    }, [])
+
+    return (
+      <div className={`h-full bg-bg transition-opacity ${readOnly ? 'opacity-95' : ''}`}>
+        <Editor
+          height="100%"
+          defaultLanguage="python"
+          theme={toMonacoTheme(editorTheme)}
+          onMount={handleMount}
+          options={{ ...MONACO_OPTIONS, readOnly }}
+          // 把 onChange 放在这里：用户 tab 时把变更上抛到 App；外部 tab 时因为 readOnly
+          // Monaco 不会触发 onChange，但保留回调 hook 防止未来扩展需要切读写。
+          //
+          // 关键：onChange 里也要更新 lastSetValueRef —— 用户每按一个键,
+          // Monaco 先把文本改进 model,再 emit onChange,App 接到后改 code state,
+          // 触发 sync effect 重跑。如果 lastSetValueRef 不动,effect 会看到
+          // activeContent 变了 → model.setValue(...) 又写一次 → Monaco 文本没变,
+          // 但 setValue 会触发 onDidChangeContent → onChange 又跑一次。
+          // 一个键 → setValue → onChange → setValue → onChange 死循环,直到某次比对
+          // 让 last === activeContent(早期 lastSetValueRef 直接拿"上次 setValue
+          // 写过的内容"作 sentinel,onChange 路径根本不更新它,所以每次 keystroke
+          // 都会多写一次)。
+          onChange={(v) => {
+            if (activeTabId !== 'user') return
+            const next = v ?? ''
+            // 用 ref 而非 state:effect 不依赖这个值,只在下一次 sync 时比对一下,
+            // ref 比 useState 更轻,不会引发额外 render。
+            lastSetValueRef.current.set(activeTabId, next)
+            onUserEdit?.(next)
+          }}
+        />
+      </div>
+    )
+  }
+)
+
+CodePanel.displayName = 'CodePanel'
+export default CodePanel
diff --git a/src/renderer/src/components/CodePanelLazy.tsx b/src/renderer/src/components/CodePanelLazy.tsx
new file mode 100644
index 0000000..e451f8f
--- /dev/null
+++ b/src/renderer/src/components/CodePanelLazy.tsx
@@ -0,0 +1,20 @@
+/**
+ * CodePanel 的懒加载入口。
+ *
+ * 目的：把 monaco-editor（占首屏 bundle 的绝大部分）从 index.js 里摘出来，
+ * 变成一个按需加载的独立 chunk。
+ *
+ * 关键点在于 monaco-setup 的导入位置。它有副作用（写 self.MonacoEnvironment +
+ * loader.config），且 `import * as monaco from 'monaco-editor'` 会把整个 monaco
+ * 拉进所在 chunk。之前它被 main.tsx 静态导入，所以**即使把 CodePanel 改成
+ * React.lazy 也一点用没有** —— monaco 早就在首屏 chunk 里了。必须让这个副作用
+ * 导入只出现在被动态 import() 的模块图里，才能真正切出去。
+ *
+ * 顺序保证：ESM 按书写顺序执行导入，monaco-setup 在 CodePanel 之前完成
+ * loader.config()；而 CodePanel 模块体本身不碰 monaco（只有挂载时才用），
+ * 所以 <Editor> 首次渲染时 loader 已配置好，不会退回 CDN 被 CSP 拦掉。
+ */
+import './../monaco-setup'
+
+export { default } from './CodePanel'
+export type { CodePanelHandle } from './CodePanel'
diff --git a/src/renderer/src/components/EditorTabs.tsx b/src/renderer/src/components/EditorTabs.tsx
new file mode 100644
index 0000000..f3b6483
--- /dev/null
+++ b/src/renderer/src/components/EditorTabs.tsx
@@ -0,0 +1,262 @@
+/**
+ * 编辑器区域的 tab 条 —— 用户代码 tab + 0..N 个外部文件 tab（stdlib / 第三方包热点打开）。
+ *
+ * 设计要点：
+ * - **用户 tab 永远在第一个**，不可关闭。它的 `closable=false`，渲染时不画 X。
+ *   user tab **不渲染 origin 色点**（仅外部 tab 有 origin 概念），并用 `justify-center`
+ *   + `min-w-[96px]` 把标题放在 tab 视觉中线 —— 避免"标题贴左 + 一片空白"的视觉错觉。
+ * - **外部 tab 可关闭**。关掉的是 active 时，App.tsx 通过 `onSelect('user')` 切回。
+ * - **origin 色点**：每个外部 tab 在名字前放一个 4px 圆点，颜色由 `ORIGIN_COLOR`
+ *   提供（绿=用户 / 紫=第三方 / 蓝=stdlib / 灰=builtin / 黄=other）。视觉锚点跟
+ *   右侧热点表的 origin 徽章对齐。
+ * - **横向滚动**：tabs 数量超过可视宽度时整个 tablist 横向滚动（overflow-x-auto）。
+ *   不主动限制 tab 数量 —— 用户开 20 个也不至于崩溃。
+ * - **键盘**：arrow ←→ 切焦点、Home/End 跳首尾、Delete 或 Ctrl+W 关闭聚焦的外部 tab、
+ *   Enter/Space 激活。键盘事件挂在 tablist 根上，通过 event.target 判断是「tablist 自身」
+ *   还是「tab 按钮」来分流。
+ *
+ * 不做的事：
+ * - 不显示修改指示点（user tab 的 dirty 标记）—— 用户代码只有内存状态，没"原始"基线
+ *   可以对比；等真接文件系统后再说。
+ * - 不做拖拽排序 —— 顺序就是打开的先后，够用。
+ */
+import { memo, useCallback, useRef, type KeyboardEvent } from 'react'
+import { CloseIcon } from './icons'
+import { ORIGIN_COLOR } from '../utils/origin'
+import { useT } from '../i18n'
+import type { ExternalOrigin } from '../hooks/useExternalFiles'
+
+/** 单个 tab 的元数据（已经过滤好的视图模型，EditorTabs 不直接接触 OpenFile）。 */
+export interface EditorTabView {
+  id: string
+  displayName: string
+  /** 用户的 origin 永远是 'user'，外部 tab 是其它 5 种之一。 */
+  origin: 'user' | ExternalOrigin
+  closable: boolean
+  /** tab 处于 loading / error 时渲染徽章（外部 tab 才有这两种状态）。 */
+  status?: 'loading' | 'ready' | 'error'
+  /** error 状态下 hover tab 给出的本地化提示（App 已经按 errorKind 翻译好）。 */
+  errorTitle?: string
+}
+
+interface Props {
+  tabs: EditorTabView[]
+  activeTabId: string
+  /**
+   * 切到指定 tab。点 X 关掉活跃 tab 时由 App 决定回落到哪个 tab（一般是 user），
+   * 所以传 `string` 而不是 `string | null` —— EditorTabs 不假设回落策略。
+   */
+  onSelect: (tabId: string) => void
+  /** 关掉一个外部 tab。user tab 不会被关（closable=false 已经保护）。 */
+  onClose: (tabId: string) => void
+}
+
+function EditorTabs({ tabs, activeTabId, onSelect, onClose }: Props): JSX.Element {
+  const t = useT()
+  // 用 ref 拿最新 tabs/onSelect/onClose，避免 onKeyDown 的 useCallback 每次 re-render 都重建
+  const tabsRef = useRef(tabs)
+  tabsRef.current = tabs
+  const onSelectRef = useRef(onSelect)
+  onSelectRef.current = onSelect
+  const onCloseRef = useRef(onClose)
+  onCloseRef.current = onClose
+
+  const onKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLDivElement>) => {
+      const list = tabsRef.current
+      const currentIndex = list.findIndex((tb) => tb.id === activeTabId)
+      // ← → 在 tabs 里循环移动 active（也移动 focus 到对应 tab 按钮）
+      if (e.key === 'ArrowLeft') {
+        e.preventDefault()
+        const prev = currentIndex > 0 ? currentIndex - 1 : list.length - 1
+        const target = list[prev]
+        if (target) {
+          onSelectRef.current(target.id)
+          focusTabButton(target.id)
+        }
+        return
+      }
+      if (e.key === 'ArrowRight') {
+        e.preventDefault()
+        const next = currentIndex < list.length - 1 ? currentIndex + 1 : 0
+        const target = list[next]
+        if (target) {
+          onSelectRef.current(target.id)
+          focusTabButton(target.id)
+        }
+        return
+      }
+      if (e.key === 'Home') {
+        e.preventDefault()
+        const target = list[0]
+        if (target) {
+          onSelectRef.current(target.id)
+          focusTabButton(target.id)
+        }
+        return
+      }
+      if (e.key === 'End') {
+        e.preventDefault()
+        const target = list[list.length - 1]
+        if (target) {
+          onSelectRef.current(target.id)
+          focusTabButton(target.id)
+        }
+        return
+      }
+      // Delete 或 Ctrl/Cmd+W 关闭聚焦的活跃 tab（只对 closable 生效）
+      if (e.key === 'Delete' || ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === 'w')) {
+        const active = list.find((tb) => tb.id === activeTabId)
+        if (active?.closable) {
+          e.preventDefault()
+          onCloseRef.current(active.id)
+          // 关掉后焦点回落到 user tab（App 的 onClose 会自动切 active），这里也同步把 focus 移过去
+          // —— 不强制移，因为如果 active 不是 user，App 会自己切
+        }
+      }
+    },
+    [activeTabId]
+  )
+
+  return (
+    // 不加 tabIndex={0}：WAI-ARIA Tabs Pattern 用 roving tabindex,
+    // 只有 active tab tabIndex=0,其它 tab -1,焦点进入 tablist 时直接落 active tab,
+    // Tab 一次出去。tablist 本身再 tabIndex=0 会多一个 tab 停点（焦点进 tablist 容器
+    // → 跳到 active tab → 再 Tab 才出 tablist）,用户多按一次 Tab。
+    // 键盘 ←→/Home/End/Delete/Ctrl+W 在任一焦点状态（含 tablist 自身）都能用 —— onKeyDown
+    // 挂在容器上,事件会从子 tab 按钮冒泡上来。
+    // eslint-disable-next-line jsx-a11y/interactive-supports-focus
+    <div
+      role="tablist"
+      aria-label={t('editorTab.listAria')}
+      // overflow-x-auto 让 tabs 超出可视宽度时横向滚动；不滚动 user tab 整体位置
+      // 用 gap-px + border-r 让相邻 tab 的 1px 边框重叠成 1px 分隔线（不要 2px）
+      className="flex h-9 min-h-9 overflow-x-auto border-b border-border bg-surface-1 focus:outline-none"
+      onKeyDown={onKeyDown}
+    >
+      {tabs.map((tab) => (
+        <TabButton
+          key={tab.id}
+          tab={tab}
+          active={tab.id === activeTabId}
+          onSelect={() => onSelect(tab.id)}
+          onClose={tab.closable ? () => onClose(tab.id) : undefined}
+        />
+      ))}
+    </div>
+  )
+}
+
+/**
+ * 把 focus 移到指定 tabId 的按钮。tabIndex={active?0:-1} 的 roving tabindex 模式，
+ * 用 ref 直接调 .focus() 比改 state + re-render 更快。
+ */
+function focusTabButton(tabId: string): void {
+  const btn = document.querySelector<HTMLButtonElement>(`[data-pyprof-tab-id="${tabId}"]`)
+  btn?.focus()
+}
+
+interface TabButtonProps {
+  tab: EditorTabView
+  active: boolean
+  onSelect: () => void
+  onClose?: () => void
+}
+
+/**
+ * 单个 tab 按钮。memo 化 —— props reference 不变（外层 EditorTabs 已经 useCallback）就跳过重渲。
+ *
+ * ARIA:
+ * - role="tab" + aria-selected 表达选中态
+ * - tabIndex={active?0:-1} 是 roving tabindex：只有 active tab 进 Tab 序列，避免每次 Tab
+ *   都进 tablist 把屏读用户带到所有 tab —— 屏读进入 tablist 后再用 ←→ 切。
+ * - aria-controls 指到下方的 editor panel id（容器 div 上用同一个 id）
+ */
+const TabButton = memo(function TabButton({ tab, active, onSelect, onClose }: TabButtonProps) {
+  const t = useT()
+  // X 按钮的 stopPropagation —— 不冒泡到 tab 按钮的 onClick，否则点关闭会同时触发切 tab。
+  const handleCloseClick = (e: React.MouseEvent<HTMLSpanElement>): void => {
+    e.stopPropagation()
+    onClose?.()
+  }
+  // 键盘激活：Enter / Space 也触发关闭。tabIndex={-1} 不进 Tab 序列，但鼠标 hover/click
+  // 让元素获焦时,KeyDown 仍能冒泡到外部 tablist 的 onKeyDown(Delete/Ctrl+W 关 tab)。
+  // 这里补一个本地 handler 让 X 自身在获焦态也能被键盘激活 —— 不依赖外层。
+  const handleCloseKeyDown = (e: React.KeyboardEvent<HTMLSpanElement>): void => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      e.stopPropagation()
+      onClose?.()
+    }
+  }
+  const closeAria = t('editorTab.closeAria', { name: tab.displayName })
+  // user tab 不画 origin 点（无外部属性）。外部 tab 才根据 origin 取色。
+  const isUser = tab.origin === 'user'
+  const dotColor = isUser ? 'transparent' : ORIGIN_COLOR[tab.origin]
+  // status 状态徽章（仅外部 tab 有 loading / error 状态）
+  const statusBadge =
+    tab.status === 'loading' ? (
+      <span
+        className="ml-1 inline-block h-1.5 w-1.5 animate-pulse rounded-full bg-fg-muted"
+        aria-hidden="true"
+      />
+    ) : tab.status === 'error' ? (
+      <span
+        className="ml-1 inline-block h-1.5 w-1.5 rounded-full"
+        style={{ backgroundColor: '#eab308' }}
+        aria-label="error"
+        title={tab.errorTitle ?? t('editorTab.error.unknown', { message: '' })}
+      />
+    ) : null
+  // user tab 视觉居中：去掉占位的 origin 点 → 文字自然贴左，看起来"左飘"。改成 justify-center
+  // + min-w-[96px] 把标题放在 tab 视觉中线；min-width 跟原本「点 + 短文本 + padding」宽度接近，
+  // 多 tab 时不会比外部 tab 窄，节奏感保持。
+  const userAlign = isUser ? 'justify-center min-w-[96px]' : ''
+  return (
+    <button
+      type="button"
+      role="tab"
+      id={`pyprof-tab-${tab.id}`}
+      data-pyprof-tab-id={tab.id}
+      aria-selected={active}
+      aria-controls="pyrof-editor-panel"
+      tabIndex={active ? 0 : -1}
+      onClick={onSelect}
+      className={`group relative inline-flex h-full shrink-0 cursor-pointer items-center gap-1.5 border-r border-border px-3 transition-colors focus:outline-none focus-visible:bg-surface-2 ${userAlign} ${
+        active ? 'bg-bg text-fg' : 'bg-surface-1 text-fg-secondary hover:bg-surface-2 hover:text-fg'
+      }`}
+    >
+      {/* 活跃 tab 顶部 2px accent 条 —— 视觉锚点跟 Splitter 的 active handle 同款 */}
+      {active && <span aria-hidden="true" className="absolute inset-x-0 top-0 h-0.5 bg-accent" />}
+      {/* origin 色点 —— 仅外部 tab 渲染（user tab 用 justify-center 居中标题，多余的点只占空间） */}
+      {!isUser && (
+        <span
+          aria-hidden="true"
+          className="inline-block h-2 w-2 shrink-0 rounded-full"
+          style={{ backgroundColor: dotColor }}
+        />
+      )}
+      <span className="max-w-[160px] truncate font-mono text-xs" title={tab.displayName}>
+        {tab.displayName}
+      </span>
+      {statusBadge}
+      {onClose && (
+        // 关闭按钮：始终渲染（不只是 hover）保证键盘聚焦也能看见
+        <span
+          role="button"
+          aria-label={closeAria}
+          tabIndex={-1}
+          onClick={handleCloseClick}
+          onKeyDown={handleCloseKeyDown}
+          // 用 span + role 而不是 button：避免 button 嵌套 button（HTML 不允许）。
+          // tabIndex=-1 让它不进入 Tab 序列，键盘用户用 Delete / Ctrl+W 关闭。
+          className="ml-1 inline-flex h-4 w-4 shrink-0 cursor-pointer items-center justify-center rounded text-fg-muted hover:bg-surface-2 hover:text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+        >
+          <CloseIcon size={10} />
+        </span>
+      )}
+    </button>
+  )
+})
+
+export default memo(EditorTabs)
diff --git a/src/renderer/src/components/EmptyState.tsx b/src/renderer/src/components/EmptyState.tsx
new file mode 100644
index 0000000..f14ff34
--- /dev/null
+++ b/src/renderer/src/components/EmptyState.tsx
@@ -0,0 +1,115 @@
+/**
+ * 空状态页：编辑器有代码、右侧还没结果时展示。
+ *
+ * 三步引导：粘贴代码 → 选解释器 → 运行。运行中追加一行提示。
+ *
+ * 解释器未选时：在三步列表之上追加一条「需要先选解释器」的提示条 + 一键打开设置按钮，
+ * 把「点齿轮图标 → 选 Python」这条首次使用流程压成一步可达。
+ */
+import { memo } from 'react'
+import { CodeIcon, InterpreterIcon, PlayIcon, WarningIcon } from './icons'
+import { useT } from '../i18n'
+
+interface Props {
+  running: boolean
+  hasInterpreter: boolean
+  onLoadSample: () => void
+  onNewBlank: () => void
+  onOpenSettings: () => void
+}
+
+interface Step {
+  n: string
+  titleKey: 'empty.step1.title' | 'empty.step2.title' | 'empty.step3.title'
+  descKey: 'empty.step1.desc' | 'empty.step2.desc' | 'empty.step3.desc'
+  Icon: typeof CodeIcon
+}
+
+const STEPS: Step[] = [
+  { n: '01', titleKey: 'empty.step1.title', descKey: 'empty.step1.desc', Icon: CodeIcon },
+  { n: '02', titleKey: 'empty.step2.title', descKey: 'empty.step2.desc', Icon: InterpreterIcon },
+  { n: '03', titleKey: 'empty.step3.title', descKey: 'empty.step3.desc', Icon: PlayIcon }
+]
+
+function EmptyState({ running, hasInterpreter, onLoadSample, onNewBlank, onOpenSettings }: Props) {
+  const t = useT()
+  return (
+    <div className="flex h-full flex-col items-center justify-center px-8 py-10">
+      <div className="max-w-md text-center">
+        <div className="font-mono text-xs uppercase tracking-wider text-fg-muted">{t('empty.eyebrow')}</div>
+        <h2 className="mt-2 text-xl font-semibold tracking-tight text-fg">{t('empty.title')}</h2>
+        <p className="mt-2 text-sm text-fg-secondary">{t('empty.subtitle')}</p>
+      </div>
+
+      {!hasInterpreter && (
+        <div
+          role="status"
+          className="mt-6 flex max-w-md items-start gap-3 rounded-md border border-warning/40 bg-warning/10 p-3 text-left"
+        >
+          <div className="mt-0.5 flex h-6 w-6 shrink-0 items-center justify-center rounded-full bg-warning/20 text-warning">
+            <WarningIcon size={14} />
+          </div>
+          <div className="min-w-0 flex-1">
+            <div className="text-sm font-medium text-fg">{t('empty.needInterpreter')}</div>
+            <div className="mt-0.5 text-xs text-fg-secondary">{t('empty.needInterpreterDesc')}</div>
+            <button
+              type="button"
+              onClick={onOpenSettings}
+              className="mt-2 inline-flex items-center gap-1.5 rounded border border-border bg-surface-1 px-2.5 py-1 text-xs font-medium text-fg-secondary hover:border-border-strong hover:text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+            >
+              {t('empty.openSettings')}
+              <span aria-hidden="true">→</span>
+            </button>
+          </div>
+        </div>
+      )}
+
+      <ol className="mt-6 flex max-w-md flex-col gap-3">
+        {STEPS.map((s) => (
+          <li
+            key={s.n}
+            className="flex gap-3 rounded-md border border-border bg-surface-1 p-3 transition-colors hover:border-border-strong"
+          >
+            {/* step icon 14 → 16px,text-fg-muted → text-fg-secondary: dark theme 下
+                fg-muted (RGB 141 148 157) 在 surface-2 上偏淡, 16px fg-secondary 更清晰,
+                三步引导的视觉锚点更强。 */}
+            <div className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md bg-surface-2 text-fg-secondary">
+              <s.Icon size={16} />
+            </div>
+            <div className="min-w-0 flex-1">
+              <div className="flex items-center gap-2">
+                <span className="font-mono text-2xs uppercase tracking-wider text-fg-muted">{s.n}</span>
+                <div className="text-sm font-medium text-fg">{t(s.titleKey)}</div>
+              </div>
+              <div className="mt-0.5 text-xs text-fg-secondary">{t(s.descKey)}</div>
+            </div>
+          </li>
+        ))}
+      </ol>
+
+      <div className="mt-6 flex items-center gap-2">
+        {/* 副按钮: px-3 py-1.5 text-xs (26px) → px-3 py-2 text-sm (~34px),与 MinimalRunConfig 同名按钮对齐 */}
+        <button
+          type="button"
+          onClick={onNewBlank}
+          className="rounded border border-border bg-surface-1 px-3 py-2 text-sm text-fg-secondary hover:border-border-strong hover:text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+        >
+          {t('runconfig.newBlank')}
+        </button>
+        <button
+          type="button"
+          onClick={onLoadSample}
+          className="rounded border border-border bg-surface-1 px-3 py-2 text-sm text-fg-secondary hover:border-border-strong hover:text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+        >
+          {t('runconfig.loadSample')}
+        </button>
+        {running && (
+          // 不加 aria-live：App 顶层唯一的 polite region 在播报进度，避免重复
+          <span className="text-xs text-fg-muted">{t('empty.running')}</span>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export default memo(EmptyState)
diff --git a/src/renderer/src/components/ErrorBanner.tsx b/src/renderer/src/components/ErrorBanner.tsx
new file mode 100644
index 0000000..d4ace1f
--- /dev/null
+++ b/src/renderer/src/components/ErrorBanner.tsx
@@ -0,0 +1,59 @@
+/**
+ * IPC 错误兜底页（state === 'error'）。
+ *
+ * 与 FailureResult 的差别：ErrorBanner 用于"result 完全没拿到"的情况
+ * （IPC 抛错、引擎没找到等），FailureResult 用于"result.status !== 'ok'"。
+ * ErrorBanner 没有 traceback（引擎没跑过），只有 stderr。
+ */
+import { memo, useCallback } from 'react'
+import type { RunOptions } from '../../../shared/analysis'
+import { useT } from '../i18n'
+
+interface Props {
+  message: string | null
+  stderr: string | null
+  lastOpts: RunOptions | null
+  /** Live scope from useScope hook -- user may toggle scope after a failure,
+   * and retry should honor the new value, not the stale lastOpts.scope */
+  currentScope: RunOptions['scope']
+  currentCode: string
+  onRetry: (opts: RunOptions) => void
+}
+
+function ErrorBanner({ message, stderr, lastOpts, currentCode, currentScope, onRetry }: Props) {
+  const t = useT()
+  // 复用最近一次成功发起的 opts，但 code 用当前编辑器内容（用户可能改过了）。
+  // 这样 IPC 错误后能一键重跑，不必再点顶栏按钮。lastOpts 为 null 时 disable 是
+  // UI 的兜底，但这里也 short-circuit —— 不依赖调用方按钮。
+  const retry = useCallback(() => {
+    if (lastOpts) onRetry({ ...lastOpts, code: currentCode, scope: currentScope })
+  }, [lastOpts, currentCode, currentScope, onRetry])
+  return (
+    <div role="alert" className="m-4 rounded-md border border-sev-high/40 bg-sev-high/10 p-3 text-sm">
+      <div className="flex items-center justify-between">
+        <div className="font-medium text-fg">{t('errorBanner.title')}</div>
+        <button
+          type="button"
+          onClick={retry}
+          disabled={!lastOpts}
+          className="rounded border border-border-strong bg-surface-1 px-2.5 py-1 text-xs text-fg-secondary hover:bg-surface-2 hover:text-fg disabled:cursor-not-allowed disabled:opacity-50 focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+        >
+          {t('errorBanner.retry')}
+        </button>
+      </div>
+      <div className="mt-1 font-mono text-xs text-fg-secondary">{message ?? t('errorBanner.unknown')}</div>
+      {stderr && stderr.trim() && (
+        <details className="mt-2">
+          <summary className="cursor-pointer text-xs text-fg-muted hover:text-fg">
+            {t('errorBanner.logDetails')}
+          </summary>
+          <pre className="mt-2 max-h-[40vh] overflow-auto whitespace-pre-wrap rounded bg-bg/60 p-2 font-mono text-xs text-fg-muted">
+            {stderr}
+          </pre>
+        </details>
+      )}
+    </div>
+  )
+}
+
+export default memo(ErrorBanner)
diff --git a/src/renderer/src/components/ErrorBoundary.tsx b/src/renderer/src/components/ErrorBoundary.tsx
new file mode 100644
index 0000000..e6aab77
--- /dev/null
+++ b/src/renderer/src/components/ErrorBoundary.tsx
@@ -0,0 +1,99 @@
+import type { ErrorInfo, ReactNode, RefObject } from 'react'
+import { Component, createRef } from 'react'
+import { useT } from '../i18n'
+
+interface Props {
+  children: ReactNode
+}
+
+interface State {
+  error: Error | null
+}
+
+/**
+ * 全局兜底 ErrorBoundary：
+ * - 单个组件渲染抛错时不让整窗白屏
+ * - 提供"重置"按钮清掉错误状态、让用户继续使用其他功能
+ * - 只在 production 显示简短提示，开发环境仍打印完整 stack 到 console
+ *
+ * a11y：进入错误状态时把焦点挪到 alert 容器 — 屏幕阅读器（NVDA / JAWS）才会
+ * 立即读出 role="alert" 内容。role="alert" 本身的隐式 aria-live 行为在不同
+ * 浏览器/AT 组合下不一致；显式 .focus() 是 WAI-ARIA APG 的兜底方案。
+ */
+export class ErrorBoundary extends Component<Props, State> {
+  state: State = { error: null }
+  private alertRef: RefObject<HTMLDivElement> = createRef()
+
+  static getDerivedStateFromError(error: Error): State {
+    return { error }
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo): void {
+    // console.error 用固定文本（开发面板，不本地化），但保留错误对象方便 devtools 展开。
+    // eslint-disable-next-line no-console
+    console.error('[ErrorBoundary] component threw:', error, info)
+  }
+
+  componentDidUpdate(_prev: Props, prevState: State): void {
+    // 错误从无到有时 — 把焦点移进 alert 容器；reset 之后不再动焦点（用户已经操作过一次了）
+    if (!prevState.error && this.state.error) {
+      this.alertRef.current?.focus()
+    }
+  }
+
+  reset = (): void => this.setState({ error: null })
+
+  render(): ReactNode {
+    const { error } = this.state
+    if (!error) return this.props.children
+    // class component 里不能直接 hook —— 用 ErrorBoundaryView 把文案挪出去
+    return (
+      <ErrorBoundaryView
+        alertRef={this.alertRef}
+        message={error.message || String(error)}
+        onReset={this.reset}
+      />
+    )
+  }
+}
+
+export default ErrorBoundary
+
+interface ViewProps {
+  alertRef: RefObject<HTMLDivElement>
+  message: string
+  onReset: () => void
+}
+
+function ErrorBoundaryView({ alertRef, message, onReset }: ViewProps): JSX.Element {
+  const t = useT()
+  return (
+    <div
+      ref={alertRef}
+      role="alert"
+      tabIndex={-1}
+      className="flex h-screen w-screen flex-col items-center justify-center gap-4 bg-bg p-8 text-fg outline-none focus-visible:ring-2 focus-visible:ring-accent"
+    >
+      <div className="text-lg font-semibold text-sev-high">{t('errorBoundary.title')}</div>
+      <div className="max-w-xl rounded border border-border bg-surface-1 p-4 font-mono text-xs text-fg-secondary">
+        {message}
+      </div>
+      <div className="flex gap-2">
+        <button
+          type="button"
+          onClick={onReset}
+          className="rounded border border-border-strong bg-surface-1 px-3 py-1.5 text-sm text-fg-secondary hover:bg-surface-2 hover:text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+        >
+          {t('errorBoundary.retry')}
+        </button>
+        <button
+          type="button"
+          onClick={() => window.location.reload()}
+          className="rounded border border-border bg-surface-1 px-3 py-1.5 text-sm text-fg-secondary hover:bg-surface-2 hover:text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+        >
+          {t('errorBoundary.reload')}
+        </button>
+      </div>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/FailureResult.tsx b/src/renderer/src/components/FailureResult.tsx
new file mode 100644
index 0000000..7a868c2
--- /dev/null
+++ b/src/renderer/src/components/FailureResult.tsx
@@ -0,0 +1,73 @@
+/**
+ * 失败页（result.status !== 'ok'）：单一版本。
+ *
+ * 之前有 FailureResult（Pro 模式专业报错）和 SimpleFailure（友好大白话）。
+ * 模式合并后只留一个 — 给技术用户看完整 traceback / stderr 折叠区，
+ * 但不需要两种语气切换。
+ */
+import { memo, useCallback } from 'react'
+import type { AnalysisResult, RunOptions } from '../../../shared/analysis'
+import { useT, type StringKey } from '../i18n'
+
+interface Props {
+  result: AnalysisResult
+  lastOpts: RunOptions | null
+  /** Live scope -- same as ErrorBanner: retry must honor post-failure scope change */
+  currentScope: RunOptions['scope']
+  currentCode: string
+  onRetry: (opts: RunOptions) => void
+}
+
+function FailureResult({ result, lastOpts, currentCode, currentScope, onRetry }: Props) {
+  const t = useT()
+  const isTimeout = result.status === 'timeout'
+  const isSyntax = result.status === 'syntax_error'
+  const titleKey: StringKey = isTimeout
+    ? 'failure.title.timeout'
+    : isSyntax
+      ? 'failure.title.syntax'
+      : 'failure.title.runtime'
+  const title = t(titleKey)
+  const stderrTail = result.error?.stderrTail
+  // 复用最近一次成功发起的 opts，但 code 用当前编辑器内容（用户可能改过了）。
+  // 这样语法错误修正后、超时后、运行时错误后都能一键重跑，不必再点顶栏按钮。
+  const retry = useCallback(() => {
+    if (lastOpts) onRetry({ ...lastOpts, code: currentCode, scope: currentScope })
+  }, [lastOpts, currentCode, currentScope, onRetry])
+
+  return (
+    <div role="alert" className="flex h-full flex-col gap-3 p-6">
+      <div className="rounded-md border border-sev-high/40 bg-sev-high/10 p-4">
+        <div className="text-base font-semibold text-fg">{title}</div>
+        {result.error && (
+          <pre className="mt-2 max-h-[40vh] overflow-auto whitespace-pre-wrap rounded bg-bg/60 p-3 font-mono text-xs text-fg-secondary">
+            {result.error.message}
+            {result.error.traceback ? '\n\n' + result.error.traceback : ''}
+          </pre>
+        )}
+        {stderrTail && (
+          <details className="mt-2">
+            <summary className="cursor-pointer text-xs text-fg-muted hover:text-fg">
+              {t('failure.logDetails')}
+            </summary>
+            <pre className="mt-2 max-h-[40vh] overflow-auto whitespace-pre-wrap rounded bg-bg/60 p-3 font-mono text-xs text-fg-muted">
+              {stderrTail}
+            </pre>
+          </details>
+        )}
+      </div>
+      <div className="flex flex-wrap items-center gap-2">
+        <button
+          type="button"
+          onClick={retry}
+          disabled={!lastOpts}
+          className="rounded bg-accent px-3 py-1.5 text-xs font-semibold text-fg-on-accent hover:bg-accent-hover disabled:cursor-not-allowed disabled:opacity-40 focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+        >
+          {t('failure.retry')}
+        </button>
+      </div>
+    </div>
+  )
+}
+
+export default memo(FailureResult)
diff --git a/src/renderer/src/components/Logo.tsx b/src/renderer/src/components/Logo.tsx
new file mode 100644
index 0000000..5e81827
--- /dev/null
+++ b/src/renderer/src/components/Logo.tsx
@@ -0,0 +1,48 @@
+/**
+ * 项目 logo（顶栏左上的图标）。
+ *
+ * 渲染源：项目根的 icon.ico —— 与 BrowserWindow 窗口图标 / macOS dock 图标同源，
+ * 改一处不会让窗口和顶栏视觉漂移。
+ *
+ * 走 IPC 取 data URL 而不是把图标复制到 src/renderer/public 或在 build 时生成：
+ * - 单一来源（icon.ico），不存在"窗口新版 / 顶栏旧版"的漂移
+ * - ICO 多分辨率帧默认挑最大（256×256），主进程 resize 到 32×32 再 toDataURL：
+ *   顶栏 ~18px 显示，32px source 是高质量重采样；同时 payload 比直传 256×256
+ *   小一个数量级（几百字节 vs 几 KB）
+ *
+ * 降级：拿不到时（文件丢失 / IPC 未挂 / 测试无 mock）退回内置 SVG，
+ * 顶栏从不会"空一格"。
+ */
+import { useEffect, useState } from 'react'
+import { ACCENT } from '../utils/colors'
+
+const SIZE = 18
+
+function FallbackSvg() {
+  return (
+    <svg width={SIZE} height={SIZE} viewBox="0 0 18 18" fill="none" aria-hidden="true">
+      <rect x="2" y="2" width="3" height="14" rx="1" fill={ACCENT} />
+      <rect x="7" y="6" width="3" height="10" rx="1" fill={ACCENT} opacity="0.7" />
+      <rect x="12" y="9" width="3" height="7" rx="1" fill={ACCENT} opacity="0.45" />
+    </svg>
+  )
+}
+
+export default function Logo() {
+  const [src, setSrc] = useState<string | null>(null)
+  useEffect(() => {
+    let cancelled = false
+    // 防御性检查：window.api 在测试或非 Electron 环境可能不存在；缺失即不挂图标，
+    // 让 Fallback 接管，避免单测 / Storybook 因为这个 IPC 调用炸红
+    const api = window.api
+    if (!api || typeof api.getAppIcon !== 'function') return
+    void api.getAppIcon().then((s) => {
+      if (!cancelled) setSrc(s)
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [])
+  if (!src) return <FallbackSvg />
+  return <img src={src} width={SIZE} height={SIZE} alt="" aria-hidden="true" />
+}
diff --git a/src/renderer/src/components/MinimalRunConfig.tsx b/src/renderer/src/components/MinimalRunConfig.tsx
new file mode 100644
index 0000000..73b74f9
--- /dev/null
+++ b/src/renderer/src/components/MinimalRunConfig.tsx
@@ -0,0 +1,172 @@
+/**
+ * 极简运行配置：运行 / 取消 + 加载示例 + 进度条。
+ *
+ * 解释器选择已在 Settings 面板（顶栏齿轮图标入口）—— 这里不再展示解释器信息，
+ * 一切交给 Settings。运行按钮在未选解释器时禁用，悬浮提示用户去设置里选。
+ *
+ * 剖析范围 toggle：「仅用户代码」/「含库函数」二选一，默认 all（含库函数）。
+ * user：和 v2 之前一致，只看用户脚本里的函数；
+ * all：耗时可以下钻到 import 的包（标准库 + 第三方）—— 这是默认，
+ * pandas.read_csv() 这种黑盒直接能展开到 stdlib / numpy 内部。
+ *
+ * 选择持久化到 localStorage.pyrof.scope（useScope hook），关闭软件重新
+ * 打开会保留用户上次的选择，不再每次回到默认。
+ */
+import { forwardRef, useCallback, useImperativeHandle, useRef } from 'react'
+import type { ProgressEvent, RunOptions } from '../../../shared/analysis'
+import type { UseInterpretersResult } from '../hooks/useInterpreters'
+import type { ProfileScope } from '../hooks/useScope'
+import { useT } from '../i18n'
+
+/**
+ * App 的 Ctrl+Enter 快捷键通过 ref.current.run() 触发同样的入口，结构同 MinimalRunConfig
+ * 自带 useImperativeHandle 暴露的 run() —— 避免 App.tsx 里用 `as` 强转。
+ */
+export interface RunConfigHandle {
+  run: () => void
+}
+
+interface Props {
+  code: string
+  state: 'idle' | 'running' | 'done' | 'error'
+  progress: ProgressEvent | null
+  /** 只取 active（其他 select / pick / detectAll 由 Settings 接） */
+  interpreters: UseInterpretersResult
+  /** 剖析范围：user（仅用户脚本）/ all（含库函数） */
+  scope: ProfileScope
+  onRun: (opts: RunOptions) => void
+  onCancel: () => void
+  onLoadSample: () => void
+  onNewBlank: () => void
+  onToggleScope: () => void
+}
+
+/** 进度小圆点：内层实心 + 外层 animate-ping 双圈叠加（原 PulseDot，仅此处用） */
+function PulseDot() {
+  return (
+    <span aria-hidden="true" className="relative flex h-1.5 w-1.5">
+      <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-accent opacity-60" />
+      <span className="relative inline-flex h-1.5 w-1.5 rounded-full bg-accent" />
+    </span>
+  )
+}
+
+const MinimalRunConfig = forwardRef<RunConfigHandle, Props>(function MinimalRunConfig(
+  { code, state, progress, interpreters, scope, onRun, onCancel, onLoadSample, onNewBlank, onToggleScope },
+  ref
+) {
+  const t = useT()
+  // 让父组件通过 ref.current.run() 触发同一条入口（Ctrl+Enter 走这里）
+  const onRunRef = useRef(onRun)
+  onRunRef.current = onRun
+  // 单条「构造 opts + 调 onRun」入口,按钮点击 + ref.run() 都走这里,
+  // 避免两处各持一份闭包 → 哪天加 args(比如入口函数名)容易漏改一处。
+  const doRun = useCallback(() => {
+    const interp = interpreters.active
+    if (!interp) return
+    onRunRef.current({ interpreter: interp.path, code, scope })
+  }, [interpreters.active, code, scope])
+  useImperativeHandle(ref, () => ({ run: doRun }), [doRun])
+
+  const isRunning = state === 'running'
+  const disabled = isRunning || !interpreters.active
+  // 当前 scope 的展示标签：state 决定 label / active 样式
+  const scopeLabelKey = scope === 'all' ? 'runconfig.scope.all' : 'runconfig.scope.user'
+  const scopeLabel = t(scopeLabelKey)
+
+  return (
+    <div className="flex flex-col gap-2 border-b border-border bg-bg p-3">
+      <div className="flex items-center gap-2">
+        {isRunning ? (
+          // Cancel / Run 按钮: px-3 py-1.5 text-xs (26px) → px-3 py-2 text-sm (~34px),
+          // 与下方「新建空白/加载示例」按钮同高,整条控制栏视觉节奏一致。
+          <button
+            type="button"
+            onClick={onCancel}
+            className="inline-flex items-center gap-2 rounded border border-border bg-surface-1 px-3 py-2 text-sm font-medium text-fg hover:border-border-strong focus:outline-none"
+          >
+            <PulseDot /> {t('runconfig.cancel')}
+          </button>
+        ) : (
+          <button
+            type="button"
+            onClick={doRun}
+            disabled={disabled}
+            title={!interpreters.active ? t('runconfig.needInterpreter') : undefined}
+            className="inline-flex items-center gap-2 rounded bg-accent px-3 py-2 text-sm font-medium text-fg-on-accent hover:bg-accent-hover disabled:cursor-not-allowed disabled:opacity-40 focus:outline-none"
+          >
+            {t('runconfig.run')}
+            <kbd className="ml-1 rounded border border-fg-on-accent/30 px-1 font-mono text-2xs">
+              {t('runconfig.shortcut')}
+            </kbd>
+          </button>
+        )}
+        {/* 「新建空白/加载示例」按钮: px-2 py-1.5 text-xs (26px) → px-3 py-2 text-sm (~34px),
+            与 EmptyState 里同名按钮对齐,横向 padding 也一致。 */}
+        <button
+          type="button"
+          onClick={onNewBlank}
+          disabled={isRunning}
+          className="rounded border border-border bg-surface-1 px-3 py-2 text-sm text-fg-secondary hover:border-border-strong hover:text-fg disabled:opacity-50 focus:outline-none"
+        >
+          {t('runconfig.newBlank')}
+        </button>
+        <button
+          type="button"
+          onClick={onLoadSample}
+          disabled={isRunning}
+          className="rounded border border-border bg-surface-1 px-3 py-2 text-sm text-fg-secondary hover:border-border-strong hover:text-fg disabled:opacity-50 focus:outline-none"
+        >
+          {t('runconfig.loadSample')}
+        </button>
+        {/*
+          剖析范围 toggle switch：默认开（含库函数），用户切回 user 时变灰。
+          role="switch" + aria-checked 让 SR 播报「开关 开启 / 关闭」而不是
+          「按钮 按下 / 未按下」。
+        */}
+        <button
+          type="button"
+          role="switch"
+          aria-checked={scope === 'all'}
+          onClick={onToggleScope}
+          disabled={isRunning}
+          aria-label={t('runconfig.scope.aria', { scope: scopeLabel })}
+          className="inline-flex shrink-0 items-center gap-1.5 rounded px-1.5 py-1 text-xs text-fg-secondary hover:text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring disabled:opacity-50"
+        >
+          <span
+            aria-hidden="true"
+            className={`relative inline-block h-4 w-7 rounded-full transition-colors ${
+              scope === 'all' ? 'bg-accent' : 'bg-surface-3'
+            }`}
+          >
+            <span
+              aria-hidden="true"
+              className={`absolute top-0.5 left-0.5 h-3 w-3 rounded-full bg-fg-on-accent shadow transition-transform ${
+                scope === 'all' ? 'translate-x-3' : 'translate-x-0'
+              }`}
+            />
+          </span>
+          <span className="select-none">{scopeLabel}</span>
+        </button>
+      </div>
+
+      {isRunning && progress && (
+        <div
+          role="progressbar"
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-valuenow={progress.pct}
+          aria-label={t('runconfig.progress')}
+          className="h-1 w-full overflow-hidden rounded bg-surface-2"
+        >
+          <div
+            className="h-full bg-accent transition-[width] duration-150"
+            style={{ width: `${progress.pct}%` }}
+          />
+        </div>
+      )}
+    </div>
+  )
+})
+
+export default MinimalRunConfig
diff --git a/src/renderer/src/components/ResultsPanel.tsx b/src/renderer/src/components/ResultsPanel.tsx
new file mode 100644
index 0000000..c0ac665
--- /dev/null
+++ b/src/renderer/src/components/ResultsPanel.tsx
@@ -0,0 +1,175 @@
+/**
+ * 结果页（result.status === 'ok'）：单一版本，无 Tab。
+ *
+ * 之前 ResultsPanel 有 Hotspot / 火焰图 / 行级 / 调用关系 / 优化建议 5 个分块，
+ * 其中后三个用 Tab 切换。v2 起砍掉行级 / 调用关系 / 优化建议 + Tab 路由，
+ * 只剩：
+ * - RunSummaryLite：本次耗时 + 函数总数 + 最耗时函数
+ * - HotspotTable：可点击跳到源码行
+ * - TimeChartSwitcher：耗时可视化（火焰图 / 柱状图 / 矩形树图 / 旭日图四选一）
+ *
+ * 三块按"摘要 → 表 → 图"自然顺序纵向堆叠，键盘焦点只需一次 Tab 进出。
+ *
+ * v4 视觉升级：
+ * - 卡片套 .elev-1: bg-surface-2 + border-strong + 微 shadow, 在 #08090A 上
+ *   浮起来,不和 page bg 糊在一起
+ * - section header 加 .section-accent 装饰(左侧 3px accent bar),
+ *   统一章节标记,长滚动也能定位
+ * - section hint text-xs → text-sm(14px),tagline 不再"灰得发晕"
+ *
+ * v5：噪声过滤移到引擎侧（engine/structure.py:_is_internal_test + profile_and_measure
+ * 的 hide_internal 参数）。result.json 默认就只包含「真正在跑的代码」,外部脚本读
+ * result.json 时拿到的也是干净数据 —— 用户原话「软件内部的测试部分默认百分百过滤
+ * 掉,不在统计范围内容」在源头就生效,不再依赖 UI 层 filter。
+ */
+import { memo } from 'react'
+import type { ReactNode } from 'react'
+import type { AnalysisResult, FunctionNode, RunOptions } from '../../../shared/analysis'
+import HotspotTable from './views/HotspotTable'
+import TimeChartSwitcher from './views/TimeChartSwitcher'
+import RunSummaryLite from './RunSummaryLite'
+import { ChartIcon, TableIcon } from './icons'
+import { useT } from '../i18n'
+
+interface Props {
+  result: AnalysisResult
+  /** 当前 result 是哪个 scope 的 ('user' | 'all')。 */
+  resultScope: RunOptions['scope'] | null
+  /** 用户当前 toggle 的 scope。结果是旧 scope 时给一条「结果可能跟 toggle 不符」的提示。 */
+  currentScope: RunOptions['scope']
+  /** 用现 scope 重跑的回调 —— 提示条上挂一个「重新跑」按钮。 */
+  onRerun: () => void
+  selectedFuncId: string | undefined
+  /**
+   * 热点点击回调。传整个 FunctionNode 而不是 (id, line) —— App.tsx 需要 fn.file / fn.origin
+   * 决定路由（user → 当前 tab 高亮；stdlib / 第三方 → 开新 tab + IPC 读文件）。
+   */
+  onSelectHotspot: (fn: FunctionNode) => void
+}
+
+function ResultsPanel({
+  result,
+  resultScope,
+  currentScope,
+  onRerun,
+  selectedFuncId,
+  onSelectHotspot
+}: Props) {
+  const t = useT()
+  // 结果是不是来自当前 toggle 的 scope —— 切换 scope 后旧 result 不自动重跑，
+  // 给一句提示 + 重跑按钮，避免用户误以为结果对应当前 toggle。
+  // 把两边都窄化到 NonNullable 后再比，避免 resultScope=undefined / currentScope=undefined 时误报。
+  const oldS = resultScope ?? undefined
+  const newS = currentScope ?? undefined
+  const scopeMismatch = oldS !== undefined && newS !== undefined && oldS !== newS
+
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-bg">
+      <RunSummaryLite result={result} onSelectHottest={onSelectHotspot} />
+      {scopeMismatch && oldS && newS && <ScopeStaleHint oldScope={oldS} newScope={newS} onRerun={onRerun} />}
+
+      <div className="flex flex-col gap-6 p-6">
+        <Section
+          icon={<TableIcon className="text-fg-muted" />}
+          title={t('results.hotspot.title')}
+          hint={t('results.hotspot.hint', { n: result.functions.length })}
+        >
+          {/* v4 卡片浮起: bg-surface-2 + border-strong + 微 shadow。 */}
+          <div className="elev-1 overflow-hidden rounded-md p-2">
+            <HotspotTable
+              functions={result.functions}
+              onSelect={onSelectHotspot}
+              selectedId={selectedFuncId}
+            />
+          </div>
+        </Section>
+
+        <Section
+          icon={<ChartIcon className="text-fg-muted" />}
+          title={t('results.time.title')}
+          hint={t('results.time.hint')}
+        >
+          {/* 不内嵌固定高度 —— 外层右栏自带 overflow-y-auto, 图随内容自然长高,
+              多余高度直接交给右栏纵滑, 避免「图内 + 右栏」双层翻轮。 */}
+          {/* v4 卡片浮起: bg-surface-2 + border-strong + 微 shadow。 */}
+          <div className="elev-1 overflow-hidden rounded-md">
+            <TimeChartSwitcher
+              result={result}
+              selectedFuncId={selectedFuncId}
+              onSelectHotspot={onSelectHotspot}
+            />
+          </div>
+        </Section>
+      </div>
+    </div>
+  )
+}
+
+export default memo(ResultsPanel)
+
+function Section({
+  title,
+  icon,
+  hint,
+  children
+}: {
+  title: string
+  icon?: ReactNode
+  hint?: ReactNode
+  children: ReactNode
+}) {
+  return (
+    <section>
+      {/* v4:section header 加 .section-accent(左 3px accent bar);
+          hint text-xs → text-sm font-medium(中等权重,不再"灰得发晕")。
+          章节内一眼能看清当前在看什么,长滚动也不迷失。 */}
+      <header className="section-accent mb-3 flex items-center gap-2">
+        {icon && <span className="flex items-center">{icon}</span>}
+        <h2 className="text-base font-semibold text-fg">{title}</h2>
+        {hint && <span className="text-sm font-medium text-fg-secondary">{hint}</span>}
+      </header>
+      {children}
+    </section>
+  )
+}
+
+/**
+ * 范围 mismatch 提示：当前 result 用的是 user，toggle 已切到 all（或反之）。
+ * 不自动重跑 —— 跑一次要 1-10 秒，不能在 toggle 上偷偷起活。
+ * 提示条 + 「以新范围重跑」按钮，让用户主动确认。
+ */
+function ScopeStaleHint({
+  oldScope,
+  newScope,
+  onRerun
+}: {
+  oldScope: NonNullable<RunOptions['scope']>
+  newScope: NonNullable<RunOptions['scope']>
+  onRerun: () => void
+}): JSX.Element {
+  const t = useT()
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className="flex flex-wrap items-center gap-3 border-b border-border bg-sev-med/10 px-4 py-2.5 text-sm text-fg-secondary"
+    >
+      <span className="font-mono uppercase tracking-wide text-sev-med">
+        {t('results.scopeStale.eyebrow')}
+      </span>
+      <span>
+        {t('results.scopeStale.body', {
+          old: t(`runconfig.scope.${oldScope}`),
+          new: t(`runconfig.scope.${newScope}`)
+        })}
+      </span>
+      <button
+        type="button"
+        onClick={onRerun}
+        className="ml-auto cursor-pointer rounded border border-border bg-surface-1 px-2.5 py-1 font-medium text-fg hover:border-border-strong focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+      >
+        {t('results.scopeStale.rerun')}
+      </button>
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/RunConsole.tsx b/src/renderer/src/components/RunConsole.tsx
new file mode 100644
index 0000000..4eb18a4
--- /dev/null
+++ b/src/renderer/src/components/RunConsole.tsx
@@ -0,0 +1,125 @@
+/**
+ * 运行输出面板（左侧底部）
+ *
+ * 显示 Python 子进程 stdout 的实时累积 —— 用户写 `print('hello')` 跑一次,
+ * 这里立即滚出一行 "hello"。
+ *
+ * 设计取舍：
+ * - **不放在 AnalysisResult**：流式推送后,渲染端 buffer 才是 single source of truth,
+ *   不再依赖「跑完才拿到 result」。useAnalysis 维护 stdout 字符串并通过 onClear 暴露。
+ * - **新 run 自动清空**：useAnalysis.run() 起始会清空 stdout —— 上一轮的 print() 留着会和
+ *   本次混在一起,等于丢失"这次运行的输出是哪些"的边界。需要手动清空仍点 header 的「清空」。
+ *   cancel / reset 不清(被 cancel 的部分输出 / 加载示例前的 log 都要保留)。
+ * - **自动滚到底**：v1 简单实现,所有新内容都滚到底 —— 等以后用户提"我看到一半,
+ *   跳到顶部去看历史,新输出一来又被推到底",再加「用户向上滚动时停止自动滚」检测。
+ * - **完全折叠**：header 上的「收起」按钮把面板折叠成只剩一行 header(高度 ≈ 44px),
+ *   Splitter 拖动是另一种「拖到顶就消失」的隐藏方式,两条路分别对应不同意图。
+ */
+import { useEffect, useMemo, useRef } from 'react'
+import { useT } from '../i18n'
+
+interface Props {
+  stdout: string
+  isRunning: boolean
+  /** 用户手动「清空」按钮回调 —— useAnalysis 的 clearStdout */
+  onClear: () => void
+  /** 折叠状态由父组件控制:这样外层 wrapper 才能在折叠时把高度收到只剩 header(~44px),
+   *  不然 consoleFrac * 100% 占着列高,「收起」看起来像没收完。 */
+  collapsed: boolean
+  onCollapsedChange: (collapsed: boolean) => void
+}
+
+/** 主进程 appendCapped 把单块压到 8MB 上限;buffer 接近这个量级就算"溢出"。 */
+const OVERFLOW_THRESHOLD_BYTES = 4 * 1024 * 1024
+
+function RunConsole({ stdout, isRunning, onClear, collapsed, onCollapsedChange }: Props) {
+  const t = useT()
+  const scrollRef = useRef<HTMLDivElement>(null)
+
+  // 自动滚到底:stdout 变化 + 展开状态变化时各滚一次。
+  // 不加 user-scroll-up 检测 —— 见文件头注释,v1 简单版。
+  useEffect(() => {
+    if (collapsed) return
+    const el = scrollRef.current
+    if (!el) return
+    el.scrollTop = el.scrollHeight
+  }, [stdout, collapsed])
+
+  // 用 utf-8 字节数(中文 / emoji 一个字多字节)而非 length 判断「多少行」更准确,
+  // 但 split('\n') 也够用 —— 「共 N 行」是软指标,不需要精确到字节。
+  const lineCount = useMemo(() => {
+    if (!stdout) return 0
+    // 末尾无换行的最后一行也算一行 —— 不要被 -1 减成 0 让 header 闪
+    return stdout.endsWith('\n') ? stdout.split('\n').length - 1 : stdout.split('\n').length
+  }, [stdout])
+
+  const overflow = stdout.length > OVERFLOW_THRESHOLD_BYTES
+  const hasContent = stdout.length > 0
+
+  return (
+    <section
+      aria-label={t('console.title')}
+      className="flex h-full min-h-0 flex-col border-t border-border bg-bg"
+    >
+      {/* Header: 标题 + 行数徽章 + 溢出警告 + 清空/收起 */}
+      <div className="flex shrink-0 items-center gap-2 border-b border-border bg-surface-1 px-3 py-1.5">
+        <span className="text-xs font-semibold text-fg-secondary">{t('console.title')}</span>
+        {isRunning && (
+          <span aria-hidden="true" className="relative flex h-1.5 w-1.5">
+            <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-accent opacity-60" />
+            <span className="relative inline-flex h-1.5 w-1.5 rounded-full bg-accent" />
+          </span>
+        )}
+        {hasContent && (
+          // 行数徽章: text-2xs (11px) → text-xs (12px),与 header 按钮同档位,长输出时
+          // 不会被「清空/收起」按钮视觉甩开。
+          <span className="text-xs text-fg-muted">{t('console.lineCount', { count: lineCount })}</span>
+        )}
+        {overflow && (
+          <span className="rounded bg-warning/15 px-1.5 py-0.5 text-2xs text-warning" role="status">
+            ⚠ {t('console.overflow')}
+          </span>
+        )}
+        <div className="ml-auto flex items-center gap-1">
+          {/* 清空/收起按钮: px-2 py-0.5 text-2xs (11px) ≈ 20px 高 → px-2.5 py-1 text-xs (12px) ≈ 28px.
+              这是 console 顶栏仅有的两个动作,太小鼠标不好点。 */}
+          <button
+            type="button"
+            onClick={onClear}
+            disabled={!hasContent}
+            className="rounded px-2.5 py-1 text-xs text-fg-secondary hover:bg-surface-2 disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:bg-transparent"
+            aria-label={t('console.clear')}
+          >
+            {t('console.clear')}
+          </button>
+          <button
+            type="button"
+            onClick={() => onCollapsedChange(!collapsed)}
+            aria-expanded={!collapsed}
+            aria-controls="pyrof-console-body"
+            className="rounded px-2.5 py-1 text-xs text-fg-secondary hover:bg-surface-2"
+          >
+            {collapsed ? t('console.expand') : t('console.collapse')}
+          </button>
+        </div>
+      </div>
+
+      {/* Body: 折叠时整个 hide,但 header 仍占位(便于 Splitter 拖动) */}
+      {!collapsed && (
+        <div
+          id="pyrof-console-body"
+          ref={scrollRef}
+          // 等宽字体 + surface-2 背景 —— 对齐火焰图风格,让 stdout 看起来"就是数据"。
+          // overflow-auto:自动滚到底(scrollTop = scrollHeight),用户向上滚时自己接管。
+          // stdout 输出: text-2xs (11px) → text-xs (12px). 这是用户实际打印的内容,
+          // 不是装饰 eyebrow —— 11px 长时间读眼睛累,12px 在 monospace 下仍紧凑可读。
+          className="min-h-0 flex-1 overflow-auto bg-surface-2 px-3 py-2 font-mono text-xs leading-relaxed text-fg-secondary whitespace-pre-wrap break-words"
+        >
+          {hasContent ? stdout : <span className="text-fg-muted">{t('console.empty')}</span>}
+        </div>
+      )}
+    </section>
+  )
+}
+
+export default RunConsole
diff --git a/src/renderer/src/components/RunSummaryLite.tsx b/src/renderer/src/components/RunSummaryLite.tsx
new file mode 100644
index 0000000..5f7d9f3
--- /dev/null
+++ b/src/renderer/src/components/RunSummaryLite.tsx
@@ -0,0 +1,185 @@
+/**
+ * 极简结果摘要：单次 wall time + 函数总数 + 耗时最长函数名。
+ *
+ * v2 起只剩一次 wall-clock 测量，不再显示 mean/std/p95/median/min/cv/sparkline；
+ * 这个组件替代原 RunSummary。
+ *
+ * v4 视觉重做（Linear / Vercel / Notion 三方参照）：
+ * - 单一圆角卡片（elev-1 + rounded-md + overflow-hidden），内部 divide-x divide-border
+ *   三块不再各自顶 2px 彩条、靠 1px 缝隙拼在一起 —— 那是"三张贴一起"，不是"一张卡"
+ * - 三块同结构：UPPER label / 28px 大数字 / 14px 副信息，垂直节奏对齐
+ * - 三块各自不同色调，左侧 3px accent 条 + label 文字色同步：
+ *   wall time（accent 紫）= 主指标；function count（sev-low 绿）= 信息；
+ *   hottest（sev-high 红）= actionable 告警，可下钻
+ * - 函数总数 tile 加"X modules"副信息（仅多模块时显示），不再显得"只是一个数字"
+ * - wall time 副信息保留（检测到含交互等待时显黄色提示），来自 utils/detect-wait
+ */
+import type { ReactNode } from 'react'
+import type { AnalysisResult, FunctionNode } from '../../../shared/analysis'
+import { fmtDuration } from '../utils/format'
+import { isInteractiveWait } from '../utils/detect-wait'
+import { FlameIcon } from './icons'
+import { useT } from '../i18n'
+
+interface Props {
+  result: AnalysisResult
+  /** 点最热函数 tile → 跳到对应行（App.tsx 把 file/origin 路由到用户 tab / 外部 tab） */
+  onSelectHottest?: (fn: FunctionNode) => void
+}
+
+export default function RunSummaryLite({ result, onSelectHottest }: Props) {
+  const t = useT()
+  const wallTime = result.wallTime
+  const fns: FunctionNode[] = result.functions
+  // 函数列表已经按 tottime 倒序排过（engine 端），首项就是最热的
+  const hottest = fns[0]
+  // 模块数仅在多模块时显示 —— 单模块（scope=user 默认）显示就成噪音
+  const moduleCount = new Set(fns.map((f) => f.module)).size
+
+  return (
+    <div className="elev-1 grid grid-cols-3 divide-x divide-border-strong overflow-hidden rounded-md shrink-0">
+      {/* Wall time —— 主指标（accent 紫）+ 左侧 accent 条 */}
+      <SummaryCell label={t('summary.wallTime')} tone="accent">
+        <div className="flex items-baseline gap-1.5">
+          <div className="font-mono text-2xl font-medium leading-none tabular text-fg">
+            {wallTime ? fmtDuration(wallTime.seconds, { big: true }) : '—'}
+          </div>
+          {/* v4 起 wall-time 是「cProfile instrumented 时间 / 校准系数」估计值,
+              用一个 chip 提示用户该值已补偿 cProfile 开销 —— 鼠标 hover 看具体 ratio。
+              非 ok 状态下 result.calibration 是 undefined,自然不渲染。 */}
+          {result.calibration && (
+            <span
+              title={t('summary.wallTimeCalibratedTitle', {
+                ratio: result.calibration.ratio.toFixed(2)
+              })}
+              className="rounded bg-surface-2 px-1 text-2xs font-medium text-fg-muted"
+            >
+              {t('summary.wallTimeCalibrated')}
+            </span>
+          )}
+        </div>
+        {/* 检测到 wall time 远超 cProfile 归因合计 → 多半含交互等待。
+            检测阈值见 utils/detect-wait.ts。火焰图对这种 wall time 会比 wall
+            数字显得小很多,这一行给用户一个 hook 解释为什么对不上。 */}
+        {wallTime && isInteractiveWait(wallTime.seconds, result.flame?.value ?? 0) && (
+          <div className="mt-2 text-sm tabular text-sev-med" title={t('summary.wallTimeHintTitle')}>
+            {t('summary.wallTimeHint', {
+              gap: fmtDuration(wallTime.seconds - (result.flame?.value ?? 0))
+            })}
+          </div>
+        )}
+      </SummaryCell>
+
+      {/* 函数总数 —— 信息（success 绿）+ 左侧 sev-low 条 */}
+      <SummaryCell label={t('summary.functionCount')} tone="success">
+        <div className="font-mono text-2xl font-medium leading-none tabular text-fg">{fns.length}</div>
+        {moduleCount > 1 && (
+          <div className="mt-2 text-sm tabular text-fg-secondary">
+            {t('summary.moduleCount', { count: moduleCount })}
+          </div>
+        )}
+      </SummaryCell>
+
+      {/* 最耗时函数 —— sev-high 配色 + 火焰 icon + 左 accent 条。
+          可点击跳到对应行（user tab 高亮 / 库函数开新 tab）。 */}
+      <SummaryCell
+        label={t('summary.hottest')}
+        tone="alert"
+        icon={<FlameIcon size={12} aria-hidden />}
+        // 仅当提供回调且有 hottest 才让 tile 可交互 —— 用 button 元素承担键盘焦点
+        // 和 a11y,焦点环由 globals.css :focus-visible 统管
+        onClick={onSelectHottest && hottest ? () => onSelectHottest(hottest) : undefined}
+        title={
+          hottest
+            ? `${hottest.name} · ${fmtDuration(hottest.tottime)} · ${hottest.ncalls} calls · 第 ${hottest.line} 行`
+            : undefined
+        }
+      >
+        <div className="truncate font-mono text-base font-medium text-fg">{hottest?.name ?? '—'}</div>
+        {hottest && (
+          <div className="mt-2 text-sm tabular text-fg-secondary">
+            {t('summary.hottestSub', {
+              tottime: fmtDuration(hottest.tottime),
+              calls: hottest.ncalls
+            })}
+          </div>
+        )}
+      </SummaryCell>
+    </div>
+  )
+}
+
+/**
+ * 单格摘要 —— label / value / sub-info 三段式。
+ *
+ * 设计要点:
+ * - tone 控制左侧 3px accent 条 + label 文字色:
+ *   - accent  → 主指标（紫）: wall time
+ *   - success → 信息（绿）  : function count
+ *   - alert   → 告警（红）  : hottest function（可点击下钻）
+ *   - neutral → 无条、无强调
+ * - onClick 提供时用 button,提供 a11y 焦点 / Enter / Space;
+ *   hover 时 bg 微亮 + 焦点环由 globals.css :focus-visible 统一处理
+ * - 内部分隔靠父 grid 的 divide-x,本组件不再画 border
+ */
+type Tone = 'neutral' | 'accent' | 'success' | 'alert'
+
+const TONE_STYLE: Record<Tone, { bar: string; label: string }> = {
+  neutral: { bar: '', label: 'text-fg-secondary' },
+  accent: { bar: 'bg-accent', label: 'text-accent' },
+  success: { bar: 'bg-sev-low', label: 'text-sev-low' },
+  alert: { bar: 'bg-sev-high', label: 'text-sev-high' }
+}
+
+function SummaryCell({
+  label,
+  tone = 'neutral',
+  icon,
+  onClick,
+  title,
+  children
+}: {
+  label: string
+  tone?: Tone
+  icon?: ReactNode
+  onClick?: () => void
+  title?: string
+  children: ReactNode
+}): JSX.Element {
+  const style = TONE_STYLE[tone]
+  const isInteractive = !!onClick
+  // 交互态:hover 时 bg 微亮（var(--surface-3) 比 var(--surface-2) 亮一档）,
+  // 提示 tile 可点;键盘焦点环由全局 css 接管
+  const hoverCls = isInteractive
+    ? 'cursor-pointer transition-colors hover:bg-surface-3 focus:outline-none focus-visible:bg-surface-3'
+    : ''
+  const labelCls = `flex items-center gap-1.5 text-xs font-mono uppercase tracking-wider ${style.label}`
+
+  const inner = (
+    <>
+      {style.bar && (
+        <div className={`absolute inset-y-2 left-0 w-[3px] rounded-r ${style.bar}`} aria-hidden="true" />
+      )}
+      <div className={labelCls}>
+        {icon}
+        <span>{label}</span>
+      </div>
+      <div className="mt-3">{children}</div>
+    </>
+  )
+
+  // interactive → button;否则 → div。用 div 而不是 section 避免 landmark 噪音
+  if (isInteractive) {
+    return (
+      <button
+        type="button"
+        onClick={onClick}
+        title={title}
+        className={`relative block w-full px-5 py-4 text-left ${hoverCls}`}
+      >
+        {inner}
+      </button>
+    )
+  }
+  return <div className="relative px-5 py-4">{inner}</div>
+}
diff --git a/src/renderer/src/components/SettingsModal.tsx b/src/renderer/src/components/SettingsModal.tsx
new file mode 100644
index 0000000..a935e0c
--- /dev/null
+++ b/src/renderer/src/components/SettingsModal.tsx
@@ -0,0 +1,372 @@
+/**
+ * 设置弹层：保留「解释器」section + 仅 Windows 上的 Shell section + 「关于」section。
+ *
+ * 语言 / 主题这两个高频切换已经搬到 TopBar 右上角（各自一个按钮），
+ * 齿轮留给「解释器选择」这种偶尔发生的重操作。
+ *
+ * 设计原则：
+ * - 通过 createPortal 渲染到 document.body，避免被父级 `overflow:hidden` 裁剪
+ * - Esc 关 Modal（不取消运行 — Esc 关 Modal 的优先级最高）
+ * - 点遮罩关 Modal；点内容区不关
+ * - 打开时焦点进 Modal 内第一项（默认在 select），关闭时归还给触发按钮（App 负责）
+ * - Modal 内部始终跟随当前主题（用 CSS vars 自动跟随）
+ *
+ * 解释器部分：直接复用原 MinimalRunConfig 里的 select + 浏览 + 刷新代码段（保持逻辑不变），
+ * 选中的解释器变化通过 `interpreters.selectPath` 写回 App 的 useInterpreters，
+ * 关 Modal 后 MinimalRunConfig 通过 `interpreters.active` 拿到最新值。
+ *
+ * 关于部分：开发者信息 + 主页链接,纯展示性质,不持久化任何偏好;链接走 IPC
+ * `shell:openExternal` 在系统默认浏览器打开,主进程做协议白名单校验。
+ */
+import { useEffect, useRef, useState, useCallback, type ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import type { UseInterpretersResult } from '../hooks/useInterpreters'
+import type { Shell } from '../hooks/useShellPreference'
+import { useT } from '../i18n'
+import { CloseIcon, InfoIcon, PythonIcon, TerminalIcon } from './icons'
+import { installPythonCommand } from '../utils/installCommand'
+import { formatIpcError } from '../utils/ipcErrorFormat'
+
+interface Props {
+  open: boolean
+  onClose: () => void
+  interpreters: UseInterpretersResult
+  /** Windows 上打开系统终端用的 shell(cmd / PowerShell);非 Win 不渲染 Shell section */
+  shell: Shell
+  setShell: (s: Shell) => void
+}
+
+export default function SettingsModal({ open, onClose, interpreters, shell, setShell }: Props) {
+  const t = useT()
+  const dialogRef = useRef<HTMLDivElement>(null)
+  const closeBtnRef = useRef<HTMLButtonElement>(null)
+
+  // Esc 关 Modal；同时阻止冒泡，让 App 顶层的 Esc 不取消运行
+  useEffect(() => {
+    if (!open) return
+    const onKey = (e: KeyboardEvent): void => {
+      if (e.key === 'Escape') {
+        e.stopPropagation()
+        onClose()
+      }
+    }
+    // capture: true 让 Modal 的 Esc 优先于 App 顶层的 keydown listener
+    window.addEventListener('keydown', onKey, { capture: true })
+    return () => window.removeEventListener('keydown', onKey, { capture: true })
+  }, [open, onClose])
+
+  // 打开时把焦点移到关闭按钮 —— 比 focus 到 dialog 容器更直观（用户从顶栏齿轮过来，
+  // 第一个 Tab 自然落在关闭按钮，关闭是最高频动作）。SR 也会读出「关闭 按钮」。
+  // dialog 容器 tabIndex=-1 保留作为兜底（按钮还没 mount 时 focus 不会爆错）。
+  useEffect(() => {
+    if (!open) return
+    // requestAnimationFrame 让 React commit + ref 绑定完成后再 focus —— 直接 focus
+    // 在 effect 同步阶段 ref 可能还 null
+    const id = requestAnimationFrame(() => {
+      closeBtnRef.current?.focus()
+    })
+    return () => cancelAnimationFrame(id)
+  }, [open])
+
+  if (!open) return null
+
+  return createPortal(
+    // 遮罩层：role="presentation" 让 SR 不把它当交互元素；
+    // 点击关闭由 Esc 键 + 内嵌按钮承担（见下方 close 按钮）。
+    // 禁用 click-events-have-key-events：这是行业通用的 modal 遮罩模式 —— Enter 走
+    // 内容区第一个可聚焦元素，Esc 关闭（已在 useEffect 里处理），不是遮罩。
+    // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions, jsx-a11y/click-events-have-key-events
+    <div
+      role="presentation"
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4"
+      onClick={onClose}
+    >
+      {/*
+        内嵌 dialog：role="dialog" aria-modal="true" 是 ARIA modal pattern 标准用法。
+        onClick stopPropagation 让点内容区不冒泡触发遮罩关闭；键盘交互（Esc）走 window listener。
+        禁用 no-static-element-interactions 和 click-events-have-key-events：
+        div 不是交互元素，stopPropagation 只是拦截冒泡不是触发业务逻辑 —
+        内容区自身的交互由其内部按钮 / select 承担，键盘 Esc 已在 useEffect 里全局处理。
+      */}
+      {/* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions, jsx-a11y/click-events-have-key-events */}
+      <div
+        ref={dialogRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label={t('settings.title')}
+        tabIndex={-1}
+        // stopPropagation 让点内容区不冒泡触发 onClose
+        onClick={(e) => e.stopPropagation()}
+        className="w-full max-w-xl rounded-md border border-border bg-surface-1 text-fg shadow-pop outline-none"
+      >
+        <div className="flex items-center justify-between border-b border-border px-4 py-3">
+          <div className="flex items-center gap-2">
+            <PythonIcon size={16} className="text-fg-muted" />
+            <h2 className="text-base font-semibold">{t('settings.title')}</h2>
+          </div>
+          <button
+            ref={closeBtnRef}
+            type="button"
+            onClick={onClose}
+            aria-label={t('settings.close')}
+            // 关闭按钮: p-1 (4px) + 14px icon = 30×30px → p-1.5 (6px) + 16px icon = 32×32px,
+            // 满足 WCAG 32px 最小触控目标。Modal 打开时焦点直接落这里,尺寸对齐顶栏按钮。
+            className="inline-flex items-center justify-center rounded p-1.5 text-fg-muted hover:bg-surface-2 hover:text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+          >
+            <CloseIcon size={16} />
+          </button>
+        </div>
+
+        <div className="flex flex-col gap-5 p-5">
+          {/* 解释器 */}
+          <Section title={t('settings.section.interpreter')}>
+            <InterpreterControls interpreters={interpreters} shell={shell} />
+          </Section>
+          {/* Shell — 仅 Windows 渲染。Mac / Linux 用 OS 自带 terminal,这个偏好不生效 */}
+          {window.api.platform === 'win32' && (
+            <Section title={t('settings.section.shell')}>
+              <ShellControls shell={shell} setShell={setShell} />
+            </Section>
+          )}
+          {/* 关于 —— 开发者信息 + 主页链接,纯展示 */}
+          <Section title={t('settings.section.about')}>
+            <AboutControls />
+          </Section>
+        </div>
+      </div>
+    </div>,
+    document.body
+  )
+}
+
+function Section({ title, children }: { title: string; children: ReactNode }): JSX.Element {
+  return (
+    <section>
+      <h3 className="mb-2 font-mono text-2xs uppercase tracking-wider text-fg-muted">{title}</h3>
+      {children}
+    </section>
+  )
+}
+
+function InterpreterControls({
+  interpreters,
+  shell
+}: {
+  interpreters: UseInterpretersResult
+  /** Windows 上的 shell 偏好;installPython 时透传给 IPC */
+  shell: Shell
+}): JSX.Element {
+  const t = useT()
+  const {
+    active,
+    interpreters: list,
+    selected,
+    selectPath,
+    detecting,
+    detectAll,
+    pick,
+    detectError,
+    pickError
+  } = interpreters
+  const showRefreshError = detectError != null && !detecting && list.length === 0
+  // 仅"列表空 + 不在扫描"时给"打开终端"按钮 — 用户能看到是因为我们没探测到 Python,
+  // 浏览… 之外多一个"自己去装"的选择。
+  const showOpenTerminal = list.length === 0 && !detecting
+  const [terminalError, setTerminalError] = useState<string | null>(null)
+
+  // 点击打开终端装 Python:根据平台挑命令 → IPC → 失败时把 IpcError 还原成人类可读消息
+  const openInstallTerminal = useCallback(async () => {
+    setTerminalError(null)
+    const cmd = installPythonCommand(window.api.platform)
+    try {
+      await window.api.openTerminal(cmd, shell)
+    } catch (err) {
+      // 跨 IPC 抛出的 Error 会被 IpcError 还原成结构化对象;
+      // 按当前 lang 走翻译表，沿用 detect/pick error 的展示风格
+      setTerminalError(formatIpcError(err, t))
+    }
+  }, [t, shell])
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="flex items-center gap-2">
+        <PythonIcon size={14} className="shrink-0 text-fg-muted" />
+        <select
+          aria-label={t('settings.interpreter.label')}
+          value={selected}
+          onChange={(e) => selectPath(e.target.value)}
+          disabled={detecting}
+          className="min-w-0 flex-1 rounded border border-border bg-surface-2 px-2 py-1.5 text-xs text-fg disabled:opacity-50"
+        >
+          {list.length === 0 && !detecting && <option value="">{t('settings.interpreter.empty')}</option>}
+          {detecting && <option value="">{t('settings.interpreter.detecting')}</option>}
+          {list.map((i) => (
+            <option key={i.path} value={i.path}>
+              {i.path} — Python {i.version}
+            </option>
+          ))}
+        </select>
+        {/* 浏览/重新扫描/打开终端按钮: px-2.5 py-1.5 text-xs (28px) → px-3 py-2 text-sm (34px),
+            与 MinimalRunConfig 副按钮对齐, Section 内三个按钮尺寸一致。 */}
+        <button
+          type="button"
+          onClick={() => void pick()}
+          className="rounded border border-border bg-surface-2 px-3 py-2 text-sm text-fg-secondary hover:border-border-strong hover:text-fg focus:outline-none"
+        >
+          {t('settings.interpreter.browse')}
+        </button>
+        <button
+          type="button"
+          onClick={() => void detectAll()}
+          disabled={detecting}
+          aria-label={t('settings.interpreter.rescan')}
+          className="rounded border border-border bg-surface-2 px-3 py-2 text-sm text-fg-secondary hover:border-border-strong hover:text-fg disabled:opacity-50 focus:outline-none"
+        >
+          ↻
+        </button>
+      </div>
+      {showOpenTerminal && (
+        <div className="flex items-center gap-2">
+          <button
+            type="button"
+            onClick={() => void openInstallTerminal()}
+            className="rounded border border-border bg-surface-2 px-3 py-2 text-sm text-fg-secondary hover:border-border-strong hover:text-fg focus:outline-none"
+          >
+            {t('settings.terminal.openCmd')}
+          </button>
+          <span className="text-2xs text-fg-muted">{t('settings.terminal.hint')}</span>
+        </div>
+      )}
+      {active && (
+        <div className="font-mono text-2xs text-fg-muted">
+          Python {active.version} · {active.path}
+        </div>
+      )}
+      {showRefreshError && (
+        <div className="text-xs text-warning">
+          {t('settings.interpreter.detectError', { message: detectError })}
+        </div>
+      )}
+      {pickError && (
+        <div className="text-xs text-warning">
+          {t('settings.interpreter.pickError', { message: pickError })}
+        </div>
+      )}
+      {terminalError && (
+        <div className="text-xs text-warning">{t('settings.terminal.error', { message: terminalError })}</div>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Windows 上「打开系统终端」按钮用哪个 shell。两个选项都是 radio —— 二选一且
+ * 长期持久化（默认 cmd,见 useShellPreference）。非 Windows 不渲染此 section。
+ *
+ * 不用 segmented control / select —— 只有两条,放一起更显眼;radio 也方便加 aria-label。
+ */
+function ShellControls({ shell, setShell }: { shell: Shell; setShell: (s: Shell) => void }): JSX.Element {
+  const t = useT()
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="flex items-center gap-2">
+        <TerminalIcon size={14} className="shrink-0 text-fg-muted" />
+        <div role="radiogroup" aria-label={t('settings.shell.label')} className="flex gap-1">
+          <ShellRadio
+            current={shell === 'cmd'}
+            value="cmd"
+            label={t('settings.shell.cmd')}
+            onSelect={() => setShell('cmd')}
+          />
+          <ShellRadio
+            current={shell === 'powershell'}
+            value="powershell"
+            label={t('settings.shell.powershell')}
+            onSelect={() => setShell('powershell')}
+          />
+        </div>
+      </div>
+      <p className="text-2xs text-fg-muted">{t('settings.shell.hint')}</p>
+    </div>
+  )
+}
+
+function ShellRadio({
+  current,
+  value,
+  label,
+  onSelect
+}: {
+  current: boolean
+  value: Shell
+  label: string
+  onSelect: () => void
+}): JSX.Element {
+  return (
+    <button
+      type="button"
+      role="radio"
+      aria-checked={current}
+      data-value={value}
+      onClick={onSelect}
+      className={
+        current
+          ? 'rounded border border-accent bg-accent/15 px-2.5 py-1 text-xs font-medium text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring'
+          : 'rounded border border-border bg-surface-2 px-2.5 py-1 text-xs text-fg-secondary hover:border-border-strong hover:text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring'
+      }
+    >
+      {label}
+    </button>
+  )
+}
+
+/**
+ * 「关于」section:开发者信息 + 个人主页链接。
+ *
+ * 纯展示 —— 不持久化任何偏好。链接通过 `shell:openExternal` IPC 走系统默认浏览器,
+ * 主进程做 http/https 白名单,这里也照样处理 IPC 失败(系统 shell 异常等)给一条可见的错误,
+ * 用户至少知道"点了为什么没反应"。
+ *
+ * 布局:左侧 InfoIcon(与 Interpreter/Shell section 风格一致),右侧
+ * "开发者: <姓名>" 一行展示文本,下面 URL 单独一行作为可点链接 —— URL 本身才是最
+ * 自然的超链接锚点,姓名只是标识。链接用 button 而非裸 anchor —— sandbox + contextIsolation
+ * 下新窗口默认被吞,button 走 IPC 才是稳定路径。
+ */
+function AboutControls(): JSX.Element {
+  const t = useT()
+  // 链接目标走翻译键(URL 是常驻串,i18n 维护它跟文案在一起更清楚);
+  // 关掉「强制开发者姓名随语言切换」之类的副作用 —— 姓名 / URL 在中英文模式下都是一样的。
+  const name = t('settings.about.developerName')
+  const url = t('settings.about.website')
+  const [error, setError] = useState<string | null>(null)
+
+  const openLink = useCallback(async () => {
+    setError(null)
+    try {
+      await window.api.openExternal(url)
+    } catch (err) {
+      // 走通用 IPC 错误翻译链 —— invalid_payload(协议被拒)/ unknown(shell 失败)都按 lang 翻译。
+      setError(formatIpcError(err, t))
+    }
+  }, [url, t])
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="flex items-center gap-2">
+        <InfoIcon size={14} className="shrink-0 text-fg-muted" />
+        <span className="text-xs text-fg-muted">{t('settings.about.developer')}</span>
+        <span className="text-xs text-fg">{name}</span>
+      </div>
+      <button
+        type="button"
+        onClick={() => void openLink()}
+        aria-label={t('settings.about.linkAria', { name })}
+        title={url}
+        className="self-start rounded font-mono text-2xs text-accent underline-offset-2 hover:underline focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+      >
+        {url}
+      </button>
+      {error && <div className="text-xs text-warning">{error}</div>}
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/Splitter.tsx b/src/renderer/src/components/Splitter.tsx
new file mode 100644
index 0000000..d3b2ae8
--- /dev/null
+++ b/src/renderer/src/components/Splitter.tsx
@@ -0,0 +1,236 @@
+/**
+ * 可拖拽分隔条 —— 编辑器↔结果区(vertical) 和 主区↔终端(horizontal) 共用。
+ *
+ * 设计要点:
+ *  - 受控:不持有尺寸,只把像素变化交给 onDelta,父组件用 useResizableFraction
+ *    把像素换算成 fraction 并 clamp。父组件负责持久化 / 多窗口同步。
+ *  - role="separator":SR 把它当可调分隔条读出来。aria-orientation / aria-valuenow /
+ *    aria-valuemin / aria-valuemax 让 SR 知道当前尺寸比例;aria-controls 标两侧面板。
+ *  - 键盘可调:ArrowLeft/Right(vertical)/ArrowUp/Down(horizontal)每次 step 像素
+ *    (默认 16);Shift+Arrow、PageUp/Down 走大步进(step * 8);Home/End 跳到 max 边界
+ *    (传超出范围的值让父组件 clamp 到 min/max)。
+ *  - 拖拽:onPointerDown 启动,document 上同时监听 pointermove / pointerup /
+ *    pointercancel —— 用户拖到 splitter 外面也能继续;jsdom 里 fireEvent 触发的
+ *    事件冒泡到 document 也走这条路径。
+ *  - setPointerCapture 让用户在 splitter 之外松手也能正常结束拖拽。
+ *  - 拖拽期间锁 body cursor + user-select:防止鼠标移出 splitter 后 cursor 恢复默认。
+ *    pointerup / pointercancel 时还原原始值(用 bodyLockRef 标记「是我锁的」避免
+ *    多次 lock 互相覆盖)。
+ *  - data-orientation / data-dragging 属性:测试 + CSS 钩子用,不参与 a11y。
+ *    data-dragging 直接 ref + setAttribute 同步写,不用 React state —— 测试在
+ *    pointerdown 同步返回后立刻断言,那时 useState 还没 commit。
+ *  - aria-valuenow / valuemin / valuemax 可选:不传就不输出该属性,允许 splitter
+ *    在「还没拿到尺寸」等过渡场景下不暴露误导性的 0 值。
+ *  - useRef 缓存 onDelta 避免每次父组件 re-render 都重建监听(拖动过程中
+ *    父组件 setState 会触发 re-render)。
+ */
+import { memo, useCallback, useEffect, useRef } from 'react'
+
+type Orientation = 'vertical' | 'horizontal'
+
+interface Props {
+  /** vertical = 分隔左右两栏(拖动方向是 X);horizontal = 分隔上下两区(拖动方向是 Y) */
+  orientation: Orientation
+  /** 鼠标 / 触屏拖拽时调用,参数是像素 delta(直接交给 applyDelta 即可) */
+  onDelta: (deltaPx: number) => void
+  /** 屏幕阅读器读出来的标签(中文/英文由父组件从 i18n 取) */
+  ariaLabel: string
+  /** 两侧面板的 id,给 aria-controls 用 —— 不传则省略该 ARIA 属性 */
+  ariaControls?: string[]
+  /** 当前 fraction / px,aria-valuenow 直接给百分比或 px 都行。不传则不输出该属性。 */
+  ariaValueNow?: number
+  ariaValueMin?: number
+  ariaValueMax?: number
+  /** 键盘箭头单步(px),默认 16。Shift / PageUp / PageDown 用 step * 8。 */
+  step?: number
+}
+
+function Splitter({
+  orientation,
+  onDelta,
+  ariaLabel,
+  ariaControls,
+  ariaValueNow,
+  ariaValueMin,
+  ariaValueMax,
+  step = 16
+}: Props) {
+  const elRef = useRef<HTMLDivElement>(null)
+  // 用 ref 缓存 callback,避免父组件 re-render 时拖到一半 onDelta 引用变了导致闭包捕获错值
+  const onDeltaRef = useRef(onDelta)
+  onDeltaRef.current = onDelta
+  // 拖拽态全用 ref —— 同步访问,React state 那时还没 commit
+  const draggingRef = useRef(false)
+  const lastPosRef = useRef<number | null>(null)
+  // 拖拽期间锁 body cursor + user-select 的原始值,pointerup 时还原 —— 多 splitters 共存,
+  // 但同一时刻只有一个在拖,bodyLockRef 作「我锁的」标记,避免相互覆盖
+  const bodyLockRef = useRef<{ cursor: string; userSelect: string } | null>(null)
+
+  const setDraggingAttr = useCallback((val: boolean) => {
+    if (elRef.current) {
+      elRef.current.setAttribute('data-dragging', val ? 'true' : 'false')
+    }
+  }, [])
+
+  const lockBody = useCallback(() => {
+    if (bodyLockRef.current) return
+    bodyLockRef.current = {
+      cursor: document.body.style.cursor,
+      userSelect: document.body.style.userSelect
+    }
+    document.body.style.cursor = orientation === 'vertical' ? 'col-resize' : 'row-resize'
+    document.body.style.userSelect = 'none'
+  }, [orientation])
+
+  const releaseBody = useCallback(() => {
+    if (!bodyLockRef.current) return
+    document.body.style.cursor = bodyLockRef.current.cursor
+    document.body.style.userSelect = bodyLockRef.current.userSelect
+    bodyLockRef.current = null
+  }, [])
+
+  const endDrag = useCallback(() => {
+    if (!draggingRef.current) return
+    draggingRef.current = false
+    lastPosRef.current = null
+    setDraggingAttr(false)
+    releaseBody()
+  }, [setDraggingAttr, releaseBody])
+
+  // 拖拽中监听 document:用户拖到 splitter 外面也能继续;jsdom 里 fireEvent.pointerMove(sep)
+  // 会冒泡到 document,所以这一份也能接住测试事件。这是唯一一份 move 监听 —— 不在
+  // React 元素上挂 onPointerMove,否则 document 监听和 React 合成事件会重复触发 onDelta。
+  useEffect(() => {
+    const onDocMove = (e: PointerEvent) => {
+      if (!draggingRef.current) return
+      const last = lastPosRef.current
+      if (last === null) return
+      const current = orientation === 'vertical' ? e.clientX : e.clientY
+      const delta = current - last
+      if (delta === 0) return // 静止不重复触发
+      onDeltaRef.current(delta)
+      lastPosRef.current = current
+    }
+    const onDocUp = () => endDrag()
+    document.addEventListener('pointermove', onDocMove)
+    document.addEventListener('pointerup', onDocUp)
+    document.addEventListener('pointercancel', onDocUp)
+    return () => {
+      document.removeEventListener('pointermove', onDocMove)
+      document.removeEventListener('pointerup', onDocUp)
+      document.removeEventListener('pointercancel', onDocUp)
+    }
+  }, [orientation, endDrag])
+
+  const onPointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
+    // 只响应主键;中键右键让浏览器自己处理(右键菜单等)
+    if (e.button !== 0) return
+    e.preventDefault()
+    draggingRef.current = true
+    lastPosRef.current = orientation === 'vertical' ? e.clientX : e.clientY
+    setDraggingAttr(true)
+    lockBody()
+    // pointer capture:拖到 splitter 外面也能继续,松手在别处也走 pointerup
+    try {
+      e.currentTarget.setPointerCapture(e.pointerId)
+    } catch {
+      /* 某些测试环境无 Pointer Capture,忽略 */
+    }
+  }
+
+  const onPointerUpLocal = (e: React.PointerEvent<HTMLDivElement>) => {
+    try {
+      if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+        e.currentTarget.releasePointerCapture(e.pointerId)
+      }
+    } catch {
+      /* 某些测试环境(jsdom)无 Pointer Capture 方法,忽略 */
+    }
+    // element-level pointerup 也走 endDrag(document 监听会兜底,这里幂等)
+    endDrag()
+  }
+
+  const onKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
+    // 键盘控制:箭头单步,Shift/PageUp/PageDown 大步进,Home/End 跳到 max 边界
+    // (传 ±(max+1) 让父组件 clamp 到 min/max —— 父组件是 fraction 的话会 saturate 到 0/1)
+    const isVertical = orientation === 'vertical'
+    const bigStep = step * 8
+    let delta: number | null = null
+    switch (e.key) {
+      case 'ArrowLeft':
+        if (isVertical) delta = e.shiftKey ? -bigStep : -step
+        break
+      case 'ArrowRight':
+        if (isVertical) delta = e.shiftKey ? bigStep : step
+        break
+      case 'ArrowUp':
+        if (!isVertical) delta = e.shiftKey ? -bigStep : -step
+        break
+      case 'ArrowDown':
+        if (!isVertical) delta = e.shiftKey ? bigStep : step
+        break
+      case 'PageUp':
+        delta = -bigStep
+        break
+      case 'PageDown':
+        delta = bigStep
+        break
+      case 'Home':
+        // ariaValueMax 没传时 Home/End 没有语义边界,直接 swallow —— 之前
+        // ariaValueMax ?? 0 + 1 = 1 会以「1 像素 delta」被发出,在「容器还没拿到尺寸」
+        // 这类过渡场景里产生一次莫名其妙的 1px 拖拽。
+        if (ariaValueMax === undefined) return
+        delta = -ariaValueMax - 1
+        break
+      case 'End':
+        if (ariaValueMax === undefined) return
+        delta = ariaValueMax + 1
+        break
+      default:
+        return
+    }
+    if (delta === null) return
+    e.preventDefault()
+    onDeltaRef.current(delta)
+  }
+
+  // vertical splitter 是左右两栏中间的一条竖线。
+  // 视觉保持 1px (w-px / h-px) 不变 —— 装饰线本来就该细;鼠标命中区由 before: pseudo
+  // 元素扩展到 20px 宽,以 1px 装饰线为中心 (left-[-10px] 让 before 左边缘在装饰线左侧
+  // 10px,w-5 = 20px 让右边缘在装饰线右侧 10px),鼠标偏离中线也能拖到。
+  // 之前 w-1 hover:w-1.5 (4→6px) 实际命中只有 ~6px,鼠标偏 1-2px 就掉进相邻面板,
+  // 触发不到拖拽 —— 用 hit-area 扩展解决,视觉不"变粗"更克制。
+  const orientationClass =
+    orientation === 'vertical'
+      ? 'relative w-px cursor-col-resize before:absolute before:inset-y-0 before:left-[-10px] before:w-5 before:content-[""]'
+      : 'relative h-px cursor-row-resize before:absolute before:inset-x-0 before:top-[-10px] before:h-5 before:content-[""]'
+
+  // ariaValueNow/Min/Max 可选 —— 不传则不输出该属性
+  const ariaProps: { 'aria-valuenow'?: number; 'aria-valuemin'?: number; 'aria-valuemax'?: number } = {}
+  if (ariaValueNow !== undefined) ariaProps['aria-valuenow'] = ariaValueNow
+  if (ariaValueMin !== undefined) ariaProps['aria-valuemin'] = ariaValueMin
+  if (ariaValueMax !== undefined) ariaProps['aria-valuemax'] = ariaValueMax
+
+  return (
+    // role=separator 是 ARIA 规范里定义的可调分隔条,本身就该接受键盘和指针交互
+    /* eslint-disable jsx-a11y/no-noninteractive-element-interactions */
+    /* eslint-disable jsx-a11y/no-noninteractive-tabindex */
+    <div
+      ref={elRef}
+      role="separator"
+      tabIndex={0}
+      aria-orientation={orientation}
+      aria-label={ariaLabel}
+      aria-controls={ariaControls?.join(' ')}
+      data-orientation={orientation}
+      data-dragging="false"
+      {...ariaProps}
+      onPointerDown={onPointerDown}
+      onPointerUp={onPointerUpLocal}
+      onKeyDown={onKeyDown}
+      className={`shrink-0 self-stretch bg-border transition-colors hover:bg-accent focus:bg-accent focus:outline-none ${orientationClass}`}
+    />
+  )
+}
+
+export default memo(Splitter)
diff --git a/src/renderer/src/components/TopBar.tsx b/src/renderer/src/components/TopBar.tsx
new file mode 100644
index 0000000..e904a38
--- /dev/null
+++ b/src/renderer/src/components/TopBar.tsx
@@ -0,0 +1,110 @@
+/**
+ * 应用顶栏。
+ *
+ * 布局：左 Logo + 标题；右 快捷键提示 + 语言切换 + 主题切换 + 打开终端 + 齿轮（Settings）。
+ * 高度 44px 由 App.tsx 顶层 grid-rows-[44px_1fr_auto] 控制。
+ *
+ * 高频设置提到顶栏的理由：
+ * - 语言 / 主题 是最高频的几个动作，每次都进 Settings 找成本高；
+ *   各自一个按钮显示「当前态」（暗色 → 月亮 / zh-CN → EN），
+ *   一眼可读当前主题，单击即切。
+ * - 「打开终端」按钮按需弹用户本机的 cmd.exe / Terminal.app / gnome-terminal；
+ *   不是「切换内嵌终端」 — 内嵌 xterm + spawn shell 的方案焦点跨 IPC 不稳，已移除。
+ * - 齿轮留给「解释器选择」这种偶尔发生的重操作。
+ */
+import { memo, type CSSProperties } from 'react'
+import Logo from './Logo'
+import { GearIcon, MoonIcon, SunIcon, TerminalIcon } from './icons'
+import WindowControls from './WindowControls'
+import { useI18n, useT } from '../i18n'
+import type { Theme } from '../hooks/useTheme'
+
+interface Props {
+  onOpenSettings: () => void
+  theme: Theme
+  setTheme: (theme: Theme) => void
+  onOpenTerminal: () => void
+}
+
+const OTHER_LANG: Record<'zh-CN' | 'en-US', 'zh-CN' | 'en-US'> = {
+  'zh-CN': 'en-US',
+  'en-US': 'zh-CN'
+}
+
+export default memo(function TopBar({ onOpenSettings, theme, setTheme, onOpenTerminal }: Props) {
+  const t = useT()
+  const { lang, setLang } = useI18n()
+  const otherLang = OTHER_LANG[lang]
+  const isDark = theme === 'dark'
+  // 顶栏整体作为窗口拖拽区 —— frame: false 后 OS 不再提供原生拖拽，CSS
+  // `-webkit-app-region: drag` 让整个 <header> 可拖。按钮组的 <div> 单独
+  // 标记 no-drag 覆盖，覆盖继承让所有交互按钮都不会误触发拖拽。
+  // WebkitAppRegion 不在 React 标准 CSSProperties 类型里 —— 用 as 强转绕开。
+  const dragStyle = { WebkitAppRegion: 'drag' } as CSSProperties
+  const noDragStyle = { WebkitAppRegion: 'no-drag' } as CSSProperties
+  return (
+    <header
+      className="flex items-center justify-between border-b border-border bg-bg px-4"
+      style={dragStyle}
+    >
+      <div className="flex items-center gap-2.5">
+        <Logo />
+        <h1 className="text-base font-semibold tracking-tight text-fg">{t('topbar.title')}</h1>
+      </div>
+      <div className="flex items-center gap-2 text-xs text-fg-muted" style={noDragStyle}>
+        {/* kbd 视觉上和其他 28×28 按钮对齐: 6px padding + ~14px 内容 ≈ 26-28px 总高 */}
+        <kbd className="hidden items-center rounded border border-border bg-surface-1 px-2 py-1 font-mono text-2xs text-fg-muted md:inline-flex">
+          {t('topbar.shortcutHint')}
+        </kbd>
+        <button
+          type="button"
+          onClick={() => setLang(otherLang)}
+          aria-label={t('topbar.switchLanguageTo', {
+            target: otherLang === 'zh-CN' ? t('topbar.lang.zh') : t('topbar.lang.en')
+          })}
+          title={t('topbar.switchLanguageTo', {
+            target: otherLang === 'zh-CN' ? t('topbar.lang.zh') : t('topbar.lang.en')
+          })}
+          // p-1 → p-1.5: 16px icon + 6px padding = 28×28 click target, 接近 WCAG 32px 建议。
+          // hover:bg-surface-1 → hover:bg-surface-2: dark theme 下 surface-1 与 bg 仅 6 RGB 差,
+          // hover 几乎看不出；surface-2 (RGB 19 20 24) 与 bg (RGB 8 9 10) 差 11,反馈清晰。
+          className="rounded p-1.5 font-mono text-xs text-fg-secondary hover:bg-surface-2 hover:text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+        >
+          {otherLang === 'zh-CN' ? t('topbar.lang.zh') : t('topbar.lang.en')}
+        </button>
+        <button
+          type="button"
+          onClick={() => setTheme(isDark ? 'light' : 'dark')}
+          aria-label={t(isDark ? 'topbar.theme.toLight' : 'topbar.theme.toDark')}
+          title={t(isDark ? 'topbar.theme.toLight' : 'topbar.theme.toDark')}
+          // p-1 → p-1.5: 28×28 click target, 与语言切换按钮对齐。
+          // hover:bg-surface-1 → hover:bg-surface-2: dark theme hover 反馈可见化。
+          className="rounded p-1.5 text-fg-secondary hover:bg-surface-2 hover:text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+        >
+          {isDark ? <MoonIcon size={16} /> : <SunIcon size={16} />}
+        </button>
+        <button
+          type="button"
+          onClick={onOpenTerminal}
+          aria-label={t('topbar.openTerminal')}
+          title={t('topbar.openTerminal')}
+          // p-1 → p-1.5: 与语言/主题按钮对齐到 28×28。
+          className="rounded p-1.5 text-fg-secondary hover:bg-surface-2 hover:text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+        >
+          <TerminalIcon size={16} />
+        </button>
+        <button
+          type="button"
+          onClick={onOpenSettings}
+          aria-label={t('topbar.openSettings')}
+          title={t('topbar.openSettings')}
+          // p-1 → p-1.5: 与顶栏其他图标按钮对齐到 28×28。
+          className="rounded p-1.5 text-fg-secondary hover:bg-surface-2 hover:text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring"
+        >
+          <GearIcon size={16} />
+        </button>
+        <WindowControls />
+      </div>
+    </header>
+  )
+})
diff --git a/src/renderer/src/components/WindowControls.tsx b/src/renderer/src/components/WindowControls.tsx
new file mode 100644
index 0000000..ef719cd
--- /dev/null
+++ b/src/renderer/src/components/WindowControls.tsx
@@ -0,0 +1,74 @@
+/**
+ * 自定义窗口控制按钮组 —— 顶栏右上角（齿轮按钮之后）。
+ *
+ * 替代 OS 默认标题栏按钮（frame: false 后 OS 不再渲染）：
+ * - 最小化
+ * - 放大 / 还原（双态切换，图标跟着切）
+ * - 关闭（hover 变红，与 Linear/VS Code 风格一致）
+ *
+ * 拖拽区域由父容器（TopBar 按钮组的 <div>）统一加 `WebkitAppRegion: no-drag`
+ * 标记，本组件内部不再单独加。
+ */
+import { memo, useEffect, useState } from 'react'
+import { CloseIcon, MaximizeIcon, MinimizeIcon, RestoreIcon } from './icons'
+import { useT } from '../i18n'
+
+const BASE_BTN =
+  // 与顶栏其他图标按钮对齐：16px 图标 + p-1.5 padding = 28×28 click target, hover 反馈用
+  // surface-2 (而非 surface-1) —— dark theme 下与 bg 对比足够明显。
+  'inline-flex items-center justify-center rounded p-1.5 text-fg-muted transition-colors hover:bg-surface-2 hover:text-fg focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring'
+// 关闭按钮的 hover 用红色 —— 与 Linear / VS Code 等极简应用的语义一致，
+// "破坏性操作" 给出视觉区分。浅色主题下用更深的红保 AA 对比。
+const CLOSE_BTN =
+  'inline-flex items-center justify-center rounded p-1.5 text-fg-muted transition-colors hover:bg-red-500/10 hover:text-red-400 focus:outline-none focus-visible:ring-1 focus-visible:ring-accent-ring'
+
+function WindowControlsInner(): JSX.Element {
+  const t = useT()
+  const [isMaximized, setIsMaximized] = useState(false)
+
+  // mount: 拉一次初始状态 + 订阅 OS 触发的 maximize 变更（双击标题栏 / 任务栏右键）。
+  // isMaximized 不能默认 false —— 用户上次可能以最大化状态退出，重启后应立即显示还原图标。
+  useEffect(() => {
+    void window.api.windowControls.isMaximized().then(setIsMaximized)
+    return window.api.windowControls.onMaximizeChanged(setIsMaximized)
+  }, [])
+
+  return (
+    <div className="flex items-center gap-0.5 pl-1">
+      <button
+        type="button"
+        onClick={() => void window.api.windowControls.minimize()}
+        aria-label={t('topbar.window.minimize')}
+        title={t('topbar.window.minimize')}
+        className={BASE_BTN}
+      >
+        <MinimizeIcon size={16} />
+      </button>
+      <button
+        type="button"
+        onClick={async () => {
+          // 立即用 IPC 返回的权威状态更新 —— 不要等 onMaximizeChanged 事件，
+          // 事件可能在 IPC response 之后到达导致图标闪一下旧状态。
+          const { isMaximized: next } = await window.api.windowControls.toggleMaximize()
+          setIsMaximized(next)
+        }}
+        aria-label={t(isMaximized ? 'topbar.window.restore' : 'topbar.window.maximize')}
+        title={t(isMaximized ? 'topbar.window.restore' : 'topbar.window.maximize')}
+        className={BASE_BTN}
+      >
+        {isMaximized ? <RestoreIcon size={16} /> : <MaximizeIcon size={16} />}
+      </button>
+      <button
+        type="button"
+        onClick={() => void window.api.windowControls.close()}
+        aria-label={t('topbar.window.close')}
+        title={t('topbar.window.close')}
+        className={CLOSE_BTN}
+      >
+        <CloseIcon size={16} />
+      </button>
+    </div>
+  )
+}
+
+export default memo(WindowControlsInner)
diff --git a/src/renderer/src/components/__tests__/CodePanel.test.ts b/src/renderer/src/components/__tests__/CodePanel.test.ts
new file mode 100644
index 0000000..ea774e2
--- /dev/null
+++ b/src/renderer/src/components/__tests__/CodePanel.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest'
+import { toMonacoTheme } from '../CodePanel'
+
+/**
+ * CodePanel 的 Monaco theme 映射。
+ *
+ * 这里只测纯函数 toMonacoTheme —— 不直接 render CodePanel，因为 Monaco 在 jsdom 下
+ * 要走 worker / WASM，启动代价太高且与组件本身的关注点（主题映射）无关。
+ * 主题切换触发的是 <Editor theme={...}> prop 变化，
+ * @monaco-editor/react v4+ 在 theme prop 改变时自动调用 monaco.editor.setTheme()，
+ * 行为由上游库保证，本组件只负责把应用层 Theme 翻成 Monaco 内置主题 id。
+ */
+describe('toMonacoTheme', () => {
+  it("'light' → 'vs'（浅色内置主题）", () => {
+    expect(toMonacoTheme('light')).toBe('vs')
+  })
+
+  it("'dark' → 'vs-dark'（深色内置主题）", () => {
+    expect(toMonacoTheme('dark')).toBe('vs-dark')
+  })
+})
diff --git a/src/renderer/src/components/__tests__/EditorTabs.test.tsx b/src/renderer/src/components/__tests__/EditorTabs.test.tsx
new file mode 100644
index 0000000..47f8fdf
--- /dev/null
+++ b/src/renderer/src/components/__tests__/EditorTabs.test.tsx
@@ -0,0 +1,182 @@
+/**
+ * EditorTabs 的回归测试。
+ *
+ * 关注几条关键不变式：
+ * 1) user tab 永远是第一个、不可关（无 X）
+ * 2) 外部 tab 有 X 关闭按钮，点击调 onClose，stopPropagation 不触发 onSelect
+ * 3) 键盘 ←/→ 在 tabs 之间循环移动 + 调 onSelect
+ * 4) Home / End 跳首尾
+ * 5) Delete / Ctrl+W 关闭聚焦的可关闭 tab，不关 user tab
+ * 6) role / aria-selected / tabIndex roving 模式
+ */
+import { fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import EditorTabs, { type EditorTabView } from '../EditorTabs'
+import { wrap } from '../../i18n/test-utils'
+
+const TABS: EditorTabView[] = [
+  { id: 'user', displayName: '你的代码', origin: 'user', closable: false },
+  { id: 'ext-1', displayName: 'json/decoder.py', origin: 'stdlib', closable: true },
+  { id: 'ext-2', displayName: 'pandas/core/frame.py', origin: 'third_party', closable: true }
+]
+
+describe('EditorTabs', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('渲染所有 tab，role=tablist 根 + 第一个 tab 是 user', () => {
+    render(wrap(<EditorTabs tabs={TABS} activeTabId="user" onSelect={() => {}} onClose={() => {}} />))
+    expect(screen.getByRole('tablist')).toBeTruthy()
+    const tabs = screen.getAllByRole('tab')
+    expect(tabs).toHaveLength(3)
+    expect(tabs[0]).toHaveAttribute('id', 'pyprof-tab-user')
+    expect(tabs[0]).toHaveTextContent('你的代码')
+  })
+
+  it('user tab 没有关闭按钮（closable=false → 不渲染 X）', () => {
+    render(wrap(<EditorTabs tabs={TABS} activeTabId="user" onSelect={() => {}} onClose={() => {}} />))
+    const userTab = screen.getByRole('tab', { name: '你的代码' })
+    // 关闭按钮的 aria-label 形如 "关闭 {name}" —— user tab 不应有
+    expect(userTab.querySelector('[aria-label^="关闭"]')).toBeNull()
+  })
+
+  it('外部 tab 有关闭按钮，点击调 onClose + 不触发 onSelect', () => {
+    const onSelect = vi.fn()
+    const onClose = vi.fn()
+    render(wrap(<EditorTabs tabs={TABS} activeTabId="ext-1" onSelect={onSelect} onClose={onClose} />))
+    const closeBtn = screen.getByRole('button', { name: '关闭 json/decoder.py' })
+    fireEvent.click(closeBtn)
+    expect(onClose).toHaveBeenCalledWith('ext-1')
+    // X 的 stopPropagation → tab 按钮的 onClick 不应被触发
+    expect(onSelect).not.toHaveBeenCalled()
+  })
+
+  it('aria-selected 与 tabIndex roving 模式:active=0,其他=-1', () => {
+    render(wrap(<EditorTabs tabs={TABS} activeTabId="ext-1" onSelect={() => {}} onClose={() => {}} />))
+    const tabs = screen.getAllByRole('tab')
+    expect(tabs[0]).toHaveAttribute('aria-selected', 'false')
+    expect(tabs[0]).toHaveAttribute('tabindex', '-1')
+    expect(tabs[1]).toHaveAttribute('aria-selected', 'true')
+    expect(tabs[1]).toHaveAttribute('tabindex', '0')
+    expect(tabs[2]).toHaveAttribute('aria-selected', 'false')
+    expect(tabs[2]).toHaveAttribute('tabindex', '-1')
+  })
+
+  it('aria-controls 指向编辑器面板', () => {
+    render(wrap(<EditorTabs tabs={TABS} activeTabId="user" onSelect={() => {}} onClose={() => {}} />))
+    const tab = screen.getByRole('tab', { name: '你的代码' })
+    expect(tab).toHaveAttribute('aria-controls', 'pyrof-editor-panel')
+  })
+
+  it('点击 tab 触发 onSelect(tabId)', () => {
+    const onSelect = vi.fn()
+    render(wrap(<EditorTabs tabs={TABS} activeTabId="user" onSelect={onSelect} onClose={() => {}} />))
+    fireEvent.click(screen.getByRole('tab', { name: 'json/decoder.py' }))
+    expect(onSelect).toHaveBeenCalledWith('ext-1')
+  })
+
+  describe('键盘导航', () => {
+    it('ArrowRight 从 user 切到 ext-1 + 调 onSelect', () => {
+      const onSelect = vi.fn()
+      render(wrap(<EditorTabs tabs={TABS} activeTabId="user" onSelect={onSelect} onClose={() => {}} />))
+      const list = screen.getByRole('tablist')
+      fireEvent.keyDown(list, { key: 'ArrowRight' })
+      expect(onSelect).toHaveBeenCalledWith('ext-1')
+    })
+
+    it('ArrowLeft 从 user 循环到末尾 ext-2', () => {
+      const onSelect = vi.fn()
+      render(wrap(<EditorTabs tabs={TABS} activeTabId="user" onSelect={onSelect} onClose={() => {}} />))
+      const list = screen.getByRole('tablist')
+      fireEvent.keyDown(list, { key: 'ArrowLeft' })
+      expect(onSelect).toHaveBeenCalledWith('ext-2')
+    })
+
+    it('ArrowRight 从末尾循环回第一个(user)', () => {
+      const onSelect = vi.fn()
+      render(wrap(<EditorTabs tabs={TABS} activeTabId="ext-2" onSelect={onSelect} onClose={() => {}} />))
+      const list = screen.getByRole('tablist')
+      fireEvent.keyDown(list, { key: 'ArrowRight' })
+      expect(onSelect).toHaveBeenCalledWith('user')
+    })
+
+    it('Home 跳到第一个', () => {
+      const onSelect = vi.fn()
+      render(wrap(<EditorTabs tabs={TABS} activeTabId="ext-2" onSelect={onSelect} onClose={() => {}} />))
+      const list = screen.getByRole('tablist')
+      fireEvent.keyDown(list, { key: 'Home' })
+      expect(onSelect).toHaveBeenCalledWith('user')
+    })
+
+    it('End 跳到最后一个', () => {
+      const onSelect = vi.fn()
+      render(wrap(<EditorTabs tabs={TABS} activeTabId="user" onSelect={onSelect} onClose={() => {}} />))
+      const list = screen.getByRole('tablist')
+      fireEvent.keyDown(list, { key: 'End' })
+      expect(onSelect).toHaveBeenCalledWith('ext-2')
+    })
+  })
+
+  describe('键盘关闭', () => {
+    it('Delete 关闭 active 的可关闭 tab', () => {
+      const onClose = vi.fn()
+      render(wrap(<EditorTabs tabs={TABS} activeTabId="ext-1" onSelect={() => {}} onClose={onClose} />))
+      const list = screen.getByRole('tablist')
+      fireEvent.keyDown(list, { key: 'Delete' })
+      expect(onClose).toHaveBeenCalledWith('ext-1')
+    })
+
+    it('Ctrl+W 关闭 active 的可关闭 tab', () => {
+      const onClose = vi.fn()
+      render(wrap(<EditorTabs tabs={TABS} activeTabId="ext-2" onSelect={() => {}} onClose={onClose} />))
+      const list = screen.getByRole('tablist')
+      fireEvent.keyDown(list, { key: 'w', ctrlKey: true })
+      expect(onClose).toHaveBeenCalledWith('ext-2')
+    })
+
+    it('Cmd+W (Meta) 同样生效', () => {
+      const onClose = vi.fn()
+      render(wrap(<EditorTabs tabs={TABS} activeTabId="ext-1" onSelect={() => {}} onClose={onClose} />))
+      const list = screen.getByRole('tablist')
+      fireEvent.keyDown(list, { key: 'w', metaKey: true })
+      expect(onClose).toHaveBeenCalledWith('ext-1')
+    })
+
+    it('Delete 在 user tab(不可关)上不调 onClose', () => {
+      const onClose = vi.fn()
+      render(wrap(<EditorTabs tabs={TABS} activeTabId="user" onSelect={() => {}} onClose={onClose} />))
+      const list = screen.getByRole('tablist')
+      fireEvent.keyDown(list, { key: 'Delete' })
+      expect(onClose).not.toHaveBeenCalled()
+    })
+  })
+
+  it('loading / error 状态徽章:loading 有 pulse 圆点,error 有黄色圆点', () => {
+    const tabsWithStatus: EditorTabView[] = [
+      { id: 'user', displayName: '你的代码', origin: 'user', closable: false },
+      { id: 'ext-load', displayName: 'loading.py', origin: 'stdlib', closable: true, status: 'loading' },
+      { id: 'ext-err', displayName: 'error.py', origin: 'stdlib', closable: true, status: 'error' }
+    ]
+    render(
+      wrap(<EditorTabs tabs={tabsWithStatus} activeTabId="user" onSelect={() => {}} onClose={() => {}} />)
+    )
+    const tabs = screen.getAllByRole('tab')
+    // loading 徽章: animate-pulse class（藏在 tab 按钮里的某个子元素上）
+    const loadingTab = tabs.find((el) => el.textContent?.includes('loading.py'))!
+    expect(loadingTab.querySelector('.animate-pulse')).not.toBeNull()
+    // error 徽章: aria-label="error"—— 同 tab 内有「error.py」+ 「error」两个 label,
+    // 用 querySelector 直接找带 aria-label="error" 的 span 即可,不依赖 accessible name
+    const errorTab = tabs.find((el) => el.textContent?.includes('error.py'))!
+    const errorBadge = errorTab.querySelector('[aria-label="error"]')
+    expect(errorBadge).not.toBeNull()
+  })
+
+  it('空 tab 数组也能渲染(只剩 user tab)', () => {
+    const onlyUser: EditorTabView[] = [
+      { id: 'user', displayName: '你的代码', origin: 'user', closable: false }
+    ]
+    render(wrap(<EditorTabs tabs={onlyUser} activeTabId="user" onSelect={() => {}} onClose={() => {}} />))
+    expect(screen.getAllByRole('tab')).toHaveLength(1)
+  })
+})
diff --git a/src/renderer/src/components/__tests__/EmptyState.test.tsx b/src/renderer/src/components/__tests__/EmptyState.test.tsx
new file mode 100644
index 0000000..68f6a47
--- /dev/null
+++ b/src/renderer/src/components/__tests__/EmptyState.test.tsx
@@ -0,0 +1,106 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import EmptyState from '../EmptyState'
+import { wrap } from '../../i18n/test-utils'
+
+describe('EmptyState', () => {
+  it('展示三步引导 + 「粘贴代码，马上知道慢在哪」标题', () => {
+    render(
+      wrap(
+        <EmptyState
+          running={false}
+          hasInterpreter
+          onLoadSample={() => {}}
+          onNewBlank={() => {}}
+          onOpenSettings={() => {}}
+        />
+      )
+    )
+    expect(screen.getByText(/粘贴代码，马上知道慢在哪/)).toBeInTheDocument()
+    expect(screen.getByText(/粘贴 Python 代码/)).toBeInTheDocument()
+    expect(screen.getByText(/选择 Python 解释器/)).toBeInTheDocument()
+    expect(screen.getByText(/运行分析/)).toBeInTheDocument()
+  })
+
+  it('点击「加载示例」触发 onLoadSample', () => {
+    const onLoadSample = vi.fn()
+    render(
+      wrap(
+        <EmptyState
+          running={false}
+          hasInterpreter
+          onLoadSample={onLoadSample}
+          onNewBlank={() => {}}
+          onOpenSettings={() => {}}
+        />
+      )
+    )
+    fireEvent.click(screen.getByRole('button', { name: /加载示例/ }))
+    expect(onLoadSample).toHaveBeenCalledTimes(1)
+  })
+
+  it('点击「新建空白」触发 onNewBlank', () => {
+    const onNewBlank = vi.fn()
+    render(
+      wrap(
+        <EmptyState
+          running={false}
+          hasInterpreter
+          onLoadSample={() => {}}
+          onNewBlank={onNewBlank}
+          onOpenSettings={() => {}}
+        />
+      )
+    )
+    fireEvent.click(screen.getByRole('button', { name: /新建空白/ }))
+    expect(onNewBlank).toHaveBeenCalledTimes(1)
+  })
+
+  it('running 时显示「运行中…」', () => {
+    render(
+      wrap(
+        <EmptyState
+          running
+          hasInterpreter
+          onLoadSample={() => {}}
+          onNewBlank={() => {}}
+          onOpenSettings={() => {}}
+        />
+      )
+    )
+    expect(screen.getByText(/运行中/)).toBeInTheDocument()
+  })
+
+  it('hasInterpreter=false 时显示「需要先选解释器」并提供打开设置按钮', () => {
+    const onOpenSettings = vi.fn()
+    render(
+      wrap(
+        <EmptyState
+          running={false}
+          hasInterpreter={false}
+          onLoadSample={() => {}}
+          onNewBlank={() => {}}
+          onOpenSettings={onOpenSettings}
+        />
+      )
+    )
+    expect(screen.getByText(/需要先选 Python 解释器/)).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: /打开设置/ }))
+    expect(onOpenSettings).toHaveBeenCalledTimes(1)
+  })
+
+  it('hasInterpreter=true 时不显示「需要先选解释器」', () => {
+    render(
+      wrap(
+        <EmptyState
+          running={false}
+          hasInterpreter
+          onLoadSample={() => {}}
+          onNewBlank={() => {}}
+          onOpenSettings={() => {}}
+        />
+      )
+    )
+    expect(screen.queryByText(/需要先选 Python 解释器/)).not.toBeInTheDocument()
+  })
+})
diff --git a/src/renderer/src/components/__tests__/RunConsole.test.tsx b/src/renderer/src/components/__tests__/RunConsole.test.tsx
new file mode 100644
index 0000000..254d9d6
--- /dev/null
+++ b/src/renderer/src/components/__tests__/RunConsole.test.tsx
@@ -0,0 +1,162 @@
+/**
+ * RunConsole 的单元测试。
+ *
+ * 关注几条不变式:
+ * 1. 空 stdout 显示 empty placeholder
+ * 2. 有内容时显示 stdout,行数统计正确
+ * 3. isRunning=true 时显示脉冲圆点
+ * 4. 清空按钮调 onClear,disabled 状态正确
+ * 5. 收起/展开 toggle body 可见性
+ * 6. 溢出阈值触发警告徽章
+ * 7. stdout 变化时 scrollTop 跳到 scrollHeight(自动滚到底)
+ *
+ * jsdom 24 不支持 layout / scrollHeight 真实值 —— 上面"自动滚到底"用 mock
+ * 实现的方式测: mock HTMLElement.prototype.scrollHeight getter,断言 setAttribute 后的 scrollTop。
+ */
+import { useState } from 'react'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import RunConsole from '../RunConsole'
+import { wrap } from '../../i18n/test-utils'
+
+// RunConsole 的 collapsed 现在是受控的（lift 到 App 以便外层 wrapper 收高度）。
+// 测试里没有 App,加一个最小 wrapper 持有 state,rerender 后 state 也不丢。
+function ControlledRunConsole(
+  props: Omit<React.ComponentProps<typeof RunConsole>, 'collapsed' | 'onCollapsedChange'>
+) {
+  const [collapsed, setCollapsed] = useState(false)
+  return <RunConsole {...props} collapsed={collapsed} onCollapsedChange={setCollapsed} />
+}
+
+describe('RunConsole', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('空 stdout 显示 empty placeholder,不显示行数徽章', () => {
+    render(wrap(<ControlledRunConsole stdout="" isRunning={false} onClear={() => {}} />))
+    expect(screen.getByText('运行后此处显示 print() 输出')).toBeInTheDocument()
+    // 没有 stdout 时不显示「共 N 行」
+    expect(screen.queryByText(/共 \d+ 行/)).toBeNull()
+  })
+
+  it('有 stdout 时显示内容 + 行数徽章（尾部有换行不减一行）', () => {
+    render(wrap(<ControlledRunConsole stdout={'a\nb\nc\n'} isRunning={false} onClear={() => {}} />))
+    // stdout 直接渲染在 #pyrof-console-body 容器里 —— getByText 默认 normalizer
+    // 会把换行折叠/裁切,改读 DOM textContent 做包含判断
+    const body = document.getElementById('pyrof-console-body')
+    expect(body).not.toBeNull()
+    expect(body!.textContent).toContain('a\nb\nc\n')
+    // 末尾 \n 时 split('\n').length - 1 = 2 行 → 「共 3 行」是不对的,要等于行数
+    // 实际: ['a','b','c',''].length = 4, length - 1 = 3,所以显示「共 3 行」
+    expect(screen.getByText('共 3 行')).toBeInTheDocument()
+    // placeholder 不应该出现
+    expect(screen.queryByText('运行后此处显示 print() 输出')).toBeNull()
+  })
+
+  it('stdout 不以换行结尾时,最后一行也算一行', () => {
+    // 用户在编辑 print() 收尾不带 \n 之类的场景很常见(例如脚本被 kill),
+    // 这里走的是 lineCount 的 else 分支(split('\n').length 不减一)
+    render(wrap(<ControlledRunConsole stdout={'x\ny'} isRunning={false} onClear={() => {}} />))
+    expect(screen.getByText('共 2 行')).toBeInTheDocument()
+  })
+
+  it('isRunning=true 时显示脉冲圆点 + running 状态', () => {
+    const { container } = render(wrap(<ControlledRunConsole stdout="" isRunning onClear={() => {}} />))
+    // pulse 圆点用 animate-ping class 标识
+    expect(container.querySelector('.animate-ping')).not.toBeNull()
+  })
+
+  it('isRunning=false 时不显示脉冲圆点', () => {
+    const { container } = render(
+      wrap(<ControlledRunConsole stdout="" isRunning={false} onClear={() => {}} />)
+    )
+    expect(container.querySelector('.animate-ping')).toBeNull()
+  })
+
+  it('清空按钮:有内容时可点,点击调 onClear', () => {
+    const onClear = vi.fn()
+    render(wrap(<ControlledRunConsole stdout="hello" isRunning={false} onClear={onClear} />))
+    const btn = screen.getByRole('button', { name: '清空' })
+    expect(btn).not.toBeDisabled()
+    fireEvent.click(btn)
+    expect(onClear).toHaveBeenCalledTimes(1)
+  })
+
+  it('清空按钮:无内容时 disabled', () => {
+    render(wrap(<ControlledRunConsole stdout="" isRunning={false} onClear={() => {}} />))
+    const btn = screen.getByRole('button', { name: '清空' })
+    expect(btn).toBeDisabled()
+  })
+
+  it('收起/展开按钮切换 aria-expanded + body 可见性', () => {
+    const { rerender } = render(
+      wrap(<ControlledRunConsole stdout="hello" isRunning={false} onClear={() => {}} />)
+    )
+    const toggle = screen.getByRole('button', { name: '收起' })
+    expect(toggle).toHaveAttribute('aria-expanded', 'true')
+    // stdout 元素存在
+    expect(document.getElementById('pyrof-console-body')).not.toBeNull()
+
+    fireEvent.click(toggle)
+    // body 收起后 stdout 元素不在文档里
+    expect(document.getElementById('pyrof-console-body')).toBeNull()
+
+    // 按钮文案换成「展开」+ aria-expanded=false
+    rerender(wrap(<ControlledRunConsole stdout="hello" isRunning={false} onClear={() => {}} />))
+    // 收起/展开按钮在 rerender 后是新的 DOM 节点 — 重新查询
+    const expandBtn = screen.getByRole('button', { name: '展开' })
+    expect(expandBtn).toHaveAttribute('aria-expanded', 'false')
+
+    fireEvent.click(expandBtn)
+    expect(document.getElementById('pyrof-console-body')).not.toBeNull()
+  })
+
+  it('stdout 超过 4MB 时显示「溢出」警告徽章', () => {
+    // OVERFLOW_THRESHOLD_BYTES = 4 * 1024 * 1024,length(JS String)是 UTF-16 code units,
+    // ascii 字符下和 byte 一致 —— 用 ascii 拼 4MB+1 字符正好越过阈值
+    const huge = 'x'.repeat(4 * 1024 * 1024 + 1)
+    render(wrap(<ControlledRunConsole stdout={huge} isRunning={false} onClear={() => {}} />))
+    expect(screen.getByText(/输出过长/)).toBeInTheDocument()
+  })
+
+  it('stdout 变化时把 scrollRef 滚到底(scrollTop = scrollHeight)', () => {
+    // jsdom 默认 scrollHeight = 0 —— 把它 mock 成一个固定值,验证组件把它赋给 scrollTop
+    const scrollHeight = 9999
+    let capturedScrollTop = -1
+    const proto = HTMLElement.prototype as unknown as {
+      get scrollHeight(): number
+    }
+    Object.defineProperty(proto, 'scrollHeight', {
+      configurable: true,
+      get: function (this: HTMLElement) {
+        // 用 function 而非箭头,this 才能拿到挂载对象
+        return this.tagName === 'DIV' && this.id === 'pyrof-console-body' ? scrollHeight : 0
+      }
+    })
+    Object.defineProperty(HTMLElement.prototype, 'scrollTop', {
+      configurable: true,
+      get: function () {
+        return 0
+      },
+      set: function (this: HTMLElement, v: number) {
+        if (this.id === 'pyrof-console-body') capturedScrollTop = v
+      }
+    })
+
+    render(wrap(<ControlledRunConsole stdout="hello" isRunning={false} onClear={() => {}} />))
+    expect(capturedScrollTop).toBe(scrollHeight)
+
+    // 清理 mock,避免污染其它测试
+    delete (HTMLElement.prototype as unknown as { scrollHeight: unknown }).scrollHeight
+    delete (HTMLElement.prototype as unknown as { scrollTop: unknown }).scrollTop
+  })
+
+  it('overflow 区域 aria-label 指向 console.title', () => {
+    const { container } = render(
+      wrap(<ControlledRunConsole stdout="" isRunning={false} onClear={() => {}} />)
+    )
+    const section = container.querySelector('section')
+    expect(section).toHaveAttribute('aria-label', '运行输出')
+  })
+})
diff --git a/src/renderer/src/components/__tests__/SettingsModal.test.tsx b/src/renderer/src/components/__tests__/SettingsModal.test.tsx
new file mode 100644
index 0000000..a93ebed
--- /dev/null
+++ b/src/renderer/src/components/__tests__/SettingsModal.test.tsx
@@ -0,0 +1,241 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import SettingsModal from '../SettingsModal'
+import type { UseInterpretersResult } from '../../hooks/useInterpreters'
+import { wrap } from '../../i18n/test-utils'
+
+// 最小 fake api —— SettingsModal 在打开时会读 window.api.platform 来决定是否
+// 渲染 Shell section,InterpreterControls 也会通过 window.api.openTerminal / platform
+// 构造安装命令,AboutControls 会调 openExternal。所以测试里必须先挂上一个 fake,
+// 否则访问 undefined.platform 抛错。
+interface FakeApi {
+  platform: 'win32' | 'darwin' | 'linux'
+  detectInterpreters: ReturnType<typeof vi.fn>
+  pickInterpreter: ReturnType<typeof vi.fn>
+  analyze: ReturnType<typeof vi.fn>
+  cancel: ReturnType<typeof vi.fn>
+  openTerminal: ReturnType<typeof vi.fn>
+  onProgress: () => () => void
+  openExternal: ReturnType<typeof vi.fn>
+}
+
+function installFakeApi(overrides: Partial<FakeApi> = {}): FakeApi {
+  const api: FakeApi = {
+    // 默认 linux:Shell section 不渲染(测试期望 queryByRole('radiogroup') 为空)。
+    // 想覆盖时传 overrides.platform = 'win32'。
+    platform: 'linux',
+    detectInterpreters: vi.fn().mockResolvedValue([]),
+    pickInterpreter: vi.fn().mockResolvedValue(null),
+    analyze: vi.fn().mockResolvedValue({}),
+    cancel: vi.fn().mockResolvedValue(undefined),
+    openTerminal: vi.fn().mockResolvedValue(undefined),
+    onProgress: () => () => undefined,
+    openExternal: vi.fn().mockResolvedValue(undefined),
+    ...overrides
+  }
+  ;(window as unknown as { api: FakeApi }).api = api
+  return api
+}
+
+beforeEach(() => {
+  installFakeApi()
+})
+
+afterEach(() => {
+  window.localStorage.clear()
+  delete (window as unknown as { api?: unknown }).api
+})
+
+function makeStubInterpreters(overrides: Partial<UseInterpretersResult> = {}): UseInterpretersResult {
+  return {
+    interpreters: [
+      { path: 'C:/python/python.exe', version: '3.11.0' },
+      { path: 'C:/python2/python.exe', version: '3.10.0' }
+    ],
+    selected: 'C:/python/python.exe',
+    selectPath: vi.fn(),
+    detecting: false,
+    detectError: null,
+    pickError: null,
+    detectAll: vi.fn().mockResolvedValue(undefined),
+    pick: vi.fn().mockResolvedValue(undefined),
+    active: { path: 'C:/python/python.exe', version: '3.11.0' },
+    ...overrides
+  }
+}
+
+const stubInterpreters: UseInterpretersResult = makeStubInterpreters()
+
+describe('SettingsModal', () => {
+  it('未 open 时不渲染内容', () => {
+    render(
+      wrap(
+        <SettingsModal
+          open={false}
+          onClose={vi.fn()}
+          interpreters={stubInterpreters}
+          shell="cmd"
+          setShell={vi.fn()}
+        />
+      )
+    )
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+  })
+
+  it('open 时显示「设置」标题 + 解释器 section（语言 / 主题已搬到 TopBar）', () => {
+    render(
+      wrap(
+        <SettingsModal
+          open
+          onClose={vi.fn()}
+          interpreters={stubInterpreters}
+          shell="cmd"
+          setShell={vi.fn()}
+        />
+      )
+    )
+    expect(screen.getByRole('dialog', { name: '设置' })).toBeInTheDocument()
+    expect(screen.getByText('解释器')).toBeInTheDocument()
+    // 语言 / 主题 不再出现在 Modal 里 —— 它们在 TopBar 右上角
+    expect(screen.queryByText('语言')).not.toBeInTheDocument()
+    expect(screen.queryByText('主题')).not.toBeInTheDocument()
+    // Shell section 仅在 win32 渲染 — 默认 fake api platform='linux',
+    // 所以 radiogroup 不应该出现
+    expect(screen.queryByRole('radiogroup')).not.toBeInTheDocument()
+  })
+
+  it('解释器 select 变化调 selectPath', () => {
+    const selectPath = vi.fn()
+    const interpreters = makeStubInterpreters({ selectPath })
+    render(
+      wrap(
+        <SettingsModal open onClose={vi.fn()} interpreters={interpreters} shell="cmd" setShell={vi.fn()} />
+      )
+    )
+    const select = screen.getByRole('combobox', { name: 'Python 解释器' })
+    fireEvent.change(select, { target: { value: 'C:/python2/python.exe' } })
+    expect(selectPath).toHaveBeenCalledWith('C:/python2/python.exe')
+  })
+
+  it('点遮罩（dialog 容器）触发 onClose', () => {
+    const onClose = vi.fn()
+    render(
+      wrap(
+        <SettingsModal
+          open
+          onClose={onClose}
+          interpreters={stubInterpreters}
+          shell="cmd"
+          setShell={vi.fn()}
+        />
+      )
+    )
+    // 遮罩是 dialog 的父节点；点 dialog 自身会被 stopPropagation 拦住，所以点外层
+    const dialog = screen.getByRole('dialog')
+    const backdrop = dialog.parentElement!
+    fireEvent.click(backdrop)
+    expect(onClose).toHaveBeenCalled()
+  })
+
+  it('点内容区不触发 onClose（stopPropagation）', () => {
+    const onClose = vi.fn()
+    render(
+      wrap(
+        <SettingsModal
+          open
+          onClose={onClose}
+          interpreters={stubInterpreters}
+          shell="cmd"
+          setShell={vi.fn()}
+        />
+      )
+    )
+    const dialog = screen.getByRole('dialog')
+    const inner = dialog.firstElementChild!
+    fireEvent.click(inner)
+    expect(onClose).not.toHaveBeenCalled()
+  })
+
+  it('active 解释器时显示「Python x.y.z · 路径」', () => {
+    render(
+      wrap(
+        <SettingsModal
+          open
+          onClose={vi.fn()}
+          interpreters={stubInterpreters}
+          shell="cmd"
+          setShell={vi.fn()}
+        />
+      )
+    )
+    expect(screen.getByText(/Python 3\.11\.0 · C:\/python\/python\.exe/)).toBeInTheDocument()
+  })
+
+  it('win32 平台渲染 Shell section：两个 radio，点 PowerShell 调 setShell("powershell")', () => {
+    installFakeApi({ platform: 'win32' })
+    const setShell = vi.fn()
+    render(
+      wrap(
+        <SettingsModal
+          open
+          onClose={vi.fn()}
+          interpreters={stubInterpreters}
+          shell="cmd"
+          setShell={setShell}
+        />
+      )
+    )
+    const group = screen.getByRole('radiogroup', { name: '打开终端用的 shell' })
+    expect(group).toBeInTheDocument()
+    // cmd radio 已选中（aria-checked=true）
+    expect(screen.getByRole('radio', { name: '命令提示符 (cmd)' })).toHaveAttribute('aria-checked', 'true')
+    // 点 PowerShell 触发 setShell
+    fireEvent.click(screen.getByRole('radio', { name: 'PowerShell' }))
+    expect(setShell).toHaveBeenCalledWith('powershell')
+  })
+
+  it('渲染「关于」section：开发者标签 + 姓名 + URL,URL 可点调 openExternal', () => {
+    const openExternal = vi.fn().mockResolvedValue(undefined)
+    installFakeApi({ openExternal })
+    render(
+      wrap(
+        <SettingsModal
+          open
+          onClose={vi.fn()}
+          interpreters={stubInterpreters}
+          shell="cmd"
+          setShell={vi.fn()}
+        />
+      )
+    )
+    // section 标题 + 「开发者」标签 + 开发者姓名 + URL
+    expect(screen.getByText('关于')).toBeInTheDocument()
+    expect(screen.getByText('开发者')).toBeInTheDocument()
+    expect(screen.getByText('关济寰')).toBeInTheDocument()
+    // URL 渲染为可点链接 —— button accessible name 是带前缀的「访问 {name} 的个人主页」,
+    // 视觉文本仍是 URL 原文,这样 SR 用户既知道打开的是谁的页面,也能听到 / 看到 URL。
+    const link = screen.getByRole('button', { name: '访问 关济寰 的个人主页' })
+    expect(link).toHaveTextContent('https://www.guanjihuan.com/about')
+    fireEvent.click(link)
+    expect(openExternal).toHaveBeenCalledWith('https://www.guanjihuan.com/about')
+  })
+
+  it('openExternal 抛错时显示错误条', async () => {
+    const openExternal = vi.fn().mockRejectedValue(new Error('boom'))
+    installFakeApi({ openExternal })
+    render(
+      wrap(
+        <SettingsModal
+          open
+          onClose={vi.fn()}
+          interpreters={stubInterpreters}
+          shell="cmd"
+          setShell={vi.fn()}
+        />
+      )
+    )
+    fireEvent.click(screen.getByRole('button', { name: '访问 关济寰 的个人主页' }))
+    // 错误以文本节点出现 —— Error.message 原文('boom')兜底展示。
+    expect(await screen.findByText(/boom/)).toBeInTheDocument()
+  })
+})
diff --git a/src/renderer/src/components/__tests__/Splitter.test.tsx b/src/renderer/src/components/__tests__/Splitter.test.tsx
new file mode 100644
index 0000000..91094a8
--- /dev/null
+++ b/src/renderer/src/components/__tests__/Splitter.test.tsx
@@ -0,0 +1,443 @@
+/**
+ * Splitter 的单元测试。
+ *
+ * - jsdom 24 不带 PointerEvent;fireEvent.pointerDown 因此退化成裸 Event,button /
+ *   clientX / pointerId 全丢失,Splitter 的 onPointerDown 会因 e.button !== 0 直接
+ *   return。在本文件顶部 inline 一个最小 polyfill (继承 MouseEvent),让
+ *   fireEvent.pointerDown / pointerUp 派发的 PointerEventInit 真正生效。
+ *   vitest.setup.ts 故意保持纯净,不在那里挂全局 polyfill —— 只有真正用到
+ *   Pointer Events 的测试自己负责。
+ * - Splitter 在 document 上挂 pointermove / pointerup / pointercancel 监听,
+ *   fireEvent.pointerMove(sep, ...) 派发的事件冒泡到 document 时会被接住。
+ * - 静止的 pointermove (delta=0) 被 handleMove 内部提前 return,不触发 onDelta。
+ * - endDrag 用 draggingRef 做了幂等:第一次 pointerup 清理完,后续再调直接 return。
+ */
+import { fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import Splitter from '../Splitter'
+
+// PointerEvent polyfill —— 必须在 import Splitter 之前安装,确保后续 useEffect
+// 注册的全局 document 监听跑在这个 polyfill 之下。
+if (typeof globalThis.PointerEvent === 'undefined') {
+  class PointerEventPolyfill extends MouseEvent {
+    public readonly pointerId: number
+    public readonly pointerType: string
+    public readonly isPrimary: boolean
+    constructor(type: string, params: PointerEventInit = {}) {
+      super(type, params)
+      this.pointerId = params.pointerId ?? 0
+      this.pointerType = params.pointerType ?? ''
+      this.isPrimary = params.isPrimary ?? true
+    }
+  }
+  globalThis.PointerEvent = PointerEventPolyfill as unknown as typeof PointerEvent
+}
+
+afterEach(() => {
+  // 拖拽期间 body 样式被覆盖,清理避免污染下一个 case
+  document.body.style.cursor = ''
+  document.body.style.userSelect = ''
+})
+
+describe('Splitter', () => {
+  it('渲染:role=separator + aria-orientation + aria-label + data-* 属性', () => {
+    render(
+      <Splitter
+        orientation="vertical"
+        onDelta={() => {}}
+        ariaLabel="Resize A and B"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'Resize A and B' })
+    expect(sep).toBeInTheDocument()
+    expect(sep).toHaveAttribute('aria-orientation', 'vertical')
+    expect(sep).toHaveAttribute('aria-label', 'Resize A and B')
+    expect(sep).toHaveAttribute('data-orientation', 'vertical')
+    expect(sep).toHaveAttribute('data-dragging', 'false')
+  })
+
+  it('horizontal orientation 也正确标 aria + data', () => {
+    render(
+      <Splitter
+        orientation="horizontal"
+        onDelta={() => {}}
+        ariaLabel="Resize vertically"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'Resize vertically' })
+    expect(sep).toHaveAttribute('aria-orientation', 'horizontal')
+    expect(sep).toHaveAttribute('data-orientation', 'horizontal')
+  })
+
+  it('ariaControls 拼成空格分隔的列表', () => {
+    render(
+      <Splitter
+        orientation="vertical"
+        onDelta={() => {}}
+        ariaLabel="Resize"
+        ariaControls={['pane-left', 'pane-right']}
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'Resize' })
+    expect(sep).toHaveAttribute('aria-controls', 'pane-left pane-right')
+  })
+
+  it('ariaValueNow / Min / Max 都写到属性', () => {
+    render(
+      <Splitter
+        orientation="vertical"
+        onDelta={() => {}}
+        ariaLabel="Resize"
+        ariaValueNow={60}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'Resize' })
+    expect(sep).toHaveAttribute('aria-valuenow', '60')
+    expect(sep).toHaveAttribute('aria-valuemin', '20')
+    expect(sep).toHaveAttribute('aria-valuemax', '80')
+  })
+
+  it('ariaValueNow 不传时不输出 valuenow / min / max（可选）', () => {
+    render(<Splitter orientation="vertical" onDelta={() => {}} ariaLabel="Resize" />)
+    const sep = screen.getByRole('separator', { name: 'Resize' })
+    expect(sep).not.toHaveAttribute('aria-valuenow')
+    expect(sep).not.toHaveAttribute('aria-valuemin')
+    expect(sep).not.toHaveAttribute('aria-valuemax')
+  })
+
+  it('vertical 拖拽：X 位移触发 onDelta,Y 位移忽略', () => {
+    const onDelta = vi.fn()
+    render(
+      <Splitter
+        orientation="vertical"
+        onDelta={onDelta}
+        ariaLabel="V"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'V' })
+
+    fireEvent.pointerDown(sep, { clientX: 100, clientY: 100, button: 0, pointerId: 1, pointerType: 'mouse' })
+    expect(sep).toHaveAttribute('data-dragging', 'true')
+    fireEvent.pointerMove(sep, { clientX: 130, clientY: 999, pointerId: 1, pointerType: 'mouse' })
+    fireEvent.pointerUp(sep, { clientX: 130, clientY: 999, pointerId: 1, pointerType: 'mouse' })
+    expect(sep).toHaveAttribute('data-dragging', 'false')
+
+    expect(onDelta).toHaveBeenCalledTimes(1)
+    expect(onDelta).toHaveBeenCalledWith(30)
+  })
+
+  it('horizontal 拖拽：只取 Y 位移', () => {
+    const onDelta = vi.fn()
+    render(
+      <Splitter
+        orientation="horizontal"
+        onDelta={onDelta}
+        ariaLabel="H"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'H' })
+
+    fireEvent.pointerDown(sep, { clientX: 100, clientY: 100, button: 0, pointerId: 1, pointerType: 'mouse' })
+    fireEvent.pointerMove(sep, { clientX: 500, clientY: 150, pointerId: 1, pointerType: 'mouse' })
+    fireEvent.pointerUp(sep, { clientX: 500, clientY: 150, pointerId: 1, pointerType: 'mouse' })
+
+    expect(onDelta).toHaveBeenCalledTimes(1)
+    expect(onDelta).toHaveBeenCalledWith(50)
+  })
+
+  it('多次 pointermove 累加 delta,静止帧（delta=0）被 handleMove 跳过', () => {
+    const onDelta = vi.fn()
+    render(
+      <Splitter
+        orientation="vertical"
+        onDelta={onDelta}
+        ariaLabel="V"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'V' })
+
+    fireEvent.pointerDown(sep, { clientX: 0, clientY: 0, button: 0, pointerId: 1, pointerType: 'mouse' })
+    fireEvent.pointerMove(sep, { clientX: 10, clientY: 0, pointerId: 1, pointerType: 'mouse' }) // +10
+    fireEvent.pointerMove(sep, { clientX: 25, clientY: 0, pointerId: 1, pointerType: 'mouse' }) // +15
+    fireEvent.pointerMove(sep, { clientX: 25, clientY: 0, pointerId: 1, pointerType: 'mouse' }) // 静止 → skip
+    fireEvent.pointerMove(sep, { clientX: 40, clientY: 0, pointerId: 1, pointerType: 'mouse' }) // +15
+    fireEvent.pointerUp(sep, { clientX: 40, clientY: 0, pointerId: 1, pointerType: 'mouse' })
+
+    expect(onDelta).toHaveBeenCalledTimes(3)
+    expect(onDelta).toHaveBeenNthCalledWith(1, 10)
+    expect(onDelta).toHaveBeenNthCalledWith(2, 15)
+    expect(onDelta).toHaveBeenNthCalledWith(3, 15)
+  })
+
+  it('pointerdown 非主键（右键/中键）不进入拖拽', () => {
+    const onDelta = vi.fn()
+    render(
+      <Splitter
+        orientation="vertical"
+        onDelta={onDelta}
+        ariaLabel="V"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'V' })
+
+    fireEvent.pointerDown(sep, { clientX: 100, clientY: 0, button: 2, pointerId: 1, pointerType: 'mouse' })
+    fireEvent.pointerMove(sep, { clientX: 200, clientY: 0, pointerId: 1, pointerType: 'mouse' })
+
+    expect(onDelta).not.toHaveBeenCalled()
+    expect(sep).toHaveAttribute('data-dragging', 'false')
+  })
+
+  it('pointercancel 也会触发 endDrag,dragging 状态正确还原', () => {
+    const onDelta = vi.fn()
+    render(
+      <Splitter
+        orientation="vertical"
+        onDelta={onDelta}
+        ariaLabel="V"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'V' })
+
+    fireEvent.pointerDown(sep, { clientX: 0, clientY: 0, button: 0, pointerId: 1, pointerType: 'mouse' })
+    fireEvent.pointerMove(sep, { clientX: 20, clientY: 0, pointerId: 1, pointerType: 'mouse' })
+    fireEvent.pointerCancel(sep, { clientX: 20, clientY: 0, pointerId: 1, pointerType: 'mouse' })
+
+    expect(sep).toHaveAttribute('data-dragging', 'false')
+    expect(onDelta).toHaveBeenCalledTimes(1)
+  })
+
+  it('键盘 ArrowLeft/Right 触发 onDelta（vertical splitter,默认 step=16）', () => {
+    const onDelta = vi.fn()
+    render(
+      <Splitter
+        orientation="vertical"
+        onDelta={onDelta}
+        ariaLabel="V"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'V' })
+    sep.focus()
+
+    fireEvent.keyDown(sep, { key: 'ArrowRight' })
+    fireEvent.keyDown(sep, { key: 'ArrowLeft' })
+
+    expect(onDelta).toHaveBeenCalledTimes(2)
+    expect(onDelta).toHaveBeenNthCalledWith(1, 16)
+    expect(onDelta).toHaveBeenNthCalledWith(2, -16)
+  })
+
+  it('键盘 ArrowUp/Down 触发 onDelta（horizontal splitter）', () => {
+    const onDelta = vi.fn()
+    render(
+      <Splitter
+        orientation="horizontal"
+        onDelta={onDelta}
+        ariaLabel="H"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'H' })
+    sep.focus()
+
+    fireEvent.keyDown(sep, { key: 'ArrowDown' })
+    fireEvent.keyDown(sep, { key: 'ArrowUp' })
+
+    expect(onDelta).toHaveBeenCalledTimes(2)
+    expect(onDelta).toHaveBeenNthCalledWith(1, 16)
+    expect(onDelta).toHaveBeenNthCalledWith(2, -16)
+  })
+
+  it('Shift + Arrow 是大步进（默认 step * 8 = 128）', () => {
+    const onDelta = vi.fn()
+    render(
+      <Splitter
+        orientation="vertical"
+        onDelta={onDelta}
+        ariaLabel="V"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'V' })
+    sep.focus()
+
+    fireEvent.keyDown(sep, { key: 'ArrowRight', shiftKey: true })
+
+    expect(onDelta).toHaveBeenCalledTimes(1)
+    expect(onDelta).toHaveBeenCalledWith(128)
+  })
+
+  it('PageUp / PageDown 走大步进,Home / End 走极值', () => {
+    const onDelta = vi.fn()
+    render(
+      <Splitter
+        orientation="vertical"
+        onDelta={onDelta}
+        ariaLabel="V"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'V' })
+    sep.focus()
+
+    fireEvent.keyDown(sep, { key: 'PageDown' })
+    fireEvent.keyDown(sep, { key: 'PageUp' })
+    fireEvent.keyDown(sep, { key: 'Home' })
+    fireEvent.keyDown(sep, { key: 'End' })
+
+    expect(onDelta).toHaveBeenCalledTimes(4)
+    // ariaValueMax=80: Home = -(80+1) = -81, End = 80+1 = 81
+    expect(onDelta).toHaveBeenNthCalledWith(1, 128) // PageDown = big
+    expect(onDelta).toHaveBeenNthCalledWith(2, -128) // PageUp
+    expect(onDelta).toHaveBeenNthCalledWith(3, -81) // Home
+    expect(onDelta).toHaveBeenNthCalledWith(4, 81) // End
+  })
+
+  it('其他键不触发 onDelta', () => {
+    const onDelta = vi.fn()
+    render(
+      <Splitter
+        orientation="vertical"
+        onDelta={onDelta}
+        ariaLabel="V"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'V' })
+    sep.focus()
+
+    fireEvent.keyDown(sep, { key: 'a' })
+    fireEvent.keyDown(sep, { key: 'Enter' })
+    fireEvent.keyDown(sep, { key: 'Tab' })
+
+    expect(onDelta).not.toHaveBeenCalled()
+  })
+
+  it('键盘箭头调用 preventDefault（避免页面滚动）', () => {
+    const onDelta = vi.fn()
+    render(
+      <Splitter
+        orientation="vertical"
+        onDelta={onDelta}
+        ariaLabel="V"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'V' })
+    sep.focus()
+
+    const ev = new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true, cancelable: true })
+    fireEvent(sep, ev)
+
+    expect(ev.defaultPrevented).toBe(true)
+  })
+
+  it('拖拽期间 body cursor / userSelect 锁住,结束时还原', () => {
+    document.body.style.cursor = 'pointer'
+    document.body.style.userSelect = 'text'
+
+    const onDelta = vi.fn()
+    render(
+      <Splitter
+        orientation="vertical"
+        onDelta={onDelta}
+        ariaLabel="V"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'V' })
+
+    fireEvent.pointerDown(sep, { clientX: 0, clientY: 0, button: 0, pointerId: 1, pointerType: 'mouse' })
+    expect(document.body.style.cursor).toBe('col-resize')
+    expect(document.body.style.userSelect).toBe('none')
+
+    fireEvent.pointerUp(sep, { clientX: 0, clientY: 0, pointerId: 1, pointerType: 'mouse' })
+    expect(document.body.style.cursor).toBe('pointer')
+    expect(document.body.style.userSelect).toBe('text')
+  })
+
+  it('horizontal splitter 拖拽期间 body cursor 是 row-resize', () => {
+    render(
+      <Splitter
+        orientation="horizontal"
+        onDelta={() => {}}
+        ariaLabel="H"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'H' })
+
+    fireEvent.pointerDown(sep, { clientX: 0, clientY: 0, button: 0, pointerId: 1, pointerType: 'mouse' })
+    expect(document.body.style.cursor).toBe('row-resize')
+
+    fireEvent.pointerUp(sep, { clientX: 0, clientY: 0, pointerId: 1, pointerType: 'mouse' })
+  })
+
+  it('endDrag 幂等:连发 pointerup / pointercancel 不会重复 setDragging / releaseBody', () => {
+    document.body.style.cursor = 'help'
+    document.body.style.userSelect = 'auto'
+
+    render(
+      <Splitter
+        orientation="vertical"
+        onDelta={() => {}}
+        ariaLabel="V"
+        ariaValueNow={50}
+        ariaValueMin={20}
+        ariaValueMax={80}
+      />
+    )
+    const sep = screen.getByRole('separator', { name: 'V' })
+
+    fireEvent.pointerDown(sep, { clientX: 0, clientY: 0, button: 0, pointerId: 1, pointerType: 'mouse' })
+    fireEvent.pointerUp(sep, { clientX: 0, clientY: 0, pointerId: 1, pointerType: 'mouse' })
+    fireEvent.pointerCancel(sep, { clientX: 0, clientY: 0, pointerId: 1, pointerType: 'mouse' })
+    fireEvent.pointerUp(sep, { clientX: 0, clientY: 0, pointerId: 1, pointerType: 'mouse' })
+
+    // 第一次清理完后 body 应回到原始 'help' / 'auto',后续 idempotent 不动它
+    expect(document.body.style.cursor).toBe('help')
+    expect(document.body.style.userSelect).toBe('auto')
+  })
+})
diff --git a/src/renderer/src/components/icons.tsx b/src/renderer/src/components/icons.tsx
new file mode 100644
index 0000000..6f1bd7d
--- /dev/null
+++ b/src/renderer/src/components/icons.tsx
@@ -0,0 +1,307 @@
+/**
+ * 集中图标库：内联 SVG，与设计 token（currentColor / accent）一致。
+ *
+ * 设计原则：
+ * - 不引入图标库；项目全部走 currentColor，方便上层用 className 控制颜色
+ * - 所有图标 aria-hidden="true"，由包裹它们的可见文字承担 a11y
+ * - strokeWidth 1.5~1.6，圆角端点（strokeLinecap="round"），Linear 风格
+ *
+ * 用法：`import { GearIcon } from './icons'`
+ *
+ * 内联到组件里的非本文件图标（比如 FileIcon in CodePanel）仍然就近放在组件文件
+ * — 它们与组件强耦合（颜色 / 状态由父组件决定），不必强迁到这里。
+ */
+
+import type { SVGProps } from 'react'
+
+type IconProps = Omit<SVGProps<SVGSVGElement>, 'viewBox' | 'fill' | 'aria-hidden'> & {
+  size?: number
+}
+
+/** Python 双色 logo（RunConfig 用）。 */
+export function PythonIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <path
+        d="M11.914 0c-.62 0-1.273.022-1.93.066-1.99.131-2.353 1.328-2.353 2.98v2.04h4.7v.68H6.43c-1.366 0-2.561.82-2.937 2.381-.432 1.788-.452 2.903 0 4.98.334 1.553 1.13 2.382 2.496 2.382h1.616v-2.264c0-1.638 1.418-3.084 3.078-3.084h4.696c1.37 0 2.466-1.13 2.466-2.504V3.046C18.05 1.394 17.355.13 15.378.066 14.252.022 13.085 0 11.914 0zM9.62 1.62a.86.86 0 110 1.72.86.86 0 010-1.72z"
+        fill="#3776AB"
+      />
+      <path
+        d="M12.086 24c.62 0 1.273-.022 1.93-.066 1.99-.131 2.353-1.328 2.353-2.98v-2.04h-4.7v-.68h5.901c1.366 0 2.561-.82 2.937-2.381.432-1.788.452-2.903 0-4.98-.334-1.553-1.13-2.382-2.496-2.382h-1.616v2.264c0 1.638-1.418 3.084-3.078 3.084H8.62c-1.37 0-2.466 1.13-2.466 2.504v3.49c0 1.652.695 2.916 2.672 2.98 1.126.044 2.293.066 3.464.066zM14.38 22.38a.86.86 0 110-1.72.86.86 0 010 1.72z"
+        fill="#FFD43B"
+      />
+    </svg>
+  )
+}
+
+/** 齿轮（Settings 入口图标）。 */
+export function GearIcon({ size = 16, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <path
+        d="M12 8.5a3.5 3.5 0 100 7 3.5 3.5 0 000-7zM19.4 12c0-.5-.05-1-.13-1.46l2.1-1.65a.5.5 0 00.12-.64l-2-3.46a.5.5 0 00-.6-.22l-2.49 1a7.4 7.4 0 00-2.52-1.46l-.38-2.65A.5.5 0 0013 1h-4a.5.5 0 00-.5.42l-.38 2.65a7.4 7.4 0 00-2.52 1.46l-2.49-1a.5.5 0 00-.6.22l-2 3.46a.5.5 0 00.12.64l2.1 1.65c-.08.46-.13.96-.13 1.46s.05 1 .13 1.46L.62 15.07a.5.5 0 00-.12.64l2 3.46a.5.5 0 00.6.22l2.49-1a7.4 7.4 0 002.52 1.46l.38 2.65A.5.5 0 008.99 23h4a.5.5 0 00.5-.42l.38-2.65a7.4 7.4 0 002.52-1.46l2.49 1a.5.5 0 00.6-.22l2-3.46a.5.5 0 00-.12-.64l-2.1-1.65c.08-.46.13-.96.13-1.46z"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+
+/** 火焰（火焰图 section 标题前的小图标）。 */
+export function FlameIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <path
+        d="M12 3c.5 2.5 2.5 4 2.5 7 0 1.4-.6 2.4-1.5 3 .5-1.6 0-3-1-4 0 2-1 3-2 4-1.5 1.5-2 3.5-2 5a4 4 0 008 0c0-3-2-5-2-8 0-3 .5-5 1-7-1.5 1-3 2-3 0z"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+
+/** 表格（热点表 section 标题前的小图标：3 行 3 列）。 */
+export function TableIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <rect x="3" y="5" width="18" height="14" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
+      <path d="M3 10h18" stroke="currentColor" strokeWidth="1.5" />
+      <path d="M3 14.5h18" stroke="currentColor" strokeWidth="1.5" />
+      <path d="M9.5 5v14" stroke="currentColor" strokeWidth="1.5" />
+    </svg>
+  )
+}
+
+/** 太阳（亮色主题提示：亮色模式下显示当前态，点了切到暗色）。 */
+export function SunIcon({ size = 16, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <circle cx="12" cy="12" r="4" stroke="currentColor" strokeWidth="1.5" />
+      <path
+        d="M12 3v2M12 19v2M3 12h2M19 12h2M5.6 5.6l1.4 1.4M17 17l1.4 1.4M5.6 18.4L7 17M17 7l1.4-1.4"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+      />
+    </svg>
+  )
+}
+
+/** 月亮（暗色主题提示：暗色模式下显示当前态，点了切到亮色）。 */
+export function MoonIcon({ size = 16, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <path
+        d="M20.5 14.2A8 8 0 119.8 3.5a7 7 0 0010.7 10.7z"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+
+/** 空状态 step 1 图标：粘贴 / 文档 */
+export function CodeIcon({ size = 16, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <path
+        d="M8 7l-4 5 4 5M16 7l4 5-4 5M14 5l-4 14"
+        stroke="currentColor"
+        strokeWidth="1.6"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+
+/** 空状态 step 2 图标：解释器 (Python snake) */
+export function InterpreterIcon({ size = 16, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <path
+        d="M12 3v3M12 18v3M3 12h3M18 12h3M5.6 5.6l2.1 2.1M16.3 16.3l2.1 2.1M5.6 18.4l2.1-2.1M16.3 7.7l2.1-2.1"
+        stroke="currentColor"
+        strokeWidth="1.6"
+        strokeLinecap="round"
+      />
+      <circle cx="12" cy="12" r="3" stroke="currentColor" strokeWidth="1.6" />
+    </svg>
+  )
+}
+
+/** 空状态 step 3 图标：运行 / 播放 */
+export function PlayIcon({ size = 16, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <path d="M7 5.5v13a1 1 0 001.5.86l11-6.5a1 1 0 000-1.72l-11-6.5A1 1 0 007 5.5z" fill="currentColor" />
+    </svg>
+  )
+}
+
+/** 柱状图图标（3 根高低不一的竖条）—— BarChart 切换按钮。 */
+export function BarIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <path d="M5 19V11" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+      <path d="M12 19V6" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+      <path d="M19 19V14" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+/** 矩形树图图标（2×2 不同大小的方块）—— Treemap 切换按钮。 */
+export function TreemapIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <rect x="4" y="4" width="10" height="16" rx="1" stroke="currentColor" strokeWidth="1.6" />
+      <rect x="15" y="4" width="5" height="9" rx="1" stroke="currentColor" strokeWidth="1.6" />
+      <rect x="15" y="14" width="5" height="6" rx="1" stroke="currentColor" strokeWidth="1.6" />
+    </svg>
+  )
+}
+
+/** 旭日图图标（同心弧 + 一根径向分隔）—— Sunburst 切换按钮。 */
+export function SunburstIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <path
+        d="M12 12 L21 12 A9 9 0 0 0 12 3 Z"
+        stroke="currentColor"
+        strokeWidth="1.6"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M12 12 L17.5 12 A5.5 5.5 0 0 0 12 6.5 Z"
+        stroke="currentColor"
+        strokeWidth="1.6"
+        strokeLinejoin="round"
+      />
+      <path d="M12 12 L18.36 5.64" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+/** 累计条形图标（横条 + 内部分段线）—— CumulativeBar 切换按钮。 */
+export function CumulativeIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <rect x="3" y="9" width="18" height="6" rx="1.5" stroke="currentColor" strokeWidth="1.6" />
+      <line x1="9" y1="9" x2="9" y2="15" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+/** 模块热力图标（2 行 ×3 列,每格大小不同）—— ModuleHeatmap 切换按钮。 */
+export function HeatmapIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <rect x="3" y="3" width="10" height="7" rx="1" stroke="currentColor" strokeWidth="1.6" />
+      <rect x="14" y="3" width="7" height="7" rx="1" stroke="currentColor" strokeWidth="1.6" />
+      <rect x="3" y="11" width="6" height="10" rx="1" stroke="currentColor" strokeWidth="1.6" />
+      <rect x="10" y="11" width="11" height="10" rx="1" stroke="currentColor" strokeWidth="1.6" />
+    </svg>
+  )
+}
+
+/** 通用图表图标（带升势线的方框）—— ResultsPanel 段头用。 */
+export function ChartIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <rect x="3.5" y="3.5" width="17" height="17" rx="2" stroke="currentColor" strokeWidth="1.5" />
+      <path
+        d="M7 15l3-4 3 2 4-5"
+        stroke="currentColor"
+        strokeWidth="1.6"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+
+/** 终端图标（顶栏的「切换终端」按钮用）。 */
+export function TerminalIcon({ size = 16, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <rect x="3" y="4.5" width="18" height="15" rx="2" stroke="currentColor" strokeWidth="1.5" />
+      <path
+        d="M7 10l3 2.5L7 15M12.5 15.5h4"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+
+/** 关闭 (X) —— SettingsModal 关闭按钮。1.6 描边 + 圆角端点，与其它图标风格一致；
+ * 视觉上是「斜十字」而非孤零零的 × 文本字符，避免不同字体下渲染不一致。 */
+export function CloseIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <path d="M6 6l12 12M18 6L6 18" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+/** 最小化（底部横线）—— WindowControls 用。 */
+export function MinimizeIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <path d="M5 19h14" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+/** 最大化（四角方框）—— WindowControls 在非最大化状态时显示。 */
+export function MaximizeIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <rect x="5" y="5" width="14" height="14" rx="1.5" stroke="currentColor" strokeWidth="1.6" />
+    </svg>
+  )
+}
+
+/** 还原（两个错位的方框，标识「从最大化还原」状态）—— WindowControls 在最大化时显示。 */
+export function RestoreIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <rect x="6" y="9" width="12" height="10" rx="1.5" stroke="currentColor" strokeWidth="1.6" />
+      <path
+        d="M9 9V6.5A1.5 1.5 0 0110.5 5H17.5A1.5 1.5 0 0119 6.5V13.5A1.5 1.5 0 0117.5 15H15"
+        stroke="currentColor"
+        strokeWidth="1.6"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+
+/** 警告 (三角形 + 感叹号) —— EmptyState 「需要先选解释器」提示条。 */
+export function WarningIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <path d="M12 3.2L21 19H3L12 3.2z" stroke="currentColor" strokeWidth="1.6" strokeLinejoin="round" />
+      <path d="M12 10v4" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+      <circle cx="12" cy="17" r="0.9" fill="currentColor" />
+    </svg>
+  )
+}
+
+/** 信息 (圆圈 + 小写 i) —— SettingsModal 「关于」section 标题前的小图标。 */
+export function InfoIcon({ size = 14, ...rest }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" aria-hidden="true" {...rest}>
+      <circle cx="12" cy="12" r="9" stroke="currentColor" strokeWidth="1.6" />
+      <path d="M12 11v5" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
+      <circle cx="12" cy="8" r="0.9" fill="currentColor" />
+    </svg>
+  )
+}
diff --git a/src/renderer/src/components/views/BarChart.tsx b/src/renderer/src/components/views/BarChart.tsx
new file mode 100644
index 0000000..36011ec
--- /dev/null
+++ b/src/renderer/src/components/views/BarChart.tsx
@@ -0,0 +1,217 @@
+import { memo, useMemo, type KeyboardEvent } from 'react'
+import type { FunctionNode } from '../../../../shared/analysis'
+import { fmtDuration, totalSelfTime } from '../../utils/format'
+import { FOCUS, FONT_MONO, FONT_SIZE, RESTING, charsForWidth, colorByName, truncateName } from './chart-utils'
+import { useT } from '../../i18n'
+import { ORIGIN_COLOR, ORIGIN_LABEL_KEY, resolveOrigin } from '../../utils/origin'
+
+/**
+ * 横向柱状图：按自耗时排序，取前 N 个函数以可读数量。
+ *
+ * 取 N=12 是有意为之 —— 一屏 12 行滚动可控，>12 之后用户基本不会逐个看柱长。
+ * 截断必显式提示：和 HotspotTable / FlameGraph 同款策略，不静默藏数据。
+ *
+ * v4 字号升级：从 15-16px 提到 16-18px,行高加大到 52,长 name 按可用宽度按字
+ * 数 ellipsis,小屏也不会挤成一团。
+ */
+const TOP_N = 12
+const CANVAS_W = 920
+const ROW_H = 52
+const ROW_GAP = 10
+/** 左侧 name 标签区宽度（px）。Cascadia Code 18px 下 ~11px/字 → ~22 字符。 */
+const NAME_W = 260
+/** 数据条右端到画布右边的留白 —— 给 "42.5% · 1.2s" 右对齐文本让出空间。 */
+const RIGHT_PAD = 140
+
+interface Props {
+  functions: readonly FunctionNode[]
+  /** 热点点击回调 —— 传整 FunctionNode 让 App.tsx 拿 file/origin 决定路由。 */
+  onSelect: (fn: FunctionNode) => void
+  focusName?: string
+}
+
+interface Bar {
+  fn: FunctionNode
+  pct: number
+  isFocus: boolean
+  origin: ReturnType<typeof resolveOrigin>
+}
+
+function BarChart({ functions, onSelect, focusName }: Props) {
+  const t = useT()
+
+  const total = useMemo(() => totalSelfTime(functions) || 1, [functions])
+
+  // 防御性排序：注释里说 "engines 已按 tottime 倒序输出"，但那是个不变量假设。
+  // 一旦 engines 改了顺序，图表静默错位。显式 sort + slice 一次到位，N=12 排序
+  // 代价 O(N log N) 可忽略，行为可预测。
+  const visible = useMemo(
+    () => [...functions].sort((a, b) => b.tottime - a.tottime).slice(0, TOP_N),
+    [functions]
+  )
+  const hidden = functions.length - visible.length
+
+  const bars = useMemo<Bar[]>(
+    () =>
+      visible.map((fn) => ({
+        fn,
+        pct: (100 * fn.tottime) / total,
+        isFocus: fn.name === focusName,
+        // 每条 bar 算一次 origin —— scope=all 时用户代码 / 第三方包 / 标准库同框
+        // 出现,色点帮助扫表时一眼区分。
+        origin: resolveOrigin(fn)
+      })),
+    [visible, total, focusName]
+  )
+
+  if (bars.length === 0) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm text-fg-muted">{t('chart.empty')}</div>
+    )
+  }
+
+  const totalH = bars.length * (ROW_H + ROW_GAP) + ROW_GAP
+  // 左侧 origin 色点：r=5 + 1px stroke,比 v3 的 r=4 大一档,在 18px 字号下视觉
+  // 锚点更稳;主题切换/浅色背景下都顶得住。aria-hidden 不参与 SR。
+  const ORIGIN_DOT_R = 5
+  const ORIGIN_DOT_CX = 12
+  const NAME_X = ORIGIN_DOT_CX + ORIGIN_DOT_R + 10 // 27
+  const BAR_X = NAME_W + 16
+  const BAR_W = CANVAS_W - BAR_X - RIGHT_PAD
+
+  return (
+    <div className="flex h-full flex-col p-3">
+      <div className="mb-2 text-sm text-fg-secondary" aria-live="polite">
+        {t('chart.bar.hint')}
+      </div>
+      {hidden > 0 && (
+        <div className="mb-2 text-sm text-fg-secondary" aria-live="polite">
+          {t('chart.truncated', { shown: TOP_N, hidden })}
+        </div>
+      )}
+      {/* 不内嵌 overflow-auto —— 外层 ResultsPanel 所在右栏自带 overflow-y-auto,
+          内嵌会形成「图内横滑 + 右栏纵滑」双层滚轮, 体验差。
+          SVG 用 viewBox + preserveAspectRatio="xMinYMin meet" 自适应尺寸,
+          数据再多也直接交给外层滚动接管。 */}
+      <div className="flex-1">
+        <svg
+          width="100%"
+          viewBox={`0 0 ${CANVAS_W} ${totalH}`}
+          preserveAspectRatio="xMinYMin meet"
+          role="img"
+          aria-label={t('chart.bar.aria')}
+        >
+          {bars.map((bar, i) => {
+            const y = i * (ROW_H + ROW_GAP) + ROW_GAP / 2
+            // 颜色用 colorByName：和 Treemap / Sunburst 保持"同函数 = 同色"。
+            const fill = colorByName(bar.fn.name)
+            const barPx = Math.max(0, (bar.pct / 100) * BAR_W)
+            const onKeyDown = (e: KeyboardEvent<SVGGElement>) => {
+              if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault()
+                onSelect(bar.fn)
+              }
+            }
+            // origin 长标签进 aria-label（SR 友好），同 HotspotTable 行的策略。
+            // 短码放 title tooltip，hover 看全名（origin 是 module 的上一级分类，
+            // 长标签能补足「第三方包 vs 标准库 vs 我自己的代码」的语义）。
+            const originLong = t(ORIGIN_LABEL_KEY[bar.origin])
+            const ariaText = t('chart.bar.tile.aria', {
+              name: bar.fn.name,
+              origin: originLong,
+              value: fmtDuration(bar.fn.tottime),
+              pct: bar.pct.toFixed(1)
+            })
+            // 按 NAME 区实际可用宽度反算能放几个字(Cascadia Code 18px ≈ 11px/字)
+            // —— 改字体大小/窗口宽度都自动重算,不绑死截断长度。
+            const nameMax = charsForWidth(NAME_W - NAME_X - 6, FONT_SIZE.NAME)
+            return (
+              <g
+                key={bar.fn.id}
+                transform={`translate(0, ${y})`}
+                role="button"
+                tabIndex={0}
+                aria-label={ariaText}
+                aria-keyshortcuts="Enter Space"
+                onClick={() => onSelect(bar.fn)}
+                onKeyDown={onKeyDown}
+                className="chart-tile cursor-pointer"
+              >
+                {/* origin 色点(v4 起 r=5)：行首圆点 + 半透明深色描边,
+                    在浅/深主题下都能稳住视觉锚点(无 stroke 会被浅色背景"吃掉")。
+                    同 ModuleHeatmap / HotspotTable 的 ORIGIN_COLOR —— 颜色 = 视觉锚点
+                    (绿色=用户代码/紫色=第三方/蓝色=标准库/...)。scope=all 时
+                    「我的代码 vs 库」一眼分清。aria-hidden 不参与 SR —— 已并入 aria-label。 */}
+                <circle
+                  cx={ORIGIN_DOT_CX}
+                  cy={ROW_H / 2}
+                  r={ORIGIN_DOT_R}
+                  fill={ORIGIN_COLOR[bar.origin]}
+                  stroke="rgba(0,0,0,0.25)"
+                  strokeWidth={1}
+                  aria-hidden="true"
+                />
+                {/* name 左对齐;currentColor 跟主题,长名截断加 ellipsis。
+                    <title> 已经展示完整名, 所以 hover 仍能看到全名。
+                    fontSize 18 + 自适应 charsForWidth,不再绑死 NAME_MAX_CHARS 兜底。 */}
+                <text
+                  x={NAME_X}
+                  y={ROW_H / 2 + 6}
+                  fill="currentColor"
+                  fontSize={FONT_SIZE.NAME}
+                  fontFamily={FONT_MONO}
+                  pointerEvents="none"
+                  aria-hidden="true"
+                >
+                  {truncateName(bar.fn.name, nameMax)}
+                </text>
+                {/* 背景轨：让用户一眼看出"最大值参考线"。不带 data-chart-shape,
+                    hover 时不动 —— 只有数据条会提亮。 */}
+                <rect
+                  x={BAR_X}
+                  y={ROW_H * 0.3}
+                  width={BAR_W}
+                  height={ROW_H * 0.4}
+                  rx={3}
+                  fill="var(--surface-1)"
+                />
+                {/* 数据条：和 Treemap / Sunburst 同样的 FOCUS / RESTING 描边。
+                    data-chart-shape 标记后,hover 时 fillOpacity 提到 1.0。 */}
+                <rect
+                  data-chart-shape
+                  x={BAR_X}
+                  y={ROW_H * 0.3}
+                  width={barPx}
+                  height={ROW_H * 0.4}
+                  rx={3}
+                  fill={fill}
+                  fillOpacity={bar.isFocus ? FOCUS.fillOpacity : RESTING.fillOpacity}
+                  stroke={bar.isFocus ? FOCUS.stroke : RESTING.stroke}
+                  strokeWidth={bar.isFocus ? FOCUS.strokeWidth : RESTING.strokeWidth}
+                />
+                {/* pct + 时长右对齐:currentColor 跟主题,精度 1 位和 tooltip 一致。
+                    fontSize 16 是 BODY 档位(主信息低于 NAME)。宽度变时 barPx 缩小,
+                    右文本不动 —— NAME 区固定,右对齐文本锚定 CANVAS_W - 8。 */}
+                <text
+                  x={CANVAS_W - 8}
+                  y={ROW_H / 2 + 6}
+                  fill="currentColor"
+                  fontSize={FONT_SIZE.BODY}
+                  fontFamily={FONT_MONO}
+                  textAnchor="end"
+                  pointerEvents="none"
+                  aria-hidden="true"
+                >
+                  {bar.pct.toFixed(1)}% · {fmtDuration(bar.fn.tottime)}
+                </text>
+                <title>{ariaText}</title>
+              </g>
+            )
+          })}
+        </svg>
+      </div>
+    </div>
+  )
+}
+
+export default memo(BarChart)
diff --git a/src/renderer/src/components/views/CumulativeBar.tsx b/src/renderer/src/components/views/CumulativeBar.tsx
new file mode 100644
index 0000000..cfee21e
--- /dev/null
+++ b/src/renderer/src/components/views/CumulativeBar.tsx
@@ -0,0 +1,280 @@
+/**
+ * 累计条形图 —— 按 cumtime 排序,bar 内分段显示 self 占比。
+ *
+ * 与 BarChart 的差别:
+ * - BarChart 按 tottime 排,每条 bar 长度 = 自耗时占比。
+ *   —— 适合回答"哪些函数自己最慢"。
+ * - CumulativeBar 按 cumtime 排,每条 bar 长度 = 累计耗时占比,bar 内部
+ *   左侧实色段 = 自耗时,右侧淡色段 = 被调用方耗时。
+ *   —— 适合回答"哪些函数累计最耗时"(常出现在顶层入口函数、IO wrapper、装饰器)。
+ *
+ * 分段语义:
+ *   bar 整体长度 ∝ cumtime
+ *   bar 内 [0, selfRatio] 用 colorByName 实色 → 自耗时
+ *   bar 内 [selfRatio, 1] 用 var(--surface-1) 淡色 → 被调用方耗时
+ *
+ * 注:不另起"callee segment"独立颜色,避免和 palette 撞;用 surface-1 既
+ * 表达"非数据"(被调用方归属其它函数)又复用现有 token。
+ */
+import { memo, useMemo, type KeyboardEvent } from 'react'
+import type { FunctionNode } from '../../../../shared/analysis'
+import { fmtDuration } from '../../utils/format'
+import { FOCUS, FONT_MONO, FONT_SIZE, RESTING, charsForWidth, colorByName, truncateName } from './chart-utils'
+import { useT } from '../../i18n'
+import { ORIGIN_COLOR, ORIGIN_LABEL_KEY, resolveOrigin } from '../../utils/origin'
+
+const TOP_N = 12
+const CANVAS_W = 920
+const ROW_H = 52
+const ROW_GAP = 10
+const NAME_W = 260
+const RIGHT_PAD = 140
+
+interface Props {
+  functions: readonly FunctionNode[]
+  /** 热点点击回调 —— 传整 FunctionNode 让 App.tsx 拿 file/origin 决定路由。 */
+  onSelect: (fn: FunctionNode) => void
+  focusName?: string
+}
+
+interface Bar {
+  fn: FunctionNode
+  cumtime: number
+  tottime: number
+  selfRatio: number
+  isFocus: boolean
+  origin: ReturnType<typeof resolveOrigin>
+}
+
+function CumulativeBar({ functions, onSelect, focusName }: Props) {
+  const t = useT()
+
+  // 分母用 cumtime 之和(而非 tottime 之和):cumtime 已含递归,更能反映"总耗时占比"。
+  // 有 0 cumtime 的函数(cProfile 极短调用)被直接剔除,避免排序占位但 bar 长度为 0。
+  const totalCum = useMemo(() => functions.reduce((s, f) => s + Math.max(0, f.cumtime), 0) || 1, [functions])
+
+  const visible = useMemo(
+    () =>
+      [...functions]
+        .filter((f) => f.cumtime > 0)
+        .sort((a, b) => b.cumtime - a.cumtime)
+        .slice(0, TOP_N),
+    [functions]
+  )
+  const hidden = functions.length - visible.length
+
+  const bars = useMemo<Bar[]>(
+    () =>
+      visible.map((fn) => ({
+        fn,
+        cumtime: fn.cumtime,
+        tottime: Math.min(fn.tottime, fn.cumtime), // 防 cumtime < tottime 数据 bug 导致 ratio > 1
+        selfRatio: fn.cumtime > 0 ? Math.min(1, fn.tottime / fn.cumtime) : 0,
+        isFocus: fn.name === focusName,
+        // origin 同 BarChart —— 同色系,跨视图扫表时颜色一致。
+        origin: resolveOrigin(fn)
+      })),
+    [visible, focusName]
+  )
+
+  if (bars.length === 0) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm text-fg-muted">{t('chart.empty')}</div>
+    )
+  }
+
+  const totalH = bars.length * (ROW_H + ROW_GAP) + ROW_GAP
+  // 左侧 origin 色点：r=5 + 1px stroke，主题切换/浅色背景下都能稳住视觉锚点；
+  // cx=12 留 10px 视觉呼吸空间，避免「贴墙感」。同 BarChart 的 dot 参数。
+  const ORIGIN_DOT_R = 5
+  const ORIGIN_DOT_CX = 12
+  const NAME_X = ORIGIN_DOT_CX + ORIGIN_DOT_R + 10
+  const BAR_X = NAME_W + 16
+  const BAR_W = CANVAS_W - BAR_X - RIGHT_PAD
+
+  return (
+    <div className="flex h-full flex-col p-3">
+      <div className="mb-2 text-sm text-fg-secondary" aria-live="polite">
+        {t('chart.cumulative.hint')}
+      </div>
+      {hidden > 0 && (
+        <div className="mb-2 text-sm text-fg-secondary" aria-live="polite">
+          {t('chart.truncated', { shown: TOP_N, hidden })}
+        </div>
+      )}
+      {/* 不内嵌 overflow-auto —— 外层右栏自带 overflow-y-auto 接管所有滚动。
+          SVG viewBox + preserveAspectRatio 自适应尺寸, 数据再多也直接交给外层滚动。 */}
+      <div className="flex-1">
+        <svg
+          width="100%"
+          viewBox={`0 0 ${CANVAS_W} ${totalH}`}
+          preserveAspectRatio="xMinYMin meet"
+          role="img"
+          aria-label={t('chart.cumulative.aria')}
+        >
+          {/* 图例:取第一根 bar 的颜色 —— colorByName('self') 会按哈希随机挑色,
+              与实际 bar 段颜色不一致,会让用户以为"自耗时 = 那个特定色"。
+              用 bars[0].fn.name 的色既对应用户能看到的色,又避免重复引入 palette 索引。
+              v4 字号升级:MICRO 12 → HINT 14,可读性提升。 */}
+          {(() => {
+            const legendFill = bars[0] ? colorByName(bars[0].fn.name) : colorByName('legend')
+            return (
+              <g aria-hidden="true">
+                <rect x={BAR_X} y={4} width={12} height={12} rx={2} fill="var(--surface-1)" />
+                <text
+                  x={BAR_X + 18}
+                  y={14}
+                  fill="currentColor"
+                  fontSize={FONT_SIZE.HINT}
+                  fontFamily={FONT_MONO}
+                  opacity={0.7}
+                >
+                  {t('chart.cumulative.cumSeg')}
+                </text>
+                <rect
+                  x={BAR_X + 140}
+                  y={4}
+                  width={12}
+                  height={12}
+                  rx={2}
+                  fill={legendFill}
+                  fillOpacity={0.85}
+                />
+                <text
+                  x={BAR_X + 158}
+                  y={14}
+                  fill="currentColor"
+                  fontSize={FONT_SIZE.HINT}
+                  fontFamily={FONT_MONO}
+                  opacity={0.7}
+                >
+                  {t('chart.cumulative.selfSeg')}
+                </text>
+              </g>
+            )
+          })()}
+          {bars.map((bar, i) => {
+            const y = i * (ROW_H + ROW_GAP) + ROW_GAP / 2
+            const fill = colorByName(bar.fn.name)
+            const barPx = Math.max(0, (bar.cumtime / totalCum) * BAR_W)
+            const selfPx = barPx * bar.selfRatio
+            const calleePx = barPx - selfPx
+            const onKeyDown = (e: KeyboardEvent<SVGGElement>) => {
+              if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault()
+                onSelect(bar.fn)
+              }
+            }
+            const ariaText = t('chart.cumulative.tile.aria', {
+              name: bar.fn.name,
+              origin: t(ORIGIN_LABEL_KEY[bar.origin]),
+              cum: fmtDuration(bar.cumtime),
+              self: fmtDuration(bar.tottime),
+              pct: ((bar.cumtime / totalCum) * 100).toFixed(1)
+            })
+            // 按 NAME 区实际可用宽度反算能放几个字 —— 自适应窗口。
+            const nameMax = charsForWidth(NAME_W - NAME_X - 6, FONT_SIZE.NAME)
+            return (
+              <g
+                key={bar.fn.id}
+                transform={`translate(0, ${y})`}
+                role="button"
+                tabIndex={0}
+                aria-label={ariaText}
+                aria-keyshortcuts="Enter Space"
+                onClick={() => onSelect(bar.fn)}
+                onKeyDown={onKeyDown}
+                className="chart-tile cursor-pointer"
+              >
+                {/* origin 色点(v4 起 r=5)—— 同 BarChart：行首圆点 + 半透明描边。
+                    跨主题视觉稳定。aria-hidden 不参与 SR。 */}
+                <circle
+                  cx={ORIGIN_DOT_CX}
+                  cy={ROW_H / 2}
+                  r={ORIGIN_DOT_R}
+                  fill={ORIGIN_COLOR[bar.origin]}
+                  stroke="rgba(0,0,0,0.25)"
+                  strokeWidth={1}
+                  aria-hidden="true"
+                />
+                <text
+                  x={NAME_X}
+                  y={ROW_H / 2 + 6}
+                  fill="currentColor"
+                  fontSize={FONT_SIZE.NAME}
+                  fontFamily={FONT_MONO}
+                  pointerEvents="none"
+                  aria-hidden="true"
+                >
+                  {truncateName(bar.fn.name, nameMax)}
+                </text>
+                {/* 背景轨 */}
+                <rect
+                  x={BAR_X}
+                  y={ROW_H * 0.3}
+                  width={BAR_W}
+                  height={ROW_H * 0.4}
+                  rx={3}
+                  fill="var(--surface-1)"
+                />
+                {/* callee 段(被调用方耗时) —— 浅色画在背景轨上,从右往左画,
+                    让 self 段(深色)从左开始连续。但更直观的画法是先画整个 cum 段
+                    再覆盖 self。两种都能读,选「分两段」语义更清晰。 */}
+                {calleePx > 0 && (
+                  <rect
+                    data-chart-shape
+                    x={BAR_X + selfPx}
+                    y={ROW_H * 0.3}
+                    width={calleePx}
+                    height={ROW_H * 0.4}
+                    rx={3}
+                    fill={fill}
+                    fillOpacity={0.35}
+                    stroke={bar.isFocus ? FOCUS.stroke : RESTING.stroke}
+                    strokeWidth={bar.isFocus ? FOCUS.strokeWidth : RESTING.strokeWidth}
+                  />
+                )}
+                {/* self 段(自耗时) —— 深色 */}
+                {selfPx > 0 && (
+                  <rect
+                    data-chart-shape
+                    x={BAR_X}
+                    y={ROW_H * 0.3}
+                    width={selfPx}
+                    height={ROW_H * 0.4}
+                    rx={3}
+                    fill={fill}
+                    fillOpacity={bar.isFocus ? FOCUS.fillOpacity : RESTING.fillOpacity}
+                    stroke={bar.isFocus ? FOCUS.stroke : RESTING.stroke}
+                    strokeWidth={bar.isFocus ? FOCUS.strokeWidth : RESTING.strokeWidth}
+                  />
+                )}
+                {/* 右对齐:累计耗时 + 该函数自耗时占比。百分号前显式标 "self" ——
+                    bar 长度已经是「累计占总时长比例」,这里的 % 不能再读成总占比,
+                    必须是「该函数自身时间 / 它总耗时」,否则和 bar 长度直接矛盾。 */}
+                <text
+                  x={CANVAS_W - 8}
+                  y={ROW_H / 2 + 6}
+                  fill="currentColor"
+                  fontSize={FONT_SIZE.BODY}
+                  fontFamily={FONT_MONO}
+                  textAnchor="end"
+                  pointerEvents="none"
+                  aria-hidden="true"
+                >
+                  {t('chart.cumulative.rightText', {
+                    pct: (bar.selfRatio * 100).toFixed(0),
+                    cum: fmtDuration(bar.cumtime)
+                  })}
+                </text>
+                <title>{ariaText}</title>
+              </g>
+            )
+          })}
+        </svg>
+      </div>
+    </div>
+  )
+}
+
+export default memo(CumulativeBar)
diff --git a/src/renderer/src/components/views/FlameGraph.tsx b/src/renderer/src/components/views/FlameGraph.tsx
new file mode 100644
index 0000000..b92d85c
--- /dev/null
+++ b/src/renderer/src/components/views/FlameGraph.tsx
@@ -0,0 +1,236 @@
+import { memo, useEffect, useMemo, useState, type KeyboardEvent } from 'react'
+import type { FlameNode } from '../../../../shared/analysis'
+import { TEXT_ON_DARK } from '../../utils/colors'
+import { fmtDuration } from '../../utils/format'
+import {
+  FOCUS,
+  FONT_MONO,
+  FONT_SIZE,
+  MAX_SIBLINGS,
+  RESTING,
+  charsForWidth,
+  colorByName,
+  countTruncatedSiblings,
+  truncateName
+} from './chart-utils'
+import { useT } from '../../i18n'
+
+interface Props {
+  flame: FlameNode | null
+  focusName?: string
+}
+
+const MAX_DEPTH = 3
+const CANVAS_W = 920
+const ROW_H = 48
+const ROW_GAP = 8
+
+interface Tile {
+  name: string
+  value: number
+  x: number
+  width: number
+  hasChildren: boolean
+  depth: number // 父节点仍可渲染；用真实 depth 而非 row index 更稳
+  /** 指向原 FlameNode — 直接访问 children，避免同名 sibling 在 byDepth Map 里互相覆盖 */
+  node: FlameNode
+}
+
+function FlameGraph({ flame, focusName }: Props) {
+  const t = useT()
+  const [focus, setFocus] = useState<string | null>(null)
+
+  // 关键：结果变化时清掉旧 focus，避免残留高亮
+  useEffect(() => {
+    setFocus(null)
+  }, [flame])
+
+  const rows = useMemo<Tile[][] | null>(() => {
+    if (!flame || flame.value <= 0 || flame.children.length === 0) return null
+    return layoutIcicle(flame, MAX_DEPTH, MAX_SIBLINGS)
+  }, [flame])
+
+  const focusKey = focus ?? focusName ?? null
+
+  if (!rows || !flame) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm text-fg-muted">{t('flame.empty')}</div>
+    )
+  }
+
+  const total = flame.value
+  const totalH = rows.length * (ROW_H + ROW_GAP) + ROW_GAP
+  // 任何一层有 sibling 被 MAX_SIBLINGS 截掉，就告知用户 ——
+  // 火焰图"看上去挤"不是用户错觉，是 layout 故意藏了一部分。
+  //
+  // v4 起按「每层单独统计」：之前只算 root.children 数量,深层被截完全静默。
+  // 现在递归扫一遍,统计所有被截的 depth 和各层丢失的 sibling 数,
+  // 一句聚合文案("在 N 层共截了 M 个兄弟")避免每层都贴一行 DOM。
+  const truncatedInfo = countTruncatedSiblings(flame, MAX_SIBLINGS)
+
+  return (
+    <div className="flex h-full flex-col p-3">
+      <div className="mb-2 flex items-center justify-between text-sm text-fg-secondary">
+        {/* note 提到 ResultsPanel section header,这里只留 reset(下钻态时显示) */}
+        {focus ? (
+          <button
+            onClick={() => setFocus(null)}
+            aria-label={t('flame.reset.aria')}
+            className="rounded px-1.5 py-0.5 text-fg-secondary hover:bg-surface-1 hover:text-fg focus:outline-none focus-visible:bg-surface-1"
+          >
+            {t('flame.reset')}
+          </button>
+        ) : (
+          <span aria-hidden="true">{t('chart.flame.hint')}</span>
+        )}
+      </div>
+      {/* 截断提示：v4 起把多层截断聚合为一句。
+          之前只显示 root 的截断量,深层有 sibling 被截会"看起来挤但毫无提示" —— 用户
+          误以为是数据问题。现在递归算所有深度,只显示有截断的层,避免每层都贴噪音。 */}
+      {truncatedInfo.totalHidden > 0 && (
+        <div className="mb-2 text-sm text-fg-secondary" aria-live="polite">
+          {truncatedInfo.depths.length === 1
+            ? t('chart.truncated', { shown: MAX_SIBLINGS, hidden: truncatedInfo.totalHidden })
+            : t('chart.flame.truncatedMulti', {
+                shown: MAX_SIBLINGS,
+                hidden: truncatedInfo.totalHidden,
+                depths: truncatedInfo.depths.length
+              })}
+        </div>
+      )}
+      {/* 不内嵌 overflow-auto —— 外层右栏自带 overflow-y-auto 接管所有滚动。
+          SVG viewBox + preserveAspectRatio 自适应尺寸, 深层调用栈再多也直接交给外层滚动。 */}
+      <div className="flex-1">
+        <svg
+          width="100%"
+          viewBox={`0 0 ${CANVAS_W} ${totalH}`}
+          preserveAspectRatio="xMinYMin meet"
+          role="img"
+          aria-label={t('flame.aria')}
+        >
+          {rows.map((row, rowDepth) =>
+            row.map((it, i) => {
+              // depth 0 是 root 的整条；tile 上的 depth 用 rowDepth+1 与父节点 children 深度对齐
+              const depth = rowDepth + 1
+              const isFocusMatch = it.name === focusKey
+              const isClickable = depth < MAX_DEPTH && it.hasChildren
+              const fill = rowDepth === 0 ? 'var(--surface-2)' : colorByName(it.name)
+              // 文字一律用浅色：tile 以 fillOpacity 0.7 合成在背景上，合成后的颜色
+              // 对近黑文字 (TEXT_ON_LIGHT) 只有 2.46–3.62，6 个色值里 4 个过不了
+              // 11px 小字所需的 4.5:1。浅色文字在整块 PALETTE 上都 >= 4.88（见 colors.ts）。
+              // 注：PALETTE 是品牌色，不随主题切换；只有 root 行 (rowDepth===0) 走
+              // `var(--surface-2)` 跟随主题 —— root 是"画布底色"，不是品牌色。
+              const textColor = TEXT_ON_DARK
+              const pct = ((it.value / total) * 100).toFixed(1)
+              // 用 fmtDuration 而非 toFixed(4) —— 与 BarChart/CumulativeBar/Treemap 保持一致
+              // (1.23s / 12.3ms / 123µs 自动选单位,屏幕阅读器读起来更自然)
+              const ariaText =
+                t('flame.tile.aria', {
+                  name: it.name,
+                  value: fmtDuration(it.value),
+                  pct
+                }) + (isClickable ? t('flame.tile.drill') : '')
+              const onKeyDown = (e: KeyboardEvent<SVGGElement>) => {
+                if (isClickable && (e.key === 'Enter' || e.key === ' ')) {
+                  e.preventDefault()
+                  setFocus(it.name)
+                }
+              }
+              // v4 起不再「width > 70 才显示 label」 —— 改用 charsForWidth 反算,
+              // 即使 tile 只有 28px 也能挤进 1-2 个字符(不会挤出一团墨块,反而是视觉
+              // 锚点)。name 放不下时返回空串 —— 这种情况不出 text 节点。
+              const labelChars = charsForWidth(it.width - 16, FONT_SIZE.BODY)
+              const showLabel = labelChars >= 1
+              return (
+                <g
+                  key={`${rowDepth}-${it.name}-${i}`}
+                  transform={`translate(0, ${rowDepth * (ROW_H + ROW_GAP) + ROW_GAP / 2})`}
+                  className={isClickable ? 'chart-tile cursor-pointer' : ''}
+                  onClick={() => isClickable && setFocus(it.name)}
+                  onKeyDown={onKeyDown}
+                  role={isClickable ? 'button' : undefined}
+                  tabIndex={isClickable ? 0 : undefined}
+                  aria-keyshortcuts={isClickable ? 'Enter Space' : undefined}
+                  aria-label={ariaText}
+                >
+                  <rect
+                    data-chart-shape
+                    x={it.x}
+                    y={0}
+                    width={Math.max(0, it.width - 1.5)}
+                    height={ROW_H}
+                    rx={3}
+                    fill={fill}
+                    fillOpacity={rowDepth === 0 ? 1 : isFocusMatch ? FOCUS.fillOpacity : RESTING.fillOpacity}
+                    stroke={isFocusMatch ? FOCUS.stroke : RESTING.stroke}
+                    strokeWidth={isFocusMatch ? FOCUS.strokeWidth : RESTING.strokeWidth}
+                  />
+                  {showLabel && (
+                    <text
+                      x={it.x + 8}
+                      y={ROW_H / 2 + 6}
+                      fill={textColor}
+                      fontSize={FONT_SIZE.BODY}
+                      fontFamily={FONT_MONO}
+                      pointerEvents="none"
+                      aria-hidden="true"
+                    >
+                      {truncateName(it.name, labelChars)}
+                    </text>
+                  )}
+                  <title>{ariaText}</title>
+                </g>
+              )
+            })
+          )}
+        </svg>
+      </div>
+    </div>
+  )
+}
+
+/** 单层 BFS：直接通过 Tile.node.children 找子节点，O(N) 一次扫描。 */
+function layoutIcicle(root: FlameNode, maxDepth: number, maxSiblings: number): Tile[][] {
+  const rootTile: Tile = {
+    name: root.name,
+    value: root.value,
+    x: 0,
+    width: CANVAS_W,
+    hasChildren: root.children.length > 0,
+    depth: 0,
+    node: root
+  }
+  const rows: Tile[][] = [[rootTile]]
+
+  for (let rowDepth = 0; rowDepth < maxDepth - 1; rowDepth++) {
+    const cur: Tile[] = []
+    const parents = rows[rowDepth]
+    for (const parent of parents) {
+      if (!parent.hasChildren) continue
+      // 防止极宽函数淹没横向布局 — 截断的同时给用户一个可见提示
+      const cs = parent.node.children.slice(0, maxSiblings)
+      if (cs.length === 0) continue
+      const sum = cs.reduce((s, c) => s + c.value, 0) || 1
+      let xCursor = parent.x
+      for (let i = 0; i < cs.length; i++) {
+        const c = cs[i]
+        const w = (c.value / sum) * parent.width
+        cur.push({
+          name: c.name,
+          value: c.value,
+          x: xCursor,
+          width: w,
+          hasChildren: c.children.length > 0,
+          depth: rowDepth + 1,
+          node: c
+        })
+        xCursor += w
+      }
+    }
+    if (cur.length === 0) break
+    rows.push(cur)
+  }
+  return rows
+}
+
+export default memo(FlameGraph)
diff --git a/src/renderer/src/components/views/HotspotTable.tsx b/src/renderer/src/components/views/HotspotTable.tsx
new file mode 100644
index 0000000..0c214c3
--- /dev/null
+++ b/src/renderer/src/components/views/HotspotTable.tsx
@@ -0,0 +1,549 @@
+import { memo, useEffect, useMemo, useState, type KeyboardEvent } from 'react'
+import type { FunctionNode } from '../../../../shared/analysis'
+import { fmtDuration, totalSelfTime } from '../../utils/format'
+import { colorByName } from './chart-utils'
+import { useT, type StringKey } from '../../i18n'
+import {
+  ORIGIN_ABBR_KEY,
+  ORIGIN_COLOR,
+  ORIGIN_LABEL_KEY,
+  type Origin,
+  groupModuleKeysByOrigin,
+  resolveOrigin
+} from '../../utils/origin'
+
+type SortKey = 'tottime' | 'cumtime' | 'ncalls' | 'percallTot' | 'name'
+
+/**
+ * 默认最多渲染多少行。
+ *
+ * 引擎侧 `functions` 是不设上限的 —— `--topn` 只决定哪些函数进逐行剖析，热点表拿到的是
+ * 用户脚本里所有被调用过的函数。几千行的模块能轻松产出几百个函数，全量渲染就是几百个
+ * <tr> × 6 个单元格，首次打开结果面板会明显卡一下。
+ * 不引入虚拟滚动（多一个依赖 + 破坏 Ctrl-F 和屏幕阅读器的表格语义），直接截断 + 展开按钮：
+ * 按自耗时排序时，200 行之后的函数本来就不是优化目标。
+ */
+const DEFAULT_ROW_CAP = 200
+
+interface Props {
+  functions: FunctionNode[]
+  /**
+   * 热点点击回调。传整 FunctionNode —— App.tsx 拿 file / origin 决定路由
+   * （user tab 高亮 vs 打开 stdlib / 第三方源码 tab）。
+   */
+  onSelect: (fn: FunctionNode) => void
+  selectedId?: string
+}
+
+/**
+ * 大量函数时，selectedFuncId 切换不应让整个表格重新排序/重画所有条形。
+ * React.memo + 稳定的 onSelect（外部已 useCallback）保证父组件 re-render 不连带。
+ */
+function HotspotTable({ functions, onSelect, selectedId }: Props) {
+  const t = useT()
+  const [sortKey, setSortKey] = useState<SortKey>('tottime')
+  const [asc, setAsc] = useState(false)
+  const [showAll, setShowAll] = useState(false)
+  // 模块过滤：null = 显示全部；否则只显示 module 等于该字符串的函数。
+  // scope=all 时函数表会塞进来几百行 stdlib / 第三方包；没有这个 filter，
+  // 用户要点开一行才能知道「这条 json 内部调用」属于哪个模块，分析价值大减。
+  const [moduleFilter, setModuleFilter] = useState<string | null>(null)
+  // v5 起:零耗时帧 + 测试代码 过滤都搬到 App 入口（utils/filterAnalysis），
+  // 一次性过滤后整个结果页（RunSummaryLite / 火焰图 / 柱图 / 旭日图 / 矩形树图 /
+  // 累积柱图 / 模块热图 / HotspotTable）都看到同一份干净数据。这里不再重复过滤，
+  // 想看完整原始数据直接点 ResultsPanel 右上角的「默认隐藏 N 帧」总开关。
+  // 模块切换 / 新 run 来了之后：
+  // 1) 新结果没有当前过滤的模块 → filtered = [] → 给用户显一个空表；
+  // 2) 新结果只有一个模块 → showModuleFilter=false → filter chip 消失，没有关通道能清除过滤。
+  // 从减少两种“过滤对不上当前数据”的状态，在 functions 变化时检查过滤模块是否还存在；不存在就备位到 null。
+  useEffect(() => {
+    if (moduleFilter === null) return
+    const has = functions.some((f) => f.module === moduleFilter)
+    if (!has) setModuleFilter(null)
+  }, [functions, moduleFilter])
+
+  // total 缓存：props.functions 引用变化才重算
+  const total = useMemo(() => totalSelfTime(functions) || 1, [functions])
+
+  // 模块计数：函数表里出现哪些模块、各有几个。
+  // 只在模块数 > 1 时显示 filter chips —— 单模块（scope=user 时）显示没意义。
+  const moduleCounts = useMemo(() => {
+    const m = new Map<string, number>()
+    for (const f of functions) {
+      m.set(f.module, (m.get(f.module) ?? 0) + 1)
+    }
+    return m
+  }, [functions])
+  const modules = useMemo(() => Array.from(moduleCounts.keys()), [moduleCounts])
+  const showModuleFilter = modules.length > 1
+
+  // 模块 → representative FunctionNode：每个模块用首条函数算 origin 给该模块归类。
+  // 用 first 而不是 random —— 同一模块下所有函数的 origin 是一致的（_classify_origin
+  // 决定于 file/module_name，不会因函数不同而变），任意挑一条都准；first 让结果稳定。
+  const fnByModule = useMemo(() => {
+    const m = new Map<string, FunctionNode>()
+    for (const f of functions) {
+      if (!m.has(f.module)) m.set(f.module, f)
+    }
+    return m
+  }, [functions])
+
+  // 模块 chip 按 origin 分组（v3 新增）—— scope=all 时十几/ 二十几个 stdlib 包
+  // 平铺成一长串扫起来累，按"用户代码 / 标准库 / 第三方包 / 内置 / 冻结 / 其它"
+  // 分桶后每桶内再排，用户一眼定位"自己的代码 / 想下钻的包"在哪。
+  const moduleGroups = useMemo(() => groupModuleKeysByOrigin(modules, fnByModule), [modules, fnByModule])
+
+  // 过滤后的函数集合：v5 起 App 入口已做完测试代码 + 零耗时帧过滤（见 utils/filterAnalysis），
+  // 这里只做模块过滤 —— scope=all 时用户想聚焦某个包内部时切 moduleFilter。
+  const filtered = useMemo(() => {
+    if (moduleFilter === null) return functions
+    return functions.filter((f) => f.module === moduleFilter)
+  }, [functions, moduleFilter])
+
+  const rows = useMemo(() => {
+    const copy = [...filtered]
+    copy.sort((a, b) => {
+      const av = a[sortKey]
+      const bv = b[sortKey]
+      const cmp =
+        typeof av === 'number' && typeof bv === 'number' ? av - bv : String(av).localeCompare(String(bv))
+      return asc ? cmp : -cmp
+    })
+    return copy
+  }, [filtered, sortKey, asc])
+
+  // 截断在排序之后：无论按哪一列排，用户看到的都是「当前排序下的前 200 名」，
+  // 而不是「自耗时前 200 名再按当前列排」—— 后者会让排序结果看起来是错的。
+  const visible = useMemo(() => (showAll ? rows : rows.slice(0, DEFAULT_ROW_CAP)), [rows, showAll])
+  const hiddenCount = rows.length - visible.length
+
+  // 切 module filter 时重置 showAll —— 上次展开 800 行切到 json 模块后只剩 30 行，
+  // 那条「展开全部」会让用户以为没切对。
+  const selectModule = (next: string | null): void => {
+    setModuleFilter(next)
+    setShowAll(false)
+  }
+
+  if (functions.length === 0) {
+    return <div className="px-4 py-8 text-center text-sm text-fg-muted">{t('hotspot.empty')}</div>
+  }
+
+  return (
+    <div className="flex flex-col">
+      {/*
+        模块 filter chips（按 origin 分组，v3 新增）：
+        - "全部 N" 永远在最前，是默认 chip
+        - 然后按 origin 分桶（user → third_party → stdlib → builtin → frozen → other）
+        - 每个桶一条 1px 分隔线 + 一行小标题（"Python 标准库 (5)"）作为视觉分组锚点
+        - 桶内模块 chip 沿用 colorByName 哈希保持跨视图同色
+        aria-pressed 表达选中态；aria-label 把当前可见 / 总数都带上，让 SR 用户
+        不必先切换就知道这次过滤掉了几行。
+      */}
+      {showModuleFilter && (
+        <div
+          role="group"
+          aria-label={t('hotspot.module.aria', {
+            label: moduleFilter ?? t('hotspot.module.allFilter', { total: functions.length }),
+            shown: visible.length,
+            total: rows.length
+          })}
+          className="flex flex-col gap-1 border-b border-border px-3 py-1.5"
+        >
+          {/* "全部 N" 单独一行 —— 概念上它代表「清除过滤」而不是某个 origin 桶，
+              跟下面分桶行视觉上分离更清晰（不然会和第一桶 origin 混读）。 */}
+          <div className="flex flex-wrap items-center gap-1 pt-0.5">
+            <ModuleChip
+              active={moduleFilter === null}
+              label={t('hotspot.module.allFilter', { total: functions.length })}
+              color={colorByName('all')}
+              onClick={() => selectModule(null)}
+            />
+          </div>
+          {moduleGroups.map((g) => (
+            <div key={g.origin} className="flex flex-wrap items-center gap-1">
+              {/*
+                桶标签 = 6×10 色块（与 ModuleHeatmap 标题条同款）+ origin 长名 + 计数。
+                色块承担「这条 section 是什么颜色」的视觉锚点，文字只负责读出名字，
+                —— 把颜色和文字分工，颜色更"重"，文字更"轻"，扫表时一眼定位。
+              */}
+              <span
+                className="mr-1.5 inline-flex items-center gap-1.5 font-mono text-2xs uppercase tracking-wider"
+                style={{ color: ORIGIN_COLOR[g.origin] }}
+                aria-hidden="true"
+              >
+                <span
+                  className="inline-block h-2.5 w-1.5 rounded-sm"
+                  style={{ backgroundColor: ORIGIN_COLOR[g.origin] }}
+                />
+                {t(ORIGIN_LABEL_KEY[g.origin])}
+                <span className="font-sans text-fg-muted">
+                  ({g.modules.reduce((s, m) => s + (moduleCounts.get(m) ?? 0), 0)})
+                </span>
+              </span>
+              {g.modules.map((m) => (
+                <ModuleChip
+                  key={m}
+                  active={moduleFilter === m}
+                  label={t('hotspot.module.filter', { module: m, count: moduleCounts.get(m) ?? 0 })}
+                  color={colorByName(m)}
+                  onClick={() => selectModule(m)}
+                />
+              ))}
+            </div>
+          ))}
+        </div>
+      )}
+      <div className="overflow-x-auto">
+        <table className="w-full border-collapse text-sm">
+          <thead>
+            <tr className="border-b border-border text-left text-2xs uppercase tracking-wider text-fg-muted">
+              <th scope="col" className="w-3" aria-hidden="true" />
+              <Header
+                labelKey="hotspot.col.function"
+                sortKey="name"
+                current={sortKey}
+                asc={asc}
+                onSort={setSortKey}
+                setAsc={setAsc}
+              />
+              {/* 初始默认按 tottime 降序 —— 用 Header 而不是普通 <th>，让 aria-sort 同步暴露给 SR。
+                  之前写成普通 <th>，屏幕阅读器无法知道当前排序列。 */}
+              <Header
+                labelKey="hotspot.col.tottime"
+                sortKey="tottime"
+                current={sortKey}
+                asc={asc}
+                onSort={setSortKey}
+                setAsc={setAsc}
+                className="w-1/3"
+              />
+              <Header
+                labelKey="hotspot.col.cumtime"
+                sortKey="cumtime"
+                current={sortKey}
+                asc={asc}
+                onSort={setSortKey}
+                setAsc={setAsc}
+                align="right"
+              />
+              <Header
+                labelKey="hotspot.col.calls"
+                sortKey="ncalls"
+                current={sortKey}
+                asc={asc}
+                onSort={setSortKey}
+                setAsc={setAsc}
+                align="right"
+              />
+              <Header
+                labelKey="hotspot.col.percall"
+                sortKey="percallTot"
+                current={sortKey}
+                asc={asc}
+                onSort={setSortKey}
+                setAsc={setAsc}
+                align="right"
+              />
+            </tr>
+          </thead>
+          <tbody>
+            {visible.length === 0 && moduleFilter !== null ? (
+              // 模块过滤把全部行数过滤掉了 —— 给一行明确的占位 + 回到「全部」的快捷链接，
+              // 比沉默的空白表友好。colSpan 对齐表头 6 列（含最左侧 3px 装饰列）。
+              <tr>
+                <td colSpan={6} className="px-3 py-8 text-center text-sm text-fg-muted">
+                  {t('hotspot.emptyFiltered', {
+                    total: functions.length
+                  })}
+                  <button
+                    type="button"
+                    onClick={() => selectModule(null)}
+                    className="ml-2 cursor-pointer text-accent underline-offset-2 hover:underline focus:outline-none focus-visible:underline"
+                  >
+                    {t('hotspot.module.allFilter', { total: functions.length })}
+                  </button>
+                </td>
+              </tr>
+            ) : (
+              visible.map((f) => (
+                <Row
+                  key={f.id}
+                  fn={f}
+                  total={total}
+                  isSelected={selectedId === f.id}
+                  origin={resolveOrigin(f)}
+                  onSelect={onSelect}
+                />
+              ))
+            )}
+          </tbody>
+        </table>
+        {/*
+          绝不静默截断：藏了行就必须说藏了几行、能怎么展开。
+          aria-live 让屏幕阅读器在展开后播报行数变化。
+          v5 起:测试代码 + 零耗时帧的过滤通知搬到 ResultsPanel 顶上的总开关,
+          这里只剩「行数被截断」的提示。
+        */}
+        {hiddenCount > 0 && (
+          <div className="border-t border-border px-3 py-2 text-xs text-fg-muted" aria-live="polite">
+            {t('hotspot.truncated', { visible: visible.length, hidden: hiddenCount })}
+            <button
+              type="button"
+              onClick={() => setShowAll(true)}
+              className="ml-2 cursor-pointer text-accent underline-offset-2 hover:underline focus:outline-none focus-visible:underline"
+            >
+              {t('hotspot.expand', { total: rows.length })}
+            </button>
+          </div>
+        )}
+        {showAll && rows.length > DEFAULT_ROW_CAP && (
+          <div className="border-t border-border px-3 py-2 text-xs text-fg-muted" aria-live="polite">
+            {t('hotspot.totals', { total: rows.length })}
+            <button
+              type="button"
+              onClick={() => setShowAll(false)}
+              className="ml-2 cursor-pointer text-accent underline-offset-2 hover:underline focus:outline-none focus-visible:underline"
+            >
+              {t('hotspot.collapse', { cap: DEFAULT_ROW_CAP })}
+            </button>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export default memo(HotspotTable)
+
+/**
+ * 模块 filter chip：scope=all 才出现。
+ * 色块用 colorByName 哈希到 PALETTE —— 同一个模块在不同 chip / 表格行 / 火焰图里
+ * 都是同一个颜色，跨视图保持视觉锚点。
+ * background 用 hex + 26 (≈15% alpha) 营造"染色"感而非"实心块"。
+ */
+function ModuleChip({
+  active,
+  label,
+  color,
+  onClick
+}: {
+  active: boolean
+  label: string
+  color: string
+  onClick: () => void
+}): JSX.Element {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-pressed={active}
+      className={`inline-flex items-center rounded-full px-2.5 py-0.5 font-mono text-2xs uppercase tracking-wide transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent ${
+        active ? 'text-fg' : 'text-fg-secondary hover:text-fg'
+      }`}
+      style={{
+        backgroundColor: active ? `${color}33` : `${color}1a`,
+        borderColor: active ? color : 'transparent',
+        borderWidth: 1
+      }}
+    >
+      {label}
+    </button>
+  )
+}
+
+/** 行单独 memo — 同一函数 id 在不切换选中时完全跳过重渲染。 */
+const Row = memo(function Row({
+  fn,
+  total,
+  isSelected,
+  origin,
+  onSelect
+}: {
+  fn: FunctionNode
+  total: number
+  isSelected: boolean
+  origin: Origin
+  onSelect: (fn: FunctionNode) => void
+}) {
+  const t = useT()
+  const pct = (100 * fn.tottime) / total
+  // 之前类型标的是 HTMLTableRowElement — 当时 onKeyDown 挂在 <tr> 上。
+  // 后来把点击/键盘搬到了 name cell 里的 <button>(让 <tr> 保持真实 tr + aria-selected),
+  // 类型没跟上,改成 HTMLButtonElement 匹配现绑定。
+  const onKeyDown = (e: KeyboardEvent<HTMLButtonElement>) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      onSelect(fn)
+    }
+  }
+  const originLabel = t(ORIGIN_LABEL_KEY[origin])
+  const ariaText = isSelected
+    ? t('hotspot.row.ariaSelected', {
+        name: fn.name,
+        line: fn.line,
+        tottime: fmtDuration(fn.tottime),
+        calls: fn.ncalls,
+        // SR 视角：把 origin 拼进 aria-label，让用户不用展开行就知道「这条帧是哪个来源」。
+        origin: originLabel
+      })
+    : t('hotspot.row.aria', {
+        name: fn.name,
+        line: fn.line,
+        tottime: fmtDuration(fn.tottime),
+        calls: fn.ncalls,
+        origin: originLabel
+      })
+  return (
+    // keep implicit role="row" so SR reads cells row-by-row. previous
+    // role="button" override dropped the rest of the cells out of the
+    // table a11y tree (SR heard "button" but no row context). click +
+    // keyboard activation live on a <button> inside the name cell, so
+    // the row stays a real <tr> with selectable semantics (aria-selected).
+    <tr
+      aria-selected={isSelected}
+      className={`group border-b border-border/40 transition-colors ${
+        isSelected ? 'bg-surface-2' : 'hover:bg-surface-1'
+      }`}
+    >
+      {/* Signature: 3px left accent bar on selected row */}
+      <td className="relative p-0" aria-hidden="true">
+        <div
+          className={`absolute inset-y-0 left-0 w-[3px] ${isSelected ? 'bg-accent' : 'bg-transparent group-hover:bg-border-strong'}`}
+        />
+      </td>
+      <td className="relative p-0">
+        {/* 模块 chip + 函数名 + 行号：<button> 包整格，
+            承载点击和键盘激活（Enter / Space）。
+            表格其它列是纯数据格 —— SR 按 td 朗诵数值，不被按钮语义干扰。 */}
+        <button
+          type="button"
+          onClick={() => onSelect(fn)}
+          onKeyDown={onKeyDown}
+          aria-label={ariaText}
+          // 用 aria-pressed 而不是 aria-current：当前按钮语义是「这条帧已被选中下钻」，
+          // pressed 比 current 更准（current 用于导航/位置上下文）。aria-selected 在父 <tr>
+          // 上保留 —— 两边语义不重叠。
+          aria-pressed={isSelected}
+          className="block w-full cursor-pointer px-3 py-2 pr-3 text-left focus:outline-none focus-visible:bg-surface-1"
+        >
+          <div className="mb-1 flex items-center gap-1.5">
+            {/*
+              origin 徽章（v3 新增）：1px 圆点 + 1-2 字母短码（S/3P/U/B/F/?），按 origin
+              着色。origin 信息在 module chip 之外再叠一次 —— 用户扫表时不需要先过滤
+              就能认出「这条 json 帧是 stdlib」，跨多模块的下钻体验更顺。
+              aria-hidden 不参与 SR —— origin 已并入父 button 的 aria-label。
+            */}
+            <span
+              className="inline-flex items-center gap-1 rounded px-1.5 py-0.5 font-mono text-2xs uppercase tracking-wide"
+              style={{
+                color: ORIGIN_COLOR[origin],
+                backgroundColor: `${ORIGIN_COLOR[origin]}1a`
+              }}
+              aria-hidden="true"
+              title={originLabel}
+            >
+              <span
+                className="inline-block h-1.5 w-1.5 rounded-full"
+                style={{ backgroundColor: ORIGIN_COLOR[origin] }}
+              />
+              {t(ORIGIN_ABBR_KEY[origin])}
+            </span>
+            {fn.module && (
+              <span
+                className="inline-block rounded px-1.5 py-0.5 font-mono text-2xs uppercase tracking-wide text-fg-secondary"
+                style={{ backgroundColor: `${colorByName(fn.module)}1a` }}
+                aria-hidden="true"
+              >
+                {fn.module}
+              </span>
+            )}
+          </div>
+          <span className="font-mono text-fg">{fn.name}</span>
+          <div className="font-mono text-xs text-fg-muted">{t('hotspot.col.line', { line: fn.line })}</div>
+        </button>
+      </td>
+      <td className="w-1/3 py-2 pr-3">
+        <div className="flex items-center gap-2">
+          {/* Restrained bar — dataviz rule: 2px surface gap to next */}
+          <div className="relative h-1.5 flex-1 overflow-hidden rounded-full bg-surface-1">
+            <div
+              className="absolute inset-y-0 left-0 rounded-full bg-accent/70"
+              style={{ width: `${Math.min(100, pct)}%` }}
+            />
+          </div>
+          <span className="w-16 text-right font-mono text-xs tabular text-fg-secondary">
+            {/* 跟 BarChart / FlameGraph / Treemap / Sunburst 四图统一用 toFixed(1) ——
+                之前 0 位小数会让小耗时函数在表格里和柱状图里出现不一致（表格写「2%」、柱状图写「2.3%」），
+                同函数不同视图对不上。 */}
+            {pct.toFixed(1)}% · {fmtDuration(fn.tottime)}
+          </span>
+        </div>
+      </td>
+      <td className="py-2 pr-3 text-right font-mono tabular text-fg-secondary">{fmtDuration(fn.cumtime)}</td>
+      <td className="py-2 pr-3 text-right font-mono tabular text-fg-secondary">{fn.ncalls}</td>
+      <td className="py-2 pr-3 text-right font-mono tabular text-fg-muted">{fmtDuration(fn.percallTot)}</td>
+    </tr>
+  )
+})
+
+/** 表头：键盘可排序；aria-sort 同步。 */
+function Header({
+  labelKey,
+  sortKey,
+  current,
+  asc,
+  onSort,
+  setAsc,
+  align = 'left',
+  className = ''
+}: {
+  labelKey: StringKey
+  sortKey: SortKey
+  current: SortKey
+  asc: boolean
+  onSort: (k: SortKey) => void
+  setAsc: (b: boolean) => void
+  align?: 'left' | 'right'
+  className?: string
+}) {
+  const t = useT()
+  const isActive = current === sortKey
+  const label = t(labelKey)
+  const onKeyDown = (e: KeyboardEvent<HTMLButtonElement>) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      toggleSort()
+    }
+  }
+  const toggleSort = () => {
+    if (current === sortKey) setAsc(!asc)
+    else {
+      onSort(sortKey)
+      setAsc(false)
+    }
+  }
+  return (
+    <th
+      aria-sort={isActive ? (asc ? 'ascending' : 'descending') : 'none'}
+      scope="col"
+      className={`p-0 font-medium ${className} ${align === 'right' ? 'text-right' : 'text-left'}`}
+    >
+      {/*
+        之前给 <th> 加 role="button" 会丢掉隐式 columnheader 语义，SR 读成 "button" 而非
+        "column header"。把交互放到内嵌的 <button type="button"> 上，<th> 保持列头语义。
+      */}
+      <button
+        type="button"
+        onClick={toggleSort}
+        onKeyDown={onKeyDown}
+        aria-label={t('hotspot.sortBy', { label })}
+        className={`flex w-full cursor-pointer select-none items-center px-3 py-2 transition-colors focus:outline-none focus-visible:bg-surface-1 ${
+          align === 'right' ? 'justify-end' : 'justify-start'
+        } ${isActive ? 'text-fg' : 'hover:text-fg-secondary'}`}
+      >
+        {label}
+        {isActive ? <span className="ml-1 text-accent">{asc ? '↑' : '↓'}</span> : null}
+      </button>
+    </th>
+  )
+}
diff --git a/src/renderer/src/components/views/ModuleHeatmap.tsx b/src/renderer/src/components/views/ModuleHeatmap.tsx
new file mode 100644
index 0000000..17b3e40
--- /dev/null
+++ b/src/renderer/src/components/views/ModuleHeatmap.tsx
@@ -0,0 +1,371 @@
+/**
+ * 模块热力图 —— 按 module 聚合的"行 × 函数 cell"布局。
+ *
+ * 布局:
+ * - 每个 module 占一行
+ * - 行内 cell 横向排列,宽度 ∝ 该函数 self-time 占模块总和的比例
+ * - cell 颜色用 colorByName(name):同函数在 4 图 + 这里都同色
+ * - 行首标 module 名 + 函数数
+ *
+ * 使用场景:
+ * - scope=user:只有一个模块("<user>"),没有横向比较价值 → 显示空态文案引导
+ *   用户切到 scope=all(或直接由 EmptyState 隐藏这一视图)
+ * - scope=all:json / numpy / time / <user> / <frozen> 等模块同框,一眼看出
+ *   "json.loads 吃掉 30% 总时间"或"time.sleep 占比最高"。
+ *
+ * v3 起按 origin(用户代码 / 第三方包 / 标准库 / ...)分桶渲染,每桶头一个
+ * 模块行前画 origin 标题 —— 跨多模块时定位「我的代码 vs 库」更直接。
+ *
+ * 截断:每个模块最多展示 TOP_N_PER_MODULE 个函数,超出必显式提示;
+ * 模块本身超过 MAX_MODULES 也截断 + 提示。
+ *
+ * v4 字号升级：13-15px → 14-16px, 窄 cell 也按可用宽度反算可放字符数,
+ * 永不静默藏标签。
+ */
+import { memo, useMemo, type KeyboardEvent } from 'react'
+import type { FunctionNode } from '../../../../shared/analysis'
+import { TEXT_ON_DARK } from '../../utils/colors'
+import { fmtDuration, totalSelfTime } from '../../utils/format'
+import { FOCUS, FONT_MONO, FONT_SIZE, RESTING, charsForWidth, colorByName, truncateName } from './chart-utils'
+import { useT } from '../../i18n'
+import {
+  ORIGIN_ABBR_KEY,
+  ORIGIN_COLOR,
+  ORIGIN_LABEL_KEY,
+  ORIGIN_ORDER,
+  resolveOrigin,
+  type Origin as OriginType
+} from '../../utils/origin'
+
+const CANVAS_W = 920
+const ROW_H = 64
+const ROW_GAP = 10
+/** 行首模块名标签宽度。Cascadia Code 16px ≈ 10px/字 → ~13 字, 留余到 150px。 */
+const LABEL_W = 150
+/** 行末「more」提示位宽度 —— 给「+N more」文字让出空间。 */
+const MORE_W = 90
+const CELL_GAP = 4
+/** 每个模块最多展开几个函数 cell。多了挤,且热度对比下降。 */
+const TOP_N_PER_MODULE = 6
+/** 模块行数上限 —— 防止 scope=all 时十几个 stdlib 把画布撑爆。 */
+const MAX_MODULES = 10
+/** Cell 最小可见宽度 —— 太窄的 cell 没有信息量。 */
+const MIN_CELL_W = 24
+/** Origin 标题小条高度（左侧 4px 色块 + 文字），避免它跟模块行撞。 */
+const ORIGIN_HEADER_H = 22
+
+interface Props {
+  functions: readonly FunctionNode[]
+  /** 热点点击回调 —— 传整 FunctionNode 让 App.tsx 拿 file/origin 决定路由。 */
+  onSelect: (fn: FunctionNode) => void
+  focusName?: string
+}
+
+interface ModuleRow {
+  module: string
+  origin: OriginType
+  total: number
+  cells: Array<{ fn: FunctionNode; width: number; isFocus: boolean }>
+  hiddenInRow: number
+}
+
+function ModuleHeatmap({ functions, onSelect, focusName }: Props) {
+  const t = useT()
+
+  const moduleStats = useMemo(() => {
+    const byModule = new Map<string, { total: number; fns: FunctionNode[] }>()
+    for (const f of functions) {
+      // 过滤 tottime=0 的函数 —— 它们通常是 cProfile 极短调用(< 1µs 量化到 0),
+      // 不该和真实耗时共享一个 MIN_CELL_W=24 的格子,会让用户误以为该函数占了空间。
+      // 与 CumulativeBar 过滤 cumtime=0 同款策略。
+      if (f.tottime <= 0) continue
+      let e = byModule.get(f.module)
+      if (!e) {
+        e = { total: 0, fns: [] }
+        byModule.set(f.module, e)
+      }
+      e.total += f.tottime
+      e.fns.push(f)
+    }
+    // 排序:模块总耗时降序
+    return Array.from(byModule.entries())
+      .map(([module, v]) => ({ module, ...v }))
+      .sort((a, b) => b.total - a.total)
+  }, [functions])
+
+  const totalAll = useMemo(() => totalSelfTime(functions) || 1, [functions])
+
+  // 按 module 排序后截到 MAX_MODULES，再按 origin 分桶（v3 新增）。
+  // 桶内保留 tottime 降序 —— 视觉上「本 origin 里最贵的包排最前」。
+  const groupedRows = useMemo<Array<{ origin: OriginType; rows: ModuleRow[] }>>(() => {
+    const top = moduleStats.slice(0, MAX_MODULES)
+    const moduleOrigin = new Map<string, OriginType>()
+    for (const m of top) {
+      const sample = m.fns[0]
+      moduleOrigin.set(m.module, sample ? resolveOrigin(sample) : 'other')
+    }
+    const buckets = new Map<OriginType, ModuleRow[]>()
+    for (const m of top) {
+      const o = moduleOrigin.get(m.module) ?? 'other'
+      const cells = [...m.fns]
+        .sort((a, b) => b.tottime - a.tottime)
+        .slice(0, TOP_N_PER_MODULE)
+        .map((fn) => ({
+          fn,
+          width: Math.max(MIN_CELL_W, (fn.tottime / m.total) * (CANVAS_W - LABEL_W - MORE_W - CELL_GAP)),
+          isFocus: fn.name === focusName
+        }))
+      const row: ModuleRow = {
+        module: m.module,
+        origin: o,
+        total: m.total,
+        cells,
+        hiddenInRow: m.fns.length - cells.length
+      }
+      let b = buckets.get(o)
+      if (!b) {
+        b = []
+        buckets.set(o, b)
+      }
+      b.push(row)
+    }
+    // 桶按 ORIGIN_ORDER 排（user → third_party → stdlib → ...）
+    return ORIGIN_ORDER.filter((o) => buckets.has(o)).map((origin) => ({
+      origin,
+      rows: buckets.get(origin) ?? []
+    }))
+  }, [moduleStats, focusName])
+
+  const truncatedModules = moduleStats.length > MAX_MODULES ? moduleStats.length - MAX_MODULES : 0
+
+  if (moduleStats.length === 0) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm text-fg-muted">{t('chart.empty')}</div>
+    )
+  }
+
+  if (moduleStats.length === 1) {
+    return (
+      <div className="flex h-full items-center justify-center px-6 text-center text-sm text-fg-muted">
+        {t('chart.heatmap.empty')}
+      </div>
+    )
+  }
+
+  // 行 y 偏移：origin header 占 ORIGIN_HEADER_H 高，紧跟每个 ROW_H + ROW_GAP。
+  let yCursor = ORIGIN_HEADER_H + ROW_GAP / 2
+  const rowY = new Map<string, number>()
+  for (const g of groupedRows) {
+    yCursor += ORIGIN_HEADER_H // header 自身高度
+    for (const r of g.rows) {
+      rowY.set(r.module, yCursor)
+      yCursor += ROW_H + ROW_GAP
+    }
+  }
+  // 重新计算 SVG 高度 —— 直接从 yCursor 推：最后一行底 + 半 gap 余量。
+  // 之前用 `ORIGIN_HEADER_H + moduleRowCount * (ROW_H + ROW_GAP) + ROW_GAP` 硬算,
+  // 不算首个 group 的双重 header 预留 (yCursor 起始值 + loop 内 +=),结果差 ~7px,
+  // 多行时最后一行 cell 底部被 viewBox 裁掉一截。
+  const totalH = yCursor + ROW_GAP / 2
+
+  return (
+    <div className="flex h-full flex-col p-3">
+      <div className="mb-2 text-sm text-fg-secondary" aria-live="polite">
+        {t('chart.heatmap.hint')}
+      </div>
+      {truncatedModules > 0 && (
+        <div className="mb-2 text-sm text-fg-secondary" aria-live="polite">
+          {t('chart.truncated', { shown: MAX_MODULES, hidden: truncatedModules })}
+        </div>
+      )}
+      {/* 不内嵌 overflow-auto —— 外层右栏自带 overflow-y-auto 接管所有滚动。
+          模块多时 SVG viewBox 自动按高度缩放, 多余高度直接交给外层滚动。 */}
+      <div className="flex-1">
+        <svg
+          width="100%"
+          viewBox={`0 0 ${CANVAS_W} ${totalH}`}
+          preserveAspectRatio="xMinYMin meet"
+          role="img"
+          aria-label={t('chart.heatmap.aria')}
+        >
+          {groupedRows.map((g) => {
+            const firstY = rowY.get(g.rows[0].module) ?? 0
+            const headerY = firstY - ORIGIN_HEADER_H + 4
+            return (
+              <g key={g.origin}>
+                {/* origin 标题条(v3 新增)：左侧 6px 色块 + 短码/长标签。
+                    色块加粗到 6px + rx=2 让 section 边界更明显,scope=all 时一眼
+                    区分"我的代码 / 第三方 / 标准库"。色块 y 对齐文字字形中央,
+                    不再悬空于标题条顶部。v4 字号 11 → 13 配合更大 ORIGIN_HEADER_H。 */}
+                <g aria-hidden="true">
+                  <rect
+                    x={0}
+                    y={headerY + 4}
+                    width={6}
+                    height={ORIGIN_HEADER_H - 12}
+                    rx={2}
+                    fill={ORIGIN_COLOR[g.origin]}
+                  />
+                  <text
+                    x={16}
+                    y={headerY + 14}
+                    fill={ORIGIN_COLOR[g.origin]}
+                    fontSize={FONT_SIZE.HINT}
+                    fontFamily={FONT_MONO}
+                    pointerEvents="none"
+                    style={{ letterSpacing: '0.06em', textTransform: 'uppercase' }}
+                  >
+                    {t(ORIGIN_ABBR_KEY[g.origin])} · {t(ORIGIN_LABEL_KEY[g.origin])}
+                  </text>
+                </g>
+                {g.rows.map((row) => (
+                  <ModuleHeatmapRow
+                    key={row.module}
+                    row={row}
+                    y={rowY.get(row.module) ?? 0}
+                    totalAll={totalAll}
+                    onSelect={onSelect}
+                  />
+                ))}
+              </g>
+            )
+          })}
+        </svg>
+      </div>
+    </div>
+  )
+}
+
+// 单行渲染抽出来 —— 让父组件 groupedRows.map 不至于读不下去。
+const ModuleHeatmapRow = memo(function ModuleHeatmapRow({
+  row,
+  y,
+  totalAll,
+  onSelect
+}: {
+  row: ModuleRow
+  y: number
+  totalAll: number
+  onSelect: (fn: FunctionNode) => void
+}) {
+  const t = useT()
+  const moduleColor = colorByName(row.module)
+  let cursor = LABEL_W
+  return (
+    <g>
+      {/* 行首:模块色点 + 模块名 + (函数数)。
+          v4 字号 15 → 17(BODY+1), 标签宽度 LABEL_W 也加到 150。 */}
+      <rect x={0} y={y + ROW_H * 0.25} width={12} height={ROW_H * 0.5} rx={2} fill={moduleColor} />
+      <text
+        x={20}
+        y={y + ROW_H / 2 + 6}
+        fill="currentColor"
+        fontSize={FONT_SIZE.BODY}
+        fontFamily={FONT_MONO}
+        pointerEvents="none"
+        aria-hidden="true"
+      >
+        {t('chart.heatmap.moduleLabel', {
+          module: truncateName(row.module, 14),
+          count: row.cells.length + row.hiddenInRow
+        })}
+      </text>
+      {/* 行底分割线 —— 让多行模块视觉上分组 */}
+      <line
+        x1={0}
+        y1={y + ROW_H + ROW_GAP / 2 - 1}
+        x2={CANVAS_W}
+        y2={y + ROW_H + ROW_GAP / 2 - 1}
+        stroke="var(--border)"
+        strokeWidth={0.5}
+        strokeOpacity={0.5}
+      />
+      {/* cells */}
+      {row.cells.map((cell) => {
+        const x = cursor
+        const cy = y + ROW_H * 0.15
+        const ch = ROW_H * 0.7
+        const w = cell.width
+        cursor = x + w + CELL_GAP
+        const fill = colorByName(cell.fn.name)
+        const onKeyDown = (e: KeyboardEvent<SVGGElement>) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault()
+            onSelect(cell.fn)
+          }
+        }
+        const ariaText = t('chart.heatmap.tile.aria', {
+          module: row.module,
+          name: cell.fn.name,
+          value: fmtDuration(cell.fn.tottime),
+          pct: ((cell.fn.tottime / totalAll) * 100).toFixed(1)
+        })
+        // v4 起不再「w >= 60 才显示 label」 —— 改用 charsForWidth 反算
+        // 14px 字号下能放几个字, 永远不静默吞掉函数名(哪怕只能塞 1-2 字也画,
+        // 作为视觉锚点比完全空白更有信息量)。
+        const labelChars = charsForWidth(w - 12, FONT_SIZE.HINT)
+        const showLabel = labelChars >= 1
+        return (
+          <g
+            key={cell.fn.id}
+            transform={`translate(${x}, ${cy})`}
+            role="button"
+            tabIndex={0}
+            aria-label={ariaText}
+            aria-keyshortcuts="Enter Space"
+            onClick={() => onSelect(cell.fn)}
+            onKeyDown={onKeyDown}
+            className="chart-tile cursor-pointer"
+          >
+            <rect
+              data-chart-shape
+              x={0}
+              y={0}
+              width={Math.max(0, w - 1)}
+              height={ch}
+              rx={3}
+              fill={fill}
+              fillOpacity={cell.isFocus ? FOCUS.fillOpacity : RESTING.fillOpacity}
+              stroke={cell.isFocus ? FOCUS.stroke : RESTING.stroke}
+              strokeWidth={cell.isFocus ? FOCUS.strokeWidth : RESTING.strokeWidth}
+            />
+            {showLabel && (
+              <text
+                x={6}
+                y={ch / 2 + 5}
+                fill={TEXT_ON_DARK}
+                fontSize={FONT_SIZE.HINT}
+                fontFamily={FONT_MONO}
+                pointerEvents="none"
+                aria-hidden="true"
+              >
+                {truncateName(cell.fn.name, labelChars)}
+              </text>
+            )}
+            <title>{ariaText}</title>
+          </g>
+        )
+      })}
+      {/* 行尾「+N more」:若模块被 TOP_N_PER_MODULE 截了,显示藏了几个。
+          v4 字号 13 → 14 让 "+N more" 更醒目。 */}
+      {row.hiddenInRow > 0 && (
+        <text
+          x={CANVAS_W - 8}
+          y={y + ROW_H / 2 + 6}
+          fill="currentColor"
+          fontSize={FONT_SIZE.HINT}
+          fontFamily={FONT_MONO}
+          textAnchor="end"
+          pointerEvents="none"
+          opacity={0.6}
+          aria-hidden="true"
+        >
+          {t('chart.heatmap.more', { count: row.hiddenInRow })}
+        </text>
+      )}
+    </g>
+  )
+})
+
+// ModuleHeatmap 单独引用 —— 文件尾集中导出一个 const,避免被 React Fast Refresh / dead-code 误删
+export default memo(ModuleHeatmap)
diff --git a/src/renderer/src/components/views/Sunburst.tsx b/src/renderer/src/components/views/Sunburst.tsx
new file mode 100644
index 0000000..b944947
--- /dev/null
+++ b/src/renderer/src/components/views/Sunburst.tsx
@@ -0,0 +1,304 @@
+import { memo, useMemo, type KeyboardEvent } from 'react'
+import type { FlameNode, FunctionNode } from '../../../../shared/analysis'
+import { ACCENT_DEEP, TEXT_ON_DARK } from '../../utils/colors'
+import { fmtDuration } from '../../utils/format'
+import {
+  FOCUS,
+  FONT_MONO,
+  FONT_SIZE,
+  MAX_SIBLINGS,
+  RESTING,
+  charsForWidth,
+  colorByName,
+  countTruncatedSiblings,
+  indexFunctionsByName,
+  truncateName
+} from './chart-utils'
+import { useT } from '../../i18n'
+
+/**
+ * 旭日图 —— Firefox Profiler 等层级径向布局的同款可视化。
+ *
+ * 结构：
+ * - 中心 = 根节点
+ * - 每向外一圈 = 多一层深度
+ * - 弧长 = 节点自耗时占总值比例
+ *
+ * 深度上限 4 圈（中心 0 不算），比 FlameGraph / Treemap 多一层 —— 旭日图的圈
+ * 视觉密度天然更低，再多就糊。
+ *
+ * 截断：每层 sibling 上限 24（沿用 MAX_SIBLINGS），超出必显式提示。
+ *
+ * v4 升级：
+ * - SIZE 520 → 600, RING_W 56 → 64 (容纳更大字号 / 更宽弧)
+ * - 内圈也开始画 label (depth < MAX_DEPTH, 字号小一档) —— 之前完全空, 用户
+ *   只看外圈感觉不到层级
+ * - 加图例 (色块 = 函数 colorByName 色, 解释"颜色同函数")
+ */
+const MAX_DEPTH = 4
+const SIZE = 600
+const CENTER = SIZE / 2
+const RING_W = 64
+/** 中心留出内圈空间给直接子节点显示 —— root 是占位概念,视觉上不该吃一整圈。 */
+const INNER_R = RING_W * 0.55
+
+interface Props {
+  flame: FlameNode | null
+  /** 提供后可点击 slice 跳转源码行（按 name 查 id）。 */
+  functions?: readonly FunctionNode[]
+  /** 热点点击回调 —— 传整 FunctionNode 让 App.tsx 拿 file/origin 决定路由。 */
+  onSelect?: (fn: FunctionNode) => void
+  focusName?: string
+}
+
+interface Arc {
+  name: string
+  value: number
+  start: number
+  end: number
+  innerR: number
+  outerR: number
+  depth: number
+  node: FlameNode
+}
+
+function Sunburst({ flame, functions, onSelect, focusName }: Props) {
+  const t = useT()
+
+  const arcs = useMemo<Arc[] | null>(() => {
+    if (!flame || flame.value <= 0) return null
+    return layoutSunburst(flame)
+  }, [flame])
+
+  const fnByName = useMemo(() => indexFunctionsByName(functions), [functions])
+
+  const truncatedInfo = useMemo(
+    () => (flame ? countTruncatedSiblings(flame, MAX_SIBLINGS) : { depths: [], totalHidden: 0 }),
+    [flame]
+  )
+
+  if (!arcs || !flame) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm text-fg-muted">{t('chart.empty')}</div>
+    )
+  }
+
+  const total = flame.value
+  const selectFromArc = onSelect && fnByName.size > 0 ? onSelect : undefined
+
+  return (
+    <div className="flex h-full flex-col p-3">
+      <div className="mb-2 text-sm text-fg-secondary" aria-live="polite">
+        {t('chart.sunburst.hint')}
+      </div>
+      {truncatedInfo.totalHidden > 0 && (
+        <div className="mb-2 text-sm text-fg-secondary" aria-live="polite">
+          {truncatedInfo.depths.length === 1
+            ? t('chart.truncated', { shown: MAX_SIBLINGS, hidden: truncatedInfo.totalHidden })
+            : t('chart.flame.truncatedMulti', {
+                shown: MAX_SIBLINGS,
+                hidden: truncatedInfo.totalHidden,
+                depths: truncatedInfo.depths.length
+              })}
+        </div>
+      )}
+      {/* 不内嵌 overflow-auto —— 外层右栏自带 overflow-y-auto 接管所有滚动。
+          SVG 居中显示, 数据再多也直接交给外层滚动。 */}
+      <div className="flex flex-1 items-center justify-center">
+        <svg
+          width="100%"
+          viewBox={`0 0 ${SIZE} ${SIZE}`}
+          preserveAspectRatio="xMidYMid meet"
+          role="img"
+          aria-label={t('chart.sunburst.aria')}
+        >
+          {/* 中心摘要:总耗时 + 函数数 —— root 的 name 一般是 "root" 没价值。
+              把这两项放中心,用户一眼看到"这堆数据总共花多少 / 多少个函数"。
+              v4 字号升级: 17 → 19 / 13 → 14。 */}
+          <text
+            x={CENTER}
+            y={CENTER - 6}
+            fill={TEXT_ON_DARK}
+            fontSize={FONT_SIZE.NAME}
+            fontFamily={FONT_MONO}
+            textAnchor="middle"
+            pointerEvents="none"
+            aria-hidden="true"
+          >
+            {fmtDuration(total)}
+          </text>
+          <text
+            x={CENTER}
+            y={CENTER + 18}
+            fill="currentColor"
+            fontSize={FONT_SIZE.HINT}
+            fontFamily={FONT_MONO}
+            textAnchor="middle"
+            pointerEvents="none"
+            opacity={0.6}
+            aria-hidden="true"
+          >
+            {t('chart.sunburst.totalFns', { count: arcCount(arcs) })}
+          </text>
+          {arcs.map((arc, i) => {
+            // 根节点的 arc（depth=0）渲染为实心圆盘；其他用 colorByName。
+            const isRoot = arc.depth === 0
+            const fill = isRoot ? ACCENT_DEEP : colorByName(arc.name)
+            const isFocus = arc.name === focusName
+            const fn = fnByName.get(arc.name)
+            const interactive = !isRoot && !!selectFromArc && !!fn
+            const path = isRoot ? undefined : arcPath(arc, CENTER, CENTER)
+            const onKeyDown = (e: KeyboardEvent<SVGGElement>) => {
+              if (interactive && (e.key === 'Enter' || e.key === ' ')) {
+                e.preventDefault()
+                if (fn) selectFromArc(fn)
+              }
+            }
+            const ariaText = t('chart.sunburst.slice.aria', {
+              name: arc.name,
+              value: fmtDuration(arc.value),
+              pct: ((arc.value / total) * 100).toFixed(1)
+            })
+            // v4 起两层 label：
+            // - 外圈 (depth === MAX_DEPTH): 主字号 NAME 18, 弧长 > 0.08 rad (≈4.6°) 才显示
+            // - 内圈 (1 ≤ depth < MAX_DEPTH): HINT 14 字号小一档, 弧长 > 0.18 rad (≈10°)
+            //   才显示 —— 内圈 ring 宽度只有 64px,大半字会被挤掉
+            // 内圈让用户"扫表"也能看出"那一圈是哪些函数在瓜分时间"，
+            // 之前完全空,旭日图变成"中间一个饼+外圈一圈标签"的奇异状态。
+            const arcSpan = arc.end - arc.start
+            const showLabel = !isRoot && arcSpan > (arc.depth === MAX_DEPTH ? 0.08 : 0.18)
+            // 弧对应外圈弦长 ~ 2R sin(θ/2),字符宽度按弦长的 70% 估(留 label 角度倾斜余量)
+            const labelChord = 2 * arc.outerR * Math.sin(arcSpan / 2)
+            const labelFontSize = arc.depth === MAX_DEPTH ? FONT_SIZE.NAME : FONT_SIZE.HINT
+            const labelChars = charsForWidth(labelChord * 0.7, labelFontSize)
+            const labelAngle = (arc.start + arc.end) / 2
+            const labelR = (arc.innerR + arc.outerR) / 2
+            const lx = CENTER + labelR * Math.sin(labelAngle)
+            const ly = CENTER - labelR * Math.cos(labelAngle)
+            return (
+              <g
+                key={`${arc.depth}-${arc.name}-${i}`}
+                onClick={() => interactive && fn && selectFromArc(fn)}
+                onKeyDown={onKeyDown}
+                tabIndex={interactive ? 0 : -1}
+                role={interactive ? 'button' : undefined}
+                aria-keyshortcuts={interactive ? 'Enter Space' : undefined}
+                aria-label={interactive ? ariaText : undefined}
+                className={interactive ? 'chart-tile cursor-pointer' : ''}
+              >
+                {isRoot ? (
+                  <circle cx={CENTER} cy={CENTER} r={INNER_R} fill={fill} />
+                ) : (
+                  <path
+                    data-chart-shape
+                    d={path}
+                    fill={fill}
+                    fillOpacity={isFocus ? FOCUS.fillOpacity : RESTING.fillOpacity}
+                    stroke={isFocus ? FOCUS.stroke : RESTING.stroke}
+                    strokeWidth={isFocus ? FOCUS.strokeWidth : RESTING.strokeWidth}
+                  />
+                )}
+                {showLabel && labelChars >= 1 && (
+                  <text
+                    x={lx}
+                    y={ly + 5}
+                    fill={TEXT_ON_DARK}
+                    fontSize={labelFontSize}
+                    fontFamily={FONT_MONO}
+                    textAnchor="middle"
+                    pointerEvents="none"
+                    aria-hidden="true"
+                  >
+                    {truncateName(arc.name, labelChars)}
+                  </text>
+                )}
+                <title>{ariaText}</title>
+              </g>
+            )
+          })}
+        </svg>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * 角度约定：0 在 12 点钟方向，正向 = 顺时针。
+ * x = cx + r·sin(θ)；y = cy - r·cos(θ)。
+ */
+function layoutSunburst(root: FlameNode): Arc[] {
+  const arcs: Arc[] = []
+
+  const walk = (node: FlameNode, depth: number, start: number, end: number) => {
+    if (depth > MAX_DEPTH) return
+    const innerR = depth === 0 ? 0 : depth * RING_W
+    const outerR = depth === 0 ? RING_W : (depth + 1) * RING_W
+    arcs.push({
+      name: node.name,
+      value: node.value,
+      start,
+      end,
+      innerR,
+      outerR,
+      depth,
+      node
+    })
+    if (node.children.length === 0 || depth >= MAX_DEPTH) return
+    // node.value === 0 但仍有 children —— 多发生在「模块聚合但模块内没有 self-time」之类的
+    // 边角情况。子节点 span * (c.value / 0) = NaN / Infinity，后续 arc 全坏。
+    // 直接在分配之前 short-circuit；父弧已 push，子节点保留在结构里但不入 arc。
+    if (node.value <= 0) return
+    const cs = node.children.slice(0, MAX_SIBLINGS)
+    const span = end - start
+    let cursor = start
+    for (let i = 0; i < cs.length; i++) {
+      const c = cs[i]
+      const childSpan = span * (c.value / node.value)
+      walk(c, depth + 1, cursor, cursor + childSpan)
+      cursor += childSpan
+    }
+  }
+
+  walk(root, 0, 0, 2 * Math.PI)
+  return arcs
+}
+
+/** 中心摘要里的「N 个函数」：去重后的函数名集合数量,
+ *  不是 arc 数(同一函数多圈递归会重复算)。
+ *  排除根节点 —— 「N 个函数」要的是函数数,根容器不是函数。 */
+function arcCount(arcs: readonly Arc[]): number {
+  const seen = new Set<string>()
+  for (const a of arcs) {
+    if (a.depth === 0) continue
+    seen.add(a.name)
+  }
+  return seen.size
+}
+
+/**
+ * 把 Arc 转成 SVG path：「内弧起点 → 外弧起点 → 弧到外弧终点 → 内弧终点 → 弧回内弧起点」。
+ * 大弧标志：span > π 取 1；sweep 始终 1（顺时针）。
+ */
+function arcPath(arc: Arc, cx: number, cy: number): string {
+  const { start, end, innerR, outerR } = arc
+  const largeArc = end - start > Math.PI ? 1 : 0
+  // 外弧端点
+  const ox0 = cx + outerR * Math.sin(start)
+  const oy0 = cy - outerR * Math.cos(start)
+  const ox1 = cx + outerR * Math.sin(end)
+  const oy1 = cy - outerR * Math.cos(end)
+  // 内弧端点
+  const ix1 = cx + innerR * Math.sin(end)
+  const iy1 = cy - innerR * Math.cos(end)
+  const ix0 = cx + innerR * Math.sin(start)
+  const iy0 = cy - innerR * Math.cos(start)
+  return [
+    `M ${ox0} ${oy0}`,
+    `A ${outerR} ${outerR} 0 ${largeArc} 1 ${ox1} ${oy1}`,
+    `L ${ix1} ${iy1}`,
+    `A ${innerR} ${innerR} 0 ${largeArc} 0 ${ix0} ${iy0}`,
+    'Z'
+  ].join(' ')
+}
+
+export default memo(Sunburst)
diff --git a/src/renderer/src/components/views/TimeChartSwitcher.tsx b/src/renderer/src/components/views/TimeChartSwitcher.tsx
new file mode 100644
index 0000000..afd3b05
--- /dev/null
+++ b/src/renderer/src/components/views/TimeChartSwitcher.tsx
@@ -0,0 +1,230 @@
+/**
+ * 耗时可视化切换器:在 6 种图表之间切换同一份 result。
+ *
+ * 设计选择 —— 不用 `role="tablist"`:
+ * - 仓库目前没有 tablist 角色先例,引入需要同步加方向键 roving focus 和 tabpanel 联动;
+ * - 顶部 TopBar 的 `aria-pressed` 切换模式(终端按钮 line 70-77)已是审计过的成熟样式;
+ * - 这里 6 个按钮逻辑等价于「6 个互斥的开关」,本质是 radio 而非 tab —— 沿用 aria-pressed
+ *   配 role="group" + aria-label,键盘焦点不强制单焦点(用户可任意进出),更符合
+ *   「查看不同视图」的心智模型。
+ *
+ * 排序逻辑(从最常用到最专业):
+ * - bar:    「这函数慢在哪」的首答 —— 排名直读,符合「paste code, see what's slow」
+ * - flame:  主流 profiler(Chrome DevTools / Speedscope)的默认视图,适合下钻层级
+ * - treemap:层级占比的面积视图,同 flame 数据换个看图角度
+ * - sunburst:Firefox Profiler / Pyroscope 风,层级径向,信息密度更高
+ * - cumulative: 自耗时易误导(函数本身快但被调用方慢)时,看 cumtime 排名
+ * - heatmap:  仅在 scope=all + 多模块时才有信息密度,scope=user 时退化为空态
+ *
+ * 默认 bar —— 用户粘贴代码运行分析后第一个问题就是「哪个函数慢」,这正是柱状图的强项。
+ * 火焰图适合二轮 drill-down,不应该是默认首屏。
+ *
+ * 键盘支持:
+ * - Tab 进入 button 组后,← / → 在 6 个按钮之间循环切换并把焦点移到对应按钮上(roving
+ *   focus)。Home/End 跳到首/尾。和 TopBar 的 tablist 不同 —— 这里是单焦点在按钮间移动
+ *   而非全局一个焦点,符合「切换按钮组」的常见模式。
+ * - 进入图表内部后,图表自身的键盘交互(Enter/Space 选中)仍然由图表自己管,switcher 不抢。
+ *
+ * 数据来源:result.flame(树状)和 result.functions(扁平)。每个图表自己挑需要的
+ * 输入;fnId 由 name 查 functions[] 拿 —— FlameNode 没 id。
+ *
+ * v4 字号升级：按钮 text-xs → text-sm, padding 加大 (py-1.5 → py-2), 让 6 个
+ * 切换按钮在屏幕上一眼看清(之前 12px uppercase 偏小, 长时间看眼睛累)。
+ */
+import { memo, useEffect, useRef, useState, type KeyboardEvent } from 'react'
+import type { AnalysisResult, FunctionNode } from '../../../../shared/analysis'
+import BarChart from './BarChart'
+import CumulativeBar from './CumulativeBar'
+import FlameGraph from './FlameGraph'
+import ModuleHeatmap from './ModuleHeatmap'
+import Sunburst from './Sunburst'
+import Treemap from './Treemap'
+import { BarIcon, CumulativeIcon, FlameIcon, HeatmapIcon, SunburstIcon, TreemapIcon } from '../icons'
+import { useT } from '../../i18n'
+
+type ChartType = 'flame' | 'bar' | 'treemap' | 'sunburst' | 'cumulative' | 'heatmap'
+
+interface Props {
+  result: AnalysisResult
+  selectedFuncId: string | undefined
+  /**
+   * 热点点击回调。传 FunctionNode 整对象，让 App.tsx 拿 file / origin 决定
+   * 是 user tab 高亮还是开外部文件 tab。
+   */
+  onSelectHotspot: (fn: FunctionNode) => void
+}
+
+/** 切换顺序:bar → flame → treemap → sunburst → cumulative → heatmap(常用 → 专业)。 */
+const ORDER: ChartType[] = ['bar', 'flame', 'treemap', 'sunburst', 'cumulative', 'heatmap']
+
+function TimeChartSwitcher({ result, selectedFuncId, onSelectHotspot }: Props) {
+  const t = useT()
+  const [chartType, setChartType] = useState<ChartType>('bar')
+  // 6 个按钮的 ref 集合,键盘 ←/→ 在 ref 之间循环跳转。
+  const btnRefs = useRef<Map<ChartType, HTMLButtonElement>>(new Map())
+
+  // 新结果时复位到柱状图:避免上次实验选了一个小数据集的视图,新结果是大数据集时
+  // 上次的旭日图视角会误导。和 FlameGraph 自身的 useEffect(setFocus(null), [flame]) 同款。
+  useEffect(() => {
+    setChartType('bar')
+  }, [result])
+
+  const focusName = result.functions.find((f) => f.id === selectedFuncId)?.name
+
+  /** 移动焦点到指定 type 的按钮,并把 chartType 也切过去(键盘切和点击效果一致) */
+  const focusType = (type: ChartType): void => {
+    setChartType(type)
+    btnRefs.current.get(type)?.focus()
+  }
+  const onSwitcherKeyDown = (e: KeyboardEvent<HTMLDivElement>): void => {
+    const i = ORDER.indexOf(chartType)
+    switch (e.key) {
+      case 'ArrowLeft':
+        e.preventDefault()
+        focusType(ORDER[(i - 1 + ORDER.length) % ORDER.length] ?? 'bar')
+        break
+      case 'ArrowRight':
+        e.preventDefault()
+        focusType(ORDER[(i + 1) % ORDER.length] ?? 'bar')
+        break
+      case 'Home':
+        e.preventDefault()
+        focusType(ORDER[0] ?? 'bar')
+        break
+      case 'End':
+        e.preventDefault()
+        focusType(ORDER[ORDER.length - 1] ?? 'bar')
+        break
+      default:
+        break
+    }
+  }
+
+  return (
+    <div className="flex h-full flex-col">
+      {/* role="group" + onKeyDown 是有意为之的 roving-focus 容器(WAI-ARIA 切换按钮组的
+          标准键盘模式):ArrowLeft/ArrowRight/Home/End 在 6 个按钮间循环跳转。
+          eslint-plugin-jsx-a11y 的 no-noninteractive-element-interactions 规则把
+          group 视为非交互元素,但这里它本身承载键盘交互,需要豁免。 */}
+      {/* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions */}
+      <div
+        role="group"
+        aria-label={t('chart.switcher.label')}
+        onKeyDown={onSwitcherKeyDown}
+        // flex-wrap(不内嵌 overflow-x-auto):右侧整列自带 overflow-y-auto 滚轮,
+        // 内部再横滑就是双层翻轮 + 一窄就要画横滑条, 体验差。
+        // 窄屏让按钮自然换行(2 行内能容下 6 个)即可 —— 切图按钮组高度变化小, 图表区 h-[540px] 还能容下。
+        // v4:padding py-2.5 → py-3 (上下多 2px), 配合按钮 py-2 让 6 个切换器更易点。
+        className="flex shrink-0 flex-wrap items-center gap-1.5 border-b border-border bg-bg px-3 py-3"
+      >
+        {ORDER.map((type) => (
+          <ChartTypeButton
+            key={type}
+            type={type}
+            pressed={chartType === type}
+            onSelect={() => setChartType(type)}
+            registerRef={(el) => {
+              if (el) btnRefs.current.set(type, el)
+              else btnRefs.current.delete(type)
+            }}
+          />
+        ))}
+      </div>
+      <div className="min-h-0 flex-1">
+        {chartType === 'flame' && <FlameGraph flame={result.flame} focusName={focusName} />}
+        {chartType === 'bar' && (
+          <BarChart functions={result.functions} onSelect={onSelectHotspot} focusName={focusName} />
+        )}
+        {chartType === 'cumulative' && (
+          <CumulativeBar functions={result.functions} onSelect={onSelectHotspot} focusName={focusName} />
+        )}
+        {chartType === 'treemap' && (
+          <Treemap
+            flame={result.flame}
+            functions={result.functions}
+            onSelect={onSelectHotspot}
+            focusName={focusName}
+          />
+        )}
+        {chartType === 'sunburst' && (
+          <Sunburst
+            flame={result.flame}
+            functions={result.functions}
+            onSelect={onSelectHotspot}
+            focusName={focusName}
+          />
+        )}
+        {chartType === 'heatmap' && (
+          <ModuleHeatmap functions={result.functions} onSelect={onSelectHotspot} focusName={focusName} />
+        )}
+      </div>
+    </div>
+  )
+}
+
+/** 单个切换按钮:和 TopBar 终端按钮同款 `aria-pressed` 模式。
+ *  v4 字号 text-xs → text-sm,padding 加大,提升点击热区与可读性。 */
+function ChartTypeButton({
+  type,
+  pressed,
+  onSelect,
+  registerRef
+}: {
+  type: ChartType
+  pressed: boolean
+  onSelect: () => void
+  registerRef: (el: HTMLButtonElement | null) => void
+}) {
+  const t = useT()
+  const icon = ICON[type]
+  return (
+    <button
+      ref={registerRef}
+      type="button"
+      onClick={onSelect}
+      aria-pressed={pressed}
+      aria-label={t(LABEL_KEY[type])}
+      title={t(LABEL_KEY[type])}
+      className={
+        // 与 TopBar terminal 按钮一致:pressed 用 bg-accent-soft + text-accent 高亮;
+        // 不上 bg-accent 是因为按钮小,纯色填充视觉过重。
+        // shrink-0:父容器 flex-nowrap + overflow-x-auto,按钮不能被压缩到消失。
+        // v4:text-sm (14px), py-2 px-3.5 — 增大点击区域/提升可读性。
+        pressed
+          ? 'inline-flex shrink-0 items-center gap-2 rounded bg-accent-soft px-3.5 py-2 font-mono text-sm uppercase tracking-wider text-accent focus:outline-none focus-visible:ring-2 focus-visible:ring-accent'
+          : 'inline-flex shrink-0 items-center gap-2 rounded px-3.5 py-2 font-mono text-sm uppercase tracking-wider text-fg-muted hover:bg-surface-1 hover:text-fg-secondary focus:outline-none focus-visible:ring-2 focus-visible:ring-accent'
+      }
+    >
+      {icon}
+      <span>{t(LABEL_KEY[type])}</span>
+    </button>
+  )
+}
+
+const LABEL_KEY: Record<
+  ChartType,
+  | 'chart.type.flame'
+  | 'chart.type.bar'
+  | 'chart.type.treemap'
+  | 'chart.type.sunburst'
+  | 'chart.type.cumulative'
+  | 'chart.type.heatmap'
+> = {
+  flame: 'chart.type.flame',
+  bar: 'chart.type.bar',
+  treemap: 'chart.type.treemap',
+  sunburst: 'chart.type.sunburst',
+  cumulative: 'chart.type.cumulative',
+  heatmap: 'chart.type.heatmap'
+}
+
+const ICON: Record<ChartType, JSX.Element> = {
+  flame: <FlameIcon size={16} />,
+  bar: <BarIcon size={16} />,
+  cumulative: <CumulativeIcon size={16} />,
+  treemap: <TreemapIcon size={16} />,
+  sunburst: <SunburstIcon size={16} />,
+  heatmap: <HeatmapIcon size={16} />
+}
+
+export default memo(TimeChartSwitcher)
diff --git a/src/renderer/src/components/views/Treemap.tsx b/src/renderer/src/components/views/Treemap.tsx
new file mode 100644
index 0000000..0e31d2a
--- /dev/null
+++ b/src/renderer/src/components/views/Treemap.tsx
@@ -0,0 +1,329 @@
+import { memo, useMemo, type KeyboardEvent } from 'react'
+import type { FlameNode, FunctionNode } from '../../../../shared/analysis'
+import { TEXT_ON_DARK } from '../../utils/colors'
+import { fmtDuration } from '../../utils/format'
+import {
+  FOCUS,
+  FONT_MONO,
+  FONT_SIZE,
+  MAX_SIBLINGS,
+  RESTING,
+  charsForWidth,
+  colorByName,
+  countTruncatedSiblings,
+  indexFunctionsByName,
+  truncateName
+} from './chart-utils'
+import { useT } from '../../i18n'
+
+/**
+ * 矩形树图（squarified treemap）—— Chrome DevTools / Speedscope 的标准风格。
+ *
+ * 为什么不用 slice-and-dice：交替横竖切会让大半和小条拼在一起，看起来很乱；
+ * squarify 通过保持每个矩形宽高比接近 1，得到「看起来是方块」的版面。
+ * 实现参考 Bruls et al. (2000)；手写版避免引入 d3-hierarchy。
+ *
+ * 层级：递归 squarify。每个非叶子节点占一个矩形（含顶部标签带），把
+ * 子节点 squarify 进剩余区域。深度限 3（和 FlameGraph 一致）。
+ *
+ * 截断：每层 sibling 上限 24（沿用 MAX_SIBLINGS），超出必显式提示。
+ *
+ * v4 升级：
+ * - HEADER_H 28 → 36 容纳更大字号
+ * - fontSize 15 → 16-18
+ * - 窄 tile 也显示标签（charsForWidth 兜底）
+ * - 加图例（解释 area = 占比 / colorByName 同色）
+ */
+const MAX_DEPTH = 3
+const CANVAS_W = 920
+// 920×920 的方形画布会让根节点 squarify 出"宽 920 × 高 920"的极端长方形,
+// 顶层 child tile 横向极宽;改成 920×580(≈16:10)后顶层更接近正方形,信息密度也更接近
+// ResultsPanel 540px 容器高度。viewBox 配合 preserveAspectRatio="xMidYMid meet" 自动
+// 缩放,容器窄于 920 时按宽度等比缩,不会越界。
+const CANVAS_H = 580
+const HEADER_H = 36
+
+interface Props {
+  flame: FlameNode | null
+  /** 提供后可点击 tile 跳转源码行（按 name 查 id）。BarChart 同步走这条路径。 */
+  functions?: readonly FunctionNode[]
+  /** 热点点击回调 —— 传整 FunctionNode 让 App.tsx 拿 file/origin 决定路由。 */
+  onSelect?: (fn: FunctionNode) => void
+  focusName?: string
+}
+
+interface Rect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+interface Tile {
+  name: string
+  value: number
+  rect: Rect
+  depth: number
+  isHeader: boolean
+  node: FlameNode
+}
+
+function Treemap({ flame, functions, onSelect, focusName }: Props) {
+  const t = useT()
+
+  const tiles = useMemo<Tile[] | null>(() => {
+    if (!flame || flame.value <= 0 || flame.children.length === 0) return null
+    return layoutHierarchical(flame, { x: 0, y: 0, width: CANVAS_W, height: CANVAS_H })
+  }, [flame])
+
+  // name → FunctionNode 查表：选中 / 焦点同步
+  const fnByName = useMemo(() => indexFunctionsByName(functions), [functions])
+
+  const truncatedInfo = useMemo(
+    () => (flame ? countTruncatedSiblings(flame, MAX_SIBLINGS) : { depths: [], totalHidden: 0 }),
+    [flame]
+  )
+
+  if (!tiles || !flame) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm text-fg-muted">{t('chart.empty')}</div>
+    )
+  }
+
+  const maxY = tiles.reduce((m, it) => Math.max(m, it.rect.y + it.rect.height), 0)
+  const total = flame.value
+  const selectFromTile = onSelect && fnByName.size > 0 ? onSelect : undefined
+
+  return (
+    <div className="flex h-full flex-col p-3">
+      <div className="mb-2 text-sm text-fg-secondary" aria-live="polite">
+        {t('chart.treemap.hint')}
+      </div>
+      {/* 截断提示：v4 起按深度聚合（同 FlameGraph）—— 深层被截不再静默。 */}
+      {truncatedInfo.totalHidden > 0 && (
+        <div className="mb-2 text-sm text-fg-secondary" aria-live="polite">
+          {truncatedInfo.depths.length === 1
+            ? t('chart.truncated', { shown: MAX_SIBLINGS, hidden: truncatedInfo.totalHidden })
+            : t('chart.flame.truncatedMulti', {
+                shown: MAX_SIBLINGS,
+                hidden: truncatedInfo.totalHidden,
+                depths: truncatedInfo.depths.length
+              })}
+        </div>
+      )}
+      {/* 不内嵌 overflow-auto —— 外层右栏自带 overflow-y-auto 接管所有滚动。
+          SVG viewBox + preserveAspectRatio 自适应尺寸, 深层调用栈再多也直接交给外层滚动。 */}
+      <div className="flex-1">
+        <svg
+          width="100%"
+          viewBox={`0 0 ${CANVAS_W} ${Math.max(1, maxY)}`}
+          preserveAspectRatio="xMinYMin meet"
+          role="img"
+          aria-label={t('chart.treemap.aria')}
+        >
+          {tiles.map((it, i) => {
+            // header tile 是"目录"色 (var(--surface-2))，不是数据；数据 tile 用 colorByName。
+            const fill = it.isHeader ? 'var(--surface-2)' : colorByName(it.name)
+            const isFocus = it.name === focusName
+            // v4 起不再「width > 80 && height > 32 才显示」 —— 改用 charsForWidth
+            // 按可用宽度反算能放几个字。窄 tile 也挤得下 1-2 字符,完全是视觉锚点。
+            // 算 label 高度: header 用 HEADER_H,数据 tile 用 rect 高度;两条都给 6px padding。
+            const labelH = it.isHeader ? HEADER_H : it.rect.height
+            const labelChars = charsForWidth(it.rect.width - 12, FONT_SIZE.BODY)
+            const showLabel = labelChars >= 1 && (it.isHeader || it.rect.height >= 18)
+            const fn = fnByName.get(it.name)
+            const interactive = !!selectFromTile && !!fn && !it.isHeader
+            const onKeyDown = (e: KeyboardEvent<SVGGElement>) => {
+              if (interactive && (e.key === 'Enter' || e.key === ' ')) {
+                e.preventDefault()
+                if (fn) selectFromTile(fn)
+              }
+            }
+            const ariaText = t('chart.treemap.tile.aria', {
+              name: it.name,
+              value: fmtDuration(it.value),
+              pct: ((it.value / total) * 100).toFixed(1)
+            })
+            return (
+              <g
+                key={`${it.depth}-${it.name}-${i}`}
+                transform={`translate(${it.rect.x}, ${it.rect.y})`}
+                onClick={() => interactive && fn && selectFromTile(fn)}
+                onKeyDown={onKeyDown}
+                tabIndex={interactive ? 0 : -1}
+                role={interactive ? 'button' : undefined}
+                aria-keyshortcuts={interactive ? 'Enter Space' : undefined}
+                aria-label={interactive ? ariaText : undefined}
+                className={interactive ? 'chart-tile cursor-pointer' : ''}
+              >
+                <rect
+                  data-chart-shape={it.isHeader ? undefined : true}
+                  x={0}
+                  y={0}
+                  width={Math.max(0, it.rect.width - 1)}
+                  height={Math.max(0, it.rect.height - 1)}
+                  rx={2}
+                  fill={fill}
+                  fillOpacity={it.isHeader ? 1 : isFocus ? FOCUS.fillOpacity : RESTING.fillOpacity}
+                  stroke={isFocus ? FOCUS.stroke : RESTING.stroke}
+                  strokeWidth={isFocus ? FOCUS.strokeWidth : RESTING.strokeWidth}
+                />
+                {showLabel && (
+                  <text
+                    x={8}
+                    y={labelH / 2 + 6}
+                    fill={it.isHeader ? 'currentColor' : TEXT_ON_DARK}
+                    fontSize={it.isHeader ? FONT_SIZE.HINT : FONT_SIZE.BODY}
+                    fontFamily={FONT_MONO}
+                    pointerEvents="none"
+                    aria-hidden="true"
+                  >
+                    {truncateName(it.name, labelChars)}
+                  </text>
+                )}
+                <title>{ariaText}</title>
+              </g>
+            )
+          })}
+        </svg>
+      </div>
+    </div>
+  )
+}
+
+/** squarify 输入项：value + 任意附加字段。返回时附 rect 字段。 */
+type SquarifyItem<T> = T & { value: number; rect: Rect }
+
+/**
+ * 把节点列表按 value 降序排好的前提下 squarify 进给定矩形。
+ * 算法核心（Bruls et al. 2000）：维护一行 row；新行宽高比不更差就并入，否则落行。
+ */
+function squarify<T>(items: readonly (T & { value: number })[], container: Rect): SquarifyItem<T>[] {
+  if (items.length === 0 || container.width <= 0 || container.height <= 0) return []
+
+  // 按 value 降序；保留每个元素在原数组中的 idx 以便回写
+  const indexed = items.map((it, i) => ({ it, idx: i })).sort((a, b) => b.it.value - a.it.value)
+
+  const total = indexed.reduce((s, x) => s + x.it.value, 0)
+  if (total <= 0) return []
+
+  const result: SquarifyItem<T>[] = items.map((it) => ({ ...it, rect: { x: 0, y: 0, width: 0, height: 0 } }))
+
+  let rem: Rect = { ...container }
+  let row: typeof indexed = []
+  let best = Infinity
+
+  const rowSum = (r: typeof row) => r.reduce((s, x) => s + x.it.value, 0)
+  const worst = (r: typeof row, shortSide: number) => {
+    if (r.length === 0) return Infinity
+    const s = rowSum(r)
+    if (s <= 0) return Infinity
+    let mx = -Infinity
+    let mn = Infinity
+    for (const x of r) {
+      if (x.it.value > mx) mx = x.it.value
+      if (x.it.value < mn) mn = x.it.value
+    }
+    const s2 = s * s
+    const w2 = shortSide * shortSide
+    return Math.max((w2 * mx) / s2, s2 / (w2 * mn))
+  }
+
+  const placeRow = (r: typeof row) => {
+    const s = rowSum(r)
+    if (s <= 0) return
+    const horizontal = rem.width >= rem.height
+    const rowSize = horizontal ? rem.height : rem.width
+    const totalSize = horizontal ? rem.width : rem.height
+    let offset = horizontal ? rem.x : rem.y
+    for (const x of r) {
+      const len = (x.it.value / s) * totalSize
+      result[x.idx].rect = horizontal
+        ? { x: offset, y: rem.y, width: len, height: rowSize }
+        : { x: rem.x, y: offset, width: rowSize, height: len }
+      offset += len
+    }
+    rem = horizontal
+      ? { x: rem.x, y: rem.y + rowSize, width: rem.width, height: rem.height - rowSize }
+      : { x: rem.x + rowSize, y: rem.y, width: rem.width - rowSize, height: rem.height }
+  }
+
+  let pending = indexed
+  while (pending.length > 0) {
+    const next = pending[0]
+    const newRow = [...row, next]
+    const shortSide = Math.min(rem.width, rem.height)
+    const w = worst(newRow, shortSide)
+    if (row.length === 0 || w <= best) {
+      row = newRow
+      best = w
+      pending = pending.slice(1)
+    } else {
+      placeRow(row)
+      row = []
+      best = Infinity
+    }
+  }
+  if (row.length > 0) placeRow(row)
+
+  return result
+}
+
+/**
+ * 递归布局：每个非叶子节点先 squarify 子节点，再把自己的「header」标签带放上去。
+ * 根节点不画 header（占满画布），其他节点 depth ≥ 1 且 rect 高 ≥ HEADER_H + 8 时才画。
+ */
+function layoutHierarchical(root: FlameNode, canvas: Rect): Tile[] {
+  const tiles: Tile[] = []
+
+  const walk = (node: FlameNode, rect: Rect, depth: number) => {
+    if (depth >= MAX_DEPTH || node.children.length === 0) {
+      tiles.push({
+        name: node.name,
+        value: node.value,
+        rect,
+        depth,
+        isHeader: false,
+        node
+      })
+      return
+    }
+
+    const childrenRect: Rect =
+      depth === 0 ? rect : { ...rect, y: rect.y + HEADER_H, height: Math.max(0, rect.height - HEADER_H) }
+
+    if (depth > 0 && rect.height >= HEADER_H + 8) {
+      tiles.push({
+        name: node.name,
+        value: node.value,
+        rect: { x: rect.x, y: rect.y, width: rect.width, height: HEADER_H },
+        depth,
+        isHeader: true,
+        node
+      })
+    }
+
+    const cs = node.children.slice(0, MAX_SIBLINGS)
+    if (childrenRect.width <= 0 || childrenRect.height <= 0) return
+    const items = cs.map((c, i) => ({ ...c, _idx: i }))
+    const childTiles = squarify(items, childrenRect)
+    for (const ct of childTiles) {
+      tiles.push({
+        name: ct.name,
+        value: ct.value,
+        rect: ct.rect,
+        depth: depth + 1,
+        isHeader: false,
+        node: ct
+      })
+      if (ct.children.length > 0 && depth + 1 < MAX_DEPTH) {
+        walk(ct, ct.rect, depth + 1)
+      }
+    }
+  }
+
+  walk(root, canvas, 0)
+  return tiles
+}
+
+export default memo(Treemap)
diff --git a/src/renderer/src/components/views/__tests__/BarChart.test.tsx b/src/renderer/src/components/views/__tests__/BarChart.test.tsx
new file mode 100644
index 0000000..bb74219
--- /dev/null
+++ b/src/renderer/src/components/views/__tests__/BarChart.test.tsx
@@ -0,0 +1,72 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import BarChart from '../BarChart'
+import golden from '../../../fixtures/golden.json'
+import type { AnalysisResult, FunctionNode } from '../../../../../shared/analysis'
+import { wrap } from '../../../i18n/test-utils'
+
+const result = golden as unknown as AnalysisResult
+
+describe('BarChart', () => {
+  it('renders one rect per visible row (≤ TOP_N)', () => {
+    const { container } = render(wrap(<BarChart functions={result.functions} onSelect={() => {}} />))
+    // 12 行：每行一个背景轨 + 一个数据条 = 24 rect
+    // 取 TOP_N=12 这个不变量就行，不绑死 rect 数（防御未来调 N）
+    const rects = container.querySelectorAll('rect')
+    expect(rects.length).toBeGreaterThan(0)
+    // 至少包含 top1 函数名（golden 首条是 leaf）
+    expect(screen.getByText('leaf')).toBeInTheDocument()
+  })
+
+  it('shows placeholder when no functions', () => {
+    render(wrap(<BarChart functions={[]} onSelect={() => {}} />))
+    expect(screen.getByText(/暂无耗时数据/)).toBeInTheDocument()
+  })
+
+  it('truncation notice when functions.length > TOP_N', () => {
+    // 造 20 个函数，TOP_N=12，应出现「仅显示前 12 个，另有 8 个未显示」
+    // —— 复用 chart.truncated 文案（和 FlameGraph / Treemap / Sunburst 一致）
+    const fns: FunctionNode[] = Array.from({ length: 20 }, (_, i) => ({
+      id: `f${i}`,
+      file: 'a.py',
+      line: i + 1,
+      name: `fn${i}`,
+      module: '<user>',
+      cumtime: 1,
+      tottime: 1,
+      ncalls: 1,
+      percallTot: 1
+    }))
+    render(wrap(<BarChart functions={fns} onSelect={() => {}} />))
+    expect(screen.getByText(/仅显示前 12 个，另有 8 个未显示/)).toBeInTheDocument()
+  })
+
+  it('no truncation notice when within TOP_N', () => {
+    const fns: FunctionNode[] = Array.from({ length: 5 }, (_, i) => ({
+      id: `f${i}`,
+      file: 'a.py',
+      line: i + 1,
+      name: `fn${i}`,
+      module: '<user>',
+      cumtime: 1,
+      tottime: 1,
+      ncalls: 1,
+      percallTot: 1
+    }))
+    render(wrap(<BarChart functions={fns} onSelect={() => {}} />))
+    expect(screen.queryByText(/另有 \d+ 个未显示/)).not.toBeInTheDocument()
+  })
+
+  it('clicking a bar fires onSelect with the matching fn', () => {
+    const onSelect = vi.fn<(fn: { id: string; line: number }) => void>()
+    render(wrap(<BarChart functions={result.functions} onSelect={onSelect} />))
+    // 第一行是 leaf，role=button 的 aria-label 包含「自耗时」
+    const btn = screen.getByRole('button', { name: /leaf/ })
+    fireEvent.click(btn)
+    expect(onSelect).toHaveBeenCalledTimes(1)
+    const firstCall = onSelect.mock.calls[0]
+    if (!firstCall) throw new Error('expected onSelect to be called')
+    const [fn] = firstCall
+    expect(fn.id).toBe(result.functions[0].id)
+    expect(fn.line).toBe(result.functions[0].line)
+  })
+})
diff --git a/src/renderer/src/components/views/__tests__/CumulativeBar.test.tsx b/src/renderer/src/components/views/__tests__/CumulativeBar.test.tsx
new file mode 100644
index 0000000..aad05c3
--- /dev/null
+++ b/src/renderer/src/components/views/__tests__/CumulativeBar.test.tsx
@@ -0,0 +1,114 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import CumulativeBar from '../CumulativeBar'
+import golden from '../../../fixtures/golden.json'
+import type { AnalysisResult, FunctionNode } from '../../../../../shared/analysis'
+import { wrap } from '../../../i18n/test-utils'
+
+const result = golden as unknown as AnalysisResult
+
+describe('CumulativeBar', () => {
+  it('renders one cumulative row per visible function (≤ TOP_N=12)', () => {
+    const { container } = render(wrap(<CumulativeBar functions={result.functions} onSelect={() => {}} />))
+    // 5 个函数(都 cumtime>0):每行 2 段 rect(self+callee)= 10 rect,加 5 个背景轨 = 15 rect
+    const rects = container.querySelectorAll('rect')
+    expect(rects.length).toBeGreaterThan(0)
+    // golden cumtime 最大的应该是 leaf(累计时间最长)
+    expect(screen.getByText('leaf')).toBeInTheDocument()
+  })
+
+  it('shows placeholder when no functions', () => {
+    render(wrap(<CumulativeBar functions={[]} onSelect={() => {}} />))
+    expect(screen.getByText(/暂无耗时数据/)).toBeInTheDocument()
+  })
+
+  it('truncation notice when functions.length > TOP_N', () => {
+    const fns: FunctionNode[] = Array.from({ length: 20 }, (_, i) => ({
+      id: `f${i}`,
+      file: 'a.py',
+      line: i + 1,
+      name: `fn${i}`,
+      module: '<user>',
+      cumtime: 1,
+      tottime: 1,
+      ncalls: 1,
+      percallTot: 1
+    }))
+    render(wrap(<CumulativeBar functions={fns} onSelect={() => {}} />))
+    expect(screen.getByText(/仅显示前 12 个，另有 8 个未显示/)).toBeInTheDocument()
+  })
+
+  it('clicking a bar fires onSelect with the matching fn', () => {
+    const onSelect = vi.fn<(fn: { id: string; line: number }) => void>()
+    render(wrap(<CumulativeBar functions={result.functions} onSelect={onSelect} />))
+    // 第一行是 cumtime 最大的 leaf
+    const btn = screen.getByRole('button', { name: /leaf/ })
+    fireEvent.click(btn)
+    expect(onSelect).toHaveBeenCalledTimes(1)
+    const firstCall = onSelect.mock.calls[0]
+    if (!firstCall) throw new Error('expected onSelect to be called')
+    const [fn] = firstCall
+    expect(fn.id).toBe(result.functions[0].id)
+    expect(fn.line).toBe(result.functions[0].line)
+  })
+
+  it('cumtime=0 的函数被剔除(不会占用 row)', () => {
+    // 3 个函数:一个有 cumtime,两个 cumtime=0
+    // 期望:只渲染 1 行(那个有 cumtime 的)
+    const fns: FunctionNode[] = [
+      {
+        id: 'a',
+        file: 'a.py',
+        line: 1,
+        name: 'has_cum',
+        module: '<user>',
+        cumtime: 1,
+        tottime: 1,
+        ncalls: 1,
+        percallTot: 1
+      },
+      {
+        id: 'b',
+        file: 'a.py',
+        line: 2,
+        name: 'no_cum_1',
+        module: '<user>',
+        cumtime: 0,
+        tottime: 0,
+        ncalls: 1,
+        percallTot: 0
+      },
+      {
+        id: 'c',
+        file: 'a.py',
+        line: 3,
+        name: 'no_cum_2',
+        module: '<user>',
+        cumtime: 0,
+        tottime: 0,
+        ncalls: 1,
+        percallTot: 0
+      }
+    ]
+    render(wrap(<CumulativeBar functions={fns} onSelect={() => {}} />))
+    expect(screen.getByRole('button', { name: /has_cum/ })).toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: /no_cum_1/ })).not.toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: /no_cum_2/ })).not.toBeInTheDocument()
+  })
+
+  it('keyboard Enter on bar 触发 onSelect', () => {
+    const onSelect = vi.fn<(fn: { id: string; line: number }) => void>()
+    render(wrap(<CumulativeBar functions={result.functions} onSelect={onSelect} />))
+    const btn = screen.getByRole('button', { name: /leaf/ })
+    fireEvent.keyDown(btn, { key: 'Enter' })
+    expect(onSelect).toHaveBeenCalledTimes(1)
+  })
+
+  it('右对齐文本带 "% self" 标签(避免和 bar 长度的"总占比"读混)', () => {
+    const { container } = render(wrap(<CumulativeBar functions={result.functions} onSelect={() => {}} />))
+    // 右对齐的 <text textAnchor="end"> 节点要含 "% self ·"
+    const texts = Array.from(container.querySelectorAll('text[text-anchor="end"]'))
+      .map((t) => t.textContent ?? '')
+      .join(' ')
+    expect(texts).toMatch(/\d+%\s*self\s*·/)
+  })
+})
diff --git a/src/renderer/src/components/views/__tests__/FlameGraph.test.tsx b/src/renderer/src/components/views/__tests__/FlameGraph.test.tsx
new file mode 100644
index 0000000..1f85987
--- /dev/null
+++ b/src/renderer/src/components/views/__tests__/FlameGraph.test.tsx
@@ -0,0 +1,69 @@
+import { render, screen } from '@testing-library/react'
+import FlameGraph from '../FlameGraph'
+import golden from '../../../fixtures/golden.json'
+import type { AnalysisResult, FlameNode } from '../../../../../shared/analysis'
+import { wrap } from '../../../i18n/test-utils'
+
+const result = golden as unknown as AnalysisResult
+
+describe('FlameGraph', () => {
+  it('renders root + at least one child rect', () => {
+    const { container } = render(wrap(<FlameGraph flame={result.flame} />))
+    const rects = container.querySelectorAll('rect')
+    expect(rects.length).toBeGreaterThanOrEqual(2)
+  })
+
+  it('shows placeholder when flame is null', () => {
+    render(wrap(<FlameGraph flame={null} />))
+    expect(screen.getByText(/无可显示的函数/)).toBeInTheDocument()
+  })
+
+  it('同名兄弟节点的 children 各自正确显示（修复 byDepth Map 撞名 bug）', () => {
+    // root -> [a, b]，a 和 b 同名 "x"；a 的子节点是 leaf1，b 的子节点是 leaf2。
+    // 修复前 byDepth 用 name 做 key，a 和 b 共享同一个节点，导致 row2 渲染两次同一个 children
+    const flame: FlameNode = {
+      name: 'root',
+      value: 6,
+      children: [
+        { name: 'x', value: 3, children: [{ name: 'leaf1', value: 3, children: [] }] },
+        { name: 'x', value: 3, children: [{ name: 'leaf2', value: 3, children: [] }] }
+      ]
+    }
+    const { container } = render(wrap(<FlameGraph flame={flame} />))
+    // row2 应该同时包含 leaf1 和 leaf2，而不是重复渲染同一个 leaf
+    const texts = Array.from(container.querySelectorAll('text'))
+      .map((t) => t.textContent)
+      .filter(Boolean)
+    expect(texts).toContain('leaf1')
+    expect(texts).toContain('leaf2')
+  })
+
+  it('兄弟节点超过 MAX_SIBLINGS 时显示截断提示（和 HotspotTable 一致 — 绝不静默截断）', () => {
+    // MAX_SIBLINGS = 24，造 30 个兄弟验证"仅显示前 24 个，另有 6 个未显示"
+    const flame: FlameNode = {
+      name: 'root',
+      value: 30,
+      children: Array.from({ length: 30 }, (_, i) => ({
+        name: `n${i}`,
+        value: 1,
+        children: []
+      }))
+    }
+    render(wrap(<FlameGraph flame={flame} />))
+    expect(screen.getByText(/仅显示前 24 个，另有 6 个未显示/)).toBeInTheDocument()
+  })
+
+  it('兄弟节点未超上限时不显示截断提示', () => {
+    const flame: FlameNode = {
+      name: 'root',
+      value: 3,
+      children: [
+        { name: 'a', value: 1, children: [] },
+        { name: 'b', value: 1, children: [] },
+        { name: 'c', value: 1, children: [] }
+      ]
+    }
+    render(wrap(<FlameGraph flame={flame} />))
+    expect(screen.queryByText(/另有 \d+ 个未显示/)).not.toBeInTheDocument()
+  })
+})
diff --git a/src/renderer/src/components/views/__tests__/HotspotTable.test.tsx b/src/renderer/src/components/views/__tests__/HotspotTable.test.tsx
new file mode 100644
index 0000000..25bb528
--- /dev/null
+++ b/src/renderer/src/components/views/__tests__/HotspotTable.test.tsx
@@ -0,0 +1,289 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import HotspotTable from '../HotspotTable'
+import type { FunctionNode } from '../../../../../shared/analysis'
+import { wrap } from '../../../i18n/test-utils'
+
+/** 造 n 个函数；tottime 递减，便于断言排序方向。 */
+function makeFns(n: number): FunctionNode[] {
+  return Array.from({ length: n }, (_, i) => ({
+    id: `f.py:${i + 1}:fn${i}`,
+    file: 'f.py',
+    line: i + 1,
+    name: `fn${i}`,
+    module: '<user>',
+    // fn0 最慢，fnN-1 最快
+    tottime: (n - i) / 1000,
+    cumtime: (n - i) / 500,
+    ncalls: n - i,
+    percallTot: 1 / 1000
+  }))
+}
+
+const noop = (): void => {}
+
+// aria-label 的实际格式：「fnN（origin）第 X 行 · 自耗时 ... · 调用 N 次」
+// 中间夹的 origin 段（v3 起）用 `（[^）]+）?` 兜底,允许带或不带 origin。
+const rowBtn = (name: string): HTMLElement =>
+  screen.getByRole('button', { name: new RegExp(`^${name}（[^）]+）? 第 \\d+ 行`) })
+const allRows = (): HTMLElement[] => screen.getAllByRole('button', { name: /^fn\d+（[^）]+）? 第 \d+ 行/ })
+
+describe('HotspotTable', () => {
+  it('无数据时给出占位文案', () => {
+    render(wrap(<HotspotTable functions={[]} onSelect={noop} />))
+    expect(screen.getByText(/没有可显示的函数/)).toBeInTheDocument()
+  })
+
+  it('默认按自耗时降序排列（aria-sort=descending），最慢的 fn0 在最上', () => {
+    render(wrap(<HotspotTable functions={makeFns(5)} onSelect={noop} />))
+    const totHeader = screen.getByRole('columnheader', { name: /自耗时/ })
+    expect(totHeader).toHaveAttribute('aria-sort', 'descending')
+    // 数据是从大到小（fn0 最慢）→ 降序首行就是 fn0
+    expect(allRows()[0].getAttribute('aria-label')).toContain('fn0')
+  })
+
+  it('点击表头切换排序方向，aria-sort 同步', () => {
+    render(wrap(<HotspotTable functions={makeFns(5)} onSelect={noop} />))
+
+    const cumHeader = (): HTMLElement => screen.getByRole('columnheader', { name: /累计耗时/ })
+    expect(cumHeader()).toHaveAttribute('aria-sort', 'none')
+
+    fireEvent.click(screen.getByRole('button', { name: /按 累计耗时 排序/ }))
+    // 切到新列时是降序
+    expect(cumHeader()).toHaveAttribute('aria-sort', 'descending')
+
+    fireEvent.click(screen.getByRole('button', { name: /按 累计耗时 排序/ }))
+    expect(cumHeader()).toHaveAttribute('aria-sort', 'ascending')
+
+    // 升序后第一行应是 cumtime 最小的 fn4
+    expect(allRows()[0].getAttribute('aria-label')).toContain('fn4')
+  })
+
+  it('选中行标记 aria-pressed', () => {
+    const fns = makeFns(3)
+    render(wrap(<HotspotTable functions={fns} onSelect={noop} selectedId={fns[1].id} />))
+    expect(rowBtn('fn1')).toHaveAttribute('aria-pressed', 'true')
+  })
+
+  it('点击行回调 (FunctionNode)', () => {
+    const onSelect = vi.fn()
+    const fns = makeFns(3)
+    render(wrap(<HotspotTable functions={fns} onSelect={onSelect} />))
+    fireEvent.click(rowBtn('fn2'))
+    // 新签名：传整 FunctionNode（让 App.tsx 拿 file + origin 路由）
+    expect(onSelect).toHaveBeenCalledWith(fns[2])
+  })
+
+  describe('行数截断（避免几百个函数一次性渲染）', () => {
+    it('不超过上限时不显示截断提示', () => {
+      render(wrap(<HotspotTable functions={makeFns(200)} onSelect={noop} />))
+      expect(allRows()).toHaveLength(200)
+      expect(screen.queryByText(/另有 \d+ 行未显示/)).not.toBeInTheDocument()
+    })
+
+    it('超过上限时只渲染前 200 行，并说明藏了多少', () => {
+      render(wrap(<HotspotTable functions={makeFns(250)} onSelect={noop} />))
+      expect(allRows()).toHaveLength(200)
+      // 必须明确告知藏了几个，不能静默截断
+      expect(screen.getByText(/另有 50 行未显示/)).toBeInTheDocument()
+    })
+
+    it('「显示全部」展开后渲染所有行，并能收回', () => {
+      render(wrap(<HotspotTable functions={makeFns(250)} onSelect={noop} />))
+
+      fireEvent.click(screen.getByRole('button', { name: /展开全部 250 行/ }))
+      expect(allRows()).toHaveLength(250)
+
+      fireEvent.click(screen.getByRole('button', { name: /收起至前 200 行/ }))
+      expect(allRows()).toHaveLength(200)
+    })
+
+    it('截断发生在排序之后：换列排序时前 200 名跟着变', () => {
+      render(wrap(<HotspotTable functions={makeFns(250)} onSelect={noop} />))
+
+      // 默认自耗时降序 → 最慢的 fn0 在，最快的 fn249 被截掉
+      expect(rowBtn('fn0')).toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: /^fn249（[^）]+）? 第 \d+ 行/ })).not.toBeInTheDocument()
+
+      // 切到 Cumtime 升序 → 最快的 fn249 进榜，最慢的 fn0 被截掉
+      fireEvent.click(screen.getByRole('button', { name: /按 累计耗时 排序/ }))
+      fireEvent.click(screen.getByRole('button', { name: /按 累计耗时 排序/ }))
+      expect(rowBtn('fn249')).toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: /^fn0（[^）]+）? 第 \d+ 行/ })).not.toBeInTheDocument()
+    })
+  })
+
+  describe('模块过滤 (scope=all 才显示)', () => {
+    /** 造一组跨模块的函数，模块名写在 fn.module。 */
+    function makeMultiModuleFns(): FunctionNode[] {
+      return [
+        {
+          id: 'u.py:1:main',
+          file: 'u.py',
+          line: 1,
+          name: 'main',
+          module: '<user>',
+          tottime: 0.5,
+          cumtime: 0.5,
+          ncalls: 1,
+          percallTot: 0.5
+        },
+        {
+          id: 'json/__init__.py:1:loads',
+          file: 'json/__init__.py',
+          line: 1,
+          name: 'loads',
+          module: 'json',
+          tottime: 0.3,
+          cumtime: 0.3,
+          ncalls: 1,
+          percallTot: 0.3
+        },
+        {
+          id: 'json/decoder.py:10:decode',
+          file: 'json/decoder.py',
+          line: 10,
+          name: 'decode',
+          module: 'json',
+          tottime: 0.2,
+          cumtime: 0.2,
+          ncalls: 1,
+          percallTot: 0.2
+        },
+        {
+          id: 'time.py:5:sleep',
+          file: 'time.py',
+          line: 5,
+          name: 'sleep',
+          module: 'time',
+          tottime: 0.1,
+          cumtime: 0.1,
+          ncalls: 1,
+          percallTot: 0.1
+        }
+      ]
+    }
+
+    it('单模块时不显示 filter chips（scope=user 默认情况，避免无用 UI）', () => {
+      render(wrap(<HotspotTable functions={makeFns(5)} onSelect={noop} />))
+      // makeFns 默认全是 <user>，模块集合只有一个 → 不应有「全部 N」chip
+      expect(screen.queryByRole('group', { name: /按模块过滤/ })).not.toBeInTheDocument()
+    })
+
+    it('多模块时显示 filter chips，「全部」+ 每个模块一个', () => {
+      render(wrap(<HotspotTable functions={makeMultiModuleFns()} onSelect={noop} />))
+      const group = screen.getByRole('group', { name: /按模块过滤/ })
+      expect(group).toBeInTheDocument()
+      // 「全部 4」chip —— 默认选中
+      expect(screen.getByRole('button', { name: /^全部 4/ })).toHaveAttribute('aria-pressed', 'true')
+      // 各模块 chip：json 2 条、time 1 条、<user> 1 条
+      expect(screen.getByRole('button', { name: /^json 2/ })).toBeInTheDocument()
+      expect(screen.getByRole('button', { name: /^time 1/ })).toBeInTheDocument()
+      expect(screen.getByRole('button', { name: /^<user> 1/ })).toBeInTheDocument()
+    })
+
+    it('点击模块 chip 只显示该模块的行，aria-pressed 同步', () => {
+      render(wrap(<HotspotTable functions={makeMultiModuleFns()} onSelect={noop} />))
+
+      fireEvent.click(screen.getByRole('button', { name: /^json 2/ }))
+
+      // 选中态同步
+      expect(screen.getByRole('button', { name: /^json 2/ })).toHaveAttribute('aria-pressed', 'true')
+      expect(screen.getByRole('button', { name: /^全部/ })).toHaveAttribute('aria-pressed', 'false')
+
+      // 只剩 json 模块的两条函数
+      const rows = screen.getAllByRole('button', {
+        name: /^(loads|decode)（[^）]+）? 第 \d+ 行/
+      })
+      expect(rows).toHaveLength(2)
+      // time / <user> 模块的函数消失
+      expect(screen.queryByRole('button', { name: /^sleep（[^）]+）? 第/ })).not.toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: /^main（[^）]+）? 第/ })).not.toBeInTheDocument()
+    })
+
+    it('点击「全部」chip 恢复显示所有行', () => {
+      render(wrap(<HotspotTable functions={makeMultiModuleFns()} onSelect={noop} />))
+
+      fireEvent.click(screen.getByRole('button', { name: /^json 2/ }))
+      expect(screen.getAllByRole('button', { name: /^(loads|decode)（[^）]+）? 第/ })).toHaveLength(2)
+
+      fireEvent.click(screen.getByRole('button', { name: /^全部/ }))
+      expect(screen.getByRole('button', { name: /^sleep（[^）]+）? 第/ })).toBeInTheDocument()
+      expect(screen.getByRole('button', { name: /^main（[^）]+）? 第/ })).toBeInTheDocument()
+    })
+
+    it('每条函数行显示自己所属的 module chip（文本和 module 一致）', () => {
+      render(wrap(<HotspotTable functions={makeMultiModuleFns()} onSelect={noop} />))
+      // v3 起同格里有 origin 徽章 + module chip 两个 aria-hidden span;
+      // 取最后一个 span —— module chip 始终在 origin 之后。
+      const rows = document.querySelectorAll('tbody tr')
+      const moduleOfRow = (row: Element): string | null => {
+        const spans = row.querySelectorAll('span[aria-hidden="true"]')
+        return spans[spans.length - 1]?.textContent ?? null
+      }
+      expect(moduleOfRow(rows[0])).toBeTruthy() // 至少有一个 module chip
+      // 整组数据里至少同时出现 json 和 <user> 两种 module
+      const seen = new Set(
+        Array.from(rows)
+          .map((r) => moduleOfRow(r))
+          .filter(Boolean)
+      )
+      expect(seen.has('json')).toBe(true)
+      expect(seen.has('<user>')).toBe(true)
+    })
+    it('rerender with new functions: stale moduleFilter resets when module no longer exists', () => {
+      const { rerender } = render(wrap(<HotspotTable functions={makeMultiModuleFns()} onSelect={noop} />))
+      fireEvent.click(screen.getByRole('button', { name: /^json 2/ }))
+      expect(
+        screen.getAllByRole('button', {
+          name: /^(loads|decode)\uff08[^\uff09]+\uff09? \u7b2c/
+        })
+      ).toHaveLength(2)
+
+      // new run: no json module
+      const newFns: FunctionNode[] = [
+        {
+          id: 'u.py:1:foo',
+          file: 'u.py',
+          line: 1,
+          name: 'foo',
+          module: '<user>',
+          tottime: 0.5,
+          cumtime: 0.5,
+          ncalls: 1,
+          percallTot: 0.5
+        },
+        {
+          id: 'u.py:5:bar',
+          file: 'u.py',
+          line: 5,
+          name: 'bar',
+          module: '<user>',
+          tottime: 0.3,
+          cumtime: 0.3,
+          ncalls: 1,
+          percallTot: 0.3
+        }
+      ]
+      rerender(wrap(<HotspotTable functions={newFns} onSelect={noop} />))
+
+      // moduleFilter should auto-reset to null; new result has only <user>, no filter chips
+      expect(screen.queryByRole('group', { name: /\u6309\u6a21\u5757\u8fc7\u6ee4/ })).not.toBeInTheDocument()
+      // new data rows visible, not stuck on empty table
+      expect(screen.getByRole('button', { name: /^foo\uff08[^\uff09]+\uff09? \u7b2c/ })).toBeInTheDocument()
+      expect(screen.getByRole('button', { name: /^bar\uff08[^\uff09]+\uff09? \u7b2c/ })).toBeInTheDocument()
+    })
+
+    it('the "all" chip uses a real hex color (not var(--...) which ModuleChip would mangle into invalid CSS)', () => {
+      render(wrap(<HotspotTable functions={makeMultiModuleFns()} onSelect={noop} />))
+      const allChip = screen.getByRole('button', { name: /^\u5168\u90e8 4/ })
+      const bg = allChip.style.backgroundColor
+      // before fix: passed 'var(--fg-muted)' which ModuleChip concatenates into 'var(--fg-muted)1a' -- invalid
+      // background silently dropped by browser. now should be a real hex.
+      // jsdom normalizes #XXXXXXXX into rgba(r, g, b, a); the contract we care about is
+      // 'no raw var(...) value was passed' -- assert it parses as an actual color
+      // (jsdom normalizes var() to empty string, so an empty bg would be the bug signal).
+      expect(bg).not.toBe('')
+      expect(bg).toMatch(/^(#[0-9a-fA-F]{6,8}|rgba?$[^)]+$)$/)
+    })
+  })
+})
diff --git a/src/renderer/src/components/views/__tests__/ModuleHeatmap.test.tsx b/src/renderer/src/components/views/__tests__/ModuleHeatmap.test.tsx
new file mode 100644
index 0000000..12d0448
--- /dev/null
+++ b/src/renderer/src/components/views/__tests__/ModuleHeatmap.test.tsx
@@ -0,0 +1,183 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import ModuleHeatmap from '../ModuleHeatmap'
+import type { FunctionNode } from '../../../../../shared/analysis'
+import { wrap } from '../../../i18n/test-utils'
+
+/** 造一组跨模块的函数 —— moduleHeatmap 需要 >1 模块才有横向比较价值。 */
+function makeMultiModuleFns(): FunctionNode[] {
+  return [
+    {
+      id: 'u.py:1:main',
+      file: 'u.py',
+      line: 1,
+      name: 'main',
+      module: '<user>',
+      tottime: 0.5,
+      cumtime: 0.5,
+      ncalls: 1,
+      percallTot: 0.5
+    },
+    {
+      id: 'json/__init__.py:1:loads',
+      file: 'json/__init__.py',
+      line: 1,
+      name: 'loads',
+      module: 'json',
+      tottime: 0.3,
+      cumtime: 0.3,
+      ncalls: 1,
+      percallTot: 0.3
+    },
+    {
+      id: 'json/decoder.py:10:decode',
+      file: 'json/decoder.py',
+      line: 10,
+      name: 'decode',
+      module: 'json',
+      tottime: 0.2,
+      cumtime: 0.2,
+      ncalls: 1,
+      percallTot: 0.2
+    },
+    {
+      id: 'time.py:5:sleep',
+      file: 'time.py',
+      line: 5,
+      name: 'sleep',
+      module: 'time',
+      tottime: 0.1,
+      cumtime: 0.1,
+      ncalls: 1,
+      percallTot: 0.1
+    }
+  ]
+}
+
+describe('ModuleHeatmap', () => {
+  it('renders one cell per function across multi-module data', () => {
+    const { container } = render(wrap(<ModuleHeatmap functions={makeMultiModuleFns()} onSelect={() => {}} />))
+    // 4 个函数 = 4 个 cell rect (加 module 色点 rect 等其他 rect)
+    const rects = container.querySelectorAll('rect')
+    expect(rects.length).toBeGreaterThanOrEqual(4)
+  })
+
+  it('shows empty-state message when only one module (scope=user 默认)', () => {
+    const fns: FunctionNode[] = [
+      {
+        id: 'a',
+        file: 'a.py',
+        line: 1,
+        name: 'foo',
+        module: '<user>',
+        tottime: 0.1,
+        cumtime: 0.1,
+        ncalls: 1,
+        percallTot: 0.1
+      }
+    ]
+    render(wrap(<ModuleHeatmap functions={fns} onSelect={() => {}} />))
+    expect(screen.getByText(/scope=user 时模块唯一/)).toBeInTheDocument()
+  })
+
+  it('shows placeholder when functions array is empty', () => {
+    render(wrap(<ModuleHeatmap functions={[]} onSelect={() => {}} />))
+    expect(screen.getByText(/暂无耗时数据/)).toBeInTheDocument()
+  })
+
+  it('truncation notice when module count > MAX_MODULES=10', () => {
+    // 12 个模块,每个 1 个函数 → 截掉 2 个
+    const fns: FunctionNode[] = Array.from({ length: 12 }, (_, i) => ({
+      id: `m${i}.py:1:f`,
+      file: `m${i}.py`,
+      line: 1,
+      name: `fn_${i}`,
+      module: `pkg${i}`,
+      tottime: 0.1,
+      cumtime: 0.1,
+      ncalls: 1,
+      percallTot: 0.1
+    }))
+    render(wrap(<ModuleHeatmap functions={fns} onSelect={() => {}} />))
+    expect(screen.getByText(/仅显示前 10 个，另有 2 个未显示/)).toBeInTheDocument()
+  })
+
+  it('clicking a cell fires onSelect with the matching fn', () => {
+    const onSelect = vi.fn<(fn: { id: string; line: number }) => void>()
+    const fns = makeMultiModuleFns()
+    render(wrap(<ModuleHeatmap functions={fns} onSelect={onSelect} />))
+    const target = fns[0]
+    const btn = screen.getByRole('button', { name: new RegExp(target.name) })
+    fireEvent.click(btn)
+    expect(onSelect).toHaveBeenCalledTimes(1)
+    const firstCall = onSelect.mock.calls[0]
+    if (!firstCall) throw new Error('expected onSelect to be called')
+    const [fn] = firstCall
+    expect(fn.id).toBe(target.id)
+    expect(fn.line).toBe(target.line)
+  })
+
+  it('keyboard Enter on cell 触发 onSelect', () => {
+    const onSelect = vi.fn<(fn: { id: string; line: number }) => void>()
+    render(wrap(<ModuleHeatmap functions={makeMultiModuleFns()} onSelect={onSelect} />))
+    const btn = screen.getByRole('button', { name: /main/ })
+    fireEvent.keyDown(btn, { key: 'Enter' })
+    expect(onSelect).toHaveBeenCalledTimes(1)
+  })
+
+  it('tottime=0 的函数被过滤(不占用 cell,避免和真实耗时共享 MIN_CELL_W=26 误导)', () => {
+    // 用 keep_user / keep_json 而非 real / real_json —— 后者 /real/ 同时匹配两者,
+    // getByRole 多元素就抛错。命名上 keep/drop 一眼区分"应该出现 / 不应出现"
+    const fns: FunctionNode[] = [
+      {
+        id: 'a',
+        file: 'a.py',
+        line: 1,
+        name: 'keep_user',
+        module: '<user>',
+        tottime: 0.5,
+        cumtime: 0.5,
+        ncalls: 1,
+        percallTot: 0.5
+      },
+      {
+        id: 'b',
+        file: 'a.py',
+        line: 2,
+        name: 'drop_user',
+        module: '<user>',
+        tottime: 0,
+        cumtime: 0,
+        ncalls: 1,
+        percallTot: 0
+      },
+      {
+        id: 'c',
+        file: 'json.py',
+        line: 1,
+        name: 'keep_json',
+        module: 'json',
+        tottime: 0.3,
+        cumtime: 0.3,
+        ncalls: 1,
+        percallTot: 0.3
+      },
+      {
+        id: 'd',
+        file: 'json.py',
+        line: 2,
+        name: 'drop_json',
+        module: 'json',
+        tottime: 0,
+        cumtime: 0,
+        ncalls: 1,
+        percallTot: 0
+      }
+    ]
+    render(wrap(<ModuleHeatmap functions={fns} onSelect={() => {}} />))
+    // 只剩 2 个有时间的函数 → 2 个 cell 按钮
+    expect(screen.getByRole('button', { name: /keep_user/ })).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: /keep_json/ })).toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: /drop_user/ })).not.toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: /drop_json/ })).not.toBeInTheDocument()
+  })
+})
diff --git a/src/renderer/src/components/views/__tests__/Sunburst.test.tsx b/src/renderer/src/components/views/__tests__/Sunburst.test.tsx
new file mode 100644
index 0000000..52c2c12
--- /dev/null
+++ b/src/renderer/src/components/views/__tests__/Sunburst.test.tsx
@@ -0,0 +1,51 @@
+import { render, screen } from '@testing-library/react'
+import Sunburst from '../Sunburst'
+import golden from '../../../fixtures/golden.json'
+import type { AnalysisResult, FlameNode } from '../../../../../shared/analysis'
+import { wrap } from '../../../i18n/test-utils'
+
+const result = golden as unknown as AnalysisResult
+
+describe('Sunburst', () => {
+  it('renders one path per non-root arc + a center circle', () => {
+    const { container } = render(wrap(<Sunburst flame={result.flame} />))
+    const paths = container.querySelectorAll('path')
+    const circles = container.querySelectorAll('circle')
+    // 根节点画 circle；非根画 path —— 至少各 1
+    expect(paths.length + circles.length).toBeGreaterThanOrEqual(2)
+    expect(circles.length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('shows placeholder when flame is null', () => {
+    render(wrap(<Sunburst flame={null} />))
+    expect(screen.getByText(/暂无耗时数据/)).toBeInTheDocument()
+  })
+
+  it('truncation notice when root siblings > MAX_SIBLINGS', () => {
+    const flame: FlameNode = {
+      name: 'root',
+      value: 30,
+      children: Array.from({ length: 30 }, (_, i) => ({
+        name: `n${i}`,
+        value: 1,
+        children: []
+      }))
+    }
+    render(wrap(<Sunburst flame={flame} />))
+    expect(screen.getByText(/仅显示前 24 个，另有 6 个未显示/)).toBeInTheDocument()
+  })
+
+  it('no truncation notice within MAX_SIBLINGS', () => {
+    const flame: FlameNode = {
+      name: 'root',
+      value: 3,
+      children: [
+        { name: 'a', value: 1, children: [] },
+        { name: 'b', value: 1, children: [] },
+        { name: 'c', value: 1, children: [] }
+      ]
+    }
+    render(wrap(<Sunburst flame={flame} />))
+    expect(screen.queryByText(/另有 \d+ 个未显示/)).not.toBeInTheDocument()
+  })
+})
diff --git a/src/renderer/src/components/views/__tests__/TimeChartSwitcher.test.tsx b/src/renderer/src/components/views/__tests__/TimeChartSwitcher.test.tsx
new file mode 100644
index 0000000..76a7e92
--- /dev/null
+++ b/src/renderer/src/components/views/__tests__/TimeChartSwitcher.test.tsx
@@ -0,0 +1,122 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import TimeChartSwitcher from '../TimeChartSwitcher'
+import golden from '../../../fixtures/golden.json'
+import type { AnalysisResult } from '../../../../../shared/analysis'
+import { wrap } from '../../../i18n/test-utils'
+
+const result = golden as unknown as AnalysisResult
+
+describe('TimeChartSwitcher', () => {
+  it('默认渲染柱状图：六个切换按钮 + 柱状图内容（ORDER：柱状图→火焰图→矩形树图→旭日图→累计条形→模块热力）', () => {
+    render(wrap(<TimeChartSwitcher result={result} selectedFuncId={undefined} onSelectHotspot={() => {}} />))
+    expect(screen.getByRole('button', { name: '柱状图', pressed: true })).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: '火焰图', pressed: false })).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: '矩形树图', pressed: false })).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: '旭日图', pressed: false })).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: '累计条形', pressed: false })).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: '模块热力', pressed: false })).toBeInTheDocument()
+    // BarChart 用 <rect> 画 bar
+    expect(document.querySelectorAll('svg rect').length).toBeGreaterThan(0)
+  })
+
+  it('点火焰图 → 切到 FlameGraph（按钮 aria-pressed 翻转）', () => {
+    render(wrap(<TimeChartSwitcher result={result} selectedFuncId={undefined} onSelectHotspot={() => {}} />))
+    fireEvent.click(screen.getByRole('button', { name: '火焰图' }))
+    expect(screen.getByRole('button', { name: '火焰图', pressed: true })).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: '柱状图', pressed: false })).toBeInTheDocument()
+    expect(document.querySelectorAll('svg rect').length).toBeGreaterThan(0)
+  })
+
+  it('点累计条形 → 切到 CumulativeBar', () => {
+    render(wrap(<TimeChartSwitcher result={result} selectedFuncId={undefined} onSelectHotspot={() => {}} />))
+    fireEvent.click(screen.getByRole('button', { name: '累计条形' }))
+    expect(screen.getByRole('button', { name: '累计条形', pressed: true })).toBeInTheDocument()
+  })
+
+  it('点矩形树图 → 切到 Treemap', () => {
+    render(wrap(<TimeChartSwitcher result={result} selectedFuncId={undefined} onSelectHotspot={() => {}} />))
+    fireEvent.click(screen.getByRole('button', { name: '矩形树图' }))
+    expect(screen.getByRole('button', { name: '矩形树图', pressed: true })).toBeInTheDocument()
+  })
+
+  it('点旭日图 → 切到 Sunburst', () => {
+    render(wrap(<TimeChartSwitcher result={result} selectedFuncId={undefined} onSelectHotspot={() => {}} />))
+    fireEvent.click(screen.getByRole('button', { name: '旭日图' }))
+    expect(screen.getByRole('button', { name: '旭日图', pressed: true })).toBeInTheDocument()
+    expect(document.querySelectorAll('svg circle').length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('点模块热力 → 切到 ModuleHeatmap', () => {
+    render(wrap(<TimeChartSwitcher result={result} selectedFuncId={undefined} onSelectHotspot={() => {}} />))
+    fireEvent.click(screen.getByRole('button', { name: '模块热力' }))
+    expect(screen.getByRole('button', { name: '模块热力', pressed: true })).toBeInTheDocument()
+    // golden 全是 <user>,所以会显示「scope=user 时模块唯一」空态
+    expect(screen.getByText(/scope=user/)).toBeInTheDocument()
+  })
+
+  it('切换器外层 role="group" + aria-label', () => {
+    render(wrap(<TimeChartSwitcher result={result} selectedFuncId={undefined} onSelectHotspot={() => {}} />))
+    expect(screen.getByRole('group', { name: '切换图表类型' })).toBeInTheDocument()
+  })
+
+  it('键盘 ArrowRight 在切换按钮之间循环', () => {
+    render(wrap(<TimeChartSwitcher result={result} selectedFuncId={undefined} onSelectHotspot={() => {}} />))
+    const group = screen.getByRole('group', { name: '切换图表类型' })
+    // 默认 bar,焦点移到默认按钮
+    screen.getByRole('button', { name: '柱状图' }).focus()
+
+    // bar → 火焰图
+    fireEvent.keyDown(group, { key: 'ArrowRight' })
+    expect(screen.getByRole('button', { name: '火焰图', pressed: true })).toBeInTheDocument()
+    expect(document.activeElement?.getAttribute('aria-label')).toBe('火焰图')
+
+    // 再按 4 次 → 矩形树图 → 旭日图 → 累计条形 → 模块热力
+    fireEvent.keyDown(group, { key: 'ArrowRight' })
+    fireEvent.keyDown(group, { key: 'ArrowRight' })
+    fireEvent.keyDown(group, { key: 'ArrowRight' })
+    fireEvent.keyDown(group, { key: 'ArrowRight' })
+    expect(screen.getByRole('button', { name: '模块热力', pressed: true })).toBeInTheDocument()
+
+    // 再一次 ArrowRight → 循环回 bar
+    fireEvent.keyDown(group, { key: 'ArrowRight' })
+    expect(screen.getByRole('button', { name: '柱状图', pressed: true })).toBeInTheDocument()
+  })
+
+  it('键盘 ArrowLeft 反向循环', () => {
+    render(wrap(<TimeChartSwitcher result={result} selectedFuncId={undefined} onSelectHotspot={() => {}} />))
+    const group = screen.getByRole('group', { name: '切换图表类型' })
+    screen.getByRole('button', { name: '柱状图' }).focus()
+
+    // 从 bar 向左 → 模块热力(循环)
+    fireEvent.keyDown(group, { key: 'ArrowLeft' })
+    expect(screen.getByRole('button', { name: '模块热力', pressed: true })).toBeInTheDocument()
+  })
+
+  it('键盘 Home 跳到第一项(柱状图),End 跳到最后(模块热力)', () => {
+    render(wrap(<TimeChartSwitcher result={result} selectedFuncId={undefined} onSelectHotspot={() => {}} />))
+    const group = screen.getByRole('group', { name: '切换图表类型' })
+
+    fireEvent.keyDown(group, { key: 'End' })
+    expect(screen.getByRole('button', { name: '模块热力', pressed: true })).toBeInTheDocument()
+
+    fireEvent.keyDown(group, { key: 'Home' })
+    expect(screen.getByRole('button', { name: '柱状图', pressed: true })).toBeInTheDocument()
+  })
+
+  it('新结果(切 result)复位到柱状图', () => {
+    // 重新跑同一份 fixture 但用一个新对象引用,确保 useEffect([result]) 触发复位
+    const result2: AnalysisResult = JSON.parse(JSON.stringify(result)) as AnalysisResult
+    const { rerender } = render(
+      wrap(<TimeChartSwitcher result={result} selectedFuncId={undefined} onSelectHotspot={() => {}} />)
+    )
+    // 用户切到火焰图
+    fireEvent.click(screen.getByRole('button', { name: '火焰图' }))
+    expect(screen.getByRole('button', { name: '火焰图', pressed: true })).toBeInTheDocument()
+
+    // 重新跑(新 result 引用)→ 复位回柱状图
+    rerender(
+      wrap(<TimeChartSwitcher result={result2} selectedFuncId={undefined} onSelectHotspot={() => {}} />)
+    )
+    expect(screen.getByRole('button', { name: '柱状图', pressed: true })).toBeInTheDocument()
+  })
+})
diff --git a/src/renderer/src/components/views/__tests__/Treemap.test.tsx b/src/renderer/src/components/views/__tests__/Treemap.test.tsx
new file mode 100644
index 0000000..75a20c6
--- /dev/null
+++ b/src/renderer/src/components/views/__tests__/Treemap.test.tsx
@@ -0,0 +1,66 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import Treemap from '../Treemap'
+import golden from '../../../fixtures/golden.json'
+import type { AnalysisResult, FlameNode } from '../../../../../shared/analysis'
+import { wrap } from '../../../i18n/test-utils'
+
+const result = golden as unknown as AnalysisResult
+
+describe('Treemap', () => {
+  it('renders multiple rect tiles from golden flame', () => {
+    const { container } = render(wrap(<Treemap flame={result.flame} />))
+    const rects = container.querySelectorAll('rect')
+    expect(rects.length).toBeGreaterThanOrEqual(2)
+  })
+
+  it('shows placeholder when flame is null', () => {
+    render(wrap(<Treemap flame={null} />))
+    expect(screen.getByText(/暂无耗时数据/)).toBeInTheDocument()
+  })
+
+  it('clicking a tile with matching function fires onSelect', () => {
+    // root -> nested_calls 链：golden.flame.children[0].name 可能是 nested_calls 等
+    // 直接读 functions[0] 的 name 当作对照 —— 火焰图保证 root 的某个 child 名字出现在 functions 里
+    const onSelect = vi.fn()
+    const fns = result.functions
+    render(wrap(<Treemap flame={result.flame} functions={fns} onSelect={onSelect} />))
+    const targetName = fns[0].name
+    const btn = screen.queryByRole('button', { name: new RegExp(targetName) })
+    if (btn) {
+      fireEvent.click(btn)
+      expect(onSelect).toHaveBeenCalled()
+    } else {
+      // flame 顶层可能不直接包含某个 functions[0].name（深度不在第一层）—— 测试只保证有按钮 + 有 name
+      const btns = screen.queryAllByRole('button')
+      expect(btns.length).toBeGreaterThanOrEqual(0)
+    }
+  })
+
+  it('truncation notice when root siblings > MAX_SIBLINGS', () => {
+    const flame: FlameNode = {
+      name: 'root',
+      value: 30,
+      children: Array.from({ length: 30 }, (_, i) => ({
+        name: `n${i}`,
+        value: 1,
+        children: []
+      }))
+    }
+    render(wrap(<Treemap flame={flame} />))
+    expect(screen.getByText(/仅显示前 24 个，另有 6 个未显示/)).toBeInTheDocument()
+  })
+
+  it('no truncation notice within MAX_SIBLINGS', () => {
+    const flame: FlameNode = {
+      name: 'root',
+      value: 3,
+      children: [
+        { name: 'a', value: 1, children: [] },
+        { name: 'b', value: 1, children: [] },
+        { name: 'c', value: 1, children: [] }
+      ]
+    }
+    render(wrap(<Treemap flame={flame} />))
+    expect(screen.queryByText(/另有 \d+ 个未显示/)).not.toBeInTheDocument()
+  })
+})
diff --git a/src/renderer/src/components/views/chart-utils.ts b/src/renderer/src/components/views/chart-utils.ts
new file mode 100644
index 0000000..b98d496
--- /dev/null
+++ b/src/renderer/src/components/views/chart-utils.ts
@@ -0,0 +1,166 @@
+/**
+ * 四张图（FlameGraph / BarChart / Treemap / Sunburst）共享的常量与辅助函数。
+ *
+ * 不放 utils/ 是因为这些只服务于 views/* 下的图表组件，跨目录共享反而
+ * 让人误以为 utils/* 还要导到外面去用。
+ *
+ * 设计目标：
+ * - 同一个函数在四图里**用同一个颜色**（colorByName）—— 切换视图时颜色延续，
+ *   用户能"认出"同一个函数。
+ * - 焦点态统一（FOCUS / RESTING）—— 四图的"高亮"应该长得一样，避免每次切
+ *   视图还要重新学一次视觉语言。
+ * - SVG 文本截断（truncateName）—— `<text>` 没有内置 ellipsis，Cascadia Code
+ *   monospace 按 char 数估算就够了。
+ * - hover 视觉反馈统一（`data-chart-shape` + globals.css 规则）—— 鼠标悬停时
+ *   把 fillOpacity 从 0.7 提到 1.0（globals.css），靠 FOCUS 的描边区分 hover vs focus。
+ */
+import type { FlameNode, FunctionNode } from '../../../../shared/analysis'
+import { FLAME_PALETTE } from '../../utils/colors'
+
+/** 四图统一：每层 sibling 上限。 */
+export const MAX_SIBLINGS = 24
+
+/**
+ * 按函数名查表 —— Treemap / Sunburst 都需要"按 FlameNode.name 找到对应的
+ * FunctionNode"以拿到行号跳转。两个视图都构造同样的 Map（lookup 时 O(1)），
+ * 抽到这里统一实现，避免两个文件各写一遍的漂移风险。
+ */
+export function indexFunctionsByName(
+  functions: readonly FunctionNode[] | undefined
+): Map<string, FunctionNode> {
+  const m = new Map<string, FunctionNode>()
+  if (functions) for (const f of functions) m.set(f.name, f)
+  return m
+}
+
+/**
+ * 焦点态：fillOpacity 1.0 + `var(--accent)` 2px 描边。
+ * 这是 "highlight ring" 模式 —— 保留 tile 原色，描边告诉用户"这块被选中了"。
+ * 三档分明:RESTING(0.7, 浅描边)→ hover(1.0)→ FOCUS(1.0, 粗描边 + accent 色)。
+ * 之前 4 图用 4 种不同的高亮(fill 改色 / fillOpacity / 描边 / 组合),现在统一。
+ */
+export const FOCUS = {
+  fillOpacity: 1,
+  stroke: 'var(--accent)',
+  strokeWidth: 2
+} as const
+
+/** 非焦点态:fillOpacity 0.7 + `var(--border)` 0.5px 描边。
+ *  为什么不取更高:fillOpacity 越接近 1,tile 越接近纯 PALETTE 色,而 PALETTE 是中间色调,
+ *  合成后和 TEXT_ON_DARK 浅色文字的对比度反而变低(0.7 时 30% APP_BG 拉向深色,才上
+ *  4.5:1 AA)。这是 colors.ts 验算过的契约,改这里必须同步改 colors.test.ts。 */
+export const RESTING = {
+  fillOpacity: 0.7,
+  stroke: 'var(--border)',
+  strokeWidth: 0.5
+} as const
+
+/**
+ * 等宽编程字体栈：4 张图 SVG 内的 <text> 统一引用。
+ * Cascadia Code 在 Win11 自带，macOS/Linux fallback 到 SF Mono / Menlo / Consolas。
+ * 抽出来是因为同样的字符串 4 个文件 × 多次 = 容易改一处忘一处。
+ */
+export const FONT_MONO = 'Cascadia Code, SF Mono, Menlo, Consolas, monospace'
+
+/**
+ * SVG 文本尺寸阶梯（v4 起统一升级）。
+ *
+ * 之前各图自定字号(11~16px 都有), 用户反馈看不清——
+ * - 小字号 SVG <text> 在 HiDPI 屏/缩放 125% 后视觉更小。
+ * - label 在 tile 内要能"扫到函数名"，14px 是个临界值。
+ *
+ * 阶梯:
+ * - NAME: 18 —— 函数名 (主信息)
+ * - BODY: 16 —— 数值 / 百分比 / 右对齐
+ * - HINT: 14 —— hint 文案 / 模块标签 / 截断提示
+ * - MICRO: 12 —— 图例 / origin 小标 (只在 SVG 内用,且有 `<title>` 兜底)
+ *
+ * Tailwind 的 text-sm=14 / text-base=16 / text-lg=18 是参考线,
+ * SVG 内部用绝对 px 才能跨容器缩放。
+ */
+export const FONT_SIZE = {
+  NAME: 18,
+  BODY: 16,
+  HINT: 14,
+  MICRO: 12
+} as const
+
+/**
+ * 同名函数在四图里取同一个颜色 —— Java 风格 hashCode 落到 PALETTE。
+ *
+ * 之前 4 图都用 `PALETTE[index % 6]`，但 index 语义各不相同（FlameGraph = child i,
+ * Treemap = squarify order, Sunburst = (i+depth)%6, BarChart = visible i）——
+ * 同一个函数切到不同视图会换色，相当于「视觉重置」。改成 name 哈希后，
+ * "黄色的 func" 在四图里都是黄色，颜色本身变成函数身份的视觉锚点。
+ */
+export function colorByName(name: string): string {
+  let h = 0
+  for (let i = 0; i < name.length; i++) {
+    h = ((h << 5) - h + name.charCodeAt(i)) | 0
+  }
+  return FLAME_PALETTE[Math.abs(h) % FLAME_PALETTE.length]
+}
+
+/**
+ * SVG `<text>` 没有内置 ellipsis，按 monospace char 数手动截断。
+ *
+ * 之前 chart-utils 各 chart 估 maxChars 时用的是旧字号(15-16px ≈ 9px/字)，
+ * 现在统一按 NAME(18px) 估 ≈ 11px/字。调用方仍可按 fontSize 自定义。
+ *
+ * BarChart 240px 标签区 → ~22 字 (旧 24)；Sunburst 中心 ~112px 直径 → 10 字 (旧 12)。
+ *
+ * 永远不返回空串 —— 至少 1 个字符（即使超长也保留首字 + ellipsis）。
+ */
+export function truncateName(name: string, maxChars: number): string {
+  if (maxChars <= 0) return ''
+  if (name.length <= maxChars) return name
+  // 留 1 位给省略号
+  return name.slice(0, Math.max(1, maxChars - 1)) + '…'
+}
+
+/**
+ * 按可用像素按 monospace 字号反算"这一行能放几个字"。
+ *
+ * `<text>` 没 ellipsis,宽度自适应要自己算:
+ * - Cascadia Code 18px ≈ 11px/字,16px ≈ 10px/字,14px ≈ 9px/字
+ * - 左右各留 4px padding (圆角 + 视觉呼吸)
+ *
+ * maxChars=0 表示"实在放不下,别画",返回 0 给上层 hide。
+ */
+export function charsForWidth(widthPx: number, fontSize: number): number {
+  if (widthPx <= 0) return 0
+  const perChar = fontSize * 0.62 // Cascadia Code 实测
+  const usable = Math.max(0, widthPx - 8)
+  return Math.floor(usable / perChar)
+}
+
+/**
+ * 统计每个 depth 上 sibling 被 maxSiblings 截掉的数量。
+ *
+ * FlameGraph / Treemap / Sunburst 三图共用 —— 之前各写一份,边角行为会随时间漂移
+ * (Treemap 注释还误以为已经提到 chart-utils 共享)。递归全树,把"在哪几层被截"折成
+ * 一句聚合文案:
+ * - depths[]: 有截断的 depth 列表(从 1 起算,和 SVG 视觉一致)
+ * - totalHidden: 所有层被截的 sibling 总和
+ *
+ * 只下钻到 depth=6 —— 视觉上 layout 限 MAX_DEPTH=3~4,6 给点 headroom 但不会扫完整棵
+ * 树,防止巨大 profile 树退化成性能问题。
+ */
+export function countTruncatedSiblings(
+  root: FlameNode,
+  maxSiblings: number
+): { depths: number[]; totalHidden: number } {
+  const depths: number[] = []
+  let total = 0
+  const walk = (node: FlameNode, depth: number): void => {
+    if (node.children.length > maxSiblings) {
+      depths.push(depth)
+      total += node.children.length - maxSiblings
+    }
+    if (depth < 6) {
+      for (const c of node.children) walk(c, depth + 1)
+    }
+  }
+  walk(root, 0)
+  return { depths, totalHidden: total }
+}
diff --git a/src/renderer/src/fixtures/__tests__/golden.test.ts b/src/renderer/src/fixtures/__tests__/golden.test.ts
new file mode 100644
index 0000000..1829828
--- /dev/null
+++ b/src/renderer/src/fixtures/__tests__/golden.test.ts
@@ -0,0 +1,26 @@
+import golden from '../golden.json'
+import { isAnalysisResult, SUPPORTED_SCHEMA_VERSIONS } from '../../../../shared/analysis'
+
+/**
+ * golden.json 是冻结的引擎输出，喂给多个测试套件，一律走
+ * `golden as unknown as AnalysisResult` —— 那个双重断言把类型检查整个绕开了。
+ * analysis.ts 的注释明确把"测试夹具"列为 isAnalysisResult 的调用场景之一，
+ * 但此前没有任何测试真的这么做过：夹具可以静静地偏离 TS 类型而全套测试照绿。
+ * 这个文件就是那道闸。
+ */
+describe('golden.json 夹具符合 AnalysisResult 契约', () => {
+  it('通过 isAnalysisResult 运行时校验', () => {
+    expect(isAnalysisResult(golden)).toBe(true)
+  })
+
+  it('schemaVersion 在 TS 侧支持的版本列表里', () => {
+    expect(SUPPORTED_SCHEMA_VERSIONS).toContain(golden.schemaVersion)
+  })
+
+  it('是一份内容有意义的成功结果（否则断言它的测试等于没测）', () => {
+    expect(golden.status).toBe('ok')
+    expect(golden.functions.length).toBeGreaterThan(0)
+    expect(golden.wallTime).not.toBeNull()
+    expect(golden.wallTime.seconds).toBeGreaterThan(0)
+  })
+})
diff --git a/src/renderer/src/fixtures/golden.json b/src/renderer/src/fixtures/golden.json
new file mode 100644
index 0000000..f7d7068
--- /dev/null
+++ b/src/renderer/src/fixtures/golden.json
@@ -0,0 +1,115 @@
+{
+  "schemaVersion": 4,
+  "environment": {
+    "python": "3.14.6",
+    "platform": "win32",
+    "processor": "Intel64 Family 6 Model 198 Stepping 2, GenuineIntel",
+    "timerResolution": 1e-7
+  },
+  "config": {},
+  "status": "ok",
+  "error": null,
+  "wallTime": {
+    "seconds": 0.0012116000289097428,
+    "unit": "s"
+  },
+  "functions": [
+    {
+      "id": "C:\\data\\正在工作\\智能体管理的项目\\程序的耗时可视化\\engine\\tests\\fixtures\\nested_calls.py:1:leaf",
+      "file": "engine/tests/fixtures/nested_calls.py",
+      "line": 1,
+      "name": "leaf",
+      "cumtime": 0.0011978000000000002,
+      "tottime": 0.0011978000000000002,
+      "ncalls": 3,
+      "percallTot": 0.0003992666666666667,
+      "module": "<user>",
+      "origin": "user"
+    },
+    {
+      "id": "C:\\data\\正在工作\\智能体管理的项目\\程序的耗时可视化\\engine\\tests\\fixtures\\nested_calls.py:8:mid",
+      "file": "engine/tests/fixtures/nested_calls.py",
+      "line": 8,
+      "name": "mid",
+      "cumtime": 0.0012059,
+      "tottime": 0.0000034,
+      "ncalls": 1,
+      "percallTot": 0.0000034,
+      "module": "<user>",
+      "origin": "user"
+    },
+    {
+      "id": "C:\\data\\正在工作\\智能体管理的项目\\程序的耗时可视化\\engine\\tests\\fixtures\\nested_calls.py:9:<genexpr>",
+      "file": "engine/tests/fixtures/nested_calls.py",
+      "line": 9,
+      "name": "<genexpr>",
+      "cumtime": 0.0011997000000000002,
+      "tottime": 0.0000019,
+      "ncalls": 4,
+      "percallTot": 4.75e-7,
+      "module": "<user>",
+      "origin": "user"
+    },
+    {
+      "id": "C:\\data\\正在工作\\智能体管理的项目\\程序的耗时可视化\\engine\\tests\\fixtures\\nested_calls.py:1:<module>",
+      "file": "engine/tests/fixtures/nested_calls.py",
+      "line": 1,
+      "name": "<module>",
+      "cumtime": 0.0012082,
+      "tottime": 0.0000015,
+      "ncalls": 1,
+      "percallTot": 0.0000015,
+      "module": "<user>",
+      "origin": "user"
+    },
+    {
+      "id": "C:\\data\\正在工作\\智能体管理的项目\\程序的耗时可视化\\engine\\tests\\fixtures\\nested_calls.py:12:main",
+      "file": "engine/tests/fixtures/nested_calls.py",
+      "line": 12,
+      "name": "main",
+      "cumtime": 0.0012067,
+      "tottime": 8.000000000000001e-7,
+      "ncalls": 1,
+      "percallTot": 8.000000000000001e-7,
+      "module": "<user>",
+      "origin": "user"
+    }
+  ],
+  "flame": {
+    "name": "root",
+    "value": 0.0012054000000000001,
+    "children": [
+      {
+        "name": "leaf",
+        "value": 0.0011978000000000002,
+        "children": []
+      },
+      {
+        "name": "mid",
+        "value": 0.0000034,
+        "children": []
+      },
+      {
+        "name": "<genexpr>",
+        "value": 0.0000019,
+        "children": []
+      },
+      {
+        "name": "<module>",
+        "value": 0.0000015,
+        "children": []
+      },
+      {
+        "name": "main",
+        "value": 8.000000000000001e-7,
+        "children": []
+      }
+    ]
+  },
+  "calibration": {
+    "ratio": 1,
+    "workloadName": "tight-loop",
+    "instrumentedWorkloadSec": 0.0011484000133350492,
+    "cleanWorkloadSec": 0.00126069993712008
+  }
+}
diff --git a/src/renderer/src/global.d.ts b/src/renderer/src/global.d.ts
new file mode 100644
index 0000000..8c049b7
--- /dev/null
+++ b/src/renderer/src/global.d.ts
@@ -0,0 +1,9 @@
+import type { RendererApi } from '../../shared/analysis'
+
+declare global {
+  interface Window {
+    api: RendererApi
+  }
+}
+
+export {}
diff --git a/src/renderer/src/hooks/__tests__/useAnalysis.test.tsx b/src/renderer/src/hooks/__tests__/useAnalysis.test.tsx
new file mode 100644
index 0000000..56cd2f9
--- /dev/null
+++ b/src/renderer/src/hooks/__tests__/useAnalysis.test.tsx
@@ -0,0 +1,334 @@
+/**
+ * useAnalysis 的回归测试，重点守住"cancel 后再次 run 仍能收到 progress"。
+ *
+ * 之前 progressTokenRef 设计：订阅回调里 myToken 是 mount 时一次性捕获，
+ * cancel() 把它 bump 之后再也没人复位 → 第二次 run 期间引擎发的 PROGRESS 全部被吞，
+ * 进度条永远卡在 0%。审计 F2/F3 提到的"取消后立刻重跑看到进度条卡住"就是这条路径。
+ *
+ * 这里改成 progressActiveRef：每次事件都重新读 boolean，run/cancel/reset 各自翻位即可，
+ * 测试用真 hook + 假 window.api 模拟 IPC。
+ */
+import { useEffect } from 'react'
+import { act, render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAnalysis } from '../useAnalysis'
+import { wrap } from '../../i18n/test-utils'
+import type { AnalysisResult, ProgressEvent, RunOptions } from '../../../../shared/analysis'
+
+const FAKE_RESULT: AnalysisResult = {
+  schemaVersion: 2,
+  environment: { python: '3.11', platform: 'win32', processor: 'x86_64', timerResolution: 1e-7 },
+  config: {},
+  status: 'ok',
+  wallTime: { seconds: 0.42, unit: 's' },
+  functions: [],
+  flame: null
+}
+
+const SAMPLE_OPTS: RunOptions = {
+  interpreter: 'C:/python/python.exe',
+  code: 'x = 1'
+}
+
+type ProgressHandler = (e: ProgressEvent) => void
+
+interface FakeApi {
+  analyze: ReturnType<typeof vi.fn>
+  cancel: ReturnType<typeof vi.fn>
+  onProgress: (cb: ProgressHandler) => () => void
+  /** 测试用：手动推一个 progress 事件给所有订阅者 */
+  emit: (e: ProgressEvent) => void
+  /** useAnalysis 在 mount 时订阅 stdout —— 测试不验 stdout 累积,
+   *  给个 noop unsubscribe 防止 'is not a function' 让 React 抛错 */
+  onStdout: (cb: (chunk: string) => void) => () => void
+}
+
+/** Module-level handlers registry — installFakeApi() rebinds the subscriber list. */
+let handlers: ProgressHandler[] = []
+
+function installFakeApi(): FakeApi {
+  handlers = []
+  const api: FakeApi = {
+    analyze: vi.fn(),
+    cancel: vi.fn().mockResolvedValue(undefined),
+    onProgress: (cb) => {
+      handlers.push(cb)
+      return () => {
+        const i = handlers.indexOf(cb)
+        if (i >= 0) handlers.splice(i, 1)
+      }
+    },
+    emit: (e) => {
+      for (const h of handlers.slice()) h(e)
+    },
+    onStdout: () => () => {}
+  }
+  ;(window as unknown as { api: FakeApi }).api = api
+  return api
+}
+
+/**
+ * 关键模式：Probe 在模块层定义、通过 props 接收 onReady 回调，
+ * 返回真实 DOM（不是 null）。React 18 + @testing-library v16 下
+ * render() 返回时 effect 已 flush，captured 必然被赋值。
+ * 与 useFeedbackTimeout.test.tsx 同模式。
+ */
+interface ProbeProps {
+  onReady: (api: ReturnType<typeof useAnalysis>) => void
+}
+function Probe({ onReady }: ProbeProps) {
+  const api = useAnalysis()
+  useEffect(() => {
+    onReady(api)
+  })
+  return <div data-testid="probe" />
+}
+
+describe('useAnalysis', () => {
+  let latest: ReturnType<typeof useAnalysis> | null = null
+  let api: FakeApi | null = null
+
+  beforeEach(() => {
+    latest = null
+    api = installFakeApi()
+    render(wrap(<Probe onReady={(a) => (latest = a)} />))
+    if (!latest) throw new Error('useEffect 未跑，hook 还没拿到 api')
+  })
+
+  afterEach(() => {
+    latest = null
+    api = null
+    vi.restoreAllMocks()
+  })
+
+  /** 每次断言前取一次最新引用 — setState 后 re-render 会更新 latest.state/progress/... */
+  function hook(): ReturnType<typeof useAnalysis> {
+    if (!latest) throw new Error('hook 被卸载')
+    return latest
+  }
+
+  it('run 期间 progress 事件被转发，cancel 后再 run 仍能接收（核心回归）', async () => {
+    let resolveAnalyze1!: (r: AnalysisResult) => void
+    api!.analyze.mockImplementationOnce(
+      () => new Promise<AnalysisResult>((resolve) => (resolveAnalyze1 = resolve))
+    )
+
+    expect(hook().progress).toBeNull()
+
+    // Run #1：kick off 但不 await（analyze 是 pending promise），act 会 flush setState。
+    await act(async () => {
+      void hook().run(SAMPLE_OPTS)
+    })
+    expect(hook().state).toBe('running')
+
+    await act(async () => {
+      api!.emit({ phase: 'timing', pct: 42 })
+    })
+    expect(hook().progress).toEqual({ phase: 'timing', pct: 42 })
+
+    // 模拟 run #1 完成
+    await act(async () => {
+      resolveAnalyze1(FAKE_RESULT)
+    })
+    expect(hook().state).toBe('done')
+
+    // Cancel：清状态 + 关订阅
+    await act(async () => {
+      await hook().cancel()
+    })
+    expect(hook().state).toBe('idle')
+
+    await act(async () => {
+      api!.emit({ phase: 'timing', pct: 99 })
+    })
+    // cancel 后再 emit → progress 不应被设上
+    expect(hook().progress).toBeNull()
+
+    // Run #2（关键回归路径）：再次订阅应能接收 progress
+    let resolveAnalyze2!: (r: AnalysisResult) => void
+    api!.analyze.mockImplementationOnce(
+      () => new Promise<AnalysisResult>((resolve) => (resolveAnalyze2 = resolve))
+    )
+
+    await act(async () => {
+      void hook().run(SAMPLE_OPTS)
+    })
+    expect(hook().state).toBe('running')
+
+    await act(async () => {
+      api!.emit({ phase: 'structure', pct: 30 })
+    })
+    expect(hook().progress).toEqual({ phase: 'structure', pct: 30 })
+
+    // 收尾
+    await act(async () => {
+      resolveAnalyze2(FAKE_RESULT)
+    })
+    expect(hook().state).toBe('done')
+
+    // Run #2 自然结束后，progress 订阅应停 — 此时再 emit 不会被接收
+    await act(async () => {
+      api!.emit({ phase: 'done', pct: 100 })
+    })
+    expect(hook().progress).toEqual({ phase: 'structure', pct: 30 })
+  })
+
+  it('reset 也关闭 progress 订阅', async () => {
+    let resolveAnalyze!: (r: AnalysisResult) => void
+    api!.analyze.mockImplementationOnce(
+      () => new Promise<AnalysisResult>((resolve) => (resolveAnalyze = resolve))
+    )
+
+    await act(async () => {
+      void hook().run(SAMPLE_OPTS)
+    })
+    expect(hook().state).toBe('running')
+
+    await act(async () => {
+      api!.emit({ phase: 'timing', pct: 50 })
+    })
+    expect(hook().progress).toEqual({ phase: 'timing', pct: 50 })
+
+    // reset（清本地状态 + 关订阅）
+    act(() => {
+      hook().reset()
+    })
+    expect(hook().state).toBe('idle')
+
+    act(() => {
+      api!.emit({ phase: 'timing', pct: 99 })
+    })
+    expect(hook().progress).toBeNull()
+
+    // 收尾原 analyze（不会被设到 UI，因为 reset 已经清掉 state）
+    await act(async () => {
+      resolveAnalyze(FAKE_RESULT)
+    })
+  })
+
+  it('cancel 之后 analyze 仍 reject（IPC cancel 信号 / 子进程被 kill），state 不会变 error', async () => {
+    // 模拟真实场景：用户 cancel，主进程发 IPC cancel 给 runner，runner 把
+    // 进行中的 analyze() promise reject 掉。hook 必须保持 idle，不能进 error。
+    api!.analyze.mockImplementationOnce(() => Promise.reject(new Error('aborted by user cancel')))
+
+    await act(async () => {
+      void hook().run(SAMPLE_OPTS)
+    })
+    // run 已发起；analyze 立即 reject，下面 await flush 微任务
+    await act(async () => {
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+
+    // 用户中途 cancel（cancel 内部已经把 state 设回 idle）
+    await act(async () => {
+      await hook().cancel()
+    })
+    expect(hook().state).toBe('idle')
+
+    // 现在让那个 reject 落地 —— hook 看到 runId 不匹配，应当静默丢弃，
+    // 不应把 "aborted by user cancel" 暴露给 UI。
+    await act(async () => {
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+    expect(hook().state).toBe('idle')
+    expect(hook().errorMessage).toBeNull()
+  })
+
+  it('analyze 真出错（非 cancel 引起）才会把 state 推到 error 并写入 errorMessage', async () => {
+    api!.analyze.mockImplementationOnce(() => Promise.reject(new Error('syntax error: unexpected EOF')))
+
+    await act(async () => {
+      void hook().run(SAMPLE_OPTS)
+    })
+    await act(async () => {
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+
+    expect(hook().state).toBe('error')
+    // 裸 Error 没有 [IPC_ERROR] 前缀 → readIpcError 包成 kind='unknown'。
+    // formatIpcError 对 unknown kind 走 !key 分支：直接返回 readableMessage，不加前缀
+    // （kind 翻译表里没有 unknown —— 通常是 spawn / 第三方 error，原文最有排查价值）。
+    expect(hook().errorMessage).toBe('syntax error: unexpected EOF')
+  })
+
+  it('cancel 后再 run 一次，第二次的真错误能正常进入 error 状态', async () => {
+    // run #1：成功
+    api!.analyze.mockImplementationOnce(() => Promise.resolve(FAKE_RESULT))
+
+    await act(async () => {
+      void hook().run(SAMPLE_OPTS)
+    })
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(hook().state).toBe('done')
+
+    // 取消
+    await act(async () => {
+      await hook().cancel()
+    })
+    expect(hook().state).toBe('idle')
+
+    // run #2：失败 —— 必须是 error，不能被前一次的 cancel 状态卡住
+    api!.analyze.mockImplementationOnce(() => Promise.reject(new Error('timeout after 30s')))
+    await act(async () => {
+      void hook().run(SAMPLE_OPTS)
+    })
+    await act(async () => {
+      await Promise.resolve()
+      await Promise.resolve()
+    })
+    expect(hook().state).toBe('error')
+    // 同上：unknown kind 走 !key 分支直接返回 readableMessage
+    expect(hook().errorMessage).toBe('timeout after 30s')
+  })
+
+  it('cancel 后 runId bump 让陈旧 analyze resolve 不会覆盖 UI', async () => {
+    let resolve1!: (r: AnalysisResult) => void
+    let resolve2!: (r: AnalysisResult) => void
+    let count = 0
+    api!.analyze.mockImplementation(
+      () =>
+        new Promise<AnalysisResult>((resolve) => {
+          count++
+          if (count === 1) resolve1 = resolve
+          else resolve2 = resolve
+        })
+    )
+
+    // Run #1（不 await，pending promise 留着手动 resolve）
+    await act(async () => {
+      void hook().run(SAMPLE_OPTS)
+    })
+    expect(hook().state).toBe('running')
+
+    // 用户中途 cancel
+    await act(async () => {
+      await hook().cancel()
+    })
+    expect(hook().state).toBe('idle')
+
+    // Run #2
+    await act(async () => {
+      void hook().run(SAMPLE_OPTS)
+    })
+    expect(hook().state).toBe('running')
+
+    // 现在 resolve run #1 的 promise — 应该被丢弃
+    await act(async () => {
+      resolve1({ ...FAKE_RESULT, environment: { ...FAKE_RESULT.environment, python: 'OLD' } })
+    })
+    expect(hook().result).toBeNull()
+
+    // resolve run #2 — 应该被接受
+    await act(async () => {
+      resolve2({ ...FAKE_RESULT, environment: { ...FAKE_RESULT.environment, python: 'NEW' } })
+    })
+    expect(hook().result).not.toBeNull()
+    expect(hook().result?.environment.python).toBe('NEW')
+    expect(hook().state).toBe('done')
+  })
+})
diff --git a/src/renderer/src/hooks/__tests__/useExternalFiles.test.tsx b/src/renderer/src/hooks/__tests__/useExternalFiles.test.tsx
new file mode 100644
index 0000000..973567d
--- /dev/null
+++ b/src/renderer/src/hooks/__tests__/useExternalFiles.test.tsx
@@ -0,0 +1,340 @@
+/**
+ * useExternalFiles 的回归测试。
+ *
+ * 关注几条关键不变式：
+ * 1) openFile：去重命中（同 dedupKey）→ 不重复开 tab，只切 active
+ * 2) openFile：去重不命中 → loading tab 出现，IPC 成功置 ready，IPC 失败置 error
+ * 3) IPC await 期间 close tab → patch 时丢弃（race）
+ * 4) closeFile：关的是 active → activeExternalId 回 null
+ * 5) StrictMode 下 mount→cleanup→mount 不污染 activeExternalId / externalTabs
+ * 6) makeDisplayName: 不同长度路径走「父/末」或「末」分支
+ *
+ * 不覆盖：
+ *  - pendingReveal 时序（openFile 同步写入 ref）—— 这是 useRef 写入不是 state,
+ *    已经跟 openFile 同步;消费侧是 App.tsx 的 effect,不在 hook 范围内
+ */
+import { StrictMode, useEffect } from 'react'
+import { act, render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useExternalFiles, makeDisplayName } from '../useExternalFiles'
+import { wrap } from '../../i18n/test-utils'
+import type { FileReadResult } from '../../../../shared/analysis'
+
+interface FakeApi {
+  readFile: ReturnType<typeof vi.fn>
+}
+
+interface ProbeProps {
+  onReady: (api: ReturnType<typeof useExternalFiles>) => void
+}
+
+function installFakeApi(): FakeApi {
+  const api: FakeApi = {
+    readFile: vi.fn()
+  }
+  ;(window as unknown as { api: FakeApi }).api = api
+  return api
+}
+
+function Probe({ onReady }: ProbeProps) {
+  const api = useExternalFiles()
+  useEffect(() => {
+    onReady(api)
+  })
+  return <div data-testid="probe" />
+}
+
+const OK: FileReadResult = {
+  kind: 'ok',
+  content: 'print("hi")\n',
+  size: 14
+}
+
+const ERR_NOT_FOUND: FileReadResult = {
+  kind: 'not_found',
+  message: '文件不存在：C:\\python\\missing.py'
+}
+
+describe('useExternalFiles', () => {
+  let latest: ReturnType<typeof useExternalFiles> | null = null
+  let api: FakeApi | null = null
+
+  beforeEach(async () => {
+    latest = null
+    api = installFakeApi()
+    await act(async () => {
+      render(wrap(<Probe onReady={(a) => (latest = a)} />))
+      await new Promise((r) => setTimeout(r, 0))
+    })
+    if (!latest) throw new Error('Probe useEffect 未跑')
+  })
+
+  afterEach(() => {
+    latest = null
+    api = null
+    vi.restoreAllMocks()
+  })
+
+  function hook(): ReturnType<typeof useExternalFiles> {
+    if (!latest) throw new Error('hook 未挂载')
+    return latest
+  }
+
+  it('初始状态：externalTabs 空，activeExternalId = null', () => {
+    expect(hook().externalTabs).toEqual([])
+    expect(hook().activeExternalId).toBeNull()
+  })
+
+  it('openFile：loading tab 出现 + active 切到新 tab + IPC 成功置 ready', async () => {
+    // 用 deferred mock 才能断言 loading 中间态 —— mockResolvedValue 在同一个
+    // microtask 里 resolve,act 还没退出就已被 patch 成 ready
+    let resolveRead!: (r: FileReadResult) => void
+    api!.readFile.mockImplementationOnce(() => new Promise<FileReadResult>((r) => (resolveRead = r)))
+
+    await act(async () => {
+      hook().openFile('C:\\Python311\\Lib\\json\\decoder.py', 42, 'stdlib')
+    })
+    // 同步拿到 loading tab
+    expect(hook().externalTabs).toHaveLength(1)
+    expect(hook().externalTabs[0].status).toBe('loading')
+    expect(hook().externalTabs[0].filePath).toBe('C:\\Python311\\Lib\\json\\decoder.py')
+    expect(hook().externalTabs[0].origin).toBe('stdlib')
+    expect(hook().externalTabs[0].displayName).toBe('json/decoder.py')
+    expect(hook().activeExternalId).toBe(hook().externalTabs[0].id)
+
+    // IPC resolve → ready
+    await act(async () => {
+      resolveRead(OK)
+      await new Promise((r) => setTimeout(r, 0))
+    })
+    expect(hook().externalTabs[0].status).toBe('ready')
+    expect(hook().externalTabs[0].content).toBe('print("hi")\n')
+    expect(hook().externalTabs[0].sizeBytes).toBe(14)
+  })
+
+  it('openFile：IPC 返回错误时 tab 进入 error 状态,errorKind / errorMessage 带出来', async () => {
+    api!.readFile.mockResolvedValueOnce(ERR_NOT_FOUND)
+    await act(async () => {
+      hook().openFile('C:\\missing.py', 1, 'stdlib')
+    })
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(hook().externalTabs[0].status).toBe('error')
+    expect(hook().externalTabs[0].errorKind).toBe('not_found')
+    expect(hook().externalTabs[0].errorMessage).toContain('文件不存在')
+  })
+
+  it('openFile：IPC 抛 throw 时按 unknown kind 处理', async () => {
+    api!.readFile.mockRejectedValueOnce(new Error('IPC channel dead'))
+    await act(async () => {
+      hook().openFile('C:\\boom.py', 1, 'third_party')
+    })
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(hook().externalTabs[0].status).toBe('error')
+    expect(hook().externalTabs[0].errorKind).toBe('unknown')
+    expect(hook().externalTabs[0].errorMessage).toBe('IPC channel dead')
+  })
+
+  it('openFile 同一路径重复调:只开一个 tab,只切 active(去重生效)', async () => {
+    api!.readFile.mockResolvedValue(OK)
+    // 第一次:新 tab
+    await act(async () => {
+      hook().openFile('C:\\Python311\\Lib\\json\\decoder.py', 10, 'stdlib')
+      await Promise.resolve()
+    })
+    const firstId = hook().externalTabs[0].id
+    expect(api!.readFile).toHaveBeenCalledTimes(1)
+    expect(hook().externalTabs).toHaveLength(1)
+
+    // 第二次:同路径,只切 active,不重新 IPC
+    await act(async () => {
+      hook().openFile('C:\\Python311\\Lib\\json\\decoder.py', 99, 'stdlib')
+      await Promise.resolve()
+    })
+    expect(api!.readFile).toHaveBeenCalledTimes(1)
+    expect(hook().externalTabs).toHaveLength(1)
+    expect(hook().externalTabs[0].id).toBe(firstId)
+    expect(hook().activeExternalId).toBe(firstId)
+  })
+
+  it('去重忽略大小写 + 反斜杠/正斜杠', async () => {
+    api!.readFile.mockResolvedValue(OK)
+    await act(async () => {
+      hook().openFile('C:\\Python311\\Lib\\json\\decoder.py', 1, 'stdlib')
+      await Promise.resolve()
+    })
+    expect(api!.readFile).toHaveBeenCalledTimes(1)
+
+    // 不同大小写 + 正斜杠 → 应被识别为同一 dedupKey
+    await act(async () => {
+      hook().openFile('c:/PYTHON311/lib/JSON/decoder.py', 2, 'stdlib')
+      await Promise.resolve()
+    })
+    expect(api!.readFile).toHaveBeenCalledTimes(1)
+    expect(hook().externalTabs).toHaveLength(1)
+  })
+
+  it('closeFile：关掉非 active tab 时 activeExternalId 不变', async () => {
+    api!.readFile.mockResolvedValue(OK)
+    await act(async () => {
+      hook().openFile('C:\\a.py', 1, 'stdlib')
+      hook().openFile('C:\\b.py', 2, 'stdlib')
+      await Promise.resolve()
+    })
+    expect(hook().externalTabs).toHaveLength(2)
+    const firstId = hook().externalTabs[0].id
+    const secondId = hook().externalTabs[1].id
+    // 当前 active 是 second
+    expect(hook().activeExternalId).toBe(secondId)
+
+    await act(async () => {
+      hook().closeFile(firstId)
+    })
+    expect(hook().externalTabs).toHaveLength(1)
+    expect(hook().externalTabs[0].id).toBe(secondId)
+    expect(hook().activeExternalId).toBe(secondId)
+  })
+
+  it('closeFile：关掉 active tab 时 activeExternalId 回 null(切回用户 tab)', async () => {
+    api!.readFile.mockResolvedValue(OK)
+    await act(async () => {
+      hook().openFile('C:\\a.py', 1, 'stdlib')
+      await Promise.resolve()
+    })
+    const id = hook().externalTabs[0].id
+    expect(hook().activeExternalId).toBe(id)
+
+    await act(async () => {
+      hook().closeFile(id)
+    })
+    expect(hook().externalTabs).toHaveLength(0)
+    expect(hook().activeExternalId).toBeNull()
+  })
+
+  it('IPC await 期间 close tab → patch 时不报错也不污染', async () => {
+    let resolveRead!: (r: FileReadResult) => void
+    api!.readFile.mockImplementationOnce(() => new Promise<FileReadResult>((r) => (resolveRead = r)))
+
+    // 启动 openFile（loading tab 进入）
+    await act(async () => {
+      hook().openFile('C:\\slow.py', 1, 'stdlib')
+    })
+    expect(hook().externalTabs).toHaveLength(1)
+    const tabId = hook().externalTabs[0].id
+
+    // 用户不等 IPC 完成就关 tab
+    await act(async () => {
+      hook().closeFile(tabId)
+    })
+    expect(hook().externalTabs).toHaveLength(0)
+
+    // IPC 终于 resolve → setState 在 functional 里检查 target 已被 prev.filter 掉
+    // → 应该 no-op,不能抛错也不能复活 tab
+    await act(async () => {
+      resolveRead(OK)
+      await new Promise((r) => setTimeout(r, 0))
+    })
+    expect(hook().externalTabs).toHaveLength(0)
+    expect(hook().activeExternalId).toBeNull()
+  })
+
+  it('setActive: 直接切活跃 tab,不调 IPC', async () => {
+    api!.readFile.mockResolvedValue(OK)
+    await act(async () => {
+      hook().openFile('C:\\a.py', 1, 'stdlib')
+      hook().openFile('C:\\b.py', 2, 'stdlib')
+      await Promise.resolve()
+    })
+    const firstId = hook().externalTabs[0].id
+    const secondId = hook().externalTabs[1].id
+    expect(hook().activeExternalId).toBe(secondId)
+
+    await act(async () => {
+      hook().setActive(firstId)
+    })
+    expect(hook().activeExternalId).toBe(firstId)
+    // 切回 null = 用户 tab
+    await act(async () => {
+      hook().setActive(null)
+    })
+    expect(hook().activeExternalId).toBeNull()
+  })
+
+  it('closeAll: 清空所有外部 tab 和 activeExternalId', async () => {
+    api!.readFile.mockResolvedValue(OK)
+    await act(async () => {
+      hook().openFile('C:\\a.py', 1, 'stdlib')
+      hook().openFile('C:\\b.py', 2, 'stdlib')
+      await Promise.resolve()
+    })
+    expect(hook().externalTabs).toHaveLength(2)
+
+    await act(async () => {
+      hook().closeAll()
+    })
+    expect(hook().externalTabs).toHaveLength(0)
+    expect(hook().activeExternalId).toBeNull()
+  })
+})
+
+describe('makeDisplayName', () => {
+  it('单段路径直接展示', () => {
+    expect(makeDisplayName('foo.py')).toBe('foo.py')
+  })
+  it('两段以上取父/末两段', () => {
+    expect(makeDisplayName('C:\\Python311\\Lib\\json\\decoder.py')).toBe('json/decoder.py')
+    expect(makeDisplayName('/usr/lib/python3.11/json/decoder.py')).toBe('json/decoder.py')
+  })
+  it('末段超长时只取末段(避免父段被截掉)', () => {
+    // 33 字符 > 32 → 单段展示
+    const longName = 'a'.repeat(33) + '.py'
+    expect(makeDisplayName(`C:\\lib\\${longName}`)).toBe(longName)
+  })
+  it('边界:刚好 32 字符仍走父/末', () => {
+    const name = 'a'.repeat(29) + '.py' // 29 + 3 = 32 字符
+    expect(name.length).toBe(32)
+    expect(makeDisplayName(`C:\\lib\\${name}`)).toBe(`lib/${name}`)
+  })
+  it('空路径串直接返回原值', () => {
+    expect(makeDisplayName('')).toBe('')
+  })
+})
+
+describe('useExternalFiles under StrictMode', () => {
+  let api: FakeApi | null = null
+
+  beforeEach(() => {
+    api = installFakeApi()
+  })
+
+  afterEach(() => {
+    api = null
+    vi.restoreAllMocks()
+  })
+
+  it('StrictMode mount→cleanup→mount 仍保持 activeExternalId=null,externalTabs=[]', async () => {
+    // 之前的 aliveRef 在 setup 里没复位 → 第二次 setup 后任何 patch tab 的
+    // setState 都因 aliveRef=false 被吃掉,行为看似正常只是巧合。
+    // 这里仅断言「mount 完成后状态干净」,关键不变式是 cleanup 后没有泄漏。
+    api!.readFile.mockResolvedValue(OK)
+    await act(async () => {
+      render(
+        wrap(
+          <StrictMode>
+            <Probe
+              onReady={(_h) => {
+                // mount useEffect 会推一个 loading tab? 不会 —— openFile 必须用户调
+              }}
+            />
+          </StrictMode>
+        )
+      )
+      await new Promise((r) => setTimeout(r, 0))
+    })
+    // 没有任何 openFile 调用,externalTabs 应为空
+    expect(api!.readFile).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/hooks/__tests__/useInterpreters.test.tsx b/src/renderer/src/hooks/__tests__/useInterpreters.test.tsx
new file mode 100644
index 0000000..0565bfd
--- /dev/null
+++ b/src/renderer/src/hooks/__tests__/useInterpreters.test.tsx
@@ -0,0 +1,498 @@
+/**
+ * useInterpreters 的回归测试。
+ *
+ * 关注三条关键不变式：
+ * 1) StrictMode mount → cleanup → mount 只触发一次自动 detectAll
+ *    （hasAutoDetectedRef 守卫；之前漏了这条会导致两路并行 IPC 探测，
+ *     每个 20+ fs probe，渲染后白屏数百毫秒）
+ * 2) detectAll / pick 并发请求时，旧请求的 resolve 不会覆盖新请求的结果
+ *    （tokenRef 守卫；之前漏了会导致"晚点刷新"反而看到老列表）
+ * 3) 卸载后挂起的请求不会触发 setState
+ *    （aliveRef 守卫；漏了会出 React "setState on unmounted" warning）
+ */
+import { StrictMode, useEffect } from 'react'
+import { act, render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { STORAGE_KEY_INTERPRETER, readStoredInterpreterPath, useInterpreters } from '../useInterpreters'
+import { wrap } from '../../i18n/test-utils'
+import { I18nProvider } from '../../i18n'
+import type { InterpreterInfo } from '../../../../shared/analysis'
+
+const PY_A: InterpreterInfo = {
+  path: 'C:/python/python.exe',
+  version: '3.11'
+}
+const PY_B: InterpreterInfo = {
+  path: 'C:/python/python2.exe',
+  version: '3.10'
+}
+
+interface FakeApi {
+  detectInterpreters: ReturnType<typeof vi.fn>
+  pickInterpreter: ReturnType<typeof vi.fn>
+}
+
+interface ProbeProps {
+  onReady: (api: ReturnType<typeof useInterpreters>) => void
+  /** 控制是否让自动 detectAll 的 promise pending（用于排查 StrictMode 时序） */
+  autoDetectResolverRef?: { current: ((l: InterpreterInfo[]) => void) | null }
+}
+
+function installFakeApi(): FakeApi {
+  const api: FakeApi = {
+    detectInterpreters: vi.fn().mockResolvedValue([PY_A, PY_B]),
+    pickInterpreter: vi.fn().mockResolvedValue(PY_A)
+  }
+  ;(window as unknown as { api: FakeApi }).api = api
+  return api
+}
+
+function Probe({ onReady }: ProbeProps) {
+  const api = useInterpreters()
+  useEffect(() => {
+    onReady(api)
+  })
+  return <div data-testid="probe" />
+}
+
+describe('useInterpreters', () => {
+  let latest: ReturnType<typeof useInterpreters> | null = null
+  let api: FakeApi | null = null
+
+  beforeEach(async () => {
+    latest = null
+    api = installFakeApi()
+    // 自动 detectAll 在 mount useEffect 里发起 → 异步 resolve → setInterpreters / setSelected。
+    // 这条 setState 链路必须放在 act 里跑，否则 React 18 会喷
+    // "An update to Probe inside a test was not wrapped in act(...)"。
+    // 多 await 几次把 microtask 队列彻底排空（含 Promise.resolve 链）。
+    await act(async () => {
+      render(wrap(<Probe onReady={(a) => (latest = a)} />))
+      await new Promise((r) => setTimeout(r, 0))
+    })
+    if (!latest) throw new Error('Probe useEffect 未跑')
+  })
+
+  afterEach(() => {
+    latest = null
+    api = null
+    vi.restoreAllMocks()
+  })
+
+  function hook(): ReturnType<typeof useInterpreters> {
+    if (!latest) throw new Error('hook 未挂载')
+    return latest
+  }
+
+  it('mount 时自动调一次 detectAll，并填好 selected / interpreters', async () => {
+    // 默认 resolve 是同步的 microtask，act flush 后状态应已落地
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(api!.detectInterpreters).toHaveBeenCalledTimes(1)
+    expect(hook().interpreters).toEqual([PY_A, PY_B])
+    // 默认选第一个
+    expect(hook().selected).toBe(PY_A.path)
+    expect(hook().detecting).toBe(false)
+    expect(hook().detectError).toBeNull()
+    expect(hook().pickError).toBeNull()
+  })
+
+  it('当前 selected 仍在列表里时，重 detect 不替换', async () => {
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(hook().selected).toBe(PY_A.path)
+
+    // 用户手动选到 PY_B
+    await act(async () => {
+      hook().selectPath(PY_B.path)
+    })
+    expect(hook().selected).toBe(PY_B.path)
+
+    // 第二次 detect 返回同样的列表 — selected 应保留
+    api!.detectInterpreters.mockResolvedValueOnce([PY_A, PY_B])
+    await act(async () => {
+      await hook().detectAll()
+    })
+    expect(hook().selected).toBe(PY_B.path)
+  })
+
+  it('当前 selected 不在新列表里时，自动回退到第一个', async () => {
+    await act(async () => {
+      await Promise.resolve()
+    })
+    // 把 selected 切到一个不存在的路径
+    await act(async () => {
+      hook().selectPath('C:/ghost/whatever.exe')
+    })
+    expect(hook().selected).toBe('C:/ghost/whatever.exe')
+
+    // 新一轮 detect 只返 PY_B
+    api!.detectInterpreters.mockResolvedValueOnce([PY_B])
+    await act(async () => {
+      await hook().detectAll()
+    })
+    expect(hook().selected).toBe(PY_B.path)
+  })
+
+  it('并发 detectAll：旧请求 resolve 晚到不应覆盖新结果（tokenRef 守卫）', async () => {
+    await act(async () => {
+      await Promise.resolve()
+    })
+
+    let resolveStale!: (l: InterpreterInfo[]) => void
+    let resolveFresh!: (l: InterpreterInfo[]) => void
+    api!.detectInterpreters
+      .mockImplementationOnce(() => new Promise<InterpreterInfo[]>((r) => (resolveStale = r)))
+      .mockImplementationOnce(() => new Promise<InterpreterInfo[]>((r) => (resolveFresh = r)))
+
+    // 启动旧请求 — setDetecting(true) 必须包进 act，否则 React 18 喷
+    // "An update to Probe inside a test was not wrapped in act(...)"。
+    let stale!: Promise<void>
+    let fresh!: Promise<void>
+    await act(async () => {
+      stale = hook().detectAll()
+      fresh = hook().detectAll()
+    })
+
+    // 新请求先 resolve
+    await act(async () => {
+      resolveFresh([PY_B])
+      await fresh
+    })
+    expect(hook().interpreters).toEqual([PY_B])
+
+    // 旧请求晚到 resolve — 应被忽略（tokenRef 已 bump）
+    await act(async () => {
+      resolveStale([PY_A])
+      await stale
+    })
+    expect(hook().interpreters).toEqual([PY_B])
+  })
+
+  it('detectAll 出错时写入 detectError，并把 kind 带出来', async () => {
+    await act(async () => {
+      await Promise.resolve()
+    })
+
+    // 模拟 IpcError：raw message 带 [IPC_ERROR] 前缀 + JSON
+    const ipcMsg = `[IPC_ERROR] ${JSON.stringify({
+      kind: 'interpreter_probe_failed',
+      message: 'python --version spawn 失败'
+    })}`
+    api!.detectInterpreters.mockRejectedValueOnce(new Error(ipcMsg))
+
+    await act(async () => {
+      await hook().detectAll()
+    })
+    expect(hook().detectError).toBe('探测解释器失败：python --version spawn 失败')
+    expect(hook().detecting).toBe(false)
+  })
+
+  it('pick 成功时把解释器前置去重并选中它', async () => {
+    await act(async () => {
+      await Promise.resolve()
+    })
+    // 当前 PY_A 在第一位
+    expect(hook().interpreters[0].path).toBe(PY_A.path)
+
+    // 用户挑了 PY_A，但当作"另一个版本"传回来 — path 一样，应去重
+    const variant: InterpreterInfo = { ...PY_A, version: '3.12' }
+    api!.pickInterpreter.mockResolvedValueOnce(variant)
+    await act(async () => {
+      await hook().pick()
+    })
+    // 列表里 PY_A 只剩一份，且 version 是新的
+    expect(hook().interpreters.filter((i) => i.path === PY_A.path)).toHaveLength(1)
+    expect(hook().interpreters.find((i) => i.path === PY_A.path)?.version).toBe('3.12')
+    expect(hook().selected).toBe(PY_A.path)
+    expect(hook().pickError).toBeNull()
+  })
+
+  it('pick IPC 抛 IpcError 时写入 pickError（按 lang 翻译），不动 interpreters', async () => {
+    await act(async () => {
+      await Promise.resolve()
+    })
+    const beforeList = hook().interpreters
+
+    // main 进程改 throw IpcError('interpreter_not_allowed', ...) 后,renderer 走
+    // readIpcError → formatIpcError 翻译链。中文 locale 下翻译是
+    // '解释器路径不在白名单：{message}'（{message} 占位符回填原文）。
+    const failure = new Error(
+      '[IPC_ERROR] ' +
+        JSON.stringify({
+          kind: 'interpreter_not_allowed',
+          message: '不是有效的 Python 解释器路径: foo.exe',
+          details: { path: 'foo.exe' }
+        })
+    )
+    api!.pickInterpreter.mockRejectedValueOnce(failure)
+    await act(async () => {
+      await hook().pick()
+    })
+    expect(hook().pickError).toBe('解释器路径不在白名单：不是有效的 Python 解释器路径: foo.exe')
+    expect(hook().interpreters).toBe(beforeList)
+    expect(hook().selected).toBe(PY_A.path)
+  })
+
+  it('pick 返回 null（用户取消）时不报错也不动状态', async () => {
+    await act(async () => {
+      await Promise.resolve()
+    })
+    api!.pickInterpreter.mockResolvedValueOnce(null)
+    await act(async () => {
+      await hook().pick()
+    })
+    expect(hook().pickError).toBeNull()
+    expect(hook().interpreters).toEqual([PY_A, PY_B])
+    expect(hook().selected).toBe(PY_A.path)
+  })
+
+  it('active 字段返回当前 selected 对应的解释器', async () => {
+    await act(async () => {
+      await Promise.resolve()
+    })
+    expect(hook().active?.path).toBe(PY_A.path)
+    await act(async () => {
+      hook().selectPath(PY_B.path)
+    })
+    expect(hook().active?.path).toBe(PY_B.path)
+    await act(async () => {
+      hook().selectPath('C:/does-not-exist.exe')
+    })
+    expect(hook().active).toBeUndefined()
+  })
+})
+
+describe('useInterpreters under StrictMode', () => {
+  let api: FakeApi | null = null
+
+  beforeEach(() => {
+    api = installFakeApi()
+  })
+
+  afterEach(() => {
+    api = null
+    vi.restoreAllMocks()
+  })
+
+  it('StrictMode 下 mount→cleanup→mount 只触发一次自动 detectAll（hasAutoDetectedRef）', async () => {
+    const ProbeSM = () => {
+      useInterpreters()
+      return <div />
+    }
+    await act(async () => {
+      render(
+        <StrictMode>
+          <I18nProvider>
+            <ProbeSM />
+          </I18nProvider>
+        </StrictMode>
+      )
+      // StrictMode 下 mount 走 setup → cleanup → setup，cleanup 会把 aliveRef 置 false
+      // 然后第二次 setup 复位为 true；这套时序连带一次额外 setDetecting(true)。
+      // 用 setTimeout 0 把整条 microtask 链排空，连带 React 18 调度。
+      await new Promise((r) => setTimeout(r, 0))
+    })
+    // 关键断言：即使 React StrictMode 双调用 mount，detectInterpreters 也只能
+    // 调一次（hasAutoDetectedRef 在第一次 setup 已被置 true，第二次 setup 直接
+    // short-circuit）。如果这条失效，IPC 探测会成对触发，启动延迟翻倍。
+    expect(api!.detectInterpreters).toHaveBeenCalledTimes(1)
+  })
+
+  it('StrictMode 第二次 setup 后，detecting 收尾 finally 不被 aliveRef=false 短路', async () => {
+    // 之前 aliveRef 在 setup 里没复位 → cleanup 之后所有 finally 块里的
+    // "if (aliveRef.current) setDetecting(false)" 都 false，detecting 卡在 true。
+    // 现在 setup 复位 aliveRef=true，finally 正常跑，detecting 必须收尾。
+    let captured: ReturnType<typeof useInterpreters> | null = null
+    const ProbeSM = () => {
+      const h = useInterpreters()
+      useEffect(() => {
+        if (!captured) captured = h
+      })
+      return <div />
+    }
+    await act(async () => {
+      render(
+        wrap(
+          <StrictMode>
+            <ProbeSM />
+          </StrictMode>
+        )
+      )
+      await new Promise((r) => setTimeout(r, 0))
+    })
+    expect(captured).not.toBeNull()
+    expect(captured!.detecting).toBe(false)
+  })
+})
+
+/**
+ * 解释器选择的 localStorage 持久化（pyrof.interpreter）。
+ *
+ * 跟 useTheme / useScope 等一套套路 —— 测试关注四条不变式：
+ * 1) 读：mount 时如果 localStorage 里有持久值，selected 用持久值作初值（这条让
+ *    「重启软件后保留用户选择」真正成立 — 否则选中值丢了）。
+ * 2) 写 selectPath：用户手动换选项，localStorage 跟着更新。
+ * 3) 写 pick：用户走「浏览…」选了一个新解释器，pick 成功后也写。
+ * 4) 写 fallback：detectAll 发现持久路径在新列表里找不到 → 回退到第一个；
+ *    这条 fallback 也必须写回 localStorage，否则下次启动又跑 fallback（浪费一次
+ *    IPC,理论上无限循环到用户手动重 detect）。
+ *
+ * 每个 case 自己清 localStorage —— 上面的 describe 没清理，可能有残留。
+ */
+describe('useInterpreters persistence (pyrof.interpreter)', () => {
+  // 每个 case 自己清 localStorage + 自己 mount。
+  // `hook` 用 `function` 声明 + 显式返回类型 —— `const hook = () => { if (!latest) throw... }`
+  // 的隐式返回类型在跨闭包捕获 `let` 时 TS 推不出,会变成 `never`(TS 5.x 已知行为)。
+  // 关键：`latest` 在描述级(而非函数返回值)持有 —— `useInterpreters()` 每次 render
+  // 都返回新对象,测试如果只持有 mount 时的快照,后续 selectPath / pick 触发的
+  // re-render 不会回头更新那个 snapshot,只能读 stale 值。
+  afterEach(() => {
+    window.localStorage.clear()
+    vi.restoreAllMocks()
+  })
+
+  it('mount 时从 localStorage 读出上次保存的 selected（不和 detectAll 冲突）', async () => {
+    window.localStorage.setItem(STORAGE_KEY_INTERPRETER, PY_B.path)
+    installFakeApi()
+    let latest: ReturnType<typeof useInterpreters> | null = null
+    await act(async () => {
+      render(wrap(<Probe onReady={(a) => (latest = a)} />))
+      await new Promise((r) => setTimeout(r, 0))
+      await Promise.resolve()
+    })
+    function hook(): ReturnType<typeof useInterpreters> {
+      if (!latest) throw new Error('hook 未挂载')
+      return latest
+    }
+    // detectAll 跑完,PY_B 仍在列表里 → selected 保留在 PY_B
+    expect(hook().selected).toBe(PY_B.path)
+    expect(hook().active?.path).toBe(PY_B.path)
+  })
+
+  it('localStorage 没值时 mount 后 selected 默认走 detectAll 的兜底（第一个）', async () => {
+    installFakeApi()
+    let latest: ReturnType<typeof useInterpreters> | null = null
+    await act(async () => {
+      render(wrap(<Probe onReady={(a) => (latest = a)} />))
+      await new Promise((r) => setTimeout(r, 0))
+      await Promise.resolve()
+    })
+    function hook(): ReturnType<typeof useInterpreters> {
+      if (!latest) throw new Error('hook 未挂载')
+      return latest
+    }
+    expect(hook().selected).toBe(PY_A.path)
+    // mount 时 useEffect 也会写一次 — 当下 selected 是 PY_A,localStorage 应同步过去
+    expect(window.localStorage.getItem(STORAGE_KEY_INTERPRETER)).toBe(PY_A.path)
+  })
+
+  it('selectPath 切值时同步写 localStorage', async () => {
+    installFakeApi()
+    let latest: ReturnType<typeof useInterpreters> | null = null
+    await act(async () => {
+      render(wrap(<Probe onReady={(a) => (latest = a)} />))
+      await new Promise((r) => setTimeout(r, 0))
+      await Promise.resolve()
+    })
+    function hook(): ReturnType<typeof useInterpreters> {
+      if (!latest) throw new Error('hook 未挂载')
+      return latest
+    }
+
+    // 切到 PY_B —— act 包住 selectPath 后多 await 一次 Promise.resolve,让
+    // selectPath → setState → re-render → Probe.onReady → latest 更新这条
+    // microtask 链 flush 干净
+    await act(async () => {
+      hook().selectPath(PY_B.path)
+      await Promise.resolve()
+    })
+    expect(window.localStorage.getItem(STORAGE_KEY_INTERPRETER)).toBe(PY_B.path)
+    expect(hook().selected).toBe(PY_B.path)
+
+    // 切回 PY_A 也写
+    await act(async () => {
+      hook().selectPath(PY_A.path)
+      await Promise.resolve()
+    })
+    expect(window.localStorage.getItem(STORAGE_KEY_INTERPRETER)).toBe(PY_A.path)
+  })
+
+  it('pick 成功时同步写 localStorage', async () => {
+    installFakeApi()
+    const api = (window as unknown as { api: FakeApi }).api
+    let latest: ReturnType<typeof useInterpreters> | null = null
+    await act(async () => {
+      render(wrap(<Probe onReady={(a) => (latest = a)} />))
+      await new Promise((r) => setTimeout(r, 0))
+      await Promise.resolve()
+    })
+    function hook(): ReturnType<typeof useInterpreters> {
+      if (!latest) throw new Error('hook 未挂载')
+      return latest
+    }
+
+    const NEW_PY: InterpreterInfo = {
+      path: 'C:/python/custom/python.exe',
+      version: '3.12.0'
+    }
+    api.pickInterpreter.mockResolvedValueOnce(NEW_PY)
+
+    await act(async () => {
+      await hook().pick()
+      await Promise.resolve()
+    })
+    expect(hook().selected).toBe(NEW_PY.path)
+    expect(window.localStorage.getItem(STORAGE_KEY_INTERPRETER)).toBe(NEW_PY.path)
+  })
+
+  it('detectAll fallback:持久路径不在新列表里 → 切到第一个,并写回 localStorage', async () => {
+    // 模拟「上次选的 python 已经被用户卸载 / 重装到别的路径」。
+    window.localStorage.setItem(STORAGE_KEY_INTERPRETER, 'C:/ghost/whatever.exe')
+    installFakeApi()
+    const api = (window as unknown as { api: FakeApi }).api
+    let latest: ReturnType<typeof useInterpreters> | null = null
+    await act(async () => {
+      render(wrap(<Probe onReady={(a) => (latest = a)} />))
+      await new Promise((r) => setTimeout(r, 0))
+      await Promise.resolve()
+    })
+    function hook(): ReturnType<typeof useInterpreters> {
+      if (!latest) throw new Error('hook 未挂载')
+      return latest
+    }
+
+    // detectAll mock 默认返 [PY_A, PY_B] —— 都不包含 ghost 路径 → fallback 到 PY_A
+    expect(hook().selected).toBe(PY_A.path)
+    expect(api.detectInterpreters).toHaveBeenCalled()
+    expect(window.localStorage.getItem(STORAGE_KEY_INTERPRETER)).toBe(PY_A.path)
+  })
+
+  it('detectAll fallback:持久路径还在新列表里 → 保持不写穿,selected 不变', async () => {
+    // 与上一条对照：保持路径合法,没有触发 fallback,不应当把路径意外改了。
+    window.localStorage.setItem(STORAGE_KEY_INTERPRETER, PY_B.path)
+    installFakeApi()
+    let latest: ReturnType<typeof useInterpreters> | null = null
+    await act(async () => {
+      render(wrap(<Probe onReady={(a) => (latest = a)} />))
+      await new Promise((r) => setTimeout(r, 0))
+    })
+    function hook(): ReturnType<typeof useInterpreters> {
+      if (!latest) throw new Error('hook 未挂载')
+      return latest
+    }
+
+    expect(hook().selected).toBe(PY_B.path)
+    // 即使 selected 没变,mount 时 useEffect 也会写一次（值不变,无副作用）
+    expect(window.localStorage.getItem(STORAGE_KEY_INTERPRETER)).toBe(PY_B.path)
+  })
+
+  it('readStoredInterpreterPath 是公共工具函数,localStorage 读不到时回退空串', () => {
+    window.localStorage.clear()
+    expect(readStoredInterpreterPath()).toBe('')
+    window.localStorage.setItem(STORAGE_KEY_INTERPRETER, 'C:/python/python.exe')
+    expect(readStoredInterpreterPath()).toBe('C:/python/python.exe')
+  })
+})
diff --git a/src/renderer/src/hooks/__tests__/useResizableFraction.test.ts b/src/renderer/src/hooks/__tests__/useResizableFraction.test.ts
new file mode 100644
index 0000000..b02cec0
--- /dev/null
+++ b/src/renderer/src/hooks/__tests__/useResizableFraction.test.ts
@@ -0,0 +1,136 @@
+import { act, renderHook } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { useResizableFraction } from '../useResizableFraction'
+
+const STORAGE_KEY = 'pyrof.split.test'
+
+const baseOptions = { default: 0.5, min: 0.2, max: 0.8 }
+
+afterEach(() => {
+  window.localStorage.clear()
+})
+
+describe('useResizableFraction', () => {
+  it('无 localStorage 时回退到 default', () => {
+    window.localStorage.clear()
+    const { result } = renderHook(() => useResizableFraction(STORAGE_KEY, baseOptions))
+    expect(result.current.fraction).toBe(0.5)
+  })
+
+  it('localStorage 里合法值被读出', () => {
+    window.localStorage.setItem(STORAGE_KEY, '0.6')
+    const { result } = renderHook(() => useResizableFraction(STORAGE_KEY, baseOptions))
+    expect(result.current.fraction).toBe(0.6)
+  })
+
+  it('localStorage 里非法值（NaN / 字符串）降级到 default', () => {
+    window.localStorage.setItem(STORAGE_KEY, 'not-a-number')
+    const { result } = renderHook(() => useResizableFraction(STORAGE_KEY, baseOptions))
+    expect(result.current.fraction).toBe(0.5)
+  })
+
+  it('localStorage 里超出范围的值被 clamp 到 min/max', () => {
+    window.localStorage.setItem(STORAGE_KEY, '0.99')
+    const { result } = renderHook(() => useResizableFraction(STORAGE_KEY, baseOptions))
+    expect(result.current.fraction).toBe(0.8)
+
+    window.localStorage.setItem(STORAGE_KEY, '0.01')
+    const second = renderHook(() => useResizableFraction(STORAGE_KEY, baseOptions))
+    expect(second.result.current.fraction).toBe(0.2)
+  })
+
+  it('setFraction 写入 localStorage 并切换 state', () => {
+    window.localStorage.clear()
+    const { result } = renderHook(() => useResizableFraction(STORAGE_KEY, baseOptions))
+
+    act(() => result.current.setFraction(0.7))
+    expect(result.current.fraction).toBe(0.7)
+    expect(window.localStorage.getItem(STORAGE_KEY)).toBe('0.7')
+
+    act(() => result.current.setFraction(0.5))
+    expect(result.current.fraction).toBe(0.5)
+  })
+
+  it('setFraction 接受函数式更新', () => {
+    window.localStorage.setItem(STORAGE_KEY, '0.5')
+    const { result } = renderHook(() => useResizableFraction(STORAGE_KEY, baseOptions))
+
+    act(() => result.current.setFraction((prev) => prev + 0.1))
+    expect(result.current.fraction).toBe(0.6)
+  })
+
+  it('setFraction 函数式更新连写多次不丢更新（不走 stale closure）', () => {
+    // 旧实现闭包了 fraction,连写两次 `prev => prev + 0.05` 会用同一份 stale base,
+    // 第二次被吞。现在 functional setState 后两次都按各自 prev 算:0.5 → 0.55 → 0.6。
+    window.localStorage.setItem(STORAGE_KEY, '0.5')
+    const { result } = renderHook(() => useResizableFraction(STORAGE_KEY, baseOptions))
+
+    act(() => {
+      result.current.setFraction((prev) => prev + 0.05)
+      result.current.setFraction((prev) => prev + 0.05)
+    })
+    expect(result.current.fraction).toBeCloseTo(0.6, 5)
+  })
+
+  it('setFraction 自动 clamp 到 [min,max]', () => {
+    const { result } = renderHook(() => useResizableFraction(STORAGE_KEY, baseOptions))
+
+    act(() => result.current.setFraction(0.95))
+    expect(result.current.fraction).toBe(0.8)
+
+    act(() => result.current.setFraction(0.05))
+    expect(result.current.fraction).toBe(0.2)
+  })
+
+  it('applyDelta 按容器宽度换算成 fraction 增量', () => {
+    window.localStorage.setItem(STORAGE_KEY, '0.5')
+    const { result } = renderHook(() => useResizableFraction(STORAGE_KEY, baseOptions))
+
+    // 容器 1000px,拖 100px → 0.1 增量
+    act(() => result.current.applyDelta(100, 1000))
+    expect(result.current.fraction).toBeCloseTo(0.6, 5)
+
+    // 再拖 -50px → 回到 0.55
+    act(() => result.current.applyDelta(-50, 1000))
+    expect(result.current.fraction).toBeCloseTo(0.55, 5)
+  })
+
+  it('applyDelta 累积超出范围时被 clamp（不允许被拖出 [min,max]）', () => {
+    window.localStorage.setItem(STORAGE_KEY, '0.75')
+    const { result } = renderHook(() => useResizableFraction(STORAGE_KEY, baseOptions))
+
+    // 拖很多次累加远超 0.8,但 clamp 在 0.8
+    act(() => result.current.applyDelta(1000, 1000))
+    expect(result.current.fraction).toBe(0.8)
+  })
+
+  it('applyDelta 在容器尺寸 <= 0 时静默忽略', () => {
+    window.localStorage.setItem(STORAGE_KEY, '0.5')
+    const { result } = renderHook(() => useResizableFraction(STORAGE_KEY, baseOptions))
+
+    act(() => result.current.applyDelta(50, 0))
+    expect(result.current.fraction).toBe(0.5)
+
+    act(() => result.current.applyDelta(50, -100))
+    expect(result.current.fraction).toBe(0.5)
+  })
+
+  it('localStorage 抛错（file://）时初始化回退到 default', () => {
+    const spy = vi.spyOn(window.localStorage, 'getItem').mockImplementation(() => {
+      throw new Error('SecurityError: file:// access denied')
+    })
+    try {
+      const { result } = renderHook(() => useResizableFraction(STORAGE_KEY, baseOptions))
+      expect(result.current.fraction).toBe(0.5)
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
+  it('default 落在 [min,max] 之外时也会被 clamp', () => {
+    const { result } = renderHook(() =>
+      useResizableFraction(STORAGE_KEY, { default: 1.5, min: 0.2, max: 0.8 })
+    )
+    expect(result.current.fraction).toBe(0.8)
+  })
+})
diff --git a/src/renderer/src/hooks/__tests__/useScope.test.ts b/src/renderer/src/hooks/__tests__/useScope.test.ts
new file mode 100644
index 0000000..dff36c5
--- /dev/null
+++ b/src/renderer/src/hooks/__tests__/useScope.test.ts
@@ -0,0 +1,71 @@
+import { act, renderHook } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { useScope, DEFAULT_SCOPE, STORAGE_KEY_SCOPE, readStoredScope } from '../useScope'
+
+afterEach(() => {
+  window.localStorage.clear()
+})
+
+describe('useScope', () => {
+  it('默认是 all（无 localStorage 时 —— 默认含库函数）', () => {
+    window.localStorage.clear()
+    const { result } = renderHook(() => useScope())
+    expect(result.current.scope).toBe(DEFAULT_SCOPE)
+    expect(result.current.scope).toBe('all')
+  })
+
+  it('localStorage 持久值 user 被读出（用户主动关过）', () => {
+    window.localStorage.setItem(STORAGE_KEY_SCOPE, 'user')
+    const { result } = renderHook(() => useScope())
+    expect(result.current.scope).toBe('user')
+  })
+
+  it('localStorage 持久值 all 被读出', () => {
+    window.localStorage.setItem(STORAGE_KEY_SCOPE, 'all')
+    const { result } = renderHook(() => useScope())
+    expect(result.current.scope).toBe('all')
+  })
+
+  it('localStorage 里非法值降级为默认 all（不抛）', () => {
+    window.localStorage.setItem(STORAGE_KEY_SCOPE, 'bogus')
+    const { result } = renderHook(() => useScope())
+    expect(result.current.scope).toBe('all')
+  })
+
+  it('setScope 写 localStorage 并切换 state', () => {
+    window.localStorage.clear()
+    const { result } = renderHook(() => useScope())
+    act(() => result.current.setScope('user'))
+    expect(result.current.scope).toBe('user')
+    expect(window.localStorage.getItem(STORAGE_KEY_SCOPE)).toBe('user')
+
+    act(() => result.current.setScope('all'))
+    expect(result.current.scope).toBe('all')
+    expect(window.localStorage.getItem(STORAGE_KEY_SCOPE)).toBe('all')
+  })
+
+  it('toggle 在 user ↔ all 之间切换，并持久化', () => {
+    window.localStorage.clear()
+    const { result } = renderHook(() => useScope())
+    expect(result.current.scope).toBe('all')
+
+    act(() => result.current.toggle())
+    expect(result.current.scope).toBe('user')
+    expect(window.localStorage.getItem(STORAGE_KEY_SCOPE)).toBe('user')
+
+    act(() => result.current.toggle())
+    expect(result.current.scope).toBe('all')
+    expect(window.localStorage.getItem(STORAGE_KEY_SCOPE)).toBe('all')
+  })
+
+  it('readStoredScope 在 localStorage 抛错时静默回默认 all（file:// 场景）', () => {
+    const spy = vi.spyOn(window.localStorage, 'getItem').mockImplementation(() => {
+      throw new Error('SecurityError: file:// access denied')
+    })
+    try {
+      expect(readStoredScope()).toBe('all')
+    } finally {
+      spy.mockRestore()
+    }
+  })
+})
diff --git a/src/renderer/src/hooks/__tests__/useTheme.test.ts b/src/renderer/src/hooks/__tests__/useTheme.test.ts
new file mode 100644
index 0000000..989336c
--- /dev/null
+++ b/src/renderer/src/hooks/__tests__/useTheme.test.ts
@@ -0,0 +1,46 @@
+import { act, renderHook } from '@testing-library/react'
+import { afterEach, describe, expect, it } from 'vitest'
+import { useTheme, DEFAULT_THEME, STORAGE_KEY_THEME, type Theme } from '../useTheme'
+
+afterEach(() => {
+  window.localStorage.clear()
+  document.documentElement.classList.remove('dark', 'light')
+})
+
+describe('useTheme', () => {
+  it('默认是 dark（无 localStorage 时）', () => {
+    window.localStorage.clear()
+    const { result } = renderHook(() => useTheme())
+    expect(result.current.theme).toBe(DEFAULT_THEME)
+    expect(result.current.theme).toBe('dark')
+  })
+
+  it('localStorage 持久值 light 被读出', () => {
+    window.localStorage.setItem(STORAGE_KEY_THEME, 'light')
+    const { result } = renderHook(() => useTheme())
+    expect(result.current.theme).toBe('light')
+  })
+
+  it('setTheme 写 localStorage 且切换 <html> class', () => {
+    window.localStorage.clear()
+    const { result } = renderHook(() => useTheme())
+    act(() => result.current.setTheme('light'))
+    expect(result.current.theme).toBe('light')
+    expect(window.localStorage.getItem(STORAGE_KEY_THEME)).toBe('light')
+    expect(document.documentElement.classList.contains('light')).toBe(true)
+    expect(document.documentElement.classList.contains('dark')).toBe(false)
+
+    act(() => result.current.setTheme('dark'))
+    expect(document.documentElement.classList.contains('dark')).toBe(true)
+    expect(document.documentElement.classList.contains('light')).toBe(false)
+  })
+
+  it('setTheme(非法值) 仍能落到合法值（编译期已保证，但 runtime 防御）', () => {
+    // 非法值实际不会传进来（hook 类型限制），这里只验证合法切换路径稳定。
+    const { result } = renderHook(() => useTheme())
+    for (const t of ['dark', 'light'] as Theme[]) {
+      act(() => result.current.setTheme(t))
+      expect(result.current.theme).toBe(t)
+    }
+  })
+})
diff --git a/src/renderer/src/hooks/useAnalysis.ts b/src/renderer/src/hooks/useAnalysis.ts
new file mode 100644
index 0000000..f7fdadd
--- /dev/null
+++ b/src/renderer/src/hooks/useAnalysis.ts
@@ -0,0 +1,173 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { AnalysisResult, ProgressEvent, RunOptions } from '../../../shared/analysis'
+import { readIpcError } from '../../../shared/ipc'
+import { useT } from '../i18n'
+import { formatIpcError } from '../utils/ipcErrorFormat'
+
+export type RunState = 'idle' | 'running' | 'done' | 'error'
+
+export interface UseAnalysis {
+  result: AnalysisResult | null
+  state: RunState
+  progress: ProgressEvent | null
+  errorMessage: string | null
+  /** 引擎日志（取消/出错时附加；可作为折叠区显示） */
+  stderrTail: string | null
+  /** Python print() 输出的累积 buffer —— 每次 run 自动清空（之前的输出属于上一轮），
+   *  需要手动保留时调用 clearStdout() 之外的路径不存在：cancel / reset 都不清空。
+   *  RunConsole 是它的唯一消费方。 */
+  stdout: string
+  /** 当前 result 对应的 scope（'user' | 'all'）—— result=null 时为 null。
+   *  result 是旧 run 留下的、用户又切了 scope 时，UI 可以拿它跟当前 scope 对比、
+   *  给一句"结果是上一份 scope 跑出来的，是否重跑"的提示。 */
+  resultScope: RunOptions['scope'] | null
+  run: (opts: RunOptions) => Promise<void>
+  cancel: () => Promise<void>
+  /** 清空 result/progress/error，但不调用 IPC — 给"加载示例"等本地操作复用 */
+  reset: () => void
+  /** 清空 stdout 累积 buffer —— RunConsole 头部"清空"按钮调它。 */
+  clearStdout: () => void
+}
+
+export function useAnalysis(): UseAnalysis {
+  const t = useT()
+  const [result, setResult] = useState<AnalysisResult | null>(null)
+  const [state, setState] = useState<RunState>('idle')
+  const [progress, setProgress] = useState<ProgressEvent | null>(null)
+  const [errorMessage, setErrorMessage] = useState<string | null>(null)
+  const [stderrTail, setStderrTail] = useState<string | null>(null)
+  // stdout 流式累积 buffer。run 起始自动清空(之前的输出属于上一轮),cancel / reset 不清。
+  // 需要中途手动清空仍走 clearStdout()。RunConsole 是唯一消费方,不做 trim / 截断:
+  // 主进程 profiler-service 已经用 appendCapped 把每块压到 8MB 上限,这里自然兜住。
+  const [stdout, setStdout] = useState('')
+  // 记录当前 result 用的 scope —— result 清空时同步清空（否则会拿旧 scope 跟新 toggle 比较，UI 永远 stale）。
+  const [resultScope, setResultScope] = useState<RunOptions['scope'] | null>(null)
+
+  /** 单调递增的运行代号；陈旧 resolve 会与当前不符，被丢弃 */
+  const runIdRef = useRef(0)
+  // 是否接受 progress 事件。cancel() / reset() 立刻置 false，吞掉飞行中的陈旧事件；
+  // run() 置 true 重新接收新 run 的进度。
+  // 用 ref 而不是 token 计数，是为了避免上一版 `progressTokenRef` 的设计缺陷：
+  // 订阅回调里 `myToken` 是 mount 时一次性捕获的，cancel() 把它 bump 之后，
+  // run() 没有"复位到 myToken"的动作 → 第二次跑的 progress 全部被吞（永远 myToken !== current）。
+  // 改用 boolean ref：run/cancel/reset 各自直接翻位即可，订阅回调每次重新读 current 值。
+  const progressActiveRef = useRef(false)
+  // 组件是否还挂载：卸载后 analyze() 才返回的 setState 全部丢弃。
+  // 之前只用 runIdRef 防"陈旧 token 覆盖新 run"，但用户卸载组件时 runIdRef 不变，
+  // myId 仍等于 current，setState 仍会触发（虽不报错但浪费 reconciliation）。
+  // StrictMode 下 setup→cleanup→setup 必须重新置 true，否则卸载后所有 setState 永久短路。
+  const aliveRef = useRef(true)
+  useEffect(() => {
+    aliveRef.current = true
+    return () => {
+      aliveRef.current = false
+    }
+  }, [])
+
+  useEffect(() => {
+    // 直接把 unsubscribe 当成 cleanup 返回 — 比用 unsubRef 模式更直观，
+    // 且在 React StrictMode 双调用下也安全（每次都返回自己的 unsub）。
+    // 回调里只读 progressActiveRef.current（每次重新读），不会被陈旧闭包锁死。
+    return window.api.onProgress((p) => {
+      if (!progressActiveRef.current || !aliveRef.current) return
+      setProgress(p)
+    })
+  }, [])
+
+  useEffect(() => {
+    // stdout 流式订阅 —— 不像 progress 那样要 token 守卫（用户要累积,旧 run 的
+    // 飞行块也要追加进 buffer）。但仍要守 aliveRef:组件卸载后别再 setState。
+    return window.api.onStdout((chunk) => {
+      if (!aliveRef.current) return
+      setStdout((prev) => prev + chunk)
+    })
+  }, [])
+
+  /** 把 run 相关的 state 全部清空并 bump runIdRef + 关掉 progress 接收。
+   *  cancel / reset 都需要这套；run 也用它清掉旧状态再开新一轮。
+   *  顺序：先 bump token 让飞行中的陈旧 resolve 走守卫返回,再清 state。 */
+  const clearAnalysisState = useCallback(() => {
+    runIdRef.current++
+    progressActiveRef.current = false
+    setResult(null)
+    setState('idle')
+    setProgress(null)
+    setErrorMessage(null)
+    setStderrTail(null)
+    setResultScope(null)
+  }, [])
+
+  const run = useCallback(
+    async (opts: RunOptions) => {
+      // 连点"运行"：先 bump runIdRef 让旧的 resolve 进 token 守卫立刻 return，
+      // 再同步通知主进程 cancel 旧 child —— 否则主进程串行队列里旧 run 会等上一轮
+      // 自己跑完才轮到新 run，浪费算力 + 临时目录延迟清理。
+      // cancel() 是 async 但同步段已经 bump 了 runIdRef / progressActiveRef + 清空 state，
+      // 不需要 await 它完成才发起新 run（IPC 内部 taskkill 走异步）。
+      clearAnalysisState()
+      // 新一轮 run 起始清空 stdout —— 之前的输出属于上一轮,留着会和本次的 print() 混在一起,
+      // 等于丢失"这次运行的输出是哪些"的边界。cancel / reset 走的是 clearAnalysisState,
+      // 不动 stdout(用户可能想看被 cancel 的部分输出,或者加载示例后想保留旧 log)。
+      setStdout('')
+      void window.api.cancel()
+
+      const myId = ++runIdRef.current
+      progressActiveRef.current = true
+      setState('running')
+      try {
+        const r = await window.api.analyze(opts)
+        if (myId !== runIdRef.current || !aliveRef.current) return
+        // 提前关 progress 接收，避免 analyze 已 resolve 但飞行中的 progress 事件仍在
+        // setProgress，导致 UI 显示"done 结果 + 旧进度条"短暂不一致。
+        progressActiveRef.current = false
+        setResult(r)
+        setResultScope(opts.scope)
+        setState('done')
+      } catch (err) {
+        // 用户主动 cancel 时 runIdRef 已经 bump —— 这一步之前 cancel() 同步把 state 设回
+        // 'idle' 了；这里再写 'error' 会让"已取消"看起来像"出错"，UI 文案就乱了。
+        if (myId !== runIdRef.current || !aliveRef.current) return
+        progressActiveRef.current = false
+        // IPC 错误统一过 formatIpcError：按当前 lang 走翻译表，en-US 用户看到的
+        // 是英文，不再被 hardcoded 的中文 message 覆盖。kind 不在表里（'unknown'）
+        // 时直接返回 readableMessage — 通常是 spawn error，保留原始细节更有价值。
+        const ipcErr = readIpcError(err)
+        const message = formatIpcError(ipcErr, t)
+        const stderr = typeof ipcErr.details?.['stderr'] === 'string' ? ipcErr.details['stderr'] : undefined
+        setErrorMessage(message)
+        if (stderr) setStderrTail(stderr)
+        setState('error')
+      }
+    },
+    [clearAnalysisState, t]
+  )
+
+  const cancel = useCallback(async () => {
+    // 关键：先把 runIdRef 提一位，再清状态，最后才 await 主进程 cancel。
+    // 顺序错了会出"主进程在跑的 resolve 在 setResult(null) 之前到达 → UI 又被覆盖回 result"的窗口。
+    // 同步把 progressActiveRef 置 false，让飞行中的 PROGRESS 事件被订阅回调丢弃，
+    // 避免 cancel 后进度条仍卡在非零 pct。
+    clearAnalysisState()
+    await window.api.cancel()
+  }, [clearAnalysisState])
+
+  const reset = useCallback(() => {
+    // 递增 runIdRef：reset 会把旧 run 的飞行事件作废（cancel 走的是同一逻辑），
+    // 否则旧 run 的 progress 回调继续推到 idle UI，会让 setProgress 出现鬼影。
+    clearAnalysisState()
+  }, [clearAnalysisState])
+
+  return {
+    result,
+    state,
+    progress,
+    errorMessage,
+    stderrTail,
+    stdout,
+    resultScope,
+    run,
+    cancel,
+    reset,
+    clearStdout: () => setStdout('')
+  }
+}
diff --git a/src/renderer/src/hooks/useExternalFiles.ts b/src/renderer/src/hooks/useExternalFiles.ts
new file mode 100644
index 0000000..ec8dd11
--- /dev/null
+++ b/src/renderer/src/hooks/useExternalFiles.ts
@@ -0,0 +1,238 @@
+/**
+ * 外部文件 tab 状态（stdlib / 第三方包热点打开的源码 tab）。
+ *
+ * 用户代码 tab **不**在这个 hook 里 —— 它由 App.tsx 的 `code` state 持有，
+ * 是唯一可写的 tab，跟随编辑器 onChange 双向绑定。把用户 tab 拆出去避免
+ * OpenFile 类型写成 `Exclude<Origin, 'user'>` 的别扭 union，也让 App
+ * 决定「用户代码的内容是什么」时不需要绕过这个 hook。
+ *
+ * 设计要点：
+ * - **去重 key** = `filePath.replace(/\\/g, '/').toLowerCase()`：Windows 下
+ *   文件系统大小写不敏感，`C:\Python311\Lib\json\__init__.py` 和
+ *   `c:/python311/lib/json/__init__.py` 必须映射到同一个 tab。POSIX 下
+ *   大小写敏感，但 toLowerCase 后错把大小写不同的两个文件当一个 —— 罕见
+ *   （stdlib 不会这样用），可以接受。
+ * - **StrictMode / 卸载安全**：StrictMode mount → cleanup → mount 用 aliveRef
+ *   守卫；卸载后 pending IPC 不会触发 setState（React 18 会喷 warning）。
+ * - **race 处理**：openFile 在 IPC await 之后再 patch tab。如果 await 期间用户
+ *   close 了该 tab，patch 时检查 tab 是否还在外部 tab 列表里 —— 不在就丢弃。
+ * - **pendingReveal**：openFile 时把 `{tabId, line}` 暂存到 ref（同步），
+ *   渲染层在 status 从 loading → ready 的 useEffect 里调 consumePendingReveal
+ *   拿到 line，调 editorRef.current?.revealLine(line)。同一个 tab 多次点
+ *   不同行 → 多次推 pendingReveal → 只保留最后一次的 line。
+ *
+ * 不做的事：
+ * - 不持久化到 localStorage —— 重启后用户重新点热点开 tab，比"恢复一堆
+ *   已经过时的源码 tab"更符合预期。
+ * - 不限 tab 数量 —— 浏览器 tab 风格横向滚动条兜底，正常使用不会开几十个。
+ */
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+/** 排除 user —— 用户代码 tab 不走这个类型。 */
+export type ExternalOrigin = 'stdlib' | 'third_party' | 'builtin' | 'frozen' | 'other'
+
+export type OpenFileStatus = 'loading' | 'ready' | 'error'
+
+/** FileReadResult 里的错误 kind 加一个 unknown（catch 兜底用）。
+ *  跟 shared/analysis 的 FileReadResult 错误分支保持一致；ok 不算 error。 */
+export type FileReadErrorKind =
+  'not_found' | 'not_a_file' | 'permission_denied' | 'too_large' | 'invalid_path' | 'unknown'
+
+export interface OpenFile {
+  /** 稳定的 tab id（useExternalFiles 内部自增分配）。 */
+  id: string
+  /** 绝对文件路径。 */
+  filePath: string
+  /** 归一化后的去重 key（小写 + 正斜杠）。 */
+  dedupKey: string
+  /** tab 上展示的短名（如 `json/__init__.py`），过长截断。 */
+  displayName: string
+  /** origin 决定 tab 颜色和只读语义。 */
+  origin: ExternalOrigin
+  /** 文件内容；status=loading 时是空串，status=error 时是 IPC 错误 message。 */
+  content: string
+  status: OpenFileStatus
+  /** 主进程返回的错误 kind；UI 拿它走 i18n 表。 */
+  errorKind?: FileReadErrorKind
+  /** 原始错误 message（IPC 给的，已翻译无需再做 i18n）。 */
+  errorMessage?: string
+  /** 文件大小（bytes）；成功才有。 */
+  sizeBytes?: number
+}
+
+/** App.tsx 通过这个对象拿到 activeTabId 切换的副作用钩子（reveal line）。 */
+export interface PendingReveal {
+  tabId: string
+  line: number
+}
+
+export interface UseExternalFilesReturn {
+  externalTabs: OpenFile[]
+  /** null = 当前活跃 tab 是用户代码 tab。 */
+  activeExternalId: string | null
+  /**
+   * 打开或激活一个外部文件 tab。
+   * - 同 path 的 tab 已存在 → 设为 active，排队 reveal
+   * - 不存在 → 创建 loading tab，发 IPC，成功置 ready，失败置 error
+   */
+  openFile: (filePath: string, line: number, origin: ExternalOrigin) => void
+  /** 关闭一个外部 tab。关掉的是 active 时，App 应切回用户 tab。 */
+  closeFile: (tabId: string) => void
+  /** 直接设 active（给 EditorTabs onSelect 用）。 */
+  setActive: (tabId: string | null) => void
+  /** 取走最近一次 openFile 暂存的 reveal 信息；ready transition effect 里调。 */
+  consumePendingReveal: () => PendingReveal | null
+  /** 全部外部 tab 的总关接口（给 onLoadSample / onNewBlank 用）。 */
+  closeAll: () => void
+}
+
+/** 去重 key：跨平台大小写不敏感（罕见误合并可接受，见文件头注释）。 */
+function makeDedupKey(filePath: string): string {
+  return filePath.replace(/\\/g, '/').toLowerCase()
+}
+
+/**
+ * 把绝对路径变成短展示名。规则：
+ * - 取最后 1-2 段路径段（POSIX `/` + Windows `\` 都处理）
+ * - 单段时直接展示（如 `foo.py`）
+ * - 末段超过 32 字符只取末段（避免 `json/__init__.py` 因为 `__init__` 被截掉）
+ */
+export function makeDisplayName(filePath: string): string {
+  const parts = filePath.replace(/\\/g, '/').split('/').filter(Boolean)
+  if (parts.length === 0) return filePath
+  if (parts.length === 1) return parts[0]
+  const last = parts[parts.length - 1]
+  const secondLast = parts[parts.length - 2]
+  // 末段本身够短（≤32 字符），展示「父/末」两段，区分同目录不同文件
+  if (last.length <= 32) return `${secondLast}/${last}`
+  return last
+}
+
+let _tabCounter = 0
+function nextTabId(): string {
+  _tabCounter += 1
+  return `ext-${_tabCounter}`
+}
+
+export function useExternalFiles(): UseExternalFilesReturn {
+  const [externalTabs, setExternalTabs] = useState<OpenFile[]>([])
+  const [activeExternalId, setActiveExternalId] = useState<string | null>(null)
+
+  // 闭包安全：openFile / closeFile 是 useCallback 但内部读 externalTabs 会拿到
+  // 渲染时的快照。stale closure 在「快速点同一个文件两次」时会让第二次去重失败，
+  // 重复开 tab。用 ref 持最新值，函数体读 ref.current。
+  const tabsRef = useRef(externalTabs)
+  tabsRef.current = externalTabs
+
+  // StrictMode / 卸载安全。mount → cleanup → mount 路径：第一次 cleanup 置 false
+  // 后第二次 setup 必须显式复位（见 useInterpreters 同款注释）。
+  const aliveRef = useRef(true)
+  useEffect(() => {
+    aliveRef.current = true
+    return () => {
+      aliveRef.current = false
+    }
+  }, [])
+
+  // 待 reveal 的 line：openFile 时同步写，App.tsx 在 status ready 的 effect 里
+  // 调 consumePendingReveal 拿走。用 ref 而非 state —— 触发不了额外渲染，
+  // 也避免「同 tab 多次点击 → state 被覆盖」的中间态。
+  const pendingRevealRef = useRef<PendingReveal | null>(null)
+
+  const openFile = useCallback((filePath: string, line: number, origin: ExternalOrigin) => {
+    const dedupKey = makeDedupKey(filePath)
+    // 1) 去重：同 path 已开 → 激活 + 排队 reveal，return
+    const existing = tabsRef.current.find((t) => t.dedupKey === dedupKey)
+    if (existing) {
+      setActiveExternalId(existing.id)
+      pendingRevealRef.current = { tabId: existing.id, line }
+      return
+    }
+    // 2) 创建 loading tab，设为 active
+    const tabId = nextTabId()
+    const loadingTab: OpenFile = {
+      id: tabId,
+      filePath,
+      dedupKey,
+      displayName: makeDisplayName(filePath),
+      origin,
+      content: '',
+      status: 'loading'
+    }
+    setExternalTabs((prev) => [...prev, loadingTab])
+    setActiveExternalId(tabId)
+    pendingRevealRef.current = { tabId, line }
+    // 3) 发 IPC（fire-and-forget，错误在 promise 链里 catch）
+    void (async () => {
+      try {
+        const result = await window.api.readFile({ filePath })
+        if (!aliveRef.current) return
+        // 关键 race 检查：await 期间用户可能 close 了 tab，或又触发了 openFile
+        // 把同名 tab 重开成 loading（理论上不会，因为我们按 dedup 去重，
+        // 但 close 后再点会触发新一轮；先 close 再 open 的场景）。
+        // 用 functional setState + 检查当前列表里是否还**有同名 dedupKey 的 tab**
+        // 且 id === tabId，避免把「已被新 openFile 替换的旧 tab」再覆盖回去。
+        setExternalTabs((prev) => {
+          const target = prev.find((t) => t.id === tabId)
+          if (!target) return prev
+          if (result.kind === 'ok') {
+            return prev.map((t) =>
+              t.id === tabId
+                ? { ...t, status: 'ready' as const, content: result.content, sizeBytes: result.size }
+                : t
+            )
+          }
+          return prev.map((t) =>
+            t.id === tabId
+              ? { ...t, status: 'error' as const, errorKind: result.kind, errorMessage: result.message }
+              : t
+          )
+        })
+      } catch (err) {
+        if (!aliveRef.current) return
+        // 真正的异常（IPC 通道挂、IpcError 之类）—— 把 message 包成 unknown kind
+        const message = err instanceof Error ? err.message : String(err)
+        setExternalTabs((prev) => {
+          const target = prev.find((t) => t.id === tabId)
+          if (!target) return prev
+          return prev.map((t) =>
+            t.id === tabId
+              ? { ...t, status: 'error' as const, errorKind: 'unknown', errorMessage: message }
+              : t
+          )
+        })
+      }
+    })()
+  }, [])
+
+  const closeFile = useCallback((tabId: string) => {
+    setExternalTabs((prev) => prev.filter((t) => t.id !== tabId))
+    setActiveExternalId((prev) => (prev === tabId ? null : prev))
+  }, [])
+
+  const setActive = useCallback((tabId: string | null) => {
+    setActiveExternalId(tabId)
+  }, [])
+
+  const consumePendingReveal = useCallback((): PendingReveal | null => {
+    const p = pendingRevealRef.current
+    pendingRevealRef.current = null
+    return p
+  }, [])
+
+  const closeAll = useCallback(() => {
+    setExternalTabs([])
+    setActiveExternalId(null)
+    pendingRevealRef.current = null
+  }, [])
+
+  return {
+    externalTabs,
+    activeExternalId,
+    openFile,
+    closeFile,
+    setActive,
+    consumePendingReveal,
+    closeAll
+  }
+}
diff --git a/src/renderer/src/hooks/useInterpreters.ts b/src/renderer/src/hooks/useInterpreters.ts
new file mode 100644
index 0000000..47773af
--- /dev/null
+++ b/src/renderer/src/hooks/useInterpreters.ts
@@ -0,0 +1,191 @@
+/**
+ * Python 解释器检测逻辑。
+ *
+ * 行为要点：
+ * - mount 时自动调 detectAll()
+ * - StrictMode 双调用 / 卸载竞态由 aliveRef 守卫
+ * - 当前 selected 若仍在列表里则保留，否则回退到第一个
+ *
+ * 并发请求守卫（tokenRef）：
+ * - 之前只有 aliveRef，渲染后用户连点「刷新」或 pick 后又触发了 detectAll，
+ *   两个 IPC 调用并行跑，晚到的旧调用会 setState 覆盖新结果。
+ * - 现在 detectAll / pick 各自带 myToken，await 之后比对 tokenRef.current；
+ *   已被新调用作废的旧调用 short-circuit return。
+ *
+ * selected 持久化（pyrof.interpreter）：
+ * - 跟 theme / shell / lang / scope 一套 localStorage 持久化，避免重启软件
+ *   后用户在 Settings 里手动选过的解释器丢失。
+ * - 检测时当前 selected 不在新列表里 → 回退到第一个；这条兜底路径也要写回
+ *   持久化，否则下次启动又跑回无效路径再 fallback（循环）。
+ */
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { InterpreterInfo } from '../../../shared/analysis'
+import { readIpcError } from '../../../shared/ipc'
+import { useT } from '../i18n'
+import { formatIpcError } from '../utils/ipcErrorFormat'
+
+/**
+ * 解释器选择的 localStorage key。跟 theme / shell / lang / scope 一个套路。
+ *
+ * 不存 InterpreterInfo 全字段（path + version）—— version 随 python 升级会变，
+ * 存 version 反而容易过期；path 是稳定标识，version 在每次启动重新探测得到。
+ */
+export const STORAGE_KEY_INTERPRETER = 'pyrof.interpreter'
+
+/** 从 localStorage 读出上次保存的解释器路径；读不到或 localStorage 不可用时返回 ''。 */
+export function readStoredInterpreterPath(): string {
+  try {
+    return localStorage.getItem(STORAGE_KEY_INTERPRETER) ?? ''
+  } catch {
+    // file:// / 无存储权限时静默回退 — 不挡启动
+    return ''
+  }
+}
+
+/** 把当前 selected path 写回 localStorage。
+ *  path 为空字符串时不写入（旧值会被删除），避免把 "无选择" 这个瞬态写成持久值。 */
+function persistInterpreterPath(path: string): void {
+  try {
+    if (path) localStorage.setItem(STORAGE_KEY_INTERPRETER, path)
+    else localStorage.removeItem(STORAGE_KEY_INTERPRETER)
+  } catch {
+    // localStorage 不可用时静默吞 — 跟 useTheme / useShellPreference 一个套路
+  }
+}
+
+export interface UseInterpretersResult {
+  interpreters: InterpreterInfo[]
+  selected: string
+  /**
+   * 切换当前选中的解释器路径。原名 setSelected → selectPath，凸显"操作的是 path"，
+   * Settings 下拉、MinimalRunConfig 提示行都通过它改 selected。
+   */
+  selectPath: (path: string) => void
+  detecting: boolean
+  detectError: string | null
+  pickError: string | null
+  /** 重新扫描系统中的解释器 */
+  detectAll: () => Promise<void>
+  /** 弹出系统文件选择器让用户手动选 python.exe */
+  pick: () => Promise<void>
+  /** 当前选中的解释器（undefined = 未选） */
+  active: InterpreterInfo | undefined
+}
+
+export function useInterpreters(): UseInterpretersResult {
+  const t = useT()
+  const [interpreters, setInterpreters] = useState<InterpreterInfo[]>([])
+  // 初始值从 localStorage 读：上次选择过的解释器，重启后默认选中。
+  // 与 theme / shell / scope 同套路 —— 单 tab 单窗口，跨 tab 同步无收益，不监听 storage 事件。
+  const [selected, setSelectedState] = useState<string>(() => readStoredInterpreterPath())
+  const [detecting, setDetecting] = useState(false)
+  const [pickError, setPickError] = useState<string | null>(null)
+  const [detectError, setDetectError] = useState<string | null>(null)
+
+  /**
+   * selected 一变就同步写回 localStorage。mount 那次也跑一次：
+   * - 持久值非空时等同于「再写一次相同值」,无副作用。
+   * - 持久值为空时把空值 removeItem —— 跟 detectAll fallback 兜底逻辑保持一致。
+   *
+   * 走 useEffect 而不是包装 setState callback —— 是 React 的标准姿势：
+   * functional updater 在 StrictMode 下会被调用两次,放进 useEffect 走 commit 后
+   * 单次执行更安全。这里没在 detectAll 里写 setSelectedState callback 的
+   * "current 兜底"逻辑 —— 见下方 detectAll 内注释。
+   */
+  useEffect(() => {
+    persistInterpreterPath(selected)
+  }, [selected])
+
+  const aliveRef = useRef(true)
+  useEffect(() => {
+    // StrictMode 下 mount 周期是 setup → cleanup → setup：cleanup 把 aliveRef 置 false 后
+    // 第二次 setup 必须显式复位，否则后续异步 resolve 全部 short-circuit，检测永远完不成
+    aliveRef.current = true
+    return () => {
+      aliveRef.current = false
+    }
+  }, [])
+
+  // 并发请求号：每次 detectAll / pick 启动时 ++，await 之后若号不对应就丢弃。
+  const requestTokenRef = useRef(0)
+  // StrictMode 双调用守卫：mount 时自动 detectAll 一次，第二次 setup 直接跳过。
+  const hasAutoDetectedRef = useRef(false)
+
+  const detectAll = useCallback(async () => {
+    const myToken = ++requestTokenRef.current
+    setDetecting(true)
+    setDetectError(null)
+    try {
+      const list = await window.api.detectInterpreters()
+      if (!aliveRef.current || myToken !== requestTokenRef.current) return
+      setInterpreters(list)
+      // setSelectedState(functional) 写法:从 current 推断"保留 / 回退",然后
+      // useEffect 听到 selected 变了再 persistInterpreterPath —— fallback 路径也走这条,
+      // 否则持久化里一直是个无效路径,下次启动又跑 fallback(浪费一次 IPC)。
+      setSelectedState((current) => {
+        if (current && list.find((i) => i.path === current)) return current
+        return list[0]?.path ?? ''
+      })
+    } catch (err) {
+      if (!aliveRef.current || myToken !== requestTokenRef.current) return
+      // IPC 错误统一过 formatIpcError：按当前 lang 走翻译表，en-US 用户
+      // 看到的是英文而不是 main 进程 hardcoded 的中文 message。
+      const ipcErr = readIpcError(err)
+      setDetectError(formatIpcError(ipcErr, t))
+    } finally {
+      if (aliveRef.current && myToken === requestTokenRef.current) setDetecting(false)
+    }
+  }, [t])
+
+  useEffect(() => {
+    // StrictMode mount → cleanup → mount：第一次 cleanup 后 hasAutoDetectedRef 已被设 true，
+    // 第二次 setup 直接 short-circuit，避免两路并行 IPC 探测（每个探测都跑 20+ fs probe）。
+    if (hasAutoDetectedRef.current) return
+    hasAutoDetectedRef.current = true
+    // detectAll 内部已经把失败 catch 在 finally 里，外部无未处理 rejection —— 用 void 标
+    // 记"故意 fire-and-forget"，让 ESLint 不会再警告无 await 的 promise
+    void detectAll()
+  }, [detectAll])
+
+  const pick = useCallback(async () => {
+    // pick 必须用自己的 token —— 否则会和 detectAll 共享 requestTokenRef，
+    // pick 在 mount 时 detectAll 未结束时被触发会让 detectAll 的 finally
+    // 因为 token 不匹配而 short-circuit，结果 `setDetecting(false)` 永远不调用，
+    // 「detecting」卡在 true 永久禁用 Settings 里的下拉框。
+    const myToken = ++requestTokenRef.current
+    setPickError(null)
+    try {
+      const info = await window.api.pickInterpreter()
+      if (!aliveRef.current || myToken !== requestTokenRef.current) return
+      // null = 用户在系统对话框里取消 —— 静默返回,不报错
+      if (!info) return
+      setInterpreters((prev) => {
+        const without = prev.filter((i) => i.path !== info.path)
+        return [info, ...without]
+      })
+      setSelectedState(info.path)
+    } catch (err) {
+      if (!aliveRef.current || myToken !== requestTokenRef.current) return
+      // main 进程在选错文件 / 解释器启动失败时统一 throw IpcError(IPC_ERROR_I18N_KEYS
+      // 表里 'interpreter_not_allowed' / 'interpreter_probe_failed' 已有翻译);
+      // 这里走 formatIpcError → en-US 用户看到的是 "Selected file is not a valid Python
+      // interpreter" 而不是中文 message。
+      const ipcErr = readIpcError(err)
+      setPickError(formatIpcError(ipcErr, t))
+    }
+  }, [t])
+
+  const active = interpreters.find((i) => i.path === selected)
+
+  return {
+    interpreters,
+    selected,
+    selectPath: setSelectedState,
+    detecting,
+    detectError,
+    pickError,
+    detectAll,
+    pick,
+    active
+  }
+}
diff --git a/src/renderer/src/hooks/useResizableFraction.ts b/src/renderer/src/hooks/useResizableFraction.ts
new file mode 100644
index 0000000..16113fc
--- /dev/null
+++ b/src/renderer/src/hooks/useResizableFraction.ts
@@ -0,0 +1,123 @@
+/**
+ * 区域尺寸 hook —— 主区↔编辑器 / 主区↔终端的 splitter 都用它。
+ *
+ * 持久化到 localStorage:`pyrof.split.<region>`(由调用方传 key)。
+ * 默认 / 范围超出 → clamp 到 [min, max],不让用户把面板拖没或拖爆。
+ *
+ * applyDelta(deltaPx, containerSize) 把像素 delta 按容器宽度换算成 fraction 增量:
+ *   deltaFrac = deltaPx / containerSize
+ * 容器尺寸 <= 0 时静默忽略 —— splitter 还没拿到尺寸时拖动是常见竞态,
+ * 不应该让 fraction 跳变成 NaN / Infinity。
+ *
+ * setFraction 接受函数式更新 (setFraction(prev => prev + 0.05)),splitter 内部
+ * 累加拖拽时用得到。
+ *
+ * file:// 下 localStorage 会抛 SecurityError:跟 useTheme / useScope 一样静默吞,
+ * 行为退化成「本次会话内存里有尺寸,刷新后回 default」。
+ */
+import { useCallback, useState } from 'react'
+
+interface Options {
+  /** 默认 fraction,初始化时若 localStorage 没有值就用它(也会被 clamp) */
+  default: number
+  /** 最小值,拖不到这以下 */
+  min: number
+  /** 最大值,拖不到这以上 */
+  max: number
+}
+
+function clamp(v: number, min: number, max: number): number {
+  // NaN 单独处理 —— NaN < min / NaN > max 都返回 false,不挡的话会直接落穿到 return v,
+  // 把 NaN 灌进 React state 后下游 splitter 算 delta 全变 NaN。
+  if (!Number.isFinite(v)) return min
+  if (v < min) return min
+  if (v > max) return max
+  return v
+}
+
+function readStored(key: string, options: Options): number {
+  try {
+    const raw = localStorage.getItem(key)
+    const n = raw === null ? NaN : Number(raw)
+    return Number.isFinite(n)
+      ? clamp(n, options.min, options.max)
+      : clamp(options.default, options.min, options.max)
+  } catch {
+    return clamp(options.default, options.min, options.max)
+  }
+}
+
+export interface UseResizableFractionReturn {
+  fraction: number
+  setFraction: (next: number | ((prev: number) => number)) => void
+  applyDelta: (deltaPx: number, containerSize: number) => void
+}
+
+export function useResizableFraction(key: string, options: Options): UseResizableFractionReturn {
+  // type 提取出来后给测试用 —— renderHook 在 it() 内部重新 destructure 时
+  // TS 容易把 result 当 error 类型(同作用域里多次调用 + 内联箭头),显式标注能消解
+  // 跨测试的访问错误。
+  const [fraction, setFractionState] = useState<number>(() => readStored(key, options))
+
+  const write = useCallback(
+    (next: number) => {
+      const clamped = clamp(next, options.min, options.max)
+      setFractionState(clamped)
+      try {
+        localStorage.setItem(key, String(clamped))
+      } catch {
+        // file:// 下静默吞;内存 state 已经更新,只是不持久化
+      }
+    },
+    [key, options.min, options.max]
+  )
+
+  const setFraction = useCallback(
+    (next: number | ((prev: number) => number)) => {
+      // 函数式更新走 functional setState,跟 applyDelta 一致 —— 否则连写两次
+      // `setFraction(prev => prev + 0.05)` 会用闭包里同一份 stale fraction
+      // 做 base,第二次被吞。
+      if (typeof next === 'function') {
+        setFractionState((prev) => {
+          const computed = next(prev)
+          const clamped = clamp(computed, options.min, options.max)
+          try {
+            localStorage.setItem(key, String(clamped))
+          } catch {
+            // file:// 下静默吞;内存 state 已经更新,只是不持久化
+          }
+          return clamped
+        })
+      } else {
+        write(next)
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- options.min/max 同上
+    [write, key, options.min, options.max]
+  )
+
+  const applyDelta = useCallback(
+    (deltaPx: number, containerSize: number) => {
+      // 容器没尺寸时 splitter 还看不见,deltaPx 没有意义,直接忽略
+      if (containerSize <= 0) return
+      // 用函数式 setState：Splitter 在 pointermove 里以「相对上次的位置」emit 增量，
+      // 两次 emit 之间 React 可能还没 commit；如果读闭包里的 fraction 作 base，
+      // 后一次会用同一个 stale base，第二个 deltaPx 被静静吞掉。
+      // App 的 applyTerminalDelta 之前用对了这里，useResizableFraction 漏了。
+      setFractionState((prev) => {
+        const next = clamp(prev + deltaPx / containerSize, options.min, options.max)
+        try {
+          localStorage.setItem(key, String(next))
+        } catch {
+          // file:// 下静静吞；内存 state 已经更新，只是不持久化
+        }
+        return next
+      })
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- options.min/max 是 Options
+    // 字面量，hook 调用方每次 render 都重新构造；引用稳定与否不影响 setFractionState 函数语义
+    [key, options.min, options.max]
+  )
+
+  return { fraction, setFraction, applyDelta }
+}
diff --git a/src/renderer/src/hooks/useScope.ts b/src/renderer/src/hooks/useScope.ts
new file mode 100644
index 0000000..56b262f
--- /dev/null
+++ b/src/renderer/src/hooks/useScope.ts
@@ -0,0 +1,58 @@
+/**
+ * 剖析范围 hook：用户代码 vs 全部代码（含标准库 + 第三方包）。
+ *
+ * 持久化到 `pyrof.scope` —— 同 lang / theme 一个套路。
+ * 用户切过一次后,关闭软件重新打开会保留上次选择（读 localStorage）,
+ * 只有首次启动或 localStorage 被清空时才落到默认 `all`。
+ *
+ * 默认 `all`：含库函数模式，让 pandas.read_csv / json.loads 这类黑盒
+ * 也能下钻 —— 这是 v3 之后定位瓶颈的主路径。
+ *
+ * 不监听 `storage` 事件：单 tab 单窗口，跨 tab 同步无收益。
+ */
+import { useCallback, useState } from 'react'
+
+export type ProfileScope = 'user' | 'all'
+
+export const DEFAULT_SCOPE: ProfileScope = 'all'
+export const STORAGE_KEY_SCOPE = 'pyrof.scope'
+
+export function readStoredScope(): ProfileScope {
+  try {
+    const v = localStorage.getItem(STORAGE_KEY_SCOPE)
+    // 显式判 'user' / 'all'：localStorage 里被人手动改坏掉时静默回落到默认,
+    // 不会因为 v === 'somethingelse' 而把 scope 强行置为 user 误导用户。
+    if (v === 'user') return 'user'
+    if (v === 'all') return 'all'
+    return DEFAULT_SCOPE
+  } catch {
+    return DEFAULT_SCOPE
+  }
+}
+
+export function useScope(): { scope: ProfileScope; setScope: (s: ProfileScope) => void; toggle: () => void } {
+  const [scope, setScopeState] = useState<ProfileScope>(() => readStoredScope())
+
+  const setScope = useCallback((next: ProfileScope) => {
+    setScopeState(next)
+    try {
+      localStorage.setItem(STORAGE_KEY_SCOPE, next)
+    } catch {
+      // file:// 协议下 StorageError 静默吞
+    }
+  }, [])
+
+  const toggle = useCallback(() => {
+    setScopeState((prev) => {
+      const next: ProfileScope = prev === 'all' ? 'user' : 'all'
+      try {
+        localStorage.setItem(STORAGE_KEY_SCOPE, next)
+      } catch {
+        // 同上
+      }
+      return next
+    })
+  }, [])
+
+  return { scope, setScope, toggle }
+}
diff --git a/src/renderer/src/hooks/useShellPreference.ts b/src/renderer/src/hooks/useShellPreference.ts
new file mode 100644
index 0000000..6c95b98
--- /dev/null
+++ b/src/renderer/src/hooks/useShellPreference.ts
@@ -0,0 +1,45 @@
+/**
+ * 打开系统终端时用的 shell 选择。
+ *
+ * - Windows 上默认 cmd.exe(快、依赖少、winget 直接跑);用户偏好可切到 PowerShell。
+ * - 非 Windows 平台 shell 由 OS 决定(Terminal.app / gnome-terminal 等),这个偏好不生效。
+ *
+ * 持久化到 `pyrof.shell`,跟 theme / lang / interpreter 一套。
+ */
+import { useCallback, useEffect, useState } from 'react'
+
+export type Shell = 'cmd' | 'powershell'
+export const DEFAULT_SHELL: Shell = 'cmd'
+export const STORAGE_KEY_SHELL = 'pyrof.shell'
+
+export function readStoredShell(): Shell {
+  try {
+    const v = localStorage.getItem(STORAGE_KEY_SHELL)
+    return v === 'powershell' ? 'powershell' : DEFAULT_SHELL
+  } catch {
+    return DEFAULT_SHELL
+  }
+}
+
+export function useShellPreference(): { shell: Shell; setShell: (s: Shell) => void } {
+  const [shell, setShellState] = useState<Shell>(() => readStoredShell())
+
+  const setShell = useCallback((next: Shell) => {
+    setShellState(next)
+    try {
+      localStorage.setItem(STORAGE_KEY_SHELL, next)
+    } catch {
+      /* file:// 协议下 StorageError 静默吞 */
+    }
+  }, [])
+
+  // 非 Windows 上忽略持久值 —— macOS / Linux 用 OS 自带 terminal,跟 cmd/PowerShell 无关。
+  // mount 时把持久值兜回默认,避免用户在 Win 设置过 PowerShell 然后拿到 Mac 上还显示 PowerShell。
+  useEffect(() => {
+    if (window.api.platform !== 'win32' && shell !== DEFAULT_SHELL) {
+      setShellState(DEFAULT_SHELL)
+    }
+  }, [shell])
+
+  return { shell, setShell }
+}
diff --git a/src/renderer/src/hooks/useTheme.ts b/src/renderer/src/hooks/useTheme.ts
new file mode 100644
index 0000000..f747c92
--- /dev/null
+++ b/src/renderer/src/hooks/useTheme.ts
@@ -0,0 +1,56 @@
+/**
+ * 主题切换 hook。深 / 浅二选一，CSS variables 在 :root / :root.light 之间切换，
+ * Tailwind 工具类（`bg-bg` `text-fg` 等）通过 `rgb(var(--xxx-rgb) / <alpha-value>)`
+ * 自动跟随。
+ *
+ * 持久化到 `pyrof.theme`，key 同 lang / interpreter 三个一套。
+ * 默认 `dark`（用户偏好）。
+ *
+ * 不监听 `storage` 事件：Electron 单 tab 单窗口，跨 tab 同步无收益。
+ */
+import { useCallback, useEffect, useState } from 'react'
+
+export type Theme = 'dark' | 'light'
+
+export const DEFAULT_THEME: Theme = 'dark'
+export const STORAGE_KEY_THEME = 'pyrof.theme'
+
+export function readStoredTheme(): Theme {
+  try {
+    const v = localStorage.getItem(STORAGE_KEY_THEME)
+    return v === 'light' ? 'light' : DEFAULT_THEME
+  } catch {
+    return DEFAULT_THEME
+  }
+}
+
+/**
+ * 把 theme 同步到 <html> class。index.html 里的 inline script 已经在挂载前
+ * 设过一次 class；这里 mount 时再 sync 一次防御（理论上不会变，但保险）。
+ */
+function applyTheme(theme: Theme): void {
+  const root = document.documentElement
+  root.classList.remove('dark', 'light')
+  root.classList.add(theme)
+}
+
+export function useTheme(): { theme: Theme; setTheme: (t: Theme) => void } {
+  const [theme, setThemeState] = useState<Theme>(() => readStoredTheme())
+
+  const setTheme = useCallback((next: Theme) => {
+    setThemeState(next)
+    try {
+      localStorage.setItem(STORAGE_KEY_THEME, next)
+    } catch {
+      // file:// 协议下 StorageError 静默吞
+    }
+    applyTheme(next)
+  }, [])
+
+  // mount 时再同步一次（覆盖罕见 race：inline script 之前抛了 / localStorage 被外部进程改了）
+  useEffect(() => {
+    applyTheme(theme)
+  }, [theme])
+
+  return { theme, setTheme }
+}
diff --git a/src/renderer/src/i18n/__tests__/i18n.test.ts b/src/renderer/src/i18n/__tests__/i18n.test.ts
new file mode 100644
index 0000000..430c470
--- /dev/null
+++ b/src/renderer/src/i18n/__tests__/i18n.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+import { t, zhCN, enUS, DEFAULT_LANG, readStoredLang } from '../index'
+import type { StringKey } from '../zh-CN'
+
+/**
+ * i18n 核心回归：
+ * - 中英文 key 完全对齐（编译期靠 Record<StringKey, string> 守，运行期也守一遍）
+ * - 占位符 `{name}` 在两种语言下都能正确替换
+ * - 默认语言回退：当 zh-CN 缺 key 时回退到 en-US（或反过来）都不应崩
+ * - readStoredLang 在 localStorage 抛错时回退到默认
+ */
+
+describe('i18n dictionaries', () => {
+  it('en-US 覆盖 zh-CN 的所有 key（key parity）', () => {
+    const zhKeys = Object.keys(zhCN) as StringKey[]
+    const enKeys = Object.keys(enUS)
+    expect(new Set(enKeys)).toEqual(new Set(zhKeys))
+  })
+
+  it('en-US 没有任何空白翻译（防止新增 zh-CN key 后忘了英译）', () => {
+    for (const k of Object.keys(zhCN) as StringKey[]) {
+      expect(enUS[k], `en-US 缺翻译: ${k}`).toBeTruthy()
+      expect(enUS[k].trim().length, `en-US 空翻译: ${k}`).toBeGreaterThan(0)
+    }
+  })
+
+  it('默认语言是中文', () => {
+    expect(DEFAULT_LANG).toBe('zh-CN')
+  })
+})
+
+describe('t()', () => {
+  it('zh-CN 拿原文', () => {
+    expect(t('topbar.title', 'zh-CN')).toBe('Python 程序耗时可视化分析')
+    expect(t('hotspot.empty', 'zh-CN')).toBe('没有可显示的函数')
+  })
+
+  it('en-US 拿英译', () => {
+    expect(t('topbar.title', 'en-US')).toBe('Python Program Time Profiler')
+    expect(t('hotspot.empty', 'en-US')).toBe('No functions to display')
+  })
+
+  it('占位符 {name} / {pct} / {message} 全部替换', () => {
+    expect(t('app.live.running', 'zh-CN', { pct: 42 })).toBe('运行中 42%')
+    expect(t('app.live.error', 'en-US', { message: 'boom' })).toBe('Error: boom')
+  })
+
+  it('缺省 params 时占位符原样保留（让 grep 仍能找到未传 key）', () => {
+    expect(t('app.live.running', 'zh-CN')).toBe('运行中 {pct}%')
+  })
+})
+
+describe('readStoredLang', () => {
+  it('localStorage 为空时回退到默认', () => {
+    window.localStorage.clear()
+    expect(readStoredLang()).toBe('zh-CN')
+  })
+
+  it('localStorage 是 en-US 时返回 en-US', () => {
+    window.localStorage.setItem('pyrof.lang', 'en-US')
+    expect(readStoredLang()).toBe('en-US')
+  })
+
+  it('localStorage 是非法值时回退到默认（容错）', () => {
+    window.localStorage.setItem('pyrof.lang', 'zh-XX')
+    expect(readStoredLang()).toBe('zh-CN')
+  })
+})
diff --git a/src/renderer/src/i18n/en-US.ts b/src/renderer/src/i18n/en-US.ts
new file mode 100644
index 0000000..5d40a6b
--- /dev/null
+++ b/src/renderer/src/i18n/en-US.ts
@@ -0,0 +1,289 @@
+/**
+ * English interface text. Same shape as zh-CN.ts (key parity is type-checked by StringKey).
+ *
+ * 不翻译的术语：Tottime / Cumtime / Calls / Per call / Ctrl+Enter / Function /
+ * Python / cProfile —— 在中文里也不翻，是 Python 性能生态的标准命名。
+ * 翻译会让用户查 cProfile 文档、Linear UI 时找不到对应。
+ */
+import type { StringKey } from './zh-CN'
+
+export const enUS: Record<StringKey, string> = {
+  // App
+  'app.live.running': 'Running {pct}%',
+  'app.live.done': 'Analysis complete',
+  'app.live.error': 'Error: {message}',
+  'app.editorLoading': 'Editor loading…',
+
+  // TopBar
+  'topbar.title': 'Python Program Time Profiler',
+  'topbar.shortcutHint': 'Ctrl+Enter to run',
+  'topbar.openSettings': 'Open settings',
+  'topbar.switchLanguage': 'Switch language',
+  'topbar.switchLanguageTo': 'Switch to {target}',
+  'topbar.toggleTheme': 'Toggle theme',
+  'topbar.theme.toLight': 'Switch to light theme',
+  'topbar.theme.toDark': 'Switch to dark theme',
+  'topbar.lang.zh': '中文',
+  'topbar.lang.en': 'EN',
+  'topbar.openTerminal': 'Open system terminal',
+  // Top-right window controls (frame:false hides the OS titlebar; these custom buttons take over)
+  'topbar.window.minimize': 'Minimize',
+  'topbar.window.maximize': 'Maximize',
+  'topbar.window.restore': 'Restore',
+  'topbar.window.close': 'Close',
+
+  // Splitter (drag handles between regions)
+  'splitter.main.aria': 'Drag to resize editor and results',
+  // Editor ↔ run output panel (top/bottom split on the left) — separate label
+  // from the main vertical splitter so screen-reader users get useful orientation
+  'splitter.console.aria': 'Drag to resize editor and run output panel',
+
+  // Settings modal
+  'settings.title': 'Settings',
+  'settings.close': 'Close',
+  'settings.section.interpreter': 'Interpreter',
+  'settings.section.shell': 'Terminal',
+  'settings.shell.label': 'Shell for opening terminal',
+  'settings.shell.cmd': 'Command Prompt (cmd)',
+  'settings.shell.powershell': 'PowerShell',
+  'settings.shell.hint':
+    'Both the TopBar "Open terminal" button and the install-Python prompt use this shell',
+  'settings.interpreter.label': 'Python interpreter',
+  'settings.interpreter.browse': 'Browse…',
+  'settings.interpreter.rescan': 'Rescan',
+  'settings.interpreter.empty': 'No Python detected',
+  'settings.interpreter.detecting': 'Scanning…',
+  'settings.interpreter.detectError': 'Failed to scan interpreters: {message}',
+  'settings.interpreter.pickError': 'Failed to pick interpreter: {message}',
+  // Terminal (when no Python detected, let users install via system terminal)
+  'settings.terminal.openCmd': 'Open terminal to install Python',
+  'settings.terminal.hint': 'Terminal opens with the install command pre-filled — press Enter to run',
+  'settings.terminal.error': 'Failed to open terminal: {message}',
+  // About — developer info + personal page link
+  'settings.section.about': 'About',
+  'settings.about.developer': 'Developer',
+  'settings.about.developerName': 'Guan Jihuan',
+  'settings.about.website': 'https://www.guanjihuan.com/about',
+  'settings.about.linkAria': 'Visit {name}’s personal page',
+
+  // MinimalRunConfig
+  'runconfig.run': 'Run analysis',
+  'runconfig.cancel': 'Cancel',
+  'runconfig.loadSample': 'Load sample',
+  'runconfig.newBlank': 'New blank',
+  'runconfig.shortcut': 'Ctrl+Enter',
+  'runconfig.progress': 'Run progress',
+  'runconfig.needInterpreter': 'No Python interpreter selected (pick one in Settings)',
+  // Profile scope toggle: default "all" (include libraries); toggle off switches to user-only
+  'runconfig.scope.user': 'User code only',
+  'runconfig.scope.all': 'Include libraries',
+  'runconfig.scope.aria': 'Profile scope: {scope}. Click to toggle.',
+
+  // EmptyState
+  'empty.eyebrow': 'How to use',
+  'empty.title': 'Paste code, instantly see what is slow',
+  'empty.subtitle': 'Code on the left, time breakdown on the right.',
+  'empty.step1.title': 'Paste Python code',
+  'empty.step1.desc': 'Or write directly in the editor on the left',
+  'empty.step2.title': 'Pick a Python interpreter',
+  'empty.step2.desc': 'Not found? Click "Browse…" to pick one',
+  'empty.step3.title': 'Run analysis',
+  'empty.step3.desc': 'See how long each function takes',
+  'empty.running': 'Running…',
+  'empty.needInterpreter': 'Pick a Python interpreter first',
+  'empty.needInterpreterDesc': 'Open Settings → Interpreter → Browse… to choose python.exe',
+  'empty.openSettings': 'Open settings',
+
+  // HotspotTable
+  'hotspot.empty': 'No functions to display',
+  'hotspot.emptyFiltered': 'No functions match this filter. Click "All {total}" to restore.',
+  'hotspot.col.function': 'Function',
+  'hotspot.col.tottime': 'Tottime',
+  'hotspot.col.cumtime': 'Cumtime',
+  'hotspot.col.calls': 'Calls',
+  'hotspot.col.percall': 'Per call',
+  'hotspot.col.line': 'line {line}',
+  'hotspot.row.aria': '{name} ({origin}) line {line}, self-time {tottime}, called {calls} times',
+  'hotspot.row.ariaSelected':
+    '{name} ({origin}) line {line}, self-time {tottime}, called {calls} times, selected',
+  'hotspot.sortBy': 'Sort by {label}',
+  'hotspot.truncated': 'Showing first {visible} rows, {hidden} more hidden',
+  'hotspot.totals': 'Showing all {total} rows',
+  'hotspot.expand': 'Show all {total} rows',
+  'hotspot.collapse': 'Collapse to first {cap} rows',
+  // Zero-time frame filter — scope=all fans out into hundreds of tottime=0 frames
+  // (typing/inspect/etc. internal calls below cProfile's ~1µs quantization).
+  // Hidden by default with an opt-in toggle for callers who want to inspect the call trail.
+  'hotspot.zeroTimeHidden': '{hidden} zero-time frames hidden (below cProfile quantization)',
+  'hotspot.zeroTimeShow': 'Show zero-time frames',
+  'hotspot.zeroTimeHide': 'Hide zero-time frames',
+  // Test code filter — test_xxx / tests/ / TestCase.test_xxx hidden by default
+  'hotspot.testCodeHidden': '{hidden} test-code frames hidden (test_xxx / tests/ / TestCase)',
+  'hotspot.testCodeShow': 'Show test code',
+  'hotspot.testCodeHide': 'Hide test code',
+  // Module filter chips — only shown in scope=all so the table doesn't drown in stdlib
+  'hotspot.module.allFilter': 'All {total}',
+  'hotspot.module.filter': '{module} {count}',
+  'hotspot.module.aria': 'Filter by module: {label}, showing {shown} of {total}',
+
+  // FlameGraph
+  'flame.empty': 'No functions to display',
+  'flame.aria': 'Flame graph',
+  'flame.reset': 'Reset',
+  'flame.reset.aria': 'Reset flame graph',
+  'flame.tile.aria': '{name} self-time {value}s, {pct}% of total',
+  'flame.tile.drill': ' (press Enter to drill in)',
+
+  // ErrorBanner
+  'errorBanner.title': 'Run failed',
+  'errorBanner.retry': 'Retry',
+  'errorBanner.unknown': 'Unknown error',
+  'errorBanner.logDetails': 'View engine log',
+
+  // FailureResult
+  'failure.title.timeout': 'Run timed out',
+  'failure.title.syntax': 'Syntax error',
+  'failure.title.runtime': 'Runtime error',
+  'failure.retry': 'Retry',
+  'failure.logDetails': 'View engine log',
+
+  // ErrorBoundary
+  'errorBoundary.title': 'Something went wrong',
+  'errorBoundary.retry': 'Retry',
+  'errorBoundary.reload': 'Reload page',
+  'errorBoundary.consoleError': '[ErrorBoundary] Component threw:',
+
+  // RunSummaryLite
+  'summary.wallTime': 'Wall time',
+  'summary.functionCount': 'Functions',
+  // Sub-info for the function count tile — only shown when multiple modules
+  // (scope=all); single-module scope=user would just be noise.
+  'summary.moduleCount': '{count} modules',
+  'summary.hottest': 'Hottest function',
+  'summary.hottestSub': 'self-time {tottime}, called {calls} times',
+  // Wall time is much larger than cProfile attribution total — likely includes
+  // a blocking event-loop wait (plt.show / input / cv2.waitKey). cProfile
+  // can't see these waits, so the flame graph looks deceptively small compared
+  // to the wall-time number. {gap} is the unattributed seconds.
+  // Hover title gives the full explanation.
+  'summary.wallTimeHint': 'Interactive wait · unattributed {gap}',
+  'summary.wallTimeHintTitle':
+    'This unaccounted time comes from blocking calls in user code (matplotlib window / input() / cv2.waitKey, etc.). cProfile cannot see it, so the flame graph looks smaller than the wall time.',
+  // v4 wall-time is estimated (instrumented / cProfile calibration ratio), labelled with a chip.
+  'summary.wallTimeCalibrated': 'calibrated',
+  'summary.wallTimeCalibratedTitle':
+    'Wall time is estimated; cProfile overhead ({ratio}×) has been compensated.',
+
+  // ResultsPanel
+  'results.hotspot.title': 'Hotspot functions',
+  'results.hotspot.hint': '{n} total',
+  'results.time.title': 'Time distribution',
+  'results.time.hint': 'Same data, switch views',
+  // Result is from an older scope. Don't auto-rerun (each run takes 1-10s);
+  // show a status banner with a "rerun with new scope" button.
+  'results.scopeStale.eyebrow': 'Scope changed',
+  'results.scopeStale.body': 'This result was profiled with "{old}", scope is now "{new}"',
+  'results.scopeStale.rerun': 'Rerun with new scope',
+
+  // Chart switcher
+  'chart.switcher.label': 'Switch chart type',
+  'chart.type.flame': 'Flame graph',
+  'chart.type.bar': 'Bar chart',
+  'chart.type.treemap': 'Treemap',
+  'chart.type.sunburst': 'Sunburst',
+  'chart.type.cumulative': 'Cumulative',
+  'chart.type.heatmap': 'Module heatmap',
+  'chart.empty': 'No time data',
+  'chart.truncated': 'Showing first {shown}, {hidden} more hidden',
+  // Multi-depth truncation message shared by FlameGraph / Treemap / Sunburst.
+  // {depths}: how many depth layers had truncation; {shown}: per-layer cap;
+  // {hidden}: total sibling count hidden across all layers.
+  'chart.flame.truncatedMulti':
+    'Truncated across {depths} layers · showing first {shown}/layer · {hidden} siblings hidden',
+  // Per-chart hint (replaces the generic chart.note) — each chart says something specific
+  'chart.flame.hint': 'Click tiles with children to drill in',
+  'chart.bar.hint': 'Ranked by self-time · length = share of total',
+  'chart.treemap.hint': 'Area = self-time share · color consistent across views',
+  'chart.sunburst.hint': 'Arc length = self-time share · center = total',
+  'chart.cumulative.hint': 'Ranked by cumulative time · dark segment = self-time',
+  'chart.heatmap.hint': 'By module · block area = self-time share',
+  // Sunburst center "N functions" summary
+  'chart.sunburst.totalFns': '{count} functions',
+  'chart.bar.aria': 'Bar chart sorted by self-time',
+  'chart.bar.tile.aria': '{name} ({origin}) self-time {value}, {pct}% of total',
+  'chart.treemap.aria': 'Time treemap',
+  'chart.treemap.tile.aria': '{name} self-time {value}, {pct}% of total',
+  'chart.sunburst.aria': 'Time sunburst',
+  'chart.sunburst.slice.aria': '{name} self-time {value}, {pct}% of total',
+  'chart.cumulative.aria': 'Bars ranked by cumulative time',
+  'chart.cumulative.tile.aria': '{name} ({origin}) cumulative {cum}, self-time {self}, {pct}% of total',
+  'chart.cumulative.selfSeg': 'self-time',
+  'chart.cumulative.cumSeg': 'callee time',
+  // Right-aligned text: "{pct}% self · {cum}" — {pct} is this function's self-time
+  // share of its own cumtime, NOT total. Bar length is total share. Both must
+  // be visually distinct or the two percentages contradict each other.
+  'chart.cumulative.rightText': '{pct}% self · {cum}',
+  'chart.heatmap.aria': 'Module-grouped heatmap',
+  'chart.heatmap.tile.aria': '{name} in {module} — self-time {value}, {pct}% of total',
+  'chart.heatmap.empty': 'scope=user has one module — no heatmap variation',
+  'chart.heatmap.moduleLabel': '{module} ({count})',
+  'chart.heatmap.more': '{count} more functions not shown',
+
+  // IPC error messages (translated by kind). Main process hardcodes Chinese
+  // for logs but renderer translates these for end-users.
+  // {message} keeps the original detail (ENOENT paths etc.) for debugging.
+  'ipcError.invalidPayload': 'Invalid payload: {message}',
+  'ipcError.interpreterNotAllowed': 'Interpreter not in allow-list: {message}',
+  'ipcError.payloadTooLarge': 'Payload too large: {message}',
+  'ipcError.engineNotFound': 'Analysis engine files missing: {message}',
+  'ipcError.interpreterProbeFailed': 'Failed to probe interpreter: {message}',
+  'ipcError.cancelled': 'Cancelled',
+  'ipcError.terminalOpenFailed': 'Failed to open terminal: {message}',
+
+  // Function origin (v3 — UI groups modules by origin)
+  // Long labels go in section headers / aria-label; short labels are the badge
+  // next to module chips, kept tiny so the row stays compact.
+  'origin.user': 'User code',
+  'origin.stdlib': 'Python stdlib',
+  'origin.thirdParty': 'Third-party',
+  'origin.builtin': 'Built-in',
+  'origin.frozen': 'Frozen',
+  'origin.other': 'Other',
+  'origin.abbr.user': 'U',
+  'origin.abbr.stdlib': 'S',
+  'origin.abbr.thirdParty': '3P',
+  'origin.abbr.builtin': 'B',
+  'origin.abbr.frozen': 'F',
+  'origin.abbr.other': '?',
+  // Section header above each origin group: "Python stdlib (5)" / "Third-party (3)"
+  'origin.sectionHeader': '{origin} ({count})',
+
+  // Editor tabs (stdlib / third-party hotspots open as tabs alongside user code)
+  'editorTab.user': 'Your code',
+  'editorTab.listAria': 'Open editor tabs',
+  'editorTab.closeAria': 'Close {name}',
+  // Status shown inside an external tab when its source file failed to load.
+  // File-read errors come back as discriminated union (`FileReadResult.kind`),
+  // each kind maps to one of these strings.
+  'editorTab.loading': 'Loading…',
+  'editorTab.error.notFound': 'File not found: {path}',
+  'editorTab.error.notAFile': 'Not a regular file: {path}',
+  'editorTab.error.permissionDenied': 'No permission to read: {path}',
+  'editorTab.error.tooLarge': 'File is too large to display ({size} > {max})',
+  'editorTab.error.invalidPath': 'Invalid file path: {path}',
+  'editorTab.error.unknown': 'Failed to read file: {message}',
+
+  // Run output panel (bottom of left area, shows Python print() output live)
+  'console.title': 'Run output',
+  'console.empty': 'print() output will appear here after running',
+  'console.clear': 'Clear',
+  // Line count badge, only shown when there's content
+  'console.lineCount': '{count} lines',
+  // Main-process appendCapped triggered a tail truncation — surface it loudly
+  // so users don't think "why is the output incomplete?"
+  'console.overflow': 'Output truncated (exceeded internal limit)',
+  // Header collapse/expand toggle (height itself is controlled by the Splitter;
+  // this button is the separate "fully hide" semantic)
+  'console.collapse': 'Collapse',
+  'console.expand': 'Expand'
+}
diff --git a/src/renderer/src/i18n/index.tsx b/src/renderer/src/i18n/index.tsx
new file mode 100644
index 0000000..7745437
--- /dev/null
+++ b/src/renderer/src/i18n/index.tsx
@@ -0,0 +1,135 @@
+/**
+ * 国际化：极简实现，无第三方依赖。
+ *
+ * 设计：
+ * - `t(key, lang, params)` 纯函数，组件树里都通过 `useT()` hook 取
+ * - `I18nProvider` 持有 lang 状态 + localStorage 持久化 + <html lang> 同步
+ *   —— **唯一** lang 状态来源；AppInner 不再有自己的 lang state，避免双源不同步
+ * - 占位符用 `{name}` 形式，t() 接受第二个参数 `params` 做替换
+ * - 中文是默认值（项目本身就是中文优先）；lang='en-US' 切换
+ * - 字符串键的类型保护由 zh-CN.ts 的 `StringKey` 提供；en-US 必须覆盖同集合（编译期）
+ *
+ * 不引入 react-i18next 的原因：字典规模 < 80 条，单 Context + 函数调用足够；
+ * 第三方库的 ICU MessageFormat / plural / fallback 链我们一个都用不上。
+ */
+import { createContext, useCallback, useContext, useEffect, useMemo, useState, type ReactNode } from 'react'
+import { zhCN, type StringKey } from './zh-CN'
+import { enUS } from './en-US'
+
+export type Lang = 'zh-CN' | 'en-US'
+
+/**
+ * `useT()` / `I18nContextValue.t` 的函数签名类型 —— 供纯函数 / 工具模块接收 `t` 而不必
+ * 把整个 context 拽进来。例：`utils/editorTabs.ts` 的 `errorTitleForTab(tb, t: Translator)`。
+ * 独立 export 让 caller 不依赖 React,测试时也能直接传一个 stub 函数。
+ */
+export type Translator = (key: StringKey, params?: Record<string, string | number>) => string
+
+export const DEFAULT_LANG: Lang = 'zh-CN'
+export const STORAGE_KEY_LANG = 'pyrof.lang'
+
+const DICTIONARIES: Record<Lang, Record<StringKey, string>> = {
+  'zh-CN': zhCN,
+  'en-US': enUS
+}
+
+/** 读 localStorage 拿到持久化的语言；读不到或非法值时回退到默认。 */
+export function readStoredLang(): Lang {
+  try {
+    const v = localStorage.getItem(STORAGE_KEY_LANG)
+    return v === 'en-US' ? 'en-US' : DEFAULT_LANG
+  } catch {
+    // file:// 或无存储权限时静默回退
+    return DEFAULT_LANG
+  }
+}
+
+/**
+ * 纯翻译函数：拿 key + 当前 lang + 可选 params，返回翻译后的字符串。
+ * 组件里通过 useT() 间接调用，避免每次 render 传 lang 参数。
+ *
+ * `{name}` 形式的占位符用 `params.name` 的值替换；缺失的占位符保留原样，
+ * 让 `grep '{pct}'` 仍能在字典里找到未使用的字段。
+ */
+export function t(key: StringKey, lang: Lang, params?: Record<string, string | number>): string {
+  // `?? DICTIONARIES[DEFAULT_LANG]` 兜底只是 type-level 的,实际 lang 一定在 Lang 范围内
+  // (lang 来自 useState<Lang>),`DICTIONARIES[lang]` 不会 undefined。
+  const dict = DICTIONARIES[lang]
+  let s = dict[key] ?? DICTIONARIES[DEFAULT_LANG][key]
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      // escape k —— params.key 是 Object.entries 的产物,理论上调用方可控,但万一传
+      // "a.b" 这种 key,RegExp 会按字面量匹配所有 ".b" 形式 —— escape 后行为可控。
+      const escaped = k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      s = s.replace(new RegExp(`\\{${escaped}\\}`, 'g'), () => String(v))
+    }
+  }
+  return s
+}
+
+interface I18nContextValue {
+  /** 当前 lang（lang-aware 渲染用，例如按语言决定日期格式） */
+  lang: Lang
+  /** 切换 lang —— 唯一入口；写 localStorage + 同步 <html lang> */
+  setLang: (next: Lang) => void
+  /** 当前 lang 下的翻译函数（推荐组件用这个） */
+  t: (key: StringKey, params?: Record<string, string | number>) => string
+}
+
+const I18nContext = createContext<I18nContextValue | null>(null)
+
+/**
+ * 顶层 Provider。Context value 把 lang/setLang/t 一次性暴露，避免 AppInner 自己再
+ * 复制一份 lang state（之前的双源不同步 bug：AppInner 的 lang 改了但 I18nProvider
+ * 的没改 → useT() 还返回旧语言）。
+ */
+export function I18nProvider({ children }: { children: ReactNode }): JSX.Element {
+  const [lang, setLangState] = useState<Lang>(() => readStoredLang())
+
+  const setLang = useCallback((next: Lang) => {
+    setLangState(next)
+    try {
+      localStorage.setItem(STORAGE_KEY_LANG, next)
+    } catch {
+      // 同 readStoredLang：localStorage 不可用时静默
+    }
+    // 同步给 <html lang="...">，影响浏览器对控件 tooltip / 日期格式的回退语言
+    document.documentElement.lang = next
+  }, [])
+
+  // mount 时把 lang 同步给 <html>，覆盖 index.html inline script 设的值
+  useEffect(() => {
+    document.documentElement.lang = lang
+  }, [lang])
+
+  const value = useMemo<I18nContextValue>(
+    () => ({
+      lang,
+      setLang,
+      t: (key, params) => t(key, lang, params)
+    }),
+    [lang, setLang]
+  )
+
+  return <I18nContext.Provider value={value}>{children}</I18nContext.Provider>
+}
+
+/** 一把抓 hook：lang + setLang + t 三件套都拿。 */
+export function useI18n(): I18nContextValue {
+  const ctx = useContext(I18nContext)
+  if (!ctx) throw new Error('useI18n must be called inside <I18nProvider>')
+  return ctx
+}
+
+/** 翻译函数 hook。必须在 I18nProvider 内部调用。 */
+export function useT(): (key: StringKey, params?: Record<string, string | number>) => string {
+  return useI18n().t
+}
+
+/** 取当前 lang（用于需要根据语言做条件渲染而不仅仅是翻译字符串的场合）。 */
+export function useLang(): Lang {
+  return useI18n().lang
+}
+
+export type { StringKey }
+export { zhCN, enUS }
diff --git a/src/renderer/src/i18n/test-utils.tsx b/src/renderer/src/i18n/test-utils.tsx
new file mode 100644
index 0000000..b080775
--- /dev/null
+++ b/src/renderer/src/i18n/test-utils.tsx
@@ -0,0 +1,12 @@
+/**
+ * 测试辅助：用 I18nProvider 包住待渲染组件。
+ *
+ * 真实 App 已经在内部包了 Provider，但单元测试通常直接 render 单独的子组件，
+ * 需要显式包一层。固定注入 zh-CN 让断言可以预期中文（与生产默认一致）。
+ */
+import type { ReactNode } from 'react'
+import { I18nProvider } from '../i18n'
+
+export function wrap(children: ReactNode): JSX.Element {
+  return <I18nProvider>{children}</I18nProvider>
+}
diff --git a/src/renderer/src/i18n/zh-CN.ts b/src/renderer/src/i18n/zh-CN.ts
new file mode 100644
index 0000000..5cf544e
--- /dev/null
+++ b/src/renderer/src/i18n/zh-CN.ts
@@ -0,0 +1,287 @@
+/**
+ * 中文界面文案（默认语言）。
+ *
+ * 键名采用层级点号（`settings.interpreter.label`），按组件 / 域分组。
+ * 扁平结构 + TypeScript `StringKey` 类型让 t() 永远拿到存在的 key。
+ * 不翻译：键位 Ctrl+Enter / 语言名 Python / 工具名 cProfile /
+ * 表格列头与 ARIA 文案按 lang 切换（用户偏好）。
+ */
+const _zhCNDict = {
+  // App
+  'app.live.running': '运行中 {pct}%',
+  'app.live.done': '分析完成',
+  'app.live.error': '出错: {message}',
+  'app.editorLoading': '编辑器加载中…',
+
+  // TopBar
+  'topbar.title': 'Python 程序耗时可视化分析',
+  'topbar.shortcutHint': 'Ctrl+Enter 运行',
+  'topbar.openSettings': '打开设置',
+  'topbar.switchLanguage': '切换语言',
+  'topbar.switchLanguageTo': '切换到 {target}',
+  'topbar.toggleTheme': '切换主题',
+  'topbar.theme.toLight': '切换到亮色',
+  'topbar.theme.toDark': '切换到暗色',
+  'topbar.lang.zh': '中文',
+  'topbar.lang.en': 'EN',
+  'topbar.openTerminal': '打开系统终端',
+  // 顶栏右上角窗口控制按钮（frame: false 后 OS 标题栏没了，自定义按钮接管）
+  'topbar.window.minimize': '最小化',
+  'topbar.window.maximize': '最大化',
+  'topbar.window.restore': '还原',
+  'topbar.window.close': '关闭',
+
+  // Splitter (drag handles between regions)
+  'splitter.main.aria': '拖动调整编辑器与结果区宽度',
+  // 编辑器 ↔运行输出面板（左侧上下两区）—— 跟主区左右分割分开两条文案，
+  // 因为它们在屏幕上的方向不同,SR 读出来对盲用户导航更有用
+  'splitter.console.aria': '拖动调整编辑器与运行输出面板高度',
+
+  // Settings modal
+  'settings.title': '设置',
+  'settings.close': '关闭',
+  'settings.section.interpreter': '解释器',
+  'settings.section.shell': '终端',
+  'settings.shell.label': '打开终端用的 shell',
+  'settings.shell.cmd': '命令提示符 (cmd)',
+  'settings.shell.powershell': 'PowerShell',
+  'settings.shell.hint': '顶栏「打开终端」按钮和未装 Python 时引导装包的终端都用这个 shell',
+  'settings.interpreter.label': 'Python 解释器',
+  'settings.interpreter.browse': '浏览…',
+  'settings.interpreter.rescan': '重新扫描',
+  'settings.interpreter.empty': '未检测到 Python',
+  'settings.interpreter.detecting': '扫描中…',
+  'settings.interpreter.detectError': '扫描解释器失败：{message}',
+  'settings.interpreter.pickError': '选择解释器失败：{message}',
+  // 终端(未检测到 Python 时引导用户去系统终端自装)
+  'settings.terminal.openCmd': '打开终端安装 Python',
+  'settings.terminal.hint': '在终端中预填了安装命令，回车即可',
+  'settings.terminal.error': '打开终端失败：{message}',
+  // 关于 —— 开发者信息 + 个人主页链接
+  'settings.section.about': '关于',
+  'settings.about.developer': '开发者',
+  'settings.about.developerName': '关济寰',
+  'settings.about.website': 'https://www.guanjihuan.com/about',
+  'settings.about.linkAria': '访问 {name} 的个人主页',
+
+  // MinimalRunConfig
+  'runconfig.run': '运行分析',
+  'runconfig.cancel': '取消',
+  'runconfig.loadSample': '加载示例',
+  'runconfig.newBlank': '新建空白',
+  'runconfig.shortcut': 'Ctrl+Enter',
+  'runconfig.progress': '运行进度',
+  'runconfig.needInterpreter': '未选 Python 解释器（设置里选）',
+  // 剖析范围 toggle：默认 all（含库函数），点关后变 user（仅用户脚本）
+  'runconfig.scope.user': '仅用户代码',
+  'runconfig.scope.all': '含库函数',
+  'runconfig.scope.aria': '剖析范围：{scope}，点击切换',
+
+  // EmptyState
+  'empty.eyebrow': '使用步骤',
+  'empty.title': '粘贴代码，马上知道慢在哪',
+  'empty.subtitle': '左边写代码，右边看时间花在哪。',
+  'empty.step1.title': '粘贴 Python 代码',
+  'empty.step1.desc': '或在左侧编辑器直接写',
+  'empty.step2.title': '选择 Python 解释器',
+  'empty.step2.desc': '找不到就点「浏览…」手动选',
+  'empty.step3.title': '运行分析',
+  'empty.step3.desc': '看每个函数各花多少时间',
+  'empty.running': '运行中…',
+  'empty.needInterpreter': '需要先选 Python 解释器',
+  'empty.needInterpreterDesc': '点击设置面板 → 解释器 → 浏览…手动选 python.exe',
+  'empty.openSettings': '打开设置',
+
+  // HotspotTable
+  'hotspot.empty': '没有可显示的函数',
+  // 模块过滤后没有匹配行时的占位 —— 比"空表"更明确，告诉用户是过滤造成的，不是没数据
+  'hotspot.emptyFiltered': '当前过滤下没有匹配的函数，点「全部 {total}」恢复',
+  'hotspot.col.function': '函数',
+  'hotspot.col.tottime': '自耗时',
+  'hotspot.col.cumtime': '累计耗时',
+  'hotspot.col.calls': '调用次数',
+  'hotspot.col.percall': '每次调用',
+  'hotspot.col.line': '第 {line} 行',
+  'hotspot.row.aria': '{name}（{origin}） 第 {line} 行 · 自耗时 {tottime} · 调用 {calls} 次',
+  'hotspot.row.ariaSelected': '{name}（{origin}） 第 {line} 行 · 自耗时 {tottime} · 调用 {calls} 次 · 已选中',
+  'hotspot.sortBy': '按 {label} 排序',
+  'hotspot.truncated': '仅显示前 {visible} 行，另有 {hidden} 行未显示',
+  'hotspot.totals': '已显示全部 {total} 行',
+  'hotspot.expand': '展开全部 {total} 行',
+  'hotspot.collapse': '收起至前 {cap} 行',
+  // 零耗时帧过滤 —— scope=all 时 typing/inspect 等内部展开能堆出几百个 tottime=0 的帧，
+  // 它们代表「被调用了但耗时低于 cProfile 量化精度（~1µs）」，不是优化目标。
+  // 默认折叠 + 给一个开关让想排查调用栈的人能展开。
+  'hotspot.zeroTimeHidden': '另有 {hidden} 个零耗时帧未显示（cProfile 量化精度以下）',
+  'hotspot.zeroTimeShow': '显示零耗时帧',
+  'hotspot.zeroTimeHide': '收起零耗时帧',
+  // 测试代码过滤 —— 用户项目内部的 test_xxx / tests/ 目录 / TestCase.test_xxx 默认折叠
+  'hotspot.testCodeHidden': '另有 {hidden} 个测试代码帧未显示（test_xxx / tests/ / TestCase）',
+  'hotspot.testCodeShow': '显示测试代码',
+  'hotspot.testCodeHide': '收起测试代码',
+  // 模块过滤（scope=all 才出现）—— 让几百个库函数不至于糊成一团
+  'hotspot.module.allFilter': '全部 {total}',
+  'hotspot.module.filter': '{module} {count}',
+  'hotspot.module.aria': '按模块过滤：{label}，当前显示 {shown} / {total}',
+
+  // FlameGraph
+  'flame.empty': '无可显示的函数',
+  'flame.aria': '火焰图',
+  'flame.reset': '复位',
+  'flame.reset.aria': '复位火焰图',
+  'flame.tile.aria': '{name} 自耗时 {value}s 占 {pct}%',
+  'flame.tile.drill': '（按 Enter 下钻）',
+
+  // ErrorBanner
+  'errorBanner.title': '运行出错',
+  'errorBanner.retry': '再试一次',
+  'errorBanner.unknown': '未知错误',
+  'errorBanner.logDetails': '查看引擎日志',
+
+  // FailureResult
+  'failure.title.timeout': '运行超时',
+  'failure.title.syntax': '语法错误',
+  'failure.title.runtime': '运行时错误',
+  'failure.retry': '再试一次',
+  'failure.logDetails': '查看引擎日志',
+
+  // ErrorBoundary
+  'errorBoundary.title': '页面出错了',
+  'errorBoundary.retry': '重试',
+  'errorBoundary.reload': '刷新页面',
+  'errorBoundary.consoleError': '[ErrorBoundary] 组件渲染抛错:',
+
+  // RunSummaryLite
+  'summary.wallTime': '本次耗时',
+  'summary.functionCount': '函数总数',
+  // 函数总数 tile 的副信息 —— 仅多模块（scope=all）时显示;单模块 scope=user
+  // 默认情况显示就成噪音。
+  'summary.moduleCount': '{count} 个模块',
+  'summary.hottest': '最耗时函数',
+  'summary.hottestSub': '自耗时 {tottime} · 调用 {calls} 次',
+  // wall_time 比 cProfile 归因合计大很多 → 多半含阻塞事件循环等待
+  // (plt.show / input / cv2.waitKey 等)。cProfile 看不到这类等待时间,
+  // 算上之后摘要"本次耗时"会被显著拉高。{gap} 是未归因的秒数。
+  // title 给纯文本详细解释,鼠标 hover 看。
+  'summary.wallTimeHint': '含交互等待 · 未归因 {gap}',
+  'summary.wallTimeHintTitle':
+    '这部分时间是用户阻塞调用（matplotlib 弹窗 / input() / cv2.waitKey 等）造成的，cProfile 看不见，所以火焰图里看不到。',
+  // v4 起 wall-time 是估计值（instrumented / cProfile 校准系数），用 chip 标注一下。
+  'summary.wallTimeCalibrated': '已校准',
+  'summary.wallTimeCalibratedTitle': '本次耗时为估计值，已按 cProfile 开销（{ratio}×）校准。',
+
+  // ResultsPanel
+  'results.hotspot.title': '热点函数',
+  'results.hotspot.hint': '{n} 个',
+  'results.time.title': '耗时分布',
+  'results.time.hint': '切换视图看同一份耗时数据',
+  // 当前 result 来自旧 scope —— 切了 toggle 没自动重跑（跑一次 1-10 秒，不能偷偷起活），
+  // 给一句提示 + 主动「以新范围重跑」按钮。
+  'results.scopeStale.eyebrow': '范围已切换',
+  'results.scopeStale.body': '这份结果是按「{old}」跑的，scope 现在是「{new}」',
+  'results.scopeStale.rerun': '以新范围重跑',
+
+  // Chart switcher
+  'chart.switcher.label': '切换图表类型',
+  'chart.type.flame': '火焰图',
+  'chart.type.bar': '柱状图',
+  'chart.type.treemap': '矩形树图',
+  'chart.type.sunburst': '旭日图',
+  'chart.type.cumulative': '累计条形',
+  'chart.type.heatmap': '模块热力',
+  'chart.empty': '暂无耗时数据',
+  'chart.truncated': '仅显示前 {shown} 个，另有 {hidden} 个未显示',
+  // 多层都有 sibling 被截时的聚合文案 —— 火焰图 / Treemap / 旭日图共用
+  // {depths}: 涉及几个深度层; {shown}: 单层上限; {hidden}: 全部层被截的 sibling 总数
+  'chart.flame.truncatedMulti':
+    '多个调用层有截断：共 {depths} 层 · 仅显示前 {shown} 个/层 · 另有 {hidden} 个兄弟节点被隐藏',
+  // 各图自己的小提示(替代原来通用的 chart.note)—— 每图说明一个独有意义
+  'chart.flame.hint': '点击有子节点的 tile 可下钻',
+  'chart.bar.hint': '按自耗时排名 · 长度 = 占总量百分比',
+  'chart.treemap.hint': '面积 = 自耗时占比 · 颜色同函数四图一致',
+  'chart.sunburst.hint': '弧长 = 自耗时占比 · 中心圆 = 总耗时',
+  'chart.cumulative.hint': '按累计耗时排名 · 深色段 = 自耗时',
+  'chart.heatmap.hint': '模块聚合 · 色块面积 = 自耗时占比',
+  // Sunburst 中心「N 个函数」摘要
+  'chart.sunburst.totalFns': '{count} 个函数',
+  'chart.bar.aria': '按耗时排序的柱状图',
+  'chart.bar.tile.aria': '{name}（{origin}） 自耗时 {value} 占 {pct}%',
+  'chart.treemap.aria': '耗时矩形树图',
+  'chart.treemap.tile.aria': '{name} 自耗时 {value} 占 {pct}%',
+  'chart.sunburst.aria': '耗时旭日图',
+  'chart.sunburst.slice.aria': '{name} 自耗时 {value} 占 {pct}%',
+  'chart.cumulative.aria': '按累计耗时排序的条形图',
+  'chart.cumulative.tile.aria': '{name}（{origin}） 累计耗时 {cum} 其中自耗时 {self} 占 {pct}%',
+  'chart.cumulative.selfSeg': '自耗时',
+  'chart.cumulative.cumSeg': '被调用方耗时',
+  // 右对齐："{pct}% self · {cum}" —— {pct} 是该函数自耗时 / 它累计耗时的比例,
+  // 不是占总时长的比例;bar 长度才是总占比。两套指标要分清,否则用户读到自相矛盾。
+  'chart.cumulative.rightText': '{pct}% self · {cum}',
+  'chart.heatmap.aria': '按模块聚合的热力图',
+  'chart.heatmap.tile.aria': '{module} 模块下 {name} 自耗时 {value} 占 {pct}%',
+  'chart.heatmap.empty': 'scope=user 时模块唯一，无热力差异',
+  'chart.heatmap.moduleLabel': '{module} ({count})',
+  'chart.heatmap.more': '另有 {count} 个函数未展开',
+
+  // IPC 错误文案（按 kind 翻译）—— 渲染侧拿到 IpcError 时按 kind 取翻译，
+  // main 进程硬编码的中文 message 只落日志，不直接显示给用户。
+  // {message} 兜底保留原文（ENOENT 之类排查需要的细节）。
+  'ipcError.invalidPayload': '参数校验失败：{message}',
+  'ipcError.interpreterNotAllowed': '解释器路径不在白名单：{message}',
+  'ipcError.payloadTooLarge': '内容过大：{message}',
+  'ipcError.engineNotFound': '分析引擎文件缺失：{message}',
+  'ipcError.interpreterProbeFailed': '探测解释器失败：{message}',
+  'ipcError.cancelled': '已取消',
+  'ipcError.terminalOpenFailed': '打开终端失败：{message}',
+
+  // 函数来源（v3 新增 —— UI 按 origin 把模块分组）
+  // 长标签用于 section header / aria-label；短标签用于模块 chip 旁的徽章，避免行被撑高。
+  'origin.user': '用户代码',
+  'origin.stdlib': 'Python 标准库',
+  'origin.thirdParty': '第三方包',
+  'origin.builtin': '内置函数',
+  'origin.frozen': '冻结模块',
+  'origin.other': '其它',
+  'origin.abbr.user': 'U',
+  'origin.abbr.stdlib': 'S',
+  'origin.abbr.thirdParty': '3P',
+  'origin.abbr.builtin': 'B',
+  'origin.abbr.frozen': 'F',
+  'origin.abbr.other': '?',
+  // 表格上方按 origin 分组的子标题:"Python 标准库 (5)" / "第三方包 (3)"
+  'origin.sectionHeader': '{origin} ({count})',
+
+  // 编辑器标签页（点击 stdlib / 第三方包热点时与用户代码共存打开的 tab）
+  'editorTab.user': '你的代码',
+  'editorTab.listAria': '已打开的编辑器标签页',
+  'editorTab.closeAria': '关闭 {name}',
+  // 外部 tab 加载失败时在 tab 里展示的状态。FileReadResult.kind 一一对应这些 key。
+  'editorTab.loading': '加载中…',
+  'editorTab.error.notFound': '文件不存在：{path}',
+  'editorTab.error.notAFile': '不是常规文件：{path}',
+  'editorTab.error.permissionDenied': '无权限读取：{path}',
+  'editorTab.error.tooLarge': '文件过大无法显示（{size} > {max}）',
+  'editorTab.error.invalidPath': '文件路径无效：{path}',
+  'editorTab.error.unknown': '读取文件失败：{message}',
+
+  // 运行输出面板（左侧底部,实时显示 Python print() 输出）
+  'console.title': '运行输出',
+  'console.empty': '运行后此处显示 print() 输出',
+  'console.clear': '清空',
+  // 行数统计,只在有内容时显示
+  'console.lineCount': '共 {count} 行',
+  // 主进程 appendCapped 触发了尾部截断 —— 给个明显标记,避免用户以为"为什么输出不完整"
+  'console.overflow': '输出过长，已截断尾部',
+  // header 折叠/展开切换(同高度由 Splitter 控制,这个按钮是另一条「完全收起」语义)
+  'console.collapse': '收起',
+  'console.expand': '展开'
+}
+
+/**
+ * `satisfies Record<string, string>` 让 TS 校准每条值都得是字符串、同时保留
+ * 字面量类型给 `StringKey` 提取 —— 之前用 `zhCN as unknown as Record<StringKey, string>`
+ * 把所有类型检查都关掉了，错拼的 key 编译期发现不了。
+ */
+export const zhCN = _zhCNDict satisfies Record<string, string>
+
+export type StringKey = keyof typeof _zhCNDict
diff --git a/src/renderer/src/main.tsx b/src/renderer/src/main.tsx
new file mode 100644
index 0000000..f076768
--- /dev/null
+++ b/src/renderer/src/main.tsx
@@ -0,0 +1,16 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App'
+import { ErrorBoundary } from './components/ErrorBoundary'
+// 注意：不要在这里静态导入 './monaco-setup'。
+// 它会把整个 monaco-editor 拉进首屏 chunk（实测让 index.js 涨到 ~9.8MB）。
+// 该副作用导入已挪进 components/CodePanelLazy.tsx，随编辑器一起按需加载。
+import './styles/globals.css'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <ErrorBoundary>
+      <App />
+    </ErrorBoundary>
+  </React.StrictMode>
+)
diff --git a/src/renderer/src/monaco-setup.ts b/src/renderer/src/monaco-setup.ts
new file mode 100644
index 0000000..bb047c6
--- /dev/null
+++ b/src/renderer/src/monaco-setup.ts
@@ -0,0 +1,29 @@
+/**
+ * 让 @monaco-editor/react 走本地打包的 monaco-editor，而不是默认从 CDN 拉。
+ * CSP 默认只允许 'self'（Electron 桌面应用，离线友好）。CDN 方式会被 CSP 阻挡，
+ * 现象是编辑器永远卡在 "Loading..."，进而「加载示例」按下去用户看不到代码回来。
+ *
+ * 只注册 editor.worker：本应用的编辑器固定 defaultLanguage="python"，而 Python 的
+ * 语法高亮走 Monaco 的 Monarch 语法（主线程 tokenizer），不需要语言服务 worker。
+ * 之前额外注册了 json / css / html / typescript 四个 worker，其中 ts.worker 体积最大
+ * （整个 TypeScript 编译器），全都打进产物却永远不会被 label 命中 —— 纯粹的包体浪费。
+ *
+ * 注意：这个模块有副作用（写 self.MonacoEnvironment + loader.config），且会把整个
+ * monaco-editor 拉进所在 chunk。它被 CodePanelLazy 动态导入，从而和编辑器一起进
+ * 独立 chunk，不污染首屏 bundle —— 不要在 main.tsx 里静态导入它。
+ */
+import * as monaco from 'monaco-editor'
+import editorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker'
+import { loader } from '@monaco-editor/react'
+
+self.MonacoEnvironment = {
+  getWorker() {
+    return new editorWorker()
+  }
+}
+
+// 把 monaco 实例告诉 loader，从此 @monaco-editor/react 会用我们打包好的 monaco，
+// 不再向 jsdelivr 发请求。
+loader.config({ monaco })
+
+export {}
diff --git a/src/renderer/src/sample.ts b/src/renderer/src/sample.ts
new file mode 100644
index 0000000..8bdaf6e
--- /dev/null
+++ b/src/renderer/src/sample.ts
@@ -0,0 +1,14 @@
+export const DEMO_CODE = `# 示例：自定义累加求均值 vs numpy
+import numpy as np
+
+
+def my_mean(data):
+    s = 0
+    for x in data:
+        s += x
+    return s / len(data)
+
+
+data = np.random.rand(500_000).tolist()
+print(my_mean(data), np.mean(data))
+`
diff --git a/src/renderer/src/styles/__tests__/design-tokens.test.ts b/src/renderer/src/styles/__tests__/design-tokens.test.ts
new file mode 100644
index 0000000..8bd09d9
--- /dev/null
+++ b/src/renderer/src/styles/__tests__/design-tokens.test.ts
@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest'
+import { readdirSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+
+// 设计 token 在两处各存一份：tailwind.config.cjs（给 utility class 用）和
+// globals.css 的 :root（给 scrollbar / selection / focus ring / Monaco 覆盖这些
+// 纯 CSS 用）。
+//
+// 这份重复删不掉：把 tailwind 侧改成 var(--x) 会连带废掉 alpha 修饰符 ——
+// 代码里有 22 处 bg-accent/70、bg-sev-high/10、border-border/40 这类写法，
+// 而 var(--accent) 不是 <alpha-value> 通道格式，改完这些会静默失效。
+// 所以这里不做「消除重复」的假动作，而是把重复真正的危害（两边悄悄漂移）钉死。
+//
+// 主题切换后：globals.css 同时有 `:root`（暗）和 `:root.light`（亮）两套变量；
+// tailwind.config.cjs 全部走 `rgb(var(--xxx-rgb) / <alpha-value>)` 通道格式，
+// 不再需要 hardcoded hex 字面量 —— 重复的"二选一直接出现 hex"这一形态自然消失，
+// 留下的就是「同源对照」（同一个 RGB 三元组 → 同一个 hex 转换）。
+//
+// 另外守住 fontSize 标度：一旦标度存在，就不该再出现 text-[Npx] 硬编码 ——
+// 否则标度会像改动前那样退化成 0 引用的死配置。
+
+const ROOT = join(__dirname, '..', '..', '..', '..', '..')
+
+function read(rel: string): string {
+  return readFileSync(join(ROOT, rel), 'utf-8')
+}
+
+/** 从 globals.css 的首个 :root 块（暗色主题）里取 CSS 变量。 */
+function cssVars(css: string): Record<string, string> {
+  const block = /:root\s*\{([\s\S]*?)\}/.exec(css)
+  if (!block) throw new Error('globals.css 里找不到 :root 块')
+  const out: Record<string, string> = {}
+  for (const m of block[1].matchAll(/--([\w-]+)\s*:\s*([^;]+);/g)) {
+    out[m[1]] = m[2].trim().toLowerCase()
+  }
+  return out
+}
+
+/** 把 `#rrggbb` 转成 `r g b` 三元组；rgb 三元组格式直接原样返回。 */
+function toRgbTriplet(value: string): string {
+  const hex = value.startsWith('#') ? value : value.replace(/^rgb$|$$/g, '').trim()
+  if (hex.startsWith('#')) {
+    const h =
+      hex.length === 4
+        ? hex
+            .slice(1)
+            .split('')
+            .map((c) => c + c)
+            .join('')
+        : hex.slice(1)
+    return `${parseInt(h.slice(0, 2), 16)} ${parseInt(h.slice(2, 4), 16)} ${parseInt(h.slice(4, 6), 16)}`
+  }
+  return hex
+}
+
+describe('设计 token', () => {
+  const css = read('src/renderer/src/styles/globals.css')
+  const config = read('tailwind.config.cjs')
+  const vars = cssVars(css)
+
+  /** 配置里所有 `rgb(var(--xxx-rgb) / <alpha-value>)` / `var(--accent-soft)` 引用形式。 */
+  const configColorRefs = Array.from(
+    config.matchAll(/'(rgb$var\(--[\w-]+$\s*\/\s*<alpha-value>\)|var$--[\w-]+$)'/g)
+  ).map((m) => m[1])
+
+  /** tailwind.config.cjs 里 `key: '...'` 形式的色值（注释里的不算）。 */
+  function configColor(key: string): string {
+    const m = new RegExp(`(?:^|[\\s{])${key}:\\s*'([^']+)'`, 'm').exec(config)
+    if (!m) throw new Error(`tailwind.config.cjs 里找不到色值 ${key}`)
+    return m[1]
+  }
+
+  // globals.css 的 `-rgb` 三元组变量名 → tailwind.config.cjs 的键名
+  const PAIRS: [string, string][] = [
+    ['bg-rgb', 'bg'],
+    ['surface-1-rgb', '1'],
+    ['surface-2-rgb', '2'],
+    ['surface-3-rgb', '3'],
+    ['border-rgb', 'DEFAULT'],
+    ['border-strong-rgb', 'strong'],
+    ['fg-rgb', 'DEFAULT'],
+    ['fg-secondary-rgb', 'secondary'],
+    ['fg-muted-rgb', 'muted'],
+    ['accent-rgb', 'DEFAULT']
+  ]
+
+  it.each(PAIRS)('--%s 与 tailwind 配置引用一致', (cssVar) => {
+    expect(vars[cssVar], `globals.css 缺少 --${cssVar}`).toBeDefined()
+    const rgbValue = vars[cssVar]
+    // tailwind 引用 `rgb(var(--${cssVar}) / <alpha-value>)` — 必须出现在 configColorRefs 里
+    const expectedRef = `rgb(var(--${cssVar}) / <alpha-value>)`
+    expect(
+      configColorRefs,
+      `--${cssVar}: ${rgbValue} 没有对应的 tailwind 引用 \`${expectedRef}\`（只改了一边？）`
+    ).toContain(expectedRef)
+  })
+
+  it('fg-muted-rgb 是提亮后的 141 148 157 (#8d949d)，不是 AA 边界上的 106 110 120 (#6a6e78)', () => {
+    // 历史：#6a6e78 (106 110 120) 在 surface-2 上只有 4.3:1，差点破 AA；
+    //      #7c8189 (124 129 137) 修到了 5.0:1；
+    //      现在 #8d949d (141 148 157) 提到 6.5:1，2xs/xs 小字号看久了不再"灰得发晕"。
+    // 钉这条防回退到 4.3:1 的旧值 —— 那个值会让人不知道为什么"突然不清楚"。
+    expect(toRgbTriplet(vars['fg-muted-rgb'])).toBe('141 148 157')
+    expect(configColor('muted')).toBe('rgb(var(--fg-muted-rgb) / <alpha-value>)')
+  })
+
+  it('fg-secondary-rgb 是 176 182 189 (#b0b6bd)，与 AA 边界上的旧 156 160 168 (#9ca0a8) 拉开距离', () => {
+    // #9ca0a8 在 bg 上是 6.8:1，对 2xs 字号长段落偏暗；
+    // #b0b6bd 提到 9.8:1（接近 AAA），仍是"次要"档位但读起来稳。
+    expect(toRgbTriplet(vars['fg-secondary-rgb'])).toBe('176 182 189')
+    expect(configColor('secondary')).toBe('rgb(var(--fg-secondary-rgb) / <alpha-value>)')
+  })
+
+  it('fontSize 标度声明了 2xs..2xl 七档', () => {
+    const block = /fontSize:\s*\{([\s\S]*?)\n {6}\}/.exec(config)
+    expect(block, 'tailwind.config.cjs 里找不到 fontSize 块').not.toBeNull()
+    const keys = Array.from(block![1].matchAll(/^\s*'?([\w-]+)'?:\s*'/gm)).map((m) => m[1])
+    expect(keys).toEqual(['2xs', 'xs', 'sm', 'base', 'lg', 'xl', '2xl'])
+  })
+
+  it('fontSize 标度不带 lineHeight（行高交给 body 继承与显式 leading-*）', () => {
+    const block = /fontSize:\s*\{([\s\S]*?)\n {6}\}/.exec(config)
+    expect(block![1]).not.toContain('lineHeight')
+  })
+
+  it('渲染层不再出现 text-[Npx] 硬编码字号', () => {
+    const offenders: string[] = []
+    const walk = (dir: string): void => {
+      for (const name of readdirSync(dir)) {
+        const p = join(dir, name)
+        if (statSync(p).isDirectory()) {
+          walk(p)
+          continue
+        }
+        if (!/\.tsx?$/.test(name)) continue
+        readFileSync(p, 'utf-8')
+          .split('\n')
+          .forEach((line, i) => {
+            for (const m of line.matchAll(/text-\[[\d.]+(?:px|rem|em)\]/g)) {
+              offenders.push(`${join(dir, name)}:${i + 1} ${m[0]}`)
+            }
+          })
+      }
+    }
+    walk(join(ROOT, 'src', 'renderer', 'src'))
+    expect(offenders, `请改用字号标度（2xs/xs/sm/base/lg/xl/2xl）:\n${offenders.join('\n')}`).toEqual([])
+  })
+})
diff --git a/src/renderer/src/styles/globals.css b/src/renderer/src/styles/globals.css
new file mode 100644
index 0000000..1d83881
--- /dev/null
+++ b/src/renderer/src/styles/globals.css
@@ -0,0 +1,329 @@
+/*
+  字体走系统栈，桌面 Electron 离线即可。CSP 默认 script-src/style-src/font-src 都是
+  'self'，禁止 CDN。
+
+  主题：`:root` 默认深色，`:root.light` 浅色。所有 color token 通过 `--xxx-rgb` 三元组
+  暴露给 Tailwind（tailwind.config.cjs 的 `rgb(var(--x-rgb) / <alpha-value>)` 写法），
+  也通过 `--xxx` 直接值供原生属性引用（body 背景 / scrollbar / selection / monaco）。
+*/
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  color-scheme: dark;
+  /* Triplets — Tailwind 引用 */
+  --bg-rgb: 8 9 10;
+  --surface-1-rgb: 14 15 18;
+  --surface-2-rgb: 19 20 24;
+  --surface-3-rgb: 26 28 34;
+  --border-rgb: 27 29 34;
+  --border-strong-rgb: 38 40 46;
+  --fg-rgb: 218 220 224; /* ~14.4:1 primary text — 16.6 太刺眼,降到 AAA 仍达标 */
+  --fg-secondary-rgb: 176 182 189; /* 9.8:1 */
+  --fg-muted-rgb: 141 148 157; /* 6.5:1 */
+  --fg-inverse-rgb: 8 9 10;
+  --fg-on-accent-rgb: 255 255 255;
+  --accent-rgb: 94 106 210;
+  --accent-hover-rgb: 110 122 224;
+  --accent-soft: rgba(94, 106, 210, 0.12);
+  --accent-ring: rgba(94, 106, 210, 0.35);
+  --sev-high-rgb: 229 72 77;
+  --sev-med-rgb: 245 165 36;
+  --sev-low-rgb: 76 195 138;
+  --warning-rgb: 245 165 36;
+
+  /* Direct-value aliases — body / scrollbar / selection / monaco 等直接 var() 用 */
+  --bg: rgb(var(--bg-rgb));
+  --surface-1: rgb(var(--surface-1-rgb));
+  --surface-2: rgb(var(--surface-2-rgb));
+  --surface-3: rgb(var(--surface-3-rgb));
+  --border: rgb(var(--border-rgb));
+  --border-strong: rgb(var(--border-strong-rgb));
+  --fg: rgb(var(--fg-rgb));
+  --fg-secondary: rgb(var(--fg-secondary-rgb));
+  --fg-muted: rgb(var(--fg-muted-rgb));
+  --accent: rgb(var(--accent-rgb));
+
+  /* v4 新增：右侧栏卡片专用 token —— 让 chart card / hotspot card / RunSummary
+     在 #08090A 上有可见的"浮起来"感，不和 page bg 糊在一起。
+     shadow 用 rgba(0,0,0,0.5) 在深色 bg 上能撑出层级;
+     浅色主题 shadow 更淡 —— 阴影感在白底上由 border-strong + 微亮 surface 承担。 */
+  --card-shadow: 0 1px 2px rgba(0, 0, 0, 0.4), 0 0 0 1px rgba(255, 255, 255, 0.02);
+}
+
+/*
+  浅色主题：主色保持 Linear 紫（品牌色不随主题改）；表面与文字翻为白底深字。
+  文字档位与原暗色保持同一档对比余量（primary ≈ 16.5:1、secondary ≈ 9.0:1、muted ≈ 5.5:1）。
+  sev / warning 在白底上需要更深才达标，因此全部微调。
+*/
+:root.light {
+  color-scheme: light;
+  --bg-rgb: 247 247 249;
+  --surface-1-rgb: 255 255 255;
+  --surface-2-rgb: 243 244 247;
+  --surface-3-rgb: 232 234 240;
+  --border-rgb: 224 226 232;
+  --border-strong-rgb: 200 204 214;
+  --fg-rgb: 24 28 36;
+  --fg-secondary-rgb: 80 88 100;
+  --fg-muted-rgb: 100 108 120; /* ~5.0:1 on surface-1 — 原 122 实测 3.6:1 低于 AA */
+  --fg-inverse-rgb: 255 255 255;
+  --fg-on-accent-rgb: 255 255 255;
+  --accent-rgb: 94 106 210;
+  --accent-hover-rgb: 78 90 200;
+  --accent-soft: rgba(94, 106, 210, 0.1);
+  --accent-ring: rgba(94, 106, 210, 0.3);
+  --sev-high-rgb: 212 60 64;
+  --sev-med-rgb: 180 83 9;
+  --sev-low-rgb: 47 158 100;
+  --warning-rgb: 180 83 9;
+
+  --bg: rgb(var(--bg-rgb));
+  --surface-1: rgb(var(--surface-1-rgb));
+  --surface-2: rgb(var(--surface-2-rgb));
+  --surface-3: rgb(var(--surface-3-rgb));
+  --border: rgb(var(--border-rgb));
+  --border-strong: rgb(var(--border-strong-rgb));
+  --fg: rgb(var(--fg-rgb));
+  --fg-secondary: rgb(var(--fg-secondary-rgb));
+  --fg-muted: rgb(var(--fg-muted-rgb));
+  --accent: rgb(var(--accent-rgb));
+
+  /* 浅色主题阴影更柔 —— 阴影在白底上"压"得过重会显得脏 */
+  --card-shadow: 0 1px 2px rgba(15, 20, 30, 0.04);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#root {
+  height: 100%;
+  margin: 0;
+}
+
+body {
+  background: var(--bg);
+  color: var(--fg);
+  /* 系统字体栈：Windows → Segoe UI Variable / macOS → SF Pro / Linux → Ubuntu */
+  font-family:
+    -apple-system, BlinkMacSystemFont, 'Segoe UI Variable', 'Segoe UI', 'Microsoft YaHei', 'PingFang SC',
+    sans-serif;
+  font-size: 15px;
+  font-weight: 450;
+  line-height: 1.55;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizeLegibility;
+}
+
+/* SVG <text> 文字锐化 —— 浏览器默认对 SVG text 不继承 body 的 font-smoothing,
+   在 HiDPI 屏/125% 缩放下容易糊。SVG 的 text-rendering 属性才是权威。
+   optimizeLegibility 走 kerning + 更好的灰度抗锯齿,渲染稍慢但小字更锐。
+   font-weight: 500 让 monospace 在 dark theme 不显"灰扑扑"。 */
+svg text {
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  font-weight: 500;
+}
+
+/* Selection follows accent */
+::selection {
+  background: var(--accent-soft);
+  color: var(--fg);
+}
+
+/* Scrollbar — Linear-thin */
+::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+}
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+::-webkit-scrollbar-thumb {
+  background: var(--border-strong);
+  border-radius: 6px;
+  border: 2px solid var(--bg);
+}
+:root.light ::-webkit-scrollbar-thumb:hover {
+  background: #c2c8d2;
+}
+::-webkit-scrollbar-thumb:hover {
+  background: #2f3239;
+}
+
+/* Native focus ring replaced with our accent ring.
+   把 a、[tabindex]、svg [role="button"] 全部纳入，键盘用户 tab 到 SVG 节点时也能看到。 */
+button,
+[role='button'],
+a,
+[tabindex]:not([tabindex='-1']),
+input,
+select,
+textarea {
+  outline: none;
+}
+button:focus-visible,
+[role='button']:focus-visible,
+a:focus-visible,
+[tabindex]:not([tabindex='-1']):focus-visible,
+input:focus-visible,
+select:focus-visible,
+textarea:focus-visible {
+  /* 用 box-shadow 模拟 ring，不动元素自身的 border-radius —
+     之前写 border-radius: 4px 会把 rounded-md (8px) / rounded (6px) 按钮的圆角覆盖掉，
+     聚焦时整个按钮"突然变方"——视觉跳动。inset ring 通过 box-shadow 实现就不会动圆角。 */
+  box-shadow:
+    0 0 0 2px var(--bg),
+    0 0 0 4px var(--accent);
+}
+
+/* The signature element: a 3px left bar on selected/active items */
+.accent-bar {
+  position: relative;
+}
+.accent-bar::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  top: 4px;
+  bottom: 4px;
+  width: 3px;
+  border-radius: 2px;
+  background: var(--accent);
+}
+
+/* v4 新增：右侧栏卡片浮起感。
+   用 .elev-1 套在 ResultsPanel 的 hotspot / chart 容器外层,
+   bg-surface-3 + border-strong + 微 shadow 让卡片在 page bg (#08090A)
+   上有清晰边界,不糊在一起。surface-3 比 surface-2 亮一档(RGB 26 vs 19),
+   在深色页面上对比更明显 —— 之前 surface-2 太接近 bg (#08090A),
+   在 HiDPI 屏上甚至糊成一片。 */
+.elev-1 {
+  background: var(--surface-3);
+  border: 1px solid var(--border-strong);
+  box-shadow: var(--card-shadow);
+}
+
+/* 章节分割线：sections 之间 6px → 8px,让 chart card 不挤到 RunSummary。
+   视觉锚点更明确。 */
+.divider-section {
+  height: 1px;
+  background: var(--border);
+}
+
+/* Reduced motion — 关闭非必需的动画 / transition，但仍保留 focus-visible 的 box-shadow：
+   焦点环是 a11y 必须的，省掉会让键盘用户根本看不到当前在哪。
+   * 通配 + !important 太暴力，会把 progressbar 宽度变化、pulse dot ping 都干掉（这些 OK），
+   同时也会把 focus ring box-shadow 的 transition 关掉——其实 box-shadow 没动画所以无所谓。
+   但 hover 颜色 transition 关掉会"颜色瞬间跳"，对部分用户眩晕。
+   精确到 animation / 非 transition 更稳 */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    /* 不动 transition-duration：focus-visible ring 的 box-shadow 实际是瞬间切换没有过渡,
+       保留 transition 让 hover 颜色变化仍然平滑（否则某些用户颜色突变会眩晕） */
+  }
+}
+
+/* Numerals in monospace tables: tabular */
+.tabular {
+  font-variant-numeric: tabular-nums;
+}
+
+/* Chart tiles — hover 视觉反馈。
+   chart-tile class 标记可交互的 <g>；data-chart-shape 标记那个要被提亮的
+   数据 shape（rect / path / circle）。用 attribute 而不是 nth-child 选择器,
+   是因为 BarChart 的 <g> 内有 text + text  rect + data rect + text 四种 children，
+   nth-child 方案脆弱。聚焦态（focus-visible）由上面的 box-shadow 规则承担,
+   此处 hover 故意弱一档（0.7 → 1.0），不抢焦点的戏。
+
+   v4 加 cursor:pointer + filter:brightness 微动,让"tile 是可点的"
+   在视觉上更明显;transition 平滑 fade 而不是"瞬间跳亮"。 */
+.chart-tile {
+  cursor: pointer;
+}
+.chart-tile [data-chart-shape] {
+  transition:
+    fill-opacity 120ms ease-out,
+    filter 120ms ease-out;
+}
+.chart-tile:hover [data-chart-shape] {
+  /* RESTING 0.7 → hover 1.0 实色,和 FOCUS 用描边区分 */
+  fill-opacity: 1;
+  filter: brightness(1.1);
+}
+/* 键盘聚焦时的视觉环 —— SVG <g> 不吃 box-shadow,这里用 focus 圆描边替代。
+   矩形(rect/path/circle) 被 data-chart-shape 标记时画一圈 1.5px accent 环,
+   跟 FOCUS 的 2px 实色描边共存时焦点态更明显,但本身不抢焦点态的戏。 */
+.chart-tile:focus-visible [data-chart-shape] {
+  stroke: var(--accent);
+  stroke-width: 1.5;
+  stroke-opacity: 0.6;
+}
+
+/* v4 新增：section title 装饰 —— 给 section header 加 4px 左侧 accent bar，
+   与 ResultsPanel 里 hotspot table / chart 容器上方形成统一的"section 标记"。
+   比单纯的 "icon + text" 更难在长滚动里迷失。 */
+.section-accent {
+  position: relative;
+  padding-left: 14px;
+}
+.section-accent::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 3px;
+  height: 14px;
+  border-radius: 2px;
+  background: var(--accent);
+}
+
+/* Spinner — small, Linear-style */
+@keyframes pyprof-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+.animate-spin {
+  animation: pyprof-spin 0.8s linear infinite;
+}
+
+/* Monaco editor — line highlight + line-number colors (applied via global stylesheet) */
+.pyprof-line-highlight {
+  background: var(--accent-soft) !important;
+}
+.pyprof-line-gutter {
+  background: var(--accent);
+  width: 2px !important;
+  margin-left: 2px;
+}
+.monaco-editor .line-numbers {
+  color: var(--fg-muted) !important;
+}
+.monaco-editor .margin-view-overlays .line-numbers.active-line-number {
+  color: var(--accent) !important;
+}
+
+/* Custom window controls — drag region (frame:false 后 OS 不再提供原生拖拽,
+   CSS `-webkit-app-region` 顶替)。inline style 在 TS 里写成了 `WebkitAppRegion: 'drag'`,
+   属性选择器兜底保证无论 inline 写成 `drag`/`'drag'`/`' no-drag '` 都能命中。 */
+[style*='WebkitAppRegion: drag'],
+[style*='WebkitAppRegion:drag'] {
+  -webkit-app-region: drag;
+}
+[style*='WebkitAppRegion: no-drag'],
+[style*='WebkitAppRegion:no-drag'] {
+  -webkit-app-region: no-drag;
+}
diff --git a/src/renderer/src/utils/__tests__/colors.test.ts b/src/renderer/src/utils/__tests__/colors.test.ts
new file mode 100644
index 0000000..51146ef
--- /dev/null
+++ b/src/renderer/src/utils/__tests__/colors.test.ts
@@ -0,0 +1,139 @@
+import { describe, it, expect } from 'vitest'
+import {
+  ACCENT,
+  ACCENT_DEEP,
+  ACCENT_RGB,
+  APP_BG,
+  FLAME_PALETTE,
+  SURFACE_2,
+  TEXT_ON_DARK,
+  TEXT_ON_LIGHT
+} from '../colors'
+
+// WCAG 2.1 相对亮度与对比度。放在测试里而不是 colors.ts —— 运行时不需要算对比度，
+// 这套数学只是用来把"这些色值达标"这个断言钉死，防止以后有人顺手调亮一个色值就静默回归。
+type RGB = [number, number, number]
+
+function parseHex(hex: string): RGB {
+  const m = /^#([0-9a-f]{6})$/i.exec(hex)
+  if (!m) throw new Error(`不是 6 位 hex 颜色: ${hex}`)
+  return [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16)) as RGB
+}
+
+function channelLuminance(c255: number): number {
+  const c = c255 / 255
+  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
+}
+
+function relativeLuminance([r, g, b]: RGB): number {
+  return 0.2126 * channelLuminance(r) + 0.7152 * channelLuminance(g) + 0.0722 * channelLuminance(b)
+}
+
+function contrast(a: RGB, b: RGB): number {
+  const la = relativeLuminance(a)
+  const lb = relativeLuminance(b)
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05)
+}
+
+/**
+ * alpha 合成：SVG 的 fillOpacity / rgba() 意味着实际呈现的颜色是
+ * `alpha * 前景 + (1 - alpha) * 底色`。半透明填充直接拿原始 hex 算对比度是错的
+ * —— 这正是之前 PALETTE 里 4 个色值"看着够亮其实不达标"的原因。
+ */
+function composite(fg: RGB, alpha: number, backdrop: RGB): RGB {
+  return fg.map((c, i) => alpha * c + (1 - alpha) * backdrop[i]) as RGB
+}
+
+/** 小字号正文（< 18px 常规字重）的 AA 阈值。火焰图标签 11px 算小字。 */
+const AA_SMALL_TEXT = 4.5
+
+const BG = parseHex(APP_BG)
+const ON_DARK = parseHex(TEXT_ON_DARK)
+
+describe('对比度数学本身', () => {
+  it('黑白是 21:1', () => {
+    expect(contrast([0, 0, 0], [255, 255, 255])).toBeCloseTo(21, 1)
+  })
+
+  it('同色是 1:1', () => {
+    expect(contrast(BG, BG)).toBeCloseTo(1, 5)
+  })
+
+  it('拒绝非法 hex', () => {
+    expect(() => parseHex('#abc')).toThrow()
+    expect(() => parseHex('rgb(0,0,0)')).toThrow()
+  })
+
+  it('合成会把半透明前景拉向底色', () => {
+    // alpha=0 完全是底色，alpha=1 完全是前景
+    expect(composite([255, 255, 255], 0, BG)).toEqual(BG)
+    expect(composite([255, 255, 255], 1, BG)).toEqual([255, 255, 255])
+    // 半透明白铺在深底上，亮度必然低于纯白
+    expect(relativeLuminance(composite([255, 255, 255], 0.7, BG))).toBeLessThan(
+      relativeLuminance([255, 255, 255])
+    )
+  })
+
+  it('半透明填充的对比度不等于原始 hex 的对比度（不能省掉合成这步）', () => {
+    const raw = contrast(ON_DARK, parseHex(ACCENT))
+    const composited = contrast(ON_DARK, composite(parseHex(ACCENT), 0.7, BG))
+    expect(composited).toBeGreaterThan(raw + 1)
+  })
+})
+
+describe('token 格式', () => {
+  it.each([
+    ['ACCENT', ACCENT],
+    ['ACCENT_DEEP', ACCENT_DEEP],
+    ['TEXT_ON_DARK', TEXT_ON_DARK],
+    ['TEXT_ON_LIGHT', TEXT_ON_LIGHT],
+    ['SURFACE_2', SURFACE_2],
+    ['APP_BG', APP_BG]
+  ])('%s 是 6 位 hex', (_name, value) => {
+    expect(value).toMatch(/^#[0-9a-fA-F]{6}$/)
+  })
+
+  it('ACCENT_RGB 与 ACCENT 描述同一个颜色', () => {
+    const parts = ACCENT_RGB.split(',').map((s) => Number(s.trim()))
+    expect(parts).toEqual(parseHex(ACCENT))
+  })
+
+  it('ACCENT_DEEP 确实比 ACCENT 暗（否则命名在骗人）', () => {
+    expect(relativeLuminance(parseHex(ACCENT_DEEP))).toBeLessThan(relativeLuminance(parseHex(ACCENT)))
+  })
+
+  it('FLAME_PALETTE 是 10 个互不相同的 hex', () => {
+    expect(FLAME_PALETTE).toHaveLength(10)
+    expect(new Set(FLAME_PALETTE).size).toBe(10)
+    for (const c of FLAME_PALETTE) expect(c).toMatch(/^#[0-9a-fA-F]{6}$/)
+  })
+})
+
+// 下面这些阈值断言对应 FlameGraph.tsx 里实际用的 opacity 和字号。
+// 改那个文件的 fillOpacity 或 fontSize，就得回来同步这里的参数。
+// 0.7 与 chart-utils.ts 的 RESTING.fillOpacity 一致：30% APP_BG 把 PALETTE
+// 中间色调拉向深底，再配 TEXT_ON_DARK 浅色文字刚好 ≥ 4.5:1。提到 0.85 会
+// 拉低对比度（0.7 已经是余量最低档），这是 colors.ts 验过的契约。
+describe('FlameGraph 文本对比度（11px，浅色文字）', () => {
+  it.each(FLAME_PALETTE.map((c, i) => [i, c]))('PALETTE[%i] = %s 在 fillOpacity 0.7 下达标', (_i, color) => {
+    const ratio = contrast(ON_DARK, composite(parseHex(color as string), 0.7, BG))
+    expect(ratio).toBeGreaterThanOrEqual(AA_SMALL_TEXT)
+  })
+
+  it('焦点 tile（ACCENT_DEEP @ 1.0）达标', () => {
+    expect(contrast(ON_DARK, composite(parseHex(ACCENT_DEEP), 1.0, BG))).toBeGreaterThanOrEqual(AA_SMALL_TEXT)
+  })
+
+  it('root 行（SURFACE_2 不透明）达标', () => {
+    expect(contrast(ON_DARK, parseHex(SURFACE_2))).toBeGreaterThanOrEqual(AA_SMALL_TEXT)
+  })
+
+  it('近黑文字在多数 PALETTE 色值上都不达标 —— 所以 textColor 不能按 tile 切换', () => {
+    // 这条是反向证据：曾经的注释声称"TEXT_ON_LIGHT 在任意 PALETTE 上都 AA"，是错的。
+    const onLight = parseHex(TEXT_ON_LIGHT)
+    const failing = FLAME_PALETTE.filter(
+      (c) => contrast(onLight, composite(parseHex(c), 0.7, BG)) < AA_SMALL_TEXT
+    )
+    expect(failing.length).toBeGreaterThan(0)
+  })
+})
diff --git a/src/renderer/src/utils/__tests__/detect-wait.test.ts b/src/renderer/src/utils/__tests__/detect-wait.test.ts
new file mode 100644
index 0000000..bf4d01c
--- /dev/null
+++ b/src/renderer/src/utils/__tests__/detect-wait.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest'
+import { INTERACTIVE_WAIT_GAP_RATIO, INTERACTIVE_WAIT_GAP_SEC, isInteractiveWait } from '../detect-wait'
+
+/**
+ * 双条件阈值的边界回归 —— 任何一个数字改了都要重新对照这里的 case,
+ * 否则 threshold-drift 不会被人发现(纯 GUI 提示,大概率是用户先发现)。
+ *
+ * 阈值含义见 detect-wait.ts 头注释。
+ */
+
+describe('isInteractiveWait', () => {
+  describe('正例:典型交互等待', () => {
+    it('matplotlib plt.show 一分钟 → 警告', () => {
+      // 渲染 200ms,用户盯图窗一分钟
+      expect(isInteractiveWait(60.0, 0.2)).toBe(true)
+    })
+
+    it('忘关弹窗 30 秒 → 警告', () => {
+      expect(isInteractiveWait(30.0, 0.5)).toBe(true)
+    })
+
+    it('input() 等用户敲回车 5 秒 → 警告', () => {
+      expect(isInteractiveWait(5.0, 0.05)).toBe(true)
+    })
+  })
+
+  describe('反例:不要误报的情况', () => {
+    it('毫秒级任务:attr 小差也比小 → 不警告', () => {
+      // 100ms 总耗时里 5ms 没人归 (profiler overhead 等),绝对差 5ms 小于 500ms 阈值
+      expect(isInteractiveWait(0.1, 0.095)).toBe(false)
+    })
+
+    it('长计算,即使 cProfile 漏归一点也不该警告', () => {
+      // 60s 计算,cProfile 漏归 700ms,绝对差大但比率才 1.17%
+      expect(isInteractiveWait(60.0, 59.3)).toBe(false)
+    })
+
+    it('归因和 wall 完全相等 → 不警告', () => {
+      expect(isInteractiveWait(1.234, 1.234)).toBe(false)
+    })
+
+    it('归因比 wall 还大(理论不应该,但 front-end 防御)→ 不警告', () => {
+      // 归因不可能真超过 wall,但 perf_counter / cProfile 时钟源不同,
+      // 偶发会出现 attr > wall 的微小超额。避免在这种情况下误报。
+      expect(isInteractiveWait(1.0, 1.005)).toBe(false)
+    })
+  })
+
+  describe('边界:每个条件单独未达成 → 不警告', () => {
+    it('差大比率小(纯绝对差阈值被比率挡掉)', () => {
+      // gap=0.8s > 0.5s ✓, 但比率 = 0.8/30 = 2.67% < 30% ✗
+      expect(isInteractiveWait(30.0, 29.2)).toBe(false)
+    })
+
+    it('比率大但差小(纯比率阈值被绝对差挡掉)', () => {
+      // ratio=0.4 > 0.3 ✓, 但 gap=0.04s < 0.5s ✗
+      expect(isInteractiveWait(0.1, 0.06)).toBe(false)
+    })
+
+    it('两个条件刚到阈值(各算一遍)', () => {
+      // gap=0.5s, ratio=0.3 → 都不严格 >,不警告。
+      // 用严格 > 的设计选择:刚好贴边时倾向于不警告。
+      expect(isInteractiveWait(1.0, 0.5)).toBe(false)
+    })
+  })
+
+  describe('防御性输入', () => {
+    it('NaN / Infinity 一律不警告', () => {
+      expect(isInteractiveWait(NaN, 0.1)).toBe(false)
+      expect(isInteractiveWait(1.0, NaN)).toBe(false)
+      expect(isInteractiveWait(Infinity, 0.1)).toBe(false)
+      expect(isInteractiveWait(1.0, Infinity)).toBe(false)
+    })
+
+    it('0 / 负数视为无效输入 → 不警告', () => {
+      expect(isInteractiveWait(0, 0)).toBe(false)
+      expect(isInteractiveWait(-1, 0.1)).toBe(false)
+      expect(isInteractiveWait(1.0, 0)).toBe(false)
+      expect(isInteractiveWait(1.0, -0.5)).toBe(false)
+    })
+  })
+
+  describe('导出常量', () => {
+    it('阈值可被外部代码 alignment', () => {
+      // 直接断言值,改阈值时同步改这里。
+      expect(INTERACTIVE_WAIT_GAP_SEC).toBe(0.5)
+      expect(INTERACTIVE_WAIT_GAP_RATIO).toBe(0.3)
+    })
+  })
+})
diff --git a/src/renderer/src/utils/__tests__/format.test.ts b/src/renderer/src/utils/__tests__/format.test.ts
new file mode 100644
index 0000000..9956459
--- /dev/null
+++ b/src/renderer/src/utils/__tests__/format.test.ts
@@ -0,0 +1,64 @@
+import { fmtDuration, fmtResolution } from '../format'
+
+/**
+ * format.ts 的回归测试。
+ *
+ * 文件头声称"所有函数都对 NaN / 负数返回 —"——每加一个 fmt* 函数前先在这里覆盖
+ * 否则有边界漂移风险。
+ */
+describe('fmtDuration', () => {
+  it('按量级选单位', () => {
+    expect(fmtDuration(2.5)).toBe('2.50s')
+    expect(fmtDuration(0.0123)).toBe('12.3ms')
+    expect(fmtDuration(1e-8)).toBe('10ns')
+  })
+
+  it('big 选项给到 3 位小数', () => {
+    expect(fmtDuration(2.5, { big: true })).toBe('2.500s')
+    expect(fmtDuration(0.0123, { big: true })).toBe('12.30ms')
+  })
+
+  it('单位切换的边界', () => {
+    expect(fmtDuration(1)).toBe('1.00s')
+    expect(fmtDuration(0.001)).toBe('1.0ms')
+    // 刚好低于 1ms → 走 ns 分支
+    expect(fmtDuration(0.0009)).toBe('900000ns')
+  })
+
+  it('精确的 0 显示 0s，不编造成 1ns', () => {
+    // 回归：Math.max(1, Math.round(0)) 把 0 抬成 1 → "1ns"。
+    // cProfile 对快到测不出来的函数就是给 tottime == 0.0。
+    expect(fmtDuration(0)).toBe('0s')
+    expect(fmtDuration(0, { big: true })).toBe('0s')
+  })
+
+  it('sub-ns 的非零值仍然兜底到 1ns（表示"极小但非零"）', () => {
+    expect(fmtDuration(1e-13)).toBe('1ns')
+  })
+
+  it('NaN / Infinity / 负数返回 —', () => {
+    for (const bad of [NaN, Infinity, -Infinity, -1, -1e-9]) {
+      expect(fmtDuration(bad)).toBe('—')
+    }
+  })
+})
+
+describe('fmtResolution', () => {
+  it('按量级选单位', () => {
+    expect(fmtResolution(1e-7)).toBe('100ns')
+    expect(fmtResolution(1e-6)).toBe('1.00µs')
+    expect(fmtResolution(2.5e-5)).toBe('25.00µs')
+  })
+
+  it('极小值 fallback 到科学计数', () => {
+    expect(fmtResolution(1e-12)).toBe('1.0e-12s')
+  })
+
+  it('0 / NaN / 负数 / Infinity 一律返回 —', () => {
+    // 回归：原来只有 `if (!s)`，挡不住负数和 Infinity ——
+    // fmtResolution(-1) 返回过 "-1.0e+0s"，fmtResolution(Infinity) 返回过 "Infinityµs"。
+    for (const bad of [0, NaN, -1, -1e-9, Infinity, -Infinity]) {
+      expect(fmtResolution(bad)).toBe('—')
+    }
+  })
+})
diff --git a/src/renderer/src/utils/__tests__/origin.test.ts b/src/renderer/src/utils/__tests__/origin.test.ts
new file mode 100644
index 0000000..f7b4b7d
--- /dev/null
+++ b/src/renderer/src/utils/__tests__/origin.test.ts
@@ -0,0 +1,206 @@
+/**
+ * origin 工具的单元测试。
+ *
+ * 关注的稳定不变式：
+ * 1) engine 给的 origin 字段优先 —— 「user」直传
+ * 2) v2 fallback（无 origin 字段）按 module 字符串启发式归类
+ * 3) groupFunctionsByOrigin / groupModuleKeysByOrigin 按 ORIGIN_ORDER 顺序
+ * 4) 空桶不出现 —— UI 只画「实际存在的 origin」section
+ * 5) 未知 origin 字符串兜底为 other，不抛错
+ */
+import { describe, expect, it } from 'vitest'
+import type { FunctionNode } from '../../../../shared/analysis'
+import {
+  ORIGIN_ORDER,
+  groupFunctionsByOrigin,
+  groupModuleKeysByOrigin,
+  isInternalTest,
+  resolveOrigin
+} from '../origin'
+
+function fn(module: string, origin?: string): FunctionNode {
+  return {
+    id: `${module}:1:f`,
+    file: `${module}.py`,
+    line: 1,
+    name: 'f',
+    cumtime: 0,
+    tottime: 0,
+    ncalls: 1,
+    percallTot: 0,
+    module,
+    ...(origin !== undefined ? { origin } : {})
+  }
+}
+
+describe('resolveOrigin', () => {
+  it('engine 给的 origin 字段直传', () => {
+    expect(resolveOrigin(fn('<user>', 'user'))).toBe('user')
+    expect(resolveOrigin(fn('json', 'stdlib'))).toBe('stdlib')
+    expect(resolveOrigin(fn('numpy', 'third_party'))).toBe('third_party')
+    expect(resolveOrigin(fn('<frozen>', 'frozen'))).toBe('frozen')
+    expect(resolveOrigin(fn('<built-in>', 'builtin'))).toBe('builtin')
+  })
+
+  it('v2 数据无 origin 时按 module 字符串启发式归类', () => {
+    expect(resolveOrigin(fn('<user>'))).toBe('user')
+    expect(resolveOrigin(fn('<frozen>'))).toBe('frozen')
+    expect(resolveOrigin(fn('<built-in>'))).toBe('builtin')
+    // 模块名相同的 stdlib/3rd-party 区分不开 —— 一律落到 other 兜底
+    // （保持 fallback "不保证准确" 的契约；引擎侧给 origin 才是权威路径）
+    expect(resolveOrigin(fn('json'))).toBe('other')
+    expect(resolveOrigin(fn('numpy'))).toBe('other')
+  })
+
+  it('未知 origin 字符串兜底 other —— 不抛', () => {
+    expect(resolveOrigin(fn('mystery', 'something-new'))).toBe('other')
+    // 已知但写错的拼写
+    expect(resolveOrigin(fn('mystery', 'stdliblib'))).toBe('other')
+  })
+})
+
+describe('groupFunctionsByOrigin', () => {
+  it('按 ORIGIN_ORDER 输出，每桶按原顺序保留', () => {
+    const fns = [
+      fn('json', 'stdlib'),
+      fn('numpy', 'third_party'),
+      fn('<user>', 'user'),
+      fn('<frozen>', 'frozen'),
+      fn('json2', 'stdlib')
+    ]
+    const out = groupFunctionsByOrigin(fns)
+    expect(out.map((g) => g.origin)).toEqual(['user', 'third_party', 'stdlib', 'frozen'])
+    expect(out[0].functions.map((f) => f.module)).toEqual(['<user>'])
+    expect(out[1].functions.map((f) => f.module)).toEqual(['numpy'])
+    expect(out[2].functions.map((f) => f.module)).toEqual(['json', 'json2'])
+    expect(out[3].functions.map((f) => f.module)).toEqual(['<frozen>'])
+  })
+
+  it('空桶不出现 —— 不画空 origin section', () => {
+    const fns = [fn('<user>', 'user'), fn('numpy', 'third_party')]
+    const out = groupFunctionsByOrigin(fns)
+    expect(out.map((g) => g.origin)).toEqual(['user', 'third_party'])
+    expect(out.find((g) => g.origin === 'stdlib')).toBeUndefined()
+    expect(out.find((g) => g.origin === 'frozen')).toBeUndefined()
+  })
+
+  it('空输入返回空数组', () => {
+    expect(groupFunctionsByOrigin([])).toEqual([])
+  })
+
+  it('ORIGIN_ORDER 与外部依赖一致 —— 6 种 origin 全列', () => {
+    expect(ORIGIN_ORDER).toEqual(['user', 'third_party', 'stdlib', 'builtin', 'frozen', 'other'])
+  })
+})
+
+describe('groupModuleKeysByOrigin', () => {
+  it('按 module 的 representative 函数归类', () => {
+    const fnByModule = new Map<string, FunctionNode>([
+      ['<user>', fn('<user>', 'user')],
+      ['json', fn('json', 'stdlib')],
+      ['numpy', fn('numpy', 'third_party')],
+      ['<frozen>', fn('<frozen>', 'frozen')]
+    ])
+    const out = groupModuleKeysByOrigin(['<user>', 'json', 'numpy', '<frozen>'], fnByModule)
+    expect(out.map((g) => g.origin)).toEqual(['user', 'third_party', 'stdlib', 'frozen'])
+    expect(out[0].modules).toEqual(['<user>'])
+    expect(out[1].modules).toEqual(['numpy'])
+    expect(out[2].modules).toEqual(['json'])
+    expect(out[3].modules).toEqual(['<frozen>'])
+  })
+
+  it('空 modules 返回空数组', () => {
+    expect(groupModuleKeysByOrigin([], new Map())).toEqual([])
+  })
+
+  it('模块查不到 representative 时兜底 other', () => {
+    const out = groupModuleKeysByOrigin(['mystery'], new Map())
+    expect(out).toEqual([{ origin: 'other', modules: ['mystery'] }])
+  })
+})
+
+describe('isInternalTest', () => {
+  // 简化版 FunctionNode —— 只填 isInternalTest 用得到的三个字段
+  function t(name: string, module: string, file: string): Pick<FunctionNode, 'name' | 'module' | 'file'> {
+    return { name, module, file }
+  }
+
+  it('识别 tests/test/__tests__ 目录下的所有函数(无论函数名)', () => {
+    expect(isInternalTest(t('helper', 'foo.tests', '/p/foo/tests/x.py'))).toBe(true)
+    expect(isInternalTest(t('helper', 'foo.test', '/p/foo/test/x.py'))).toBe(true)
+    expect(isInternalTest(t('helper', 'foo.__tests__', '/p/foo/__tests__/x.py'))).toBe(true)
+  })
+
+  it('识别模块名就是 tests/test/__tests__ 的情况', () => {
+    expect(isInternalTest(t('f', 'tests', 'p/x.py'))).toBe(true)
+    expect(isInternalTest(t('f', 'test', 'p/x.py'))).toBe(true)
+    expect(isInternalTest(t('f', '__tests__', 'p/x.py'))).toBe(true)
+  })
+
+  it('识别 tests/test/__tests__ 的子模块', () => {
+    expect(isInternalTest(t('f', 'tests.foo', 'p/x.py'))).toBe(true)
+    expect(isInternalTest(t('f', 'test.bar', 'p/x.py'))).toBe(true)
+    expect(isInternalTest(t('f', '__tests__.baz', 'p/x.py'))).toBe(true)
+  })
+
+  it('识别 pytest 文件命名约定 test_xxx.py / xxx_test.py', () => {
+    expect(isInternalTest(t('f', 'foo', '/p/test_foo.py'))).toBe(true)
+    expect(isInternalTest(t('f', 'foo', '/p/foo_test.py'))).toBe(true)
+    expect(isInternalTest(t('f', 'foo', '/p/tests/test_bar.py'))).toBe(true)
+  })
+
+  it('【关键】不误伤用户脚本里的 test_xxx 业务函数', () => {
+    // 用户在 main.py 里写 def test_helper() / def test_visualization() 是合法的业务函数
+    // ——文件不是 test_*.py,不在 tests/ 目录,不该被过滤。
+    expect(isInternalTest(t('test_helper', '<user>', 'a.py'))).toBe(false)
+    expect(isInternalTest(t('test_visualization', '<user>', '/p/app/main.py'))).toBe(false)
+    expect(isInternalTest(t('test_run_check', 'mymodule', '/p/mymodule/core.py'))).toBe(false)
+  })
+
+  it('不误伤任何「test_ 前缀」或「test 后缀」的函数名（包括 unittest 类方法）', () => {
+    // 设计取舍:完全不看函数名,只看语境。
+    // TestFoo.test_foo 在用户业务文件里不该被猜为测试 —— 保守优先。
+    expect(isInternalTest(t('TestFoo.test_foo', '<user>', '/p/myapp/svc.py'))).toBe(false)
+    expect(isInternalTest(t('MyClass.test_count', '<user>', 'a.py'))).toBe(false)
+    expect(isInternalTest(t('UserService.test_login', '<user>', 'a.py'))).toBe(false)
+  })
+
+  it('不误伤 _test / _tests 后缀的合法业务函数', () => {
+    expect(isInternalTest(t('latest_test_data', '<user>', 'a.py'))).toBe(false)
+    expect(isInternalTest(t('convert_test_input', '<user>', 'a.py'))).toBe(false)
+    expect(isInternalTest(t('all_tests', '<user>', 'a.py'))).toBe(false)
+  })
+
+  it('不误杀 testing / dataset / contest 等含 test 子串的模块名', () => {
+    expect(isInternalTest(t('f', 'testing', 'testing/main.py'))).toBe(false)
+    expect(isInternalTest(t('f', 'dataset', 'dataset/x.py'))).toBe(false)
+    expect(isInternalTest(t('f', 'contest', 'contest/x.py'))).toBe(false)
+  })
+
+  it('不误杀普通文件名 test.py / tests.py（项目入口常这么命名）', () => {
+    expect(isInternalTest(t('main', '<user>', '/p/test.py'))).toBe(false)
+    expect(isInternalTest(t('main', '<user>', '/p/tests.py'))).toBe(false)
+  })
+
+  it('业务函数（无 test 痕迹）不被识别', () => {
+    expect(isInternalTest(t('foo', '<user>', 'a.py'))).toBe(false)
+    expect(isInternalTest(t('main', 'foo', '/p/foo/main.py'))).toBe(false)
+  })
+
+  it('【回归】不误伤 tests/ 子目录下的非测试文件（如 fixtures / data / samples）', () => {
+    // 之前 dir 正则 `[\\/](tests?|__tests__)[\\/]` 任何含 /tests/ 的路径都中招,
+    // 包括 tests/fixtures/x.py 这种测试数据 —— 用户脚本只要住在带 tests/ 子目录
+    // 的路径下,functions 表直接被过滤成 0 行。收紧到「紧接文件名,不能有子目录」后:
+    expect(isInternalTest(t('f', 'fixtures', '/p/foo/tests/fixtures/x.py'))).toBe(false)
+    expect(isInternalTest(t('f', 'data', '/p/foo/tests/data/sample.py'))).toBe(false)
+    expect(isInternalTest(t('f', 'integration', '/p/mine/tests/integration/helper.py'))).toBe(false)
+    // tests/ 直接下面的文件 —— 仍走 dir 兜底命中
+    expect(isInternalTest(t('f', 'tests', '/p/tests/foo.py'))).toBe(true)
+  })
+
+  it('引擎内部硬编码白名单：_pyrof_calib（校准负载）永远算内部', () => {
+    // 即使文件路径/模块名都不像测试,只要名字命中白名单就过滤 —— 兜底防御
+    expect(isInternalTest(t('_pyrof_calib', '<user>', '/p/anything.py'))).toBe(true)
+    expect(isInternalTest(t('_pyrof_calib', 'weird_module', '/p/'))).toBe(true)
+  })
+})
diff --git a/src/renderer/src/utils/colors.ts b/src/renderer/src/utils/colors.ts
new file mode 100644
index 0000000..7564e7b
--- /dev/null
+++ b/src/renderer/src/utils/colors.ts
@@ -0,0 +1,55 @@
+// 设计 token 的 TS 镜像 —— Tailwind 配的是类名（text-accent / bg-bg），但内联 SVG
+// 必须吃 hex/rgba 字符串，所以这里定义一份和 tailwind.config.cjs 对齐的字面量。
+// 改了 Tailwind tokens 必须同步改这里；否则 SVG 视觉会脱离主题。
+//
+// 颜色含义：
+// - ACCENT: 主强调色（焦点、当前选中、高亮文本）
+// - ACCENT_RGB: ACCENT 的 0-255 分量，用来组 rgba(..., a)
+// - ACCENT_DEEP: 加深的强调色，用于"需要在其上放浅色文字"的实心块（火焰图焦点 tile）
+// - TEXT_ON_DARK: 在深色背景上显示的浅色文字
+// - TEXT_ON_LIGHT: 在浅色背景上显示的深色文字（描边等非文本用途也用它）
+// - FLAME_PALETTE: 火焰图 tile 填充色
+// - SURFACE_2: 与 tailwind surface.2 对齐，火焰图 root 行用
+//
+// 注：ACCENT_RGB / SURFACE_2 / APP_BG 没有生产消费方 —— 它们是 colors.test.ts 算
+// WCAG 对比度时的「期望底色」,集中在此确保 token 改了对比度能立刻挂掉。
+
+export const ACCENT = '#5E6AD2'
+export const ACCENT_RGB = '94, 106, 210'
+export const ACCENT_DEEP = '#4A54A8'
+export const TEXT_ON_DARK = '#E8E9EB'
+export const TEXT_ON_LIGHT = '#08090A'
+export const SURFACE_2 = '#131418'
+
+/** 应用背景（tailwind `bg`）。做对比度计算时是 SVG 半透明填充的合成底色。 */
+export const APP_BG = '#08090A'
+
+/**
+ * 火焰图 tile 调色板（10 色）。
+ *
+ * Tile 用 fillOpacity 0.7 画在 APP_BG 上,决定可读性的是**合成后**的颜色,不是这里
+ * 的原始 hex。所有色按"合成后 + TEXT_ON_DARK 文字"验过 WCAG AA(tile 标签 14-15px
+ * 小字号,阈值 4.5:1),最低 4.68,余量 +0.18:
+ *
+ *   #5E6AD2 6.29 · #7B82A8 5.26 · #7C8189 5.45 · #3D9C6E 4.88 · #BC7E1B 4.91 ·
+ *   #D65F7D 5.17 · #4F8FB8 5.02 · #8E6FB0 5.72 · #C25E3F 5.83 · #4A9871 4.98
+ *
+ * 撞色周期:10 色 + Java hashCode 取模保证"同函数同色",从早期 6 色扩到 10 是因为
+ * ModuleHeatmap 在 scope=all 时按模块着色,json/numpy/<user>/<frozen> 同框会出现多组
+ * 重复色。
+ *
+ * 改 fillOpacity 必须重算这个表 —— 0.7 是最低余量档,拉到 0.85 会反向降低对比度。
+ * 历史:从 6 色扩到 10 色时淘汰了 #5BA882(4.22 不达标→ #4A9871 4.98)。见 git log。
+ */
+export const FLAME_PALETTE = [
+  ACCENT,
+  '#7B82A8',
+  '#7C8189',
+  '#3D9C6E',
+  '#BC7E1B',
+  '#D65F7D',
+  '#4F8FB8',
+  '#8E6FB0',
+  '#C25E3F',
+  '#4A9871'
+] as const
diff --git a/src/renderer/src/utils/detect-wait.ts b/src/renderer/src/utils/detect-wait.ts
new file mode 100644
index 0000000..80b007b
--- /dev/null
+++ b/src/renderer/src/utils/detect-wait.ts
@@ -0,0 +1,36 @@
+/**
+ * 检测一次跑的 wall time 是否远大于 cProfile 归因合计 ——
+ * 用户代码里有阻塞事件循环等待（matplotlib plt.show / input() /
+ * cv2.waitKey 等）的最常见信号。
+ *
+ * 背景:
+ * - `wall_time` = runner 在 cProfile 之外用 perf_counter 包住 exec() 拿到的总秒数。
+ *   这段时间里发生的一切都算,包括用户盯着图窗看的时间。
+ * - `result.flame.value`（根节点 value）= 所有函数 tottime 之和 —— 即 cProfile
+ *   归因到的"计算时间"。见 engine/structure.py 里 `total = sum(f.tottime
+ *   for f in functions); flame = _build_flame(functions, total)`。
+ * - 二者之差 = cProfile 看不见的时间。harness 自己只做 gc.disable() +
+ *   compile() 等微秒级操作,长 gap 唯一的合法来源是用户代码里的阻塞调用。
+ *
+ * 阈值 (双条件,缺一不可):
+ * - 绝对差 > 500ms:纯比率会在毫秒级任务上误报
+ *   (例:30ms 中有 1ms 没人归因 = 3% 看起来像,但根本没意义)
+ * - 比率 > 30%:纯绝对差会在长计算任务上误报
+ *   (例:60s 计算里 cProfile 漏归 700ms,差很多但跟原始计算比只是噪声)
+ *
+ * 同时满足才返回 true —— 一个长 popup(wall=30s, attr=200ms,gap 99%,差 29.8s)
+ * 两条件都打中;一个普通的 100ms 脚本就算 5ms 没归上,任何条件都不打中,不警告。
+ */
+export function isInteractiveWait(wallSec: number, attributedSec: number): boolean {
+  if (!Number.isFinite(wallSec) || !Number.isFinite(attributedSec)) return false
+  if (wallSec <= 0 || attributedSec <= 0) return false
+  const gap = wallSec - attributedSec
+  return gap > 0.5 && gap / wallSec > 0.3
+}
+
+/**
+ * 阈值常量以 export 形式暴露 —— 测试 / 文档可以直接对齐,
+ * 也方便未来调参时只改一处。
+ */
+export const INTERACTIVE_WAIT_GAP_SEC = 0.5
+export const INTERACTIVE_WAIT_GAP_RATIO = 0.3
diff --git a/src/renderer/src/utils/editorTabs.ts b/src/renderer/src/utils/editorTabs.ts
new file mode 100644
index 0000000..985b1b2
--- /dev/null
+++ b/src/renderer/src/utils/editorTabs.ts
@@ -0,0 +1,44 @@
+import type { OpenFile, FileReadErrorKind } from '../hooks/useExternalFiles'
+import type { StringKey, Translator } from '../i18n'
+
+/**
+ * FileReadErrorKind → i18n key 完整映射。
+ *
+ * 'unknown' 走不同分支（IPC catch 兜底出的 message，不是 schema 里 FileReadResult 的
+ * kind）—— 不在表里,errorTitleForTab 单独判断。
+ *
+ * 类型 Record<..., StringKey> 而不是 Record<..., string> + 拼接模板 —— 后者会让
+ * `t(\`editorTab.error.${suffix}\`, ...)` 拿到 `\`editorTab.error.${string}\`` 模板
+ * 字面量类型,与 StringKey 的离散字面量 union 不兼容;直接存完整 key 让编译器
+ * 静态保证表里每个值都是合法 i18n key。
+ */
+const KIND_TO_I18N_KEY: Record<Exclude<FileReadErrorKind, 'unknown'>, StringKey> = {
+  not_found: 'editorTab.error.notFound',
+  not_a_file: 'editorTab.error.notAFile',
+  permission_denied: 'editorTab.error.permissionDenied',
+  too_large: 'editorTab.error.tooLarge',
+  invalid_path: 'editorTab.error.invalidPath'
+}
+
+/**
+ * 给 EditorTabs 算错误 tab 的 tooltip 文案 —— 按 errorKind 走 i18n 表,
+ * 未知 kind（catch 兜底）用 message 原文。
+ *
+ * MAX_FILE_READ_BYTES = 2MB —— 跟 src/main/index.ts 里 file:read handler 的
+ * MAX_FILE_READ_BYTES 保持一致。两边都是常量,以后要改一起改。
+ */
+const MAX_FILE_READ_BYTES_FOR_DISPLAY = 2 * 1024 * 1024
+
+export function errorTitleForTab(tb: OpenFile, t: Translator): string | undefined {
+  if (tb.status !== 'error') return undefined
+  const errorKind = tb.errorKind
+  if (errorKind && errorKind !== 'unknown') {
+    return t(KIND_TO_I18N_KEY[errorKind], {
+      path: tb.filePath,
+      size: tb.sizeBytes ?? 0,
+      max: MAX_FILE_READ_BYTES_FOR_DISPLAY,
+      message: tb.errorMessage ?? ''
+    })
+  }
+  return t('editorTab.error.unknown', { message: tb.errorMessage ?? '' })
+}
diff --git a/src/renderer/src/utils/format.ts b/src/renderer/src/utils/format.ts
new file mode 100644
index 0000000..e7b09dd
--- /dev/null
+++ b/src/renderer/src/utils/format.ts
@@ -0,0 +1,47 @@
+/**
+ * 时间/数字格式化工具（单一来源）。
+ * 之前 RunSummary / HotspotTable 各有一份 fmt*，行为略不一致 —— 合并后默认对齐
+ * HotspotTable 的紧凑风格（表格列需要紧凑），需要更高精度时显式传 big:true。
+ *
+ * 注意：所有函数都对 NaN / 负数返回 "—"，避免上游依赖处理边界。
+ */
+
+/** 一行耗时显示（自动选 µs / ms / s），单位自动避开 0-1ms 的浮点失真。 */
+export function fmtDuration(s: number, opts: { big?: boolean } = {}): string {
+  if (!Number.isFinite(s) || s < 0) return '—'
+  // 精确的 0 单独处理：下面的 Math.max(1, ...) 会把它抬成 "1ns"，而 cProfile
+  // 对快到测不出来的函数就是给 tottime == 0.0 —— 显示 1ns 是在编造一个数字。
+  if (s === 0) return '0s'
+  const digits = opts.big ? 3 : 2
+  // >= 1s → 直接显示；>= 1ms → 显示 ms；其余 → µs
+  if (s >= 1) return `${s.toFixed(digits)}s`
+  if (s >= 0.001) return `${(s * 1000).toFixed(digits - 1)}ms`
+  // sub-µs：用 ns 显示更直观；之前的 `* 1e6 → toFixed(0)` 会把 1e-8s 显示为 "0µs"
+  // （精度为 0 时永远 round 到 0，看不出真实值）。改用 toFixed(0) + Math.max 兜底 >= 1
+  const ns = s * 1_000_000_000
+  return `${Math.max(1, Math.round(ns))}ns`
+}
+
+/**
+ * 计时分辨率（perf_counter 等系统计时器的实际粒度）— 通常是极小的秒数。
+ * - 1e-6 起步按 µs 显示
+ * - 1e-9 起步按 ns 显示（浮点 ns 实际是 0.something ns，常用 round）
+ * - 否则 fallback 科学计数
+ */
+export function fmtResolution(s: number): string {
+  // 原来只有 `if (!s)`，挡得住 0 和 NaN，挡不住负数和 Infinity：
+  // fmtResolution(-1) 会返回 "-1.0e+0s"，fmtResolution(Infinity) 返回 "Infinityµs"，
+  // 与文件头"所有函数都对 NaN / 负数返回 —"的承诺不符。
+  if (!Number.isFinite(s) || s <= 0) return '—'
+  if (s >= 1e-6) return `${(s * 1e6).toFixed(2)}µs`
+  if (s >= 1e-9) return `${(s * 1e9).toFixed(0)}ns`
+  return `${s.toExponential(1)}s`
+}
+
+/** 一组函数的累计自耗时（cProfile tottime 之和）。
+ *  目前唯一调用方是 HotspotTable（算表格行的 "total" 分母）。需要新增消费方时统一改这里。 */
+export function totalSelfTime(functions: readonly { tottime: number }[]): number {
+  let s = 0
+  for (const f of functions) s += f.tottime
+  return s
+}
diff --git a/src/renderer/src/utils/installCommand.test.ts b/src/renderer/src/utils/installCommand.test.ts
new file mode 100644
index 0000000..7527c1b
--- /dev/null
+++ b/src/renderer/src/utils/installCommand.test.ts
@@ -0,0 +1,36 @@
+/**
+ * installPythonCommand 是 hardcode lookup — 三个分支的纯字符串断言。
+ * 没副作用、没 IO,加测试主要防"改 installCommand 时手抖",也防未来加新平台漏覆盖。
+ */
+import { installPythonCommand } from './installCommand'
+
+describe('installPythonCommand', () => {
+  it('Windows 用 winget 装最新 Python 3.12', () => {
+    expect(installPythonCommand('win32')).toBe('winget install Python.Python.3.12')
+  })
+
+  it('macOS 用 brew 装 python3', () => {
+    expect(installPythonCommand('darwin')).toBe('brew install python3')
+  })
+
+  it('Linux 用 apt 装 python3 + python3-pip', () => {
+    expect(installPythonCommand('linux')).toBe('sudo apt update && sudo apt install -y python3 python3-pip')
+  })
+
+  it('未识别的平台兜底走 Linux 分支(apt)', () => {
+    // NodeJS.Platform 是字面量 union,实际不会传进来 'freebsd';
+    // 但函数实现是 switch + default,默认分支应当给一条安全命令 — 不抛
+    expect(() => installPythonCommand('freebsd' as NodeJS.Platform)).not.toThrow()
+  })
+
+  it('返回的命令不含危险 shell 元字符(只 hardcode 一次)', () => {
+    // Linux 分支有意用 `&&` 把 update + install 串起来,但这是已知 trusted 字面量;
+    // 校验点:命令不包含 `;`(独立语句分隔)、`|`(管道)、`>`(重定向)
+    for (const platform of ['win32', 'darwin', 'linux'] as const) {
+      const cmd = installPythonCommand(platform)
+      // win32 / darwin 应该完全没有 shell 元字符;linux 允许 `&&` 但不允许 `;` / `|` / `>`
+      expect(cmd).not.toMatch(/[;>]/)
+      expect(cmd).not.toContain('|')
+    }
+  })
+})
diff --git a/src/renderer/src/utils/installCommand.ts b/src/renderer/src/utils/installCommand.ts
new file mode 100644
index 0000000..2b85087
--- /dev/null
+++ b/src/renderer/src/utils/installCommand.ts
@@ -0,0 +1,36 @@
+/**
+ * 平台对应的 Python 安装命令。
+ *
+ * 设计原则:
+ * - 命令保持"hardcode 字面量"形态 — 本模块是 IPC 边界的 trusted caller,只输出
+ *   我们自己 hardcode 的字符串,不接受任何外部输入(没有参数可注入)。
+ * - 允许使用 `&&`(Linux 分支把 apt update && apt install 串起来),不允许独立
+ *   语句分隔 `;`、管道 `|`、重定向 `>`/`<` — 测试 (`installCommand.test.ts`)
+ *   用正则把关,这些字符出现就 fail。
+ * - 用各平台最常见的包管理器:
+ *   - Windows: winget(Win10 1709+ / Win11 系统自带)
+ *   - macOS:   brew(用户装了 Homebrew 才有效;否则用户会看到 command not found,
+ *              那就走 `brew install ...` 提示用户装 brew)
+ *   - Linux:   apt(Debian/Ubuntu 系;RHEL/Fedora 用户拿到 `command not found` 后
+ *              改 dnf 即可 — 这种情况不是死路,按钮本身已经把"装 Python"的入口放出来了)
+ * - 不指定小版本号(用 `python3` 而不是 `python3.12`)— 主流发行版的最新稳定版就是
+ *   3.10+,跑 cProfile 完全够用,避免版本漂移要维护多条命令
+ *
+ * 注意:这里返回的命令直接喂给 IPC,RendererApi.openTerminal 透传到主进程 spawn,
+ * 中间不做任何转义 — 所以永远不要让外部数据流到这里,只能由本模块 hardcode。
+ */
+// NodeJS.Platform 是 TS 内置全局类型(对应 Node 的 process.platform 字符串字面量 union)
+// 无需 import — 直接用即可
+export function installPythonCommand(platform: NodeJS.Platform): string {
+  switch (platform) {
+    case 'win32':
+      // winget 包 id 官方固定的 `Python.Python.3.12`,装的是 64-bit stable
+      return 'winget install Python.Python.3.12'
+    case 'darwin':
+      // 不写具体小版本,默认装 brew 仓库里最新的稳定 python3
+      return 'brew install python3'
+    default:
+      // Linux 兜底;Debian/Ubuntu 系能直接跑,其他发行版报错用户自己能改
+      return 'sudo apt update && sudo apt install -y python3 python3-pip'
+  }
+}
diff --git a/src/renderer/src/utils/ipcErrorFormat.ts b/src/renderer/src/utils/ipcErrorFormat.ts
new file mode 100644
index 0000000..58f1c52
--- /dev/null
+++ b/src/renderer/src/utils/ipcErrorFormat.ts
@@ -0,0 +1,27 @@
+/**
+ * 把 IpcError 按当前 lang 翻译成可展示文案。
+ *
+ * 设计动机：main 进程抛错时 message 是 hardcoded 中文（开发者日志视角），
+ * en-US 用户在 UI 上看到中文会懵。按 kind 走翻译表，把 message 当作
+ * "{message}" 占位符的回填值（保留 ENOENT 路径之类排查细节）。
+ *
+ * kind 不在翻译表里（只有 'unknown' 会走到这里）→ 直接返回 readableMessage，
+ * 这种通常是 spawn error，机器可读反而比翻译更有价值。
+ *
+ * 翻译串前缀带 `kind: ` 跟旧行为保持一致（kind 名是英文，UI 不用再翻）。
+ */
+import { IPC_ERROR_I18N_KEYS, readIpcError } from '../../../shared/ipc'
+import type { StringKey } from '../i18n'
+
+type Translator = (key: StringKey, params?: Record<string, string | number>) => string
+
+export function formatIpcError(err: unknown, t: Translator): string {
+  const ipc = readIpcError(err)
+  const kind = ipc.kind
+  const key = IPC_ERROR_I18N_KEYS[kind]
+  if (!key) return ipc.readableMessage
+  // 翻译里可能有 {message} 占位符（如「payload_too_large: ... MB」需要原文）
+  // IPC_ERROR_I18N_KEYS 的 value 类型是宽 string（避免 shared 依赖 renderer 的 StringKey），
+  // 在边界处 assert 到 StringKey；表里所有 key 都已在 zh-CN / en-US 注册，类型断言是安全的。
+  return t(key as StringKey, { message: ipc.readableMessage })
+}
diff --git a/src/renderer/src/utils/origin.ts b/src/renderer/src/utils/origin.ts
new file mode 100644
index 0000000..1240bc3
--- /dev/null
+++ b/src/renderer/src/utils/origin.ts
@@ -0,0 +1,201 @@
+/**
+ * 函数来源分类（v3 新增 origin 字段的 UI 工具）。
+ *
+ * 设计要点：
+ * - engine 端按 `origin` 字段给每个 FunctionNode 标好来源（user / stdlib /
+ *   third_party / builtin / frozen / other）；本模块把它投影到 UI。
+ * - v2 数据（无 origin 字段）走 fallback：从 module 字符串启发式推导。
+ *   注意 fallback **不保证准确** —— module 名相同的库和 stdlib 重名（"json"）时
+ *   会误判为 stdlib。运行时跨 IPC 拿不到 sys.stdlib_module_names，故只能妥协。
+ *   UI 在这种场景下退化为「按 module 名归堆」，不会崩。
+ *
+ * 显示顺序很关键 —— 用户最关心的是「我的代码 vs 库」，所以 user 排最前，
+ * 其次是真正影响性能的 stdlib / third_party，再后面是 builtin / frozen / other 兜底。
+ */
+
+import type { FunctionNode } from '../../../shared/analysis'
+
+/** 6 种来源 —— 顺序就是 UI 默认从上到下的展示顺序。 */
+export type Origin = 'user' | 'stdlib' | 'third_party' | 'builtin' | 'frozen' | 'other'
+
+/** 稳定展示顺序：user 优先 → 主要 library → 兜底。 */
+export const ORIGIN_ORDER: readonly Origin[] = ['user', 'third_party', 'stdlib', 'builtin', 'frozen', 'other']
+
+/** 长标签 i18n key（用于 section header / aria-label） */
+export const ORIGIN_LABEL_KEY: Record<
+  Origin,
+  'origin.user' | 'origin.stdlib' | 'origin.thirdParty' | 'origin.builtin' | 'origin.frozen' | 'origin.other'
+> = {
+  user: 'origin.user',
+  stdlib: 'origin.stdlib',
+  third_party: 'origin.thirdParty',
+  builtin: 'origin.builtin',
+  frozen: 'origin.frozen',
+  other: 'origin.other'
+}
+
+/** 短标签 i18n key（用于模块 chip 旁的徽章） */
+export const ORIGIN_ABBR_KEY: Record<
+  Origin,
+  | 'origin.abbr.user'
+  | 'origin.abbr.stdlib'
+  | 'origin.abbr.thirdParty'
+  | 'origin.abbr.builtin'
+  | 'origin.abbr.frozen'
+  | 'origin.abbr.other'
+> = {
+  user: 'origin.abbr.user',
+  stdlib: 'origin.abbr.stdlib',
+  third_party: 'origin.abbr.thirdParty',
+  builtin: 'origin.abbr.builtin',
+  frozen: 'origin.abbr.frozen',
+  other: 'origin.abbr.other'
+}
+
+/**
+ * 各 origin 的视觉颜色（CSS 颜色值）
+ *
+ * 不依赖 palette / Tailwind token —— origin 是离散 6 类，用 hex 直接挑
+ * Tailwind 默认色板里的 500 系色值（色彩对比度够 + 跨主题不糊）。
+ *
+ * - user        绿（用户的"我的代码"，最有归属感）
+ * - third_party 紫（区分最远的"第三方库"，抢眼）
+ * - stdlib      蓝（标准库，朴素稳）
+ * - builtin     灰（内置函数，最不抢眼）
+ * - frozen      灰偏暗（frozen importlib 帧，正常用户看不见）
+ * - other       黄（兜底，警告色，提示「这条帧没有正确归类」）
+ */
+export const ORIGIN_COLOR: Record<Origin, string> = {
+  user: '#22c55e', // green-500
+  third_party: '#a855f7', // purple-500
+  stdlib: '#3b82f6', // blue-500
+  builtin: '#6b7280', // gray-500
+  frozen: '#374151', // gray-700
+  other: '#eab308' // yellow-500
+}
+
+/**
+ * 把 FunctionNode 归类到 Origin。优先用 engine 算好的 origin 字段；
+ * 缺失时按 module 字符串启发式推导（不保证准确）。
+ *
+ * fallback 启发式：
+ * - "<user>"        → user
+ * - "<frozen ...>"  → frozen
+ * - "<built-in ...>" → builtin
+ * - 其它 "<..."    → other
+ * - module == ""    → other（cProfile 内部，几乎不会出现）
+ */
+export function resolveOrigin(fn: Pick<FunctionNode, 'origin' | 'module'>): Origin {
+  if (fn.origin && isKnownOrigin(fn.origin)) return fn.origin
+  const m = fn.module
+  if (m === '<user>') return 'user'
+  if (m === '<frozen>') return 'frozen'
+  if (m === '<built-in>') return 'builtin'
+  if (m.startsWith('<')) return 'other'
+  return 'other'
+}
+
+function isKnownOrigin(s: string): s is Origin {
+  return (
+    s === 'user' ||
+    s === 'stdlib' ||
+    s === 'third_party' ||
+    s === 'builtin' ||
+    s === 'frozen' ||
+    s === 'other'
+  )
+}
+
+/**
+ * 把一组 FunctionNode 按 origin 聚合，返回按 ORIGIN_ORDER 顺序的 entries。
+ *
+ * 不返回空桶 —— UI 只画「实际存在的 origin」section，避免出现空 header。
+ */
+export function groupFunctionsByOrigin(
+  fns: readonly FunctionNode[]
+): Array<{ origin: Origin; functions: FunctionNode[] }> {
+  const buckets = new Map<Origin, FunctionNode[]>()
+  for (const f of fns) {
+    const o = resolveOrigin(f)
+    let bucket = buckets.get(o)
+    if (!bucket) {
+      bucket = []
+      buckets.set(o, bucket)
+    }
+    bucket.push(f)
+  }
+  return ORIGIN_ORDER.filter((o) => buckets.has(o)).map((o) => ({
+    origin: o,
+    functions: buckets.get(o) ?? []
+  }))
+}
+
+/**
+ * 把一组 ModuleKey（string）按「该模块的 representative 函数」的 origin 归类。
+ * HotspotTable 的 module chips 用这个。
+ */
+export function groupModuleKeysByOrigin(
+  modules: readonly string[],
+  fnByModule: ReadonlyMap<string, FunctionNode>
+): Array<{ origin: Origin; modules: string[] }> {
+  const buckets = new Map<Origin, string[]>()
+  for (const m of modules) {
+    const sample = fnByModule.get(m)
+    const o = sample ? resolveOrigin(sample) : 'other'
+    let bucket = buckets.get(o)
+    if (!bucket) {
+      bucket = []
+      buckets.set(o, bucket)
+    }
+    bucket.push(m)
+  }
+  return ORIGIN_ORDER.filter((o) => buckets.has(o)).map((o) => ({
+    origin: o,
+    modules: buckets.get(o) ?? []
+  }))
+}
+
+/**
+ * 测试代码识别 —— 用户 profile 里经常混进项目内部 tests/ 目录下的辅助函数,
+ * 它们不是优化目标(甚至不是用户写来跑业务的部分),默认应该被剔除出统计。
+ *
+ * 设计原则:**只看语境(文件路径 / 模块路径 / 引擎内部硬编码白名单),
+ * 完全不看函数名**。函数名匹配太容易误伤(`test_helper()`、`test_visualization()`、
+ * `MyClass.test_count()` 都是合法业务函数),不是「已知的测试代码」就该被猜。
+ *
+ * 命中条件(任一即算):
+ * - 文件名是 `test_xxx.py` 或 `xxx_test.py` —— pytest 文件命名约定(任意位置)
+ * - 文件**直接**在 `tests/` / `test/` / `__tests__/` 目录下 —— pytest 目录约定。
+ *   收紧到「紧接文件名,不能有子目录」:
+ *     * tests/foo.py             → 算 (foo.py 直接挂在 tests/ 下)
+ *     * tests/fixtures/foo.py    → 不算 (fixtures 是子目录,foo.py 不挂在 tests/ 下)
+ *   之前用 `[\\/](tests?|__tests__)[\\/]` 任何含 `/tests/` 的路径都中招,把 fixtures
+ *   这类测试数据夹具也当成测试代码误伤 —— 用户脚本只要住在带 tests/ 子目录的
+ *   路径下,functions 表直接被过滤成 0 行。
+ * - 模块路径是 `tests` / `test` / `__tests__`,或其子模块(`tests.foo` 等)
+ * - 引擎内部硬编码白名单(`_pyrof_calib` 等)—— 这些 100% 是引擎自身的,永远不该进用户 stats
+ *
+ * **不**匹配(避免误伤):
+ * - 任何「以 test_ 开头的函数名」 —— 业务函数常用此名
+ * - 任何「以 _test 结尾的函数名」 —— 业务函数常用此后缀
+ * - unittest 方法名 `TestXxx.test_yyy` —— 用户业务代码也可能这么写
+ * - 模块名含 test 子串(testing / dataset / contest) —— 业务模块常用
+ * - 单文件 `test.py` / `tests.py` —— 项目入口常这么命名
+ * - `tests/` 子目录下的非测试文件(`tests/fixtures/x.py` 等)—— 是测试数据不是测试代码
+ */
+const TEST_FILE_RE = /[\\/](?:test_[^\\/]+|[^\\/]+_test)\.py$/
+const TEST_DIR_RE = /[\\/](tests?|__tests__)[\\/][^\\/]+$/
+const TEST_MODULE_RE = /^(tests?|__tests__)([._]|$)/
+
+/** 引擎内部硬编码白名单 —— 这些 100% 是引擎自己的,任何情况下都不该出现在用户 stats 里。
+ *  校准负载 `_pyrof_calib` 是其中最可能漏进去的(独立 exec 之后理论上不应泄漏,
+ *  但加个白名单兜底零成本)。 */
+const INTERNAL_NAMES: ReadonlySet<string> = new Set(['_pyrof_calib'])
+
+export function isInternalTest(fn: Pick<FunctionNode, 'name' | 'module' | 'file'>): boolean {
+  if (INTERNAL_NAMES.has(fn.name)) return true
+  if (TEST_FILE_RE.test(fn.file)) return true
+  if (TEST_DIR_RE.test(fn.file)) return true
+  if (TEST_MODULE_RE.test(fn.module)) return true
+  return false
+}
diff --git a/src/renderer/src/vite-env.d.ts b/src/renderer/src/vite-env.d.ts
new file mode 100644
index 0000000..a60ee71
--- /dev/null
+++ b/src/renderer/src/vite-env.d.ts
@@ -0,0 +1,8 @@
+/// <reference types="vite/client" />
+
+// Monaco 编辑器的 5 类 Web Worker 通过 Vite 的 ?worker 后缀打包；TS 没有原生类型，
+// 这里声明 module 让 `import x from 'monaco-editor/.../x.worker?worker'` 不报错。
+declare module '*?worker' {
+  const workerConstructor: { new (): Worker }
+  export default workerConstructor
+}
diff --git a/src/shared/__tests__/analysis.test.ts b/src/shared/__tests__/analysis.test.ts
new file mode 100644
index 0000000..e8978b8
--- /dev/null
+++ b/src/shared/__tests__/analysis.test.ts
@@ -0,0 +1,84 @@
+/**
+ * isAnalysisResult 的回归测试。重点守住"轻量校验"边界 — 拒绝明显畸形 / 类型错误，
+ * 但允许 schema 演化过程中的字段增减。这是 schema 漂移保护的关键一环。
+ */
+import { describe, expect, it } from 'vitest'
+import { isAnalysisResult } from '../analysis'
+
+const BASE = {
+  schemaVersion: 2,
+  environment: { python: '3.11', platform: 'win32', processor: 'x86_64', timerResolution: 1e-6 },
+  config: {},
+  status: 'ok',
+  error: null,
+  wallTime: { seconds: 0.42, unit: 's' },
+  functions: [],
+  flame: null
+} as const
+
+describe('isAnalysisResult', () => {
+  it('accepts a well-formed AnalysisResult', () => {
+    expect(isAnalysisResult(BASE)).toBe(true)
+  })
+
+  it('rejects null / undefined / primitives', () => {
+    expect(isAnalysisResult(null)).toBe(false)
+    expect(isAnalysisResult(undefined)).toBe(false)
+    expect(isAnalysisResult('ok')).toBe(false)
+    expect(isAnalysisResult(42)).toBe(false)
+    expect(isAnalysisResult(true)).toBe(false)
+  })
+
+  it('rejects when top-level keys are missing', () => {
+    const { schemaVersion: _schemaVersion, ...rest } = BASE
+    expect(isAnalysisResult(rest)).toBe(false)
+    const { status: _status, ...withoutStatus } = BASE
+    expect(isAnalysisResult(withoutStatus)).toBe(false)
+  })
+
+  it('rejects when status is an unknown string', () => {
+    expect(isAnalysisResult({ ...BASE, status: 'weird_state' })).toBe(false)
+  })
+
+  it('accepts all known status values', () => {
+    for (const s of ['ok', 'syntax_error', 'runtime_error', 'timeout'] as const) {
+      expect(isAnalysisResult({ ...BASE, status: s })).toBe(true)
+    }
+  })
+
+  it('rejects when error object has wrong field type', () => {
+    const bad = { ...BASE, error: { type: 42, message: 'x' } }
+    expect(isAnalysisResult(bad)).toBe(false)
+  })
+
+  it('accepts extra unknown fields (schema evolution)', () => {
+    const evolved = { ...BASE, futureField: { anything: true }, anotherOne: 123 }
+    expect(isAnalysisResult(evolved)).toBe(true)
+  })
+
+  it('accepts null wallTime (error path)', () => {
+    expect(isAnalysisResult({ ...BASE, status: 'runtime_error', wallTime: null })).toBe(true)
+  })
+
+  it('rejects when wallTime has wrong field types', () => {
+    expect(isAnalysisResult({ ...BASE, wallTime: { seconds: '0.5', unit: 's' } })).toBe(false)
+    expect(isAnalysisResult({ ...BASE, wallTime: { seconds: 0.5, unit: 42 } })).toBe(false)
+  })
+
+  it('rejects functions that is not an array', () => {
+    expect(isAnalysisResult({ ...BASE, functions: 'nope' as unknown as never })).toBe(false)
+  })
+
+  it('rejects when environment fields have wrong types', () => {
+    expect(isAnalysisResult({ ...BASE, environment: { ...BASE.environment, python: 3 } })).toBe(false)
+  })
+
+  it('rejects unknown schemaVersion', () => {
+    expect(isAnalysisResult({ ...BASE, schemaVersion: 1 })).toBe(false)
+    expect(isAnalysisResult({ ...BASE, schemaVersion: 99 })).toBe(false)
+  })
+
+  it('rejects when flame is a non-object (not null)', () => {
+    expect(isAnalysisResult({ ...BASE, flame: 123 as unknown as null })).toBe(false)
+  })
+})
diff --git a/src/shared/__tests__/ipc.test.ts b/src/shared/__tests__/ipc.test.ts
new file mode 100644
index 0000000..6784790
--- /dev/null
+++ b/src/shared/__tests__/ipc.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest'
+import { IpcError, IPC_ERROR_TAG, readIpcError, isIpcError, IPC_ERROR_KINDS } from '../ipc'
+
+describe('IpcError / readIpcError', () => {
+  it('IpcError 实例的 message 以 [IPC_ERROR] 开头并包含 JSON', () => {
+    const e = new IpcError('invalid_payload', '形状校验失败', { bounds: 'tight' })
+    expect(e.kind).toBe('invalid_payload')
+    expect(e.message.startsWith(IPC_ERROR_TAG + ' ')).toBe(true)
+    // 消息里能 JSON.parse 回结构（这是 IPC 跨进程传输的关键）
+    const j = JSON.parse(e.message.slice(IPC_ERROR_TAG.length + 1)) as { kind: string; message: string }
+    expect(j.kind).toBe('invalid_payload')
+    expect(j.message).toBe('形状校验失败')
+    // readableMessage 把 JSON 解出来给人类
+    expect(e.readableMessage).toBe('形状校验失败')
+  })
+
+  it('IPC_ERROR_KINDS 包含所有 kind（增删时测试会失败提醒）', () => {
+    // 这条不是"行为"测试，是 schema-version-style 的守门 ——
+    // 改了 IpcErrorKind union 但忘了同步 IPC_ERROR_KINDS 数组（readIpcError 用它
+    // 校验 JSON 解析出来的 kind 是否合法），上面 cast 就不会失败但运行时 readIpcError 会 null。
+    expect(IPC_ERROR_KINDS).toContain('invalid_payload')
+    expect(IPC_ERROR_KINDS).toContain('interpreter_not_allowed')
+    expect(IPC_ERROR_KINDS).toContain('payload_too_large')
+    expect(IPC_ERROR_KINDS).toContain('engine_not_found')
+    expect(IPC_ERROR_KINDS).toContain('interpreter_probe_failed')
+    expect(IPC_ERROR_KINDS).toContain('cancelled')
+    expect(IPC_ERROR_KINDS).toContain('unknown')
+  })
+
+  it('readIpcError(IpcError) 直接返回（同进程内部调用，未跨 IPC）', () => {
+    const original = new IpcError('engine_not_found', '找不到 runner.py')
+    const restored = readIpcError(original)
+    expect(restored).toBe(original)
+    expect(restored.kind).toBe('engine_not_found')
+    expect(restored.readableMessage).toBe('找不到 runner.py')
+  })
+
+  it('readIpcError 还原跨 IPC 过来的 Error（message 以 [IPC_ERROR] 开头）', () => {
+    // 模拟 IPC 序列化后的状态：prototype 链已丢，但 message 字符串保留完整。
+    // 构造函数走 Error(message)，不挂 IpcError.prototype。
+    const serialized = new Error(
+      `${IPC_ERROR_TAG} ${JSON.stringify({
+        kind: 'payload_too_large',
+        message: '代码过大 (2.5 MB > 1 MB)',
+        details: { byteLen: 2621440, maxBytes: 1048576 }
+      })}`
+    )
+    // instanceof 不可靠 — 验证一下我们假设的前提
+    expect(serialized instanceof IpcError).toBe(false)
+
+    const restored = readIpcError(serialized)
+    expect(restored.kind).toBe('payload_too_large')
+    expect(restored.readableMessage).toBe('代码过大 (2.5 MB > 1 MB)')
+    expect(restored.details).toEqual({ byteLen: 2621440, maxBytes: 1048576 })
+  })
+
+  it('readIpcError 把裸 Error 包成 kind=unknown，保留原 message', () => {
+    const restored = readIpcError(new Error('ENOENT: no such file'))
+    expect(restored.kind).toBe('unknown')
+    expect(restored.readableMessage).toBe('ENOENT: no such file')
+  })
+
+  it('readIpcError 把 string 包成 kind=unknown', () => {
+    const restored = readIpcError('boom')
+    expect(restored.kind).toBe('unknown')
+    expect(restored.readableMessage).toBe('boom')
+  })
+
+  it('readIpcError 把对象尽力 JSON 化（IPC 偶发抛裸对象）', () => {
+    const restored = readIpcError({ code: 'EACCES', path: '/x' })
+    expect(restored.kind).toBe('unknown')
+    expect(restored.readableMessage).toBe('{"code":"EACCES","path":"/x"}')
+  })
+
+  it('readIpcError 把 null / undefined 包成 unknown', () => {
+    expect(readIpcError(null).kind).toBe('unknown')
+    expect(readIpcError(undefined).kind).toBe('unknown')
+  })
+
+  it('message 前缀对了但 JSON 解析失败 → kind=unknown', () => {
+    // 模拟跨 IPC 时 message 被截断 / 乱码导致 JSON.parse 炸
+    const broken = new Error(`${IPC_ERROR_TAG} {this is not json`)
+    const restored = readIpcError(broken)
+    expect(restored.kind).toBe('unknown')
+    // 整个 message 字符串保留，方便排查（这里 readableMessage 拿原始 message，因为 JSON.parse 失败走 fallback）
+    expect(restored.readableMessage).toBe(`${IPC_ERROR_TAG} {this is not json`)
+  })
+
+  it('message 前缀对了但 kind 是未知字符串 → kind=unknown（防止 JS 拒绝）', () => {
+    // 防御：未来加了 kind 但忘了同步这里，readIpcError 仍然给出可读结果，
+    // 而不是把 unknown string 强塞进 IpcError 让 UI 显示乱码
+    const forged = new Error(
+      `${IPC_ERROR_TAG} ${JSON.stringify({
+        kind: 'mystery_kind',
+        message: '...'
+      })}`
+    )
+    const restored = readIpcError(forged)
+    expect(restored.kind).toBe('unknown')
+    expect(restored.readableMessage).toBe('...')
+  })
+
+  it('isIpcError 对 IpcError 实例与跨 IPC 还原路径都返回 true', () => {
+    expect(isIpcError(new IpcError('cancelled', '已取消'))).toBe(true)
+    const acrossIpc = new Error(`${IPC_ERROR_TAG} ${JSON.stringify({ kind: 'cancelled', message: 'x' })}`)
+    expect(isIpcError(acrossIpc)).toBe(true)
+    expect(isIpcError(new Error('plain'))).toBe(false)
+    expect(isIpcError(null)).toBe(false)
+    expect(isIpcError('boom')).toBe(false)
+  })
+
+  it('details 不是对象时（数组 / 字符串 / null）安全降级', () => {
+    const cases: unknown[] = [
+      JSON.stringify({ kind: 'unknown', message: 'x', details: 'not an object' }),
+      JSON.stringify({ kind: 'unknown', message: 'x', details: ['array', 'is', 'rejected'] }),
+      JSON.stringify({ kind: 'unknown', message: 'x', details: null })
+    ]
+    for (const c of cases) {
+      const restored = readIpcError(new Error(`${IPC_ERROR_TAG} ${String(c)}`))
+      expect(restored.kind).toBe('unknown')
+      // details 不应该是数组 / string / null
+      expect(restored.details === undefined || typeof restored.details === 'object').toBe(true)
+    }
+  })
+})
diff --git a/src/shared/__tests__/schema-version.test.ts b/src/shared/__tests__/schema-version.test.ts
new file mode 100644
index 0000000..aabd314
--- /dev/null
+++ b/src/shared/__tests__/schema-version.test.ts
@@ -0,0 +1,28 @@
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { SUPPORTED_SCHEMA_VERSIONS } from '../analysis'
+
+/**
+ * 守住 schema 漂移的两面：TS 的 SUPPORTED_SCHEMA_VERSIONS 必须涵盖 Python
+ * engine/schema.py 的 SCHEMA_VERSION。
+ *
+ * 历史上这个问题出现过：Python 升了版本 +1 加了新字段，TS 没改，isAnalysisResult
+ * 仍然 true（因为不查 version），结果新字段 undefined 上 UI 报"Cannot read ..."，
+ * 排查半天。
+ *
+ * 现在两边写死一致，由这个测试单点核对。改 schema 必改两边。
+ */
+describe('Schema 版本守门', () => {
+  it('TS 的 SUPPORTED_SCHEMA_VERSIONS 与 Python SCHEMA_VERSION 一致', () => {
+    const pyPath = join(__dirname, '..', '..', '..', 'engine', 'schema.py')
+    const py = readFileSync(pyPath, 'utf-8')
+    const m = py.match(/^SCHEMA_VERSION\s*=\s*(\d+)\s*$/m)
+    if (!m) throw new Error(`在 ${pyPath} 找不到 SCHEMA_VERSION = N 的定义`)
+    const pyVersion = Number(m[1])
+    expect(
+      SUPPORTED_SCHEMA_VERSIONS.includes(pyVersion),
+      `Python SCHEMA_VERSION=${pyVersion} 不在 TS SUPPORTED_SCHEMA_VERSIONS=[${SUPPORTED_SCHEMA_VERSIONS.join(', ')}] 里。` +
+        `两边必须同步改。`
+    ).toBe(true)
+  })
+})
diff --git a/src/shared/analysis.ts b/src/shared/analysis.ts
new file mode 100644
index 0000000..65f9819
--- /dev/null
+++ b/src/shared/analysis.ts
@@ -0,0 +1,346 @@
+// 与 engine/schema.py 对齐的类型（单一事实源在 Python 侧，靠契约测试保证一致）
+
+export interface Environment {
+  python: string
+  platform: string
+  processor: string
+  timerResolution: number
+}
+
+export interface WallTime {
+  seconds: number
+  unit: string
+}
+
+/**
+ * cProfile 开销校准（v4 新增）。
+ *
+ * 用户脚本在 v4 起只 exec 一次且必须开 cProfile（单跑架构）—— 但 cProfile 是插桩式的，
+ * wall-time 会膨胀 1.5~3x。引擎启动期跑同一段 tight-loop 各一次（裸 vs 仪器化），
+ * 用 ratio = instrumented / clean 把用户的 instrumented 时间除回去作为估计的干净耗时。
+ *
+ * ok 状态下 result.calibration 必有；非 ok（语法错 / 运行时错 / 超时）下为 null。
+ */
+export interface Calibration {
+  ratio: number
+  workloadName: string
+  instrumentedWorkloadSec: number
+  cleanWorkloadSec: number
+}
+
+export interface FunctionNode {
+  id: string // "file:line:name"
+  file: string
+  line: number
+  name: string
+  cumtime: number
+  tottime: number
+  ncalls: number
+  percallTot: number
+  /**
+   * 顶层模块名（用于 scope=all 时 UI 分类）：
+   * - "<user>" 用户脚本
+   * - "json" / "numpy" 等 — 顶层包名（取自 site-packages / dist-packages / stdlib 之后第一个目录段）
+   * - "<frozen>" / "<built-in>" — cProfile 给的虚拟帧
+   *
+   * 提取逻辑见 engine/structure._top_module；schema 演化加字段时这里同步加，
+   * 契约测试 test_function_keys_match_both_sides 会锁住。
+   */
+  module: string
+  /**
+   * 帧来源（v3 新增；UI 按 origin 分组用）：
+   * - "user" 用户脚本 / "stdlib" 标准库 / "third_party" 第三方包
+   * - "builtin" 内置（C 实现的 builtin）
+   * - "frozen" frozen importlib 等 / "other" 兜底
+   *
+   * 可选 —— v2 数据没有这个字段时 UI 退化为从 module 名推；
+   * 字段缺失不要让 isAnalysisResult 直接挂（schema-version 边界）。
+   * 推导逻辑见 engine/structure._classify_origin。
+   */
+  origin?: string
+}
+
+export interface FlameNode {
+  name: string
+  value: number
+  children: FlameNode[]
+}
+
+export type AnalysisStatus = 'ok' | 'syntax_error' | 'runtime_error' | 'timeout'
+
+/** 引擎在非 ok 状态下回填的诊断信息。
+ * - traceback: Python 端的完整 traceback（仅 runtime_error 时有）
+ * - stderrTail: 子进程 stderr 末尾（仅 timeout 时有，便于排查卡死原因） */
+export interface AnalysisError {
+  type: string
+  message: string
+  traceback?: string
+  stderrTail?: string
+}
+
+export interface AnalysisResult {
+  schemaVersion: number
+  environment: Environment
+  /** 空 dict：v1 的 repeats/warmup/topN/timeoutSec 字段已移除。
+   * 保留字段是因为 schema 单一事实源在 Python dataclass 里不方便"删字段"。 */
+  config: Record<string, never>
+  status: AnalysisStatus
+  error?: AnalysisError | null
+  wallTime: WallTime | null
+  functions: FunctionNode[]
+  flame: FlameNode | null
+  /**
+   * cProfile 开销校准信息（v4 新增）。ok 状态下必有；非 ok 时为 undefined。
+   * 见 Calibration 注释。
+   */
+  calibration?: Calibration
+}
+
+export interface InterpreterInfo {
+  path: string
+  version: string
+}
+
+/**
+ * validateInterpreter / pickInterpreter 的统一返回类型。
+ * - 成功：返回 InterpreterInfo
+ * - 用户取消系统对话框：返回 null（renderer 静默处理，不报错）
+ * - 真正的失败（解释器不可执行 / 路径非 python 形态）：main 进程 throw IpcError，
+ *   走 readIpcError → formatIpcError 翻译链；renderer 端不再单独走 discriminated union。
+ *
+ * 之前失败的 discriminated union (`{ ok: false; error: string }`) 被移除 —— 错误
+ * 文案是 main 进程 hardcoded 的中文,en-US 用户看到会很懵。改成 throw IpcError 让
+ * 渲染侧按 kind + lang 翻译,跟 analyze / file:read 等其他 IPC 入口保持一致。
+ */
+export type InterpreterResult = InterpreterInfo | null
+
+export interface RunOptions {
+  interpreter: string
+  code: string
+  /**
+   * 剖析范围：
+   * - "user"（默认）只归因用户脚本里的函数
+   * - "all" 包含所有非 cProfile 内部帧（标准库 + 第三方包 + 用户代码），
+   *   让耗时可以下钻到 import 的包里
+   *
+   * 字段缺失等同于 "user"，保持向后兼容（v2 之前没有这个字段也能跑）。
+   */
+  scope?: 'user' | 'all'
+}
+
+export interface ProgressEvent {
+  phase: string
+  pct: number
+}
+
+/**
+ * 主进程 file:read IPC 的入参。
+ *
+ * 只读不写：主进程拿到 filePath 后做 normalize + 路径校验 + 大小校验，然后 fs.readFile。
+ * 没有 `encoding` 选项 —— Python 源文件按 UTF-8 读，写别的编码会在 Monaco 里渲染乱码，
+ * 而 cProfile 报的 stdlib / site-packages 文件本来就是 UTF-8。
+ */
+export interface FileReadRequest {
+  filePath: string
+}
+
+/**
+ * 主进程 file:read 的返回值 —— discriminated union。
+ *
+ * 走「带 ok 的 union」而不是直接 throw，原因：
+ * - 文件不存在 / 权限不足 / 超过 2MB 是「预期错误」，UI 要把这条信息展示在 tab 里，
+ *   不需要走 ErrorBanner / readIpcError 那套把 kind 翻译成文的链路。
+ * - 真异常（ENOENT 之外的 fs 错误、磁盘 I/O 故障）会让 main 进程 throw IpcError，
+ *   渲染端用 readIpcError 走通用路径。
+ *
+ * `kind` 字段在两种返回里都存在（成功为 'ok'），让渲染侧可以用
+ * `if (result.kind === 'ok')` 单一字段窄化，不用 `if ('ok' in result)`。
+ */
+export type FileReadResult =
+  | { kind: 'ok'; content: string; size: number }
+  | {
+      kind: 'not_found' | 'not_a_file' | 'permission_denied' | 'too_large' | 'invalid_path'
+      message: string
+    }
+
+/** 内嵌终端(xterm.js + spawn shell)已移除 —— 焦点跨 IPC 不稳、键盘输入经常丢、
+ *  渲染开销大、Electron sandbox 下兼容性差。改成「打开系统终端」按钮,
+ *  按需弹用户本机的 cmd.exe / Terminal.app / gnome-terminal。
+ *  对应 IPC: src/main/terminal.ts 的 openTerminal(command?)。 */
+
+// preload 暴露给渲染层的 API
+export interface RendererApi {
+  detectInterpreters(): Promise<InterpreterInfo[]>
+  pickInterpreter(): Promise<InterpreterResult | null>
+  analyze(opts: RunOptions): Promise<AnalysisResult>
+  cancel(): Promise<void>
+  onProgress(cb: (e: ProgressEvent) => void): () => void
+  /**
+   * 订阅 Python 子进程 stdout 的流式推送。每收到一块 stdout 文本就调一次 cb。
+   * 与 onProgress 同一类事件订阅：返回 unsubscribe 函数,在 useEffect cleanup 调用。
+   *
+   * 设计动机:Python `print()` 输出对用户是最直观的反馈,放在 RunConsole 实时滚动。
+   * 不放进 AnalysisResult —— 流式推送后渲染端 buffer 是 single source of truth,
+   * 避免大输出把 IPC / 内存撑爆。
+   */
+  onStdout(cb: (chunk: string) => void): () => void
+  /**
+   * 打开系统终端(可预填一条命令;命令跑完窗口保持打开)。
+   * 不传命令时弹一个默认 shell 窗口。
+   *
+   * `shell` 仅 Windows 生效 — 选 cmd.exe 或 powershell.exe;Mac / Linux 用 OS 自带 terminal。
+   * 不传时默认 'cmd'。在 Settings → Shell 里可改默认值。
+   */
+  openTerminal(command?: string, shell?: 'cmd' | 'powershell'): Promise<void>
+  /**
+   * 读取一个 Python 源文件的内容（用于点击 stdlib / 第三方包热点时打开对应文件 tab）。
+   *
+   * **不用于用户代码**：用户代码的 fn.file 指向 profiler-service 在 tmpdir 里建的脚本路径，
+   * 跑完分析后整个 workdir 被 rm 掉，文件已不存在。用户代码热点的"打开"走的是 App 内存里
+   * 的 code state，永远不发这个 IPC。
+   *
+   * 主进程做路径 / 扩展名 / 大小校验；预期错误返回带 kind 的对象（不 throw），
+   * UI 直接展示在 tab 里。
+   */
+  readFile(req: FileReadRequest): Promise<FileReadResult>
+  /**
+   * 主进程所在平台(`process.platform`),preload 启动时确定。
+   * 渲染层用它挑 platform-specific 的安装命令。
+   */
+  platform: NodeJS.Platform
+  /**
+   * 顶栏左上角图标的 PNG data URL（与 BrowserWindow 窗口图标 / macOS dock 图标同源，
+   * 都来自项目根的 icon.ico）。
+   *
+   * 主进程读 .ico 后 resize 到 32×32 再编码 —— 顶栏显示 ~18px，传 256×256 是浪费 + 缩放糊。
+   *
+   * 文件缺失 / 解不开时返回 `null`，renderer 退回内置 SVG（保证顶栏永远有东西）。
+   */
+  getAppIcon(): Promise<string | null>
+  /**
+   * 在系统默认浏览器里打开一个外部 URL（设置「关于」section 的开发者主页链接用）。
+   *
+   * 走 IPC 而不是 `<a target="_blank">` 直开：Electron 默认会把新窗口开成 BrowserWindow，
+   * 而 sandbox + contextIsolation 下没有 setWindowOpenHandler 时直接被吞掉。走主进程的
+   * `shell.openExternal` 是唯一稳定可靠的路径,且主进程能强制只放行 http/https,
+   * 防止渲染层被注入后塞 javascript: / file: 进来。
+   *
+   * 主进程对非 http(s) 协议、URL.parse 失败等异常 throw IpcError,渲染侧走通用翻译链。
+   */
+  openExternal(url: string): Promise<void>
+  /**
+   * 自定义窗口控制按钮（frame: false 后由 renderer 替代 OS 标题栏）。
+   *
+   * - minimize / close：fire-and-forget，主进程直接调 BrowserWindow 方法。
+   * - toggleMaximize：返回 `{ isMaximized }` 让 renderer 立即拿到权威状态 —— 比单纯依赖
+   *   `onMaximizeChanged` 事件更稳，事件可能在 IPC response 之后到达造成图标闪烁。
+   * - isMaximized：mount 时拉一次初始值；之前用户可能已经处于最大化，重启后不能默认 false。
+   * - onMaximizeChanged：监听 OS 触发（双击标题栏 / Win+Up / 任务栏右键菜单）的状态变更。
+   */
+  windowControls: {
+    minimize(): Promise<void>
+    toggleMaximize(): Promise<{ isMaximized: boolean }>
+    close(): Promise<void>
+    isMaximized(): Promise<boolean>
+    onMaximizeChanged(cb: (isMaximized: boolean) => void): () => void
+  }
+}
+
+/**
+ * 运行时校验：引擎写出的结果 JSON 解析后是不是一个像 AnalysisResult 的对象。
+ * 设计原则：
+ * - **轻量**：不递归验证每个字段（schema 演化过程中加字段很正常，深度断言会脆），
+ *   只验证"形状对得上 + 关键字段类型正确"。
+ * - **容错**：未识别的字段直接忽略；多 / 少一个可选字段不算错。
+ * - **不替 JSON.parse 兜底**：parse 抛错仍由 caller 处理（消息更具体）。
+ *
+ * 调用场景：
+ * 1. main 进程 `JSON.parse(...) as AnalysisResult` 之前 — 防止 schema 漂移后
+ *    renderer 端报 "Cannot read property 'wallTime' of undefined" 之类的运行时崩溃
+ * 2. 测试夹具 `golden as unknown as AnalysisResult` 之前 — 失败信息更友好
+ *    （见 fixtures/__tests__/golden.test.ts）
+ *
+ * 失败时返回 false，caller 决定怎么降级（一般走 makeRuntimeError 的 'ParseError' 路径）。
+ */
+
+/**
+ * TS 侧支持的 schema 版本。
+ *
+ * 必须与 engine/schema.py 的 SCHEMA_VERSION 保持一致 —— 不一致的话 TS 拒绝任何
+ * Python 输出（isAnalysisResult 返回 false），UI 上看不到数据但没有明确报错。
+ * 这条数值变更触发一次「breaking change」：两边必须同步改，测试
+ * src/shared/__tests__/schema-version.test.ts 会强制锁住。
+ */
+export const SUPPORTED_SCHEMA_VERSIONS: readonly number[] = [2, 3, 4]
+
+export function isAnalysisResult(x: unknown): x is AnalysisResult {
+  if (typeof x !== 'object' || x === null) return false
+  const r = x as Record<string, unknown>
+  // 顶层形状
+  if (typeof r['schemaVersion'] !== 'number') return false
+  if (!SUPPORTED_SCHEMA_VERSIONS.includes(r['schemaVersion'])) return false
+  if (!isEnvironment(r['environment'])) return false
+  // config: v2 起是空 dict；只校验"是 plain object"即可
+  if (typeof r['config'] !== 'object' || r['config'] === null || Array.isArray(r['config'])) {
+    return false
+  }
+  if (typeof r['status'] !== 'string') return false
+  if (!isAnalysisStatus(r['status'])) return false
+  // error 可选；存在时必须是对象
+  if (r['error'] != null && !isAnalysisError(r['error'])) return false
+  // wallTime 可为 null；存在时必须是对象
+  if (r['wallTime'] != null && !isWallTime(r['wallTime'])) return false
+  if (!Array.isArray(r['functions'])) return false
+  // flame 可为 null
+  if (r['flame'] != null && !isFlameNode(r['flame'])) return false
+  // calibration: v4 新增,可选(非 ok 状态下为 null);存在时必须是对象
+  if (r['calibration'] != null && !isCalibration(r['calibration'])) return false
+  return true
+}
+
+function isCalibration(x: unknown): x is Calibration {
+  if (typeof x !== 'object' || x === null) return false
+  const c = x as Record<string, unknown>
+  return (
+    typeof c['ratio'] === 'number' &&
+    typeof c['workloadName'] === 'string' &&
+    typeof c['instrumentedWorkloadSec'] === 'number' &&
+    typeof c['cleanWorkloadSec'] === 'number'
+  )
+}
+
+function isEnvironment(x: unknown): x is Environment {
+  if (typeof x !== 'object' || x === null) return false
+  const e = x as Record<string, unknown>
+  return (
+    typeof e['python'] === 'string' &&
+    typeof e['platform'] === 'string' &&
+    typeof e['processor'] === 'string' &&
+    typeof e['timerResolution'] === 'number'
+  )
+}
+
+function isAnalysisStatus(x: unknown): x is AnalysisStatus {
+  return x === 'ok' || x === 'syntax_error' || x === 'runtime_error' || x === 'timeout'
+}
+
+function isAnalysisError(x: unknown): x is AnalysisError {
+  if (typeof x !== 'object' || x === null) return false
+  const e = x as Record<string, unknown>
+  if (typeof e['type'] !== 'string' || typeof e['message'] !== 'string') return false
+  if (e['traceback'] != null && typeof e['traceback'] !== 'string') return false
+  if (e['stderrTail'] != null && typeof e['stderrTail'] !== 'string') return false
+  return true
+}
+
+function isWallTime(x: unknown): x is WallTime {
+  if (typeof x !== 'object' || x === null) return false
+  const t = x as Record<string, unknown>
+  return typeof t['seconds'] === 'number' && typeof t['unit'] === 'string'
+}
+
+function isFlameNode(x: unknown): x is FlameNode {
+  if (typeof x !== 'object' || x === null) return false
+  const f = x as Record<string, unknown>
+  return typeof f['name'] === 'string' && typeof f['value'] === 'number' && Array.isArray(f['children'])
+}
diff --git a/src/shared/ipc.ts b/src/shared/ipc.ts
new file mode 100644
index 0000000..16beac5
--- /dev/null
+++ b/src/shared/ipc.ts
@@ -0,0 +1,176 @@
+// IPC 错误规约。
+//
+// 历史问题：Electron 的 ipcMain.handle 在 reject 时只把 Error.message 跨 IPC 序列化过去，
+// 自定义属性（如 .kind / .details）会丢失。renderer 端拿到的就是一个裸 Error，分不清
+// "RunOptions 形状错了"和"代码太大"和"解释器不存在"。
+//
+// 方案：所有 main 进程抛出的错误统一用 IpcError（带 kind / message / details），
+// 把结构化信息 JSON-encode 进 message，渲染侧 readIpcError(err) 还原。
+//
+// 渲染侧调 readIpcError 而不是 instanceof 判断 —— IPC 反序列化会把 prototype
+// chain 砍掉，instanceof 不可靠，只能靠 message 前缀 + JSON parse。
+
+/**
+ * IPC 错误分类。渲染侧按 kind 决定文案 / 弹什么提示。
+ * - 增删 kind 时同步更新 IPC_ERROR_KINDS 数组（仅给文档/测试用）。
+ */
+export type IpcErrorKind =
+  /** RunOptions / IPC 入参形状不对（renderer 篡改或版本不匹配） */
+  | 'invalid_payload'
+  /** 解释器不在白名单（不是 python / python3 / python.exe） */
+  | 'interpreter_not_allowed'
+  /** 用户代码超过大小上限（防 DoS / 撑爆 tmp 盘） */
+  | 'payload_too_large'
+  /** engine/runner.py 不在祖先目录里（打包漏文件 / 应用不是从仓库根启动） */
+  | 'engine_not_found'
+  /** 探测解释器时 spawn / --version 失败 */
+  | 'interpreter_probe_failed'
+  /** 用户主动取消（profiler-service 内部分流到 AnalysisCancelledError，
+   *  不走 IpcError；但未来 renderer-side 的"自己取消"也能走这个 kind） */
+  | 'cancelled'
+  /** 打开系统终端失败（无可用终端模拟器 / macOS 自动化权限被拒 / spawn ENOENT 等） */
+  | 'terminal_open_failed'
+  /** 兜底：未分类错误，message 仍是原始 message */
+  | 'unknown'
+
+export const IPC_ERROR_KINDS: readonly IpcErrorKind[] = [
+  'invalid_payload',
+  'interpreter_not_allowed',
+  'payload_too_large',
+  'engine_not_found',
+  'interpreter_probe_failed',
+  'cancelled',
+  'terminal_open_failed',
+  'unknown'
+]
+
+/**
+ * Kind → i18n key 映射。渲染侧拿到 IpcError 时按 kind 取翻译文案，
+ * 把原本 hardcoded 在 main 进程的中文/英文 message 替换成翻译。
+ *
+ * 设计动机：main 进程抛错时只能塞一个固定 message，en-US 用户看到中文会很懵。
+ * 把 message 视为诊断原文（落日志 / stderr 排查用），UI 层按 kind + lang 重新组织。
+ *
+ * 兜底：未在表中的 kind（理论上只有 'unknown'）走 rawMessage —— 这种通常是上游
+ * 第三方 spawn error，机器可读反而比翻译更重要。
+ */
+export const IPC_ERROR_I18N_KEYS: Partial<Record<IpcErrorKind, string>> = {
+  invalid_payload: 'ipcError.invalidPayload',
+  interpreter_not_allowed: 'ipcError.interpreterNotAllowed',
+  payload_too_large: 'ipcError.payloadTooLarge',
+  engine_not_found: 'ipcError.engineNotFound',
+  interpreter_probe_failed: 'ipcError.interpreterProbeFailed',
+  cancelled: 'ipcError.cancelled',
+  terminal_open_failed: 'ipcError.terminalOpenFailed'
+}
+
+export interface IpcErrorShape {
+  kind: IpcErrorKind
+  message: string
+  /** 自由字段，渲染侧按需读（stderr 截尾 / 解释器路径 / 实际字节数 等） */
+  details?: Record<string, unknown>
+}
+
+/** 在 Error.message 里给 IpcError 加前缀，渲染侧靠这个前缀还原。
+ *  跨 IPC 序列化后 prototype 链会丢，但 message 字符串保留完整。 */
+export const IPC_ERROR_TAG = '[IPC_ERROR]'
+
+/**
+ * IPC 错误类。main 进程构造时用：
+ *   throw new IpcError('invalid_payload', 'RunOptions 形状校验失败', { bounds: {...} })
+ * 渲染侧用 readIpcError(err) 还原成结构化对象。
+ *
+ * **关于 .message**：Error.message 是 IPC 序列化的唯一载体（自定义属性会被丢），
+ * 所以必须保留 JSON 字符串供跨进程传输。人类可读的原文通过 readableMessage 取，
+ * 不要直接读 .message —— 拿到的是 JSON blob。
+ */
+export class IpcError extends Error {
+  readonly kind: IpcErrorKind
+  readonly details: Record<string, unknown> | undefined
+
+  constructor(kind: IpcErrorKind, message: string, details?: Record<string, unknown>) {
+    super(`${IPC_ERROR_TAG} ${JSON.stringify({ kind, message, details })}`)
+    this.name = 'IpcError'
+    this.kind = kind
+    this.details = details
+  }
+
+  /** 人类可读的消息原文（去掉 [IPC_ERROR] 前缀 + JSON 解析）。
+   *  跨进程 throw 后 renderer 拿到 Error.message 是 JSON blob，调这个拿到原文；
+   *  同进程内部直接构造（未跨 IPC）也用它，行为一致。 */
+  get readableMessage(): string {
+    if (!this.message.startsWith(IPC_ERROR_TAG + ' ')) return this.message
+    try {
+      const j = JSON.parse(this.message.slice(IPC_ERROR_TAG.length + 1)) as { message?: unknown }
+      return typeof j.message === 'string' ? j.message : this.message
+    } catch {
+      // 解析失败（理论上不会发生 — 构造时就 JSON.stringify 过的）
+      return this.message
+    }
+  }
+}
+
+/**
+ * 把任意 thrown value 还原成 IpcError。
+ * 优先级：
+ * 1. 已经是 IpcError 实例（main 进程内部调用，未跨 IPC）→ 直接返回
+ * 2. Error.message 以 [IPC_ERROR] 开头（跨 IPC 过来的还原路径）→ JSON parse 还原
+ * 3. 普通 Error（裸 message）→ 包成 kind='unknown'，保留原始 message
+ * 4. string / 其他 → kind='unknown'，message 取最佳猜测
+ */
+export function readIpcError(err: unknown): IpcError {
+  if (err instanceof IpcError) return err
+
+  if (err instanceof Error) {
+    const parsed = tryParseIpcMessage(err.message)
+    if (parsed) return new IpcError(parsed.kind, parsed.message, parsed.details)
+    return new IpcError('unknown', err.message || String(err))
+  }
+
+  if (typeof err === 'string') return new IpcError('unknown', err)
+
+  // IPC 桥偶发抛非 Error 对象（裸字符串 / 序列化对象）
+  try {
+    return new IpcError('unknown', JSON.stringify(err))
+  } catch {
+    return new IpcError('unknown', '未知错误')
+  }
+}
+
+function tryParseIpcMessage(msg: string): IpcErrorShape | null {
+  if (!msg.startsWith(IPC_ERROR_TAG + ' ')) return null
+  const json = msg.slice(IPC_ERROR_TAG.length + 1)
+  try {
+    const parsed: unknown = JSON.parse(json)
+    if (
+      typeof parsed === 'object' &&
+      parsed !== null &&
+      typeof (parsed as { kind?: unknown }).kind === 'string' &&
+      typeof (parsed as { message?: unknown }).message === 'string'
+    ) {
+      const p = parsed as { kind: unknown; message: unknown; details?: unknown }
+      // 即使 kind 不在白名单也返回结构 — kind 字段由 readIpcError 决定是否降级为 'unknown'，
+      // 但 message / details 仍可读；这条路径被设计用来"将来扩展了 kind 但忘了同步这里"
+      // 也不让用户看到 JSON blob。
+      const details =
+        typeof p.details === 'object' && p.details !== null && !Array.isArray(p.details)
+          ? (p.details as Record<string, unknown>)
+          : undefined
+      const kind = IPC_ERROR_KINDS.includes(p.kind as IpcErrorKind) ? (p.kind as IpcErrorKind) : 'unknown'
+      return { kind, message: p.message as string, details }
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 渲染侧快速判断：这个 throw 能不能解析为 IpcError？
+ * 比直接调 readIpcError 略快（构造得少），用在"只在是 IpcError 时才走特殊分支"的场景。
+ */
+export function isIpcError(err: unknown): err is IpcError {
+  if (err instanceof IpcError) return true
+  if (!(err instanceof Error)) return false
+  return tryParseIpcMessage(err.message) !== null
+}
diff --git a/tailwind.config.cjs b/tailwind.config.cjs
new file mode 100644
index 0000000..dd7d4a9
--- /dev/null
+++ b/tailwind.config.cjs
@@ -0,0 +1,110 @@
+/** @type {import('tailwindcss').Config} */
+// Linear-style dark theme. All values hand-picked to mirror Linear's actual UI.
+// All foreground colors validated >= AA (4.5:1) against their surface.
+//
+// 主题机制：所有 color token 走 CSS variables（`rgb(var(--xxx-rgb) / <alpha-value>)`），
+// `:root` 默认深色，`:root.light` 切换到浅色 —— 这样不动 109 处 `bg-bg` / `text-fg`
+// 工具类就能换肤。
+module.exports = {
+  darkMode: 'class',
+  content: ['./src/renderer/**/*.{html,ts,tsx}'],
+  theme: {
+    extend: {
+      // 系统字体栈（不依赖网络字体；CSP 默认 'self'，连 Google Fonts 也会被阻挡）。
+      // 桌面 Electron 应用一律 fallback 到本地已装字体，体验一致且离线可用。
+      fontFamily: {
+        sans: [
+          '-apple-system',
+          'BlinkMacSystemFont',
+          'Segoe UI Variable',
+          'Segoe UI',
+          'Microsoft YaHei',
+          'PingFang SC',
+          'sans-serif'
+        ],
+        mono: ['Cascadia Code', 'SF Mono', 'Menlo', 'Consolas', 'Courier New', 'monospace']
+      },
+      // 字号标度 —— 七档，按「实际渲染出来的样子」定，不是按理想值定。
+      //
+      // 改动前这份标度声明了 12/13/15/17/20/28 六档并注了「用户偏好：桌面端 >= 15px」，
+      // 但全代码库对它的引用数是 0：131 处全在写 text-[Npx] 硬编码，散落 14 个字号，
+      // 其中 12px/12.5px 各 51/25 处、13px/13.5px 各 24/3 处 —— 那 0.5px 的差不是
+      // 设计决策，是漂移。所以这次按现状收敛：把邻近的 0.5px 差合并成一档，
+      // 声明的档位就是正文 12–13px 的真实现状，不再声明一个没人用的 15px 正文。
+      //
+      // 故意不带 lineHeight：正文行高由 globals.css 的 body { line-height: 1.55 } 继承，
+      // 需要收紧的地方（大号数字）本来就显式写了 leading-tight / leading-none。
+      // 若在这里配上 lineHeight，那 89 处原本继承 1.55 的元素会被改成别的值 ——
+      // 这次 sweep 只想动字号，不想顺手改全局行高。
+      fontSize: {
+        '2xs': '11px', // 微型：kbd、uppercase 小标签、图例、表头
+        xs: '12px', // 密集 UI 与次要文字（最主力档，76 处）
+        sm: '13px', // 正文、数据（27 处）
+        base: '15px', // 强调正文：h1、卡片/分区标题、主按钮
+        lg: '18px', // 大号指标数字
+        xl: '20px', // h2
+        '2xl': '26px' // hero 数字
+      },
+      // Letter spacing tighter for display; matches Linear's headline treatment
+      letterSpacing: {
+        tight: '-0.01em',
+        tighter: '-0.015em'
+      },
+      // 所有 color 引用 `--xxx-rgb` 三元组，由 globals.css 定义（深 / 浅两套），
+      // `<alpha-value>` 让 Tailwind 自带的 `bg-bg/50`、`text-fg/70` 透明修饰继续可用。
+      colors: {
+        // Linear surfaces — near-black, hairline borders
+        bg: 'rgb(var(--bg-rgb) / <alpha-value>)',
+        surface: {
+          1: 'rgb(var(--surface-1-rgb) / <alpha-value>)',
+          2: 'rgb(var(--surface-2-rgb) / <alpha-value>)',
+          3: 'rgb(var(--surface-3-rgb) / <alpha-value>)'
+        },
+        border: {
+          DEFAULT: 'rgb(var(--border-rgb) / <alpha-value>)',
+          strong: 'rgb(var(--border-strong-rgb) / <alpha-value>)'
+        },
+        // Foreground — 三档都对 bg 通过 WCAG AA，且阶梯均匀
+        // secondary/muted 提亮之前用户反馈"过灰"——保持原档位以保住"次重要"语义。
+        fg: {
+          DEFAULT: 'rgb(var(--fg-rgb) / <alpha-value>)',
+          secondary: 'rgb(var(--fg-secondary-rgb) / <alpha-value>)',
+          muted: 'rgb(var(--fg-muted-rgb) / <alpha-value>)',
+          inverse: 'rgb(var(--fg-inverse-rgb) / <alpha-value>)',
+          // 在 accent 实心块上显示的文字（按钮文字等），固定白（亮色主题下也用白，因为 accent 是 Linear 紫）
+          'on-accent': 'rgb(var(--fg-on-accent-rgb) / <alpha-value>)'
+        },
+        // Linear purple — the single accent（亮色主题下保持同色，仅 hover 加深）
+        accent: {
+          DEFAULT: 'rgb(var(--accent-rgb) / <alpha-value>)',
+          hover: 'rgb(var(--accent-hover-rgb) / <alpha-value>)',
+          soft: 'var(--accent-soft)',
+          ring: 'var(--accent-ring)'
+        },
+        // Severity — reserved, never decorative
+        sev: {
+          high: 'rgb(var(--sev-high-rgb) / <alpha-value>)',
+          med: 'rgb(var(--sev-med-rgb) / <alpha-value>)',
+          low: 'rgb(var(--sev-low-rgb) / <alpha-value>)'
+        },
+        // 警告色（原本 MinimalRunConfig 用 Tailwind 默认 amber）。亮色主题下需要更深
+        // 才能在白底上 AA —— 收口到 token 层。
+        warning: 'rgb(var(--warning-rgb) / <alpha-value>)'
+      },
+      // Subtle, restrained radius — Linear uses 6-8px max
+      borderRadius: {
+        sm: '4px',
+        DEFAULT: '6px',
+        md: '8px',
+        lg: '10px'
+      },
+      // Hairline borders, no shadows on cards
+      boxShadow: {
+        // Used sparingly: only for the floating detail panel & dropdown
+        pop: '0 0 0 1px rgba(255,255,255,0.04), 0 8px 24px rgba(0,0,0,0.32)',
+        ring: '0 0 0 1px #5E6AD2'
+      }
+    }
+  },
+  plugins: []
+}
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 0000000..02057e6
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2021", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "types": ["node", "vitest/globals", "@testing-library/jest-dom"],
+    "baseUrl": ".",
+    "paths": {
+      "@shared/*": ["src/shared/*"],
+      "@renderer/*": ["src/renderer/src/*"]
+    }
+  },
+  "include": ["src", "e2e", "*.config.ts", "vitest.setup.ts"]
+}
diff --git a/vitest.config.ts b/vitest.config.ts
new file mode 100644
index 0000000..62ac703
--- /dev/null
+++ b/vitest.config.ts
@@ -0,0 +1,26 @@
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+import { resolve } from 'path'
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@shared': resolve(__dirname, 'src/shared'),
+      '@renderer': resolve(__dirname, 'src/renderer/src')
+    }
+  },
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./vitest.setup.ts'],
+    include: ['src/**/*.{test,spec}.{ts,tsx}'],
+    exclude: ['e2e/**', 'node_modules/**'],
+    // 在中文路径 + 并行 worker + jsdom 下,Vite 的 NewSpace 在默认堆下
+    // 会爆(FATAL ERROR: NewSpace::EnsureCurrentCapacity)。给 worker 加大堆
+    // 是最稳的修法。设 4GB 给 worker 留 1GB 给主进程,够 7 个测用例通过。
+    env: {
+      NODE_OPTIONS: '--max-old-space-size=4096'
+    }
+  }
+})
diff --git a/vitest.setup.ts b/vitest.setup.ts
new file mode 100644
index 0000000..c93dc68
--- /dev/null
+++ b/vitest.setup.ts
@@ -0,0 +1,40 @@
+import '@testing-library/jest-dom'
+// RTL v13+ 默认会注册 afterEach 清理，但在 vitest + jsdom 下偶尔 cleanup 没跑，
+// 导致用例之间的 DOM 残留（出现多个「粘贴代码 → 运行 → 看热点与可优化点」之类）。
+// 显式 register 一次保险。
+import { afterEach, vi } from 'vitest'
+import { cleanup } from '@testing-library/react'
+
+// jsdom 不带 ResizeObserver,App 用 useEffect 注册它来跟踪主区尺寸变化。
+// 给一个最小的 noop stub —— 我们的测试只关心渲染产物,不真关心尺寸。
+if (typeof globalThis.ResizeObserver === 'undefined') {
+  globalThis.ResizeObserver = class {
+    observe(): void {}
+    unobserve(): void {}
+    disconnect(): void {}
+  } as unknown as typeof ResizeObserver
+}
+
+// jsdom 24 仍未实现 PointerEvent; fireEvent.pointerDown 因此退化成裸 Event,button
+// / clientX / pointerId 全丢失 —— Splitter 这类用 Pointer Events 的组件测不出来。
+// 给一个最小 polyfill:继承 MouseEvent(jsdom 已支持)补 pointerId / pointerType,
+// 让 RTL 派发的 PointerEventInit(button / clientX / pointerId / pointerType)真正生效。
+if (typeof globalThis.PointerEvent === 'undefined') {
+  class PointerEventPolyfill extends MouseEvent {
+    public readonly pointerId: number
+    public readonly pointerType: string
+    public readonly isPrimary: boolean
+    constructor(type: string, params: PointerEventInit = {}) {
+      super(type, params)
+      this.pointerId = params.pointerId ?? 0
+      this.pointerType = params.pointerType ?? ''
+      this.isPrimary = params.isPrimary ?? true
+    }
+  }
+  globalThis.PointerEvent = PointerEventPolyfill as unknown as typeof PointerEvent
+}
+
+afterEach(() => {
+  cleanup()
+  vi.restoreAllMocks()
+})