flutter_cockpit #

简体中文

flutter_cockpit is the in-app runtime for AI-driven Flutter development.

It provides:

• runtime bootstrap through FlutterCockpit.runApp or FlutterCockpitApp
• command execution for taps, text input, gestures, waits, assertions, screenshots, and snapshots
• remote session serving over HTTP
• snapshot, artifact, recording, and bundle models
• target, plane, surface, and fallback-aware runtime models for AI-first summaries

Install #

Requires Flutter 3.32.0 or newer.

dependencies:
  flutter_cockpit: ^1.0.0

If only cockpit/main.dart imports the runtime, prefer putting flutter_cockpit under dev_dependencies. Use production dependencies only for an explicit shared-entrypoint or shipped-runtime integration.

The runtime package declares native plugin entries for Android, iOS, macOS, Linux, Windows, and web. That lets app-window screenshots and recording fallbacks register consistently whenever the cockpit entrypoint is compiled. Keep the integration low-intrusion by importing it from cockpit/main.dart instead of production lib/ code unless the host app explicitly ships a shared runtime entrypoint. Flutter-view screenshots, semantic control, network signals, runtime diagnostics, and remote sessions work in-app. System dialogs, notifications, host screenshots, and host recordings should still be driven by cockpit system actions so capability discovery and platform fallbacks remain truthful.

Recommended Integration #

Keep the normal production entrypoint unchanged and add cockpit/main.dart. Do not add flutter_cockpit imports to production lib/ code.

import 'package:flutter/material.dart';
import 'package:flutter_cockpit/flutter_cockpit_flutter.dart';

import 'package:your_app/app_shell.dart';

Future<void> main() async {
  runApp(buildCockpitDevelopmentApp());
}

Widget buildCockpitDevelopmentApp() {
  return FlutterCockpitApp(
    config: FlutterCockpitConfig.production(
      remoteSession: CockpitRemoteSessionConfiguration.resolveFromEnvironment(
        fallback: const CockpitRemoteSessionConfiguration(
          enabled: true,
          host: '127.0.0.1',
          port: 47331,
        ),
      ),
    ),
    child: MaterialApp(
      navigatorObservers: <NavigatorObserver>[
        FlutterCockpit.navigatorObserver,
      ],
      home: const AppShell(),
    ),
  );
}

Replace package:your_app/app_shell.dart with the import that already exposes your app root widget or bootstrap. launch-app injects the FLUTTER_COCKPIT_REMOTE_* dart-defines, so resolveFromEnvironment(...) enables the remote surface without taking over the production bootstrap. Only wire FlutterCockpit.navigatorObserver inside a navigator created by the cockpit entrypoint, or in a shared entrypoint the host explicitly accepts. If your production app already owns MaterialApp, GoRouter, or another router, wrap the existing root with FlutterCockpitApp from cockpit/main.dart and keep route synchronization in that cockpit layer, for example by listening to the app router and calling FlutterCockpit.setCurrentRouteName(...).

Run it with:

flutter run -t cockpit/main.dart

What The Runtime Exposes #

• low-intrusion root bootstrap
• command routing and execution
• UI snapshots with bounded diagnostics
• accessibility, network, runtime, and rebuild signals
• screenshot and recording requests
• remote session status and command endpoints

Host-side orchestration, MCP, workspace tooling, and delivery validation live in cockpit. The runtime bundle models now preserve targetKind, primaryExecutionPlane, planesUsed, surfaceKindsUsed, fallbackCount, plus per-step and per-observation plane metadata so host-side tooling can explain when Flutter control stayed on-plan versus when it had to degrade to another surface. On web, the runtime supports the Flutter semantic and Flutter-view control path directly, while the method channels are registered as explicit unavailable stubs so capability checks stay truthful instead of failing through missing-plugin noise. On mobile and desktop, native method-channel recording and capture register through the package plugin entries and are used as app-window evidence fallbacks; prefer system or host evidence through cockpit when the goal is to prove system dialogs, notifications, host windows, or cross-app behavior.

Package page: pub.dev/packages/flutter_cockpit