feat: custom terminal background image + theme editor hardening

- settings: backgroundImage/backgroundImageOpacity (10..100, default 60)
- main: otimg:// protocol serves only the configured background file
  (path-allowlisted, 403 otherwise); dev http origin cannot load file:
- TerminalView: allowTransparency + transparent theme background while an
  image is set; .term-bg-image layer behind the xterm surface
- terminal.css: .has-bg-image keeps .xterm-viewport transparent — the old
  chrome-bg pin covered the image layer (root cause of image not showing)
- ThemeSettingsTab: image picker + opacity slider
- ThemeEditor: duplicate-name hint now covers builtin names too; seed
  colors normalized to #rrggbb
- settingsStore: sanitize theme colors, reject non-hex values

src/main/index.ts

@@ -1,6 +1,7 @@
-import { app, BrowserWindow, globalShortcut, nativeImage, shell } from 'electron'
+import { app, BrowserWindow, globalShortcut, net, nativeImage, protocol, shell } from 'electron'
 import { existsSync } from 'fs'
 import { join } from 'path'
+import { pathToFileURL } from 'url'
 import { isTrustedRendererUrl, registerIpc } from './ipc'
 import { killAllPtys, killPtysByOwner } from './pty'
 import { applyStartupSystemSettings, loadSettings } from './settingsStore'
@@ -45,6 +46,14 @@ if (!app.isPackaged) {
   app.setPath('userData', join(app.getPath('appData'), 'OpenTerminal-dev'))
 }
 
+// Custom background image (设置 → 主题): the renderer page cannot load file:
+// subresources directly (Chromium blocks them from non-file origins), so it
+// references them through this scheme instead. The handler serves exactly one
+// file — the configured background image — nothing else.
+protocol.registerSchemesAsPrivileged([
+  { scheme: 'otimg', privileges: { secure: true, supportFetchAPI: false, corsEnabled: false } }
+])
+
 // Single instance: a second launch just surfaces the existing window (pulls
 // it out of the tray if hidden there) instead of starting another process.
 // The refused instance skips the whole startup path: `app.quit()` only asks
