Tools

Add React Native native tool suites, React inspection tools, artifact providers, JavaScript custom tools, or native custom tools, gate them with ToolGuard, and keep them limited to local development workflows.

React Native exposes native tool suites from iOS and Android plus JavaScript-backed and native custom tools registered in app code.

Important Security Rule

Do not ship broad native tools, JavaScript custom tools, or React action tools in App Store, Play Store, CI release, or other distributable builds unless the capability is explicitly approved.

Do this:

enable broad tools only behind an app-owned local development condition
use the narrowest guard that works for the workflow
keep React props, state, actions, secure storage, and file-system access opt-in

Do not do this:

ship fullAccess broadly
enable React actions unless a workflow explicitly needs them
expose secret, file, or runtime mutation tools without allow-lists

Native Tool Registration

The native bridge registers FileSystem, Database, Preferences, Reflection, and SecureStorage suites during initialization. VisualTree is opt-in because it exposes rendered UI structure and screenshots. Suite-specific options flow through remoteTools.

await Ansight.initializeAndActivate(
  Ansight.createOptionsBuilder()
    .withReadOnlyToolAccess()
    .withVisualTreeTools()
    .withDatabaseTools({
      includePlatformRoots: true,
      additionalRoots: [{ alias: "fixtures", path: "/tmp/app-db" }],
    })
    .withFileSystemTools({
      additionalRoots: [{ alias: "exports", path: "/tmp/app-exports" }],
    })
    .withPreferencesTools({
      allowedStores: ["standard"],
      allowedKeyPrefixes: ["debug."],
    })
    .withReflectionTools({
      includeBuiltInRoots: true,
      allowedRootIds: ["application"],
      allowedTypePrefixes: ["com.example."],
    })
    .withRemoteTools({
      secureStorage: {
        allowedKeys: ["debug_token"],
        allowedKeyPrefixes: ["debug."],
      },
    })
    .build(),
);

secureStorage.preferencesName is Android-specific. secureStorage.appleService is iOS-specific. The top-level secureStorage option is accepted as a compatibility alias for remoteTools.secureStorage.

Suite Registration API

Surface	Common API
VisualTree	`withVisualTreeTools()`, `remoteTools.visualTree`
Native Database	`withDatabaseTools(...)`, `remoteTools.database`
Native FileSystem	`withFileSystemTools(...)`, `remoteTools.fileSystem`
Native Preferences	`withPreferencesTools(...)`, `remoteTools.preferences`
Native SecureStorage	`withRemoteTools({ secureStorage: ... })`, `remoteTools.secureStorage`, top-level `secureStorage` alias
Native Reflection	`withReflectionTools(...)`, `remoteTools.reflection`
React Inspection	`installReactTools(...)`, `uninstallReactTools()`
JavaScript Custom Tools	`registerTool(...)`, `unregisterTool(...)`, `listRegisteredTools()`, `clearRegisteredTools()`
Native Custom Tools	iOS `AnsightRuntime.shared.registerTool(...)`, Android `AnsightRuntime.registerTool(...)`
Artifacts	`registerArtifactProvider(...)`, `registerArtifactProviders(...)`, `unregisterArtifactProvider(...)`, `clearArtifactProviders()`

Guard Levels

Guard	What it allows
`withToolsDisabled()` / `"disabled"`	No discovery, no execution.
`withReadOnlyToolAccess()` / `"readOnly"`	Read-scoped tools only.
`withReadWriteToolAccess()` / `"readWrite"`	Read and write tools. Delete tools remain blocked.
`withAllToolAccess()` / `"fullAccess"`	Read, write, and delete tools.

Tool Suites

Native tool ids match the underlying iOS and Android SDKs. Artifacts are documented separately in Artifacts.

Suite	Typical use
VisualTree	Inspect native hierarchy, capture screenshots, and manage overlays.
Database	Discover SQLite databases, inspect schema, and run read-only queries.
FileSystem	List directories, read files, download files, push, copy, move, and delete files inside approved roots.
Preferences	Read and mutate native preferences under store/key allow-lists.
SecureStorage	Read and mutate native secure storage under explicit key allow-lists.
Reflection	Inspect native registered roots and built-in roots according to platform support and options.
React Inspection	Inspect React Fiber component trees, React Native host trees, navigation state, and optional component actions.
JavaScript Custom Tools	Expose narrow app-specific development operations.
Native Custom Tools	Expose narrow app-specific Swift or Kotlin operations.

Recommended Defaults

For most teams:

Start with installReactTools(...) without props, state, or actions.
Use withReadOnlyToolAccess() by default.
Add native VisualTree only when Studio needs platform view hierarchy or native screenshots.
Add Database only when SQLite inspection is needed.
Add FileSystem, Preferences, or SecureStorage only for a specific debugging workflow.
Add Artifacts when app-specific output should become a streamed file or durable session artifact.
Add JavaScript or native custom tools only for narrow operations that packaged suites cannot cover.
Add React actions, native writes, and delete-scoped tools only when the workflow genuinely depends on them.