From 35fcf1ed580e7ce4bc1fe2c7b71d052bff5a9869 Mon Sep 17 00:00:00 2001
From: Brendan Allan <14191578+Brendonovich@users.noreply.github.com>
Date: Mon, 20 Jul 2026 16:10:24 +0000
Subject: [PATCH 1/8] feat(desktop): add image backgrounds

---
 .../session/session-new-design-view.tsx       |  6 +-
 .../components/settings-background-image.ts   | 36 ++++++++++++
 .../app/src/components/settings-general.tsx   | 20 +++++++
 .../src/components/settings-v2/general.tsx    | 25 +++++++++
 packages/app/src/components/titlebar.tsx      |  1 +
 packages/app/src/context/platform.tsx         | 12 ++++
 packages/app/src/i18n/ar.ts                   |  4 ++
 packages/app/src/i18n/br.ts                   |  4 ++
 packages/app/src/i18n/bs.ts                   |  4 ++
 packages/app/src/i18n/da.ts                   |  4 ++
 packages/app/src/i18n/de.ts                   |  4 ++
 packages/app/src/i18n/en.ts                   |  4 ++
 packages/app/src/i18n/es.ts                   |  4 ++
 packages/app/src/i18n/fr.ts                   |  4 ++
 packages/app/src/i18n/ja.ts                   |  4 ++
 packages/app/src/i18n/ko.ts                   |  4 ++
 packages/app/src/i18n/no.ts                   |  4 ++
 packages/app/src/i18n/pl.ts                   |  4 ++
 packages/app/src/i18n/ru.ts                   |  4 ++
 packages/app/src/i18n/th.ts                   |  4 ++
 packages/app/src/i18n/tr.ts                   |  4 ++
 packages/app/src/i18n/uk.ts                   |  4 ++
 packages/app/src/i18n/zh.ts                   |  4 ++
 packages/app/src/i18n/zht.ts                  |  4 ++
 packages/app/src/pages/home.tsx               |  5 +-
 packages/app/src/pages/layout-new.tsx         |  1 +
 packages/app/src/pages/layout.tsx             |  6 +-
 packages/app/src/pages/session.tsx            |  1 +
 .../desktop/src/main/attachment-picker.ts     | 11 +++-
 .../desktop/src/main/background-image.test.ts | 56 +++++++++++++++++++
 packages/desktop/src/main/background-image.ts | 50 +++++++++++++++++
 packages/desktop/src/main/ipc.ts              | 29 ++++++++++
 packages/desktop/src/main/windows.ts          |  7 +++
 packages/desktop/src/preload/index.ts         |  8 +++
 packages/desktop/src/preload/types.ts         |  8 +++
 packages/desktop/src/renderer/index.tsx       | 33 +++++++++++
 packages/desktop/src/renderer/styles.css      | 18 ++++++
 37 files changed, 400 insertions(+), 5 deletions(-)
 create mode 100644 packages/app/src/components/settings-background-image.ts
 create mode 100644 packages/desktop/src/main/background-image.test.ts
 create mode 100644 packages/desktop/src/main/background-image.ts