@@ -57,6 +66,19 @@ if (!gotSingleInstanceLock) {
   app.on('second-instance', () => showOrCreate())
 
   app.whenReady().then(() => {
+    // Serve the configured background image (path lives in settings; anything
+    // else — including a path that is no longer configured — is refused, so the
+    // protocol cannot be used to read arbitrary files).
+    protocol.handle('otimg', (request) => {
+      const url = new URL(request.url)
+      const requested = decodeURIComponent(url.pathname.replace(/^\//, ''))
+      const allowed = loadSettings().terminal.backgroundImage
+      if (allowed === '' || requested !== allowed || !existsSync(requested)) {
+        return new Response('', { status: 403 })
+      }
+      return net.fetch(pathToFileURL(requested).toString())
+    })
+
     registerIpc()
     registerUpdateIpc()
     // Before the window exists: a renderer-triggered check must not run against

src/main/settingsStore.ts

@@ -138,11 +138,15 @@ function sanitizeThemes(value: unknown, warnings: Warnings): TerminalTheme[] {
         : null
     const colors: ThemeColors = { ...DEFAULT_DARK.colors }
     const target = colors as unknown as Record<string, string>
+    const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i
     for (const key of THEME_COLOR_KEYS) {
       const color = candidate?.[key]
-      if (typeof color === 'string' && color !== '') target[key] = color
-      else if (color !== undefined) {
-        warnings.push(`customThemes[${index}].colors.${key} repaired → built-in default`)
+      // Only well-formed hex colours survive: xterm would render anything else
+      // as black, and the theme editor's native colour input needs #rrggbb.
+      if (typeof color === 'string' && HEX_COLOR.test(color.trim())) {
+        target[key] = color.trim()
+      } else if (color !== undefined) {
+        warnings.push(`customThemes[${index}].colors.${key}: not a hex color — repaired`)
       }
     }
     themes.push({

src/renderer/index.html

@@ -5,7 +5,7 @@
     <title>OpenTerminal</title>
     <meta
       http-equiv="Content-Security-Policy"
-      content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; font-src 'self' data:"
+      content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; font-src 'self' data:; img-src 'self' file: data: otimg:"
     />
   </head>
   <body>

src/renderer/src/settings/ThemeSettingsTab.tsx

@@ -1,5 +1,5 @@
 import { useMemo } from 'react'
-import { Button, ColorPicker, Popconfirm } from 'antd'
+import { Button, ColorPicker, Popconfirm, Slider } from 'antd'
 import { t } from '@shared/i18n'
 import type { TerminalSettings } from '@shared/settings'
 import { DEFAULT_SETTINGS } from '@shared/settings'
@@ -46,8 +46,45 @@ export function ThemeSettingsTab({
     await setCustomThemes(next)
   }
 
+  const pickImage = async (): Promise<void> => {
+    const files = await window.api.pickFiles()
+    const image = files.find((f) => /\.(png|jpe?g|bmp|gif|webp|avif)$/i.test(f))
+    if (image) await updateTerminal({ backgroundImage: image })
+  }
+
   return (
     <div className="theme-pane">
+      <div className="theme-accent-row">
+        <div>
+          <div className="settings-block-label">{t('settings.theme.backgroundImage')}</div>
+          <div className="settings-block-hint">{t('settings.theme.backgroundImageDesc')}</div>
+        </div>
+        <div className="theme-accent-controls">
+          <Button size="small" onClick={() => void pickImage()}>
+            {t('settings.theme.chooseImage')}
+          </Button>
+          {settings.terminal.backgroundImage !== '' && (
+            <Button size="small" onClick={() => void updateTerminal({ backgroundImage: '' })}>
+              {t('settings.theme.clearImage')}
+            </Button>
+          )}
+        </div>
+      </div>
+      {settings.terminal.backgroundImage !== '' && (
+        <div className="theme-accent-row">
+          <div>
+            <div className="settings-block-label">{t('settings.theme.imageOpacity')}</div>
+          </div>
+          <Slider
+            style={{ width: 200 }}
+            min={10}
+            max={100}
+            step={5}
+            value={settings.terminal.backgroundImageOpacity}
+            onChange={(v) => void updateTerminal({ backgroundImageOpacity: v })}
+          />
+        </div>
+      )}
       <div className="theme-accent-row">
         <div>
           <div className="settings-block-label">{t('settings.theme.accent')}</div>

src/renderer/src/settings/settings.css

@@ -582,3 +582,11 @@
 .shortcut-input.is-recording .ant-input {
   border-color: var(--tab-accent, #3fb950);
 }
+
+/* theme editor: duplicate-name notice under the name field */
+.theme-editor-hint {
+  margin: -4px 0 10px;
+  padding-left: 2px;
+  font-size: 12px;
+  color: #d29922;
+}

src/renderer/src/terminal/TerminalView.tsx

@@ -67,8 +67,20 @@ const SEARCH_DECORATIONS: NonNullable<NonNullable<Parameters<SearchAddon['findNe
 // xterm's default overviewRulerBorder (#7f7f7f) renders as a light vertical line
 // on the dark surface once scrollback exists. Force it transparent; search-match
 // marks in the ruler keep their own colors.
-function withChromeColors(colors: ITheme): ITheme {
-  return { ...colors, overviewRulerBorder: '#00000000' }
+function withChromeColors(colors: ITheme, transparentBackground: boolean): ITheme {
+  return {
+    ...colors,
+    overviewRulerBorder: '#00000000',
+    // While a custom background image is set the xterm surface goes fully
+    // transparent so the image layer behind the host is what shows through.
+    ...(transparentBackground ? { background: '#00000000' } : {})
+  }
+}
+
+/** URL for a background image, served by the main process's otimg:// handler
+ *  (the page itself cannot reference file: paths from non-file origins). */
+function toFileUrl(path: string): string {
+  return `otimg://bg/${encodeURIComponent(path)}`
 }
 
 export interface TerminalHandle {
@@ -673,8 +685,9 @@ export const TerminalView: ForwardRefExoticComponent<TerminalViewProps & { ref?:
       cursorBlink: tSettings.cursorBlink,
       cursorStyle: tSettings.cursorStyle,
       cursorInactiveStyle: tSettings.cursorInactiveStyle,
-      theme: withChromeColors(getThemeById(tSettings.themeId, settings.customThemes).colors as ITheme),
+      theme: withChromeColors(getThemeById(tSettings.themeId, settings.customThemes).colors as ITheme, Boolean(tSettings.backgroundImage)),
       allowProposedApi: true,
+      allowTransparency: true,
       overviewRuler: { width: 9, showTopBorder: false, showBottomBorder: false },
       drawBoldTextInBrightColors: true,
       minContrastRatio: 1,
@@ -1009,7 +1022,7 @@ export const TerminalView: ForwardRefExoticComponent<TerminalViewProps & { ref?:
     // Live-appliable in xterm 6: without this the setting only took effect for
     // 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)
+    term.options.theme = withChromeColors(getThemeById(tSettings.themeId, settings.customThemes).colors as ITheme, Boolean(tSettings.backgroundImage))
     scheduleFit()
   }, [tSettings, settings.customThemes, scheduleFit])
 
@@ -1048,7 +1061,13 @@ export const TerminalView: ForwardRefExoticComponent<TerminalViewProps & { ref?:
     [sessionId]
   )
 
-  const terminalClassName = useMemo(() => ['terminal-view', className].filter(Boolean).join(' '), [className])
+  const terminalClassName = useMemo(
+    () =>
+      ['terminal-view', settings.terminal.backgroundImage !== '' && 'has-bg-image', className]
+        .filter(Boolean)
+        .join(' '),
+    [className, settings.terminal.backgroundImage]
+  )
 
   /**
    * [M5] Compute and store the floating popup position so it hugs the text
@@ -1277,6 +1296,15 @@ export const TerminalView: ForwardRefExoticComponent<TerminalViewProps & { ref?:
           </div>
         )}
         <div className="terminal-view-dock" ref={hostRef}>
+          {settings.terminal.backgroundImage !== '' && (
+            <div
+              className="term-bg-image"
+              style={{
+                backgroundImage: `url("${toFileUrl(settings.terminal.backgroundImage)}")`,
+                opacity: Math.min(100, Math.max(10, settings.terminal.backgroundImageOpacity)) / 100
+              }}
+            />
+          )}
           {dead && (
             <div className="term-dead-mask">
               <div>{t('terminal.dead.message', { code: exitCode })}</div>

src/renderer/src/terminal/terminal.css

@@ -15,11 +15,17 @@
 
 /* xterm.css defaults .xterm-viewport to #000; when the pane height isn't a
    multiple of the cell height the leftover bottom strip shows that black.
-   Pin it to the (theme-derived) chrome background so the gap is invisible. */
-.terminal-view .xterm .xterm-viewport {
+   Pin it to the (theme-derived) chrome background so the gap is invisible.
+   With a custom background image the viewport must stay transparent — this
+   opaque layer would cover the .term-bg-image behind the xterm surface. */
+.terminal-view:not(.has-bg-image) .xterm .xterm-viewport {
   background-color: var(--chrome-bg);
 }
 
+.terminal-view.has-bg-image .xterm .xterm-viewport {
+  background-color: transparent;
+}
+
 /* 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)
@@ -353,6 +359,24 @@
   padding: 0;
 }
 
+/* ---- custom background image (设置 → 主题) ----
+   Sits behind the xterm screen; while an image is set the theme background is
+   transparent (allowTransparency), so this layer is what shows through. */
+.term-bg-image {
+  position: absolute;
+  inset: 0;
+  z-index: 0;
+  background-size: cover;
+  background-position: center;
+  background-repeat: no-repeat;
+  pointer-events: none;
+}
+
+.terminal-view-dock > .xterm {
+  position: relative;
+  z-index: 1;
+}
+
 /* ---- dead process overlay ---- */
 .term-dead-mask {
   position: absolute;

src/renderer/src/theme/editor/ThemeEditor.tsx

@@ -2,7 +2,7 @@ import { useEffect, useMemo, useState } from 'react'
 import { Input, Modal } from 'antd'
 import { t } from '@shared/i18n'
 import type { ThemeColors, TerminalTheme } from '@shared/theme'
-import { DEFAULT_DARK, getThemeById } from '@shared/theme'
+import { BUILTIN_THEMES, DEFAULT_DARK, getThemeById } from '@shared/theme'
 import { useSettingsStore } from '../../settings/store'
 
 export interface ThemeEditorProps {
@@ -49,6 +49,17 @@ const ANSI_KEYS: FieldSpec[] = [
   { key: 'brightWhite', label: 'Bright White' }
 ]
 
+/** The native colour input only accepts #rrggbb: clamp every seeded value so a
+ *  hand-edited or migrated theme can't render the picker as solid black. */
+function normalizeThemeColors(colors: ThemeColors, fallback: ThemeColors): ThemeColors {
+  const out = { ...fallback }
+  for (const key of Object.keys(fallback) as (keyof ThemeColors)[]) {
+    const value = colors[key] ?? ''
+    out[key] = /^#[0-9a-f]{6}$/i.test(value) ? value : (fallback[key] ?? '')
+  }
+  return out
+}
+
 export function ThemeEditor({ open, onClose, themeId }: ThemeEditorProps): React.JSX.Element {
   const settings = useSettingsStore((s) => s.settings)
   const updateTerminal = useSettingsStore((s) => s.updateTerminal)
@@ -64,6 +75,11 @@ export function ThemeEditor({ open, onClose, themeId }: ThemeEditorProps): React
   const [name, setName] = useState('')
   const [colors, setColors] = useState<ThemeColors>(DEFAULT_DARK.colors)
   const [saving, setSaving] = useState(false)
+  /** another theme (builtin or custom) already uses this name (allowed, but the user should know) */
+  const duplicateName =
+    name.trim() !== '' &&
+    (BUILTIN_THEMES.some((th) => th.name === name.trim()) ||
+      settings.customThemes.some((th) => th.id !== themeId && th.name === name.trim()))
 
   // (re)initialize the form each time the modal opens
   useEffect(() => {
@@ -75,12 +91,12 @@ export function ThemeEditor({ open, onClose, themeId }: ThemeEditorProps): React
         return
       }
       setName(editingTheme.name)
-      setColors({ ...editingTheme.colors })
+      setColors(normalizeThemeColors(editingTheme.colors, DEFAULT_DARK.colors))
     } else {
       /** create mode: seed a fresh copy based on the currently active theme */
       const active = getThemeById(settings.terminal.themeId, settings.customThemes)
       setName(active.name + t('settings.themeEditor.copySuffix'))
-      setColors({ ...active.colors })
+      setColors(normalizeThemeColors(active.colors, DEFAULT_DARK.colors))
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [open])
@@ -141,6 +157,7 @@ export function ThemeEditor({ open, onClose, themeId }: ThemeEditorProps): React
             maxLength={60}
           />
         </div>
+        {duplicateName && <div className="theme-editor-hint">{t('settings.themeEditor.duplicateName')}</div>}
 
         <div className="theme-editor-colors">
           {headerKeys().map((spec) => (

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

@@ -139,12 +139,18 @@ const settings: Record<string, string> = {
   'settings.highlight.builtin.url': 'Web links',
   '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',
+  'settings.theme.chooseImage': 'Choose image',
+  'settings.theme.clearImage': 'Remove',
+  'settings.theme.imageOpacity': 'Image opacity',
   'settings.theme.customBadge': 'Custom',
   'settings.theme.deleteTitle': 'Delete custom theme',
   'settings.theme.create': 'New theme',
   'settings.theme.editTitle': 'Edit theme',
   'settings.themeEditor.name': 'Name',
   'settings.themeEditor.namePlaceholder': 'Theme name',
+  'settings.themeEditor.duplicateName': 'Same name as another theme (saving is still allowed)',
   'settings.themeEditor.copySuffix': ' (copy)',
   'settings.about.currentVersion': 'Current version',
   'settings.about.statusIdle': 'Click to check for updates',

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

@@ -136,12 +136,18 @@ const settings: Record<string, string> = {
   'settings.highlight.builtin.url': 'ウェブリンク',
   'settings.theme.accent': 'タブのアクセントカラー',
   'settings.theme.accentDesc': 'アクティブなタブの枠線、サイドバーのインジケーター、SSH バッジのアクセントカラー',
+  'settings.theme.backgroundImage': '背景画像',
+  'settings.theme.backgroundImageDesc': 'ターミナルの背後に画像を表示します。削除すると無地の背景に戻ります',
+  'settings.theme.chooseImage': '画像を選択',
+  'settings.theme.clearImage': '削除',
+  'settings.theme.imageOpacity': '画像の不透明度',
   'settings.theme.customBadge': 'カスタム',
   'settings.theme.deleteTitle': 'カスタムテーマを削除',
   'settings.theme.create': '新しいテーマ',
   'settings.theme.editTitle': 'テーマを編集',
   'settings.themeEditor.name': '名前',
   'settings.themeEditor.namePlaceholder': 'テーマ名',
+  'settings.themeEditor.duplicateName': '他のテーマと同名です（保存は可能）',
   'settings.themeEditor.copySuffix': '（コピー）',
   'settings.about.currentVersion': '現在のバージョン',
   'settings.about.statusIdle': 'クリックして更新を確認',

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

@@ -133,12 +133,18 @@ const settings: Record<string, string> = {
   'settings.highlight.builtin.url': '网址链接',
   'settings.theme.accent': '标签强调色',
   'settings.theme.accentDesc': '活动标签边框、侧栏指示条与 SSH 徽章的强调颜色',
+  'settings.theme.backgroundImage': '背景图片',
+  'settings.theme.backgroundImageDesc': '为终端设置一张背景图片；移除后恢复纯色背景',
+  'settings.theme.chooseImage': '选择图片',
+  'settings.theme.clearImage': '移除图片',
+  'settings.theme.imageOpacity': '图片不透明度',
   'settings.theme.customBadge': '自定义',
   'settings.theme.deleteTitle': '删除自定义主题',
   'settings.theme.create': '新建主题',
   'settings.theme.editTitle': '编辑主题',
   'settings.themeEditor.name': '名称',
   'settings.themeEditor.namePlaceholder': '主题名称',
+  'settings.themeEditor.duplicateName': '与其他主题重名，仍可保存',
   'settings.themeEditor.copySuffix': '（副本）',
   'settings.about.currentVersion': '当前版本',
   'settings.about.statusIdle': '点击检查更新',

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

@@ -133,12 +133,18 @@ const settings: Record<string, string> = {
   'settings.highlight.builtin.url': '網址連結',
   'settings.theme.accent': '標籤強調色',
   'settings.theme.accentDesc': '作用中標籤的邊框、側邊欄指示條與 SSH 徽章的強調顏色',
+  'settings.theme.backgroundImage': '背景圖片',
+  'settings.theme.backgroundImageDesc': '為終端設定一張背景圖片；移除後恢復純色背景',
+  'settings.theme.chooseImage': '選擇圖片',
+  'settings.theme.clearImage': '移除圖片',
+  'settings.theme.imageOpacity': '圖片不透明度',
   'settings.theme.customBadge': '自訂',
   'settings.theme.deleteTitle': '刪除自訂主題',
   'settings.theme.create': '新增主題',
   'settings.theme.editTitle': '編輯主題',
   'settings.themeEditor.name': '名稱',
   'settings.themeEditor.namePlaceholder': '主題名稱',
+  'settings.themeEditor.duplicateName': '與其他主題同名，仍可儲存',
   'settings.themeEditor.copySuffix': '（副本）',
   'settings.about.currentVersion': '目前版本',
   'settings.about.statusIdle': '點擊檢查更新',

src/shared/settings.ts

@@ -49,6 +49,10 @@ export interface TerminalSettings {
   showOpenCwdButton: boolean
   /** accent color for the active tab outline, rail indicator and SSH badges */
   tabAccentColor: string
+  /** absolute path to an image rendered behind the terminal; '' = none */
+  backgroundImage: string
+  /** background image layer opacity, 10..100 (%) */
+  backgroundImageOpacity: number
 }
 
 export interface SystemSettings {
@@ -132,7 +136,9 @@ export const DEFAULT_SETTINGS: AppSettings = {
     showRecButton: false,
     showOpenLogsButton: false,
     showOpenCwdButton: true,
-    tabAccentColor: '#3fb950'
+    tabAccentColor: '#3fb950',
+    backgroundImage: '',
+    backgroundImageOpacity: 60
   },
   customThemes: [],
   highlightRules: DEFAULT_HIGHLIGHT_RULES,