From f8f1a98e1be97b06dcd7ff773fe951231e0539f7 Mon Sep 17 00:00:00 2001
From: jisongniu <529058747@qq.com>
Date: Sat, 11 Jul 2026 21:08:08 +0800
Subject: [PATCH 1/3] =?UTF-8?q?feat(settings):=20=E8=AE=BE=E7=BD=AE?=
 =?UTF-8?q?=E9=A1=B9=E6=82=AC=E5=81=9C=E6=98=BE=E7=A4=BA=E5=8A=9F=E8=83=BD?=
 =?UTF-8?q?=E8=AF=B4=E6=98=8E=EF=BC=8C=E9=99=8D=E4=BD=8E=20Less=20Computer?=
 =?UTF-8?q?=20/=20=E5=BD=95=E9=9F=B3=E8=83=B6=E5=9B=8A=E7=AD=89=E7=9A=84?=
 =?UTF-8?q?=E7=90=86=E8=A7=A3=E9=97=A8=E6=A7=9B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

页面瘦身后设置页描述小字全部隐藏，Less Computer、录音胶囊这类光看名字
猜不出用途的功能只剩一个标签，理解成本高。本次把已有的 desc 文案以
Tooltip 形式挂回标签文字上：

- Tooltip 新增 wrap 模式，整句说明允许换行（默认 nowrap 不变）
- SettingRow 的 desc 恢复生效：悬停标签文字弹出说明，虚线下划线 +
  help 光标做「可悬停」暗示，布局保持紧凑
- SectionTitle 新增 hint，Less Computer / Claude 控制台 / 录音与输入
  三个板块标题接上已有的 desc 文案
- 录音与输入里录音胶囊 / 录音方式 / 首选麦克风 / 录音时静音 /
  插入剪贴板等行补传现成的 i18n desc

文案全部复用现有 i18n key，五种语言无需新增翻译。
---
 openless-all/app/src/components/Tooltip.tsx   | 19 +++++-
 .../pages/settings/ClaudeConsoleSection.tsx   |  2 +-
 .../src/pages/settings/CodingAgentSection.tsx |  2 +-
 .../pages/settings/RecordingInputSection.tsx  | 22 +++---
 .../app/src/pages/settings/shared.tsx         | 68 +++++++++++++------
 5 files changed, 75 insertions(+), 38 deletions(-)

diff --git a/openless-all/app/src/components/Tooltip.tsx b/openless-all/app/src/components/Tooltip.tsx
index b4e44ea7..fb5e2ae4 100644
--- a/openless-all/app/src/components/Tooltip.tsx
+++ b/openless-all/app/src/components/Tooltip.tsx
@@ -21,10 +21,12 @@ interface TooltipProps {
   content: ReactNode;
   /** 提示出现在锚点的哪一侧，默认 right（适合左侧栏菜单）。 */
   placement?: 'right' | 'top' | 'bottom';
+  /** 整句说明类提示允许换行；默认 nowrap 适合菜单名等短文案。 */
+  wrap?: boolean;
   children: ReactNode;
 }
 
