mobile-debug-mcp 0.33.0 → 0.35.0

package/dist/observe/logs/model.js

@@ -0,0 +1 @@
+export {};

package/dist/{network → observe/network}/index.js

@@ -1,5 +1,5 @@
-import { execAdb, parseLogLine } from '../utils/android/utils.js';
-import { execCommand } from '../utils/ios/utils.js';
+import { execAdb, parseLogLine } from '../../utils/android/utils.js';
+import { execCommand } from '../../utils/ios/utils.js';
 // ─── Module state ─────────────────────────────────────────────────────────────
 // lastActionTimestamp: set when an action tool fires (tap, swipe, etc.)
 // lastConsumedTimestamp: advanced after each get_network_activity call to prevent duplicates

package/dist/observe/readiness-service.js

@@ -1,3 +1,4 @@
+import { pausedReadiness } from '../debugger/guard.js';
 import { resolveTargetDevice, withResolvedDevice } from '../utils/resolve-device.js';
 import { remainingBudget, runWithBudget } from '../utils/operation-budget.js';
 import { ToolsObserve } from './index.js';
@@ -32,6 +33,7 @@ export async function getAppReadiness(args, wait = false) {
     let device = null;
     let tracker = new ReadinessTracker(args.platform ?? 'android', args.deviceId ?? '');
     let failureCode;
+    let debugPause = null;
     await runWithBudget(args.timeoutMs ?? (wait ? 30000 : 15000), async () => {
         try {
             device = await resolve(args);
@@ -41,6 +43,11 @@ export async function getAppReadiness(args, wait = false) {
                 let count = 0;
                 while (wait || count < 2) {
                     remainingBudget();
+                    debugPause = device.platform === 'android' ? pausedReadiness(device.id) : null;
+                    if (debugPause) {
+                        failureCode = wait ? 'DEBUGGER_PAUSED' : undefined;
+                        return;
+                    }
                     const captureStarted = Date.now();
                     try {
                         const tree = await ToolsObserve.getUITreeHandler({ platform: device.platform, deviceId: device.id });
@@ -78,10 +85,14 @@ export async function getAppReadiness(args, wait = false) {
             failureCode = !expired && (!device || isDeviceUnavailable(error)) ? 'DEVICE_UNAVAILABLE' : wait ? 'READINESS_TIMEOUT' : 'READINESS_UNAVAILABLE';
         }
     });
+    if (debugPause)
+        return { success: !wait, device, readiness: debugPause, elapsed_ms: performance.now() - started, ...(wait ? { failure_code: 'DEBUGGER_PAUSED' } : {}) };
     const state = tracker.summary.state;
     const success = !failureCode && (wait ? state === 'settled' : state !== 'unknown');
-    return { success, device, readiness: tracker.summary, elapsed_ms: performance.now() - started,
-        ...(!success ? { failure_code: failureCode ?? (wait ? 'READINESS_TIMEOUT' : 'READINESS_UNAVAILABLE') } : {}) };
+    return {
+        success, device, readiness: tracker.summary, elapsed_ms: performance.now() - started,
+        ...(!success ? { failure_code: failureCode ?? (wait ? 'READINESS_TIMEOUT' : 'READINESS_UNAVAILABLE') } : {})
+    };
 }
 export async function withReadyWait(target, timeoutMs, operation, failure) {
     const started = performance.now();

package/dist/observe/readiness.js

@@ -1,7 +1,8 @@
+import { pausedReadiness } from '../debugger/guard.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { remainingBudget } from '../utils/operation-budget.js';
 import { computeSnapshotSignature, getSnapshotSessionId } from './snapshot-metadata.js';
-const baselineLimitations = ['NORMALIZED_UI_ONLY', 'FOREGROUND_APP_UNVERIFIED', 'UNRESPONSIVE_SIGNAL_UNSUPPORTED', 'DEBUGGER_SIGNAL_UNSUPPORTED'];
+const baselineLimitations = ['NORMALIZED_UI_ONLY', 'FOREGROUND_APP_UNVERIFIED', 'UNRESPONSIVE_SIGNAL_UNSUPPORTED'];
 const capabilities = { loading: true, transitioning: true, settled: true, unresponsive: false, debugger_paused: false };
 export function isDeviceUnavailable(error) {
     return /device.*(?:not found|offline|disconnected)|no devices found|READINESS_DEVICE_UNAVAILABLE/i.test(String(error));
@@ -12,35 +13,40 @@ export class ReadinessTracker {
     stabilityMs;
     signature = null;
     stableSince = 0;
-    summary = {
-        state: 'unknown', scope: 'device_ui', basis: 'insufficient', captured_at_ms: null,
-        sample_count: 0, stable_for_ms: 0, snapshot_session_id: null, snapshot_revision: null,
-        evidence: [], limitations: [...baselineLimitations, 'INSUFFICIENT_SAMPLES'], capabilities: { ...capabilities }
-    };
+    summary;
     constructor(platform, deviceId, stabilityMs = 500) {
         this.platform = platform;
         this.deviceId = deviceId;
         this.stabilityMs = stabilityMs;
+        this.summary = {
+            state: 'unknown', scope: 'device_ui', basis: 'insufficient', captured_at_ms: null,
+            sample_count: 0, stable_for_ms: 0, snapshot_session_id: null, snapshot_revision: null,
+            evidence: [], limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', 'INSUFFICIENT_SAMPLES'], capabilities: { ...capabilities, debugger_paused: this.platform === 'android' }
+        };
     }
     unavailable(code = 'OBSERVATION_FAILED') {
         this.signature = null;
-        this.summary = { ...this.summary, state: 'unknown', basis: 'insufficient', stable_for_ms: 0,
-            sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, code],
-            evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: null, snapshot_revision: null }].slice(-8) };
+        this.summary = {
+            ...this.summary, state: 'unknown', basis: 'insufficient', stable_for_ms: 0,
+            sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', code],
+            evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: null, snapshot_revision: null }].slice(-8)
+        };
         return this.summary;
     }
     deadline() {
         this.summary = { ...this.summary, limitations: [...new Set([...this.summary.limitations, 'DEADLINE_EXCEEDED'])] };
         return this.summary;
     }
-    observe(tree, acquisitionStartedAtMs, now = performance.now()) {
+    observe(sample, acquisitionStartedAtMs, now = performance.now()) {
+        const paused = this.platform === 'android' ? pausedReadiness(this.deviceId) : null;
+        if (paused) {
+            this.summary = paused;
+            return this.summary;
+        }
+        const tree = sample;
         if (tree?.error)
             return this.unavailable('OBSERVATION_FAILED');
-        if (!tree || tree.device?.platform !== this.platform || tree.device?.id !== this.deviceId ||
-            tree.snapshot_session_id !== getSnapshotSessionId() || !Number.isSafeInteger(tree.snapshot_revision) || tree.snapshot_revision <= 0 ||
-            !Number.isFinite(tree.captured_at_ms) || tree.captured_at_ms < acquisitionStartedAtMs || tree.captured_at_ms <= 0 ||
-            !Array.isArray(tree.elements) || !tree.elements.length || tree.elements.some((element) => !element || typeof element !== 'object') ||
-            !Number.isFinite(tree.resolution?.width) || !Number.isFinite(tree.resolution?.height) || tree.resolution.width <= 0 || tree.resolution.height <= 0)
+        if (!validReadinessSample(tree, this.platform, this.deviceId, acquisitionStartedAtMs))
             return this.unavailable('OBSERVATION_INVALID');
         const signature = computeSnapshotSignature(tree);
         if (!signature)
@@ -53,18 +59,32 @@ export class ReadinessTracker {
             this.stableSince = now;
         this.signature = signature;
         const stableFor = unchanged && !nativeLoading && !textLoading ? Math.max(0, now - this.stableSince) : 0;
-        const state = nativeLoading || textLoading ? 'loading' : !previous ? 'unknown' : !unchanged ? 'transitioning' : stableFor >= this.stabilityMs ? 'settled' : 'unknown';
-        const code = nativeLoading ? 'NATIVE_LOADING_INDICATOR' : textLoading ? 'LOADING_LABEL' : state === 'transitioning' ? 'SNAPSHOT_CHANGED' : state === 'settled' ? 'SNAPSHOT_STABLE' : 'INSUFFICIENT_SAMPLES';
+        const state = readinessState(nativeLoading || textLoading, previous, unchanged, stableFor, this.stabilityMs);
+        const code = readinessCode(nativeLoading, textLoading, state);
         this.summary = {
             state, scope: 'device_ui', basis: textLoading && !nativeLoading ? 'heuristic' : state === 'unknown' ? 'insufficient' : 'observed',
             captured_at_ms: tree.captured_at_ms, snapshot_session_id: tree.snapshot_session_id, snapshot_revision: tree.snapshot_revision,
             sample_count: this.summary.sample_count + 1, stable_for_ms: stableFor,
             evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: tree.captured_at_ms, snapshot_revision: tree.snapshot_revision }].slice(-8),
-            limitations: [...baselineLimitations, ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities }
+            limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities, debugger_paused: this.platform === 'android' }
         };
         return this.summary;
     }
 }
