Visual editor

Where to open it

The editor lives at /workflows/{slug}/edit and is reached from:

• The “Edit” click on a card in /workflows.
• The “Create workflow” form, which redirects to the editor of the freshly-created workflow.

Direct URL works for bookmarks. /workflows/{slug} redirects to /workflows/{slug}/edit — there is no separate read-only detail page in v1.

Anatomy

 ┌──────────┬─────────────────────────────────┬────────────────┐
 │  PALETTE │ [Auto inputs] Validate|Save|Run │   PROPERTIES   │
 │          ├─────────────────────────────────┤                │
 │  INPUTS  │                                 │  (visible when │
 │  ├ Force │                                 │   a node is    │
 │  ├ Length│       REACT FLOW CANVAS         │    selected —  │
 │  ├ …     │                                 │   branched by  │
 │  └Custom…│                                 │   node kind)   │
 │          │                                 │                │
 │ Packages │                                 │                │
 │  ├ func  │                                 │                │
 │  ├ func  │                                 │                │
 └──────────┴─────────────────────────────────┴────────────────┘

Adding an input node

The top of the palette is dedicated to input nodes. Two paths:

1. Type cards — one draggable card per primitive and physical canonical type (Force, Length, Moment, …). Drop on the canvas ⇒ a typed input node appears with its label pre-filled (and editable later).
2. Custom… button — opens a modal to declare any other shape:
   • Label — displayed on the card and in the run form.
   • Type expression — canonical name (Force), parameterised (list[Force], dict[str, Length]) or inline struct as JSON: {"d": "Length", "p": "Length", "As": "Area"}.
   • Description (optional) — renders under the field at run time.
   • Required at run submission (toggle).

Every input node has a single output port named value; edges from the node use that port.

Note

Input nodes can feed multiple function ports. A single {d: Length, p: Length, As: Area, Re_min: Stress} input can be wired into every sizing function of a bolted-joint graph — that’s the whole point of the explicit-input model.

Adding a function node

1. In the palette’s package sections, locate the function — functions are grouped by owning package. Only ready versions are displayed.
2. Drag the function card onto the canvas. The drop position becomes the node position.
3. The new node is auto-named — function_name by default, with a numeric suffix (force-calc-2) on collisions inside the same graph.

Note

Function nodes pin the exact function version selected from the palette (FRO-wkf-05). Updating the package later does not touch this node. To switch version, select the node and use the dropdown in the properties panel.

Auto-create inputs on drop

The toolbar hosts an Auto inputs switch. When on, dropping a function node also creates:

• One input node per input port declared on the function’s io_spec.
• Each input node is pre-typed from the port type (Force, struct, list…).
• Edges are drawn automatically from each input node’s value to the matching function port.

The auto-created input nodes are placed on the left of the function node, stacked vertically around the function’s Y position. Left off, the user manually drags types from the palette — useful when you want to share an existing input node across two functions.

Drawing edges

• Click a source handle (right of a node), drag to a target handle (left of another node), release.
• The editor calls POST /types/check-connection asynchronously before materialising the edge.

What happens on drop

ALLOWED

Edge committed. Tooltip on hover shows the sous-typage reason — Force → Numeric explains “Numeric is a descendant of Float”.

REFUSED

Destructive toast surfaces "Force → Length · …". The edge is not added to the canvas; no DB state, no validation noise.

The type system reference covers the exact rules.

Selecting a node — the properties panel

Click a node. A right-hand panel opens. The panel branches on the node’s kind.

Function node panel

Field	Meaning
Node key (read-only)	The stable identifier used in edges and run outputs.
Display label	Free-form override of the function name. Saved as custom_label.
Function version	Dropdown listing every ready version of the same function. Switching drops edges whose ports no longer exist in the new signature (FRO-wkf-05).
Source package	Link to /packages/{id} for the owning package.

Input node panel

Field	Meaning
Node key (read-only)	Becomes the key of the run submission payload (inputs[node_key]).
Label	Shown on the node card and as the title of the run-form card.
Type expression	Textarea accepting a canonical name, a parameterised form, or struct JSON. Validated on blur — malformed JSON surfaces an inline error.
Description	Optional free text rendered under the field at run time.
Required	When off, the run form allows leaving the field blank and the function receives its default.

Close the panel with the × button or click the canvas background.

Validate button

Validate runs a dry-run of the full graph validation against POST /workflows/{slug}/validate. Unlike the save path, this endpoint:

• Never persists anything, never creates a version.
• Always returns 200 OK with a structured report — even on errors.
• Is owner-only (same rule as save).

The dialog categorises issues:

• Cycles — a → b → a paths.
• Unconnected function inputs — strict-mode violations: a function port has no incoming edge. Wire an input node (or an upstream output) to fix.
• Invalid input-node types — a type_expr the catalog cannot parse.
• Subtyping violations — per-edge reason.
• Duplicate target ports — two edges pointing at the same input.
• Unknown source/target ports — edge references a port that does not exist in the current io_spec.
• Missing typed I/O — function nodes whose pinned version has no io_spec.
• Unknown function versions / nodes — dangling references.

Note

The same JSON shape is emitted as the detail of a 409 response from POST /{slug}/versions. Callers can reuse the same UI for both surfaces — the frontend does exactly that.

Save a version

Save version POSTs to /workflows/{slug}/versions. The backend runs the full validation; on success a new version (monotonic integer) is created and becomes is_latest=true. On validation failure the call returns 409 with the same report shape as Validate.

Old versions are immutable and remain queryable — runs reference the version they were started against, not the current head.

Running a workflow

The Run button is disabled while the canvas has no node or no version has ever been saved. When enabled, it navigates to /workflows/{slug}/runs/new — see execution for the full flow.

Not in v1

Out of scope for the v1 editor — planned for v1.5 / v2:

• Visual struct builder — structs are declared as JSON in the Custom Input dialog; a field-by-field builder would be nicer.
• Auto-layout — arrange nodes automatically (dagre / ELK).
• Undo / redo — the editor is stateless between reloads for v1.
• Multi-selection & bulk operations.
• Copy / paste of sub-graphs.
• Logic nodes — if, for (FRO-wkf-15).
• Import / export YAML (FRO-wkf-13).