@bdayadev/flutter-ultra-mcp 1.12.0 → 1.14.0

package/skills/setup-localization/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: setup-localization
 description: Add `flutter_localizations` and `intl` dependencies, enable "generate true" in `pubspec.yaml`, and create an `l10n.yaml` configuration file. Use when initializing localization support for a new Flutter project.
+  last_modified: Tue, 21 Apr 2026 21:27:35 GMT
 ---
 
 # Internationalizing Flutter Applications
@@ -15,46 +16,67 @@ description: Add `flutter_localizations` and `intl` dependencies, enable "genera
 
 ## Core Concepts
 
-Flutter handles i18n/l10n via `flutter_localizations` and `intl`. Uses App Resource Bundle (`.arb`) files compiled into a generated `AppLocalizations` class for type-safe access.
+Flutter handles internationalization (i18n) and localization (l10n) via the `flutter_localizations` and `intl` packages. The standard approach uses App Resource Bundle (`.arb`) files to define localized strings, which are then compiled into a generated `AppLocalizations` class for type-safe access within the widget tree.
 
 ## Setup Workflow
 
-- [ ] 1. Add dependencies to `pubspec.yaml`.
-- [ ] 2. Enable the `generate` flag.
-- [ ] 3. Create the `l10n.yaml` configuration file.
-- [ ] 4. Configure `MaterialApp` or `CupertinoApp`.
+Copy and track this checklist when initializing internationalization in a Flutter project:
+
+- [ ] **Task Progress**
+  - [ ] 1. Add dependencies to `pubspec.yaml`.
+  - [ ] 2. Enable the `generate` flag.
+  - [ ] 3. Create the `l10n.yaml` configuration file.
+  - [ ] 4. Configure `MaterialApp` or `CupertinoApp`.
 
 ### 1. Add Dependencies
 
+Add the required localization packages to the project. Execute the following commands in the terminal:
+
 ```bash
 flutter pub add flutter_localizations --sdk=flutter
 flutter pub add intl:any
 ```
 
+Verify your `pubspec.yaml` includes the following under `dependencies`:
+
+```yaml
+dependencies:
+  flutter:
+    sdk: flutter
+  flutter_localizations:
+    sdk: flutter
+  intl: any
+```
+
 ### 2. Enable Code Generation
 
+Open `pubspec.yaml` and enable the `generate` flag within the `flutter` section to automate localization tasks:
+
 ```yaml
-# pubspec.yaml
 flutter:
   generate: true
 ```
 
 ### 3. Create Configuration File
 
+Create a new file named `l10n.yaml` in the root directory of the Flutter project. Define the input directory, template file, and output file:
+
 ```yaml
-# l10n.yaml
 arb-dir: lib/l10n
 template-arb-file: app_en.arb
 output-localization-file: app_localizations.dart
 synthetic-package: true
 ```
 
-### 4. Configure App Entry Point
+### 4. Configure the App Entry Point
+
+Import the generated localizations and the `flutter_localizations` library in your `main.dart`. Inject the delegates and supported locales into your `MaterialApp` or `CupertinoApp`.
 
 ```dart
 import 'package:flutter_localizations/flutter_localizations.dart';
-import 'package:flutter_gen/gen_l10n/app_localizations.dart';
+import 'package:flutter_gen/gen_l10n/app_localizations.dart'; // Adjust path if synthetic-package is false
 
+// ... inside build method
 return MaterialApp(
   localizationsDelegates: const [
     AppLocalizations.delegate,
@@ -62,16 +84,22 @@ return MaterialApp(
     GlobalWidgetsLocalizations.delegate,
     GlobalCupertinoLocalizations.delegate,
   ],
-  supportedLocales: const [Locale('en'), Locale('es')],
+  supportedLocales: const [
+    Locale('en'), // English
+    Locale('es'), // Spanish
+  ],
   home: const MyHomePage(),
 );
 ```
 
 ## Implementation Workflow
 
+Follow this workflow when adding or modifying localized content.
+
 ### 1. Define ARB Files
 
