@mobileaidev/ai-app-bridge 0.3.5 → 0.3.7

package/docs/COMMAND_CONTRACT.md

@@ -1114,7 +1114,18 @@ metadata, not the raw transport bytes. Settlement proves the recorded execution
 it does not turn an ambiguous action or unverified business assertion into a pass.
 
 Native Intent `longPress`, `swipe` and `scroll` use `/v1/action/gesture-target`.
-The top visible SDK window owns pointer selection. A touchable, non-focusable
+The SDK selects the top visible window belonging to the current Activity on its
+display. Application windows use `WindowManager.LayoutParams.token` for Activity
+ownership; subwindows resolve that token through their parent window. Focus is
+not evidence of Activity ownership. A missing token, unresolved parent or unknown
+window type blocks selection with `native_window_metadata_unavailable`.
+Native tree snapshots publish this decision as `foregroundWindowId`, referring to
+exactly one entry in `windows`. Host summaries and semantic selection consume
+that identity, and SDK semantic, coordinate, gesture and H5 execution use the same
+window policy. Native window snapshots without this field require an updated SDK;
+Host does not reconstruct the decision from focus or array order.
+
+A touchable, non-focusable
 popup can use its focused owner with the same application window token; the SDK
 does not select a background window when the popup blocks an action. Native/H5
 window selection shares this rule. Native window observation carries
@@ -1640,3 +1651,29 @@ explicit state assertions, or request Agent help through `ctx.askAgent`.
 `ios-setup --start-wda true` records the exact XCTest invocation and result bundle before starting the device test. A completed XCTest failure that explicitly says UI test initialization timed out while enabling automation is a settled failed startup (`ios_wda_automation_confirmation_required`). The Runner launch was dispatched; this does not undo its installation. Confirm Enable UI Automation on the device, then explicitly run setup again.
 
 `ios-execution --operation reconcile --device-id DEVICE` reads the original result bundle after an interrupted Host. For a legacy generic `ios-setup` marker, supply `--setup-result-path ORIGINAL_RESPONSE.json`: recovery requires the original CLI JSON response (or its unwrapped value), its matching retained Host action in the current FactStore, the same device and startup interval, and the original XCTest bundle identified by that response. Missing, mismatched, or generic test failures remain unresolved. This option is accepted only for SDK/command reconciliation, never action cancellation or WDA session recovery. Lock files and original evidence are retained.
+
+### Bounded SDK UI observation
+
+`ui-observation`, `ios-ui-observation` and `web-ui-observation` expose
+`start`, `status` and `stop`. Start requires `durationMs` in 100–5000; stop
+requires the returned `leaseId`. Android/iOS accept `provider: native|flutter`.
+The capability is available to JS and Python Script under `capture.read`.
+There is no unbounded lease, automatic renewal or activation at SDK startup.
+Closing/reopening a window establishes a new baseline; an idle interval is not
+evidence of an unchanged UI. Lifecycle and explicit business captures remain
+independent of heavy UI observation.
+
+Native and Flutter controls use `/v1/ui/observation` and
+`/v1/flutter/observation`. The response schema is `aab.ui-observation/v1`.
+`GET /v1/flutter/snapshot` explicitly pulls fresh Dart UI state. Flutter tree,
+node and selection commands use it. `GET /v1/status` does not pull a Flutter
+tree or publish cached layout as current UI. Query a provider's observation
+command for its live lease state. These endpoints require rebuilt SDKs;
+installing a new CLI cannot patch an installed application's old SDK.
+
+Ordinary CLI/MCP `feedback=full` opens a window before the action and releases
+it in finally. If observation is unavailable, the action is rejected before
+dispatch; acquiring evidence does not mark the enclosing UI action dispatched.
+Launch retains its independent system feedback path. Script/Intent bypass this
+feedback wrapper and explicitly request windows only when their evidence needs
+them. SDK/page expiry handles a Host that disappears without sending stop.

