fix: hint sparse snapshot fallback

Author: thymikee

src/commands/cli-output.ts

@@ -62,6 +62,7 @@ const cliOutputFormatters: Partial<Record<CommandName, CliOutputFormatter>> = {
       result: result as Parameters<typeof snapshotCliOutput>[0]['result'],
       raw: input.raw as boolean | undefined,
       interactiveOnly: input.interactiveOnly as boolean | undefined,
+      scope: input.scope as string | undefined,
     }),
   wait: messageOutput,
   alert: messageOutput,

src/commands/client-output.ts

@@ -107,6 +107,7 @@ export function snapshotCliOutput(params: {
   result: CaptureSnapshotResult;
   raw?: boolean;
   interactiveOnly?: boolean;
+  scope?: string;
 }): CliOutput {
   const data = serializeSnapshotResult(params.result);
   return {
@@ -116,6 +117,7 @@ export function snapshotCliOutput(params: {
     text: formatSnapshotText(data, {
       raw: params.raw,
       flatten: params.interactiveOnly,
+      scoped: typeof params.scope === 'string' && params.scope.trim().length > 0,
     }),
   };
 }

src/utils/__tests__/output.test.ts

@@ -1296,6 +1296,49 @@ test('formatSnapshotText prints snapshot warnings ahead of empty output', () =>
   assert.match(text, /Interactive snapshot is empty after filtering 42 raw Android nodes/);
 });
 
+test('formatSnapshotText hints to use screenshot overlay refs for sparse snapshots', () => {
+  const text = withNoColor(() =>
+    formatSnapshotText({
+      nodes: [
+        {
+          ref: 'e1',
+          index: 0,
+          depth: 0,
+          type: 'Window',
+          label: 'Main',
+        },
+      ],
+      truncated: false,
+    }),
+  );
+
+  assert.match(text, /Snapshot: 1 node/);
+  assert.match(text, /Hint: sparse accessibility snapshot returned 1 node/);
+  assert.match(text, /screenshot --overlay-refs/);
+});
+
+test('formatSnapshotText suppresses sparse snapshot hint for scoped reads', () => {
+  const text = withNoColor(() =>
+    formatSnapshotText(
+      {
+        nodes: [
+          {
+            ref: 'e1',
+            index: 0,
+            depth: 0,
+            type: 'StaticText',
+            label: 'Expanded details',
+          },
+        ],
+        truncated: false,
+      },
+      { scoped: true },
+    ),
+  );
+
+  assert.doesNotMatch(text, /sparse accessibility snapshot/);
+});
+
 test('formatSnapshotText keeps flattened output and adds duplicate nav warning', () => {
   const nodes = Array.from({ length: 24 }, (_, index) => ({
     ref: `e${index + 1}`,

src/utils/output.ts

@@ -55,9 +55,15 @@ type SnapshotDiffLine = {
   text?: string;
 };
 
+type SnapshotTextOptions = {
+  raw?: boolean;
+  flatten?: boolean;
+  scoped?: boolean;
+};
+
 export function formatSnapshotText(
   data: Record<string, unknown>,
-  options: { raw?: boolean; flatten?: boolean } = {},
+  options: SnapshotTextOptions = {},
 ): string {
   const rawNodes = data.nodes;
   const nodes = Array.isArray(rawNodes) ? (rawNodes as SnapshotNode[]) : [];
@@ -606,10 +612,12 @@ function formatMuted(text: string, useColor: boolean): string {
 function buildSnapshotNotices(
   data: Record<string, unknown>,
   nodes: SnapshotNode[],
-  options: { raw?: boolean; flatten?: boolean },
+  options: SnapshotTextOptions,
   helperPresentation: AndroidHelperPresentationInput = { nodes, filteredCount: 0 },
 ): string[] {
   const notices = readSnapshotWarnings(data);
+  const sparseSnapshotHint = formatSparseSnapshotHint(nodes, options);
+  if (sparseSnapshotHint) notices.push(sparseSnapshotHint);
   if (!options.raw && helperPresentation.filteredCount > 0) {
     notices.push(
       `Collapsed ${helperPresentation.filteredCount} Android helper node${helperPresentation.filteredCount === 1 ? '' : 's'} from the agent-facing text snapshot; use --raw or --json for the full hierarchy.`,
@@ -622,6 +630,15 @@ function buildSnapshotNotices(
   return notices;
 }
 
+function formatSparseSnapshotHint(
+  nodes: SnapshotNode[],
+  options: Pick<SnapshotTextOptions, 'scoped'>,
+): string | null {
+  if (options.scoped === true || nodes.length > 3) return null;
+  const noun = nodes.length === 1 ? 'node' : 'nodes';
+  return `Hint: sparse accessibility snapshot returned ${nodes.length} ${noun}. The app may expose limited accessibility metadata; run screenshot --overlay-refs for visual context.`;
+}
+
 function readSnapshotWarnings(data: Record<string, unknown>): string[] {
   const rawWarnings = data.warnings;
   if (!Array.isArray(rawWarnings)) {

website/docs/docs/snapshots.md

@@ -38,7 +38,6 @@ It does not automatically switch to AX.
 - Those summaries intentionally show only a few labels for token efficiency. Use `snapshot --raw` when you need the full off-screen tree instead of the compact summary.
 - Add `-s "<label>"` (or `-s @ref`) to keep results screen-local.
 - Add `-d <depth>` when you only need upper hierarchy layers.
-- If `snapshot -i` returns 0 nodes on Android but the screen is visibly populated, trust `screenshot` as visual truth, wait briefly, then take one fresh `snapshot -i`.
 - If `snapshot -i -d <n>` says the interactive output is empty at that depth, retry once without `-d` before taking more shallow snapshots.
 - Re-snapshot after any UI mutation before reusing refs.
 - On Android after navigation or submit, snapshot capture retries suspicious trees for a short post-action deadline and `@ref` interactions refresh while that freshness window is active. If `snapshot -i` still disagrees with the visible screen, trust `screenshot`, wait briefly, then take one fresh snapshot instead of looping stale snapshots.