VisualTree

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

Install

Published pod: AnsightToolsVisualTree.

SwiftPM:

.product(name: "AnsightToolsVisualTree", package: "ansight-sdk")

CocoaPods:

pod 'AnsightToolsVisualTree', '1.4.0-preview.1'

Register the Suite

import AnsightCore
import AnsightToolsVisualTree

try AnsightRuntime.shared.registerVisualTreeTools()

Registration API

registerVisualTreeTools(): registers the full UIKit visual tree, screenshot, and diagnostic overlay suite.
.readOnly: exposes visual tree, screenshot, node inspection, and read-only overlay tools.
.readWrite: also exposes overlay creation, update, removal, and clearing.

Visual-Tree Providers

AnsightVisualTreeProviderRegistry always exposes the UIKit hierarchy as native. Additional UI frameworks can implement AnsightVisualTreeProvider and register their own stable source:

import AnsightToolsVisualTree

try AnsightVisualTreeProviderRegistry.register(
    customProvider,
    replaceExisting: true
)

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

Objective-C hosts can register the same model through ANSVisualTreeProvider.

Specific Concerns

The tools inspect the foreground UIKit scene.
Screenshot capture exports rendered UI content.
ui.get_screenshot streams bytes over the binary transfer channel; the result returns transfer metadata.
Node inspection can expose labels, accessibility metadata, and implementation-specific properties.
Overlay tools draw input-transparent diagnostic rectangles.
Persistent overlays created with durationMs = 0 stay visible until removed or cleared.

Important: Calling screenshot tools will result in an FPS drop while the current frame is rendered, 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 UIKit hierarchy for the foreground scene.
`Get Screenshot`	`ui.get_screenshot`	`Read`	Captures a screenshot and streams bytes over binary transfer.
`Inspect Node`	`ui.inspect_node`	`Read`	Returns detailed metadata for one visual tree node.
`Show Overlay`	`ui.show_overlay`	`Write`	Draws a diagnostic overlay.
`Get Overlay`	`ui.get_overlay`	`Read`	Returns one overlay.
`Query Overlays`	`ui.query_overlays`	`Read`	Lists live diagnostic overlays.
`Update Overlay`	`ui.update_overlay`	`Write`	Updates an existing overlay.
`Remove Overlay`	`ui.remove_overlay`	`Write`	Removes one overlay.
`Clear Overlays`	`ui.clear_overlays`	`Write`	Clears diagnostic overlays.

Tool Details

Get Visual Tree

Use ui.get_visual_tree to capture the current hierarchy. Typical arguments include a provider source, bounds, computed-style inclusion, maximum depth, maximum nodes, and an optional root node id. The response includes a capture-local types registry referenced by node typeId values plus normalized roles, actions, state, presentation, and sibling order. See the Visual-Tree Payload Contract.

Get Screenshot

Use ui.get_screenshot for an on-demand screenshot. The app streams image bytes over ansight.file-transfer.v1; the resident host uses transferId to map the binary frames.

Inspect Node

Use ui.inspect_node with a visual tree nodeId and optional provider source to return one node, optional ancestors, optional descendants, and implementation-specific properties.

Overlay Tools

Use ui.show_overlay, ui.update_overlay, ui.remove_overlay, and ui.clear_overlays to draw and manage diagnostic overlays. Use ui.get_overlay or ui.query_overlays to inspect overlays without mutation.