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.0.2-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.

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 performance measurements unless visual evidence is required.

Tool Matrix

Name	Id	Scope	Description	Security
`Get Visual Tree`	`ui.get_visual_tree`	`Read`	Returns the current UIKit hierarchy for the foreground scene.	High
`Get Screenshot`	`ui.get_screenshot`	`Read`	Captures a screenshot and streams bytes over binary transfer.	High
`Inspect Node`	`ui.inspect_node`	`Read`	Returns detailed metadata for one visual tree node.	High
`Show Overlay`	`ui.show_overlay`	`Write`	Draws a diagnostic overlay.	Critical
`Get Overlay`	`ui.get_overlay`	`Read`	Returns one overlay.	High
`Query Overlays`	`ui.query_overlays`	`Read`	Lists live diagnostic overlays.	High
`Update Overlay`	`ui.update_overlay`	`Write`	Updates an existing overlay.	Critical
`Remove Overlay`	`ui.remove_overlay`	`Write`	Removes one overlay.	Critical
`Clear Overlays`	`ui.clear_overlays`	`Write`	Clears diagnostic overlays.	Critical

Tool Details

Get Visual Tree

Use ui.get_visual_tree to capture the current UIKit hierarchy. Typical arguments include bounds, computed-style inclusion, maximum depth, and an optional root node id.

Get Screenshot

Use ui.get_screenshot for an on-demand screenshot. The app streams image bytes over ansight.file-transfer.v1; Studio and the MCP bridge use transferId to map the binary frames.

Inspect Node

Use ui.inspect_node with a visual tree nodeId 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.