Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix(desktop): restore the macOS title bar drag region (#17474)

Grzegorz Kielakbf92bcb6b337
diff --git a/__tests__/routes/root-layout.test.tsx b/__tests__/routes/root-layout.test.tsx
index 081c942a60..8a21933188 100644
--- a/__tests__/routes/root-layout.test.tsx
+++ b/__tests__/routes/root-layout.test.tsx
@@ -1,7 +1,7 @@
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { fireEvent, render, screen } from "@testing-library/react";
+import { act, fireEvent, render, screen } from "@testing-library/react";
import { type ReactNode } from "react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { createRoutesStub, data, Link } from "react-router";
import MainApp, { ErrorBoundary } from "#/routes/root-layout";
import { ActiveBackendProvider } from "#/contexts/active-backend-context";
@@ -396,6 +396,113 @@ describe("root layout", () => {
expect(await screen.findByTestId("command-menu")).toBeInTheDocument();
expect(screen.queryByTestId("alert-banner")).not.toBeInTheDocument();
});
+
+ describe("macOS desktop title bar", () => {
+ afterEach(() => {
+ delete window.desktopShell;
+ });
+
+ it("reserves a draggable band for the traffic lights on the macOS desktop app", () => {
+ window.desktopShell = { platform: "darwin" };
+
+ renderMainApp();
+
+ expect(screen.getByTestId("titlebar-drag-region")).toHaveAttribute(
+ "aria-hidden",
+ "true",
+ );
+ expect(screen.getByTestId("root-layout")).toHaveClass("pt-7");
+ });
+
+ it("adds no band in a browser tab, where the shell owns no window chrome", () => {
+ renderMainApp();
+
+ expect(
+ screen.queryByTestId("titlebar-drag-region"),
+ ).not.toBeInTheDocument();
+ expect(screen.getByTestId("root-layout")).not.toHaveClass("pt-7");
+ });
+
+ it.each(["win32", "linux"])(
+ "adds no band on %s, which keeps the native title bar",
+ (platform) => {
+ window.desktopShell = { platform };
+
+ renderMainApp();
+
+ expect(
+ screen.queryByTestId("titlebar-drag-region"),
+ ).not.toBeInTheDocument();
+ expect(screen.getByTestId("root-layout")).not.toHaveClass("pt-7");
+ },
+ );
+
+ it("keeps a drag band on the loading screen, before config resolves", () => {
+ window.desktopShell = { platform: "darwin" };
+ useConfigMock.mockReturnValue({ isLoading: true, data: null });
+
+ renderMainApp();
+
+ expect(screen.getByTestId("titlebar-drag-region")).toBeInTheDocument();
+ });
+
+ it("keeps the band and the inset on the route error screen", async () => {
+ window.desktopShell = { platform: "darwin" };
+
+ renderRouteError(new Error("Kaboom"));
+
+ expect(await screen.findByText("Kaboom")).toBeInTheDocument();
+ expect(
+ screen.getByTestId("titlebar-drag-region").parentElement,
+ ).toHaveClass("pt-7");
+ });
+
+ it("drops the band once the window goes fullscreen, where macOS hides the traffic lights", async () => {
+ let isFullScreen = false;
+ let emit: ((value: boolean) => void) | undefined;
+ window.desktopShell = {
+ platform: "darwin",
+ isFullScreen: () => isFullScreen,
+ onFullScreenChange: (cb) => {
+ emit = (value) => {
+ isFullScreen = value;
+ cb(value);
+ };
+ return () => {};
+ },
+ };
+
+ renderMainApp();
+ expect(screen.getByTestId("titlebar-drag-region")).toBeInTheDocument();
+
+ await act(async () => emit?.(true));
+
+ expect(
+ screen.queryByTestId("titlebar-drag-region"),
+ ).not.toBeInTheDocument();
+ expect(screen.getByTestId("root-layout")).not.toHaveClass("pt-7");
+
+ await act(async () => emit?.(false));
+
+ expect(screen.getByTestId("titlebar-drag-region")).toBeInTheDocument();
+ });
+
+ it("never renders the band when the window is already fullscreen on load, as after a reload", () => {
+ window.desktopShell = {
+ platform: "darwin",
+ isFullScreen: () => true,
+ onFullScreenChange: () => () => {},
+ };
+
+ renderMainApp();
+
+ // Checked on the first commit: a band that is dropped later still flashes.
+ expect(
+ screen.queryByTestId("titlebar-drag-region"),
+ ).not.toBeInTheDocument();
+ expect(screen.getByTestId("root-layout")).not.toHaveClass("pt-7");
+ });
+ });
});
describe("root layout error boundary", () => {
diff --git a/__tests__/utils/desktop-shell.test.ts b/__tests__/utils/desktop-shell.test.ts
new file mode 100644
index 0000000000..7c2654b02b
--- /dev/null
+++ b/__tests__/utils/desktop-shell.test.ts
@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+ isDesktopFullScreen,
+ isMacDesktopShell,
+ subscribeDesktopFullScreen,
+} from "#/utils/desktop-shell";
+
+function setShell(platform: string | undefined) {
+ if (platform === undefined) {
+ delete window.desktopShell;
+ return;
+ }
+ window.desktopShell = { platform };
+}
+
+afterEach(() => {
+ setShell(undefined);
+});
+
+describe("isMacDesktopShell", () => {
+ it("is false in a plain browser tab (no preload bridge)", () => {
+ expect(isMacDesktopShell()).toBe(false);
+ });
+
+ it("is true when the Electron preload reports darwin", () => {
+ setShell("darwin");
+ expect(isMacDesktopShell()).toBe(true);
+ });
+
+ it.each(["win32", "linux"])(
+ "is false on the %s desktop build, which keeps the native title bar",
+ (platform) => {
+ setShell(platform);
+ expect(isMacDesktopShell()).toBe(false);
+ },
+ );
+
+ it("is false when the bridge exposes no platform", () => {
+ window.desktopShell = {};
+ expect(isMacDesktopShell()).toBe(false);
+ });
+});
+
+describe("subscribeDesktopFullScreen", () => {
+ it("is a no-op unsubscribe in a browser tab, where there is no window to watch", () => {
+ const cb = vi.fn();
+
+ expect(() => subscribeDesktopFullScreen(cb)()).not.toThrow();
+ expect(cb).not.toHaveBeenCalled();
+ });
+
+ it("forwards fullscreen transitions from the bridge", () => {
+ const unsubscribe = vi.fn();
+ let emit: ((value: boolean) => void) | undefined;
+ window.desktopShell = {
+ platform: "darwin",
+ onFullScreenChange: (cb) => {
+ emit = cb;
+ return unsubscribe;
+ },
+ };
+ const cb = vi.fn();
+
+ const stop = subscribeDesktopFullScreen(cb);
+ emit?.(true);
+
+ expect(cb).toHaveBeenCalledWith(true);
+ stop();
+ expect(unsubscribe).toHaveBeenCalled();
+ });
+});
+
+describe("isDesktopFullScreen", () => {
+ it("is false in a browser tab", () => {
+ expect(isDesktopFullScreen()).toBe(false);
+ });
+
+ it("is false when the bridge exposes no fullscreen state", () => {
+ setShell("darwin");
+ expect(isDesktopFullScreen()).toBe(false);
+ });
+
+ it("reads the state the preload holds, which no transition announces after a reload", () => {
+ window.desktopShell = {
+ platform: "darwin",
+ isFullScreen: () => true,
+ };
+ expect(isDesktopFullScreen()).toBe(true);
+ });
+});
diff --git a/electron/main.mjs b/electron/main.mjs
index 277f7f1898..ab7f1f6a01 100644
--- a/electron/main.mjs
+++ b/electron/main.mjs
@@ -388,14 +388,27 @@ function createMainWindow() {
// App-shell background (--oh-background in src/index.css) β€” avoids white
// flashes during the show β†’ maximize repaint after the splash closes.
backgroundColor: "#0b0e14",
+ // hiddenInset hides the native title bar but keeps the traffic lights
+ // floating over the app shell; the renderer reserves a drag band for them.
titleBarStyle: process.platform === "darwin" ? "hiddenInset" : "default",
icon: appIconPath,
webPreferences: {
nodeIntegration: false,
contextIsolation: true,
+ preload: join(__dirname, "preload-main.cjs"),
},
});
+ // The renderer drops its reserved traffic-light band in fullscreen, where
+ // macOS hides the buttons. Only transitions are pushed; the preload reads the
+ // current state over "window:full-screen:get" on every page load.
+ const sendFullScreenState = () => {
+ if (!mainWin || mainWin.isDestroyed()) return;
+ mainWin.webContents.send("window:full-screen", mainWin.isFullScreen());
+ };
+ mainWin.on("enter-full-screen", sendFullScreenState);
+ mainWin.on("leave-full-screen", sendFullScreenState);
+
mainWin.loadURL("http://localhost:8000");
mainWin.once("ready-to-show", () => {
@@ -565,6 +578,13 @@ ipcMain.handle("boot-log:quit", (event) => {
app.quit();
});
+// Synchronous so the preload has the state before the first render; a
+// renderer that starts with "not fullscreen" paints the band and then drops it.
+ipcMain.on("window:full-screen:get", (event) => {
+ const win = BrowserWindow.fromWebContents(event.sender);
+ event.returnValue = win !== null && !win.isDestroyed() && win.isFullScreen();
+});
+
// ── Backend stack ─────────────────────────────────────────────────────────────
/**
diff --git a/electron/preload-main.cjs b/electron/preload-main.cjs
new file mode 100644
index 0000000000..16dab85c19
--- /dev/null
+++ b/electron/preload-main.cjs
@@ -0,0 +1,38 @@
+/**
+ * Preload for the main app window.
+ *
+ * The renderer is the ordinary web app served over loopback, so it cannot tell
+ * a desktop launch from a browser tab. This exposes just enough for the shell
+ * to reserve room for the macOS traffic lights and mark a drag region β€” see
+ * src/utils/desktop-shell.ts.
+ *
+ * CommonJS on purpose: sandboxed preload scripts cannot use ESM.
+ */
+const { contextBridge, ipcRenderer } = require("electron");
+
+// Read once here, before any page script runs, and kept current from the
+// pushed transitions: the renderer subscribes long after load, and a reload of
+// a fullscreen window reports no transition at all.
+let isFullScreen = Boolean(ipcRenderer.sendSync("window:full-screen:get"));
+const listeners = new Set();
+ipcRenderer.on("window:full-screen", (_event, value) => {
+ isFullScreen = Boolean(value);
+ for (const cb of listeners) cb(isFullScreen);
+});
+
+contextBridge.exposeInMainWorld("desktopShell", {
+ platform: process.platform,
+ /** The window's current fullscreen state. */
+ isFullScreen: () => isFullScreen,
+ /**
+ * Subscribe to native fullscreen transitions: cb(isFullScreen). Returns an
+ * unsubscribe fn.
+ *
+ * Chromium does not report `display-mode: fullscreen` for a natively
+ * fullscreened BrowserWindow, so a CSS media query cannot see this.
+ */
+ onFullScreenChange(cb) {
+ listeners.add(cb);
+ return () => listeners.delete(cb);
+ },
+});
diff --git a/src/hooks/use-desktop-full-screen.ts b/src/hooks/use-desktop-full-screen.ts
new file mode 100644
index 0000000000..e98b3ed709
--- /dev/null
+++ b/src/hooks/use-desktop-full-screen.ts
@@ -0,0 +1,17 @@
+import React from "react";
+import {
+ isDesktopFullScreen,
+ subscribeDesktopFullScreen,
+} from "#/utils/desktop-shell";
+
+/**
+ * Whether the desktop window is in native fullscreen. Always false in a
+ * browser tab.
+ */
+export function useDesktopFullScreen(): boolean {
+ return React.useSyncExternalStore(
+ subscribeDesktopFullScreen,
+ isDesktopFullScreen,
+ () => false,
+ );
+}
diff --git a/src/routes/root-layout.tsx b/src/routes/root-layout.tsx
index ed78969e8d..236c352b34 100644
--- a/src/routes/root-layout.tsx
+++ b/src/routes/root-layout.tsx
@@ -27,6 +27,9 @@ import { ReactRouterNavigationProvider } from "./react-router-navigation-provide
import { OnboardingHost } from "#/components/features/onboarding";
import { isOnboardingPreviewActive } from "#/components/features/onboarding/onboarding-preview";
import { CanvasExtensionsRuntimeProvider } from "#/components/features/canvas-extensions/canvas-extensions-runtime";
+import { isMacDesktopShell } from "#/utils/desktop-shell";
+import { useDesktopFullScreen } from "#/hooks/use-desktop-full-screen";
+import { cn } from "#/utils/utils";
const EnvironmentSwitchOverlay = React.lazy(
() => import("#/components/features/backends/environment-switch-overlay"),
@@ -45,13 +48,45 @@ const SuperAdminSetupGuide = React.lazy(
() => import("#/components/features/setup-guide/super-admin-setup-guide"),
);
+/**
+ * The macOS desktop app hides its title bar ("hiddenInset"), leaving the
+ * traffic lights over the shell. Screens reserve a 28px band for them (pt-7)
+ * and make it the window's drag handle; the padding keeps it free of controls.
+ */
+function useShowTitleBarBand(): boolean {
+ const isFullScreen = useDesktopFullScreen();
+ // Fullscreen hides the traffic lights, so the band has nothing to clear.
+ return isMacDesktopShell() && !isFullScreen;
+}
+
+function TitleBarDragRegion() {
+ if (!useShowTitleBarBand()) return null;
+ return (
+ <div
+ data-testid="titlebar-drag-region"
+ aria-hidden="true"
+ className="app-region-drag fixed inset-x-0 top-0 z-50 h-7"
+ />
+ );
+}
+
+function ErrorShell({ children }: { children: React.ReactNode }) {
+ const showTitleBarBand = useShowTitleBarBand();
+ return (
+ <div className={cn(showTitleBarBand && "pt-7")}>
+ <TitleBarDragRegion />
+ {children}
+ </div>
+ );
+}
+
export function ErrorBoundary() {
const error = useRouteError();
const { t } = useTranslation("openhands");
if (isRouteErrorResponse(error)) {
return (
- <div>
+ <ErrorShell>
<h1>{error.status}</h1>
<p>{error.statusText}</p>
<pre>
@@ -59,22 +94,22 @@ export function ErrorBoundary() {
? JSON.stringify(error.data)
: error.data}
</pre>
- </div>
+ </ErrorShell>
);
}
if (error instanceof Error) {
return (
- <div>
+ <ErrorShell>
<h1>{t(I18nKey.ERROR$GENERIC)}</h1>
<pre>{error.message}</pre>
- </div>
+ </ErrorShell>
);
}
return (
- <div>
+ <ErrorShell>
<h1>{t(I18nKey.ERROR$UNKNOWN)}</h1>
- </div>
+ </ErrorShell>
);
}
@@ -91,6 +126,7 @@ function MainAppContent() {
const appTitle = useAppTitle();
const { data: settings } = useSettings();
const config = useConfig();
+ const showTitleBarBand = useShowTitleBarBand();
useSyncAutomationTelemetryConsent();
@@ -111,6 +147,7 @@ function MainAppContent() {
if (config.isLoading) {
return (
<div className="min-h-screen flex items-center justify-center bg-base">
+ <TitleBarDragRegion />
<LoadingSpinner size="large" />
</div>
);
@@ -129,9 +166,13 @@ function MainAppContent() {
<SidebarMobileNavProvider>
<div
data-testid="root-layout"
- className="h-screen lg:min-w-5xl flex flex-col md:flex-row bg-base overflow-hidden p-0"
+ className={cn(
+ "h-screen lg:min-w-5xl flex flex-col md:flex-row bg-base overflow-hidden p-0",
+ showTitleBarBand && "pt-7",
+ )}
>
<title>{appTitle}</title>
+ <TitleBarDragRegion />
<Sidebar />
<div className="flex min-h-0 flex-col w-full min-w-0 h-full gap-3">
diff --git a/src/tailwind.css b/src/tailwind.css
index ce6c9a6040..361a72da03 100644
--- a/src/tailwind.css
+++ b/src/tailwind.css
@@ -664,3 +664,8 @@ button.extension-module-card-interactive {
0px 4px 6px -4px rgba(0, 0, 0, 0.1),
0px 10px 15px -3px rgba(0, 0, 0, 0.1);
}
+
+/* Window drag handle for the macOS desktop app's hidden title bar. */
+@utility app-region-drag {
+ -webkit-app-region: drag;
+}
diff --git a/src/utils/desktop-shell.ts b/src/utils/desktop-shell.ts
new file mode 100644
index 0000000000..67577053fb
--- /dev/null
+++ b/src/utils/desktop-shell.ts
@@ -0,0 +1,46 @@
+/**
+ * Desktop-shell detection for the renderer.
+ *
+ * The app is served over loopback, so a desktop launch is indistinguishable
+ * from a browser tab unless the Electron preload says so β€” see
+ * electron/preload-main.cjs.
+ */
+
+interface DesktopShellBridge {
+ platform?: string;
+ isFullScreen?: () => boolean;
+ onFullScreenChange?: (cb: (isFullScreen: boolean) => void) => () => void;
+}
+
+declare global {
+ interface Window {
+ desktopShell?: DesktopShellBridge;
+ }
+}
+
+function getDesktopShell(): DesktopShellBridge | undefined {
+ return typeof window === "undefined" ? undefined : window.desktopShell;
+}
+
+/**
+ * True inside the macOS desktop app, where `titleBarStyle: "hiddenInset"`
+ * leaves the traffic lights floating over the top-left of the app shell.
+ */
+export function isMacDesktopShell(): boolean {
+ return getDesktopShell()?.platform === "darwin";
+}
+
+/** Whether the desktop window is in native fullscreen; false in a browser tab. */
+export function isDesktopFullScreen(): boolean {
+ return getDesktopShell()?.isFullScreen?.() ?? false;
+}
+
+/**
+ * Subscribe to native fullscreen transitions. Returns an unsubscribe function;
+ * outside the desktop app it is a no-op, since a browser tab owns no window.
+ */
+export function subscribeDesktopFullScreen(
+ cb: (isFullScreen: boolean) => void,
+): () => void {
+ return getDesktopShell()?.onFullScreenChange?.(cb) ?? (() => {});
+}