Add Flutter runtime inspector support

Author: DjDeveloperr

.gitignore

@@ -9,6 +9,8 @@ packages/inspector-agent/.build/
 packages/inspector-agent/.swiftpm/
 packages/nativescript-inspector/dist/
 packages/react-native-inspector/dist/
+packages/flutter-inspector/.dart_tool/
+packages/flutter-inspector/pubspec.lock
 docs/.vitepress/dist/
 docs/.vitepress/cache/
 cloud/

AGENTS.md

@@ -48,6 +48,10 @@ The native side should own anything that depends on macOS frameworks, `xcrun sim
   React Native in-app inspector runtime that connects to the Rust server over
   WebSocket, publishes React Fiber component hierarchies with Metro source
   locations, and performs best-effort debug JS/native prop edits.
+- `packages/flutter-inspector/lib/simdeck_flutter_inspector.dart`
+  Flutter in-app inspector runtime that connects to the Rust server over
+  WebSocket, publishes widget/render/semantics hierarchies with debug creation
+  locations, and performs best-effort semantics, focus, text, and scroll actions.
 
 ## Working Rules
 
@@ -56,6 +60,7 @@ The native side should own anything that depends on macOS frameworks, `xcrun sim
 - Keep browser-only presentation logic in `client/`.
 - Keep NativeScript app runtime inspection logic in `packages/nativescript-inspector/`.
 - Keep React Native app runtime inspection logic in `packages/react-native-inspector/`.
+- Keep Flutter app runtime inspection logic in `packages/flutter-inspector/`.
 - Prefer adding a native API endpoint before adding client-only assumptions.
 - Do not add a Node or Swift dependency to solve work that already fits in Foundation/AppKit.
 - When touching private API usage, keep the adaptation small and explicit and document any simulator/runtime assumptions here.

README.md

@@ -39,7 +39,7 @@ view inside the editor.
 - Full simulator control & inspection using private accessibility APIs - available using `simdeck` CLI
 - Real-time screen `describe` command using accessibility view tree - available in token-efficient format for agents
 - CoreSimulator chrome asset rendering for device bezels
-- NativeScript, React Native, UIKit and SwiftUI runtime inspector plugins to view app's view hierarchy live
+- NativeScript, React Native, Flutter, UIKit and SwiftUI runtime inspector plugins to view app's view hierarchy live
 - `simdeck/test` for fast JS/TS app tests that can query accessibility state and drive simulator controls.
 - SimDeck Studio for sharing Simulator streams & automatic PR deployments to on-demand simulators
 
@@ -182,9 +182,10 @@ booting is unavailable.
 `stream` writes an Annex B H.264 elementary stream to stdout for diagnostics or
 external tools such as `ffplay`.
 
-`describe` uses the project daemon to prefer React Native, NativeScript, or
-UIKit in-app inspectors, then falls back to the built-in private CoreSimulator
-accessibility bridge. Use `--format agent` or `--format compact-json` for
+`describe` uses the project daemon to prefer React Native, NativeScript,
+Flutter, or UIKit in-app inspectors, then falls back to the built-in private
+CoreSimulator accessibility bridge. Use `--format agent` or
+`--format compact-json` for
 lower-token hierarchy dumps. Coordinate commands accept screen coordinates from
 the accessibility tree by default; pass `--normalized` to send `0.0..1.0`
 coordinates directly.
@@ -241,6 +242,27 @@ so the package can capture React Fiber commits. The auto entrypoint no-ops
 outside development, reads `EXPO_PUBLIC_SIMDECK_PORT` when present, and
 otherwise scans common SimDeck daemon ports.
 
+## Flutter Inspector
+
+Flutter apps can expose their widget tree, render frames, semantics metadata,
+and debug widget creation locations with the Flutter inspector package:
+
+```dart
+import 'package:flutter/foundation.dart';
+import 'package:flutter/widgets.dart';
+import 'package:simdeck_flutter_inspector/simdeck_flutter_inspector.dart';
+
+void main() {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  if (kDebugMode) {
+    startSimDeckFlutterInspector(port: 4310);
+  }
+
+  runApp(const App());
+}
+```
+
 ## VS Code
 
 Install the `nativescript.simdeck-vscode` extension from the VS Code Marketplace, then

client/src/api/types.ts

