refactor(screenshot): drop the dead crop outcome flag and cover the projection seams

- ScreenshotCropOutcome.cropped was a constant true that no caller read;
  the crop either returns (success) or throws, so the outcome reduces to
  the partialIntersection observation.
- resolveScreenshotRectSpace and resolveSnapshotBounds were the only
  projection exports without coverage: pin the accepted-backend map, the
  unaccepted-backend typed refusal, and the viewport-root / union / empty
  bounds branches.

Author: thymikee

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

@@ -2,10 +2,14 @@ import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
+import { SCREENSHOT_CROP_REASONS } from '@agent-device/contracts/capture';
+import { AppError } from '@agent-device/kernel/errors';
 import type { Rect } from '@agent-device/kernel/snapshot';
 import {
   intersectScreenshotRect,
   projectSnapshotRectToScreenshot,
+  resolveScreenshotRectSpace,
+  resolveSnapshotBounds,
   type ScreenshotRectSpace,
 } from './snapshot-rect-projection.ts';
 
@@ -56,3 +60,55 @@ test('the crop projection law agrees with every golden geometry case', () => {
     assert.deepEqual(intersection, fixture.expectedIntersection, fixture.name);
   }
 });
+
+test('resolveScreenshotRectSpace maps each accepted backend to its projection space and refuses the rest', () => {
+  assert.equal(resolveScreenshotRectSpace('android'), 'device-pixels');
+  assert.equal(resolveScreenshotRectSpace('xctest'), 'viewport-points');
+  assert.equal(resolveScreenshotRectSpace('macos-helper'), 'viewport-points');
+  for (const backend of [undefined, 'linux', 'web', 'harmonyos', 'vega']) {
+    assert.throws(
+      () => resolveScreenshotRectSpace(backend),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'UNSUPPORTED_OPERATION' &&
+        error.details?.reason === SCREENSHOT_CROP_REASONS.targetNotAccepted,
+    );
+  }
+});
+
+test('resolveSnapshotBounds prefers the largest viewport root, else unions every positive rect excluding unlabeled images', () => {
+  assert.deepEqual(
+    resolveSnapshotBounds([
+      { type: 'XCUIElementTypeImage', label: '', rect: { x: 0, y: 0, width: 50, height: 50 } },
+      {
+        type: 'XCUIElementTypeApplication',
+        label: 'Settings',
+        rect: { x: 0, y: 0, width: 402, height: 874 },
+      },
+      {
+        type: 'XCUIElementTypeButton',
+        label: 'Continue',
+        rect: { x: 100, y: 100, width: 200, height: 50 },
+      },
+    ]),
+    { x: 0, y: 0, width: 402, height: 874 },
+  );
+  assert.deepEqual(
+    resolveSnapshotBounds([
+      { type: 'XCUIElementTypeButton', label: 'A', rect: { x: 10, y: 20, width: 100, height: 40 } },
+      {
+        type: 'XCUIElementTypeButton',
+        label: 'B',
+        rect: { x: 300, y: 400, width: 60, height: 30 },
+      },
+      { type: 'XCUIElementTypeImage', label: '', rect: { x: 0, y: 0, width: 999, height: 999 } },
+    ]),
+    { x: 10, y: 20, width: 350, height: 410 },
+  );
+  assert.equal(
+    resolveSnapshotBounds([
+      { type: 'XCUIElementTypeButton', label: 'A', rect: { x: 0, y: 0, width: 0, height: 50 } },
+    ]),
+    null,
+  );
+});

src/daemon/__tests__/screenshot-crop.test.ts

@@ -21,8 +21,8 @@ import { writeSolidPng } from './screenshot-runtime-fixture.ts';
 
 test('the warning composition is the single owner: partial intersection and only', () => {
   expect(buildScreenshotCropWarnings(undefined)).toEqual([]);
-  expect(buildScreenshotCropWarnings({ cropped: true, partialIntersection: false })).toEqual([]);
-  const warnings = buildScreenshotCropWarnings({ cropped: true, partialIntersection: true });
+  expect(buildScreenshotCropWarnings({ partialIntersection: false })).toEqual([]);
+  const warnings = buildScreenshotCropWarnings({ partialIntersection: true });
   expect(warnings).toHaveLength(1);
   expect(warnings[0]).toMatch(new RegExp(`^${SCREENSHOT_CROP_REASONS.partialIntersection}: `));
 });
@@ -129,7 +129,7 @@ test('an android crop runs the fresh full-tree capture once and leaves the sessi
   });
   try {
     const outcome = await seam.run();
-    expect(outcome).toEqual({ cropped: true, partialIntersection: false });
+    expect(outcome).toEqual({ partialIntersection: false });
     expect(await readPngSize(seam.screenshotPath)).toEqual({ width: 40, height: 20 });
     expect(seam.captureSnapshot).toHaveBeenCalledTimes(1);
     const options = seam.captureSnapshot.mock.calls[0]?.[0].options;
@@ -153,7 +153,7 @@ test('an iOS simulator crop projects the points-space frame into the 3x capture'
   });
   try {
     const outcome = await seam.run();
-    expect(outcome).toEqual({ cropped: true, partialIntersection: false });
+    expect(outcome).toEqual({ partialIntersection: false });
     expect(await readPngSize(seam.screenshotPath)).toEqual({ width: 300, height: 120 });
   } finally {
     seam.dispose();
@@ -169,7 +169,7 @@ test('a frame that runs past the image is clipped and reported partial', async (
   });
   try {
     const outcome = await seam.run();
-    expect(outcome).toEqual({ cropped: true, partialIntersection: true });
+    expect(outcome).toEqual({ partialIntersection: true });
     expect(await readPngSize(seam.screenshotPath)).toEqual({ width: 20, height: 20 });
   } finally {
     seam.dispose();

src/daemon/screenshot-crop.ts

@@ -21,10 +21,7 @@ import { runtimeExecutionFromContext } from './snapshot-runtime-capture-input.ts
 import type { BoundScreenshotRuntime } from './screenshot-runtime-binding.ts';
 import type { SessionState } from './types.ts';
 
-export type ScreenshotCropOutcome = Readonly<{
-  cropped: true;
-  partialIntersection: boolean;
-}>;
+export type ScreenshotCropOutcome = Readonly<{ partialIntersection: boolean }>;
 
 const CROP_PARTIAL_INTERSECTION_WARNING = `${SCREENSHOT_CROP_REASONS.partialIntersection}: the selector frame extends past the captured image; the crop was clipped to the image frame`;
 
@@ -100,7 +97,7 @@ export async function cropScreenshotToSelector(params: {
     box.width < projected.width ||
     box.height < projected.height;
   await cropPngFile(screenshotPath, box);
-  return { cropped: true, partialIntersection };
+  return { partialIntersection };
 }
 
 /** Resolve the selector to exactly one framed node, or fail with a typed crop reason. */