fix(ios): centralize WebDriver snapshot evidence

Author: thymikee

packages/capture-kit/src/ios-snapshot-engine/errors.test.ts

@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { toIosSnapshotEngineErrorDetails } from './errors.ts';
+import { IosSnapshotEngineError } from './types.ts';
+
+test('engine error details expose only the public reason and field', () => {
+  const error = new IosSnapshotEngineError('invalid-viewport', 'invalid viewport', {
+    field: 'viewport',
+    index: 4,
+    frame: { x: 0, y: 0, width: 10, height: 10 },
+  });
+
+  assert.deepEqual(toIosSnapshotEngineErrorDetails(error), {
+    reason: 'invalid-viewport',
+    field: 'viewport',
+  });
+});

packages/capture-kit/src/ios-snapshot-engine/errors.ts

@@ -0,0 +1,15 @@
+import type { IosSnapshotEngineError, IosSnapshotEngineFailureReason } from './types.ts';
+
+export type IosSnapshotEnginePublicErrorDetails = Readonly<{
+  reason: IosSnapshotEngineFailureReason;
+  field?: string;
+}>;
+
+export function toIosSnapshotEngineErrorDetails(
+  error: IosSnapshotEngineError,
+): IosSnapshotEnginePublicErrorDetails {
+  return {
+    reason: error.reason,
+    ...(error.details.field ? { field: error.details.field } : {}),
+  };
+}

packages/capture-kit/src/ios-snapshot-engine/index.ts

@@ -12,4 +12,6 @@ export {
 export { collectIosStructuralIdentifierSuppression } from './noise-structural.ts';
 export { findNearestScrollableContainer, mergeReplacement, updateReplacement } from './tree.ts';
 export { IosSnapshotEngineError } from './types.ts';
+export { toIosSnapshotEngineErrorDetails } from './errors.ts';
+export { resolveIosViewportEvidenceFromRoots } from './viewport.ts';
 export type { SnapshotTreeRuleContext } from './tree.ts';

packages/capture-kit/src/ios-snapshot-engine/viewport.test.ts

@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { resolveIosViewportEvidenceFromRoots } from './viewport.ts';
+
+test('viewport evidence prefers reported application and window roots', () => {
+  assert.deepEqual(
+    resolveIosViewportEvidenceFromRoots([
+      { type: 'XCUIElementTypeApplication', rectStatus: 'invalid' },
+      {
+        type: 'XCUIElementTypeWindow',
+        rect: { x: 0, y: 0, width: 390, height: 844 },
+        rectStatus: 'reported',
+      },
+    ]),
+    { kind: 'reported', rect: { x: 0, y: 0, width: 390, height: 844 } },
+  );
+});
+
+test('viewport evidence can fall back to the largest top-level root', () => {
+  assert.deepEqual(
+    resolveIosViewportEvidenceFromRoots(
+      [
+        { type: 'Other', rect: { x: 0, y: 0, width: 100, height: 100 } },
+        { type: 'Other', rect: { x: 0, y: 0, width: 200, height: 300 } },
+      ],
+      { fallbackToLargestRoot: true },
+    ),
+    { kind: 'reported', rect: { x: 0, y: 0, width: 200, height: 300 } },
+  );
+});
+
+test('viewport evidence preserves explicit missing geometry reasons', () => {
+  assert.deepEqual(
+    resolveIosViewportEvidenceFromRoots([{ type: 'Application', rectStatus: 'invalid' }]),
+    { kind: 'missing', reason: 'invalid' },
+  );
+  assert.deepEqual(
+    resolveIosViewportEvidenceFromRoots([{ type: 'Application', rectStatus: 'not-provided' }]),
+    { kind: 'missing', reason: 'not-provided' },
+  );
+});

packages/capture-kit/src/ios-snapshot-engine/viewport.ts

@@ -0,0 +1,50 @@
+import type { IosViewportEvidence } from '@agent-device/contracts/ios-snapshot';
+import { normalizeType } from '@agent-device/contracts/snapshot';
+import type { Rect } from '@agent-device/kernel/snapshot';
+import { isPositiveFiniteRect } from '@agent-device/kernel/rect';
+
+export type IosSnapshotViewportRoot = Readonly<{
+  type?: string;
+  rect?: Rect;
+  rectStatus?: 'reported' | 'invalid' | 'not-provided';
+}>;
+
+export function resolveIosViewportEvidenceFromRoots(
+  roots: readonly IosSnapshotViewportRoot[],
+  options: Readonly<{ fallbackToLargestRoot?: boolean }> = {},
+): IosViewportEvidence | undefined {
+  const viewportRoots = roots.filter(isViewportRoot);
+  const candidates =
+    viewportRoots.length > 0 || options.fallbackToLargestRoot !== true ? viewportRoots : roots;
+  const root = [...candidates].sort(compareViewportRoots)[0];
+  if (!root) return undefined;
+  if (isPositiveFiniteRect(root.rect)) return { kind: 'reported', rect: root.rect };
+  return {
+    kind: 'missing',
+    reason:
+      root.rectStatus === 'invalid' || (root.rectStatus === undefined && root.rect !== undefined)
+        ? 'invalid'
+        : 'not-provided',
+  };
+}
+
+function isViewportRoot(root: IosSnapshotViewportRoot): boolean {
+  const type = normalizeType(root.type ?? '');
+  return type === 'application' || type === 'window';
+}
+
+function compareViewportRoots(
+  left: IosSnapshotViewportRoot,
+  right: IosSnapshotViewportRoot,
+): number {
+  const status = rootGeometryRank(right.rectStatus) - rootGeometryRank(left.rectStatus);
+  return status || rectArea(right.rect) - rectArea(left.rect);
+}
+
+function rootGeometryRank(status: IosSnapshotViewportRoot['rectStatus']): number {
+  return status === 'reported' ? 2 : status === 'invalid' ? 1 : 0;
+}
+
+function rectArea(rect: Rect | undefined): number {
+  return rect && isPositiveFiniteRect(rect) ? rect.width * rect.height : 0;
+}

packages/capture-kit/src/ios-snapshot-planning.test.ts

@@ -147,6 +147,10 @@ test('presented producers cannot claim acquisition narrowing', () => {
   });
 });
 
