mobile-debug-mcp 0.25.1 → 0.26.0

package/docs/rfcs/003-wait-and-synchronization-reliability.md

@@ -0,0 +1,296 @@
+# RFC-003: Wait and Synchronization Reliability
+
+Priority: 3  
+Depends on: RFC-001 (Stronger State Verification), RFC-002 (Platform-Native Element Metadata and Resolution Hints)
+
+---
+
+# 1. Problem
+
+Agents can often identify the right element (RFC-002) and verify the right state (RFC-001), but still fail because they act before the UI has reached the intended post-action state.
+
+This causes:
+
+- retries caused by racing the UI
+- false failures from stale snapshots
+- overuse of network/log verification when UI evidence should suffice
+- flakiness in asynchronous and in-place update flows
+- unreliable behaviour in Compose-heavy or thin accessibility trees
+
+Current system limitations:
+
+- wait_for_ui is underused after actions involving async state changes
+- current waits focus on expected elements appearing, not general UI transition detection
+- snapshot staleness is not explicitly surfaced
+- loading state transitions are inconsistently observable
+
+---
+
+# 2. Goals
+
+This RFC introduces:
+
+1. UI-first synchronization policy after actions
+2. Snapshot staleness and revision metadata
+3. UI-change based waiting for in-place updates
+4. Structured loading-state detection
+5. Compose-aware synchronization hints
+
+Success goals:
+
+- reduce retries caused by premature actions
+- increase successful post-action verification
+- reduce unnecessary fallbacks to logs/network checks
+- improve reliability in asynchronous UI flows
+
+---
+
+# 3. Non-Goals
+
+This RFC does not:
+
+- redefine state verification semantics (RFC-001)
+- redefine element identity contracts (RFC-002)
+- add new interaction primitives (long press, pinch, etc.)
+- replace network or log verification where no UI outcome exists
+
+---
+
+# 4. Proposed Model
+
+## 4.1 UI-First Synchronization Contract (v1)
+
+Default post-action flow SHOULD be:
+
+```text
+action
+→ wait_for_ui(expected outcome)
+→ verify state
+→ only fall back to network/logs when no UI outcome exists or wait fails
+```
+
+Tool-level contract:
+
+- After actions expected to cause visible UI changes, agents SHOULD invoke wait_for_ui or wait_for_ui_change before verification.
+- wait_for_ui SHOULD be used when an expected element or explicit outcome is known.
+- wait_for_ui_change SHOULD be used for in-place mutations where a specific element target is not known.
+- wait_for_screen_change SHOULD remain preferred for full navigation transitions when available.
+
+Rules:
+
+- UI evidence MUST be preferred over network or log evidence when a UI outcome is expected.
+- Actions that trigger navigation, async mutation, or visible state changes SHOULD be followed by a wait.
+- Network/log checks are fallback signals, not primary synchronization mechanisms.
+- This synchronization order is normative tool behavior for agents, not advisory prose.
+
+---
+
+## 4.2 Snapshot Revision Contract
+
+All snapshot responses MUST include revision metadata.
+
+Emission scope:
+
+- snapshot_revision and captured_at_ms MUST be emitted on snapshot responses.
+- get_ui_tree responses SHOULD emit the same fields when backed by the same snapshot generation layer.
+- If both surfaces exist, revision values MUST be consistent across them when derived from the same underlying snapshot.
+
+Required snapshot envelope:
+
+```json
+{
+  "snapshot_revision": 184,
+  "captured_at_ms": 1714452012301
+}
+```
+
+Field requirements:
+
+- snapshot_revision REQUIRED on every snapshot response.
+- captured_at_ms REQUIRED on every snapshot response.
+
+Source of truth:
+
+- snapshot_revision originates in the snapshot generation layer.
+- It MUST increment when a meaningful hierarchy delta is detected.
+- Cosmetic-only changes MUST NOT increment revision.
+
+Meaningful deltas include:
+
+- node added or removed
+- visible text mutation
+- control state change
+- list content mutation
+- navigation or view transition
+
+Cosmetic churn examples (must not increment):
+
+- cursor blink
+- focus-only changes
+- animation-only transitions
+- timestamp or unrelated ephemeral text changes
+
+Rules:
+
+- Agents SHOULD use revision changes as synchronization signals.
+- Stale revisions SHOULD trigger reacquisition before verification.
+- This extends the snapshot response contract defined by RFC-002.
+
+- Snapshot responses are the normative required emission surface; get_ui_tree emission is recommended for consistency.
+- snapshot_revision MUST be monotonically increasing within a session.
+
+---
+
+## 4.3 wait_for_ui_change API
+
+Concrete API contract:
+
+```ts
+wait_for_ui_change({
+  expected_change?: "hierarchy_diff" | "text_change" | "state_change",
+  timeout_ms?: number,
+  stability_window_ms?: number
+}) => {
+  success: boolean,
+  observed_change: "hierarchy_diff" | "text_change" | "state_change" | null,
+  snapshot_revision?: number,
+  timeout: boolean
+}
+```
+
+Relationship to other wait primitives:
+
+- wait_for_screen_change remains the preferred primitive for navigation-level transitions.
+- wait_for_ui_change is the preferred primitive for non-navigation UI mutations and in-place updates.
+- wait_for_ui_change is additive to wait_for_screen_change, not a replacement for it.
+
+Rules:
+
+- stability_window_ms represents time a detected change must remain stable before success.
+- Meaningful delta semantics are inherited from Section 4.2.
+- wait_for_ui_change complements wait_for_ui; it does not replace it.
+
+- Agents SHOULD prefer wait_for_screen_change for navigation and wait_for_ui_change for non-navigation changes.
+
+---
+
+## 4.4 Structured Loading-State Contract
+
+Loading signals are OPTIONAL overall, but when a detectable loading signal exists they SHOULD be surfaced on snapshot responses and UI tree responses, and if emitted they MUST conform to the contract below.
+
+Required shape:
+
+```json
+{
+  "loading_state": {
+    "active": true,
+    "signal": "progress_indicator",
+    "source": "snapshot"
+  }
+}
+```
+
+Required fields:
+
+- active
+- signal
+- source
+
+Rules:
+
+- Loading signals are synchronization hints only.
+- Loading completion MUST NOT alone be treated as success.
+- If emitted, the shape above MUST be used.
+- Absence of loading_state is valid when no reliable loading signal is detectable; malformed or partial loading_state emission is not valid.
+
+---
+
+## 4.5 Compose-Aware Synchronization Hints
+
+For Compose or thin accessibility structures:
+
+Systems SHOULD support:
+
+- merged semantic node changes as wait signals
+- text mutations within existing nodes
+- in-place recomposition awareness
+
+These are synchronization hints layered on top of standard wait behaviour.
+
+---
+
+# 5. Failure Modes
+
+## 5.1 Premature Action Progression
+
+If an action is followed immediately by verification without waiting:
+
+- system SHOULD bias toward suggesting wait_for_ui
+- retries SHOULD prefer synchronization correction before repeated action execution
+
+---
+
+## 5.2 Stale Snapshot Reads
+
+If verification uses an old snapshot:
+
+- revision metadata SHOULD expose staleness
+- agents SHOULD reacquire snapshot before retrying verification
+
+---
+
+## 5.3 No Visible UI Outcome
+
+If no UI outcome is expected:
+
+- network/log verification MAY be primary evidence
+- UI-first policy does not apply rigidly
+
+---
+
+## 5.4 False Positive UI Change Detection
+
+If unrelated UI churn triggers early wait completion:
+
+- systems SHOULD reject cosmetic-only changes using Section 4.2 rules
+- agents SHOULD prefer stability windows before considering waits satisfied
+
+---
+
+# 6. Acceptance Criteria
+
+RFC-003 specification is complete when:
+
+- Snapshot Revision Contract is fully defined and mandatory.
+- wait_for_ui_change API contract is fully defined.
+- Loading-State Contract required schema is defined.
+- Synchronization tool-selection rules are explicitly specified.
+- False-positive change handling is specified.
+
+Implementation readiness success is measured when:
+
+- snapshot revisions reduce stale-read retries
+- synchronization retries decrease
+- post-action verification success increases
+
+---
+
+# 7. Success Metrics
+
+- Fewer retries caused by timing/synchronization errors
+- Higher post-action verification success rate
+- Reduced unnecessary fallback to network/log evidence
+- Improved stability in asynchronous and Compose-heavy flows
+
+---
+
+# 8. Deferred To Later RFCs
+
+- Advanced subscriptions / notify-when-element-appears APIs
+- Full action-to-ui trace correlation (Priority 7)
+- Gesture-trigger-specific synchronization logic
+- Element appearance subscription / notify-when-ready APIs
+
+---
+
+This RFC standardises temporal reliability and synchronization signals layered on top of state verification and element identity guarantees from RFC-001 and RFC-002.

