@bdayadev/flutter-ultra-mcp 1.8.0 → 1.9.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.8.0",
+      "version": "1.9.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.8.0"
+  "version": "1.9.0"
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "flutter",
-  "version": "1.8.0",
+  "version": "1.9.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bdayadev/flutter-ultra-mcp",
-  "version": "1.8.0",
+  "version": "1.9.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/skills/design-audit/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: flutter-design-audit
+description: Audit the live Flutter app for design quality issues across accessibility, layout, and design-system conformance. Runs 10 checks (touch targets, semantics, text overflow, layout overflow, hardcoded colors, hardcoded text styles, inconsistent spacing, nested cards, over-centering, tiny text), extracts theme tokens, and tests at 4 responsive breakpoints. Produces a scored markdown report with per-issue fix suggestions.
+---
+
+# Flutter Design Audit
+
+Collect live design evidence from the running app before writing any recommendations. All tools are read-only and safe to run without side effects.
+
+## Workflow
+
+### 1. Attach to the session
+
+- `mcp__plugin_flutter_flutter-ultra-runtime__discover_sessions` — find active sessions.
+- `mcp__plugin_flutter_flutter-ultra-runtime__attach` with the matching sessionId.
+
+### 2. Capture baseline screenshot
+
+- `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` — visual snapshot before audit begins.
+
+### 3. Run full design audit
+
+Run the three audit tools in sequence. Each tool is independent and can be called separately.
+
+#### 3a. Run all design checks
+
+```
+mcp__plugin_flutter_flutter-ultra-runtime__audit_design
+  sessionId: <id>
+  # checks defaults to all 10 — omit for full audit
+```
+
+Checks performed:
+
+| Check                  | Severity | What it detects                               |
+| ---------------------- | -------- | --------------------------------------------- |
+| `touch_targets`        | error    | Tappable widgets < 48×48 dp (WCAG 2.5.5)      |
+| `missing_semantics`    | warning  | Interactive widgets without a Semantics label |
+| `text_overflow`        | warning  | Text widgets clipping or showing ellipsis     |
+| `layout_overflow`      | error    | RenderFlex / RenderBox overflow               |
+| `hardcoded_color`      | info     | Colors not from colorScheme                   |
+| `hardcoded_text_style` | info     | TextStyle with raw fontSize/color             |
+| `inconsistent_spacing` | info     | Padding values not on a 4 dp grid             |
+| `nested_cards`         | warning  | Card inside Card (doubled elevation)          |
+| `everything_centered`  | info     | >80% of Text nodes use TextAlign.center       |
+| `tiny_text`            | warning  | Text with fontSize < 12 dp                    |
+
+Scores returned: `accessibility` (0–100), `layout` (0–100), `designSystem` (0–100).
+
+#### 3b. Extract design tokens
+
+```
+mcp__plugin_flutter_flutter-ultra-runtime__extract_design_tokens
+  sessionId: <id>
+```
+
+Returns:
+
+- `colorScheme` — all Material 3 color roles as hex strings.
+- `textTheme` — fontSize for each text style (displayLarge → labelSmall).
+- `brightness` — `light` or `dark`.
+- `violations` — list of token reads that failed (evaluate unavailable).
+
+#### 3c. Responsive audit at 4 breakpoints
+
+```
+mcp__plugin_flutter_flutter-ultra-runtime__audit_responsive
+  sessionId: <id>
+  # viewports defaults to compact/medium/expanded/large
+```
+
+Default viewports:
+
+| Label    | Size     |
+| -------- | -------- |
+| compact  | 375×667  |
+| medium   | 768×1024 |
+| expanded | 1200×800 |
+| large    | 1440×900 |
+
+Returns per-viewport issue counts and `crossViewportIssues` identifying regressions across breakpoints.
+
+Note: viewport resizing requires a web or desktop debug build. On mobile/release builds, results reflect the current native window size.
+
+### 4. Capture per-viewport screenshots (optional)
+
+If the responsive audit shows regressions, take a screenshot at each problematic viewport to document the issue:
+
+```
+mcp__plugin_flutter_flutter-ultra-runtime__screenshot
+  sessionId: <id>
+  width: 375
+  height: 667
+```
+
+### 5. Deeper investigation for specific issues
+
+#### Touch target failures
+
+1. `mcp__plugin_flutter_flutter-ultra-runtime__find_widget` with `finder: { type: 'InkWell' }` to locate all tappable areas.
+2. `mcp__plugin_flutter_flutter-ultra-runtime__get_widget_details` on the failing widget to confirm its bounds.
+3. `mcp__plugin_flutter_flutter-ultra-runtime__toggle_debug_paint` to visualise hit-test areas.
+
+#### Layout overflow
+
+1. `mcp__plugin_flutter_flutter-ultra-runtime__dump_render_tree` — search for `OVERFLOWED`.
+2. `mcp__plugin_flutter_flutter-ultra-runtime__toggle_debug_paint` to show overflow markers.
+3. `mcp__plugin_flutter_flutter-ultra-runtime__screenshot` — capture the debug paint view.
+
+#### Semantics gaps
+
+1. `mcp__plugin_flutter_flutter-ultra-runtime__dump_semantics_tree` — find nodes without labels.
+2. On mobile: `mcp__plugin_flutter_flutter-ultra-native-mobile__dump_a11y_tree` for the OS-level accessibility tree.
+
+#### Hardcoded colors / text styles
+
+1. `mcp__plugin_flutter_flutter-ultra-runtime__evaluate` to inspect a specific widget's style:
+   ```dart
+   // Example: read the actual color of a Text widget's style
+   (context.findRenderObject() as RenderParagraph).text.style?.color?.value.toRadixString(16)
+   ```
+2. Compare against `extract_design_tokens` output to identify deviations.
+
+## Output format
+
+Produce a markdown report with the following sections:
+
+### Design Audit Report
+
+**App:** `<sessionId>`
+**Date:** `<today>`
+**Scores:** Accessibility: X/100 | Layout: Y/100 | Design System: Z/100
+
+#### Issues (N total — E errors, W warnings, I info)
+
+| Severity | Rule          | Widget     | Issue                          | Suggestion               |
+| -------- | ------------- | ---------- | ------------------------------ | ------------------------ |
+| error    | touch_targets | IconButton | 32×32 dp — below 48 dp minimum | Wrap in SizedBox(48, 48) |
+| ...      |               |            |                                |                          |
+
+#### Design Tokens
+
+**Color Scheme (brightness: light)**
+
+| Role    | Hex     |
+| ------- | ------- |
+| primary | #006590 |
+| ...     |         |
+
+**Text Theme**
+
+| Style        | Size  |
+| ------------ | ----- |
+| displayLarge | 57 dp |
+| ...          |       |
+
+#### Responsive Analysis
+
+| Viewport | Size     | Issues |
+| -------- | -------- | ------ |
+| compact  | 375×667  | 3      |
+| medium   | 768×1024 | 2      |
+| ...      |          |        |
+
+**Cross-viewport regressions:** `<crossViewportIssues list or "None">`
+
+#### Screenshots
+
+- Baseline: `<path>`
+- compact viewport: `<path if captured>`
+
+## Common fix patterns
+
+| Issue                  | Fix                                                                                         |
+| ---------------------- | ------------------------------------------------------------------------------------------- |
+| Touch target too small | `SizedBox(width: 48, height: 48, child: icon)` or `IconButton(padding: EdgeInsets.all(12))` |
+| Missing semantics      | `Semantics(label: 'Close dialog', child: icon)`                                             |
+| Text overflow          | `Text(str, maxLines: 2, overflow: TextOverflow.ellipsis)` inside `Flexible`                 |
+| Layout overflow        | Replace `Row` with `Wrap`, or add `Flexible`/`Expanded` to children                         |
+| Hardcoded color        | Replace `Color(0xFF006590)` with `Theme.of(context).colorScheme.primary`                    |
+| Hardcoded TextStyle    | Replace `TextStyle(fontSize: 16)` with `Theme.of(context).textTheme.bodyLarge`              |
+| Nested Cards           | Replace inner `Card` with `Container` + `decoration: BoxDecoration(borderRadius: ...)`      |
+| Over-centering         | Use `TextAlign.start` for body copy; reserve `center` for headings                          |
+| Tiny text              | Increase to ≥ 12 dp, or use `textTheme.labelSmall` (14 dp minimum by M3 spec)               |
+| Inconsistent spacing   | Use `const EdgeInsets.all(8)` / `16` / `24` — multiples of 4                                |
+
+## See also
+
+- `flutter-debug` — triage runtime exceptions and layout overflows in detail
+- `flutter-tour` — navigate the app to audit each screen systematically

