@bdayadev/flutter-ultra-mcp 1.5.8 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (17) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/dart/ultra_flutter/CHANGELOG.md +3 -30
  4. package/dart/ultra_flutter/LICENSE +201 -0
  5. package/dart/ultra_flutter/README.md +28 -79
  6. package/dart/ultra_flutter_devtools/CHANGELOG.md +7 -0
  7. package/dart/ultra_flutter_devtools/LICENSE +201 -0
  8. package/dart/ultra_flutter_devtools/README.md +24 -3
  9. package/package.json +1 -1
  10. package/skills/bisect/SKILL.md +91 -121
  11. package/skills/debug/SKILL.md +98 -99
  12. package/skills/devtools/SKILL.md +93 -91
  13. package/skills/drive/SKILL.md +90 -98
  14. package/skills/scaffold/SKILL.md +132 -126
  15. package/skills/setup/SKILL.md +89 -92
  16. package/skills/test/SKILL.md +112 -104
  17. package/skills/tour/SKILL.md +94 -82
package/skills/test/SKILL.md CHANGED
@@ -1,125 +1,115 @@
1
1
  ---
2
2
  name: flutter-test
3
- description: Orchestrating Flutter unit, widget, and patrol E2E tests with focused reporting. Use when the user asks to run tests, validate a fix, or check coverage on a Flutter project.
3
+ description: Orchestrates Flutter unit, widget, golden, and patrol E2E tests with focused reporting. Use when the user asks to run tests, validate a fix, check coverage, update golden screenshots, discover available tests, or triage a failing CI test suite locally.
4
4
  ---
5
5
 
6
- # flutter-test — Test Orchestration
6
+ # Test Orchestration
7
7
 
8
- ## When to use
8
+ Covers all Flutter test layers: unit, widget, golden, and patrol E2E. For ad-hoc interactive flow verification without a written test, use `flutter-drive` instead.
9
9
 
10
- Use this skill when the user asks to run tests, validate that a fix works, check coverage, or triage a failing CI test suite locally. This skill covers all three Flutter test layers: unit, widget, and patrol E2E. For ad-hoc interactive flow verification without a written test, use `flutter-drive` instead.
10
+ ## Workflow
11
11
 
12
- ## Prerequisites
12
+ ### 1. Identify project and scope
13
13
 
14
- - A Flutter project is available and identifiable (pubspec.yaml present).
15
- - For patrol E2E: the app must be buildable for the target device/web. A connected device or emulator is required for mobile E2E.
16
- - For coverage reports: `lcov` must be available on the host, or the skill produces the raw `lcov.info` path for the user.
14
+ - `mcp__plugin_flutter_flutter-ultra-build__list_projects` to find available projects.
15
+ - `mcp__plugin_flutter_flutter-ultra-build__project_info` for the target project path, flavors, and entry points.
16
+ - `mcp__plugin_flutter_flutter-ultra-build__test_filter` to discover test files matching a name pattern before running.
17
+ - Determine scope from the user's request: unit only, widget only, patrol E2E only, golden only, full suite, or coverage.
17
18
 
18
- ## Workflow
19
+ ### 2. Static analysis (fail fast)
20
+
21
+ `mcp__plugin_flutter_flutter-ultra-build__analyze` on the project. If errors are returned, report them and stop.
19
22
 
20
- ### 1. Identify the project and test scope
23
+ ### 3. Unit and widget tests
21
24
 
22
- - Call `mcp__plugin_flutter_flutter-ultra-build__list_projects` to find available projects.
23
- - Call `mcp__plugin_flutter_flutter-ultra-build__project_info` for the target project to confirm the project path and available flavors.
24
- - Determine the test scope from the user's request:
25
- - **Unit/widget only** → sections 2–3
26
- - **Patrol E2E only** → section 4
27
- - **Full suite** → sections 2–4 in order
28
- - **Coverage** → section 2 with coverage flag, then section 5
25
+ **Start:**
29
26
 
30
- ### 2. Static analysis first (fail fast)
27
+ - `mcp__plugin_flutter_flutter-ultra-build__start_run_unit_tests` with optional `testNamePattern` to scope.
28
+ - `mcp__plugin_flutter_flutter-ultra-build__start_run_widget_tests` similarly.
29
+ - Pass `coverage: true` when coverage is requested.
31
30
 