-**Template (`lib/l10n/app_en.arb`):**
+- **If creating NEW content:** Add the base string to the template file (`lib/l10n/app_en.arb`). Include a description for context.
+- **If EDITING existing content:** Locate the key in all supported `.arb` files and update the values.
 
 ```json
 {
@@ -82,59 +110,98 @@ return MaterialApp(
 }
 ```
 
-**Other locales (`lib/l10n/app_es.arb`):**
+Create corresponding files for other locales (e.g., `app_es.arb`):
 
 ```json
 {
-  "helloWorld": "!Hola Mundo!"
+  "helloWorld": "¡Hola Mundo!"
 }
 ```
 
 ### 2. Generate Localization Classes
 
+Run the following command to trigger code generation:
+
 ```bash
 flutter pub get
 ```
 
+_Feedback Loop:_ Run validator -> review terminal output for ARB syntax errors -> fix missing commas or mismatched placeholders -> re-run `flutter pub get`.
+
 ### 3. Consume Localized Strings
 
+Access the localized strings in your widget tree using `AppLocalizations.of(context)`. Ensure the widget calling this is a descendant of `MaterialApp`.
+
 ```dart
 Text(AppLocalizations.of(context)!.helloWorld)
 ```
 
 ## Advanced Formatting
 
+Use placeholders for dynamic data, plurals, and conditional selects.
+
 ### Placeholders
 
+Define parameters within curly braces and specify their type in the metadata object.
+
 ```json
 "hello": "Hello {userName}",
 "@hello": {
+  "description": "A message with a single parameter",
   "placeholders": {
-    "userName": { "type": "String", "example": "Bob" }
+    "userName": {
+      "type": "String",
+      "example": "Bob"
+    }
   }
 }
 ```
 
 ### Plurals
 
+Use the `plural` syntax to handle quantity-based string variations. The `other` case is mandatory.
+
 ```json
 "nWombats": "{count, plural, =0{no wombats} =1{1 wombat} other{{count} wombats}}",
 "@nWombats": {
-  "placeholders": { "count": { "type": "num", "format": "compact" } }
+  "description": "A plural message",
+  "placeholders": {
+    "count": {
+      "type": "num",
+      "format": "compact"
+    }
+  }
 }
 ```
 
 ### Selects
 
+Use the `select` syntax for conditional strings, such as gendered text.
+
 ```json
 "pronoun": "{gender, select, male{he} female{she} other{they}}",
 "@pronoun": {
-  "placeholders": { "gender": { "type": "String" } }
+  "description": "A gendered message",
+  "placeholders": {
+    "gender": {
+      "type": "String"
+    }
+  }
 }
 ```
 
 ## Examples
 
+### Complete `l10n.yaml`
+
+```yaml
+arb-dir: lib/l10n
+template-arb-file: app_en.arb
+output-localization-file: app_localizations.dart
+synthetic-package: true
+use-escaping: true
+```
+
 ### Complete Widget Implementation
 
 ```dart
@@ -154,10 +221,13 @@ class GreetingWidget extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     final l10n = AppLocalizations.of(context)!;
-    return Column(children: [
-      Text(l10n.hello(userName)),
-      Text(l10n.nWombats(notificationCount)),
-    ]);
+
+    return Column(
+      children: [
+        Text(l10n.hello(userName)),
+        Text(l10n.nWombats(notificationCount)),
+      ],
+    );
   }
 }
 ```

package/skills/test/SKILL.md

@@ -11,7 +11,7 @@ Covers all Flutter test layers: unit, widget, golden, and patrol E2E. For ad-hoc
 
 ### 1. Identify project and scope
 
-- `mcp__plugin_flutter_flutter-ultra-build__list_projects` to find available projects.
+- `mcp__plugin_flutter_flutter-ultra-build__list_projects` to find available projects. If the target project does not yet exist, use `mcp__plugin_flutter_flutter-ultra-build__create_project` to scaffold it before proceeding.
 - `mcp__plugin_flutter_flutter-ultra-build__project_info` for the target project path, flavors, and entry points.
 - `mcp__plugin_flutter_flutter-ultra-build__test_filter` to discover test files matching a name pattern before running.
 - Determine scope from the user's request: unit only, widget only, patrol E2E only, golden only, full suite, or coverage.
