Nodes & graphs

Brut is a node canvas. You build a graph — nodes connected by wires — and run it. Nodes are shots and decisions, not samplers and latents: a node is "generate an image," "animate this clip," "plan the film," not a low-level knob.

#The canvas

• Add a node — the + on the left rail opens the node browser: every node by category (in workflow order), with a hover card showing what it does, what flows in and out, and whether it costs money. Click places it at the canvas center; drag drops it where you let go. Or press Tab over the canvas for the quick palette at your cursor — type to filter, ↑/↓ + Enter to place.
• Pan — middle-drag. Box-select — left-drag. Zoom — scroll wheel.
• Wire — drag from an output port to an input port. Drop a wire on empty canvas and the add menu opens, filtered to compatible nodes — pick one and it's placed and wired. Double-click a wire to splice a node into it.
• Run — ▶ Run executes the whole graph; the ▶ on a node runs just that node and everything it depends on.
• Copy, paste, duplicate — Ctrl+C copies the selected nodes, Ctrl+V pastes fresh copies, Ctrl+D duplicates in one step. Copies keep their incoming wires: a duplicated node arrives already fed by the same upstream nodes as the original (outgoing wires are not duplicated — that would double-feed whatever the original feeds).
• Paste an image — Ctrl+V with an image on the OS clipboard (Photoshop Ctrl+A+Ctrl+C, a render buffer's Copy button, a browser image) drops a ready-filled Image In node at your cursor. If you copied both, whichever you copied last wins the shortcut.
• Tidy — the grid button on the left rail auto-arranges the whole graph into columns that follow the wiring (nodes stack top-down within a column). It's one undo step — Ctrl+Z puts everything back.
• Node ids — every node's title bar shows its id in small type (multi_shot-21). That's the name Marcel and the ledger use when they refer to a node — click the id to copy it.

#Ports and wires

Every node exposes typed ports. Wires carry one of three things: images, text (prompts and plans), or video. Ports are labeled by role — a Compose node has scene and reference image inlets; a Multi-Shot node has base and reference. Brut only lets you connect compatible types, and picks the right inlet automatically when you drag-to-connect.

Some nodes expose per-tile output plugs — a Shot Board tile has its own handle so you can route one chosen shot downstream, a Clip Board tile has one per clip.

#The execution model

When you run, Brut topologically sorts the graph and executes on a promise-graph scheduler: each node starts the moment its inputs are ready, so independent branches run concurrently. Two things make this cheap and fast:

• Input-hash caching — a node whose inputs haven't changed and that has a cached output is skipped, free. See Never pay twice.
• Handle-aware routing — inputs are grouped by role, so a node knows which images are the "scene" vs the "reference," and which tile's output a wire carries.

Runs can overlap if their scopes don't share a node. Paid work is guarded so nothing double-pays.

#Node families

Each family has its own page under Nodes in the sidebar. Sticky notes, emoji stamps, the pen and text labels aren't nodes — they're annotation tools in the rail's Organize section, also one right-click away via the ring menu (all documented on the utility page).

#Saving & undo

The canvas autosaves into the project itself (a .workspace.json beside the saved graphs, written moments after every change), and it remembers which named graph it is — relaunch the app in any mode, or reopen the project from another machine on a NAS share, and you land exactly where you left off, name in the selector and all. Named saves are still explicit (File ▾ → Save, Ctrl+S); a • next to the graph name means the canvas has changes not yet saved to it, and opening another graph over unsaved work asks first instead of silently replacing it. Undo/redo (Ctrl+Z / Ctrl+Shift+Z) covers structure and parameters — never generation results, which are the ledger's job, so undoing a param edit keeps your caches warm.