refactor(contracts): one viewport-root predicate for the whole repo

"Is this the Application/Window root" was written nine times: three
spellings normalizing `type|role|subrole`, five lowercasing `type` alone,
and one comparing the normalized type for EQUALITY. Two of the nine sat
in `contracts/snapshot-visibility.ts` itself, disagreeing with each other.

Measured before collapsing, using #1592's method — ground the comparison
in what each backend ACTUALLY emits, not in fixture strings. Over the 31
names iOS's `elementTypeName` can return, the 18 fully-qualified class
names Android emits, and the 24 mapped/raw forms the macOS helper
produces, the nine agreed on 71 of 73. The two exceptions are macOS
window subroles, and the only spelling that disagreed is maestro's `===`,
whose platform union is `android | ios` — so it can never see them. The
duplication was textual, not behavioral, which is what made the collapse
safe.

`isViewportRootNode` reads role and subrole because the macOS helper is
the only backend populating them and the only one able to emit a window
whose `type` does not say so: `normalizedSnapshotType` returns the raw
subrole for a non-standard window, so an `AXWindow` with subrole
`AXSystemDialog` or `AXUnknown` reads as neither from `type` alone. Those
two shapes are the whole behavioral delta of this change, at the six
call sites that were type-only, and they are windows by role.

`snapshot-viewport-root.test.ts` pins the predicate over those three
emitted vocabularies. Red evidence: reverting the canonical definition to
the type-only spelling fails 2 of 5 cells, to the equality spelling 4 of 5.

Also drops two kernel re-declarations this made visible: maestro's local
`containsPoint` and `rectsOverlap` were character-identical to
`@agent-device/kernel/rect`'s `containsPoint` and `isRectVisibleInViewport`,
in a file that already imports from that module. And `resolveViewportRect`
loses three `as Rect` casts that only existed because `.filter()` cannot
narrow `node.rect` — one `flatMap` states the same thing honestly.

Deliberately NOT in this change: the three viewport RESOLVERS still
diverge, and on Android that is a live defect rather than duplication.
Filed separately with the measurement.

Author: thymikee

packages/contracts/src/facades/snapshot.ts

