callstack · thymikee · Apr 1, 2026 · Apr 1, 2026
diff --git a/src/__tests__/client.test.ts b/src/__tests__/client.test.ts
@@ -346,3 +346,30 @@ test('client throws AppError for daemon failures', async () => {
     },
   );
 });
+
+test('client capture.snapshot preserves visibility metadata from daemon responses', async () => {
+  const setup = createTransport(async () => ({
+    ok: true,
+    data: {
+      nodes: [],
+      truncated: false,
+      appBundleId: 'com.expensify.chat.dev',
+      visibility: {
+        partial: true,
+        visibleNodeCount: 64,
+        totalNodeCount: 67,
+        reasons: ['offscreen-nodes'],
+      },
+    },
+  }));
+  const client = createAgentDeviceClient(setup.config, { transport: setup.transport });
+
+  const result = await client.capture.snapshot();
+
+  assert.deepEqual(result.visibility, {
+    partial: true,
+    visibleNodeCount: 64,
+    totalNodeCount: 67,
+    reasons: ['offscreen-nodes'],
+  });
+});
diff --git a/src/client-shared.ts b/src/client-shared.ts
@@ -185,6 +185,7 @@ export function serializeSnapshotResult(result: CaptureSnapshotResult): Record<s
     truncated: result.truncated,
     ...(result.appName ? { appName: result.appName } : {}),
     ...(result.appBundleId ? { appBundleId: result.appBundleId } : {}),
+    ...(result.visibility ? { visibility: result.visibility } : {}),
     ...(result.warnings && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
   };
 }
diff --git a/src/client-types.ts b/src/client-types.ts
@@ -6,7 +6,7 @@ import type {
   SessionRuntimeHints,
 } from './daemon/types.ts';
 import type { DeviceKind, DeviceTarget, Platform, PlatformSelector } from './utils/device.ts';
-import type { ScreenshotOverlayRef, SnapshotNode } from './utils/snapshot.ts';
+import type { ScreenshotOverlayRef, SnapshotNode, SnapshotVisibility } from './utils/snapshot.ts';
 import type { MetroPrepareKind, PrepareMetroRuntimeResult } from './client-metro.ts';
 
 type DaemonTransportMode = 'auto' | 'socket' | 'http';
@@ -254,6 +254,7 @@ export type CaptureSnapshotResult = {
   truncated: boolean;
   appName?: string;
   appBundleId?: string;
+  visibility?: SnapshotVisibility;
   warnings?: string[];
   identifiers: AgentDeviceIdentifiers;
 };