package/docs/specs/mcp-tooling-spec-v1.md

@@ -151,6 +151,7 @@ Examples:
 
 - `wait_for_ui`
 - `wait_for_screen_change`
+- `wait_for_ui_change`
 
 ### 6.2 Rules
 
@@ -239,6 +240,8 @@ Raw layer contents include:
 - UI hierarchy or accessibility tree
 - normalized readable element state where exposed by the platform
 - platform-native identity hints such as stable identifiers, roles, and test tags
+- snapshot metadata such as `snapshot_revision` and `captured_at_ms`
+- `loading_state` when a reliable loading signal is detectable
 - screenshot when available
 - element-level attributes
 - logs and fingerprint/activity observations
@@ -305,10 +308,15 @@ Canonical pattern:
 
 `wait_for_ui -> tap_element -> wait_for_screen_change (optional) -> expect_screen`
 
+For in-place UI mutations, agents SHOULD prefer:
+
+`wait_for_ui_change -> expect_element_visible / expect_state`
+
 Interpretation:
 
 - `tap_element.success` = executed
 - `wait_for_screen_change.success` = UI changed
+- `wait_for_ui_change.success` = in-place UI mutation observed and stable
 - `expect_screen.success` = correct outcome verified
 
 ## 12. Known Deviations

package/docs/tools/interact.md

