@bdayadev/flutter-ultra-mcp 0.0.0

package/dart/ultra_flutter/EXTENSIONS.md

@@ -0,0 +1,61 @@
+# `ext.flutter.ultra.*` VM service extension catalogue
+
+Every extension below is registered by `UltraFlutterBinding.initServiceExtensions()` when the binding is active. All extensions return a JSON envelope with `type: '_extensionType'`, `method`, and `status: 'Success'` on success; errors map to standard `developer.ServiceExtensionResponse` codes (`extensionErrorMin..extensionErrorMin+16` for typed errors, `invalidParams` for bad input).
+
+## Parity matrix vs marionette
+
+| `ext.flutter.ultra.*` | marionette equivalent            | Notes                                                                                |
+| --------------------- | -------------------------------- | ------------------------------------------------------------------------------------ |
+| `getVersion`          | `marionette.getVersion`          | Returns `{version: <semver>}` from `src/version.g.dart`.                             |
+| `interactiveElements` | `marionette.interactiveElements` | Returns `{elements: [...]}` from `ElementTreeFinder`.                                |
+| `tap`                 | `marionette.tap`                 | Body: `WidgetMatcher` JSON (`key`/`text`/`type`/`x`+`y`/`focused`).                  |
+| `doubleTap`           | `marionette.doubleTap`           | Optional `delay` (ms, positive). Default 100ms.                                      |
+| `longPress`           | `marionette.longPress`           | Optional `duration` (ms). Default 600ms.                                             |
+| `enterText`           | `marionette.enterText`           | Requires `input` plus a matcher.                                                     |
+| `clearText`           | _(new — enhancement)_            | Convenience wrapper around `enterText('')`. Saves agents two round-trips.            |
+| `swipe`               | `marionette.swipe`               | Either coord-based (`startX/Y` + `endX/Y`) or element + `direction` + `distance`.    |
+| `pinchZoom`           | `marionette.pinchZoom`           | Required `scale`, optional `startDistance` (default 200).                            |
+| `scrollTo`            | `marionette.scrollTo`            | Scrolls until the matched widget is visible.                                         |
+| `getLogs`             | `marionette.getLogs`             | Requires a `LogCollector` in `UltraConfiguration`.                                   |
+| `takeScreenshots`     | `marionette.takeScreenshots`     | Returns one screenshot per `RenderView`.                                             |
+| `startScreencast`     | `marionette.startScreencast`     | Optional `maxWidth`, `maxHeight`, `wsPort`.                                          |
+| `stopScreencast`      | `marionette.stopScreencast`      | Idempotent.                                                                          |
+| `pressBackButton`     | `marionette.pressBackButton`     | Returns `didPop`.                                                                    |
+| `listExtensions`      | `marionette.listExtensions`      | Returns user-registered custom extensions (registered via `registerUltraExtension`). |
+
+15 extensions in total: 14 ported + 1 enhancement (`clearText`).
+
+## Adding a custom extension
+
+```dart
+import 'package:ultra_flutter/ultra_flutter.dart';
+
+void registerMyExtensions() {
+  registerUltraExtension(
+    name: 'myApp.fetchProfile', // becomes `ext.flutter.myApp.fetchProfile`
+    description: 'Returns the currently-signed-in profile snapshot.',
+    callback: (params) async {
+      final id = params['id'];
+      if (id == null) {
+        return UltraExtensionResult.invalidParams('Missing "id"');
+      }
+      // ...
+      return UltraExtensionResult.success({'profile': {/* ... */}});
+    },
+  );
+}
+```
+
+Call `registerMyExtensions()` after `AppBinding.ensureInitialized()` and before `runApp()`. Custom extensions show up in the `listExtensions` response so the MCP server can advertise them to the LLM.
+
+## Why `ext.flutter.ultra.*` and not `ext.ultra.*`
+
+Flutter's DevTools and `package:vm_service` only allow registration under `ext.flutter.*` — the `flutter.` prefix is hard-coded by `developer.registerExtension` validation in our `register_extension_internal.dart`. The `ultra` second segment is our namespace.
+
+## Planned future extensions
+
+- `ultra.waitFor` — server-side polling that resolves when a matcher hits (saves agents N round-trips).
+- `ultra.scrollUntilVisible` — single-call hybrid of `scrollTo` + `waitFor` for stubborn lazy lists.
+- `ultra.matcher` — hierarchical matchers (`{type: 'TextField', ancestor: {key: 'login_form'}}`).
+
+Tracked at plan §6.1; not in 0.0.1-dev.

