The editor surface

Everything below is the VS Code extension as the user sees it, and every quoted label is verbatim. When you tell the user where to click, you quote the label from this file. If you catch yourself naming a button, menu entry or toast that is not quoted here, stop and write: "Wait. Labels are verbatim." Then quote the one that is, or tell the user the extension has no such control.

.weft files open as the graph by default (a stray text tab is closed automatically); the "Source" button is the text view. The extension talks to the dispatcher at http://localhost:9999 (setting weft.dispatcherUrl).

Where things live

• Activity bar, icon "Weft": two sidebar views.
  • Projects: one row per .weft file in the workspace (label = folder name). Click to pin and open its graph; inline buttons "Open in Editor" and "Run Project"; title-bar "Refresh".
  • Executions: runs of the pinned project, newest first (paged, "Load more (N more)" at the bottom). Row = status icon, entry node, time; tooltip = the color id. Inline "View in Graph" and "Delete"; title-bar "Refresh Executions" and "Clear All Executions".
• The graph panel, titled "Weft Graph: ".
• The Problems panel carries the compiler's live diagnostics.

Reading the graph

• A node is a white card: accent bar in the type's color, header with the status glyph (✓ completed, ● running, ◉ waiting, ✕ failed, ■ cancelled, ⊘ skipped) and the type name, body with the label and its ports. Left rail: input ports. Right rail: output ports. Each port is a dot colored by its type (String gray, Number blue, Boolean rose, files gold/purple/green/brown, List teal, Dict purple, Access teal, Bus amber, MustOverride red); a required input carries a *.
• The small amber arrow top-left of every box is _should_flow, the port that decides whether it runs: filled when something answers it, hollow when nothing does.
• Wires are arrows colored by the source port's type.
• Groups are large boxes ("GROUP" header) holding child nodes; collapsed they become a chip with the label, an expand button, and the description line. A group grows a "Config" strip under its header once the source gives one of its ports a value (g.tone = "formal"): the field edits that line, and the strip is gone when no port has one. Loops render violet with a rotate icon, their settings in that strip always, followed by any port the source gave a value, implicit index and done ports on the rails, carry ports marked ↻. @include blocks are violet with the filename; their body fields hold the values written on their ports (keep.n = 7) and edit those lines in place (no { } toggle: an alias has no braces); their "Open" button navigates into that file and the toolbar grows a "Return · " button.
• Access nodes (TelegramAccess and friends) show a "Connect ..." button in their body; one with a required, unpicked connection pins open (expanded, collapse disabled, "Pick a connection first") until a connection is picked. Trigger nodes show their display (the address a caller sends to and how the door checks them, or a timer's schedule; never a key). Infra nodes carry a status pill (running, stopped, failed...) and a body feed of what the service prints.
• Debug nodes render their latest value inline; media nodes render the image, an audio/video player, or a download card.
• Status glows: amber running, cyan waiting for input, green completed or skipped, red failed.

Toolbar and action bar

Top-left floating toolbar: "Return · " (inside an @include), the [follow toggle], "N new run(s) · Follow" (runs that started while locked or off; click to show the newest and follow again), and "Source" (opens the text beside the graph; click again to focus it).

The [follow toggle] has three parts, each explained on hover; only the active one shows its word:

• "Following · " (eye icon): every run that starts takes over the graph. The default.
• "Locked · " (lock icon): the graph stays on this run; runs that start are counted, not shown. Greyed while no run is on screen.
• "Off" (crossed eye): no run on the graph, just the program.

Clicking Run, Activate, or Infra Start in the editor switches to Following. A run started from the terminal (including every weft run you issue) never changes the mode: if the user left the graph Locked or Off, your run lands in the "N new run(s)" count, not on their screen, so tell them to click it (or switch to "Following") to watch it. Each project remembers whether it was left Following.

Top-right: "Simplified view" toggle. On: square, read-only nodes (toast "Switch to the builder view to edit the graph"), one dot per side, for reading and showing. Builder and simplified keep separate saved positions.

Bottom-center action bar, contextual slots. [the pre-flight] runs before Run, Activate, or Resync is sent: a runtime validation through the warm parse-server, where an unpicked connection and cousins land on the bar's error banner (the complete list, each entry clickable to its file and line) and the verb is not sent, so a build that cannot run never starts.

• Infra slot (when the project has infra): "Start Infra" / "Stop Infra" / "Upgrade Infra" (amber, when source changed since start) / terminate (trash). An eye toggle "Show infrastructure subgraph" dims everything except the infra closure.
• Run slot: "Run Project" (or "Run 1 target" / "Run N targets" once targets are set). While working the button becomes its own cancel: "Building...", "Cached, loading...", "Provisioning infra...", "Running...". While following a live run it is "Stop Execution".
• Trigger slot (when the source declares triggers): "Activate" / "Deactivate" / "Resync" (amber "Out of sync" when the project changed since activation). An eye toggle "Show trigger subgraph". Deactivating opens the picker "Deactivate: how should triggers come down?": Park (submissions wait indefinitely), Hibernate (grace window, then refuse), Wipe (drop everything, cancels suspended runs), plus what to do with running executions. Reactivating offers "Execute parked + keep suspensions", "Keep suspensions only", "Wipe all".

Banners above the bar: red for a failed verb (click for full diagnostics), amber for infra drift ("Infrastructure has changed. Click Upgrade to apply."), indigo "Graph locked while ..." while a verb owns the graph.

The in-graph palette (Ctrl+P or Cmd+P)

"Search nodes and actions...". The Actions section: Undo (Ctrl+Z), Redo, Duplicate Selected, Delete Selected, Select All Nodes, Fit View, Auto Organize Layout. The Nodes section: every type in the project's catalog with a preview panel (description, input chips, output chips, tags).

Editing in the builder view

Every GUI edit is a structured edit applied through the compiler, so the text and the picture cannot drift, and Ctrl+Z undoes in either view. Simplified view refuses structure edits with "Simplified view is read-only (you can still move, expand, and collapse).".

• Add a node: palette, or right-click the canvas "Add Node... (Ctrl+P)".
• Wire: drag from an output dot to an input dot. Dropping a wire on empty space opens the palette and completes the wire in one undo step. A port already filled by a literal refuses the wire ("'x' is driven by a config assignment; unset it first to drive it with an edge.").
• Read a key off a wire: right-click a wire whose value is a record and pick a field, one level at a time ("Up one level", "Read the whole value" to go back). The wire turns dotted with the path at its end; in source it is t.n = s.out.profile.wpm. A JsonDict or scalar value offers nothing and says to declare the shape or Cast first.
• Edit a node's settings: expand it and edit the fields inline: text, selects, checkboxes, code editors, entry lists, file pickers, connection pickers. A port-driven field carries a { } / = chip toggling whether it is written inside the braces or as its own line. An @file(...) field shows a file chip; editing it writes the referenced file (the source keeps one line). The lock chip turns it into read-only @asset.
• Ports: hover a custom port for its remove ×; "+ input" / "+ output" where the type allows. Right-click a port: "Make optional" / "Make required", "Type: " (editable), "Remove port". On loop ports the right-click also shows and changes the role (broadcast, iter, gather, carry).
• Nodes: right-click for "Duplicate (Ctrl+D)", "Delete (Del)", "Tags...", and "Set as target" / "Unset target" (any node). On an infra node: "Stop this node" (scales to zero, keeps disks) and "Terminate this node" (destroys them), both behind a confirmation.
• An infra node's card: while its container runs, the node's body shows readouts of its live state and a button for each way out of a state it can sit in. Those come from the RUNNING container, not from this file, so their labels are the node's to name and you read them off the card in front of you rather than quoting them from here. A secret it is showing you once renders masked, with buttons to reveal and to copy.
• Rename: double-click a node's label or a group's header.
• Groups and loops: the expand/collapse toggle on the box; "Auto Organize Layout" in the palette reflows; positions persist under layouts/ (never in the source).

Keyboard: Ctrl+P palette, Ctrl+Enter run, Ctrl+Z/Y undo/redo, Ctrl+A select, Ctrl+D duplicate, Del delete, Esc closes the palette and drops a wire you are dragging. Zoom is Ctrl/Cmd+wheel (5% to 200%); the bottom-left controls carry zoom, fit, and lock.

Running and watching

The Run button runs the pinned project's ordinary roots, or the selected work when a cut is set. Triggers need an explicit fire or supplied outputs. The run lands in the Executions list. Clicking any node opens [the inspector]: status, duration, cost ("$0.0123 (own key)"), the exact inputs and outputs of that firing as one card per port (a long value expands, copies, and selects whole on a double-click), closed ports greyed out, skip reasons in plain words ("its _should_flow said no", "the required input 'x' closed", "the scope 'x' it lives in did not run"), error boxes, bus and loop activity panels, and a firing navigator ("‹ 2/5 iter 5/2 ›") for nodes that fired several times. The Copy button exports the whole inspection.

Past runs: in the Executions view, "View in Graph" replays the run in the graph with every value in place and locks the [follow toggle] onto it; "N new run(s) · Follow" jumps to the newest. From the terminal the same facts are weft executions, weft events <color>, weft logs (the weft-running skill).

Diagnostics and AI edits

As the user types (or as nodes/ changes), the structural validation runs on a short debounce and the Problems panel fills with the same line:column message diagnostics the CLI prints. The panel is structural-only: runtime findings (an unpicked connection) never squiggle source, because their fix is not in the text; [the pre-flight] shows them. A diagnostic may name another file than the one being edited (a node spliced in by @include keeps its own file's coordinates). The graph keeps showing the last good render with a problems pill ("N problems") until the source compiles again (hint on the pill: stale node copies cause most catalog errors, run weft catalog update). An AI chat extension can stream SEARCH/REPLACE edits into the open file and the graph updates as each block lands (setting weft.ai.streamingEditsEnabled).