@@ -58,6 +58,7 @@ Preferred verification:
 
 Use `wait_for_screen_change` only when a visible transition is the expected outcome. If a button should trigger an API request but the screen should stay the same, rely on network activity and classification instead.
 For backend-only actions, prefer comparing `get_screen_fingerprint` before/after and call `get_network_activity` immediately after the action; do not wait on `wait_for_screen_change` if no visible transition is expected.
+Use `wait_for_ui_change` when the screen stays in place but visible text or element state should change.
 
 ---
 
@@ -148,6 +149,26 @@ Notes:
 
 ---
 
+## wait_for_ui_change
+
+Purpose:
+
+- detect a stable in-place UI mutation without naming a target element first
+
+Capabilities:
+
+- waits for hierarchy, text, or state deltas
+- uses snapshot revision metadata when available
+- confirms the change remains stable before returning success
+
+Guidance:
+
+- prefer `wait_for_screen_change` for navigation
+- prefer `wait_for_ui_change` for in-place updates and recomposition-style changes
+- follow with `expect_*` when the expected final state is known
+
+---
+
 ## find_element
 
 Locate a UI element on the current screen using semantic matching and return an actionable element descriptor.

package/docs/tools/observe.md

@@ -83,13 +83,14 @@ Input:
 Response (example):
 
 ```json
-{ "device": { "platform": "android", "id": "emulator-5554" }, "screen": "", "resolution": { "width": 1080, "height": 2400 }, "elements": [ { "text": "Sign in", "type": "android.widget.Button", "resourceId": "com.example:id/signin", "clickable": true, "bounds": [0,0,100,50], "state": { "enabled": true }, "stable_id": "com.example:id/signin", "role": "button", "test_tag": "com.example:id/signin", "selector": { "value": "com.example:id/signin", "confidence": { "score": 1, "reason": "resource_id" } }, "semantic": { "is_clickable": true, "is_container": false } } ] }
+{ "device": { "platform": "android", "id": "emulator-5554" }, "screen": "", "resolution": { "width": 1080, "height": 2400 }, "snapshot_revision": 12, "captured_at_ms": 1710000000123, "loading_state": { "active": true, "signal": "spinner", "source": "ui_tree" }, "elements": [ { "text": "Sign in", "type": "android.widget.Button", "resourceId": "com.example:id/signin", "clickable": true, "bounds": [0,0,100,50], "state": { "enabled": true }, "stable_id": "com.example:id/signin", "role": "button", "test_tag": "com.example:id/signin", "selector": { "value": "com.example:id/signin", "confidence": { "score": 1, "reason": "resource_id" } }, "semantic": { "is_clickable": true, "is_container": false } } ] }
 ```
 
 Notes:
 - Useful for inspection, selector development, and fallback debugging.
 - Elements may include a normalized `state` object when the platform exposes readable state such as checked, selected, focused, expanded, text input, or slider values.
 - Elements may also include platform-native identity hints such as `stable_id`, `role`, `test_tag`, `selector`, and `semantic`.
