perf(desktop): load Windows foreground helpers only for capture reveals

ElectronWindow started a worker thread that imports the xa11y native
module at construction, and every reveal on Windows loaded ffi-rs and
opened user32. Users who never capture paid both at launch. The worker
now starts on the first capture reveal, and only a window that had
prepareReveal called on it takes the Win32 foreground path; ordinary
reveals keep Electron's native behaviour from main.

Renderer events are sent before the reveal runs and the reveal is best
effort, so a foreground refusal on Windows no longer drops the message
or duplicates it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: juliusmarminge

apps/desktop/src/electron/ElectronWindow.test.ts

@@ -17,6 +17,7 @@ const {
   nativeAppByPidMock,
   nativeAppListMock,
   shellHostedForegroundMock,
+  startWindowsForegroundFocusThreadMock,
   windowsForegroundFocusMock,
   windowsForegroundPrepareMock,
   windowsForegroundCloseMock,
@@ -30,6 +31,7 @@ const {
   nativeAppByPidMock: vi.fn(),
   nativeAppListMock: vi.fn(),
   shellHostedForegroundMock: vi.fn(),
+  startWindowsForegroundFocusThreadMock: vi.fn(),
   windowsForegroundFocusMock: vi.fn(),
   windowsForegroundPrepareMock: vi.fn(),
   windowsForegroundCloseMock: vi.fn(),
@@ -43,11 +45,7 @@ vi.mock("./WindowsForeground.ts", () => ({
 }));
 
 vi.mock("./WindowsForegroundFocusThread.ts", () => ({
-  startWindowsForegroundFocusThread: () => ({
-    prepare: windowsForegroundPrepareMock,
-    focus: windowsForegroundFocusMock,
-    close: windowsForegroundCloseMock,
-  }),
+  startWindowsForegroundFocusThread: startWindowsForegroundFocusThreadMock,
 }));
 
 vi.mock("@crowecawcaw/xa11y", () => ({
@@ -110,6 +108,11 @@ describe("ElectronWindow", () => {
     nativeAppByPidMock.mockReset();
     nativeAppListMock.mockReset().mockResolvedValue([]);
     shellHostedForegroundMock.mockReset().mockResolvedValue(false);
+    startWindowsForegroundFocusThreadMock.mockReset().mockReturnValue({
+      prepare: windowsForegroundPrepareMock,
+      focus: windowsForegroundFocusMock,
+      close: windowsForegroundCloseMock,
+    });
     windowsForegroundFocusMock.mockReset().mockResolvedValue(false);
     windowsForegroundPrepareMock.mockReset().mockResolvedValue(false);
     windowsForegroundCloseMock.mockReset();
@@ -261,6 +264,7 @@ describe("ElectronWindow", () => {
         focus: vi.fn(() => operations.push("focus")),
       } as unknown as Electron.BrowserWindow;
       const electronWindow = yield* ElectronWindow.ElectronWindow;
+      yield* electronWindow.prepareReveal(window);
 
       yield* electronWindow.reveal(window);
 
@@ -337,6 +341,7 @@ describe("ElectronWindow", () => {
       } as unknown as Electron.BrowserWindow;
 
       const electronWindow = yield* ElectronWindow.ElectronWindow;
+      yield* electronWindow.prepareReveal(window);
       const revealFiber = yield* electronWindow.reveal(window).pipe(
         Effect.andThen(
           Effect.sync(() => {
@@ -391,6 +396,7 @@ describe("ElectronWindow", () => {
       } as unknown as Electron.BrowserWindow;
       appFocusMock.mockImplementation(() => operations.push("app-focus"));
       const electronWindow = yield* ElectronWindow.ElectronWindow;
+      yield* electronWindow.prepareReveal(window);
 
       yield* electronWindow.reveal(window);
 
@@ -459,6 +465,8 @@ describe("ElectronWindow", () => {
         window.getNativeWindowHandle.mockReturnValue(handle);
         activeWindowMock.mockResolvedValue({ id: hwnd, owner: { processId: process.pid } });
         const electronWindow = yield* ElectronWindow.ElectronWindow;
+        yield* electronWindow.prepareReveal(window as unknown as Electron.BrowserWindow);
+        window.getTitle.mockClear();
 
         yield* electronWindow.reveal(window as unknown as Electron.BrowserWindow);
 
@@ -488,6 +496,7 @@ describe("ElectronWindow", () => {
         },
       ]);
       const electronWindow = yield* ElectronWindow.ElectronWindow;
+      yield* electronWindow.prepareReveal(window as unknown as Electron.BrowserWindow);
 
       yield* electronWindow.reveal(window as unknown as Electron.BrowserWindow);
 
@@ -510,6 +519,7 @@ describe("ElectronWindow", () => {
         },
       ]);
       const electronWindow = yield* ElectronWindow.ElectronWindow;
+      yield* electronWindow.prepareReveal(window as unknown as Electron.BrowserWindow);
 
       yield* electronWindow.reveal(window as unknown as Electron.BrowserWindow);
 
@@ -533,6 +543,7 @@ describe("ElectronWindow", () => {
         },
       ]);
       const electronWindow = yield* ElectronWindow.ElectronWindow;
+      yield* electronWindow.prepareReveal(window as unknown as Electron.BrowserWindow);
 
       yield* electronWindow.reveal(window as unknown as Electron.BrowserWindow);
 
@@ -546,6 +557,7 @@ describe("ElectronWindow", () => {
       const window = makeWindowsRevealWindow();
       activateWindowsForegroundMock.mockRejectedValue(cause);
       const electronWindow = yield* ElectronWindow.ElectronWindow;
+      yield* electronWindow.prepareReveal(window as unknown as Electron.BrowserWindow);
 
       const exit = yield* Effect.exit(
         electronWindow.reveal(window as unknown as Electron.BrowserWindow),
@@ -578,6 +590,8 @@ describe("ElectronWindow", () => {
         return foreground.promise;
       });
       const electronWindow = yield* ElectronWindow.ElectronWindow;
+      yield* electronWindow.prepareReveal(window as unknown as Electron.BrowserWindow);
+      window.getTitle.mockClear();
 
       const revealFiber = yield* electronWindow
         .reveal(window as unknown as Electron.BrowserWindow)
@@ -610,6 +624,7 @@ describe("ElectronWindow", () => {
           new Error("Windows initially refused foreground activation"),
         );
         const electronWindow = yield* ElectronWindow.ElectronWindow;
+        yield* electronWindow.prepareReveal(window as unknown as Electron.BrowserWindow);
 
         const revealFiber = yield* electronWindow
           .reveal(window as unknown as Electron.BrowserWindow)
@@ -684,9 +699,49 @@ describe("ElectronWindow", () => {
       assert.equal(vi.mocked(laterWindow.destroy).mock.calls.length, 1);
     }).pipe(Effect.provide(TestLayer)),
   );
-  it.effect("closes the Windows focus worker when its layer is released", () =>
+  it.effect("an ordinary reveal on Windows does not touch the Win32 foreground helpers", () =>
+    Effect.gen(function* () {
+      const window = makeWindowsRevealWindow();
+      const electronWindow = yield* ElectronWindow.ElectronWindow;
+
+      yield* electronWindow.reveal(window as unknown as Electron.BrowserWindow);
+
+      assert.lengthOf(activateWindowsForegroundMock.mock.calls, 0);
+      assert.lengthOf(windowsForegroundFocusMock.mock.calls, 0);
+      assert.lengthOf(shellHostedForegroundMock.mock.calls, 0);
+      assert.lengthOf(startWindowsForegroundFocusThreadMock.mock.calls, 0);
+      assert.lengthOf(window.focus.mock.calls, 1);
+    }).pipe(Effect.provide(testLayer("win32"))),
+  );
+
+  it.effect("a capture reveal on Windows uses the Win32 path only once", () =>
+    Effect.gen(function* () {
+      const window = makeWindowsRevealWindow();
+      const electronWindow = yield* ElectronWindow.ElectronWindow;
+
+      yield* electronWindow.prepareReveal(window as unknown as Electron.BrowserWindow);
+      yield* electronWindow.reveal(window as unknown as Electron.BrowserWindow);
+      yield* electronWindow.reveal(window as unknown as Electron.BrowserWindow);
+
+      assert.lengthOf(activateWindowsForegroundMock.mock.calls, 1);
+      assert.lengthOf(window.focus.mock.calls, 2);
+    }).pipe(Effect.provide(testLayer("win32"))),
+  );
+
+  it.effect("starts the Windows focus worker lazily and closes it with the layer", () =>
     Effect.gen(function* () {
       yield* ElectronWindow.ElectronWindow.pipe(Effect.provide(testLayer("win32")));
+      assert.lengthOf(startWindowsForegroundFocusThreadMock.mock.calls, 0);
+      assert.lengthOf(windowsForegroundCloseMock.mock.calls, 0);
+
+      yield* Effect.gen(function* () {
+        const electronWindow = yield* ElectronWindow.ElectronWindow;
+        const window = makeWindowsRevealWindow() as unknown as Electron.BrowserWindow;
+        yield* electronWindow.prepareReveal(window);
+        yield* electronWindow.prepareReveal(window);
+        assert.lengthOf(startWindowsForegroundFocusThreadMock.mock.calls, 1);
+        assert.lengthOf(windowsForegroundCloseMock.mock.calls, 0);
+      }).pipe(Effect.provide(testLayer("win32")));
       assert.lengthOf(windowsForegroundCloseMock.mock.calls, 1);
     }),
   );

apps/desktop/src/electron/ElectronWindow.ts

@@ -13,7 +13,6 @@ import * as Ref from "effect/Ref";
 import * as Schema from "effect/Schema";
 
 import * as Electron from "electron";
-import { activeWindow } from "get-windows";
 
 import { activateWindowsForeground, isWindowsShellHostedForeground } from "./WindowsForeground.ts";
 import { startWindowsForegroundFocusThread } from "./WindowsForegroundFocusThread.ts";
@@ -29,6 +28,7 @@ function windowsForegroundFocusTarget(window: Electron.BrowserWindow) {
 }
 
 async function isWindowsBrowserWindowForeground(window: Electron.BrowserWindow): Promise<boolean> {
+  const { activeWindow } = await import("get-windows");
   const foreground = await activeWindow().catch(() => undefined);
   if (window.isDestroyed() || foreground?.owner.processId !== process.pid) return false;
   const handle = window.getNativeWindowHandle();
@@ -154,15 +154,18 @@ export class ElectronWindow extends Context.Service<
 
 export const make = Effect.gen(function* () {
   const platform = yield* HostProcessPlatform;
-  const windowsForegroundFocus =
-    platform === "win32"
-      ? startWindowsForegroundFocusThread(
-          NodePath.join(__dirname, "electron", "WindowsForegroundFocusWorker.cjs"),
-        )
-      : undefined;
-  if (windowsForegroundFocus) {
-    yield* Effect.addFinalizer(() => Effect.sync(() => windowsForegroundFocus.close()));
-  }
+  // The focus worker loads a native accessibility module. Start it on the first
+  // capture reveal so users who never capture pay nothing at launch.
+  let windowsForegroundFocus: ReturnType<typeof startWindowsForegroundFocusThread> | undefined;
+  const ensureWindowsForegroundFocus = () => {
+    windowsForegroundFocus ??= startWindowsForegroundFocusThread(
+      NodePath.join(__dirname, "electron", "WindowsForegroundFocusWorker.cjs"),
+    );
+    return windowsForegroundFocus;
+  };
+  // Tracks a capture reveal in flight. Ordinary reveals keep Electron's native path.
+  const captureRevealWindows = new Set<number>();
+  yield* Effect.addFinalizer(() => Effect.sync(() => windowsForegroundFocus?.close()));
   const mainWindowRef = yield* Ref.make<Option.Option<Electron.BrowserWindow>>(Option.none());
 
   const listWindows = Effect.try({
@@ -275,10 +278,11 @@ export const make = Effect.gen(function* () {
       }),
     prepareReveal: (window) =>
       Effect.promise(async () => {
-        if (platform !== "win32" || !windowsForegroundFocus || window.isDestroyed()) {
+        if (platform !== "win32" || window.isDestroyed()) {
           return false;
         }
-        return windowsForegroundFocus
+        captureRevealWindows.add(window.id);
+        return ensureWindowsForegroundFocus()
           .prepare(windowsForegroundFocusTarget(window))
           .catch(() => false);
       }),
@@ -289,22 +293,25 @@ export const make = Effect.gen(function* () {
             return;
           }
 
+          // Only a capture reveal fights another process for the foreground, which
+          // needs Win32 calls that load native modules. Everything else stays native.
+          const captureReveal = platform === "win32" && captureRevealWindows.delete(window.id);
           const shellHostedForeground =
-            platform === "win32" && (await isWindowsShellHostedForeground().catch(() => false));
+            captureReveal && (await isWindowsShellHostedForeground().catch(() => false));
 
           if (window.isMinimized()) {
             window.restore();
           }
 
-          if (platform === "win32") {
+          if (captureReveal) {
             Electron.app.focus();
           }
 
-          if (platform === "win32" || !window.isVisible()) {
+          if (captureReveal || !window.isVisible()) {
             window.show();
           }
 
-          if (platform === "win32") {
+          if (captureReveal) {
             window.moveTop();
           }
 
@@ -314,7 +321,7 @@ export const make = Effect.gen(function* () {
 
           window.focus();
 
-          if (platform === "win32") {
+          if (captureReveal) {
             if (shellHostedForeground) {
               await windowsForegroundFocus
                 ?.focus(windowsForegroundFocusTarget(window))

apps/desktop/src/window/DesktopWindow.test.ts

@@ -1301,7 +1301,7 @@ describe("DesktopWindow", () => {
         });
 
         assert.equal(foreground, "Explorer");
-        assert.deepEqual(operations, ["reveal", "send", "send", "send"]);
+        assert.deepEqual(operations, ["send", "reveal", "send", "send"]);
         assert.deepEqual(fakeWindow.send.mock.calls, [
           [MENU_ACTION_CHANNEL, "snap-shot-started:capture-1"],
           [SNAP_SHOT_READY_CHANNEL, "capture-1"],
@@ -1311,6 +1311,32 @@ describe("DesktopWindow", () => {
     }),
   );
 
+  it.effect("delivers the renderer event even when the reveal fails", () =>
+    Effect.gen(function* () {
+      const fakeWindow = makeFakeBrowserWindow();
+      const createCount = yield* Ref.make(0);
+      const mainWindow = yield* Ref.make<Option.Option<Electron.BrowserWindow>>(Option.none());
+      const layer = makeTestLayer({
+        window: fakeWindow.window,
+        createCount,
+        mainWindow,
+        onReveal: () => {
+          throw new Error("another process kept the foreground");
+        },
+      });
+
+      yield* Effect.gen(function* () {
+        const desktopWindow = yield* DesktopWindow.DesktopWindow;
+        yield* desktopWindow.handleBackendReady(new URL("http://127.0.0.1:3773"));
+        yield* Effect.exit(desktopWindow.dispatchMenuAction("snap-shot-started:capture-1"));
+
+        assert.deepEqual(fakeWindow.send.mock.calls, [
+          [MENU_ACTION_CHANNEL, "snap-shot-started:capture-1"],
+        ]);
+      }).pipe(Effect.provide(layer));
+    }),
+  );
+
   it.effect("leaves a completed capture pending while only the connecting splash exists", () =>
     Effect.gen(function* () {
       const splash = makeFakeBrowserWindow();

apps/desktop/src/window/DesktopWindow.ts

@@ -869,7 +869,11 @@ export const make = Effect.gen(function* () {
     const send = Effect.sync(() => {
       if (!targetWindow.isDestroyed()) targetWindow.webContents.send(channel, payload);
     });
-    const dispatch = reveal ? electronWindow.reveal(targetWindow).pipe(Effect.andThen(send)) : send;
+    // The renderer must learn about the event even when another process refuses to
+    // yield the foreground, so send first and treat the reveal as best effort.
+    const dispatch = reveal
+      ? send.pipe(Effect.andThen(electronWindow.reveal(targetWindow).pipe(Effect.ignoreCause)))
+      : send;
     if (targetWindow.webContents.isLoadingMainFrame()) {
       targetWindow.webContents.once("did-finish-load", () => void runPromise(dispatch));
       return;