@@ -107,6 +107,7 @@ After unit tests with `coverage: true`:
 4. **Patrol E2E failures**: read `logContext` from `get_patrol_result`. Cross-reference with `get_patrol_browser_errors` for web.
 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.
 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.
+7. **Flaky tests due to external API responses**: use `mcp__plugin_flutter_flutter-ultra-browser__mock_network_route` before running patrol web tests to stub non-deterministic endpoints and isolate the test from network variance.
 
 ## Output format
 

package/skills/tour/SKILL.md

@@ -49,6 +49,7 @@ If the user supplied a route list, use that directly.
    - Browser screenshot (web): `mcp__plugin_flutter_flutter-ultra-browser__screenshot`
    - Device screenshot (mobile): `mcp__plugin_flutter_flutter-ultra-native-mobile__take_device_screenshot`
    - Desktop screenshot: `mcp__plugin_flutter_flutter-ultra-native-desktop__desktop_screenshot`
+   - For auth-gated mobile routes that open a CCT/SVC: call `mcp__plugin_flutter_flutter-ultra-native-mobile__detect_in_app_browser` first; if detected, screenshot the in-app browser before dismissing it.
 5. **Responsive captures** (when requested): `mcp__plugin_flutter_flutter-ultra-gesture__take_responsive_screenshots` to capture at phone/tablet/desktop breakpoints in one call.
 6. Record `{ route, file, timestamp }` for the report.
 
@@ -68,12 +69,15 @@ Push live progress to a connected DevTools panel:
 
 ### 6. Handle edge cases
 
-- **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.
+- **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. For CCT/SVC-based auth on mobile, use `mcp__plugin_flutter_flutter-ultra-native-mobile__detect_in_app_browser` to detect the Custom Tab and interact with it before returning to the app.
 - **Parameterized routes** (`/item/:id`): substitute a known test ID. Ask the user for sample IDs if none are obvious.
 - **Routes that crash**: catch errors from `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors`, log in the report, continue to the next route.
 - **Async data loading**: poll `mcp__plugin_flutter_flutter-ultra-runtime__widget_exists` for loading indicators; wait up to 5s in 500ms increments.
 - **Bottom sheets / dialogs**: trigger via `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` on the parent route, screenshot, dismiss.
+- **Unexpected browser dialogs** (web tours): use `mcp__plugin_flutter_flutter-ultra-browser__handle_dialog` to dismiss alert/confirm/prompt dialogs that block screenshot capture.
 - **Platform rendering**: use `mcp__plugin_flutter_flutter-ultra-runtime__set_platform_override` to capture iOS-style UI on a non-iOS device.
+- **Notification state screenshots**: use `mcp__plugin_flutter_flutter-ultra-native-mobile__open_notification_tray` to expand the notification shade, then `mcp__plugin_flutter_flutter-ultra-native-mobile__list_notifications` to enumerate visible notifications before capturing a screenshot.
+- **Consistent API responses**: use `mcp__plugin_flutter_flutter-ultra-browser__mock_network_route` (web) to stub API responses before navigating to data-dependent routes, ensuring reproducible screenshots across runs.
 
 ### 7. Compile the report
 
@@ -81,27 +85,32 @@ Write `tour-report.md` with a markdown table of all routes, screenshot paths, an
 
 ## Tool reference
 