@@ -118,6 +118,7 @@ export interface AccessibilityNode {
   enabled?: boolean | null;
   frame?: AccessibilityFrame | null;
   frameInScreen?: AccessibilityFrame | null;
+  flutter?: Record<string, unknown> | null;
   help?: string | null;
   imageName?: string | null;
   inspectorId?: string | null;
@@ -132,11 +133,13 @@ export interface AccessibilityNode {
   role?: string | null;
   role_description?: string | null;
   scroll?: Record<string, unknown> | null;
+  semantics?: Record<string, unknown> | null;
   source?:
     | "native-ax"
     | "in-app-inspector"
     | "nativescript"
     | "react-native"
+    | "flutter"
     | "swiftui"
     | string
     | null;
@@ -161,6 +164,7 @@ export type AccessibilitySource =
   | "in-app-inspector"
   | "nativescript"
   | "react-native"
+  | "flutter"
   | "swiftui";
 export type AccessibilitySourcePreference = AccessibilitySource | "auto";
 

client/src/app/uiState.ts

@@ -29,6 +29,7 @@ export const TOUCH_OVERLAY_VISIBLE_STORAGE_KEY = "xcw-touch-overlay-visible";
 const ACCESSIBILITY_SOURCE_ORDER: AccessibilitySource[] = [
   "nativescript",
   "react-native",
+  "flutter",
   "swiftui",
   "in-app-inspector",
   "native-ax",
@@ -153,6 +154,7 @@ export function isAccessibilitySource(
   return (
     value === "nativescript" ||
     value === "react-native" ||
+    value === "flutter" ||
     value === "swiftui" ||
     value === "in-app-inspector" ||
     value === "native-ax"

client/src/features/accessibility/AccessibilityInspector.tsx

@@ -467,6 +467,7 @@ function NodeDetails({
     ["Module", node.moduleName ?? ""],
     ["NativeScript", nativeScriptDescription(node.nativeScript)],
     ["React Native", reactNativeDescription(node.reactNative)],
+    ["Flutter", flutterDescription(node.flutter)],
     ["UIKit Class", node.className ?? ""],
     ["Last JS", lastUIKitScriptText(node)],
     ["Value", node.AXValue ?? ""],
@@ -727,6 +728,7 @@ function errorMessage(error: unknown): string {
 const HIERARCHY_SOURCE_ORDER: AccessibilitySource[] = [
   "nativescript",
   "react-native",
+  "flutter",
   "swiftui",
   "in-app-inspector",
   "native-ax",
@@ -756,6 +758,9 @@ function sourceLabel(source: AccessibilitySource): string {
   if (source === "react-native") {
     return "React Native";
   }
+  if (source === "flutter") {
+    return "Flutter";
+  }
   if (source === "swiftui") {
     return "SwiftUI";
   }
@@ -795,6 +800,17 @@ function reactNativeDescription(
   return [tag, testID, nativeID].filter(Boolean).join(" / ");
 }
 
+function flutterDescription(value: Record<string, unknown> | null | undefined) {
+  if (!value) {
+    return "";
+  }
+  const widgetType =
+    typeof value.widgetType === "string" ? value.widgetType : "";
+  const stateType = typeof value.stateType === "string" ? value.stateType : "";
+  const key = typeof value.key === "string" ? value.key : "";
+  return [widgetType, stateType, key].filter(Boolean).join(" / ");
+}
+
 function lastUIKitScriptText(node: AccessibilityNode): string {
   const direct = stringRecordValue(node.uikitScript, "script");
   if (direct) {

client/src/styles/components.css

@@ -624,6 +624,12 @@
   color: color-mix(in srgb, #61dafb 78%, var(--text));
 }
 
+.hierarchy-source-pill.source-flutter {
+  border-color: color-mix(in srgb, #54c5f8 50%, var(--border));
+  background: color-mix(in srgb, #54c5f8 14%, transparent);
+  color: color-mix(in srgb, #54c5f8 80%, var(--text));
+}
+
 .hierarchy-source-pill.source-swiftui {
   border-color: color-mix(in srgb, #ff6b9d 50%, var(--border));
   background: color-mix(in srgb, #ff6b9d 14%, transparent);

docs/.vitepress/config.mts

@@ -135,6 +135,10 @@ export default defineConfig({
               text: "React Native Runtime",
               link: "/inspector/react-native",
             },
+            {
+              text: "Flutter Runtime",
+              link: "/inspector/flutter",
+            },
           ],
         },
       ],

docs/api/inspector-protocol.md

@@ -122,7 +122,7 @@ Params:
 { "includeHidden": false, "maxDepth": 20, "source": "uikit" }
 ```
 
-By default the agent returns the published framework hierarchy (e.g. NativeScript) when one exists. Pass `"source": "uikit"` to force the raw UIKit tree.
+By default the agent returns the published framework hierarchy (for example NativeScript, React Native, Flutter, or SwiftUI) when one exists. Pass `"source": "uikit"` to force the raw UIKit tree when the runtime supports UIKit inspection.
 
 Published framework nodes may include `sourceLocation`:
 

docs/api/rest.md

@@ -442,6 +442,7 @@ Returns the current accessibility tree. The server merges framework inspectors,
 | `auto` _(default)_ / unset   | Use the most accurate source available, falling back to AX.                                            |
 | `nativescript` / `ns`        | Force the NativeScript logical tree if a NativeScript inspector is connected for the foreground app.   |
 | `react-native` / `rn`        | Force the React Native component tree if a React Native inspector is connected for the foreground app. |
+| `flutter` / `fl`             | Force the Flutter widget tree if a Flutter inspector is connected for the foreground app.              |
 | `swiftui` / `swift-ui`       | Force the published SwiftUI logical tree if the Swift agent root publisher is installed in the app.    |
 | `uikit` / `in-app-inspector` | Force the raw UIKit hierarchy from the in-app inspector agent (NativeScript or Swift).                 |
 | `native-ax` / `ax`           | Always use the native accessibility snapshot.                                                          |
@@ -456,8 +457,8 @@ The response always includes:
 ```json
 {
   "roots": [...],
-  "source": "nativescript|react-native|swiftui|in-app-inspector|native-ax",
-  "availableSources": ["nativescript", "react-native", "swiftui", "in-app-inspector", "native-ax"],
+  "source": "nativescript|react-native|flutter|swiftui|in-app-inspector|native-ax",
+  "availableSources": ["nativescript", "react-native", "flutter", "swiftui", "in-app-inspector", "native-ax"],
   "fallbackReason": "...",
   "inspector": { ... }
 }