+function validReadinessSample(tree, platform, deviceId, acquisitionStartedAtMs) {
+    return !!tree && validIdentity(tree, platform, deviceId) && validFreshness(tree, acquisitionStartedAtMs) && validGeometry(tree);
+}
+function validIdentity(tree, platform, deviceId) {
+    return tree.device?.platform === platform && tree.device?.id === deviceId &&
+        tree.snapshot_session_id === getSnapshotSessionId() && Number.isSafeInteger(tree.snapshot_revision) && tree.snapshot_revision > 0;
+}
+function validFreshness(tree, startedAtMs) {
+    return Number.isFinite(tree.captured_at_ms) && !(tree.captured_at_ms < startedAtMs) && tree.captured_at_ms > 0;
+}
+function validGeometry(tree) {
+    return Array.isArray(tree.elements) && tree.elements.length > 0 && !tree.elements.some((element) => !element || typeof element !== 'object') &&
+        Number.isFinite(tree.resolution?.width) && Number.isFinite(tree.resolution?.height) && tree.resolution.width > 0 && tree.resolution.height > 0;
+}
 const waits = new AsyncLocalStorage();
 export function currentReadinessWait() { return waits.getStore(); }
 export function withReadinessTracker(tracker, operation) { return waits.run(tracker, operation); }