32
- Before running any tests, call `mcp__plugin_flutter_flutter-ultra-build__analyze` on the project.
31
+ **Poll:**
33
32
 
34
- - If analysis returns errors (not warnings): report them and stop — tests will fail to compile anyway.
35
- - If analysis returns only warnings: continue but include the warning count in the final report.
33
+ - `mcp__plugin_flutter_flutter-ultra-build__poll_run_unit_tests` (or `poll_run_widget_tests`) until status is `completed` or `failed`.
36
34
 
37
- ### 3. Unit and widget tests
35
+ **Results:**
36
+
37
+ - `mcp__plugin_flutter_flutter-ultra-build__get_run_unit_tests_result` (or `get_run_widget_tests_result`).
38
+ - Parse: total, passed, failed, skipped, duration, and per-failure details.
38
39
 
39
- **Start the test run:**
40
+ **Cancel:** `mcp__plugin_flutter_flutter-ultra-build__cancel_run_unit_tests` (or `cancel_run_widget_tests`) if interrupted.
40
41
 
41
- - Unit tests: `mcp__plugin_flutter_flutter-ultra-build__start_run_unit_tests`
42
- - Pass `testNamePattern` to scope to a specific test file or test name regex (e.g. `invoice_bloc_test`, `.*BlocTest.*`).
43
- - Pass `coverage: true` when the user requests coverage.
44
- - Widget tests: `mcp__plugin_flutter_flutter-ultra-build__start_run_widget_tests`
45
- - Same pattern filtering applies.
42
+ ### 4. Golden tests
46
43
 
47
- **Poll until complete:**
44
+ **Validate existing goldens:**
48
45
 
49
- - Call `mcp__plugin_flutter_flutter-ultra-build__poll_run_unit_tests` (or `poll_run_widget_tests`) in a loop until status is `completed` or `failed`.
50
- - Poll interval: respect the tool's natural response time; do not sleep artificially.
46
+ - `mcp__plugin_flutter_flutter-ultra-build__start_run_golden_tests` -> `mcp__plugin_flutter_flutter-ultra-build__poll_run_golden_tests` -> `mcp__plugin_flutter_flutter-ultra-build__get_run_golden_tests_result`.
47
+ - Failures indicate visual regressions — the `.png` diff files show what changed.
51
48
 
52
- **Get results:**
49
+ **Update goldens after intentional UI changes:**
53
50
 
54
- - Call `mcp__plugin_flutter_flutter-ultra-build__get_run_unit_tests_result` (or `get_run_widget_tests_result`).
55
- - Parse: total tests, passed, failed, skipped, duration.
56
- - For each failure: extract test name, file path, line number, and failure message.
51
+ - `mcp__plugin_flutter_flutter-ultra-build__start_update_goldens` -> `mcp__plugin_flutter_flutter-ultra-build__poll_update_goldens` -> `mcp__plugin_flutter_flutter-ultra-build__get_update_goldens_result`.
52
+ - After updating, the changed `.png` files in `test/goldens/` must be committed.
57
53
 
58
- **Cancellation:** if the user interrupts, call `mcp__plugin_flutter_flutter-ultra-build__cancel_run_unit_tests` (or `cancel_run_widget_tests`).
54
+ **Cancel:** `mcp__plugin_flutter_flutter-ultra-build__cancel_run_golden_tests` or `mcp__plugin_flutter_flutter-ultra-build__cancel_update_goldens`.
59
55
 
60
- ### 4. Patrol E2E tests
56
+ ### 5. Patrol E2E tests
61
57
 
62
- **Discover available tests:**
58
+ **Discover tests:**
63
59
 
64
- - Call `mcp__plugin_flutter_flutter-ultra-patrol__list_tests` to enumerate test files and individual test names in `integration_test/`.
60
+ - `mcp__plugin_flutter_flutter-ultra-patrol__list_tests` to enumerate integration test files and individual test names.
65
61
 
66
62
  **Start a patrol run:**
67
63
 