+- The tree response may include `snapshot_revision`, `captured_at_ms`, and `loading_state` when a reliable signal is available.
 - Prefer `wait_for_ui` for deterministic element resolution in interactive flows.
 
 ---
@@ -136,7 +137,8 @@ Behavior:
 - Fast by default: does not wait for new logs and avoids long blocking operations.
 - Returns a dual-layer payload:
   - `raw` is authoritative and contains the underlying observation data unchanged.
-  - `semantic` is optional, derived from `raw`, and intended for planning only.
+- `semantic` is optional, derived from `raw`, and intended for planning only.
+- `raw` now includes `snapshot_revision`, `captured_at_ms`, and `loading_state` when detectable.
 
 Response (example):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/skills/rfc-review/SKILL.md

@@ -0,0 +1,52 @@
+# RFC Review skill
+
+name: rfc-review
+version: 0.1.1
+summary: Reusable workflow for reviewing RFCs/specs in this repository with a consistent readiness rubric and output template.
+
+# Purpose
+Help an agent review an RFC for clarity, implementation readiness, and alignment with the current codebase. Use a common template so reviews stay consistent across documents and reviewers.
+
+# Activation conditions
+Activate when an agent needs to:
+- review a new or revised RFC
+- assess whether an RFC is implementation-ready
+- identify whether feedback is an RFC issue or an implementation issue
+- compare a spec against the current `src/` contract surface and docs
+
+# Surface area (actions)
+- locate-rfc
+- compare-against-code
+- assess-contract-completeness
+- classify-gaps
+- produce-review
+
+# Core guidance
+1. Read the RFC first, then compare it against the relevant code, docs, and tests.
+2. Separate **spec gaps** from **implementation gaps**.
+3. Check for: problem clarity, scope boundaries, explicit contracts, acceptance criteria, non-goals, and consistency with existing behavior.
+4. Prefer precise feedback that names the missing contract, unclear rule, or inconsistent behavior.
+5. Use the shared review template in `references/rfc-review-template.md` for the final output.
+6. If the RFC is not ready, say exactly what must be clarified before implementation can start.
+7. Classify each blocker as either a **spec gap** or an **implementation contract gap** and stop at that boundary.
+
+# Inputs & outputs
+- review-rfc(input: { rfcPath, relatedPaths?, focusAreas? }) -> { verdict, risks, specGaps, implementationGaps, recommendations }
+- compare-against-code(input: { rfcPath, codePaths[] }) -> { matches, mismatches, notes }
+- produce-review(input: { rfcPath, findings[] }) -> { summary, verdict, checklist, nextStep }
+
+# Failure handling
+- If the RFC file is missing, stop and report the missing path explicitly.
+- If the RFC is ambiguous, classify each concern as either "spec" or "implementation" instead of blending them.
+- If the review cannot be grounded in the current repo, state that the RFC is not reviewable yet.
+
+# Progressive disclosure
+- Keep this file short.
+- Load the reference template only when writing the final review.
+
+# References
+- `references/rfc-review-template.md` — standard review format and verdict rubric
+- `references/rfc-review-checklist.md` — questions to apply while reviewing an RFC
+
+# License
+Same as repository (MIT).

package/skills/rfc-review/references/rfc-review-checklist.md

@@ -0,0 +1,12 @@
+# RFC Review Checklist
+
+Ask these questions while reviewing:
+
+1. Is the problem statement specific and grounded in current failures?
+2. Are non-goals explicit?
+3. Are contracts concrete enough to implement?
+4. Are acceptance criteria testable?
+5. Does the RFC define the source of truth for new fields or behaviors?
+6. Does it match existing code paths and public tool surfaces?
+7. Can each open concern be classified as a spec issue or an implementation issue?
+8. Is the RFC ready to implement without further interpretation?

package/skills/rfc-review/references/rfc-review-template.md

