refactor(platforms): break the four upward edges out of src/platforms

packages/capture-kit/package.json

@@ -46,6 +46,10 @@
       "types": "./src/screenshot-diff-pixels.ts",
       "default": "./src/screenshot-diff-pixels.ts"
     },
+    "./snapshot-desktop-projection": {
+      "types": "./src/snapshot-desktop-projection.ts",
+      "default": "./src/snapshot-desktop-projection.ts"
+    },
     "./snapshot-occlusion": {
       "types": "./src/snapshot-occlusion.ts",
       "default": "./src/snapshot-occlusion.ts"

packages/capture-kit/src/snapshot-desktop-projection.test.ts

@@ -0,0 +1,42 @@
+import { expect, test } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import { scopeSnapshotNodes } from './snapshot-desktop-projection.ts';
+
+test('scopeSnapshotNodes agrees with every golden scope-policy table case', () => {
+  const cases = JSON.parse(
+    fs.readFileSync(
+      path.resolve(import.meta.dirname, '../../../contracts/fixtures/snapshot-scope-policy.json'),
+      'utf8',
+    ),
+  ) as Array<{
+    name: string;
+    scope: string;
+    nodes: Array<{
+      depth: number;
+      label?: string;
+      value?: string;
+      identifier?: string;
+      presented?: boolean;
+    }>;
+    expectedSubtreeIndexes: number[];
+  }>;
+  expect(cases.length).toBeGreaterThan(0);
+  for (const fixture of cases) {
+    const parents: number[] = [];
+    const nodes = fixture.nodes.map((node, index) => {
+      parents.length = node.depth;
+      const parentIndex = node.depth > 0 ? parents[node.depth - 1] : undefined;
+      parents[node.depth] = index;
+      return { ...node, index, parentIndex, rect: { x: index, y: 0, width: 1, height: 1 } };
+    });
+    const scoped = scopeSnapshotNodes(nodes, fixture.scope, (range) =>
+      nodes.slice(range.start, range.end).some((node) => node.presented !== false),
+    );
+    expect(
+      scoped.map((node) => node.rect?.x),
+      fixture.name,
+    ).toEqual(fixture.expectedSubtreeIndexes);
+    if (scoped.length > 0) expect(scoped[0]?.depth, fixture.name).toBe(0);
+  }
+});

packages/capture-kit/src/snapshot-desktop-projection.ts

@@ -0,0 +1,75 @@
+import type { RawSnapshotNode } from '@agent-device/kernel/snapshot';
+import type { SnapshotOptions, SnapshotResult } from '@agent-device/contracts/interactor-types';
+import {
+  findSnapshotScopeRange,
+  normalizeSnapshotScope,
+  reindexSnapshotNodes,
+} from '@agent-device/contracts/snapshot-scope';
+
+const INTERACTIVE_ROLE_TOKENS = [
+  'button',
+  'menu',
+  'textfield',
+  'searchfield',
+  'checkbox',
+  'radio',
+  'switch',
+] as const;
+
+export function shapeDesktopSurfaceSnapshot(
+  data: SnapshotResult,
+  options: Pick<SnapshotOptions, 'depth' | 'interactiveOnly' | 'scope'>,
+): SnapshotResult {
+  let nodes = data.nodes ?? [];
+  if (options.scope) {
+    nodes = scopeSnapshotNodes(nodes, options.scope, (range) =>
+      options.interactiveOnly
+        ? nodes.slice(range.start, range.end).some(isInteractiveSnapshotNode)
+        : true,
+    );
+  }
+  if (options.interactiveOnly) nodes = filterInteractiveSnapshotNodes(nodes);
+  if (typeof options.depth === 'number') nodes = filterSnapshotNodesByDepth(nodes, options.depth);
+  return { ...data, nodes };
+}
+
+export function scopeSnapshotNodes(
+  nodes: RawSnapshotNode[],
+  scope: string,
+  subtreeContributes?: (range: { start: number; end: number }) => boolean,
+): RawSnapshotNode[] {
+  const normalizedScope = normalizeSnapshotScope(scope);
+  if (!normalizedScope) return reindexSnapshotNodes(nodes);
+  const range = findSnapshotScopeRange(nodes, normalizedScope, subtreeContributes);
+  if (!range) return [];
+  const slice = nodes.slice(range.start, range.end);
+  return reindexSnapshotNodes(slice, slice[0]?.depth ?? 0);
+}
+
+function filterInteractiveSnapshotNodes(nodes: RawSnapshotNode[]): RawSnapshotNode[] {
+  if (nodes.length === 0) return nodes;
+  const byIndex = new Map(nodes.map((node) => [node.index, node]));
+  const keepIndexes = new Set<number>();
+  for (const node of nodes) {
+    if (!isInteractiveSnapshotNode(node)) continue;
+    let current: RawSnapshotNode | undefined = node;
+    while (current) {
+      if (keepIndexes.has(current.index)) break;
+      keepIndexes.add(current.index);
+      current =
+        typeof current.parentIndex === 'number' ? byIndex.get(current.parentIndex) : undefined;
+    }
+  }
+  if (keepIndexes.size === 0) return nodes;
+  return reindexSnapshotNodes(nodes.filter((node) => keepIndexes.has(node.index)));
+}
+
+function filterSnapshotNodesByDepth(nodes: RawSnapshotNode[], maxDepth: number): RawSnapshotNode[] {
+  return reindexSnapshotNodes(nodes.filter((node) => (node.depth ?? 0) <= maxDepth));
+}
+
+function isInteractiveSnapshotNode(node: RawSnapshotNode): boolean {
+  if ([node.focused, node.hittable, node.rect].some(Boolean)) return true;
+  const role = `${node.type ?? ''} ${node.role ?? ''} ${node.subrole ?? ''}`.toLowerCase();
+  return INTERACTIVE_ROLE_TOKENS.some((token) => role.includes(token));
+}

packages/contracts/package.json

@@ -127,6 +127,10 @@
       "types": "./src/back-runtime.ts",
       "default": "./src/back-runtime.ts"
     },
