fix(preview): isolate keyboard focus during automation and indicate active focus (#647) (#710)

Author: rynfar

apps/desktop/src/preview/Manager.ts

@@ -1578,6 +1578,11 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
       }
       const tabs = yield* SynchronizedRef.get(tabsRef);
       if (tabs.has(tabId)) yield* update(tabId, { controller: "none" });
+      if (currentMainWindow && !currentMainWindow.isDestroyed()) {
+        yield* attempt({ operation: "focusMainWindow", tabId }, () => {
+          currentMainWindow?.webContents.focus();
+        }).pipe(Effect.ignore);
+      }
     });
     return yield* control.semaphore.withPermit(execute().pipe(Effect.onExit(finalize)));
   });

apps/web/src/browser/HostedBrowserWebview.tsx

@@ -1,13 +1,17 @@
 "use client";
 
+import { useAtomValue } from "@effect/atom-react";
+import { scopedThreadKey } from "@t3tools/client-runtime/environment";
 import type { PreviewViewportSetting, ScopedThreadRef } from "@t3tools/contracts";
 import { useShallow } from "zustand/react/shallow";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 import { previewBridge } from "~/components/preview/previewBridge";
 import { usePreviewBridge } from "~/components/preview/usePreviewBridge";
 import { useClientSettingsHydrated } from "~/hooks/useSettings";
+import { dispatchSnapShotComposerFocus } from "~/lib/desktopSnapShot";
 import { cn, isMacPlatform } from "~/lib/utils";
+import { previewStateAtom } from "~/previewStateStore";
 
 import { resolveBrowserSurfacePanelRect, useBrowserSurfaceStore } from "./browserSurfaceStore";
 import { useActiveBrowserRecordingTabIds } from "./browserRecording";