package/skills/design-verify/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: flutter-design-verify
+description: Compare a running Flutter app against Figma mockups. Captures screenshots at multiple viewports, extracts theme tokens and component inventory, then uses Claude vision to identify design-implementation drift between the live app and Figma frames.
+---
+
+# Flutter Design Verify
+
+Compare a live Flutter app against Figma designs. Collect evidence from both sources, then produce a side-by-side report identifying drift.
+
+## Prerequisites
+
+- Flutter app is running in debug mode (web or desktop for viewport resizing).
+- Figma MCP plugin is installed and authenticated (`mcp__plugin_figma_figma__authenticate`).
+- User has the Figma file URL containing the design frames.
+
+## Workflow
+
+### 1. Attach to the running Flutter session
+
+```
+mcp__plugin_flutter_flutter-ultra-runtime__discover_sessions
+```
+
+Pick the matching session, then:
+
+```
+mcp__plugin_flutter_flutter-ultra-runtime__attach
+  sessionId: <id>
+```
+
+### 2. Capture Flutter screenshots
+
+Capture the current screen, then navigate to each route and repeat:
+
+```
+mcp__plugin_flutter_flutter-ultra-runtime__screenshot
+  sessionId: <id>
+  width: 375
+  height: 667
+```
+
+Capture at relevant viewports (compact 375×667, medium 768×1024, expanded 1200×800) using `audit_responsive` as a guide for which breakpoints show regressions.
+
+### 3. Extract Flutter design tokens
+
+```
+mcp__plugin_flutter_flutter-ultra-runtime__extract_design_tokens
+  sessionId: <id>
+```
+
+Returns `colorScheme`, `textTheme`, and `brightness`. These become the Flutter side of the token diff.
+
+### 4. Extract component inventory
+
+```
+mcp__plugin_flutter_flutter-ultra-runtime__extract_component_inventory
+  sessionId: <id>
+```
+
+Returns per-type widget counts grouped by category (input / container / display / layout / navigation). Use this to map Flutter components to Figma component usage.
+
+### 5. Run design audit (optional but recommended)
+
+```
+mcp__plugin_flutter_flutter-ultra-runtime__audit_design
+  sessionId: <id>
+```
+
+Pre-flight check — surface existing issues before comparing against Figma.
+
+```
+mcp__plugin_flutter_flutter-ultra-runtime__audit_responsive
+  sessionId: <id>
+```
+
+Identify which viewports have the most drift so Figma frame selection can match.
+
+### 6. Retrieve Figma designs
+
+Ask the user for the Figma file URL if not already provided.
+
+#### 6a. Get Figma frame screenshots
+
+```
+mcp__plugin_figma_figma__get_screenshot
+  url: <figma-frame-url>
+```
+
+Capture one screenshot per screen / frame that corresponds to the Flutter routes captured in step 2. Match by route name or frame title.
+
+#### 6b. Get Figma design tokens (variables)
+
+```
+mcp__plugin_figma_figma__get_variable_defs
+  url: <figma-file-url>
+```
+
+Returns color, typography, spacing, and radius variables. These become the Figma side of the token diff.
+
+### 7. Vision comparison
+
+Present each Flutter screenshot alongside its matching Figma frame to Claude for visual analysis. For each pair, identify:
+
+- **Color drift** — buttons, backgrounds, text colors that differ.
+- **Typography drift** — font sizes, weights, line heights that differ.
+- **Spacing drift** — padding, gap, margin inconsistencies.
+- **Missing components** — UI elements present in Figma but absent in Flutter.
+- **Extra components** — UI elements in Flutter not in Figma (scope creep).
+- **Layout drift** — column/row arrangements, alignment, wrapping differences.
+
+### 8. Token diff
+
+Compare `extract_design_tokens` output against `get_variable_defs` output:
+
+| Token               | Flutter value | Figma value | Match? |
+| ------------------- | ------------- | ----------- | ------ |
+| primary color       | #006590       | #006591     | NO     |
+| bodyMedium fontSize | 14 dp         | 14 sp       | YES    |
+| ...                 |               |             |        |
+
+Flag every mismatch as a drift item with severity:
+
+- **error** — value differs by more than 10% or is a completely different hue.
+- **warning** — value differs by ≤ 10% (rounding or unit conversion).
+- **info** — token present in Flutter but missing from Figma variables, or vice versa.
+
+### 9. Component mapping
+
+Cross-reference `extract_component_inventory` output against Figma component usage:
+
+- List Flutter components with no Figma counterpart.
+- List Figma components with no Flutter counterpart.
+- Flag count mismatches (e.g., Flutter has 14 ElevatedButton instances, Figma frame shows 2).
+
+## Output format
+
+Produce a markdown report:
+
+### Design Verification Report
+
+**Flutter session:** `<sessionId>`
+**Figma file:** `<url>`
+**Date:** `<today>`
+
+#### Visual Comparison
+
+For each Flutter route ↔ Figma frame pair:
+
+| Screen | Flutter screenshot | Figma frame | Drift items |
+| ------ | ------------------ | ----------- | ----------- |
+| /home  | (image)            | (image)     | 3 errors    |
+
+#### Token Diff Table
+
+| Token   | Flutter | Figma   | Status  |
+| ------- | ------- | ------- | ------- |
+| primary | #006590 | #006591 | warning |
+
+#### Component Mapping
+
+| Type           | Flutter count | In Figma? | Notes                   |
+| -------------- | ------------- | --------- | ----------------------- |
+| ElevatedButton | 14            | yes       | Figma shows 2 per frame |
+
+#### Summary
+
+- Total drift items: N (E errors, W warnings, I info)
+- Token mismatches: N
+- Missing Figma components in Flutter: N
+- Recommendation: list top 3 highest-impact fixes
+
+## See also
+
+- `flutter-design-audit` — standalone Flutter design quality audit without Figma
+- `flutter-figma-push` — push Flutter web screenshots to Figma as editable frames
+- `flutter-tour` — navigate all routes for comprehensive per-screen capture

