app/docs/interface/flow-editor.md

# The flow editor

The canvas is where most of the work happens. It floats its chrome over a
full-bleed graph, so what you are looking at is always the flow.

## The canvas

Nodes are laid out for you, left to right on a desktop and top to bottom on a
phone, and the arrangement is recomputed as the graph changes. There is
nothing to drag and nothing to tidy.

The edges come from message names, so there is no layout to store or to merge
when two people edit the same flow.

What is drawn:

- **Your nodes**, with a status dot — running, succeeded, failed, or nothing at
  all when idle. Status is always named in words too, never colour alone.
- **Edges**, which pulse when a value goes down them. Click one to inspect it.
- **Endpoints** — anything wired into this flow that is not a node in it: a
  dashboard control writing a message, a tile reading one, a node in another
  flow on the far side of a dotted name. Drawn as labelled boxes at the
  boundary, so a value never appears to come from nowhere.

Values are live. The editor holds a websocket to the engine, and the connection
banner tells you when it is not.

## Adding a node

**Add node** on the dock, or ⌘P / Ctrl-P for the command palette, which also
jumps between flows and offers your shared nodes. Pick a type and it appears on
the canvas with its panel open.

## The node panel

Floats on the right; a full-screen sheet on a phone.

**Consumes** and **Provides** are the ports. Each port has two lines: its name
and payload type (a `list` also says what its items are), then the message it
is bound to, how often at most it is delivered, and, on an output, a
*streaming* toggle for ports that publish repeatedly during one execution. The
message field suggests messages already in the flow, which is usually how you
wire something: type the name that already exists.

A port is named after its message until you name it yourself. Its name field
then stays empty and shows the name it follows. A name typed there stays when
the message changes, which is how a port is bound to a message called
something else, as a [`wren`](../reference/node-types.md#wren) target is;
clear it to follow the message again. The name is what the node's code sees,
so it is letters, digits and `_`, not starting with a digit, and no two inputs
or two outputs of a node share one. The field keeps the name it had otherwise.

Renaming an output renames the message everywhere it is read. Inputs are not
renamed, because an input is more often re-pointed at a different message than
renamed.

**Settings** is generated from the node type's parameter schema, so an MQTT
node shows broker, topic and QoS, and an ntfy node shows server, topic and
priority. A field marked as a credential renders as a picker over your stored
[secrets](operations.md) instead of a text box. A setting holding JSON, such as
a Switch node's rules, shows one line of it; click it to edit the whole value
in a larger editor, which saves only once the text parses. Escape or Cancel
leaves the setting as it was.

A Function node gets a second settings section where you add your own: a
setting is a constant of this node's code and arrives as an argument beside its
ports. See [Where a node's values come from](../concepts/values.md).

**Timeout** (Function nodes) is how many seconds the code may be *silent*
before it is stopped: it measures silence, not duration, so a node that yields
every few seconds can run for hours under a timeout of 300. Left empty there is
no limit, which is the default. Set one where a node going quiet means it is
stuck rather than working. A `0` says so explicitly.

**Code** is the editor. It saves as you type and applies on ⌘S; the node
reloads without the flow stopping. A node file defines `process(...)`; if it
defines exactly one public function under another name, that one is used
instead.

**Shared** turns a node's code into a library entry other flows can reuse.
Editing a shared node edits the copy every flow using it runs, which is the
point and also the caution.

!!! note "Not in the panel yet"

    `device` and `device_policy`, which machine a node's code runs on, are set
    through the API rather than the panel, with `PUT /flows/{name}`. See
    [Remote workers](../code/workers.md).

## The flow panel

Click the canvas title to open the flow's own settings.

- **Running** — the switch that starts and stops the flow. Stopped means none
  of its subscriptions, schedules or webhooks exist.
- **Mode** — `live` or `batch`. Live reacts to what arrives; batch only runs
  when a run asks it to. See [Runs](../concepts/runs.md).
- **Inputs** — messages the flow takes from outside, with the value each starts
  from. For a batch flow these are also the run's parameters.
- **Outputs** (batch only) — which messages a run reports as its result.
- **Contents** — a reminder that this flow's name namespaces every message
  inside it.

## Inspecting an edge

Click a wire. You get the last payload that went down it, when, and a sparkline
of its recent numeric history. You can also republish that value from the node
that produced it, which re-runs everything downstream. It is the fastest way to
test a change without waiting for the real sensor.

## The dock

Along the bottom, floating over the canvas.

| Control | What it does |
|---|---|
| **Add node** | opens the palette |
| **Fit** | returns to the view the flow opened with |
| **Run** | injects a value by hand; on a batch flow, opens the parameters dialog |
| **Pause / Resume** | holds messages instead of running them |
| **Step** | releases exactly one held message |
| **Publish** | puts the draft live |
| **Discard** | throws the draft away |
| **Issues** | what is stopping this flow from running, per node |
| **Logs** | what the nodes printed, filterable |

Pause and step together are how you test a flow before it moves anything
physical: pause it, inject a value, step it through, watch the values appear on
the edges, then publish.

## Shortcuts

| Chord | Action |
|---|---|
| ⌘P / Ctrl-P | command palette |
| ⌘S / Ctrl-S | publish the flow — or, with focus in the code editor, apply the code |
| ⌘Z / ⌘⇧Z | undo / redo (the flow; the code editor has its own) |
| ⌘C / ⌘V | copy and paste nodes, including between flows |

## Drafts and publishing

Saving writes a draft; the engine keeps running what was published. Publishing
promotes it and reloads.

If someone else saved the same flow while you were working, publishing answers
with a conflict rather than overwriting them. The Flows list offers **Publish
all changes** when several flows are sitting on drafts.

## Issues

The canvas validates as you edit and marks the node each issue belongs to:

- a port that needs a message nothing in reach provides
- a message that exists but has never held a value
- a dependency cycle
- a node reading a message it also writes, with nothing to start it from
- code that did not load
- a webhook with no shared secret (advisory — it does not stop the flow)
- a node that loaded but reports itself down, such as a connector that cannot
  reach its device

A flow with any of these except the last two does not run, and the health
summary on Home counts it. The last one clears on its own once the node reports
itself well again.

## See also

- [Flows, nodes and messages](../concepts/flows.md) — the model behind the canvas
- [Node types](../reference/node-types.md) — everything the palette offers
- [Writing node code](../code/nodes.md) — what goes in the editor