@clawpump/claw-agent 0.1.5 → 0.1.6

package/agent/apps/desktop/src/themes/color.ts

@@ -0,0 +1,142 @@
+/**
+ * Small color helpers shared by the theme context (synthesised light variants)
+ * and the VS Code theme converter (token → seed mapping).
+ *
+ * Everything works in 6-digit `#rrggbb`. `normalizeHex` is the front door for
+ * untrusted input (VS Code themes use `#rgb`, `#rgba`, `#rrggbbaa`, and named
+ * tokens), flattening alpha over a backdrop so downstream math stays simple.
+ */
+
+export function hexToRgb(hex: string): [number, number, number] | null {
+  const clean = hex.trim().replace(/^#/, '')
+
+  if (!/^[0-9a-f]{6}$/i.test(clean)) {
+    return null
+  }
+
+  return [0, 2, 4].map(i => parseInt(clean.slice(i, i + 2), 16)) as [number, number, number]
+}
+
+export const rgbToHex = ([r, g, b]: [number, number, number]): string =>
+  `#${[r, g, b].map(n => Math.round(Math.min(255, Math.max(0, n))).toString(16).padStart(2, '0')).join('')}`
+
+export function mix(a: string, b: string, amount: number): string {
+  const ar = hexToRgb(a)
+  const br = hexToRgb(b)
+
+  return ar && br
+    ? rgbToHex([ar[0] + (br[0] - ar[0]) * amount, ar[1] + (br[1] - ar[1]) * amount, ar[2] + (br[2] - ar[2]) * amount])
+    : a
+}
+
+const linearize = (channel: number): number =>
+  channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4
+
+/** WCAG relative luminance (gamma-corrected), 0..1. */
+export function relativeLuminance(hex: string): number {
+  const rgb = hexToRgb(hex)
+
+  if (!rgb) {
+    return 0
+  }
+
+  const [r, g, b] = rgb.map(v => linearize(v / 255))
+
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+/** WCAG contrast ratio (1..21) between two hex colors. */
+export function contrastRatio(a: string, b: string): number {
+  const la = relativeLuminance(a)
+  const lb = relativeLuminance(b)
+
+  return la >= lb ? (la + 0.05) / (lb + 0.05) : (lb + 0.05) / (la + 0.05)
+}
+
+/** Returns a readable foreground (#161616 or #ffffff) for a background hex. */
+export function readableOn(hex: string): string {
+  return relativeLuminance(hex) > 0.58 ? '#161616' : '#ffffff'
+}
+
+/**
+ * Guarantee `color` reads against `bg`: if it's below `min` contrast, mix it
+ * toward white (on a dark bg) or black (on a light bg) in steps until it clears,
+ * keeping the hue as much as possible. Used so imported accents never collapse
+ * into a near-background sidebar (the "invisible label" case).
+ */
+export function ensureContrast(color: string, bg: string, min: number): string {
+  if (contrastRatio(color, bg) >= min) {
+    return color
+  }
+
+  const towards = relativeLuminance(bg) < 0.5 ? '#ffffff' : '#000000'
+  let best = color
+
+  for (let amount = 0.2; amount <= 1.0001; amount += 0.2) {
+    best = mix(color, towards, Math.min(amount, 1))
+
+    if (contrastRatio(best, bg) >= min) {
+      return best
+    }
+  }
+
+  return best
+}
+
+/** Perceptual-ish luminance in 0..1 (naive, for light/dark bucketing). */
+export function luminance(hex: string): number {
+  const rgb = hexToRgb(hex)
+
+  if (!rgb) {
+    return 0
+  }
+
+  const [r, g, b] = rgb.map(v => v / 255)
+
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+/**
+ * Coerce any CSS hex color VS Code themes throw at us into a flat 6-digit
+ * `#rrggbb`, compositing alpha over `backdrop`. Accepts `#rgb`, `#rgba`,
+ * `#rrggbb`, `#rrggbbaa` (with or without the leading `#`). Returns null for
+ * non-hex values (named colors, `rgb()`, etc.) so callers can fall back.
+ */
+export function normalizeHex(input: string | undefined | null, backdrop = '#000000'): string | null {
+  if (typeof input !== 'string') {
+    return null
+  }
+
+  let clean = input.trim().replace(/^#/, '')
+
+  // Expand shorthand (#rgb / #rgba) to full width.
+  if (clean.length === 3 || clean.length === 4) {
+    clean = clean
+      .split('')
+      .map(ch => ch + ch)
+      .join('')
+  }
+
+  if (!/^[0-9a-f]{6}([0-9a-f]{2})?$/i.test(clean)) {
+    return null
+  }
+
+  const rgb = hexToRgb(`#${clean.slice(0, 6)}`)
+
+  if (!rgb) {
+    return null
+  }
+
+  if (clean.length === 6) {
+    return rgbToHex(rgb)
+  }
+
+  const alpha = parseInt(clean.slice(6, 8), 16) / 255
+  const base = hexToRgb(backdrop) ?? [0, 0, 0]
+
+  return rgbToHex([
+    base[0] + (rgb[0] - base[0]) * alpha,
+    base[1] + (rgb[1] - base[1]) * alpha,
+    base[2] + (rgb[2] - base[2]) * alpha
+  ])
+}

package/agent/apps/desktop/src/themes/context.tsx

@@ -9,15 +9,30 @@
  * The two are persisted independently. Shift+X toggles light/dark.
  */
 
+import { useStore } from '@nanostores/react'
 import { createContext, type ReactNode, useCallback, useContext, useEffect, useMemo, useState } from 'react'
 
 import { matchesQuery, useMediaQuery } from '@/hooks/use-media-query'
+import { persistString, persistStringRecord, storedString, storedStringRecord } from '@/lib/storage'
+import { $activeGatewayProfile, normalizeProfileKey } from '@/store/profile'
 
+import { hexToRgb, mix, readableOn } from './color'
 import { BUILTIN_THEME_LIST, BUILTIN_THEMES, DEFAULT_SKIN_NAME, DEFAULT_TYPOGRAPHY, nousTheme } from './presets'
 import type { DesktopTheme, DesktopThemeColors } from './types'
+import { $userThemes, resolveTheme } from './user-themes'
 
+// Legacy global skin (pre per-profile themes). Still the inheritance fallback
+// for any profile without its own assignment, so single-profile users and old
+// installs are unaffected.
 const SKIN_KEY = 'hermes-desktop-theme-v2'
 const MODE_KEY = 'hermes-desktop-mode-v1'
+// Per-profile skin + light/dark mode assignments: { [profileKey]: value }. A
+// profile inherits the global default until it's given its own appearance.
+const PROFILE_SKINS_KEY = 'hermes-desktop-profile-themes-v1'
+const PROFILE_MODES_KEY = 'hermes-desktop-profile-modes-v1'
+// Last active profile, recorded so the boot-time paint can pick that profile's
+// theme before the gateway reports which profile actually launched.
+const LAST_PROFILE_KEY = 'hermes-desktop-active-profile-v1'
 const RETIRED_SKINS = new Set(['nous-light', 'default', 'gold'])
 
 export type ThemeMode = 'light' | 'dark' | 'system'
@@ -27,48 +42,39 @@ const INJECTED_FONT_URLS = new Set<string>()
 const resolveMode = (mode: ThemeMode, systemDark = matchesQuery('(prefers-color-scheme: dark)')): 'light' | 'dark' =>
   mode === 'system' ? (systemDark ? 'dark' : 'light') : mode
 
-const normalizeSkin = (name: string | null | undefined): string =>
-  name && BUILTIN_THEMES[name] && !RETIRED_SKINS.has(name) ? name : DEFAULT_SKIN_NAME
-
-// ─── Color math (for synthesised light variants of dark-only skins) ────────
-
-function hexToRgb(hex: string): [number, number, number] | null {
-  const clean = hex.trim().replace(/^#/, '')
-
-  if (!/^[0-9a-f]{6}$/i.test(clean)) {
-    return null
-  }
-
-  return [0, 2, 4].map(i => parseInt(clean.slice(i, i + 2), 16)) as [number, number, number]
-}
-
-const rgbToHex = ([r, g, b]: [number, number, number]) =>
-  `#${[r, g, b].map(n => Math.round(n).toString(16).padStart(2, '0')).join('')}`
-
-function mix(a: string, b: string, amount: number): string {
-  const ar = hexToRgb(a)
-  const br = hexToRgb(b)
-
-  return ar && br
-    ? rgbToHex([ar[0] + (br[0] - ar[0]) * amount, ar[1] + (br[1] - ar[1]) * amount, ar[2] + (br[2] - ar[2]) * amount])
-    : a
-}
-
-function readableOn(hex: string): string {
-  const rgb = hexToRgb(hex)
-
-  if (!rgb) {
-    return '#ffffff'
+const normalizeSkin = (name: string | null): string =>
+  name && resolveTheme(name) && !RETIRED_SKINS.has(name) ? name : DEFAULT_SKIN_NAME
+
+const normalizeMode = (value: string | null): ThemeMode =>
+  value === 'light' || value === 'dark' || value === 'system' ? value : 'light'
+
+// ─── Per-profile appearance persistence ─────────────────────────────────────
+// Skin and mode are each stored per profile. "default" isn't a real profile —
+// it *is* the legacy global slot, so it reads/writes the global directly. Named
+// profiles get their own entry and fall back to that global until assigned, so
+// unassigned profiles and pre-per-profile installs stay on the global value.
+const profilePref = <T extends string>(record: string, legacy: string, normalize: (v: string | null) => T) => ({
+  resolve: (profile: string): T => normalize(storedStringRecord(record)[profile] ?? storedString(legacy)),
+  assign: (profile: string, value: T): void => {
+    if (profile === 'default') {
+      persistString(legacy, value)
+    } else {
+      persistStringRecord(record, { ...storedStringRecord(record), [profile]: value })
+    }
   }
+})
 
-  const [r, g, b] = rgb.map(v => {
-    const c = v / 255
+export const skinPref = profilePref(PROFILE_SKINS_KEY, SKIN_KEY, normalizeSkin)
+export const modePref = profilePref(PROFILE_MODES_KEY, MODE_KEY, normalizeMode)
 
-    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
-  })
+// Last active profile — lets the boot paint pick its appearance before the
+// gateway reports which profile actually launched.
+const readBootProfileKey = () => normalizeProfileKey(storedString(LAST_PROFILE_KEY))
+const rememberActiveProfileKey = (profile: string) => persistString(LAST_PROFILE_KEY, profile)
 
-  return 0.2126 * r + 0.7152 * g + 0.0722 * b > 0.58 ? '#161616' : '#ffffff'
-}
+// ─── Color math (for synthesised light variants of dark-only skins) ────────
+// hexToRgb / mix / readableOn live in ./color so the VS Code converter shares
+// the exact same math.
 
 function synthLightColors(seed: DesktopTheme): DesktopThemeColors {
   const accent = seed.colors.ring || seed.colors.primary
@@ -108,7 +114,7 @@ function synthLightColors(seed: DesktopTheme): DesktopThemeColors {
 
 /** Returns the seed palette for a given skin + mode (no overrides applied). */
 export function getBaseColors(skinName: string, mode: 'light' | 'dark'): DesktopThemeColors {
-  const seed = BUILTIN_THEMES[skinName] ?? nousTheme
+  const seed = resolveTheme(skinName) ?? nousTheme
 
   if (mode === 'dark') {
     return seed.darkColors ?? seed.colors
@@ -118,7 +124,7 @@ export function getBaseColors(skinName: string, mode: 'light' | 'dark'): Desktop
 }
 
 function deriveTheme(skinName: string, mode: 'light' | 'dark'): DesktopTheme {
-  const seed = BUILTIN_THEMES[skinName] ?? nousTheme
+  const seed = resolveTheme(skinName) ?? nousTheme
 
   return {
     ...seed,
@@ -221,6 +227,17 @@ function applyTheme(theme: DesktopTheme, mode: 'light' | 'dark') {
     foreground: c.foreground
   })
 
+  // Raw (non-JSON) keys read by the inline pre-paint script in index.html —
+  // they let a brand-new window paint the themed background on its very first
+  // frame, before this module has even loaded.
+  try {
+    window.localStorage.setItem('hermes-boot-background', c.background)
+    window.localStorage.setItem('hermes-boot-color-scheme', rendered)
+  } catch {
+    // Storage may be unavailable (private mode / quota); the inline script
+    // falls back to prefers-color-scheme.
+  }
+
   if (typo.fontUrl && !INJECTED_FONT_URLS.has(typo.fontUrl)) {
     const link = document.createElement('link')
     link.rel = 'stylesheet'
@@ -231,12 +248,23 @@ function applyTheme(theme: DesktopTheme, mode: 'light' | 'dark') {
   }
 }
 
-// Boot-time paint to avoid a flash before <ThemeProvider> mounts.
+// Pin Electron's nativeTheme to the app's mode so the NATIVE window chrome
+// (macOS vibrancy material, titlebar, pre-paint background) matches the app
+// theme instead of the OS appearance. An explicit light/dark pick is forced;
+// 'system' stays 'system' so prefers-color-scheme keeps tracking the OS.
+const syncNativeTheme = (pref: ThemeMode, rendered: 'light' | 'dark') =>
+  window.hermesDesktop?.setNativeTheme?.(pref === 'system' ? 'system' : rendered)
+
+// Boot-time paint to avoid a flash before <ThemeProvider> mounts. Use the last
+// active profile's appearance so a non-default profile relaunch paints its own
+// skin + light/dark mode.
 if (typeof window !== 'undefined') {
-  const skin = normalizeSkin(window.localStorage.getItem(SKIN_KEY))
-  const mode = (window.localStorage.getItem(MODE_KEY) as ThemeMode) ?? 'light'
-  const resolved = resolveMode(mode)
-  applyTheme(deriveTheme(skin, resolved), resolved)
+  const profile = readBootProfileKey()
+  const pref = modePref.resolve(profile)
+  const resolved = resolveMode(pref)
+  const theme = deriveTheme(skinPref.resolve(profile), resolved)
+  applyTheme(theme, resolved)
+  syncNativeTheme(pref, renderedModeFor(theme.colors, resolved))
 }
 
 // ─── Context ────────────────────────────────────────────────────────────────
@@ -245,7 +273,15 @@ interface ThemeContextValue {
   theme: DesktopTheme
   themeName: string
   mode: ThemeMode
+  /** The light/dark switch the user picked. */
   resolvedMode: 'light' | 'dark'
+  /**
+   * The mode actually painted, derived from the active background's luminance.
+   * Differs from `resolvedMode` for skins that keep a bright surface in "dark"
+   * (or vice-versa). Surface-bound UI (e.g. the terminal palette) should key off
+   * this so it matches what's on screen instead of inverting.
+   */
+  renderedMode: 'light' | 'dark'
   availableThemes: Array<{ name: string; label: string; description: string }>
   setTheme: (name: string) => void
   setMode: (mode: ThemeMode) => void
@@ -258,65 +294,82 @@ const ThemeContext = createContext<ThemeContextValue>({
   themeName: DEFAULT_SKIN_NAME,
   mode: 'light',
   resolvedMode: 'light',
+  renderedMode: 'light',
   availableThemes: SKIN_LIST,
   setTheme: () => {},
   setMode: () => {}
 })
 
 export function ThemeProvider({ children }: { children: ReactNode }) {
+  // Skin + mode are assigned per profile; the active profile drives which
+  // appearance shows. Single-profile users only ever see "default", so their
+  // behavior is unchanged.
+  const profileKey = normalizeProfileKey(useStore($activeGatewayProfile))
+
+  // Built-ins + user-installed themes. Reactive so an import shows up live in
+  // the palette, settings grid, and `/skin` without a reload.
+  const userThemes = useStore($userThemes)
+
+  const availableThemes = useMemo(
+    () =>
+      [...Object.values(BUILTIN_THEMES), ...Object.values(userThemes)].map(({ name, label, description }) => ({
+        name,
+        label,
+        description
+      })),
+    [userThemes]
+  )
+
   const [themeName, setThemeNameState] = useState(() =>
-    typeof window === 'undefined' ? DEFAULT_SKIN_NAME : normalizeSkin(window.localStorage.getItem(SKIN_KEY))
+    typeof window === 'undefined' ? DEFAULT_SKIN_NAME : skinPref.resolve(readBootProfileKey())
   )
 
   const [mode, setModeState] = useState<ThemeMode>(() =>
-    typeof window === 'undefined' ? 'light' : ((window.localStorage.getItem(MODE_KEY) as ThemeMode) ?? 'light')
+    typeof window === 'undefined' ? 'light' : modePref.resolve(readBootProfileKey())
   )
 
+  // Follow profile switches: paint the profile's assigned skin + mode and
+  // remember it for the next boot's first paint.
+  useEffect(() => {
+    rememberActiveProfileKey(profileKey)
+    setThemeNameState(skinPref.resolve(profileKey))
+    setModeState(modePref.resolve(profileKey))
+  }, [profileKey])
+
   const systemDark = useMediaQuery('(prefers-color-scheme: dark)')
   const resolvedMode = resolveMode(mode, systemDark)
   const activeTheme = useMemo(() => deriveTheme(themeName, resolvedMode), [themeName, resolvedMode])
 
+  // What actually gets painted (matches the `.dark` class applyTheme toggles).
+  const renderedMode = useMemo(() => renderedModeFor(activeTheme.colors, resolvedMode), [activeTheme, resolvedMode])
+
   useEffect(() => applyTheme(activeTheme, resolvedMode), [activeTheme, resolvedMode])
 
+  // Keep the native window appearance pinned to the app theme (vibrancy
+  // material, titlebar, new-window pre-paint background).
+  useEffect(() => syncNativeTheme(mode, renderedMode), [mode, renderedMode])
+
+  // Assign to whichever profile is live right now (read fresh so the callbacks
+  // stay stable across profile switches).
+  const liveProfile = () => normalizeProfileKey($activeGatewayProfile.get())
+
   const setTheme = useCallback((name: string) => {
     const next = normalizeSkin(name)
     setThemeNameState(next)
-    window.localStorage.setItem(SKIN_KEY, next)
+    skinPref.assign(liveProfile(), next)
   }, [])
 
   const setMode = useCallback((next: ThemeMode) => {
     setModeState(next)
-    window.localStorage.setItem(MODE_KEY, next)
+    modePref.assign(liveProfile(), next)
   }, [])
 
-  // Shift+X toggles light/dark anywhere outside an editable field.
-  useEffect(() => {
-    const onKeyDown = (event: KeyboardEvent) => {
-      const t = event.target as HTMLElement | null
-
-      const editing =
-        t?.isContentEditable ||
-        t instanceof HTMLInputElement ||
-        t instanceof HTMLTextAreaElement ||
-        t instanceof HTMLSelectElement
-
-      if (editing || event.repeat || event.altKey || event.ctrlKey || event.metaKey) {
-        return
-      }
-
-      if (event.shiftKey && event.code === 'KeyX') {
-        setMode(resolvedMode === 'dark' ? 'light' : 'dark')
-      }
-    }
-
-    window.addEventListener('keydown', onKeyDown)
-
-    return () => window.removeEventListener('keydown', onKeyDown)
-  }, [resolvedMode, setMode])
+  // The light/dark toggle (Shift+X by default) is owned by the keybind runtime
+  // (`appearance.toggleMode`) so it shows up in the hotkey map and is rebindable.
 
   const value = useMemo<ThemeContextValue>(
-    () => ({ theme: activeTheme, themeName, mode, resolvedMode, availableThemes: SKIN_LIST, setTheme, setMode }),
-    [activeTheme, themeName, mode, resolvedMode, setTheme, setMode]
+    () => ({ theme: activeTheme, themeName, mode, resolvedMode, renderedMode, availableThemes, setTheme, setMode }),
+    [activeTheme, themeName, mode, resolvedMode, renderedMode, availableThemes, setTheme, setMode]
   )
 
   return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>

package/agent/apps/desktop/src/themes/install.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest'
+
+import type { DesktopMarketplaceThemeResult } from '@/global'
+
+import { luminance } from './color'
+import { buildThemeFromMarketplace } from './install'
+
+const themeJson = (type: 'light' | 'dark', background: string, foreground: string) =>
+  JSON.stringify({ type, colors: { 'editor.background': background, 'editor.foreground': foreground } })
+
+// A full base-8 ANSI set keyed off `red` so each variant is distinguishable.
+const ansiColors = (red: string) => ({
+  'terminal.ansiBlack': '#000000',
+  'terminal.ansiRed': red,
+  'terminal.ansiGreen': '#00aa00',
+  'terminal.ansiYellow': '#aaaa00',
+  'terminal.ansiBlue': '#0000aa',
+  'terminal.ansiMagenta': '#aa00aa',
+  'terminal.ansiCyan': '#00aaaa',
+  'terminal.ansiWhite': '#aaaaaa'
+})
+
+const themeJsonWithAnsi = (type: 'light' | 'dark', background: string, foreground: string, red: string) =>
+  JSON.stringify({ type, colors: { 'editor.background': background, 'editor.foreground': foreground, ...ansiColors(red) } })
+
+describe('buildThemeFromMarketplace', () => {
+  it('folds a light + dark variant into one family with both slots', () => {
+    const result: DesktopMarketplaceThemeResult = {
+      extensionId: 'ryanolsonx.solarized',
+      displayName: 'Solarized',
+      themes: [
+        { label: 'Solarized Light', uiTheme: 'vs', contents: themeJson('light', '#fdf6e3', '#586e75') },
+        { label: 'Solarized Dark', uiTheme: 'vs-dark', contents: themeJson('dark', '#002b36', '#93a1a1') }
+      ]
+    }
+
+    const theme = buildThemeFromMarketplace(result)
+
+    expect(theme.label).toBe('Solarized')
+    expect(theme.name).toBe('vsc-solarized')
+    // colors = the light variant, darkColors = the dark variant → the toggle works.
+    expect(theme.colors.background).toBe('#fdf6e3')
+    expect(theme.darkColors?.background).toBe('#002b36')
+    expect(luminance(theme.colors.background)).toBeGreaterThan(0.5)
+    expect(luminance(theme.darkColors!.background)).toBeLessThan(0.5)
+  })
+
+  it('orders variants by contribution regardless of light/dark sequence', () => {
+    const result: DesktopMarketplaceThemeResult = {
+      extensionId: 'github.github-vscode-theme',
+      displayName: 'GitHub Theme',
+      themes: [
+        { label: 'GitHub Dark Default', uiTheme: 'vs-dark', contents: themeJson('dark', '#0d1117', '#e6edf3') },
+        { label: 'GitHub Light Default', uiTheme: 'vs', contents: themeJson('light', '#ffffff', '#1f2328') }
+      ]
+    }
+
+    const theme = buildThemeFromMarketplace(result)
+    expect(theme.colors.background).toBe('#ffffff')
+    expect(theme.darkColors?.background).toBe('#0d1117')
+  })
+
+  it('fills both slots with the sole palette for a single-variant extension', () => {
+    const result: DesktopMarketplaceThemeResult = {
+      extensionId: 'dracula-theme.theme-dracula',
+      displayName: 'Dracula',
+      themes: [{ label: 'Dracula', uiTheme: 'vs-dark', contents: themeJson('dark', '#282a36', '#f8f8f2') }]
+    }
+
+    const theme = buildThemeFromMarketplace(result)
+    expect(theme.colors.background).toBe('#282a36')
+    expect(theme.darkColors).toBe(theme.colors)
+  })
+
+  it('keys each variant terminal palette to its mode (terminal / darkTerminal)', () => {
+    const result: DesktopMarketplaceThemeResult = {
+      extensionId: 'ryanolsonx.solarized',
+      displayName: 'Solarized',
+      themes: [
+        { label: 'Solarized Light', uiTheme: 'vs', contents: themeJsonWithAnsi('light', '#fdf6e3', '#586e75', '#dc322f') },
+        { label: 'Solarized Dark', uiTheme: 'vs-dark', contents: themeJsonWithAnsi('dark', '#002b36', '#93a1a1', '#ff5f56') }
+      ]
+    }
+
+    const theme = buildThemeFromMarketplace(result)
+    expect(theme.terminal?.red).toBe('#dc322f')
+    expect(theme.darkTerminal?.red).toBe('#ff5f56')
+  })
+
+  it('reuses the sole variant terminal palette for both modes', () => {
+    const result: DesktopMarketplaceThemeResult = {
+      extensionId: 'dracula-theme.theme-dracula',
+      displayName: 'Dracula',
+      themes: [{ label: 'Dracula', uiTheme: 'vs-dark', contents: themeJsonWithAnsi('dark', '#282a36', '#f8f8f2', '#ff5555') }]
+    }
+
+    const theme = buildThemeFromMarketplace(result)
+    expect(theme.terminal?.red).toBe('#ff5555')
+    expect(theme.darkTerminal?.red).toBe('#ff5555')
+  })
+
+  it('leaves terminal slots unset when no variant ships an ANSI palette', () => {
+    const result: DesktopMarketplaceThemeResult = {
+      extensionId: 'x.plain',
+      displayName: 'Plain',
+      themes: [{ label: 'Plain', uiTheme: 'vs-dark', contents: themeJson('dark', '#101010', '#fafafa') }]
+    }
+
+    const theme = buildThemeFromMarketplace(result)
+    expect(theme.terminal).toBeUndefined()
+    expect(theme.darkTerminal).toBeUndefined()
+  })
+
+  it('throws when the extension contributes no themes', () => {
+    expect(() =>
+      buildThemeFromMarketplace({ extensionId: 'x.y', displayName: 'X', themes: [] })
+    ).toThrow(/does not contribute/i)
+  })
+})

package/agent/apps/desktop/src/themes/install.ts

@@ -0,0 +1,95 @@
+/**
+ * Install desktop themes from external sources.
+ *
+ * The heavy lifting (network + .vsix unzip) lives in the Electron main process
+ * (`electron/vscode-marketplace.cjs`), reached via `window.hermesDesktop.themes`.
+ * Main hands back the raw theme JSON; we parse + convert + persist here so the
+ * conversion stays in one unit-testable place.
+ */
+
+import type { DesktopMarketplaceThemeResult } from '@/global'
+
+import type { DesktopTheme } from './types'
+import { installUserTheme } from './user-themes'
+import { convertVscodeColorTheme, parseVscodeTheme, vscodeThemeSlug } from './vscode'
+
+/** A `publisher.extension` id, e.g. `dracula-theme.theme-dracula`. */
+export const MARKETPLACE_ID_RE = /^[\w-]+\.[\w-]+$/
+
+/** Parse + convert + persist a pasted VS Code theme JSON. */
+export function installVscodeThemeFromText(
+  text: string,
+  opts?: { label?: string; source?: string }
+): DesktopTheme {
+  const raw = parseVscodeTheme(text)
+  const { theme } = convertVscodeColorTheme(raw, opts)
+
+  return installUserTheme(theme)
+}
+
+/**
+ * Fold every color theme an extension contributes into ONE desktop theme family.
+ *
+ * Many extensions ship a light *and* a dark variant (GitHub, Solarized, Winter
+ * is Coming…). Rather than install them as separate flat entries — which made
+ * the light/dark toggle a no-op and let "install in dark mode" land on the light
+ * variant — we map the first light variant onto `colors` and the first dark
+ * variant onto `darkColors`. The result is a single picker entry whose light/dark
+ * toggle switches between the real variants. A single-variant extension fills
+ * both slots with its one palette (the toggle is a no-op, as it must be).
+ */
+export function buildThemeFromMarketplace(result: DesktopMarketplaceThemeResult): DesktopTheme {
+  if (!result.themes.length) {
+    throw new Error(`"${result.extensionId}" does not contribute any color themes.`)
+  }
+
+  const variants = result.themes.map(file => {
+    const raw = parseVscodeTheme(file.contents)
+    const label = file.label || raw.name || result.displayName
+    const { mode, theme } = convertVscodeColorTheme(raw, { label, source: result.extensionId })
+
+    return { mode, palette: theme.colors, terminal: theme.terminal }
+  })
+
+  const fallback = variants[0]
+  const light = variants.find(variant => variant.mode === 'light') ?? fallback
+  const dark = variants.find(variant => variant.mode === 'dark') ?? fallback
+
+  // The terminal ANSI palette tracks the painted variant the same way colors do
+  // (light → terminal, dark → darkTerminal); each falls back to the other so a
+  // single-variant import still themes the terminal in both modes.
+  const terminal = light.terminal ?? dark.terminal
+  const darkTerminal = dark.terminal ?? light.terminal
+
+  return {
+    name: vscodeThemeSlug(result.displayName),
+    label: result.displayName,
+    description: `VS Code · ${result.extensionId}`,
+    colors: light.palette,
+    darkColors: dark.palette,
+    ...(terminal ? { terminal } : {}),
+    ...(darkTerminal ? { darkTerminal } : {})
+  }
+}
+
+/**
+ * Download a Marketplace extension and install the theme family it contributes
+ * (see `buildThemeFromMarketplace`). Returns the single installed theme.
+ */
+export async function installVscodeThemeFromMarketplace(id: string): Promise<DesktopTheme> {
+  const trimmed = id.trim()
+
+  if (!MARKETPLACE_ID_RE.test(trimmed)) {
+    throw new Error('Expected a Marketplace id like "publisher.extension".')
+  }
+
+  const api = window.hermesDesktop?.themes
+
+  if (!api?.fetchMarketplace) {
+    throw new Error('Marketplace install is only available in the desktop app.')
+  }
+
+  const result = await api.fetchMarketplace(trimmed)
+
+  return installUserTheme(buildThemeFromMarketplace(result))
+}