refactor: consolidate desktop snapshot capture

Author: thymikee

scripts/layering/cutover-policy-ast.ts

@@ -19,6 +19,19 @@ export function propertyName(node: unknown): string | undefined {
     : undefined;
 }
 
+export function memberPath(node: unknown): string[] | undefined {
+  if (node === null || typeof node !== 'object') return undefined;
+  const record = node as Record<string, unknown>;
+  if (record.type === 'Identifier') {
+    return typeof record.name === 'string' ? [record.name] : undefined;
+  }
+  if (record.type === 'ChainExpression') return memberPath(record.expression);
+  if (record.type !== 'MemberExpression' || record.computed === true) return undefined;
+  const object = memberPath(record.object);
+  const name = propertyName(record.property);
+  return object && name ? [...object, name] : undefined;
+}
+
 export function visitAst(node: unknown, visitor: (node: Record<string, unknown>) => void): void {
   if (node === null || typeof node !== 'object') return;
   if (Array.isArray(node)) {

scripts/layering/platform-package-source-policy.ts

@@ -1,4 +1,5 @@
 import { parseSync } from 'oxc-parser';
+import { memberPath } from './cutover-policy-ast.ts';
 import { parseImports, type LayeringViolation } from './model.ts';
 
 const RULE = 'R13 platform-package-substrate';
@@ -38,21 +39,6 @@ function rootIdentifier(node: unknown): string | undefined {
   return undefined;
 }
 
-function memberPath(node: unknown): string[] | undefined {
-  if (node === null || typeof node !== 'object') return undefined;
-  const record = node as Record<string, unknown>;
-  if (record['type'] === 'Identifier') {
-    const name = record['name'];
-    return typeof name === 'string' ? [name] : undefined;
-  }
-  if (record['type'] === 'ChainExpression') return memberPath(record['expression']);
-  if (record['type'] !== 'MemberExpression' || record['computed'] === true) return undefined;
-  const object = memberPath(record['object']);
-  const property = record['property'] as Record<string, unknown> | undefined;
-  const name = property?.['type'] === 'Identifier' ? property['name'] : undefined;
-  return object && typeof name === 'string' ? [...object, name] : undefined;
-}
-
 function literalString(node: unknown): string | undefined {
   if (node === null || typeof node !== 'object') return undefined;
   const value = (node as Record<string, unknown>)['value'];

scripts/layering/runtime-command-cutover-snapshot.ts

@@ -1,5 +1,5 @@
 import { parseSync } from 'oxc-parser';
-import { propertyName, visitAst } from './cutover-policy-ast.ts';
+import { memberPath, visitAst } from './cutover-policy-ast.ts';
 import { countNamedCalls, lineOf, namedFunction } from './runtime-command-cutover-ast.ts';
 import type { UnruledViolation } from './runtime-command-cutover-model.ts';
 
@@ -78,20 +78,6 @@ export function snapshotPlatformPolicyBranchViolations(
   return violations;
 }
 
-function memberPath(node: unknown): string[] | undefined {
-  if (node === null || typeof node !== 'object') return undefined;
-  const record = node as AstNode;
-  if (record['type'] === 'Identifier') {
-    const name = record['name'];
-    return typeof name === 'string' ? [name] : undefined;
-  }
-  if (record['type'] === 'ChainExpression') return memberPath(record['expression']);
-  if (record['type'] !== 'MemberExpression' || record['computed'] === true) return undefined;
-  const object = memberPath(record['object']);
-  const name = propertyName(record['property']);
-  return object && name ? [...object, name] : undefined;
-}
-
 function samePath(actual: readonly string[], expected: readonly string[]): boolean {
   return (
     actual.length === expected.length && actual.every((part, index) => part === expected[index])

src/core/interactors/linux.ts

@@ -19,8 +19,7 @@ import {
 } from '../../platforms/linux/input-actions.ts';
 import { singlePointerPlanEndpoints } from '@agent-device/contracts/interaction';
 import { screenshotLinux } from '../../platforms/linux/screenshot.ts';
-import { snapshotLinux } from '../../platforms/linux/snapshot.ts';
-import { shapeDesktopSurfaceSnapshot } from '../../snapshot/snapshot-desktop-surface.ts';
+import { captureLinuxSurfaceSnapshot } from '../../snapshot/snapshot-desktop-surface.ts';
 import type { Interactor } from '@agent-device/contracts/interaction';
 
 export function createLinuxInteractor(): Interactor {
@@ -47,19 +46,11 @@ export function createLinuxInteractor(): Interactor {
     },
     screenshot: (outPath, options) => screenshotLinux(outPath, options),
     snapshot: async (options) => {
-      const result = await withDiagnosticTimer(
+      return await withDiagnosticTimer(
         'snapshot_capture',
-        async () => await snapshotLinux(options?.surface, options?.signal),
+        async () => await captureLinuxSurfaceSnapshot(options, options?.signal),
         { backend: 'linux-atspi' },
       );
-      return shapeDesktopSurfaceSnapshot(
-        {
-          nodes: result.nodes ?? [],
-          truncated: result.truncated ?? false,
-          backend: 'linux-atspi',
-        },
-        options ?? {},
-      );
     },
     back: () => backLinux(),
     home: () => homeLinux(),

src/platform-runtime-operation-host.ts

@@ -27,7 +27,7 @@ import { createAppleApplicationTools } from './platform-runtime-apple-applicatio
 import { createAndroidApplicationTools } from './platform-runtime-android-application-tools.ts';
 import { createLocalApplicationInteractorHost } from './platform-runtime-local-application-interactors.ts';
 import { createApplicationResourceLifecycle } from './platform-runtime-application-resources.ts';
-import { createSnapshotRuntimeHost } from './platform-runtime-snapshot-host.ts';
+import { createSnapshotRuntimeHost } from './snapshot/snapshot-desktop-surface.ts';
 
 export function createPlatformRuntimeHost(options: {
   sessionsDir: string;

src/platform-runtime-snapshot-host.ts

@@ -10,7 +10,7 @@ import {
 import { captureScreenshotViaRunner } from './core/screenshot.ts';
 import { iosRunnerOverrides, resolveAppleBackRunnerCommand } from './interactions.ts';
 import { appleRemotePressCommand } from './os/tvos/remote.ts';
-import { runMacOsScreenshotAction, runMacOsSnapshotAction } from './os/macos/helper.ts';
+import { runMacOsScreenshotAction } from './os/macos/helper.ts';
 import { runAppleRunnerCommand } from './core/runner/runner-client.ts';
 import {
   withAppleRunnerProvider,
@@ -32,7 +32,7 @@ import type {
   SnapshotOptions,
 } from '@agent-device/contracts/interaction';
 import { readSnapshotQualityVerdict } from '../../snapshot-quality/verdict.ts';
-import { shapeDesktopSurfaceSnapshot } from '../../snapshot/snapshot-desktop-surface.ts';
+import { captureMacOsSurfaceSnapshot } from '../../snapshot/snapshot-desktop-surface.ts';
 
 export function createAppleInteractor(
   device: DeviceInfo,
@@ -151,24 +151,11 @@ async function captureAppleSnapshot(
   runnerOpts: RunnerCallOptions,
 ) {
   if (isMacOs(device) && options?.surface && options.surface !== 'app') {
-    return await captureMacOsSurfaceSnapshot(options.surface, options);
+    return await captureMacOsSurfaceSnapshot(options, options.signal);
   }
   return await captureAppleRunnerSnapshot(device, options, runnerOpts);
 }
 
-async function captureMacOsSurfaceSnapshot(
-  surface: Exclude<NonNullable<SnapshotOptions['surface']>, 'app'>,
-  options: SnapshotOptions,
-) {
-  return shapeDesktopSurfaceSnapshot(
-    await runMacOsSnapshotAction(surface, {
-      bundleId: surface === 'menubar' ? options.appBundleId : undefined,
-      signal: options.signal,
-    }),
-    options,
-  );
-}
-
 async function captureAppleRunnerSnapshot(
   device: DeviceInfo,
   options: SnapshotOptions | undefined,

src/platforms/apple/interactor.ts

@@ -6,10 +6,10 @@ const { runMacOsSnapshotAction, snapshotLinux } = vi.hoisted(() => ({
   snapshotLinux: vi.fn(),
 }));
 
-vi.mock('./platforms/apple/os/macos/helper.ts', () => ({ runMacOsSnapshotAction }));
-vi.mock('./platforms/linux/snapshot.ts', () => ({ snapshotLinux }));
+vi.mock('../platforms/apple/os/macos/helper.ts', () => ({ runMacOsSnapshotAction }));
+vi.mock('../platforms/linux/snapshot.ts', () => ({ snapshotLinux }));
 
-import { createSnapshotRuntimeHost } from './platform-runtime-snapshot-host.ts';
+import { createSnapshotRuntimeHost } from './snapshot-desktop-surface.ts';
 
 const macosDevice = {
   id: 'desktop',
@@ -35,6 +35,7 @@ test('Apple snapshot host preserves non-app macOS surface capture and menubar id
   runMacOsSnapshotAction.mockResolvedValue({
     nodes: [{ index: 0, depth: 0, type: 'MenuBar', label: 'System menu' }],
     truncated: false,
+    backend: 'macos-helper',
   });
   const signal = new AbortController().signal;
 

…c/platform-runtime-snapshot-host.test.ts …napshot/snapshot-desktop-surface.test.tssrc/platform-runtime-snapshot-host.test.ts renamed to src/snapshot/snapshot-desktop-surface.test.ts src/platform-runtime-snapshot-host.test.ts renamed to src/snapshot/snapshot-desktop-surface.test.ts

@@ -1,7 +1,57 @@
 import { attachRefs, type RawSnapshotNode } from '@agent-device/kernel/snapshot';
 import type { SnapshotOptions, SnapshotResult } from '@agent-device/contracts/interaction';
+import type { CaptureSnapshotInput, SnapshotRuntimeHost } from '@agent-device/contracts/platform';
+import type { DeviceInfo } from '@agent-device/kernel/device';
 import { findNodeByLabel } from './snapshot-node-label.ts';
 
+type SnapshotSurfaceOptions = NonNullable<CaptureSnapshotInput['options']>;
+
+export function createSnapshotRuntimeHost(): SnapshotRuntimeHost {
+  return Object.freeze({ captureSurface });
+}
+
+export async function captureLinuxSurfaceSnapshot(
+  options: CaptureSnapshotInput['options'],
+  signal?: AbortSignal,
+) {
+  const { snapshotLinux } = await import('../platforms/linux/snapshot.ts');
+  const result = await snapshotLinux(options?.surface, signal);
+  return shapeDesktopSurfaceSnapshot(
+    { nodes: result.nodes, truncated: result.truncated, backend: 'linux-atspi' },
+    options ?? {},
+  );
+}
+
+export async function captureMacOsSurfaceSnapshot(
+  options: SnapshotSurfaceOptions,
+  signal?: AbortSignal,
+) {
+  const surface = options.surface;
+  if (!surface || surface === 'app') {
+    throw new TypeError('Apple surface capture requires a non-app macOS surface');
+  }
+  const { runMacOsSnapshotAction } = await import('../platforms/apple/os/macos/helper.ts');
+  const result = await runMacOsSnapshotAction(surface, {
+    bundleId: surface === 'menubar' ? options.appBundleId : undefined,
+    signal,
+  });
+  return shapeDesktopSurfaceSnapshot(result, options);
+}
+
+const captureSurface: SnapshotRuntimeHost['captureSurface'] = async (device, options, signal) => {
+  if (device.platform === 'linux') {
+    return await captureLinuxSurfaceSnapshot(options, signal);
+  }
+  requireMacOsSurfaceDevice(device);
+  return await captureMacOsSurfaceSnapshot(options ?? {}, signal);
+};
+
+function requireMacOsSurfaceDevice(device: DeviceInfo): void {
+  if (device.platform !== 'apple' || device.appleOs !== 'macos') {
+    throw new TypeError('Apple surface capture requires a non-app macOS surface');
+  }
+}
+
 const INTERACTIVE_ROLE_TOKENS = [
   'button',
   'menu',
@@ -13,7 +63,7 @@ const INTERACTIVE_ROLE_TOKENS = [
 ] as const;
 
 /** Applies the legacy desktop-surface projection once for both runtime hosts and legacy capture. */
-export function shapeDesktopSurfaceSnapshot(
+function shapeDesktopSurfaceSnapshot(
   data: SnapshotResult,
   options: Pick<SnapshotOptions, 'depth' | 'interactiveOnly' | 'scope'>,
 ): SnapshotResult {