# Needle Inspector Agent — Tool Documentation

This file is auto-generated alongside `agent.js` and describes all available APIs and tools.
Inject `agent.js` into any page with a Three.js scene to access these tools via `window.__NEEDLE_INSPECTOR__`.

> **IMPORTANT: All API methods are async and return Promises. You MUST use `await` when calling them.**
> Calling without `await` returns a Promise object (`{}`) instead of the actual data.

## Setup

```js
// Guaranteed path: install before the application constructs Three.js objects.
await page.addInitScript({ url: 'https://inspector.needle.tools/agent.js' });

// Wait for scene detection
await page.waitForFunction(() => window.__NEEDLE_INSPECTOR__?.ready);
```

## API Methods

All methods are available on `window.__NEEDLE_INSPECTOR__` and return Promises.
**You MUST `await` every call**, either inside an async `page.evaluate` or by awaiting the result.

### `ready: boolean`

True once the inspector has detected a Three.js scene and booted its services.

```js
await page.waitForFunction(() => window.__NEEDLE_INSPECTOR__?.ready);
```

### `getTools(): Promise<ToolDefinition[]>`

Return the authoritative runtime tool names, descriptions, and JSON input schemas.

```js
const tools = await page.evaluate(() => window.__NEEDLE_INSPECTOR__.getTools());
```

### `callTool(name: string, args?: object): Promise<unknown>`

Call a registered runtime tool.

```js
const result = await page.evaluate(() =>
  window.__NEEDLE_INSPECTOR__.callTool("hierarchy_search_nodes", { query: "player" })
);
```

### `getHierarchy(maxDepth?: number): Promise<SerializedNode[]>`

Get the scene hierarchy. Addressable nodes carry a TARGET for subsequent tool calls.

```js
const tree = await page.evaluate(() => window.__NEEDLE_INSPECTOR__.getHierarchy(3));
```

### `getSelectedNodes(): Promise<SerializedNode[]>`

Get the currently selected hierarchy nodes and their TARGETs.

```js
const selected = await page.evaluate(() => window.__NEEDLE_INSPECTOR__.getSelectedNodes());
```

### `selectNode(target: TARGET): Promise<{ success: boolean; message?: string }>`

Select the hierarchy node named by a TARGET returned from this API.

```js
await page.evaluate(target => window.__NEEDLE_INSPECTOR__.selectNode(target), target);
```

### `searchNodes(query: string, maxResults?: number): Promise<SerializedNode[]>`

Search nodes by name. Prefer hierarchy_search_nodes for the complete model-facing contract.

```js
const nodes = await page.evaluate(() => window.__NEEDLE_INSPECTOR__.searchNodes("player"));
```

### `getProperties(target: TARGET): Promise<FindPropertiesResult>`

Get properties for a TARGET returned by a search or resource tool.

```js
const props = await page.evaluate(target =>
  window.__NEEDLE_INSPECTOR__.getProperties(target), target
);
```

### `findProperties(args: { targets?, nodeQuery?, propertyQuery?, includeValues? }): Promise<FindPropertiesResult>`

Search properties through the runtime property_find tool.

```js
const found = await page.evaluate(target =>
  window.__NEEDLE_INSPECTOR__.findProperties({ targets: [target], propertyQuery: "position" }), target
);
```

### `readProperty(target: TARGET, propertyPath: string): Promise<ReadPropertyResult>`

Read one property from a TARGET returned by a search or resource tool.

```js
const value = await page.evaluate(target =>
  window.__NEEDLE_INSPECTOR__.readProperty(target, "position.x"), target
);
```

## Node Format

Hierarchy nodes are returned as:

```json
{
  "target": {
    "address": {
      "type": "node",
      "id": "stable-id"
    }
  },
  "name": "string",
  "type": "string (e.g. Mesh, Light, Camera, Scene)",
  "label": "string",
  "visible": true,
  "selected": false,
  "expanded": false,
  "childCount": 0,
  "children": [
    "(nested nodes, if within maxDepth)"
  ]
}
```

## Tools

Call tools via `callTool(name, args)`. Always obtain the authoritative names, descriptions, and JSON schemas from `getTools()` at runtime; this document deliberately does not duplicate them.

## Typical Workflow

```js
// 1. Inject and wait
await page.addInitScript({ url: 'https://inspector.needle.tools/agent.js' });
await page.waitForFunction(() => window.__NEEDLE_INSPECTOR__?.ready);

// 2. Explore the scene (note: await inside evaluate!)
const tree = await page.evaluate(async () => await window.__NEEDLE_INSPECTOR__.getHierarchy(3));

// 3. Find a node and keep its TARGET verbatim
const search = await page.evaluate(() => window.__NEEDLE_INSPECTOR__.callTool(
  "hierarchy_search_nodes", { query: "player" }
));
const target = search.results[0].target;

// 4. Inspect its properties
const props = await page.evaluate(target => window.__NEEDLE_INSPECTOR__.getProperties(target), target);

// 5. Read a specific value
const pos = await page.evaluate(target => window.__NEEDLE_INSPECTOR__.readProperty(target, "position.x"), target);
```