refactor(screenshot): dedupe the meaningful-signal predicate and polish png-crop

- Hoist isMeaningfulSignal into @agent-device/contracts/snapshot (next to
  normalizeType/isMeaningfulLabel) so the ref overlay and the crop
  rect-projection share one copy instead of each carrying an identical
  private predicate. Behavior is unchanged.
- png-crop: isCropBox was a no-op 'box is Rect' predicate (input already
  Rect) — make it a plain boolean, and tighten the doc to the contract.

Author: thymikee

packages/capture-kit/src/png-crop.ts

@@ -5,10 +5,9 @@ import { PNG } from './png.ts';
 import { decodePngAsync, encodePngAsync } from './png-worker-client.ts';
 
 /**
- * Crops a PNG file in place to `box` (daemon screenshot `--crop-on` path). Decode and encode
- * run on the PNG worker thread like the `--scale` resize; the row copy is a straight blit.
- * The box is the caller's already-intersected crop region, so a box outside the image is
- * a caller bug this refuses rather than clamps.
+ * Crops `filePath` in place to `box` (positive integer pixels). `box` is the caller's
+ * already-intersected region, so one outside the image is a caller bug — refused, not clamped.
+ * Decode and encode run on the PNG worker thread; a full-image box is a no-op.
  */
 export async function cropPngFile(filePath: string, box: Rect): Promise<void> {
   if (!isCropBox(box)) {
@@ -32,7 +31,7 @@ export async function cropPngFile(filePath: string, box: Rect): Promise<void> {
   await fs.writeFile(filePath, await encodePngAsync(cropPngBox(source, box)));
 }
 
-function isCropBox(box: Rect): box is Rect {
+function isCropBox(box: Rect): boolean {
   return (
     Number.isInteger(box.x) &&
     box.x >= 0 &&

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

@@ -1,6 +1,10 @@
 import { AppError } from '@agent-device/kernel/errors';
 import { SCREENSHOT_CROP_REASONS } from '@agent-device/contracts/capture';
-import { isViewportRootNode, normalizeType } from '@agent-device/contracts/snapshot';
+import {
+  isMeaningfulSignal,
+  isViewportRootNode,
+  normalizeType,
+} from '@agent-device/contracts/snapshot';
 import { isPositiveFiniteRect, rectArea } from '@agent-device/kernel/rect';
 import type { Rect, SnapshotNode } from '@agent-device/kernel/snapshot';
 
@@ -121,14 +125,7 @@ function measureSnapshotBounds(nodes: ReadonlyArray<Pick<SnapshotNode, 'rect'>>)
 }
 
 function isSnapshotBoundsOutlier(node: Pick<SnapshotNode, 'type' | 'label'>): boolean {
-  return normalizeType(node.type ?? '') === 'image' && !isMeaningfulBoundsSignal(node.label);
-}
-
-function isMeaningfulBoundsSignal(value: string | undefined): boolean {
-  if (typeof value !== 'string') return false;
-  const trimmed = value.trim();
-  if (!trimmed) return false;
-  return !/^(true|false)$/i.test(trimmed);
+  return normalizeType(node.type ?? '') === 'image' && !isMeaningfulSignal(node.label);
 }
 
 function roundRect(rect: Rect): Rect {

packages/contracts/src/facades/snapshot.ts

@@ -26,5 +26,6 @@ export {
   extractNodeText,
   isFillableType,
   isMeaningfulLabel,
+  isMeaningfulSignal,
   normalizeType,
 } from '../snapshot-text.ts';

packages/contracts/src/snapshot-text.ts

@@ -38,6 +38,14 @@ export function isMeaningfulLabel(value: string): boolean {
   return true;
 }
 
+/** A non-empty, non-boolean `label`/`value` is a usable overlay or crop signal. */
+export function isMeaningfulSignal(value: string | undefined): boolean {
+  if (typeof value !== 'string') return false;
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  return !/^(true|false)$/i.test(trimmed);
+}
+
 export function extractNodeText(
   node: Pick<RawSnapshotNode, 'label' | 'value' | 'identifier'>,
 ): string {

src/daemon/screenshot-overlay.ts

@@ -14,6 +14,7 @@ import {
 import { analyzeReactNativeOverlay } from '../core/react-native-overlay.ts';
 import {
   findNearestAncestor,
+  isMeaningfulSignal,
   isViewportRootNode,
   normalizeType,
 } from '@agent-device/contracts/snapshot';
@@ -296,14 +297,6 @@ function isUsableOverlayTarget(node: SnapshotNode | null): node is SnapshotNode
   return Boolean(node?.rect && hasPositiveRect(node.rect) && !isViewportRootNode(node));
 }
 
-function isMeaningfulSignal(value: string | undefined): boolean {
-  if (typeof value !== 'string') return false;
-  const trimmed = value.trim();
-  if (!trimmed) return false;
-  if (/^(true|false)$/i.test(trimmed)) return false;
-  return true;
-}
-
 function isOverlaySignal(value: string | undefined): boolean {
   if (!isMeaningfulSignal(value)) return false;
   return !isGenericOverlayLabel(value);