@@ -93,8 +97,22 @@ export function HostedBrowserWebview(props: {
     (state) => (state.activityByTabId[runtimeTabId] ?? 0) > 0,
   );
   const recordingActive = useActiveBrowserRecordingTabIds().has(runtimeTabId);
+  const threadKey = scopedThreadKey(threadRef);
+  const previewState = useAtomValue(previewStateAtom(threadKey));
+  const controller = previewState.desktopByTabId[tabId]?.controller ?? "none";
+  const controllerRef = useRef(controller);
+  controllerRef.current = controller;
   usePreviewBridge({ threadRef, tabId, runtimeTabId });
 
+  useEffect(() => {
+    if (controller === "agent" && typeof document !== "undefined") {
+      if (document.activeElement === webviewRef.current) {
+        webviewRef.current?.blur();
+        dispatchSnapShotComposerFocus();
+      }
+    }
+  }, [controller]);
+
   useEffect(() => {
     if (!clientSettingsHydrated) return;
     crashRecoveryRef.current = INITIAL_WEBVIEW_CRASH_RECOVERY_STATE;
@@ -156,13 +174,21 @@ export function HostedBrowserWebview(props: {
         }
       }, recovery.delayMs);
     };
+    const handleFocus = () => {
+      if (controllerRef.current === "agent") {
+        webview.blur();
+        dispatchSnapShotComposerFocus();
+      }
+    };
+    webview.addEventListener("focus", handleFocus);
     webview.addEventListener("did-attach", register);
     webview.addEventListener("dom-ready", register);
     webview.addEventListener("render-process-gone", recoverGuest);
     register();
     return () => {
       disposed = true;
       if (recoveryTimeout !== null) clearTimeout(recoveryTimeout);
+      webview.removeEventListener("focus", handleFocus);
       webview.removeEventListener("did-attach", register);
       webview.removeEventListener("dom-ready", register);
       webview.removeEventListener("render-process-gone", recoverGuest);

apps/web/src/components/preview/PreviewPanelShell.tsx

@@ -8,6 +8,7 @@ import {
 } from "react";
 
 import { isElectron } from "~/env";
+import { usePreviewFocus } from "~/hooks/usePreviewFocus";
 import { useResizableWidth } from "~/hooks/useResizableWidth";
 import { cn } from "~/lib/utils";
 
@@ -65,6 +66,7 @@ export function PreviewPanelShell(props: {
   children: ReactNode;
 }) {
   const useDragRegion = isElectron && props.mode !== "sheet" && props.mode !== "embedded";
+  const previewFocused = usePreviewFocus();
   const isInline = props.mode === "inline";
   const collapsible = isInline && props.open !== undefined;
   const open = props.open ?? true;
@@ -142,6 +144,7 @@ export function PreviewPanelShell(props: {
       }
       data-preview-panel-mode={props.mode}
       data-preview-panel-maximized={maximized ? "true" : "false"}
+      data-preview-focused={previewFocused ? "true" : undefined}
     >
       {isInline && !maximized ? <RightPanelResizeHandle handlers={handlers} /> : null}
       <div className={cn("h-full min-h-0 w-full", collapsible && "overflow-clip")}>

apps/web/src/components/preview/PreviewView.tsx

@@ -41,6 +41,8 @@ import {
 } from "~/previewMiniPlayerStore";
 import { useRightPanelStore } from "~/rightPanelStore";
 
+import { usePreviewFocus } from "~/hooks/usePreviewFocus";
+import { cn } from "~/lib/utils";
 import { previewBridge } from "./previewBridge";
 import { subscribePreviewAction } from "./previewActionBus";
 import { openPreviewSession } from "./openPreviewSession";
@@ -705,10 +707,16 @@ export function PreviewView({
     });
   }, [handleRefresh, handleResetZoom, handleZoomIn, handleZoomOut, visible]);
 
+  const previewFocused = usePreviewFocus();
+
   return (
     <div
-      className="flex min-h-0 flex-1 flex-col bg-background"
+      className={cn(
+        "flex min-h-0 flex-1 flex-col bg-background transition-shadow duration-150",
+        previewFocused && "ring-1 ring-inset ring-ring/60",
+      )}
       data-thread-key={scopedThreadKey(threadRef)}
+      data-preview-focused={previewFocused ? "true" : undefined}
     >
       <PreviewChromeRow
         url={url}

apps/web/src/components/preview/usePreviewBridge.ts

@@ -16,6 +16,7 @@ import {
   useFaviconProjectRefForThread,
 } from "~/browserFaviconStore";
 import { useBrowserPointerStore } from "~/browser/browserPointerStore";
+import { dispatchSnapShotComposerFocus } from "~/lib/desktopSnapShot";
 import { applyPreviewDesktopState, type DesktopPreviewOverlay } from "~/previewStateStore";
 import { previewEnvironment } from "~/state/preview";
 import { usePreparedConnection } from "~/state/session";
@@ -61,13 +62,24 @@ export function usePreviewBridge(input: {
   const lastReportedUrl = useRef<string | null>(null);
   const lastReportedKind = useRef<DesktopPreviewTabState["navStatus"]["kind"] | null>(null);
   const lastDesktopNavStatus = useRef<DesktopPreviewTabState["navStatus"] | null>(null);
+  const lastController = useRef<DesktopPreviewTabState["controller"] | null>(null);
   const handleStateChange = useEffectEvent(
     (changedTabId: string, state: DesktopPreviewTabState): void => {
       if (changedTabId !== runtimeTabId) return;
       if (shouldClearBrowserPointer(lastDesktopNavStatus.current, state.navStatus)) {
         clearBrowserPointer(runtimeTabId);
       }
       lastDesktopNavStatus.current = state.navStatus;
+      if (lastController.current === "agent" && state.controller !== "agent") {
+        if (
+          typeof document !== "undefined" &&
+          document.activeElement?.tagName.toLowerCase() === "webview"
+        ) {
+          (document.activeElement as HTMLElement).blur();
+          dispatchSnapShotComposerFocus();
+        }
+      }
+      lastController.current = state.controller;
       applyPreviewDesktopState(stableThreadRef, tabId, projectDesktopState(state));
       if (state.favicon) {
         recordFaviconForThread(stableThreadRef, state.favicon, projectRef, environmentHostname);
@@ -93,6 +105,7 @@ export function usePreviewBridge(input: {
     lastReportedUrl.current = null;
     lastReportedKind.current = null;
     lastDesktopNavStatus.current = null;
+    lastController.current = null;
     return bridge.onStateChange(handleStateChange);
   }, [bridge, runtimeTabId, stableThreadRef, tabId]);
   useEffect(() => {

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

@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, it } from "vite-plus/test";
+
+import { subscribeToPreviewFocusChanges } from "./usePreviewFocus";
+
+const originalWindow = globalThis.window;
+
+afterEach(() => {
+  if (originalWindow === undefined) {
+    delete (globalThis as { window?: Window }).window;
+  } else {
+    globalThis.window = originalWindow;
+  }
+});
+
+describe("subscribeToPreviewFocusChanges", () => {
+  it("notifies on focus and blur transitions until unsubscribed", () => {
+    const listeners = new Map<string, Set<() => void>>();
+    globalThis.window = {
+      addEventListener: (type: string, listener: EventListenerOrEventListenerObject) => {
+        const callbacks = listeners.get(type) ?? new Set<() => void>();
+        callbacks.add(listener as () => void);
+        listeners.set(type, callbacks);
+      },
+      removeEventListener: (type: string, listener: EventListenerOrEventListenerObject) => {
+        listeners.get(type)?.delete(listener as () => void);
+      },
+    } as unknown as Window & typeof globalThis;
+    let notifications = 0;
+
+    const unsubscribe = subscribeToPreviewFocusChanges(() => {
+      notifications += 1;
+    });
+
+    for (const listener of listeners.get("focusin") ?? []) listener();
+    for (const listener of listeners.get("focusout") ?? []) listener();
+    for (const listener of listeners.get("focus") ?? []) listener();
+    for (const listener of listeners.get("blur") ?? []) listener();
+    expect(notifications).toBe(4);
+
+    unsubscribe();
+    for (const listener of listeners.get("focusin") ?? []) listener();
+    for (const listener of listeners.get("focusout") ?? []) listener();
+    expect(notifications).toBe(4);
+  });
+});

apps/web/src/hooks/usePreviewFocus.ts

@@ -0,0 +1,21 @@
+import { useSyncExternalStore } from "react";
+
+import { isPreviewFocused } from "../lib/previewFocus";
+
+export function subscribeToPreviewFocusChanges(listener: () => void): () => void {
+  if (typeof window === "undefined") return () => {};
+  window.addEventListener("focusin", listener, true);
+  window.addEventListener("focusout", listener, true);
+  window.addEventListener("focus", listener, true);
+  window.addEventListener("blur", listener, true);
+  return () => {
+    window.removeEventListener("focusin", listener, true);
+    window.removeEventListener("focusout", listener, true);
+    window.removeEventListener("focus", listener, true);
+    window.removeEventListener("blur", listener, true);
+  };
+}
+
+export function usePreviewFocus(): boolean {
+  return useSyncExternalStore(subscribeToPreviewFocusChanges, isPreviewFocused, () => false);
+}

apps/web/src/lib/previewFocus.test.ts

@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, it } from "vite-plus/test";
+
+import { isPreviewFocused } from "./previewFocus";
+
+class MockHTMLElement {
+  isConnected = false;
+  tagName = "DIV";
+  closestSelector: string | null = null;
+
+  closest(selector: string): MockHTMLElement | null {
+    if (!this.isConnected) return null;
+    if (this.closestSelector && selector.includes(this.closestSelector)) {
+      return this;
+    }
+    return null;
+  }
+}
+
+const originalDocument = globalThis.document;
+const originalHTMLElement = globalThis.HTMLElement;
+
+afterEach(() => {
+  if (originalDocument === undefined) {
+    delete (globalThis as { document?: Document }).document;
+  } else {
+    globalThis.document = originalDocument;
+  }
+
+  if (originalHTMLElement === undefined) {
+    delete (globalThis as { HTMLElement?: typeof HTMLElement }).HTMLElement;
+  } else {
+    globalThis.HTMLElement = originalHTMLElement;
+  }
+});
+
+describe("isPreviewFocused", () => {
+  it("returns false when document is undefined or activeElement is null", () => {
+    globalThis.document = undefined as unknown as Document;
+    expect(isPreviewFocused()).toBe(false);
+
+    globalThis.document = { activeElement: null } as unknown as Document;
+    expect(isPreviewFocused()).toBe(false);
+  });
+
+  it("returns false for detached elements", () => {
+    const detached = new MockHTMLElement();
+    detached.isConnected = false;
+    detached.tagName = "WEBVIEW";
+
+    globalThis.HTMLElement = MockHTMLElement as unknown as typeof HTMLElement;
+    globalThis.document = { activeElement: detached } as unknown as Document;
+
+    expect(isPreviewFocused()).toBe(false);
+  });
+
+  it("returns true for attached webview", () => {
+    const webview = new MockHTMLElement();
+    webview.isConnected = true;
+    webview.tagName = "WEBVIEW";
+
+    globalThis.HTMLElement = MockHTMLElement as unknown as typeof HTMLElement;
+    globalThis.document = { activeElement: webview } as unknown as Document;
+
+    expect(isPreviewFocused()).toBe(true);
+  });
+
+  it("returns true for focus inside preview panel", () => {
+    const input = new MockHTMLElement();
+    input.isConnected = true;
+    input.tagName = "INPUT";
+    input.closestSelector = "data-preview-panel-mode";
+
+    globalThis.HTMLElement = MockHTMLElement as unknown as typeof HTMLElement;
+    globalThis.document = { activeElement: input } as unknown as Document;
+
+    expect(isPreviewFocused()).toBe(true);
+  });
+
+  it("returns true for focus inside preview viewport", () => {
+    const toolbarButton = new MockHTMLElement();
+    toolbarButton.isConnected = true;
+    toolbarButton.tagName = "BUTTON";
+    toolbarButton.closestSelector = "data-preview-viewport";
+
+    globalThis.HTMLElement = MockHTMLElement as unknown as typeof HTMLElement;
+    globalThis.document = { activeElement: toolbarButton } as unknown as Document;
+
+    expect(isPreviewFocused()).toBe(true);
+  });
+
+  it("returns true for focus inside preview mini player", () => {
+    const playerControl = new MockHTMLElement();
+    playerControl.isConnected = true;
+    playerControl.tagName = "BUTTON";
+    playerControl.closestSelector = "data-preview-mini-player";
+
+    globalThis.HTMLElement = MockHTMLElement as unknown as typeof HTMLElement;
+    globalThis.document = { activeElement: playerControl } as unknown as Document;
+
+    expect(isPreviewFocused()).toBe(true);
+  });
+
+  it("returns false for elements outside preview", () => {
+    const composer = new MockHTMLElement();
+    composer.isConnected = true;
+    composer.tagName = "TEXTAREA";
+
+    globalThis.HTMLElement = MockHTMLElement as unknown as typeof HTMLElement;
+    globalThis.document = { activeElement: composer } as unknown as Document;
+
+    expect(isPreviewFocused()).toBe(false);
+  });
+});

apps/web/src/lib/previewFocus.ts

@@ -1,15 +1,20 @@
 /**
  * Returns true when the user's keyboard focus is somewhere inside the
- * preview panel (URL bar, chrome buttons, or — once detected via Electron
- * `<webview>` focus events — the embedded page).
+ * preview panel (URL bar, chrome buttons, the embedded page via Electron
+ * `<webview>`, or the floating preview mini-player).
  *
  * Used by the global keybinding handler to gate `preview.refresh` and
- * `preview.focusUrl` to only fire while the preview owns focus.
+ * `preview.focusUrl` to only fire while the preview owns focus, and by the
+ * preview chrome/shell to render focus indicators.
  */
 export function isPreviewFocused(): boolean {
+  if (typeof document === "undefined" || typeof HTMLElement === "undefined") return false;
   const activeElement = document.activeElement;
   if (!(activeElement instanceof HTMLElement)) return false;
   if (!activeElement.isConnected) return false;
   if (activeElement.tagName.toLowerCase() === "webview") return true;
-  return activeElement.closest("[data-preview-panel-mode]") !== null;
+  if (activeElement.closest("[data-preview-panel-mode]") !== null) return true;
+  if (activeElement.closest("[data-preview-viewport]") !== null) return true;
+  if (activeElement.closest("[data-preview-mini-player]") !== null) return true;
+  return false;
 }