refactor(macos): derive macOS surface routing from one owner table

packages/contracts/src/facades/session.ts

@@ -1,4 +1,13 @@
 export type { SessionAction } from '../session-action.ts';
 export type { SessionScope } from '../session-scope.ts';
-export { SESSION_SURFACES, parseSessionSurface } from '../session-surface.ts';
-export type { SessionSurface } from '../session-surface.ts';
+export {
+  SESSION_SURFACES,
+  macOsHelperSurface,
+  macOsSurfaceBackend,
+  parseSessionSurface,
+} from '../session-surface.ts';
+export type {
+  MacOsHelperSurface,
+  MacOsSurfaceBackend,
+  SessionSurface,
+} from '../session-surface.ts';

packages/contracts/src/session-surface.test.ts

@@ -0,0 +1,23 @@
+import { expect, test } from 'vitest';
+import {
+  SESSION_SURFACES,
+  macOsHelperSurface,
+  macOsSurfaceBackend,
+  type MacOsSurfaceBackend,
+  type SessionSurface,
+} from './session-surface.ts';
+
+const EXPECTED_BACKENDS: Record<SessionSurface, MacOsSurfaceBackend> = {
+  app: 'xctest',
+  'frontmost-app': 'macos-helper',
+  desktop: 'macos-helper',
+  menubar: 'macos-helper',
+};
+
+test.each([
+  ...SESSION_SURFACES.map((surface) => [surface, EXPECTED_BACKENDS[surface]] as const),
+  [undefined, 'xctest'] as const,
+])('the macOS %s surface is served by %s', (surface, backend) => {
+  expect(macOsSurfaceBackend(surface)).toBe(backend);
+  expect(macOsHelperSurface(surface)).toBe(backend === 'macos-helper' ? surface : undefined);
+});

packages/contracts/src/session-surface.ts

@@ -1,3 +1,4 @@
+import type { SnapshotBackend } from '@agent-device/kernel/snapshot';
 import { defineStringEnum } from './string-enum.ts';
 
 export const SESSION_SURFACES = ['app', 'frontmost-app', 'desktop', 'menubar'] as const;
