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/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) => (