-| Action              | Tool                                                                      |
-| ------------------- | ------------------------------------------------------------------------- |
-| Find sessions       | `mcp__plugin_flutter_flutter-ultra-runtime__discover_sessions`            |
-| Launch app          | `mcp__plugin_flutter_flutter-ultra-runtime__launch_app`                   |
-| Attach              | `mcp__plugin_flutter_flutter-ultra-runtime__attach`                       |
-| Evaluate Dart       | `mcp__plugin_flutter_flutter-ultra-runtime__evaluate`                     |
-| VM screenshot       | `mcp__plugin_flutter_flutter-ultra-runtime__screenshot`                   |
-| Find widget         | `mcp__plugin_flutter_flutter-ultra-runtime__find_widget`                  |
-| Widget exists       | `mcp__plugin_flutter_flutter-ultra-runtime__widget_exists`                |
-| Platform override   | `mcp__plugin_flutter_flutter-ultra-runtime__set_platform_override`        |
-| Runtime errors      | `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors`           |
-| Wait for settle     | `mcp__plugin_flutter_flutter-ultra-gesture__wait_for`                     |
-| Responsive shots    | `mcp__plugin_flutter_flutter-ultra-gesture__take_responsive_screenshots`  |
-| Screencast start    | `mcp__plugin_flutter_flutter-ultra-gesture__start_screencast`             |
-| Screencast stop     | `mcp__plugin_flutter_flutter-ultra-gesture__stop_screencast`              |
-| Browser screenshot  | `mcp__plugin_flutter_flutter-ultra-browser__screenshot`                   |
-| Browser launch      | `mcp__plugin_flutter_flutter-ultra-browser__launch_browser`               |
-| Connect CDP         | `mcp__plugin_flutter_flutter-ultra-browser__connect_over_cdp`             |
-| Device screenshot   | `mcp__plugin_flutter_flutter-ultra-native-mobile__take_device_screenshot` |
-| Desktop screenshot  | `mcp__plugin_flutter_flutter-ultra-native-desktop__desktop_screenshot`    |
-| Push DevTools event | `mcp__plugin_flutter_flutter-ultra-devtools__push_event`                  |
+| Action                 | Tool                                                                      |
+| ---------------------- | ------------------------------------------------------------------------- |
+| Find sessions          | `mcp__plugin_flutter_flutter-ultra-runtime__discover_sessions`            |
+| Launch app             | `mcp__plugin_flutter_flutter-ultra-runtime__launch_app`                   |
+| Attach                 | `mcp__plugin_flutter_flutter-ultra-runtime__attach`                       |
+| Evaluate Dart          | `mcp__plugin_flutter_flutter-ultra-runtime__evaluate`                     |
+| VM screenshot          | `mcp__plugin_flutter_flutter-ultra-runtime__screenshot`                   |
+| Find widget            | `mcp__plugin_flutter_flutter-ultra-runtime__find_widget`                  |
+| Widget exists          | `mcp__plugin_flutter_flutter-ultra-runtime__widget_exists`                |
+| Platform override      | `mcp__plugin_flutter_flutter-ultra-runtime__set_platform_override`        |
+| Runtime errors         | `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors`           |
+| Wait for settle        | `mcp__plugin_flutter_flutter-ultra-gesture__wait_for`                     |
+| Responsive shots       | `mcp__plugin_flutter_flutter-ultra-gesture__take_responsive_screenshots`  |
+| Screencast start       | `mcp__plugin_flutter_flutter-ultra-gesture__start_screencast`             |
+| Screencast stop        | `mcp__plugin_flutter_flutter-ultra-gesture__stop_screencast`              |
+| Browser screenshot     | `mcp__plugin_flutter_flutter-ultra-browser__screenshot`                   |
+| Browser launch         | `mcp__plugin_flutter_flutter-ultra-browser__launch_browser`               |
+| Connect CDP            | `mcp__plugin_flutter_flutter-ultra-browser__connect_over_cdp`             |
+| Device screenshot      | `mcp__plugin_flutter_flutter-ultra-native-mobile__take_device_screenshot` |
+| Desktop screenshot     | `mcp__plugin_flutter_flutter-ultra-native-desktop__desktop_screenshot`    |
+| Detect CCT/SVC         | `mcp__plugin_flutter_flutter-ultra-native-mobile__detect_in_app_browser`  |
+| Open notif tray        | `mcp__plugin_flutter_flutter-ultra-native-mobile__open_notification_tray` |
+| List notifications     | `mcp__plugin_flutter_flutter-ultra-native-mobile__list_notifications`     |
+| Dismiss browser dialog | `mcp__plugin_flutter_flutter-ultra-browser__handle_dialog`                |
+| Mock API response      | `mcp__plugin_flutter_flutter-ultra-browser__mock_network_route`           |
+| Push DevTools event    | `mcp__plugin_flutter_flutter-ultra-devtools__push_event`                  |
 
 ## Example
 

