refactor(snapshot): establish presentation ownership boundary (#2005)

* refactor(snapshot): establish presentation ownership boundary

* docs: keep context glossary within budget

* fix(snapshot): address presentation boundary review

* test(snapshot): ratchet eager closure budgets

Author: thymikee

CONTEXT.md

@@ -196,6 +196,11 @@ alone.
 **Presentation options**:
 The policy input controlling how one snapshot acquisition becomes a public projection.
 
+**Snapshot presentation facet**:
+The host-side owner of the neutral acquisition-to-presentation contract and TypeScript policies.
+Platform acquisition supplies raw facts and a fold policy; runner-side Swift presentation remains
+separate across the process boundary.
+
 **Capture hint**:
 The acquisition-facing view of a snapshot request, derived once from presentation options. It names
 the projection a backend must serve, keeps raw traversal depth separate from regular presented depth,

docs/adr/0004-ios-snapshot-backend-strategy.md

@@ -63,6 +63,26 @@ The daemon should make degraded output observable. If an iOS interactive snapsho
 application root or another sparse shape, surface a structured quality verdict and warning so
 agents know the snapshot is degraded output rather than proof that the screen has no controls.
 
+## Host-side ownership boundary
+
+The shared TypeScript side has one snapshot-presentation facet. The neutral acquisition-to-presented
+carrier and clip-fold geometry contract live in `@agent-device/contracts/snapshot-presentation`; the
+host-side iOS post-wire policies and shared tree helpers live under `src/snapshot/snapshot-presentation/`.
+Platform-specific presentation adapters retain only the policy mechanics that cannot yet cross their
+runtime boundary. Daemon assembly owns only the ordering of capture, compaction, occlusion, and ref
+publication. It does not own the presentation vocabulary or a second geometry carrier.
+
+Android acquisition remains in its platform module and adapts its raw hierarchy to the shared
+carrier. Swift keeps its runner-side `SnapshotPresentation` implementation because it consumes the
+capture-plan tier before the process boundary. The contract fixture under
+`contracts/fixtures/snapshot-presentation-conformance.json` is the shared proof between those
+runtimes; it does not imply that Swift and TypeScript share an implementation.
+
+This is the first ownership slice of the Wave 4 debt tracked by #1983. Freshness recovery,
+timeout evidence, and screenshot-overlay policy retain their existing daemon adapters until their
+neutral host seams are extracted; new consumers must use the facet rather than add another daemon
+presentation path.
+
 ## Regression Notes
 
 PR #639 made XCTest AX serialization failures explicit instead of swallowing them as empty

fallow-baselines/health.json

@@ -581,7 +581,7 @@
     "src/daemon/session-routing.ts:high impact",
     "src/daemon/handlers/session-state.ts:complexity",
     "src/commands/cli-grammar/common.ts:high impact",
-    "src/daemon/snapshot-presentation/tree.ts:high impact",
+    "src/snapshot/snapshot-presentation/tree.ts:high impact",
     "src/utils/success-text.ts:high impact",
     "src/cli.ts:complexity",
     "src/utils/timeouts.ts:high impact",

packages/contracts/package.json

@@ -7,6 +7,9 @@
   "dependencies": {
     "@agent-device/kernel": "workspace:*"
   },
+  "devDependencies": {
+    "fast-check": "^4.9.0"
+  },
   "exports": {
     "./alert-contract": {
       "types": "./src/alert-contract.ts",
@@ -252,6 +255,10 @@
       "types": "./src/facades/replay.ts",
       "default": "./src/facades/replay.ts"
     },
+    "./react-native-overlay": {
+      "types": "./src/react-native-overlay.ts",
+      "default": "./src/react-native-overlay.ts"
+    },
     "./screen-recording-runtime": {
       "types": "./src/screen-recording-runtime.ts",
       "default": "./src/screen-recording-runtime.ts"
@@ -292,6 +299,10 @@
       "types": "./src/facades/snapshot.ts",
       "default": "./src/facades/snapshot.ts"
     },
+    "./snapshot-presentation": {
+      "types": "./src/snapshot-presentation.ts",
+      "default": "./src/snapshot-presentation.ts"
+    },
     "./snapshot-runtime": {
       "types": "./src/snapshot-runtime.ts",
       "default": "./src/snapshot-runtime.ts"

packages/contracts/src/react-native-overlay.ts

@@ -0,0 +1,67 @@
+import type { RawSnapshotNode } from '@agent-device/kernel/snapshot';
+
+export type ReactNativeOverlayNode = Pick<
+  RawSnapshotNode,
+  'index' | 'type' | 'role' | 'subrole' | 'label' | 'value' | 'identifier' | 'rect' | 'hittable'
+>;
+
+const COLLAPSED_WARNING_PREFIX_PATTERNS = [
+  /^!,\s+/,
+  /^(warn|warning|error):\s+/,
+  /\b(?:possible\s+)?unhandled (?:promise )?rejection\b/,
+] as const;
+const COLLAPSED_WARNING_TEXT_MARKERS = [
+  'open debugger to view warnings',
+  'getsnapshot should be cached to avoid an infinite loop',
+  'unique "key" prop',
+  "unique 'key' prop",
+  'virtualizedlists should never be nested',
+  'failed prop type',
+] as const;
+
+export function isReactNativeCollapsedWarningWrapperCandidate(
+  node: ReactNativeOverlayNode,
+): boolean {
+  return (
+    isReactNativeCollapsedWarningLabel(node.label?.trim()) && isFullScreenOverlayRect(node.rect)
+  );
+}
+
+export function isReactNativeCollapsedWarningWrapperWithVisibleBanner(
+  node: ReactNativeOverlayNode,
+  descendants: ReactNativeOverlayNode[],
+): boolean {
+  const nodeLabel = node.label?.trim();
+  if (!nodeLabel || !isReactNativeCollapsedWarningWrapperCandidate(node)) return false;
+  return descendants.some(
+    (descendant) =>
+      descendant.label?.trim() === nodeLabel && isReactNativeCollapsedWarningBanner(descendant),
+  );
+}
+
+export function isReactNativeCollapsedWarningLabel(rawLabel: string | undefined): boolean {
+  const label = rawLabel?.trim().toLowerCase();
+  if (!label) return false;
+  return (
+    COLLAPSED_WARNING_TEXT_MARKERS.some((marker) => label.includes(marker)) ||
+    COLLAPSED_WARNING_PREFIX_PATTERNS.some((pattern) => pattern.test(label))
+  );
+}
+
+export function isReactNativeOverlayDismissLabel(label: string): boolean {
+  return /^dismiss(?:\s*\([^)]*\))?$/i.test(label);
+}
+
+export function isReactNativeOverlayMinimizeLabel(label: string): boolean {
+  return /^minimi[sz]e(?:\b|\s|\()/i.test(label);
+}
+
+export function isReactNativeCollapsedWarningBanner(node: ReactNativeOverlayNode): boolean {
+  if (!node.rect) return false;
+  return node.rect.width >= 120 && node.rect.height >= 36 && node.rect.height <= 180;
+}
+
+function isFullScreenOverlayRect(rect: RawSnapshotNode['rect']): boolean {
+  if (!rect) return false;
+  return rect.x <= 1 && rect.y <= 1 && rect.width >= 300 && rect.height >= 600;
+}

packages/contracts/src/snapshot-presentation.test.ts

@@ -0,0 +1,98 @@
+import { expect, test } from 'vitest';
+import type { RawSnapshotNode } from '@agent-device/kernel/snapshot';
+import fc from 'fast-check';
+import {
+  createSnapshotPresentationNode,
+  foldSnapshotRect,
+  serializeRegularSnapshotPresentationNode,
+} from './snapshot-presentation.ts';
+
+const rawNode: RawSnapshotNode = {
+  index: 7,
+  type: 'Button',
+  label: 'Save',
+  rect: { x: 0, y: 0, width: 100, height: 80 },
+  hittable: true,
+};
+
+const rectArb = fc.record({
+  x: fc.integer({ min: -500, max: 500 }),
+  y: fc.integer({ min: -500, max: 500 }),
+  width: fc.integer({ min: -20, max: 500 }),
+  height: fc.integer({ min: -20, max: 500 }),
+});
+
+const positiveRectArb = fc.record({
+  x: fc.integer({ min: -500, max: 500 }),
+  y: fc.integer({ min: -500, max: 500 }),
+  width: fc.integer({ min: 1, max: 500 }),
+  height: fc.integer({ min: 1, max: 500 }),
+});
+
+test('the shared fold carries both viewport and ancestor clipping into effective geometry', () => {
+  expect(
+    foldSnapshotRect(
+      rawNode.rect,
+      { x: 20, y: 10, width: 50, height: 50 },
+      { x: 30, y: 20, width: 100, height: 20 },
+    ),
+  ).toEqual({ x: 30, y: 20, width: 40, height: 20 });
+});
+
+test('regular serialization publishes effective geometry and fails closed on degenerate clips', () => {
+  const presented = createSnapshotPresentationNode(rawNode, {
+    x: 30,
+    y: 20,
+    width: 40,
+    height: 20,
+  });
+  expect(serializeRegularSnapshotPresentationNode(presented)).toEqual({
+    ...rawNode,
+    rect: { x: 30, y: 20, width: 40, height: 20 },
+    hittable: true,
+  });
+
+  expect(
+    serializeRegularSnapshotPresentationNode(
+      createSnapshotPresentationNode(rawNode, { x: 30, y: 20, width: 0, height: 20 }),
+    ),
+  ).toEqual({
+    ...rawNode,
+    rect: { x: 30, y: 20, width: 0, height: 20 },
+    hittable: undefined,
+  });
+});
+
+test('property: effective geometry stays inside every positive clip and never upgrades actionability', () => {
+  fc.assert(
+    fc.property(rectArb, positiveRectArb, positiveRectArb, (reported, viewport, ancestorClip) => {
+      const effective = foldSnapshotRect(reported, viewport, ancestorClip);
+      const raw = { index: 0, depth: 0, rect: reported, hittable: true as const };
+      const presented = createSnapshotPresentationNode(raw, effective);
+      const regular = serializeRegularSnapshotPresentationNode(presented);
+
+      expect(presented.raw.rect).toEqual(reported);
+      expect(regular.rect).toEqual(effective);
+      if (effective && effective.width > 0 && effective.height > 0) {
+        expect(rectContains(viewport, effective)).toBe(true);
+        expect(rectContains(ancestorClip, effective)).toBe(true);
+        expect(regular.hittable).toBe(true);
+      } else {
+        expect(regular.hittable).toBeUndefined();
+      }
+    }),
+    { numRuns: 100 },
+  );
+});
+
+function rectContains(
+  outer: { x: number; y: number; width: number; height: number },
+  inner: { x: number; y: number; width: number; height: number },
+): boolean {
+  return (
+    inner.x >= outer.x &&
+    inner.y >= outer.y &&
+    inner.x + inner.width <= outer.x + Math.max(0, outer.width) &&
+    inner.y + inner.height <= outer.y + Math.max(0, outer.height)
+  );
+}

packages/contracts/src/snapshot-presentation.ts

@@ -0,0 +1,77 @@
+import type { RawSnapshotNode, Rect } from '@agent-device/kernel/snapshot';
+import { isPositiveFiniteRect } from '@agent-device/kernel/rect';
+
+/**
+ * The typed carrier between acquisition facts and a regular snapshot projection.
+ *
+ * `raw.rect` remains the backend-reported frame for raw output and traversal. A regular
+ * projection must publish `effectiveRect`, after the owning presentation policy has folded its
+ * viewport and ancestor clips. Keeping both values in one contract prevents an adapter from
+ * accidentally publishing acquisition geometry as presented geometry (#1797, #1983).
+ */
+export type SnapshotPresentationNode = {
+  raw: RawSnapshotNode;
+  effectiveRect?: Rect;
+};
+
+export function createSnapshotPresentationNode(
+  raw: RawSnapshotNode,
+  effectiveRect?: Rect,
+): SnapshotPresentationNode {
+  return {
+    raw,
+    ...(effectiveRect ? { effectiveRect } : {}),
+  };
+}
+
+/**
+ * Folds a reported frame through the viewport and the nearest effective ancestor clip.
+ * Empty intersections preserve the reported origin and become zero-area frames, so diagnostics
+ * retain useful coordinates while regular actionability can fail closed.
+ */
+export function foldSnapshotRect(
+  reportedRect: Rect | undefined,
+  viewport: Rect | undefined,
+  ancestorClip: Rect | undefined,
+): Rect | undefined {
+  if (!reportedRect) return undefined;
+  let effective = normalizeRect(reportedRect);
+  if (viewport) effective = intersectRect(effective, viewport);
+  if (ancestorClip) effective = intersectRect(effective, ancestorClip);
+  return effective;
+}
+
+/** Serializes one regular node without allowing its reported frame to cross the presentation seam. */
+export function serializeRegularSnapshotPresentationNode(
+  node: SnapshotPresentationNode,
+): RawSnapshotNode {
+  return {
+    ...node.raw,
+    ...(node.effectiveRect ? { rect: node.effectiveRect } : { rect: undefined }),
+    hittable:
+      node.raw.hittable === true && isPositiveFiniteRect(node.effectiveRect) ? true : undefined,
+  };
+}
+
+function intersectRect(left: Rect, right: Rect): Rect {
+  const x = Math.max(left.x, right.x);
+  const y = Math.max(left.y, right.y);
+  const maxX = Math.min(left.x + left.width, right.x + right.width);
+  const maxY = Math.min(left.y + left.height, right.y + right.height);
+  const hasIntersection = maxX > x && maxY > y;
+  return {
+    x: hasIntersection ? x : left.x,
+    y: hasIntersection ? y : left.y,
+    width: hasIntersection ? maxX - x : 0,
+    height: hasIntersection ? maxY - y : 0,
+  };
+}
+
+function normalizeRect(rect: Rect): Rect {
+  return {
+    x: rect.x,
+    y: rect.y,
+    width: Math.max(0, rect.width),
+    height: Math.max(0, rect.height),
+  };
+}

pnpm-lock.yaml

@@ -54,7 +54,6 @@ const PINNED_TEST_FILE_LINES: Readonly<Record<string, number>> = Object.freeze({
   'src/daemon/handlers/__tests__/session-replay-divergence.test.ts': 1137,
   'src/platforms/apple/core/__tests__/apps.test.ts': 1210,
   'src/daemon/handlers/__tests__/session-replay-repair-transaction.test.ts': 1208,
-  'src/daemon/snapshot-presentation/ios/presentation.test.ts': 1201,
   'src/daemon/handlers/__tests__/session-replay-target-verification-runtime.test.ts': 1183,
   'src/__tests__/client-metro.test.ts': 1105,
   'src/__tests__/cli-network.test.ts': 1092,

scripts/__tests__/test-file-size-ratchet.test.ts

@@ -32,7 +32,7 @@ test('a TypeScript-only Apple change selects the iOS and macOS lanes without a S
       ),
     );
   }
-  assert.deepEqual(lanes('src/daemon/snapshot-presentation/ios/action-shelf.ts'), [...IOS]);
+  assert.deepEqual(lanes('src/snapshot/snapshot-presentation/ios/action-shelf.ts'), [...IOS]);
   assert.deepEqual(lanes('test/integration/replays/macos/01-desktop.ad'), ['replay-macos']);
 });