[clubanderson]

RFC phase 4 (UI) of #17620 on v5: the workflow-model Editor — a real design surface for state machines (lanes, chips, edges, drag/drop, live compile), not a form over the JSON. Follows the owner's brief: "the editor needs to be a good design tool too".

Stacked on the merged Workflows-tab (#17681) and Simulate (#17688) PRs. Includes the remainder of #17685 (P4 backend) until it merges — after rebasing on v5 that is only its changelog fragment and the route registration line.

Screenshots (hive-default copy, 22 states / 91 transitions)

Quiet default — orthogonal gutter routing, one bundled trunk per lane pair, no edge labels:

Focus mode — hovering claimed dims non-incident edges and lifts its 12 in/out edges to the front:

What

Settings → Workflows gains an Editor nav item plus Edit buttons on library rows and the detail view (owner only; hive-default offers Edit a copy). The ingest result gains Open in editor.

Layout: toolbar · templates palette · SVG canvas · inspector · bottom drawer (Problems · YAML · Diff · Simulate).

Interaction model

• Columns are lanes: add, rename (dbl-click header), reorder by dragging the header, resize with snap-to-grid, toggle terminal (shaded), delete (moves or deletes its states after confirm).
• States are chips: drag within/between lanes (updates lifecycle.column + order), dbl-click rename, Delete/Backspace, marquee multi-select, shift-click, arrow-key nudge, tabindex=0 + Enter/Delete for keyboard users.
• Transitions: drag from a chip's right-edge port to another chip; defaults on: '' and focuses the inspector field. Edges use a quiet-by-default, detail-on-focus layer shared with the library diagram (design feedback on the hive-default knot): orthogonal routing through the lane gutters with one bundled trunk per lane pair, same-lane edges stacked on the lane margin, lane-skipping edges in corridors outside the lanes (backward ones above the headers, dashed/muted), no edge labels by default (hover/select an edge for its pill label; a Labels toggle labels only the exceptional events — the most common on such as stage-change never), focus mode (hover/select a state → non-incident edges dim, incident edges come to the front in the accent colour with arrowheads; hovering an edge highlights both end chips), and fan-out collapse (>4 edges from one state into one lane → one trunk with a +N badge; hover expands, click pins). Pure router wfRouteEdges / wfOrthoPath / wfEdgeChannels / wfEdgeCommonEvent with node tests (bundling by lane pair, back edge outside, adjacent back edge in the gutter, labels hidden by default, common event tagged, fan threshold and expansion, determinism).
• Pan (wheel / space+drag / middle button), zoom (Ctrl/Cmd+wheel, ± / Fit), minimap when the model overflows, Auto-layout (topological lane order, stage-number order within lanes).
• Compile badges on chips/edges/columns with tooltips; inferred elements dashed with a one-click ✓ confirm; initial-state marker.
• Palette: common states (ids/kinds/stage numbers), common columns, and hive-default stages (fetched once). Drops assign unique slugified ids.
• Inspector: state (id + rename with reference update, label, column, stage number, owner, type, kinds, confidence, replies, citations), transition (on with declared-events datalist, guard, note), column (id, label, hint, terminal), model (name, description, source, provenance, version, derivation, initial, label prefix, scope repo).
• Live compile (300 ms debounce) → POST /api/workflows/compile; status pill compiles / N warnings / does not compile; Problems drawer click-to-select; instant client-side mirror of the compiler's refusals (wfEdLocalProblems).
• YAML drawer: two-way (model→yaml debounced while the tab is visible and unfocused; yaml→model on Apply with inline parse errors).
• Diff drawer: client-side structural diff of the working copy vs last saved (wfEdDiff, same shape as Go ModelDiff), plus stored-version diff via GET …/diff.
• Simulate drawer: compact fact table → POST /api/workflows/simulate {model, kind, facts} for the unsaved model; decided state highlighted (.wf-ed-sim-hit), others dimmed; reason + trace shown.
• History: undo/redo (Cmd/Ctrl-Z, Shift-Cmd-Z), capped snapshot stack, dirty indicator; Save posts with meta.version: '' so the store assigns the next integer, then reloads the library and reopens the saved entry; Save as…, Revert, leave-guard via hiveConfirm.
• Start screen: new blank model, duplicate hive-default, open from library, last ingest result, marketplace placeholder (phase 7).
• Export: SVG (self-contained, theme tokens resolved from the canvas), PNG (rasterised, shown inline with open-in-new-tab — no forced downloads), model JSON, model YAML.

Pure core (no DOM, node-tested)

wfEdNewModel, wfEdAddColumn, wfEdMoveColumn, wfEdRemoveColumn, wfEdAddState, wfEdMoveState, wfEdRenameState, wfEdRemoveState, wfEdAddTransition, wfEdUpdate, wfEdUniqueId, wfEdAutoLayout, wfEdLayout, wfEdDiff, wfEdLocalProblems, wfEdSvg, wfEdMinimapSvg, wfEdStatus. All deterministic and non-mutating; workflows_editor_ui_test.go runs them under node from the generated bundle.

APIs added

• POST /api/workflows/yaml — {model} → {yaml} and {yaml} → {model, error?} (JSON→YAML so field names match json tags).
• POST /api/workflows/simulate — {model, kind, facts} for an unsaved model; same response shape as the stored-model variant (reuses stageengine.Explain).
• POST /api/workflows now assigns the next integer version when meta.version is empty.
  All in dashboard/openapi.json with handler tests; read-only computations need no owner role (mirrors the GET handlers).

Guards

Plain JS/CSS in the concatenated bundle (no libraries); CSS tokens only; no toLocaleString; no forced downloads; all actions delegated via data-action except the canvas pointer listeners attached idempotently after each render. Style/import/history-cap/band-wiring ratchets, openapi route coverage, settings-search and deeplink tests pass; gen -check clean.

Verified in a browser (Chrome via CDP against a local dashboard)

New model → 3 columns → palette drops → port-drag transitions (incl. backward) → chip drag between lanes → header drag reorder → lane resize → marquee → Delete → Cmd-Z / Shift-Cmd-Z → compile pill + Problems → YAML edit → Apply (and a parse error shown inline) → Simulate highlighting the decided state → Save (v1) → edit → client diff → Save (v2) → stored-version diff → Export SVG/PNG/JSON/YAML → Library Edit reopen → hive-default Edit a copy → leave guard. Bugs found by the smoke test (YAML newlines lost through esc(), focus lost after re-render, dark export colours in light theme, crowded edge labels) are fixed in this PR.

Docs

docs/design/workflow-models.md — new "Editor (RFC phase 4, UI)" section; changelog.d/added-workflowmodel-editor.md.

Deferred

Editing events/gates/roles/rules on the canvas (available through the YAML drawer); nested regions beyond flattening; marketplace (phase 7); keyboard-only lane reorder; collaborative/locking semantics; persisted lane widths.

Refs #17620

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign hanthor for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[github-actions]

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR	Title	Relation	Files
#17714	✨ Workflow models: signed bundles, hub marketplace catalogue with nightly refresh, spoke import/publish	same files	dashboard/openapi.json src/docs/design/workflow-models.md src/pkg/dashboard/api_workflows.go src/pkg/dashboard/static-src/js/config-workflows-library.js src/pkg/dashboard/static-src/manifest.txt src/pkg/dashboard/static/index.html

[github-actions]

Mutation testing

❌ gremlins did not produce a report for 1 package(s), so no verdict can be derived from this run (see the job log):

• pkg/dashboard: gremlins exited 137

Verdict: error (#17349).

[hivecommons-hive]

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

clubanderson this PR is held at stage/071-needs-author and the hive will not merge it yet.

Why:

• the branch conflicts with the base and needs a rebase

Next: the hive does not push to your branch. Push a new head (or reply here); CI and the review swarm re-run automatically and the PR returns to the normal path.

Evidence bundle `#17706a8cd2cf` sha256:4a109f0f70260536785547bfeed02f578ece31d958dfa9434e9f59c313adebeb — download from the dashboard or `hivectl review evidence #17706`.

[hivecommons-hive]

merged by Hive trusted-author auto-merge: author @clubanderson holds role owner and GitHub permission admin on repo; CI green at a8cd2cf.

[github-actions]

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback