Canvases

A flow holds one or more canvases. Main is the entry: runs, publishing, campaigns and the Tests window always use it. Next to it you can keep your own canvases (to sketch, park ideas or organize), and the AI agent and suggestions work in drafts: copies of main that come back into it only when someone keeps them.

The Canvases window

Canvases sits on the left of the editor (see Layout and windows). It lists every canvas like a file explorer:

1. Main first (a star marks it).
2. Canvases: your own and your team's.
3. Drafts, grouped by whose they are: "Muhammad's drafts". An agent's draft has a spark, and a pulsing dot while its agent is working.

Click one to open it as a tab above the canvas. Colored dots show who else is on which canvas. Everyone with the flow open sees every canvas, including other people's agent drafts, live.

Each canvas's ⋯ menu:

+ at the top makes a new, empty canvas. ⌘K lists canvases too.

Open canvases sit as tabs above the canvas, like files in a code editor: Main first, each tab with its color, a spark for an agent's draft and a lock when it's read-only for you. + at the end of the tabs makes a new canvas.

Call a canvas

A canvas can be called from main like a flow, so a big flow splits into readable parts that live in one place.

1. On the canvas, start with Flow input (its sample keys are the inputs) and end with Return.
2. On main, add Run flow and pick Canvas · in its flow list; fill the inputs.
3. Open canvas under the picker jumps to it.

The canvas is walked inside the caller's run (its logs nest under the Run flow node, {{ nodes.<id> }} in it means its own nodes), so Wait for it must stay on. A real run uses the canvases as last published; a test run uses them as they are drawn now. A canvas can call other canvases (5 deep at most, no loops). Drafts can't be called.

Locks

Any canvas can be locked. A locked canvas is read-only for everyone except whoever holds the lock: a person, or an agent conversation. The lock icon takes the holder's color.

• Lock from the canvas's menu; Unlock is for the holder, or a workspace owner or admin (so a forgotten lock never traps a flow).
• An agent's draft starts locked by its conversation. Others can watch it but not change it.
• Ask the agent in the chat to unlock its draft and the lock passes to you: you can edit it, others still can't. Unlock it again to free it for everyone.
• An agent never edits a canvas someone else locked; it's told who holds it and works around it or asks you.
• While main is locked, keeping a draft into it is refused.
• The collaboration server enforces locks too: an edit that changes a canvas someone else locked is refused before it applies (only its holder, a workspace owner or admin, or the person whose agent holds it may change the lock itself).

Drafts and keeping them

A draft starts as a copy of main (its base) and records each edit as a step, like a commit. The agent's drafts show their changes in the of its conversation; suggestions show in the Suggestions tab of Comments.

Keep merges a draft into main the way Git does, with three versions: the base, main now, and the draft.

• Each field of a node, its name, settings, description and pin are compared on their own, so two people changing different fields of the same node never conflict.
• Where a node sits never conflicts (the draft's move wins).
• A node deleted on one side and changed on the other is a conflict; deleted on one side and untouched on the other is deleted.
• Connections and sticky notes are sets: what either side added comes in, what either side removed goes.

Keep has three methods, like GitHub's merge button (the one you pick is remembered for the flow):

With conflicts, Keep stays off until each one is settled: pick Main's or Draft's per conflict, or Resolve with agent (the agent updates its draft from main, settles the conflicts knowing both sides, tests again and tells you it's ready). Rebase stops at the step where a conflict is.

Update from main brings main's changes since the base into the draft and moves the base to main as it is now, so the draft tests against what's really there. Undo all deletes the draft; main never changed.

Sparks

What the agent changed carries a spark until you decide:

• In its draft: changed nodes are outlined (green new, amber changed) and sparked until you keep or undo the draft.
• Straight on a canvas (a small change): the nodes it touched are sparked for everyone until you press Keep (or Undo) on that change in the chat.

Test runs show where they ran: the Runs window and the Runs page name the canvas when it isn't main.

Node context

Every node remembers who made it and who changed it last, and when; an agent's edit says so ("Created by Muhammad (via agent) · 2 h ago" in ). This is stamped by the live document when a node is written, never typed by hand, and a merge carries the draft's.

Every node also has a description: what it does in this flow and why, in a sentence or two. It shows under the node on the canvas, you can edit it in Node details, and the agent writes or refreshes it whenever it adds or changes a node, so a later conversation understands the flow without guessing.

How it works

• The flow's live document holds meta { name, entry } and canvas, a map of canvases by id: { name, kind: "main" | "canvas" | "draft", color, lock, draft, nodes, edges, notes } (src/lib/collab/graph.ts). Types: TFlowCanvas in src/types/lib/flow.
• lock: { userId, sessionId, lockedAt } | null. mark: node ids the agent changed straight on it (sparked until kept). draft: { userId, sessionId, base, step: [{ message, graph, createdAt }], isSubmitted }.
• Node meta: { createdAt, updatedAt, created: { userId, sessionId }, updated: { userId, sessionId } } is set by collabGraphWrite from its actor.
• The collaboration server mirrors main onto Flow.graph and the callable canvases (kind canvas) onto Flow.canvas on every store; publishing copies both (published.graph, published.canvas, and the publish version's canvas).
• A Run flow node with flowId: "canvas:<id>" is resolved by flowPayload from the calling flow's canvases into the run's child graphs, like a called flow; the engine walks it the same way.
• Server code writes canvases through flowCanvas (a Hocuspocus direct connection: everyone sees the change at once) and merges with flowCanvasMerge (src/controllers/flow/canvas).
• Actions in src/actions/app/[workspace]/studio/canvas: aStudioCanvasKeep (method, resolve, skip), aStudioCanvasUndo, aStudioCanvasSync, aStudioCanvasSuggest. aStudioVersionRevert reverts a kept version.
• Locks are checked in the editor and in the collaboration server's beforeHandleMessage (the ticket carries isAdmin).
• A run's flow.canvas ({ id, name } or null for main) is set by flowPayload and kept by the engine on the run.
• Deleting an agent conversation deletes its drafts.
• Each canvas has its own undo history in the editor (⌘Z covers your edits on the canvas you're on).
• Comments are pinned to a canvas and a node (or a point); opening a thread on another canvas switches to it.

FAQ

Which canvas does a run use?

Main, for real runs, schedules, campaigns, publishing and Tests (canvases it calls through Run flow come along). A Test run you start while another canvas is open tests that canvas; an agent tests its own draft.

Can someone else change my agent's draft?

No. It's locked to your conversation. They can open it and watch. Ask the agent to unlock it and the lock passes to you.

I kept a draft by mistake. How do I take it back?

Open Version history and press Revert on its version. What it changed goes back; what others changed since stays.