Understand what your app is showing

VisualTree tools connect what you see on screen with the elements that make up the live UI. Use hierarchy snapshots, focused node inspection, and screenshots to investigate layout or content problems.

AnsightFlutterInstrumentation.install() registers Flutter handlers and calls enableFlutterVisualTreeProvider(). The shared visual-tree suite can then return Flutter as a source alongside the platform-native hierarchy. On macOS, the Flutter source is the supported UI hierarchy; native AppKit inspection and actions are not currently available.

Enable native tools in the runtime:

final options = createOptionsBuilder()
    .withRemoteTools(
      const AnsightRemoteToolsOptions(visualTree: true),
    )
    .withReadOnlyToolAccess()
    .build();

Use ui.get_visual_tree to discover sources and capture the tree, ui.inspect_node for node details, and ui.get_screenshot for an on-demand image. Native and Flutter sources use the shared compact visual-tree v2 contract, including a top-level types registry, node typeId references, semantic roles/actions, stable string ValueKey automation ids, and platform-neutral presentation data. Overlay tools are available when the native provider supports them.

For recorded macOS evidence, wrap the visible app in AnsightFlutterCaptureBoundary. Each automatic frame captured in screenshotAndVisualTree mode includes a timestamp-correlated tree rooted at that boundary. The traversal covers mounted descendants, including the visible contents of scrollable views; limits are recorded explicitly if a tree is ever truncated.

For Flutter-specific search and route state, use Flutter Inspection. Widget labels, keys, text, diagnostics, and layout bounds may contain sensitive app data.