fix: report blockers on wait timeout (#546)

Author: thymikee

src/daemon/handlers/__tests__/snapshot-handler.test.ts

@@ -84,6 +84,125 @@ beforeEach(() => {
   mockRunnerCommand.mockResolvedValue({});
 });
 
+async function runWaitCommand(
+  sessionName: string,
+  device: SessionState['device'],
+  positionals: string[],
+) {
+  const sessionStore = makeSessionStore();
+  sessionStore.set(sessionName, makeSession(sessionName, device));
+  return await handleSnapshotCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'wait',
+      positionals,
+      flags: {},
+    },
+    sessionName,
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+  });
+}
+
+const locationPermissionNodes = [
+  {
+    index: 0,
+    depth: 0,
+    type: 'android.widget.FrameLayout',
+    label: 'Location permission',
+    rect: { x: 0, y: 0, width: 390, height: 844 },
+  },
+  {
+    index: 1,
+    depth: 1,
+    parentIndex: 0,
+    type: 'android.widget.TextView',
+    label: 'Allow location access?',
+    rect: { x: 24, y: 210, width: 342, height: 40 },
+  },
+  {
+    index: 2,
+    depth: 1,
+    parentIndex: 0,
+    type: 'android.widget.Button',
+    label: 'Not now',
+    rect: { x: 24, y: 320, width: 140, height: 48 },
+    hittable: true,
+  },
+  {
+    index: 3,
+    depth: 1,
+    parentIndex: 0,
+    type: 'android.widget.Button',
+    label: 'Continue',
+    rect: { x: 180, y: 320, width: 160, height: 48 },
+    hittable: true,
+  },
+];
+
+const locationRequiredNodes = [
+  {
+    index: 0,
+    depth: 0,
+    type: 'android.widget.TextView',
+    label: 'Location required',
+    rect: { x: 24, y: 180, width: 342, height: 40 },
+  },
+  {
+    index: 1,
+    depth: 0,
+    type: 'android.widget.Button',
+    label: 'Dismiss',
+    rect: { x: 24, y: 260, width: 342, height: 48 },
+  },
+];
+
+const iosSurfaceSummaryNodes = [
+  {
+    index: 0,
+    depth: 0,
+    type: 'XCUIElementTypeApplication',
+    label: 'Expo Go',
+    rect: { x: 0, y: 0, width: 393, height: 852 },
+  },
+  {
+    index: 1,
+    depth: 1,
+    type: 'XCUIElementTypeImage',
+    label: 'gearshape.fill',
+    rect: { x: 12, y: 54, width: 24, height: 24 },
+  },
+  {
+    index: 2,
+    depth: 1,
+    type: 'XCUIElementTypeOther',
+    label: 'Tab Bar',
+    rect: { x: 0, y: 760, width: 393, height: 92 },
+  },
+  {
+    index: 3,
+    depth: 1,
+    type: 'XCUIElementTypeStaticText',
+    label: 'Confirm catalog refresh',
+    rect: { x: 48, y: 280, width: 297, height: 36 },
+  },
+  {
+    index: 4,
+    depth: 1,
+    type: 'XCUIElementTypeButton',
+    label: 'Keep browsing',
+    rect: { x: 48, y: 360, width: 297, height: 48 },
+  },
+  {
+    index: 5,
+    depth: 1,
+    type: 'XCUIElementTypeButton',
+    identifier: 'host.exp.exponent:id/reload_button',
+    rect: { x: 260, y: 54, width: 48, height: 48 },
+  },
+];
+
 test('snapshot rejects @ref scope without existing session snapshot', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-sim';
@@ -574,6 +693,98 @@ test('wait text on Android uses freshness-aware capture instead of one-shot snap
   );
 });
 
