This page ships a Markdown twin for AI tools.

Guides

Workflows docs

Install @texuli/workflows, build a typed graph, edit or view it. In development. Not a workflow runner.

Back to overview

What Workflows is

Workflows is an embeddable graph system: @texuli/workflows holds a typed model of nodes, ports and edges, a deterministic layout, an editor, an inspector, an accessible outline and a read-only viewer. The package is published as 0.18.0 and is **in development** (pre-1.0). Pin the exact version or use ^0.17.0.

It authors and views workflow diagrams. It does not run automations, persist graphs, or host a workflow service. The host app stores the graph and owns any runner.

The JSON live preview on this site stays at /workflows-page/json/. The technical docs you are reading live at /guides/solutions/workflows/.

What you get

  • Closed node types, validated operations, cycle policy and hard limits.
  • Layered auto-layout, left-to-right or top-to-bottom.
  • WorkflowEditor, WorkflowViewer and WorkflowInspector.
  • Canonical JSON (parseWorkflow / stringifyWorkflow) and a spec adapter for workflow-graph blueprints.

There is no hosted persistence. The host keeps the data.

Install

Svelte 5 (^5.57.2) is a peer of @texuli/workflows. Import @texuli/tokens/base.css once; each view imports its own CSS.

npm install @texuli/workflows

Build a graph and edit it

Declare node types, apply operations (each one is validated), lay the graph out, then pass it to WorkflowEditor.

<script lang="ts">
  import { WorkflowEditor } from '@texuli/workflows/editor';
  import { layoutMoves, layoutWorkflow } from '@texuli/workflows/layout';
  import {
    applyWorkflowOps,
    createWorkflow,
    defineNodeTypes,
    type WorkflowGraph,
  } from '@texuli/workflows/model';

  const registry = defineNodeTypes([
    {
      type: 'request',
      label: 'Request',
      category: 'Start',
      ports: [{ id: 'out', direction: 'out', dataType: 'any' }],
    },
    {
      type: 'end',
      label: 'End',
      category: 'Done',
      ports: [{ id: 'in', direction: 'in', dataType: 'any' }],
    },
  ]);

  const at = { x: 0, y: 0 };
  const built = applyWorkflowOps(
    createWorkflow(),
    [
      { op: 'addNode', node: { id: 'ask', type: 'request', label: 'Expense submitted', position: at } },
      { op: 'addNode', node: { id: 'paid', type: 'end', label: 'Paid', position: at } },
      {
        op: 'connect',
        edge: { id: 'e1', from: { node: 'ask', port: 'out' }, to: { node: 'paid', port: 'in' } },
      },
    ],
    { registry }
  );
  if (!built.ok) throw new Error(built.error.message);

  const moves = layoutMoves(layoutWorkflow(built.graph, { direction: 'LR' }));
  const laid = applyWorkflowOps(built.graph, [{ op: 'moveNodes', moves }], { registry });
  let graph = $state.raw<WorkflowGraph>(laid.ok ? laid.graph : built.graph);
</script>

<WorkflowEditor {graph} {registry} onchange={(next) => (graph = next)} />

For a read-only figure, use WorkflowViewer from @texuli/workflows/viewer with the same graph and registry and a label.

Graph model

Everything in @texuli/workflows/model is a pure function. defineNodeTypes declares the closed vocabulary. createWorkflow starts empty. applyWorkflowOps applies add, connect, move, group and remove operations; a refused operation changes nothing.

import {
  applyWorkflowOps,
  createWorkflow,
  createWorkflowHistory,
  defineNodeTypes,
  parseWorkflow,
  stringifyWorkflow,
} from '@texuli/workflows/model';

Every operation checks ports, directions, data types, cardinality, duplicates, the cycle policy and hard limits (500 nodes, 2,000 edges, 5,000 operations per batch). Labels are text; control and bidirectional override characters are refused. Link and image props pass the URL policy at the untrusted tier.

parseWorkflow and stringifyWorkflow round-trip canonical JSON. createWorkflowHistory is undo and redo for the host to keep.

Layout

layoutWorkflow and layoutMoves in @texuli/workflows/layout place nodes with a deterministic layered auto-layout, left-to-right or top-to-bottom, right-to-left aware. Apply the moves with applyWorkflowOps.

Spec adapter

fromSpecWorkflow and toSpecWorkflow in @texuli/workflows/spec-adapter convert the @texuli/spec workflowGraph JSON used by blueprint workflow-graph nodes.

Editor

WorkflowEditor from @texuli/workflows/editor is the Svelte 5 authoring surface: toolbar, palette, canvas with minimap, inspector and a treegrid outline. Parts also import on their own (WorkflowCanvas, WorkflowToolbar, WorkflowPalette, WorkflowMinimap, WorkflowOutline, WorkflowNodeBody).

The editor reports each change with onchange(graph, event). Undo and redo run on createWorkflowHistory. The host stores the graph.

Viewer and inspector

WorkflowViewer from @texuli/workflows/viewer is a read-only figure whose nodes are a list that says where each one leads. Pass a label. WorkflowInspector from @texuli/workflows/inspector edits the selected node's typed props.

Player

@texuli/player paints a workflow-graph node with this package: the viewer in view mode, the editor in edit mode, through the spec adapter. An agent can send a workflow as JSON. That painter is in development with the rest of Workflows.

The JSON live preview on this site is /workflows-page/json/.

Keyboard first

On the canvas, arrows move focus to the nearest node in that direction, Alt+Arrow nudges one grid step, Space toggles selection, Enter on a port starts connect mode (arrows cycle compatible ports, Enter connects, Escape cancels), Delete removes, and Ctrl or Cmd with Z / Y undoes and redoes. = / - zoom, and 0 fits the view.

The outline is a WAI-ARIA treegrid that reads and edits the whole graph without the canvas. The palette adds a node with a button press as well as a drag (WCAG 2.5.7).

Drag contract

The shared drag contract applies: localized announcements, 24 px targets, reduced motion and forced colors. Nothing renders as HTML.

Status

Workflows is **in development**. @texuli/workflows is on npm as 0.18.0. Under 0.x a new minor may break. Native rendering is planned, not built.

Not built

  • A live automation or workflow runner
  • Hosted persistence or multiplayer
  • A visual schema builder outside the typed graph
  • Native Compose, Android or iOS painting of the editor

Texuli draws and edits the graph. The host app stores it and owns any execution. Hard limits are 500 nodes and 2,000 edges.

Untrusted graphs

A graph from an agent, a paste or a share link is untrusted data. Use parseWorkflow or applyWorkflowOps so every operation is checked. Labels are text. There is no HTML sink.

Catalog and skill

Agents can emit a workflow-graph catalog node (view or edit). @texuli/player paints it with @texuli/workflows. The Texuli skill covers the editor, viewer, inspector, model and layout under skills/texuli/build-ui/SKILL.md.

Do not invent a hosted runner or an MCP operation that is not in @texuli/tools. Convert blueprint JSON with fromSpecWorkflow / toSpecWorkflow.