package/docs/OPTIONAL_EXECUTORS.md

@@ -0,0 +1,182 @@
+# Optional UI executors (0.3.7)
+
+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.
+
+## What is installed
+
+| Capability | Dependency location | Integration requirement |
+| --- | --- | --- |
+| Android UI Automator / Espresso | Application **androidTest** dependencies and its generated test APK | Small precompiled test entry; matching installed application and test packages |
+| Android WebView H5 | Optional `ai-app-bridge-test-espresso-web` in androidTest | JavaScript already enabled by the application; explicit WebView and frame selection |
+| Android Compose | Optional `ai-app-bridge-test-compose` in androidTest | Application-matched Compose test runtime and a JUnit rule surrounding the session |
+| Flutter WidgetTester | `ai_app_bridge_test` in **dev_dependencies**, using Flutter SDK test packages | Debug APK built from `integration_test/bridge_test.dart` |
+| Web Playwright | CLI-managed directory outside the page SDK | Explicitly prepare the pinned Playwright package and matching browser |
+| iOS | Existing WDA / XCUITest integration | Existing signing, device and WDA prerequisites; no new iOS executor in this version |
+
+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
+
+Add the selected artifacts to the application's `androidTestImplementation` configuration. All Bridge artifacts use the same version:
+
+```kotlin
+android {
+    defaultConfig {
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+    }
+}
+dependencies {
+    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-instrumentation:0.3.7")
+    // Optional H5 adapter:
+    androidTestImplementation("com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-test-espresso-web:0.3.7")
+}
+```
+
+Place this tiny entry in the existing `app/src/androidTest/java/...` directory:
+
+```java
+package example.app;
+import io.github.mobileaidev.aiappbridge.executor.instrumentation.AndroidExecutorTest;
+public final class BridgeSessionTest extends AndroidExecutorTest {}
+```
+
+This is a precompiled, long-running JUnit test. Host passes the session identity, token, Activity and lease as Instrumentation arguments. The test thread executes incoming commands serially. Python/JS scripts do not become Kotlin/Java source and do not require rebuilding for each workflow. You may extend the test's `adapters()` and add ordinary JUnit rules or idling resources. Arbitrary business field reflection and arbitrary existing `@Test` method invocation are not exposed as remote commands.
+
+Opening a session **restarts and instruments the target application**. Install the matching main and test APKs built from this application first:
+
+```sh
+./gradlew :app:assembleDebug :app:assembleDebugAndroidTest
+adb -s DEVICE install -r -t app/build/outputs/apk/debug/app-debug.apk
+adb -s DEVICE install -r -t app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk
+ai-app-bridge android-executor --operation status --serial DEVICE
+ai-app-bridge android-executor --operation open --serial DEVICE \
+  --package-name example.app \
+  --instrumentation example.app.test/androidx.test.runner.AndroidJUnitRunner \
+  --test-class example.app.BridgeSessionTest --activity example.app.MainActivity
+```
+
+Use the actual installed component names returned by `status`. Supply the returned `sessionId` and `runtimeEpoch` to subsequent operations. `observe` requires an `engine` listed in `open.capabilities.adapters`. `act` requires the current `snapshotId` and a `nodeId` from that observation. Changing adapters invalidates the previous snapshot.
+
+The instrumentation artifact includes `uiautomator` and `espresso`. Add H5 in `adapters()` with `adapters.put("espresso-web", new EspressoWebExecutor())`, after obtaining `super.adapters()`. H5 observation accepts `webView: {by:"description",value:"..."}` or `resourceId`, and `framePath: [{name:"..."}]` or `{index:0}` entries. An unspecified WebView must match exactly one WebView. JavaScript is not automatically enabled. `webClick`, `webKeys`, `webClear` and `webScrollIntoView` use WebDriver JavaScript atoms, not Android IME or physical touch. Open Shadow DOM and cross-origin frame support must be checked for the concrete WebView; closed Shadow DOM is not advertised.
+
+## Dependency checks and Compose
+
+Apply `io.github.mobileaidev.aiappbridge.test` from the same Gradle plugin artifact. It only validates resolved dependencies; it adds no UI bytecode instrumentation and does not rewrite versions. With JitPack, map this plugin ID in `pluginManagement.resolutionStrategy.eachPlugin` to `com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-gradle-plugin:<requested version>`, as for the existing `io.github.mobileaidev.aiappbridge.android` plugin. Include JitPack, Google Maven and Maven Central in the appropriate repositories.
+
+The initial Android adapter profile is runner **1.7.0**, Espresso / Espresso-Web **3.7.0**, UI Automator **2.4.0**, Java **11**, minSdk **23**, compileSdk **35**. The source build uses AGP **8.9.1** and JDK **17**. This is a supported profile, not a promise that every old Gradle/AGP combination can consume the artifacts.
+
+Compose is optional and its runtime is supplied by the consumer. The initial Compose adapter profile is **1.8.3**. Apply the application's **same Compose BOM** to its main/debug and androidTest dependencies, then add `ui-test-junit4` without an independent version. The plugin rejects a different main/test Compose runtime or an unvalidated adapter profile. It does not upgrade an application's Kotlin, Compose, AGP or compileSdk to make the check pass. An application outside this profile can keep the existing SDK/UI Automator route or provide a separately validated adapter build.
+
+```java
+@Rule public final ComposeTestRule compose =
+    AndroidComposeTestRule_androidKt.createEmptyComposeRule();
+@Override protected Map<String, ExecutorAdapter> adapters() {
+    Map<String, ExecutorAdapter> adapters = super.adapters();
+    adapters.put("compose", new ComposeExecutor(compose));
+    return adapters;
+}
+```
+
+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.
+
+## Flutter
+
+Add `ai_app_bridge_test: 0.3.7` 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.
+
+```dart
+// integration_test/bridge_test.dart
+import 'package:ai_app_bridge_test/ai_app_bridge_test.dart';
+import 'package:your_app/main.dart' as app;
+void main() => aiAppBridgeTest(app.main);
+```
+
+```sh
+flutter build apk --debug --target integration_test/bridge_test.dart \
+  --dart-define=INTEGRATION_TEST_SHOULD_REPORT_RESULTS_TO_NATIVE=false
+adb -s DEVICE install -r -t build/app/outputs/flutter-apk/app-debug.apk
+ai-app-bridge flutter-executor --operation open --serial DEVICE \
+  --package-name example.app --activity example.app.MainActivity
+```
+
+This version supports the standard **Android Flutter embedder**, with its normal application private cache directory. Launch configuration and original receipts use `no_backup/ai-app-bridge-integration`, outside evictable caches. Opening restarts the test-entrypoint app. Closing drains the tester queue and terminates only the original process, identified by boot ID, PID and process start time. The helper uses a fully live frame policy. `tap`, `longPress`, drag/fling, `ensureVisible`, `pageBack`, `pump` and `enterText` are exposed. `enterText` changes Flutter editing state and reads it back; it does not prove native IME input. Flutter platform views, WebView DOM and system dialogs require another applicable provider. Flutter iOS/desktop/web test-host launch is not implemented by this helper.
+
+## Web
+
+```sh
+ai-app-bridge web-executor --operation status --browser chromium
+ai-app-bridge web-executor --operation prepare --browser chromium --timeout-ms 300000
+ai-app-bridge web-executor --operation open --url http://localhost:3000 --browser chromium
+```
+
+The CLI manages exact Playwright **1.63.0**, an included npm lock file and matching browser downloads. `prepare` is explicit; normal SDK usage does not download browsers. Cache keys include the dependency lock digest, OS and CPU architecture. Node **26.3.x** is the verified Host baseline (`>=26.3.0 <27` contract). Browser preparation is serialized and reports failures. `status` separates the static version from actual executable availability.
+
+`observe` returns pages and documents. Pass the observed `targetId`, `frameId` and `documentId` to actions/waits. A navigation during automatic waiting cannot move an old command into the replacement document. Selectors must be unique; role names and text matching are exact. `css` accepts standard CSS syntax, not Playwright selector chains. Actions include click, doubleClick, hover, fill, type, press, check, select, drag, scrollIntoView and upload. Physical `wheel` is not exposed: Playwright's page mouse API cannot bind the event atomically to the observed document. It is never replaced with a synthetic DOM event. Dialogs default to dismiss; an action may explicitly request accept/dismiss. Browser dialogs, popup pages, open Shadow DOM and iframe observations are supported; native OS dialogs and closed Shadow DOM are outside this executor.
+
+Control `text` contains the element's `innerText`, preserving an empty string. It is `null` for elements without `innerText`; hidden `textContent` is not substituted. Each action ID occupies one slot across all pages in the session. Reusing it on another page is rejected with `executor_receipt_identity_mismatch`; changing other action arguments is rejected with `idempotency_conflict`.
+
+## Agent, Python and JS contract
+
+Discover only the operation needed:
+
+```json
+{"command":"android-executor","operation":"act"}
+```
+
+This is a `capabilities` selection, not an action. Execute through the existing `run` tool, or `ctx.call` in Script with **`app.test`** permission. Script targets remain `platform:"android"` for Android/Flutter Android, and `platform:"web"` for browser sessions. Device/package targeting is inherited from the Script target; session identities are explicit inputs.
+
+```javascript
+// Within module.exports.main = async ctx => { ... }
+const reply = await ctx.call('android-executor', {
+  ...ctx.inputs.identity, operation: 'observe', engine: 'espresso'
+});
+if (!reply.ok || !reply.result.ok) throw new Error(JSON.stringify(reply));
+const observation = reply.result.observation;
+const buttons = observation.nodes.filter(n => n.text === 'Submit');
+if (buttons.length !== 1) throw new Error('Expected exactly one Submit button');
+const result = await ctx.call('android-executor', {
+  ...ctx.inputs.identity, operation: 'act', snapshotId: observation.snapshotId,
+  actionId: 'submit-once', action: {type: 'click', nodeId: buttons[0].nodeId}
+});
+if (!result.ok || !result.result.ok) throw new Error(JSON.stringify(result));
+```
+
+```python
+reply = ctx.call('flutter-executor', {**ctx.inputs['identity'], 'operation': 'observe'})
+assert reply['ok'] and reply['result']['ok'], str(reply)
+observation = reply['result']['observation']
+nodes = [n for n in observation['nodes'] if n.get('key') == 'submit']
+assert len(nodes) == 1
+result = ctx.call('flutter-executor', {
+    **ctx.inputs['identity'], 'operation': 'act',
+    'snapshotId': observation['snapshotId'], 'actionId': 'submit-once',
+    'action': {'type': 'tap', 'nodeId': nodes[0]['nodeId']}
+})
+assert result['ok'] and result['result']['ok'], str(result)
+```
+
+An action receipt means the framework call ended, not that a payment/order/business transaction succeeded. Observe again and assert the independent business result. Do not reuse stale snapshots or change an action's mechanism after a failure without a new decision.
+
+## Cancellation, recovery and lifecycle
+
+- One test thread / browser worker serializes UI effects. Native device effects use the shared device ownership contract. UI Automator and the legacy UIA runtime cannot own Android UiAutomation simultaneously; the Host drains and hands over the connection explicitly.
+- `timeoutMs` requests cancellation; it does not prove rollback. Already executing framework work must return its original receipt or the original process must be confirmed ended. An unsettled WebView atom ends the test session. No replacement action starts against an unresolved device effect.
+- The same `actionId` with identical arguments returns its original receipt. A changed request is rejected. An unresolved receipt is never redispatched. Deduplication is session-scoped; it is not universal exactly-once business execution across process loss or new sessions.
+- `receipt` remains readable after normal close. Host restart can recover Android/Flutter descriptors and read retained device records; a lost browser worker's original receipts remain readable, but its live browser session cannot be resumed.
+- Use explicit `close` for normal teardown. Android/Flutter tests also have an idle lease (default 10 minutes, selectable 10 seconds–1 hour). Host loss preserves original state for recovery; it does not erase unresolved ownership. Run `device-ownership --operation reconcile --serial DEVICE` when required by the error. A closed Flutter test may require reconciliation/close to end its original app process.
+- Each session permits at most 4096 action receipts, with bounded request/response and observation sizes. Receipts are retained for audit; storage is not automatically deleted across sessions. Operators must archive/remove closed session artifacts according to their retention policy. Never remove an unresolved session's records to bypass a device lock.
+
+## Performance evidence
+
+On the same API-36 device, sample APK, Activity, counter button and Instrumentation lifetime, 20 effective samples per path (two warmup rounds excluded) alternated Espresso touch and the existing SDK touch. Both included Host persistence and the same Espresso observations before/after every action. Every counter increment was verified.
+
+| Metric (ms) | Espresso | Existing SDK touch |
+| --- | ---: | ---: |
+| Median action | 362 | 314 |
+| Action p95 | 397 | 345 |
+| Median action + before/after observation | 413 | 359 |
+
+This does not establish a general speedup. Startup, dependency preparation, screenshots, model time and CLI process startup are excluded and must be reported separately. Semantics/setter input is a different operation from physical keyboard/IME input; its shorter duration cannot establish an equivalent-interaction speedup.
+
+The version's local verification and publication status are recorded in the repository delivery report. Local artifact checks are separate from public registry publication and real customer workflow acceptance.

