Quick Look: native ⇧Space preview + Finder-convert hint

- ⇧Space opens `QLPreviewPanel` over Cmdr; cursor-follow keeps the preview tracking the focused pane's selection (100 ms trailing-edge debounce + generation counter, same pattern as type-to-jump)
- Backend `QuickLookController` is a `Mutex<...>` singleton driving the AppKit shared `QLPreviewPanel`. All AppKit calls hop to the main thread via `app.run_on_main_thread()` + `mpsc` channel, same pattern as `clipboard/pasteboard.rs`. First codebase use of `define_class!` (`MainThreadOnly` NSObject) — documented in the new `src-tauri/src/quick_look/CLAUDE.md`
- Panel becomes key (no supported `orderFront:` mode). Key forwarding: panel delegate's `previewPanel:handleEvent:` emits a `quick-look-key` Tauri event for arrows / typing / ⇧Space; the frontend listener calls `explorerRef.routePanelKey(payload)`, which fans out to the focused pane's existing nav primitives. Esc returns NO so AppKit's native close path handles it, surfacing via the `NSWindowWillCloseNotification` observer
- Volume gate via `Volume::supports_local_fs_access()` — MTP and virtual git portal entries silently no-op (debug log under `target: "quick_look"`); never `Path::exists()`-based, because MTP paths look real
- Three IPC commands replace the old fire-and-forget `quick_look`: `quick_look_open`, `quick_look_set_path`, `quick_look_close`. Bindings regenerated
- Menu accelerator updated `Some("Space")` → `Some("Shift+Space")`. FilePane Space handler guarded with `!e.shiftKey`. JS shortcut path also has `⇧Space` on `file.quickLook`. Empirically both fire per keystroke (AppKit menu + WKWebView keydown), so the dispatcher arms a 200 ms `quickLookDispatchGuard` on entry and swallows the second fire
- Focus-watchdog teaches itself about the panel: while `quickLookState.isOpen`, `shouldSuppress()` returns true (panel-is-key by design — the warning was a known not-a-bug)
- Educational toast for Finder converts: pressing plain Space in the file list pops a persistent info toast explaining Space-vs-⇧Space + a deep link to Settings > Keyboard shortcuts. The toast reappears on each Space press as a gentle reminder until the user clicks "Don't show again" (flips `fileExplorer.suppressQuickLookHint` in Settings > Advanced) or while the toast is already on screen. The X button just closes the instance, not the future ones — matching the user's intent
- Tests: 9 Rust controller state-machine tests, 20 Vitest tests (`quick-look-state`, `quick-look-hint`, `QuickLookHintToastContent.a11y`), 1 new `focus-watchdog` suppression case. Manual MCP smoke procedure at `apps/desktop/test/manual/quick-look-mcp.md` (native panel is outside Playwright's reach)
- Docs: new `apps/desktop/src-tauri/src/quick_look/CLAUDE.md`, new row in `docs/architecture.md`, Selection section in `apps/desktop/src/lib/file-explorer/CLAUDE.md` updated for both the ⇧Space shortcut and the hint behavior. Plan doc at `docs/specs/quick-look-plan.md` retained for reference

Author: vdavid

Cargo.lock

@@ -191,7 +191,11 @@ objc2-app-kit = { version = "0.3", features = [
     "NSDragging", "NSDraggingItem", "NSImage", "NSColor", "NSColorSpace",
     "NSApplication", "NSMenu", "NSMenuItem", "NSPasteboard", "NSRunningApplication",
     "NSWorkspace", "NSPanel", "NSOpenPanel", "NSSavePanel", "NSWindow", "NSResponder",
+    "NSEvent",
 ] }
+# Native macOS Quick Look panel (QLPreviewPanel + protocols). Published 2025-10-04, well
+# outside the 14-day cool-off; tracks the same objc2 0.6 family as the other bindings above.
+objc2-quick-look-ui = { version = "0.3.2", features = ["QLPreviewPanel", "QLPreviewItem", "objc2-app-kit"] }
 block2 = "0.6"
 security-framework = "3.2"
 # Drive indexing: macOS FSEvents watcher with event IDs and sinceWhen replay

apps/desktop/src-tauri/Cargo.toml

@@ -283,26 +283,160 @@ pub fn copy_to_clipboard<R: Runtime>(app: AppHandle<R>, text: String) -> Result<
     app.clipboard().write_text(text).map_err(|e| e.to_string())
 }
 