@@ -79,3 +99,9 @@ export function observeReadinessWait(tree, startedAtMs) {
     if (summary.limitations.some(code => ['OBSERVATION_INVALID', 'OBSERVATION_FAILED'].includes(code)))
         throw new Error('READINESS_SAMPLE_INVALID');
 }
+function readinessState(loading, previous, unchanged, stableFor, stabilityMs) {
+    return loading ? 'loading' : !previous ? 'unknown' : !unchanged ? 'transitioning' : stableFor >= stabilityMs ? 'settled' : 'unknown';
+}
+function readinessCode(nativeLoading, textLoading, state) {
+    return nativeLoading ? 'NATIVE_LOADING_INDICATOR' : textLoading ? 'LOADING_LABEL' : state === 'transitioning' ? 'SNAPSHOT_CHANGED' : state === 'settled' ? 'SNAPSHOT_STABLE' : 'INSUFFICIENT_SAMPLES';
+}

package/dist/observe/screenshot-encoding.js

@@ -0,0 +1,41 @@
+async function convert(buffer, platform) {
+    const { default: sharp } = await import('sharp');
+    const image = sharp(buffer);
+    const meta = await image.metadata().catch((error) => {
+        console.error(platform === 'android' ? 'sharp.metadata failed (Android):' : 'sharp.metadata failed:', error);
+        return {};
+    });
+    const hasAlpha = !!meta.hasAlpha || !!(meta.channels && meta.channels > 3);
+    let webp = null, jpeg = null;
+    try {
+        webp = await image.webp({ quality: 80 }).toBuffer();
+    }
+    catch (error) {
+        console.error(`WebP conversion failed (${platform === 'android' ? 'Android' : 'iOS'}):`, error instanceof Error ? error.message : String(error));
+    }
+    try {
+        jpeg = await image.jpeg({ quality: 80 }).toBuffer();
+    }
+    catch (error) {
+        console.error(`JPEG conversion failed (${platform === 'android' ? 'Android' : 'iOS'}):`, error instanceof Error ? error.message : String(error));
+    }
+    return { hasAlpha, webp, jpeg };
+}
+export async function encodeScreenshot(buffer, platform) {
+    const png = buffer.toString('base64');
+    try {
+        const { hasAlpha, webp, jpeg } = await convert(buffer, platform);
+        if (webp) {
+            if (hasAlpha && platform === 'ios')
+                return { screenshot: webp.toString('base64'), screenshot_mime: 'image/webp', screenshot_fallback: png, screenshot_fallback_mime: 'image/png' };
+            const fallback = jpeg ? jpeg.toString('base64') : platform === 'android' ? null : undefined;
+            return { screenshot: webp.toString('base64'), screenshot_mime: 'image/webp', screenshot_fallback: fallback, screenshot_fallback_mime: jpeg ? 'image/jpeg' : undefined };
+        }
+        if (!hasAlpha && jpeg)
+            return { screenshot: jpeg.toString('base64'), screenshot_mime: 'image/jpeg' };
+    }
+    catch (error) {
+        console.error(`Screenshot conversion pipeline failed (${platform === 'android' ? 'Android' : 'iOS'}):`, error instanceof Error ? error.message : String(error));
+    }
+    return { screenshot: png, screenshot_mime: 'image/png' };
+}

