refactor(ios): converge Limrun snapshots through engine (#2222)

* refactor(ios): converge Limrun snapshots through engine

* fix(limrun): defer snapshot engine loading

* fix(limrun): harden snapshot viewport evidence

* fix(limrun): preserve snapshot engine evidence

* fix(limrun): preserve unknown snapshot truncation

* refactor(ios): reuse private presentation evidence seam

* test(ios): remove stale presentation assertion binding

* test(ios): extract snapshot truncation regressions

* test: ratchet snapshot suite size pins

* test(snapshot): cover provider presentation ownership

* test(snapshot): type Limrun composition fixture

* test(snapshot): exercise public Limrun runtime composition

Author: thymikee

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

@@ -56,14 +56,14 @@ const IOS_SNAPSHOT_PRODUCER_CAPABILITY_VALUES = {
     producer: 'limrun-ios-tree',
     stage: 'acquired',
     acquisitionDepth: {
-      rawTraversal: { kind: 'complete' },
+      rawTraversal: { kind: 'incomplete' },
       regularPresented: { kind: 'incomplete' },
     },
     scopeCompleteness: 'incomplete',
     interactiveQueryCompleteness: 'incomplete',
     viewportEvidence: 'available',
     hittabilityEvidence: 'unavailable',
-    presentationOwner: 'snapshot-state',
+    presentationOwner: 'ios-snapshot-engine',
   },
 } as const satisfies Record<IosSnapshotProducer, IosSnapshotProducerCapabilities>;
 

packages/contracts/src/client-capture.ts

