@humain/workflow

@humain/workflow is a React-only workflow editor. Start with its semantic preset catalog, then add only the product definitions and adapters your application owns.

Install

npm install @humain/ui @humain/workflow lucide-react

Import the two public stylesheets once at the application entrypoint:

import '@humain/ui/styles.css';
import '@humain/workflow/styles.css';

Do not import package source paths, internal graph modules, or @xyflow/react. The graph engine is a private implementation detail.

Layered imports

The root entry remains supported for existing consumers. New code can import from the narrowest public layer so its bundler does not retain the editor stack for domain-only or non-visual runtime usage:

import {
  createWorkflowPresetRegistry,
  validateWorkflowDocument,
} from '@humain/workflow/domain';
import { createWorkflowExecutionController } from '@humain/workflow/runtime';
import { WorkflowEditor } from '@humain/workflow/editor';

• @humain/workflow/domain contains JSON-safe contracts and pure workflow behavior.
• @humain/workflow/runtime contains non-React controllers and adapter state.
• @humain/workflow/editor contains React hooks, messages, and editor components.

Import @humain/workflow/styles.css when rendering the editor. Emitted files outside these documented entry points are private implementation details.

Preset-first quick start

include preserves the product-supplied order. It does not sort presets into the package's default catalog order.

import { ThemeProvider } from '@humain/ui';
import {
  createWorkflowNodeRegistry,
  createWorkflowPresetDefinitions,
  type WorkflowDocument,
  WorkflowEditor,
} from '@humain/workflow';
import { useState } from 'react';

const definitions = createWorkflowPresetDefinitions({
  include: ['manual-trigger', 'ai-agent', 'http-request', 'workflow-end'],
});
const registry = createWorkflowNodeRegistry(definitions);

const initialDocument: WorkflowDocument = {
  schemaVersion: 1,
  id: 'support-flow',
  name: 'Support flow',
  nodes: [
    {
      id: 'start',
      type: 'manual-trigger',
      position: { x: 80, y: 220 },
      configuration: {},
    },
    {
      id: 'agent',
      type: 'ai-agent',
      position: { x: 360, y: 220 },
      configuration: {},
    },
    {
      id: 'http',
      type: 'http-request',
      position: { x: 360, y: 460 },
      configuration: {},
    },
    {
      id: 'end',
      type: 'workflow-end',
      position: { x: 660, y: 220 },
      configuration: {},
    },
  ],
  edges: [
    {
      id: 'start-to-agent',
      sourceNodeId: 'start',
      sourcePortId: 'output',
      targetNodeId: 'agent',
      targetPortId: 'input',
    },
    {
      id: 'agent-tool-to-http',
      sourceNodeId: 'agent',
      sourcePortId: 'tool-primary',
      targetNodeId: 'http',
      targetPortId: 'tool-input',
    },
    {
      id: 'agent-to-end',
      sourceNodeId: 'agent',
      sourcePortId: 'output',
      targetNodeId: 'end',
      targetPortId: 'input',
    },
  ],
};

export function SupportWorkflow() {
  const [document, setDocument] = useState(initialDocument);

  return (
    <ThemeProvider>
      <WorkflowEditor
        document={document}
        registry={registry}
        nodeCatalogDefinitions={definitions}
        onDocumentChange={({ document: nextDocument }) =>
          setDocument(nextDocument)
        }
      />
    </ThemeProvider>
  );
}

The first and third edges are semantic data flow (output to input). The middle edge is the named AI tool relationship (tool-primary to tool-input). Persist this JSON-only document shape; React elements, functions, clients, credentials, and secrets belong outside it.

Use defaultDocument instead of document when the editor should own its local state. Use document with onDocumentChange when the host owns state and acknowledges every proposal. Do not mix the two ownership models.

Ownership and extension

The package owns editing, graph projection, structural validation, history, accessibility behavior, and package-created copy. The host owns persistence, product validation, publication, execution, authentication, authorization, credentials, secret storage, and service clients. Supply the host-owned adapters through WorkflowEditor rather than embedding services in a node definition or workflow document.

Adapter replacement lifecycle

During an active durable operation, replacing the validation adapter cancels validation-dependent saves and publications; replacing the publication adapter cancels only publication; and replacing the persistence adapter cancels only saves. Pending autosave is rescheduled against the replacement validation adapter. Obsolete outcomes are ignored, and cleanup removes only the operation's own busy feedback so newer unrelated notices remain visible. Updating messages.controllerErrors alone only refreshes fallback copy and does not cancel active host work.

Live announcements

useWorkflowAnnouncements accepts an optional reannounceKey. Change that key when an otherwise identical message represents a new event; the hook first clears both live regions, then publishes the message again so assistive technology can announce it reliably. First-time and changed messages remain available immediately without that repeat transition. Clearing message empties the regions but retains the prior event identity, so a later identical event with a new key still receives the repeat transition.

Execution safety

WorkflowEditor defaults executionMode to "simulation". When an execution adapter can cause side effects, pass executionMode="live" and keep that prop current whenever the host's execution configuration changes. @humain/workflow does not inspect an adapter or workflow to infer safety, authorization, or product policy.

In live mode, WorkflowEditor owns the confirmation boundary for every editor execution entry point. A standalone WorkflowGraphOutline still uses mode-aware labels, but its callbacks remain the consumer's confirmation policy.

Activated connections show a one-shot execution tracer by default. Its core uses the source port tone and its halo uses the source node tone. Pass showExecutionFlowAnimation={false} to keep execution state colors while removing spatial motion; the tracer is also hidden automatically for users who prefer reduced motion.

See the preset, custom-registry, and linear HTTP Request examples in Node registry, message and accessibility requirements in Accessibility and theming, and adapter contracts in Editor quickstart.

Coding-agent skill

npx @humain/workflow@latest skill
npx @humain/workflow@latest skill --project --agent codex --yes

The Workflow skill mirrors the public React-only contract: presets, documents, registries, copy, adapters, accessibility, and verification. The 0.1.x line is a preview API; pin the minor version until the package is promoted to a stable release.