package/docs/RELEASE.md

@@ -1,8 +1,27 @@
-# 0.3.5 发行与接入交接
+# 0.3.7 发行与接入交接
 
 本文件记录正式版的依赖关系和出仓库交付入口。封版要求是同一提交的源码、发行包与公开接入合同一致；单个样本的测试进度不改变包版本或发布状态。推送 Git、创建远端标签及发布 npm/pub 包由维护者执行。
 
-## 0.3.5 变更
+## 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 观察性能评估记录。
+
+- 可选 Android Instrumentation 会话，复用业务 androidTest；UI Automator、Espresso、Espresso-Web 和 Compose 可在同一会话内选择。
+- 可选 Flutter integration_test/WidgetTester 测试入口，以及 Host 管理的 Playwright 1.63.0 浏览器执行器。
+- 公开 capabilities + run、Python/JS Script 的 app.test 权限、观测身份、原始回执、取消和设备占用接线。
+- Compose 主包/测试包版本检查；按测试配置隔离依赖，不自动升级业务 AGP/Kotlin/Compose。
+- Android 7 权限输出的零 flags 省略及空格分隔格式支持，来源为实际 API-25 环境和 AOSP Settings 输出实现。
+- 本地交付和外部发布分开记录；这份源码不表示 npm/JitPack/pub.dev 已发布 0.3.7。
+
+接入合同、具体依赖和实测性能见 [OPTIONAL_EXECUTORS.md](OPTIONAL_EXECUTORS.md)。
+
+## 随本版包含的 0.3.5 修复
 
 - 修正 UIA nodeRef 原回执对账，正常重启和死进程后的显式启动可完成原 session 审计；未知回执和失效引用仍受保护。
 - UIA node runtime 支持 Android API 25+，保留 POSIX 原子重命名、fsync、进程锁与原始 Binder 回调；不使用 dump 或坐标回退。Android 7 权限观察支持未初始化的权限状态以及旧 ActivityManager 的身份字段。