+test('wait text timeout includes compact current-surface labels and buttons', async () => {
+  const sessionName = 'android-wait-timeout-surface';
+  mockDispatch.mockResolvedValue({
+    nodes: locationPermissionNodes,
+    truncated: false,
+    backend: 'android',
+    analysis: { rawNodeCount: 4, maxDepth: 1 },
+  });
+
+  const response = await runWaitCommand(sessionName, androidDevice, ['Receipt uploaded', '0']);
+
+  expect(response?.ok).toBe(false);
+  if (response && !response.ok) {
+    expect(response.error.message).toBe(
+      'wait timed out for text: Receipt uploaded. Current surface: Location permission, Allow location access?, Not now, Continue.',
+    );
+    expect(response.error.details?.currentSurface).toEqual({
+      labels: ['Location permission', 'Allow location access?', 'Not now', 'Continue'],
+      buttons: ['Not now', 'Continue'],
+    });
+  }
+});
+
+test('wait selector timeout includes compact current-surface details', async () => {
+  const sessionName = 'android-wait-selector-timeout-surface';
+  mockDispatch.mockResolvedValue({
+    nodes: locationRequiredNodes,
+    truncated: false,
+    backend: 'android',
+    analysis: { rawNodeCount: 2, maxDepth: 0 },
+  });
+
+  const response = await runWaitCommand(sessionName, androidDevice, ['id=receipt-uploaded', '0']);
+
+  expect(response?.ok).toBe(false);
+  if (response && !response.ok) {
+    expect(response.error.message).toBe(
+      'wait timed out for selector: id=receipt-uploaded. Current surface: Location required, Dismiss.',
+    );
+    expect(response.error.details?.currentSurface).toEqual({
+      labels: ['Location required', 'Dismiss'],
+      buttons: ['Dismiss'],
+    });
+  }
+});
+
+test('wait timeout summary prefers content labels over chrome and identifier noise', async () => {
+  const sessionName = 'ios-wait-timeout-surface-summary';
+  mockRunnerCommand.mockResolvedValue({ found: false });
+  mockDispatch.mockResolvedValue({
+    nodes: iosSurfaceSummaryNodes,
+    truncated: false,
+    backend: 'xctest',
+  });
+
+  const response = await runWaitCommand(sessionName, iosSimulatorDevice, [
+    'Impossible success text',
+    '0',
+  ]);
+
+  expect(response?.ok).toBe(false);
+  if (response && !response.ok) {
+    expect(response.error.message).toBe(
+      'wait timed out for text: Impossible success text. Current surface: Confirm catalog refresh, Keep browsing.',
+    );
+    expect(response.error.details?.currentSurface).toEqual({
+      labels: [
+        'Confirm catalog refresh',
+        'Keep browsing',
+        'host.exp.exponent:id/reload_button',
+        'Expo Go',
+        'gearshape.fill',
+        'Tab Bar',
+      ],
+      buttons: ['Keep browsing', 'host.exp.exponent:id/reload_button'],
+    });
+  }
+});
+
+test('wait timeout preserves current behavior when current-surface inspection fails', async () => {
+  const sessionName = 'android-wait-timeout-surface-fails';
+  mockDispatch.mockRejectedValue(new Error('snapshot unavailable'));
+
+  const response = await runWaitCommand(sessionName, androidDevice, ['Receipt uploaded', '0']);
+
+  expect(response?.ok).toBe(false);
+  if (response && !response.ok) {
+    expect(response.error.message).toBe('wait timed out for text: Receipt uploaded');
+    expect(response.error.details).toBeUndefined();
+  }
+});
+
 test('settings rejects unsupported iOS physical devices', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-device';

src/daemon/selector-runtime.ts

@@ -43,6 +43,7 @@ import {
 } from './selector-recording.ts';
 import { createDaemonRuntimePolicy } from './runtime-policy.ts';
 import { createDaemonRuntimeSessionStore } from './runtime-session.ts';
+import { maybeWaitTimeoutSurfaceResponse } from './wait-current-surface.ts';
 
 type SelectorRuntimeParams = {
   req: DaemonRequest;
@@ -208,7 +209,12 @@ export async function dispatchWaitViaRuntime(
       recordIfSession(sessionStore, sessionName, req, result);
       return toDaemonWaitData(result);
     });
-    return await maybeAndroidForegroundBlockerResponse(params, response, 'wait');
+    const enrichedResponse = await maybeWaitTimeoutSurfaceResponse(
+      { req, logPath: params.logPath, session, device },
+      response,
+    );
+    // Keep generic wait-surface details first so Android blocker detection can own the top-level message.
+    return await maybeAndroidForegroundBlockerResponse(params, enrichedResponse, 'wait');
   };
   if (parsed.kind === 'sleep') return await execute();
   return await withSessionlessRunnerCleanup(session, device, execute);

src/daemon/wait-current-surface.ts

