@mobileaidev/ai-app-bridge 0.3.6 → 0.3.8

package/README.md

@@ -7,7 +7,7 @@ discovery. Every request checks the mapping before dispatch. Mutating requests
 are never replayed after a missing route or uncertain result. For manual cleanup,
 pass the exact serial and returned Host port to `remove-forward`.
 
-This source version is `0.3.6`; registry publication is a separate release step.
+This source version is `0.3.8`; registry publication is a separate release step.
 The default installation includes the Script/Intent and capture contracts below.
 Local package verification does not change npm dist-tags.
 The supported Node range is `>=26.3.0 <27`; this release was checked on 26.3.0.
@@ -60,7 +60,7 @@ domains, commands, and options, then call `run` with the selected command.
 
 ```bash
 # Install the current stable release; see docs/RELEASE.md for packaging.
-npm install -g @mobileaidev/ai-app-bridge@0.3.6
+npm install -g @mobileaidev/ai-app-bridge@0.3.8
 
 ai-app-bridge status --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge tree --package-name io.github.mobileaidev.aiappbridge.sample

package/bin/command-registry.js

@@ -8,6 +8,7 @@ const { executionCommandSchema, nativeGestureSchema, nativeSelector, flutterSele
 const { flutterActionSchema, webCommandSchema } = require('./shared-kernel/provider-command-contracts');
 
 const commandDefinitions = [
+  { command: 'executor-prepare', domain: 'advanced', summary: 'Prepare optional test executors from the existing project: generate Android androidTest entry/dependencies and matching APKs, add Flutter dev dependency and build the generated entrypoint, prepare managed iOS WDA, or install pinned Playwright/browser. Host preparation does not install or launch a mobile application. No application ID is changed. Requires app.test in Script.', targetKind: 'host', options: ['platform'] },
   { command: 'ui-observation', domain: 'core', summary: 'Start a bounded UI observation window (100–5000 ms), inspect it, or stop its lease. Off by default; provider selects native or Flutter. New windows establish a fresh baseline.', targetApp: true, options: ['operation', 'provider', 'durationMs', 'leaseId', 'packageName', 'serial'] },
   { command: 'ios-ui-observation', domain: 'ios', summary: 'Control bounded iOS native or Flutter UI observation. Off by default; expires locally even if the Host exits.', targetKind: 'ios-app', options: ['operation', 'provider', 'durationMs', 'leaseId', 'deviceId', 'bundleId'] },
   { command: 'web-ui-observation', domain: 'web', summary: 'Control bounded Web DOM change observation. Off by default; expires locally even if the Host exits.', targetKind: 'web-target', options: ['operation', 'durationMs', 'leaseId', 'sessionId', 'runtimeEpoch', 'targetId'] },
@@ -151,6 +152,7 @@ const isolatedCommandDefinitions = [
 ];
 
 const mutationCommands = new Set([
+  'executor-prepare',
   'install-apk', 'clear-app-data', 'freeze-app', 'thaw-app', 'launch-app',
   'launch-activity', 'permission-grant',
   'permission-revoke', 'permission-dialog', 'appops-set',
@@ -254,12 +256,13 @@ function isMutationCommand(command, args = {}) {
 }
 
 function isAndroidMutation(command, args = {}) {
-  return isMutationCommand(command, args) && !['runtime', 'device-ownership'].includes(command)
+  return isMutationCommand(command, args) && !['runtime', 'device-ownership', 'executor-prepare'].includes(command)
     && !command.startsWith('ios-') && !command.startsWith('web-');
 }
 
 function executionTimeoutMs(command, args = {}) {
   if (args.timeoutMs !== undefined) return args.timeoutMs;
+  if (command === 'executor-prepare') return 600000;
   if (['android-executor', 'flutter-executor'].includes(command)) return args.operation === 'open' ? 60000 : 30000;
   if (command === 'web-executor') return args.operation === 'prepare' ? 300000 : 30000;
   if (iosSdkCommands.has(command) || command === 'ios-execution' || require('./ios-wda-port').commands.has(command)) return 30000;
@@ -273,7 +276,7 @@ function executionTimeoutMs(command, args = {}) {
 // These are execution capabilities, independent of MCP/CLI transport. Script
 // permissions gate Bridge calls; trusted local code is not a process sandbox.
 const scriptPermissions = Object.freeze({
-  'app.test': ['web-executor', 'android-executor', 'flutter-executor'],
+  'app.test': ['web-executor', 'android-executor', 'flutter-executor', 'executor-prepare'],
   'app.read': ['status', 'tree', 'uia-tree', 'screenshot', 'flutter-tree', 'flutter-nodes', 'h5-dom', 'flutter-h5-dom', 'keyboard-state', 'permission-state',
     'ios-status', 'ios-tree', 'ios-uia-tree', 'ios-screenshot', 'ios-flutter-tree', 'ios-flutter-nodes', 'ios-h5-dom', 'ios-wda-status', 'web-status', 'web-dom'],
   'capture.read': ['ui-observation', 'ios-ui-observation', 'web-ui-observation', 'logs', 'network', 'state', 'events', 'logcat', 'webview-console', 'webview-network', 'ios-logs', 'ios-network', 'ios-state', 'ios-events', 'web-logs', 'web-network', 'web-state', 'web-events'],
@@ -291,7 +294,7 @@ function commandContract(command) {
   const definition = commandByName.get(command) || isolatedByName.get(command);
   if (!definition) throw new CommandError('unknown_command', `Unknown command: ${command}`, { field: 'command' });
   const isolated = isolatedByName.has(command);
-  const platform = command === 'runtime' ? 'host' : isolated ? (command === 'evidence' ? 'host' : 'multi')
+  const platform = ['runtime', 'executor-prepare'].includes(command) ? 'host' : isolated ? (command === 'evidence' ? 'host' : 'multi')
     : definition.domain === 'ios' ? 'ios' : definition.domain === 'web' ? 'web' : 'android';
   const role = command === 'runtime' || command === 'intent' || command === 'script' || workflowCommands.has(command) ? 'execution'
     : command === 'evidence' ? 'evidence' : expertCommands.has(command) ? 'expert' : 'capability';
@@ -317,6 +320,7 @@ function commandContract(command) {
 function commandSchema(command) {
   const definition = commandByName.get(command) || isolatedByName.get(command);
   if (!definition) throw new CommandError('unknown_command', `Unknown command: ${command}`, { field: 'command' });
+  if (command === 'executor-prepare') return require('./executors/preparation').preparationSchema();
   if (require('./ui-observation').commands.has(command)) return require('./ui-observation').schema(command, optionTypes);
   if (command === 'web-executor') return require('./executors/command-schema').webExecutorSchema();
   if (command === 'android-executor') return require('./executors/command-schema').androidExecutorSchema();

package/bin/device-provider.js

@@ -1752,18 +1752,52 @@ function parseForegroundWindow(raw) {
     'mResumedActivity',
     'mFocusedApp',
   ];
-  for (const marker of markers) {
-    const line = lines.find((item) => item.includes(marker));
-    if (!line) continue;
-    const component = parseComponentFromWindowLine(line);
+  const records = [];
+  const focusedDisplayIds = new Set();
+  let displayId = null;
+  for (const line of lines) {
+    if (/^WINDOW MANAGER\b/.test(line)) displayId = null;
+    const display = line.match(/^\s*Display: mDisplayId=(\d+)\b/);
+    if (display) displayId = Number(display[1]);
+    const focusedDisplay = line.match(/^\s*mTopFocusedDisplayId=(-?\d+)\b/);
+    if (focusedDisplay) focusedDisplayIds.add(Number(focusedDisplay[1]));
+    const focus = line.match(/^\s*(mCurrentFocus|mTopResumedActivity|mResumedActivity|mFocusedApp)(?:\[(\d+)\])?\s*[:=]\s*(.*)$/);
+    if (!focus) continue;
+    const component = parseComponentFromWindowLine(focus[3]);
     if (!component) continue;
+    records.push({
+      source: focus[1],
+      displayId: focus[2] === undefined ? displayId : Number(focus[2]),
+      value: focus[3].trim(),
+      component,
+      raw: line.trim(),
+    });
+  }
+  for (const marker of markers) {
+    const unique = new Map();
+    for (const record of records.filter((item) => item.source === marker)) {
+      unique.set(`${record.displayId}:${record.value}`, record);
+    }
+    const candidates = [...unique.values()];
+    if (!candidates.length) continue;
+    const focusedDisplayId = focusedDisplayIds.size === 1 ? [...focusedDisplayIds][0] : null;
+    const selected = candidates.length === 1 ? candidates
+      : candidates.filter((item) => focusedDisplayId !== null && item.displayId === focusedDisplayId);
+    if (selected.length !== 1) {
+      return {
+        ok: false,
+        error: 'foreground_ambiguous',
+        source: marker,
+        focusedDisplayId,
+        candidates: candidates.map((item) => ({ displayId: item.displayId, ...item.component, raw: item.raw })),
+      };
+    }
+    const record = selected[0];
     return {
       ok: true,
       source: marker,
-      packageName: component.packageName,
-      activity: component.activity,
-      component: component.component,
-      raw: line.trim(),
+      ...record.component,
+      raw: record.raw,
     };
   }
   return {

package/bin/execution-host.js

@@ -585,6 +585,7 @@ function getSharedObservationCollector(factRecorder) {
 }
 
 async function runRawCommand(command, args = {}) {
+  if (command === 'executor-prepare') return require('./executors/preparation').prepareExecutor(args);
   if (command === 'android-executor') {
     androidExecutor ||= new (require('./executors/android-host').AndroidExecutorHost)();
     return androidExecutor.run(args);

package/bin/executors/command-schema.js

@@ -56,7 +56,7 @@ function androidExecutorSchema() {
   const bound = (properties = {}, required = []) => ({ properties: { ...target, ...session, ...properties }, required: ['serial', 'packageName', 'sessionId', 'runtimeEpoch', ...required] });
   const action = { anyOf: [
     object({ type: { enum: ['click', 'longClick', 'scrollTo', 'swipeUp', 'swipeDown', 'swipeLeft', 'swipeRight', 'webClick', 'webClear', 'webScrollIntoView', 'semanticLongClick', 'composeClearText'] }, nodeId: identifier }, ['type', 'nodeId']),
-    object({ type: { enum: ['setText', 'typeText', 'replaceText', 'webKeys', 'composeInput', 'composeReplaceText'] }, nodeId: identifier, text: { type: 'string', maxLength: 65536 } }, ['type', 'nodeId', 'text']),
+    object({ type: { enum: ['setText', 'typeText', 'replaceText', 'replaceTextViaInputConnection', 'webKeys', 'composeInput', 'composeReplaceText'] }, nodeId: identifier, text: { type: 'string', maxLength: 65536 } }, ['type', 'nodeId', 'text']),
     object({ type: { const: 'composeScrollToIndex' }, nodeId: identifier, index: integer(0, 1000000) }, ['type', 'nodeId', 'index']),
     object({ type: { const: 'scroll' }, nodeId: identifier, direction: { enum: ['up', 'down', 'left', 'right'] }, percent: { type: 'number', exclusiveMinimum: 0, maximum: 10 } }, ['type', 'nodeId', 'direction', 'percent']),
     object({ type: { enum: ['back', 'home', 'closeKeyboard'] } }, ['type']),

package/bin/executors/preparation.js

@@ -0,0 +1,248 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { pathToFileURL, fileURLToPath } = require('node:url');
+const { createHash, randomUUID } = require('node:crypto');
+const { CommandError } = require('../command-errors');
+const { object, text, integer } = require('../shared-kernel/argument-schema');
+const { resolveRequestPath } = require('../shared-kernel/request-context');
+const { execFileBounded } = require('../shared-kernel/execution-io');
+const { executorHome, atomicJson, readJson, preparePackage } = require('./managed-runtime');
+const bridgeVersion = require('../../package.json').version;
+const testClass = 'io.github.mobileaidev.aiappbridge.generated.BridgeSessionTest';
+const identifier = { ...text, maxLength: 4096 };
+const common = { timeoutMs: integer(1, 1800000), requestId: identifier, feedback: { enum: ['auto', 'off', 'full'] } };
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+
+function preparationSchema() {
+  const definitions = {
+    android: { properties: { projectDir: identifier, module: { ...text, pattern: '^(:[A-Za-z0-9_-]+)+$' },
+      variant: { ...text, pattern: '^[A-Za-z][A-Za-z0-9]*$' },
+      adapters: { type: 'array', uniqueItems: true, maxItems: 2, items: { enum: ['espresso-web', 'compose'] } },
+      repositoryUrl: identifier, gradlePath: identifier }, required: ['projectDir', 'module', 'variant'] },
+    flutter: { properties: { projectDir: identifier, entrypoint: identifier, flutterPath: identifier,
+      flavor: { ...text, pattern: '^[A-Za-z][A-Za-z0-9_]*$' }, testPackagePath: identifier,
+      mainArguments: { type: 'array', items: { type: 'string', maxLength: 4096 }, maxItems: 100 },
+      dartDefines: { type: 'array', items: identifier, maxItems: 100 } }, required: ['projectDir'] },
+    ios: { properties: { xcodebuild: identifier }, required: [] },
+    web: { properties: { browser: { enum: ['chromium', 'firefox', 'webkit'] } }, required: [] },
+  };
+  const branches = Object.entries(definitions).map(([platform, definition]) =>
+    object({ platform: { const: platform }, ...common, ...definition.properties }, ['platform', ...definition.required]));
+  return { type: 'object', additionalProperties: false, required: ['platform'],
+    properties: { ...Object.assign({}, ...branches.map(branch => branch.properties)), platform: { enum: Object.keys(definitions) } }, anyOf: branches };
+}
+
+function requireFile(file) {
+  if (!fs.statSync(file, { throwIfNoEntry: false })?.isFile())
+    throw new CommandError('executor_prepare_file_missing', `Required project file is missing: ${file}`);
+  return file;
+}
+
+function repository(value = 'https://jitpack.io') {
+  const url = new URL(value);
+  if (!['https:', 'file:'].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+    throw new CommandError('invalid_argument', 'repositoryUrl must be an HTTPS or local file Maven repository without credentials, query or fragment.');
+  return url.href;
+}
+
+async function withProject(projectDir, action, { home = executorHome() } = {}) {
+  const project = fs.realpathSync(resolveRequestPath(projectDir));
+  const locks = path.join(home, 'preparation-locks');
+  fs.mkdirSync(locks, { recursive: true, mode: 0o700 });
+  const { DatabaseSync } = require('node:sqlite');
+  const lock = new DatabaseSync(path.join(locks, `${digest(project)}.sqlite`));
+  let locked = false;
+  try {
+    try { lock.exec('PRAGMA busy_timeout=0; BEGIN EXCLUSIVE'); locked = true; }
+    catch (error) { if (error.errcode === 5) throw new CommandError('executor_preparing', 'This project is already being prepared.'); throw error; }
+    const directory = path.join(project, 'build', 'ai-app-bridge', 'prepare', randomUUID());
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const startedAtMs = Date.now();
+    try {
+      const result = { ok: true, bridgeVersion, directory, ...await action(project, directory), elapsedMs: Date.now() - startedAtMs };
+      atomicJson(path.join(directory, 'result.json'), result);
+      return result;
+    } catch (error) {
+      const result = { ok: false, bridgeVersion, directory, error: error.code || 'executor_prepare_failed',
+        message: error.message, elapsedMs: Date.now() - startedAtMs };
+      atomicJson(path.join(directory, 'result.json'), result);
+      throw new CommandError(result.error, result.message, { details: { directory, resultFile: path.join(directory, 'result.json') } });
+    }
+  } finally { if (locked) lock.exec('ROLLBACK'); lock.close(); }
+}
+
+async function loggedRun(run, file, args, directory, name, options) {
+  const logFile = path.join(directory, `${name}.log`);
+  try {
+    const result = await run(file, args, { ...options, maxBuffer: 16 * 1024 * 1024 });
+    fs.writeFileSync(logFile, result.stdout + result.stderr, { mode: 0o600 });
+    return result;
+  } catch (error) {
+    fs.writeFileSync(logFile, String(error.stdout || '') + String(error.stderr || '') + '\n' + error.message, { mode: 0o600 });
+    throw new CommandError('executor_prepare_build_failed', `${name} failed. Read ${logFile}`, { details: { logFile, exitCode: error.code } });
+  }
+}
+
+function androidEntry(adapters) {
+  const compose = adapters.includes('compose');
+  return `package io.github.mobileaidev.aiappbridge.generated;
+public final class BridgeSessionTest extends io.github.mobileaidev.aiappbridge.executor.instrumentation.AndroidExecutorTest {
+${compose ? '  @org.junit.Rule public final androidx.compose.ui.test.junit4.ComposeTestRule compose = androidx.compose.ui.test.junit4.AndroidComposeTestRule_androidKt.createEmptyComposeRule();' : ''}
+  @Override protected java.util.Map<String, io.github.mobileaidev.aiappbridge.executor.ExecutorAdapter> adapters() {
+    java.util.Map<String, io.github.mobileaidev.aiappbridge.executor.ExecutorAdapter> adapters = super.adapters();
+${adapters.includes('espresso-web') ? '    adapters.put("espresso-web", new io.github.mobileaidev.aiappbridge.executor.web.EspressoWebExecutor());' : ''}
+${compose ? '    adapters.put("compose", new io.github.mobileaidev.aiappbridge.executor.compose.ComposeExecutor(compose));' : ''}
+    return adapters;
+  }
+}
+`;
+}
+
+async function prepareAndroid(args, { run = execFileBounded, home } = {}) {
+  if (process.platform === 'win32') throw new CommandError('executor_host_unsupported', 'Android preparation currently supports macOS/Linux Gradle wrappers.');
+  const repositoryUrl = repository(args.repositoryUrl);
+  return withProject(args.projectDir, async (project, directory) => {
+    const wrapper = requireFile(args.gradlePath ? resolveRequestPath(args.gradlePath) : path.join(project, 'gradlew'));
+    const adapters = args.adapters ?? [];
+    const javaFile = path.join(directory, 'java', ...testClass.split('.')) + '.java';
+    fs.mkdirSync(path.dirname(javaFile), { recursive: true });
+    fs.writeFileSync(javaFile, androidEntry(adapters));
+    const coordinate = module => `com.github.mobileAiDev.ai-app-bridge:${module}:${bridgeVersion}`;
+    const config = { directory, module: args.module, variant: args.variant, repositoryUrl,
+      pluginCoordinate: coordinate('ai-app-bridge-gradle-plugin'),
+      dependencies: [coordinate('ai-app-bridge-test-instrumentation'), ...adapters.map(adapter => coordinate(`ai-app-bridge-test-${adapter}`)),
+        ...(adapters.includes('compose') ? ['androidx.compose.ui:ui-test-junit4:1.8.3'] : [])] };
+    const configFile = path.join(directory, 'config.json');
+    atomicJson(configFile, config);
+    const template = path.resolve(__dirname, '../../runtime/executors/android/prepare.init.gradle');
+    await loggedRun(run, 'sh', [wrapper, '--init-script', template, `-Daab.prepare.config=${configFile}`,
+      `${args.module}:aiAppBridgePrepareExecutor`, '--console=plain', '--no-configuration-cache', '--max-workers=2'],
+    directory, 'gradle-build', { cwd: project, timeoutMs: args.timeoutMs ?? 600000 });
+    const build = readJson(path.join(directory, 'android-build.json'));
+    if (build?.schemaVersion !== 'aab.android-prepared-build/v1' || build.variant !== args.variant || build.module !== args.module
+      || !build.packageName || !build.testPackageName || !build.runner || !build.applicationApks?.length || !build.testApks?.length)
+      throw new CommandError('executor_prepare_artifact_missing', 'The requested application/test variant did not produce complete build metadata.');
+    const artifacts = files => files.map(file => ({ path: requireFile(file), sha256: digest(fs.readFileSync(file)) }));
+    return { platform: 'android', engine: 'android-instrumentation', ...build, testClass,
+      instrumentation: `${build.testPackageName}/${build.runner}`, repositoryUrl,
+      adapters: ['uiautomator', 'espresso', ...adapters], applicationApks: artifacts(build.applicationApks), testApks: artifacts(build.testApks),
+      lifecycle: 'built-not-installed', projectFilesEdited: [],
+      next: 'Install the matching application and test APKs, then android-executor open with the returned component and class plus the actual launcher Activity.' };
+  }, { home });
+}
+
+async function prepareFlutter(args, { run = execFileBounded, home } = {}) {
+  return withProject(args.projectDir, async (project, directory) => {
+    const flutter = args.flutterPath ?? 'flutter';
+    const entrypoint = requireFile(path.resolve(project, args.entrypoint ?? 'lib/main.dart'));
+    const pubspec = requireFile(path.join(project, 'pubspec.yaml'));
+    const original = fs.readFileSync(pubspec);
+    const defines = args.dartDefines ?? [];
+    if (defines.some(value => value.split('=')[0] === 'INTEGRATION_TEST_SHOULD_REPORT_RESULTS_TO_NATIVE'))
+      throw new CommandError('invalid_argument', 'The Bridge test entrypoint owns INTEGRATION_TEST_SHOULD_REPORT_RESULTS_TO_NATIVE.');
+    const probe = await loggedRun(run, flutter, ['--version', '--machine'], directory, 'flutter-version', { cwd: project, timeoutMs: 30000 });
+    const sdk = JSON.parse(probe.stdout);
+    const version = /^(\d+)\.(\d+)\.(\d+)$/.exec(sdk.frameworkVersion);
+    if (!version || Number(version[1]) !== 3 || Number(version[2]) < 41)
+      throw new CommandError('executor_flutter_sdk_unsupported', `Flutter ${sdk.frameworkVersion} is outside the supported stable Flutter 3.41+ profile.`);
+    // Establish the baseline from the existing lock, even on a clean computer.
+    // A normal pub get could silently change versions before our comparison.
+    await loggedRun(run, flutter, ['pub', 'get', '--enforce-lockfile'], directory, 'flutter-pub-get', { cwd: project, timeoutMs: args.timeoutMs ?? 600000 });
+    const beforeGraph = JSON.parse((await loggedRun(run, flutter, ['pub', 'deps', '--json'], directory, 'flutter-deps-before', { cwd: project, timeoutMs: 30000 })).stdout);
+    if (productionVersions(beforeGraph).has('ai_app_bridge_test'))
+      throw new CommandError('executor_flutter_dependency_scope', 'ai_app_bridge_test must be a dev_dependency; move the existing production dependency before preparing.');
+    let packageRoot = project;
+    while (!fs.existsSync(path.join(packageRoot, '.dart_tool/package_config.json'))) {
+      const parent = path.dirname(packageRoot);
+      if (parent === packageRoot) throw new CommandError('executor_flutter_dependency_missing', 'Pub did not create a package configuration.');
+      packageRoot = parent;
+    }
+    const lockFile = requireFile(path.join(packageRoot, 'pubspec.lock'));
+    const originalLock = fs.readFileSync(lockFile);
+    const packageConfig = path.join(packageRoot, '.dart_tool/package_config.json');
+    const beforeHelper = JSON.parse(fs.readFileSync(packageConfig)).packages.find(item => item.name === 'ai_app_bridge_test');
+    const beforeDependency = beforeGraph.packages.find(item => item.name === 'ai_app_bridge_test');
+    const matchingSource = beforeHelper && (args.testPackagePath
+      ? fs.realpathSync(fileURLToPath(new URL(beforeHelper.rootUri, pathToFileURL(packageConfig)))) === fs.realpathSync(resolveRequestPath(args.testPackagePath))
+      : beforeDependency?.source === 'hosted');
+    const dependency = args.testPackagePath
+      ? `dev:ai_app_bridge_test:${JSON.stringify({ path: fs.realpathSync(resolveRequestPath(args.testPackagePath)) })}`
+      : `dev:ai_app_bridge_test:${bridgeVersion}`;
+    const reusedDependency = matchingSource && beforeDependency.version === bridgeVersion;
+    try {
+      if (!reusedDependency) await loggedRun(run, flutter, ['pub', 'add', dependency], directory, 'flutter-dependencies', { cwd: project, timeoutMs: args.timeoutMs ?? 600000 });
+      const afterGraph = JSON.parse((await loggedRun(run, flutter, ['pub', 'deps', '--json'], directory, 'flutter-deps-after', { cwd: project, timeoutMs: 30000 })).stdout);
+      const afterVersions = new Map(afterGraph.packages.map(item => [item.name, item.version]));
+      const changes = [...productionVersions(beforeGraph)].filter(([name, version]) => afterVersions.get(name) !== version)
+        .map(([name, before]) => ({ name, before, after: afterVersions.get(name) ?? null }));
+      if (changes.length) {
+        atomicJson(path.join(directory, 'dependency-conflicts.json'), changes);
+        throw new CommandError('executor_flutter_dependency_conflict', 'The test helper would change existing application dependencies; its pubspec/lock changes were reverted. See dependency-conflicts.json.');
+      }
+      const packages = JSON.parse(fs.readFileSync(path.join(packageRoot, '.dart_tool/package_config.json')));
+      const helper = packages.packages.find(item => item.name === 'ai_app_bridge_test');
+      if (!helper || afterVersions.get('ai_app_bridge_test') !== bridgeVersion)
+        throw new CommandError('executor_flutter_dependency_mismatch', `Pub must resolve ai_app_bridge_test ${bridgeVersion}; received ${afterVersions.get('ai_app_bridge_test')}.`);
+    } catch (error) {
+      if (!original.equals(fs.readFileSync(pubspec)) || !originalLock.equals(fs.readFileSync(lockFile))) {
+        fs.writeFileSync(pubspec, original);
+        fs.writeFileSync(lockFile, originalLock);
+        try {
+          await loggedRun(run, flutter, ['pub', 'get', '--offline', '--enforce-lockfile'], directory, 'flutter-restore-dependencies', { cwd: project, timeoutMs: 60000 });
+        } catch (restoreError) {
+          throw new CommandError('executor_flutter_dependency_restore_failed', `Pubspec and lock were restored, but Pub metadata restoration failed after ${error.code || error.message}. ${restoreError.message}`);
+        }
+      }
+      throw error;
+    }
+    const generated = path.join(directory, 'bridge_test.dart');
+    const launch = args.mainArguments === undefined ? 'app.main' : `() => app.main(<String>${JSON.stringify(args.mainArguments).replaceAll('$', '\\$')})`;
+    const importUri = pathToFileURL(entrypoint).href.replaceAll("'", '%27').replaceAll('$', '%24');
+    fs.writeFileSync(generated, `import 'package:ai_app_bridge_test/ai_app_bridge_test.dart';\nimport '${importUri}' as app;\nvoid main() => aiAppBridgeTest(${launch});\n`);
+    await loggedRun(run, flutter, ['build', 'apk', '--debug', '--no-pub', '--target', generated,
+      '--dart-define=INTEGRATION_TEST_SHOULD_REPORT_RESULTS_TO_NATIVE=false',
+      ...(args.flavor ? ['--flavor', args.flavor] : []), ...defines.map(value => `--dart-define=${value}`)],
+    directory, 'flutter-build', { cwd: project, timeoutMs: args.timeoutMs ?? 600000 });
+    const apk = requireFile(path.join(project, 'build/app/outputs/flutter-apk', `app-${args.flavor ? `${args.flavor}-` : ''}debug.apk`));
+    return { platform: 'flutter', devicePlatform: 'android', engine: 'flutter-integration-test', flutter: sdk,
+      projectDir: project, entrypoint, generatedEntrypoint: generated,
+      reusedDependency: Boolean(reusedDependency),
+      applicationApks: [{ path: apk, sha256: digest(fs.readFileSync(apk)) }], lifecycle: 'built-not-installed',
+      dependencySource: args.testPackagePath ? { path: fs.realpathSync(resolveRequestPath(args.testPackagePath)) } : { hosted: 'pub.dev', version: bridgeVersion },
+      projectFilesEdited: original.equals(fs.readFileSync(pubspec)) ? [] : ['pubspec.yaml'],
+      applicationDependencyVersionsChanged: [],
+      dependencyMetadata: ['pubspec.lock', '.dart_tool/package_config.json', '.flutter-plugins-dependencies'],
+      next: 'Install this debug APK into the original application package, then flutter-executor open. Ordinary lib/main.dart builds do not start WidgetTester.' };
+  }, { home });
+}
+
+function productionVersions(graph) {
+  const packages = new Map(graph.packages.map(item => [item.name, item]));
+  const versions = new Map();
+  function visit(name) {
+    if (versions.has(name)) return;
+    const item = packages.get(name);
+    if (!item) throw new CommandError('executor_flutter_dependency_graph_invalid', `Pub dependency is absent: ${name}`);
+    versions.set(name, item.version);
+    for (const child of item.directDependencies) visit(child);
+  }
+  for (const item of graph.packages.filter(item => item.kind === 'root')) for (const name of item.directDependencies) visit(name);
+  return versions;
+}
+
+async function prepareExecutor(args, dependencies = {}) {
+  if (args.platform === 'android') return prepareAndroid(args, dependencies);
+  if (args.platform === 'flutter') return prepareFlutter(args, dependencies);
+  if (args.platform === 'web') return { platform: 'web', bridgeVersion, ...await preparePackage(args.browser ?? 'chromium', dependencies) };
+  if (args.platform === 'ios') {
+    const { prepareManagedWda, wdaBuildEnvironment } = require('../ios-wda-project');
+    const xcode = await (dependencies.run ?? execFileBounded)(args.xcodebuild ?? 'xcodebuild', ['-version'],
+      { timeoutMs: 30000, env: wdaBuildEnvironment() });
+    return { ...await prepareManagedWda(dependencies), xcode: xcode.stdout.trim() };
+  }
+  throw new CommandError('invalid_argument', 'Select android, flutter, ios or web.');
+}
+
+module.exports = { preparationSchema, prepareExecutor, prepareAndroid, prepareFlutter, androidEntry, withProject, loggedRun, testClass, bridgeVersion, productionVersions };

package/bin/intent/install-intent.js

@@ -48,7 +48,9 @@ async function inspectApk(args, run = execute) {
     if (error instanceof CommandError) throw error;
     throw new CommandError('invalid_apk', 'APK manifest or signature verification failed.', { field: 'apkPath', details: { cause: error.code || null } });
   }
-  const pkg = /^package: name='([^']+)' versionCode='([^']+)' versionName='([^']*)'/m.exec(badging.stdout);
+  // AGP-generated instrumentation APKs can omit both version attributes.
+  // Identity still comes from the manifest package, verified signer and bytes.
+  const pkg = /^package: name='([^']+)' versionCode='([0-9]*)' versionName='([^']*)'/m.exec(badging.stdout);
   const certificates = [...new Set([...signatures.stdout.matchAll(/^(?:Signer #\d+|V(?:[124]|3(?:\.[01])?) Signer:) certificate SHA-256 digest: ([a-fA-F0-9]{64})\r?$/gm)].map(match => match[1].toLowerCase()))];
   if (!pkg || !certificates.length) throw new CommandError('invalid_apk', 'The APK has no verified package identity.', { field: 'apkPath' });
   if (args.packageName !== undefined && args.packageName !== pkg[1]) throw new CommandError('apk_package_mismatch', 'packageName differs from the APK manifest.', { field: 'packageName', details: { requested: args.packageName, apk: pkg[1] } });

package/bin/ios-provider.js

@@ -14,7 +14,7 @@ const { isMutationCommand, executionTimeoutMs } = require('./command-registry');
 const { normalizeExecutionTarget } = require('./shared-kernel/execution-target');
 const { descriptorBinding, bindingHeaders, assertRuntimeResponse, bindingFailure } = require('./ios-runtime-binding');
 const { openWdaPort, target: wdaTarget } = require('./ios-wda-port');
-const { prepareWdaProject, wdaBuildEnvironment } = require('./ios-wda-project');
+const { prepareManagedWda, wdaBuildEnvironment } = require('./ios-wda-project');
 const { executeWDAAction, reconcileWDA, completionPort } = require('./ios-wda-execution');
 const { deviceCommandRejection, deviceCommandProof } = require('./ios-device-outcome');
 const { initializationProof } = require('./ios-wda-startup');
@@ -776,8 +776,8 @@ class IOSBridgeProvider {
     if (!teamId) return { ok: false, error: 'ios_team_id_required', message: 'Signing WDA requires an explicit teamId or configured DEVELOPMENT_TEAM.' };
     checkExecution();
     const directory = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'aab-wda-runtime-'));
-    const prepared = prepareWdaProject({ destination: path.join(directory, 'source') });
     const ctx = this.context(args);
+    const prepared = await prepareManagedWda();
     const xcodeArgs = ['-project', prepared.projectPath, '-scheme', 'WebDriverAgentRunner', '-sdk', 'iphoneos', '-destination', `id=${device.udid}`,
       '-derivedDataPath', path.join(directory, 'build'), `DEVELOPMENT_TEAM=${teamId}`, `PRODUCT_BUNDLE_IDENTIFIER=${wdaTestBundleId}`,
       'ENABLE_DEFAULT_HEADER_SEARCH_PATHS=NO', '-allowProvisioningUpdates'];

package/bin/ios-wda-project.js

@@ -76,4 +76,51 @@ function prepareWdaProject({ destination, packageDirectory = path.dirname(requir
   return result;
 }
 
-module.exports = { supportedVersion, prepareWdaProject, wdaBuildEnvironment };
+async function prepareManagedWda({ home = require('./executors/managed-runtime').executorHome() } = {}) {
+  const { atomicJson, readJson } = require('./executors/managed-runtime');
+  const bridgeVersion = require('../package.json').version;
+  const hash = createHash('sha256').update(fs.readFileSync(__filename)).update(bridgeVersion).update(supportedVersion);
+  const sourceRoot = path.join(__dirname, '..', 'runtime', 'ios-wda');
+  for (const name of fs.readdirSync(sourceRoot).sort()) hash.update(name).update(fs.readFileSync(path.join(sourceRoot, name)));
+  const nativeRoot = path.dirname(require.resolve('@mobileaidev/segmented-fact-store-native/package.json'));
+  for (const name of ['package.json', 'include/sfs.h', 'src/sfs.c']) hash.update(fs.readFileSync(path.join(nativeRoot, name)));
+  const dependencyDigest = hash.digest('hex');
+  const directory = path.join(home, 'packages', 'ios-wda', dependencyDigest);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const { DatabaseSync } = require('node:sqlite');
+  const lock = new DatabaseSync(path.join(directory, 'prepare.sqlite'));
+  let locked = false;
+  try {
+    try { lock.exec('PRAGMA busy_timeout=0; BEGIN EXCLUSIVE'); locked = true; }
+    catch (error) { if (error.errcode === 5) throw new CommandError('executor_preparing', 'This WDA project is already being prepared.'); throw error; }
+    const readyFile = path.join(directory, 'prepared.json');
+    const existing = readJson(readyFile);
+    const sha256 = file => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    if (existing) {
+      for (const item of existing.files) {
+        const file = path.join(directory, 'source', item.path);
+        if (!fs.existsSync(file) || sha256(file) !== item.sha256)
+          throw new CommandError('ios_wda_prepared_source_changed', 'The managed WDA source changed after preparation. Select a new executor home to prepare clean source.');
+      }
+      return { ...existing.result, reused: true };
+    }
+    const destination = path.join(directory, 'source');
+    const prepared = prepareWdaProject({ destination });
+    const files = [];
+    function visit(relative) {
+      for (const entry of fs.readdirSync(path.join(destination, relative), { withFileTypes: true })) {
+        const name = path.join(relative, entry.name);
+        if (entry.isDirectory()) visit(name);
+        else if (entry.isFile()) files.push({ path: name, sha256: sha256(path.join(destination, name)) });
+      }
+    }
+    visit('');
+    const result = { ok: true, platform: 'ios', engine: 'wda-xcuitest', bridgeVersion, dependencyDigest, directory,
+      ...prepared, reused: false, lifecycle: 'source-prepared',
+      next: 'Run ios-setup with startWda, deviceId, bundleId and teamId to sign, build and start this managed Runner. Device trust and Enable UI Automation still require the device owner.' };
+    atomicJson(readyFile, { result, files });
+    return result;
+  } finally { if (locked) lock.exec('ROLLBACK'); lock.close(); }
+}
+
+module.exports = { supportedVersion, prepareWdaProject, prepareManagedWda, wdaBuildEnvironment };

package/bin/script/script-host-port.js

@@ -229,7 +229,7 @@ async function mutationResult(command, args, options, ctx) {
   const actionId = options.dispatchActionId || mutationActionId(ctx.executionId, ctx.callId);
   const bound = dispatchArgs(args, actionId);
   try {
-    return await admitExecutionMutation(ctx.target, ctx.mutationLease, async () => {
+    const execute = async () => {
       try { return await actionOnce(command, bound, options, {
       actions: ctx.actions,
       target: ctx.target,
@@ -238,7 +238,8 @@ async function mutationResult(command, args, options, ctx) {
       actionId,
       onAction: ctx.onAction,
       }); } finally { ctx.onSettled(); }
-    });
+    };
+    return command === 'executor-prepare' ? await execute() : await admitExecutionMutation(ctx.target, ctx.mutationLease, execute);
   } catch (error) {
     return unavailableEnvelope({ command, error: error.code || error.message, executionId: ctx.executionId, callId: ctx.callId });
   }

package/bin/shared-kernel/execution-target.js

@@ -73,6 +73,10 @@ function commandPlatform(command) {
 // select another platform; a partial identity can override defaults only on the
 // same platform. Never mix an Android serial with an iOS/Web connection.
 function bindCommandTarget(command, args, defaultTarget = null, explicitTarget) {
+  if (command === 'executor-prepare') {
+    if (explicitTarget !== undefined) throw new CommandError('target_platform_mismatch', 'Executor preparation runs on the Host and accepts no device target.');
+    return { target: null, args: { ...args } };
+  }
   const platform = commandPlatform(command);
   const definition = definitions[platform];
   const selected = explicitTarget === undefined ? defaultTarget : normalizeExecutionTarget(explicitTarget);

package/bin/shared-kernel/request-context.js

@@ -7,8 +7,8 @@ const context = new AsyncLocalStorage();
 const requestDirectory = () => context.getStore()?.cwd ?? process.cwd();
 const resolveRequestPath = value => path.resolve(requestDirectory(), value);
 const inRequestDirectory = (cwd, action) => context.run({ cwd }, action);
-const localPaths = ['outFile', 'artifactDir', 'apkPath', 'appPath', 'recordingDir', 'outputDir', 'archiveDir', 'wdaProjectPath', 'agentModule'];
-const executables = ['adb', 'aaptPath', 'apksignerPath', 'devicectl', 'xcodebuild', 'pythonPath'];
+const localPaths = ['outFile', 'artifactDir', 'apkPath', 'appPath', 'recordingDir', 'outputDir', 'archiveDir', 'wdaProjectPath', 'agentModule', 'projectDir', 'testPackagePath'];
+const executables = ['adb', 'aaptPath', 'apksignerPath', 'devicectl', 'xcodebuild', 'pythonPath', 'flutterPath', 'gradlePath'];
 
 // Only contract-defined filesystem fields are resolved. Web URL paths, source
 // text and arbitrary Script inputs keep their original values.

package/bin/target-execution.js

@@ -165,6 +165,8 @@ function requestDigest(command, args) {
 }
 
 function targetFor(command, args) {
+  if (command === 'executor-prepare') return { kind: 'host', platform: 'host',
+    key: `executor-prepare:${JSON.stringify([args.platform, args.projectDir ?? null])}` };
   if (command === 'logcat' && String(args.deviceLogScope || '').toLowerCase() === 'device') {
     const serial = targetPart(args.serial);
     return {

package/docs/OPTIONAL_EXECUTORS.md

@@ -1,4 +1,4 @@
-# Optional UI executors (0.3.6)
+# Optional UI executors (0.3.8)
 
 Bridge keeps its existing SDK paths and exposes optional executors through `capabilities`, `run`, and JavaScript/Python Script. Select an executor explicitly. No command silently changes a touch into a setter, switches framework after failure, or repeats an uncertain action.
 
@@ -15,9 +15,35 @@ Bridge keeps its existing SDK paths and exposes optional executors through `capa
 
 These dependencies are isolated from ordinary production source sets. They are visible in build metadata and diagnostics. They do not disappear from the installation or compatibility requirements. Android does **not** need a separate business App, repository, or Gradle project. The standard test APK is an Android test artifact.
 
