# SmartArt

## Actions

| Tool | Action | Parameters | Notes |
|------|--------|------------|-------|
| `smartart` | `add-smart-art` | `session_id`, `slide_index`, `layout_name`, `left`, `top`, `width`, `height` | Creates a SmartArt diagram shape using a built-in gallery layout, identified by name (see below). Returns `shapeIndex`, `layoutName`, and `nodeCount` (the layout's default node count). |
| `smartart` | `add-node` | `session_id`, `slide_index`, `shape_index`, `text` | Adds a new top-level (root) node with the given text, appended after the existing top-level nodes. Returns `nodeIndex` and the new `nodeCount`. |
| `smartart` | `add-child-node` | `session_id`, `slide_index`, `shape_index`, `parent_node_index`, `text` | Adds a new node nested one level below `parent_node_index`, appended after that parent's existing children. Returns `nodeIndex` and the new `nodeCount`. |
| `smartart` | `set-node-text` | `session_id`, `slide_index`, `shape_index`, `node_index`, `text` | Sets the text of an existing node. |
| `smartart` | `get-node-text` | `session_id`, `slide_index`, `shape_index`, `node_index` | Returns the text of an existing node. |
| `smartart` | `delete-node` | `session_id`, `slide_index`, `shape_index`, `node_index` | Deletes a node (and any of its children). Returns the new `nodeCount`. |
| `smartart` | `get-node-count` | `session_id`, `slide_index`, `shape_index` | Returns the total number of nodes, flat across the whole hierarchy. |

## Layout Names

`layout_name` is the SmartArt gallery's stable, human-readable display name — not a numeric
position or file path. Common examples:

| Category | Example layout names |
|----------|----------------------|
| Process | `"Basic Process"`, `"Step Up Process"`, `"Continuous Block Process"` |
| Cycle | `"Basic Cycle"`, `"Continuous Cycle"` |
| Hierarchy | `"Organization Chart"`, `"Horizontal Hierarchy"` |
| List | `"Basic Block List"`, `"Vertical Bullet List"` |
| Pyramid | `"Basic Pyramid"` |
| Relationship | `"Basic Venn"`, `"Balance"` |

An unrecognized `layout_name` returns `Success=false` — the exact set of available names depends
on the installed Office version/language, so when in doubt, confirm the name is spelled exactly as
it appears in PowerPoint's own **Insert → SmartArt** gallery (case-insensitive match is tolerated).

## Node Addressing

Nodes are addressed by their **1-based position in the diagram's flat node list**
(`SmartArt.AllNodes`, in document order across the whole hierarchy) — the same order PowerPoint's
own object model already uses, not an invented per-level or path-based scheme. After
`add-smart-art`, use `get-node-count`/`get-node-text` to discover the layout's default node
positions before editing them.

## Building a Diagram

```
smartart(action: "add-smart-art", session_id: ..., slide_index: ...,
  layout_name: "Basic Process", left: 60, top: 120, width: 500, height: 250)
## → shapeIndex, nodeCount (e.g. 3 default placeholder nodes)

smartart(action: "set-node-text", session_id: ..., slide_index: ..., shape_index: <shapeIndex>,
  node_index: 1, text: "Plan")
smartart(action: "set-node-text", session_id: ..., slide_index: ..., shape_index: <shapeIndex>,
  node_index: 2, text: "Build")
smartart(action: "set-node-text", session_id: ..., slide_index: ..., shape_index: <shapeIndex>,
  node_index: 3, text: "Ship")

## Need a 4th step? Append a new top-level node instead of assuming a 4th slot already exists:
smartart(action: "add-node", session_id: ..., slide_index: ..., shape_index: <shapeIndex>,
  text: "Iterate")
```

## Hierarchy Diagrams (Organization Chart)

`"Organization Chart"` starts with a single root node — build out reports using `add-child-node`
against the root (or an existing child, for a deeper tree):

```
smartart(action: "add-smart-art", session_id: ..., slide_index: ...,
  layout_name: "Organization Chart", left: 60, top: 100, width: 500, height: 350)
## → shapeIndex, nodeCount = 1 (just the root)

smartart(action: "set-node-text", session_id: ..., slide_index: ..., shape_index: <shapeIndex>,
  node_index: 1, text: "CEO")

smartart(action: "add-child-node", session_id: ..., slide_index: ..., shape_index: <shapeIndex>,
  parent_node_index: 1, text: "VP Engineering")
smartart(action: "add-child-node", session_id: ..., slide_index: ..., shape_index: <shapeIndex>,
  parent_node_index: 1, text: "VP Sales")
```

## Removing Nodes

`delete-node` removes the target node and any of its descendants — always call `get-node-count`
(or check the `nodeCount` from a prior response) before deleting, and re-resolve node positions
afterward rather than assuming subsequent indices are unchanged (a delete shifts every later
node's flat position down by however many nodes were removed).

## Verify Visually

Diagram layout, spacing, and text overflow are only obvious once rendered — always
`export(action: "export-slide-to-image", ...)` after building or editing a SmartArt diagram to
confirm node text fits and the layout reads as intended (see `export-and-verify.md`).