See the live app state behind the UI

Inspect exposed runtime objects in your iOS app to understand the state driving its behavior.

Reflection tools let you examine exposed runtime objects when a screen alone does not explain an app’s behavior. Keep roots and traversal narrow, and enable inspection, mutation, or invocation only under the required tool policy.

Install

Published pod: AnsightToolsReflection.

SwiftPM:

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

CocoaPods:

pod 'AnsightToolsReflection'

Register the Suite

import AnsightCore
import AnsightToolsReflection

AnsightReflectionRootRegistry.register(
    id: "session",
    object: sessionViewModel,
    displayName: "Current Session"
)

try AnsightRuntime.shared.registerReflectionTools()

Registration API

AnsightReflectionRootRegistry.register(...): exposes a live object root.
AnsightReflectionRootRegistry.registerGetter(...): exposes a root through a getter.
AnsightReflectionRootRegistry.deregister(...): removes one root.
AnsightReflectionRootRegistry.clear(): removes all roots.
registerReflectionTools(options:): registers the reflection suite.
AnsightReflectionToolsOptions.createBuilder(): creates a suite options builder.
allowRoot(...) / allowTypePrefix(...): narrows reflection traversal.

Specific Concerns

Reflection can expose private state, model graphs, and user data.
Register narrow roots instead of broad application objects.
reflect.set_member_value requires a root-owned AnsightReflectionMutableRoot path.
reflect.invoke_method requires a root-owned AnsightReflectionInvokableRoot path.
List and describe use .read; inspect, set, and invoke use .critical because they can disclose sensitive state or execute arbitrary app code.

Tool Matrix

Name	Id	Policy	Description
`List Reflection Roots`	`reflect.list_roots`	`Read`	Lists registered reflection roots.
`Inspect Object`	`reflect.inspect_object`	`Critical`	Returns a snapshot of a registered root or nested path.
`Describe Type`	`reflect.describe_type`	`Read`	Returns runtime type metadata.
`Set Member Value`	`reflect.set_member_value`	`Critical`	Calls a root-owned `AnsightReflectionMutableRoot` setter path.
`Invoke Method`	`reflect.invoke_method`	`Critical`	Calls a root-owned `AnsightReflectionInvokableRoot` method.

Tool Details

Use read tools to list roots and describe types. Object snapshots, mutation, and invocation use .critical and require an options builder configured with withAllToolAccess() for the local development workflow. Keep roots and type traversal narrow; mutation and invocation still require the root-owned adapters described above.

Root descriptors returned by reflect.list_roots include hostRuntime, which identifies the runtime that owns the root. iOS roots report kind: "swift" with the Swift/Objective-C runtime display name, so clients can route reflection commands to the native runtime boundary instead of inferring ownership from root ids or labels.