package/skills/use-http-package/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: use-http-package
 description: Use the `http` package to execute GET, POST, PUT, or DELETE requests. Use when you need to fetch from or send data to a REST API.
+  last_modified: Tue, 21 Apr 2026 21:36:42 GMT
 ---
 
 # Implementing Flutter Networking
@@ -15,56 +16,82 @@ description: Use the `http` package to execute GET, POST, PUT, or DELETE request
 
 ## Configuration & Permissions
 
-1. Add the `http` package: `flutter pub add http`
-2. Import: `import 'package:http/http.dart' as http;`
-3. **Android**: Add `<uses-permission android:name="android.permission.INTERNET" />` to `AndroidManifest.xml`.
-4. **macOS**: Add `com.apple.security.network.client` = `true` to both entitlements files.
+Configure the environment and platform-specific permissions required for network access.
+
+1. Add the `http` package dependency via the terminal:
+   ```bash
+   flutter pub add http
+   ```
+2. Import the package in your Dart files:
+   ```dart
+   import 'package:http/http.dart' as http;
+   ```
+3. Configure Android permissions by adding the Internet permission to `android/app/src/main/AndroidManifest.xml`:
+   ```xml
+   <uses-permission android:name="android.permission.INTERNET" />
+   ```
+4. Configure macOS entitlements by adding the network client key to both `macos/Runner/DebugProfile.entitlements` and `macos/Runner/Release.entitlements`:
+   ```xml
+   <key>com.apple.security.network.client</key>
+   <true/>
+   ```
 
 ## Request Execution & Response Handling
 
-- **URIs:** Always use `Uri.parse('your_url')`.
-- **Headers:** Inject via the `headers` parameter map.
-- **Payloads:** For POST/PUT, encode body with `jsonEncode()`.
-- **Status Validation:** Treat `200 OK` (GET/PUT/DELETE) and `201 CREATED` (POST) as success.
-- **Error Handling:** Throw explicit exceptions on non-success codes. Never return `null`.
-- **Deserialization:** `jsonDecode(response.body)` then map to model's `fromJson`.
+Execute HTTP operations and map responses to strongly typed Dart objects.
+
+- **URIs:** Always parse URL strings using `Uri.parse('your_url')`.
+- **Headers:** Inject authorization and content-type headers via the `headers` parameter map. Use `HttpHeaders.authorizationHeader` for auth tokens.
+- **Payloads:** For POST and PUT requests, encode the body using `jsonEncode()` from `dart:convert`.
+- **Status Validation:** Evaluate `response.statusCode`. Treat `200 OK` (GET/PUT/DELETE) and `201 CREATED` (POST) as success.
+- **Error Handling:** Throw explicit exceptions for non-success status codes. Never return `null` on failure, as this prevents `FutureBuilder` from triggering its error state and causes infinite loading indicators.
+- **Deserialization:** Parse the raw string using `jsonDecode(response.body)` and map it to a custom Dart object using a factory constructor (e.g., `fromJson`).
 
 ## Background Parsing
 
-For large payloads (>16ms parse time), use `compute()` from `package:flutter/foundation.dart` to parse in a background isolate. The parsing function must be top-level or static.
+Offload expensive JSON parsing to a separate Isolate to prevent UI jank (frame drops).
+
+- Import `package:flutter/foundation.dart`.
+- Use the `compute()` function to run the parsing logic in a background isolate.
+- Ensure the parsing function passed to `compute()` is a top-level function or a static method, as closures or instance methods cannot be passed across isolates.
 
 ## Workflow: Executing Network Operations
 
+Use the following checklist to implement and validate network operations.
+
 **Task Progress:**
 
