mobile-debug-mcp 0.25.0 → 0.26.0

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'
@@ -40,6 +42,11 @@ interface UiElement {
   _interactable?: boolean
   _sliderLike?: boolean
   state?: UIElementState | null
+  stable_id?: string | null
+  role?: string | null
+  test_tag?: string | null
+  selector?: { value: string | null, confidence: { score: number, reason: string } | null } | null
+  semantic?: { is_clickable: boolean, is_container: boolean } | null
 }
 
 interface ResolvedUiElementContext {
@@ -55,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
@@ -80,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
@@ -157,7 +175,13 @@ export class ToolsInteract {
       class: el.type ?? el.class ?? null,
       bounds,
       index,
-      elementId
+      elementId,
+      state: el.state ?? null,
+      stable_id: el.stable_id ?? null,
+      role: el.role ?? null,
+      test_tag: el.test_tag ?? null,
+      selector: el.selector ?? null,
+      semantic: el.semantic ?? null
     }
   }
 
@@ -184,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,
@@ -197,7 +281,12 @@ export class ToolsInteract {
       class: element.type ?? element.class ?? null,
       bounds: ToolsInteract._normalizeBounds(element.bounds),
       index,
-      state: element.state ?? null
+      state: element.state ?? null,
+      stable_id: element.stable_id ?? null,
+      role: element.role ?? null,
+      test_tag: element.test_tag ?? null,
+      selector: element.selector ?? null,
+      semantic: element.semantic ?? null
     }
   }
 
@@ -621,6 +710,11 @@ export class ToolsInteract {
       bounds: boundsObj,
       clickable: !!best.clickable,
       enabled: !!best.enabled,
+      stable_id: best.stable_id ?? null,
+      role: best.role ?? null,
+      test_tag: best.test_tag ?? null,
+      selector: best.selector ?? null,
+      semantic: best.semantic ?? null,
       tapCoordinates,
       telemetry: {
         matchedIndex: best?._index ?? null,
@@ -934,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,
@@ -1040,7 +1212,12 @@ export class ToolsInteract {
           class: result.element.class ?? null,
           bounds: result.element.bounds ?? null,
           index: typeof result.element.index === 'number' ? result.element.index : null,
-          state: (result.element as any).state ?? null
+          state: (result.element as any).state ?? null,
+          stable_id: (result.element as any).stable_id ?? null,
+          role: (result.element as any).role ?? null,
+          test_tag: (result.element as any).test_tag ?? null,
+          selector: (result.element as any).selector ?? null,
+          semantic: (result.element as any).semantic ?? null
         },
         observed: {
           status: result.status,
@@ -1055,7 +1232,12 @@ export class ToolsInteract {
             class: result.element.class ?? null,
             bounds: result.element.bounds ?? null,
             index: typeof result.element.index === 'number' ? result.element.index : null,
-            state: (result.element as any).state ?? null
+            state: (result.element as any).state ?? null,
+            stable_id: (result.element as any).stable_id ?? null,
+            role: (result.element as any).role ?? null,
+            test_tag: (result.element as any).test_tag ?? null,
+            selector: (result.element as any).selector ?? null,
+            semantic: (result.element as any).semantic ?? null
           }
         },
         reason: 'selector is visible'

package/src/observe/android.ts

@@ -7,6 +7,7 @@ import { promises as fsPromises } from "fs"
 import path from "path"
 import { computeScreenFingerprint } from "../utils/ui/index.js"
 import { parsePngSize } from "../utils/image.js"
+import { deriveSnapshotMetadata } from "./snapshot-metadata.js"
 
 const activeLogStreams: Map<string, { proc: any, file: string }> = new Map()
 
@@ -74,20 +75,29 @@ export class AndroidObserve {
           }
       }
 
+      const snapshotMetadata = deriveSnapshotMetadata(`android:${deviceInfo.id}`, {
+        screen: "",
+        resolution,
+        elements
+      }, 'ui_tree')
+
       return {
         device: deviceInfo,
         screen: "",
         resolution,
-        elements
+        elements,
+        ...snapshotMetadata
       };
     } catch (e) {
       const errorMessage = `Failed to get UI tree. ADB Path: '${getAdbCmd()}'. Error: ${e instanceof Error ? e.message : String(e)}`;
       console.error(errorMessage);
+      const snapshotMetadata = deriveSnapshotMetadata(`android:${deviceInfo.id}`, null, 'ui_tree')
       return {
           device: deviceInfo,
           screen: "",
           resolution: { width: 0, height: 0 },
           elements: [],
+          ...snapshotMetadata,
           error: errorMessage
       };
     }

package/src/observe/index.ts

@@ -5,6 +5,7 @@ import type {
   CaptureDebugSnapshotRawResponse,
   SnapshotSemanticResponse
 } from '../types.js'
