> For the complete documentation index, see [llms.txt](https://vibemx.gitbook.io/neuronai-studio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vibemx.gitbook.io/neuronai-studio/workflows/canvas-editor.md).

# Canvas Editor

The workflow canvas is a React Flow-based visual editor embedded in Livewire. Drag nodes, connect edges, configure forms on the node, and save validated graphs.

## Open the editor

```
/neuronai-studio/workflows/{id}/edit
```

> **Screenshot pending:** Full workflow graph with searchable palette, floating Playground/Share, and expanded node forms.
>
> Asset path: `docs/assets/screenshots/workflows-canvas.png` Capture: Workflow editor with a multi-node graph — dark theme, 1440×900

## Editor features

| Feature                   | Description                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------- |
| **Node palette**          | Searchable, categorized drag-and-drop component list                                  |
| **Tools / MCP catalogs**  | Browse registry and MCP tools to attach bindings without leaving the canvas           |
| **Inline node forms**     | Selected nodes expand with configuration fields on the canvas                         |
| **Node toolbar**          | Controls / Advanced / Collapse / Duplicate / Delete on selection                      |
| **Actions modal**         | Configure Tool Mode `tool_exposure` (slug, description, `input` param) on specialists |
| **Playground**            | Floating top-right overlay to run and chat with the workflow                          |
| **Share**                 | Floating menu for Connect API, PHP export, and JSON                                   |
| **Logs**                  | Bottom-left drawer for traces, live events, and validation                            |
| **Sticky notes**          | Non-executable annotations stored in `graph.annotations`                              |
| **Zoom / lock / minimap** | Viewport controls with interactive lock                                               |
| **Undo / redo**           | Revert canvas changes                                                                 |
| **Auto-layout**           | Dagre-based graph layout                                                              |
| **Edge splicing**         | Insert nodes between existing connections                                             |
| **Validate**              | Check graph structure before save                                                     |
| **Import / export JSON**  | Copy graph JSON in/out                                                                |

## Architecture

```mermaid
flowchart LR
    Livewire[Workflows/Editor Livewire] --> Shell[WorkflowEditorShell]
    Shell --> Palette[NodePalette]
    Shell --> Canvas[WorkflowCanvas React Flow]
    Shell --> Playground[PlaygroundOverlay]
    Shell --> Share[ShareMenu]
    Shell --> Logs[LogsDrawer]
    Canvas -->|save| Livewire
    Livewire --> DB[(neuronai_studio_workflow_definitions.graph)]
```

React bundles communicate with Livewire via `window.Livewire` calls. See [Frontend Bundles](/neuronai-studio/reference/frontend-bundles.md).

## Save and validate

Before saving, `GraphValidator` checks:

* Exactly one **Start** node
* At least one **Stop** node
* A control-flow path from Start to Stop (edges with `targetHandle: tools` are ignored for reachability and cycles)
* Valid edge connections (handle compatibility)
* Agent nodes: `agent_id` in existing mode, or `provider` + `model` in inline mode
* Tools binding edges: target must be an inline Agent; source must be Tool or MCP

Sticky notes (`type: note`) are ignored by validation and runtime; they persist under `annotations`.

Fix validation errors in the Logs drawer (Validation tab) before saving.

## Agent tools on the canvas

Agent nodes expose a cyan **tools** handle in both inline and existing modes. Attach tools by:

* Connecting a **Tool** or **MCP** node to the **tools** handle
* Picking entries from the **Tools** / **MCP** catalogs on the canvas (same registry refs as the agent editor)

Canvas bindings merge with tools already defined on the agent definition. A Tool/MCP node on a **tools** edge is a binding only — it does **not** run as a sequential step unless that node is also on the Start→Stop path via `default` handles.

### Tool Mode / Toolset

Enable **Tool Mode** on a toolable Agent to turn it into a specialist. The node shows an amber **toolset** source handle instead of control-flow Response. Use the **Actions** modal to set `tool_exposure` (slug, description, caller-controlled `input`). Wire:

```
specialist (toolset) → supervisor (tools)
```

Control-flow stays `Start → supervisor → Stop`. The specialist is invoked only when the supervisor’s model calls the Actions slug (`node:{id}` → `NodeAsTool`). See [AI nodes → Tool Mode](/neuronai-studio/workflows/ai-nodes.md#tool-mode-agent-as-tool).

## JSON graph format

```json
{
  "version": 1,
  "nodes": [
    { "id": "start-1", "type": "start", "position": { "x": 0, "y": 0 }, "data": {} }
  ],
  "edges": [
    { "id": "e1", "source": "start-1", "target": "agent-1", "sourceHandle": "default", "targetHandle": "default" }
  ],
  "annotations": [
    { "id": "note_1", "type": "note", "position": { "x": 40, "y": 40 }, "data": { "text": "Pricing notes" } }
  ],
  "viewport": { "x": 0, "y": 0, "zoom": 1 }
}
```

## Keyboard shortcuts

| Shortcut               | Action                                |
| ---------------------- | ------------------------------------- |
| `Delete` / `Backspace` | Remove selected node (not start/stop) |
| `⌘/Ctrl+D`             | Duplicate selected node               |
| `⌘/Ctrl+Z`             | Undo                                  |
| `⌘/Ctrl+Shift+Z`       | Redo                                  |
| `Escape`               | Clear selection                       |

## Preview mode

Read-only preview for code-sourced workflows:

```
/neuronai-studio/workflows/preview?class=App\Neuron\Workflows\MyWorkflow
```

## Next steps

* [Node types](/neuronai-studio/workflows/flow-nodes.md)
* [State & Conditions](/neuronai-studio/workflows/state-and-conditions.md)
* [Export & Production](/neuronai-studio/workflows/export-and-production.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://vibemx.gitbook.io/neuronai-studio/workflows/canvas-editor.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.