-- [ ] 1. Define strongly typed Dart model with `fromJson`.
-- [ ] 2. Implement network request method returning `Future<Model>`.
-- [ ] 3. Apply conditional logic:
-  - **GET**: Append query parameters to URI.
-  - **POST/PUT**: Set `Content-Type: application/json; charset=UTF-8`, attach `jsonEncode` body.
-  - **DELETE**: Return empty model instance on success.
-- [ ] 4. Validate `statusCode` and throw `Exception` on failure.
-- [ ] 5. Integrate into UI using `FutureBuilder`.
-- [ ] 6. Handle `snapshot.hasData`, `snapshot.hasError`, default to `CircularProgressIndicator`.
-- [ ] 7. Run app -> trigger request -> review console for exceptions -> fix.
+- [ ] 1. Define the strongly typed Dart model with a `fromJson` factory constructor.
+- [ ] 2. Implement the network request method returning a `Future<Model>`.
+- [ ] 3. Apply conditional logic based on the operation type:
+  - **If fetching data (GET):** Append query parameters to the URI.
+  - **If mutating data (POST/PUT):** Set `'Content-Type': 'application/json; charset=UTF-8'` and attach the `jsonEncode` body.
+  - **If deleting data (DELETE):** Return an empty model instance on success (`200 OK`).
+- [ ] 4. Validate the `statusCode` and throw an `Exception` on failure.
+- [ ] 5. Integrate the `Future` into the UI using `FutureBuilder`.
+- [ ] 6. Handle `snapshot.hasData`, `snapshot.hasError`, and default to a `CircularProgressIndicator`.
+- [ ] 7. **Feedback Loop:** Run the app -> trigger the network request -> review console for unhandled exceptions -> fix parsing or permission errors.
 
 ## Examples
 