@@ -37,6 +37,7 @@ export type CaptureSnapshotOptions = AgentDeviceRequestOverrides &
 
 export type CaptureSnapshotResult = {
   nodes: SnapshotNode[];
+  /** Present only when the capture owner establishes whether the tree was truncated. */
   truncated?: boolean;
   appName?: string;
   appBundleId?: string;

packages/contracts/src/ios-snapshot.ts

@@ -72,7 +72,8 @@ export type IosSnapshotFact =
   | 'interactive-query'
   | 'viewport'
   | 'hittability'
-  | 'generation';
+  | 'generation'
+  | 'truncation';
 
 type IosSnapshotProducerCapabilityFacts = Readonly<{
   acquisitionDepth: IosSnapshotAcquisitionDepthCapability;

packages/provider-limrun/src/ios-interactor-snapshot.test.ts

@@ -8,8 +8,10 @@ test('limrun iOS snapshot stamps the xctest channel with its own producer', asyn
       elementTree: async () =>
         JSON.stringify({
           elementType: 'Application',
+          frame: { x: 0, y: 0, width: 320, height: 240 },
           children: [{ elementType: 'Button', label: 'Continue', enabled: true }],
         }),
+      deviceInfo: { screenWidth: 320, screenHeight: 240 },
     },
   } as unknown as LimrunIosSession;
 

packages/provider-limrun/src/ios-snapshot-adapter.fixtures.ts

@@ -0,0 +1,66 @@
+import type { LimrunIosSession } from './ios.ts';
+import type { IosTreeNode } from './snapshot.ts';
+
+export const LIMRUN_SNAPSHOT_SCREEN: Readonly<{ width: number; height: number }> = Object.freeze({
+  width: 320,
+  height: 240,
+});
+
+export function limrunSnapshotTree(): IosTreeNode {
+  return {
+    elementType: 'Application',
+    label: 'App',
+    frame: {
+      x: 0,
+      y: 0,
+      width: LIMRUN_SNAPSHOT_SCREEN.width,
+      height: LIMRUN_SNAPSHOT_SCREEN.height,
+    },
+    children: [
+      {
+        elementType: 'Table',
+        label: 'Settings',
+        frame: {
+          x: 0,
+          y: 0,
+          width: LIMRUN_SNAPSHOT_SCREEN.width,
+          height: LIMRUN_SNAPSHOT_SCREEN.height,
+        },
+        children: [
+          {
+            elementType: 'Cell',
+            label: 'Target',
+            frame: { x: 16, y: 40, width: 288, height: 52 },
+            children: [
+              {
+                elementType: 'Button',
+                label: 'Save',
+                frame: { x: 32, y: 48, width: 100, height: 36 },
+                enabled: true,
+                hittable: true,
+              },
+              {
+                elementType: 'StaticText',
+                label: 'Save',
+                frame: { x: 32, y: 48, width: 100, height: 36 },
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+export function createLimrunSnapshotSession(
+  tree: IosTreeNode | IosTreeNode[] = limrunSnapshotTree(),
+  screen = LIMRUN_SNAPSHOT_SCREEN,
+): Pick<LimrunIosSession, 'client' | 'instanceId'> {
+  return {
+    instanceId: 'limrun-snapshot-test-instance',
+    client: {
+      elementTree: async () => JSON.stringify(tree),
+      deviceInfo: { screenWidth: screen.width, screenHeight: screen.height },
+    },
+  } as Pick<LimrunIosSession, 'client' | 'instanceId'>;
+}

packages/provider-limrun/src/ios-snapshot-adapter.test.ts

@@ -0,0 +1,130 @@
+import { expect, test, vi } from 'vitest';
+import {
+  IOS_SNAPSHOT_PRODUCER_CAPABILITIES,
+  createIosSnapshotRequest,
+  planIosSnapshot,
+} from '@agent-device/capture-kit/ios-snapshot-planning';
+import { captureLimrunIosSnapshot } from './ios-snapshot-adapter.ts';
+import {
+  LIMRUN_SNAPSHOT_SCREEN,
+  createLimrunSnapshotSession,
+  limrunSnapshotTree,
+} from './ios-snapshot-adapter.fixtures.ts';
+
+test('derives the current engine viewport from the tree before the cached deviceInfo', async () => {
+  const session = createLimrunSnapshotSession(limrunSnapshotTree(), { width: 240, height: 320 });
+  const elementTree = vi.fn(session.client.elementTree);
+  const result = await captureLimrunIosSnapshot(
+    { ...session, client: { ...session.client, elementTree } },
+    { interactiveOnly: false },
+  );
+
+  expect(elementTree).toHaveBeenCalledWith();
+  expect(result.nodes?.[0]?.rect).toEqual({ x: 0, y: 0, width: 320, height: 240 });
+  expect(result.nodes?.map((node) => node.label)).toEqual([
+    'App',
+    'Settings',
+    'Target',
+    'Save',
+    'Save',
+  ]);
+  expect(result.nodes?.find((node) => node.label === 'Save')).not.toHaveProperty('hittable');
+  expect(result.warnings).toContain(
+    'Limrun iOS tree responses do not expose truncation metadata; tree completeness is not independently verified.',
+  );
+  expect(result.warnings).toContain(
+    'Limrun iOS snapshots do not provide hittability evidence; regular snapshots will not mark nodes actionable.',
+  );
+});
+
+test.each([
+  {
+    name: 'raw full',
+    options: { raw: true, interactiveOnly: true },
+    labels: ['App', 'Settings', 'Target', 'Save', 'Save'],
+  },
+  { name: 'raw traversal depth', options: { raw: true, depth: 1 }, labels: ['App', 'Settings'] },
+  { name: 'regular presented depth', options: { depth: 1 }, labels: ['App', 'Settings'] },
+  { name: 'regular scope', options: { scope: 'Target' }, labels: ['Target', 'Save', 'Save'] },
+])('routes $name through the shared engine projection', async ({ options, labels }) => {
+  const result = await captureLimrunIosSnapshot(createLimrunSnapshotSession(), options);
+
+  expect(result.nodes?.map((node) => node.label)).toEqual(labels);
+  expect(result.truncated).toBeUndefined();
+});
+
+test('the Limrun capability plan leaves unsupported acquisition tiers to the shared engine', () => {
+  const request = createIosSnapshotRequest({ raw: true, interactiveOnly: true, depth: 2 });
+  const plan = planIosSnapshot(request, IOS_SNAPSHOT_PRODUCER_CAPABILITIES['limrun-ios-tree']);
+
+  expect(plan.narrowing).toEqual({ depth: null, scope: null, interactiveOnly: false });
+  expect(plan.evidence).toEqual({
+    scope: 'incomplete',
+    interactiveQuery: 'incomplete',
+    viewport: 'available',
+    hittability: 'unavailable',
+  });
+});
+
+test('regular Limrun presentation never infers hittability from an enabled rectangle', async () => {
+  const tree = limrunSnapshotTree();
+  tree.children![0]!.children!.push({
+    elementType: 'Button',
+    label: 'Enabled but unverified',
+    frame: { x: 120, y: 120, width: 80, height: 40 },
+    enabled: true,
+    hittable: true,
+  });
+
+  const result = await captureLimrunIosSnapshot(createLimrunSnapshotSession(tree));
+  const target = result.nodes?.find((node) => node.label === 'Enabled but unverified');
+
+  expect(target).toMatchObject({ enabled: true, rect: { x: 120, y: 120, width: 80, height: 40 } });
+  expect(target).not.toHaveProperty('hittable');
+});
+
+test('regular presentation fails with a typed viewport error while raw output discloses the missing evidence', async () => {
+  const tree = limrunSnapshotTree();
+  tree.frame = undefined;
+  const session = createLimrunSnapshotSession(tree, { width: 0, height: 240 });
+
+  await expect(captureLimrunIosSnapshot(session)).rejects.toMatchObject({
+    code: 'COMMAND_FAILED',
+    details: {
+      reason: 'invalid-viewport',
+      hint: 'Limrun iOS snapshots did not provide a valid viewport (invalid); retry with --raw to inspect the acquired tree, while regular presentation requires viewport evidence.',
+    },
+  });
+
+  const raw = await captureLimrunIosSnapshot(session, { raw: true });
+  expect(raw.nodes).toHaveLength(5);
+  expect(raw.warnings).toContain(
+    'Limrun iOS snapshots did not provide a valid viewport (invalid); retry with --raw to inspect the acquired tree, while regular presentation requires viewport evidence.',
+  );
+});
+
+test('falls back to valid Limrun deviceInfo when the tree has no viewport root frame', async () => {
+  const tree = limrunSnapshotTree();
+  tree.frame = undefined;
+
+  const result = await captureLimrunIosSnapshot(
+    createLimrunSnapshotSession(tree, { width: 240, height: 320 }),
+  );
+
+  expect(result.nodes).toHaveLength(5);
+});
+
+test('the Limrun acquired result keeps provider provenance and SDK screen dimensions', async () => {
+  const result = await captureLimrunIosSnapshot(createLimrunSnapshotSession());
+
+  expect(result).toMatchObject({
+    backend: 'xctest',
+    producer: 'limrun-ios-tree',
+  });
+  expect(result.nodes?.[0]?.rect).toEqual({
+    x: 0,
+    y: 0,
+    width: LIMRUN_SNAPSHOT_SCREEN.width,
+    height: LIMRUN_SNAPSHOT_SCREEN.height,
+  });
+});