diff --git a/packages/app/src/components/session/session-new-design-view.tsx b/packages/app/src/components/session/session-new-design-view.tsx
index a324c64fa6df..3925d568c5c7 100644
--- a/packages/app/src/components/session/session-new-design-view.tsx
+++ b/packages/app/src/components/session/session-new-design-view.tsx
@@ -4,7 +4,11 @@ import { NEW_SESSION_CONTENT_WIDTH } from "@/pages/session/new-session-layout"
 
 export function NewSessionDesignView(props: { children: JSX.Element }) {
   return (
-    <div data-component="session-new-design" class="relative size-full overflow-hidden bg-v2-background-bg-deep ">
+    <div
+      data-component="session-new-design"
+      data-background-surface="shell"
+      class="relative size-full overflow-hidden bg-v2-background-bg-deep "
+    >
       <div class="absolute inset-x-0 top-[25.375%] flex justify-center px-6">
         <div class={NEW_SESSION_CONTENT_WIDTH}>
           <WordmarkV2 class="h-auto w-full text-v2-background-bg-inverse" />
diff --git a/packages/app/src/components/settings-background-image.ts b/packages/app/src/components/settings-background-image.ts
new file mode 100644
index 000000000000..eda0de2a524d
--- /dev/null
+++ b/packages/app/src/components/settings-background-image.ts
@@ -0,0 +1,36 @@
+import { createStore } from "solid-js/store"
+import { useLanguage } from "@/context/language"
+import { usePlatform } from "@/context/platform"
+import { showToast } from "@/utils/toast"
+
+export function useSettingsBackgroundImage() {
+  const platform = usePlatform()
+  const language = useLanguage()
+  const [state, setState] = createStore({ busy: false })
+
+  const run = async (action: (() => Promise<unknown>) | undefined) => {
+    if (!action || state.busy) return
+    setState("busy", true)
+    try {
+      await action()
+    } catch (error) {
+      showToast({
+        variant: "error",
+        title: language.t("common.requestFailed"),
+        description: error instanceof Error ? error.message : String(error),
+      })
+    } finally {
+      setState("busy", false)
+    }
+  }
+
+  return {
+    available: !!platform.selectBackgroundImage,
+    active: () => platform.backgroundImage?.() ?? false,
+    get busy() {
+      return state.busy
+    },
+    select: () => run(platform.selectBackgroundImage),
+    clear: () => run(platform.clearBackgroundImage),
+  }
+}
diff --git a/packages/app/src/components/settings-general.tsx b/packages/app/src/components/settings-general.tsx
index 3beb97225a4e..1afb1866cb52 100644
--- a/packages/app/src/components/settings-general.tsx
+++ b/packages/app/src/components/settings-general.tsx
@@ -31,6 +31,7 @@ import { decode64 } from "@/utils/base64"
 import { playSoundById, SOUND_OPTIONS } from "@/utils/sound"
 import { Link } from "./link"
 import { SettingsList } from "./settings-list"
+import { useSettingsBackgroundImage } from "./settings-background-image"
 
 let demoSoundState = {
   cleanup: undefined as (() => void) | undefined,
@@ -87,6 +88,7 @@ export const SettingsGeneral: Component = () => {
   const language = useLanguage()
   const permission = usePermission()
   const platform = usePlatform()
+  const backgroundImage = useSettingsBackgroundImage()
   const dialog = useDialog()
   const params = useParams()
   const settings = useSettings()
@@ -499,6 +501,24 @@ export const SettingsGeneral: Component = () => {
           />
         </SettingsRow>
 
+        <Show when={backgroundImage.available}>
+          <SettingsRow
+            title={language.t("settings.general.row.backgroundImage.title")}
+            description={language.t("settings.general.row.backgroundImage.description")}
+          >
+            <div class="flex items-center gap-2">
+              <Button size="small" variant="secondary" disabled={backgroundImage.busy} onClick={backgroundImage.select}>
+                {language.t("settings.general.row.backgroundImage.choose")}
+              </Button>
+              <Show when={backgroundImage.active()}>
+                <Button size="small" variant="ghost" disabled={backgroundImage.busy} onClick={backgroundImage.clear}>
+                  {language.t("settings.general.row.backgroundImage.remove")}
+                </Button>
+              </Show>
+            </div>
+          </SettingsRow>
+        </Show>
+
         <SettingsRow
           title={language.t("settings.general.row.uiFont.title")}
           description={language.t("settings.general.row.uiFont.description")}
diff --git a/packages/app/src/components/settings-v2/general.tsx b/packages/app/src/components/settings-v2/general.tsx
index ed2328c89aa5..e2f27615f25a 100644
--- a/packages/app/src/components/settings-v2/general.tsx
+++ b/packages/app/src/components/settings-v2/general.tsx
@@ -29,6 +29,7 @@ import { Link } from "../link"
 import { SettingsListV2 } from "./parts/list"
 import { SettingsRowV2 } from "./parts/row"
 import { LayoutRetirementNotice, LayoutTransitionToggle } from "./interface-transition"
+import { useSettingsBackgroundImage } from "../settings-background-image"
 import "./settings-v2.css"
 
 let demoSoundState = {
@@ -88,6 +89,7 @@ export const SettingsGeneralV2: Component<{
   const language = useLanguage()
   const permission = usePermission()
   const platform = usePlatform()
+  const backgroundImage = useSettingsBackgroundImage()
   const dialog = useDialog()
   const settings = useSettings()
   const serverSync = useServerSync()
@@ -460,6 +462,29 @@ export const SettingsGeneralV2: Component<{
           />
         </SettingsRowV2>
 
+        <Show when={backgroundImage.available}>
+          <SettingsRowV2
+            title={language.t("settings.general.row.backgroundImage.title")}
+            description={language.t("settings.general.row.backgroundImage.description")}
+          >
+            <div class="flex items-center gap-2">
+              <ButtonV2
+                size="normal"
+                variant="neutral"
+                disabled={backgroundImage.busy}
+                onClick={backgroundImage.select}
+              >
+                {language.t("settings.general.row.backgroundImage.choose")}
+              </ButtonV2>
+              <Show when={backgroundImage.active()}>
+                <ButtonV2 size="normal" variant="ghost" disabled={backgroundImage.busy} onClick={backgroundImage.clear}>
+                  {language.t("settings.general.row.backgroundImage.remove")}
+                </ButtonV2>
+              </Show>
+            </div>
+          </SettingsRowV2>
+        </Show>
+
         <SettingsRowV2
           title={language.t("settings.general.row.uiFont.title")}
           description={language.t("settings.general.row.uiFont.description")}
diff --git a/packages/app/src/components/titlebar.tsx b/packages/app/src/components/titlebar.tsx
index 1a2a8a81b6d4..2122647fdbba 100644
--- a/packages/app/src/components/titlebar.tsx
+++ b/packages/app/src/components/titlebar.tsx
@@ -227,6 +227,7 @@ export function Titlebar(props: { update?: TitlebarUpdate }) {
 
   return (
     <header
+      data-background-surface="shell"
       data-slot={useV2Titlebar() ? "titlebar-v2" : undefined}
       classList={{
         "shrink-0 relative flex flex-row": true,
diff --git a/packages/app/src/context/platform.tsx b/packages/app/src/context/platform.tsx
index 1a061a667552..f511e94ec60f 100644
--- a/packages/app/src/context/platform.tsx
+++ b/packages/app/src/context/platform.tsx
@@ -112,6 +112,18 @@ type PlatformBase = {
   /** Read image from clipboard (desktop only) */
   readClipboardImage?(): Promise<File | null>
 
+  /** Load and apply the saved desktop background image. */
+  loadBackgroundImage?(): Promise<boolean>
+
+  /** Whether the desktop currently has a background image. */
+  backgroundImage?: Accessor<boolean>
+
+  /** Select and apply a desktop background image. */
+  selectBackgroundImage?(): Promise<boolean>
+
+  /** Clear the saved desktop background image. */
+  clearBackgroundImage?(): Promise<void>
+
   /** Export collected diagnostic logs (desktop only) */
   exportDebugLogs?(): Promise<string>
 
diff --git a/packages/app/src/i18n/ar.ts b/packages/app/src/i18n/ar.ts
index bdf7f080d367..ca8d0b1fecc1 100644
--- a/packages/app/src/i18n/ar.ts
+++ b/packages/app/src/i18n/ar.ts
@@ -704,6 +704,10 @@ export const dict = {
   "settings.general.row.font.description": "خصّص الخط المستخدم في كتل التعليمات البرمجية",
   "settings.general.row.terminalFont.title": "خط الطرفية",
   "settings.general.row.terminalFont.description": "خصّص الخط المستخدم في الطرفية",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "خط الواجهة",
   "settings.general.row.uiFont.description": "خصّص الخط المستخدم في الواجهة بأكملها",
   "settings.general.row.followup.title": "سلوك المتابعة",
diff --git a/packages/app/src/i18n/br.ts b/packages/app/src/i18n/br.ts
index a256566ca8ef..49a95f5cc802 100644
--- a/packages/app/src/i18n/br.ts
+++ b/packages/app/src/i18n/br.ts
@@ -713,6 +713,10 @@ export const dict = {
   "settings.general.row.font.description": "Personalize a fonte usada em blocos de código",
   "settings.general.row.terminalFont.title": "Fonte do terminal",
   "settings.general.row.terminalFont.description": "Personalize a fonte usada no terminal",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "Fonte da interface",
   "settings.general.row.uiFont.description": "Personalize a fonte usada em toda a interface",
   "settings.general.row.followup.title": "Comportamento de acompanhamento",
diff --git a/packages/app/src/i18n/bs.ts b/packages/app/src/i18n/bs.ts
index e786f93f6374..1961072084e3 100644
--- a/packages/app/src/i18n/bs.ts
+++ b/packages/app/src/i18n/bs.ts
@@ -778,6 +778,10 @@ export const dict = {
   "settings.general.row.font.description": "Prilagodi font koji se koristi u blokovima koda",
   "settings.general.row.terminalFont.title": "Font terminala",
   "settings.general.row.terminalFont.description": "Prilagodite font koji se koristi u terminalu",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "UI font",
   "settings.general.row.uiFont.description": "Prilagodi font koji se koristi u cijelom interfejsu",
   "settings.general.row.followup.title": "Ponašanje nadovezivanja",
diff --git a/packages/app/src/i18n/da.ts b/packages/app/src/i18n/da.ts
index 15a65144159d..7b068e3da683 100644
--- a/packages/app/src/i18n/da.ts
+++ b/packages/app/src/i18n/da.ts
@@ -773,6 +773,10 @@ export const dict = {
   "settings.general.row.font.description": "Tilpas skrifttypen, der bruges i kodeblokke",
   "settings.general.row.terminalFont.title": "Terminalskrifttype",
   "settings.general.row.terminalFont.description": "Tilpas den skrifttype, der bruges i terminalen",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "UI-skrifttype",
   "settings.general.row.uiFont.description": "Tilpas skrifttypen, der bruges i hele brugerfladen",
   "settings.general.row.followup.title": "Opfølgningsadfærd",
diff --git a/packages/app/src/i18n/de.ts b/packages/app/src/i18n/de.ts
index 5041b42ee81f..82d87e20db7f 100644
--- a/packages/app/src/i18n/de.ts
+++ b/packages/app/src/i18n/de.ts
@@ -724,6 +724,10 @@ export const dict = {
   "settings.general.row.font.description": "Die in Codeblöcken verwendete Schriftart anpassen",
   "settings.general.row.terminalFont.title": "Terminalschriftart",
   "settings.general.row.terminalFont.description": "Passe die im Terminal verwendete Schriftart an",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "UI-Schriftart",
   "settings.general.row.uiFont.description": "Die im gesamten Interface verwendete Schriftart anpassen",
   "settings.general.row.followup.title": "Verhalten bei Folgefragen",
diff --git a/packages/app/src/i18n/en.ts b/packages/app/src/i18n/en.ts
index 3b5543e15c3d..42680e12026c 100644
--- a/packages/app/src/i18n/en.ts
+++ b/packages/app/src/i18n/en.ts
@@ -862,6 +862,10 @@ export const dict = {
   "settings.general.row.colorScheme.description": "Choose whether OpenCode follows the system, light, or dark theme",
   "settings.general.row.theme.title": "Theme",
   "settings.general.row.theme.description": "Customise how OpenCode is themed.",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.font.title": "Code Font",
   "settings.general.row.font.description": "Customise the font used in code blocks",
   "settings.general.row.terminalFont.title": "Terminal Font",
diff --git a/packages/app/src/i18n/es.ts b/packages/app/src/i18n/es.ts
index a43bc1c41b94..cccdb2e9f0e3 100644
--- a/packages/app/src/i18n/es.ts
+++ b/packages/app/src/i18n/es.ts
@@ -781,6 +781,10 @@ export const dict = {
   "settings.general.row.font.description": "Personaliza la fuente usada en bloques de código",
   "settings.general.row.terminalFont.title": "Fuente del terminal",
   "settings.general.row.terminalFont.description": "Personaliza la fuente utilizada en el terminal",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "Fuente de la interfaz",
   "settings.general.row.uiFont.description": "Personaliza la fuente usada en toda la interfaz",
   "settings.general.row.followup.title": "Comportamiento de seguimiento",
diff --git a/packages/app/src/i18n/fr.ts b/packages/app/src/i18n/fr.ts
index f836b810f231..249e04ff274b 100644
--- a/packages/app/src/i18n/fr.ts
+++ b/packages/app/src/i18n/fr.ts
@@ -720,6 +720,10 @@ export const dict = {
   "settings.general.row.font.description": "Personnaliser la police utilisée dans les blocs de code",
   "settings.general.row.terminalFont.title": "Police du terminal",
   "settings.general.row.terminalFont.description": "Personnalisez la police utilisée dans le terminal",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "Police de l'interface",
   "settings.general.row.uiFont.description": "Personnaliser la police utilisée dans toute l'interface",
   "settings.general.row.followup.title": "Comportement de suivi",
diff --git a/packages/app/src/i18n/ja.ts b/packages/app/src/i18n/ja.ts
index 98692efef4f6..7dfd031f73c2 100644
--- a/packages/app/src/i18n/ja.ts
+++ b/packages/app/src/i18n/ja.ts
@@ -709,6 +709,10 @@ export const dict = {
   "settings.general.row.font.description": "コードブロックで使用するフォントをカスタマイズします",
   "settings.general.row.terminalFont.title": "ターミナルのフォント",
   "settings.general.row.terminalFont.description": "ターミナルで使用するフォントをカスタマイズ",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "UIフォント",
   "settings.general.row.uiFont.description": "インターフェース全体で使用するフォントをカスタマイズします",
   "settings.general.row.followup.title": "フォローアップの動作",
diff --git a/packages/app/src/i18n/ko.ts b/packages/app/src/i18n/ko.ts
index be27f810ad8a..e6ecae4c9f94 100644
--- a/packages/app/src/i18n/ko.ts
+++ b/packages/app/src/i18n/ko.ts
@@ -580,6 +580,10 @@ export const dict = {
   "settings.general.row.font.description": "코드 블록에 사용되는 글꼴을 사용자 지정",
   "settings.general.row.terminalFont.title": "터미널 글꼴",
   "settings.general.row.terminalFont.description": "터미널에서 사용할 글꼴을 설정합니다",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "UI 글꼴",
   "settings.general.row.uiFont.description": "인터페이스 전반에 사용되는 글꼴을 사용자 지정",
   "settings.general.row.followup.title": "후속 조치 동작",
diff --git a/packages/app/src/i18n/no.ts b/packages/app/src/i18n/no.ts
index 26029d750c5c..8ab2b32424c7 100644
--- a/packages/app/src/i18n/no.ts
+++ b/packages/app/src/i18n/no.ts
@@ -654,6 +654,10 @@ export const dict = {
   "settings.general.row.font.description": "Tilpass skrifttypen som brukes i kodeblokker",
   "settings.general.row.terminalFont.title": "Terminalskrift",
   "settings.general.row.terminalFont.description": "Tilpass skrifttypen som brukes i terminalen",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "UI-skrift",
   "settings.general.row.uiFont.description": "Tilpass skrifttypen som brukes i hele grensesnittet",
   "settings.general.row.followup.title": "Oppfølgingsadferd",
diff --git a/packages/app/src/i18n/pl.ts b/packages/app/src/i18n/pl.ts
index 8b49dcfa63a2..8f01e698b96d 100644
--- a/packages/app/src/i18n/pl.ts
+++ b/packages/app/src/i18n/pl.ts
@@ -714,6 +714,10 @@ export const dict = {
   "settings.general.row.font.description": "Dostosuj czcionkę używaną w blokach kodu",
   "settings.general.row.terminalFont.title": "Czcionka terminala",
   "settings.general.row.terminalFont.description": "Dostosuj czcionkę używaną w terminalu",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "Czcionka interfejsu",
   "settings.general.row.uiFont.description": "Dostosuj czcionkę używaną w całym interfejsie",
   "settings.general.row.followup.title": "Zachowanie kontynuacji",
diff --git a/packages/app/src/i18n/ru.ts b/packages/app/src/i18n/ru.ts
index b0bf904406b5..3e2518b5be34 100644
--- a/packages/app/src/i18n/ru.ts
+++ b/packages/app/src/i18n/ru.ts
@@ -778,6 +778,10 @@ export const dict = {
   "settings.general.row.font.description": "Настройте шрифт, используемый в блоках кода",
   "settings.general.row.terminalFont.title": "Шрифт терминала",
   "settings.general.row.terminalFont.description": "Настройте шрифт, используемый в терминале",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "Шрифт интерфейса",
   "settings.general.row.uiFont.description": "Настройте шрифт, используемый во всем интерфейсе",
   "settings.general.row.followup.title": "Поведение уточняющих вопросов",
diff --git a/packages/app/src/i18n/th.ts b/packages/app/src/i18n/th.ts
index 388921e1bcfa..352b2e01a3f2 100644
--- a/packages/app/src/i18n/th.ts
+++ b/packages/app/src/i18n/th.ts
@@ -771,6 +771,10 @@ export const dict = {
   "settings.general.row.font.description": "ปรับแต่งฟอนต์ที่ใช้ในบล็อกโค้ด",
   "settings.general.row.terminalFont.title": "ฟอนต์เทอร์มินัล",
   "settings.general.row.terminalFont.description": "ปรับแต่งฟอนต์ที่ใช้ในเทอร์มินัล",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "ฟอนต์ UI",
   "settings.general.row.uiFont.description": "ปรับแต่งฟอนต์ที่ใช้ทั่วทั้งอินเทอร์เฟซ",
   "settings.general.row.followup.title": "พฤติกรรมการติดตามผล",
diff --git a/packages/app/src/i18n/tr.ts b/packages/app/src/i18n/tr.ts
index b0295660dbfc..fb13377fd468 100644
--- a/packages/app/src/i18n/tr.ts
+++ b/packages/app/src/i18n/tr.ts
@@ -784,6 +784,10 @@ export const dict = {
   "settings.general.row.font.description": "Kod bloklarında kullanılan yazı tipini özelleştirin",
   "settings.general.row.terminalFont.title": "Terminal yazı tipi",
   "settings.general.row.terminalFont.description": "Terminalde kullanılan yazı tipini özelleştirin",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "Arayüz Yazı Tipi",
   "settings.general.row.uiFont.description": "Arayüz genelinde kullanılan yazı tipini özelleştirin",
   "settings.general.row.followup.title": "Takip davranışı",
diff --git a/packages/app/src/i18n/uk.ts b/packages/app/src/i18n/uk.ts
index 61baf625b97f..4c35ca9c39fa 100644
--- a/packages/app/src/i18n/uk.ts
+++ b/packages/app/src/i18n/uk.ts
@@ -870,6 +870,10 @@ export const dict = {
   "settings.general.row.font.description": "Налаштуйте шрифт, який використовується в блоках коду",
   "settings.general.row.terminalFont.title": "Шрифт термінала",
   "settings.general.row.terminalFont.description": "Налаштуйте шрифт, який використовується в терміналі",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "Шрифт інтерфейсу",
   "settings.general.row.uiFont.description": "Налаштуйте шрифт, який використовується в інтерфейсі",
   "settings.general.row.followup.title": "Поведінка продовження",
diff --git a/packages/app/src/i18n/zh.ts b/packages/app/src/i18n/zh.ts
index b6342e22d3e8..84eeae984311 100644
--- a/packages/app/src/i18n/zh.ts
+++ b/packages/app/src/i18n/zh.ts
@@ -768,6 +768,10 @@ export const dict = {
   "settings.general.row.font.description": "自定义代码块使用的字体",
   "settings.general.row.terminalFont.title": "终端字体",
   "settings.general.row.terminalFont.description": "自定义终端使用的字体",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "界面字体",
   "settings.general.row.uiFont.description": "自定义整个界面使用的字体",
   "settings.general.row.followup.title": "跟进消息行为",
diff --git a/packages/app/src/i18n/zht.ts b/packages/app/src/i18n/zht.ts
index 7195a5264d12..5e5be498bb51 100644
--- a/packages/app/src/i18n/zht.ts
+++ b/packages/app/src/i18n/zht.ts
@@ -763,6 +763,10 @@ export const dict = {
   "settings.general.row.font.description": "自訂程式碼區塊使用的字型",
   "settings.general.row.terminalFont.title": "終端機字型",
   "settings.general.row.terminalFont.description": "自訂終端機使用的字型",
+  "settings.general.row.backgroundImage.title": "Background image",
+  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.choose": "Choose image",
+  "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "介面字型",
   "settings.general.row.uiFont.description": "自訂整個介面使用的字型",
   "settings.general.row.followup.title": "後續追問行為",
diff --git a/packages/app/src/pages/home.tsx b/packages/app/src/pages/home.tsx
index 278032a4ca26..7875a0039694 100644
--- a/packages/app/src/pages/home.tsx
+++ b/packages/app/src/pages/home.tsx
@@ -598,7 +598,10 @@ export function NewHome() {
   }
 
   return (
-    <div class="rounded-[10px] shadow-[var(--v2-elevation-raised)] m-2 min-h-0 overflow-hidden bg-v2-background-bg-base self-stretch flex-1">
+    <div
+      data-background-surface="panel"
+      class="rounded-[10px] shadow-[var(--v2-elevation-raised)] m-2 min-h-0 overflow-hidden bg-v2-background-bg-base self-stretch flex-1"
+    >
       <ScrollView
         class="h-full [container-type:size]"
         thumbContainer={sessionThumbTrack}
diff --git a/packages/app/src/pages/layout-new.tsx b/packages/app/src/pages/layout-new.tsx
index fd0df68d2791..aca3b780906d 100644
--- a/packages/app/src/pages/layout-new.tsx
+++ b/packages/app/src/pages/layout-new.tsx
@@ -26,6 +26,7 @@ export default function NewLayout(props: ParentProps) {
 
   return (
     <div
+      data-background-surface="shell"
       class="relative bg-v2-background-bg-deep flex-1 min-h-0 min-w-0 flex flex-col select-none [&_input]:select-text [&_textarea]:select-text [&_[contenteditable]]:select-text"
       style={{
         "padding-top": "env(safe-area-inset-top, 0px)",
diff --git a/packages/app/src/pages/layout.tsx b/packages/app/src/pages/layout.tsx
index 545eee827a0b..35bf7221187e 100644
--- a/packages/app/src/pages/layout.tsx
+++ b/packages/app/src/pages/layout.tsx
@@ -2246,7 +2246,10 @@ export default function LegacyLayout(props: ParentProps) {
   )
 
   return (
-    <div class="relative bg-background-base flex-1 min-h-0 min-w-0 flex flex-col select-none [&_input]:select-text [&_textarea]:select-text [&_[contenteditable]]:select-text">
+    <div
+      data-background-surface="shell"
+      class="relative bg-background-base flex-1 min-h-0 min-w-0 flex flex-col select-none [&_input]:select-text [&_textarea]:select-text [&_[contenteditable]]:select-text"
+    >
       {autoselecting() ?? ""}
       <Titlebar update={titlebarUpdate} />
       <Show when={updateVersion() !== undefined}>
@@ -2344,6 +2347,7 @@ export default function LegacyLayout(props: ParentProps) {
               }}
             >
               <main
+                data-background-surface="content"
                 classList={{
                   "size-full overflow-x-hidden flex flex-col items-start contain-strict border-t border-border-weak-base bg-background-base xl:border-l xl:rounded-tl-[12px]": true,
                 }}
diff --git a/packages/app/src/pages/session.tsx b/packages/app/src/pages/session.tsx
index 2a0bbfde91a2..fb4c1127a546 100644
--- a/packages/app/src/pages/session.tsx
+++ b/packages/app/src/pages/session.tsx
@@ -335,6 +335,7 @@ function SessionRouteFrame(props: ParentProps<{ padded?: boolean }>) {
 function SessionPanelFrame(props: ParentProps<{ newLayout: boolean; raised?: boolean }>) {
   return (
     <div
+      data-background-surface={props.newLayout ? "panel" : undefined}
       classList={{
         "flex-1 min-h-0 flex flex-col": true,
         "bg-v2-background-bg-base": props.newLayout,
diff --git a/packages/desktop/src/main/attachment-picker.ts b/packages/desktop/src/main/attachment-picker.ts
index 52584d2c3b5f..e171b84e66ab 100644
--- a/packages/desktop/src/main/attachment-picker.ts
+++ b/packages/desktop/src/main/attachment-picker.ts
@@ -37,11 +37,18 @@ export function assertAttachmentBudget(files: { size: number }[]) {
 }
 
 export async function readAttachment(filePath: string, maxBytes = MAX_ATTACHMENT_BYTES) {
+  return readBoundedFile(
+    filePath,
+    maxBytes,
+    `Selected attachments exceed the ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MB limit`,
+  )
+}
+
+export async function readBoundedFile(filePath: string, maxBytes: number, message: string) {
   const file = await open(filePath, "r")
   try {
     const info = await file.stat()
-    if (info.size > maxBytes)
-      throw new Error(`Selected attachments exceed the ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MB limit`)
+    if (info.size > maxBytes) throw new Error(message)
     const bytes = Buffer.allocUnsafe(info.size)
     let offset = 0
     while (offset < info.size) {
diff --git a/packages/desktop/src/main/background-image.test.ts b/packages/desktop/src/main/background-image.test.ts
new file mode 100644
index 000000000000..1f892df56f8d
--- /dev/null
+++ b/packages/desktop/src/main/background-image.test.ts
@@ -0,0 +1,56 @@
+import { afterEach, expect, test } from "bun:test"
+import { mkdtemp, rm, truncate, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+import { clearBackgroundImage, findBackgroundImage, saveBackgroundImage } from "./background-image"
+
+const directories: string[] = []
+
+afterEach(async () => {
+  await Promise.all(directories.splice(0).map((directory) => rm(directory, { recursive: true, force: true })))
+})
+
+test("persists and clears a selected image", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "opencode-background-"))
+  directories.push(directory)
+  const source = join(directory, "source.png")
+  await writeFile(source, new Uint8Array([1, 2, 3]))
+
+  expect((await saveBackgroundImage(directory, source))?.mime).toBe("image/png")
+  expect((await findBackgroundImage(directory))?.path).toBe(join(directory, "background-image.png"))
+
+  await clearBackgroundImage(directory)
+  expect(await findBackgroundImage(directory)).toBeUndefined()
+})
+
+test("rejects unsupported image formats", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "opencode-background-"))
+  directories.push(directory)
+  const source = join(directory, "source.svg")
+  await writeFile(source, "<svg />")
+
+  expect(saveBackgroundImage(directory, source)).rejects.toThrow("Unsupported background image format")
+})
+
+test("replaces an existing image", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "opencode-background-"))
+  directories.push(directory)
+  const first = join(directory, "first.png")
+  const second = join(directory, "second.webp")
+  await Promise.all([writeFile(first, new Uint8Array([1])), writeFile(second, new Uint8Array([2]))])
+
+  await saveBackgroundImage(directory, first)
+  await saveBackgroundImage(directory, second)
+
+  expect((await findBackgroundImage(directory))?.mime).toBe("image/webp")
+})
+
+test("rejects images larger than 20 MB", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "opencode-background-"))
+  directories.push(directory)
+  const source = join(directory, "large.png")
+  await writeFile(source, "")
+  await truncate(source, 20 * 1024 * 1024 + 1)
+
+  expect(saveBackgroundImage(directory, source)).rejects.toThrow("Background images must be 20 MB or smaller")
+})
diff --git a/packages/desktop/src/main/background-image.ts b/packages/desktop/src/main/background-image.ts
new file mode 100644
index 000000000000..32076dc1519e
--- /dev/null
+++ b/packages/desktop/src/main/background-image.ts
@@ -0,0 +1,50 @@
+import { randomUUID } from "node:crypto"
+import { mkdir, rename, rm, stat, writeFile } from "node:fs/promises"
+import { extname, join } from "node:path"
+import { MAX_ATTACHMENT_BYTES, readBoundedFile } from "./attachment-picker"
+
+const name = "background-image"
+const mime = {
+  ".avif": "image/avif",
+  ".bmp": "image/bmp",
+  ".gif": "image/gif",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+} as const
+
+export const backgroundImageExtensions = Object.keys(mime).map((extension) => extension.slice(1))
+
+export async function findBackgroundImage(directory: string) {
+  const candidates = await Promise.all(
+    Object.entries(mime).map(async ([extension, contentType]) => {
+      const path = join(directory, `${name}${extension}`)
+      const info = await stat(path).catch(() => undefined)
+      if (!info?.isFile() || info.size > MAX_ATTACHMENT_BYTES) return
+      return { path, mime: contentType, revision: `${info.mtimeMs}-${info.size}`, modified: info.mtimeMs }
+    }),
+  )
+  return candidates.filter((candidate) => candidate !== undefined).sort((a, b) => b.modified - a.modified)[0]
+}
+
+export async function saveBackgroundImage(directory: string, path: string) {
+  const extension = extname(path).toLowerCase() as keyof typeof mime
+  if (!mime[extension]) throw new Error("Unsupported background image format")
+  const data = await readBoundedFile(path, MAX_ATTACHMENT_BYTES, "Background images must be 20 MB or smaller")
+  await mkdir(directory, { recursive: true })
+  const target = join(directory, `${name}${extension}`)
+  const temporary = join(directory, `.${name}-${randomUUID()}`)
+  await writeFile(temporary, new Uint8Array(data))
+  await rename(temporary, target).finally(() => rm(temporary, { force: true }))
+  await Promise.all(
+    Object.keys(mime)
+      .filter((candidate) => candidate !== extension)
+      .map((candidate) => rm(join(directory, `${name}${candidate}`), { force: true })),
+  )
+  return findBackgroundImage(directory)
+}
+
+export async function clearBackgroundImage(directory: string) {
+  await Promise.all(Object.keys(mime).map((extension) => rm(join(directory, `${name}${extension}`), { force: true })))
+}
diff --git a/packages/desktop/src/main/ipc.ts b/packages/desktop/src/main/ipc.ts
index 1103401c492b..d9c6e30b29db 100644
--- a/packages/desktop/src/main/ipc.ts
+++ b/packages/desktop/src/main/ipc.ts
@@ -8,6 +8,12 @@ import type { DesktopMenuAction } from "@opencode-ai/app/desktop-menu"
 import type { FatalRendererError, ServerReadyData, TitlebarTheme } from "../preload/types"
 import { runDesktopMenuAction } from "./desktop-menu-actions"
 import { assertAttachmentBudget, createPickedFileAuthorizations } from "./attachment-picker"
+import {
+  backgroundImageExtensions,
+  clearBackgroundImage,
+  findBackgroundImage,
+  saveBackgroundImage,
+} from "./background-image"
 import { getStore, removeStoreFileIfEmpty } from "./store"
 import { getPinchZoomEnabled, getWindowID, setPinchZoomEnabled, setTitlebar, updateTitlebar } from "./windows"
 import type { UpdaterController } from "./updater-controller"
@@ -80,6 +86,29 @@ export function registerIpcHandlers(deps: Deps) {
   ipcMain.handle("updater-check", () => deps.updater.check())
   ipcMain.handle("updater-install", () => deps.updater.install())
   ipcMain.handle("set-background-color", (_event: IpcMainInvokeEvent, color: string) => deps.setBackgroundColor(color))
+  const backgroundImageState = async () => {
+    const image = await findBackgroundImage(app.getPath("userData"))
+    return image ? { revision: image.revision } : null
+  }
+  const publishBackgroundImage = (state: { revision: string } | null) => {
+    BrowserWindow.getAllWindows().forEach((win) => win.webContents.send("background-image-changed", state))
+    return state
+  }
+  ipcMain.handle("load-background-image", backgroundImageState)
+  ipcMain.handle("select-background-image", async () => {
+    const result = await dialog.showOpenDialog({
+      properties: ["openFile"],
+      title: "Choose a background image",
+      filters: [{ name: "Images", extensions: backgroundImageExtensions }],
+    })
+    if (result.canceled || !result.filePaths[0]) return null
+    await saveBackgroundImage(app.getPath("userData"), result.filePaths[0])
+    return publishBackgroundImage(await backgroundImageState())
+  })
+  ipcMain.handle("clear-background-image", async () => {
+    await clearBackgroundImage(app.getPath("userData"))
+    publishBackgroundImage(null)
+  })
   ipcMain.handle("export-debug-logs", () => deps.exportDebugLogs())
   ipcMain.handle("record-fatal-renderer-error", (_event: IpcMainInvokeEvent, error: FatalRendererError) =>
     deps.recordFatalRendererError(error),
diff --git a/packages/desktop/src/main/windows.ts b/packages/desktop/src/main/windows.ts
index 693690c9c455..61ce34f1954b 100644
--- a/packages/desktop/src/main/windows.ts
+++ b/packages/desktop/src/main/windows.ts
@@ -9,6 +9,7 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path"
 import { fileURLToPath, pathToFileURL } from "node:url"
 import type { TitlebarTheme } from "../preload/types"
 import { exportDebugLogs, write as writeLog } from "./logging"
+import { findBackgroundImage } from "./background-image"
 import { getStore, removeStoreFile } from "./store"
 import { PINCH_ZOOM_ENABLED_KEY, WINDOW_IDS_KEY } from "./store-keys"
 import { createUnresponsiveSampler } from "./unresponsive"
@@ -259,6 +260,12 @@ export function registerRendererProtocol() {
       return new Response("Not found", { status: 404 })
     }
 
+    if (url.pathname === "/background-image") {
+      const image = await findBackgroundImage(app.getPath("userData"))
+      if (!image) return new Response("Not found", { status: 404 })
+      return net.fetch(pathToFileURL(image.path).toString())
+    }
+
     const file = resolve(rendererRoot, `.${decodeURIComponent(url.pathname)}`)
     const rel = relative(rendererRoot, file)
     if (rel.startsWith("..") || isAbsolute(rel)) {
diff --git a/packages/desktop/src/preload/index.ts b/packages/desktop/src/preload/index.ts
index d14dd0d00a22..e41ae550a89d 100644
--- a/packages/desktop/src/preload/index.ts
+++ b/packages/desktop/src/preload/index.ts
@@ -120,6 +120,14 @@ const api: ElectronAPI = {
   setTitlebar: (theme) => ipcRenderer.invoke("set-titlebar", theme),
   runDesktopMenuAction: (action) => ipcRenderer.invoke("run-desktop-menu-action", action),
   setBackgroundColor: (color: string) => ipcRenderer.invoke("set-background-color", color),
+  loadBackgroundImage: () => ipcRenderer.invoke("load-background-image"),
+  selectBackgroundImage: () => ipcRenderer.invoke("select-background-image"),
+  clearBackgroundImage: () => ipcRenderer.invoke("clear-background-image"),
+  onBackgroundImageChanged: (cb) => {
+    const handler = (_: unknown, image: Parameters<typeof cb>[0]) => cb(image)
+    ipcRenderer.on("background-image-changed", handler)
+    return () => ipcRenderer.removeListener("background-image-changed", handler)
+  },
   exportDebugLogs: () => ipcRenderer.invoke("export-debug-logs"),
   recordFatalRendererError: (error) => ipcRenderer.invoke("record-fatal-renderer-error", error),
 }
diff --git a/packages/desktop/src/preload/types.ts b/packages/desktop/src/preload/types.ts
index da10f7008def..350b8d62820d 100644
--- a/packages/desktop/src/preload/types.ts
+++ b/packages/desktop/src/preload/types.ts
@@ -41,6 +41,10 @@ export type FatalRendererError = {
   os?: string
 }
 
+export type BackgroundImage = {
+  revision: string
+}
+
 export type ElectronAPI = {
   killSidecar: () => Promise<void>
   installCli: () => Promise<string>
@@ -103,6 +107,10 @@ export type ElectronAPI = {
   setTitlebar: (theme: TitlebarTheme) => Promise<void>
   runDesktopMenuAction: (action: DesktopMenuAction) => Promise<void>
   setBackgroundColor: (color: string) => Promise<void>
+  loadBackgroundImage: () => Promise<BackgroundImage | null>
+  selectBackgroundImage: () => Promise<BackgroundImage | null>
+  clearBackgroundImage: () => Promise<void>
+  onBackgroundImageChanged: (cb: (image: BackgroundImage | null) => void) => () => void
   exportDebugLogs: () => Promise<string>
   recordFatalRendererError: (error: FatalRendererError) => Promise<void>
 }
diff --git a/packages/desktop/src/renderer/index.tsx b/packages/desktop/src/renderer/index.tsx
index 13c122cb2ecb..e178173d010c 100644
--- a/packages/desktop/src/renderer/index.tsx
+++ b/packages/desktop/src/renderer/index.tsx
@@ -112,6 +112,21 @@ function DesktopMemoryRouter(props: BaseRouterProps & { windowID: string }) {
 
 const createPlatform = (windowState: DesktopWindowState): Platform => {
   const attachmentPaths = new WeakMap<File, string>()
+  const [backgroundImage, setBackgroundImage] = createSignal(false)
+  const applyBackgroundImage = (image: Awaited<ReturnType<typeof window.api.loadBackgroundImage>>) => {
+    setBackgroundImage(!!image)
+    document.documentElement.toggleAttribute("data-background-image", !!image)
+    if (image) {
+      document.documentElement.style.setProperty(
+        "--desktop-background-image",
+        `url("oc://renderer/background-image?revision=${encodeURIComponent(image.revision)}")`,
+      )
+      return true
+    }
+    document.documentElement.style.removeProperty("--desktop-background-image")
+    return false
+  }
+  window.api.onBackgroundImageChanged(applyBackgroundImage)
   const os = (() => {
     const ua = navigator.userAgent
     if (ua.includes("Mac")) return "macos"
@@ -310,6 +325,23 @@ const createPlatform = (windowState: DesktopWindowState): Platform => {
         type: "image/png",
       })
     },
+
+    async loadBackgroundImage() {
+      return applyBackgroundImage(await window.api.loadBackgroundImage())
+    },
+
+    async selectBackgroundImage() {
+      const image = await window.api.selectBackgroundImage()
+      if (!image) return backgroundImage()
+      return applyBackgroundImage(image)
+    },
+
+    async clearBackgroundImage() {
+      await window.api.clearBackgroundImage()
+      applyBackgroundImage(null)
+    },
+
+    backgroundImage,
   }
 }
 
@@ -329,6 +361,7 @@ function LoadingSplash() {
 
 function DesktopRoot(props: { windowState: DesktopWindowState }) {
   const platform = createPlatform(props.windowState)
+  void platform.loadBackgroundImage?.()
   const loadLocale = async () => {
     const current = await platform.storage?.("opencode.global.dat").getItem("language")
     const legacy = current ? undefined : await platform.storage?.().getItem("language.v1")
diff --git a/packages/desktop/src/renderer/styles.css b/packages/desktop/src/renderer/styles.css
index e69de29bb2d1..0b485ed0f337 100644
--- a/packages/desktop/src/renderer/styles.css
+++ b/packages/desktop/src/renderer/styles.css
@@ -0,0 +1,18 @@
+html[data-background-image] body {
+  background-image: linear-gradient(rgb(0 0 0 / 18%), rgb(0 0 0 / 18%)), var(--desktop-background-image);
+  background-position: center;
+  background-repeat: no-repeat;
+  background-size: cover;
+}
+
+html[data-background-image] [data-background-surface="shell"] {
+  background-color: transparent !important;
+}
+
+html[data-background-image] [data-background-surface="content"] {
+  background-color: color-mix(in srgb, var(--background-base) 76%, transparent) !important;
+}
+
+html[data-background-image] [data-background-surface="panel"] {
+  background-color: color-mix(in srgb, var(--v2-background-bg-base) 70%, transparent) !important;
+}

From 364e2d9f03412710e79f79a1d5d06f7545e91eb6 Mon Sep 17 00:00:00 2001
From: Brendan Allan <14191578+Brendonovich@users.noreply.github.com>
Date: Mon, 20 Jul 2026 16:19:59 +0000
Subject: [PATCH 2/8] feat(app): support web image backgrounds

---
 packages/app/src/context/platform.tsx         |  8 ++--
 packages/app/src/entry.tsx                    | 37 +++++++++++++++++++
 packages/app/src/i18n/ar.ts                   |  2 +-
 packages/app/src/i18n/br.ts                   |  2 +-
 packages/app/src/i18n/bs.ts                   |  2 +-
 packages/app/src/i18n/da.ts                   |  2 +-
 packages/app/src/i18n/de.ts                   |  2 +-
 packages/app/src/i18n/en.ts                   |  2 +-
 packages/app/src/i18n/es.ts                   |  2 +-
 packages/app/src/i18n/fr.ts                   |  2 +-
 packages/app/src/i18n/ja.ts                   |  2 +-
 packages/app/src/i18n/ko.ts                   |  2 +-
 packages/app/src/i18n/no.ts                   |  2 +-
 packages/app/src/i18n/pl.ts                   |  2 +-
 packages/app/src/i18n/ru.ts                   |  2 +-
 packages/app/src/i18n/th.ts                   |  2 +-
 packages/app/src/i18n/tr.ts                   |  2 +-
 packages/app/src/i18n/uk.ts                   |  2 +-
 packages/app/src/i18n/zh.ts                   |  2 +-
 packages/app/src/i18n/zht.ts                  |  2 +-
 packages/app/src/index.css                    | 24 ++++++++++++
 .../app/src/utils/web-background-image.ts     | 33 +++++++++++++++++
 packages/desktop/src/renderer/index.tsx       |  4 +-
 packages/desktop/src/renderer/styles.css      | 18 ---------
 24 files changed, 118 insertions(+), 42 deletions(-)
 create mode 100644 packages/app/src/utils/web-background-image.ts

diff --git a/packages/app/src/context/platform.tsx b/packages/app/src/context/platform.tsx
index f511e94ec60f..c9effb2fc127 100644
--- a/packages/app/src/context/platform.tsx
+++ b/packages/app/src/context/platform.tsx
@@ -112,16 +112,16 @@ type PlatformBase = {
   /** Read image from clipboard (desktop only) */
   readClipboardImage?(): Promise<File | null>
 
-  /** Load and apply the saved desktop background image. */
+  /** Load and apply the saved app background image. */
   loadBackgroundImage?(): Promise<boolean>
 
-  /** Whether the desktop currently has a background image. */
+  /** Whether the app currently has a background image. */
   backgroundImage?: Accessor<boolean>
 
-  /** Select and apply a desktop background image. */
+  /** Select and apply an app background image. */
   selectBackgroundImage?(): Promise<boolean>
 
-  /** Clear the saved desktop background image. */
+  /** Clear the saved app background image. */
   clearBackgroundImage?(): Promise<void>
 
   /** Export collected diagnostic logs (desktop only) */
diff --git a/packages/app/src/entry.tsx b/packages/app/src/entry.tsx
index c41c1bb4b63e..96c092bf6b60 100644
--- a/packages/app/src/entry.tsx
+++ b/packages/app/src/entry.tsx
@@ -1,6 +1,7 @@
 // @refresh reload
 
 import * as Sentry from "@sentry/solid"
+import { createSignal } from "solid-js"
 import { render } from "solid-js/web"
 import { AppBaseProviders, AppInterface } from "@/app"
 import { type Platform, PlatformProvider } from "@/context/platform"
@@ -8,6 +9,12 @@ import { dict as en } from "@/i18n/en"
 import { dict as zh } from "@/i18n/zh"
 import { handleNotificationClick } from "@/utils/notification-click"
 import { authFromToken } from "@/utils/server"
+import {
+  clearWebBackgroundImage,
+  loadWebBackgroundImage,
+  saveWebBackgroundImage,
+  selectWebBackgroundImage,
+} from "@/utils/web-background-image"
 import pkg from "../package.json"
 import { ServerConnection } from "./context/server"
 
@@ -119,6 +126,21 @@ const clearAuthToken = () => {
   history.replaceState(null, "", location.pathname + (params.size ? `?${params}` : "") + location.hash)
 }
 
+const [backgroundImage, setBackgroundImage] = createSignal(false)
+let backgroundImageUrl: string | undefined
+const applyBackgroundImage = (image: Blob | null) => {
+  if (backgroundImageUrl) URL.revokeObjectURL(backgroundImageUrl)
+  backgroundImageUrl = image ? URL.createObjectURL(image) : undefined
+  setBackgroundImage(!!backgroundImageUrl)
+  document.documentElement.toggleAttribute("data-background-image", !!backgroundImageUrl)
+  if (backgroundImageUrl) {
+    document.documentElement.style.setProperty("--app-background-image", `url("${backgroundImageUrl}")`)
+    return true
+  }
+  document.documentElement.style.removeProperty("--app-background-image")
+  return false
+}
+
 const platform: Platform = {
   platform: "web",
   version: pkg.version,
@@ -132,8 +154,23 @@ const platform: Platform = {
     return stored ? ServerConnection.Key.make(stored) : null
   },
   setDefaultServer: writeDefaultServerUrl,
+  backgroundImage,
+  async loadBackgroundImage() {
+    return applyBackgroundImage(await loadWebBackgroundImage())
+  },
+  async selectBackgroundImage() {
+    const file = await selectWebBackgroundImage()
+    if (!file) return backgroundImage()
+    return applyBackgroundImage(await saveWebBackgroundImage(file))
+  },
+  async clearBackgroundImage() {
+    await clearWebBackgroundImage()
+    applyBackgroundImage(null)
+  },
 }
 
+void platform.loadBackgroundImage?.()
+
 if (import.meta.env.VITE_SENTRY_DSN) {
   Sentry.init({
     dsn: import.meta.env.VITE_SENTRY_DSN,
diff --git a/packages/app/src/i18n/ar.ts b/packages/app/src/i18n/ar.ts
index ca8d0b1fecc1..397fcbd7ffa0 100644
--- a/packages/app/src/i18n/ar.ts
+++ b/packages/app/src/i18n/ar.ts
@@ -705,7 +705,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "خط الطرفية",
   "settings.general.row.terminalFont.description": "خصّص الخط المستخدم في الطرفية",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "خط الواجهة",
diff --git a/packages/app/src/i18n/br.ts b/packages/app/src/i18n/br.ts
index 49a95f5cc802..019221d36c73 100644
--- a/packages/app/src/i18n/br.ts
+++ b/packages/app/src/i18n/br.ts
@@ -714,7 +714,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "Fonte do terminal",
   "settings.general.row.terminalFont.description": "Personalize a fonte usada no terminal",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "Fonte da interface",
diff --git a/packages/app/src/i18n/bs.ts b/packages/app/src/i18n/bs.ts
index 1961072084e3..463e58f0a8e4 100644
--- a/packages/app/src/i18n/bs.ts
+++ b/packages/app/src/i18n/bs.ts
@@ -779,7 +779,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "Font terminala",
   "settings.general.row.terminalFont.description": "Prilagodite font koji se koristi u terminalu",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "UI font",
diff --git a/packages/app/src/i18n/da.ts b/packages/app/src/i18n/da.ts
index 7b068e3da683..2d9b339bba68 100644
--- a/packages/app/src/i18n/da.ts
+++ b/packages/app/src/i18n/da.ts
@@ -774,7 +774,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "Terminalskrifttype",
   "settings.general.row.terminalFont.description": "Tilpas den skrifttype, der bruges i terminalen",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "UI-skrifttype",
diff --git a/packages/app/src/i18n/de.ts b/packages/app/src/i18n/de.ts
index 82d87e20db7f..cdf3f0467002 100644
--- a/packages/app/src/i18n/de.ts
+++ b/packages/app/src/i18n/de.ts
@@ -725,7 +725,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "Terminalschriftart",
   "settings.general.row.terminalFont.description": "Passe die im Terminal verwendete Schriftart an",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "UI-Schriftart",
diff --git a/packages/app/src/i18n/en.ts b/packages/app/src/i18n/en.ts
index 42680e12026c..f99d5b61afce 100644
--- a/packages/app/src/i18n/en.ts
+++ b/packages/app/src/i18n/en.ts
@@ -863,7 +863,7 @@ export const dict = {
   "settings.general.row.theme.title": "Theme",
   "settings.general.row.theme.description": "Customise how OpenCode is themed.",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.font.title": "Code Font",
diff --git a/packages/app/src/i18n/es.ts b/packages/app/src/i18n/es.ts
index cccdb2e9f0e3..91c3b9bf9cd4 100644
--- a/packages/app/src/i18n/es.ts
+++ b/packages/app/src/i18n/es.ts
@@ -782,7 +782,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "Fuente del terminal",
   "settings.general.row.terminalFont.description": "Personaliza la fuente utilizada en el terminal",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "Fuente de la interfaz",
diff --git a/packages/app/src/i18n/fr.ts b/packages/app/src/i18n/fr.ts
index 249e04ff274b..67b13eb091e6 100644
--- a/packages/app/src/i18n/fr.ts
+++ b/packages/app/src/i18n/fr.ts
@@ -721,7 +721,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "Police du terminal",
   "settings.general.row.terminalFont.description": "Personnalisez la police utilisée dans le terminal",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "Police de l'interface",
diff --git a/packages/app/src/i18n/ja.ts b/packages/app/src/i18n/ja.ts
index 7dfd031f73c2..79d036cb9a2b 100644
--- a/packages/app/src/i18n/ja.ts
+++ b/packages/app/src/i18n/ja.ts
@@ -710,7 +710,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "ターミナルのフォント",
   "settings.general.row.terminalFont.description": "ターミナルで使用するフォントをカスタマイズ",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "UIフォント",
diff --git a/packages/app/src/i18n/ko.ts b/packages/app/src/i18n/ko.ts
index e6ecae4c9f94..610ad04ca384 100644
--- a/packages/app/src/i18n/ko.ts
+++ b/packages/app/src/i18n/ko.ts
@@ -581,7 +581,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "터미널 글꼴",
   "settings.general.row.terminalFont.description": "터미널에서 사용할 글꼴을 설정합니다",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "UI 글꼴",
diff --git a/packages/app/src/i18n/no.ts b/packages/app/src/i18n/no.ts
index 8ab2b32424c7..3d1484fd7a0d 100644
--- a/packages/app/src/i18n/no.ts
+++ b/packages/app/src/i18n/no.ts
@@ -655,7 +655,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "Terminalskrift",
   "settings.general.row.terminalFont.description": "Tilpass skrifttypen som brukes i terminalen",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "UI-skrift",
diff --git a/packages/app/src/i18n/pl.ts b/packages/app/src/i18n/pl.ts
index 8f01e698b96d..1a4a35de1c98 100644
--- a/packages/app/src/i18n/pl.ts
+++ b/packages/app/src/i18n/pl.ts
@@ -715,7 +715,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "Czcionka terminala",
   "settings.general.row.terminalFont.description": "Dostosuj czcionkę używaną w terminalu",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "Czcionka interfejsu",
diff --git a/packages/app/src/i18n/ru.ts b/packages/app/src/i18n/ru.ts
index 3e2518b5be34..16465b75a6fa 100644
--- a/packages/app/src/i18n/ru.ts
+++ b/packages/app/src/i18n/ru.ts
@@ -779,7 +779,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "Шрифт терминала",
   "settings.general.row.terminalFont.description": "Настройте шрифт, используемый в терминале",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "Шрифт интерфейса",
diff --git a/packages/app/src/i18n/th.ts b/packages/app/src/i18n/th.ts
index 352b2e01a3f2..865579ef74ab 100644
--- a/packages/app/src/i18n/th.ts
+++ b/packages/app/src/i18n/th.ts
@@ -772,7 +772,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "ฟอนต์เทอร์มินัล",
   "settings.general.row.terminalFont.description": "ปรับแต่งฟอนต์ที่ใช้ในเทอร์มินัล",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "ฟอนต์ UI",
diff --git a/packages/app/src/i18n/tr.ts b/packages/app/src/i18n/tr.ts
index fb13377fd468..c733af6cde1f 100644
--- a/packages/app/src/i18n/tr.ts
+++ b/packages/app/src/i18n/tr.ts
@@ -785,7 +785,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "Terminal yazı tipi",
   "settings.general.row.terminalFont.description": "Terminalde kullanılan yazı tipini özelleştirin",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "Arayüz Yazı Tipi",
diff --git a/packages/app/src/i18n/uk.ts b/packages/app/src/i18n/uk.ts
index 4c35ca9c39fa..1b558dd8d24a 100644
--- a/packages/app/src/i18n/uk.ts
+++ b/packages/app/src/i18n/uk.ts
@@ -871,7 +871,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "Шрифт термінала",
   "settings.general.row.terminalFont.description": "Налаштуйте шрифт, який використовується в терміналі",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "Шрифт інтерфейсу",
diff --git a/packages/app/src/i18n/zh.ts b/packages/app/src/i18n/zh.ts
index 84eeae984311..cfb686b71af3 100644
--- a/packages/app/src/i18n/zh.ts
+++ b/packages/app/src/i18n/zh.ts
@@ -769,7 +769,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "终端字体",
   "settings.general.row.terminalFont.description": "自定义终端使用的字体",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "界面字体",
diff --git a/packages/app/src/i18n/zht.ts b/packages/app/src/i18n/zht.ts
index 5e5be498bb51..8a1c6fdfa180 100644
--- a/packages/app/src/i18n/zht.ts
+++ b/packages/app/src/i18n/zht.ts
@@ -764,7 +764,7 @@ export const dict = {
   "settings.general.row.terminalFont.title": "終端機字型",
   "settings.general.row.terminalFont.description": "自訂終端機使用的字型",
   "settings.general.row.backgroundImage.title": "Background image",
-  "settings.general.row.backgroundImage.description": "Choose an image for the desktop background.",
+  "settings.general.row.backgroundImage.description": "Choose an image for the app background.",
   "settings.general.row.backgroundImage.choose": "Choose image",
   "settings.general.row.backgroundImage.remove": "Remove",
   "settings.general.row.uiFont.title": "介面字型",
diff --git a/packages/app/src/index.css b/packages/app/src/index.css
index 78a9e103a7f5..08da436ae966 100644
--- a/packages/app/src/index.css
+++ b/packages/app/src/index.css
@@ -3,6 +3,30 @@
 @import "@opencode-ai/ui/v2/styles/tailwind.css";
 @import "tw-animate-css";
 
+html[data-background-image] body {
+  background-image: linear-gradient(rgb(0 0 0 / 12%), rgb(0 0 0 / 12%)), var(--app-background-image);
+  background-color: transparent !important;
+  background-position: center;
+  background-repeat: no-repeat;
+  background-size: cover;
+}
+
+html[data-background-image] #root {
+  background-color: transparent !important;
+}
+
+html[data-background-image] [data-background-surface="shell"] {
+  background-color: transparent !important;
+}
+
+html[data-background-image] [data-background-surface="content"] {
+  background-color: color-mix(in srgb, var(--background-base) 68%, transparent) !important;
+}
+
+html[data-background-image] [data-background-surface="panel"] {
+  background-color: color-mix(in srgb, var(--v2-background-bg-base) 56%, transparent) !important;
+}
+
 @font-face {
   font-family: "JetBrainsMono Nerd Font Mono";
   src: url("/assets/JetBrainsMonoNerdFontMono-Regular.woff2") format("woff2");
diff --git a/packages/app/src/utils/web-background-image.ts b/packages/app/src/utils/web-background-image.ts
new file mode 100644
index 000000000000..89e497cf1718
--- /dev/null
+++ b/packages/app/src/utils/web-background-image.ts
@@ -0,0 +1,33 @@
+const cacheName = "opencode-background-image-v1"
+const maxBytes = 20 * 1024 * 1024
+
+function key() {
+  return new URL("/__opencode/background-image", location.origin).toString()
+}
+
+export async function loadWebBackgroundImage() {
+  const response = await (await caches.open(cacheName)).match(key())
+  return response?.blob() ?? null
+}
+
+export async function saveWebBackgroundImage(file: File) {
+  if (!file.type.startsWith("image/")) throw new Error("Unsupported background image format")
+  if (file.size > maxBytes) throw new Error("Background images must be 20 MB or smaller")
+  await (await caches.open(cacheName)).put(key(), new Response(file, { headers: { "Content-Type": file.type } }))
+  return file
+}
+
+export async function clearWebBackgroundImage() {
+  await (await caches.open(cacheName)).delete(key())
+}
+
+export function selectWebBackgroundImage() {
+  return new Promise<File | null>((resolve) => {
+    const input = document.createElement("input")
+    input.type = "file"
+    input.accept = "image/avif,image/bmp,image/gif,image/jpeg,image/png,image/webp"
+    input.onchange = () => resolve(input.files?.[0] ?? null)
+    input.oncancel = () => resolve(null)
+    input.click()
+  })
+}
diff --git a/packages/desktop/src/renderer/index.tsx b/packages/desktop/src/renderer/index.tsx
index e178173d010c..55f164d8e8ba 100644
--- a/packages/desktop/src/renderer/index.tsx
+++ b/packages/desktop/src/renderer/index.tsx
@@ -118,12 +118,12 @@ const createPlatform = (windowState: DesktopWindowState): Platform => {
     document.documentElement.toggleAttribute("data-background-image", !!image)
     if (image) {
       document.documentElement.style.setProperty(
-        "--desktop-background-image",
+        "--app-background-image",
         `url("oc://renderer/background-image?revision=${encodeURIComponent(image.revision)}")`,
       )
       return true
     }
-    document.documentElement.style.removeProperty("--desktop-background-image")
+    document.documentElement.style.removeProperty("--app-background-image")
     return false
   }
   window.api.onBackgroundImageChanged(applyBackgroundImage)
diff --git a/packages/desktop/src/renderer/styles.css b/packages/desktop/src/renderer/styles.css
index 0b485ed0f337..e69de29bb2d1 100644
--- a/packages/desktop/src/renderer/styles.css
+++ b/packages/desktop/src/renderer/styles.css
@@ -1,18 +0,0 @@
-html[data-background-image] body {
-  background-image: linear-gradient(rgb(0 0 0 / 18%), rgb(0 0 0 / 18%)), var(--desktop-background-image);
-  background-position: center;
-  background-repeat: no-repeat;
-  background-size: cover;
-}
-
-html[data-background-image] [data-background-surface="shell"] {
-  background-color: transparent !important;
-}
-
-html[data-background-image] [data-background-surface="content"] {
-  background-color: color-mix(in srgb, var(--background-base) 76%, transparent) !important;
-}
-
-html[data-background-image] [data-background-surface="panel"] {
-  background-color: color-mix(in srgb, var(--v2-background-bg-base) 70%, transparent) !important;
-}

From d881c1c4764da4f3af4607dcaf49a85958f5839f Mon Sep 17 00:00:00 2001
From: Brendan Allan <14191578+Brendonovich@users.noreply.github.com>
Date: Mon, 20 Jul 2026 16:53:40 +0000
Subject: [PATCH 3/8] fix(app): make background prompt translucent

---
 packages/app/src/components/prompt-input.tsx | 1 +
 packages/app/src/index.css                   | 5 +++++
 2 files changed, 6 insertions(+)

diff --git a/packages/app/src/components/prompt-input.tsx b/packages/app/src/components/prompt-input.tsx
index a820067a4e74..2811247c5ee4 100644
--- a/packages/app/src/components/prompt-input.tsx
+++ b/packages/app/src/components/prompt-input.tsx
@@ -1615,6 +1615,7 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
           <div class="flex flex-col gap-3">
             <DockShellForm
               data-component={newSession() ? "session-new-composer" : "session-composer"}
+              data-background-surface="prompt"
               onSubmit={handleSubmit}
               classList={{
                 "group/prompt-input min-h-[96px] w-full rounded-xl bg-v2-background-bg-base shadow-[var(--v2-elevation-raised)]": true,
diff --git a/packages/app/src/index.css b/packages/app/src/index.css
index 08da436ae966..afcfbcb7b949 100644
--- a/packages/app/src/index.css
+++ b/packages/app/src/index.css
@@ -27,6 +27,11 @@ html[data-background-image] [data-background-surface="panel"] {
   background-color: color-mix(in srgb, var(--v2-background-bg-base) 56%, transparent) !important;
 }
 
+html[data-background-image] [data-background-surface="prompt"] {
+  background-color: color-mix(in srgb, var(--v2-background-bg-base) 68%, transparent) !important;
+  backdrop-filter: blur(16px);
+}
+
 @font-face {
   font-family: "JetBrainsMono Nerd Font Mono";
   src: url("/assets/JetBrainsMonoNerdFontMono-Regular.woff2") format("woff2");

From 5452a13e07f832ade1c2344221c040e6b466af26 Mon Sep 17 00:00:00 2001
From: Brendan Allan <14191578+Brendonovich@users.noreply.github.com>
Date: Mon, 20 Jul 2026 23:43:41 +0000
Subject: [PATCH 4/8] fix(app): refine background contrast

---
 packages/app/src/components/prompt-project-selector.tsx   | 2 ++
 .../src/components/session/session-new-design-view.tsx    | 2 +-
 packages/app/src/index.css                                | 8 +++++++-
 3 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/packages/app/src/components/prompt-project-selector.tsx b/packages/app/src/components/prompt-project-selector.tsx
index 45d0371fda58..ff0fc920bc4c 100644
--- a/packages/app/src/components/prompt-project-selector.tsx
+++ b/packages/app/src/components/prompt-project-selector.tsx
@@ -446,6 +446,7 @@ export function PromptProjectAddButton(props: { controller: PromptProjectControl
   return (
     <button
       data-action="prompt-project"
+      data-background-surface="project-selector"
       type="button"
       class="flex h-7 min-w-0 max-w-[160px] items-center gap-1.5 rounded-sm px-2 text-[13px] font-[440] leading-5 tracking-[-0.04px] text-v2-text-text-faint transition-colors hover:bg-v2-overlay-simple-overlay-hover focus-visible:bg-v2-overlay-simple-overlay-hover focus-visible:outline-none"
       onClick={() => props.controller.add()}
@@ -464,6 +465,7 @@ function ProjectTrigger(props: ComponentProps<"button"> & { controller: PromptPr
     <button
       {...rest}
       data-action="prompt-project"
+      data-background-surface="project-selector"
       type="button"
       class="flex h-7 min-w-0 max-w-[203px] items-center gap-1.5 rounded-sm px-1.5 transition-colors focus-visible:bg-v2-overlay-simple-overlay-hover focus-visible:outline-none"
       classList={{
diff --git a/packages/app/src/components/session/session-new-design-view.tsx b/packages/app/src/components/session/session-new-design-view.tsx
index 3925d568c5c7..35862a75f58d 100644
--- a/packages/app/src/components/session/session-new-design-view.tsx
+++ b/packages/app/src/components/session/session-new-design-view.tsx
@@ -11,7 +11,7 @@ export function NewSessionDesignView(props: { children: JSX.Element }) {
     >
       <div class="absolute inset-x-0 top-[25.375%] flex justify-center px-6">
         <div class={NEW_SESSION_CONTENT_WIDTH}>
-          <WordmarkV2 class="h-auto w-full text-v2-background-bg-inverse" />
+          <WordmarkV2 class="h-auto w-full text-v2-background-bg-inverse [&>g>g>g]:!opacity-30" />
           <div class="mt-8">{props.children}</div>
         </div>
       </div>
diff --git a/packages/app/src/index.css b/packages/app/src/index.css
index afcfbcb7b949..5af8603296f5 100644
--- a/packages/app/src/index.css
+++ b/packages/app/src/index.css
@@ -4,7 +4,7 @@
 @import "tw-animate-css";
 
 html[data-background-image] body {
-  background-image: linear-gradient(rgb(0 0 0 / 12%), rgb(0 0 0 / 12%)), var(--app-background-image);
+  background-image: linear-gradient(rgb(0 0 0 / 20%), rgb(0 0 0 / 20%)), var(--app-background-image);
   background-color: transparent !important;
   background-position: center;
   background-repeat: no-repeat;
@@ -32,6 +32,12 @@ html[data-background-image] [data-background-surface="prompt"] {
   backdrop-filter: blur(16px);
 }
 
+html[data-background-image] [data-background-surface="project-selector"] {
+  background-color: color-mix(in srgb, var(--v2-background-bg-base) 68%, transparent) !important;
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--v2-border-border-base) 70%, transparent);
+  backdrop-filter: blur(16px);
+}
+
 @font-face {
   font-family: "JetBrainsMono Nerd Font Mono";
   src: url("/assets/JetBrainsMonoNerdFontMono-Regular.woff2") format("woff2");

From 6fb632eeb657432bcf5e5585ee9b0b16cbb709c5 Mon Sep 17 00:00:00 2001
From: Brendan Allan <14191578+Brendonovich@users.noreply.github.com>
Date: Mon, 20 Jul 2026 23:47:03 +0000
Subject: [PATCH 5/8] fix(app): tune background presentation

---
 .../src/components/session/session-new-design-view.tsx    | 2 +-
 packages/app/src/index.css                                | 8 +++++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/packages/app/src/components/session/session-new-design-view.tsx b/packages/app/src/components/session/session-new-design-view.tsx
index 35862a75f58d..ad59d2fb53c0 100644
--- a/packages/app/src/components/session/session-new-design-view.tsx
+++ b/packages/app/src/components/session/session-new-design-view.tsx
@@ -11,7 +11,7 @@ export function NewSessionDesignView(props: { children: JSX.Element }) {
     >
       <div class="absolute inset-x-0 top-[25.375%] flex justify-center px-6">
         <div class={NEW_SESSION_CONTENT_WIDTH}>
-          <WordmarkV2 class="h-auto w-full text-v2-background-bg-inverse [&>g>g>g]:!opacity-30" />
+          <WordmarkV2 class="h-auto w-full text-v2-background-bg-inverse [&>g>g>g]:!opacity-[0.45]" />
           <div class="mt-8">{props.children}</div>
         </div>
       </div>
diff --git a/packages/app/src/index.css b/packages/app/src/index.css
index 5af8603296f5..900227d5a80d 100644
--- a/packages/app/src/index.css
+++ b/packages/app/src/index.css
@@ -4,7 +4,7 @@
 @import "tw-animate-css";
 
 html[data-background-image] body {
-  background-image: linear-gradient(rgb(0 0 0 / 20%), rgb(0 0 0 / 20%)), var(--app-background-image);
+  background-image: linear-gradient(rgb(0 0 0 / 30%), rgb(0 0 0 / 30%)), var(--app-background-image);
   background-color: transparent !important;
   background-position: center;
   background-repeat: no-repeat;
@@ -38,6 +38,12 @@ html[data-background-image] [data-background-surface="project-selector"] {
   backdrop-filter: blur(16px);
 }
 
+html[data-background-image] [data-background-surface="prompt"] [data-background-surface="project-selector"] {
+  background-color: transparent !important;
+  box-shadow: none;
+  backdrop-filter: none;
+}
+
 @font-face {
   font-family: "JetBrainsMono Nerd Font Mono";
   src: url("/assets/JetBrainsMonoNerdFontMono-Regular.woff2") format("woff2");

From 8eec2c6d57a7fa0c74cafd51f8cf17b3c205703c Mon Sep 17 00:00:00 2001
From: Brendan Allan <14191578+Brendonovich@users.noreply.github.com>
Date: Mon, 20 Jul 2026 23:59:10 +0000
Subject: [PATCH 6/8] fix(app): glass the workspace bar

---
 packages/app/src/index.css             | 14 ++++++++++++++
 packages/app/src/pages/new-session.tsx |  1 +
 2 files changed, 15 insertions(+)

diff --git a/packages/app/src/index.css b/packages/app/src/index.css
index 900227d5a80d..5ccb5e882b62 100644
--- a/packages/app/src/index.css
+++ b/packages/app/src/index.css
@@ -44,6 +44,20 @@ html[data-background-image] [data-background-surface="prompt"] [data-background-
   backdrop-filter: none;
 }
 
+html[data-background-image] [data-background-surface="workspace-bar"] {
+  padding-inline: 6px;
+  border-radius: 6px;
+  background-color: color-mix(in srgb, var(--v2-background-bg-base) 68%, transparent) !important;
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--v2-border-border-base) 70%, transparent);
+  backdrop-filter: blur(16px);
+}
+
+html[data-background-image] [data-background-surface="workspace-bar"] [data-background-surface="project-selector"] {
+  background-color: transparent !important;
+  box-shadow: none;
+  backdrop-filter: none;
+}
+
 @font-face {
   font-family: "JetBrainsMono Nerd Font Mono";
   src: url("/assets/JetBrainsMonoNerdFontMono-Regular.woff2") format("woff2");
diff --git a/packages/app/src/pages/new-session.tsx b/packages/app/src/pages/new-session.tsx
index c2668e1567be..44ccd49da92a 100644
--- a/packages/app/src/pages/new-session.tsx
+++ b/packages/app/src/pages/new-session.tsx
@@ -180,6 +180,7 @@ export default function NewSessionPage() {
                     />
                     <Show when={projectController.selected()}>
                       <div
+                        data-background-surface={showWorkspaceBar() ? "workspace-bar" : undefined}
                         class="flex min-h-7 min-w-0 items-center gap-0 text-v2-text-text-faint"
                         classList={{
                           "flex-col justify-center sm:flex-row": showWorkspaceBar(),

From 98bb5e3bb4c235aab4893ecbdcd2f3950336438a Mon Sep 17 00:00:00 2001
From: Brendan Allan <14191578+Brendonovich@users.noreply.github.com>
Date: Tue, 21 Jul 2026 00:02:13 +0000
Subject: [PATCH 7/8] fix(app): center the workspace bar

---
 packages/app/src/pages/new-session.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/app/src/pages/new-session.tsx b/packages/app/src/pages/new-session.tsx
index 44ccd49da92a..9b12bce4b041 100644
--- a/packages/app/src/pages/new-session.tsx
+++ b/packages/app/src/pages/new-session.tsx
@@ -184,6 +184,7 @@ export default function NewSessionPage() {
                         class="flex min-h-7 min-w-0 items-center gap-0 text-v2-text-text-faint"
                         classList={{
                           "flex-col justify-center sm:flex-row": showWorkspaceBar(),
+                          "w-fit max-w-full self-center": showWorkspaceBar(),
                           "justify-start": !showWorkspaceBar(),
                         }}
                       >

From 4e4729535ef8426f1f3adf793c4370e906e103dd Mon Sep 17 00:00:00 2001
From: Brendan Allan <14191578+Brendonovich@users.noreply.github.com>
Date: Tue, 21 Jul 2026 00:04:58 +0000
Subject: [PATCH 8/8] fix(app): pad the workspace bar

---
 packages/app/src/index.css | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/app/src/index.css b/packages/app/src/index.css
index 5ccb5e882b62..3260c18054c2 100644
--- a/packages/app/src/index.css
+++ b/packages/app/src/index.css
@@ -46,6 +46,7 @@ html[data-background-image] [data-background-surface="prompt"] [data-background-
 
 html[data-background-image] [data-background-surface="workspace-bar"] {
   padding-inline: 6px;
+  padding-block: 2px;
   border-radius: 6px;
   background-color: color-mix(in srgb, var(--v2-background-bg-base) 68%, transparent) !important;
   box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--v2-border-border-base) 70%, transparent);