feat: add Linux desktop automation support via AT-SPI2

package.json

@@ -74,6 +74,9 @@
   "dependencies": {
     "pngjs": "^7.0.0"
   },
+  "optionalDependencies": {
+    "node-gtk": "^0.14.0"
+  },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.52.10",
     "@rslib/core": "0.20.1",

src/core/dispatch-resolve.ts

@@ -10,6 +10,7 @@ import {
 import { listAndroidDevices } from '../platforms/android/devices.ts';
 import { ensureAdb } from '../platforms/android/index.ts';
 import { findBootableIosSimulator, listAppleDevices } from '../platforms/ios/devices.ts';
+import { listLinuxDevices } from '../platforms/linux/devices.ts';
 import { withDiagnosticTimer } from '../utils/diagnostics.ts';
 import {
   resolveAndroidSerialAllowlist,
@@ -104,10 +105,15 @@ export async function resolveTargetDevice(flags: ResolveDeviceFlags): Promise<De
       if (selector.target && !selector.platform) {
         throw new AppError(
           'INVALID_ARGS',
-          'Device target selector requires --platform. Use --platform ios|macos|android|apple with --target mobile|tv|desktop.',
+          'Device target selector requires --platform. Use --platform ios|macos|android|linux|apple with --target mobile|tv|desktop.',
         );
       }
 
+      if (selector.platform === 'linux') {
+        const devices = await listLinuxDevices();
+        return await resolveDevice(devices, selector);
+      }
+
       if (selector.platform === 'android') {
         await ensureAdb();
         const devices = await listAndroidDevices({ serialAllowlist: androidSerialAllowlist });
@@ -122,6 +128,11 @@ export async function resolveTargetDevice(flags: ResolveDeviceFlags): Promise<De
       }
 
       const devices: DeviceInfo[] = [];
+      try {
+        devices.push(...(await listLinuxDevices()));
+      } catch {
+        // ignore
+      }
       try {
         devices.push(...(await listAndroidDevices({ serialAllowlist: androidSerialAllowlist })));
       } catch {

src/core/dispatch.ts

@@ -13,6 +13,7 @@ import { getInteractor, type Interactor, type RunnerContext } from './interactor
 import { runIosRunnerCommand } from '../platforms/ios/runner-client.ts';
 import { runMacOsPressAction, runMacOsReadTextAction } from '../platforms/ios/macos-helper.ts';
 import { pushIosNotification } from '../platforms/ios/index.ts';
+import { snapshotLinux } from '../platforms/linux/index.ts';
 import type { SessionSurface } from './session-surface.ts';
 import { isDeepLinkTarget } from './open-target.ts';
 import { getClickButtonValidationError, resolveClickButton } from './click-button.ts';
@@ -765,6 +766,25 @@ async function handleSnapshotCommand(
   context: DispatchContext | undefined,
   _runnerCtx: RunnerContext,
 ): Promise<Record<string, unknown>> {
+  if (device.platform === 'linux') {
+    const linuxResult = await withDiagnosticTimer(
+      'snapshot_capture',
+      async () =>
+        await snapshotLinux(context?.surface, {
+          interactiveOnly: context?.snapshotInteractiveOnly,
+          compact: context?.snapshotCompact,
+          depth: context?.snapshotDepth,
+          scope: context?.snapshotScope,
+          raw: context?.snapshotRaw,
+        }),
+      { backend: 'linux-atspi' },
+    );
+    return {
+      nodes: linuxResult.nodes ?? [],
+      truncated: linuxResult.truncated ?? false,
+      backend: 'linux-atspi',
+    };
+  }
   if (device.platform !== 'android') {
     const result = (await withDiagnosticTimer(
       'snapshot_capture',

src/core/interactors.ts

@@ -134,6 +134,67 @@ export function getInteractor(device: DeviceInfo, runnerContext: RunnerContext):
         setSetting: (setting, state, appId, options) =>
           setAndroidSetting(device, setting, state, appId, options),
       };
+    case 'linux':
+      return {
+        open: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'open not yet supported on Linux');
+        },
+        openDevice: () => Promise.resolve(),
+        close: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'close not yet supported on Linux');
+        },
+        tap: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'tap not yet supported on Linux');
+        },
+        doubleTap: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'doubleTap not yet supported on Linux');
+        },
+        swipe: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'swipe not yet supported on Linux');
+        },
+        longPress: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'longPress not yet supported on Linux');
+        },
+        focus: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'focus not yet supported on Linux');
+        },
+        type: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'type not yet supported on Linux');
+        },
+        fill: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'fill not yet supported on Linux');
+        },
+        scroll: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'scroll not yet supported on Linux');
+        },
+        scrollIntoView: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'scrollIntoView not yet supported on Linux');
+        },
+        screenshot: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'screenshot not yet supported on Linux');
+        },
+        back: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'back not yet supported on Linux');
+        },
+        home: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'home not yet supported on Linux');
+        },
+        rotate: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'rotate not supported on Linux');
+        },
+        appSwitcher: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'appSwitcher not yet supported on Linux');
+        },
+        readClipboard: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'readClipboard not yet supported on Linux');
+        },
+        writeClipboard: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'writeClipboard not yet supported on Linux');
+        },
+        setSetting: () => {
+          throw new AppError('UNSUPPORTED_OPERATION', 'setSetting not supported on Linux');
+        },
+      };
     case 'ios':
     case 'macos': {
       const { overrides, runnerOpts } = iosRunnerOverrides(device, runnerContext);

src/daemon/handlers/__tests__/interaction.test.ts

@@ -68,7 +68,7 @@ async function emulateCaptureSnapshotForSession(
     [],
     effectiveFlags.out,
     contextFromFlags(effectiveFlags, session.appBundleId, session.trace?.outPath),
-  )) as { nodes?: never[]; truncated?: boolean; backend?: 'xctest' | 'android' | 'macos-helper' };
+  )) as { nodes?: never[]; truncated?: boolean; backend?: 'xctest' | 'android' | 'macos-helper' | 'linux-atspi' };
   const snapshot = buildSnapshotState(snapshotData ?? {}, effectiveFlags);
   session.snapshot = snapshot;
   sessionStore.set(session.name, session);