+    "./backend-diagnostics": {
+      "types": "./src/backend-diagnostics.ts",
+      "default": "./src/backend-diagnostics.ts"
+    },
     "./boot-failure": {
       "types": "./src/boot-failure.ts",
       "default": "./src/boot-failure.ts"
@@ -423,6 +427,10 @@
       "types": "./src/snapshot-runtime.ts",
       "default": "./src/snapshot-runtime.ts"
     },
+    "./snapshot-scope": {
+      "types": "./src/snapshot-scope.ts",
+      "default": "./src/snapshot-scope.ts"
+    },
     "./snapshot-timeout-evidence": {
       "types": "./src/snapshot-timeout-evidence.ts",
       "default": "./src/snapshot-timeout-evidence.ts"

packages/contracts/src/backend-diagnostics.ts

@@ -0,0 +1,39 @@
+import type { NetworkIncludeMode } from '@agent-device/kernel/contracts';
+
+export type BackendDiagnosticsTimeWindow = {
+  since?: string;
+  until?: string;
+};
+
+export type BackendDiagnosticsPageOptions = BackendDiagnosticsTimeWindow & {
+  cursor?: string;
+  limit?: number;
+};
+
+export type BackendNetworkIncludeMode = NetworkIncludeMode;
+
+export type BackendNetworkEntry = {
+  timestamp?: string;
+  method?: string;
+  url?: string;
+  status?: number;
+  durationMs?: number;
+  requestHeaders?: Record<string, string>;
+  responseHeaders?: Record<string, string>;
+  requestBody?: string;
+  responseBody?: string;
+  metadata?: Record<string, unknown>;
+};
+
+export type BackendDumpNetworkOptions = BackendDiagnosticsPageOptions & {
+  include?: BackendNetworkIncludeMode;
+};
+
+export type BackendDumpNetworkResult = {
+  entries: readonly BackendNetworkEntry[];
+  nextCursor?: string;
+  timeWindow?: BackendDiagnosticsTimeWindow;
+  backend?: string;
+  redacted?: boolean;
+  notes?: readonly string[];
+};

packages/platform-android/src/app-state.ts

@@ -28,6 +28,34 @@ const ANDROID_FOCUS_MARKERS = [
   'ResumedActivity:',
 ] as const;
 
+export type AndroidCommandExecutor = (
+  args: string[],
+  options: { allowFailure: boolean },
+) => Promise<{ exitCode: number; stdout?: string; stderr?: string }>;
+
+export async function readAndroidAppStateWithExecutor(
+  run: AndroidCommandExecutor,
+): Promise<AppStateRuntimeResult> {
+  const windowFocus = await readAndroidFocusWithExecutor(run, FOCUS_COMMANDS);
+  if (windowFocus) return windowFocus;
+
+  const activityFocus = await readAndroidFocusWithExecutor(run, ACTIVITY_COMMANDS);
+  if (activityFocus) return activityFocus;
+  return {};
+}
+
+async function readAndroidFocusWithExecutor(
+  run: AndroidCommandExecutor,
+  commands: readonly (readonly string[])[],
+): Promise<AppStateRuntimeResult | null> {
+  for (const args of commands) {
+    const result = await run([...args], { allowFailure: true });
+    const parsed = parseAndroidForegroundApp(result.stdout ?? '');
+    if (parsed) return parsed;
+  }
+  return null;
+}
+
 export async function readAndroidAppState(
   host: AndroidAppStateHost,
   device: DeviceInfo,

packages/platform-android/src/index.ts

@@ -55,11 +55,11 @@ export async function readAndroidAppState(
   return await read(host, device, signal);
 }
 
-export async function parseAndroidForegroundApp(
-  text: string,
-): Promise<Readonly<{ package?: string; activity?: string }> | null> {
-  const { parseAndroidForegroundApp: parse } = await import('./app-state.ts');
-  return parse(text);
+export async function readAndroidAppStateWithExecutor(
+  run: import('./app-state.ts').AndroidCommandExecutor,
+): Promise<import('@agent-device/contracts/app-state-runtime').AppStateRuntimeResult> {
+  const { readAndroidAppStateWithExecutor: read } = await import('./app-state.ts');
+  return await read(run);
 }
 
 export const runtimeModule = Object.freeze({

scripts/layering/package-boundaries.test.ts

@@ -75,6 +75,7 @@ const CONTRACT_EXPORTS = [
   '@agent-device/contracts/audio-probe-support',
   '@agent-device/contracts/audio-runtime-plan',
   '@agent-device/contracts/back-mode',
+  '@agent-device/contracts/backend-diagnostics',
   '@agent-device/contracts/back-runtime',
   '@agent-device/contracts/boot-failure',
   '@agent-device/contracts/capture',
@@ -150,6 +151,7 @@ const CONTRACT_EXPORTS = [
   '@agent-device/contracts/snapshot',
   '@agent-device/contracts/snapshot-presentation',
   '@agent-device/contracts/snapshot-runtime',
+  '@agent-device/contracts/snapshot-scope',
   '@agent-device/contracts/snapshot-timeout-evidence',
   '@agent-device/contracts/startup-recovery-fence',
   '@agent-device/contracts/touch-runtime',
@@ -463,6 +465,7 @@ test('the real tree parses, declares, and passes R11', () => {
     '@agent-device/capture-kit/png-worker-client',
     '@agent-device/capture-kit/screenshot-density',
     '@agent-device/capture-kit/screenshot-diff-pixels',
+    '@agent-device/capture-kit/snapshot-desktop-projection',
     '@agent-device/capture-kit/snapshot-occlusion',
     '@agent-device/capture-kit/snapshot-quality-backend-capabilities',
     '@agent-device/capture-kit/snapshot-quality-verdict',

src/__tests__/eager-closure-budgets.ts

@@ -130,6 +130,7 @@ export const FACADE_BUDGETS: Readonly<Record<string, number>> = Object.freeze({
   'packages/capture-kit/src/screenshot-density.ts': 6,
   'packages/capture-kit/src/screenshot-diff-pixels.ts': 1,
   'packages/capture-kit/src/mobile-snapshot-semantics.ts': 10,
+  'packages/capture-kit/src/snapshot-desktop-projection.ts': 2,
   'packages/capture-kit/src/snapshot-occlusion.ts': 10,
   'packages/capture-kit/src/snapshot-quality-backend-capabilities.ts': 1,
   'packages/capture-kit/src/snapshot-quality-verdict.ts': 2,
@@ -172,6 +173,7 @@ export const FACADE_BUDGETS: Readonly<Record<string, number>> = Object.freeze({
   'packages/contracts/src/audio-probe-support.ts': 5,
   'packages/contracts/src/audio-runtime-plan.ts': 5,
   'packages/contracts/src/back-mode.ts': 1,
+  'packages/contracts/src/backend-diagnostics.ts': 1,
   'packages/contracts/src/boot-failure.ts': 1,
   'packages/contracts/src/click-button.ts': 3,
   'packages/contracts/src/clipboard.ts': 1,
@@ -239,6 +241,7 @@ export const FACADE_BUDGETS: Readonly<Record<string, number>> = Object.freeze({
   'packages/contracts/src/settings.ts': 3,
   'packages/contracts/src/snapshot-presentation.ts': 2,
   'packages/contracts/src/snapshot-runtime.ts': 3,
+  'packages/contracts/src/snapshot-scope.ts': 1,
   'packages/contracts/src/snapshot-timeout-evidence.ts': 1,
   'packages/contracts/src/startup-recovery-fence.ts': 1,
   'packages/contracts/src/tv-remote.ts': 3,

src/backend.ts

@@ -15,7 +15,6 @@ import type { ResolvedScrollExecutionOptions } from '@agent-device/contracts/scr
 import type { TvRemoteButton } from '@agent-device/contracts/tv-remote';
 import type { RecordingExportQuality } from '@agent-device/contracts/recording';
 import type { SessionSurface } from '@agent-device/contracts/session';
-import type { NetworkIncludeMode } from '@agent-device/kernel/contracts';
 import type {
   DeviceTarget,
   Platform,
@@ -307,14 +306,22 @@ export type BackendTraceResult = Record<string, unknown> & {
   outPath?: string;
 };
 
-export type BackendDiagnosticsTimeWindow = {
-  since?: string;
-  until?: string;
-};
-
-export type BackendDiagnosticsPageOptions = BackendDiagnosticsTimeWindow & {
-  cursor?: string;
-  limit?: number;
+import type {
+  BackendDiagnosticsPageOptions,
+  BackendDiagnosticsTimeWindow,
+  BackendDumpNetworkOptions,
+  BackendDumpNetworkResult,
+  BackendNetworkEntry,
+  BackendNetworkIncludeMode,
+} from '@agent-device/contracts/backend-diagnostics';
+
+export type {
+  BackendDiagnosticsPageOptions,
+  BackendDiagnosticsTimeWindow,
+  BackendDumpNetworkOptions,
+  BackendDumpNetworkResult,
+  BackendNetworkEntry,
+  BackendNetworkIncludeMode,
 };
 
 export type BackendLogEntry = {
@@ -340,34 +347,6 @@ export type BackendReadLogsResult = {
   notes?: readonly string[];
 };
 
-export type BackendNetworkIncludeMode = NetworkIncludeMode;
-
-export type BackendNetworkEntry = {
-  timestamp?: string;
-  method?: string;
-  url?: string;
-  status?: number;
-  durationMs?: number;
-  requestHeaders?: Record<string, string>;
-  responseHeaders?: Record<string, string>;
-  requestBody?: string;
-  responseBody?: string;
-  metadata?: Record<string, unknown>;
-};
-
-export type BackendDumpNetworkOptions = BackendDiagnosticsPageOptions & {
-  include?: BackendNetworkIncludeMode;
-};
-
-export type BackendDumpNetworkResult = {
-  entries: readonly BackendNetworkEntry[];
-  nextCursor?: string;
-  timeWindow?: BackendDiagnosticsTimeWindow;
-  backend?: string;
-  redacted?: boolean;
-  notes?: readonly string[];
-};
-
 export type BackendPerfMetric = {
   name: string;
   value?: number;

src/core/interactors/linux.ts

@@ -21,7 +21,7 @@ import {
 } from '../../platforms/linux/input-actions.ts';
 import { singlePointerPlanEndpoints } from '@agent-device/contracts/gesture-plan';
 import { screenshotLinux } from '../../platforms/linux/screenshot.ts';
-import { captureLinuxSurfaceSnapshot } from '../../snapshot/snapshot-desktop-surface.ts';
+import { captureLinuxSurfaceSnapshot } from '../../platforms/linux/surface-snapshot.ts';
 import type { Interactor } from '@agent-device/contracts/interactor-types';
 
 function unsupportedLinuxAlert(): Promise<never> {

src/core/snapshot-state.ts

@@ -19,7 +19,7 @@ import {
   annotateSnapshotNodesCoveredByPolicy,
 } from '@agent-device/capture-kit/snapshot-occlusion';
 import { coveredAndroidReplacementNodeIndexes } from '../snapshot/android-replacement-surface-occlusion.ts';
-import { scopeSnapshotNodes } from '../snapshot/snapshot-desktop-surface.ts';
+import { scopeSnapshotNodes } from '@agent-device/capture-kit/snapshot-desktop-projection';
 import { normalizeSnapshotTree, pruneGroupNodes } from '../core/snapshot-tree-ingestion.ts';
 import { presentIosInteractiveSnapshot } from '../snapshot/snapshot-presentation/ios/index.ts';