VisualTree

Register the native Android VisualTree tool suite to inspect the view hierarchy, capture screenshots, and manage diagnostic overlays.

Install

Published artifact: ai.ansight:ansight-tools-visualtree-android.

dependencies {
    debugImplementation("ai.ansight:ansight-tools-visualtree-android:1.4.0-preview.1")
}

Register the Suite

import ai.ansight.runtime.AnsightOptions
import ai.ansight.tools.visualtree.withVisualTreeTools

val options = AnsightOptions.createBuilder()
    .withVisualTreeTools()
    .withReadOnlyToolAccess()
    .build()

Registration API

withVisualTreeTools(): registers the visual tree, screenshot, and diagnostic overlay suite.
AndroidVisualTreeTools.create(): creates the suite tools for lower-level registration.
withReadOnlyToolAccess(): exposes visual tree, screenshot, node inspection, and read-only overlay tools.
withReadWriteToolAccess(): also exposes overlay creation, update, removal, and clearing; every overlay mutation uses Write.

Visual-Tree Providers

AndroidVisualTreeProviderRegistry always exposes the Android view hierarchy as native. Additional UI frameworks can implement AndroidVisualTreeProvider and register their own stable source:

import ai.ansight.tools.visualtree.AndroidVisualTreeProviderRegistry

AndroidVisualTreeProviderRegistry.register(
    provider = customProvider,
    replaceExisting = true,
)

The provider supplies source, displayName, getVisualTree(...), and inspectNode(...). Pass source to ui.get_visual_tree or ui.inspect_node; omitting it selects native. Responses use the shared compact visual-tree v2 contract.

Specific Concerns

The native provider captures every top-level Android window root owned by the foreground activity, including dialogs and popup windows when present.
Screenshot capture exports rendered UI content.
ui.get_screenshot streams bytes over the binary transfer channel.
Overlay removal tools use Write consistently across platforms.

Important: Calling screenshot tools will result in an FPS drop while the current frame is captured, encoded, and transferred. Avoid screenshot-heavy investigations during trend measurements unless visual evidence is required.

Tool Matrix

Name	Id	Policy	Description
`Get Visual Tree`	`ui.get_visual_tree`	`Read`	Returns the current visual hierarchy for the requested source.
`Get Screenshot`	`ui.get_screenshot`	`Read`	Captures a screenshot and streams bytes over binary transfer.
`Inspect Node`	`ui.inspect_node`	`Read`	Returns one node from the current visual tree.
`Show Overlay`	`ui.show_overlay`	`Write`	Shows a rectangular diagnostic overlay.
`Get Overlay`	`ui.get_overlay`	`Read`	Returns one diagnostic overlay.
`Query Overlays`	`ui.query_overlays`	`Read`	Lists active diagnostic overlays.
`Update Overlay`	`ui.update_overlay`	`Write`	Updates a diagnostic overlay.
`Remove Overlay`	`ui.remove_overlay`	`Write`	Removes a diagnostic overlay.
`Clear Overlays`	`ui.clear_overlays`	`Write`	Clears diagnostic overlays.

Tool Details

Use read tools for inspection and screenshots. ui.get_visual_tree and ui.inspect_node accept an optional source argument for provider selection. Their responses include a top-level types registry referenced by each node’s typeId, semantic roles and actions, automation ids, presentation data, and structural child order. See the Visual-Tree Payload Contract. Use write tools only when the session needs to create, update, remove, or clear overlays remotely.