@@ -10,3 +11,34 @@ const SESSION_SURFACE_ENUM = defineStringEnum(SESSION_SURFACES, {
 export function parseSessionSurface(value: string | undefined): SessionSurface {
   return SESSION_SURFACE_ENUM.parse(value);
 }
+
+/** The backend that serves every operation on a macOS surface. */
+export type MacOsSurfaceBackend = Extract<SnapshotBackend, 'xctest' | 'macos-helper'>;
+
+const MACOS_SURFACE_BACKENDS = {
+  app: 'xctest',
+  'frontmost-app': 'macos-helper',
+  desktop: 'macos-helper',
+  menubar: 'macos-helper',
+} as const satisfies Record<SessionSurface, MacOsSurfaceBackend>;
+
+/** An absent surface is an app session, the reading every route already gives it. */
+export function macOsSurfaceBackend(surface: SessionSurface | undefined): MacOsSurfaceBackend {
+  return MACOS_SURFACE_BACKENDS[surface ?? 'app'];
+}
+
+type HelperRoutedSurface = {
+  [S in SessionSurface]: (typeof MACOS_SURFACE_BACKENDS)[S] extends 'macos-helper' ? S : never;
+}[SessionSurface];
+
+declare const helperSurface: unique symbol;
+/** A surface the owner routed to the macOS helper; only `macOsHelperSurface` produces one. */
+export type MacOsHelperSurface = HelperRoutedSurface & { readonly [helperSurface]: true };
+
+export function macOsHelperSurface(
+  surface: SessionSurface | undefined,
+): MacOsHelperSurface | undefined {
+  return surface !== undefined && macOsSurfaceBackend(surface) === 'macos-helper'
+    ? (surface as MacOsHelperSurface)
+    : undefined;
+}

packages/platform-apple/src/__tests__/interactor-macos-surface.test.ts

@@ -0,0 +1,181 @@
+import { beforeEach, expect, test, vi } from 'vitest';
+import type { DeviceInfo } from '@agent-device/kernel/device';
+import { SCREENSHOT_FULLSCREEN_REASONS } from '@agent-device/contracts/capture';
+import type { PressPointOptions } from '@agent-device/contracts/interactor-types';
+import {
+  SESSION_SURFACES,
+  type MacOsSurfaceBackend,
+  type SessionSurface,
+} from '@agent-device/contracts/session';
+
+vi.mock('../os/macos/helper.ts', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../os/macos/helper.ts')>();
+  return {
+    ...actual,
+    runMacOsScreenshotAction: vi.fn(async (outPath: string) => ({ path: outPath })),
+    runMacOsSnapshotAction: vi.fn(async (surface: SessionSurface) => ({
+      surface,
+      nodes: [],
+      truncated: false,
+      backend: 'macos-helper' as const,
+    })),
+    runMacOsReadTextAction: vi.fn(async () => ({ text: 'helper' })),
+    runMacOsPressAction: vi.fn(async (x: number, y: number) => ({ x, y })),
+  };
+});
+
+vi.mock('../core/screenshot.ts', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../core/screenshot.ts')>();
+  return {
+    ...actual,
+    captureScreenshotViaRunner: vi.fn(),
+    screenshotIos: vi.fn(),
+  };
+});
+
+vi.mock('../core/runner-client.ts', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../core/runner-client.ts')>();
+  return {
+    ...actual,
+    runAppleRunnerCommand: vi.fn(async () => ({})),
+  };
+});
+
+import { createAppleInteractor } from '../interactor.ts';
+import {
+  runMacOsPressAction,
+  runMacOsReadTextAction,
+  runMacOsScreenshotAction,
+  runMacOsSnapshotAction,
+} from '../os/macos/helper.ts';
+import { captureScreenshotViaRunner, screenshotIos } from '../core/screenshot.ts';
+import { runAppleRunnerCommand } from '../core/runner-client.ts';
+
+const macOsDevice: DeviceInfo = {
+  platform: 'apple',
+  appleOs: 'macos',
+  id: 'host-mac',
+  name: 'Host Mac',
+  kind: 'device',
+  target: 'desktop',
+  booted: true,
+};
+
+const MACOS_SURFACE_BACKENDS: Record<SessionSurface, MacOsSurfaceBackend> = {
+  app: 'xctest',
+  'frontmost-app': 'macos-helper',
+  desktop: 'macos-helper',
+  menubar: 'macos-helper',
+};
+
+const SURFACE_ROWS = [
+  ...SESSION_SURFACES.map((surface) => [surface, MACOS_SURFACE_BACKENDS[surface]] as const),
+  [undefined, 'xctest'] as const,
+];
+
+const HELPER_ROWS = SESSION_SURFACES.filter(
+  (surface) => MACOS_SURFACE_BACKENDS[surface] === 'macos-helper',
+);
+
+const PRIMARY_PRESS: Omit<PressPointOptions, 'surface'> = {
+  button: 'primary',
+  count: 1,
+  intervalMs: 0,
+  holdMs: 0,
+  jitterPx: 0,
+  doubleTap: false,
+};
+
+const helperEntryPoints = [
+  runMacOsScreenshotAction,
+  runMacOsSnapshotAction,
+  runMacOsReadTextAction,
+  runMacOsPressAction,
+];
+const runnerEntryPoints = [runAppleRunnerCommand, screenshotIos, captureScreenshotViaRunner];
+
+function clearEntryPoints(): void {
+  for (const entry of [...helperEntryPoints, ...runnerEntryPoints]) vi.mocked(entry).mockClear();
+}
+
+beforeEach(clearEntryPoints);
+
+function reachedBackend(): MacOsSurfaceBackend {
+  const helper = helperEntryPoints.some((entry) => vi.mocked(entry).mock.calls.length > 0);
+  const runner = runnerEntryPoints.some((entry) => vi.mocked(entry).mock.calls.length > 0);
+  expect(helper !== runner).toBe(true);
+  return helper ? 'macos-helper' : 'xctest';
+}
+
+test.each(SURFACE_ROWS)(
+  'every macOS operation on the %s surface reaches the %s backend',
+  async (surface, backend) => {
+    const interactor = createAppleInteractor(macOsDevice, {});
+    const operations: Record<string, () => Promise<unknown>> = {
+      screenshot: async () => await interactor.screenshot('/tmp/out.png', { surface }),
+      snapshot: async () => await interactor.snapshot({ surface }),
+      readTextAtPoint: async () => await interactor.readTextAtPoint?.({ x: 1, y: 2 }, { surface }),
+      pressPoint: async () =>
+        await interactor.pressPoint?.({ x: 1, y: 2 }, { ...PRIMARY_PRESS, surface }),
+    };
+    const reached: Record<string, MacOsSurfaceBackend> = {};
+    for (const [name, run] of Object.entries(operations)) {
+      clearEntryPoints();
+      await run();
+      reached[name] = reachedBackend();
+    }
+    expect(reached).toEqual({
+      screenshot: backend,
+      snapshot: backend,
+      readTextAtPoint: backend,
+      pressPoint: backend,
+    });
+  },
+);
+
+test.each(HELPER_ROWS)(
+  'refuses an explicit --fullscreen on the macOS %s surface before any capture',
+  async (surface) => {
+    const interactor = createAppleInteractor(macOsDevice, {});
+
+    await expect(
+      interactor.screenshot('/tmp/out.png', { surface, fullscreen: true }),
+    ).rejects.toMatchObject({
+      code: 'INVALID_ARGS',
+      details: expect.objectContaining({
+        reason: SCREENSHOT_FULLSCREEN_REASONS.macOsHelperSurfaceFixedFrame,
+        surface,
+      }),
+    });
+
+    expect(runMacOsScreenshotAction).not.toHaveBeenCalled();
+  },
+);
+
+test.each(HELPER_ROWS)(
+  'captures the %s surface through the helper when --fullscreen is not requested',
+  async (surface) => {
+    const interactor = createAppleInteractor(macOsDevice, {});
+
+    await interactor.screenshot('/tmp/out.png', { surface });
+
+    expect(runMacOsScreenshotAction).toHaveBeenCalledOnce();
+    const [, options] = vi.mocked(runMacOsScreenshotAction).mock.calls[0]!;
+    expect(options).toEqual({ surface });
+    expect(Object.hasOwn(options ?? {}, 'fullscreen')).toBe(false);
+  },
+);
+
+test('keeps a macOS app session on the runner path with --fullscreen unchanged', async () => {
+  const interactor = createAppleInteractor(macOsDevice, {});
+
+  await interactor.screenshot('/tmp/out.png', { surface: 'app', fullscreen: true });
+
+  expect(runMacOsScreenshotAction).not.toHaveBeenCalled();
+  expect(screenshotIos).toHaveBeenCalledOnce();
+  expect(screenshotIos).toHaveBeenCalledWith(
+    macOsDevice,
+    '/tmp/out.png',
+    expect.objectContaining({ fullscreen: true }),
+  );
+});

