# Tools reference

## Recommended design loop

1. Call `get_state` before editing. Read the active file, current selection, variables, tree, and schema summary.
2. Call `get_guidelines()` to list the design guides and styles.
3. Load one task guide and one suitable style with their parameters.
4. Use `get_nodes` when you need full details for specific nodes.
5. Make one coherent atomic change with `batch_edit`.
6. Call `screenshot` and judge the rendered pixels—not only the JSON.
7. Use `snapshot_layout` to catch clipping, overlap, or incorrect sizing.
8. Iterate until the composition is clean, then call `export`.

Do not guess node IDs or edit the `.nibs` file directly while Nib is open.

## Available tools

### `get_state`

Returns the active document path, variables, human selection, and depth-limited tree. The first call from each agent also includes the schema summary.

```json
{ "depth": 3 }
```

### `get_nodes`

Reads nodes by exact ID, case-insensitive name pattern, or both.

```json
{
  "ids": ["hero1", "title"],
  "namePattern": "hero|cta",
  "searchDepth": 2
}
```

### `batch_edit`

Applies all operations atomically and saves the document. If any operation is invalid, none are applied.

```json
{
  "ops": [
    {
      "op": "insert",
      "parentId": null,
      "node": {
        "id": "hero1",
        "type": "frame",
        "name": "Launch Hero",
        "x": 0,
        "y": 0,
        "width": 1440,
        "height": 900,
        "layout": "column",
        "padding": 80,
        "gap": 24,
        "fill": "$surface",
        "children": []
      }
    },
    {
      "op": "insert",
      "parentId": "hero1",
      "node": {
        "id": "title",
        "type": "text",
        "content": "Designed with intent.",
        "font": "Newsreader",
        "size": 88,
        "weight": 600,
        "color": "$text"
      }
    }
  ]
}
```

Supported operations:

- `insert`: `{ op, parentId, index?, node }`. Use `parentId: null` for a top-level node.
- `update`: `{ op, id, props }`. Properties are shallow-merged and revalidated.
- `delete`: `{ op, id }`. Deletes the node and its subtree.
- `move`: `{ op, id, parentId, index? }`. Use `parentId: null` to move to the document root.
- `set_variable`: `{ op, name, value }`.

Important schema rules:

- Every node ID is exactly five characters using letters, digits, `_`, or `-`.
- Top-level nodes require `x` and `y`.
- Nested nodes must not have `x` or `y`; they use their parent frame’s row/column layout.
- Node types are `frame`, `text`, `rect`, `ellipse`, `image`, and `svg`.
- Width and height accept numbers, `fill`, or `hug` where applicable.
- Variables are referenced as `$name` and may contain light/dark values.
- Fills support colors, variables, solid fills, linear/radial gradients, and images.

### `screenshot`

Returns isolated PNG image content for top-level frames.

```json
{ "nodeIds": ["hero1"], "scale": 1 }
```

Use screenshots after every meaningful visual change.

### `export`

Writes every requested frame to a directory. PNG supports exact 1×, 2×, and 3× scales; HTML is self-contained.

```json
{
  "nodeIds": ["hero1", "card1"],
  "dir": "/Users/me/Desktop/nib-exports",
  "format": "png",
  "scales": [1, 2, 3]
}
```

### `get_guidelines`

The guidelines API has three steps:

```json
{}
```

```json
{ "category": "guide", "name": "graphics" }
```

```json
{
  "category": "guide",
  "name": "graphics",
  "params": { "preset": "story-9-16" }
}
```

Task guides: `graphics`, `mobile-app`, and `landing-page`.

Styles: `quiet-linen`, `obsidian-brief`, `broadsheet-noon`, `block-signal`, `cotton-arcade`, `terminal-ledger`, `chamber-ivory`, and `poster-rally`.

### `snapshot_layout`

Returns measured renderer positions and sizes for every node under the requested frames.

```json
{ "frameIds": ["hero1"] }
```

Use it to verify frame bounds, responsive flow, clipping, and spacing after edits.

### `list_projects`

Returns the sidebar tree: projects, loose **Open files**, nested `.nibs` paths, and which file is active.

```json
{}
```

### `open_file`

Opens a `.nibs` path as the active document (same as choosing it in the sidebar).

```json
{ "path": "/Users/you/project/launch.nibs" }
```

### `new_file`

Creates a new document with one starter frame and opens it.

```json
{ "projectFolder": "/Users/you/campaign", "name": "spring-ads" }
```

Or:

```json
{ "path": "/Users/you/Desktop/idea.nibs" }
```

### `duplicate_file` / `rename_file` / `delete_file`

Disk operations on `.nibs` files. Delete moves to Trash and refuses the **active** file until you open another document.

```json
{ "path": "/Users/you/campaign/launch.nibs" }
```

```json
{ "path": "/Users/you/campaign/launch.nibs", "name": "launch-v2.nibs" }
```

## Bundled fonts

These fonts render consistently in the canvas, screenshots, and exports:

- Geist
- Geist Mono
- Inter
- Newsreader
- Playfair Display
- Anton
- IBM Plex Mono

Nib also loads `.ttf` and `.otf` files from an `assets/fonts/` folder beside the active `.nibs` document.