@phenx-inc/ctlsurf 0.14.2 → 0.15.1

package/src/renderer/components/EditorPanel.tsx

@@ -6,6 +6,8 @@ import jsonWorker from 'monaco-editor/esm/vs/language/json/json.worker?worker'
 import cssWorker from 'monaco-editor/esm/vs/language/css/css.worker?worker'
 import htmlWorker from 'monaco-editor/esm/vs/language/html/html.worker?worker'
 import tsWorker from 'monaco-editor/esm/vs/language/typescript/ts.worker?worker'
+import { useAppearance } from '../lib/theme'
+import { THEMES } from '../lib/themes'
 
 // Configure Monaco workers for Vite
 self.MonacoEnvironment = {
@@ -21,6 +23,31 @@ self.MonacoEnvironment = {
 // Use local monaco instead of CDN
 loader.config({ monaco })
 
+// One Monaco theme per scheme. Monaco only ships 'vs' / 'vs-dark', so each
+// scheme inherits the matching base (keeping its syntax highlighting) and
+// overrides the surfaces, which are what would otherwise clash with the
+// surrounding chrome. Registered at module load — Monaco resolves a theme by
+// name at render time, so these must exist before the first <Editor> mounts.
+for (const t of THEMES) {
+  monaco.editor.defineTheme(`ctlsurf-${t.id}`, {
+    base: t.editor.base,
+    inherit: true,
+    rules: [],
+    colors: {
+      'editor.background': t.editor.background,
+      'editor.foreground': t.editor.foreground,
+      'editor.lineHighlightBackground': t.editor.lineHighlight,
+      'editor.selectionBackground': t.editor.selection,
+      'editorLineNumber.foreground': t.swatch.surface,
+      'editorLineNumber.activeForeground': t.swatch.accent,
+      'editorGutter.background': t.editor.background,
+      'editorWidget.background': t.editor.lineHighlight,
+      'editorCursor.foreground': t.terminal.cursor,
+      'scrollbarSlider.background': `${t.swatch.surface}99`,
+    },
+  })
+}
+
 interface FileEntry {
   name: string
   path: string
@@ -86,6 +113,7 @@ interface EditorPanelProps {
 }
 
 export function EditorPanel({ cwd }: EditorPanelProps) {
+  const { theme } = useAppearance()
   const [rootEntries, setRootEntries] = useState<FileEntry[]>([])
   const [openFile, setOpenFile] = useState<string | null>(null)
   const [fileContent, setFileContent] = useState<string>('')
@@ -208,7 +236,7 @@ export function EditorPanel({ cwd }: EditorPanelProps) {
                 language={getLanguage(openFile)}
                 value={fileContent}
                 onChange={(val) => { setFileContent(val || ''); setModified(true) }}
-                theme="vs-dark"
+                theme={`ctlsurf-${theme.id}`}
                 options={{
                   minimap: { enabled: false },
                   fontSize: 13,

package/src/renderer/components/ObserverPanel.tsx

@@ -43,13 +43,15 @@ const SENSITIVITY_LEVELS: Array<{ value: Sensitivity; label: string; hint: strin
   { value: 'all', label: 'All signals', hint: 'Everything, including low-confidence observations' },
 ]
 
+// Resolved from the token layer so both themes get a legible variant; see the
+// :root blocks in styles.css.
 const SEVERITY_COLORS: Record<string, string> = {
-  info: '#7aa2f7',
-  warn: '#e0af68',
-  high: '#ff9e64',
-  critical: '#f7768e',
+  info: 'var(--accent)',
+  warn: 'var(--warning)',
+  high: 'var(--sev-high)',
+  critical: 'var(--danger)',
 }
-const DIGEST_COLOR = '#bb9af7'
+const DIGEST_COLOR = 'var(--sev-digest)'
 
 function EyeIcon({ size = 16 }: { size?: number }) {
   return (
@@ -67,9 +69,14 @@ function formatTime(iso: string): string {
   return d.toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit' })
 }
 
+// `${color}55` only worked while the colours were hex literals; token
+// references have to be blended for real.
+const tint = (color: string, pct: number): string =>
+  `color-mix(in srgb, ${color} ${pct}%, transparent)`
+
 function Chip({ color, label }: { color: string; label: string }) {
   return (
-    <span className="obs-chip" style={{ color, borderColor: `${color}55`, background: `${color}14` }}>
+    <span className="obs-chip" style={{ color, borderColor: tint(color, 33), background: tint(color, 8) }}>
       <span className="obs-chip-dot" style={{ background: color }} />
       {label}
     </span>

package/src/renderer/components/SettingsDialog.tsx

@@ -1,4 +1,37 @@
 import { useState, useEffect } from 'react'
+import { useAppearance } from '../lib/theme'
+import { THEMES, themesByMode, type ThemeDef } from '../lib/themes'
+
+// A tile per scheme. The swatch is drawn from the theme's own literal colours
+// (not the active tokens) so each preview shows what it actually is.
+function ThemeGrid({ themes, value, onChange }: {
+  themes: ThemeDef[]
+  value: string
+  onChange: (id: string) => void
+}) {
+  return (
+    <div className="theme-options" role="radiogroup">
+      {themes.map(t => (
+        <button
+          key={t.id}
+          type="button"
+          role="radio"
+          aria-checked={value === t.id}
+          title={t.name}
+          className={`theme-option ${value === t.id ? 'active' : ''}`}
+          onClick={() => onChange(t.id)}
+        >
+          <span className="theme-swatch" style={{ background: t.swatch.bg }} aria-hidden="true">
+            <span className="theme-swatch-bar" style={{ background: t.swatch.surface }} />
+            <span className="theme-swatch-dot" style={{ background: t.swatch.accent }} />
+            <span className="theme-swatch-line" style={{ background: t.swatch.text }} />
+          </span>
+          <span className="theme-option-label">{t.name}</span>
+        </button>
+      ))}
+    </div>
+  )
+}
 
 interface ProfileSummary {
   id: string
@@ -21,6 +54,7 @@ interface SettingsDialogProps {
 }
 
 export function SettingsDialog({ open, onClose }: SettingsDialogProps) {
+  const { appearance, theme, update: updateAppearance } = useAppearance()
   const [profileList, setProfileList] = useState<ProfileListResponse | null>(null)
   const [activeProfileId, setActiveProfileId] = useState('production')
   const [editingId, setEditingId] = useState<string | null>(null)
@@ -157,6 +191,54 @@ export function SettingsDialog({ open, onClose }: SettingsDialogProps) {
       <div className="settings-dialog" onClick={e => e.stopPropagation()}>
         <h3>Settings</h3>
 
+        {!editingId && (
+          // ─── Appearance (global) ───────────────
+          <div className="settings-section">
+            <h4>Appearance</h4>
+            <p className="settings-hint">
+              Applies everywhere, including the terminal and code editor.
+            </p>
+
+            <label className="settings-checkbox">
+              <input
+                type="checkbox"
+                checked={appearance.sync}
+                onChange={e => updateAppearance({ sync: e.target.checked })}
+              />
+              <span>Sync with system appearance</span>
+              <span className="settings-hint">
+                Switches between your light and dark picks as the OS changes.
+              </span>
+            </label>
+
+            {appearance.sync ? (
+              <>
+                <div className="theme-group-label">Light</div>
+                <ThemeGrid
+                  themes={themesByMode('light')}
+                  value={appearance.light}
+                  onChange={id => updateAppearance({ light: id })}
+                />
+                <div className="theme-group-label">Dark</div>
+                <ThemeGrid
+                  themes={themesByMode('dark')}
+                  value={appearance.dark}
+                  onChange={id => updateAppearance({ dark: id })}
+                />
+                <span className="settings-hint">
+                  Currently {theme.name}.
+                </span>
+              </>
+            ) : (
+              <ThemeGrid
+                themes={THEMES}
+                value={appearance.theme}
+                onChange={id => updateAppearance({ theme: id })}
+              />
+            )}
+          </div>
+        )}
+
         {editingId ? (
           // ─── Profile Edit Form ─────────────────
           <div className="settings-section">

package/src/renderer/components/TerminalPanel.tsx

@@ -5,6 +5,7 @@ import { WebLinksAddon } from '@xterm/addon-web-links'
 import '@xterm/xterm/css/xterm.css'
 import { convertToEmailTable } from '../lib/tableToHtml'
 import { speech } from '../lib/speech'
+import { currentTheme, subscribeTheme } from '../lib/theme'
 
 // Show a transient toast in the active terminal panel. Broadcast as a window
 // event so module-level helpers (which have no component scope) can trigger it.
@@ -137,6 +138,16 @@ type TermState = {
 
 const _terminals = new Map<string, TermState>()
 
+// Terminals are cached here and outlive the components that render them, so
+// the palette swap is driven from module scope rather than a component effect.
+// xterm paints to a canvas, so the CSS tokens in styles.css cannot reach it —
+// each theme carries its own 16-colour palette in lib/themes.ts.
+subscribeTheme((theme) => {
+  for (const state of _terminals.values()) {
+    state.terminal.options.theme = theme.terminal
+  }
+})
+
 // Within a couple of lines of the bottom still counts as "at bottom", so a
 // small redraw delta doesn't strand the view just shy of the end.
 function isAtBottom(terminal: Terminal): boolean {
@@ -197,28 +208,7 @@ function getOrCreateTerminal(tabId: string, onExit: (tabId: string) => void): {
     macOptionClickForcesSelection: true,
     fontSize: 14,
     fontFamily: "'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'SF Mono', monospace",
-    theme: {
-      background: '#1a1b26',
-      foreground: '#a9b1d6',
-      cursor: '#c0caf5',
-      selectionBackground: '#33467C',
-      black: '#15161e',
-      red: '#f7768e',
-      green: '#9ece6a',
-      yellow: '#e0af68',
-      blue: '#7aa2f7',
-      magenta: '#bb9af7',
-      cyan: '#7dcfff',
-      white: '#a9b1d6',
-      brightBlack: '#414868',
-      brightRed: '#f7768e',
-      brightGreen: '#9ece6a',
-      brightYellow: '#e0af68',
-      brightBlue: '#7aa2f7',
-      brightMagenta: '#bb9af7',
-      brightCyan: '#7dcfff',
-      brightWhite: '#c0caf5'
-    },
+    theme: currentTheme().terminal,
     scrollback: 10000,
     scrollOnUserInput: true,
     allowTransparency: false

package/src/renderer/components/TicketPanel.tsx

@@ -2,20 +2,27 @@ import { useState, useEffect, useCallback } from 'react'
 
 interface Option { value: string; color: string }
 
+// Token references rather than literals, so the pills follow the theme. They
+// are also alpha-blended below via color-mix, which needs a var() to mix into.
 const STATUS_OPTIONS: Option[] = [
-  { value: 'Open', color: '#7aa2f7' },
-  { value: 'In Progress', color: '#e0af68' },
-  { value: 'Blocked', color: '#f7768e' },
-  { value: 'Done', color: '#9ece6a' },
+  { value: 'Open', color: 'var(--accent)' },
+  { value: 'In Progress', color: 'var(--warning)' },
+  { value: 'Blocked', color: 'var(--danger)' },
+  { value: 'Done', color: 'var(--success)' },
 ]
 const PRIORITY_OPTIONS: Option[] = [
-  { value: 'Low', color: '#565f89' },
-  { value: 'Med', color: '#e0af68' },
-  { value: 'High', color: '#f7768e' },
+  { value: 'Low', color: 'var(--text-muted)' },
+  { value: 'Med', color: 'var(--warning)' },
+  { value: 'High', color: 'var(--danger)' },
 ]
 
 const colorOf = (opts: Option[], value: string): string =>
-  opts.find(o => o.value === value)?.color ?? '#565f89'
+  opts.find(o => o.value === value)?.color ?? 'var(--text-muted)'
+
+// `${color}1f` used to work because the colours were hex literals; tokens need
+// a real blend.
+const tint = (color: string, pct: number): string =>
+  `color-mix(in srgb, ${color} ${pct}%, transparent)`
 
 interface Ticket {
   id: string
@@ -24,6 +31,10 @@ interface Ticket {
   status: string
   priority: string
   created: string | null
+  // Owning datastore — tickets can live in more than one store per project,
+  // so edits and dispatch prompts must reference the row's own store.
+  blockId?: string
+  pageId?: string
 }
 
 type SaveState = { kind: 'idle' } | { kind: 'saving' } | { kind: 'error'; message: string }
@@ -75,10 +86,13 @@ function ticketPrompt(t: Ticket, refs: TicketRefs | null): string {
     'ctlsurf references (use the ctlsurf MCP tools to read details or update status):',
     `- Ticket row ID: ${t.id}`,
   )
-  if (refs) {
+  // Prefer the ticket's own store — it may not be the project's primary one.
+  const blockId = t.blockId ?? refs?.blockId
+  const pageId = t.pageId ?? refs?.pageId
+  if (blockId && pageId) {
     lines.push(
-      `- Tickets datastore block ID: ${refs.blockId}`,
-      `- Agent Datastore page ID: ${refs.pageId}`,
+      `- Tickets datastore block ID: ${blockId}`,
+      `- Agent Datastore page ID: ${pageId}`,
     )
   }
   return lines.join('\n')
@@ -100,7 +114,7 @@ function Segmented({ options, value, onChange }: SegmentedProps) {
             key={o.value}
             type="button"
             className={`ticket-seg ${active ? 'active' : ''}`}
-            style={active ? { borderColor: o.color, color: o.color, background: `${o.color}1f` } : undefined}
+            style={active ? { borderColor: o.color, color: o.color, background: tint(o.color, 12) } : undefined}
             onClick={() => onChange(o.value)}
           >
             <span className="ticket-seg-dot" style={{ background: o.color }} />
@@ -132,7 +146,7 @@ function TicketCard({ ticket, onClick, onSend }: { ticket: Ticket; onClick: () =
         </div>
         <span
           className="ticket-card-pri"
-          style={{ color: colorOf(PRIORITY_OPTIONS, ticket.priority), borderColor: `${colorOf(PRIORITY_OPTIONS, ticket.priority)}66` }}
+          style={{ color: colorOf(PRIORITY_OPTIONS, ticket.priority), borderColor: tint(colorOf(PRIORITY_OPTIONS, ticket.priority), 40) }}
         >
           {ticket.priority}
         </span>
@@ -170,6 +184,8 @@ export function TicketPane({ onSendToTerminal }: { onSendToTerminal: (text: stri
 
   // form state
   const [editingId, setEditingId] = useState<string | null>(null)
+  // Store the edited ticket came from, so the save lands in the right one.
+  const [editingBlockId, setEditingBlockId] = useState<string | null>(null)
   const [title, setTitle] = useState('')
   const [description, setDescription] = useState('')
   const [status, setStatus] = useState(STATUS_OPTIONS[0].value)
@@ -209,6 +225,7 @@ export function TicketPane({ onSendToTerminal }: { onSendToTerminal: (text: stri
 
   const openNewForm = useCallback(() => {
     setEditingId(null)
+    setEditingBlockId(null)
     setTitle('')
     setDescription('')
     setStatus(STATUS_OPTIONS[0].value)
@@ -219,6 +236,7 @@ export function TicketPane({ onSendToTerminal }: { onSendToTerminal: (text: stri
 
   const openEditForm = useCallback((t: Ticket) => {
     setEditingId(t.id)
+    setEditingBlockId(t.blockId ?? null)
     setTitle(t.title)
     setDescription(t.description)
     setStatus(STATUS_OPTIONS.some(o => o.value === t.status) ? t.status : STATUS_OPTIONS[0].value)
@@ -233,7 +251,7 @@ export function TicketPane({ onSendToTerminal }: { onSendToTerminal: (text: stri
     const payload = { title: title.trim(), description: description.trim(), status, priority }
     try {
       const r = editingId
-        ? await window.worker.updateTicket(editingId, payload)
+        ? await window.worker.updateTicket(editingId, payload, editingBlockId ?? undefined)
         : await window.worker.addTicket(payload)
       if (r?.ok) {
         setView('list')
@@ -244,7 +262,7 @@ export function TicketPane({ onSendToTerminal }: { onSendToTerminal: (text: stri
     } catch (err: any) {
       setSave({ kind: 'error', message: err?.message || 'Failed to save ticket' })
     }
-  }, [title, description, status, priority, editingId, save.kind, refreshList])
+  }, [title, description, status, priority, editingId, editingBlockId, save.kind, refreshList])
 
   // Only capture keys while editing a ticket, so list-view typing in the terminal
   // isn't hijacked. Esc returns to the list; Cmd/Ctrl+Enter saves.

package/src/renderer/index.html

@@ -4,10 +4,42 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>ctlsurf-worker</title>
+  <!-- Stamp the theme before the first paint. This has to be an inline,
+       synchronous script in <head>: reading the pref over IPC (or waiting for
+       the bundle) would let one frame of the wrong theme through, which reads
+       as a flash every launch. lib/theme.ts owns the same key afterwards. -->
+  <script>
+    (function () {
+      var DARK = 'tokyo-night', LIGHT = 'tokyo-day'
+      var a = null
+      try {
+        var raw = localStorage.getItem('ctlsurf.appearance')
+        if (raw) a = JSON.parse(raw)
+        else {
+          // Migrate the original system/light/dark preference. lib/theme.ts
+          // performs the same mapping; both must agree or the first frame
+          // disagrees with the second.
+          var legacy = localStorage.getItem('ctlsurf.theme')
+          if (legacy === 'light') a = { sync: false, theme: LIGHT }
+          else if (legacy === 'dark') a = { sync: false, theme: DARK }
+        }
+      } catch (e) { /* private mode, or corrupt JSON */ }
+      var prefersLight = window.matchMedia && window.matchMedia('(prefers-color-scheme: light)').matches
+      var id
+      if (a && a.sync === false) id = a.theme
+      else if (a) id = prefersLight ? a.light : a.dark
+      else id = prefersLight ? LIGHT : DARK
+      document.documentElement.setAttribute('data-theme', id || (prefersLight ? LIGHT : DARK))
+    })()
+  </script>
   <!-- Boot splash styles are inlined here so they paint on the first frame,
        before the JS bundle and styles.css have loaded. Without this the window
-       shows an empty dark pane while React mounts and the startup IPC runs. -->
+       shows an empty dark pane while React mounts and the startup IPC runs.
+       They cannot use the tokens in styles.css for the same reason, so the two
+       palettes are repeated here — keep them in step with :root there. -->
   <style>
+    :root { color-scheme: dark }
+    :root[data-theme='tokyo-day'], :root[data-theme='catppuccin-latte'] { color-scheme: light }
     #boot-splash {
       position: fixed;
       inset: 0;
@@ -48,6 +80,31 @@
       letter-spacing: 0.04em;
       color: #565f89;
     }
+    /* One rule per theme: the splash paints before styles.css exists, so it
+       cannot use the tokens. Keep in step with the :root blocks there. */
+    :root[data-theme='tokyo-day'] #boot-splash { background: #e9eaef; }
+    :root[data-theme='tokyo-day'] .boot-spinner {
+      border-color: rgba(46, 125, 233, 0.22);
+      border-top-color: #2e7de9;
+    }
+    :root[data-theme='tokyo-day'] .boot-splash-title { color: #1b1e33; }
+    :root[data-theme='tokyo-day'] .boot-splash-label { color: #6b7190; }
+
+    :root[data-theme='catppuccin-mocha'] #boot-splash { background: #1e1e2e; }
+    :root[data-theme='catppuccin-mocha'] .boot-spinner {
+      border-color: rgba(137, 180, 250, 0.22);
+      border-top-color: #89b4fa;
+    }
+    :root[data-theme='catppuccin-mocha'] .boot-splash-title { color: #cdd6f4; }
+    :root[data-theme='catppuccin-mocha'] .boot-splash-label { color: #7f849c; }
+
+    :root[data-theme='catppuccin-latte'] #boot-splash { background: #eff1f5; }
+    :root[data-theme='catppuccin-latte'] .boot-spinner {
+      border-color: rgba(30, 102, 245, 0.22);
+      border-top-color: #1e66f5;
+    }
+    :root[data-theme='catppuccin-latte'] .boot-splash-title { color: #2f3145; }
+    :root[data-theme='catppuccin-latte'] .boot-splash-label { color: #7c7f93; }
   </style>
 </head>
 <body>

package/src/renderer/lib/theme.ts

@@ -0,0 +1,173 @@
+import { useEffect, useState } from 'react'
+import {
+  DEFAULT_DARK, DEFAULT_LIGHT, getTheme, isThemeId, type ThemeDef,
+} from './themes'
+
+// Appearance state.
+//
+// `sync` follows the OS and picks between the `light` / `dark` choices as it
+// flips; with sync off, `theme` is pinned. Keeping the pair around while pinned
+// means turning sync back on restores what you had rather than resetting.
+//
+// Stored in localStorage alongside the other renderer-local UI prefs
+// (ctlsurf.floatingMicVisible, ctlsurf.voice.*) rather than in the main-process
+// settings file — index.html has to read it synchronously before first paint,
+// which IPC cannot do. The main process keeps a mirror for recovery; see below.
+export interface Appearance {
+  sync: boolean
+  theme: string
+  light: string
+  dark: string
+}
+
+const KEY = 'ctlsurf.appearance'
+const LEGACY_KEY = 'ctlsurf.theme'
+
+export const DEFAULT_APPEARANCE: Appearance = {
+  sync: true,
+  theme: DEFAULT_DARK,
+  light: DEFAULT_LIGHT,
+  dark: DEFAULT_DARK,
+}
+
+function coerce(raw: unknown): Appearance | null {
+  if (!raw || typeof raw !== 'object') return null
+  const o = raw as Record<string, unknown>
+  // An unknown id (a theme removed in a later version) falls back rather than
+  // leaving the app with no palette at all.
+  return {
+    sync: o.sync !== false,
+    theme: isThemeId(o.theme) ? o.theme : DEFAULT_APPEARANCE.theme,
+    light: isThemeId(o.light) ? o.light : DEFAULT_APPEARANCE.light,
+    dark: isThemeId(o.dark) ? o.dark : DEFAULT_APPEARANCE.dark,
+  }
+}
+
+// null means "nothing stored", distinct from an explicit default — only the
+// former may be replaced by the main-process mirror on boot.
+function stored(): Appearance | null {
+  try {
+    const raw = localStorage.getItem(KEY)
+    if (raw) return coerce(JSON.parse(raw))
+    // Migrate the original system/light/dark preference.
+    const legacy = localStorage.getItem(LEGACY_KEY)
+    if (legacy === 'light') return { ...DEFAULT_APPEARANCE, sync: false, theme: DEFAULT_LIGHT }
+    if (legacy === 'dark') return { ...DEFAULT_APPEARANCE, sync: false, theme: DEFAULT_DARK }
+    if (legacy === 'system') return { ...DEFAULT_APPEARANCE }
+  } catch { /* private mode, or corrupt JSON */ }
+  return null
+}
+
+export function getAppearance(): Appearance {
+  return stored() ?? { ...DEFAULT_APPEARANCE }
+}
+
+const darkQuery = (): MediaQueryList | null =>
+  typeof window.matchMedia === 'function'
+    ? window.matchMedia('(prefers-color-scheme: dark)')
+    : null
+
+export function prefersDark(): boolean {
+  return darkQuery()?.matches !== false
+}
+
+export function resolveThemeId(a: Appearance = getAppearance()): string {
+  if (!a.sync) return a.theme
+  return prefersDark() ? a.dark : a.light
+}
+
+// Subscribers get the resolved ThemeDef, so none of them has to redo the
+// system-preference dance. Module-level: terminals outlive the components that
+// render them (see the _terminals cache in TerminalPanel), so the xterm palette
+// listener must not be tied to a component lifecycle.
+type Listener = (theme: ThemeDef) => void
+const listeners = new Set<Listener>()
+
+export function subscribeTheme(fn: Listener): () => void {
+  listeners.add(fn)
+  return () => { listeners.delete(fn) }
+}
+
+export function currentTheme(): ThemeDef {
+  return getTheme(resolveThemeId())
+}
+
+function applyDom(): ThemeDef {
+  const theme = currentTheme()
+  document.documentElement.setAttribute('data-theme', theme.id)
+  for (const fn of listeners) fn(theme)
+  return theme
+}
+
+// Keep the native layer in step: form controls, scrollbars and the background
+// Electron paints before the renderer loads are Chromium's, not our CSS. The
+// main process also persists this, which is what makes the choice recoverable.
+function syncNative(a: Appearance): void {
+  const theme = getTheme(resolveThemeId(a))
+  void window.worker?.setAppearance?.({
+    pref: a,
+    source: a.sync ? 'system' : theme.mode,
+    background: theme.background,
+  }).catch(() => { /* older main process */ })
+}
+
+export function setAppearance(next: Appearance): ThemeDef {
+  try { localStorage.setItem(KEY, JSON.stringify(next)) } catch { /* ignore */ }
+  syncNative(next)
+  return applyDom()
+}
+
+export function updateAppearance(patch: Partial<Appearance>): ThemeDef {
+  return setAppearance({ ...getAppearance(), ...patch })
+}
+
+// Re-resolve when the OS flips appearance, but only while syncing — a pinned
+// theme should survive the OS changing under it.
+darkQuery()?.addEventListener('change', () => {
+  const a = getAppearance()
+  if (a.sync) { applyDom(); syncNative(a) }
+})
+
+// index.html stamps data-theme before first paint so there is no flash; this
+// re-runs it to pick up anything that changed since (and to seed listeners).
+applyDom()
+
+// localStorage is not as durable as it looks: a reset Chromium quota database,
+// or two Electron instances sharing one --user-data-dir, silently empties it,
+// which would reset the choice. The main process mirrors it into settings.json,
+// so recover from there.
+//
+// Order matters — this reads before anything writes, which is why boot does not
+// call syncNative() on this branch. Guarded on "nothing stored" at both ends so
+// a real choice can never be clobbered by a late-arriving reply.
+if (stored() === null) {
+  const restore = window.worker?.getAppearance?.()
+  if (restore) {
+    void restore
+      .then((r) => {
+        const recovered = coerce(r?.pref)
+        if (recovered && stored() === null) setAppearance(recovered)
+      })
+      .catch(() => { /* older main process */ })
+  }
+} else {
+  syncNative(getAppearance())
+}
+
+export function useAppearance(): {
+  appearance: Appearance
+  theme: ThemeDef
+  update: (patch: Partial<Appearance>) => void
+} {
+  const [appearance, setState] = useState<Appearance>(getAppearance)
+  const [theme, setTheme] = useState<ThemeDef>(currentTheme)
+
+  // Read state back off the store rather than tracking it locally, so a change
+  // made in one component reaches every other consumer.
+  useEffect(() => subscribeTheme((t) => {
+    setTheme(t)
+    setState(getAppearance())
+  }), [])
+
+  return { appearance, theme, update: updateAppearance }
+}