@agentprojectcontext/apx 1.42.1 → 1.43.0

package/src/interfaces/web/src/components/voice/VoiceSttCard.tsx

@@ -1,11 +1,16 @@
-import { Field } from "../ui";
+import { Field, Input } from "../ui";
 import { UiSelect } from "../UiSelect";
 import { WHISPER_MODELS, type TranscriptionConfig } from "../../lib/api/voice";
+import { isSecretMarker, secretSuffix } from "../../lib/secrets";
 import { t } from "../../i18n";
 
 // STT (speech-to-text) configuration. Persisted under config.transcription.
-// The actual capture happens in the deck overlay / Telegram / CLI; here the
-// owner just picks the backend + (for local whisper) the model + language.
+// The actual capture happens in the desktop window / Telegram / CLI; here the
+// owner picks the engine and configures it:
+//   local  — embedded faster-whisper (offline; model + language)
+//   openai — OpenAI cloud Whisper (api_key + model)
+//   custom — any OpenAI-compatible server: mlx-audio on this Mac's Metal GPU,
+//            a Radeon/NVIDIA box on the LAN, or a remote endpoint (base_url).
 
 interface Props {
   config: TranscriptionConfig;
@@ -17,6 +22,7 @@ const providerOptions = () => [
   { value: "auto", label: t("voice_ui.stt_provider_auto") },
   { value: "local", label: t("voice_ui.stt_provider_local") },
   { value: "openai", label: t("voice_ui.stt_provider_openai") },
+  { value: "custom", label: t("voice_ui.stt_provider_custom") },
 ];
 
 const langOptions = () => [
@@ -32,9 +38,30 @@ const langOptions = () => [
 export function VoiceSttCard({ config, onPatch, busy }: Props) {
   const provider = config.provider || "auto";
   const local = config.local || {};
+  const openai = config.openai || {};
+  const custom = config.custom || {};
   const model = local.model || "small";
   const language = local.language || "auto";
-  const usesLocal = provider !== "openai";
+  // "auto" tries local first, so its tuning shares the local block.
+  const showLocal = provider === "auto" || provider === "local";
+
+  // Text fields patch on blur (not every keystroke), and only when changed.
+  const patchText = (key: string, prev: string | undefined, value: string) => {
+    const next = value.trim();
+    if (next === (prev || "").trim()) return;
+    onPatch({ [key]: next });
+  };
+  // Secrets: a blank field keeps the stored key; the daemon ignores redacted
+  // "*** set ***" markers, so we never echo one back as a real value.
+  const patchKey = (key: string, value: string) => {
+    const next = value.trim();
+    if (!next || isSecretMarker(next)) return;
+    onPatch({ [key]: next });
+  };
+  const keyPlaceholder = (marker: unknown) =>
+    isSecretMarker(marker)
+      ? t("voice_ui.api_key_set", { suffix: secretSuffix(marker) ?? "" })
+      : t("voice_ui.api_key_label");
 
   return (
     <div className="space-y-3">
@@ -48,7 +75,7 @@ export function VoiceSttCard({ config, onPatch, busy }: Props) {
         />
       </Field>
 
-      {usesLocal && (
+      {showLocal && (
         <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
           <Field label={t("voice_ui.stt_model_label")} hint={t("voice_ui.stt_model_hint")}>
             <UiSelect
@@ -68,6 +95,75 @@ export function VoiceSttCard({ config, onPatch, busy }: Props) {
           </Field>
         </div>
       )}
+
+      {provider === "openai" && (
+        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
+          <Field
+            label={t("voice_ui.api_key_label")}
+            hint={isSecretMarker(openai.api_key)
+              ? t("voice_ui.api_key_keep_hint")
+              : t("voice_ui.api_key_reuse_hint", { engine: "engines.openai.api_key", env: "OPENAI_API_KEY" })}
+          >
+            <Input
+              type="password"
+              autoComplete="new-password"
+              defaultValue=""
+              placeholder={keyPlaceholder(openai.api_key)}
+              onBlur={(e) => patchKey("transcription.openai.api_key", e.target.value)}
+              disabled={busy}
+            />
+          </Field>
+          <Field label={t("voice_ui.stt_openai_model_label")} hint={t("voice_ui.stt_openai_model_hint")}>
+            <Input
+              defaultValue={openai.model || ""}
+              placeholder="whisper-1"
+              onBlur={(e) => patchText("transcription.openai.model", openai.model, e.target.value)}
+              disabled={busy}
+            />
+          </Field>
+        </div>
+      )}
+
+      {provider === "custom" && (
+        <div className="space-y-3">
+          <Field label={t("voice_ui.stt_custom_baseurl_label")} hint={t("voice_ui.stt_custom_baseurl_hint")}>
+            <Input
+              defaultValue={custom.base_url || ""}
+              placeholder="http://localhost:8000/v1"
+              onBlur={(e) => patchText("transcription.custom.base_url", custom.base_url, e.target.value)}
+              disabled={busy}
+            />
+          </Field>
+          <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
+            <Field label={t("voice_ui.stt_custom_model_label")} hint={t("voice_ui.stt_custom_model_hint")}>
+              <Input
+                defaultValue={custom.model || ""}
+                placeholder="mlx-community/whisper-large-v3-turbo"
+                onBlur={(e) => patchText("transcription.custom.model", custom.model, e.target.value)}
+                disabled={busy}
+              />
+            </Field>
+            <Field label={t("voice_ui.stt_language_label")} hint={t("voice_ui.stt_language_hint")}>
+              <UiSelect
+                value={custom.language || "auto"}
+                onChange={(v) => onPatch({ "transcription.custom.language": v })}
+                options={langOptions()}
+                disabled={busy}
+              />
+            </Field>
+          </div>
+          <Field label={t("voice_ui.api_key_label")} hint={t("voice_ui.stt_custom_key_hint")}>
+            <Input
+              type="password"
+              autoComplete="new-password"
+              defaultValue=""
+              placeholder={keyPlaceholder(custom.api_key)}
+              onBlur={(e) => patchKey("transcription.custom.api_key", e.target.value)}
+              disabled={busy}
+            />
+          </Field>
+        </div>
+      )}
     </div>
   );
 }

package/src/interfaces/web/src/i18n/en.ts

@@ -940,6 +940,9 @@ export const en = {
     reload_manifest:     "Reload manifest",
     widget_native:       "Native APX widget",
     widget_external:     "External widget",
+    preview_badge:       "Preview",
+    preview_title:       "Deck — Coming soon",
+    preview_body:        "The Deck module is still in development and not released yet. We'll re-enable it once Deck ships in a stable release. For now everything here is read-only and no changes will be saved.",
   },
 
   memory_panel: {
@@ -1150,9 +1153,17 @@ export const en = {
     stt_model_hint:       "Bigger = more accurate and slower.",
     stt_language_label:   "Language",
     stt_language_hint:    "For Spanish, setting \"Spanish\" improves accuracy.",
-    stt_provider_auto:    "Automatic (local, then OpenAI)",
+    stt_provider_auto:    "Automatic (local, then remote)",
     stt_provider_local:   "Local — faster-whisper (offline)",
     stt_provider_openai:  "OpenAI — Whisper-1 (cloud)",
+    stt_provider_custom:  "Custom — OpenAI-compatible server",
+    stt_openai_model_label: "OpenAI model",
+    stt_openai_model_hint:  "Defaults to whisper-1.",
+    stt_custom_baseurl_label: "Base URL (OpenAI-compatible)",
+    stt_custom_baseurl_hint:  "e.g. http://localhost:8000/v1 (mlx-audio on Metal) or http://192.168.1.50:9000/v1 (Radeon/NVIDIA on the LAN).",
+    stt_custom_model_label:   "Model",
+    stt_custom_model_hint:    "e.g. mlx-community/whisper-large-v3-turbo or large-v3.",
+    stt_custom_key_hint:      "Optional — most local servers need no key.",
     lang_auto:            "Auto-detect",
     lang_es:              "Spanish",
     lang_en:              "English",
@@ -1302,18 +1313,33 @@ export const en = {
     desktop_pos_left:        "Left",
     desktop_pos_center:      "Center",
     desktop_pos_right:       "Right",
+    desktop_theme_system:    "System",
     desktop_theme_light:     "Light",
     desktop_theme_dark:      "Dark",
     desktop_status_desc:     "The window launches from the terminal or via autostart.",
     desktop_running:         "Running",
     desktop_stopped:         "Stopped",
     desktop_refresh:         "refresh",
+    desktop_start:           "Start",
+    desktop_stop:            "Stop",
+    desktop_restart:         "Restart",
+    desktop_restart_hint:    "Reload the open window so config changes (theme, position) apply now.",
+    desktop_restart_done:    "Restarting the window — applying the latest config.",
+    desktop_restart_none:    "No desktop window is connected.",
+    desktop_start_done:      "Desktop window launched.",
+    desktop_start_already:   "Desktop window is already running.",
+    desktop_stop_done:       "Desktop window stopped.",
+    desktop_stop_none:       "No desktop window was running.",
     desktop_from_terminal:   "From terminal:",
     desktop_autostart_desc:  "Launches the window at user login. Equivalent to `apx desktop install` (no sudo required).",
     desktop_platform:        "platform: {platform}",
     desktop_shortcut_desc:   "Global hotkey that shows/hides the window and starts listening.",
     desktop_accelerator:     "Accelerator",
-    desktop_accelerator_hint:"Electron format, e.g. \"CommandOrControl+G\" or \"CommandOrControl+Shift+Space\". Restart the window to apply.",
+    desktop_accelerator_hint:"Click the field and press your key combo. Restart the window to apply.",
+    desktop_shortcut_record:    "Click to set a shortcut",
+    desktop_shortcut_recording: "Press your combo…",
+    desktop_shortcut_change:    "click to change",
+    desktop_shortcut_esc:       "Esc to cancel",
     desktop_shortcut_saved:  "Shortcut saved. Restart the window (apx desktop stop && start) to apply it.",
     desktop_autostart_on:    "Autostart enabled for the next login.",
     desktop_autostart_off:   "Autostart disabled.",

package/src/interfaces/web/src/i18n/es.ts

@@ -938,6 +938,9 @@ export const es = {
     reload_manifest:     "Recargar manifest",
     widget_native:       "Widget nativo APX",
     widget_external:     "Widget externo",
+    preview_badge:       "Vista previa",
+    preview_title:       "Deck — Próximamente",
+    preview_body:        "El módulo Deck todavía está en desarrollo y no fue lanzado aún. Lo volveremos a activar cuando Deck salga en una versión estable. Por ahora todo acá es de solo lectura y no se guardará ningún cambio.",
   },
 
   memory_panel: {
@@ -1148,9 +1151,17 @@ export const es = {
     stt_model_hint:       "Más grande = más preciso y más lento.",
     stt_language_label:   "Idioma",
     stt_language_hint:    "Para español, elegir \"Español\" mejora la precisión.",
-    stt_provider_auto:    "Automático (local, después OpenAI)",
+    stt_provider_auto:    "Automático (local, después remoto)",
     stt_provider_local:   "Local — faster-whisper (offline)",
     stt_provider_openai:  "OpenAI — Whisper-1 (cloud)",
+    stt_provider_custom:  "Custom — server OpenAI-compatible",
+    stt_openai_model_label: "Modelo OpenAI",
+    stt_openai_model_hint:  "Por defecto whisper-1.",
+    stt_custom_baseurl_label: "URL base (OpenAI-compatible)",
+    stt_custom_baseurl_hint:  "Ej: http://localhost:8000/v1 (mlx-audio en Metal) o http://192.168.1.50:9000/v1 (Radeon/NVIDIA en la red).",
+    stt_custom_model_label:   "Modelo",
+    stt_custom_model_hint:    "Ej: mlx-community/whisper-large-v3-turbo o large-v3.",
+    stt_custom_key_hint:      "Opcional — la mayoría de los servers locales no requieren key.",
     lang_auto:            "Detección automática",
     lang_es:              "Español",
     lang_en:              "Inglés",
@@ -1300,18 +1311,33 @@ export const es = {
     desktop_pos_left:        "Izquierda",
     desktop_pos_center:      "Centro",
     desktop_pos_right:       "Derecha",
+    desktop_theme_system:    "Sistema",
     desktop_theme_light:     "Claro",
     desktop_theme_dark:      "Oscuro",
     desktop_status_desc:     "La ventana se abre desde la terminal o por arranque automático.",
     desktop_running:         "Corriendo",
     desktop_stopped:         "Detenida",
     desktop_refresh:         "refrescar",
+    desktop_start:           "Iniciar",
+    desktop_stop:            "Detener",
+    desktop_restart:         "Reiniciar",
+    desktop_restart_hint:    "Recarga la ventana abierta para aplicar ya los cambios de config (tema, posición).",
+    desktop_restart_done:    "Reiniciando la ventana — aplicando la última config.",
+    desktop_restart_none:    "No hay ninguna ventana de desktop conectada.",
+    desktop_start_done:      "Ventana de desktop iniciada.",
+    desktop_start_already:   "La ventana de desktop ya estaba corriendo.",
+    desktop_stop_done:       "Ventana de desktop detenida.",
+    desktop_stop_none:       "No había ninguna ventana de desktop corriendo.",
     desktop_from_terminal:   "Desde la terminal:",
     desktop_autostart_desc:  "Abre la ventana al iniciar sesión. Equivale a `apx desktop install` (no requiere sudo).",
     desktop_platform:        "plataforma: {platform}",
     desktop_shortcut_desc:   "Atajo global que muestra/oculta la ventana y empieza a escuchar.",
     desktop_accelerator:     "Acelerador",
-    desktop_accelerator_hint:"Formato Electron, ej. \"CommandOrControl+G\" o \"CommandOrControl+Shift+Space\". Reiniciá la ventana para aplicar.",
+    desktop_accelerator_hint:"Hacé clic en el campo y apretá tu combinación de teclas. Reiniciá la ventana para aplicar.",
+    desktop_shortcut_record:    "Hacé clic para definir un atajo",
+    desktop_shortcut_recording: "Apretá tu combinación…",
+    desktop_shortcut_change:    "clic para cambiar",
+    desktop_shortcut_esc:       "Esc para cancelar",
     desktop_shortcut_saved:  "Atajo guardado. Reiniciá la ventana (apx desktop stop && start) para aplicarlo.",
     desktop_autostart_on:    "Arranque automático habilitado para el próximo inicio de sesión.",
     desktop_autostart_off:   "Arranque automático deshabilitado.",

package/src/interfaces/web/src/lib/api/desktop.ts

@@ -16,6 +16,25 @@ export interface DesktopStatus {
   running: boolean;
 }
 
+export interface DesktopRestartResult {
+  ok: boolean;
+  /** How many connected windows were told to reload (0 = none connected). */
+  reloaded: number;
+}
+
+export interface DesktopStartResult {
+  ok: boolean;
+  pid?: number;
+  /** True when a window was already running (start was a no-op). */
+  already?: boolean;
+}
+
+export interface DesktopStopResult {
+  ok: boolean;
+  /** False when nothing was running. */
+  stopped?: boolean;
+}
+
 export interface AutostartStatus {
   ok: boolean;
   enabled: boolean;
@@ -26,6 +45,15 @@ export const Desktop = {
   /** GET /desktop/status — connected window count + running flag (live probe). */
   status: () => http.get<DesktopStatus>("/desktop/status"),
 
+  /** POST /desktop/start — launch the floating window (detached Electron). */
+  start: () => http.post<DesktopStartResult>("/desktop/start", {}),
+
+  /** POST /desktop/stop — terminate the running window. */
+  stop: () => http.post<DesktopStopResult>("/desktop/stop", {}),
+
+  /** POST /desktop/restart — tell every live window to reload + re-read config. */
+  restart: () => http.post<DesktopRestartResult>("/desktop/restart", {}),
+
   /** GET /desktop/autostart — current login-item state for this platform. */
   autostartGet: () => http.get<AutostartStatus>("/desktop/autostart"),
 

package/src/interfaces/web/src/lib/api/voice.ts

@@ -99,9 +99,33 @@ export interface TranscriptionLocalConfig {
   beam_size?: number;
   idle_minutes?: number;
 }
+export interface TranscriptionOpenAIConfig {
+  base_url?: string;     // defaults to https://api.openai.com/v1
+  api_key?: string;      // may carry a redacted "*** set ***" marker
+  model?: string;        // defaults to whisper-1
+}
+export interface TranscriptionCustomConfig {
+  base_url?: string;     // OpenAI-compatible server, e.g. http://localhost:8000/v1
+  api_key?: string;      // optional; may carry a redacted marker
+  model?: string;        // e.g. mlx-community/whisper-large-v3-turbo
+  language?: string;     // ISO code or "auto"
+}
 export interface TranscriptionConfig {
-  provider?: string;     // "auto" | "local" | "openai"
+  provider?: string;     // "auto" | "local" | "openai" | "custom"
   local?: TranscriptionLocalConfig;
+  openai?: TranscriptionOpenAIConfig;
+  custom?: TranscriptionCustomConfig;
+}
+
+/** One STT engine entry as reported by GET /transcribe/providers. */
+export interface SttProviderEntry {
+  id: string;             // "local" | "openai" | "custom"
+  available: boolean;
+  configured: boolean;
+}
+export interface SttProvidersResponse {
+  configured_provider: string;
+  engines: SttProviderEntry[];
 }
 
 // Known engine voice presets used to fill selects without a daemon round-trip.
@@ -109,7 +133,7 @@ export const OPENAI_TTS_VOICES = ["alloy", "echo", "fable", "onyx", "nova", "shi
 export const GEMINI_TTS_VOICES = ["Kore", "Puck", "Charon", "Fenrir", "Aoede"];
 export const ELEVENLABS_MODELS = ["eleven_multilingual_v2", "eleven_turbo_v2_5", "eleven_flash_v2_5"];
 export const OPENAI_TTS_MODELS = ["tts-1", "tts-1-hd"];
-export const WHISPER_MODELS = ["tiny", "base", "small", "medium", "large-v2", "large-v3"];
+export const WHISPER_MODELS = ["tiny", "base", "small", "medium", "large-v2", "large-v3", "large-v3-turbo"];
 
 // Friendly labels + ordering for the provider list. The daemon is the source
 // of truth for availability; this only adds display names + a stable order.

package/src/interfaces/web/src/screens/modules/DeckScreen.tsx

@@ -1,5 +1,5 @@
 import useSWR from "swr";
-import { RefreshCw } from "lucide-react";
+import { RefreshCw, Construction } from "lucide-react";
 import { Deck } from "../../lib/api/deck";
 import { Section } from "../../components/Section";
 import { Button, Empty, Loading } from "../../components/ui";
@@ -21,7 +21,17 @@ export function DeckScreen() {
     { refreshInterval: 30_000 }
   );
 
+  // ── Deck is NOT released yet ───────────────────────────────────────────
+  // The whole module is shown behind a non-dismissable "coming soon" modal
+  // (see the overlay at the bottom of this component) and the UI underneath is
+  // made inert. As defense-in-depth, the real widget mutation is disabled here
+  // too: if someone forces the modal out of the DOM, toggling a widget does
+  // NOTHING — no request ever hits the daemon, so nothing breaks.
+  // 👉 Re-enable the body below (remove this guard) when Deck ships in a stable
+  //    release. The original implementation is kept intact, just unreachable.
   const handleToggle = async (widgetId: string, enabled: boolean) => {
+    return; // no-op while Deck is pre-release — see note above.
+    // eslint-disable-next-line no-unreachable
     try {
       await Deck.setWidget(widgetId, { enabled });
       // Optimistically update local data so the switch flips immediately.
@@ -58,7 +68,11 @@ export function DeckScreen() {
       // Re-validate after a short delay to get the server's persisted state.
       setTimeout(() => mutate(), 800);
     } catch (e: unknown) {
-      const msg = e instanceof Error ? e.message : t("modules_ui.deck_save_error");
+      // `e` reads as `unknown` here because the early `return` above makes this
+      // catch unreachable while Deck is pre-release — TS skips control-flow
+      // narrowing in dead code. Cast so the kept-for-later body still
+      // typechecks; behaviour is unchanged (this block never runs today).
+      const msg = e instanceof Error ? (e as Error).message : t("modules_ui.deck_save_error");
       toast.error(msg);
     }
   };
@@ -77,7 +91,18 @@ export function DeckScreen() {
   const enabledCount = externalWidgets.filter((w) => w.user_enabled === true).length;
 
   return (
-    <div className="mx-auto max-w-4xl space-y-6 p-6" data-testid="screen-deck">
+    <div className="relative min-h-full" data-testid="screen-deck">
+      {/* ── Underlying Deck UI ──────────────────────────────────────────────
+          Shown for context only while Deck is pre-release. It is made fully
+          inert (no focus, no pointer events) and blurred behind the overlay
+          below. All real actions are also neutralized in code (see
+          handleToggle), so nothing runs even if this layer is re-enabled by
+          hand. Remove the `inert`/blur wrapper when Deck ships. */}
+    <div
+      className="mx-auto max-w-4xl space-y-6 p-6 pointer-events-none select-none blur-[2px] opacity-60"
+      aria-hidden
+      inert
+    >
       {/* Daemon info card */}
       {data && <DaemonCard manifest={data} />}
 
@@ -160,5 +185,32 @@ export function DeckScreen() {
         </Section>
       )}
     </div>
+
+      {/* ── "Coming soon" overlay ───────────────────────────────────────────
+          Non-dismissable: there is no close button and clicking the backdrop
+          does nothing. It floats over the inert Deck UI above. Remove this
+          whole block (and the inert wrapper / handleToggle guard) when Deck is
+          released. */}
+      <div
+        className="absolute inset-0 z-10 flex items-center justify-center p-6 backdrop-blur-[1px]"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="deck-coming-soon-title"
+        data-testid="deck-coming-soon"
+      >
+        <div className="w-full max-w-md rounded-2xl border border-border bg-card/95 p-8 text-center shadow-2xl">
+          <div className="mx-auto mb-4 flex size-12 items-center justify-center rounded-full bg-muted">
+            <Construction className="size-6 text-muted-fg" />
+          </div>
+          <span className="inline-block rounded-full bg-muted px-2.5 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-muted-fg">
+            {t("deck_screen.preview_badge")}
+          </span>
+          <h2 id="deck-coming-soon-title" className="mt-3 text-lg font-semibold">
+            {t("deck_screen.preview_title")}
+          </h2>
+          <p className="mt-2 text-sm text-muted-fg">{t("deck_screen.preview_body")}</p>
+        </div>
+      </div>
+    </div>
   );
 }

package/src/interfaces/web/src/screens/modules/DesktopScreen.tsx

@@ -2,8 +2,9 @@ import { useEffect, useMemo, useState } from "react";
 import { Link } from "react-router-dom";
 import useSWR from "swr";
 import { Section, Kbd, StatusDot } from "../../components/Section";
-import { Button, Field, Input, Switch, Loading, Empty } from "../../components/ui";
+import { Button, Field, Switch, Loading, Empty } from "../../components/ui";
 import { UiSelect } from "../../components/UiSelect";
+import { ShortcutInput } from "../../components/ShortcutInput";
 import { useToast } from "../../components/Toast";
 import { useGlobalConfig } from "../../hooks/useGlobalConfig";
 import { Desktop, fetchDesktopMessages, type GlobalMessage } from "../../lib/api/desktop";
@@ -16,8 +17,9 @@ const positionOpts = () => [
   { value: "right",  label: t("modules_ui.desktop_pos_right") },
 ];
 const themeOpts = () => [
-  { value: "light", label: t("modules_ui.desktop_theme_light") },
-  { value: "dark",  label: t("modules_ui.desktop_theme_dark") },
+  { value: "system", label: t("modules_ui.desktop_theme_system") },
+  { value: "light",  label: t("modules_ui.desktop_theme_light") },
+  { value: "dark",   label: t("modules_ui.desktop_theme_dark") },
 ];
 
 // Desktop module — manage the floating voice window (the Electron app launched
@@ -32,14 +34,16 @@ export function DesktopScreen() {
   const cfgView = config as unknown as {
     desktop?: {
       shortcut?: string; enabled?: boolean;
-      theme?: "light" | "dark";
+      theme?: "light" | "dark" | "system";
       position?: "left" | "center" | "right";
     };
     overlay?: { shortcut?: string }; // legacy fallback
   };
   const savedShortcut = cfgView.desktop?.shortcut || cfgView.overlay?.shortcut || DEFAULT_SHORTCUT;
   const enabled  = cfgView.desktop?.enabled !== false;
-  const theme    = cfgView.desktop?.theme    || "light";
+  // Default to "system" so the window follows the OS appearance until the
+  // user explicitly pins light/dark.
+  const theme    = cfgView.desktop?.theme    || "system";
   const position = cfgView.desktop?.position || "right";
 
   const { data: status, isLoading: stLoading, mutate: mutateStatus } = useSWR(
@@ -63,8 +67,35 @@ export function DesktopScreen() {
   const [shortcut, setShortcut] = useState(savedShortcut);
   const [busy, setBusy] = useState(false);
   const [autostartBusy, setAutostartBusy] = useState(false);
+  // Which lifecycle action (start/stop/restart) is in flight — drives the
+  // per-button spinner and disables its siblings while one runs.
+  const [lifeAction, setLifeAction] = useState<"start" | "stop" | "restart" | null>(null);
   useEffect(() => setShortcut(savedShortcut), [savedShortcut]);
 
+  // Start/Stop launch or kill the Electron window (daemon spawns/SIGTERMs it);
+  // Restart tells a live window to reload + re-read config (theme, position,
+  // shortcut) — the "apply now" the static status-poll never did. All three
+  // re-poll status shortly after so the dot + buttons settle.
+  const runLifecycle = async (action: "start" | "stop" | "restart", fn: () => Promise<void>) => {
+    setLifeAction(action);
+    try { await fn(); }
+    catch (e) { toast.error((e as Error).message); }
+    finally { setLifeAction(null); setTimeout(() => mutateStatus(), 1200); }
+  };
+  const startDesktop = () => runLifecycle("start", async () => {
+    const r = await Desktop.start();
+    toast.success(r.already ? t("modules_ui.desktop_start_already") : t("modules_ui.desktop_start_done"));
+  });
+  const stopDesktop = () => runLifecycle("stop", async () => {
+    const r = await Desktop.stop();
+    toast.success(r.stopped ? t("modules_ui.desktop_stop_done") : t("modules_ui.desktop_stop_none"));
+  });
+  const restartDesktop = () => runLifecycle("restart", async () => {
+    const r = await Desktop.restart();
+    if (r.reloaded > 0) toast.success(t("modules_ui.desktop_restart_done"));
+    else toast.info(t("modules_ui.desktop_restart_none"));
+  });
+
   const saveShortcut = async () => {
     const next = shortcut.trim();
     if (!next || next === savedShortcut) return;
@@ -101,23 +132,58 @@ export function DesktopScreen() {
       <div className="grid gap-6 xl:grid-cols-[1fr_1fr]">
         {/* ── LEFT: configuration + status ─────────────────────────────── */}
         <div className="space-y-6">
-          <Section title={t("desktop_screen.status_title")} description={t("modules_ui.desktop_status_desc")}>
+          <Section
+            title={t("desktop_screen.status_title")}
+            description={t("modules_ui.desktop_status_desc")}
+            action={
+              <div className="flex items-center gap-2">
+                <Button
+                  variant="primary"
+                  size="sm"
+                  onClick={startDesktop}
+                  loading={lifeAction === "start"}
+                  disabled={running || (lifeAction !== null && lifeAction !== "start")}
+                >
+                  {t("modules_ui.desktop_start")}
+                </Button>
+                <Button
+                  variant="secondary"
+                  size="sm"
+                  onClick={stopDesktop}
+                  loading={lifeAction === "stop"}
+                  disabled={!running || (lifeAction !== null && lifeAction !== "stop")}
+                >
+                  {t("modules_ui.desktop_stop")}
+                </Button>
+                <Button
+                  variant="secondary"
+                  size="sm"
+                  onClick={restartDesktop}
+                  loading={lifeAction === "restart"}
+                  disabled={!running || (lifeAction !== null && lifeAction !== "restart")}
+                  title={t("modules_ui.desktop_restart_hint")}
+                >
+                  {t("modules_ui.desktop_restart")}
+                </Button>
+              </div>
+            }
+          >
             {stLoading ? <Loading /> : (
-              <div className="flex items-center gap-2 text-sm">
+              <div className="flex flex-wrap items-center gap-x-2 gap-y-1 text-sm">
                 <StatusDot ok={running} />
                 <span className="font-medium">{running ? t("modules_ui.desktop_running") : t("modules_ui.desktop_stopped")}</span>
                 <button
                   type="button"
                   onClick={() => mutateStatus()}
-                  className="ml-2 text-xs text-muted-fg underline-offset-2 hover:underline"
+                  className="text-xs text-muted-fg underline-offset-2 hover:underline"
                 >
                   {t("modules_ui.desktop_refresh")}
                 </button>
+                <span className="text-xs text-muted-fg">
+                  ({t("modules_ui.desktop_from_terminal")} <Kbd>apx desktop start</Kbd> · <Kbd>apx desktop --debug</Kbd>)
+                </span>
               </div>
             )}
-            <p className="mt-3 text-xs text-muted-fg">
-              {t("modules_ui.desktop_from_terminal")} <Kbd>apx desktop start</Kbd> · <Kbd>apx desktop --debug</Kbd>
-            </p>
           </Section>
 
           <Section
@@ -142,31 +208,27 @@ export function DesktopScreen() {
             description={t("modules_ui.desktop_shortcut_desc")}
           >
             {cfgLoading ? <Loading /> : (
-              <div className="flex items-end gap-3">
-                <div className="flex-1">
-                  <Field
-                    label={t("modules_ui.desktop_accelerator")}
-                    hint={t("modules_ui.desktop_accelerator_hint")}
-                  >
-                    <Input
-                      value={shortcut}
-                      onChange={(e) => setShortcut(e.target.value)}
-                      onKeyDown={(e) => { if (e.key === "Enter") saveShortcut(); }}
-                      placeholder={DEFAULT_SHORTCUT}
-                      className="max-w-md font-mono"
-                      disabled={busy}
-                    />
-                  </Field>
-                </div>
-                <Button
-                  variant="primary"
-                  onClick={saveShortcut}
-                  loading={busy}
-                  disabled={!shortcut.trim() || shortcut.trim() === savedShortcut}
-                >
-                  {t("common.save")}
-                </Button>
-              </div>
+              <Field
+                label={t("modules_ui.desktop_accelerator")}
+                hint={t("modules_ui.desktop_accelerator_hint")}
+              >
+                <ShortcutInput
+                  value={shortcut}
+                  onChange={setShortcut}
+                  disabled={busy}
+                  trailing={
+                    <Button
+                      variant="primary"
+                      size="sm"
+                      onClick={saveShortcut}
+                      loading={busy}
+                      disabled={!shortcut.trim() || shortcut.trim() === savedShortcut}
+                    >
+                      {t("common.save")}
+                    </Button>
+                  }
+                />
+              </Field>
             )}
           </Section>