@@ -0,0 +1,131 @@
+import type { SnapshotNode } from '../utils/snapshot.ts';
+import type { DaemonRequest, DaemonResponse, SessionState } from './types.ts';
+import { captureSnapshot } from './handlers/snapshot-capture.ts';
+import { errorResponse } from './handlers/response.ts';
+import { normalizeType } from './snapshot-processing.ts';
+
+type WaitCurrentSurfaceParams = {
+  req: DaemonRequest;
+  logPath?: string;
+  session: SessionState | undefined;
+  device: SessionState['device'];
+};
+
+type CurrentSurfaceDetails = {
+  labels: string[];
+  buttons?: string[];
+};
+
+const CHROME_ROLE_MARKERS = ['application', 'window', 'tabbar', 'scrollbar', 'image'] as const;
+const CHROME_LABELS = new Set(['tab bar']);
+
+export async function maybeWaitTimeoutSurfaceResponse(
+  params: WaitCurrentSurfaceParams,
+  response: DaemonResponse,
+): Promise<DaemonResponse> {
+  if (response.ok || !isWaitTimeoutMessage(response.error.message)) return response;
+  const currentSurface = await inspectCurrentSurface(params).catch(() => null);
+  if (!currentSurface) return response;
+  return errorResponse(
+    response.error.code,
+    `${response.error.message}. Current surface: ${currentSurface.summary}.`,
+    {
+      ...(response.error.details ?? {}),
+      currentSurface: currentSurface.details,
+    },
+  );
+}
+
+function isWaitTimeoutMessage(message: string): boolean {
+  return /^wait timed out for (?:selector|text): /i.test(message);
+}
+
+async function inspectCurrentSurface(
+  params: WaitCurrentSurfaceParams,
+): Promise<{ summary: string; details: CurrentSurfaceDetails } | null> {
+  const capture = await captureSnapshot({
+    device: params.device,
+    session: params.session,
+    flags: {
+      ...params.req.flags,
+      snapshotInteractiveOnly: true,
+      snapshotCompact: true,
+    },
+    logPath: params.logPath ?? '',
+  });
+  const orderedNodes = [...capture.snapshot.nodes].sort(compareSurfacePriority);
+  const labels = topSurfaceTexts(orderedNodes, 6, { includeIdentifiers: true });
+  if (labels.length === 0) return null;
+  const contentNodes = orderedNodes.filter((node) => !isChromeLikeNode(node));
+  const summaryLabels = topSurfaceTexts(contentNodes, 4, { includeIdentifiers: false });
+  const buttons = topSurfaceTexts(orderedNodes.filter(isButtonLikeNode), 4, {
+    includeIdentifiers: true,
+  });
+  const summary = (summaryLabels.length > 0 ? summaryLabels : labels.slice(0, 4)).join(', ');
+  return {
+    summary,
+    details: {
+      labels,
+      ...(buttons.length > 0 ? { buttons } : {}),
+    },
+  };
+}
+
+function topSurfaceTexts(
+  nodes: SnapshotNode[],
+  limit: number,
+  options: { includeIdentifiers: boolean },
+): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const node of nodes) {
+    const text = extractSurfaceText(node, options);
+    if (!text || seen.has(text)) continue;
+    seen.add(text);
+    result.push(text);
+    if (result.length >= limit) break;
+  }
+  return result;
+}
+
+function compareSurfacePriority(a: SnapshotNode, b: SnapshotNode): number {
+  return surfacePriority(a) - surfacePriority(b) || compareSurfaceOrder(a, b);
+}
+
+function surfacePriority(node: SnapshotNode): number {
+  const hasHumanText = Boolean(extractSurfaceText(node, { includeIdentifiers: false }));
+  const chromePenalty = isChromeLikeNode(node) ? 2 : 0;
+  return chromePenalty + (hasHumanText ? 0 : 1);
+}
+
+function compareSurfaceOrder(a: SnapshotNode, b: SnapshotNode): number {
+  if (a.rect && b.rect) return a.rect.y - b.rect.y || a.rect.x - b.rect.x;
+  if (a.rect) return -1;
+  if (b.rect) return 1;
+  return (a.depth ?? 0) - (b.depth ?? 0) || a.index - b.index;
+}
+
+function extractSurfaceText(node: SnapshotNode, options: { includeIdentifiers: boolean }): string {
+  const candidates = options.includeIdentifiers
+    ? [node.label, node.value, node.identifier]
+    : [node.label, node.value];
+  const value = candidates
+    .map((candidate) => (typeof candidate === 'string' ? candidate.trim() : ''))
+    .find((candidate) => candidate.length > 0);
+  return value ? value.replace(/\s+/g, ' ').slice(0, 80) : '';
+}
+
+function isChromeLikeNode(node: SnapshotNode): boolean {
+  const roleText = normalizeType(`${node.type ?? ''} ${node.role ?? ''} ${node.subrole ?? ''}`);
+  const label = `${node.label ?? ''} ${node.value ?? ''}`.trim().toLowerCase();
+  return (
+    CHROME_ROLE_MARKERS.some((marker) => roleText.includes(marker)) ||
+    CHROME_LABELS.has(label) ||
+    label.endsWith('.fill')
+  );
+}
+
+function isButtonLikeNode(node: SnapshotNode): boolean {
+  const roleText = `${node.type ?? ''} ${node.role ?? ''} ${node.subrole ?? ''}`;
+  return normalizeType(roleText).includes('button');
+}