chore: update agentflow workflow and add changelog

.github/workflows/publish-agentflow.yml

@@ -18,12 +18,13 @@ on:
                 required: false
                 type: string
             tag:
-                description: 'npm dist-tag'
+                description: 'npm dist-tag (dev = internal, next = pre-release, latest = stable)'
                 required: false
                 type: choice
                 default: 'dev'
                 options:
                     - dev
+                    - next
                     - latest
 
 jobs:

packages/agentflow/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to `@flowiseai/agentflow` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.0-dev.13] - 2026-04-17
+
+### Added
+
+-   Core canvas functionality (add, connect, edit, delete, duplicate nodes)
+-   15 built-in node types (Start, Agent, LLM, Condition, Condition Agent, Human Input, Loop, Direct Reply, Custom Function, Tool, Retriever, Sticky Note, HTTP, Iteration, Execute Flow)
+-   Node editor dialog with dynamic input types (text, number, boolean, dropdown, arrays, JSON, code, variable selector, async options)
+-   Async option loading for models, tools, and credentials
+-   Variable system with `{{variable}}` syntax and visual picker
+-   Field visibility based on input values (show/hide conditions)
+-   Flow validation with visual feedback (empty flows, missing start node, disconnected nodes, cycles, hanging edges, per-node input errors)
+-   Connection constraints (single Start node, no nested Iteration, cycle prevention)
+-   Flow export as JSON with secret stripping
+-   AI flow generation from natural language descriptions
+-   Credential creation dialog inline from node editor
+-   Dark/light mode theming via design tokens and CSS variables
+-   Read-only mode for view-only embedding
+-   Custom rendering via `renderHeader` and `renderNodePalette` render props
+-   Imperative API via ref (`getFlow`, `validate`, `fitView`, `clear`, `addNode`, `toJSON`)
+-   Request interceptor for customizing outgoing API requests
+-   Dirty state tracking
+-   Keyboard shortcut: Cmd/Ctrl+S to save
+-   CodeMirror rich code editor (JavaScript, Python, JSON)
+-   TipTap rich text / markdown editor
+-   10 working examples demonstrating all features

packages/agentflow/README.md

@@ -5,17 +5,21 @@
 
 > Embeddable React component for building and visualizing AI agent workflows
 
-## ⚠️ Status
+## Status: Dev
 
-**This package is currently under active development.**
+**Current version: `0.0.0-dev.13`**
 
--   🚧 Components are not yet fully functional
--   ❌ End-to-end functionality is not complete
--   🔄 Features are still being implemented and tested
--   ⚡ APIs may change before stable release
--   📝 Documentation is being updated as development progresses
+This package is functional and has comprehensive test coverage, but the public API may still change before a stable release. It is suitable for early integration and testing but not yet recommended for production use.
 
-**Cannot be used in production. For development and testing purposes only.**
+**What works today:**
+
+-   13 node types with full editing support (Loop and Human Input nodes are present in the palette but not yet fully verified end-to-end)
+-   Connection validation, flow validation, and export
+-   Async option loading (models, credentials, tools)
+-   Variable picker and field visibility conditions
+-   AI flow generation from natural language
+-   Dark/light mode theming
+-   Read-only mode and custom rendering via render props
 
 ## Overview
 
@@ -24,7 +28,7 @@
 ## Features
 
 -   **Visual Canvas** — Drag-and-drop flow editor built on ReactFlow with zoom, pan, minimap, and fit-to-view controls
--   **15 Built-in Node Types** — Start, Agent, LLM, Condition, Condition Agent, Human Input, Loop, Direct Reply, Custom Function, Tool, Retriever, Sticky Note, HTTP, Iteration, and Execute Flow
+-   **13 Built-in Node Types** — Start, Agent, LLM, Condition, Condition Agent, Direct Reply, Custom Function, Tool, Retriever, Sticky Note, HTTP, Iteration, and Execute Flow
 -   **Node Editor Dialog** — Modal for editing node parameters with dynamic input types (text, number, boolean, dropdown, arrays, JSON, code, variable selector, async options)
 -   **Credential Management** — Create and edit credentials inline from the node editor
 -   **Rich Text Editor** — TipTap-based editor with syntax highlighting for JavaScript, TypeScript, Python, and JSON (lazy-loaded)