-/// Quick Look preview (macOS only)
+// ============================================================================
+// Quick Look (native QLPreviewPanel on macOS, stubs elsewhere)
+// ============================================================================
+//
+// Three commands rather than one because the panel is a process-wide singleton
+// owned by AppKit — we can `open` it, re-target it via `set_path`, or `close`
+// it, but we don't get to construct fresh instances. The frontend tracks
+// `isOpen` and picks the right call. See `crate::quick_look` for the full
+// design (and the why-singleton, why-main-thread, why-events arguments).
+//
+// All three commands wrap their main-thread hop in `blocking_with_timeout` (2 s)
+// so a wedged AppKit pump never freezes the IPC blocking pool.
+
+/// Open (or re-open) Quick Look on the given path.
 #[tauri::command]
 #[specta::specta]
 #[cfg(target_os = "macos")]
-pub fn quick_look(path: String) -> Result<(), String> {
-    Command::new("qlmanage")
-        .arg("-p")
-        .arg(&path)
-        .spawn()
-        .map_err(|e| e.to_string())?;
+pub async fn quick_look_open(app: AppHandle, path: String, volume_id: String) -> Result<(), String> {
+    use crate::commands::util::blocking_with_timeout;
+    use std::sync::mpsc::channel;
+    use tokio::time::Duration;
+
+    if !volume_supports_local_fs(&volume_id) {
+        log::debug!(
+            target: "quick_look",
+            "skipping open: volume {volume_id} doesn't support local fs access (path={path})"
+        );
+        return Ok(());
+    }
+
+    let app_inner = app.clone();
+    let path_inner = path;
+    blocking_with_timeout(Duration::from_secs(2), Err("timed out".to_string()), move || {
+        let (tx, rx) = channel();
+        let app_for_closure = app_inner.clone();
+        let path_main = std::path::PathBuf::from(path_inner);
+        app_inner
+            .run_on_main_thread(move || {
+                let state = app_for_closure.state::<crate::quick_look::QuickLookState>();
+                if let Ok(mut ctrl) = state.lock() {
+                    ctrl.open_on_main(&app_for_closure, path_main);
+                }
+                let _ = tx.send(());
+            })
+            .map_err(|e| format!("run_on_main_thread failed: {e}"))?;
+        rx.recv().map_err(|_| "main-thread reply lost".to_string())?;
+        Ok::<(), String>(())
+    })
+    .await
+}
+
+#[tauri::command]
+#[specta::specta]
+#[cfg(target_os = "macos")]
+pub async fn quick_look_set_path(app: AppHandle, path: String, volume_id: String) -> Result<(), String> {
+    use crate::commands::util::blocking_with_timeout;
+    use std::sync::mpsc::channel;
+    use tokio::time::Duration;
+
+    if !volume_supports_local_fs(&volume_id) {
+        log::debug!(
+            target: "quick_look",
+            "skipping set_path: volume {volume_id} doesn't support local fs access (path={path})"
+        );
+        return Ok(());
+    }
+
+    let app_inner = app.clone();
+    let path_inner = path;
+    blocking_with_timeout(Duration::from_secs(2), Err("timed out".to_string()), move || {
+        let (tx, rx) = channel();
+        let app_for_closure = app_inner.clone();
+        let path_main = std::path::PathBuf::from(path_inner);
+        app_inner
+            .run_on_main_thread(move || {
+                let state = app_for_closure.state::<crate::quick_look::QuickLookState>();
+                if let Ok(mut ctrl) = state.lock() {
+                    ctrl.set_path_on_main(path_main);
+                }
+                let _ = tx.send(());
+            })
+            .map_err(|e| format!("run_on_main_thread failed: {e}"))?;
+        rx.recv().map_err(|_| "main-thread reply lost".to_string())?;
+        Ok::<(), String>(())
+    })
+    .await
+}
+
+#[tauri::command]
+#[specta::specta]
+#[cfg(target_os = "macos")]
+pub async fn quick_look_close(app: AppHandle) -> Result<(), String> {
+    use crate::commands::util::blocking_with_timeout;
+    use std::sync::mpsc::channel;
+    use tokio::time::Duration;
+
+    let app_inner = app.clone();
+    blocking_with_timeout(Duration::from_secs(2), Err("timed out".to_string()), move || {
+        let (tx, rx) = channel();
+        let app_for_closure = app_inner.clone();
+        app_inner
+            .run_on_main_thread(move || {
+                let state = app_for_closure.state::<crate::quick_look::QuickLookState>();
+                if let Ok(mut ctrl) = state.lock() {
+                    ctrl.close_on_main();
+                }
+                let _ = tx.send(());
+            })
+            .map_err(|e| format!("run_on_main_thread failed: {e}"))?;
+        rx.recv().map_err(|_| "main-thread reply lost".to_string())?;
+        Ok::<(), String>(())
+    })
+    .await
+}
+
+#[tauri::command]
+#[specta::specta]
+#[cfg(not(target_os = "macos"))]
+pub async fn quick_look_open(_app: AppHandle, _path: String, _volume_id: String) -> Result<(), String> {
     Ok(())
 }
 
 #[tauri::command]
 #[specta::specta]
 #[cfg(not(target_os = "macos"))]
-pub fn quick_look(_path: String) -> Result<(), String> {
+pub async fn quick_look_set_path(_app: AppHandle, _path: String, _volume_id: String) -> Result<(), String> {
     Ok(())
 }
 
+#[tauri::command]
+#[specta::specta]
+#[cfg(not(target_os = "macos"))]
+pub async fn quick_look_close(_app: AppHandle) -> Result<(), String> {
+    Ok(())
+}
+
+/// Helper: returns true if the named volume supports `std::fs`-style access
+/// (local POSIX, OS-mounted SMB). False for MTP and other protocol-only
+/// volumes — those have no NSURL the Quick Look panel can preview.
+#[cfg(target_os = "macos")]
+fn volume_supports_local_fs(volume_id: &str) -> bool {
+    let manager = crate::file_system::get_volume_manager();
+    match manager.get(volume_id) {
+        Some(volume) => volume.supports_local_fs_access(),
+        None => {
+            // Unknown volume id — assume yes so we don't accidentally silence
+            // working previews. The frontend always sends a real id for entries
+            // it just listed.
+            log::debug!(target: "quick_look", "volume {volume_id} not found; assuming local fs access");
+            true
+        }
+    }
+}
+
 /// Open the Get Info window for a file (macOS only, no-op on other platforms)
 #[tauri::command]
 #[specta::specta]

apps/desktop/src-tauri/src/commands/ui.rs

@@ -148,7 +148,9 @@ pub fn builder() -> Builder<tauri::Wry> {
         crate::commands::ui::update_view_mode_menu,
         crate::commands::ui::show_in_finder,
         crate::commands::ui::copy_to_clipboard,
-        crate::commands::ui::quick_look,
+        crate::commands::ui::quick_look_open,
+        crate::commands::ui::quick_look_set_path,
+        crate::commands::ui::quick_look_close,
         crate::commands::ui::get_info,
         crate::commands::ui::open_in_editor,
         crate::commands::ui::cloud_make_available_offline,

apps/desktop/src-tauri/src/ipc.rs

@@ -89,7 +89,9 @@ pub(crate) fn collect_cross_platform_types(types: &mut Types) -> Vec<Function> {
         crate::commands::ui::show_tab_context_menu,
         crate::commands::ui::show_network_host_context_menu,
         crate::commands::ui::show_in_finder,
-        crate::commands::ui::quick_look,
+        crate::commands::ui::quick_look_open,
+        crate::commands::ui::quick_look_set_path,
+        crate::commands::ui::quick_look_close,
         crate::commands::ui::get_info,
         crate::commands::ui::open_in_editor,
         crate::commands::ui::cloud_make_available_offline,

apps/desktop/src-tauri/src/ipc_collectors.rs

@@ -115,6 +115,7 @@ mod permissions;
 #[cfg(target_os = "linux")]
 mod permissions_linux;
 mod pluralize;
+mod quick_look;
 mod redact;
 mod restricted_paths;
 pub mod search;
@@ -571,6 +572,12 @@ pub fn run() {
             #[cfg(target_os = "macos")]
             app.manage(updater::UpdateState::new());
 
+            // Native Quick Look controller. Empty on init; populated lazily
+            // when the user presses Shift+Space. macOS-only state machine;
+            // on other platforms the type is `Mutex<()>` so this compiles
+            // everywhere.
+            app.manage(quick_look::init_state());
+
             // Initialize pane state store for MCP context tools
             app.manage(mcp::PaneStateStore::new());
 

apps/desktop/src-tauri/src/lib.rs

@@ -97,7 +97,11 @@ pub(crate) fn build_menu_macos<R: Runtime>(
         Some(show_in_file_manager_accelerator()),
     )?;
     let get_info_item = MenuItem::with_id(app, GET_INFO_ID, "Get info", true, Some("Cmd+I"))?;
-    let quick_look_item = MenuItem::with_id(app, QUICK_LOOK_ID, "Quick look", true, Some("Space"))?;
+    // Shift+Space rather than plain Space: AppKit consumes modifier
+    // accelerators before the webview can capture them, so the menu actually
+    // fires. Plain Space was dead — the webview's Tier-2 selection-toggle
+    // handler ate the keydown before AppKit's menu dispatcher saw it.
+    let quick_look_item = MenuItem::with_id(app, QUICK_LOOK_ID, "Quick look", true, Some("Shift+Space"))?;
 
     let file_menu = Submenu::with_items(
         app,