package/dist/observe/snapshot-collection.js

@@ -0,0 +1,79 @@
+import { omitEvidence } from './evidence.js';
+import { measure } from '../utils/timing.js';
+import { deriveSnapshotMetadata } from './snapshot-metadata.js';
+import { deriveSnapshotSemantic } from './snapshot-semantic.js';
+import { snapshotLog, streamLog } from './snapshot-logs.js';
+async function settle(tasks) {
+    const results = await Promise.allSettled(Object.values(tasks));
+    return Object.fromEntries(Object.keys(tasks).map((key, index) => [key, results[index]]));
+}
+function apply(result, success, failure) {
+    if (result.status === 'fulfilled')
+        success(result.value);
+    else
+        failure(result.reason instanceof Error ? result.reason.message : String(result.reason));
+}
+async function collect(raw, input, deps) {
+    const { platform, deviceId, includeScreenshot = true, includeLogs = true, sessionId, logLines = 200 } = input;
+    const results = await settle({
+        screenshot: includeScreenshot ? measure('screenshot_ms', () => deps.captureScreenshotHandler({ platform, deviceId })) : Promise.resolve(null),
+        currentScreen: !platform || platform === 'android' ? deps.getCurrentScreenHandler({ deviceId }) : Promise.resolve(null),
+        fingerprint: deps.getScreenFingerprintHandler({ platform, deviceId }),
+        uiTree: deps.getUITreeHandler({ platform, deviceId }),
+        readLogStream: includeLogs ? deps.readLogStreamHandler({ platform, deviceId, sessionId: sessionId || 'default', limit: logLines }) : Promise.resolve({ entries: [] })
+    });
+    let entries = [];
+    apply(results.screenshot, value => { raw.screenshot = value && value.screenshot ? value.screenshot : null; }, error => { raw.screenshot_error = error; });
+    apply(results.currentScreen, value => { raw.activity = value && (value.activity || value.shortActivity) ? value.activity || value.shortActivity : raw.activity || ''; }, error => { raw.activity_error = error; });
+    apply(results.fingerprint, value => {
+        if (value && value.fingerprint)
+            raw.fingerprint = value.fingerprint;
+        if (value && value.activity)
+            raw.activity = raw.activity || value.activity;
+        if (value && value.error)
+            raw.fingerprint_error = value.error;
+    }, error => { raw.fingerprint = null; raw.fingerprint_error = error; });
+    apply(results.uiTree, value => { raw.ui_tree = value; if (value && value.error)
+        raw.ui_tree_error = value.error; }, error => { raw.ui_tree = null; raw.ui_tree_error = error; });
+    apply(results.readLogStream, value => { entries = Array.isArray(value?.entries) ? value.entries : []; }, error => { raw.logs_error = error; });
+    return entries;
+}
+async function collectLogs(entries, input, deps) {
+    if (entries.length)
+        return entries.map(streamLog);
+    const { platform, appId, deviceId, logLines = 200 } = input;
+    const response = await deps.getLogsHandler({ platform, appId, deviceId, lines: logLines });
+    return (response && response.logs ? response.logs : []).slice(-Math.max(0, logLines)).map(snapshotLog);
+}
+function metadata(raw, input) {
+    const key = raw.ui_tree?.device ? `${raw.ui_tree.device.platform}:${raw.ui_tree.device.id}` : `${input.platform || 'unknown'}:${input.deviceId || 'default'}`;
+    const value = deriveSnapshotMetadata(key, raw.ui_tree, 'snapshot', raw.ui_tree?.snapshot_revision ? null : raw.fingerprint || raw.activity || null);
+    raw.snapshot_revision = raw.ui_tree?.snapshot_revision ?? value.snapshot_revision;
+    raw.captured_at_ms = raw.ui_tree?.captured_at_ms ?? value.captured_at_ms;
+    raw.snapshot_delta = raw.ui_tree?.snapshot_delta ?? value.snapshot_delta ?? null;
+    raw.loading_state = raw.ui_tree?.loading_state ?? value.loading_state;
+}
+export async function collectDebugSnapshot(input = {}, deps) {
+    if (input.includeScreenshot === false)
+        omitEvidence('screenshot');
+    if (input.includeLogs === false)
+        omitEvidence('logs');
+    const timestamp = Date.now();
+    const raw = {
+        timestamp, snapshot_revision: 0, captured_at_ms: timestamp,
+        reason: input.reason || '', activity: null, fingerprint: null, screenshot: null, ui_tree: null, logs: []
+    };
+    const entries = await collect(raw, input, deps);
+    if (input.includeLogs !== false) {
+        try {
+            raw.logs = await collectLogs(entries, input, deps);
+        }
+        catch (error) {
+            raw.logs = [];
+            raw.logs_error = error instanceof Error ? error.message : String(error);
+        }
+    }
+    metadata(raw, input);
+    const semantic = deriveSnapshotSemantic(raw);
+    return semantic ? { raw, semantic } : { raw };
+}