@@ -20,16 +39,20 @@
 - CLI `--version`、录制目录、错误字段、Script 起步权限及 Reader UIA 只读重试修正；明确 freeze 与 MCP 重连语义。
 - Android Gradle 无实现的历史开关发出弃用提示，旧 DSL 仍可构建；各端统一版本。
 
+## 新增可选分发物
+
+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.7，通过 androidTestImplementation 消费。Gradle 插件增加 `io.github.mobileaidev.aiappbridge.test` 依赖校验入口。新 Flutter 包 `ai_app_bridge_test` 使用 0.3.7，只作为 dev_dependency；它的发布不依赖 Android SDK 的 JitPack 坐标。
+
 ## 版本与消费方式
 
 | 交付物 | 发行版本 | 独立消费入口 | 发布依赖 |
 | --- | --- | --- | --- |
-| Android SDK | `0.3.5` | JitPack `com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-android:0.3.5` | 同名 Git tag，JitPack 对该提交成功构建 |
-| Android Gradle 插件 | `0.3.5` | JitPack `ai-app-bridge-gradle-plugin` 模块及插件 ID `io.github.mobileaidev.aiappbridge.android` | 与 SDK 相同的 Git tag；不再使用旧默认 `0.2.8` |
-| 原生 iOS SDK | Git tag `0.3.5` | Git URL 的仓库根 `Package.swift`，产品 `AiAppBridgeIOS` | 根清单包含 Swift runtime、C adapter 和 segmented C store，无外部 C 包路径 |
-| Flutter 插件 | `0.3.5` | pub `ai_app_bridge_flutter` | Android 固定依赖上述 SDK；iOS Swift/C 源码随插件分发 |
-| Desktop CLI/MCP | `0.3.5` | npm `@mobileaidev/ai-app-bridge` | 包含 UIA bundle、WDA 模板和 native store 源码；WDA 上游固定 `14.1.1` |
-| Web SDK | `0.3.5` | npm `@mobileaidev/ai-app-bridge-web` | 独立浏览器源码包，无 npm 对 CLI 的安装依赖 |
+| Android SDK | `0.3.7` | JitPack `com.github.mobileAiDev.ai-app-bridge:ai-app-bridge-android:0.3.7` | 同名 Git tag，JitPack 对该提交成功构建 |
+| Android Gradle 插件 | `0.3.7` | JitPack `ai-app-bridge-gradle-plugin` 模块及插件 ID `io.github.mobileaidev.aiappbridge.android` | 与 SDK 相同的 Git tag；不再使用旧默认 `0.2.8` |
+| 原生 iOS SDK | Git tag `0.3.7` | Git URL 的仓库根 `Package.swift`，产品 `AiAppBridgeIOS` | 根清单包含 Swift runtime、C adapter 和 segmented C store，无外部 C 包路径 |
+| Flutter 插件 | `0.3.7` | pub `ai_app_bridge_flutter` | Android 固定依赖上述 SDK；iOS Swift/C 源码随插件分发 |
+| Desktop CLI/MCP | `0.3.7` | npm `@mobileaidev/ai-app-bridge` | 包含 UIA bundle、WDA 模板和 native store 源码；WDA 上游固定 `14.1.1` |
+| Web SDK | `0.3.7` | 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 打包进插件。
@@ -38,11 +61,11 @@ Host 支持范围声明为 Node `>=26.3.0 <27`，本轮实际验证基线是 **2
 
 ## 发布顺序
 
