refactor(ios): centralize provider snapshot presentation

Author: thymikee

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

@@ -5,6 +5,7 @@ export {
   publishIosSnapshot,
   resolveIosViewportEvidenceFromRoots,
 } from './engine.ts';
+export type { IosSnapshotViewportRoot } from './engine.ts';
 export { presentIosRunnerSnapshot } from './runner-presentation.ts';
 export {
   buildIosInteractiveSnapshotPresentation,

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

@@ -145,6 +145,7 @@ test('presented producers cannot claim acquisition narrowing', () => {
     interactiveQuery: 'complete',
     viewport: 'available',
     hittability: 'available',
+    truncation: 'available',
   });
 });
 
@@ -162,10 +163,25 @@ test('capability residue derives unavailable Appium facts from the registry', ()
     [
       { kind: 'unavailable-fact', fact: 'hittability' },
       { kind: 'unavailable-fact', fact: 'acquisition-depth' },
+      { kind: 'unavailable-fact', fact: 'truncation' },
     ],
   );
 });
 
+test('capability residue reports truncation independently from acquisition depth', () => {
+  const producer = acquiredProducer({
+    acquisitionDepth: {
+      rawTraversal: { kind: 'complete' },
+      regularPresented: { kind: 'complete' },
+    },
+    truncationEvidence: 'unavailable',
+  });
+
+  assert.deepEqual(deriveIosSnapshotCapabilityResidue(producer), [
+    { kind: 'unavailable-fact', fact: 'truncation' },
+  ]);
+});
+
 test('comparison identity rejects every identity axis and residue mismatch', () => {
   const base = comparisonIdentity();
   const mismatches: IosSnapshotComparisonIdentity[] = [
@@ -242,6 +258,7 @@ function acquiredProducer(
     interactiveQueryCompleteness: 'incomplete',
     viewportEvidence: 'available',
     hittabilityEvidence: 'available',
+    truncationEvidence: 'available',
     presentationOwner: 'snapshot-state',
     ...overrides,
   };

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

@@ -10,6 +10,7 @@ import type {
   IosSnapshotProducerCapabilities,
   IosSnapshotRequest,
   IosSnapshotRequestInput,
+  IosViewportEvidence,
 } from '@agent-device/contracts/ios-snapshot';
 
 const IOS_SNAPSHOT_PRODUCER_CAPABILITY_VALUES = {
@@ -24,6 +25,7 @@ const IOS_SNAPSHOT_PRODUCER_CAPABILITY_VALUES = {
     interactiveQueryCompleteness: 'complete',
     viewportEvidence: 'available',
     hittabilityEvidence: 'available',
+    truncationEvidence: 'available',
     presentationOwner: 'ios-snapshot-engine',
   },
   'simulator-ax-bridge': {
@@ -37,6 +39,7 @@ const IOS_SNAPSHOT_PRODUCER_CAPABILITY_VALUES = {
     interactiveQueryCompleteness: 'incomplete',
     viewportEvidence: 'available',
     hittabilityEvidence: 'available',
+    truncationEvidence: 'available',
     presentationOwner: 'snapshot-state',
   },
   'appium-source': {
@@ -50,6 +53,7 @@ const IOS_SNAPSHOT_PRODUCER_CAPABILITY_VALUES = {
     interactiveQueryCompleteness: 'incomplete',
     viewportEvidence: 'available',
     hittabilityEvidence: 'unavailable',
+    truncationEvidence: 'unavailable',
     presentationOwner: 'ios-snapshot-engine',
   },
   'limrun-ios-tree': {
@@ -63,6 +67,7 @@ const IOS_SNAPSHOT_PRODUCER_CAPABILITY_VALUES = {
     interactiveQueryCompleteness: 'incomplete',
     viewportEvidence: 'available',
     hittabilityEvidence: 'unavailable',
+    truncationEvidence: 'unavailable',
     presentationOwner: 'ios-snapshot-engine',
   },
 } as const satisfies Record<IosSnapshotProducer, IosSnapshotProducerCapabilities>;
@@ -85,9 +90,24 @@ export function deriveIosSnapshotCapabilityResidue(
   ) {
     residue.push({ kind: 'unavailable-fact', fact: 'acquisition-depth' });
   }
+  if (producer.truncationEvidence === 'unavailable') {
+    residue.push({ kind: 'unavailable-fact', fact: 'truncation' });
+  }
   return Object.freeze(residue);
 }
 
+export function deriveIosSnapshotAcquisitionResidue(
+  producer: IosSnapshotProducerCapabilities,
+  viewport: IosViewportEvidence,
+): readonly IosAcquisitionResidue[] {
+  return Object.freeze([
+    ...deriveIosSnapshotCapabilityResidue(producer),
+    ...(viewport.kind === 'missing'
+      ? [{ kind: 'missing-viewport' as const, reason: viewport.reason }]
+      : []),
+  ]);
+}
+
 export function createIosSnapshotRequest(input: IosSnapshotRequestInput = {}): IosSnapshotRequest {
   return Object.freeze({
     projection: input.projection ?? (input.raw === true ? 'raw' : 'regular'),
@@ -149,6 +169,7 @@ export function planIosSnapshot(
       interactiveQuery: producer.interactiveQueryCompleteness,
       viewport: producer.viewportEvidence,
       hittability: producer.hittabilityEvidence,
+      truncation: producer.truncationEvidence,
     }),
   });
 }

packages/contracts/src/interactor-types.ts

@@ -8,6 +8,10 @@ import type { SettingOptions } from './settings.ts';
 import type { SessionSurface } from './session-surface.ts';
 import type { BackendSnapshotResult } from './snapshot-types.ts';
 import type { RunnerLogicalLeaseContext } from './runner-lease-context.ts';
+import type {
+  IosProviderAcquisitionProducer,
+  IosSnapshotAcquisitionFacts,
+} from './ios-snapshot.ts';
 import type {
   RawSnapshotNode,
   Point,
@@ -249,6 +253,13 @@ export type SnapshotResult = Omit<BackendSnapshotResult, 'backend' | 'nodes'> &
   nodes?: RawSnapshotNode[];
 } & SnapshotProvenance;
 
+export type SnapshotRuntimeAcquiredResult = Readonly<{
+  stage: 'acquired';
+  acquisition: IosSnapshotAcquisitionFacts & Readonly<{ producer: IosProviderAcquisitionProducer }>;
+}>;
+
+export type SnapshotRuntimeResult = SnapshotResult | SnapshotRuntimeAcquiredResult;
+
 export type Interactor = {
   open(
     app: string,
@@ -305,7 +316,7 @@ export type Interactor = {
   ): Promise<Record<string, unknown> | void>;
   screenshot(outPath: string, options?: ScreenshotOptions): Promise<void>;
   setViewport?(width: number, height: number): Promise<Record<string, unknown> | void>;
-  snapshot(options?: SnapshotOptions): Promise<SnapshotResult>;
+  snapshot(options?: SnapshotOptions): Promise<SnapshotRuntimeResult>;
   /**
    * Native reading of the live text at a point, when the backend has one. Answers the text the
    * owner can see right now, which can exceed what an already-captured node carries (an editable

packages/contracts/src/ios-snapshot.ts

@@ -7,6 +7,10 @@ export type IosSnapshotProducer =
   | 'limrun-ios-tree';
 
 export type IosAcquisitionProducer = Exclude<IosSnapshotProducer, 'apple-runner'>;
+export type IosProviderAcquisitionProducer = Extract<
+  IosAcquisitionProducer,
+  'appium-source' | 'limrun-ios-tree'
+>;
 export type IosAcquisitionIntent = 'full' | 'surface-observation';
 export type IosSnapshotProjection = 'regular' | 'raw';
 export type IosSnapshotCompleteness = 'complete' | 'incomplete';
@@ -81,6 +85,7 @@ type IosSnapshotProducerCapabilityFacts = Readonly<{
   interactiveQueryCompleteness: IosSnapshotCompleteness;
   viewportEvidence: IosSnapshotEvidenceAvailability;
   hittabilityEvidence: IosSnapshotEvidenceAvailability;
+  truncationEvidence: IosSnapshotEvidenceAvailability;
   presentationOwner: IosSnapshotPresentationOwner;
 }>;
 
@@ -161,6 +166,8 @@ export type IosSnapshotAcquisition =
   | IosSnapshotAcquisitionForIntent<'full'>
   | IosSnapshotAcquisitionForIntent<'surface-observation'>;
 
+export type IosSnapshotAcquisitionFacts = Omit<IosSnapshotAcquisition, 'hint'>;
+
 export type IosRunnerPayloadFacts = Readonly<{
   nodes: readonly RawSnapshotNode[];
   truncated: boolean;
@@ -214,6 +221,7 @@ export type IosSnapshotPlan = Readonly<{
     interactiveQuery: IosSnapshotCompleteness;
     viewport: IosSnapshotEvidenceAvailability;
     hittability: IosSnapshotEvidenceAvailability;
+    truncation: IosSnapshotEvidenceAvailability;
   }>;
 }>;
 

packages/contracts/src/snapshot-runtime.test.ts

@@ -1,7 +1,12 @@
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import type { Interactor, RunnerContext } from './interactor-types.ts';
+import type {
+  Interactor,
+  RunnerContext,
+  SnapshotRuntimeAcquiredResult,
+  SnapshotResult,
+} from './interactor-types.ts';
 import {
   bindLocalSnapshotInteractor,
   bindProviderSnapshotInteractor,
@@ -71,6 +76,39 @@ test('provider snapshot binding fails closed when its selected owner loses the i
   );
 });
 
+test('provider snapshot binding presents acquired facts through the supplied host owner', async () => {
+  const acquired: SnapshotRuntimeAcquiredResult = {
+    stage: 'acquired',
+    acquisition: {
+      producer: 'appium-source',
+      intent: 'full',
+      nodes: [],
+      viewport: { kind: 'reported', rect: { x: 0, y: 0, width: 390, height: 844 } },
+      lineage: { targetId: 'ios-1' },
+      residue: [{ kind: 'unavailable-fact', fact: 'truncation' }],
+    },
+  };
+  const presented: SnapshotResult = {
+    backend: 'xctest',
+    producer: 'appium-source',
+    nodes: [],
+  };
+  let presentedInput: SnapshotRuntimeAcquiredResult | undefined;
+  const operations = bindProviderSnapshotInteractor({
+    device,
+    signal: new AbortController().signal,
+    resolveInteractor: () => ({ snapshot: async () => acquired }) as unknown as Interactor,
+    presentIosAcquisition: async (input) => {
+      presentedInput = input;
+      return presented;
+    },
+  });
+
+  const result = await operations.captureSnapshot({ options: { raw: true } });
+  assert.equal(result, presented);
+  assert.equal(presentedInput, acquired);
+});
+
 // ---------------------------------------------------------------------------
 // Per-capture cancellation (`CaptureSnapshotInput.signal`). A `DeviceBinding`'s
 // signal is fixed at bind time, but `wait` binds once and polls many times, so

packages/contracts/src/snapshot-runtime.ts

@@ -4,11 +4,13 @@ import type {
   Interactor,
   RunnerContext,
   SnapshotOptions,
+  SnapshotRuntimeAcquiredResult,
+  SnapshotRuntimeResult,
   SnapshotResult,
 } from './interactor-types.ts';
 import type { RuntimeOperationFact } from './platform-runtime.ts';
 
-export type { SnapshotResult } from './interactor-types.ts';
+export type { SnapshotRuntimeAcquiredResult, SnapshotResult } from './interactor-types.ts';
 
 /** Runner metadata needed by the selected snapshot implementation, without request-owned state. */
 export type SnapshotRuntimeExecution = Readonly<Omit<RunnerContext, 'appBundleId' | 'signal'>>;
@@ -75,8 +77,17 @@ export type SnapshotRuntimeHost = Readonly<{
     options: CaptureSnapshotInput['options'],
     signal: AbortSignal,
   ): Promise<SnapshotResult>;
+  presentIosAcquisition(
+    input: SnapshotRuntimeAcquiredResult,
+    options: CaptureSnapshotInput['options'],
+  ): SnapshotResult | Promise<SnapshotResult>;
 }>;
 
+export type SnapshotRuntimePresenter = (
+  input: SnapshotRuntimeAcquiredResult,
+  options: CaptureSnapshotInput['options'],
+) => SnapshotResult | Promise<SnapshotResult>;
+
 export type LocalSnapshotInteractorResolver = (
   device: DeviceInfo,
   runner: RunnerContext,
@@ -90,12 +101,14 @@ type SnapshotInteractorBindingParams =
       signal: AbortSignal;
       ownership: 'local';
       resolveInteractor: LocalSnapshotInteractorResolver;
+      presentIosAcquisition?: never;
     }>
   | Readonly<{
       device: DeviceInfo;
       signal: AbortSignal;
       ownership: 'provider';
       resolveInteractor: ProviderSnapshotInteractorResolver;
+      presentIosAcquisition?: SnapshotRuntimePresenter;
     }>;
 
 /** Captures one selected owner's interactor authority for the lifetime of a request binding. */
@@ -120,7 +133,16 @@ function bindSnapshotInteractor(
         { reason: 'provider-runtime-interactor-missing', deviceId: params.device.id },
       );
     }
-    return await interactor.snapshot({ ...input.options, signal });
+    const result: SnapshotRuntimeResult = await interactor.snapshot({ ...input.options, signal });
+    if (!isSnapshotRuntimeAcquiredResult(result)) return result;
+    if (!params.presentIosAcquisition) {
+      throw new AppError(
+        'COMMAND_FAILED',
+        'Acquired iOS snapshot has no host presentation owner.',
+        { reason: 'ios-snapshot-presenter-missing', deviceId: params.device.id },
+      );
+    }
+    return await params.presentIosAcquisition(result, input.options);
   };
   return Object.freeze({
     captureSnapshot,
@@ -145,7 +167,14 @@ export function bindProviderSnapshotInteractor(
     device: DeviceInfo;
     signal: AbortSignal;
     resolveInteractor: ProviderSnapshotInteractorResolver;
+    presentIosAcquisition?: SnapshotRuntimePresenter;
   }>,
 ): SnapshotRuntimeOperations {
   return bindSnapshotInteractor({ ...params, ownership: 'provider' });
 }
+
+function isSnapshotRuntimeAcquiredResult(
+  result: SnapshotRuntimeResult,
+): result is SnapshotRuntimeAcquiredResult {
+  return 'stage' in result && result.stage === 'acquired';
+}

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

@@ -1,5 +1,10 @@
 import type { GesturePlan } from '@agent-device/contracts/gesture-plan-types';
-import type { Interactor, RunnerContext } from '@agent-device/contracts/interactor-types';
+import type {
+  Interactor,
+  RunnerContext,
+  SnapshotResult,
+  SnapshotRuntimeResult,
+} from '@agent-device/contracts/interactor-types';
 import { AppError } from '@agent-device/kernel/errors';
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
@@ -13,6 +18,11 @@ import { createAppleInteractor } from '../interactor.ts';
 
 type RecordedRunnerCall = { command: RunnerCommand; options: AppleRunnerCommandOptions };
 
+function presentedSnapshot(result: SnapshotRuntimeResult): SnapshotResult {
+  if ('stage' in result) throw new Error('Apple runner snapshot must be presented');
+  return result;
+}
+
 // Every Interactor method must either ride the injected runner transport or
 // fail fast as a local-tooling method the provider composes itself. The two
 // tables below partition the surface; the partition test keeps them total, so
@@ -175,7 +185,7 @@ test('snapshot merges its per-call cancellation signal with the interaction cont
 
 test('snapshot over the injected transport keeps the shared xctest result shape', async () => {
   const interactor = createAppleInteractor(IOS_SIMULATOR, {}, recordingRunnerProvider([]));
-  const result = await interactor.snapshot();
+  const result = presentedSnapshot(await interactor.snapshot());
   assert.equal(result.backend, 'xctest');
   assert.equal(result.nodes?.length, 2);
 });
@@ -246,7 +256,7 @@ test('snapshot publishes runner presentation through the engine and drops its qu
     },
   );
 
-  const result = await interactor.snapshot({ interactiveOnly: true });
+  const result = presentedSnapshot(await interactor.snapshot({ interactiveOnly: true }));
 
   assert.deepEqual(
     result.nodes?.map((node) => node.type),
@@ -263,7 +273,7 @@ test('macOS app snapshots preserve runner nodes outside the iOS presentation eng
     { runCommand: async () => ({ nodes }) },
   );
 
-  const result = await interactor.snapshot({ interactiveOnly: true });
+  const result = presentedSnapshot(await interactor.snapshot({ interactiveOnly: true }));
 
   assert.deepEqual(result.nodes, nodes);
 });
@@ -350,7 +360,7 @@ test('snapshot accepts only structured healthy empty scope results', async () =>
   };
   const interactor = createAppleInteractor(IOS_SIMULATOR, {}, healthyEmptyProvider);
 
-  const scoped = await interactor.snapshot({ scope: 'missing' });
+  const scoped = presentedSnapshot(await interactor.snapshot({ scope: 'missing' }));
   assert.deepEqual(scoped.nodes, []);
   assert.equal(scoped.backend, 'xctest');
   assert.equal(scoped.quality?.state, 'healthy');