+test('Appium source advertises viewport evidence when its root reports geometry', () => {
+  assert.equal(IOS_SNAPSHOT_PRODUCER_CAPABILITIES['appium-source'].viewportEvidence, 'available');
+});
+
 test('comparison identity rejects every identity axis and residue mismatch', () => {
   const base = comparisonIdentity();
   const mismatches: IosSnapshotComparisonIdentity[] = [

packages/capture-kit/src/ios-snapshot-planning.ts

@@ -46,7 +46,7 @@ const IOS_SNAPSHOT_PRODUCER_CAPABILITY_VALUES = {
     },
     scopeCompleteness: 'incomplete',
     interactiveQueryCompleteness: 'incomplete',
-    viewportEvidence: 'unavailable',
+    viewportEvidence: 'available',
     hittabilityEvidence: 'unavailable',
   },
   'limrun-ios-tree': {

packages/contracts/src/snapshot-private-evidence.ts

@@ -28,6 +28,7 @@ export type SnapshotOcclusionContextEvidence = {
   androidSiblingOrderByNodeIndex?: ReadonlyMap<number, AndroidSiblingOrderEvidence>;
 };
 
+/** Identifies the engine that owns interactive iOS snapshot presentation. */
 export type SnapshotPresentationEvidence = {
   owner: 'ios-snapshot-engine';
 };

packages/platform-apple/src/__tests__/interactor-runner-provider.test.ts

@@ -275,13 +275,12 @@ test('snapshot reports typed runner presentation failures', async () => {
     { runCommand: async () => ({ nodes: [{ index: 0, type: 'Application' }] }) },
   );
 
-  await assert.rejects(
-    interactor.snapshot(),
-    (error: unknown) =>
-      error instanceof AppError &&
-      error.code === 'COMMAND_FAILED' &&
-      error.details?.reason === 'missing-viewport',
-  );
+  await assert.rejects(interactor.snapshot(), (error: unknown) => {
+    assert.ok(error instanceof AppError);
+    assert.equal(error.code, 'COMMAND_FAILED');
+    assert.deepEqual(error.details, { reason: 'missing-viewport', field: 'viewport' });
+    return true;
+  });
 });
 
 test('sparse runner payloads with no viewport fail before publishing actionable nodes', async () => {

packages/platform-apple/src/runner/snapshot-presentation.ts

@@ -4,17 +4,17 @@ import type {
   IosViewportEvidence,
 } from '@agent-device/contracts/ios-snapshot';
 import type { SnapshotOptions } from '@agent-device/contracts/interactor-types';
-import { normalizeType } from '@agent-device/contracts/snapshot';
 import {
   IosSnapshotEngineError,
   presentIosRunnerSnapshot,
+  resolveIosViewportEvidenceFromRoots,
+  toIosSnapshotEngineErrorDetails,
 } from '@agent-device/capture-kit/ios-snapshot-engine';
 import { readSnapshotQualityVerdict } from '@agent-device/capture-kit/snapshot-quality-verdict';
 import {
   createIosSnapshotRequest,
   buildIosSnapshotPresentationKey,
 } from '@agent-device/capture-kit/ios-snapshot-planning';
-import { isPositiveFiniteRect } from '@agent-device/kernel/rect';
 import { AppError } from '@agent-device/kernel/errors';
 import type { RawSnapshotNode, SnapshotQualityVerdict } from '@agent-device/kernel/snapshot';
 
@@ -119,36 +119,18 @@ function runnerViewportEvidence(
   qualityNodes: readonly RawSnapshotNode[] | undefined,
 ): IosViewportEvidence {
   return (
-    readReportedViewport(qualityNodes) ??
-    readReportedViewport(nodes) ?? { kind: 'missing', reason: 'not-provided' }
+    resolveIosViewportEvidenceFromRoots(rootNodes(qualityNodes), {
+      fallbackToLargestRoot: true,
+    }) ??
+    resolveIosViewportEvidenceFromRoots(rootNodes(nodes), { fallbackToLargestRoot: true }) ?? {
+      kind: 'missing',
+      reason: 'not-provided',
+    }
   );
 }
 
-function readReportedViewport(
-  nodes: readonly RawSnapshotNode[] | undefined,
-): IosViewportEvidence | undefined {
-  const roots = nodes?.filter((node) => node.parentIndex === undefined) ?? [];
-  const root =
-    [...roots]
-      .filter((node) => isViewportRoot(node))
-      .sort(compareRectArea)
-      .at(0) ?? [...roots].sort(compareRectArea).at(0);
-  if (!root) return undefined;
-  if (isPositiveFiniteRect(root.rect)) return { kind: 'reported', rect: root.rect };
-  return { kind: 'missing', reason: root.rect ? 'invalid' : 'not-provided' };
-}
-
-function isViewportRoot(node: RawSnapshotNode): boolean {
-  const type = normalizeType(node.type ?? '');
-  return type === 'application' || type === 'window';
-}
-
-function compareRectArea(left: RawSnapshotNode, right: RawSnapshotNode): number {
-  return rectArea(right.rect) - rectArea(left.rect);
-}
-
-function rectArea(rect: RawSnapshotNode['rect']): number {
-  return rect ? rect.width * rect.height : 0;
+function rootNodes(nodes: readonly RawSnapshotNode[] | undefined): readonly RawSnapshotNode[] {
+  return nodes?.filter((node) => node.parentIndex === undefined) ?? [];
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -160,7 +142,7 @@ function throwSnapshotEngineError(error: unknown): never {
   throw new AppError(
     'COMMAND_FAILED',
     error.message,
-    { reason: error.reason, iosSnapshotEngine: { details: error.details } },
+    toIosSnapshotEngineErrorDetails(error),
     error,
   );
 }