@bdayadev/flutter-ultra-mcp 1.3.2 → 1.5.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.3.2",
+      "version": "1.5.0",
       "author": {
         "name": "Bdaya-Dev",
         "url": "https://github.com/Bdaya-Dev"
@@ -31,5 +31,5 @@
       ]
     }
   ],
-  "version": "1.3.2"
+  "version": "1.5.0"
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "flutter",
-  "version": "1.3.2",
+  "version": "1.5.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/dart/ultra_flutter/pubspec.yaml

@@ -15,8 +15,6 @@ topics:
   - agent
   - testing
 
-publish_to: none
-
 environment:
   sdk: '>=3.6.0 <4.0.0'
   flutter: '>=3.27.0'

package/dart/ultra_flutter_devtools/pubspec.yaml

@@ -7,8 +7,6 @@ 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
 
-publish_to: none
-
 environment:
   sdk: ^3.5.0
   flutter: '>=3.24.0'

package/examples/counter-app/README.md

@@ -17,8 +17,8 @@ In debug mode the `UltraFlutterBinding` is automatically initialized, exposing
 
 ## Widget Keys
 
-| Key | Widget | Purpose |
-|-----|--------|---------|
-| `counter_value` | Text | Displays current count |
-| `increment` | FAB | Increments counter |
-| `decrement` | FAB | Decrements counter |
+| Key             | Widget | Purpose                |
+| --------------- | ------ | ---------------------- |
+| `counter_value` | Text   | Displays current count |
+| `increment`     | FAB    | Increments counter     |
+| `decrement`     | FAB    | Decrements counter     |

package/examples/counter-app/pubspec.yaml

@@ -18,6 +18,8 @@ dependencies:
 dev_dependencies:
   flutter_test:
     sdk: flutter
+  integration_test:
+    sdk: flutter
 
 flutter:
   uses-material-design: true

package/examples/oidc-app/README.md

@@ -19,11 +19,13 @@ interception and CCT (Custom Chrome Tab) OAuth solver on mobile.
 ## Running
 
 1. Start the mock OIDC server:
+
    ```bash
    dart run lib/mock_oidc_server.dart
    ```
 
 2. Run the Flutter app:
+
    ```bash
    flutter run -d chrome
    ```
@@ -32,14 +34,14 @@ interception and CCT (Custom Chrome Tab) OAuth solver on mobile.
 
 ## Widget Keys
 
-| Key | Widget | Purpose |
-|-----|--------|---------|
-| `login_button` | FilledButton | Initiates OIDC flow |
-| `logout_button` | FilledButton.tonal | Clears token |
-| `auth_status` | Text | Shows "Authenticated" or "Not authenticated" |
-| `token_preview` | SelectableText | Truncated token display |
-| `loading_indicator` | CircularProgressIndicator | During OAuth exchange |
-| `error_text` | Text | Error message |
+| Key                 | Widget                    | Purpose                                      |
+| ------------------- | ------------------------- | -------------------------------------------- |
+| `login_button`      | FilledButton              | Initiates OIDC flow                          |
+| `logout_button`     | FilledButton.tonal        | Clears token                                 |
+| `auth_status`       | Text                      | Shows "Authenticated" or "Not authenticated" |
+| `token_preview`     | SelectableText            | Truncated token display                      |
+| `loading_indicator` | CircularProgressIndicator | During OAuth exchange                        |
+| `error_text`        | Text                      | Error message                                |
 
 ## CI Usage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bdayadev/flutter-ultra-mcp",
-  "version": "1.3.2",
+  "version": "1.5.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",
@@ -28,7 +28,10 @@
     "format": "prettier --write \"**/*.{ts,tsx,js,json,md,yml,yaml}\"",
     "format:check": "prettier --check \"**/*.{ts,tsx,js,json,md,yml,yaml}\"",
     "bundle": "node scripts/bundle.mjs",
-    "prepare": "npm run build --if-present || true"
+    "prepare": "npm run build --if-present || true",
+    "test:e2e:web": "vitest run tests/e2e/web/",
+    "test:e2e:oidc": "vitest run tests/e2e/oidc/",
+    "test:dogfood": "vitest run tests/e2e/dogfood/"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.0.0",

package/packages/flutter-ultra-browser/package.json

@@ -36,4 +36,4 @@
     "typescript": "^5.6.0",
     "vitest": "^2.0.0"
   }
