fix(ios): preserve unavailable snapshot facts

Author: thymikee

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

@@ -236,6 +236,10 @@ test('unavailable hittability never becomes regular actionability', () => {
   const acquired = publishIosSnapshot({ stage: 'acquired', acquisition: unavailable }, request);
   assert.equal(
     acquired.payload.nodes.find((node) => node.label === 'Partially visible')?.hittable,
+    undefined,
+  );
+  assert.equal(
+    'hittable' in (acquired.payload.nodes.find((node) => node.label === 'Partially visible') ?? {}),
     false,
   );
 

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

@@ -107,17 +107,21 @@ function appendFoldedNode(
 
   const index = kept.length;
   keptDepth += 1;
+  const { hittable: sourceHittable, ...sourceNode } = node;
   kept.push({
     raw: {
-      ...node,
+      ...sourceNode,
       index,
       depth: keptDepth,
       parentIndex: keptIndex,
-      hittable:
-        node.parentIndex !== undefined &&
-        options.hittabilityAvailable !== false &&
-        node.hittable === true &&
-        isGeometricallyActionable(node.enabled !== false, decision.effectiveRect, viewport),
+      ...foldedHittability(
+        sourceHittable,
+        node.parentIndex !== undefined,
+        decision.effectiveRect,
+        node.enabled !== false,
+        viewport,
+        options,
+      ),
     },
     sourceIndex: node.index,
     ...(decision.effectiveRect ? { effectiveRect: decision.effectiveRect } : {}),
@@ -126,6 +130,25 @@ function appendFoldedNode(
   return { keptIndex, keptDepth };
 }
 
+function foldedHittability(
+  sourceHittable: RawSnapshotNode['hittable'],
+  hasParent: boolean,
+  effectiveRect: Rect | undefined,
+  enabled: boolean,
+  viewport: Rect,
+  options: IosSnapshotFoldOptions,
+): Partial<Pick<RawSnapshotNode, 'hittable'>> {
+  if (options.hittabilityAvailable === false) {
+    return sourceHittable === false ? { hittable: false } : {};
+  }
+  return {
+    hittable:
+      hasParent &&
+      sourceHittable === true &&
+      isGeometricallyActionable(enabled, effectiveRect, viewport),
+  };
+}
+
 function nextScrollAnchor(
   decision: GeometryDecision,
   parentAnchor: BranchState['anchor'],

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

@@ -142,17 +142,19 @@ function createRegularProjectedNode(
   if (!isEligibleForIosRegularPresentation(node.raw)) return undefined;
   const depth = parent ? (parent.depth ?? 0) + 1 : 0;
   if (maximumDepth !== null && depth > maximumDepth) return undefined;
+  const hittable = isProjectedNodeHittable(node);
   return {
     ...node.raw,
     index,
     depth,
     parentIndex: parent?.index,
     ...(node.effectiveRect ? { rect: node.effectiveRect } : { rect: undefined }),
-    hittable: isProjectedNodeHittable(node),
+    ...(hittable === undefined ? {} : { hittable }),
   };
 }
 
-function isProjectedNodeHittable(node: IosSnapshotPresentationNode): boolean {
+function isProjectedNodeHittable(node: IosSnapshotPresentationNode): RawSnapshotNode['hittable'] {
+  if (node.raw.hittable === undefined) return undefined;
   return Boolean(
     node.raw.hittable === true &&
     node.effectiveRect &&

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

@@ -147,8 +147,12 @@ 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('Appium source plan carries its viewport evidence capability', () => {
+  const plan = planIosSnapshot(
+    createIosSnapshotRequest(),
+    IOS_SNAPSHOT_PRODUCER_CAPABILITIES['appium-source'],
+  );
+  assert.equal(plan.evidence.viewport, 'available');
 });
 
 test('comparison identity rejects every identity axis and residue mismatch', () => {

packages/provider-webdriver/src/webdriver-ios-snapshot.test.ts

@@ -31,7 +31,7 @@ test('Appium iOS snapshots acquire facts and publish regular output through the
       ['XCUIElementTypeButton', 'Continue', 1],
     ],
   );
-  assert.equal(result.nodes?.find((node) => node.label === 'Continue')?.hittable, false);
+  assert.equal(result.nodes?.find((node) => node.label === 'Continue')?.hittable, undefined);
   assert.equal(source.mock.calls.length, 1);
   assert.ok(result.warnings?.some((warning) => warning.includes('hittability evidence')));
   assert.deepEqual(Object.keys(result).sort(), [
@@ -85,6 +85,22 @@ test('Appium iOS options become an engine plan and engine-owned projection', ()
   assert.deepEqual(published.publication.comparisonIdentity.lineage, {});
 });
 
+test('Appium regular presentation omits unavailable hittability while raw preserves supplied facts', async () => {
+  const source =
+    '<AppiumAUT><XCUIElementTypeApplication x="0" y="0" width="390" height="844">' +
+    '<XCUIElementTypeButton name="Continue" x="24" y="700" width="160" height="48" hittable="true" />' +
+    '</XCUIElementTypeApplication></AppiumAUT>';
+
+  const regular = await captureWebDriverIosSnapshot({ source: async () => source });
+  const regularButton = regular.nodes?.find((node) => node.label === 'Continue');
+  assert.equal(regularButton?.hittable, undefined);
+  assert.equal('hittable' in (regularButton ?? {}), false);
+
+  const raw = await captureWebDriverIosSnapshot({ source: async () => source }, { raw: true });
+  assert.equal(raw.nodes?.find((node) => node.label === 'Continue')?.hittable, true);
+  assert.ok(raw.warnings?.some((warning) => warning.includes('does not guarantee')));
+});
+
 test('Appium iOS interactive requests stay provider-unpruned and use engine presentation', () => {
   const acquired = acquireWebDriverIosSnapshot(SOURCE, { interactiveOnly: true }, 'ios-1');
 
@@ -95,7 +111,10 @@ test('Appium iOS interactive requests stay provider-unpruned and use engine pres
     published.result.nodes?.some((node) => node.label === 'Continue'),
     true,
   );
-  assert.equal(published.result.nodes?.find((node) => node.label === 'Continue')?.hittable, false);
+  assert.equal(
+    published.result.nodes?.find((node) => node.label === 'Continue')?.hittable,
+    undefined,
+  );
 });
 
 test('Appium iOS regular presentation fails typed when page source has no viewport', () => {
@@ -109,6 +128,7 @@ test('Appium iOS regular presentation fails typed when page source has no viewpo
   });
   assert.deepEqual(acquired.input.acquisition.residue, [
     { kind: 'unavailable-fact', fact: 'hittability' },
+    { kind: 'unavailable-fact', fact: 'acquisition-depth' },
     { kind: 'missing-viewport', reason: 'not-provided' },
   ]);
   assert.throws(
@@ -147,15 +167,12 @@ test('Appium iOS regular presentation fails typed when root geometry is invalid'
   );
 });
 
-test('Appium iOS truncation is typed and disclosed at response level', async () => {
-  const result = await captureWebDriverIosSnapshot(
-    { source: async () => SOURCE.replace('<AppiumAUT>', '<AppiumAUT truncated="true">') },
-    { raw: true },
-  );
+test('Appium iOS hierarchy limits are typed and disclosed at response level', async () => {
+  const result = await captureWebDriverIosSnapshot({ source: async () => SOURCE }, { raw: true });
 
-  assert.equal(result.truncated, true);
+  assert.equal(result.truncated, false);
   assert.deepEqual(result.warnings, [
-    'Appium page source does not provide hittability evidence; the capture carries no hittability fact.',
-    'Appium page source is truncated; the snapshot hierarchy may be incomplete.',
+    'Appium page source does not guarantee hittability evidence; regular presentation treats it as unavailable.',
+    'Appium page source does not report hierarchy completeness; depth- or child-limited nodes may be absent.',
   ]);
 });

packages/provider-webdriver/src/webdriver-ios-snapshot.ts

@@ -16,6 +16,7 @@ import type {
   IosSnapshotPlan,
   IosSnapshotPublication,
   IosSnapshotRequest,
+  IosSnapshotFact,
   IosViewportEvidence,
 } from '@agent-device/contracts/ios-snapshot';
 import type { SnapshotOptions, SnapshotResult } from '@agent-device/contracts/interactor-types';
@@ -29,8 +30,13 @@ const iosSnapshotEngine = createIosSnapshotEngine();
 const RESIDUE_WARNINGS = {
   'missing-viewport':
     'Appium page source does not provide a valid viewport; regular snapshot presentation is unavailable.',
-  truncated: 'Appium page source is truncated; the snapshot hierarchy may be incomplete.',
-} satisfies Pick<Record<IosAcquisitionResidue['kind'], string>, 'missing-viewport' | 'truncated'>;
+} satisfies Pick<Record<IosAcquisitionResidue['kind'], string>, 'missing-viewport'>;
+const UNAVAILABLE_FACT_WARNINGS: Partial<Record<IosSnapshotFact, string>> = {
+  'acquisition-depth':
+    'Appium page source does not report hierarchy completeness; depth- or child-limited nodes may be absent.',
+  hittability:
+    'Appium page source does not guarantee hittability evidence; regular presentation treats it as unavailable.',
+};
 
 export type WebDriverIosSnapshotAcquisition = Readonly<{
   request: IosSnapshotRequest;
@@ -71,11 +77,11 @@ export function acquireWebDriverIosSnapshot(
     kind: 'missing' as const,
     reason: 'not-provided' as const,
   };
-  const residue = residueForSource(sourceFacts.truncated, viewport);
+  const residue = residueForSource(viewport);
   const common = {
     producer: 'appium-source' as const,
     nodes: sourceFacts.nodes,
-    truncated: sourceFacts.truncated,
+    truncated: false,
     viewport,
     lineage: targetId ? { targetId } : {},
     residue,
@@ -110,15 +116,14 @@ export function publishWebDriverIosSnapshot(
   return { acquisition, publication, result };
 }
 
-function residueForSource(
-  truncated: boolean,
-  viewport: IosViewportEvidence,
-): readonly IosAcquisitionResidue[] {
-  const residue: IosAcquisitionResidue[] = [{ kind: 'unavailable-fact', fact: 'hittability' }];
+function residueForSource(viewport: IosViewportEvidence): readonly IosAcquisitionResidue[] {
+  const residue: IosAcquisitionResidue[] = [
+    { kind: 'unavailable-fact', fact: 'hittability' },
+    { kind: 'unavailable-fact', fact: 'acquisition-depth' },
+  ];
   if (viewport.kind === 'missing') {
     residue.push({ kind: 'missing-viewport', reason: viewport.reason });
   }
-  if (truncated) residue.push({ kind: 'truncated', dimension: 'nodes' });
   return residue;
 }
 
@@ -133,11 +138,9 @@ function warningsForResidue(residue: readonly IosAcquisitionResidue[]): { warnin
 
 function warningForResidue(entry: IosAcquisitionResidue): string | undefined {
   if (entry.kind === 'unavailable-fact') {
-    return entry.fact === 'hittability'
-      ? 'Appium page source does not provide hittability evidence; the capture carries no hittability fact.'
-      : undefined;
+    return UNAVAILABLE_FACT_WARNINGS[entry.fact];
   }
-  if (entry.kind === 'missing-viewport' || entry.kind === 'truncated') {
+  if (entry.kind === 'missing-viewport') {
     return RESIDUE_WARNINGS[entry.kind];
   }
   return undefined;

packages/provider-webdriver/src/webdriver-source.test.ts

@@ -28,6 +28,8 @@ test('WebDriver source facts do not fill absent provider attributes', () => {
   assert.equal(node?.label, 'Continue');
   assert.equal(node?.identifier, 'Continue');
   assert.equal('enabled' in (node ?? {}), false);
+  assert.equal('selected' in (node ?? {}), false);
+  assert.equal('focused' in (node ?? {}), false);
   assert.equal('visibleToUser' in (node ?? {}), false);
   assert.equal('hittable' in (node ?? {}), false);
 });
@@ -64,12 +66,12 @@ test('legacy WebDriver parsing keeps Android source booleans and ignores iOS hin
   assert.equal(node?.hittable, false);
 });
 
-test('WebDriver source facts expose provider truncation without publishing wrapper nodes', () => {
+test('WebDriver source facts preserve roots without claiming hierarchy completeness', () => {
   const facts = parseWebDriverSourceFacts(
     '<AppiumAUT truncated="true"><XCUIElementTypeApplication x="0" y="0" width="390" height="844" /></AppiumAUT>',
   );
 
-  assert.equal(facts.truncated, true);
+  assert.equal('truncated' in facts, false);
   assert.deepEqual(facts.roots, [
     {
       type: 'XCUIElementTypeApplication',

packages/provider-webdriver/src/webdriver-source.ts

@@ -8,8 +8,6 @@ export type WebDriverSourceParseMode = 'facts' | 'legacy-derived';
 export type WebDriverSourceFacts = Readonly<{
   nodes: RawSnapshotNode[];
   roots: readonly WebDriverSourceRootFact[];
-  /** True only when the source explicitly marks the hierarchy as truncated. */
-  truncated: boolean;
 }>;
 
 export type WebDriverSourceRootFact = Readonly<{
@@ -36,7 +34,7 @@ export function parseWebDriverSourceFacts(
   for (const root of roots) {
     appendSourceNodes(nodes, root, undefined, 0, mode, sourceRoots);
   }
-  return { nodes, roots: sourceRoots, truncated: hasExplicitTruncationMarker(roots) };
+  return { nodes, roots: sourceRoots };
 }
 
 function appendSourceNodes(
@@ -150,20 +148,19 @@ function sourceStateFacts(
   const enabled = booleanAttribute(attrs.enabled);
   const visibleToUser = booleanAttribute(attrs.displayed ?? attrs.visible);
   return {
-    ...optionalBooleanFact('enabled', enabled, false),
-    selected: booleanAttribute(attrs.selected),
-    focused: booleanAttribute(attrs.focused),
-    ...optionalBooleanFact('visibleToUser', visibleToUser, false),
+    ...optionalBooleanFact('enabled', enabled),
+    ...optionalBooleanFact('selected', booleanAttribute(attrs.selected)),
+    ...optionalBooleanFact('focused', booleanAttribute(attrs.focused)),
+    ...optionalBooleanFact('visibleToUser', visibleToUser),
     ...reportedHittabilityFact(attrs.hittable),
   };
 }
 
 function optionalBooleanFact(
-  key: 'enabled' | 'visibleToUser',
+  key: 'enabled' | 'selected' | 'focused' | 'visibleToUser',
   value: boolean | undefined,
-  defaultWhenAbsent: boolean,
-): Partial<RawSnapshotNode> {
-  return defaultWhenAbsent || value !== undefined ? { [key]: value ?? true } : {};
+): Partial<Pick<RawSnapshotNode, 'enabled' | 'selected' | 'focused' | 'visibleToUser'>> {
+  return value === undefined ? {} : { [key]: value };
 }
 
 function reportedHittabilityFact(
@@ -173,14 +170,6 @@ function reportedHittabilityFact(
   return reportedHittable === undefined ? {} : { hittable: reportedHittable };
 }
 
-function hasExplicitTruncationMarker(nodes: readonly XmlNode[]): boolean {
-  return nodes.some(
-    (node) =>
-      booleanAttribute(node.attributes.truncated) === true ||
-      hasExplicitTruncationMarker(node.children),
-  );
-}
-
 function rectFromAttributes(attrs: Record<string, string>): RawSnapshotNode['rect'] | undefined {
   const bounds = parseBounds(attrs.bounds ?? null);
   if (bounds) return bounds;