68
- - Call `mcp__plugin_flutter_flutter-ultra-patrol__start_patrol_test` with:
69
- - `testFilePath` or `testName` to scope the run.
70
- - `device` for the target (web, emulator ID, or physical device ID from `mcp__plugin_flutter_flutter-ultra-runtime__list_devices`).
71
- - `flavor` if the project uses flavors.
64
+ - `mcp__plugin_flutter_flutter-ultra-patrol__start_patrol_test` with `testFilePath`, `device`, and optional `flavor`.
65
+ - For develop/hot-reload mode: `mcp__plugin_flutter_flutter-ultra-patrol__start_patrol_develop` to start the test runner in watch mode.
66
+ - `mcp__plugin_flutter_flutter-ultra-patrol__patrol_develop_run` to re-run a test.
67
+ - `mcp__plugin_flutter_flutter-ultra-patrol__patrol_hot_reload` to reload after code changes.
72
68
 
73
- **Poll until complete:**
69
+ **Poll:** `mcp__plugin_flutter_flutter-ultra-patrol__poll_patrol_job` until done.
74
70
 
75
- - Call `mcp__plugin_flutter_flutter-ultra-patrol__poll_patrol_job` in a loop until done.
76
- - While polling, optionally call `mcp__plugin_flutter_flutter-ultra-patrol__take_patrol_screenshot` at key intervals to capture mid-test state.
71
+ **Screenshots during run:** `mcp__plugin_flutter_flutter-ultra-patrol__take_patrol_screenshot` at key intervals.
77
72
 
78
- **Get enriched results:**
73
+ **Video recording:**
79
74
 
80
- - Call `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_result`.
81
- - The result includes:
82
- - Pass/fail per test step
83
- - `logContext`: log lines captured around the failure point
84
- - Screenshot paths captured during the test
85
- - Browser console errors (for web): call `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_browser_errors` for additional detail.
75
+ - `mcp__plugin_flutter_flutter-ultra-patrol__start_patrol_recording` before the test.
76
+ - `mcp__plugin_flutter_flutter-ultra-patrol__stop_patrol_recording` after.
77
+ - `mcp__plugin_flutter_flutter-ultra-patrol__extract_video_frame` to pull a specific frame for analysis.
86
78
 
87
- **For web E2E failures**: also call `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_web_debugger_port` to get the Chrome DevTools port, then use `mcp__plugin_flutter_flutter-ultra-browser__connect_over_cdp` for deeper inspection.
79
+ **Results:**
88
80
 
89
- **Cancellation:** call `mcp__plugin_flutter_flutter-ultra-patrol__cancel_patrol_job` if interrupted.
81
+ - `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_result` — includes pass/fail per step, log context, screenshot paths.
82
+ - `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_browser_errors` for web E2E browser console errors.
90
83
 
91
- ### 5. Coverage report (when requested)
84
+ **Web debugging:** `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_web_debugger_port` to get the Chrome DevTools port, then `mcp__plugin_flutter_flutter-ultra-browser__connect_over_cdp` for deeper inspection.
92
85
 
93
- After unit tests complete with `coverage: true`:
86
+ **Cancel:** `mcp__plugin_flutter_flutter-ultra-patrol__cancel_patrol_job`.
94
87
 
95
- - The build server writes `coverage/lcov.info` relative to the project root.
96
- - Call `mcp__plugin_flutter_flutter-ultra-build__get_run_unit_tests_result` — the result includes the coverage file path.
97
- - Report the top-level line coverage percentage if parseable.
98
- - If the user wants an HTML report: note that they can run `genhtml coverage/lcov.info -o coverage/html` locally.
99
- - Do not attempt to parse `lcov.info` manually — report the file path and overall percentage only.
88
+ ### 6. Integration tests (non-patrol)
100
89
 
101
- ### 6. Golden test handling
90
+ - `mcp__plugin_flutter_flutter-ultra-build__start_run_integration_tests` to start the run.
91
+ - Poll and get results using the same pattern as unit/widget tests.
92
+ - Cancel with the corresponding cancel tool if interrupted.
102
93
 
103
- When the user asks to update or validate golden screenshots:
94
+ ### 7. Coverage report
104
95
 
105
- - **Validate**: `mcp__plugin_flutter_flutter-ultra-build__start_run_golden_tests` → `poll_run_golden_tests` → `get_run_golden_tests_result`.
106
- - **Update**: `mcp__plugin_flutter_flutter-ultra-build__start_update_goldens` → `poll_update_goldens` → `get_update_goldens_result`.
107
- - After updating, note that the changed `.png` files in `test/goldens/` must be committed.
96
+ After unit tests with `coverage: true`:
108
97
 