-## Android: one entry in the existing application
+## Automatic preparation in the existing project
 
-Add the selected artifacts to the application's `androidTestImplementation` configuration. All Bridge artifacts use the same version:
+Use `executor-prepare` from CLI, MCP `run`, or JavaScript/Python `ctx.call` with `app.test`. This is a Host operation: it does not require a device target, install an App, start UI observation, or open an executor session. Preparation uses the selected project's existing toolchain and keeps its application ID. The result separates preparation from installation and session readiness.
+
+```sh
+ai-app-bridge executor-prepare --platform android --project-dir /project \
+  --module :app --variant debug --adapters '["espresso-web"]'
+ai-app-bridge executor-prepare --platform flutter --project-dir /flutter-app \
+  --flutter-path /flutter-sdk/bin/flutter
+ai-app-bridge executor-prepare --platform ios
+ai-app-bridge executor-prepare --platform web --browser chromium
+```
+
+- Android: a temporary Gradle init script adds the test dependencies and a generated session class only for this invocation. The dependency-check plugin is applied automatically. The result contains the actual application ID, instrumentation component, test class, APK paths and SHA-256 values. Existing matching test dependencies/runners are reused; conflicting Bridge test dependencies are rejected. Business Gradle, manifest and source files are not edited. Select the actual module and debuggable variant; flavors and APK splits retain their original identities. The current build integration uses the AGP 7.4–8.x variant API on macOS/Linux; AGP 9 and Windows preparation are not part of this profile. A local `file:` Maven `repositoryUrl` can explicitly select development artifacts; ordinary preparation resolves the same release version from JitPack.
+- Flutter: the command runs the project's selected Flutter executable, adds the exact `ai_app_bridge_test` version to `dev_dependencies` with Pub, and generates a test entry under `build/ai-app-bridge`. It supports Pub workspaces, an explicit `entrypoint`, `flavor`, `dartDefines`, and `mainArguments` for applications whose main accepts a string list. Pubspec/lock changes are visible configuration; the result lists them. Main Dart code is not edited. The helper uses the same Flutter SDK as the App. Baseline resolution uses `pub get --enforce-lockfile`: commit a valid application/workspace lockfile first. This prevents dependency changes before comparison, including on a new computer. If adding the helper changes an existing production dependency version or Pub fails midway, preparation restores the pubspec/lock and reports the conflict or original error. A successful dependency solve is followed by a real debug build. Repeated preparation reuses the exact resolved helper. `testPackagePath` explicitly selects a local helper during development and must carry the matching Bridge version. The current WidgetTester host remains Android-only; iOS Flutter controls use the existing iOS Flutter SDK/WDA paths.
+- iOS: checks Xcode and prepares a pinned WDA project in the managed executor directory. Source hashes are verified before reuse. `ios-setup --start-wda` reuses that project to sign, build and launch the Runner for the explicitly selected phone. Xcode, signing credentials, device trust and Enable UI Automation are still required. No XCTest source is added to the business application.
+- Web: uses the existing pinned Playwright/browser preparation, outside the page SDK. It can be reused without modifying the web project or adding browser dependencies to its production bundle.
+
+Generated files and logs are placed under the project's `build/ai-app-bridge/prepare/<id>`; each preparation writes `result.json`, including failures. Mobile preparation reports `built-not-installed` (iOS source preparation reports `source-prepared`). Install the returned matching artifacts with the public install commands, then open the selected executor. JS/Python workflow changes do not require rebuilding an already prepared App; changes to application code or test dependencies do.
+
+Installing the npm package alone does not install Android SDK/JDK, Flutter, Xcode, Python, or project-specific tools such as Rust. Preparation reports the missing prerequisite or original compiler log; it never upgrades a business toolchain to hide a conflict.
+
+Android uses the project's Gradle wrapper. For a monorepo that shares a wrapper outside `projectDir`, pass its exact path as `--gradle-path /path/to/gradlew`. Existing matching test dependencies and a custom test runner are retained. Installing a generated androidTest APK does not require it to declare an application version; manifest package, signature and installed APK bytes are still verified.
+
+Android WebView H5 requires the optional `espresso-web` adapter and the application's existing JavaScript configuration. iOS WKWebView uses the existing bound H5 SDK path. Playwright manages browser pages; it is not silently used as the controller for a native App's embedded WebView.
+
+## Android: optional manual customization
+
+Automatic preparation generates the entry and dependencies below. Add them manually only when the project needs custom test rules or adapters. All Bridge artifacts use the same version:
 
 ```kotlin
 android {
@@ -26,9 +52,9 @@ android {
     }
 }
 dependencies {
-    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-instrumentation:0.3.6")
+    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-instrumentation:0.3.8")
     // Optional H5 adapter:
-    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-espresso-web:0.3.6")
+    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-espresso-web:0.3.8")
 }
 ```
 