diff --git a/src/client.ts b/src/client.ts
@@ -29,6 +29,7 @@ import type {
   AppOpenOptions,
   CaptureScreenshotOptions,
   CaptureSnapshotOptions,
+  CaptureSnapshotResult,
   EnsureSimulatorOptions,
   InternalRequestOptions,
   MaterializationReleaseOptions,
@@ -215,11 +216,16 @@ export function createAgentDeviceClient(
         const session = resolveSessionName(config.session, options.session);
         const data = await execute('snapshot', [], options);
         const appBundleId = readOptionalString(data, 'appBundleId');
+        const visibility =
+          typeof data.visibility === 'object' && data.visibility !== null
+            ? (data.visibility as CaptureSnapshotResult['visibility'])
+            : undefined;
         return {
           nodes: readSnapshotNodes(data.nodes),
           truncated: data.truncated === true,
           appName: readOptionalString(data, 'appName'),
           appBundleId,
+          ...(visibility ? { visibility } : {}),
           warnings: Array.isArray(data.warnings)
             ? data.warnings.filter((entry): entry is string => typeof entry === 'string')
             : undefined,

diff --git a/src/daemon/handlers/__tests__/snapshot-handler.test.ts b/src/daemon/handlers/__tests__/snapshot-handler.test.ts
@@ -332,6 +332,60 @@ test('snapshot warns when Android freshness retries still return the previous ro
   expect(mockDispatch).toHaveBeenCalledTimes(3);
 });
 
+test('snapshot response includes normalized visibility metadata', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-visibility';
+  sessionStore.set(sessionName, makeSession(sessionName, androidDevice));
+
+  mockDispatch.mockResolvedValue({
+    nodes: [
+      {
+        index: 0,
+        depth: 0,
+        type: 'android.widget.ScrollView',
+        label: 'Messages',
+        rect: { x: 0, y: 100, width: 390, height: 500 },
+        hiddenContentBelow: true,
+      },
+      {
+        index: 1,
+        depth: 1,
+        parentIndex: 0,
+        type: 'android.widget.Button',
+        label: 'Visible message',
+        rect: { x: 0, y: 140, width: 390, height: 48 },
+        hittable: true,
+      },
+    ],
+    truncated: false,
+    backend: 'android',
+    analysis: { rawNodeCount: 2, maxDepth: 1 },
+  });
+
+  const response = await handleSnapshotCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'snapshot',
+      positionals: [],
+      flags: { snapshotInteractiveOnly: true },
+    },
+    sessionName,
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+  });
+
+  expect(response?.ok).toBe(true);
+  if (response?.ok) {
+    expect(response.data?.visibility).toEqual({
+      partial: true,
+      visibleNodeCount: 2,
+      totalNodeCount: 2,
+      reasons: ['scroll-hidden-below'],
+    });
+  }
+});
+
 test('diff snapshot carries stale-tree warnings for recent Android presses', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'android-diff-stale-after-press';

diff --git a/src/daemon/handlers/snapshot-capture.ts b/src/daemon/handlers/snapshot-capture.ts
@@ -7,8 +7,10 @@ import {
   normalizeRef,
   type RawSnapshotNode,
   type SnapshotState,
+  type SnapshotVisibility,
 } from '../../utils/snapshot.ts';
 import { normalizeSnapshotTree } from '../../utils/snapshot-tree.ts';
+import { buildMobileSnapshotPresentation } from '../../utils/mobile-snapshot-semantics.ts';
 import type { DaemonResponse, SessionState } from '../types.ts';
 import {
   ANDROID_FRESHNESS_RETRY_DELAYS_MS,
@@ -202,6 +204,41 @@ export function buildSnapshotState(
   };
 }
 
+export function buildSnapshotVisibility(params: {
+  nodes: SnapshotState['nodes'];
+  backend?: SnapshotState['backend'];
+  snapshotRaw?: boolean;
+}): SnapshotVisibility {
+  const { nodes, backend, snapshotRaw } = params;
+  if (snapshotRaw || backend === 'macos-helper') {
+    return {
+      partial: false,
+      visibleNodeCount: nodes.length,
+      totalNodeCount: nodes.length,
+      reasons: [],
+    };
+  }
+
+  const presentation = buildMobileSnapshotPresentation(nodes);
+  const reasons = new Set<SnapshotVisibility['reasons'][number]>();
+  if (presentation.hiddenCount > 0) {
+    reasons.add('offscreen-nodes');
+  }
+  if (presentation.nodes.some((node) => node.hiddenContentAbove)) {
+    reasons.add('scroll-hidden-above');
+  }
+  if (presentation.nodes.some((node) => node.hiddenContentBelow)) {
+    reasons.add('scroll-hidden-below');
+  }
+
+  return {
+    partial: reasons.size > 0,
+    visibleNodeCount: presentation.nodes.length,
+    totalNodeCount: nodes.length,
+    reasons: [...reasons],
+  };
+}
+
 function shapeMacOsSurfaceSnapshot(
   data: SnapshotData,
   options: {

diff --git a/src/daemon/handlers/snapshot.ts b/src/daemon/handlers/snapshot.ts
@@ -2,7 +2,11 @@ import { isCommandSupportedOnDevice } from '../../core/capabilities.ts';
 import type { DaemonRequest, DaemonResponse, SessionState } from '../types.ts';
 import { SessionStore } from '../session-store.ts';
 import { buildSnapshotDiff, countSnapshotComparableLines } from '../snapshot-diff.ts';
-import { captureSnapshot, resolveSnapshotScope } from './snapshot-capture.ts';
+import {
+  buildSnapshotVisibility,
+  captureSnapshot,
+  resolveSnapshotScope,
+} from './snapshot-capture.ts';
 import {
   buildSnapshotSession,
   recordIfSession,
@@ -60,6 +64,11 @@ export async function handleSnapshotCommands(params: {
         flags: req.flags,
         session,
       });
+      const visibility = buildSnapshotVisibility({
+        nodes: capture.snapshot.nodes,
+        backend: capture.snapshot.backend,
+        snapshotRaw: req.flags?.snapshotRaw,
+      });
       const nextSession = buildSnapshotSession({
         session,
         sessionName,
@@ -77,6 +86,7 @@ export async function handleSnapshotCommands(params: {
         data: {
           nodes: capture.snapshot.nodes,
           truncated: capture.snapshot.truncated ?? false,
+          visibility,
           ...(warnings.length > 0 ? { warnings } : {}),
           appName: nextSession.appBundleId
             ? (nextSession.appName ?? nextSession.appBundleId)

diff --git a/src/platforms/android/__tests__/scroll-hints.test.ts b/src/platforms/android/__tests__/scroll-hints.test.ts
@@ -108,3 +108,150 @@ test('annotateAndroidScrollableContentHints marks bottomed-out scroll areas with
   assert.equal(nodes[0].hiddenContentAbove, true);
   assert.equal(nodes[0].hiddenContentBelow, undefined);
 });
+
+test('annotateAndroidScrollableContentHints infers bottomed-out scroll areas from a single aligned block', () => {
+  const nodes: RawSnapshotNode[] = [
+    {
+      index: 0,
+      type: 'android.widget.ScrollView',
+      label: 'Messages',
+      rect: { x: 0, y: 100, width: 390, height: 500 },
+      depth: 0,
+    },
+    {
+      index: 1,
+      type: 'android.view.ViewGroup',
+      rect: { x: 0, y: 100, width: 390, height: 500 },
+      depth: 1,
+      parentIndex: 0,
+    },
+    {
+      index: 2,
+      type: 'android.view.ViewGroup',
+      rect: { x: 0, y: 432, width: 390, height: 168 },
+      depth: 2,
+      parentIndex: 1,
+    },
+  ];
+
+  const dump = [
+    '    com.facebook.react.views.scroll.ReactScrollView{d32a800 VFED.V... ........ 0,0-390,500 #4b2}',
+    '      com.facebook.react.views.view.ReactViewGroup{77d31ae V.E...... ........ 0,0-390,804 #4b0}',
+    '        com.facebook.react.views.view.ReactViewGroup{c V.E...... ........ 0,636-390,804 #3}',
+  ].join('\n');
+
+  annotateAndroidScrollableContentHints(nodes, dump);
+
+  assert.equal(nodes[0].hiddenContentAbove, true);
+  assert.equal(nodes[0].hiddenContentBelow, undefined);
+});
+
+test('annotateAndroidScrollableContentHints infers virtualized scroll coverage without a unique block offset', () => {
+  const nodes: RawSnapshotNode[] = [
+    {
+      index: 0,
+      type: 'android.widget.ScrollView',
+      label: 'Messages',
+      rect: { x: 0, y: 100, width: 390, height: 500 },
+      depth: 0,
+    },
+    {
+      index: 1,
+      type: 'android.view.ViewGroup',
+      rect: { x: 0, y: 100, width: 390, height: 500 },
+      depth: 1,
+      parentIndex: 0,
+    },
+    {
+      index: 2,
+      type: 'android.view.ViewGroup',
+      rect: { x: 0, y: 100, width: 390, height: 143 },
+      depth: 2,
+      parentIndex: 1,
+    },
+    ...Array.from({ length: 11 }, (_value, index) => ({
+      index: index + 3,
+      type: 'android.view.ViewGroup',
+      rect: { x: 0, y: 243 + index * 192, width: 390, height: 192 },
+      depth: 2,
+      parentIndex: 1,
+    })),
+  ];
+
+  const dump = [
+    '    com.facebook.react.views.scroll.ReactScrollView{d32a800 VFED.V... ........ 0,0-390,500 #4b2}',
+    '      com.facebook.react.views.view.ReactViewGroup{77d31ae V.E...... ........ 0,0-390,853 #4b0}',
+    '        com.facebook.react.views.view.ReactViewGroup{a V.E...... ........ 0,285-390,477 #1}',
+    '        com.facebook.react.views.view.ReactViewGroup{b V.E...... ........ 0,477-390,669 #2}',
+    '        com.facebook.react.views.view.ReactViewGroup{c V.E...... ........ 0,669-390,861 #3}',
+    '        com.facebook.react.views.view.ReactViewGroup{d V.E...... ........ 0,861-390,1053 #4}',
+    '        com.facebook.react.views.view.ReactViewGroup{e V.E...... ........ 0,1053-390,1245 #5}',
+    '        com.facebook.react.views.view.ReactViewGroup{f V.E...... ........ 0,1245-390,1437 #6}',
+  ].join('\n');
+
+  annotateAndroidScrollableContentHints(nodes, dump);
+
+  assert.equal(nodes[0].hiddenContentAbove, true);
+  assert.equal(nodes[0].hiddenContentBelow, true);
+});
+
+test('annotateAndroidScrollableContentHints keeps shallow offset matching for fully mounted content', () => {
+  const nodes: RawSnapshotNode[] = [
+    {
+      index: 0,
+      type: 'android.widget.ScrollView',
+      label: 'Messages',
+      rect: { x: 0, y: 100, width: 390, height: 500 },
+      depth: 0,
+    },
+    {
+      index: 1,
+      type: 'android.view.ViewGroup',
+      rect: { x: 0, y: 100, width: 390, height: 500 },
+      depth: 1,
+      parentIndex: 0,
+    },
+    {
+      index: 2,
+      type: 'android.view.ViewGroup',
+      rect: { x: 0, y: 100, width: 390, height: 100 },
+      depth: 2,
+      parentIndex: 1,
+    },
+    {
+      index: 3,
+      type: 'android.view.ViewGroup',
+      rect: { x: 0, y: 200, width: 390, height: 180 },
+      depth: 2,
+      parentIndex: 1,
+    },
+    {
+      index: 4,
+      type: 'android.view.ViewGroup',
+      rect: { x: 0, y: 380, width: 390, height: 120 },
+      depth: 2,
+      parentIndex: 1,
+    },
+    {
+      index: 5,
+      type: 'android.view.ViewGroup',
+      rect: { x: 0, y: 500, width: 390, height: 100 },
+      depth: 2,
+      parentIndex: 1,
+    },
+  ];
+
+  const dump = [
+    '    com.facebook.react.views.scroll.ReactScrollView{d32a800 VFED.V... ........ 0,0-390,500 #4b2}',
+    '      com.facebook.react.views.view.ReactViewGroup{77d31ae V.E...... ........ 0,0-390,520 #4b0}',
+    '        com.facebook.react.views.view.ReactViewGroup{a V.E...... ........ 0,20-390,120 #1}',
+    '        com.facebook.react.views.view.ReactViewGroup{b V.E...... ........ 0,120-390,300 #2}',
+    '        com.facebook.react.views.view.ReactViewGroup{c V.E...... ........ 0,300-390,420 #3}',
+    '        com.facebook.react.views.view.ReactViewGroup{d V.E...... ........ 0,420-390,520 #4}',
+  ].join('\n');
+
+  annotateAndroidScrollableContentHints(nodes, dump);
+
+  assert.equal(nodes[0].hiddenContentAbove, true);
+  assert.equal(nodes[0].hiddenContentBelow, undefined);
+});