109
- ## Failure triage
98
+ - `mcp__plugin_flutter_flutter-ultra-build__get_run_unit_tests_result` includes the coverage file path (`coverage/lcov.info`).
99
+ - Report the top-level line coverage percentage.
100
+ - For HTML report: `genhtml coverage/lcov.info -o coverage/html`.
110
101
 
111
- When tests fail, apply this triage sequence:
102
+ ## Failure triage
112
103
 
113
- 1. **Compilation errors** (test file won't load): surface the exact error from the result — usually a missing import or type mismatch. Fix the test file if asked.
114
- 2. **Assertion failures** (expected ≠ actual): show the test name, expected value, actual value, and file:line. Do not auto-fix unless asked.
115
- 3. **Timeout failures**: check if the test awaits a Future that never resolves. Suggest checking if `pumpAndSettle` is waiting on an infinite animation.
116
- 4. **Patrol E2E failures**: read `logContext` from `get_patrol_result` — it contains the log lines immediately before the failure. Cross-reference with `get_patrol_browser_errors` for web.
117
- 5. **Screenshot on failure**: patrol captures screenshots automatically on failure; report the path. For unit/widget failures, call `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` if the app is running in debug mode.
104
+ 1. **Compilation errors**: surface the exact error from the result. Usually a missing import or type mismatch.
105
+ 2. **Assertion failures**: show test name, expected/actual values, file:line.
106
+ 3. **Timeout failures**: check for `pumpAndSettle` waiting on an infinite animation.
107
+ 4. **Patrol E2E failures**: read `logContext` from `get_patrol_result`. Cross-reference with `get_patrol_browser_errors` for web.
108
+ 5. **Screenshot on failure**: patrol captures screenshots automatically. For unit/widget failures, call `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` if the app is running.
109
+ 6. **Network issues during E2E**: use `mcp__plugin_flutter_flutter-ultra-runtime__start_http_capture` + `mcp__plugin_flutter_flutter-ultra-runtime__get_http_events` to check API calls.
118
110
 
119
111
  ## Output format
120
112
 
121
- After all test layers complete, produce a structured summary:
122
-
123
113
  ```
124
114
  ## Test Results
125
115
 
@@ -130,41 +120,59 @@ After all test layers complete, produce a structured summary:
130
120
  | E2E | 5 | 4 | 1 | 0 | 47s |
131
121
 
132
122
  ### Failures
133
-
134
- **Unit: invoice_bloc_test.dart:87** — `InvoiceListBloc`
135
- Expected: `InvoiceListLoaded` with 3 items
136
- Got: `InvoiceListLoaded` with 0 items
137
-
138
- **E2E: login_flow_test.dart — "should redirect to dashboard after login"**
139
- Log context: [ERROR] ZitadelException: invalid_client at 14:23:01.332
140
- Screenshot: .omc/research/patrol-2026-05-19/login_flow_failure.png
123
+ **Unit: invoice_bloc_test.dart:87**
124
+ Expected: InvoiceListLoaded with 3 items
125
+ Got: InvoiceListLoaded with 0 items
141
126
  ```
142
127
 
143
- Include the coverage percentage at the bottom if coverage was requested.
128
+ ## Tool reference
129
+
130
+ | Action | Tool |
131
+ |--------|------|
132
+ | List projects | `mcp__plugin_flutter_flutter-ultra-build__list_projects` |
133
+ | Project info | `mcp__plugin_flutter_flutter-ultra-build__project_info` |
134
+ | Discover tests | `mcp__plugin_flutter_flutter-ultra-build__test_filter` |
135
+ | Static analysis | `mcp__plugin_flutter_flutter-ultra-build__analyze` |
136
+ | Start unit tests | `mcp__plugin_flutter_flutter-ultra-build__start_run_unit_tests` |
137
+ | Poll unit tests | `mcp__plugin_flutter_flutter-ultra-build__poll_run_unit_tests` |
138
+ | Get unit results | `mcp__plugin_flutter_flutter-ultra-build__get_run_unit_tests_result` |
139
+ | Start widget tests | `mcp__plugin_flutter_flutter-ultra-build__start_run_widget_tests` |
140
+ | Start golden tests | `mcp__plugin_flutter_flutter-ultra-build__start_run_golden_tests` |
141
+ | Update goldens | `mcp__plugin_flutter_flutter-ultra-build__start_update_goldens` |
142
+ | List patrol tests | `mcp__plugin_flutter_flutter-ultra-patrol__list_tests` |
143
+ | Start patrol test | `mcp__plugin_flutter_flutter-ultra-patrol__start_patrol_test` |
144
+ | Poll patrol | `mcp__plugin_flutter_flutter-ultra-patrol__poll_patrol_job` |
145
+ | Get patrol result | `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_result` |
146
+ | Patrol screenshot | `mcp__plugin_flutter_flutter-ultra-patrol__take_patrol_screenshot` |
147
+ | Patrol recording | `mcp__plugin_flutter_flutter-ultra-patrol__start_patrol_recording` |
148
+ | Extract frame | `mcp__plugin_flutter_flutter-ultra-patrol__extract_video_frame` |
149
+ | Browser errors | `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_browser_errors` |
150
+ | Web debugger port | `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_web_debugger_port` |
151
+ | Connect CDP | `mcp__plugin_flutter_flutter-ultra-browser__connect_over_cdp` |
152
+ | HTTP capture | `mcp__plugin_flutter_flutter-ultra-runtime__start_http_capture` |
153
+ | VM screenshot | `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` |
144
154
 
145
155
  ## Example
146
156
 
147
157
  ```
148
- User: "Run the full test suite for the Invora Flutter app and show me what's failing."
149
-
150
- 1. list_projects → project: clients/invora/invora-flutter
151
- 2. analyze → 0 errors, 3 warnings (continue)
152
- 3. start_run_unit_tests(project: "invora-flutter") → jobId: "unit-001"
153
- 4. poll_run_unit_tests(jobId: "unit-001") → completed
154
- 5. get_run_unit_tests_result → 42 total, 1 failed: invoice_bloc_test.dart:87
155
- 6. start_run_widget_tests(project: "invora-flutter") → jobId: "widget-001"
156
- 7. poll_run_widget_tests → completed, 18/18 passed
157
- 8. list_tests(project: "invora-flutter") → 5 patrol tests
158
- 9. start_patrol_test(testFilePath: "integration_test/", device: "web") → jobId: "patrol-001"
159
- 10. poll_patrol_job → completed, 1 failed: login_flow_test.dart
160
- 11. get_patrol_result → logContext: "ZitadelException: invalid_client", screenshot path
161
- 12. get_patrol_browser_errors → CORS error on /oauth/v2/token
162
- → Report table + failure details
158
+ User: "Run the full test suite and show me what's failing."
159
+
160
+ 1. list_projects -> project: "my-app"
161
+ 2. analyze -> 0 errors, 3 warnings
162
+ 3. start_run_unit_tests -> jobId: "unit-001"
163
+ 4. poll_run_unit_tests -> completed
164
+ 5. get_run_unit_tests_result -> 42 total, 1 failed
165
+ 6. start_run_widget_tests -> 18/18 passed
166
+ 7. list_tests -> 5 patrol tests
167
+ 8. start_patrol_test(device: "web") -> jobId: "patrol-001"
168
+ 9. poll_patrol_job -> completed, 1 failed
169
+ 10. get_patrol_result -> logContext: "ZitadelException: invalid_client"
170
+ 11. get_patrol_browser_errors -> CORS error on /oauth/v2/token
171
+ -> Report table + failure details
163
172
  ```
164
173
 
165
174
  ## See also
166
175
 
167
- - Sibling skill: `flutter-drive` for ad-hoc interactive flow automation without a written test
168
- - Sibling skill: `flutter-debug` for live runtime triage after a test exposes a bug
169
- - `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_result` — enriched E2E failure context
170
- - `mcp__plugin_flutter_flutter-ultra-build__test_filter` — narrow test scope by name or file pattern
176
+ - `flutter-drive` — ad-hoc interactive flow automation without a written test
177
+ - `flutter-debug` — live runtime triage after a test exposes a bug
178
+ - `flutter-bisect` — git bisect to find which commit broke a passing test
package/skills/tour/SKILL.md CHANGED
@@ -1,101 +1,113 @@
1
1
  ---
2
2
  name: flutter-tour
3
- description: Running route-by-route screenshot tours of a Flutter app. Use when capturing visual state across many app routes, doing pre-release visual regression sweeps, or documenting a feature's UI for review.
3
+ description: Captures route-by-route screenshots of a running Flutter app for visual documentation and regression sweeps. Use when the user asks to visually document the app, capture all screens, do a pre-release visual sweep, create responsive screenshots at multiple breakpoints, or produce a screenshot inventory for design QA.
4
4
  ---
5
5
 
6
- # flutter-tour — Route Screenshot Tour
6
+ # Route Screenshot Tour
7
7
 
8
- ## When to use
8
+ ## Workflow
9
9
 
10
- Use this skill when the user asks to visually document the app, capture all screens for review, or perform a pre-release sweep of the UI. Also use it when producing a screenshot inventory for a design QA pass.
10
+ ### 1. Connect to the app
11
11
 
12
- ## Prerequisites
12
+ - `mcp__plugin_flutter_flutter-ultra-runtime__discover_sessions` to find active debug sessions.
13
+ - If none found, `mcp__plugin_flutter_flutter-ultra-runtime__launch_app` with the target project, device, and flavor.
14
+ - Poll with `mcp__plugin_flutter_flutter-ultra-runtime__poll_launch_app` until attached.
15
+ - `mcp__plugin_flutter_flutter-ultra-runtime__attach` with the returned URI.
16
+ - For web targets, also `mcp__plugin_flutter_flutter-ultra-browser__launch_browser` or `mcp__plugin_flutter_flutter-ultra-browser__connect_over_cdp` to get a browser context.
13
17
 
14
- - A Flutter app is already running in debug mode (or can be launched via `mcp__plugin_flutter_flutter-ultra-runtime__launch_app`).
15
- - For web tours: a browser context is available or can be created via `mcp__plugin_flutter_flutter-ultra-browser__launch_browser`.
16
- - The app uses GoRouter or Navigator 2.0 (route list can be discovered via `evaluate`).
18
+ ### 2. Discover routes
17
19
 
18
- ## Workflow
20
+ Call `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` to extract the route table:
21
+
22
+ ```dart
23
+ GoRouter.of(navigatorKey.currentContext!).configuration.routes.map((r) => r.path).toList()
24
+ ```
25
+
26
+ Fallback for Navigator 1.0: call `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree` and find `Navigator` routes in the tree.
27
+
28
+ If the user supplied a route list, use that directly.
29
+
30
+ ### 3. For each route
31
+
32
+ 1. Navigate: `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` with `context.go('/route')`.
33
+ 2. Wait for settle: call `mcp__plugin_flutter_flutter-ultra-gesture__wait_for` with a stable-frame check, or evaluate `SchedulerBinding.instance.endOfFrame`.
34
+ 3. Check for loading indicators: `mcp__plugin_flutter_flutter-ultra-runtime__widget_exists` with type `CircularProgressIndicator`. Wait and retry up to 5s.
35
+ 4. **Capture screenshots** (choose based on target):
36
+ - VM screenshot: `mcp__plugin_flutter_flutter-ultra-runtime__screenshot`
37
+ - Browser screenshot (web): `mcp__plugin_flutter_flutter-ultra-browser__screenshot`
38
+ - Device screenshot (mobile): `mcp__plugin_flutter_flutter-ultra-native-mobile__take_device_screenshot`
39
+ - Desktop screenshot: `mcp__plugin_flutter_flutter-ultra-native-desktop__desktop_screenshot`
40
+ 5. **Responsive captures** (when requested): `mcp__plugin_flutter_flutter-ultra-gesture__take_responsive_screenshots` to capture at phone/tablet/desktop breakpoints in one call.
41
+ 6. Record `{ route, file, timestamp }` for the report.
42
+
43
+ ### 4. Video tours (optional)
44
+
45
+ For animated transitions between routes:
19
46
 
20
- 1. **Attach to the running session**
21
- - Call `mcp__plugin_flutter_flutter-ultra-runtime__discover_sessions` to find active sessions.
22
- - If none, call `mcp__plugin_flutter_flutter-ultra-runtime__launch_app` with the target project/flavor.
23
- - Call `mcp__plugin_flutter_flutter-ultra-runtime__attach` with the chosen `sessionId`.
24
-
25
- 2. **Discover routes**
26
- - Call `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` with:
27
- ```dart
28
- import 'package:go_router/go_router.dart';
29
- final router = GoRouter.of(context);
30
- router.configuration.routes.map((r) => r.path).toList().toString()
31
- ```
32
- - If GoRouter is not used, call `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree` and look for `Navigator` or `MaterialApp` `routes` keys.
33
- - If the user supplied a route list explicitly, use that directly.
34
-
35
- 3. **For each route** (iterate in order):
36
- a. Navigate via evaluate:
37
-
38
- ```dart
39
- context.go('/your-route');
40
- ```
41
-
42
- Or for named routes: `context.goNamed('routeName')`.
43
- b. Wait for the UI to settle — call `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` with `SchedulerBinding.instance.endOfFrame` to await the next frame.
44
- c. Take a screenshot: `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` — save path as `.omc/research/tour-<YYYY-MM-DD>/<route-slug>.png` where `route-slug` replaces `/` with `-` and strips leading `-`.
45
- d. For **web targets**: also call `mcp__plugin_flutter_flutter-ultra-browser__screenshot` for a pixel-perfect browser-rendered capture alongside the VM-service capture.
46
- e. Record the mapping `{ route, file, timestamp, title }` for the report.
47
-
48
- 4. **Handle auth-gated routes**
49
- - If a route redirects to a login screen, detect it by checking the widget tree for a login form key or `LoginPage` widget type.
50
- - Perform login via `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` (inject credentials into state) or via gesture tools.
51
- - Retry the navigation after authentication.
52
-
53
- 5. **Compile the report**
54
- - Write `.omc/research/tour-<date>/tour-report.md` with a markdown table:
55
- ```markdown
56
- | Route | Screenshot | Notes |
57
- | ----- | ---------------------- | ----- |
58
- | /home | [home.png](./home.png) | |
59
- ```
60
- - List any routes that could not be captured and the reason (auth wall, crash, async timeout).
61
-
62
- ## Handling edge cases
63
-
64
- - **Auth-gated routes**: detect redirect to login by calling `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree` after navigation and checking top-level widget type. Authenticate first, then retry.
65
- - **Routes with async data**: after `context.go(...)`, await `SchedulerBinding.instance.endOfFrame` and optionally call `evaluate` to check if a loading indicator is still present (`find.byType(CircularProgressIndicator).evaluate().isNotEmpty`). Wait up to 5 seconds in 500 ms increments.
66
- - **Routes that cause errors**: catch exceptions from `evaluate`; log the error in the report and continue to the next route.
67
- - **Parameterized routes** (e.g. `/item/:id`): substitute a known test ID, e.g. `/item/1`. Ask the user for sample IDs if none are obvious from context.
68
- - **Bottom sheets / dialogs**: these are not routes in GoRouter. Capture them by triggering them via `evaluate` after navigating to the parent route, screenshot, then dismiss.
69
-
70
- ## Output format
71
-
72
- At the end of the tour, produce:
73
-
74
- 1. A summary message listing how many routes were captured successfully vs. skipped.
75
- 2. The path to `tour-report.md`.
76
- 3. Inline markdown image links for any screenshots already visible in context (first 3 max to avoid flooding).
47
+ - `mcp__plugin_flutter_flutter-ultra-gesture__start_screencast` before starting navigation.
48
+ - Navigate through all routes with short pauses.
49
+ - `mcp__plugin_flutter_flutter-ultra-gesture__stop_screencast` to finalize the recording.
50
+
51
+ ### 5. DevTools integration (optional)
52
+
53
+ Push live progress to a connected DevTools panel:
54
+
55
+ - `mcp__plugin_flutter_flutter-ultra-devtools__push_event` with `type: "screenshot"` and payload `{ route, path }` after each capture.
56
+
57
+ ### 6. Handle edge cases
58
+
59
+ - **Auth-gated routes**: after navigation, check for a login widget via `mcp__plugin_flutter_flutter-ultra-runtime__find_widget`. Authenticate via `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` or gesture tools, then retry.
60
+ - **Parameterized routes** (`/item/:id`): substitute a known test ID. Ask the user for sample IDs if none are obvious.
61
+ - **Routes that crash**: catch errors from `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors`, log in the report, continue to the next route.
62
+ - **Async data loading**: poll `mcp__plugin_flutter_flutter-ultra-runtime__widget_exists` for loading indicators; wait up to 5s in 500ms increments.
63
+ - **Bottom sheets / dialogs**: trigger via `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` on the parent route, screenshot, dismiss.
64
+ - **Platform rendering**: use `mcp__plugin_flutter_flutter-ultra-runtime__set_platform_override` to capture iOS-style UI on a non-iOS device.
65
+
66
+ ### 7. Compile the report
67
+
68
+ Write `tour-report.md` with a markdown table of all routes, screenshot paths, and notes. List skipped routes with reasons.
69
+
70
+ ## Tool reference
71
+
72
+ | Action | Tool |
73
+ |--------|------|
74
+ | Find sessions | `mcp__plugin_flutter_flutter-ultra-runtime__discover_sessions` |
75
+ | Launch app | `mcp__plugin_flutter_flutter-ultra-runtime__launch_app` |
76
+ | Attach | `mcp__plugin_flutter_flutter-ultra-runtime__attach` |
77
+ | Evaluate Dart | `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` |
78
+ | VM screenshot | `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` |
79
+ | Find widget | `mcp__plugin_flutter_flutter-ultra-runtime__find_widget` |
80
+ | Widget exists | `mcp__plugin_flutter_flutter-ultra-runtime__widget_exists` |
81
+ | Platform override | `mcp__plugin_flutter_flutter-ultra-runtime__set_platform_override` |
82
+ | Runtime errors | `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors` |
83
+ | Wait for settle | `mcp__plugin_flutter_flutter-ultra-gesture__wait_for` |
84
+ | Responsive shots | `mcp__plugin_flutter_flutter-ultra-gesture__take_responsive_screenshots` |
85
+ | Screencast start | `mcp__plugin_flutter_flutter-ultra-gesture__start_screencast` |
86
+ | Screencast stop | `mcp__plugin_flutter_flutter-ultra-gesture__stop_screencast` |
87
+ | Browser screenshot | `mcp__plugin_flutter_flutter-ultra-browser__screenshot` |
88
+ | Browser launch | `mcp__plugin_flutter_flutter-ultra-browser__launch_browser` |
89
+ | Connect CDP | `mcp__plugin_flutter_flutter-ultra-browser__connect_over_cdp` |
90
+ | Device screenshot | `mcp__plugin_flutter_flutter-ultra-native-mobile__take_device_screenshot` |
91
+ | Desktop screenshot | `mcp__plugin_flutter_flutter-ultra-native-desktop__desktop_screenshot` |
92
+ | Push DevTools event | `mcp__plugin_flutter_flutter-ultra-devtools__push_event` |
77
93
 
78
94
  ## Example
79
95
 
80
96
  ```
81
- User: "Take a screenshot tour of the Invora app — all routes."
82
-
83
- 1. discover_sessions → sessionId: "flutter-1"
84
- 2. attach(sessionId: "flutter-1")
85
- 3. evaluate → routes: ["/", "/login", "/dashboard", "/invoices", "/invoices/:id", "/settings"]
86
- 4. For "/":
87
- - evaluate: context.go('/')
88
- - evaluate: await SchedulerBinding.instance.endOfFrame
89
- - screenshot → .omc/research/tour-2026-05-19/-home.png
90
- 5. For "/login":
97
+ User: "Take a screenshot tour of all routes."
98
+
99
+ 1. discover_sessions -> attach(sessionId: "flutter-1")
100
+ 2. evaluate -> routes: ["/", "/login", "/dashboard", "/invoices", "/settings"]
101
+ 3. For each route:
91
102
  - evaluate: context.go('/login')
92
- - screenshot → .omc/research/tour-2026-05-19/-login.png
93
- ... (repeat for each route)
94
- 6. Write tour-report.md with table of all routes + image links.
103
+ - wait_for -> settled
104
+ - screenshot -> tour/login.png
105
+ - take_responsive_screenshots -> tour/login-phone.png, tour/login-tablet.png
106
+ 4. Write tour-report.md
107
+ -> "5 routes captured, 0 skipped. Report at tour-report.md"
95
108
  ```
96
109
 
97
110
  ## See also
98
111
 
99
- - Sibling skill: `flutter-drive` for multi-step interaction flows
100
- - `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` — arbitrary Dart expression evaluation in app context
101
- - `mcp__plugin_flutter_flutter-ultra-browser__screenshot` — browser-level screenshot for web targets
112
+ - `flutter-drive` — interactive multi-step flows with assertions
113
+ - `flutter-debug` — triage runtime errors found during a tour