@@ -5,6 +5,7 @@ export {
   isNodeVisibleInEffectiveViewport,
   isNodeVisibleOnScreen,
   isUsefulVisibilityAnchor,
+  isViewportRootNode,
   isTapPointInsideViewport,
   resolveEffectiveViewportRect,
   resolveViewportRect,

packages/contracts/src/scroll-gesture.ts

@@ -1,5 +1,6 @@
 import { AppError } from '@agent-device/kernel/errors';
 import { defineStringEnum } from './string-enum.ts';
+import { isViewportRootNode } from './snapshot-visibility.ts';
 import type { Rect, SnapshotNode } from '@agent-device/kernel/snapshot';
 
 // What a caller may ASK for, as opposed to `ScrollDirection` (what the gesture resolves to):
@@ -273,7 +274,7 @@ export function parseScrollDirection(direction: string): ScrollDirection {
 
 function inferViewportRect(nodes: Array<Pick<SnapshotNode, 'type' | 'rect'>>): Rect | undefined {
   const candidate = nodes
-    .filter((node) => isViewportNode(node.type) && isValidRect(node.rect))
+    .filter((node) => isViewportRootNode(node) && isValidRect(node.rect))
     .map((node) => node.rect)
     .sort(
       (left, right) =>
@@ -290,12 +291,6 @@ function inferViewportRect(nodes: Array<Pick<SnapshotNode, 'type' | 'rect'>>): R
   return { x: 0, y: 0, width, height };
 }
 
-function isViewportNode(type: string | undefined): boolean {
-  if (!type) return false;
-  const normalized = type.toLowerCase();
-  return normalized.includes('application') || normalized.includes('window');
-}
-
 function isValidRect(rect: Rect | undefined): rect is Rect {
   return !!rect && rect.width > 0 && rect.height > 0;
 }

packages/contracts/src/snapshot-visibility.ts

@@ -15,37 +15,52 @@ type SnapshotVisibilityNode = Pick<
   'rect' | 'index' | 'parentIndex' | 'type' | 'role' | 'subrole'
 >;
 
+/**
+ * The application/window root: the node a target rect is measured against, and
+ * the node whose own rect is invariant under any gesture.
+ *
+ * One definition for the whole repo. It reads `type`, `role` AND `subrole`
+ * because the macOS helper is the only backend that populates the latter two,
+ * and it is the only backend that can emit a window whose `type` does not say
+ * so — `normalizedSnapshotType` returns the raw subrole for a non-standard
+ * window, so an `AXWindow` with subrole `AXSystemDialog` or `AXUnknown` reads
+ * as neither from `type` alone while `role` names it exactly.
+ *
+ * Substring, not equality: macOS emits unmapped roles with their `AX` prefix
+ * intact and subroles like `AXFloatingWindow` that are windows by any reading.
+ * iOS emits a closed set of 31 short names in which only `Application` and
+ * `Window` contain either word, so substring and equality agree there. Android
+ * emits fully-qualified Java class names and no root node at all, so no
+ * spelling of this predicate matches anything on Android — see
+ * `resolveViewportRect`'s third fallback, which is what Android actually uses.
+ */
+export function isViewportRootNode(node: Pick<SnapshotNode, 'type' | 'role' | 'subrole'>): boolean {
+  const kind = [node.type, node.role, node.subrole]
+    .map((value) => normalizeType(value ?? ''))
+    .join(' ');
+  return kind.includes('application') || kind.includes('window');
+}
+
 /**
  * The root viewport a target rect is measured against: the largest
  * Application/Window rect containing the target's center, falling back to the
  * largest such rect, then to the largest containing rect of any node.
  */
 export function resolveViewportRect(nodes: RawSnapshotNode[], targetRect: Rect): Rect | null {
   const targetCenter = centerOfRect(targetRect);
-  const rectNodes = nodes.filter((node) => hasValidRect(node.rect));
-  const viewportNodes = rectNodes.filter((node) => {
-    const type = (node.type ?? '').toLowerCase();
-    return type.includes('application') || type.includes('window');
-  });
-
-  const containingViewport = pickLargestRect(
-    viewportNodes
-      .map((node) => node.rect as Rect)
-      .filter((rect) => containsPoint(rect, targetCenter.x, targetCenter.y)),
+  const rects = nodes.flatMap((node) =>
+    hasValidRect(node.rect) ? [{ node, rect: node.rect }] : [],
   );
-  if (containingViewport) return containingViewport;
-
-  const viewportFallback = pickLargestRect(viewportNodes.map((node) => node.rect as Rect));
-  if (viewportFallback) return viewportFallback;
+  const viewportRects = rects
+    .filter((entry) => isViewportRootNode(entry.node))
+    .map((entry) => entry.rect);
+  const contains = (rect: Rect) => containsPoint(rect, targetCenter.x, targetCenter.y);
 
-  const genericContaining = pickLargestRect(
-    rectNodes
-      .map((node) => node.rect as Rect)
-      .filter((rect) => containsPoint(rect, targetCenter.x, targetCenter.y)),
+  return (
+    pickLargestRect(viewportRects.filter(contains)) ??
+    pickLargestRect(viewportRects) ??
+    pickLargestRect(rects.map((entry) => entry.rect).filter(contains))
   );
-  if (genericContaining) return genericContaining;
-
-  return null;
 }
 
 function hasValidRect(rect: Rect | undefined): rect is Rect {

packages/maestro/src/internal/runtime-port-geometry.ts

@@ -6,7 +6,7 @@ import { pointInsideRect } from './shared.ts';
 import {
   findNearestScrollableAncestor,
   isScrollableNodeLike,
-  normalizeType,
+  isViewportRootNode,
 } from '@agent-device/contracts/snapshot';
 import { MAESTRO_COMPATIBILITY_PRESETS } from './compatibility-policy.ts';
 import { resolveNumeric } from './engine-flow.ts';
@@ -108,8 +108,7 @@ function findScrollContainer(
 function findLargestViewportRect(nodes: SnapshotState['nodes']): Rect | undefined {
   return nodes
     .filter((node) => {
-      const type = normalizeType(node.type ?? '');
-      return isPositiveFiniteRect(node.rect) && (type === 'application' || type === 'window');
+      return isPositiveFiniteRect(node.rect) && isViewportRootNode(node);
     })
     .sort(
       (left, right) =>

packages/maestro/src/internal/snapshot-policy.ts

@@ -3,8 +3,13 @@ import {
   findNearestScrollableAncestor,
   findSnapshotAncestor,
   isUsefulVisibilityAnchor,
+  isViewportRootNode,
 } from '@agent-device/contracts/snapshot';
-import { isPositiveFiniteRect } from '@agent-device/kernel/rect';
+import {
+  containsPoint,
+  isPositiveFiniteRect,
+  isRectVisibleInViewport,
+} from '@agent-device/kernel/rect';
 import type { Rect, SnapshotNode } from '@agent-device/kernel/snapshot';
 
 export function isMaestroNodeVisible(
@@ -47,15 +52,12 @@ function isVisibleInEffectiveViewport(node: SnapshotNode, nodes: SnapshotNode[])
   const viewport =
     findNearestScrollableAncestor(node, byIndex, (ancestor) => Boolean(ancestor.rect))?.rect ??
     resolveRootViewport(nodes, node.rect);
-  return viewport ? rectsOverlap(node.rect, viewport) : true;
+  return viewport ? isRectVisibleInViewport(node.rect, viewport) : true;
 }
 
 function resolveRootViewport(nodes: SnapshotNode[], target: Rect): Rect | null {
   const viewportRects = nodes
-    .filter((node) => {
-      const type = (node.type ?? '').toLowerCase();
-      return node.rect && (type.includes('application') || type.includes('window'));
-    })
+    .filter((node) => node.rect && isViewportRootNode(node))
     .map((node) => node.rect!)
     .sort((left, right) => right.width * right.height - left.width * left.height);
   const centerX = target.x + target.width / 2;
@@ -64,14 +66,3 @@ function resolveRootViewport(nodes: SnapshotNode[], target: Rect): Rect | null {
     viewportRects.find((rect) => containsPoint(rect, centerX, centerY)) ?? viewportRects[0] ?? null
   );
 }
-
-function rectsOverlap(left: Rect, right: Rect): boolean {
-  return (
-    Math.max(left.x, right.x) <= Math.min(left.x + left.width, right.x + right.width) &&
-    Math.max(left.y, right.y) <= Math.min(left.y + left.height, right.y + right.height)
-  );
-}
-
-function containsPoint(rect: Rect, x: number, y: number): boolean {
-  return x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height;
-}

src/core/interaction-targeting.ts

@@ -1,7 +1,7 @@
 import type { Rect, SnapshotNode } from '@agent-device/kernel/snapshot';
 import { centerOfRect } from '@agent-device/kernel/snapshot';
 import { containsPoint, pickLargestRect } from '@agent-device/kernel/rect';
-import { normalizeType } from '@agent-device/contracts/snapshot';
+import { normalizeType, isViewportRootNode } from '@agent-device/contracts/snapshot';
 import { findNearestHittableAncestor } from '../snapshot/snapshot-processing.ts';
 import { isSnapshotNodeInteractionBlocked } from '../snapshot/snapshot-occlusion.ts';
 import {
@@ -158,10 +158,7 @@ function isScrollingContainer(node: SnapshotNode): boolean {
 function resolveRootViewportRect(nodes: SnapshotNode[], targetRect: Rect): Rect | null {
   const targetCenter = centerOfRect(targetRect);
   const viewportRects = nodes
-    .filter((node) => {
-      const type = (node.type ?? '').toLowerCase();
-      return type.includes('application') || type.includes('window');
-    })
+    .filter(isViewportRootNode)
     .map((node) => normalizeRect(node.rect))
     .filter((rect): rect is Rect => rect !== null);
   if (viewportRects.length === 0) return null;

src/daemon/handlers/find.ts

@@ -1,4 +1,5 @@
 import { dispatchCommand } from '../../core/dispatch.ts';
+import { isViewportRootNode } from '@agent-device/contracts/snapshot';
 import {
   findBestMatchesByLocator,
   isReadOnlyFindAction,
@@ -371,8 +372,7 @@ function isRootInteractionContainer(
   root: SnapshotState['nodes'][number] | undefined,
 ): boolean {
   if (!root?.rect || !node.rect) return false;
-  const type = node.type?.toLowerCase() ?? '';
-  if (!type.includes('application') && !type.includes('window')) return false;
+  if (!isViewportRootNode(node)) return false;
   return rectsMatch(node.rect, root.rect);
 }
 

src/daemon/interaction-outcome-policy.ts

@@ -3,7 +3,7 @@ import { isMobilePlatform } from '@agent-device/kernel/device';
 import type { SnapshotNode, SnapshotState } from '@agent-device/kernel/snapshot';
 import { collectKeyboardChromeRefs } from '../core/snapshot-chrome.ts';
 import { emitDiagnostic } from '../utils/diagnostics.ts';
-import { normalizeType } from '@agent-device/contracts/snapshot';
+import { isViewportRootNode } from '@agent-device/contracts/snapshot';
 import { contextFromFlags } from './context.ts';
 import type { SessionState } from './types.ts';
 
@@ -390,22 +390,7 @@ function isNonDiscriminatingSurfaceNode(
   node: SnapshotNode,
   keyboardChromeRefs: ReadonlySet<string>,
 ): boolean {
-  return isViewportRootKind(node) || (node.ref !== undefined && keyboardChromeRefs.has(node.ref));
-}
-
-/**
- * Minimal local equivalent of `isViewportRoot` in
- * `src/snapshot/snapshot-occlusion.ts` (source of truth) — that function is
- * module-private and keyed off the broader `RawSnapshotNode` shape used by
- * occlusion/viewport resolution, so it is reimplemented here rather than
- * exported solely for this caller. Same normalized-kind substring test; keep
- * the two in lockstep if the underlying AX vocabulary changes.
- */
-function isViewportRootKind(node: Pick<SnapshotNode, 'type' | 'role' | 'subrole'>): boolean {
-  const normalizedKind = [node.type, node.role, node.subrole]
-    .map((value) => normalizeType(value ?? ''))
-    .join(' ');
-  return normalizedKind.includes('application') || normalizedKind.includes('window');
+  return isViewportRootNode(node) || (node.ref !== undefined && keyboardChromeRefs.has(node.ref));
 }
 
 function interactionSurfaceSemanticKey(node: SnapshotNode): string | undefined {

src/daemon/screenshot-overlay.ts

@@ -9,7 +9,7 @@ import {
 import type { PNG } from '../utils/png.ts';
 import { decodePngAsync, encodePngAsync } from '../utils/png-worker-client.ts';
 import { analyzeReactNativeOverlay } from '../core/react-native-overlay.ts';
-import { normalizeType } from '@agent-device/contracts/snapshot';
+import { isViewportRootNode, normalizeType } from '@agent-device/contracts/snapshot';
 import { findNearestAncestor } from '../snapshot/snapshot-processing.ts';
 import { resolveAndroidOverlaySourceRect } from './screenshot-overlay-android.ts';
 import { hasPositiveRect, rectArea, rectContains } from './screenshot-overlay-rects.ts';
@@ -212,7 +212,7 @@ function isAndroidUnlabeledClickableSource(
   node: SnapshotNode,
 ): boolean {
   if (snapshot.backend !== 'android') return false;
-  if (!node.hittable || !hasPositiveRect(node.rect) || isViewportLikeNode(node)) return false;
+  if (!node.hittable || !hasPositiveRect(node.rect) || isViewportRootNode(node)) return false;
   const normalizedType = normalizeType(node.type ?? '');
   if (ANDROID_UNLABELED_CLICKABLE_EXCLUDED_TYPES.some((type) => normalizedType.includes(type))) {
     return false;
@@ -318,7 +318,7 @@ function projectRectToScreenshot(
 function resolveSnapshotBounds(nodes: SnapshotState['nodes']): Rect | null {
   let viewport: Rect | null = null;
   for (const node of nodes) {
-    if (!isViewportLikeNode(node) || !hasPositiveRect(node.rect)) continue;
+    if (!isViewportRootNode(node) || !hasPositiveRect(node.rect)) continue;
     if (!viewport || rectArea(node.rect) > rectArea(viewport)) {
       viewport = node.rect;
     }
@@ -366,7 +366,7 @@ function hasActionableRole(node: SnapshotNode): boolean {
 }
 
 function isOverlayActionableNode(node: SnapshotNode): boolean {
-  return hasActionableRole(node) && !isViewportLikeNode(node);
+  return hasActionableRole(node) && !isViewportRootNode(node);
 }
 
 function isProxyOverlayNode(node: SnapshotNode): boolean {
@@ -379,15 +379,8 @@ function isProxyOverlayNode(node: SnapshotNode): boolean {
   );
 }
 
-function isViewportLikeNode(node: Pick<SnapshotNode, 'type' | 'role' | 'subrole'>): boolean {
-  const roleText = [node.type, node.role, node.subrole]
-    .map((value) => normalizeType(value ?? ''))
-    .join(' ');
-  return roleText.includes('application') || roleText.includes('window');
-}
-
 function isUsableOverlayTarget(node: SnapshotNode | null): node is SnapshotNode {
-  return Boolean(node?.rect && hasPositiveRect(node.rect) && !isViewportLikeNode(node));
+  return Boolean(node?.rect && hasPositiveRect(node.rect) && !isViewportRootNode(node));
 }
 
 function isMeaningfulSignal(value: string | undefined): boolean {

src/snapshot/snapshot-occlusion.ts

@@ -2,7 +2,7 @@ import type { RawSnapshotNode, Rect } from '@agent-device/kernel/snapshot';
 import { centerOfRect } from '@agent-device/kernel/snapshot';
 import { areRectsApproximatelyEqual, normalizeRect } from '../utils/rect-center.ts';
 import { containsPoint } from '@agent-device/kernel/rect';
-import { normalizeType } from '@agent-device/contracts/snapshot';
+import { normalizeType, isViewportRootNode } from '@agent-device/contracts/snapshot';
 
 const COVERED_PRESENTATION_HINT = 'covered';
 const OVERLAY_KIND_FRAGMENTS = [
@@ -220,7 +220,7 @@ function isOverlayLikeNode(
   options: SnapshotOcclusionOptions,
 ): boolean {
   if (!positiveRect(node.rect)) return false;
-  if (isViewportRoot(node)) return false;
+  if (isViewportRootNode(node)) return false;
   if (isFullViewportChromeContainer(node, byIndex)) return false;
   // This is a presentation-order heuristic: only known floating UI chrome should cover
   // later targets. Generic hittable containers can appear later without being visually on top.
@@ -241,7 +241,7 @@ function isFullViewportChromeContainer(
   let current = typeof node.parentIndex === 'number' ? byIndex.get(node.parentIndex) : undefined;
   const visited = new Set<number>();
   while (current && !visited.has(current.index)) {
-    if (isViewportRoot(current)) {
+    if (isViewportRootNode(current)) {
       const viewportRect = positiveRect(current.rect);
       return Boolean(viewportRect && areRectsApproximatelyEqual(rect, viewportRect));
     }
@@ -295,7 +295,7 @@ function isRenderableAdditionalOverlayNode(
   return (
     options.isAdditionalOverlayNode?.(node) === true &&
     positiveRect(node.rect) !== null &&
-    !isViewportRoot(node)
+    !isViewportRootNode(node)
   );
 }
 
@@ -321,11 +321,6 @@ function normalizeNodeKind(node: Pick<RawSnapshotNode, 'type' | 'role' | 'subrol
   return [node.type, node.role, node.subrole].map((value) => normalizeType(value ?? '')).join(' ');
 }
 
-function isViewportRoot(node: RawSnapshotNode): boolean {
-  const normalized = normalizeNodeKind(node);
-  return normalized.includes('application') || normalized.includes('window');
-}
-
 function areRelatedSnapshotNodes(
   left: RawSnapshotNode,
   right: RawSnapshotNode,