-}
+}

package/packages/flutter-ultra-build/package.json

@@ -35,4 +35,4 @@
     "@types/proper-lockfile": "^4.1.4",
     "vitest": "^2.1.9"
   }
-}
+}

package/packages/flutter-ultra-devtools/package.json

@@ -33,4 +33,4 @@
     "typescript": "^5.6.0",
     "vitest": "^3.2.4"
   }
-}
+}

package/packages/flutter-ultra-gesture/package.json

@@ -55,4 +55,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

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

@@ -78,4 +78,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

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

@@ -69,4 +69,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/packages/flutter-ultra-patrol/README.md

@@ -22,12 +22,12 @@ MCP server orchestrating **Patrol E2E tests** across web, Android, iOS, and desk
 
 ## Environment contract (from plugin `.mcp.json`)
 
-| Var                         | Used for                                                                                                                                                                                                    |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `FLUTTER_ULTRA_PATROL_FORK` | Absolute path to `vendor/patrol/`.                                                                                                                                                                          |
-| `FLUTTER_ULTRA_STATE_DIR`   | Future on-disk job persistence (in-memory in v1.0).                                                                                                                                                         |
+| Var                         | Used for                                                                                                                                                                              |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FLUTTER_ULTRA_PATROL_FORK` | Absolute path to `vendor/patrol/`.                                                                                                                                                    |
+| `FLUTTER_ULTRA_STATE_DIR`   | Future on-disk job persistence (in-memory in v1.0).                                                                                                                                   |
 | `PATROL_WEB_BROWSER_ARGS`   | Comma-separated Chromium flags merged into every `--web-browser-args`. Default: `--enable-unsafe-swiftshader,--disable-renderer-backgrounding,--disable-background-timer-throttling`. |
-| `FLUTTER_ULTRA_LOG_LEVEL`   | `debug`/`info`/`warn`/`error`. Default `info`.                                                                                                                                                              |
+| `FLUTTER_ULTRA_LOG_LEVEL`   | `debug`/`info`/`warn`/`error`. Default `info`.                                                                                                                                        |
 
 ## Invocation strategy
 

package/packages/flutter-ultra-patrol/package.json

@@ -35,4 +35,4 @@
   "engines": {
     "node": ">=20"
   }
-}
+}

package/packages/flutter-ultra-runtime/package.json

@@ -66,4 +66,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/shared/contracts/package.json

@@ -2,7 +2,7 @@
   "name": "@flutter-ultra/contracts",
   "version": "0.0.0",
   "private": true,
-  "description": "JSON Schema contract definitions for ext.flutter.ultra.* wire format \u00e2\u20ac\u201d single source of truth for TS\u00e2\u2020\u201dDart interop.",
+  "description": "JSON Schema contract definitions for ext.flutter.ultra.* wire format — single source of truth for TS↔Dart interop.",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -28,4 +28,4 @@
   "devDependencies": {
     "vitest": "^3.2.4"
   }
-}
+}

package/shared/device-router/package.json

@@ -59,4 +59,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/shared/keyring/package.json

@@ -21,4 +21,4 @@
   "dependencies": {
     "@napi-rs/keyring": "^1.3.0"
   }
-}
+}

package/shared/mcp-runtime/package.json

@@ -55,4 +55,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/shared/state-store/package.json

@@ -57,4 +57,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/shared/vm-service-client/package.json

@@ -59,4 +59,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/skills/bisect/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: flutter-bisect
+description: Automate git bisect to find the commit that introduced a bug. Flutter-aware: runs pub get + build_runner between commits. Use when a test passes on an older commit but fails on HEAD and you need to find exactly which commit broke it.
+disable-model-invocation: true
+---
+
+# flutter-bisect — Automated Regression Finder
+
+## When to use
+
+Use this skill when a test (unit, widget, or patrol E2E) passes on an older commit but fails on HEAD and you need to pinpoint exactly which commit introduced the regression. Do not use for diagnosing a bug you already know the source of — use `flutter-debug` instead.
+
+## Prerequisites
+
+- The working tree is in a git repository (`git status` returns without error).
+- The user provides (or you can infer) a **known-good** commit reference: a tag (`v1.2.0`), a branch name (`main@{7 days ago}`), or a full SHA.
+- A **test oracle** is specified: a unit/widget test name pattern, a patrol test file, or a Bash-style exit-code command.
+- No uncommitted changes that would interfere — stash them first (see Edge cases).
+
+## Workflow
+
+### 1. Confirm inputs before starting
+
+Ask (or confirm from context) the following before calling any git command:
+
+- **Good commit**: the last-known-good reference (tag, SHA, or relative ref).
+- **Bad commit**: defaults to `HEAD`.
+- **Oracle type**: `unit`, `widget`, or `patrol`.
+- **Oracle selector**: test name pattern or patrol `testFilePath`.
+- **Project**: call `mcp__plugin_flutter_flutter-ultra-build__list_projects` if not already known.
+- **Has build_runner**: check for `build.yaml` in the project root — if present, set `needs_build_runner=true`.
+
+### 2. Stash uncommitted changes
+
+Before touching any git ref, check for dirty working tree:
+
+```bash
+git -C <project-root> status --porcelain
+```
+
+If output is non-empty, stash:
+
+```bash
+git -C <project-root> stash push -m "flutter-bisect-autoStash"
+```
+
+Record whether a stash was created — you must restore it in step 7.
+
+### 3. Start bisect
+
+```bash
+git -C <project-root> bisect start --first-parent HEAD <good-commit>
+```
+
+`--first-parent` skips noise from merged feature branches and keeps the walk on the mainline. Git prints the number of steps remaining — surface this to the user.
+
+### 4. At each bisect step — the Flutter-aware oracle loop
+
+Repeat until git prints `<sha> is the first bad commit`:
+
+#### 4a. Get current commit info
+
+```bash
+git -C <project-root> log -1 --format="%H %s"
+```
+
+Show the user which commit is under test and how many steps remain.
+
+#### 4b. Restore Flutter state for this commit
+
+Run these in order — do not skip even if pubspec.yaml looks unchanged (lockfile may differ):
+
+1. **pub get**: `mcp__plugin_flutter_flutter-ultra-build__pub_get` with the project name.
+   - If pub get fails (e.g. dependency conflict introduced by this commit), mark the commit **bad** and continue — a broken dep is a broken state.
+2. **build_runner** (only if `needs_build_runner=true`):
+   - Call `mcp__plugin_flutter_flutter-ultra-build__start_build_runner_build`.
+   - Poll `mcp__plugin_flutter_flutter-ultra-build__poll_build_runner_job` until done.
+   - Get result via `mcp__plugin_flutter_flutter-ultra-build__get_build_runner_result`.
+   - If build_runner fails: mark the commit **bad** and continue.
+
+#### 4c. Run the oracle
+
+**Unit/widget oracle:**
+
+- Start: `mcp__plugin_flutter_flutter-ultra-build__start_run_unit_tests` with `testNamePattern` (or `start_run_widget_tests`).
+- Poll: `mcp__plugin_flutter_flutter-ultra-build__poll_run_unit_tests` (or `poll_run_widget_tests`).
+- Result: `mcp__plugin_flutter_flutter-ultra-build__get_run_unit_tests_result` (or `get_run_widget_tests_result`).
+- If all targeted tests pass → **good**. If any fail → **bad**.
+
+**Patrol oracle:**
+
+- Start: `mcp__plugin_flutter_flutter-ultra-patrol__start_patrol_test` with `testFilePath` and `device`.
+- Poll: `mcp__plugin_flutter_flutter-ultra-patrol__poll_patrol_job`.
+- Result: `mcp__plugin_flutter_flutter-ultra-patrol__get_patrol_result`.
+- If all steps pass → **good**. If any fail → **bad**.
+
+#### 4d. Mark the commit
+
+```bash
+# if oracle passed:
+git -C <project-root> bisect good
+
+# if oracle failed:
+git -C <project-root> bisect bad
+```
+
+Git will output the next commit to test, or the final verdict. Loop back to 4a.
+
+### 5. Capture and report the first bad commit
+
+When git prints `<sha> is the first bad commit`, capture the full details:
+
+```bash
+git -C <project-root> show --stat <sha>
+git -C <project-root> log -1 --format="%H%n%an <%ae>%n%ad%n%s%n%b" --date=iso <sha>
+```
+
+Present a structured report (see Output format).
+
+### 6. Reset bisect
+
+Always reset, even on error:
+
+```bash
+git -C <project-root> bisect reset
+```
+
+### 7. Restore stash (if created in step 2)
+
+```bash
+git -C <project-root> stash pop
+```
+
+## Edge cases
+
+| Situation                                    | Handling                                                                                                                                                                                                                              |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Merge commits on the walk**                | `--first-parent` avoids them; if user omits it intentionally (to bisect a merged branch), remove the flag and warn that step count increases.                                                                                         |
+| **Uncommitted changes**                      | Auto-stash in step 2; restore in step 7. If stash pop fails (conflict), warn the user and leave the stash intact — do not discard it.                                                                                                 |
+| **Submodule repo**                           | `git bisect` operates on the outer repo. If the Flutter project is a submodule, confirm the user wants to bisect the outer aggregate, not the inner submodule. Pass the correct `-C <path>` to all git commands.                      |
+| **Flutter SDK version change**               | If a commit changes the Flutter SDK constraint (`.tool-versions`, `fvm` config, `flutter.constraints`), call `mcp__plugin_flutter_flutter-ultra-build__flutter_clean` before pub get to clear the compiled kernel cache.              |
+| **pub get resolves a different lockfile**    | Expected — this is exactly what the skill needs. Never pin the lockfile artificially during bisect.                                                                                                                                   |
+| **Oracle is flaky**                          | If the oracle fails on a commit that visually looks clean, re-run it once. If it fails again, mark bad. Do not retry more than once per commit — flakiness analysis is out of scope here; use `flutter-debug` after bisect completes. |
+| **All commits bad (misconfigured good ref)** | If `git bisect start` immediately shows 0 steps or git says the good commit is not an ancestor, stop and ask the user to verify the good commit reference.                                                                            |
+
+## Output format
+
+After bisect completes, produce:
+
+```
+## Bisect Result
+
+First bad commit: <sha>
+Author:  <name> <<email>>
+Date:    <iso date>
+Message: <subject line>
+
+<body if present>
+
+Files changed:
+<git show --stat output>
+
+Steps taken: <N> commits tested across <M> total candidates.
+```
+
+If bisect could not converge (user cancelled, all commits bad, or git error), produce:
+
+```
+## Bisect Aborted
+
+Reason: <what went wrong>
+Last tested commit: <sha or "none">
+Recommendation: <next debugging step>
+```
+
+## Example
+
+```
+User: "The InvoiceBloc unit test was green on v1.3.0 but fails on HEAD. Find which commit broke it."
+
+1. list_projects → project: "invora-flutter"
+2. Check build.yaml → present → needs_build_runner=true
+3. git status → clean → no stash needed
+4. git bisect start --first-parent HEAD v1.3.0 → "~6 steps (roughly 53 revisions)"
+5. [commit abc123] pub_get → ok; build_runner → ok; run_unit_tests(pattern: "InvoiceBloc") → FAIL → bisect bad
+6. [commit def456] pub_get → ok; build_runner → ok; run_unit_tests → FAIL → bisect bad
+7. [commit ghi789] pub_get → ok; build_runner → ok; run_unit_tests → PASS → bisect good
+8. [commit jkl012] pub_get → ok; build_runner → ok; run_unit_tests → FAIL → bisect bad
+9. [commit mno345] pub_get → ok; build_runner → ok; run_unit_tests → PASS → bisect good
+10. [commit pqr678] pub_get → ok; build_runner → ok; run_unit_tests → FAIL → bisect bad
+11. git: "pqr678 is the first bad commit"
+12. git show --stat pqr678 → "refactor(billing): collapse invoice state machine"
+13. git bisect reset
+→ Report: first bad commit pqr678, author, date, changed files
+```
+
+## See also
+
+- `flutter-test` — run the full test suite without bisecting
+- `flutter-debug` — inspect live runtime state after bisect identifies a suspect commit
+- `mcp__plugin_flutter_flutter-ultra-build__start_build_runner_build` — build_runner reference
+- `mcp__plugin_flutter_flutter-ultra-patrol__start_patrol_test` — patrol oracle reference

package/skills/debug/SKILL.md

@@ -1,20 +1,156 @@
 ---
-name: debug
+name: flutter-debug
 description: Attaching to a running Flutter app and triaging an error from the stack trace, widget tree, render tree, and recent screenshot. Use when the user reports a runtime exception, layout overflow, or unexpected behaviour and you need to inspect live state.
 ---
 
-# Debug (stub)
+# flutter-debug — Attach, Inspect, and Triage
 
-**Status:** scaffold stub. Implementation owner: wave-3 skills worker (see plan §8.3, §12).
+## When to use
+
+Use this skill when the user reports a runtime exception, a layout overflow, a blank screen, unexpected navigation, or any "it's broken" situation in a running Flutter app. The goal is to collect enough live evidence to diagnose the root cause without guessing. Propose code fixes only after inspecting live state — never before.
+
+## Prerequisites
+
+- A Flutter app is running in debug mode (VM Service available).
+- The user has described the symptom: exception message, screen name, reproduction steps, or "just broke".
+- Do **not** modify any source files during this skill unless the user explicitly asks for a fix.
 
 ## Workflow
 
-- `mcp__flutter-ultra-runtime__discover_sessions` and pick the target app.
-- Pull recent errors with `mcp__flutter-ultra-runtime__get_runtime_errors`.
-- Cross-reference frames with `mcp__flutter-ultra-runtime__get_widget_tree` and `dump_render_tree`.
-- Capture a screenshot for context.
-- Propose a fix inline; do not edit code unless asked.
+Follow the triage ladder in order — stop at the level where the root cause becomes clear.
+
+### 1. Attach to the session
+
+- Call `mcp__plugin_flutter_flutter-ultra-runtime__discover_sessions` — list all active sessions.
+- Pick the session matching the reported app (by name or port).
+- Call `mcp__plugin_flutter_flutter-ultra-runtime__attach` with `sessionId`.
+
+### 2. Capture initial state
+
+Run these together immediately after attach:
+
+- `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` — visual snapshot of the current screen.
+- `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors` — all unhandled exceptions since last clear.
+- `mcp__plugin_flutter_flutter-ultra-runtime__get_logs` — recent `debugPrint` / `print` / framework log output.
+
+### 3. Triage by error type
+
+#### 3a. Runtime exception (stack trace present)
+
+1. Read the stack trace from `get_runtime_errors` — identify the throwing file and line.
+2. Call `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` to inspect the problematic object:
+   ```dart
+   // Example: check if a value is null
+   MyWidget.of(context)?.someField?.toString() ?? 'NULL'
+   ```
+3. Call `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree` focused on the widget subtree around the reported location — pass `widgetId` if known from the stack frame.
+4. Look for: null state, missing providers, incorrect key types, uninitialized controllers.
+
+#### 3b. Layout overflow (RenderFlex / RenderBox overflow)
+
+1. Call `mcp__plugin_flutter_flutter-ultra-runtime__dump_render_tree` — search the output for `OVERFLOWED` or constraint violations.
+2. Call `mcp__plugin_flutter_flutter-ultra-runtime__toggle_debug_paint` to enable visual constraint overlays; take another `screenshot`.
+3. Identify the overflowing `RenderFlex` or `RenderConstrainedBox` and trace it back to the widget via `get_widget_tree`.
+4. Common causes: missing `Expanded`/`Flexible`, fixed height in a `Column` inside a scrollable, `Text` without `overflow: TextOverflow.ellipsis`.
+
+#### 3c. Blank screen / wrong route
+
+1. Call `mcp__plugin_flutter_flutter-ultra-runtime__evaluate`:
+   ```dart
+   GoRouter.of(context).routerDelegate.currentConfiguration.fullPath
+   ```
+   to confirm the actual current route.
+2. Call `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree` from root — look for `ErrorWidget`, empty `SizedBox`, or a redirect loop (same route repeated in the navigator stack).
+3. Check `get_logs` for GoRouter redirect events or `debugPrint` from route guards.
+
+#### 3d. State / data issue (wrong data shown, stale UI)
+
+1. Call `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` to read the current BLoC/Riverpod/Provider state:
+   ```dart
+   context.read<MyBloc>().state.toString()
+   // or for Riverpod:
+   ProviderScope.containerOf(context).read(myProvider).toString()
+   ```
+2. Compare against expected values from the user's description.
+3. Call `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree` to verify the widget rebuilds are reaching the right subtree.
+
+#### 3e. Accessibility / semantics issue
+
+1. Call `mcp__plugin_flutter_flutter-ultra-runtime__dump_semantics_tree` — look for missing labels, incorrect roles, or hidden interactive elements.
+2. Check for `excludeFromSemantics: true` incorrectly applied to interactive widgets.
+
+### 4. Inspect the widget tree around the problem
+
+- Call `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_tree` with the suspected parent widget key or type as anchor.
+- Call `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_details` on a specific widget ID to get its full properties (constraints, size, key, state).
+- Call `mcp__plugin_flutter_flutter-ultra-runtime__find_widget` to locate a specific widget by key or text when the tree is large.
+
+### 5. Deeper render inspection
+
+If layout is the issue and the widget tree alone is not enough:
+
+- Call `mcp__plugin_flutter_flutter-ultra-runtime__dump_render_tree` — this shows sizes, constraints, and positions for every render object.
+- Call `mcp__plugin_flutter_flutter-ultra-runtime__dump_layer_tree` for compositing and repaint boundary issues (useful for performance jank or incorrect clipping).
+
+### 6. Evaluate in-app expressions
+
+Use `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` freely to inspect live objects:
+
+- Check if a future completed: `myCompleter.isCompleted`
+- Read a stream's last value: `myStreamController.stream` (wrap in a Future)
+- Confirm a service is initialized: `MyService.instance != null`
+
+### 7. Test the fix
+
+Once the root cause is identified and a code fix is proposed (or applied at user request):
+
+- Call `mcp__plugin_flutter_flutter-ultra-runtime__hot_reload` to apply changes without losing app state.
+- Repeat step 3 (appropriate branch) to confirm the error is gone.
+- Call `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` for a before/after comparison.
+- If hot reload is not sufficient (e.g. `initState` changed), call `mcp__plugin_flutter_flutter-ultra-runtime__hot_restart`.
+
+## Common patterns and their diagnosis
+
+| Symptom                                    | First tool                                | What to look for                                                     |
+| ------------------------------------------ | ----------------------------------------- | -------------------------------------------------------------------- |
+| `Null check operator used on a null value` | `get_runtime_errors` + `evaluate`         | Null state before async load completes; missing null guard           |
+| `RenderFlex overflowed by N pixels`        | `dump_render_tree` + `toggle_debug_paint` | Column/Row child without `Expanded`; fixed height container          |
+| Blank white screen                         | `get_widget_tree` + `evaluate` (route)    | `ErrorWidget` at root; redirect loop; unhandled exception in build   |
+| `setState called after dispose`            | `get_runtime_errors` + `get_logs`         | Async callback holding stale `BuildContext`; missing `mounted` check |
+| Navigation not working                     | `evaluate` (GoRouter path) + `get_logs`   | Route guard redirecting; wrong named route; deep link not registered |
+| Infinite loading spinner                   | `evaluate` (state) + `get_logs`           | Future never completing; stream not emitting; provider not notifying |
+| Wrong data displayed                       | `evaluate` (BLoC/provider state)          | Stale state; `context.watch` vs `context.read` misuse                |
+
+## Output format
+
+After triage, produce:
+
+1. **Root cause**: one sentence identifying the exact problem.
+2. **Evidence**: which tool output revealed it (stack trace line, widget tree excerpt, render tree constraint).
+3. **Proposed fix**: specific code change with file and line reference (do not edit unless asked).
+4. **Screenshots**: before state screenshot path; after-fix screenshot path if hot_reload was applied.
+
+## Example
+
+```
+User: "The invoices list is showing a blank white screen after I merged the new filter PR."
+
+1. discover_sessions → attach(sessionId: "flutter-1")
+2. screenshot → blank screen confirmed
+3. get_runtime_errors → "Null check operator used on null value at invoice_list_bloc.dart:47"
+4. evaluate: context.read<InvoiceListBloc>().state.toString() → "InvoiceListInitial"
+   (bloc never emitted data — the filter query returned null instead of empty list)
+5. get_widget_tree → root is ErrorWidget wrapping the list scaffold
+6. Root cause: InvoiceListBloc.mapEventToState at line 47 calls `event.filter!` but
+   filter is null on first load after the PR introduced a nullable field.
+7. Proposed fix: change `event.filter!` to `event.filter ?? const InvoiceFilter()` at
+   invoice_list_bloc.dart:47.
+8. hot_reload → screenshot → list loads correctly.
+```
 
 ## See also
 
-- Plan §8.3
+- Sibling skill: `flutter-drive` for driving interactive flows before/after a fix
+- `mcp__plugin_flutter_flutter-ultra-runtime__get_runtime_errors` — unhandled exception log
+- `mcp__plugin_flutter_flutter-ultra-runtime__dump_render_tree` — full render object tree with constraints
+- `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` — arbitrary Dart expression in live app context