package/dist/observe/snapshot-logs.js

@@ -0,0 +1,30 @@
+function levelOf(message, raw, stream) {
+    return (raw && String(raw).toUpperCase()) || (stream
+        ? /\bERROR\b/i.test(message) ? 'ERROR' : /\bWARN\b/i.test(message) ? 'WARN' : 'INFO'
+        : /\b(FATAL EXCEPTION|ERROR| E )\b/i.test(message) ? 'ERROR' : /\b(WARN| W )\b/i.test(message) ? 'WARN' : 'INFO');
+}
+export function snapshotLog(item) {
+    if (!item)
+        return { timestamp: null, level: 'INFO', message: '' };
+    if (typeof item === 'string')
+        return { timestamp: null, level: levelOf(item, undefined, false), message: item };
+    const fields = item;
+    const message = fields.message || fields.msg || JSON.stringify(item);
+    const raw = fields.level || fields.levelName || fields._level || '';
+    const time = fields.timestamp || fields._iso || null;
+    const timestamp = time && typeof time === 'string' ? (isNaN(new Date(time).getTime()) ? null : new Date(time).getTime()) : typeof time === 'number' ? time : null;
+    return { timestamp, level: levelOf(message, raw, true), message };
+}
+export function streamLog(item) {
+    const fields = item;
+    const message = fields && (fields.message || fields.msg) ? fields.message || fields.msg : typeof item === 'string' ? item : JSON.stringify(item);
+    const raw = fields && (fields.level || fields.levelName || fields._level) ? fields.level || fields.levelName || fields._level : '';
+    const iso = fields && (fields._iso || fields.timestamp);
+    let timestamp = null;
+    if (iso && typeof iso === 'string') {
+        const date = new Date(iso);
+        if (!isNaN(date.getTime()))
+            timestamp = date.getTime();
+    }
+    return { timestamp, level: levelOf(message, raw, true), message };
+}

