Bugfix: Fix ⌘, to refocus Settings window if open

- Add missing allow-set-focus capability for the settings window
- Settings window self-focuses via focus-self event (cross-window setFocus doesn't reliably bring windows to front on macOS)
- Use getByLabel() instead of stale module-level JS window ref
- Add capabilities/CLAUDE.md to prevent similar permission gaps

Author: vdavid

apps/desktop/src-tauri/capabilities/CLAUDE.md

@@ -0,0 +1,14 @@
+# Tauri capabilities
+
+Each window has its own capability file controlling which Tauri APIs it can call.
+When adding a Tauri API call to a window (setFocus, setTitle, show, etc.),
+you must add the corresponding permission here or the call will be silently
+rejected at runtime with a "not allowed" error.
+
+- `default.json` — main window
+- `desktop.json` — desktop-wide permissions
+- `settings.json` — settings window
+- `viewer.json` — file viewer windows
+
+Check the [Tauri permissions reference](https://tauri.app/security/permissions/)
+for available permission identifiers.

apps/desktop/src-tauri/capabilities/settings.json

@@ -7,6 +7,7 @@
     ],
     "permissions": [
         "core:window:allow-close",
+        "core:window:allow-set-focus",
         "core:event:default",
         "core:app:allow-set-app-theme",
         "core:webview:allow-internal-toggle-devtools",

apps/desktop/src/lib/settings/settings-window.ts

@@ -4,12 +4,11 @@
  */
 
 import { WebviewWindow } from '@tauri-apps/api/webviewWindow'
+import { emitTo } from '@tauri-apps/api/event'
 import { getAppLogger } from '$lib/logging/logger'
 
 const log = getAppLogger('settings')
 
-let settingsWindow: WebviewWindow | null = null
-
 const SETTINGS_WIDTH = 800
 const SETTINGS_HEIGHT = 600
 const SETTINGS_MAX_WIDTH = 852
@@ -18,29 +17,21 @@ const SETTINGS_MIN_HEIGHT = 400
 
 /**
  * Opens the settings window, or focuses it if already open.
- * Window always opens centered on screen.
+ * Uses `WebviewWindow.getByLabel` to reliably detect an existing window
+ * instead of a module-level JS reference that can go stale.
  */
 export async function openSettingsWindow(): Promise<void> {
-    log.debug('openSettingsWindow called')
-
-    // Check if window already exists
-    if (settingsWindow) {
-        log.debug('Settings window already exists, attempting to focus')
-        try {
-            await settingsWindow.setFocus()
-            log.debug('Focused existing settings window')
-            return
-        } catch (error) {
-            // Window was closed, create a new one
-            log.debug('Failed to focus existing window (likely closed), creating new: {error}', { error })
-            settingsWindow = null
-        }
+    const existing = await WebviewWindow.getByLabel('settings')
+    if (existing) {
+        // Emit to the settings window so it can self-focus. Cross-window setFocus()
+        // doesn't reliably bring a window to front on macOS.
+        await emitTo('settings', 'focus-self')
+        return
     }
 
-    log.info('Creating new settings window with url=/settings')
+    log.info('Creating new settings window')
 
-    // Create new settings window, centered on screen
-    settingsWindow = new WebviewWindow('settings', {
+    new WebviewWindow('settings', {
         url: '/settings',
         title: 'Settings',
         width: SETTINGS_WIDTH,
@@ -51,22 +42,6 @@ export async function openSettingsWindow(): Promise<void> {
         center: true,
         resizable: true,
         decorations: true,
-    })
-
-    // Listen for window creation success
-    void settingsWindow.once('tauri://created', () => {
-        log.info('Settings window created successfully')
-    })
-
-    // Listen for window close to clean up reference
-    void settingsWindow.once('tauri://destroyed', () => {
-        log.debug('Settings window destroyed, cleaning up reference')
-        settingsWindow = null
-    })
-
-    // Handle any creation errors
-    void settingsWindow.once('tauri://error', (e) => {
-        log.error('Failed to create settings window: {error}', { error: e })
-        settingsWindow = null
+        focus: true,
     })
 }

apps/desktop/src/routes/settings/+page.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
     import { onMount, onDestroy, tick } from 'svelte'
     import { getCurrentWindow } from '@tauri-apps/api/window'
+    import { listen, type UnlistenFn } from '@tauri-apps/api/event'
     import SettingsSidebar from '$lib/settings/components/SettingsSidebar.svelte'
     import SettingsContent from '$lib/settings/components/SettingsContent.svelte'
     import { initializeSettings, forceSave as forceSettingsSave } from '$lib/settings'
@@ -23,6 +24,7 @@
     let selectedSection = $state<string[]>(['General', 'Appearance'])
     let initialized = $state(false)
     let contentElement: HTMLElement | null = $state(null)
+    let unlistenFocusSelf: UnlistenFn | undefined
 
     // Log page script initialization
     log.debug('Settings page script loaded')
@@ -127,6 +129,15 @@
             // Focus will be handled naturally by the browser's tab order
             await tick()
 
+            // Listen for focus-self events (from ⌘, when window is already open).
+            // Self-focusing is needed because cross-window setFocus() doesn't reliably
+            // bring a window to front on macOS.
+            unlistenFocusSelf = await listen('focus-self', () => {
+                // setTimeout(0) defers past the originating keydown handler —
+                // without it, macOS restores focus to the main window.
+                setTimeout(() => void getCurrentWindow().setFocus(), 0)
+            })
+
             // Set up MCP event listeners and sync initial state
             await setupMcpEventListeners(handleSectionSelect, handleSettingChanged)
             await notifySettingsWindowOpen(true)
@@ -143,7 +154,8 @@
         log.debug('Settings page destroying, flushing pending saves')
         // Fire and forget - we can't await in onDestroy
         void Promise.all([forceSettingsSave(), flushShortcutsSave()])
-        // Clean up MCP event listeners and notify backend
+        // Clean up event listeners and notify backend
+        unlistenFocusSelf?.()
         cleanupMcpEventListeners()
         cleanupAccentColor()
         void notifySettingsWindowOpen(false)

docs/architecture.md

@@ -56,6 +56,7 @@ All under `apps/desktop/src-tauri/src/`.
 | `drag_image_detection.rs` | macOS method swizzle for drag image size detection |
 | `drag_image_swap.rs` | Rich/transparent drag image swap for self-drags |
 | `commands/` | Tauri command definitions (IPC entry points) |
+| `capabilities/` | Per-window Tauri API permissions — must be updated when using new Tauri APIs from a window |
 
 ## Other apps