+import { deriveSnapshotMetadata } from './snapshot-metadata.js'
 
 export { AndroidObserve } from './android.js'
 export { iOSObserve } from './ios.js'
@@ -21,6 +22,12 @@ interface SnapshotTreeElementLike {
   clickable?: boolean
   enabled?: boolean
   visible?: boolean
+  state?: unknown
+  stable_id?: string | null
+  role?: string | null
+  test_tag?: string | null
+  selector?: unknown
+  semantic?: unknown
 }
 
 interface SnapshotTreeLike {
@@ -239,7 +246,17 @@ export class ToolsObserve {
 
   static async captureDebugSnapshotHandler({ reason, includeLogs = true, logLines = 200, platform, appId, deviceId, sessionId }: { reason?: string; includeLogs?: boolean; logLines?: number; platform?: 'android' | 'ios'; appId?: string; deviceId?: string; sessionId?: string } = {}) {
     const timestamp = Date.now()
-    const raw: CaptureDebugSnapshotRawResponse = { timestamp, reason: reason || '', activity: null, fingerprint: null, screenshot: null, ui_tree: null, logs: [] }
+    const raw: CaptureDebugSnapshotRawResponse = {
+      timestamp,
+      snapshot_revision: 0,
+      captured_at_ms: timestamp,
+      reason: reason || '',
+      activity: null,
+      fingerprint: null,
+      screenshot: null,
+      ui_tree: null,
+      logs: []
+    }
 
     // Parallel fetches for performance: screenshot, current screen, fingerprint, ui tree, and log stream/get logs
     const sid = sessionId || 'default'
@@ -329,6 +346,20 @@ export class ToolsObserve {
       }
     }
 
+    const snapshotDeviceKey = raw.ui_tree?.device
+      ? `${raw.ui_tree.device.platform}:${raw.ui_tree.device.id}`
+      : `${platform || 'unknown'}:${deviceId || 'default'}`
+    const snapshotMetadata = deriveSnapshotMetadata(
+      snapshotDeviceKey,
+      raw.ui_tree,
+      'snapshot',
+      raw.ui_tree?.snapshot_revision ? null : (raw.fingerprint || raw.activity || null)
+    )
+
+    raw.snapshot_revision = raw.ui_tree?.snapshot_revision ?? snapshotMetadata.snapshot_revision
+    raw.captured_at_ms = raw.ui_tree?.captured_at_ms ?? snapshotMetadata.captured_at_ms
+    raw.loading_state = raw.ui_tree?.loading_state ?? snapshotMetadata.loading_state
+
     const semantic = deriveSnapshotSemantic(raw)
     return semantic ? { raw, semantic } : { raw }
   }

package/src/observe/ios.ts

@@ -1,12 +1,13 @@
 import { spawn } from "child_process"
 import { promises as fs } from "fs"
-import { GetLogsResponse, CaptureIOSScreenshotResponse, GetUITreeResponse, UIElement, DeviceInfo, UIElementState } from "../types.js"
+import { GetLogsResponse, CaptureIOSScreenshotResponse, GetUITreeResponse, UIElement, DeviceInfo, UIElementSemanticMetadata, UIElementState, UIResolutionSelector, SelectorConfidence } from "../types.js"
 import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcrunCmd, isIDBInstalled } from "../utils/ios/utils.js"
 import { createWriteStream, promises as fsPromises } from 'fs'
 import path from 'path'
 import { parseLogLine } from '../utils/android/utils.js'
 import { computeScreenFingerprint } from '../utils/ui/index.js'
 import { parsePngSize } from '../utils/image.js'
+import { deriveSnapshotMetadata } from './snapshot-metadata.js'
 
 const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
 let iosExecCommand = execCommand
