fix(theme): dim background image toward dark and lift text contrast in image mode

On light themes the pane base is near-white (--chrome-bg), so lowering the
background image opacity washed the wallpaper out to white instead of
darkening it, and the theme's dark foreground text became unreadable.

- terminal.css: in has-bg-image mode the dock gets a fixed dark base
  (#0d1117), so the opacity slider always dims toward dark regardless of
  theme
- TerminalView: raise xterm minimumContrastRatio from 1 to 4.5 (WCAG AA,
  same as VS Code's terminal default) while an image is set; xterm treats
  the transparent background as black luminance, so dark foreground colors
  are lifted to stay readable over the wallpaper. Also fix the option name
  (minContrastRatio is silently ignored; the real key is
  minimumContrastRatio)
- i18n: update backgroundImageDesc in zh-CN/zh-TW/en/ja
- AGENTS.md: document the two image-mode invariants

AGENTS.md

@@ -51,6 +51,7 @@ Electron + electron-vite + React 终端工具（本地终端 / SSH / SFTP）。
 
 - 终端主题由 xterm 主题派生 UI 配色：`src/renderer/src/theme/chrome.ts` 的 `applyChromeTheme` 写入 `--chrome-bg/-bg-deep/-border/-hover` CSS 变量，antd token 在 `main.tsx` ThemedConfigProvider 派生
 - 标签强调色：`settings.tabAccentColor`（默认 `#3fb950`），经 `--tab-accent` CSS 变量生效
+- 背景图（`settings.terminal.backgroundImage`）：图片层 `.term-bg-image` 在 xterm 画布之下（`terminal.css`），xterm 背景设 `#00000000` 透明。**图片模式下的两条铁律**：① `.terminal-view.has-bg-image .terminal-view-dock` 强制深色底衬 `#0d1117`，不能用 `--chrome-bg`——浅色主题下它是白色，调低透明度会把图洗白而不是压暗；② `minimumContrastRatio` 从 1 提到 4.5（WCAG AA，与 VS Code 终端默认值一致；TerminalView 构造与设置热更两处都要改；注意正确拼写是 `minimumContrastRatio`，`minContrastRatio` 会被静默忽略），xterm 的对比度计算把透明背景当黑色亮度，会把浅色主题的深色前景自动提亮到可读。无图时保持 1 不动主题配色
 
 ## 终端尺寸同步
 

src/renderer/src/terminal/TerminalView.tsx

@@ -778,7 +778,11 @@ export const TerminalView: ForwardRefExoticComponent<TerminalViewProps & { ref?:
       allowTransparency: true,
       overviewRuler: { width: 9, showTopBorder: false, showBottomBorder: false },
       drawBoldTextInBrightColors: true,
-      minContrastRatio: 1,
+      // In image mode the xterm background is transparent (#00000000), which
+      // xterm's contrast cache treats as black; a raised contrast floor lifts
+      // dark foreground colors (light themes) enough to stay readable over
+      // the wallpaper. Without an image keep 1 (off) to honor theme colors.
+      minimumContrastRatio: tSettings.backgroundImage ? 4.5 : 1,
       automaticFontFallback: true,
       convertEol: false,
       windowsPty: { backend: 'conpty', buildNumber: 0 }
@@ -1113,6 +1117,7 @@ export const TerminalView: ForwardRefExoticComponent<TerminalViewProps & { ref?:
     // terminals opened after the change, which reads as "the setting is broken".
     term.options.scrollback = tSettings.scrollback
     term.options.theme = withChromeColors(getThemeById(tSettings.themeId, settings.customThemes).colors as ITheme, Boolean(tSettings.backgroundImage))
+    term.options.minimumContrastRatio = tSettings.backgroundImage ? 4.5 : 1
     scheduleFit()
   }, [tSettings, settings.customThemes, scheduleFit])
 

src/renderer/src/terminal/terminal.css

@@ -26,6 +26,14 @@
   background-color: transparent;
 }
 
+/* With a background image the dock must dim toward a fixed dark base instead of
+   the theme chrome color: on light themes --chrome-bg is near-white, so lowering
+   the image opacity would wash the wallpaper out to white (text unreadable)
+   rather than darkening it. */
+.terminal-view.has-bg-image .terminal-view-dock {
+  background: #0d1117;
+}
+
 /* Slim slate scrollbar for the xterm viewport — the native Windows one renders
    light track + arrow buttons that look broken on the dark surface. The thumb
    sits inset inside a wider grab lane (transparent border + padding-box clip)

src/shared/i18n/dicts/en/settings.ts

@@ -284,7 +284,7 @@ const settings: Record<string, string> = {
   'settings.theme.accent': 'Tab accent color',
   'settings.theme.accentDesc': 'Accent color for the active tab border, the sidebar indicator, and SSH badges',
   'settings.theme.backgroundImage': 'Background image',
-  'settings.theme.backgroundImageDesc': 'Show an image behind the terminal; remove it to go back to a solid background. Lower the opacity if text gets hard to read (20–40% works well for bright images)',
+  'settings.theme.backgroundImageDesc': 'Show an image behind the terminal; remove it to go back to a solid background. In every theme the image dims toward dark and text is brightened automatically; lower the opacity if it is still hard to read (20–40% works well for bright images)',
   'settings.theme.chooseImage': 'Choose image',
   'settings.theme.clearImage': 'Remove',
   'settings.theme.imageOpacity': 'Image opacity',

src/shared/i18n/dicts/ja/settings.ts

@@ -279,7 +279,7 @@ const settings: Record<string, string> = {
   'settings.theme.accent': 'タブのアクセントカラー',
   'settings.theme.accentDesc': 'アクティブなタブの枠線、サイドバーのインジケーター、SSH バッジのアクセントカラー',
   'settings.theme.backgroundImage': '背景画像',
-  'settings.theme.backgroundImageDesc': 'ターミナルの背後に画像を表示します。削除すると無地の背景に戻ります。文字が読みにくい場合は不透明度を下げてください（明るい画像は 20–40% が目安です）',
+  'settings.theme.backgroundImageDesc': 'ターミナルの背後に画像を表示します。削除すると無地の背景に戻ります。どのテーマでも画像は暗い側へ減光され、文字は自動で明るくなります。それでも読みにくい場合は不透明度を下げてください（明るい画像は 20–40% が目安です）',
   'settings.theme.chooseImage': '画像を選択',
   'settings.theme.clearImage': '削除',
   'settings.theme.imageOpacity': '画像の不透明度',

src/shared/i18n/dicts/zh-CN/settings.ts

@@ -268,7 +268,7 @@ const settings: Record<string, string> = {
   'settings.theme.accent': '标签强调色',
   'settings.theme.accentDesc': '活动标签边框、侧栏指示条与 SSH 徽章的强调颜色',
   'settings.theme.backgroundImage': '背景图片',
-  'settings.theme.backgroundImageDesc': '为终端设置一张背景图片；移除后恢复纯色背景；文字看不清时调低透明度（亮图建议 20–40%）',
+  'settings.theme.backgroundImageDesc': '为终端设置一张背景图片；移除后恢复纯色背景；任何主题下图片都向深色压暗、文字自动提亮，仍看不清时调低透明度（亮图建议 20–40%）',
   'settings.theme.chooseImage': '选择图片',
   'settings.theme.clearImage': '移除图片',
   'settings.theme.imageOpacity': '图片不透明度',

src/shared/i18n/dicts/zh-TW/settings.ts

@@ -268,7 +268,7 @@ const settings: Record<string, string> = {
   'settings.theme.accent': '標籤強調色',
   'settings.theme.accentDesc': '作用中標籤的邊框、側邊欄指示條與 SSH 徽章的強調顏色',
   'settings.theme.backgroundImage': '背景圖片',
-  'settings.theme.backgroundImageDesc': '為終端設定一張背景圖片；移除後恢復純色背景；文字看不清時調低透明度（亮圖建議 20–40%）',
+  'settings.theme.backgroundImageDesc': '為終端設定一張背景圖片；移除後恢復純色背景；任何主題下圖片都向深色壓暗、文字自動提亮，仍看不清時調低透明度（亮圖建議 20–40%）',
   'settings.theme.chooseImage': '選擇圖片',
   'settings.theme.clearImage': '移除圖片',
   'settings.theme.imageOpacity': '圖片不透明度',