feat(runtime): add pilot runtime scroll and text replay

README.md

@@ -9,14 +9,13 @@ debugging context.
 
 It lets you describe a UI path in YAML, replay that Scenario against a running
 Flutter app, and collect the context needed to understand what happened:
-actions, screenshots, semantic Snapshots, logs, run reports, and timeline
+actions, screenshots, Widget Trees, logs, run reports, and timeline
 views. The goal is to make a UI bug report readable by humans, CI, and AI
 coding agents without relying on vague manual reproduction notes.
 
-Flutter Pilot builds above `mcp_flutter`, which provides the Flutter runtime
-bridge for interaction and inspection. Thanks to the `mcp_flutter` project for
-making Flutter UI state and runtime operations available through a toolable
-interface.
+Flutter Pilot currently drives debug Runtime Targets through `mcp_flutter`.
+The built-in `pilot_runtime` package is under active development as the next
+runtime bridge.
 
 ## What It Does
 
@@ -145,13 +144,13 @@ stdout for scripts.
 Validate a Scenario without connecting to a Flutter app:
 
 ```bash
-flutter_pilot validate examples/smoke_scenario.yaml
+flutter_pilot validate examples/smoke_app/smoke_scenario.yaml
 ```
 
 Run a Scenario by launching the current Target App Package:
 
 ```bash
-flutter_pilot test examples/smoke_scenario.yaml
+flutter_pilot test examples/smoke_app/smoke_scenario.yaml
 ```
 
 Run all Project Scenarios from the default Pilot Directory, `pilot/`:
@@ -169,7 +168,7 @@ flutter_pilot test pilot/regression
 Select the Target Device, Flutter flavor, or app entrypoint when needed:
 
 ```bash
-flutter_pilot test examples/smoke_scenario.yaml \
+flutter_pilot test examples/smoke_app/smoke_scenario.yaml \
   --device <device-id-or-name> \
   --flavor staging \
   --target lib/main_staging.dart
@@ -178,9 +177,9 @@ flutter_pilot test examples/smoke_scenario.yaml \
 Stop after a specific Step and print captured diagnostic context:
 
 ```bash
-flutter_pilot test examples/smoke_scenario.yaml \
+flutter_pilot test examples/smoke_app/smoke_scenario.yaml \
   --until wait_for_error \
-  --print snapshot
+  --print widget-tree
 ```
 
 Regenerate the HTML timeline from an existing run directory:
@@ -218,14 +217,14 @@ flutter_pilot test <scenario-directory>
 flutter_pilot test <scenario.yaml> --device <device-id-or-name>
 flutter_pilot test <scenario.yaml> --flavor <flavor> --target <entrypoint.dart>
 flutter_pilot test <scenario.yaml> --until <step-or-label>
-flutter_pilot test <scenario.yaml> --until <step-or-label> --print <snapshot|widget-tree|errors>
+flutter_pilot test <scenario.yaml> --until <step-or-label> --print <widget-tree|errors>
 flutter_pilot report <run-directory>
 flutter_pilot diff <before-run> <after-run>
 flutter_pilot diff <before-run> <after-run> --json
 ```
 
 `--print` may be repeated. When several diagnostics are requested, Flutter Pilot
-prints them in a stable order: Snapshot, Widget Tree, then errors.
+prints them in a stable order: Widget Tree, then errors.
 
 With no Scenario file, `test` discovers Project Scenarios under `pilot/`. With
 a directory argument, it discovers Project Scenarios under that directory.
@@ -249,7 +248,6 @@ batch run directory under `.runs/` and child Scenario Run directories inside it.
 The artifact model is designed for both human review and machine consumption.
 
 - Screenshot: what a user saw on screen.
-- Snapshot: structured UI state for tools and AI agents.
 - Widget Tree: deeper Flutter hierarchy data when requested.
 - Logs: runtime and diagnostic output.
 - Device Video Recording: optional run-level video saved when
@@ -288,6 +286,5 @@ consistent.
 
 ## Scope
 
-Flutter Pilot focuses on reproducible Flutter UI debugging artifacts. It does
-not replace `mcp_flutter`, and it is not trying to become a broad visual
-regression platform in the first version.
+Flutter Pilot focuses on reproducible Flutter UI debugging artifacts. It is not
+trying to become a broad visual regression platform in the first version.

README_zh.md

@@ -9,12 +9,11 @@ Flutter UI 操作路径描述成可提交、可分享、可重复执行的 YAML
 调试所需的上下文整理成适合开发者、CI 和 AI 编码代理阅读的产物。
 
 > 项目状态：Flutter Pilot 仍在开发中。当前实现重点是 Dart CLI、Scenario
-> YAML 解析与校验、报告生成和命令外壳；通过 `mcp_flutter` 实际驱动 Flutter
-> UI 的执行能力还在建设中。
+> YAML 解析与校验、报告生成和命令外壳；通过 `mcp_flutter` 驱动 Flutter
+> UI。内置的 `pilot_runtime` 运行时桥接仍在建设中。
 
-Flutter Pilot 构建在 `mcp_flutter` 之上。`mcp_flutter` 负责提供 Flutter
-运行时交互和检查能力，Flutter Pilot 则在其上增加 Scenario DSL、调试产物收集、
-运行报告和后续 diff 能力。
+Flutter Pilot 当前通过 `mcp_flutter` 驱动 Flutter debug Runtime Target。
+内置的 `pilot_runtime` 包正在作为下一代运行时桥接开发。
 
 ## 它能做什么
 