@@ -22,6 +23,9 @@ export function _resetIOSExecCommandForTests() {
 interface IDBElement {
   AXFrame?: { x: number | string, y: number | string, width: number | string, height: number | string, w?: number | string, h?: number | string };
   frame?: { x: number | string, y: number | string, width: number | string, height: number | string, w?: number | string, h?: number | string };
+  AXIdentifier?: string;
+  accessibilityIdentifier?: string;
+  identifier?: string;
   AXUniqueId?: string;
   AXLabel?: string;
   AXValue?: string;
@@ -63,6 +67,59 @@ function parseIOSNumber(value: unknown): number | null {
   return Number.isFinite(parsed) ? parsed : null
 }
 
+function normalizeIOSType(value: unknown): string {
+  return typeof value === 'string' ? value.trim().toLowerCase() : ''
+}
+
+function inferIOSRole(type: string, traits: string[]): string | null {
+  if (/slider|adjustable/.test(type) || traits.some((trait) => /adjustable|slider/.test(trait))) return 'slider'
+  if (/button/.test(type) || traits.some((trait) => /button/.test(trait))) return 'button'
+  if (/cell/.test(type)) return 'cell'
+  if (/switch/.test(type)) return 'switch'
+  if (/text field|textfield|search field/.test(type)) return 'text_field'
+  if (/image/.test(type)) return 'image'
+  if (/window|application|group|scroll view|collection view/.test(type)) return 'container'
+  return null
+}
+
+function getIOSStableId(node: IDBElement): string | null {
+  const candidates = [node.AXIdentifier, node.accessibilityIdentifier, node.identifier, node.AXUniqueId]
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim().length > 0) return candidate
+  }
+  return null
+}
+
+function buildIOSSelectorConfidence(source: 'identifier' | 'label' | 'value' | 'type' | 'none'): SelectorConfidence | null {
+  switch (source) {
+    case 'identifier':
+      return { score: 1, reason: 'accessibility_identifier' }
+    case 'label':
+      return { score: 0.9, reason: 'label_match' }
+    case 'value':
+      return { score: 0.75, reason: 'value_match' }
+    case 'type':
+      return { score: 0.35, reason: 'type_match' }
+    default:
+      return null
+  }
+}
+
+function buildIOSSelector(type: string, label: string | null, value: string | null, stableId: string | null): UIResolutionSelector | null {
+  if (stableId) return { value: stableId, confidence: buildIOSSelectorConfidence('identifier') }
+  if (label) return { value: label, confidence: buildIOSSelectorConfidence('label') }
+  if (value) return { value: value, confidence: buildIOSSelectorConfidence('value') }
+  if (type) return { value: type, confidence: buildIOSSelectorConfidence('type') }
+  return null
+}
+
+function buildIOSSemantic(type: string, traits: string[]): UIElementSemanticMetadata {
+  return {
+    is_clickable: traits.includes("UIAccessibilityTraitButton") || /adjustable|slider/.test(type) || type === "Button" || type === "Cell",
+    is_container: /window|application|group|scroll view|collection view/.test(type)
+  }
+}
+
 function isIOSAdjustable(node: IDBElement, type: string, traits: string[]): boolean {
   return /slider|adjustable|stepper|progress/i.test(type) || traits.some((trait) => /adjustable|slider|progress/i.test(trait))
 }