packages/platform-apple/src/interactions.ts

@@ -10,6 +10,7 @@ import {
   type TextEntryRoute,
   type TypeTextBackendResult,
 } from '@agent-device/contracts/interactor-types';
+import { macOsHelperSurface, type MacOsHelperSurface } from '@agent-device/contracts/session';
 import {
   SCROLL_DURATION_MAX_MS,
   normalizeScrollDurationMs,
@@ -194,8 +195,9 @@ async function runApplePressPoint(
   point: { x: number; y: number },
   options: PressPointOptions,
 ): Promise<Record<string, unknown>> {
-  if (isMacOs(device) && options.surface && options.surface !== 'app') {
-    return await runMacOsSurfacePress(context, point, options);
+  const helper = isMacOs(device) ? macOsHelperSurface(options.surface) : undefined;
+  if (helper) {
+    return await runMacOsSurfacePress(context, point, options, helper);
   }
   if (options.button !== 'primary') {
     return await runAppleAlternateClick(device, context, runnerOpts, point, options.button);
@@ -216,19 +218,20 @@ async function runMacOsSurfacePress(
   context: RunnerContext,
   point: { x: number; y: number },
   options: PressPointOptions,
+  surface: MacOsHelperSurface,
 ): Promise<Record<string, unknown>> {
   if (options.button !== 'primary') {
     throw new AppError(
       'UNSUPPORTED_OPERATION',
-      `${options.button} click is not supported on macOS ${options.surface} sessions.`,
+      `${options.button} click is not supported on macOS ${surface} sessions.`,
     );
   }
   const { runMacOsPressAction } = await import('./os/macos/helper.ts');
   // `count` is independent presses and `doubleTap` raises the click state inside each one,
   // the same reading every other platform gives the two flags.
   const posted = await runMacOsPressAction(point.x, point.y, {
     bundleId: context.appBundleId,
-    surface: options.surface,
+    surface,
     holdMs: options.holdMs,
     clicks: options.count,
     doubleClick: options.doubleTap,