src/daemon/handlers/session-replay-heal.ts

@@ -183,7 +183,7 @@ async function captureSnapshotForReplay(
   })) as {
     nodes?: RawSnapshotNode[];
     truncated?: boolean;
-    backend?: 'xctest' | 'android' | 'macos-helper';
+    backend?: 'xctest' | 'android' | 'macos-helper' | 'linux-atspi';
   };
   const rawNodes = data?.nodes ?? [];
   const nodes = attachRefs(action.flags?.snapshotRaw ? rawNodes : pruneGroupNodes(rawNodes));

src/daemon/handlers/snapshot-capture.ts

@@ -1,5 +1,6 @@
 import { dispatchCommand, type CommandFlags } from '../../core/dispatch.ts';
 import { runMacOsSnapshotAction } from '../../platforms/ios/macos-helper.ts';
+import { snapshotLinux } from '../../platforms/linux/index.ts';
 import type { AndroidSnapshotAnalysis } from '../../platforms/android/ui-hierarchy.ts';
 import {
   attachRefs,
@@ -36,7 +37,7 @@ type CaptureSnapshotParams = {
 type SnapshotData = {
   nodes?: RawSnapshotNode[];
   truncated?: boolean;
-  backend?: 'xctest' | 'android' | 'macos-helper';
+  backend?: 'xctest' | 'android' | 'macos-helper' | 'linux-atspi';
   analysis?: AndroidSnapshotAnalysis;
 };
 
@@ -61,6 +62,20 @@ export async function captureSnapshot(params: CaptureSnapshotParams): Promise<{
 
 export async function captureSnapshotData(params: CaptureSnapshotParams): Promise<SnapshotData> {
   const { device, session, flags, outPath, logPath, snapshotScope } = params;
+  if (device.platform === 'linux') {
+    const linuxResult = await snapshotLinux(session?.surface, {
+      interactiveOnly: flags?.snapshotInteractiveOnly,
+      compact: flags?.snapshotCompact,
+      depth: flags?.snapshotDepth,
+      scope: snapshotScope,
+      raw: flags?.snapshotRaw,
+    });
+    return {
+      nodes: linuxResult.nodes,
+      truncated: linuxResult.truncated,
+      backend: 'linux-atspi',
+    };
+  }
   if (device.platform === 'macos' && session?.surface && session.surface !== 'app') {
     const helperSnapshot = await runMacOsSnapshotAction(session.surface, {
       bundleId: session.surface === 'menubar' ? session.appBundleId : undefined,
@@ -175,7 +190,7 @@ export function buildSnapshotState(
   data: {
     nodes?: RawSnapshotNode[];
     truncated?: boolean;
-    backend?: 'xctest' | 'android' | 'macos-helper';
+    backend?: 'xctest' | 'android' | 'macos-helper' | 'linux-atspi';
   },
   flags:
     | (Pick<
@@ -189,7 +204,7 @@ export function buildSnapshotState(
   const snapshotRaw = flags?.snapshotRaw;
   const normalizedNodes = normalizeSnapshotTree(snapshotRaw ? rawNodes : pruneGroupNodes(rawNodes));
   const scopedNodes =
-    flags?.snapshotScope && data?.backend !== 'macos-helper'
+    flags?.snapshotScope && data?.backend !== 'macos-helper' && data?.backend !== 'linux-atspi'
       ? scopeSnapshotNodes(normalizedNodes, flags.snapshotScope)
       : normalizedNodes;
   const nodes = attachRefs(scopedNodes);
@@ -216,7 +231,7 @@ export function buildSnapshotVisibility(params: {
   snapshotRaw?: boolean;
 }): SnapshotVisibility {
   const { nodes, backend, snapshotRaw } = params;
-  if (snapshotRaw || backend === 'macos-helper') {
+  if (snapshotRaw || backend === 'macos-helper' || backend === 'linux-atspi') {
     return {
       partial: false,
       visibleNodeCount: nodes.length,