package/dist/observe/snapshot-metadata.js

@@ -133,35 +133,9 @@ export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverrid
     const previous = existing && Date.now() - existing.updatedAt <= 10 * 60 * 1000 ? existing : undefined;
     if (!previous && existing)
         snapshotStateByDevice.delete(deviceKey);
-    const hasValidTree = !!tree && !tree.error;
-    const records = hasValidTree ? buildElementRecords(tree) : null;
-    const currentElementSignatures = records?.signatures ?? previous?.elementSignatures ?? new Map();
-    const currentElements = records?.elementsByIdentity ?? previous?.elements ?? new Map();
+    const { hasValidTree, currentElementSignatures, currentElements } = snapshotRecords(tree, previous);
     const revision = previous && (signature === null || previous.signature === signature) ? previous.revision : nextRevision++;
-    const history = previous?.history ?? new Map();
-    const historyTimes = previous?.historyTimes ?? new Map();
-    const oversized = previous?.oversized ?? new Map();
-    if (hasValidTree) {
-        history.set(revision, currentElements);
-        historyTimes.set(revision, Date.now());
-        if ((tree.elements?.length ?? 0) > 500)
-            oversized.set(revision, (tree.elements?.length ?? 0) - 500);
-    }
-    for (const [id, timestamp] of historyTimes) {
-        if (Date.now() - timestamp > 10 * 60 * 1000) {
-            history.delete(id);
-            historyTimes.delete(id);
-            oversized.delete(id);
-        }
-    }
-    while (history.size > 8) {
-        const oldest = history.keys().next().value;
-        if (oldest === undefined)
-            break;
-        history.delete(oldest);
-        historyTimes.delete(oldest);
-        oversized.delete(oldest);
-    }
+    const { history, historyTimes, oversized } = retainHistory(previous, revision, currentElements, tree, hasValidTree);
     snapshotStateByDevice.set(deviceKey, {
         revision,
         signature,
@@ -199,19 +173,20 @@ export function getStateDelta(deviceKey, baseRevision, currentRevision) {
     let index = 0;
     for (const [identity, element] of base) {
         if (!current.has(identity))
-            removed.push({ stable_id: element.stable_id ?? undefined, resourceId: element.resourceId ?? undefined, contentDescription: element.contentDescription ?? undefined, text: element.text ?? undefined, index });
+            removed.push(removedElement(element, index));
         index++;
     }
     const all = added.length + changed.length + removed.length;
     const limit = 200;
+    const truncated = all > limit || state.oversized.has(baseRevision) || state.oversized.has(currentRevision);
     return {
         base_snapshot_revision: baseRevision,
         snapshot_revision: currentRevision,
         added: added.slice(0, limit),
         changed: changed.slice(0, Math.max(0, limit - added.length)),
         removed: removed.slice(0, Math.max(0, limit - added.length - changed.length)),
-        truncated: all > limit || state.oversized.has(baseRevision) || state.oversized.has(currentRevision),
-        ...((all > limit || state.oversized.has(baseRevision) || state.oversized.has(currentRevision))
+        truncated,
+        ...((truncated)
             ? { omitted_changes: Math.max(all - limit, state.oversized.get(baseRevision) ?? 0, state.oversized.get(currentRevision) ?? 0) } : {})
     };
 }
@@ -234,3 +209,40 @@ export function resetSnapshotMetadataForTests() {
     snapshotStateByDevice.clear();
     nextRevision = 1;
 }
+function retainHistory(previous, revision, currentElements, tree, hasValidTree) {
+    const history = previous?.history ?? new Map();
+    const historyTimes = previous?.historyTimes ?? new Map();
+    const oversized = previous?.oversized ?? new Map();
+    if (hasValidTree) {
+        history.set(revision, currentElements);
+        historyTimes.set(revision, Date.now());
+        if ((tree.elements?.length ?? 0) > 500)
+            oversized.set(revision, (tree.elements?.length ?? 0) - 500);
+    }
+    for (const [id, timestamp] of historyTimes) {
+        if (Date.now() - timestamp > 10 * 60 * 1000) {
+            history.delete(id);
+            historyTimes.delete(id);
+            oversized.delete(id);
+        }
+    }
+    while (history.size > 8) {
+        const oldest = history.keys().next().value;
+        if (oldest === undefined)
+            break;
+        history.delete(oldest);
+        historyTimes.delete(oldest);
+        oversized.delete(oldest);
+    }
+    return { history, historyTimes, oversized };
+}
+function snapshotRecords(tree, previous) {
+    const hasValidTree = !!tree && !tree.error;
+    const records = hasValidTree ? buildElementRecords(tree) : null;
+    const currentElementSignatures = records?.signatures ?? previous?.elementSignatures ?? new Map();
+    const currentElements = records?.elementsByIdentity ?? previous?.elements ?? new Map();
+    return { hasValidTree, currentElementSignatures, currentElements };
+}
+function removedElement(element, index) {
+    return { stable_id: element.stable_id ?? undefined, resourceId: element.resourceId ?? undefined, contentDescription: element.contentDescription ?? undefined, text: element.text ?? undefined, index };
+}

package/dist/observe/snapshot-semantic.js

@@ -0,0 +1,115 @@
+export function normalizeHint(value) {
+    if (value === null || value === undefined)
+        return '';
+    return String(value).trim().replace(/\s+/g, ' ').toLowerCase();
+}
+export function titleCase(value) {
+    return value
+        .replace(/[_-]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/\b\w/g, (match) => match.toUpperCase());
+}
+export function shortActivityName(activity) {
+    if (!activity)
+        return null;
+    const trimmed = String(activity).trim();
+    if (!trimmed)
+        return null;
+    const lastSegment = trimmed.split('.').pop() || trimmed;
+    const withoutSuffix = lastSegment.replace(/Activity$/, '');
+    return withoutSuffix ? titleCase(withoutSuffix) : titleCase(lastSegment);
+}
+function elementText(element) {
+    return normalizeHint(element?.text ?? element?.contentDescription ?? element?.contentDesc ?? element?.accessibilityLabel ?? element?.resourceId ?? element?.id ?? '');
+}
+export function collectSnapshotTexts(tree) {
+    const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+    const texts = [];
+    const actionables = [];
+    for (const element of elements) {
+        const text = elementText(element);
+        if (text)
+            texts.push(text);
+        if (element?.clickable && element?.enabled !== false && text) {
+            actionables.push(text);
+        }
+    }
+    return {
+        texts: Array.from(new Set(texts)),
+        actionables: Array.from(new Set(actionables))
+    };
+}
+export function inferSnapshotScreen(raw) {
+    const tree = raw.ui_tree;
+    const treeScreen = normalizeHint(tree?.screen);
+    if (treeScreen)
+        return titleCase(treeScreen);
+    const activity = shortActivityName(raw.activity);
+    if (activity)
+        return activity;
+    const { texts } = collectSnapshotTexts(tree);
+    if (texts.length > 0)
+        return titleCase(texts[0]);
+    return null;
+}
+export function deriveSnapshotSemantic(raw) {
+    const tree = raw.ui_tree;
+    const { texts, actionables } = collectSnapshotTexts(tree);
+    const screenFromTree = normalizeHint(tree?.screen);
+    const activityHint = normalizeHint(raw.activity);
+    const screen = inferSnapshotScreen(raw);
+    if (!screen && !activityHint && texts.length === 0 && !raw.logs.length)
+        return null;
+    const hasErrorLogs = raw.logs.some((entry) => /error|fatal exception|exception|failed/i.test(entry.message));
+    const hasLoadingSignals = texts.some((text) => /loading|please wait|spinner|progress/i.test(text));
+    const hasPrimaryText = texts.some((text) => /sign in|log in|login|home|checkout|settings|menu|profile|search/i.test(text));
+    const hasScreenshot = typeof raw.screenshot === 'string' && raw.screenshot.length > 0;
+    const hasUiTree = !!tree && Array.isArray(tree.elements);
+    const signals = {
+        has_activity: !!activityHint,
+        has_ui_tree: hasUiTree,
+        has_screenshot: hasScreenshot,
+        has_visible_text: texts.length > 0,
+        has_clickable_elements: actionables.length > 0,
+        has_error_logs: hasErrorLogs,
+        has_loading_signals: hasLoadingSignals,
+        has_primary_text: hasPrimaryText
+    };
+    const warnings = snapshotWarnings(screenFromTree, activityHint, hasUiTree, hasErrorLogs);
+    const confidence = snapshotConfidence(hasUiTree, screen, activityHint, actionables.length, texts.length, hasScreenshot, hasErrorLogs, hasLoadingSignals);
+    if (!screen && confidence < 0.3)
+        return null;
+    return {
+        screen,
+        signals,
+        actions_available: actionables.length > 0 ? actionables.slice(0, 10) : null,
+        confidence,
+        warnings
+    };
+}
+function snapshotWarnings(screenFromTree, activityHint, hasUiTree, hasErrorLogs) {
+    const warnings = [];
+    if (screenFromTree && activityHint && screenFromTree !== activityHint) {
+        warnings.push('ui_tree.screen and activity hints differ');
+    }
+    if (!hasUiTree)
+        warnings.push('ui tree unavailable');
+    if (!activityHint)
+        warnings.push('activity unavailable');
+    if (hasErrorLogs)
+        warnings.push('error signals present in logs');
+    return warnings;
+}
+function snapshotConfidence(hasUiTree, screen, activityHint, actionableCount, textCount, hasScreenshot, hasErrorLogs, hasLoadingSignals) {
+    const evidenceScore = (hasUiTree ? 0.35 : 0) +
+        (screen ? 0.2 : 0) +
+        (activityHint ? 0.15 : 0) +
+        (actionableCount > 0 ? 0.15 : 0) +
+        (textCount > 0 ? 0.1 : 0) +
+        (hasScreenshot ? 0.05 : 0) +
+        (hasErrorLogs ? -0.15 : 0) +
+        (hasLoadingSignals ? -0.05 : 0);
+    const confidence = Math.max(0, Math.min(1, Number(evidenceScore.toFixed(2))));
+    return confidence;
+}