mobile-debug-mcp 0.34.0 → 0.35.0

package/dist/utils/cli/ios/preflight-ios.js

@@ -22,11 +22,10 @@ async function findFirst(root, patterns, maxDepth = 4) {
             console.error('DEBUG findFirst: entries', ents.map(e => e.name));
             for (const e of ents) {
                 const full = path.join(dir, e.name);
-                for (const p of patterns) {
-                    if (e.name.endsWith(p)) {
-                        console.error('DEBUG findFirst: matched', full);
-                        return full;
-                    }
+                const matched = patterns.some(pattern => e.name.endsWith(pattern));
+                if (matched) {
+                    console.error('DEBUG findFirst: matched', full);
+                    return full;
                 }
                 if (e.isDirectory() && depth < maxDepth)
                     queue.push({ dir: full, depth: depth + 1 });
@@ -52,26 +51,7 @@ function startCompanionIfNeeded(companionPath, udid) {
     }
 }
 async function main() {
-    const args = process.argv.slice(2);
-    let projectArg;
-    let udid;
-    let startCompanion = false;
-    let kmpBuild = null;
-    for (let i = 0; i < args.length; i++) {
-        const a = args[i];
-        if (a === '--project' && args[i + 1]) {
-            projectArg = args[i + 1];
-            i++;
-        }
-        else if (a === '--udid' && args[i + 1]) {
-            udid = args[i + 1];
-            i++;
-        }
-        else if (a === '--start-companion')
-            startCompanion = true;
-        else if (!projectArg)
-            projectArg = a;
-    }
+    const { projectArg, udid, startCompanion, kmpBuild } = argumentsForPreflight(process.argv.slice(2));
     const cwd = process.cwd();
     const projectRoot = projectArg ? path.resolve(projectArg) : cwd;
     // If user passed a direct .xcodeproj or .xcworkspace path, accept it as the projectFile
@@ -108,15 +88,8 @@ async function main() {
     // 4) idb_companion
     const companionPath = commandWhich('idb_companion');
     const companionAvailable = !!companionPath;
-    const suggestions = [];
-    if (!projectFile)
-        suggestions.push('Provide correct project path or ensure .xcodeproj/.xcworkspace exists in project dir');
-    if (!kmpFramework)
-        suggestions.push('Run KMP Gradle task to produce Shared.framework before xcodebuild (e.g., :shared:embedAndSignAppleFrameworkForXcode)');
-    if (!idbAvailable)
-        suggestions.push('Ensure idb is in PATH or set MCP_IDB_PATH / IDB_PATH');
-    if (!companionAvailable)
-        suggestions.push('Install idb_companion and ensure it is in PATH');
+    const suggestions = preflightSuggestions(projectFile, kmpFramework, idbAvailable, companionAvailable);
+    const companionInfo = { cmd: companionPath, installed: companionAvailable };
     const result = {
         ok: !!projectFile && !!idbAvailable,
         project: {
@@ -133,10 +106,7 @@ async function main() {
             cmd: idbPath,
             installed: idbAvailable
         },
-        idb_companion: {
-            cmd: companionPath,
-            installed: companionAvailable
-        },
+        idb_companion: companionInfo,
         suggestions
     };
     if (startCompanion && udid) {
@@ -153,3 +123,37 @@ main().catch(e => {
     console.log(JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }, null, 2));
     process.exit(2);
 });
+function argumentsForPreflight(args) {
+    let projectArg;
+    let udid;
+    let startCompanion = false;
+    const kmpBuild = null;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--project' && args[i + 1]) {
+            projectArg = args[i + 1];
+            i++;
+        }
+        else if (a === '--udid' && args[i + 1]) {
+            udid = args[i + 1];
+            i++;
+        }
+        else if (a === '--start-companion')
+            startCompanion = true;
+        else if (!projectArg)
+            projectArg = a;
+    }
+    return { projectArg, udid, startCompanion, kmpBuild };
+}
+function preflightSuggestions(projectFile, kmpFramework, idbAvailable, companionAvailable) {
+    const suggestions = [];
+    if (!projectFile)
+        suggestions.push('Provide correct project path or ensure .xcodeproj/.xcworkspace exists in project dir');
+    if (!kmpFramework)
+        suggestions.push('Run KMP Gradle task to produce Shared.framework before xcodebuild (e.g., :shared:embedAndSignAppleFrameworkForXcode)');
+    if (!idbAvailable)
+        suggestions.push('Ensure idb is in PATH or set MCP_IDB_PATH / IDB_PATH');
+    if (!companionAvailable)
+        suggestions.push('Install idb_companion and ensure it is in PATH');
+    return suggestions;
+}

package/dist/utils/ios/utils.js

@@ -19,16 +19,14 @@ export function getConfiguredIdbPath() {
             if (!p)
                 continue;
             try {
-                if (fs.existsSync(p)) {
-                    const raw = fs.readFileSync(p, 'utf8');
-                    const json = JSON.parse(raw);
-                    if (json) {
-                        if (json.idbPath)
-                            return json.idbPath;
-                        if (json.IDB_PATH)
-                            return json.IDB_PATH;
-                    }
-                }
+                if (!fs.existsSync(p))
+                    continue;
+                const raw = fs.readFileSync(p, 'utf8');
+                const json = JSON.parse(raw);
+                if (json?.idbPath)
+                    return json.idbPath;
+                if (json?.IDB_PATH)
+                    return json.IDB_PATH;
             }
             catch { }
         }
@@ -214,18 +212,18 @@ export async function getIOSDeviceMetadata(deviceId = "booted") {
                 const devicesMap = data.devices || {};
                 for (const runtime in devicesMap) {
                     const devices = devicesMap[runtime];
-                    if (Array.isArray(devices)) {
-                        for (const device of devices) {
-                            if (deviceId === "booted" || device.udid === deviceId) {
-                                resolve({
-                                    platform: "ios",
-                                    id: device.udid,
-                                    osVersion: parseRuntimeName(runtime),
-                                    model: device.name,
-                                    simulator: true,
-                                });
-                                return;
-                            }
+                    if (!Array.isArray(devices))
+                        continue;
+                    for (const device of devices) {
+                        if (deviceId === "booted" || device.udid === deviceId) {
+                            resolve({
+                                platform: "ios",
+                                id: device.udid,
+                                osVersion: parseRuntimeName(runtime),
+                                model: device.name,
+                                simulator: true,
+                            });
+                            return;
                         }
                     }
                 }
@@ -257,36 +255,37 @@ export async function listIOSDevices(appId) {
                             const bmap = bdata.devices || {};
                             for (const rt in bmap) {
                                 const devs = bmap[rt];
-                                if (Array.isArray(devs))
-                                    for (const d of devs)
-                                        bootedSet.add(d.udid);
+                                if (!Array.isArray(devs))
+                                    continue;
+                                for (const d of devs)
+                                    bootedSet.add(d.udid);
                             }
                         }
                         catch { }
                     }
                     for (const runtime in devicesMap) {
                         const devices = devicesMap[runtime];
-                        if (Array.isArray(devices)) {
-                            for (const device of devices) {
-                                const info = {
-                                    platform: 'ios',
-                                    id: device.udid,
-                                    osVersion: parseRuntimeName(runtime),
-                                    model: device.name,
-                                    simulator: true,
-                                    booted: bootedSet.has(device.udid)
-                                };
-                                if (appId) {
-                                    // check if installed
-                                    const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
-                                        .then(() => { info.appInstalled = true; })
-                                        .catch(() => { info.appInstalled = false; })
-                                        .then(() => { out.push(info); });
-                                    checks.push(p);
-                                }
-                                else {
-                                    out.push(info);
-                                }
+                        if (!Array.isArray(devices))
+                            continue;
+                        for (const device of devices) {
+                            const info = {
+                                platform: 'ios',
+                                id: device.udid,
+                                osVersion: parseRuntimeName(runtime),
+                                model: device.name,
+                                simulator: true,
+                                booted: bootedSet.has(device.udid)
+                            };
+                            if (appId) {
+                                // check if installed
+                                const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
+                                    .then(() => { info.appInstalled = true; })
+                                    .catch(() => { info.appInstalled = false; })
+                                    .then(() => { out.push(info); });
+                                checks.push(p);
+                            }
+                            else {
+                                out.push(info);
                             }
                         }
                     }

package/dist/utils/java.js

@@ -39,27 +39,9 @@ export async function detectJavaHome(options = {}) {
             }
             debug('[java.detect] ANDROID_STUDIO_JDK present but java -version did not match expected versions');
         }
-        // 2) Android Studio JBR candidates (prefer these over JAVA_HOME)
-        const jbrCandidates = [
-            '/Applications/Android Studio.app/Contents/jbr',
-            '/Applications/Android Studio.app/Contents/jbr/Contents/Home',
-            '/Applications/Android Studio Preview.app/Contents/jbr',
-            '/Applications/Android Studio Preview.app/Contents/jbr/Contents/Home',
-            '/Applications/Android Studio Preview 2022.3.app/Contents/jbr',
-            '/Applications/Android Studio Preview 2022.3.app/Contents/jbr/Contents/Home',
-            '/Applications/Android Studio Preview 2023.1.app/Contents/jbr',
-            '/Applications/Android Studio Preview 2023.1.app/Contents/jbr/Contents/Home'
-        ];
-        for (const p of jbrCandidates) {
-            const javaBin = path.join(p, 'bin', 'java');
-            if (existsSync(javaBin)) {
-                const v = javaVersionOf(javaBin);
-                if (isJavaVersionAcceptable(v)) {
-                    debug('[java.detect] Found Android Studio JBR at:', p);
-                    return p;
-                }
-            }
-        }
+        const jbr = findStudioJava(debug);
+        if (jbr)
+            return jbr;
         // 3) If JAVA_HOME set, validate it (accept 17 or 21)
         if (process.env.JAVA_HOME) {
             try {
@@ -96,40 +78,74 @@ export async function detectJavaHome(options = {}) {
         catch (e) {
             debug('[java.detect] /usr/libexec/java_home -v 21 failed: ' + String(e));
         }
-        // 6) macOS common JDK locations
-        try {
-            const homes = execSync('ls -1 /Library/Java/JavaVirtualMachines || true', { stdio: ['ignore', 'pipe', 'inherit'] }).toString().split(/\r?\n/).filter(Boolean);
-            for (const h of homes) {
-                if (h.toLowerCase().includes('17') || h.toLowerCase().includes('jdk-17') || h.toLowerCase().includes('21') || h.toLowerCase().includes('jdk-21')) {
-                    const candidate = `/Library/Java/JavaVirtualMachines/${h}/Contents/Home`;
-                    return candidate;
-                }
+        const commonHome = findMacJavaHome(debug);
+        if (commonHome)
+            return commonHome;
+        return findLinuxJavaHome(debug);
+    }
+    catch (e) {
+        debug('[java.detect] error detecting java home:', e instanceof Error ? e.message : String(e));
+    }
+    return undefined;
+}
+function findStudioJava(debug) {
+    // 2) Android Studio JBR candidates (prefer these over JAVA_HOME)
+    const jbrCandidates = [
+        '/Applications/Android Studio.app/Contents/jbr',
+        '/Applications/Android Studio.app/Contents/jbr/Contents/Home',
+        '/Applications/Android Studio Preview.app/Contents/jbr',
+        '/Applications/Android Studio Preview.app/Contents/jbr/Contents/Home',
+        '/Applications/Android Studio Preview 2022.3.app/Contents/jbr',
+        '/Applications/Android Studio Preview 2022.3.app/Contents/jbr/Contents/Home',
+        '/Applications/Android Studio Preview 2023.1.app/Contents/jbr',
+        '/Applications/Android Studio Preview 2023.1.app/Contents/jbr/Contents/Home'
+    ];
+    for (const p of jbrCandidates) {
+        const javaBin = path.join(p, 'bin', 'java');
+        if (existsSync(javaBin)) {
+            const v = javaVersionOf(javaBin);
+            if (isJavaVersionAcceptable(v)) {
+                debug('[java.detect] Found Android Studio JBR at:', p);
+                return p;
             }
         }
-        catch (e) {
-            debug('[java.detect] listing /Library/Java/JavaVirtualMachines failed: ' + String(e));
-        }
-        // 7) Linux locations
-        const linuxCandidates = [
-            '/usr/lib/jvm/java-17-openjdk-amd64',
-            '/usr/lib/jvm/java-17-openjdk',
-            '/usr/lib/jvm/zulu17',
-            '/usr/lib/jvm/temurin-17-jdk',
-            '/usr/lib/jvm/temurin-21-jdk',
-            '/usr/lib/jvm/java-21-openjdk-amd64'
-        ];
-        for (const p of linuxCandidates) {
-            try {
-                if (existsSync(p))
-                    return p;
-            }
-            catch (e) {
-                debug(`[java.detect] checking linux candidate ${p} failed: ${String(e)}`);
+    }
+    return undefined;
+}
+function findMacJavaHome(debug) {
+    // 6) macOS common JDK locations
+    try {
+        const homes = execSync('ls -1 /Library/Java/JavaVirtualMachines || true', { stdio: ['ignore', 'pipe', 'inherit'] }).toString().split(/\r?\n/).filter(Boolean);
+        for (const h of homes) {
+            if (h.toLowerCase().includes('17') || h.toLowerCase().includes('jdk-17') || h.toLowerCase().includes('21') || h.toLowerCase().includes('jdk-21')) {
+                const candidate = `/Library/Java/JavaVirtualMachines/${h}/Contents/Home`;
+                return candidate;
             }
         }
     }
     catch (e) {
-        debug('[java.detect] error detecting java home:', e instanceof Error ? e.message : String(e));
+        debug('[java.detect] listing /Library/Java/JavaVirtualMachines failed: ' + String(e));
+    }
+    return undefined;
+}
+function findLinuxJavaHome(debug) {
+    // 7) Linux locations
+    const linuxCandidates = [
+        '/usr/lib/jvm/java-17-openjdk-amd64',
+        '/usr/lib/jvm/java-17-openjdk',
+        '/usr/lib/jvm/zulu17',
+        '/usr/lib/jvm/temurin-17-jdk',
+        '/usr/lib/jvm/temurin-21-jdk',
+        '/usr/lib/jvm/java-21-openjdk-amd64'
+    ];
+    for (const p of linuxCandidates) {
+        try {
+            if (existsSync(p))
+                return p;
+        }
+        catch (e) {
+            debug(`[java.detect] checking linux candidate ${p} failed: ${String(e)}`);
+        }
     }
     return undefined;
 }

package/dist/utils/resolve-device.js

@@ -66,6 +66,9 @@ async function resolveDevice(opts) {
             throw new Error(`Device '${deviceId}' not found for platform ${platform}`);
         return found;
     }
+    return selectDevice(devices, platform, appId, prefer);
+}
+function selectDevice(devices, platform, appId, prefer) {
     let candidates = devices.slice();
     if (prefer === "physical")
         candidates = candidates.filter(d => !d.simulator);
@@ -99,8 +102,7 @@ async function resolveDevice(opts) {
             return candidates[0];
         }
         const list = candidates.map(d => ({ id: d.id, platform: d.platform, osVersion: d.osVersion, model: d.model, simulator: d.simulator, appInstalled: d.appInstalled }));
-        const err = new Error(`Multiple matching devices found: ${JSON.stringify(list, null, 2)}`);
-        err.devices = list;
+        const err = Object.assign(new Error(`Multiple matching devices found: ${JSON.stringify(list, null, 2)}`), { devices: list });
         throw err;
     }
     throw new Error(`No devices found for platform ${platform}`);

package/dist/utils/ui/index.js

@@ -73,36 +73,11 @@ export function computeScreenFingerprint(tree, current, platform, limit = 50) {
 }
 export async function scrollToElementShared(opts) {
     const { selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId, fetchTree, swipe, stabilizationDelayMs = 350 } = opts;
-    const matchElement = (el) => {
-        if (!el)
-            return false;
-        if (selector.text !== undefined && selector.text !== el.text)
-            return false;
-        if (selector.resourceId !== undefined && selector.resourceId !== el.resourceId)
-            return false;
-        if (selector.contentDesc !== undefined && selector.contentDesc !== el.contentDescription)
-            return false;
-        if (selector.className !== undefined && selector.className !== el.type)
-            return false;
-        return true;
-    };
-    const isVisible = (el, resolution) => {
-        if (!el)
-            return false;
-        if (el.visible === false)
-            return false;
-        if (!el.bounds || !resolution || !resolution.width || !resolution.height)
-            return (el.visible === undefined ? true : !!el.visible);
-        const [left, top, right, bottom] = el.bounds;
-        const withinY = bottom > 0 && top < resolution.height;
-        const withinX = right > 0 && left < resolution.width;
-        return withinX && withinY;
-    };
     const findVisibleMatch = (elements, resolution) => {
         if (!Array.isArray(elements))
             return null;
         for (const e of elements) {
-            if (matchElement(e) && isVisible(e, resolution))
+            if (matchElement(selector, e) && isVisible(e, resolution))
                 return e;
         }
         return null;
@@ -169,3 +144,28 @@ export async function scrollToElementShared(opts) {
     }
     return { success: false, reason: 'Element not found after scrolling', scrollsPerformed: scrollsPerformed };
 }
+function matchElement(selector, el) {
+    if (!el)
+        return false;
+    if (selector.text !== undefined && selector.text !== el.text)
+        return false;
+    if (selector.resourceId !== undefined && selector.resourceId !== el.resourceId)
+        return false;
+    if (selector.contentDesc !== undefined && selector.contentDesc !== el.contentDescription)
+        return false;
+    if (selector.className !== undefined && selector.className !== el.type)
+        return false;
+    return true;
+}
+function isVisible(el, resolution) {
+    if (!el)
+        return false;
+    if (el.visible === false)
+        return false;
+    if (!el.bounds || !resolution || !resolution.width || !resolution.height)
+        return (el.visible === undefined ? true : !!el.visible);
+    const [left, top, right, bottom] = el.bounds;
+    const withinY = bottom > 0 && top < resolution.height;
+    const withinX = right > 0 && left < resolution.width;
+    return withinX && withinY;
+}

package/docs/CHANGELOG.md

@@ -1,9 +1,53 @@
 # Changelog
 
+[Documentation](README.md)
+
+Entries describe their release at the time it was recorded. Historical source
+paths and commands may have moved; use the [contribution guide](../CONTRIBUTING.md)
+and [tool reference](tools/TOOLS.md) for the current checkout.
+
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
 ## Unreleased
 
+## [0.35.0]
+
+- Updated the agent plugin to `0.0.4`, pinned to MCP `0.35.0`.
+
+- Added an opt-in isolated Android coroutine debugger assessment fixture for
+  suspension, dispatcher changes, nested work, stepping and cancellation, with
+  explicit local dependencies. This does not add coroutine reconstruction.
+- Added an opt-in isolated Kotlin debugger validation journey for named locals
+  before/after assignment, compiler scope tables, stale references and app recovery.
+  This adds evidence and regression coverage without changing debugger behaviour.
+- Added opt-in debugger `responseMode: "compact"` to omit repeated target metadata
+  from routine commands while retaining diagnostics, execution state and cleanup.
+  Existing full responses remain the default; discovery and state stay complete.
+- Android debugger failures now include bounded, sanitized stage/reason diagnostics
+  and static recovery guidance while preserving error codes. Capability probes
+  report ordered prerequisite diagnostics; terminal summaries retain failure evidence.
+  Raw stderr, exception messages and app locals are excluded from diagnostics.
+
+- **Runtime requirement:** Node.js 22 or newer is now required. Updated Sharp,
+  Zod and transitive dependencies to clear the dependency audit findings; CI
+  configuration now uses Node 22. Public tool definitions remain unchanged.
+- Split observation, snapshot, iOS build, Android utility and system diagnostic
+  responsibilities into typed services. Removed all 136 legacy quality exceptions;
+  production source meets the default size, complexity, nesting and explicit-any
+  limits. Added screenshot encoding and snapshot log normalization regressions.
+
+- Split server handlers by capability, share target/execution-control contracts, and inject clocks into interaction polling services while preserving tool contracts. Added deterministic timing tests and an Android labelled-slider convergence journey.
+
+- Added ArchUnitTS architecture checks to lint and CI for shared contracts, server boundaries, pure interaction calculations and runtime dependency cycles. Negative controls cover NodeNext resolution, aliases, dynamic imports and re-exports.
+
+- Group interaction services by adjustment, targeting, waits and assertions; separate server schemas and handlers, and place log-derived network observations under `observe/network`. Tool contracts and behaviour are unchanged.
+
+- Reduced `ToolsInteract` to a typed composition facade within the enforced class budget. Extracted adjustment, candidate resolution, synchronization and assertion services without new legacy exceptions, and added an isolated Android interaction journey plus a permanent default-budget regression check.
+
+- Added code-quality gates to lint and CI for source/class/function size, complexity, nesting, explicit `any`, and interaction/runtime import boundaries. Legacy exceptions have per-symbol ceilings that cannot grow unnoticed.
+- Extracted typed UI/control helpers, bounded handle storage, action-result construction and capability-specific tool definitions; clarified and typed debugger session operations and worker protocol messages while retaining public tool contracts.
+- Fixed the debugger device check to fingerprint Java sources in `src/debugger/java/` after the worker relocation.
+
 ## [0.34.0]
 - Added optional Android JDI runtime debugging: explicit device/process attach, source breakpoints/events, bounded stacks and shallow locals, stepping/resume, stale-reference rejection, pause-aware UI guards/readiness, expiry and owned detach/cleanup. Requires a host JDK 17+ and a running debuggable app; evaluation, mutation, native/coroutine and iOS debugging remain unsupported.
 - Added optional bounded Android Perfetto capture with capability/start/status/stop/cancel tools, explicit journey trace linkage, local artifacts, process-ownership checks and retryable cleanup. iOS tracing and automatic trace analysis remain unsupported.

package/docs/README.md

@@ -0,0 +1,38 @@
+# Documentation
+
+Mobile Debug MCP provides tools for building, controlling, and inspecting Android
+and iOS apps. Start with the [project README](../README.md) for requirements,
+installation, and client configuration.
+
+## Choose a starting point
+
+- **New to the server?** See the [project overview and installation options](../README.md#start-here).
+- **Looking up a tool?** Use the [tool reference](tools/TOOLS.md) for inputs,
+  responses, examples, and shared interaction principles.
+- **Troubleshooting setup?** Check [environment diagnostics](tools/system.md) and
+  the [tool path settings](../README.md#environment-setup).
+- **Investigating an app failure?** Start with [observations](tools/observe.md)
+  and [evidence correlation](tools/correlated-evidence.md). For deeper Android
+  investigation, use [system traces](tools/system-traces.md) or the
+  [runtime debugger](tools/debugger.md).
+- **Installing a client plugin?** See [client installation](../README.md#agent-plugin)
+  and the [plugin guide](../agent-plugin/README.md) for packaging and versioning.
+
+## Contributing
+
+- [Contribution guide](../CONTRIBUTING.md): local setup, validation, and documentation conventions.
+- [Code structure and quality checks](code-structure.md): module ownership, enforced limits, and existing debt.
+- [Development process](specs/process.md): maintenance and feature workflows.
+- [Agent entrypoint](../AGENTS.md) and [repository skills](../.agents/skills/README.md).
+
+## Design and evidence
+
+- [Design records](specs/): feature intent, specifications, and dated verification
+  records, grouped by feature.
+- [Changelog](CHANGELOG.md): release history.
+- [Benchmark index](benchmarks/README.md): reproducible performance checks and recorded limits.
+
+The tool reference describes the current checkout. Specifications record design
+intent and may contain earlier contracts; approval alone does not establish that
+a feature shipped. Verification records describe the named build and environment,
+not every supported platform or the currently published npm package.

package/docs/benchmarks/README.md

@@ -0,0 +1,18 @@
+# Benchmarks
+
+[Documentation](../README.md)
+
+Use these guides to run a benchmark or inspect its recorded results. Each
+benchmark has one directory containing its instructions, report, and supporting
+data. Generated filenames are retained so the harness can update them directly.
+
+These reports describe particular builds and devices. Passing a smoke check does
+not establish a performance improvement, and Android timings do not establish
+iOS latency.
+
+| Benchmark | Protocol | Recorded results | Design |
+| --- | --- | --- | --- |
+| Interaction latency | [Run the benchmark](interaction-latency/README.md) | [Android measurements](interaction-latency/final.md), [iOS interaction validation](interaction-latency/ios-validation.md) | [018](../specs/018-interaction-latency-and-batched-journeys/spec.md) |
+| UI-tree observation | [Run the paired benchmark](ui-tree-performance/README.md) | [Comparison and limitations](ui-tree-performance/comparison.md) | [019](../specs/019-ui-tree-observation-performance/spec.md) |
+
+Fixture instructions: [latency journey app](../../test/fixtures/latency-journey-app/README.md).

package/docs/benchmarks/interaction-latency/README.md

@@ -1,5 +1,7 @@
 # Interaction latency benchmark
 
+[Benchmark index](../README.md) · [Documentation](../../README.md)
+
 Run after `npm run verify`:
 
 ```sh
@@ -24,3 +26,15 @@ See [iOS simulator validation](ios-validation.md) for the interaction checks.
 The process exits unsuccessfully on >10% full p95 regression or <30% light p50
 improvement. A failed run is reported and excluded from percentiles as the spec
 requires; inspect its selector and tool or step before accepting the result.
+
+## Recorded results
+
+- [Android measurements](final.md): latency summaries and acceptance gates.
+- [Raw Android report](final.json): requests, timing components, and per-run outcomes.
+- [iOS interaction validation](ios-validation.md): correctness checks, separate
+  from the Android latency measurements.
+
+The harness overwrites `final.md` and `final.json` when run. These checked-in
+results describe the recorded build and environment; they do not establish the
+performance of the current checkout. Review generated reports and preserve any
+unresolved limitations when recording a new run.

package/docs/benchmarks/interaction-latency/final.md

@@ -1,5 +1,7 @@
 # Interaction latency benchmark
 
+[Benchmark index](../README.md) · [Documentation](../../README.md)
+
 Commit: d3e6ae720db1ad1da294795790689df5a80b56b0 (working tree candidate). Fixture: 1.0, SHA-256 98244deeeba0a21da7d99a3e4b43c97806d6f8a8787ad7fe38249e5d311a6fb6.
 
 Environment: Pixel_9_Pro, Android 16, API 36. Three warm-ups and ten measured runs per mode. Failed runs excluded.
@@ -14,4 +16,5 @@ First failure by mode: baseline: none; full: none; light: none.
 
 Full p95 gate: true. Light p50 gate: true.
 
-See final.json for requests, timing components, and failure selectors.
+See the [raw report](final.json) for requests, timing components, and failure selectors.
+See the [benchmark instructions](README.md) to run a new measurement.

package/docs/benchmarks/interaction-latency/ios-validation.md

@@ -1,5 +1,7 @@
 # Spec 018 iOS device validation
 
+[Benchmark index](../README.md) · [Documentation](../../README.md)
+
 Validated on 27 September 2026 with the booted iPhone Air simulator (iOS 26.4.1).
 
 - `npm run test:device` passed all six Android and iOS screenshot, log, and UI-tree smoke checks.