-1. 完成源码审阅并冻结一个提交，核对以下命令的产物确实来自它；包含当前 untracked 的实际源码、测试和文档，排除本机生成目录。所有对外发行版本使用同一个 `0.3.5`，若需要改版本，先同时更新上表涉及的 manifest 与固定依赖。
-2. 维护者推送提交与 `0.3.5` 标签，让 JitPack 构建 Android SDK/插件。确认两条公开坐标可解析后，再发布依赖它们的 Flutter 包。本地 Gradle project/path/AAR 替换不能证明 JitPack 坐标可消费。
+1. 完成源码审阅并冻结一个提交，核对以下命令的产物确实来自它；包含当前 untracked 的实际源码、测试和文档，排除本机生成目录。所有对外发行版本使用同一个 `0.3.7`，若需要改版本，先同时更新上表涉及的 manifest 与固定依赖。
+2. 维护者推送提交与 `0.3.7` 标签，让 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.5`，让已有候选入口也使用本次正式版。将 GitHub `main` 与发行提交同步，并创建非预发布的 GitHub Release。
+5. 同步 npm `next` 指向 `0.3.7`，让已有候选入口也使用本次正式版。将 GitHub `main` 与发行提交同步，并创建非预发布的 GitHub Release。
 6. 从 registry/tag 安装刚发布的确切版本，读取 `capabilities` 和版本，核对来源及支持范围，确认默认安装入口指向本次发行版本。正式发布不自动等于全平台生产验收完成。
 
 正式发布命令需在对应目录由维护者执行，例如 npm 使用 `npm publish --tag latest`；pub 使用 `flutter pub publish`。这些命令属于发布动作，不能混入本地验证脚本。
@@ -83,7 +106,7 @@ npm 升级不会替换已连接的 MCP 进程。用 `ai-app-bridge --version`
 已有工作结束后显式停止旧 Runtime，并在 Cursor 等客户端重连 MCP，核对 initialize
 中的 `serverInfo.version`。工具描述仍有旧 `batch`/`smoke` 时刷新客户端缓存。
 
-实际发布状态与验证边界见仓库 `docs/RELEASE_HANDOFF_0.3.5_2026-09-14.md`。
+实际发布状态与验证边界见仓库 `docs/RELEASE_HANDOFF_0.3.7_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.5",
+  "version": "0.3.7",
   "description": "Desktop CLI and MCP server for AI App Bridge across Android, iOS, Flutter, WebView, and Web targets.",
   "repository": {
     "type": "git",
@@ -26,6 +26,7 @@
     "bin/fact-recorder.js",
     "bin/fact-store.js",
     "bin/feedback-probe.js",
+    "bin/ui-observation.js",
     "bin/android-uia-xml.js",
     "bin/android-permissions.js",
     "bin/mmap-scan-index.js",
@@ -44,6 +45,8 @@
     "bin/script",
     "bin/intent",
     "bin/shared-kernel",
+    "bin/executors",
+    "runtime/executors",
     "runtime/uia",
     "bin/observation-collector.js",
     "bin/ios-provider.js",
@@ -63,6 +66,7 @@
     "!bin/script/p9-*.js",
     "!bin/intent/intent-device-adapter.js",
     "docs/COMMAND_CONTRACT.md",
+    "docs/OPTIONAL_EXECUTORS.md",
     "bin/ios-wda-port.js",
     "bin/ios-wda-project.js",
     "bin/ios-wda-execution.js",

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

@@ -0,0 +1,45 @@
+{
+  "name": "ai-app-bridge-playwright-runtime",
+  "version": "0.3.7",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "ai-app-bridge-playwright-runtime",
+      "version": "0.3.7",
+      "dependencies": {
+        "playwright": "1.63.0"
+      },
+      "engines": {
+        "node": ">=26.3.0 <27"
+      }
+    },
+    "node_modules/playwright": {
+      "version": "1.63.0",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.63.0.tgz",
+      "integrity": "sha512-+7ziBLidS4NaNCdt57SUDT+wYmmd5fmiQejUic/kb+YsYSCPyOOE9sebzMjNmQrsnNpDJqd4WHvV/8lfKfUDUg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.63.0"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.63.0",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.63.0.tgz",
+      "integrity": "sha512-rYCsBF/M5HjUch52bbtVONEFjv6Xu8sm8h72dNlR5bzIE1fvC/bxgspzkjSfU+MweEMmPM8KJebG6nnyxo5mCg==",
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    }
+  }
+}

package/runtime/executors/playwright/package.json

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