@@ -113,6 +117,22 @@ export default function App() {
 }
 ```
 
+### More Examples
+
+The [examples app](./examples/README.md) includes working demos for:
+
+-   **Variable usage** — `{{variable}}` syntax, variable picker, available sources
+-   **Async options** — Loading models, tools, and credentials from the API
+-   **Status indicators** — Node execution states (running, finished, error, stopped)
+-   **Field visibility** — Show/hide conditions on node inputs
+-   **State management** — Dirty tracking, flow change callbacks
+-   **Dark mode** — Light/dark theme toggle
+-   **Custom UI** — Custom header and node palette via render props
+-   **Filtered components** — Restricting available node types with presets
+-   **Validation actions** — Validation button, error display, and custom `canvasActions` alongside built-in controls
+
+Run `cd examples && npm install && npm run dev` to try them locally.
+
 ## Props
 
 <!-- prettier-ignore -->
@@ -122,6 +142,7 @@ export default function App() {
 | `token`              | `string`                                   | —              | Authentication token for API calls                              |
 | `requestInterceptor` | `(config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig` | — | Customize outgoing API requests (e.g., set `withCredentials`, add headers). The callback receives the full Axios request config — only modify what you need. See [Security: requestInterceptor](#security-requestinterceptor) below. |
 | `initialFlow`        | `FlowData`                                 | —              | Initial flow data to render (uncontrolled — only used on mount) |
+| `flowId`             | `string`                                   | —              | Flow identifier (reserved for future use)                       |
 | `components`         | `string[]`                                 | —              | Restrict which node types appear in the palette                 |
 | `onFlowChange`       | `(flow: FlowData) => void`                 | —              | Called when the flow changes (node/edge add, remove, move)      |
 | `onSave`             | `(flow: FlowData) => void`                 | —              | Called when the user triggers a save                            |
@@ -131,6 +152,7 @@ export default function App() {
 | `showDefaultHeader`  | `boolean`                                  | `true`         | Show built-in header (ignored if `renderHeader` provided)       |
 | `showDefaultPalette` | `boolean`                                  | `true`         | Show built-in node palette                                      |
 | `enableGenerator`    | `boolean`                                  | `true`         | Show the AI flow generator button                               |
+| `canvasActions`      | `ReactNode`                                | —              | Additional content rendered in the top-right canvas overlay, to the right of the built-in validation FAB. Hidden when `readOnly` is true. |
 | `renderHeader`       | `(props: HeaderRenderProps) => ReactNode`  | —              | Custom header renderer                                          |
 | `renderNodePalette`  | `(props: PaletteRenderProps) => ReactNode` | —              | Custom node palette renderer                                    |
 
@@ -168,8 +190,6 @@ The following node types are available in the palette by default. Use the `compo
 | `llmAgentflow`             | LLM / language model call            |
 | `conditionAgentflow`       | Conditional branching                |
 | `conditionAgentAgentflow`  | Agent-level conditional branching    |
-| `humanInputAgentflow`      | Wait for user input                  |
-| `loopAgentflow`            | Loop / iteration                     |
 | `directReplyAgentflow`     | Direct response to user              |
 | `customFunctionAgentflow`  | Custom JavaScript function           |
 | `toolAgentflow`            | Tool integration                     |
@@ -201,44 +221,35 @@ cd examples && pnpm install && pnpm dev
 
 Visit the [examples](./examples) directory for more usage patterns. See [TESTS.md](./TESTS.md) for the full test plan and coverage status.
 
-## Publishing
+## Troubleshooting
 
-### Version Update
+### API Connection Issues
 
-Bump the version in `package.json` before publishing. Use `npm version` to update the version and create a git tag:
+-   **CORS errors** — Ensure the Flowise server allows requests from your app's origin. Check the Flowise CORS configuration.
+-   **401 Unauthorized** — Use an API Key (Settings > API Keys), not a JWT user token. Verify the key is passed via the `token` prop.
+-   **Wrong `apiBaseUrl`** — The URL must point to the Flowise API root (e.g., `http://localhost:3000`), not a subpath.
 
-```bash
-# Prerelease (for testing)
-npm version prerelease --preid=dev   # 0.0.0-dev.1 → 0.0.0-dev.2
+### Validation Errors
 
-# Patch / Minor / Major (for stable releases)
-npm version patch                    # 0.0.1
-npm version minor                    # 0.1.0
-npm version major                    # 1.0.0
-```
+-   **"Flow is empty"** — Add at least one node to the canvas.
+-   **"Missing start node"** — Every flow requires a `startAgentflow` node. Add one from the palette.
+-   **"Disconnected nodes"** — All non-sticky-note nodes must be reachable from the start node. Connect any orphaned nodes.
+-   **"Cycle detected"** — Flows must be acyclic (DAGs). Remove the edge that creates the cycle.
 
-### Verify Before Publishing
+### Theme Issues
 
-```bash
-# Build and check the tarball contents
-pnpm build
-npm pack --dry-run
-
-# Full publish dry-run (runs prepublishOnly + simulates upload)
-npm publish --dry-run
-```
+-   **Dark mode not applying** — Pass `isDarkMode={true}` as a prop. The component uses its own design tokens and does not inherit from the host app's theme.
+-   **Style conflicts** — Ensure `@flowiseai/agentflow/flowise.css` is imported. The component's CSS variables are scoped to avoid collisions.
 
-### Publish
+### Variables Not Resolving
 
-```bash
-# Prerelease — tagged so `npm install @flowiseai/agentflow` won't pick it up
-npm publish --tag dev
+-   **Variable not in picker** — Variables are sourced from upstream nodes. Ensure the source node is connected and upstream of the current node.
+-   **Incorrect path** — Variable syntax is `{{nodeName.outputKey}}`. Check that the node name and output key match exactly.
 
-# Stable release — gets the `latest` tag
-npm publish
-```
+### Async Options Not Loading
 
-> The `prepublishOnly` script automatically runs `clean` and `build` before every publish, so stale dist files are never uploaded.
+-   **Empty dropdowns for models/tools/credentials** — These load from the Flowise API. Verify `apiBaseUrl` and `token` are correct and the server is running.
+-   **Network errors in console** — Check browser DevTools for failed requests. The API client logs errors to the console.
 
 ## Documentation
 

packages/agentflow/TESTS.md

@@ -34,6 +34,7 @@ Presentational components that are mostly JSX. Only add tests if the component c
 
 The Jest config uses file extensions to select the test environment:
 
+<!-- prettier-ignore -->
 | Extension   | Environment             | When to use                                                                |
 | ----------- | ----------------------- | -------------------------------------------------------------------------- |
 | `.test.ts`  | **node** (no DOM)       | Pure logic — utilities, reducers, data transformations                     |
@@ -98,6 +99,8 @@ jest.mock('@/infrastructure/store', () => ({
 
 **CSS/SVG** (`src/__mocks__/styleMock.js`): Empty object export for CSS and SVG imports.
 
+**TipTap** (`src/__mocks__/@tiptap/`): Stubs for `@tiptap/react` and related ESM-only packages that cannot run in Jest's CommonJS environment. The RichTextEditor component is lazy-loaded in production, so these mocks only affect tests that import it directly.
+
 ### Custom Jest Environment
 
 `src/__test_utils__/jest-environment-jsdom.js` intercepts `require('canvas')` and returns a mock before jsdom tries to load the native binary. This prevents build failures in environments without native canvas compilation.

packages/agentflow/examples/README.md

@@ -122,14 +122,30 @@ Full integration with a running Flowise instance. Requires `VITE_FLOW_ID` for th
 
 ### Additional Examples
 
-| Example                 | File                            | Description                                                                          |
-| ----------------------- | ------------------------------- | ------------------------------------------------------------------------------------ |
-| **Multi-Node Flow**     | `MultiNodeFlow.tsx`             | Complete translation agent flow with multiple connected nodes showing gradient edges |
-| **Dark Mode**           | `DarkModeExample.tsx`           | Theme toggle demonstrating light/dark mode support                                   |
-| **Status Indicators**   | `StatusIndicatorsExample.tsx`   | Node execution states (running, finished, error, stopped) with animated loader       |
-| **Custom UI**           | `CustomUIExample.tsx`           | Custom header and node palette using render props                                    |
-| **All Node Types**      | `AllNodeTypesExample.tsx`       | Visual catalog of all 15 available node types with colors and icons                  |
-| **Filtered Components** | `FilteredComponentsExample.tsx` | Restricting available nodes with preset configurations                               |
+| Example                 | File                            | Description                                                                              |
+| ----------------------- | ------------------------------- | ---------------------------------------------------------------------------------------- |
+| **Multi-Node Flow**     | `MultiNodeFlow.tsx`             | Complete translation agent flow with multiple connected nodes showing gradient edges     |
+| **Dark Mode**           | `DarkModeExample.tsx`           | Theme toggle demonstrating light/dark mode support                                       |
+| **Status Indicators**   | `StatusIndicatorsExample.tsx`   | Node execution states (running, finished, error, stopped) with animated loader           |
+| **Custom Node**         | `CustomNodeExample.tsx`         | Node with self-contained InputParam definitions and show/hide field visibility           |
+| **Custom UI**           | `CustomUIExample.tsx`           | Custom header and node palette using render props                                        |
+| **All Node Types**      | `AllNodeTypesExample.tsx`       | Visual catalog of all 15 available node types with colors and icons                      |
+| **Filtered Components** | `FilteredComponentsExample.tsx` | Restricting available nodes with preset configurations                                   |
+| **Validation Actions**  | `ValidationActionsExample.tsx`  | Validation button, error display, and custom `canvasActions` alongside built-in controls |
+
+### Feature Coverage
+
+| Feature                                        | Demonstrated In                |
+| ---------------------------------------------- | ------------------------------ |
+| Variable usage (`{{variable}}` syntax, picker) | Custom Node                    |
+| Async options (models, tools, credentials)     | Basic Usage (with running API) |
+| Flow execution status indicators               | Status Indicators              |
+| Field visibility (show/hide conditions)        | Custom Node                    |
+| State management (dirty tracking, callbacks)   | Basic Usage                    |
+| Dark/light mode theming                        | Dark Mode                      |
+| Custom header and palette via render props     | Custom UI                      |
+| Restricting node types with `components` prop  | Filtered Components            |
+| Validation actions and custom `canvasActions`  | Validation Actions             |
 
 ## Switching Examples