package/skills/figma-push/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: flutter-figma-push
+description: Push Flutter web app UI to Figma as editable layers. Navigates to each route, captures the browser view, and uses the Figma MCP to create editable Figma frames from the live app screenshots.
+disable-model-invocation: true
+---
+
+# Flutter Figma Push
+
+Push screenshots of a running Flutter web app into Figma as editable frames. Web only — requires a browser-accessible Flutter app.
+
+## Prerequisites
+
+- Flutter web app is running and accessible via a browser URL.
+- Figma MCP plugin is installed and authenticated.
+- User has an existing Figma file URL to push frames into (or a new file will be created).
+
+## Workflow
+
+### 1. Confirm the app is running
+
+```
+mcp__plugin_flutter_flutter-ultra-runtime__discover_sessions
+```
+
+If no session is found, ask the user for the browser URL of the Flutter web app directly.
+
+### 2. Connect the browser
+
+```
+mcp__plugin_flutter_flutter-ultra-browser__launch_browser
+```
+
+Then navigate to the Flutter web app URL:
+
+```
+mcp__plugin_flutter_flutter-ultra-browser__navigate
+  url: <flutter-web-app-url>
+```
+
+If the app is already open in a browser, connect over CDP instead:
+
+```
+mcp__plugin_flutter_flutter-ultra-browser__connect_over_cdp
+  wsEndpoint: <devtools-ws-url>
+```
+
+### 3. Collect the route list
+
+Ask the user for the list of routes to capture, or infer from the app's navigation structure via:
+
+```
+mcp__plugin_flutter_flutter-ultra-runtime__find_widget
+  sessionId: <id>
+  finder: { type: 'Navigator' }
+```
+
+Typical routes to capture: `/`, `/home`, `/profile`, `/settings`, and any primary feature screens.
+
+### 4. For each route — capture and push
+
+Repeat this sequence for every route:
+
+#### 4a. Navigate
+
+```
+mcp__plugin_flutter_flutter-ultra-browser__navigate
+  url: <flutter-web-app-url>/<route>
+```
+
+#### 4b. Wait for Flutter render to settle
+
+```
+mcp__plugin_flutter_flutter-ultra-browser__wait_for_url
+  url: <expected-url>
+```
+
+Allow 1–2 seconds for animations to complete. Check console for any errors:
+
+```
+mcp__plugin_flutter_flutter-ultra-browser__console_logs
+```
+
+#### 4c. Take a browser screenshot
+
+```
+mcp__plugin_flutter_flutter-ultra-browser__screenshot
+```
+
+This captures the full browser viewport as rendered by the Flutter web engine.
+
+#### 4d. Push to Figma
+
+```
+mcp__plugin_figma_figma__generate_figma_design
+  url: <figma-file-url>
+  imageData: <screenshot-data>
+  frameName: <route-name>
+```
+
+The Figma MCP creates an editable frame from the screenshot. The frame name should match the route (e.g., `Flutter / home`, `Flutter / settings`).
+
+### 5. Capture at multiple viewports (optional)
+
+For responsive design, repeat step 4 at each breakpoint by resizing the browser viewport via JavaScript:
+
+```
+mcp__plugin_flutter_flutter-ultra-browser__evaluate_js
+  expression: "window.resizeTo(375, 667)"
+```
+
+Then re-navigate and push with a viewport-suffixed frame name (e.g., `Flutter / home / compact`).
+
+Standard breakpoints: compact (375×667), medium (768×1024), expanded (1200×800).
+
+### 6. Report
+
+After all routes are pushed, produce a summary:
+
+```
+## Figma Push Complete
+
+| Route | Viewport | Figma frame | Status |
+| ----- | -------- | ----------- | ------ |
+| /home | 375×667  | Flutter / home / compact | created |
+| /home | 1200×800 | Flutter / home / expanded | created |
+| ...   |          |             |        |
+
+Figma file: <url>
+Total frames created: N
+```
+
+Include the Figma file URL so the user can open it directly.
+
+## Notes
+
+- This skill is web-only. Mobile screenshots require `mcp__plugin_flutter_flutter-ultra-native-mobile__take_device_screenshot` and cannot be pushed directly to Figma via the browser path.
+- CanvasKit (default Flutter web renderer) renders to a `<canvas>` element — the browser screenshot captures the correct visual output.
+- If `generate_figma_design` is unavailable, fall back to `mcp__plugin_figma_figma__use_figma` to upload the screenshot as an image asset.
+
+## See also
+
+- `flutter-design-verify` — compare Flutter screenshots against existing Figma frames for drift detection
+- `flutter-design-audit` — run design quality checks on the live Flutter app