@@ -124,6 +181,11 @@ export function traverseIDBNode(node: IDBElement, elements: UIElement[], parentI
   const frame = node.AXFrame || node.frame;
   const traits = node.AXTraits || [];
   const state = extractIOSState(node, type, label, value, traits);
+  const normalizedType = normalizeIOSType(type)
+  const stableId = getIOSStableId(node)
+  const selector = buildIOSSelector(type, label, value, stableId)
+  const semantic = buildIOSSemantic(normalizedType, traits)
+  const role = inferIOSRole(normalizedType, traits)
   
   const clickable = traits.includes("UIAccessibilityTraitButton") || type === "Button" || type === "Cell";
   
@@ -135,14 +197,19 @@ export function traverseIDBNode(node: IDBElement, elements: UIElement[], parentI
       text: label,
       contentDescription: value,
       type: type,
-      resourceId: node.AXUniqueId || null,
+      resourceId: stableId,
       clickable: clickable,
       enabled: true,
       visible: true,
       bounds: bounds,
       center: getCenter(bounds),
       depth: depth,
-      state
+      state,
+      stable_id: stableId,
+      role,
+      test_tag: stableId,
+      selector,
+      semantic
     };
 
     if (parentIndex !== -1) {
@@ -419,16 +486,19 @@ export class iOSObserve {
 
   async getUITree(deviceId: string = "booted"): Promise<GetUITreeResponse> {
     const device = await getIOSDeviceMetadata(deviceId);
+    const deviceKey = `ios:${device.id}`
     
     const idbExists = await isIDBInstalled();
     if (!idbExists) {
+       const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
        return {
           device,
           screen: "",
           resolution: { width: 0, height: 0 },
           elements: [],
+          ...snapshotMetadata,
           error: "iOS UI tree retrieval requires 'idb' (iOS Device Bridge). Please install it via Homebrew: `brew tap facebook/fb && brew install idb-companion` and `pip3 install fb-idb`."
-       };
+        };
     }
 
     const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
@@ -474,15 +544,17 @@ export class iOSObserve {
          console.error(`Attempt ${attempts} failed: ${e}`);
       }
       
-      if (attempts === maxAttempts) {
-          return {
-              device,
-              screen: "",
-              resolution: { width: 0, height: 0 },
-              elements: [],
-              error: `Failed to retrieve valid UI dump after ${maxAttempts} attempts.`
-          };
-      }
+       if (attempts === maxAttempts) {
+           const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
+           return {
+               device,
+               screen: "",
+               resolution: { width: 0, height: 0 },
+               elements: [],
+               ...snapshotMetadata,
+               error: `Failed to retrieve valid UI dump after ${maxAttempts} attempts.`
+           };
+       }
     }
 
     try {
@@ -503,20 +575,29 @@ export class iOSObserve {
             height = rootBounds[3] - rootBounds[1];
         }
 
+        const snapshotMetadata = deriveSnapshotMetadata(deviceKey, {
+          screen: "",
+          resolution: { width, height },
+          elements
+        }, 'ui_tree')
+
         return {
             device,
             screen: "",
             resolution: { width, height },
-            elements
+            elements,
+            ...snapshotMetadata
         };
     } catch (e) {
-         return {
+         const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
+          return {
             device,
             screen: "",
             resolution: { width: 0, height: 0 },
             elements: [],
+            ...snapshotMetadata,
             error: `Failed to parse idb output: ${e instanceof Error ? e.message : String(e)}`
-         };
+          };
     }
   }
 

package/src/observe/snapshot-metadata.ts

@@ -0,0 +1,107 @@
+import crypto from 'crypto'
+import type { GetUITreeResponse, LoadingState, UIElement } from '../types.js'
+
+interface SnapshotState {
+  revision: number
+  signature: string | null
+}
+
+const snapshotStateByDevice = new Map<string, SnapshotState>()
+
+function normalize(value: unknown): string {
+  if (value === null || value === undefined) return ''
+  return String(value).trim().toLowerCase()
+}
+
+function normalizeBounds(bounds: unknown): [number, number, number, number] | null {
+  if (!Array.isArray(bounds) || bounds.length < 4) return null
+  const normalized = bounds.slice(0, 4).map((value) => Number(value))
+  if (normalized.some((value) => Number.isNaN(value))) return null
+  return normalized as [number, number, number, number]
+}
+
+function stableElementSignature(element: UIElement) {
+  return {
+    text: normalize(element.text),
+    contentDescription: normalize(element.contentDescription),
+    resourceId: normalize(element.resourceId),
+    type: normalize(element.type),
+    stable_id: normalize(element.stable_id),
+    role: normalize(element.role),
+    test_tag: normalize(element.test_tag),
+    selector: normalize(element.selector?.value),
+    clickable: !!element.clickable,
+    enabled: !!element.enabled,
+    visible: !!element.visible,
+    state: element.state ?? null,
+    bounds: normalizeBounds(element.bounds)
+  }
+}
+
+export function computeSnapshotSignature(tree: Pick<GetUITreeResponse, 'elements' | 'screen' | 'resolution' | 'error'> | null | undefined): string | null {
+  if (!tree || tree.error) return null
+
+  const payload = {
+    screen: normalize(tree.screen),
+    resolution: tree.resolution || { width: 0, height: 0 },
+    elements: Array.isArray(tree.elements) ? tree.elements.map((element) => stableElementSignature(element)) : []
+  }
+
+  return crypto.createHash('sha256').update(JSON.stringify(payload)).digest('hex')
+}
+
+export function detectLoadingState(tree: Pick<GetUITreeResponse, 'elements' | 'error'> | null | undefined, source: string): LoadingState | null {
+  if (!tree || tree.error || !Array.isArray(tree.elements)) return null
+
+  for (const element of tree.elements) {
+    if (!element?.visible) continue
+    const text = normalize(element?.text ?? element?.contentDescription ?? '')
+    const type = normalize(element?.type ?? '')
+    const combined = `${type} ${text}`
+    if (/progress|spinner|loading|please wait|busy|loading indicator|skeleton|pending/.test(combined)) {
+      const signal = /progress/.test(combined)
+        ? 'progress_indicator'
+        : /spinner/.test(combined)
+          ? 'spinner'
+          : /busy/.test(combined)
+            ? 'busy_indicator'
+            : /skeleton/.test(combined)
+              ? 'skeleton'
+              : 'loading_indicator'
+      return { active: true, signal, source }
+    }
+  }
+
+  return null
+}
+
+export function deriveSnapshotMetadata(
+  deviceKey: string,
+  tree: Pick<GetUITreeResponse, 'elements' | 'screen' | 'resolution' | 'error'> | null | undefined,
+  source: string,
+  signatureOverride?: string | null
+) {
+  const signature = signatureOverride ?? computeSnapshotSignature(tree)
+  const previous = snapshotStateByDevice.get(deviceKey)
+
+  let revision = 1
+  if (previous) {
+    if (signature === null) {
+      revision = previous.revision
+    } else {
+      revision = previous.signature === signature ? previous.revision : previous.revision + 1
+    }
+  }
+
+  snapshotStateByDevice.set(deviceKey, { revision, signature })
+
+  return {
+    snapshot_revision: revision,
+    captured_at_ms: Date.now(),
+    loading_state: detectLoadingState(tree, source)
+  }
+}
+
+export function resetSnapshotMetadataForTests() {
+  snapshotStateByDevice.clear()
+}