VLCode-Lite/.codex/vendor/VL-Workflow-Engine/ui/INTEGRATION.md

Workflow Editor — Integration Guide

Canonical source: vl-workflow-engine/ui/workflow-editor.html Version: 2.1 (Spec 3.16) Replaces: project-local copies in VL-Code, VLCode-Lite

---

What Changed

v2.1 — Checkpoint, Pause, Re-run, Node Editor

Feature	Description
Checkpoint persistence	DAG state (node statuses) is saved to localStorage after each step. On page refresh, the DAG re-renders with previous execution state intact. Checkpoints expire after 24h.
Pause execution	New amber "Pause" button in toolbar. Sends POST /api/workflow/:runID/pause (fallback to /cancel). Workflow stops cleanly, checkpoint is saved, user can resume from any node.
Re-run from node	Right-click any node → "Re-run from here". Calls POST /api/workflow/rerun with the last checkpoint + target stepID. Downstream nodes are cleared; upstream statuses preserved.
Edit inputs & re-run	Right-click → "Edit inputs & re-run" opens a modal editor. Type-specific fields (LLM: model/tokens/messages, Service: input params, Set/Write: target/value, Loop: source/while, Download: source/target). Plus a generic "Variable Overrides" JSON field for $vars.
Context menu	Right-click on any node shows: Re-run from here, Edit inputs & re-run, View details, Copy node ID.
New PostMessage APIs	setCheckpoint, rerunFromStep, editNode — parent can programmatically trigger checkpoint storage, re-runs, and the edit modal.
New outgoing message	nodeEdited — sent to parent when user edits a node's inputs, with the modified nodeData and overrides.

v2.0 — Spec 3.16 Bug Fixes

#	Issue	Impact
1	BREAK phantom connections	next: "BREAK" no longer creates a connection to a non-existent node. Both RETURN and BREAK are now excluded from connection generation. This was the likely cause of DAG rendering failures.
2	Loop while mode not rendered	renderLoopBody() now detects while vs source mode and renders the correct fields (while expression, maxIterations).
3	Missing Download/Unzip node types	Download_* and Unzip_* are now recognized with dedicated icons (DL/UZ), colors, accent bars, and body renderers.
4	computeIO ignored while expression	Variable references in while expressions now appear in I/O audit badges.

Visual Parity

All existing visuals are preserved:

• Same CSS variables, dark theme, font stack
• Same 11 original node type colors + accent bars + 2 new (Download, Unzip)
• Same connection styles (serial/parallel/branch-case)
• Same minimap, legend, toast, toolbar layout
• Same drag, selection, scroll, resize behavior
• Same PNG/JSON export/import
• Same SSE-based execution with live status updates

---

How to Integrate

Option A: Direct Copy (simplest)

# VL-Code
cp vl-workflow-engine/ui/workflow-editor.html vl-code/src/web/public/workflow-editor.html

# VLCode-Lite
cp vl-workflow-engine/ui/workflow-editor.html VLCode-Lite/public/workflow-editor.html

No other changes needed — the PostMessage API is fully backward compatible.

Option B: Symlink (keeps in sync)

# VL-Code
ln -sf ../../../../VL-Workflow-Engine/ui/workflow-editor.html vl-code/src/web/public/workflow-editor.html

# VLCode-Lite
ln -sf ../VL-Workflow-Engine/ui/workflow-editor.html VLCode-Lite/public/workflow-editor.html

Option C: npm dependency (for VLClaw and future consumers)

const path = require('path');
const editorPath = path.join(require.resolve('vl-workflow-engine'), '..', 'ui', 'workflow-editor.html');
// Serve this file via your static file handler or express.static

---

API Endpoints Required

The editor calls these endpoints directly (same-origin). Consumers must ensure these routes exist:

Method	Path	Purpose	Required?
POST	/api/workflow/execute	Start a workflow (SSE response)	Yes (existing)
POST	/api/workflow/rerun	Re-run from step with checkpoint + overrides (SSE response)	New (for re-run feature)
POST	/api/workflow/:runID/pause	Pause a running workflow	New (for pause feature)
POST	/api/workflow/:runID/abort	Abort a running workflow	Recommended
GET	/api/workflow/:runID/checkpoint	Fetch latest checkpoint	Recommended (fallback: localStorage)

If /api/workflow/rerun is not implemented, the editor falls back to /api/workflow/execute with { fromStep, checkpoint, overrides } params. See the engine's executeFrom() API for implementation details in API.md.

---

PostMessage API (Extended)

Parent → iframe

Message	Payload	Since	Description
loadWorkflow	{ type: 'loadWorkflow', data: workflowJSON }	v1.0	Parse and render a workflow
updateNodeStatus	{ type: 'updateNodeStatus', nodeId, status }	v1.0	Update node status
highlightNode	{ type: 'highlightNode', nodeId }	v1.0	Select and scroll to a node
clearStatus	{ type: 'clearStatus' }	v1.0	Clear all node statuses
setCheckpoint	{ type: 'setCheckpoint', checkpoint, runID }	v2.1	Store a checkpoint (persists to localStorage)
rerunFromStep	{ type: 'rerunFromStep', nodeId, overrides? }	v2.1	Programmatically trigger re-run from a step
editNode	{ type: 'editNode', nodeId }	v2.1	Open the edit modal for a node

iframe → Parent

Message	Payload	Since	Description
ready	{ type: 'ready' }	v1.0	iframe is ready
nodeClick	{ type: 'nodeClick', nodeId, nodeType, nodeData }	v1.0	User clicked a node
workflowImported	{ type: 'workflowImported', workflow }	v1.0	User imported JSON
nodeEdited	{ type: 'nodeEdited', nodeId, nodeData, overrides }	v2.1	User edited node inputs and triggered re-run

---

Supported Node Types (13 total)

Type	Icon	Color	Since
LLM	AI	Indigo-purple	v1.0
Service	SV	Green	v1.0
API	AP	Cyan	v1.0
Component	CP	Teal	v1.0
Set	=	Blue	v1.0
Write	WR	Orange	v1.0
Branch	BR	Purple	v1.0
Loop	LP	Pink	v1.0
Stop	ST	Red	v1.0
Pause	⏸	Violet	v1.0
Fork	FK	Emerald	v1.0
Download	DL	Sky blue	v2.0
Unzip	UZ	Yellow	v2.0

---

User Workflows

Breakpoint Resume (page refresh)

1. User runs workflow → nodes light up green/orange/red
2. Page refreshes / closes
3. User reopens → DAG renders with last-known node statuses (from localStorage)
4. User right-clicks a failed/incomplete node → "Re-run from here"
5. Engine resumes from that step using saved checkpoint

Edit & Re-run (fix bad input)

1. Workflow finishes but LLM output was wrong
2. User right-clicks the LLM node → "Edit inputs & re-run"
3. Modal shows: model, max_tokens, messages (editable JSON)
4. User fixes the prompt, adds variable overrides if needed
5. Clicks "Re-run from here" → engine resumes from that node with new inputs
6. Downstream nodes re-execute; upstream results are preserved

Pause & Inspect

1. User clicks "Pause" during execution
2. Workflow pauses cleanly; checkpoint saved
3. User inspects node statuses, variables
4. User can resume from any node or edit inputs first

---

Testing

After integration, verify:

1. Spec 3.16: Loop while mode, BREAK badge, Download/Unzip nodes
2. Context menu: Right-click a node → menu appears with 4 options
3. Re-run: Right-click → "Re-run from here" → workflow resumes from that step
4. Edit modal: Right-click → "Edit inputs" → modal shows type-specific fields
5. Checkpoint persistence: Run workflow, refresh page → node statuses restored
6. Pause: Click pause during execution → workflow stops, checkpoint saved