feat(desktop): Linux AppImage polish — window controls, updater UX, docs (#2144)

* feat(electron): add Linux AppImage releases * ci: cache Linux OpenCode CLI artifacts * fix(ci): await Linux release inventory check * fix(electron): add frameless window controls on Linux desktop Linux AppImages were created without native WM decorations and without in-app controls, leaving users unable to close the window with a mouse. Treat Linux like Windows: frameless BrowserWindow plus the existing WindowsWindowControls header buttons and app-menu entry. macOS keeps hidden title bar with traffic lights unchanged. Shared usesFramelessElectronChrome() helper drives main window, mini chat, header insets, and titlebar controls. Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com> * feat(desktop): add configurable window controls position by OS Add desktopWindowControlsPosition setting (auto/left/right) with OS-aware defaults: Linux left, Windows right. Wire frameless chrome controls in Header, TitlebarLeftControls, and MiniChatLayout, plus a Sessions settings control for Windows and Linux desktop shells. Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com> * fix(desktop): address Linux AppImage release review findings Propagate updater capability errors to the UI, treat missing latest-linux.yml feeds as no-update, stop installed-apps IPC spam on Linux, document FUSE/AppImage limits, add CHANGELOG entry, migrate remaining btriapitsyn URLs, and run Electron Linux unit tests on PRs. Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com> --------- Co-authored-by: jibanez-staticduo <staticduo@gmail.com> Co-authored-by: Serhii Dziupin <makeittech@users.noreply.github.com>
2026-07-13 08:59:31 +03:00
parent 7e248d4e9b
commit 502c96630e
55 changed files with 1679 additions and 112 deletions
@@ -4,12 +4,17 @@ import { Icon } from '@/components/icon/Icon';
 import { useI18n } from '@/lib/i18n';
 import { cn } from '@/lib/utils';
 import { invokeDesktop } from '@/lib/desktop';
+import type { DesktopWindowControlsSide } from '@/lib/desktop';

 type WindowsWindowControlsProps = {
  visible: boolean;
+  position?: DesktopWindowControlsSide;
 };

-export const WindowsWindowControls = React.memo(function WindowsWindowControls({ visible }: WindowsWindowControlsProps) {
+export const WindowsWindowControls = React.memo(function WindowsWindowControls({
+  visible,
+  position = 'right',
+}: WindowsWindowControlsProps) {
  const { t } = useI18n();
  const [isMaximized, setIsMaximized] = React.useState(false);

@@ -44,9 +49,12 @@ export const WindowsWindowControls = React.memo(function WindowsWindowControls({
  }

  const buttonClassName = 'app-region-no-drag inline-flex h-12 w-11 items-center justify-center text-muted-foreground transition-colors hover:bg-interactive-hover hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary';
+  const containerClassName = position === 'left'
+    ? 'app-region-no-drag -ml-3 mr-2 flex h-12 shrink-0 items-center'
+    : 'app-region-no-drag -mr-3 ml-2 flex h-12 shrink-0 items-center';

  return (
-    <div className="app-region-no-drag -mr-3 ml-2 flex h-12 shrink-0 items-center" aria-label={t('header.windowControls.groupAria')}>
+    <div className={containerClassName} aria-label={t('header.windowControls.groupAria')}>
      <button
        type="button"
        className={buttonClassName}
@@ -31,6 +31,7 @@ import { useFeatureFlagsStore } from '@/stores/useFeatureFlagsStore';

 import { useGitHubAuthStore } from '@/stores/useGitHubAuthStore';
 import { useRuntimeAPIs } from '@/hooks/useRuntimeAPIs';
+import { useDesktopWindowControlsLayout } from '@/hooks/useDesktopWindowControlsLayout';
 import { ContextUsageDisplay } from '@/components/ui/ContextUsageDisplay';
 import { WindowsWindowControls } from '@/components/desktop/WindowsWindowControls';
 import { UpdateDialog } from '@/components/ui/UpdateDialog';
@@ -789,12 +790,7 @@ export const Header: React.FC<HeaderProps> = ({
    return /Macintosh|Mac OS X/.test(navigator.userAgent || '');
  }, []);

-  const isWindowsElectronDesktop = React.useMemo(() => {
-    if (typeof window === 'undefined') {
-      return false;
-    }
-    return Boolean(window.__OPENCHAMBER_ELECTRON__) && window.__OPENCHAMBER_PLATFORM__ === 'win32';
-  }, []);
+  const { usesFramelessChrome, side: windowControlsSide } = useDesktopWindowControlsLayout();

  const macosMajorVersion = React.useMemo(() => {
    if (typeof window === 'undefined') {
@@ -1598,11 +1594,11 @@ export const Header: React.FC<HeaderProps> = ({
    if (isTabletStandalonePwa) {
      return 'max(calc(0.75rem + var(--oc-wco-left-inset, 0px)), 5.5rem)';
    }
-    if ((!isDesktopApp || isWindowsElectronDesktop) && !isVSCode) {
+    if ((!isDesktopApp || usesFramelessChrome) && !isVSCode) {
      return 'calc(0.75rem + var(--oc-wco-left-inset, 0px))';
    }
    return '0.75rem';
-  }, [isDesktopApp, isDesktopWindowFullscreen, isMacPlatform, isTabletStandalonePwa, isVSCode, isWindowsElectronDesktop]);
+  }, [isDesktopApp, isDesktopWindowFullscreen, isMacPlatform, isTabletStandalonePwa, isVSCode, usesFramelessChrome]);

  useEffect(() => {
    if (typeof document === 'undefined') {
@@ -1671,7 +1667,7 @@ export const Header: React.FC<HeaderProps> = ({
  }, [isDesktopApp, isMacPlatform, macosMajorVersion]);

  const webWindowControlsOverlayStyle = React.useMemo<React.CSSProperties | undefined>(() => {
-    if ((isDesktopApp && !isWindowsElectronDesktop) || isVSCode) {
+    if ((isDesktopApp && !usesFramelessChrome) || isVSCode) {
      return undefined;
    }

@@ -1682,7 +1678,7 @@ export const Header: React.FC<HeaderProps> = ({
      minHeight: 'max(3rem, var(--oc-wco-titlebar-height, 0px))',
      height: 'max(3rem, var(--oc-wco-titlebar-height, 0px))',
    };
-  }, [isDesktopApp, isVSCode, isWindowsElectronDesktop]);
+  }, [isDesktopApp, isVSCode, usesFramelessChrome]);

  const updateHeaderHeight = React.useCallback(() => {
    if (typeof document === 'undefined') {
@@ -2217,7 +2213,7 @@ export const Header: React.FC<HeaderProps> = ({
            Icon={'picture-in-picture-2'}
          />
          {desktopSidebarActions}
-          <WindowsWindowControls visible={isWindowsElectronDesktop} />
+          <WindowsWindowControls visible={usesFramelessChrome && windowControlsSide === 'right'} position="right" />
        </div>
      </div>
    </div>
@@ -6,8 +6,10 @@ import { useUIStore } from '@/stores/useUIStore';
 import { useI18n } from '@/lib/i18n';
 import { useProjectActionsContext } from '@/hooks/useProjectActionsContext';
 import { ProjectActionsButton } from '@/components/layout/ProjectActionsButton';
+import { WindowsWindowControls } from '@/components/desktop/WindowsWindowControls';
 import { formatShortcutForDisplay, getEffectiveShortcutCombo } from '@/lib/shortcuts';
 import { invokeDesktop } from '@/lib/desktop';
+import { useDesktopWindowControlsLayout } from '@/hooks/useDesktopWindowControlsLayout';

 const ICON_BUTTON_CLASS =
  'app-region-no-drag inline-flex h-8 w-8 items-center justify-center gap-2 rounded-md typography-ui-label font-medium text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary hover:bg-interactive-hover transition-colors';
@@ -32,12 +34,7 @@ export const TitlebarLeftControls: React.FC = () => {
  const clusterRef = React.useRef<HTMLDivElement | null>(null);

  const toggleShortcut = formatShortcutForDisplay(getEffectiveShortcutCombo('toggle_sidebar', shortcutOverrides));
-  const isWindowsElectronDesktop = React.useMemo(() => {
-    if (typeof window === 'undefined') {
-      return false;
-    }
-    return Boolean(window.__OPENCHAMBER_ELECTRON__) && window.__OPENCHAMBER_PLATFORM__ === 'win32';
-  }, []);
+  const { usesFramelessChrome, side: windowControlsSide } = useDesktopWindowControlsLayout();

  const handleOpenWindowsAppMenu = React.useCallback((event: React.MouseEvent<HTMLButtonElement>) => {
    const rect = event.currentTarget.getBoundingClientRect();
@@ -88,7 +85,11 @@ export const TitlebarLeftControls: React.FC = () => {
      }}
    >
      <div ref={clusterRef} className="flex items-center gap-2">
-        {isWindowsElectronDesktop ? (
+        {usesFramelessChrome && windowControlsSide === 'left' ? (
+          <WindowsWindowControls visible position="left" />
+        ) : null}
+
+        {usesFramelessChrome ? (
          <Tooltip>
            <TooltipTrigger asChild>
              <button
@@ -8,6 +8,7 @@ import { SessionSwitcherDropdown } from '@/components/session/SessionSwitcherDro
 import { cn } from '@/lib/utils';
 import { useI18n } from '@/lib/i18n';
 import { invokeDesktop, isElectronShell } from '@/lib/desktop';
+import { useDesktopWindowControlsLayout } from '@/hooks/useDesktopWindowControlsLayout';
 import { useSessionUIStore } from '@/sync/session-ui-store';
 import { useSessionWorktreeStore } from '@/sync/session-worktree-store';
 import { useSessionMessages, useSessions } from '@/sync/sync-context';
@@ -69,9 +70,7 @@ const MiniChatHeader: React.FC<{ mode: MiniChatMode }> = ({ mode }) => {
  const [pinned, setPinned] = React.useState(false);
  const macosMajor = typeof window !== 'undefined' ? window.__OPENCHAMBER_MACOS_MAJOR__ ?? 0 : 0;
  const hasMacTrafficLights = Number.isFinite(macosMajor) && macosMajor > 0;
-  const isWindowsElectronDesktop = typeof window !== 'undefined'
-    && Boolean(window.__OPENCHAMBER_ELECTRON__)
-    && window.__OPENCHAMBER_PLATFORM__ === 'win32';
+  const { usesFramelessChrome, side: windowControlsSide } = useDesktopWindowControlsLayout();
  const macosHeaderSizeClass = hasMacTrafficLights
    ? macosMajor >= 26
      ? 'h-12'
@@ -256,10 +255,13 @@ const MiniChatHeader: React.FC<{ mode: MiniChatMode }> = ({ mode }) => {
      className={cn(
        'flex items-center gap-3 bg-background pr-3',
        hasMacTrafficLights ? 'pl-[5.5rem]' : 'pl-3',
-        isWindowsElectronDesktop ? 'h-12' : macosHeaderSizeClass || 'min-h-14',
+        usesFramelessChrome ? 'h-12' : macosHeaderSizeClass || 'min-h-14',
      )}
      style={dragRegionStyle}
    >
+      {usesFramelessChrome && windowControlsSide === 'left' ? (
+        <WindowsWindowControls visible position="left" />
+      ) : null}
      <SessionSwitcherDropdown>
        <button
          type="button"
@@ -318,7 +320,7 @@ const MiniChatHeader: React.FC<{ mode: MiniChatMode }> = ({ mode }) => {
      >
        <Icon name="external-link" className="h-4 w-4" />
      </Button>
-      <WindowsWindowControls visible={isWindowsElectronDesktop} />
+      <WindowsWindowControls visible={usesFramelessChrome && windowControlsSide === 'right'} position="right" />
    </header>
  );
 };
@@ -14,14 +14,29 @@ import {
  setDesktopKeepAwake,
  setDesktopLaunchAtLogin,
  setDesktopMinimizeToTray,
+  usesFramelessElectronChrome,
+  type DesktopWindowControlsPosition,
 } from '@/lib/desktop';
 import { useI18n } from '@/lib/i18n';
+import { updateDesktopSettings } from '@/lib/persistence';
 import { runtimeFetch } from '@/lib/runtime-fetch';
 import { getRuntimeApiBaseUrl } from '@/lib/runtime-switch';
+import { useUIStore } from '@/stores/useUIStore';
+import { cn } from '@/lib/utils';
+
+const WINDOW_CONTROLS_POSITION_OPTIONS: Array<{ id: DesktopWindowControlsPosition; labelKey: string }> = [
+  { id: 'auto', labelKey: 'settings.openchamber.desktopNetwork.option.windowControlsAuto' },
+  { id: 'left', labelKey: 'settings.openchamber.desktopNetwork.option.windowControlsLeft' },
+  { id: 'right', labelKey: 'settings.openchamber.desktopNetwork.option.windowControlsRight' },
+];

 export const DesktopNetworkSettings: React.FC = () => {
  const { t } = useI18n();
+  const tUnsafe = React.useCallback((key: string) => t(key as Parameters<typeof t>[0]), [t]);
  const isLocalDesktop = isDesktopShell() && isDesktopLocalOriginActive();
+  const showWindowControlsPosition = usesFramelessElectronChrome();
+  const desktopWindowControlsPosition = useUIStore((state) => state.desktopWindowControlsPosition);
+  const setDesktopWindowControlsPosition = useUIStore((state) => state.setDesktopWindowControlsPosition);
  const [savedValue, setSavedValue] = React.useState(false);
  const [draftValue, setDraftValue] = React.useState(false);
  const [savedPassword, setSavedPassword] = React.useState('');
@@ -211,6 +226,11 @@ export const DesktopNetworkSettings: React.FC = () => {
    }
  }, []);

+  const handleWindowControlsPositionChange = React.useCallback((value: DesktopWindowControlsPosition) => {
+    setDesktopWindowControlsPosition(value);
+    void updateDesktopSettings({ desktopWindowControlsPosition: value });
+  }, [setDesktopWindowControlsPosition]);
+
  const handleLaunchAtLoginToggle = React.useCallback(async () => {
    if (!launchAtLoginSupported || isSavingLaunchAtLogin) {
      return;
@@ -324,12 +344,54 @@ export const DesktopNetworkSettings: React.FC = () => {
    }
  }, [draftPassword, draftValue, isDirty, t]);

-  if (!isLocalDesktop) {
+  if (!isLocalDesktop && !showWindowControlsPosition) {
    return null;
  }

  return (
    <div className="mb-8">
+      {showWindowControlsPosition ? (
+        <>
+          <div className="mb-1 px-1">
+            <h3 className="typography-ui-header font-medium text-foreground">{t('settings.openchamber.desktopNetwork.field.windowControlsPosition')}</h3>
+          </div>
+          <section className="space-y-2 px-2 pb-2 pt-0">
+            <div data-settings-item="sessions.desktop-window-controls-position" className="space-y-1 py-1.5">
+              <div className="typography-micro text-muted-foreground/70">
+                {t('settings.openchamber.desktopNetwork.field.windowControlsPositionDescription')}
+              </div>
+              <div
+                className="mt-1 flex flex-wrap items-center gap-1"
+                role="group"
+                aria-label={t('settings.openchamber.desktopNetwork.field.windowControlsPositionAria')}
+              >
+                {WINDOW_CONTROLS_POSITION_OPTIONS.map((option) => {
+                  const selected = desktopWindowControlsPosition === option.id;
+                  return (
+                    <Button
+                      key={option.id}
+                      type="button"
+                      variant="outline"
+                      size="xs"
+                      className={cn(
+                        '!font-normal',
+                        selected ? 'border-[var(--primary-base)] text-[var(--primary-base)] bg-[var(--primary-base)]/10' : 'text-foreground',
+                      )}
+                      aria-pressed={selected}
+                      onClick={() => handleWindowControlsPositionChange(option.id)}
+                    >
+                      {tUnsafe(option.labelKey)}
+                    </Button>
+                  );
+                })}
+              </div>
+            </div>
+          </section>
+        </>
+      ) : null}
+
+      {!isLocalDesktop ? null : (
+        <>
      <div className="mb-1 px-1">
        <h3 className="typography-ui-header font-medium text-foreground">{t('settings.openchamber.desktopNetwork.title')}</h3>
      </div>
@@ -502,6 +564,8 @@ export const DesktopNetworkSettings: React.FC = () => {
          </Button>
        </div>
      </section>
+        </>
+      )}
    </div>
  );
 };
@@ -14,7 +14,7 @@ import { DesktopNetworkSettings } from './DesktopNetworkSettings';
 import { KeyboardShortcutsSettings } from './KeyboardShortcutsSettings';
 import { ScrollableOverlay } from '@/components/ui/ScrollableOverlay';
 import { useDeviceInfo } from '@/lib/device';
-import { isDesktopLocalOriginActive, isDesktopShell, isVSCodeRuntime, isWebRuntime } from '@/lib/desktop';
+import { isDesktopLocalOriginActive, isDesktopShell, isVSCodeRuntime, isWebRuntime, usesFramelessElectronChrome } from '@/lib/desktop';
 import { subscribeRuntimeEndpointChanged } from '@/lib/runtime-switch';
 import type { OpenChamberSection } from './types';

@@ -39,7 +39,7 @@ export const OpenChamberPage: React.FC<OpenChamberPageProps> = ({ section }) =>
    const showAbout = isMobile && isWebRuntime();
    const isVSCode = isVSCodeRuntime();
    void runtimeEndpointEpoch;
-    const showDesktopNetworkSettings = isDesktopShell() && isDesktopLocalOriginActive();
+    const showDesktopNetworkSettings = isDesktopShell() && (isDesktopLocalOriginActive() || usesFramelessElectronChrome());

    // If no section specified, show all (mobile/legacy behavior)
    if (!section) {
@@ -153,7 +153,7 @@ const SessionsSectionContent: React.FC = () => {
    const isVSCode = isVSCodeRuntime();
    const runtimeEndpointEpoch = useRuntimeEndpointEpoch();
    void runtimeEndpointEpoch;
-    const showDesktopNetworkSettings = isDesktopShell() && isDesktopLocalOriginActive();
+    const showDesktopNetworkSettings = isDesktopShell() && (isDesktopLocalOriginActive() || usesFramelessElectronChrome());
    return (
        <div className="space-y-6">
            <DefaultsSettings />
@@ -184,7 +184,7 @@ export const AboutDialog: React.FC<AboutDialogProps> = ({
          <div className="flex flex-col items-center gap-2 pt-2">
            <div className="flex items-center justify-center gap-4">
              <a
-                href="https://github.com/btriapitsyn/openchamber"
+                href="https://github.com/openchamber/openchamber"
                target="_blank"
                rel="noopener noreferrer"
                className="flex items-center gap-1.5 typography-meta text-muted-foreground hover:text-foreground transition-colors"
@@ -0,0 +1,21 @@
+import { useMemo } from 'react';
+
+import {
+  resolveDesktopWindowControlsSide,
+  usesFramelessElectronChrome,
+  type DesktopWindowControlsSide,
+} from '@/lib/desktop';
+import { useUIStore } from '@/stores/useUIStore';
+
+export function useDesktopWindowControlsLayout(): {
+  usesFramelessChrome: boolean;
+  side: DesktopWindowControlsSide;
+} {
+  const preference = useUIStore((state) => state.desktopWindowControlsPosition);
+
+  return useMemo(() => {
+    const usesFramelessChrome = usesFramelessElectronChrome();
+    const side = resolveDesktopWindowControlsSide(preference);
+    return { usesFramelessChrome, side };
+  }, [preference]);
+}
@@ -38,6 +38,9 @@ export type SkillCatalogConfig = {
  gitIdentityId?: string;
 };

+export type DesktopWindowControlsPosition = 'auto' | 'left' | 'right';
+export type DesktopWindowControlsSide = 'left' | 'right';
+
 export type DesktopSettings = {
  themeId?: string;
  useSystemTheme?: boolean;
@@ -136,6 +139,7 @@ export type DesktopSettings = {
  pwaAppName?: string;
  pwaOrientation?: 'system' | 'portrait' | 'landscape';
  mobileKeyboardMode?: MobileKeyboardMode;
+  desktopWindowControlsPosition?: DesktopWindowControlsPosition;
  inputSpellcheckEnabled?: boolean;
  showOpenCodeUpdateNotifications?: boolean;
  openCodeUpdateToastDismissedVersion?: string;
@@ -231,6 +235,39 @@ const getDesktopBridge = (): DesktopBridgeGlobal | null => {

 export const isElectronShell = (): boolean => getElectronRuntime()?.runtime === 'electron';

+export const getElectronPlatform = (): string | null => {
+  if (typeof window === 'undefined') return null;
+  const platform = (window as unknown as { __OPENCHAMBER_PLATFORM__?: string }).__OPENCHAMBER_PLATFORM__;
+  return typeof platform === 'string' ? platform : null;
+};
+
+/** Width of the three in-app window control buttons (3 × w-11). */
+export const DESKTOP_WINDOW_CONTROLS_WIDTH_PX = 132;
+
+/** Windows and Linux use frameless windows with in-app minimize/maximize/close controls. */
+export const usesFramelessElectronChrome = (): boolean => {
+  if (!isElectronShell()) return false;
+  const platform = getElectronPlatform();
+  return platform === 'win32' || platform === 'linux';
+};
+
+export const getDefaultDesktopWindowControlsSide = (platform: string | null = getElectronPlatform()): DesktopWindowControlsSide => {
+  if (platform === 'linux') {
+    return 'left';
+  }
+  return 'right';
+};
+
+export const resolveDesktopWindowControlsSide = (
+  preference: DesktopWindowControlsPosition | undefined,
+  platform: string | null = getElectronPlatform(),
+): DesktopWindowControlsSide => {
+  if (preference === 'left' || preference === 'right') {
+    return preference;
+  }
+  return getDefaultDesktopWindowControlsSide(platform);
+};
+
 export const hasDesktopInvoke = (): boolean => {
  return typeof getDesktopBridge()?.invoke === 'function';
 };
@@ -619,13 +656,8 @@ export const checkForDesktopUpdates = async (): Promise<UpdateInfo | null> => {
    return null;
  }

-  try {
-    const info = await invokeDesktop<UpdateInfo>('desktop_check_for_updates');
-    return info as UpdateInfo;
-  } catch (error) {
-    console.warn('Failed to check for updates', error);
-    return null;
-  }
+  const info = await invokeDesktop<UpdateInfo>('desktop_check_for_updates');
+  return info as UpdateInfo;
 };

 export const downloadDesktopUpdate = async (
@@ -674,8 +706,8 @@ export const downloadDesktopUpdate = async (
    await invokeDesktop('desktop_download_and_install_update');
    return true;
  } catch (error) {
-    console.warn('Failed to download update', error);
-    return false;
+    // Propagate actionable updater capability / install errors to the UI store.
+    throw error instanceof Error ? error : new Error(String(error));
  } finally {
    if (unlisten) {
      try {
@@ -873,6 +905,11 @@ export const fetchDesktopInstalledApps = async (
    return { apps: [], success: false, hasCache: false, isCacheStale: false };
  }

+  // Linux desktop does not resolve installed GUI apps; skip the IPC round-trip.
+  if (getElectronPlatform() === 'linux') {
+    return { apps: [], success: true, hasCache: false, isCacheStale: false };
+  }
+
  const candidate = Array.isArray(apps) ? apps.filter((value) => typeof value === 'string') : [];
  if (candidate.length === 0) {
    return { apps: [], success: true, hasCache: false, isCacheStale: false };
@@ -886,7 +923,10 @@ export const fetchDesktopInstalledApps = async (
    if (!result || typeof result !== 'object') {
      return { apps: [], success: false, hasCache: false, isCacheStale: false };
    }
-    const payload = result as { apps?: unknown; hasCache?: unknown; isCacheStale?: unknown };
+    const payload = result as { apps?: unknown; hasCache?: unknown; isCacheStale?: unknown; supported?: unknown };
+    if (payload.supported === false) {
+      return { apps: [], success: true, hasCache: false, isCacheStale: false };
+    }
    if (!Array.isArray(payload.apps)) {
      return { apps: [], success: false, hasCache: false, isCacheStale: false };
    }
@@ -893,6 +893,12 @@ export const settingsDict = {
  'settings.openchamber.sessionRetention.toast.failedArchiveCount': 'Failed to archive {count} session(s)',
  'settings.openchamber.sessionRetention.toast.failedDeleteCount': 'Failed to delete {count} session(s)',
  'settings.openchamber.desktopNetwork.title': 'Desktop Network Access',
+  'settings.openchamber.desktopNetwork.field.windowControlsPosition': 'Window controls position',
+  'settings.openchamber.desktopNetwork.field.windowControlsPositionDescription': 'Choose where minimize, maximize, and close buttons appear. Auto follows your operating system.',
+  'settings.openchamber.desktopNetwork.field.windowControlsPositionAria': 'Window controls position',
+  'settings.openchamber.desktopNetwork.option.windowControlsAuto': 'Auto',
+  'settings.openchamber.desktopNetwork.option.windowControlsLeft': 'Left',
+  'settings.openchamber.desktopNetwork.option.windowControlsRight': 'Right',
  'settings.openchamber.desktopNetwork.field.launchAtLoginAria': 'Start OpenChamber at login',
  'settings.openchamber.desktopNetwork.field.launchAtLogin': 'Start OpenChamber when you log in',
  'settings.openchamber.desktopNetwork.field.launchAtLoginDescription': 'Starts the app in the background without opening a window. Use the desktop status icon to open it.',
@@ -860,6 +860,12 @@ export const settingsDict = {
  "settings.openchamber.sessionRetention.toast.failedArchiveCount": "No se pudo archivar {count} sesión(es)",
  "settings.openchamber.sessionRetention.toast.failedDeleteCount": "No se pudo eliminar {count} sesión(es)",
  "settings.openchamber.desktopNetwork.title": "Acceso de red de escritorio",
+  "settings.openchamber.desktopNetwork.field.windowControlsPosition": "Posición de los controles de ventana",
+  "settings.openchamber.desktopNetwork.field.windowControlsPositionDescription": "Elige dónde aparecen los botones de minimizar, maximizar y cerrar. Automático sigue el sistema operativo.",
+  "settings.openchamber.desktopNetwork.field.windowControlsPositionAria": "Posición de los controles de ventana",
+  "settings.openchamber.desktopNetwork.option.windowControlsAuto": "Automático",
+  "settings.openchamber.desktopNetwork.option.windowControlsLeft": "Izquierda",
+  "settings.openchamber.desktopNetwork.option.windowControlsRight": "Derecha",
  "settings.openchamber.desktopNetwork.field.launchAtLoginAria": "Iniciar OpenChamber al iniciar sesión",
  "settings.openchamber.desktopNetwork.field.launchAtLogin": "Iniciar OpenChamber al iniciar sesión",
  "settings.openchamber.desktopNetwork.field.launchAtLoginDescription": "Inicia la app en segundo plano sin abrir una ventana. Usa el icono de estado del escritorio para abrirla.",
@@ -785,6 +785,12 @@ export const settingsDict = {
  'settings.openchamber.sessionRetention.toast.failedArchiveCount': 'Échec de l\'archivage des sessions {count}',
  'settings.openchamber.sessionRetention.toast.failedDeleteCount': 'Échec de la suppression des sessions {count}',
  'settings.openchamber.desktopNetwork.title': 'Accès au réseau de bureau',
+  'settings.openchamber.desktopNetwork.field.windowControlsPosition': 'Position des contrôles de fenêtre',
+  'settings.openchamber.desktopNetwork.field.windowControlsPositionDescription': 'Choisissez où apparaissent les boutons Réduire, Agrandir et Fermer. Auto suit le système d’exploitation.',
+  'settings.openchamber.desktopNetwork.field.windowControlsPositionAria': 'Position des contrôles de fenêtre',
+  'settings.openchamber.desktopNetwork.option.windowControlsAuto': 'Auto',
+  'settings.openchamber.desktopNetwork.option.windowControlsLeft': 'Gauche',
+  'settings.openchamber.desktopNetwork.option.windowControlsRight': 'Droite',
  'settings.openchamber.desktopNetwork.field.launchAtLoginAria': 'Démarrez OpenChamber lors de la connexion',
  'settings.openchamber.desktopNetwork.field.launchAtLogin': 'Démarrez OpenChamber lorsque vous vous connectez',
  'settings.openchamber.desktopNetwork.field.launchAtLoginDescription': 'Démarre l\'application en arrière-plan sans ouvrir de fenêtre. Utilisez l\'icône d\'état du bureau pour l\'ouvrir.',
@@ -893,6 +893,12 @@ export const settingsDict = {
  'settings.openchamber.sessionRetention.toast.failedArchiveCount': '{count} 個の Session のアーカイブに失敗しました',
  'settings.openchamber.sessionRetention.toast.failedDeleteCount': '{count} 個の Session の削除に失敗しました',
  'settings.openchamber.desktopNetwork.title': 'Desktop ネットワークアクセス',
+  'settings.openchamber.desktopNetwork.field.windowControlsPosition': 'ウィンドウコントロールの位置',
+  'settings.openchamber.desktopNetwork.field.windowControlsPositionDescription': '最小化・最大化・閉じるボタンの表示位置を選びます。自動は OS に合わせます。',
+  'settings.openchamber.desktopNetwork.field.windowControlsPositionAria': 'ウィンドウコントロールの位置',
+  'settings.openchamber.desktopNetwork.option.windowControlsAuto': '自動',
+  'settings.openchamber.desktopNetwork.option.windowControlsLeft': '左',
+  'settings.openchamber.desktopNetwork.option.windowControlsRight': '右',
  'settings.openchamber.desktopNetwork.field.launchAtLoginAria': 'ログイン時に OpenChamber を起動',
  'settings.openchamber.desktopNetwork.field.launchAtLogin': 'ログイン時に OpenChamber を起動',
  'settings.openchamber.desktopNetwork.field.launchAtLoginDescription': 'ウィンドウを開かずにバックグラウンドでアプリを起動します。デスクトップのステータスアイコンから開けます。',
@@ -860,6 +860,12 @@ export const settingsDict = {
  'settings.openchamber.sessionRetention.toast.failedArchiveCount': '세션 {count}개를 보관하지 못했습니다',
  'settings.openchamber.sessionRetention.toast.failedDeleteCount': '세션 {count}개를 삭제하지 못했습니다',
  'settings.openchamber.desktopNetwork.title': 'Desktop 네트워크 접속',
+  'settings.openchamber.desktopNetwork.field.windowControlsPosition': '창 컨트롤 위치',
+  'settings.openchamber.desktopNetwork.field.windowControlsPositionDescription': '최소화, 최대화, 닫기 버튼이 표시될 위치를 선택합니다. 자동은 운영체제를 따릅니다.',
+  'settings.openchamber.desktopNetwork.field.windowControlsPositionAria': '창 컨트롤 위치',
+  'settings.openchamber.desktopNetwork.option.windowControlsAuto': '자동',
+  'settings.openchamber.desktopNetwork.option.windowControlsLeft': '왼쪽',
+  'settings.openchamber.desktopNetwork.option.windowControlsRight': '오른쪽',
  'settings.openchamber.desktopNetwork.field.launchAtLoginAria': '로그인 시 OpenChamber 시작',
  'settings.openchamber.desktopNetwork.field.launchAtLogin': '로그인 시 OpenChamber 시작',
  'settings.openchamber.desktopNetwork.field.launchAtLoginDescription': '창을 열지 않고 백그라운드에서 앱을 시작합니다. 데스크톱 상태 아이콘으로 열 수 있습니다.',
@@ -737,6 +737,12 @@ export const settingsDict = {
  'settings.openchamber.desktopNetwork.hint.openAfterRestart': 'Po restarcie otwórz z innego urządzenia: ',
  'settings.openchamber.desktopNetwork.hint.openNow': 'Otwórz z innego urządzenia: ',
  'settings.openchamber.desktopNetwork.title': 'Dostęp sieciowy pulpitu',
+  'settings.openchamber.desktopNetwork.field.windowControlsPosition': 'Pozycja elementów sterujących oknem',
+  'settings.openchamber.desktopNetwork.field.windowControlsPositionDescription': 'Wybierz, gdzie mają się pojawiać przyciski minimalizacji, maksymalizacji i zamykania. Automatycznie dopasowuje się do systemu operacyjnego.',
+  'settings.openchamber.desktopNetwork.field.windowControlsPositionAria': 'Pozycja elementów sterujących oknem',
+  'settings.openchamber.desktopNetwork.option.windowControlsAuto': 'Automatycznie',
+  'settings.openchamber.desktopNetwork.option.windowControlsLeft': 'Lewo',
+  'settings.openchamber.desktopNetwork.option.windowControlsRight': 'Prawo',
  'settings.openchamber.git.changesViewAria': 'Tryb widoku zmian Git',
  'settings.openchamber.git.changesViewTitle': 'Widok zmian',
  'settings.openchamber.git.enableGitmoji': 'Włącz wybieranie Gitmoji',
@@ -860,6 +860,12 @@ export const settingsDict = {
  "settings.openchamber.sessionRetention.toast.failedArchiveCount": "Não foi possível arquivar {count} sessão(es)",
  "settings.openchamber.sessionRetention.toast.failedDeleteCount": "Não foi possível excluir {count} sessão(es)",
  "settings.openchamber.desktopNetwork.title": "Acesso de rede do desktop",
+  "settings.openchamber.desktopNetwork.field.windowControlsPosition": "Posição dos controles da janela",
+  "settings.openchamber.desktopNetwork.field.windowControlsPositionDescription": "Escolha onde os botões de minimizar, maximizar e fechar aparecem. Automático segue o sistema operacional.",
+  "settings.openchamber.desktopNetwork.field.windowControlsPositionAria": "Posição dos controles da janela",
+  "settings.openchamber.desktopNetwork.option.windowControlsAuto": "Automático",
+  "settings.openchamber.desktopNetwork.option.windowControlsLeft": "Esquerda",
+  "settings.openchamber.desktopNetwork.option.windowControlsRight": "Direita",
  "settings.openchamber.desktopNetwork.field.launchAtLoginAria": "Iniciar o OpenChamber ao fazer login",
  "settings.openchamber.desktopNetwork.field.launchAtLogin": "Iniciar o OpenChamber ao fazer login",
  "settings.openchamber.desktopNetwork.field.launchAtLoginDescription": "Inicia o app em segundo plano sem abrir uma janela. Use o ícone de status da área de trabalho para abrir.",
@@ -860,6 +860,12 @@ export const settingsDict = {
  "settings.openchamber.sessionRetention.toast.failedArchiveCount": "Не вдалося заархівувати сесій: {count}",
  "settings.openchamber.sessionRetention.toast.failedDeleteCount": "Не вдалося видалити сесій: {count}",
  "settings.openchamber.desktopNetwork.title": "Мережевий доступ десктопного застосунку",
+  "settings.openchamber.desktopNetwork.field.windowControlsPosition": "Позиція елементів керування вікном",
+  "settings.openchamber.desktopNetwork.field.windowControlsPositionDescription": "Виберіть, де з’являються кнопки згортання, розгортання та закриття. Авто відповідає вашій операційній системі.",
+  "settings.openchamber.desktopNetwork.field.windowControlsPositionAria": "Позиція елементів керування вікном",
+  "settings.openchamber.desktopNetwork.option.windowControlsAuto": "Авто",
+  "settings.openchamber.desktopNetwork.option.windowControlsLeft": "Зліва",
+  "settings.openchamber.desktopNetwork.option.windowControlsRight": "Справа",
  "settings.openchamber.desktopNetwork.field.launchAtLoginAria": "Запускати OpenChamber під час входу в систему",
  "settings.openchamber.desktopNetwork.field.launchAtLogin": "Запускати OpenChamber під час входу в систему",
  "settings.openchamber.desktopNetwork.field.launchAtLoginDescription": "Запускає застосунок у фоні без відкриття вікна. Відкрийте його через піктограму стану на робочому столі.",
@@ -860,6 +860,12 @@ export const settingsDict = {
  'settings.openchamber.sessionRetention.toast.failedArchiveCount': '归档 {count} 个会话失败',
  'settings.openchamber.sessionRetention.toast.failedDeleteCount': '删除 {count} 个会话失败',
  'settings.openchamber.desktopNetwork.title': '桌面端网络访问',
+  'settings.openchamber.desktopNetwork.field.windowControlsPosition': '窗口控件位置',
+  'settings.openchamber.desktopNetwork.field.windowControlsPositionDescription': '选择最小化、最大化和关闭按钮的显示位置。自动会按操作系统决定。',
+  'settings.openchamber.desktopNetwork.field.windowControlsPositionAria': '窗口控件位置',
+  'settings.openchamber.desktopNetwork.option.windowControlsAuto': '自动',
+  'settings.openchamber.desktopNetwork.option.windowControlsLeft': '左侧',
+  'settings.openchamber.desktopNetwork.option.windowControlsRight': '右侧',
  'settings.openchamber.desktopNetwork.field.launchAtLoginAria': '登录时启动 OpenChamber',
  'settings.openchamber.desktopNetwork.field.launchAtLogin': '登录时启动 OpenChamber',
  'settings.openchamber.desktopNetwork.field.launchAtLoginDescription': '在后台启动应用且不打开窗口。可通过桌面状态图标打开。',
@@ -857,6 +857,12 @@
  'settings.openchamber.sessionRetention.toast.failedArchiveCount': '封存 {count} 個工作階段失敗',
  'settings.openchamber.sessionRetention.toast.failedDeleteCount': '刪除 {count} 個工作階段失敗',
  'settings.openchamber.desktopNetwork.title': '桌面端網路存取',
+  'settings.openchamber.desktopNetwork.field.windowControlsPosition': '視窗控制項位置',
+  'settings.openchamber.desktopNetwork.field.windowControlsPositionDescription': '選擇最小化、最大化和關閉按鈕的顯示位置。自動會依作業系統決定。',
+  'settings.openchamber.desktopNetwork.field.windowControlsPositionAria': '視窗控制項位置',
+  'settings.openchamber.desktopNetwork.option.windowControlsAuto': '自動',
+  'settings.openchamber.desktopNetwork.option.windowControlsLeft': '左側',
+  'settings.openchamber.desktopNetwork.option.windowControlsRight': '右側',
  'settings.openchamber.desktopNetwork.field.allowLanAccessAria': '允許桌面 sidecar 區域網路存取',
  'settings.openchamber.desktopNetwork.field.allowLanAccess': '允許你本機網路中的其他裝置開啟此應用程式',
  'settings.openchamber.desktopNetwork.field.allowLanAccessDescription': '會重新啟動應用程式，以便手機、平板和同一 Wi‑Fi 下的其他電腦存取。',
@@ -540,6 +540,12 @@ const applyDesktopUiPreferences = (settings: DesktopSettings) => {
      store.setWeekStartPreference(settings.weekStartPreference);
    }
  }
+  if (typeof settings.desktopWindowControlsPosition === 'string'
+    && (settings.desktopWindowControlsPosition === 'auto' || settings.desktopWindowControlsPosition === 'left' || settings.desktopWindowControlsPosition === 'right')) {
+    if (settings.desktopWindowControlsPosition !== store.desktopWindowControlsPosition) {
+      store.setDesktopWindowControlsPosition(settings.desktopWindowControlsPosition);
+    }
+  }
  if (typeof settings.chatRenderMode === 'string'
    && (settings.chatRenderMode === 'sorted' || settings.chatRenderMode === 'live')) {
    if (settings.chatRenderMode !== store.chatRenderMode) {
@@ -1114,6 +1120,10 @@ const sanitizeWebSettings = (payload: unknown): DesktopSettings | null => {
    && (candidate.weekStartPreference === 'auto' || candidate.weekStartPreference === 'sunday' || candidate.weekStartPreference === 'monday')) {
    result.weekStartPreference = candidate.weekStartPreference;
  }
+  if (typeof candidate.desktopWindowControlsPosition === 'string'
+    && (candidate.desktopWindowControlsPosition === 'auto' || candidate.desktopWindowControlsPosition === 'left' || candidate.desktopWindowControlsPosition === 'right')) {
+    result.desktopWindowControlsPosition = candidate.desktopWindowControlsPosition;
+  }
  if (typeof candidate.chatRenderMode === 'string'
    && (candidate.chatRenderMode === 'sorted' || candidate.chatRenderMode === 'live')) {
    result.chatRenderMode = candidate.chatRenderMode;
@@ -370,6 +370,14 @@ const SETTINGS_SEARCH_ITEMS: readonly SettingsSearchItem[] = [
    keywords: ['desktop', 'startup', 'login'],
    isAvailable: (ctx) => ctx.isDesktopLocalOrigin,
  },
+  {
+    id: 'sessions.desktop-window-controls-position',
+    page: 'sessions',
+    titleKey: 'settings.openchamber.desktopNetwork.field.windowControlsPosition',
+    descriptionKey: 'settings.openchamber.desktopNetwork.field.windowControlsPositionDescription',
+    keywords: ['desktop', 'window', 'controls', 'minimize', 'maximize', 'close', 'titlebar', 'linux', 'windows'],
+    isAvailable: (ctx) => ctx.isDesktop && (ctx.isWindows || !ctx.isMac),
+  },
  {
    id: 'sessions.desktop-minimize-to-tray',
    page: 'sessions',
@@ -20,6 +20,7 @@ export type ActivityRenderMode = 'collapsed' | 'summary';
 export type SessionRetentionAction = 'archive' | 'delete';
 export type TimeFormatPreference = 'auto' | '12h' | '24h';
 export type WeekStartPreference = 'auto' | 'sunday' | 'monday';
+export type DesktopWindowControlsPosition = 'auto' | 'left' | 'right';
 export type FileEditorKeymap = 'default' | 'vim';

 function normalizeFileEditorKeymap(value: unknown): FileEditorKeymap {
@@ -649,6 +650,7 @@ interface UIStore {
  showExpandedEditTools: boolean;
  timeFormatPreference: TimeFormatPreference;
  weekStartPreference: WeekStartPreference;
+  desktopWindowControlsPosition: DesktopWindowControlsPosition;
  mermaidRenderingMode: MermaidRenderingMode;
  userMessageRenderingMode: UserMessageRenderingMode;
  collapsibleUserMessages: boolean;
@@ -803,6 +805,7 @@ interface UIStore {
  setShowExpandedEditTools: (value: boolean) => void;
  setTimeFormatPreference: (value: TimeFormatPreference) => void;
  setWeekStartPreference: (value: WeekStartPreference) => void;
+  setDesktopWindowControlsPosition: (value: DesktopWindowControlsPosition) => void;
  setMermaidRenderingMode: (value: MermaidRenderingMode) => void;
  setUserMessageRenderingMode: (value: UserMessageRenderingMode) => void;
  setCollapsibleUserMessages: (value: boolean) => void;
@@ -950,6 +953,7 @@ export const useUIStore = create<UIStore>()(
        showExpandedEditTools: false,
        timeFormatPreference: 'auto',
        weekStartPreference: 'auto',
+        desktopWindowControlsPosition: 'auto',
        mermaidRenderingMode: 'svg',
        userMessageRenderingMode: 'markdown',
        collapsibleUserMessages: true,
@@ -2100,6 +2104,9 @@ export const useUIStore = create<UIStore>()(
        setWeekStartPreference: (value) => {
          set({ weekStartPreference: value });
        },
+        setDesktopWindowControlsPosition: (value) => {
+          set({ desktopWindowControlsPosition: value });
+        },
        setMermaidRenderingMode: (value) => {
          set({ mermaidRenderingMode: value });
        },
@@ -2357,6 +2364,7 @@ export const useUIStore = create<UIStore>()(
          showExpandedEditTools: state.showExpandedEditTools,
          timeFormatPreference: state.timeFormatPreference,
          weekStartPreference: state.weekStartPreference,
+          desktopWindowControlsPosition: state.desktopWindowControlsPosition,
          mermaidRenderingMode: state.mermaidRenderingMode,
          userMessageRenderingMode: state.userMessageRenderingMode,
          collapsibleUserMessages: state.collapsibleUserMessages,