-### Fetching and Parsing in the Background
+### High-Fidelity Implementation: Fetching and Parsing in the Background
 
 ```dart
+import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:http/http.dart' as http;
 
+// 1. Top-level parsing function for Isolate
 List<Photo> parsePhotos(String responseBody) {
   final parsed = (jsonDecode(responseBody) as List<Object?>)
       .cast<Map<String, Object?>>();
   return parsed.map<Photo>(Photo.fromJson).toList();
 }
 
+// 2. Network execution with background parsing
 Future<List<Photo>> fetchPhotos() async {
   final response = await http.get(
     Uri.parse('https://jsonplaceholder.typicode.com/photos'),
@@ -75,18 +102,24 @@ Future<List<Photo>> fetchPhotos() async {
   );
 
   if (response.statusCode == 200) {
+    // Offload heavy parsing to a background isolate
     return compute(parsePhotos, response.body);
   } else {
     throw Exception('Failed to load photos. Status: ${response.statusCode}');
   }
 }
 
+// 3. Strongly typed model
 class Photo {
   final int id;
   final String title;
   final String thumbnailUrl;
 
-  const Photo({required this.id, required this.title, required this.thumbnailUrl});
+  const Photo({
+    required this.id,
+    required this.title,
+    required this.thumbnailUrl,
+  });
 
   factory Photo.fromJson(Map<String, dynamic> json) {
     return Photo(
@@ -97,8 +130,10 @@ class Photo {
   }
 }
 
+// 4. UI Integration
 class PhotoGallery extends StatefulWidget {
   const PhotoGallery({super.key});
+
   @override
   State<PhotoGallery> createState() => _PhotoGalleryState();
 }
@@ -109,6 +144,7 @@ class _PhotoGalleryState extends State<PhotoGallery> {
   @override
   void initState() {
     super.initState();
+    // Initialize Future once to prevent re-fetching on rebuilds
     _futurePhotos = fetchPhotos();
   }
 
@@ -129,6 +165,8 @@ class _PhotoGalleryState extends State<PhotoGallery> {
         } else if (snapshot.hasError) {
           return Center(child: Text('Error: ${snapshot.error}'));
         }
+
+        // Default loading state
         return const Center(child: CircularProgressIndicator());
       },
     );

package/skills/use-pattern-matching/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: use-pattern-matching
 description: Use switch expressions and pattern matching where appropriate
+  last_modified: Fri, 24 Apr 2026 15:08:55 GMT
 ---
 
 # Implementing Dart Patterns
@@ -15,60 +16,82 @@ description: Use switch expressions and pattern matching where appropriate
 
 ## Pattern Selection Strategy
 
-- **If validating and extracting from deserialized data (e.g., JSON):** Use Map and List patterns.
-- **If handling multiple return values:** Use Record patterns.
-- **If executing type-specific behavior (Algebraic Data Types):** Use Object patterns with `sealed` classes.
-- **If matching numeric ranges or conditions:** Use Relational and Logical-and patterns.
-- **If multiple cases share logic:** Use Logical-or (`||`) patterns.
-- **If ignoring specific values:** Use the Wildcard pattern (`_`).
+Apply specific pattern types based on the data structure and desired outcome. Follow these conditional guidelines:
+
+- **If validating and extracting from deserialized data (e.g., JSON):** Use Map and List patterns to simultaneously check structure and destructure key-value pairs.
+- **If handling multiple return values:** Use Record patterns to destructure fields directly into local variables.
+- **If executing type-specific behavior (Algebraic Data Types):** Use Object patterns combined with `sealed` classes to ensure exhaustiveness.
+- **If matching numeric ranges or conditions:** Use Relational (`>=`, `<=`) and Logical-and (`&&`) patterns.
+- **If multiple cases share logic:** Use Logical-or (`||`) patterns to share a single case body or guard clause.
+- **If ignoring specific values:** Use the Wildcard pattern (`_`) or a non-matching Rest element (`...`) in collections.
 
 ## Switch Statements vs. Expressions
 
-- **If producing a value:** Use a **switch expression**. Syntax: `switch (value) { pattern => expression, }`. Must be exhaustive.
-- **If executing statements or side effects:** Use a **switch statement**. Empty cases fall through. Non-empty cases implicitly break.
+Select the appropriate switch construct based on the execution context:
+
+- **If producing a value:** Use a **switch expression**.
+  - Syntax: `switch (value) { pattern => expression, }`
+  - Rule: Each case must be a single expression. No implicit fallthrough. Must be exhaustive.
+- **If executing statements or side effects:** Use a **switch statement**.
+  - Syntax: `switch (value) { case pattern: statements; }`
+  - Rule: Empty cases fall through to the next case. Non-empty cases implicitly break (no `break` keyword required).
 
 ## Core Pattern Implementations
 
-- **Logical-or (`||`):** Both branches must define the exact same set of variables.
-- **Logical-and (`&&`):** Branches must _not_ define overlapping variables.
+Implement patterns using the following syntax and rules:
+
+- **Logical-or (`||`):** `pattern1 || pattern2`. Both branches must define the exact same set of variables.
+- **Logical-and (`&&`):** `pattern1 && pattern2`. Branches must _not_ define overlapping variables.
 - **Relational:** `==`, `!=`, `<`, `>`, `<=`, `>=` followed by a constant expression.
-- **Cast (`as`):** Throws if the value does not match the type.
-- **Null-check (`?`):** Fails the match if the value is null.
-- **Null-assert (`!`):** Throws if the value is null.
-- **Variable:** `var name` or `Type name`. Binds the matched value.
+- **Cast (`as`):** `pattern as Type`. Throws if the value does not match the type. Use to forcibly assert types during destructuring.
+- **Null-check (`?`):** `pattern?`. Fails the match if the value is null. Binds the variable to the non-nullable base type.
+- **Null-assert (`!`):** `pattern!`. Throws if the value is null.
+- **Variable:** `var name` or `Type name`. Binds the matched value to a new local variable.
 - **Wildcard (`_`):** Matches any value and discards it.
-- **List:** `[pattern1, pattern2]`. Matches lists of exact length unless a Rest element (`...`) is used.
-- **Map:** `{"key": pattern}`. Matches maps containing the specified keys.
-- **Record:** `(pattern1, named: pattern2)`. Use `:var name` to infer the getter name.
-- **Object:** `ClassName(field: pattern)`. Use `:var field` to infer the getter name.
+- **List:** `[pattern1, pattern2]`. Matches lists of exact length unless a Rest element (`...` or `...var rest`) is used.
+- **Map:** `{"key": pattern}`. Matches maps containing the specified keys. Ignores unmatched keys.
+- **Record:** `(pattern1, named: pattern2)`. Matches records of the exact shape. Use `:var name` to infer the getter name.
+- **Object:** `ClassName(field: pattern)`. Matches instances of `ClassName`. Use `:var field` to infer the getter name.
 
 ## Workflows
 
 ### Task Progress: Implementing Pattern Matching
 
-- [ ] Identify the data structure being evaluated.
-- [ ] Select the appropriate switch construct.
-- [ ] Define the required patterns.
-- [ ] Extract required data using Variable patterns.
+Copy this checklist to track progress when implementing complex pattern matching logic:
+
+- [ ] Identify the data structure being evaluated (JSON, Record, Class, Enum).
+- [ ] Select the appropriate switch construct (Expression for values, Statement for side-effects).
+- [ ] Define the required patterns (Object, Map, List, Record).
+- [ ] Extract required data using Variable patterns (`var x`, `:var y`).
 - [ ] Apply Guard clauses (`when condition`) for logic that cannot be expressed via patterns.
-- [ ] Handle unmatched cases using a Wildcard (`_`) or `default`.
+- [ ] Handle unmatched cases using a Wildcard (`_`) or `default` clause (if not using a sealed class).
 - [ ] Run exhaustiveness validator.
 
 ### Feedback Loop: Exhaustiveness Checking
 
-1. Execute `dart analyze`.
-2. Look for "The type 'X' is not exhaustively matched" errors.
-3. Add the missing Object patterns for unhandled subtypes, or add a Wildcard case.
+When switching over `sealed` classes or enums, you must ensure all subtypes are handled.
+
+1. **Run validator:** Execute `dart analyze`.
+2. **Review errors:** Look for "The type 'X' is not exhaustively matched by the switch cases" errors.
+3. **Fix:** Add the missing Object patterns for the unhandled subtypes, or add a Wildcard (`_`) case if a default fallback is acceptable.
 
 ## Examples
 
 ### JSON Validation and Destructuring
 
+Use Map and List patterns to validate structure and extract data in a single step.
+
+**Input:**
+
 ```dart
 var data = {
   'user': ['Lily', 13],
 };
