feat(desktop): add cross-platform window capture

apps/desktop/package.json

@@ -24,6 +24,7 @@
     "electron": "41.5.0",
     "electron-store": "^8.2.0",
     "electron-updater": "^6.6.2",
+    "get-windows": "9.3.0",
     "playwright-core": "1.60.0",
     "react-grab": "^0.1.32"
   },

apps/desktop/scripts/electron-launcher.mjs

@@ -20,7 +20,7 @@ export const APP_BUNDLE_ID = isDevelopment
   ? `com.t3tools.t3code.dev.${devBundleIdSuffix || "local"}`
   : "com.t3tools.t3code";
 const APP_PROTOCOL_SCHEMES = isDevelopment ? ["t3code-dev"] : ["t3code"];
-const LAUNCHER_VERSION = 15;
+const LAUNCHER_VERSION = 16;
 const developmentMacIconPngPath = NodePath.join(
   repoRoot,
   "assets",
@@ -221,13 +221,23 @@ function ensureMacIconIcns(runtimeDir) {
   }
 }
 
+export function resolveMacBundleInfoPlistStrings(executableName) {
+  return {
+    CFBundleDisplayName: APP_DISPLAY_NAME,
+    CFBundleName: APP_DISPLAY_NAME,
+    CFBundleIdentifier: APP_BUNDLE_ID,
+    CFBundleExecutable: executableName,
+    CFBundleIconFile: "icon.icns",
+    NSScreenCaptureUsageDescription:
+      "T3 Code captures the active window when you use the window capture shortcut.",
+  };
+}
+
 function patchMainBundleInfoPlist(appBundlePath, iconPath, executableName) {
   const infoPlistPath = NodePath.join(appBundlePath, "Contents", "Info.plist");
-  setPlistString(infoPlistPath, "CFBundleDisplayName", APP_DISPLAY_NAME);
-  setPlistString(infoPlistPath, "CFBundleName", APP_DISPLAY_NAME);
-  setPlistString(infoPlistPath, "CFBundleIdentifier", APP_BUNDLE_ID);
-  setPlistString(infoPlistPath, "CFBundleExecutable", executableName);
-  setPlistString(infoPlistPath, "CFBundleIconFile", "icon.icns");
+  for (const [key, value] of Object.entries(resolveMacBundleInfoPlistStrings(executableName))) {
+    setPlistString(infoPlistPath, key, value);
+  }
   setPlistJson(infoPlistPath, "CFBundleURLTypes", [
     {
       CFBundleURLName: APP_BUNDLE_ID,

apps/desktop/scripts/electron-launcher.test.mjs

@@ -3,6 +3,7 @@ import { assert, describe, it } from "vite-plus/test";
 import {
   makeDevelopmentLauncherScript,
   resolveElectronBinaryPath,
+  resolveMacBundleInfoPlistStrings,
   resolveMacLauncherIconPaths,
   resolveMacLauncherPaths,
 } from "./electron-launcher.mjs";
@@ -80,6 +81,15 @@ describe("electron development launcher", () => {
     assert.notInclude(script, "node_modules/electron");
   });
 
+  it("declares why the macOS app captures the screen", () => {
+    const values = resolveMacBundleInfoPlistStrings("T3 Code (Dev) Launcher");
+
+    assert.equal(
+      values.NSScreenCaptureUsageDescription,
+      "T3 Code captures the active window when you use the window capture shortcut.",
+    );
+  });
+
   it("derives launcher icons from canonical development and production assets", () => {
     const development = resolveMacLauncherIconPaths("/runtime", true);
     const production = resolveMacLauncherIconPaths("/runtime", false);

apps/desktop/src/app/DesktopApp.ts

@@ -27,6 +27,7 @@ import * as DesktopAppSettings from "../settings/DesktopAppSettings.ts";
 import * as DesktopShellEnvironment from "../shell/DesktopShellEnvironment.ts";
 import * as DesktopState from "./DesktopState.ts";
 import * as DesktopUpdates from "../updates/DesktopUpdates.ts";
+import * as DesktopWindowCapture from "../windowCapture/DesktopWindowCapture.ts";
 import * as DesktopWslBackend from "../wsl/DesktopWslBackend.ts";
 
 const DEFAULT_DESKTOP_BACKEND_PORT = 3773;
@@ -148,6 +149,7 @@ const bootstrap = Effect.gen(function* () {
   const serverExposure = yield* DesktopServerExposure.DesktopServerExposure;
   const wslBackend = yield* DesktopWslBackend.DesktopWslBackend;
   const desktopWindow = yield* DesktopWindow.DesktopWindow;
+  const windowCapture = yield* DesktopWindowCapture.DesktopWindowCapture;
   yield* logBootstrapInfo("bootstrap start");
 
   if (environment.isDevelopment && Option.isNone(environment.configuredBackendPort)) {
@@ -196,6 +198,7 @@ const bootstrap = Effect.gen(function* () {
       "bootstrap fell back to local-only because no advertised network host was available",
     );
   }
+  yield* windowCapture.initialize;
 
   yield* installDesktopIpcHandlers();
   yield* logBootstrapInfo("bootstrap ipc handlers registered");

apps/desktop/src/app/DesktopPreReadyPlatform.ts

@@ -53,6 +53,18 @@ export const make = Effect.gen(function* () {
       platform === "linux"
         ? readCommandLineSwitchValue(Electron.app.commandLine, "password-store")
         : null;
+    if (platform === "linux") {
+      const enabledFeatures = Electron.app.commandLine
+        .getSwitchValue("enable-features")
+        .split(",")
+        .filter(Boolean);
+      if (!enabledFeatures.includes("GlobalShortcutsPortal")) {
+        Electron.app.commandLine.appendSwitch(
+          "enable-features",
+          [...enabledFeatures, "GlobalShortcutsPortal"].join(","),
+        );
+      }
+    }
     const linux = platform === "linux" ? resolveEarlyLinuxElectronOptionsFromProcess() : null;
 
     if (linux !== null) {

apps/desktop/src/ipc/DesktopIpcHandlers.ts

@@ -44,6 +44,13 @@ import {
   setTheme,
   showContextMenu,
 } from "./methods/window.ts";
+import {
+  acknowledgeWindowCapture,
+  captureWindow,
+  getWindowCaptureState,
+  listPendingWindowCaptures,
+  readWindowCapture,
+} from "./methods/windowCapture.ts";
 import * as PreviewIpc from "./methods/preview.ts";
 import { getWslState, setWslBackendEnabled, setWslDistro, setWslOnly } from "./methods/wsl.ts";
 
@@ -60,6 +67,11 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
   yield* ipc.handle(getClientSettings);
   yield* ipc.handle(setClientSettings);
   yield* ipc.handle(getConnectionCatalog);
+  yield* ipc.handle(getWindowCaptureState);
+  yield* ipc.handle(captureWindow);
+  yield* ipc.handle(listPendingWindowCaptures);
+  yield* ipc.handle(readWindowCapture);
+  yield* ipc.handle(acknowledgeWindowCapture);
   yield* ipc.handle(setConnectionCatalog);
   yield* ipc.handle(clearConnectionCatalog);
 

apps/desktop/src/ipc/channels.ts

@@ -22,6 +22,11 @@ export const GET_LOCAL_ENVIRONMENT_BEARER_TOKEN_CHANNEL =
   "desktop:get-local-environment-bearer-token";
 export const GET_CLIENT_SETTINGS_CHANNEL = "desktop:get-client-settings";
 export const SET_CLIENT_SETTINGS_CHANNEL = "desktop:set-client-settings";
+export const GET_WINDOW_CAPTURE_STATE_CHANNEL = "desktop:get-window-capture-state";
+export const CAPTURE_WINDOW_CHANNEL = "desktop:capture-window";
+export const LIST_PENDING_WINDOW_CAPTURES_CHANNEL = "desktop:list-pending-window-captures";
+export const READ_WINDOW_CAPTURE_CHANNEL = "desktop:read-window-capture";
+export const ACKNOWLEDGE_WINDOW_CAPTURE_CHANNEL = "desktop:acknowledge-window-capture";
 export const GET_CONNECTION_CATALOG_CHANNEL = "desktop:get-connection-catalog";
 export const SET_CONNECTION_CATALOG_CHANNEL = "desktop:set-connection-catalog";
 export const CLEAR_CONNECTION_CATALOG_CHANNEL = "desktop:clear-connection-catalog";

apps/desktop/src/ipc/methods/clientSettings.ts

@@ -4,6 +4,7 @@ import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 
 import * as DesktopClientSettings from "../../settings/DesktopClientSettings.ts";
+import * as DesktopWindowCapture from "../../windowCapture/DesktopWindowCapture.ts";
 import * as IpcChannels from "../channels.ts";
 import * as DesktopIpc from "../DesktopIpc.ts";
 
@@ -23,6 +24,8 @@ export const setClientSettings = DesktopIpc.makeIpcMethod({
   result: Schema.Void,
   handler: Effect.fn("desktop.ipc.clientSettings.set")(function* (settings) {
     const clientSettings = yield* DesktopClientSettings.DesktopClientSettings;
+    const windowCapture = yield* DesktopWindowCapture.DesktopWindowCapture;
     yield* clientSettings.set(settings);
+    yield* windowCapture.configure(settings);
   }),
 });

apps/desktop/src/ipc/methods/windowCapture.ts

@@ -0,0 +1,57 @@
+import {
+  DesktopPendingWindowCapture,
+  DesktopWindowCapture as DesktopWindowCaptureSchema,
+  DesktopWindowCaptureId,
+  DesktopWindowCaptureState,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+
+import * as DesktopWindowCapture from "../../windowCapture/DesktopWindowCapture.ts";
+import * as IpcChannels from "../channels.ts";
+import * as DesktopIpc from "../DesktopIpc.ts";
+
+export const getWindowCaptureState = DesktopIpc.makeIpcMethod({
+  channel: IpcChannels.GET_WINDOW_CAPTURE_STATE_CHANNEL,
+  payload: Schema.Void,
+  result: DesktopWindowCaptureState,
+  handler: Effect.fn("desktop.ipc.windowCapture.getState")(function* () {
+    return yield* (yield* DesktopWindowCapture.DesktopWindowCapture).state;
+  }),
+});
+
+export const captureWindow = DesktopIpc.makeIpcMethod({
+  channel: IpcChannels.CAPTURE_WINDOW_CHANNEL,
+  payload: Schema.Void,
+  result: Schema.Void,
+  handler: Effect.fn("desktop.ipc.windowCapture.capture")(function* () {
+    yield* (yield* DesktopWindowCapture.DesktopWindowCapture).capture;
+  }),
+});
+
+export const listPendingWindowCaptures = DesktopIpc.makeIpcMethod({
+  channel: IpcChannels.LIST_PENDING_WINDOW_CAPTURES_CHANNEL,
+  payload: Schema.Void,
+  result: Schema.Array(DesktopPendingWindowCapture),
+  handler: Effect.fn("desktop.ipc.windowCapture.listPending")(function* () {
+    return yield* (yield* DesktopWindowCapture.DesktopWindowCapture).listPending;
+  }),
+});
+
+export const readWindowCapture = DesktopIpc.makeIpcMethod({
+  channel: IpcChannels.READ_WINDOW_CAPTURE_CHANNEL,
+  payload: DesktopWindowCaptureId,
+  result: DesktopWindowCaptureSchema,
+  handler: Effect.fn("desktop.ipc.windowCapture.read")(function* (id) {
+    return yield* (yield* DesktopWindowCapture.DesktopWindowCapture).read(id);
+  }),
+});
+
+export const acknowledgeWindowCapture = DesktopIpc.makeIpcMethod({
+  channel: IpcChannels.ACKNOWLEDGE_WINDOW_CAPTURE_CHANNEL,
+  payload: DesktopWindowCaptureId,
+  result: Schema.Void,
+  handler: Effect.fn("desktop.ipc.windowCapture.acknowledge")(function* (id) {
+    yield* (yield* DesktopWindowCapture.DesktopWindowCapture).acknowledge(id);
+  }),
+});

apps/desktop/src/main.ts

@@ -49,6 +49,7 @@ import * as DesktopObservability from "./app/DesktopObservability.ts";
 import * as DesktopServerExposure from "./backend/DesktopServerExposure.ts";
 import * as DesktopClientSettings from "./settings/DesktopClientSettings.ts";
 import * as DesktopSavedEnvironments from "./settings/DesktopSavedEnvironments.ts";
+import * as DesktopWindowCapture from "./windowCapture/DesktopWindowCapture.ts";
 import * as DesktopAppSettings from "./settings/DesktopAppSettings.ts";
 import * as DesktopPreReadyPlatform from "./app/DesktopPreReadyPlatform.ts";
 import * as DesktopShellEnvironment from "./shell/DesktopShellEnvironment.ts";
@@ -157,6 +158,11 @@ const desktopWindowLayer = DesktopWindow.layer.pipe(
   Layer.provideMerge(desktopPreviewLayer),
 );
 
+const desktopWindowCaptureLayer = DesktopWindowCapture.layer.pipe(
+  Layer.provideMerge(desktopWindowLayer),
+  Layer.provideMerge(desktopFoundationLayer),
+);
+
 // Pool layer instantiates the backend factory once for the Windows
 // primary instance and exposes it via pool.primary. Consumers go through
 // the pool now; the legacy DesktopBackendManager service is gone. The
@@ -189,6 +195,7 @@ const desktopApplicationLayer = Layer.mergeAll(
   DesktopShellEnvironment.layer,
   desktopSshLayer,
 ).pipe(
+  Layer.provideMerge(desktopWindowCaptureLayer),
   Layer.provideMerge(DesktopUpdates.layer),
   Layer.provideMerge(desktopWslBackendLayer),
   Layer.provideMerge(desktopLocalEnvironmentAuthLayer),

apps/desktop/src/preload.ts

@@ -51,6 +51,13 @@ contextBridge.exposeInMainWorld("desktopBridge", {
   getClientSettings: () => ipcRenderer.invoke(IpcChannels.GET_CLIENT_SETTINGS_CHANNEL),
   setClientSettings: (settings) =>
     ipcRenderer.invoke(IpcChannels.SET_CLIENT_SETTINGS_CHANNEL, settings),
+  getWindowCaptureState: () => ipcRenderer.invoke(IpcChannels.GET_WINDOW_CAPTURE_STATE_CHANNEL),
+  captureWindow: () => ipcRenderer.invoke(IpcChannels.CAPTURE_WINDOW_CHANNEL),
+  listPendingWindowCaptures: () =>
+    ipcRenderer.invoke(IpcChannels.LIST_PENDING_WINDOW_CAPTURES_CHANNEL),
+  readWindowCapture: (id) => ipcRenderer.invoke(IpcChannels.READ_WINDOW_CAPTURE_CHANNEL, id),
+  acknowledgeWindowCapture: (id) =>
+    ipcRenderer.invoke(IpcChannels.ACKNOWLEDGE_WINDOW_CAPTURE_CHANNEL, id),
   getConnectionCatalog: () => ipcRenderer.invoke(IpcChannels.GET_CONNECTION_CATALOG_CHANNEL),
   setConnectionCatalog: (catalog) =>
     ipcRenderer.invoke(IpcChannels.SET_CONNECTION_CATALOG_CHANNEL, catalog),

apps/desktop/src/settings/DesktopClientSettings.test.ts

@@ -1,6 +1,10 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, describe, it } from "@effect/vitest";
-import { ClientSettingsSchema, type ClientSettings } from "@t3tools/contracts";
+import {
+  ClientSettingsSchema,
+  DEFAULT_CLIENT_SETTINGS,
+  type ClientSettings,
+} from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
@@ -13,6 +17,7 @@ import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
 import * as DesktopClientSettings from "./DesktopClientSettings.ts";
 
 const clientSettings: ClientSettings = {
+  ...DEFAULT_CLIENT_SETTINGS,
   appearanceContrast: 100,
   browserDefaultViewport: { _tag: "preset", width: 1024, height: 600, presetId: "nest-hub" },
   browserDefaultZoomFactor: 1.25,