@@ -0,0 +1,28 @@
+# RFC Review Template
+
+Use this structure for every RFC review:
+
+## Verdict
+- Ready / Needs clarification / Needs implementation contract / Not ready
+
+## Summary
+- One short paragraph on the RFC's current quality.
+
+## What is good
+- List the strongest parts of the RFC.
+
+## Issues
+For each issue, include:
+- **Type:** spec / implementation / implementation contract / doc
+- **Severity:** low / medium / high
+- **Why it matters:** one sentence
+- **Fix:** exact change needed
+
+## Missing contract surfaces
+- List any API shapes, response fields, state transitions, or invariants that are still undefined.
+
+## Codebase alignment
+- Note whether the RFC matches current `src/`, docs, and tests.
+
+## Next step
+- State the smallest next action needed to move the RFC forward.

package/src/interact/index.ts

@@ -5,6 +5,7 @@ export { AndroidInteract, iOSInteract };
 
 import { resolveTargetDevice } from '../utils/resolve-device.js'
 import { ToolsObserve } from '../observe/index.js'
+import { computeSnapshotSignature } from '../observe/snapshot-metadata.js'
 import { nextActionId } from '../server/common.js'
 import type {
   ActionFailureCode,
@@ -12,6 +13,7 @@ import type {
   ExpectElementVisibleResponse,
   ExpectStateResponse,
   ExpectScreenResponse,
+  WaitForUIChangeResponse,
   UIElementState,
   TapElementResponse
 } from '../types.js'
@@ -60,9 +62,16 @@ interface UiResolution {
   height?: number
 }
 
+interface UiChangeSignatureSet {
+  hierarchy: string | null
+  text: string | null
+  state: string | null
+}
+
 
 export class ToolsInteract {
   private static readonly _maxResolvedUiElements = 256
+  private static readonly _uiChangeKinds: Array<'hierarchy_diff' | 'text_change' | 'state_change'> = ['hierarchy_diff', 'text_change', 'state_change']
   private static readonly _sliderSearchLookahead = 8
   private static readonly _sliderNegativeGapTolerancePx = 32
   private static readonly _sliderPositiveGapLimitPx = 640
@@ -85,6 +94,10 @@ export class ToolsInteract {
     return normalized as [number, number, number, number]
   }
 
+  private static _hash(value: unknown): string {
+    return createHash('sha256').update(JSON.stringify(value)).digest('hex')
+  }
+
   private static _matchesSelector(el: UiElement, selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean }): boolean {
     if (!selector) return false
     const normalize = ToolsInteract._normalize
@@ -195,6 +208,66 @@ export class ToolsInteract {
     }
   }
 
+  private static _buildUiChangeSignatures(tree: any): UiChangeSignatureSet {
+    const elements = Array.isArray(tree?.elements) ? tree.elements as UiElement[] : []
+    const textPayload: Array<{ text: string, contentDescription: string, resourceId: string }> = []
+    const statePayload: Array<{
+      checked: boolean | null
+      selected: boolean | string | { id: string; label?: string } | null
+      focused: boolean | null
+      expanded: boolean | null
+      enabled: boolean | null
+      text_value: string | null
+      value: number | string | null
+      raw_value: number | string | null
+      value_range: UIElementState['value_range']
+    }> = []
+
+    for (const el of elements) {
+      textPayload.push({
+        text: ToolsInteract._normalize(el?.text ?? el?.label ?? el?.value ?? ''),
+        contentDescription: ToolsInteract._normalize(el?.contentDescription ?? el?.contentDesc ?? el?.accessibilityLabel ?? ''),
+        resourceId: ToolsInteract._normalize(el?.resourceId ?? el?.resourceID ?? el?.id ?? '')
+      })
+
+      statePayload.push({
+        checked: el?.state?.checked ?? null,
+        selected: el?.state?.selected ?? null,
+        focused: el?.state?.focused ?? null,
+        expanded: el?.state?.expanded ?? null,
+        enabled: el?.state?.enabled ?? null,
+        text_value: el?.state?.text_value ?? null,
+        value: el?.state?.value ?? null,
+        raw_value: el?.state?.raw_value ?? null,
+        value_range: el?.state?.value_range ?? null
+      })
+    }
+
+    return {
+      hierarchy: computeSnapshotSignature(tree),
+      text: ToolsInteract._hash({
+        screen: ToolsInteract._normalize(tree?.screen),
+        elements: textPayload
+      }),
+      state: ToolsInteract._hash({
+        screen: ToolsInteract._normalize(tree?.screen),
+        elements: statePayload
+      })
+    }
+  }
+
+  private static _matchesUiChange(expected: 'hierarchy_diff' | 'text_change' | 'state_change' | undefined, initial: UiChangeSignatureSet, current: UiChangeSignatureSet): 'hierarchy_diff' | 'text_change' | 'state_change' | null {
+    const candidates = expected ? [expected] : ToolsInteract._uiChangeKinds
+
+    for (const changeKind of candidates) {
+      if (changeKind === 'hierarchy_diff' && initial.hierarchy !== current.hierarchy) return changeKind
+      if (changeKind === 'text_change' && initial.text !== current.text) return changeKind
+      if (changeKind === 'state_change' && initial.state !== current.state) return changeKind
+    }
+
+    return null
+  }
+
   private static _resolvedTargetFromElement(
     elementId: string,
     element: UiElement,
@@ -955,6 +1028,84 @@ export class ToolsInteract {
     }
   }
 
+  static async waitForUIChangeHandler({
+    platform,
+    deviceId,
+    timeout_ms = 60000,
+    stability_window_ms = 250,
+    expected_change
+  }: {
+    platform?: 'android' | 'ios',
+    deviceId?: string,
+    timeout_ms?: number,
+    stability_window_ms?: number,
+    expected_change?: 'hierarchy_diff' | 'text_change' | 'state_change'
+  }): Promise<WaitForUIChangeResponse> {
+    const start = Date.now()
+    const pollIntervalMs = 300
+    const stabilityWindow = Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 250)
+    let baseline: UiChangeSignatureSet | null = null
+    let lastObservedRevision: number | null = null
+    let lastLoadingState: any = null
+
+    while (Date.now() - start < timeout_ms) {
+      try {
+        const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId }) as any
+        const signatures = ToolsInteract._buildUiChangeSignatures(tree)
+        lastObservedRevision = typeof tree?.snapshot_revision === 'number' ? tree.snapshot_revision : lastObservedRevision
+        lastLoadingState = tree?.loading_state ?? lastLoadingState
+
+        if (!baseline) {
+          baseline = signatures
+        } else {
+          const observedChange = ToolsInteract._matchesUiChange(expected_change, baseline, signatures)
+          if (observedChange) {
+            if (stabilityWindow > 0) {
+              await new Promise(resolve => setTimeout(resolve, stabilityWindow))
+              const confirmTree = await ToolsObserve.getUITreeHandler({ platform, deviceId }) as any
+              const confirmSignatures = ToolsInteract._buildUiChangeSignatures(confirmTree)
+              const confirmChange = ToolsInteract._matchesUiChange(expected_change, baseline, confirmSignatures)
+              if (!confirmChange || confirmSignatures.hierarchy !== signatures.hierarchy || confirmSignatures.text !== signatures.text || confirmSignatures.state !== signatures.state) {
+                lastObservedRevision = typeof confirmTree?.snapshot_revision === 'number' ? confirmTree.snapshot_revision : lastObservedRevision
+                lastLoadingState = confirmTree?.loading_state ?? lastLoadingState
+                await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+                continue
+              }
+              lastObservedRevision = typeof confirmTree?.snapshot_revision === 'number' ? confirmTree.snapshot_revision : lastObservedRevision
+              lastLoadingState = confirmTree?.loading_state ?? lastLoadingState
+            }
+
+            return {
+              success: true,
+              observed_change: observedChange,
+              snapshot_revision: lastObservedRevision ?? undefined,
+              timeout: false,
+              elapsed_ms: Date.now() - start,
+              expected_change,
+              loading_state: lastLoadingState ?? null,
+              reason: 'UI change observed'
+            }
+          }
+        }
+      } catch {
+        // Keep polling until timeout; the observable surface should be best-effort.
+      }
+
+      await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+    }
+
+    return {
+      success: false,
+      observed_change: null,
+      snapshot_revision: lastObservedRevision ?? undefined,
+      timeout: true,
+      elapsed_ms: Date.now() - start,
+      expected_change,
+      loading_state: lastLoadingState ?? null,
+      reason: 'timeout'
+    }
+  }
+
   static async expectScreenHandler({
     platform,
     fingerprint,