-export function Tooltip({ content, placement = 'right', children }: TooltipProps) {
+export function Tooltip({ content, placement = 'right', wrap = false, children }: TooltipProps) {
   const anchorRef = useRef<HTMLSpanElement>(null);
   const timerRef = useRef<number | null>(null);
   const [pos, setPos] = useState<{ x: number; y: number } | null>(null);
@@ -81,7 +83,14 @@ export function Tooltip({ content, placement = 'right', children }: TooltipProps
       {children}
       {pos != null &&
         createPortal(
-          <span role="tooltip" style={{ ...bubbleStyle, ...placementStyle(placement, pos) }}>
+          <span
+            role="tooltip"
+            style={{
+              ...bubbleStyle,
+              ...(wrap ? wrapBubbleStyle : null),
+              ...placementStyle(placement, pos),
+            }}
+          >
             {content}
           </span>,
           document.body,
@@ -120,6 +129,12 @@ const bubbleStyle: CSSProperties = {
   animation: 'ol-tooltip-in 0.12s ease-out both',
 };
 
+const wrapBubbleStyle: CSSProperties = {
+  whiteSpace: 'normal',
+  width: 'max-content',
+  maxWidth: 280,
+};
+
 const TOOLTIP_KEYFRAMES = `
 @keyframes ol-tooltip-in {
   from { opacity: 0; scale: .96; }
diff --git a/openless-all/app/src/pages/settings/ClaudeConsoleSection.tsx b/openless-all/app/src/pages/settings/ClaudeConsoleSection.tsx
index ee0ef786..15ac74c3 100644
--- a/openless-all/app/src/pages/settings/ClaudeConsoleSection.tsx
+++ b/openless-all/app/src/pages/settings/ClaudeConsoleSection.tsx
@@ -154,7 +154,7 @@ export function ClaudeConsoleSection() {
         onClick={() => setExpanded(v => !v)}
         style={{ all: 'unset', cursor: 'pointer', display: 'flex', alignItems: 'center', gap: 8, width: '100%' }}
       >
-        <SectionTitle>{t('settings.codingConsole.title')}</SectionTitle>
+        <SectionTitle hint={t('settings.codingConsole.desc')}>{t('settings.codingConsole.title')}</SectionTitle>
         <span style={{ marginLeft: 'auto', fontSize: 12, color: 'var(--ol-ink-4)' }}>
           {expanded ? `${t('common.hide')} ▴` : `${t('common.show')} ▾`}
         </span>
diff --git a/openless-all/app/src/pages/settings/CodingAgentSection.tsx b/openless-all/app/src/pages/settings/CodingAgentSection.tsx
index d54e83ce..0414a04e 100644
--- a/openless-all/app/src/pages/settings/CodingAgentSection.tsx
+++ b/openless-all/app/src/pages/settings/CodingAgentSection.tsx
@@ -55,7 +55,7 @@ export function CodingAgentSection() {
 
   return (
     <Card>
-      <SectionTitle>{t('settings.codingAgent.title')}</SectionTitle>
+      <SectionTitle hint={t('settings.codingAgent.desc')}>{t('settings.codingAgent.title')}</SectionTitle>
       <SectionDesc>{t('settings.codingAgent.desc')}</SectionDesc>
 
       <SettingRow label={t('settings.codingAgent.enable')} desc={t('settings.codingAgent.hotkeyHint')}>
diff --git a/openless-all/app/src/pages/settings/RecordingInputSection.tsx b/openless-all/app/src/pages/settings/RecordingInputSection.tsx
index e6281eb1..af909536 100644
--- a/openless-all/app/src/pages/settings/RecordingInputSection.tsx
+++ b/openless-all/app/src/pages/settings/RecordingInputSection.tsx
@@ -26,7 +26,7 @@ import type {
 import { useHotkeySettings } from '../../state/HotkeySettingsContext';
 import { SelectLite } from '../../components/ui/SelectLite';
 import { Card, Collapsible } from '../_atoms';
-import { SettingRow, Toggle, inputStyle, segmentedTrackStyle } from './shared';
+import { SectionTitle, SettingRow, Toggle, inputStyle, segmentedTrackStyle } from './shared';
 import { MicrophoneSelect } from './MicrophoneSelect';
 import { detectOS } from '../../components/WindowChrome';
 
@@ -182,11 +182,9 @@ export function RecordingInputSection() {
   return (
     <>
       <Card>
-        <div style={{ marginBottom: 6 }}>
-          <div style={{ fontSize: 14, fontWeight: 600, color: 'var(--ol-ink)', letterSpacing: '-0.01em' }}>
-            {t('settings.recording.title')}
-          </div>
-        </div>
+        <SectionTitle hint={t('settings.recording.desc')}>
+          {t('settings.recording.title')}
+        </SectionTitle>
         {isHotkeyModeMigrationNoticeActive() && showDesktopHotkey && (
           <div
             style={{
@@ -220,7 +218,7 @@ export function RecordingInputSection() {
         </SettingRow>
         )}
         {showDesktopHotkey && (
-        <SettingRow label={t('settings.recording.modeLabel')}>
+        <SettingRow label={t('settings.recording.modeLabel')} desc={t('settings.recording.modeDesc')}>
           <div style={segmentedTrackStyle}>
             {choices.map(([v, l]) => (
               <button
@@ -242,7 +240,7 @@ export function RecordingInputSection() {
           </div>
         </SettingRow>
         )}
-        <SettingRow label={t('settings.recording.microphoneLabel')}>
+        <SettingRow label={t('settings.recording.microphoneLabel')} desc={t('settings.recording.microphoneDesc')}>
           <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
             <MicrophoneSelect
               devices={microphoneDevices}
@@ -258,11 +256,11 @@ export function RecordingInputSection() {
           </div>
         </SettingRow>
         {os !== 'linux' && !isAndroid && (
-        <SettingRow label={t('settings.recording.capsuleLabel')}>
+        <SettingRow label={t('settings.recording.capsuleLabel')} desc={t('settings.recording.capsuleDesc')}>
           <Toggle on={prefs.showCapsule} onToggle={onShowCapsuleChange} />
         </SettingRow>
         )}
-        <SettingRow label={t('settings.recording.muteDuringRecordingLabel')}>
+        <SettingRow label={t('settings.recording.muteDuringRecordingLabel')} desc={t('settings.recording.muteDuringRecordingDesc')}>
           <Toggle on={prefs.muteDuringRecording} onToggle={onMuteDuringRecordingChange} />
         </SettingRow>
         <SettingRow
@@ -304,11 +302,11 @@ export function RecordingInputSection() {
       {/* ─── 插入与剪贴板（折叠，仅 macOS / Windows） ──────────────── */}
       {showDesktopInsert && (
       <Collapsible title={t('settings.recording.insertGroupTitle')}>
-        <SettingRow label={t('settings.recording.restoreClipboardLabel')}>
+        <SettingRow label={t('settings.recording.restoreClipboardLabel')} desc={t('settings.recording.restoreClipboardDesc')}>
           <Toggle on={prefs.restoreClipboardAfterPaste} onToggle={onRestoreClipboardChange} />
         </SettingRow>
         {capability.adapter !== 'macEventTap' && (
-          <SettingRow label={t('settings.recording.pasteShortcutLabel')}>
+          <SettingRow label={t('settings.recording.pasteShortcutLabel')} desc={t('settings.recording.pasteShortcutDesc')}>
             <SelectLite
               value={prefs.pasteShortcut}
               onChange={next => onPasteShortcutChange(next as PasteShortcut)}
diff --git a/openless-all/app/src/pages/settings/shared.tsx b/openless-all/app/src/pages/settings/shared.tsx
index f58b4c63..29961993 100644
--- a/openless-all/app/src/pages/settings/shared.tsx
+++ b/openless-all/app/src/pages/settings/shared.tsx
@@ -2,27 +2,44 @@
 // AsrPresetId 也放在这里，让 settings/ 下各 section 都从同一处来源拿。
 
 import type { CSSProperties, ReactNode } from "react"
+import { Tooltip } from "../../components/Tooltip"
 import { useMobileLayout } from "../../lib/useMobileLayout"
 
+// 带说明的文字统一加虚线下划线 + help 光标，暗示「悬停可看解释」。
+const hintableTextStyle: CSSProperties = {
+    cursor: "help",
+    textDecoration: "underline dotted",
+    textDecorationColor: "var(--ol-ink-4)",
+    textUnderlineOffset: 3,
+}
+
 export function SectionTitle({
     children,
+    hint,
     style,
 }: {
     children: ReactNode
+    /** 悬停在标题文字上时的功能说明，给 Less Computer 这类光看名字猜不出用途的板块。 */
+    hint?: string
     style?: CSSProperties
 }) {
+    const titleStyle: CSSProperties = {
+        fontSize: 14,
+        fontWeight: 600,
+        color: "var(--ol-ink)",
+        marginBottom: 6,
+        letterSpacing: "-0.01em",
+        ...style,
+    }
+    if (!hint) {
+        return <div style={titleStyle}>{children}</div>
+    }
     return (
-        <div
-            style={{
-                fontSize: 14,
-                fontWeight: 600,
-                color: "var(--ol-ink)",
-                marginBottom: 6,
-                letterSpacing: "-0.01em",
-                ...style,
-            }}
-        >
-            {children}
+        // display:flex 让 Tooltip 的锚点收缩到标题文字本身，提示贴着文字弹出。
+        <div style={{ ...titleStyle, display: "flex" }}>
+            <Tooltip content={hint} wrap placement="bottom">
+                <span style={hintableTextStyle}>{children}</span>
+            </Tooltip>
         </div>
     )
 }
@@ -42,13 +59,21 @@ interface SettingRowProps {
     controlWidth?: number | string
 }
 
-// 页面瘦身：不再渲染每行的描述小字（desc 仍保留在 props 里，调用点无需改、便于恢复）。
+// 页面瘦身后描述小字不再常驻展示；desc 改为悬停在标签文字上时以 Tooltip 弹出，
+// 布局保持紧凑的同时不牺牲可理解性。
 export function SettingRow({
     label,
+    desc,
     children,
     controlWidth,
 }: SettingRowProps) {
     const mobile = useMobileLayout()
+    const labelStyle: CSSProperties = {
+        fontSize: 13,
+        fontWeight: 500,
+        color: "var(--ol-ink)",
+        minWidth: 0,
+    }
     return (
         <div
             style={{
@@ -60,16 +85,15 @@ export function SettingRow({
                 alignItems: "center",
             }}
         >
-            <div style={{ minWidth: 0, alignSelf: "center" }}>
-                <div
-                    style={{
-                        fontSize: 13,
-                        fontWeight: 500,
-                        color: "var(--ol-ink)",
-                    }}
-                >
-                    {label}
-                </div>
+            {/* display:flex 让 Tooltip 锚点收缩到文字宽度，提示贴着文字弹出。 */}
+            <div style={{ minWidth: 0, alignSelf: "center", display: "flex" }}>
+                {desc ? (
+                    <Tooltip content={desc} wrap placement="bottom">
+                        <div style={{ ...labelStyle, ...hintableTextStyle }}>{label}</div>
+                    </Tooltip>
+                ) : (
+                    <div style={labelStyle}>{label}</div>
+                )}
             </div>
             <div
                 style={{

From 85e113754b3625a6eace8017cb67d7aa777bb1c1 Mon Sep 17 00:00:00 2001
From: jisongniu <529058747@qq.com>
Date: Sun, 12 Jul 2026 18:14:25 +0800
Subject: [PATCH 2/3] =?UTF-8?q?feat(settings):=20Less=20Computer=20?=
 =?UTF-8?q?=E5=BF=AB=E6=8D=B7=E9=94=AE=E6=8F=90=E7=A4=BA=E8=A1=A5=E4=B8=80?=
 =?UTF-8?q?=E5=8F=A5=E3=80=8C=E5=8A=9F=E8=83=BD=E8=AF=B4=E6=98=8E=E5=8F=82?=
 =?UTF-8?q?=E8=A7=81=E9=AB=98=E7=BA=A7=E8=AE=BE=E7=BD=AE=E9=A1=B5=E3=80=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

通用页 Less Computer 那行原提示只讲快捷键用法，补一句指向「高级」设置页
的功能说明入口，降低理解门槛。5 语言同步。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 openless-all/app/src/i18n/en.ts    | 2 +-
 openless-all/app/src/i18n/ja.ts    | 2 +-
 openless-all/app/src/i18n/ko.ts    | 2 +-
 openless-all/app/src/i18n/zh-CN.ts | 2 +-
 openless-all/app/src/i18n/zh-TW.ts | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/openless-all/app/src/i18n/en.ts b/openless-all/app/src/i18n/en.ts
index 200bd48f..b071f3ae 100644
--- a/openless-all/app/src/i18n/en.ts
+++ b/openless-all/app/src/i18n/en.ts
@@ -634,7 +634,7 @@ export const en: typeof zhCN = {
       comingSoonNote: 'Config is saved now; hotkey triggering and the execution flow land in a later version.',
       hotkeyHint: 'When enabled, hold the shortcut below to talk; release it and Claude shows the result in the capsule.',
       voiceHotkey: 'Hold-to-talk key',
-      voiceHotkeyDesc: 'Hold to talk, release to run. Supports Ctrl/Option/Fn single keys.',
+      voiceHotkeyDesc: 'Hold to talk, release to run. Supports Ctrl/Option/Fn single keys. See the Advanced settings page for what it does.',
       provider: 'Agent backend',
       opencodeReady: 'OpenCode v{{version}} detected.',
       opencodeMissing: 'opencode command not found. Install it (npm i -g opencode-ai) and sign in with opencode auth login before use.',
diff --git a/openless-all/app/src/i18n/ja.ts b/openless-all/app/src/i18n/ja.ts
index 77142167..722a64f8 100644
--- a/openless-all/app/src/i18n/ja.ts
+++ b/openless-all/app/src/i18n/ja.ts
@@ -636,7 +636,7 @@ export const ja: typeof zhCN = {
       comingSoonNote: '設定はすぐ保存されます。ホットキー起動と実行フローは今後のバージョンで対応。',
       hotkeyHint: '有効にすると、下のショートカットを押しながら話し、離すと Claude の結果がカプセルに表示されます。',
       voiceHotkey: '押しながら話すキー',
-      voiceHotkeyDesc: '押して話す、離して実行。Ctrl/Option/Fn などの単キー対応。',
+      voiceHotkeyDesc: '押して話す、離して実行。Ctrl/Option/Fn などの単キー対応。機能の説明は「詳細」設定ページを参照。',
       provider: 'Agent バックエンド',
       opencodeReady: 'OpenCode v{{version}} を検出しました。',
       opencodeMissing: 'opencode コマンドが見つかりません。先にインストール（npm i -g opencode-ai）して opencode auth login でログインしてください。',
diff --git a/openless-all/app/src/i18n/ko.ts b/openless-all/app/src/i18n/ko.ts
index 699966d4..7d6b04e6 100644
--- a/openless-all/app/src/i18n/ko.ts
+++ b/openless-all/app/src/i18n/ko.ts
@@ -636,7 +636,7 @@ export const ko: typeof zhCN = {
       comingSoonNote: '설정은 즉시 저장됩니다. 단축키 트리거와 실행 흐름은 이후 버전에서 제공됩니다.',
       hotkeyHint: '켜면 아래 단축키를 누른 채 말하고, 놓으면 Claude 결과가 캡슐에 표시됩니다.',
       voiceHotkey: '누르고 말하기 키',
-      voiceHotkeyDesc: '누르고 말하고 놓으면 실행. Ctrl/Option/Fn 단일 키 지원.',
+      voiceHotkeyDesc: '누르고 말하고 놓으면 실행. Ctrl/Option/Fn 단일 키 지원. 기능 설명은 「고급」 설정 페이지 참조.',
       provider: 'Agent 백엔드',
       opencodeReady: 'OpenCode v{{version}} 감지됨.',
       opencodeMissing: 'opencode 명령을 찾을 수 없습니다. 먼저 설치(npm i -g opencode-ai)하고 opencode auth login으로 로그인하세요.',
diff --git a/openless-all/app/src/i18n/zh-CN.ts b/openless-all/app/src/i18n/zh-CN.ts
index 04b5a8df..3e7226c1 100644
--- a/openless-all/app/src/i18n/zh-CN.ts
+++ b/openless-all/app/src/i18n/zh-CN.ts
@@ -632,7 +632,7 @@ export const zhCN = {
       comingSoonNote: '配置即时保存；热键触发与执行链路随后续版本生效。',
       hotkeyHint: '开启后，按住下方快捷键说话，松开后 Claude 处理并把结果显示在胶囊里。',
       voiceHotkey: '按住说话键',
-      voiceHotkeyDesc: '按住说话、松开执行。支持 Ctrl/Option/Fn 等单键。',
+      voiceHotkeyDesc: '按住说话、松开执行。支持 Ctrl/Option/Fn 等单键。功能说明参见「高级」设置页。',
       provider: 'Agent 后端',
       opencodeReady: '已检测到 OpenCode v{{version}}。',
       opencodeMissing: '未检测到 opencode 命令。请先安装（npm i -g opencode-ai）并用 opencode auth login 登录后再使用。',
diff --git a/openless-all/app/src/i18n/zh-TW.ts b/openless-all/app/src/i18n/zh-TW.ts
index 0e316d29..fede84e2 100644
--- a/openless-all/app/src/i18n/zh-TW.ts
+++ b/openless-all/app/src/i18n/zh-TW.ts
@@ -634,7 +634,7 @@ export const zhTW: typeof zhCN = {
       comingSoonNote: '設定即時儲存；熱鍵觸發與執行鏈路隨後續版本生效。',
       hotkeyHint: '開啟後，按住下方快捷鍵說話，放開後 Claude 處理並把結果顯示在膠囊裡。',
       voiceHotkey: '按住說話鍵',
-      voiceHotkeyDesc: '按住說話、放開執行。支援 Ctrl/Option/Fn 等單鍵。',
+      voiceHotkeyDesc: '按住說話、放開執行。支援 Ctrl/Option/Fn 等單鍵。功能說明參見「進階」設定頁。',
       provider: 'Agent 後端',
       opencodeReady: '已偵測到 OpenCode v{{version}}。',
       opencodeMissing: '未偵測到 opencode 指令。請先安裝（npm i -g opencode-ai）並用 opencode auth login 登入後再使用。',

From 9e2462ecf74824d78ff728593da64a416832c7cb Mon Sep 17 00:00:00 2001
From: Chris233 <h-chris233@outlook.com>
Date: Sun, 12 Jul 2026 21:32:18 +0800
Subject: [PATCH 3/3] fix(settings): make hints accessible and viewport-safe

---
 openless-all/app/src/components/Tooltip.tsx   | 238 ++++++++++++++----
 .../pages/settings/ClaudeConsoleSection.tsx   |   9 +-
 .../app/src/pages/settings/shared.tsx         |   6 +-
 3 files changed, 200 insertions(+), 53 deletions(-)

diff --git a/openless-all/app/src/components/Tooltip.tsx b/openless-all/app/src/components/Tooltip.tsx
index fb5e2ae4..c5729707 100644
--- a/openless-all/app/src/components/Tooltip.tsx
+++ b/openless-all/app/src/components/Tooltip.tsx
@@ -1,94 +1,223 @@
-// Tooltip.tsx — 统一的悬浮提示，macOS 菜单式「预热」行为：
-//
-//   - 首次 hover：延迟 600ms 才出现 —— 日常操作扫过按钮不触发一堆提示；
-//   - 预热窗口内（某个 tooltip 正显示、或刚关闭 <300ms）再 hover 相邻目标：
-//     0 延迟即时切换 —— 想连续查看各菜单功能说明时不用每个都等。
-//
-// 预热状态是模块级共享的，所有 Tooltip 实例天然联动。渲染用 portal + fixed
-// 定位，不受祖先 overflow / transform / backdrop-filter 包含块影响。
-
-import { useEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+/**
+ * 统一的悬浮提示，支持 hover、键盘 focus 和触摸触发。
+ *
+ * Tooltip 使用 portal + fixed 定位，不受父级 overflow、transform 或 backdrop-filter 影响。
+ */
+import {
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type PointerEvent,
+  type ReactNode,
+} from 'react';
 import { createPortal } from 'react-dom';
 
 /** 首次 hover 到出现的延迟。 */
 const WARM_DELAY_MS = 600;
-/** tooltip 关闭后预热状态的存续窗口：这段时间内 hover 相邻目标即时显示。 */
+/** tooltip 关闭后的预热窗口。 */
 const WARM_LINGER_MS = 300;
 
 let warmUntil = 0;
 
 interface TooltipProps {
   content: ReactNode;
-  /** 提示出现在锚点的哪一侧，默认 right（适合左侧栏菜单）。 */
+  /** 提示出现在锚点的哪一侧，默认 right。 */
   placement?: 'right' | 'top' | 'bottom';
-  /** 整句说明类提示允许换行；默认 nowrap 适合菜单名等短文案。 */
+  /** 整句说明允许换行，默认 nowrap。 */
   wrap?: boolean;
+  /** 让标签本身成为可聚焦的 Tooltip 触发器。 */
+  focusable?: boolean;
   children: ReactNode;
 }
 
-export function Tooltip({ content, placement = 'right', wrap = false, children }: TooltipProps) {
+type TooltipPlacement = NonNullable<TooltipProps['placement']>;
+
+interface AnchorRect {
+  left: number;
+  right: number;
+  top: number;
+  bottom: number;
+  width: number;
+  height: number;
+}
+
+interface TooltipPosition {
+  anchor: AnchorRect;
+  placement: TooltipPlacement;
+  offsetX: number;
+  offsetY: number;
+}
+
+export function Tooltip({
+  content,
+  placement = 'right',
+  wrap = false,
+  focusable = false,
+  children,
+}: TooltipProps) {
   const anchorRef = useRef<HTMLSpanElement>(null);
+  const bubbleRef = useRef<HTMLSpanElement>(null);
   const timerRef = useRef<number | null>(null);
-  const [pos, setPos] = useState<{ x: number; y: number } | null>(null);
+  const hoveredRef = useRef(false);
+  const focusedRef = useRef(false);
+  const tooltipId = useId();
+  const [pos, setPos] = useState<TooltipPosition | null>(null);
 
-  const show = () => {
+  const readAnchorRect = (): AnchorRect | null => {
     const anchor = anchorRef.current;
-    if (!anchor) return;
+    if (!anchor) return null;
     const rect = anchor.getBoundingClientRect();
-    if (placement === 'right') {
-      setPos({ x: rect.right + 10, y: rect.top + rect.height / 2 });
-    } else if (placement === 'top') {
-      setPos({ x: rect.left + rect.width / 2, y: rect.top - 8 });
-    } else {
-      setPos({ x: rect.left + rect.width / 2, y: rect.bottom + 8 });
+    return {
+      left: rect.left,
+      right: rect.right,
+      top: rect.top,
+      bottom: rect.bottom,
+      width: rect.width,
+      height: rect.height,
+    };
+  };
+
+  const show = () => {
+    const anchor = readAnchorRect();
+    if (!anchor) return;
+    setPos({ anchor, placement, offsetX: 0, offsetY: 0 });
+  };
+
+  const clearTimer = () => {
+    if (timerRef.current == null) return;
+    window.clearTimeout(timerRef.current);
+    timerRef.current = null;
+  };
+
+  const scheduleShow = () => {
+    clearTimer();
+    if (Date.now() < warmUntil) {
+      show();
+      return;
     }
+    timerRef.current = window.setTimeout(() => {
+      timerRef.current = null;
+      show();
+    }, WARM_DELAY_MS);
   };
 
   const hide = () => {
-    if (timerRef.current != null) {
-      window.clearTimeout(timerRef.current);
-      timerRef.current = null;
-    }
+    clearTimer();
     setPos(prev => {
       if (prev) warmUntil = Date.now() + WARM_LINGER_MS;
       return null;
     });
   };
 
+  const hideIfInactive = () => {
+    if (!hoveredRef.current && !focusedRef.current) hide();
+  };
+
   const onEnter = () => {
-    if (Date.now() < warmUntil) {
+    hoveredRef.current = true;
+    scheduleShow();
+  };
+
+  const onLeave = () => {
+    hoveredRef.current = false;
+    hideIfInactive();
+  };
+
+  const onFocus = () => {
+    focusedRef.current = true;
+    clearTimer();
+    show();
+  };
+
+  const onBlur = () => {
+    focusedRef.current = false;
+    hideIfInactive();
+  };
+
+  const onPointerDown = (event: PointerEvent<HTMLSpanElement>) => {
+    if (event.pointerType === 'touch') {
+      clearTimer();
       show();
       return;
     }
-    timerRef.current = window.setTimeout(show, WARM_DELAY_MS);
+    hide();
   };
 
+  useLayoutEffect(() => {
+    const bubble = bubbleRef.current;
+    if (!bubble || !pos) return;
+
+    const margin = 8;
+    const bubbleRect = bubble.getBoundingClientRect();
+    let nextPlacement = pos.placement;
+
+    if (
+      pos.placement === 'bottom'
+      && bubbleRect.bottom > window.innerHeight - margin
+      && pos.anchor.top - 8 - bubbleRect.height >= margin
+    ) {
+      nextPlacement = 'top';
+    } else if (
+      pos.placement === 'top'
+      && bubbleRect.top < margin
+      && pos.anchor.bottom + 8 + bubbleRect.height <= window.innerHeight - margin
+    ) {
+      nextPlacement = 'bottom';
+    }
+
+    if (nextPlacement !== pos.placement) {
+      setPos({ ...pos, placement: nextPlacement, offsetX: 0, offsetY: 0 });
+      return;
+    }
+
+    const offsetX = Math.max(margin - bubbleRect.left, 0)
+      - Math.max(bubbleRect.right - (window.innerWidth - margin), 0);
+    const offsetY = Math.max(margin - bubbleRect.top, 0)
+      - Math.max(bubbleRect.bottom - (window.innerHeight - margin), 0);
+
+    if (Math.abs(offsetX) > 0.5 || Math.abs(offsetY) > 0.5) {
+      setPos({
+        ...pos,
+        offsetX: pos.offsetX + offsetX,
+        offsetY: pos.offsetY + offsetY,
+      });
+    }
+  }, [pos]);
+
   useEffect(
     () => () => {
-      if (timerRef.current != null) window.clearTimeout(timerRef.current);
+      clearTimer();
     },
     [],
   );
 
   return (
-    // display:grid 单格包装：span 尺寸与子元素一致（display:contents 的 rect 恒为 0
-    // 无法定位），又不给 flex/grid 父容器引入额外的布局盒差异。
+    // display:grid 保持锚点尺寸与子元素一致，同时避免引入额外布局差异。
     <span
       ref={anchorRef}
       onMouseEnter={onEnter}
-      onMouseLeave={hide}
-      onMouseDown={hide}
+      onMouseLeave={onLeave}
+      onFocus={onFocus}
+      onBlur={onBlur}
+      onPointerDown={onPointerDown}
+      tabIndex={focusable ? 0 : undefined}
+      aria-describedby={focusable && pos != null ? tooltipId : undefined}
       style={{ display: 'grid' }}
     >
       {children}
       {pos != null &&
         createPortal(
           <span
+            ref={bubbleRef}
+            id={tooltipId}
             role="tooltip"
             style={{
               ...bubbleStyle,
               ...(wrap ? wrapBubbleStyle : null),
-              ...placementStyle(placement, pos),
+              ...placementStyle(pos),
             }}
           >
             {content}
@@ -99,20 +228,33 @@ export function Tooltip({ content, placement = 'right', wrap = false, children }
   );
 }
 
-function placementStyle(placement: 'right' | 'top' | 'bottom', pos: { x: number; y: number }): CSSProperties {
+function placementStyle(pos: TooltipPosition): CSSProperties {
+  const { anchor, placement, offsetX, offsetY } = pos;
   if (placement === 'right') {
-    return { left: pos.x, top: pos.y, transform: 'translateY(-50%)' };
+    return {
+      left: anchor.right + 10 + offsetX,
+      top: anchor.top + anchor.height / 2 + offsetY,
+      transform: 'translateY(-50%)',
+    };
   }
   if (placement === 'top') {
-    return { left: pos.x, top: pos.y, transform: 'translate(-50%, -100%)' };
+    return {
+      left: anchor.left + anchor.width / 2 + offsetX,
+      top: anchor.top - 8 + offsetY,
+      transform: 'translate(-50%, -100%)',
+    };
   }
-  return { left: pos.x, top: pos.y, transform: 'translateX(-50%)' };
+  return {
+    left: anchor.left + anchor.width / 2 + offsetX,
+    top: anchor.bottom + 8 + offsetY,
+    transform: 'translateX(-50%)',
+  };
 }
 
 const bubbleStyle: CSSProperties = {
   position: 'fixed',
   zIndex: 1000,
-  maxWidth: 260,
+  maxWidth: 'min(260px, calc(100vw - 16px))',
   padding: '5px 9px',
   borderRadius: 8,
   fontSize: 11.5,
@@ -132,15 +274,17 @@ const bubbleStyle: CSSProperties = {
 const wrapBubbleStyle: CSSProperties = {
   whiteSpace: 'normal',
   width: 'max-content',
-  maxWidth: 280,
+  maxWidth: 'min(280px, calc(100vw - 16px))',
+  maxHeight: 'calc(100vh - 16px)',
+  overflowY: 'auto',
 };
 
-const TOOLTIP_KEYFRAMES = `
-@keyframes ol-tooltip-in {
-  from { opacity: 0; scale: .96; }
-  to   { opacity: 1; scale: 1; }
-}
-`;
+const TOOLTIP_KEYFRAMES = [
+  '@keyframes ol-tooltip-in {',
+  '  from { opacity: 0; scale: .96; }',
+  '  to   { opacity: 1; scale: 1; }',
+  '}',
+].join('\n');
 
 if (typeof document !== 'undefined' && !document.getElementById('ol-tooltip-style')) {
   const tag = document.createElement('style');
diff --git a/openless-all/app/src/pages/settings/ClaudeConsoleSection.tsx b/openless-all/app/src/pages/settings/ClaudeConsoleSection.tsx
index 15ac74c3..db351824 100644
--- a/openless-all/app/src/pages/settings/ClaudeConsoleSection.tsx
+++ b/openless-all/app/src/pages/settings/ClaudeConsoleSection.tsx
@@ -14,6 +14,7 @@ import {
   type CodingAgentEvent,
   type CodingAgentPermissionMode,
 } from '../../lib/ipc'
+import { Tooltip } from '../../components/Tooltip'
 import { Btn, Card } from '../_atoms'
 import { SectionDesc, SectionTitle, SettingRow, inputStyle } from './shared'
 
@@ -150,15 +151,17 @@ export function ClaudeConsoleSection() {
 
   return (
     <Card>
-      <button
+      <Tooltip content={t('settings.codingConsole.desc')} wrap placement="bottom">
+        <button
         onClick={() => setExpanded(v => !v)}
         style={{ all: 'unset', cursor: 'pointer', display: 'flex', alignItems: 'center', gap: 8, width: '100%' }}
       >
-        <SectionTitle hint={t('settings.codingConsole.desc')}>{t('settings.codingConsole.title')}</SectionTitle>
+        <SectionTitle>{t('settings.codingConsole.title')}</SectionTitle>
         <span style={{ marginLeft: 'auto', fontSize: 12, color: 'var(--ol-ink-4)' }}>
           {expanded ? `${t('common.hide')} ▴` : `${t('common.show')} ▾`}
         </span>
-      </button>
+        </button>
+      </Tooltip>
       <SectionDesc>{t('settings.codingConsole.desc')}</SectionDesc>
 
       {expanded && (
diff --git a/openless-all/app/src/pages/settings/shared.tsx b/openless-all/app/src/pages/settings/shared.tsx
index 29961993..64a312ff 100644
--- a/openless-all/app/src/pages/settings/shared.tsx
+++ b/openless-all/app/src/pages/settings/shared.tsx
@@ -37,7 +37,7 @@ export function SectionTitle({
     return (
         // display:flex 让 Tooltip 的锚点收缩到标题文字本身，提示贴着文字弹出。
         <div style={{ ...titleStyle, display: "flex" }}>
-            <Tooltip content={hint} wrap placement="bottom">
+            <Tooltip content={hint} wrap placement="bottom" focusable>
                 <span style={hintableTextStyle}>{children}</span>
             </Tooltip>
         </div>
@@ -88,8 +88,8 @@ export function SettingRow({
             {/* display:flex 让 Tooltip 锚点收缩到文字宽度，提示贴着文字弹出。 */}
             <div style={{ minWidth: 0, alignSelf: "center", display: "flex" }}>
                 {desc ? (
-                    <Tooltip content={desc} wrap placement="bottom">
-                        <div style={{ ...labelStyle, ...hintableTextStyle }}>{label}</div>
+                    <Tooltip content={desc} wrap placement="bottom" focusable>
+                        <span style={{ ...labelStyle, ...hintableTextStyle }}>{label}</span>
                     </Tooltip>
                 ) : (
                     <div style={labelStyle}>{label}</div>