package/dart/ultra_flutter/README.md

@@ -0,0 +1,109 @@
+# ultra_flutter
+
+In-app Flutter binding mixin that exposes `ext.flutter.ultra.*` VM service
+extensions used by the `flutter-ultra-mcp` Claude Code plugin. AI agents
+attach via the Dart VM Service and drive your app — taps, text input,
+scroll, screenshots, screencast, logs, hot reload, custom RPCs — without
+any flutter_driver instrumentation.
+
+A composable fork of [`marionette_flutter`][marionette] v0.5.0 with one
+critical UX win: the binding is a **mixin** (`mixin UltraFlutterBinding on
+WidgetsBinding`) instead of a class, so it stacks cleanly onto other
+`WidgetsFlutterBinding` subclasses (Sentry, integration_test, etc).
+
+[marionette]: https://github.com/leancodepl/marionette_mcp
+
+## Install
+
+```yaml
+dev_dependencies:
+  ultra_flutter: ^0.0.1-dev.1
+```
+
+(Only `dev_dependencies` — the binding code is fully tree-shaken out of
+release builds when guarded behind `kDebugMode`.)
+
+## Usage
+
+### Simple — no other custom binding
+
+```dart
+import 'package:flutter/foundation.dart';
+import 'package:flutter/widgets.dart';
+import 'package:ultra_flutter/ultra_flutter.dart';
+
+Future<void> main() async {
+  if (kDebugMode) {
+    UltraFlutterBinding.ensureInitialized();
+  } else {
+    WidgetsFlutterBinding.ensureInitialized();
+  }
+  runApp(const MyApp());
+}
+```
+
+### Composed with Sentry
+
+Mix in `SentryWidgetsBindingMixin` directly alongside `UltraFlutterBinding`:
+
+```dart
+import 'package:flutter/widgets.dart';
+import 'package:sentry_flutter/sentry_flutter.dart';
+import 'package:ultra_flutter/ultra_flutter.dart';
+// ignore: implementation_imports
+import 'package:sentry_flutter/src/binding_wrapper.dart';
+
+class AppBinding extends WidgetsFlutterBinding
+    with SentryWidgetsBindingMixin, UltraFlutterBinding {}
+
+Future<void> main() async {
+  AppBinding.ensureInitialized();
+  await SentryFlutter.init(
+    (options) => options.dsn = '<your dsn>',
+    appRunner: () => runApp(const MyApp()),
+  );
+}
+```
+
+This sidesteps the historical marionette↔Sentry "must be the only binding"
+race — both instrumentations live on a single composed binding instance,
+no singleton race needed.
+
+### Configuration
+
+```dart
+UltraFlutterBinding.setUltraConfiguration(
+  UltraConfiguration(
+    isInteractiveWidget: (type) => type.toString() == 'MyCustomButton',
+    extractText: (element) {
+      final widget = element.widget;
+      if (widget is MyCustomLabel) return widget.labelText;
+      return null;
+    },
+    logCollector: PrintLogCollector(), // or LoggingLogCollector, etc.
+    maxScreenshotSize: const Size(2000, 2000),
+  ),
+);
+UltraFlutterBinding.ensureInitialized(); // or your AppBinding subclass
+```
+
+Configuration **must** be set BEFORE the binding initializes (i.e. before
+the first `runApp` / `ensureInitialized`). The mixin form can't take
+constructor arguments, so the static slot pattern is required.
+
+## Extensions
+
+See [EXTENSIONS.md](EXTENSIONS.md) for the full catalogue of
+`ext.flutter.ultra.*` service extensions and how to register your own
+custom ones.
+
+## License
+
+Apache-2.0. This is a fork of `marionette_flutter` (also Apache-2.0); see
+top-level [LICENSE](../../LICENSE) and `NOTICE`.
+
+## Status
+
+Pre-1.0. Mixin shape stable; further extensions (`waitFor`,
+`scrollUntilVisible`, hierarchical matchers) tracked in the plan §6.1
+followups.

package/dart/ultra_flutter/pubspec.yaml

@@ -0,0 +1,37 @@
+name: ultra_flutter
+description: >-
+  In-app Flutter binding mixin exposing ext.flutter.ultra.* VM service
+  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: 0.0.1-dev.1
+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
+topics:
+  - mcp
+  - ai
+  - claude
+  - agent
+  - testing
+
+publish_to: none
+
+environment:
+  sdk: '>=3.6.0 <4.0.0'
+  flutter: '>=3.27.0'
+
+resolution: workspace
+
+dependencies:
+  flutter:
+    sdk: flutter
+  web: ^1.1.0
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter
+  test: '>=1.24.0'
+
+flutter:
+  uses-material-design: false