package/skills/record-demo/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: record-demo
+description: Records a video or GIF demo of a Flutter app flow. Detects platform (web browser or native device), starts recording, drives the UI interaction, stops recording, then converts to the requested format (MP4, WebM, or GIF). Use when the user asks to record a demo, capture a flow as video, or produce an animated GIF of app behavior.
+---
+
+# Record Demo
+
+Orchestrates platform detection → start recording → drive flow → stop recording → convert format.
+
+## Workflow
+
+### 1. Detect platform
+
+Determine recording method based on the running target:
+
+- **Web** — use `mcp__plugin_flutter_flutter-ultra-browser__new_context` with `recordVideo.dir` set to a local output directory. Playwright records all pages automatically; video is saved on `mcp__plugin_flutter_flutter-ultra-browser__close_context`.
+- **Android device** — use `mcp__plugin_flutter_flutter-ultra-native-mobile__start_device_recording` with an `outputPath` ending in `.mp4`.
+- **iOS Simulator** — use `mcp__plugin_flutter_flutter-ultra-native-mobile__start_device_recording` with an `outputPath` ending in `.mp4`.
+
+Discover running sessions first:
+
+```
+mcp__plugin_flutter_flutter-ultra-runtime__discover_sessions
+```
+
+Check `device.kind` in the response: `'web'` → browser path, `'android'` / `'ios-sim'` → native path.
+
+### 2. Start recording
+
+#### Web (Playwright recordVideo)
+
+```
+mcp__plugin_flutter_flutter-ultra-browser__new_context
+  browserId: <id>
+  recordVideo:
+    dir: /tmp/flutter-demo-recordings
+    size:          # optional — omit to use viewport size
+      width: 1280
+      height: 800
+```
+
+Returns `contextId` and `recordingDir`. Then open a tab and navigate to the app URL.
+
+#### Native device (Android / iOS)
+
+```
+mcp__plugin_flutter_flutter-ultra-native-mobile__start_device_recording
+  deviceId: <udid>
+  outputPath: /tmp/flutter-demo.mp4
+  maxDurationSec: 60
+```
+
+Returns `recordingId`. Keep it for the stop call.
+
+### 3. Drive the UI flow
+
+Use the appropriate tools to exercise the flow being recorded:
+
+- **Runtime** — `mcp__plugin_flutter_flutter-ultra-runtime__hot_reload`, `mcp__plugin_flutter_flutter-ultra-runtime__evaluate`, `mcp__plugin_flutter_flutter-ultra-runtime__find_widget`
+- **Browser** — `mcp__plugin_flutter_flutter-ultra-browser__click`, `mcp__plugin_flutter_flutter-ultra-browser__fill`, `mcp__plugin_flutter_flutter-ultra-browser__navigate`
+- **Native** — `mcp__plugin_flutter_flutter-ultra-native-mobile__native_tap`, `mcp__plugin_flutter_flutter-ultra-native-mobile__native_type`, `mcp__plugin_flutter_flutter-ultra-native-mobile__native_swipe`
+
+For responsive demos, resize the viewport between key interactions:
+
+- Mobile: 390×844
+- Tablet: 768×1024
+- Desktop: 1440×900
+
+Take screenshots at key moments for verification alongside the recording.
+
+### 4. Stop recording
+
+#### Web
+
+```
+mcp__plugin_flutter_flutter-ultra-browser__close_context
+  contextId: <id>
+```
+
+Returns `videoPath` — the `.webm` file Playwright wrote to `recordingDir`.
+
+#### Native device
+
+```
+mcp__plugin_flutter_flutter-ultra-native-mobile__stop_device_recording
+  recordingId: <id>
+```
+
+Returns `path` and `durationMs`.
+
+### 5. Convert to target format
+
+Use `mcp__plugin_flutter_flutter-ultra-build__convert_recording` to convert to the user's desired format:
+
+#### High-quality GIF (for sharing in docs / GitHub)
+
+```
+mcp__plugin_flutter_flutter-ultra-build__convert_recording
+  inputPath: /tmp/flutter-demo.mp4
+  outputPath: /tmp/flutter-demo.gif
+  outputFormat: gif
+  maxWidth: 800
+  fps: 12
+```
+
+#### Compressed MP4 (for embedding in web pages)
+
+```
+mcp__plugin_flutter_flutter-ultra-build__convert_recording
+  inputPath: /tmp/flutter-demo.webm
+  outputPath: /tmp/flutter-demo.mp4
+  outputFormat: mp4
+  maxWidth: 1280
+  quality: 23
+```
+
+#### WebM (smallest size, web-native)
+
+```
+mcp__plugin_flutter_flutter-ultra-build__convert_recording
+  inputPath: /tmp/flutter-demo.mp4
+  outputPath: /tmp/flutter-demo.webm
+  outputFormat: webm
+  quality: 30
+```
+
+### 6. Report result
+
+Return the output file path, size in bytes, and format. Suggest next steps:
+
+- Embed GIF in README with `![demo](./flutter-demo.gif)`
+- Upload MP4 as a GitHub release asset
+- Use WebM in `<video>` tags on web landing pages
+
+## Notes
+
+- ffmpeg must be installed for `convert_recording`. If not found, the tool returns a clear installation hint.
+- Android `screenrecord` has a 180-second hard limit. For longer demos, restart recording in segments.
+- iOS Simulator recording requires macOS with Xcode installed.
+- Playwright writes `.webm` by default; pass it directly to `convert_recording` for format changes.
+- For CanvasKit Flutter web, ensure semantics are enabled before driving UI with browser tools.