feat(desktop): add optional macOS dock bounce on completion

apps/desktop/src/main.ts

@@ -49,6 +49,7 @@ syncShellEnvironment();
 
 const PICK_FOLDER_CHANNEL = "desktop:pick-folder";
 const CONFIRM_CHANNEL = "desktop:confirm";
+const REQUEST_USER_ATTENTION_CHANNEL = "desktop:request-user-attention";
 const SET_THEME_CHANNEL = "desktop:set-theme";
 const CONTEXT_MENU_CHANNEL = "desktop:context-menu";
 const OPEN_EXTERNAL_CHANNEL = "desktop:open-external";
@@ -1150,6 +1151,9 @@ function registerIpcHandlers(): void {
     return showDesktopConfirmDialog(message, owner);
   });
 
+  ipcMain.removeHandler(REQUEST_USER_ATTENTION_CHANNEL);
+  ipcMain.handle(REQUEST_USER_ATTENTION_CHANNEL, async () => requestUserAttention());
+
   ipcMain.removeHandler(SET_THEME_CHANNEL);
   ipcMain.handle(SET_THEME_CHANNEL, async (_event, rawTheme: unknown) => {
     const theme = getSafeTheme(rawTheme);
@@ -1291,6 +1295,20 @@ function getIconOption(): { icon: string } | Record<string, never> {
   return iconPath ? { icon: iconPath } : {};
 }
 
+function requestUserAttention(): boolean {
+  if (process.platform !== "darwin" || !app.dock) {
+    return false;
+  }
+
+  const anyFocusedWindow = BrowserWindow.getAllWindows().some((window) => window.isFocused());
+  if (anyFocusedWindow) {
+    return false;
+  }
+
+  app.dock.bounce("informational");
+  return true;
+}
+
 function createWindow(): BrowserWindow {
   const window = new BrowserWindow({
     width: 1100,

apps/desktop/src/preload.ts

@@ -3,6 +3,7 @@ import type { DesktopBridge } from "@t3tools/contracts";
 
 const PICK_FOLDER_CHANNEL = "desktop:pick-folder";
 const CONFIRM_CHANNEL = "desktop:confirm";
+const REQUEST_USER_ATTENTION_CHANNEL = "desktop:request-user-attention";
 const SET_THEME_CHANNEL = "desktop:set-theme";
 const CONTEXT_MENU_CHANNEL = "desktop:context-menu";
 const OPEN_EXTERNAL_CHANNEL = "desktop:open-external";
@@ -21,6 +22,7 @@ contextBridge.exposeInMainWorld("desktopBridge", {
   },
   pickFolder: () => ipcRenderer.invoke(PICK_FOLDER_CHANNEL),
   confirm: (message) => ipcRenderer.invoke(CONFIRM_CHANNEL, message),
+  requestUserAttention: () => ipcRenderer.invoke(REQUEST_USER_ATTENTION_CHANNEL),
   setTheme: (theme) => ipcRenderer.invoke(SET_THEME_CHANNEL, theme),
   showContextMenu: (items, position) => ipcRenderer.invoke(CONTEXT_MENU_CHANNEL, items, position),
   openExternal: (url: string) => ipcRenderer.invoke(OPEN_EXTERNAL_CHANNEL, url),

apps/web/src/components/settings/SettingsPanels.tsx

@@ -49,7 +49,7 @@ import {
 import { ensureNativeApi, readNativeApi } from "../../nativeApi";
 import { useStore } from "../../store";
 import { formatRelativeTime, formatRelativeTimeLabel } from "../../timestampFormat";
-import { cn } from "../../lib/utils";
+import { cn, isMacPlatform } from "../../lib/utils";
 import { Button } from "../ui/button";
 import { Collapsible, CollapsibleContent } from "../ui/collapsible";
 import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "../ui/empty";
@@ -475,6 +475,9 @@ export function useSettingsRestore(onRestored?: () => void) {
       ...(settings.confirmThreadDelete !== DEFAULT_UNIFIED_SETTINGS.confirmThreadDelete
         ? ["Delete confirmation"]
         : []),
+      ...(settings.dockBounceOnCompletion !== DEFAULT_UNIFIED_SETTINGS.dockBounceOnCompletion
+        ? ["Completion dock bounce"]
+        : []),
       ...(isGitWritingModelDirty ? ["Git writing model"] : []),
       ...(areProviderSettingsDirty ? ["Providers"] : []),
     ],
@@ -483,6 +486,7 @@ export function useSettingsRestore(onRestored?: () => void) {
       isGitWritingModelDirty,
       settings.confirmThreadArchive,
       settings.confirmThreadDelete,
+      settings.dockBounceOnCompletion,
       settings.defaultThreadEnvMode,
       settings.diffWordWrap,
       settings.enableAssistantStreaming,
@@ -516,6 +520,7 @@ export function GeneralSettingsPanel() {
   const { theme, setTheme } = useTheme();
   const settings = useSettings();
   const { updateSettings } = useUpdateSettings();
+  const isMacDesktop = isElectron && isMacPlatform(navigator.platform);
   const serverConfigQuery = useQuery(serverConfigQueryOptions());
   const [isOpeningKeybindings, setIsOpeningKeybindings] = useState(false);
   const [openKeybindingsError, setOpenKeybindingsError] = useState<string | null>(null);
@@ -958,6 +963,35 @@ export function GeneralSettingsPanel() {
           }
         />
 
+        {isMacDesktop ? (
+          <SettingsRow
+            title="Completion dock bounce"
+            description="Bounce the macOS Dock icon when a thread finishes while the app is in the background."
+            resetAction={
+              settings.dockBounceOnCompletion !==
+              DEFAULT_UNIFIED_SETTINGS.dockBounceOnCompletion ? (
+                <SettingResetButton
+                  label="completion dock bounce"
+                  onClick={() =>
+                    updateSettings({
+                      dockBounceOnCompletion: DEFAULT_UNIFIED_SETTINGS.dockBounceOnCompletion,
+                    })
+                  }
+                />
+              ) : null
+            }
+            control={
+              <Switch
+                checked={settings.dockBounceOnCompletion}
+                onCheckedChange={(checked) =>
+                  updateSettings({ dockBounceOnCompletion: Boolean(checked) })
+                }
+                aria-label="Bounce the macOS Dock icon when a thread completes"
+              />
+            }
+          />
+        ) : null}
+
         <SettingsRow
           title="Text generation model"
           description="Configure the model used for generated commit messages, PR titles, and similar Git text."

apps/web/src/hooks/useSettings.test.ts

@@ -7,10 +7,12 @@ describe("buildLegacyClientSettingsMigrationPatch", () => {
       buildLegacyClientSettingsMigrationPatch({
         confirmThreadArchive: true,
         confirmThreadDelete: false,
+        dockBounceOnCompletion: false,
       }),
     ).toEqual({
       confirmThreadArchive: true,
       confirmThreadDelete: false,
+      dockBounceOnCompletion: false,
     });
   });
 });

apps/web/src/hooks/useSettings.ts

@@ -70,9 +70,7 @@ function splitPatch(patch: Partial<UnifiedSettings>): {
  * only re-render when the slice they care about changes.
  */
 
-export function useSettings<T extends UnifiedSettings = UnifiedSettings>(
-  selector?: (s: UnifiedSettings) => T,
-): T {
+export function useSettings<T = UnifiedSettings>(selector?: (s: UnifiedSettings) => T): T {
   const { data: serverConfig } = useQuery(serverConfigQueryOptions());
   const [clientSettings] = useLocalStorage(
     CLIENT_SETTINGS_STORAGE_KEY,
@@ -210,6 +208,10 @@ export function buildLegacyClientSettingsMigrationPatch(
     patch.confirmThreadDelete = legacySettings.confirmThreadDelete;
   }
 
+  if (Predicate.isBoolean(legacySettings.dockBounceOnCompletion)) {
+    patch.dockBounceOnCompletion = legacySettings.dockBounceOnCompletion;
+  }
+
   if (Predicate.isBoolean(legacySettings.diffWordWrap)) {
     patch.diffWordWrap = legacySettings.diffWordWrap;
   }