@@ -79,11 +105,13 @@ Compose is optional and its runtime is supplied by the consumer. The initial Com
 
 The rule must start **before** Activity/composition creation. The adapter uses automatic test clock advancement and idle frame ticks; animation timing is not wall-clock fidelity. `click` uses Compose touch input; `composeInput`, `composeReplaceText`, `composeClearText`, scroll semantics and `semanticLongClick` are explicit semantics operations. WebView/platform Views and system dialogs require their corresponding adapters. No private Compose field reflection is used by Bridge.
 
+Espresso text actions have different semantics. `replaceText` is the framework's setter path; a custom editor can deliberately suppress its business listeners, so an immediate text readback is insufficient. `replaceTextViaInputConnection` explicitly selects the editor's full text and commits through its `InputConnection`, reporting `espresso-input-connection`. It supports Unicode when the editor accepts that connection and does not fall back to a setter. `typeText` injects key input and has the framework's keyboard character limits. Reopen the screen and check persisted application state for all three paths; none alone proves a physical keyboard/IME workflow. Espresso observations include checked state for `Checkable` widgets.
+
 ## Flutter
 
-Add `ai_app_bridge_test: 0.3.6` to the application's `dev_dependencies`. The helper takes `flutter_test` and `integration_test` from the **same Flutter SDK** as the application. It is a Dart test helper, not an additional Android plugin with its own AGP/Kotlin versions.
+Add `ai_app_bridge_test: 0.3.8` to the application's `dev_dependencies`. The helper takes `flutter_test` and `integration_test` from the **same Flutter SDK** as the application. It is a Dart test helper, not an additional Android plugin with its own AGP/Kotlin versions.
 