package/dart/ultra_flutter_devtools/README.md

@@ -0,0 +1,7 @@
+# ultra_flutter_devtools
+
+Flutter DevTools extension UI for the `flutter-ultra-mcp` plugin. Shows live MCP activity: attached sessions, recent tool calls, errors, screenshot grid.
+
+**Status:** scaffold stub. Implementation owner: **wave-2 devtools worker** (see plan §12, §6.2).
+
+Loaded by Flutter DevTools as an iframe extension. Pairs with the [`flutter-ultra-devtools`](../../packages/flutter-ultra-devtools/) MCP server which tails `state/tool-events.jsonl` and pushes events over WebSocket.

package/dart/ultra_flutter_devtools/pubspec.yaml

@@ -0,0 +1,27 @@
+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: 0.1.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
+
+publish_to: none
+
+environment:
+  sdk: ^3.5.0
+  flutter: '>=3.24.0'
+
+resolution: workspace
+
+dependencies:
+  flutter:
+    sdk: flutter
+  devtools_extensions: ^0.3.0
+  devtools_app_shared: ^0.3.0
+  web: ^1.1.0
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter

package/docs/UPSTREAM-PATROL-PRS.md

@@ -0,0 +1,5 @@
+# Upstream Patrol PRs
+
+Placeholder. **Wave-4 worker M** populates this document with the upstream Patrol PRs we open against [`leancodepl/patrol`](https://github.com/leancodepl/patrol) from the Bdaya patrol fork at `vendor/patrol/` — including PR URLs, status, the corresponding fork commits, and the rebase-back-to-bdaya-main plan for the merged ones.
+
+See plan §12 wave 4 for the full schedule.

package/docs/UPSTREAM-SENTRY-PR.md

@@ -0,0 +1,62 @@
+# Upstream Sentry PR — expose `SentryWidgetsBindingMixin`
+
+## Status
+
+**Not filed yet.** Tracked as Path A per `flutter-ultra-mcp-v1.md` §6.1.
+Filing this PR is opportunistic cleanup, not a blocker for v1.
+
+## Current state
+
+`package:sentry_flutter/sentry_flutter.dart` (v9.20.0) declares:
+
+```dart
+export 'src/binding_wrapper.dart'
+    show BindingWrapper, SentryWidgetsFlutterBinding;
+```
+
+The `show` clause hides `SentryWidgetsBindingMixin` from the public API
+even though the mixin is defined in the same file. Consumers reach it via a
+deliberate `// ignore: implementation_imports` import of
+`package:sentry_flutter/src/binding_wrapper.dart`.
+
+## Proposed change
+
+Extend the `show` clause to include the mixin:
+
+```dart
+export 'src/binding_wrapper.dart'
+    show BindingWrapper, SentryWidgetsFlutterBinding, SentryWidgetsBindingMixin;
+```
+
+The mixin is already used as a typedef inside other public Sentry classes,
+so exposing it is a non-breaking change.
+
+## Motivation
+
+Composability. Multiple Flutter ecosystem packages (testing harnesses,
+debug bindings, AI-agent automation like ultra_flutter) need to mix
+Sentry's binding instrumentation alongside their own. Today they either:
+
+1. Subclass `SentryWidgetsFlutterBinding` (cannot also compose another
+   `WidgetsFlutterBinding` subclass — Dart `with` requires a mixin), OR
+2. Reach into `package:sentry_flutter/src/binding_wrapper.dart` directly
+   with `// ignore: implementation_imports` (brittle, breaks the visibility
+   contract).
+
+Making the mixin public moves option 2 from "private reach-through" to
+"sanctioned composition".
+
+## Risks
+
+- Surface-area expansion: once public, the mixin name + signature are
+  versioned. Sentry maintainers would need to follow semver on it.
+- Misuse: users might mix the mixin onto unusual base classes and hit
+  internal-state assumptions. Counter: the mixin already encapsulates its
+  state cleanly (`_isTrackingActive`, `_options`, etc.) and gracefully
+  degrades when the rest of Sentry isn't wired.
+
+## When to file
+
+After `ultra_flutter` ships v1.0 and we have at least one real consumer
+demonstrating the composition pattern. PR will reference the
+ultra_flutter use case as the concrete motivation.