@@ -30,7 +29,7 @@ Runtime Target 的连接信息不会写进 YAML。相同的 Scenario 可以被
 提交到仓库，并通过 CLI 参数在不同的 Runtime Target 上运行。
 
 一次运行会在 `.runs/` 下生成运行目录。这个目录的目标是独立可读：开发者可以
-查看截图和 HTML timeline，CI 可以归档产物，AI 代理可以读取结构化 Snapshot、
+查看截图和 HTML timeline，CI 可以归档产物，AI 代理可以读取结构化 Widget Tree、
 日志和 `run_report.json` 作为紧凑的调试上下文。
 
 ## 为什么需要它
@@ -135,13 +134,13 @@ stdout，方便脚本读取。
 不连接 Flutter 应用，只校验 Scenario：
 
 ```bash
-flutter_pilot validate examples/smoke_scenario.yaml
+flutter_pilot validate examples/smoke_app/smoke_scenario.yaml
 ```
 
 通过启动当前 Target App Package 运行 Scenario：
 
 ```bash
-flutter_pilot test examples/smoke_scenario.yaml
+flutter_pilot test examples/smoke_app/smoke_scenario.yaml
 ```
 
 运行默认 Pilot Directory（`pilot/`）下的全部 Project Scenarios：
@@ -159,7 +158,7 @@ flutter_pilot test pilot/regression
 需要时可以选择 Target Device、Flutter flavor 或应用入口文件：
 
 ```bash
-flutter_pilot test examples/smoke_scenario.yaml \
+flutter_pilot test examples/smoke_app/smoke_scenario.yaml \
   --device <device-id-or-name> \
   --flavor staging \
   --target lib/main_staging.dart
@@ -168,9 +167,9 @@ flutter_pilot test examples/smoke_scenario.yaml \
 运行到指定 Step 后停止，并打印捕获到的诊断上下文：
 
 ```bash
-flutter_pilot test examples/smoke_scenario.yaml \
+flutter_pilot test examples/smoke_app/smoke_scenario.yaml \
   --until wait_for_error \
-  --print snapshot
+  --print widget-tree
 ```
 
 基于已有运行目录重新生成 HTML timeline：
@@ -207,14 +206,14 @@ flutter_pilot test <scenario-directory>
 flutter_pilot test <scenario.yaml> --device <device-id-or-name>
 flutter_pilot test <scenario.yaml> --flavor <flavor> --target <entrypoint.dart>
 flutter_pilot test <scenario.yaml> --until <step-or-label>
-flutter_pilot test <scenario.yaml> --until <step-or-label> --print <snapshot|widget-tree|errors>
+flutter_pilot test <scenario.yaml> --until <step-or-label> --print <widget-tree|errors>
 flutter_pilot report <run-directory>
 flutter_pilot diff <before-run> <after-run>
 flutter_pilot diff <before-run> <after-run> --json
 ```
 
 `--print` 可以重复传入。请求多个诊断输出时，Flutter Pilot 会按稳定顺序打印：
-Snapshot、Widget Tree、errors。
+Widget Tree、errors。
 
 不传 Scenario 文件时，`test` 会从 `pilot/` 发现 Project Scenarios。传入目录时，
 它会从该目录发现 Project Scenarios。目录发现会递归扫描 `.yaml` 和 `.yml` 文件，
@@ -236,7 +235,6 @@ Scenario Run 会在 `.runs/` 下写入一个运行目录。Project Run 会在 `.
 人工审查和机器消费。
 
 - Screenshot：用户在屏幕上看到的画面。
-- Snapshot：供工具和 AI 代理消费的结构化 UI 状态。
 - Widget Tree：按需捕获的更深层 Flutter 层级数据。
 - Logs：运行时和诊断输出。
 - Device Video Recording：启用 `scenario.recording` 时保存的可选运行级视频，
@@ -268,5 +266,4 @@ dart test
 
 ## 范围
 
-Flutter Pilot 聚焦可复现的 Flutter UI 调试产物。它不会替代 `mcp_flutter`，
-第一版也不会扩展成通用的视觉回归平台。
+Flutter Pilot 聚焦可复现的 Flutter UI 调试产物。第一版不会扩展成通用的视觉回归平台。

docs-internal/adr/0001-use-dart-cli-with-yaml-scenario-dsl.md

@@ -1,3 +1,3 @@
 # Use Dart CLI with YAML Scenario DSL for Flutter Pilot
 
-Flutter Pilot will start as a Dart CLI package with a YAML Scenario DSL, rather than a Flutter app, an `integration_test` wrapper, or a standalone MCP server. A CLI gives humans, CI, and AI agents a stable command surface for validating scenarios, replaying UI paths, and collecting artifacts, while the YAML Scenario format keeps reproductions portable across machines and Runtime Targets. This keeps Flutter Pilot focused on reproducible debugging artifacts above `mcp_flutter`, instead of coupling the first version to a specific UI shell or Flutter test harness.
+Flutter Pilot will start as a Dart CLI package with a YAML Scenario DSL, rather than a Flutter app, an `integration_test` wrapper, or a standalone MCP server. A CLI gives humans, CI, and AI agents a stable command surface for validating scenarios, replaying UI paths, and collecting artifacts, while the YAML Scenario format keeps reproductions portable across machines and Runtime Targets. This keeps Flutter Pilot focused on reproducible debugging artifacts through `pilot_runtime`, instead of coupling the first version to a specific UI shell or Flutter test harness.