-The helper declares Flutter **>=3.41.0** and Dart **>=3.11.0 <4.0.0**. This release was built and exercised with Flutter **3.41.9 on Android API 25** and **3.44.8 on Android API 36**. These are the verified combinations; newer SDK versions still need validation with the application's plugin graph.
+The helper declares Flutter **>=3.41.0** and Dart **>=3.11.0 <4.0.0**. The 0.3.8 automatic preparation was exercised with LocalSend on Flutter **3.41.9 / Android API 36**, preserving all 214 production dependency versions. Earlier executor validation covered Flutter 3.41.9 / API 25 and 3.44.8 / API 36. These are specific verified combinations; other SDK versions still need validation with the application's plugin graph.
 
 ```dart
 // integration_test/bridge_test.dart

package/docs/RELEASE.md

@@ -1,8 +1,22 @@
-# 0.3.6 发行与接入交接
+# 0.3.8 发行与接入交接
 
 本文件记录正式版的依赖关系和出仓库交付入口。封版要求是同一提交的源码、发行包与公开接入合同一致；单个样本的测试进度不改变包版本或发布状态。推送 Git、创建远端标签及发布 npm/pub 包由维护者执行。
 
-## 0.3.6 新增
+## 0.3.8 自动准备
+
+- 新增 `executor-prepare`，为原工程准备可选测试执行器，公开命令数为 122。
+- Android 自动生成 androidTest 入口、注入测试依赖并构建原包名的主包与测试包；Flutter 自动添加 dev_dependency、生成入口并检查业务依赖版本。
+- iOS 管理并校验可复用的 WDA 工程；Web 复用精确版本 Playwright 和浏览器准备流程。
+- 准备不启动持续 UI 观察，不自动升级业务工具链；实际设备/浏览器验证与发布证据另行记录。
+- Espresso 增加显式 `replaceTextViaInputConnection` 输入选项，并返回可勾选控件的实际状态；原有 setter 和按键输入分别保留其语义。NotallyX 真机回归验证了自定义 `setText` 抑制业务监听的情况，不能只以屏幕文字变化认定保存成功。
+- 允许安装标准 AGP 生成的无版本号 androidTest APK，包名、签名和安装后文件哈希校验继续执行。
+
+## 随本版包含的 0.3.7 修复
+
+- Android Host 读取全部焦点记录，跳过 `null`，不再依赖记录排列顺序。只有一个有效窗口时直接使用；多个窗口通过系统 `mTopFocusedDisplayId` 选择，仍不能唯一定位时返回 `foreground_ambiguous`。
+- 包名匹配、SDK 窗口与控件身份校验沿用既有路径。App SDK 只同步发行版本。
+
+## 随本版包含的 0.3.6 能力
 
 - Android、iOS、Flutter、Web 与内嵌 H5 的持续 UI 观察默认关闭；仅按需开启 100–5000 ms 的观察窗口，期限到达、主动停止或相应生命周期退出时清理观察任务。新增三个平台观察控制命令，公开命令共 121 个。
 - Flutter 当前树改为显式读取 `/v1/flutter/snapshot`，状态请求不再触发树遍历；CLI/MCP 与 App 内 SDK 需要配套升级。Android 指纹编码减少 JNI 调用与临时分配。实测证据及边界见仓库中的 UI 观察性能评估记录。
@@ -12,7 +26,7 @@
 - 公开 capabilities + run、Python/JS Script 的 app.test 权限、观测身份、原始回执、取消和设备占用接线。
 - Compose 主包/测试包版本检查；按测试配置隔离依赖，不自动升级业务 AGP/Kotlin/Compose。
 - Android 7 权限输出的零 flags 省略及空格分隔格式支持，来源为实际 API-25 环境和 AOSP Settings 输出实现。
-- 本地交付和外部发布分开记录；这份源码不表示 npm/JitPack/pub.dev 已发布 0.3.6。
+- 本地交付和外部发布分开记录；这份源码不表示 npm/JitPack/pub.dev 已发布 0.3.8。
 
 接入合同、具体依赖和实测性能见 [OPTIONAL_EXECUTORS.md](OPTIONAL_EXECUTORS.md)。
 
@@ -36,18 +50,18 @@
 
 ## 新增可选分发物
 
-Android `ai-app-bridge-test-core`、`ai-app-bridge-test-uia`、`ai-app-bridge-test-espresso`、`ai-app-bridge-test-instrumentation`、`ai-app-bridge-test-espresso-web`、`ai-app-bridge-test-compose` 均使用 0.3.6，通过 androidTestImplementation 消费。Gradle 插件增加 `io.github.mobileaidev.aiappbridge.test` 依赖校验入口。新 Flutter 包 `ai_app_bridge_test` 使用 0.3.6，只作为 dev_dependency；它的发布不依赖 Android SDK 的 JitPack 坐标。
+Android `ai-app-bridge-test-core`、`ai-app-bridge-test-uia`、`ai-app-bridge-test-espresso`、`ai-app-bridge-test-instrumentation`、`ai-app-bridge-test-espresso-web`、`ai-app-bridge-test-compose` 均使用 0.3.8，通过 androidTestImplementation 消费。Gradle 插件增加 `io.github.mobileaidev.aiappbridge.test` 依赖校验入口。新 Flutter 包 `ai_app_bridge_test` 使用 0.3.8，只作为 dev_dependency；它的发布不依赖 Android SDK 的 JitPack 坐标。
 
 ## 版本与消费方式
 
 | 交付物 | 发行版本 | 独立消费入口 | 发布依赖 |
 | --- | --- | --- | --- |
-| Android SDK | `0.3.6` | JitPack `com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-android:0.3.6` | 同名 Git tag，JitPack 对该提交成功构建 |
-| Android Gradle 插件 | `0.3.6` | JitPack `ai-app-bridge-gradle-plugin` 模块及插件 ID `io.github.mobileaidev.aiappbridge.android` | 与 SDK 相同的 Git tag；不再使用旧默认 `0.2.8` |
-| 原生 iOS SDK | Git tag `0.3.6` | Git URL 的仓库根 `Package.swift`，产品 `AiAppBridgeIOS` | 根清单包含 Swift runtime、C adapter 和 segmented C store，无外部 C 包路径 |
-| Flutter 插件 | `0.3.6` | pub `ai_app_bridge_flutter` | Android 固定依赖上述 SDK；iOS Swift/C 源码随插件分发 |
-| Desktop CLI/MCP | `0.3.6` | npm `@mobileaidev/ai-app-bridge` | 包含 UIA bundle、WDA 模板和 native store 源码；WDA 上游固定 `14.1.1` |
-| Web SDK | `0.3.6` | npm `@mobileaidev/ai-app-bridge-web` | 独立浏览器源码包，无 npm 对 CLI 的安装依赖 |
+| Android SDK | `0.3.8` | JitPack `com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-android:0.3.8` | 同名 Git tag，JitPack 对该提交成功构建 |
+| Android Gradle 插件 | `0.3.8` | JitPack `ai-app-bridge-gradle-plugin` 模块及插件 ID `io.github.mobileaidev.aiappbridge.android` | 与 SDK 相同的 Git tag；不再使用旧默认 `0.2.8` |
+| 原生 iOS SDK | Git tag `0.3.8` | Git URL 的仓库根 `Package.swift`，产品 `AiAppBridgeIOS` | 根清单包含 Swift runtime、C adapter 和 segmented C store，无外部 C 包路径 |
+| Flutter 插件 | `0.3.8` | pub `ai_app_bridge_flutter` | Android 固定依赖上述 SDK；iOS Swift/C 源码随插件分发 |
+| Desktop CLI/MCP | `0.3.8` | npm `@mobileaidev/ai-app-bridge` | 包含 UIA bundle、WDA 模板和 native store 源码；WDA 上游固定 `14.1.1` |
+| Web SDK | `0.3.8` | npm `@mobileaidev/ai-app-bridge-web` | 独立浏览器源码包，无 npm 对 CLI 的安装依赖 |
 | Native store | `0.1.0` | 随 CLI 的 bundled dependency 安装 | 不要求另行发布到 npm；`file:../../native/segmented-fact-store` 是工作区构建入口，最终 tarball 必须包含该依赖源码 |
 
 Flutter 的 podspec 是随 pub 插件消费的本地 podspec，不是独立 CocoaPods trunk 发布包；原生 iOS 使用根 Swift package。Flutter SwiftPM 的 `../FlutterFramework` 由 Flutter 的集成生成，不能当作本仓库的外部私有依赖，也不应将本机 Flutter framework 打包进插件。
@@ -56,11 +70,11 @@ Host 支持范围声明为 Node `>=26.3.0 <27`，本轮实际验证基线是 **2
 
 ## 发布顺序
 
-1. 完成源码审阅并冻结一个提交，核对以下命令的产物确实来自它；包含当前 untracked 的实际源码、测试和文档，排除本机生成目录。所有对外发行版本使用同一个 `0.3.6`，若需要改版本，先同时更新上表涉及的 manifest 与固定依赖。
-2. 维护者推送提交与 `0.3.6` 标签，让 JitPack 构建 Android SDK/插件。确认两条公开坐标可解析后，再发布依赖它们的 Flutter 包。本地 Gradle project/path/AAR 替换不能证明 JitPack 坐标可消费。
+1. 完成源码审阅并冻结一个提交，核对以下命令的产物确实来自它；包含当前 untracked 的实际源码、测试和文档，排除本机生成目录。所有对外发行版本使用同一个 `0.3.8`，若需要改版本，先同时更新上表涉及的 manifest 与固定依赖。
+2. 维护者推送提交与 `0.3.8` 标签，让 JitPack 构建 Android SDK/插件。确认两条公开坐标可解析后，再发布依赖它们的 Flutter 包。本地 Gradle project/path/AAR 替换不能证明 JitPack 坐标可消费。
 3. 原生 iOS 消费相同 Git tag 的根 package；完成根 package 的 iOS 构建，不仅构建 `ios/ai-app-bridge-ios/Package.swift`。Flutter iOS 则检查实际 pub 包内 Swift/C 源码与声明相符。
 4. CLI 与 Web SDK 可分别发布到 npm 的 `latest` dist-tag。CLI 的 native store 已打包随行，不等待一个不存在的单独 registry 依赖。Flutter 包发布以第 2 步完成为前提。
-5. 同步 npm `next` 指向 `0.3.6`，让已有候选入口也使用本次正式版。将 GitHub `main` 与发行提交同步，并创建非预发布的 GitHub Release。
+5. 同步 npm `next` 指向 `0.3.8`，让已有候选入口也使用本次正式版。将 GitHub `main` 与发行提交同步，并创建非预发布的 GitHub Release。
 6. 从 registry/tag 安装刚发布的确切版本，读取 `capabilities` 和版本，核对来源及支持范围，确认默认安装入口指向本次发行版本。正式发布不自动等于全平台生产验收完成。
 
 正式发布命令需在对应目录由维护者执行，例如 npm 使用 `npm publish --tag latest`；pub 使用 `flutter pub publish`。这些命令属于发布动作，不能混入本地验证脚本。
@@ -101,7 +115,7 @@ npm 升级不会替换已连接的 MCP 进程。用 `ai-app-bridge --version`
 已有工作结束后显式停止旧 Runtime，并在 Cursor 等客户端重连 MCP，核对 initialize
 中的 `serverInfo.version`。工具描述仍有旧 `batch`/`smoke` 时刷新客户端缓存。
 
-实际发布状态与验证边界见仓库 `docs/EXECUTOR_DELIVERY_0.3.6.md`。
+实际发布状态与验证边界见仓库 `docs/RELEASE_HANDOFF_0.3.8_2026-09-15.md`。
 Android Gradle 插件的 `webSocketCaptureEnabled`、`logInstrumentationEnabled`、
 `webViewDebuggingEnabled` 没有对应插桩实现，现明确弃用并在显式设置时输出提示；
 旧配置仍可构建。当前有效开关是 `enabled`、`okHttpCaptureEnabled`，以及可选

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobileaidev/ai-app-bridge",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Desktop CLI and MCP server for AI App Bridge across Android, iOS, Flutter, WebView, and Web targets.",
   "repository": {
     "type": "git",

package/runtime/executors/android/prepare.init.gradle

@@ -0,0 +1,70 @@
+// Applied only to this preparation build. No business Gradle/source file is edited.
+initscript {
+    def config = new groovy.json.JsonSlurper().parse(new File(System.getProperty('aab.prepare.config')))
+    repositories {
+        maven { url = uri(config.repositoryUrl) }
+        google()
+        mavenCentral()
+    }
+    dependencies { classpath config.pluginCoordinate }
+}
+
+def config = new groovy.json.JsonSlurper().parse(new File(System.getProperty('aab.prepare.config')))
+def repositoryMode
+gradle.settingsEvaluated { settings ->
+    repositoryMode = settings.dependencyResolutionManagement.repositoriesMode.get().name()
+    settings.dependencyResolutionManagement.repositories {
+        maven { url = uri(config.repositoryUrl) }
+        google()
+        mavenCentral()
+    }
+}
+gradle.beforeProject { consumer ->
+    if (consumer.path != config.module) return
+    consumer.plugins.withId('com.android.application') {
+        if (repositoryMode == 'PREFER_PROJECT') {
+            consumer.repositories {
+                maven { url = uri(config.repositoryUrl) }
+                google()
+                mavenCentral()
+            }
+        }
+        consumer.pluginManager.apply(io.github.mobileaidev.aiappbridge.gradle.AiAppBridgeTestGradlePlugin)
+        consumer.extensions.getByName('androidComponents').finalizeDsl { android ->
+            if (!android.defaultConfig.testInstrumentationRunner) {
+                android.defaultConfig.testInstrumentationRunner = 'androidx.test.runner.AndroidJUnitRunner'
+            }
+            // Consumer dependencies are complete only after its build script.
+            config.dependencies.each { coordinate ->
+                def parts = coordinate.split(':')
+                def existing = consumer.configurations.getByName('androidTestImplementation').allDependencies.findAll { it.name == parts[1] }
+                if (existing.empty) consumer.dependencies.add('androidTestImplementation', coordinate)
+                else if (parts[1].startsWith('ai-app-bridge-test-') && (existing.size() != 1 || existing[0].version != parts[2])) {
+                    throw new GradleException('[AiAppBridge] Existing test dependency must match ' + coordinate + '; no dependency was replaced.')
+                }
+            }
+        }
+        consumer.android.sourceSets.androidTest.java.srcDir(new File(config.directory, 'java'))
+        consumer.android.applicationVariants.all { variant ->
+            if (variant.name != config.variant) return
+            if (!variant.buildType.debuggable) throw new GradleException('[AiAppBridge] Executor preparation requires a debuggable variant.')
+            def testVariant = variant.testVariant
+            if (testVariant == null) throw new GradleException('[AiAppBridge] Enable androidTest for the selected variant.')
+            consumer.tasks.register('aiAppBridgePrepareExecutor') { task ->
+                task.dependsOn(variant.assembleProvider, testVariant.assembleProvider)
+                task.doLast {
+                    def report = [
+                        schemaVersion: 'aab.android-prepared-build/v1',
+                        projectDir: consumer.rootDir.absolutePath, module: consumer.path, variant: variant.name,
+                        gradleVersion: consumer.gradle.gradleVersion,
+                        packageName: variant.applicationId, testPackageName: testVariant.applicationId,
+                        runner: testVariant.mergedFlavor.testInstrumentationRunner,
+                        applicationApks: variant.outputs.collect { it.outputFile.absolutePath },
+                        testApks: testVariant.outputs.collect { it.outputFile.absolutePath }
+                    ]
+                    new File(config.directory, 'android-build.json').text = groovy.json.JsonOutput.toJson(report)
+                }
+            }
+        }
+    }
+}

package/runtime/executors/playwright/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "ai-app-bridge-playwright-runtime",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "ai-app-bridge-playwright-runtime",
-      "version": "0.3.6",
+      "version": "0.3.8",
       "dependencies": {
         "playwright": "1.63.0"
       },

package/runtime/executors/playwright/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-app-bridge-playwright-runtime",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "private": true,
   "description": "Optional, isolated browser runtime managed by AI App Bridge.",
   "engines": { "node": ">=26.3.0 <27" },