@bdayadev/flutter-ultra-mcp 1.12.0 → 1.14.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "flutter",
       "description": "Durable cross-platform Flutter automation via 8 specialized MCP servers, in-app mixin binding, and an optional DevTools panel. Replaces marionette_mcp and the official dart mcp-server for Claude Code.",
-      "version": "1.12.0",
+      "version": "1.14.0",
       "author": {
         "name": "Bdaya-Dev",
         "url": "https://github.com/Bdaya-Dev"
@@ -23,5 +23,5 @@
       "tags": ["flutter", "dart", "mcp", "testing", "automation", "patrol", "cross-platform"]
     }
   ],
-  "version": "1.12.0"
+  "version": "1.14.0"
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "flutter",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "Durable cross-platform Flutter automation via 8 specialized MCP servers, in-app mixin binding, and an optional DevTools panel. Replaces marionette_mcp and the official dart mcp-server for Claude Code.",
   "author": {
     "name": "Bdaya-Dev",

package/README.md

@@ -5,7 +5,7 @@
 [![CI](https://github.com/Bdaya-Dev/flutter-ultra-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Bdaya-Dev/flutter-ultra-mcp/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/Bdaya-Dev/flutter-ultra-mcp)](LICENSE)
 
-A Claude Code plugin that gives your AI agent full control over Flutter apps across all platforms. 8 isolated MCP servers, 248 tools, 2 Dart packages, and 12 built-in skills — installed with a single command.
+A Claude Code plugin that gives your AI agent full control over Flutter apps across all platforms. 8 isolated MCP servers, 295 tools, 2 Dart packages, and 31 built-in skills — installed with a single command.
 
 ## Why
 
@@ -44,17 +44,17 @@ Start a debug session (`flutter run -d chrome`), open Claude Code, and ask it to
 
 Each server runs as its own Node.js process. Crash isolation means a bug in one server cannot affect the others. Servers share session state through small JSON files on disk — if a server restarts, it picks up where it left off.
 
-| Server                         |   Tools | What it does                                                                                              |
-| ------------------------------ | ------: | --------------------------------------------------------------------------------------------------------- |
-| `flutter-ultra-build`          |      96 | Pub dependencies, code generation, analysis, formatting, tests, platform builds, l10n, assets, signing    |
-| `flutter-ultra-runtime`        |      55 | Attach to debug sessions, widget tree inspection, performance profiling, design audit, logs, HTTP capture |
-| `flutter-ultra-browser`        |      26 | Playwright-driven web automation — OAuth flows, popups, console, network, storage, JS evaluation          |
-| `flutter-ultra-native-mobile`  |      24 | Android (UIAutomator) + iOS (XCUITest) — permissions, OAuth tabs, accessibility tree, device recording    |
-| `flutter-ultra-gesture`        |      18 | Tap, swipe, scroll, text input, screenshots, screencast via the in-app `ultra_flutter` mixin              |
-| `flutter-ultra-patrol`         |      15 | Orchestrate `patrol_cli` for E2E tests across web, Android, and iOS — run, poll, record, screenshot       |
-| `flutter-ultra-native-desktop` |       9 | Windows (UIA), macOS (Accessibility), Linux (AT-SPI) — window listing, a11y tree, clicks, file dialogs    |
-| `flutter-ultra-devtools`       |       5 | Live MCP activity panel inside Flutter DevTools — sessions, tool calls, errors, screenshot grid           |
-| **Total**                      | **248** |                                                                                                           |
+| Server                         |   Tools | What it does                                                                                                             |
+| ------------------------------ | ------: | ------------------------------------------------------------------------------------------------------------------------ |
+| `flutter-ultra-build`          |      97 | Pub dependencies, code generation, analysis, formatting, tests, platform builds, l10n, assets, signing, project creation |
+| `flutter-ultra-runtime`        |      56 | Attach to debug sessions, widget tree, VM service method calls, performance profiling, design audit, logs, HTTP capture  |
+| `flutter-ultra-browser`        |      35 | Playwright web automation — network mocking, offline sim, OAuth, drag-drop, dialogs, tracing, console, storage           |
+| `flutter-ultra-native-mobile`  |      43 | Android + iOS — a11y tree, permissions, file picker, notifications, share sheet, CCT/SVC, GPS, deep links, app mgmt      |
+| `flutter-ultra-gesture`        |      19 | Tap, swipe, scroll, text input, multi-touch W3C Actions, screenshots, screencast via `ultra_flutter` mixin               |
+| `flutter-ultra-patrol`         |      31 | Orchestrate `patrol_cli` for E2E tests across web, Android, and iOS — run, poll, record, screenshot                      |
+| `flutter-ultra-native-desktop` |       9 | Windows (UIA), macOS (Accessibility), Linux (AT-SPI) — window listing, a11y tree, clicks, file dialogs, remote SSH       |
+| `flutter-ultra-devtools`       |       5 | Live MCP activity panel inside Flutter DevTools — sessions, tool calls, errors, screenshot grid                          |
+| **Total**                      | **295** |                                                                                                                          |
 
 See [docs/architecture.md](docs/architecture.md) for the full design.
 
@@ -62,6 +62,8 @@ See [docs/architecture.md](docs/architecture.md) for the full design.
 
 Skills teach Claude the correct tool call sequences for common workflows. Invoke them with `/flutter:<name>`.
 
+### Workflow skills (12)
+
 | Skill                    | Description                                                                                  |
 | ------------------------ | -------------------------------------------------------------------------------------------- |
 | `/flutter:setup`         | One-command setup of flutter-ultra in an existing codebase                                   |
@@ -77,6 +79,32 @@ Skills teach Claude the correct tool call sequences for common workflows. Invoke
 | `/flutter:record-demo`   | Record a video or GIF demo of an app flow (web browser or native device)                     |
 | `/flutter:devtools`      | Wire up and use the DevTools panel for live MCP activity inspection                          |
 
+### Teaching skills (19 — vendored from [flutter/skills](https://github.com/flutter/skills) + [dart-lang/skills](https://github.com/dart-lang/skills))
+
+Each teaching skill includes a **Flutter Ultra Integration** section mapping to the MCP tools that execute the workflow it teaches.
+
+| Skill                                        | Description                                                          |
+| -------------------------------------------- | -------------------------------------------------------------------- |
+| `/flutter:add-integration-test`              | Configure Flutter Driver and write integration tests                 |
+| `/flutter:add-widget-preview`                | Add `@Preview` annotations for real-time widget previewing           |
+| `/flutter:add-widget-test`                   | Write component-level tests with `WidgetTester`                      |
+| `/flutter:apply-architecture-best-practices` | Structure apps with MVVM + Repository layered architecture           |
+| `/flutter:build-responsive-layout`           | Build adaptive layouts with `LayoutBuilder` and `MediaQuery`         |
+| `/flutter:fix-layout-issues`                 | Diagnose and fix RenderFlex overflow and unbounded constraint errors |
+| `/flutter:implement-json-serialization`      | Manual JSON mapping with `fromJson`/`toJson`                         |
+| `/flutter:setup-declarative-routing`         | Configure `go_router` with deep linking and nested navigation        |
+| `/flutter:setup-localization`                | Set up `flutter_localizations` with ARB files                        |
+| `/flutter:use-http-package`                  | Execute HTTP requests with the `http` package                        |
+| `/flutter:add-unit-test`                     | Write unit tests with `package:test`                                 |
+| `/flutter:build-cli-app`                     | Build Dart CLI apps with argument parsing and compilation            |
+| `/flutter:collect-coverage`                  | Collect LCOV coverage reports                                        |
+| `/flutter:fix-runtime-errors`                | Resolve type system, null safety, and static analysis errors         |
+| `/flutter:generate-test-mocks`               | Generate mock objects with `package:mockito` + `build_runner`        |
+| `/flutter:migrate-to-checks-package`         | Migrate from `expect`/`matcher` to `package:checks`                  |
+| `/flutter:resolve-package-conflicts`         | Fix `pub get` version conflicts                                      |
+| `/flutter:run-static-analysis`               | Run `dart analyze` and `dart fix`                                    |
+| `/flutter:use-pattern-matching`              | Apply switch expressions and Dart 3 pattern matching                 |
+
 ## Installation
 
 ### Plugin (required)
@@ -85,7 +113,7 @@ Skills teach Claude the correct tool call sequences for common workflows. Invoke
 /plugin install Bdaya-Dev/flutter-ultra-mcp
 ```
 
-This registers all 8 MCP servers and 12 skills automatically. No manual configuration needed.
+This registers all 8 MCP servers and 31 skills automatically. No manual configuration needed.
 
 ### Dart package (required for gesture and screencast tools)
 

package/dart/ultra_flutter/pubspec.yaml

@@ -4,7 +4,7 @@ description: >-
   extensions (gesture, screenshot, inspector, screencast, log collection)
   for the flutter-ultra-mcp Claude Code plugin. Composable with Sentry and
   other WidgetsFlutterBinding subclasses via the mixin form.
-version: 1.12.0
+version: 1.14.0
 homepage: https://github.com/Bdaya-Dev/flutter-ultra-mcp
 repository: https://github.com/Bdaya-Dev/flutter-ultra-mcp
 issue_tracker: https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues

package/dart/ultra_flutter_devtools/pubspec.yaml

@@ -2,7 +2,7 @@ name: ultra_flutter_devtools
 description: >-
   Flutter DevTools extension showing live MCP activity for the flutter-ultra-mcp
   Claude Code plugin (sessions, recent tool calls, errors, screenshot grid).
-version: 1.12.0
+version: 1.14.0
 homepage: https://github.com/Bdaya-Dev/flutter-ultra-mcp
 repository: https://github.com/Bdaya-Dev/flutter-ultra-mcp
 issue_tracker: https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bdayadev/flutter-ultra-mcp",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "Flutter Ultra MCP plugin monorepo — 8 MCP servers + ultra_flutter Dart packages + skills for Claude Code.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp",

package/packages/flutter-ultra-native-desktop/package.json

@@ -65,9 +65,11 @@
   "dependencies": {
     "@flutter-ultra/mcp-runtime": "^0.0.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "ssh2": "^1.16.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@types/ssh2": "^1.15.0",
     "rimraf": "^6.0.0",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"

package/packages/flutter-ultra-native-mobile/package.json

@@ -56,9 +56,11 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "fast-xml-parser": "^4.5.0",
     "playwright-core": "^1.49.0",
+    "ssh2": "^1.16.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@types/ssh2": "^1.15.0",
     "rimraf": "^6.0.0",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"

package/skills/add-integration-test/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: add-integration-test
 description: Configures Flutter Driver for app interaction and converts MCP actions into permanent integration tests. Use when adding integration testing to a project, exploring UI components via MCP, or automating user flows with the integration_test package.
+  last_modified: Tue, 21 Apr 2026 18:29:20 GMT
 ---
 
 # Implementing Flutter Integration Tests
@@ -26,17 +27,17 @@ Configure the project to support integration testing and Flutter Driver extensio
 2. Enable the Flutter Driver extension in your application entry point (typically `lib/main.dart` or a dedicated `lib/main_test.dart`):
    - Import `package:flutter_driver/driver_extension.dart`.
    - Call `enableFlutterDriverExtension();` before `runApp()`.
-3. Add `Key` parameters (e.g., `ValueKey('login_button')`) to critical widgets for reliable targeting.
+3. Add `Key` parameters (e.g., `ValueKey('login_button')`) to critical widgets in the application code to ensure reliable targeting during tests.
 
 ## Interactive Exploration via MCP
 
-Use MCP tools to interactively explore and manipulate the application state before writing static tests.
+Use the Dart/Flutter MCP server tools to interactively explore and manipulate the application state before writing static tests.
 
 - **Launch**: Execute `launch_app` with `target: "lib/main_test.dart"` to start the application and acquire the DTD URI.
 - **Inspect**: Execute `get_widget_tree` to discover available `Key`s, `Text` nodes, and widget `Type`s.
 - **Interact**: Execute `tap`, `enter_text`, and `scroll` to simulate user flows.
 - **Wait**: Always execute `waitFor` or verify state with `get_health` when navigating or triggering animations.
-- **Troubleshoot Unmounted Widgets**: If a widget is not found, it may be lazily loaded. Execute `scroll` or `scrollIntoView` to force the widget to mount.
+- **Troubleshoot Unmounted Widgets**: If a widget is not found in the tree, it may be lazily loaded in a `SliverList` or `ListView`. Execute `scroll` or `scrollIntoView` to force the widget to mount before interacting with it.
 
 ## Test Authoring Guidelines
 
@@ -44,41 +45,54 @@ Structure integration tests using the `flutter_test` API paradigm.
 
 - Create a dedicated `integration_test/` directory at the project root.
 - Name all test files using the `<name>_test.dart` convention.
-- Initialize the binding: `IntegrationTestWidgetsFlutterBinding.ensureInitialized();`
-- Load the application UI: `await tester.pumpWidget(MyApp());`
-- Trigger frames: `await tester.pumpAndSettle();` after interactions.
-- Assert visibility: `expect(find.byKey(ValueKey('foo')), findsOneWidget);`
-- Scroll to off-screen widgets: `await tester.scrollUntilVisible(itemFinder, 500.0, scrollable: listFinder);`
+- Initialize the binding by calling `IntegrationTestWidgetsFlutterBinding.ensureInitialized();` at the start of `main()`.
+- Load the application UI using `await tester.pumpWidget(MyApp());`.
+- Trigger frames and wait for animations to complete using `await tester.pumpAndSettle();` after interactions like `tester.tap()`.
+- Assert widget visibility using `expect(find.byKey(ValueKey('foo')), findsOneWidget);` or `findsNothing`.
+- Scroll to specific off-screen widgets using `await tester.scrollUntilVisible(itemFinder, 500.0, scrollable: listFinder);`.
+
+**Conditional Logic for Legacy `flutter_driver`:**
+
+- If maintaining or migrating legacy `flutter_driver` tests, use `driver.waitFor()`, `driver.waitForAbsent()`, `driver.tap()`, and `driver.scroll()` instead of the `WidgetTester` APIs.
 
 ## Execution and Profiling
 
-Execute tests using the `flutter drive` command. Require a host driver script at `test_driver/integration_test.dart`.
+Execute tests using the `flutter drive` command. Require a host driver script located in `test_driver/integration_test.dart` that calls `integrationDriver()`.
 
-- **Chrome:** Launch `chromedriver --port=4444`, then: `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart -d chrome`
-- **Headless web:** Run with `-d web-server`.
-- **Android (Local):** `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart`
+**Conditional Execution Targets:**
+
+- **If testing on Chrome:** Launch `chromedriver --port=4444` in a separate terminal, then run:
+  `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart -d chrome`
+- **If testing headless web:** Run with `-d web-server`.
+- **If testing on Android (Local):** Run `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart`.
+- **If testing on Firebase Test Lab (Android):**
+  1. Build debug APK: `flutter build apk --debug`
+  2. Build test APK: `./gradlew app:assembleAndroidTest`
+  3. Upload both APKs to the Firebase Test Lab console.
 
 ## Workflow: End-to-End Integration Testing
 
-- [ ] **Setup**
+Copy and follow this checklist to implement and verify integration tests.
+
+- [ ] **Task Progress: Setup**
   - [ ] Add `integration_test` and `flutter_test` to `pubspec.yaml`.
   - [ ] Inject `enableFlutterDriverExtension()` into the app entry point.
   - [ ] Assign `ValueKey`s to target widgets.
-- [ ] **Exploration**
+- [ ] **Task Progress: Exploration**
   - [ ] Run `launch_app` via MCP.
   - [ ] Map the widget tree using `get_widget_tree`.
   - [ ] Validate interaction paths using MCP tools (`tap`, `enter_text`).
-- [ ] **Authoring**
+- [ ] **Task Progress: Authoring**
   - [ ] Create `integration_test/app_test.dart`.
   - [ ] Write test cases using `WidgetTester` APIs.
   - [ ] Create `test_driver/integration_test.dart` with `integrationDriver()`.
-- [ ] **Execution & Feedback Loop**
-  - [ ] Run `flutter drive`.
-  - [ ] Review output -> fix `PumpAndSettleTimedOutException` or missing widget issues -> re-run.
+- [ ] **Task Progress: Execution & Feedback Loop**
+  - [ ] Run `flutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart`.
+  - [ ] **Feedback Loop**: Review test output -> If `PumpAndSettleTimedOutException` occurs, check for infinite animations -> If widget not found, add `scrollUntilVisible` -> Re-run test until passing.
 
 ## Examples
 
-### Standard Integration Test
+### Standard Integration Test (`integration_test/app_test.dart`)
 
 ```dart
 import 'package:flutter/material.dart';
@@ -91,20 +105,29 @@ void main() {
 
   group('End-to-end test', () {
     testWidgets('tap on the floating action button, verify counter', (tester) async {
+      // Load app widget.
       await tester.pumpWidget(const MyApp());
+
+      // Verify the counter starts at 0.
       expect(find.text('0'), findsOneWidget);
 
+      // Find the floating action button to tap on.
       final fab = find.byKey(const ValueKey('increment'));
+
+      // Emulate a tap on the floating action button.
       await tester.tap(fab);
+
+      // Trigger a frame and wait for animations.
       await tester.pumpAndSettle();
 
+      // Verify the counter increments by 1.
       expect(find.text('1'), findsOneWidget);
     });
   });
 }
 ```
 
-### Host Driver Script
+### Host Driver Script (`test_driver/integration_test.dart`)
 
 ```dart
 import 'package:integration_test/integration_test_driver.dart';
@@ -112,6 +135,35 @@ import 'package:integration_test/integration_test_driver.dart';
 Future<void> main() => integrationDriver();
 ```
 
+### Performance Profiling Driver Script (`test_driver/perf_driver.dart`)
+
+Use this driver script if you wrap your test actions in `binding.traceAction()` to capture performance metrics.
+
+```dart
+import 'package:flutter_driver/flutter_driver.dart' as driver;
+import 'package:integration_test/integration_test_driver.dart';
+
+Future<void> main() {
+  return integrationDriver(
+    responseDataCallback: (data) async {
+      if (data != null) {
+        final timeline = driver.Timeline.fromJson(
+          data['scrolling_timeline'] as Map<String, dynamic>,
+        );
+
+        final summary = driver.TimelineSummary.summarize(timeline);
+
+        await summary.writeTimelineToFile(
+          'scrolling_timeline',
+          pretty: true,
+          includeSummary: true,
+        );
+      }
+    },
+  );
+}
+```
+
 ## Flutter Ultra Integration
 
 After writing the integration test, use these tools to launch the app and verify it:

package/skills/add-unit-test/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: add-unit-test
 description: Write and organize unit tests for functions, methods, and classes using `package:test`. Use when creating new logic or fixing bugs to ensure code remains correct and regression-free.
+  last_modified: Fri, 24 Apr 2026 15:07:58 GMT
 ---
 
 # Testing Dart and Flutter Applications

package/skills/add-widget-preview/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: add-widget-preview
 description: Adds interactive widget previews to the project using the previews.dart system. Use when creating new UI components or updating existing screens to ensure consistent design and interactive testing.
+  last_modified: Tue, 21 Apr 2026 20:05:23 GMT
 ---
 
 # Previewing Flutter Widgets
@@ -16,44 +17,56 @@ description: Adds interactive widget previews to the project using the previews.
 
 Use the Flutter Widget Previewer to render widgets in real-time, isolated from the full application context.
 
-- **Target Elements:** Apply the `@Preview` annotation to top-level functions, static methods, or public widget constructors/factories that have no required arguments and return a `Widget` or `WidgetBuilder`.
-- **Imports:** Always import `package:flutter/widget_previews.dart`.
-- **Custom Annotations:** Extend the `Preview` class to create custom annotations that inject common properties (themes, wrappers).
-- **Multiple Configurations:** Apply multiple `@Preview` annotations to generate multiple preview instances. Or extend `MultiPreview`.
-- **Runtime Transformations:** Override `transform()` in custom `Preview` or `MultiPreview` classes for dynamic modification.
+- **Target Elements:** Apply the `@Preview` annotation to top-level functions, static methods within a class, or public widget constructors/factories that have no required arguments and return a `Widget` or `WidgetBuilder`.
+- **Imports:** Always import `package:flutter/widget_previews.dart` to access the preview annotations.
+- **Custom Annotations:** Extend the `Preview` class to create custom annotations that inject common properties (e.g., themes, wrappers) across multiple widgets.
+- **Multiple Configurations:** Apply multiple `@Preview` annotations to a single target to generate multiple preview instances. Alternatively, extend `MultiPreview` to encapsulate common multi-preview configurations.
+- **Runtime Transformations:** Override the `transform()` method in custom `Preview` or `MultiPreview` classes to modify preview configurations dynamically at runtime (e.g., generating names based on dynamic values, which is impossible in a `const` context).
 
 ## Handling Limitations
 
-The Widget Previewer runs in a web environment:
+Adhere to the following constraints when authoring previewable widgets, as the Widget Previewer runs in a web environment:
 
-- **No Native APIs:** Do not use `dart:io` or `dart:ffi`. Use conditional imports to mock or bypass.
-- **Asset Paths:** Use package-based paths (e.g., `packages/my_package_name/assets/my_image.png`).
-- **Public Callbacks:** Ensure all callback arguments are public and constant.
-- **Constraints:** Apply explicit constraints using the `size` parameter if your widget is unconstrained.
+- **No Native APIs:** Do not use native plugins or APIs from `dart:io` or `dart:ffi`. Widgets with transitive dependencies on `dart:io` or `dart:ffi` will throw exceptions upon invocation. Use conditional imports to mock or bypass these in preview mode.
+- **Asset Paths:** Use package-based paths for assets loaded via `dart:ui` `fromAsset` APIs (e.g., `packages/my_package_name/assets/my_image.png` instead of `assets/my_image.png`).
+- **Public Callbacks:** Ensure all callback arguments provided to preview annotations are public and constant to satisfy code generation requirements.
+- **Constraints:** Apply explicit constraints using the `size` parameter in the `@Preview` annotation if your widget is unconstrained, as the previewer defaults to constraining them to approximately half the viewport.
 
 ## Workflows
 
 ### Creating a Widget Preview
 
+Copy and track this checklist when implementing a new widget preview:
+
 - [ ] Import `package:flutter/widget_previews.dart`.
-- [ ] Identify a valid target (top-level function, static method, or parameter-less constructor).
-- [ ] Apply the `@Preview` annotation.
-- [ ] Configure parameters (`name`, `group`, `size`, `theme`, `brightness`).
-- [ ] If applying same config to multiple widgets, extract into a custom class extending `Preview`.
+- [ ] Identify a valid target (top-level function, static method, or parameter-less public constructor).
+- [ ] Apply the `@Preview` annotation to the target.
+- [ ] Configure preview parameters (`name`, `group`, `size`, `theme`, `brightness`, etc.) as needed.
+- [ ] If applying the same configuration to multiple widgets, extract the configuration into a custom class extending `Preview`.
 
 ### Interacting with Previews
 
-**If using a supported IDE (Flutter 3.38+):**
+Follow the appropriate conditional workflow to launch and interact with the Widget Previewer:
+
+**If using a supported IDE (Android Studio, IntelliJ, VS Code with Flutter 3.38+):**
 
-1. Launch the IDE. Widget Previewer starts automatically.
-2. Open the "Flutter Widget Preview" tab.
-3. Toggle "Filter previews by selected file" if needed.
+1. Launch the IDE. The Widget Previewer starts automatically.
+2. Open the "Flutter Widget Preview" tab in the sidebar.
+3. Toggle "Filter previews by selected file" at the bottom left if you want to view previews outside the currently active file.
 
 **If using the Command Line:**
 
-1. Navigate to the project root.
+1. Navigate to the Flutter project's root directory.
 2. Run `flutter widget-preview start`.
-3. View in the Chrome environment.
+3. View the automatically opened Chrome environment.
+
+**Feedback Loop: Preview Iteration**
+
+1. Modify the widget code or preview configuration.
+2. Observe the automatic update in the Widget Previewer.
+3. If global state (e.g., static initializers) was modified: Click the global hot restart button at the bottom right.
+4. If only the local widget state needs resetting: Click the individual hot restart button on the specific preview card.
+5. Review errors in the IDE/CLI console -> fix -> repeat.
 
 ## Examples
 
@@ -69,21 +82,59 @@ Widget mySampleText() {
 }
 ```
 
+### Custom Preview with Runtime Transformation
+
+```dart
+import 'package:flutter/widget_previews.dart';
+import 'package:flutter/material.dart';
+
+final class TransformativePreview extends Preview {
+  const TransformativePreview({
+    super.name,
+    super.group,
+  });
+
+  PreviewThemeData _themeBuilder() {
+    return PreviewThemeData(
+      materialLight: ThemeData.light(),
+      materialDark: ThemeData.dark(),
+    );
+  }
+
+  @override
+  Preview transform() {
+    final originalPreview = super.transform();
+    final builder = originalPreview.toBuilder();
+
+    builder
+      ..name = 'Transformed - ${originalPreview.name}'
+      ..theme = _themeBuilder;
+
+    return builder.toPreview();
+  }
+}
+
+@TransformativePreview(name: 'Custom Themed Button')
+Widget myButton() => const ElevatedButton(onPressed: null, child: Text('Click'));
+```
+
 ### MultiPreview Implementation
 
 ```dart
 import 'package:flutter/widget_previews.dart';
 import 'package:flutter/material.dart';
 
+/// Creates light and dark mode previews automatically.
 final class MultiBrightnessPreview extends MultiPreview {
   const MultiBrightnessPreview({required this.name});
+
   final String name;
 
   @override
   List<Preview> get previews => const [
-    Preview(brightness: Brightness.light),
-    Preview(brightness: Brightness.dark),
-  ];
+        Preview(brightness: Brightness.light),
+        Preview(brightness: Brightness.dark),
+      ];
 
   @override
   List<Preview> transform() {
@@ -98,9 +149,7 @@ final class MultiBrightnessPreview extends MultiPreview {
 }
 
 @MultiBrightnessPreview(name: 'Primary Card')
-Widget cardPreview() => const Card(
-  child: Padding(padding: EdgeInsets.all(8.0), child: Text('Content')),
-);
+Widget cardPreview() => const Card(child: Padding(padding: EdgeInsets.all(8.0), child: Text('Content')));
 ```
 
 ## Flutter Ultra Integration

package/skills/add-widget-test/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: add-widget-test
 description: Implement a component-level test using `WidgetTester` to verify UI rendering and user interactions (tapping, scrolling, entering text). Use when validating that a specific widget displays correct data and responds to events as expected.
+  last_modified: Tue, 21 Apr 2026 21:15:41 GMT
 ---
 
 # Writing Flutter Widget Tests
@@ -15,41 +16,53 @@ description: Implement a component-level test using `WidgetTester` to verify UI
 
 ## Setup & Configuration
 
-1. Add `flutter_test` to `dev_dependencies` in `pubspec.yaml`.
-2. Place all test files in `test/` at the project root.
-3. Suffix all test file names with `_test.dart`.
+Ensure the testing environment is properly configured before authoring widget tests.
+
+1. Add the `flutter_test` dependency to the `dev_dependencies` section of `pubspec.yaml`.
+2. Place all test files in the `test/` directory at the root of the project.
+3. Suffix all test file names with `_test.dart` (e.g., `widget_test.dart`).
 
 ## Core Components
 
-- **`WidgetTester`**: Primary interface for building and interacting with widgets. Provided by `testWidgets()`.
-- **`Finder`**: Locates widgets (e.g., `find.text('Submit')`, `find.byType(TextField)`, `find.byKey(Key('submit_btn'))`).
-- **`Matcher`**: Verifies presence or state (e.g., `findsOneWidget`, `findsNothing`, `findsNWidgets(2)`).
+Utilize the following `flutter_test` components to interact with and validate the widget tree:
+
+- **`WidgetTester`**: The primary interface for building and interacting with widgets in the test environment. Provided automatically by the `testWidgets()` function.
+- **`Finder`**: Locates widgets in the test environment (e.g., `find.text('Submit')`, `find.byType(TextField)`, `find.byKey(Key('submit_btn'))`).
+- **`Matcher`**: Verifies the presence or state of widgets located by a `Finder` (e.g., `findsOneWidget`, `findsNothing`, `findsNWidgets(2)`, `matchesGoldenFile`).
 
 ## Workflow: Implementing a Widget Test
 
+Copy the following checklist to track progress when implementing a new widget test.
+
 ### Task Progress
 
-- [ ] **Step 1:** Define the test with `testWidgets('description', (WidgetTester tester) async { ... })`.
-- [ ] **Step 2:** Build the widget with `await tester.pumpWidget(MyWidget())`. Wrap in `MaterialApp` if needed.
-- [ ] **Step 3:** Locate elements with `Finder` objects.
-- [ ] **Step 4:** Verify initial state with `expect(finder, matcher)`.
-- [ ] **Step 5:** Simulate interactions (e.g., `await tester.tap(buttonFinder)`).
-- [ ] **Step 6:** Rebuild the tree with `await tester.pump()` or `await tester.pumpAndSettle()`.
-- [ ] **Step 7:** Verify updated state with `expect()`.
-- [ ] **Step 8:** Run with `flutter test test/your_test_file_test.dart`.
-- [ ] **Step 9:** Feedback Loop: Review output -> fix assertions -> re-run.
+- [ ] **Step 1: Define the test.** Use `testWidgets('description', (WidgetTester tester) async { ... })`.
+- [ ] **Step 2: Build the widget.** Call `await tester.pumpWidget(MyWidget())` to render the UI. Wrap the widget in a `MaterialApp` or `Directionality` widget if it requires inherited directional or theme data.
+- [ ] **Step 3: Locate elements.** Instantiate `Finder` objects for the target widgets.
+- [ ] **Step 4: Verify initial state.** Use `expect(finder, matcher)` to validate the initial render.
+- [ ] **Step 5: Simulate interactions.** Execute gestures or inputs (e.g., `await tester.tap(buttonFinder)`).
+- [ ] **Step 6: Rebuild the tree.** Call `await tester.pump()` or `await tester.pumpAndSettle()` to process state changes.
+- [ ] **Step 7: Verify updated state.** Use `expect()` to validate the UI after the interaction.
+- [ ] **Step 8: Run and validate.** Execute `flutter test test/your_test_file_test.dart`.
+- [ ] **Step 9: Feedback Loop.** Review test output -> identify failing matchers -> adjust widget logic or test assertions -> re-run until passing.
 
 ## Interaction & State Management
 
-- **Static rendering:** `pumpWidget()` once, then immediately assert.
-- **Standard state changes (button taps):** `tester.tap()` then `tester.pump()`.
-- **Animations/transitions:** Trigger the action then `tester.pumpAndSettle()`.
-- **Text input:** `await tester.enterText(textFieldFinder, 'Input string')`.
-- **Long lists:** `await tester.scrollUntilVisible(itemFinder, 500.0, scrollable: listFinder)`.
+Apply the following conditional logic based on the type of interaction or state change being tested:
+
+- **If testing static rendering:** Call `await tester.pumpWidget()` once, then immediately run `expect()` assertions.
+- **If testing standard state changes (e.g., button taps):**
+  1. Call `await tester.tap(finder)`.
+  2. Call `await tester.pump()` to trigger a single frame rebuild.
+- **If testing animations, transitions, or asynchronous UI updates:**
+  1. Trigger the action (e.g., `await tester.drag(finder, Offset(500, 0))`).
+  2. Call `await tester.pumpAndSettle()` to repeatedly pump frames until no more frames are scheduled (animation completes).
+- **If testing text input:** Call `await tester.enterText(textFieldFinder, 'Input string')`.
+- **If testing items in a dynamic or long list:** Call `await tester.scrollUntilVisible(itemFinder, 500.0, scrollable: listFinder)` to ensure the target widget is rendered before interacting with it.
 
 ## Examples
 
-### TodoList Widget Test
+### High-Fidelity Widget Test Implementation
 
 **Target Widget (`lib/todo_list.dart`):**
 
@@ -58,6 +71,7 @@ import 'package:flutter/material.dart';
 
 class TodoList extends StatefulWidget {
   const TodoList({super.key});
+
   @override
   State<TodoList> createState() => _TodoListState();
 }
@@ -103,7 +117,7 @@ class _TodoListState extends State<TodoList> {
 }
 ```
 
-**Test (`test/todo_list_test.dart`):**
+**Test Implementation (`test/todo_list_test.dart`):**
 
 ```dart
 import 'package:flutter/material.dart';
@@ -112,16 +126,31 @@ import 'package:my_app/todo_list.dart';
 
 void main() {
   testWidgets('Add and remove a todo item', (WidgetTester tester) async {
+    // 1. Build the widget
     await tester.pumpWidget(const TodoList());
+
+    // 2. Verify initial state
     expect(find.byType(ListTile), findsNothing);
 
+    // 3. Enter text into the TextField
     await tester.enterText(find.byType(TextField), 'Buy groceries');
+
+    // 4. Tap the add button
     await tester.tap(find.byType(FloatingActionButton));
+
+    // 5. Rebuild the widget to reflect the new state
     await tester.pump();
+
+    // 6. Verify the item was added
     expect(find.text('Buy groceries'), findsOneWidget);
 
+    // 7. Swipe the item to dismiss it
     await tester.drag(find.byType(Dismissible), const Offset(500, 0));
+
+    // 8. Build the widget until the dismiss animation ends
     await tester.pumpAndSettle();
+
+    // 9. Verify the item was removed
     expect(find.text('Buy groceries'), findsNothing);
   });
 }