+```
 
+**Implementation:**
+
+```dart
 if (data case {'user': [String name, int age]}) {
   print('User $name is $age years old.');
 } else {
@@ -78,6 +101,10 @@ if (data case {'user': [String name, int age]}) {
 
 ### Algebraic Data Types (Sealed Classes)
 
+Use Object patterns with switch expressions to handle family types exhaustively.
+
+**Implementation:**
+
 ```dart
 sealed class Shape {}
 
@@ -91,6 +118,7 @@ class Circle implements Shape {
   Circle(this.radius);
 }
 
+// Switch expression guarantees exhaustiveness due to `sealed` modifier.
 double calculateArea(Shape shape) => switch (shape) {
   Square(length: var l) => l * l,
   Circle(:var radius)   => math.pi * radius * radius,
@@ -99,15 +127,24 @@ double calculateArea(Shape shape) => switch (shape) {
 
 ### Variable Swapping and Destructuring
 
+Use variable assignment patterns to swap values or extract record fields without temporary variables.
+
+**Implementation:**
+
 ```dart
 var (a, b) = ('left', 'right');
 (b, a) = (a, b); // Swap values
 
+// Destructuring a function return
 var (name, age) = getUserInfo();
 ```
 
 ### Guard Clauses and Logical-or
 
+Use `when` to evaluate arbitrary conditions after a pattern matches.
+
+**Implementation:**
+
 ```dart
 switch (shape) {
   case Square(size: var s) || Circle(size: var s) when s > 0: