flowcraft 1.0.0-beta.1

package/docs/guide/recipes/data-processing-pipeline.md

@@ -0,0 +1,123 @@
+# Recipes: Creating a Data Processing Pipeline
+
+A common use case for a workflow is to process a piece of data through a series of transformation, validation, and storage steps. Flowcraft's fluent API on the `Node` class (`.map`, `.filter`, `.tap`, `.toContext`) is perfect for this, allowing you to define a clear, readable, and powerful pipeline.
+
+> [!IMPORTANT]
+> **Key Concept: Immutable Chains**
+>
+> Each method in the fluent chain (`.map`, `.filter`, etc.) is **immutable**. It returns a brand new `Node` instance and does **not** modify the node it was called on.
+>
+> You must capture the result of the chain in a variable.
+>
+> **Correct:**
+>
+> ```typescript
+> // The entire chain is assigned to a new variable.
+> const userProcessingPipeline = new ValueNode(rawUser)
+>   .tap(...)
+>   .map(...)
+> ```
+>
+> **Incorrect:**
+>
+> ```typescript
+> const startNode = new ValueNode(rawUser);
+> // This does nothing! The new node returned by .tap() is discarded.
+> startNode.tap(...);
+> ```
+
+## The Goal
+
+Create a workflow that:
+
+1. Starts with a raw user object.
+2. Logs the initial object for debugging (`.tap`).
+3. Transforms the object into a more usable format (`.map`).
+4. Filters out inactive users (`.filter`).
+5. Stores the final, processed data in the `Context` (`.toContext`).
+
+```mermaid
+graph TD
+    A[Start: Raw User] --> B["tap(log raw)"]
+    B --> C["map(transform)"]
+    C --> D{"filter(isActive)"}
+    D -- "true" --> E["toContext(save)"]
+    D -- "false" --> F[End / Discard]
+```
+
+## The Implementation
+
+We can define this entire pipeline by chaining methods, starting from a simple node that provides the initial data.
+
+### 1. The Pipeline Definition
+
+We'll use a `ValueNode` (a simple `Node` that just returns a value from its `exec` method) as the starting point for our chain.
+
+```typescript
+import { contextKey, FILTER_FAILED, Flow, Node, TypedContext } from 'flowcraft'
+
+// A simple node that just returns a value, to start our chain
+class ValueNode<T> extends Node<void, T> {
+	constructor(private value: T) { super() }
+	async exec(): Promise<T> { return this.value }
+}
+
+// Define context keys for our results
+const PROCESSED_USER = contextKey<string>('processed_user')
+const FAILED_USER_ID = contextKey<number>('failed_user_id')
+
+// Our raw input data
+const rawUser = { id: 42, firstName: 'jane', lastName: 'doe', status: 'active' }
+
+// --- The Pipeline ---
+const userProcessingPipeline = new ValueNode(rawUser)
+	.tap(user => console.log(`[DEBUG] Processing user ID: ${user.id}`))
+	.map(user => ({
+		userId: user.id,
+		fullName: `${user.firstName.charAt(0).toUpperCase()}${user.firstName.slice(1)} ${user.lastName.toUpperCase()}`,
+		isActive: user.status === 'active',
+	}))
+	.filter(processedUser => processedUser.isActive) // <-- This is our conditional gate
+	.map(activeUser => `Welcome, ${activeUser.fullName}!`)
+	.toContext(PROCESSED_USER) // <-- This only runs if the filter passes
+```
+
+### 2. Wiring the Branches
+
+The `.filter()` method creates a branch. The `DEFAULT_ACTION` path continues the chain if the filter passes. The `FILTER_FAILED` path is taken if it fails. We need to wire up a node to handle that failure path.
+
+```typescript
+// A node to handle the case where the filter fails
+const handleInactiveUser = new ValueNode(rawUser)
+	.map(user => user.id)
+	.toContext(FAILED_USER_ID)
+
+// Connect the failure path
+userProcessingPipeline.next(handleInactiveUser, FILTER_FAILED)
+
+const flow = new Flow(userProcessingPipeline)
+```
+
+### 3. Running the Pipeline
+
+Now, let's run it. Since our user is `active`, the filter will pass.
+
+```typescript
+const context = new TypedContext()
+await flow.run(context)
+
+console.log('\n--- Active User Result ---')
+console.log('Processed User:', context.get(PROCESSED_USER)) // "Welcome, Jane DOE!"
+console.log('Failed User ID:', context.get(FAILED_USER_ID)) // undefined
+```
+
+If we change the input data to be an inactive user:
+`const rawUser = { id: 99, ..., status: 'inactive' }`, the output would be:
+
+```
+--- Inactive User Result ---
+Processed User: undefined
+Failed User ID: 99
+```
+
+This demonstrates how to build a concise yet powerful data processing sequence that includes transformation, debugging, conditional logic, and state management, all in a single, readable chain.

package/docs/guide/recipes/fan-out-fan-in.md

@@ -0,0 +1,112 @@
+# Recipes: Dynamic Fan-Out and Fan-In
+
+A "fan-out, fan-in" pattern is where a workflow splits into multiple parallel branches that execute concurrently (fan-out) and then merges the results of those branches back together before proceeding (fan-in).
+
+Flowcraft provides a dedicated `ParallelFlow` builder that makes creating this pattern simple and declarative.
+
+## The Pattern
+
+1. **`ParallelFlow`**: This builder takes an array of nodes that will be executed concurrently.
+2. **Aggregation Node**: A single node is connected to the `ParallelFlow` instance. It will only run after *all* the parallel branches have completed, allowing it to "fan-in" or aggregate the results from the `Context`.
+
+```mermaid
+graph TD
+    A[Start] --> B(ParallelFlow)
+    subgraph "Run in Parallel"
+      B --> C[Process Branch 1]
+      B --> D[Process Branch 2]
+      B --> E[...]
+    end
+    C --> F((Aggregate Results))
+    D --> F
+    E --> F
+```
+
+## Example: Parallel Data Enrichment
+
+Imagine we have a user object and we want to perform two slow, independent API calls simultaneously: one to get the user's recent activity and another to get their profile metadata.
+
+### 1. Define Context and Nodes
+
+We'll need keys for the initial input and the results of each parallel branch.
+
+```typescript
+import { contextKey, Flow, Node, ParallelFlow, TypedContext } from 'flowcraft'
+
+// Context Keys
+const USER_ID = contextKey<string>('user_id')
+const ACTIVITY_DATA = contextKey<any>('activity_data')
+const METADATA = contextKey<any>('metadata')
+const FINAL_REPORT = contextKey<string>('final_report')
+
+// A mock API call
+function mockApiCall(operation: string, delay: number) {
+	console.log(`Starting API call: ${operation}...`)
+	return new Promise(resolve => setTimeout(() => {
+		console.log(`...Finished API call: ${operation}`)
+		resolve({ result: `${operation} data` })
+	}, delay))
+}
+
+// Nodes for each parallel task
+const fetchActivityNode = new Node()
+	.exec(async ({ ctx }) => mockApiCall(`fetchActivity for ${ctx.get(USER_ID)}`, 100))
+	.toContext(ACTIVITY_DATA)
+
+const fetchMetadataNode = new Node()
+	.exec(async ({ ctx }) => mockApiCall(`fetchMetadata for ${ctx.get(USER_ID)}`, 150))
+	.toContext(METADATA)
+
+// The final aggregation node (the "fan-in" point)
+const createReportNode = new Node()
+	.exec(async ({ ctx }) => {
+		const activity = ctx.get(ACTIVITY_DATA)
+		const metadata = ctx.get(METADATA)
+		return `Report created. Activity: ${activity.result}, Metadata: ${metadata.result}`
+	})
+	.toContext(FINAL_REPORT)
+```
+
+### 2. Wire the Flow with `ParallelFlow`
+
+We create a `ParallelFlow` instance with our two API-calling nodes. Then, we connect our aggregation node to run after the parallel block is complete.
+
+```typescript
+// Create the parallel fan-out block
+const parallelEnrichment = new ParallelFlow([
+	fetchActivityNode,
+	fetchMetadataNode,
+])
+
+// After all parallel nodes are done, run the report node.
+parallelEnrichment.next(createReportNode)
+
+const enrichmentFlow = new Flow(parallelEnrichment)
+```
+
+### 3. Run the Flow
+
+```typescript
+const context = new TypedContext([
+	[USER_ID, 'user-123']
+])
+
+console.time('ParallelExecution')
+await enrichmentFlow.run(context)
+console.timeEnd('ParallelExecution')
+
+console.log(context.get(FINAL_REPORT))
+```
+
+The output will be:
+
+```
+Starting API call: fetchActivity for user-123...
+Starting API call: fetchMetadata for user-123...
+...Finished API call: fetchActivity for user-123
+...Finished API call: fetchMetadata for user-123
+ParallelExecution: 155.25ms
+Report created. Activity: fetchActivity for user-123 data, Metadata: fetchMetadata for user-123 data
+```
+
+Notice that the total execution time is approximately the duration of the *longest* API call (150ms), not the sum of both (~250ms). This demonstrates how the `ParallelFlow` builder provides a clean and powerful way to implement the fan-out, fan-in pattern for I/O-bound tasks. The `GraphBuilder` uses this same component internally whenever it detects this pattern in a declarative graph.

package/docs/guide/recipes/index.md

@@ -0,0 +1,15 @@
+# Recipes
+
+This section provides practical, copy-paste-friendly solutions for common patterns you'll encounter when building workflows with Flowcraft.
+
+- **[Creating a Loop](./creating-a-loop.md)**
+  - Learn how to use a cyclical graph structure to repeat actions until a condition is met.
+
+- **[Dynamic Fan-Out and Fan-In](./fan-out-fan-in.md)**
+  - See how to split your workflow into parallel branches and merge the results.
+
+- **[Building a Resilient API Call Node](./resilient-api-call.md)**
+  - A crucial pattern for any real-world application. Learn how to build a node that automatically retries on failure and has a fallback plan.
+
+- **[Creating a Data Processing Pipeline](./data-processing-pipeline.md)**
+  - Discover the power of the fluent API (`.map`, `.filter`, `.tap`) to build concise and readable data transformation chains.

package/docs/guide/recipes/resilient-api-call.md

@@ -0,0 +1,110 @@
+# Recipes: Building a Resilient API Call Node
+
+A very common task in any workflow is calling an external API. These calls can be unreliable due to network issues or temporary service outages. This recipe shows you how to build a robust `Node` that can handle these failures gracefully using Flowcraft's built-in retry and fallback mechanisms.
+
+## The Goal
+
+Create a node that:
+
+1. Calls an external API.
+2. If the API call fails, automatically retries the call a few times.
+3. If all retries fail, executes a fallback logic (e.g., returns a cached or default value) so the workflow can continue.
+
+```mermaid
+graph TD
+    A[Start] --> B{Call API}
+    B -- Success --> D[Proceed]
+    B -- Failure --> C{Retry?}
+    C -- "Yes (< 3 attempts)" --> B
+    C -- "No (all retries failed)" --> E[Execute Fallback]
+    E --> D
+```
+
+## The Implementation
+
+We will create a `FetchDataNode` that simulates calling a flaky API.
+
+### 1. The Node Definition
+
+We configure the node's retry behavior directly in its constructor options. The core logic is in `exec`, and the safety net is in `execFallback`.
+
+```typescript
+import { contextKey, Node, NodeArgs, TypedContext } from 'flowcraft'
+
+const API_RESULT = contextKey<any>('api_result')
+
+class FetchDataNode extends Node<void, any> {
+	private attempts = 0
+
+	constructor() {
+		// Configure the node to try a total of 3 times (1 initial + 2 retries),
+		// waiting 200ms between attempts.
+		super({ maxRetries: 3, wait: 200 })
+	}
+
+	// The main logic: try to call the API.
+	async exec(): Promise<any> {
+		this.attempts++
+		console.log(`Attempting to call API... (attempt #${this.attempts})`)
+
+		// Simulate a failing API
+		if (this.attempts < 3) {
+			throw new Error('API service is temporarily unavailable.')
+		}
+
+		// This will only be reached on the 3rd attempt in our simulation.
+		console.log('API call successful!')
+		return { id: 123, data: 'live data from API' }
+	}
+
+	// The fallback logic: run if all `exec` attempts fail.
+	async execFallback({ error }): Promise<any> {
+		console.error(`All API attempts failed. Final error: "${error.message}"`)
+		console.log('Returning cached/default data as a fallback.')
+		return { id: 123, data: 'cached fallback data' }
+	}
+
+	// The post-logic: store the result (from either exec or execFallback)
+	async post({ ctx, execRes }: NodeArgs<void, any>) {
+		ctx.set(API_RESULT, execRes)
+	}
+}
+```
+
+### 2. Running the Resilient Node
+
+Now, we can run this node as part of a flow. Even though the API "fails" twice, the workflow will complete successfully because of the retry and fallback logic.
+
+```typescript
+import { ConsoleLogger, Flow, TypedContext } from 'flowcraft'
+
+const resilientNode = new FetchDataNode()
+const flow = new Flow(resilientNode)
+const context = new TypedContext()
+
+// Use a logger to see the retry warnings
+await flow.run(context, { logger: new ConsoleLogger() })
+
+console.log('\nWorkflow complete.')
+console.log('Final result in context:', context.get(API_RESULT))
+```
+
+### Expected Output
+
+The output shows the node attempting the call, logging warnings for the retries, executing the fallback, and the workflow completing successfully with the fallback data.
+
+```
+[INFO] Running node: FetchDataNode
+Attempting to call API... (attempt #1)
+[WARN] Attempt 1/3 failed for FetchDataNode. Retrying...
+Attempting to call API... (attempt #2)
+[WARN] Attempt 2/3 failed for FetchDataNode. Retrying...
+[ERROR] All retries failed for FetchDataNode. Executing fallback.
+All API attempts failed. Final error: "API service is temporarily unavailable."
+Returning cached/default data as a fallback.
+
+Workflow complete.
+Final result in context: { id: 123, data: 'cached fallback data' }
+```
+
+This pattern is essential for building production-grade workflows that can withstand transient failures. For more details, see the full guide on **[Error Handling](../advanced-guides/error-handling.md)**.

package/docs/guide/tooling/graph-validation.md

@@ -0,0 +1,160 @@
+# Validating Workflows with Graph Analysis
+
+As your workflows grow in complexity, it becomes crucial to ensure their structural integrity before they are ever executed. A graph with a cycle, an orphaned node, or an incorrect connection can lead to unexpected runtime behavior or infinite loops.
+
+Flowcraft provides a powerful, lightweight, and **type-safe** utility library for performing static analysis and validation on your declarative `WorkflowGraph` definitions. This allows you to catch errors early, enforce best practices, and build more reliable systems.
+
+## The `analyzeGraph` Utility
+
+The foundation of the validation library is the `analyzeGraph` function. This is a pure, static utility that takes a `WorkflowGraph` object and returns a rich `GraphAnalysis` object containing pre-computed metadata about the graph's structure.
+
+-   **`nodes`**: A map of all nodes, augmented with their `inDegree` and `outDegree`.
+-   **`startNodeIds`**: An array of all node IDs with no incoming connections.
+-   **`cycles`**: An array of any cycles found, where each cycle is an array of node IDs.
+
+```typescript
+import { analyzeGraph } from 'flowcraft'
+import { myGraph } from './my-workflows'
+
+const analysis = analyzeGraph(myGraph)
+console.log('Start Nodes:', analysis.startNodeIds)
+console.log('Cycles Found:', analysis.cycles.length)
+```
+
+## Writing Validation Rules
+
+The real power comes from creating declarative validation rules that operate on this analysis data.
+
+### `createNodeRule` Factory
+
+This factory function is the primary tool for building custom validators. It takes three arguments:
+
+1.  `description`: A string describing the rule for clear error messages.
+2.  `filter`: A function that selects which nodes the rule should apply to (e.g., `node => node.type === 'output'`).
+3.  `check`: A function that receives a selected node and returns whether it's valid.
+
+### Built-in Validators
+
+Flowcraft includes a pre-built validator for the most common and critical graph error:
+
+-   `checkForCycles`: A validator that checks the analysis for any cycles and returns a `ValidationError` for each one found.
+
+## Putting It All Together: A Custom Validator
+
+Let's create a custom validation function for our application that enforces a set of rules.
+
+**Example Scenario**: Our application requires that:
+1.  All graphs must be acyclic (no loops).
+2.  Nodes of type `output` must be terminal (have no outgoing connections).
+3.  Nodes of type `condition` must have exactly one input.
+
+```typescript
+import type { MyAppNodeTypeMap } from './my-types' // Your application's node types
+import {
+	analyzeGraph,
+	checkForCycles,
+	createNodeRule,
+	TypedWorkflowGraph,
+	ValidationError
+} from 'flowcraft'
+
+// --- 1. Define the validation ruleset for our application ---
+const myRules = [
+	// Use the built-in cycle checker
+	checkForCycles,
+
+	// Rule: 'output' nodes must be terminal.
+	createNodeRule<MyAppNodeTypeMap>(
+		'Output must be terminal',
+		node => node.type === 'output',
+		node => ({
+			valid: node.outDegree === 0,
+			message: `Output node '${node.id}' cannot have outgoing connections.`
+		})
+	),
+
+	// Rule: 'condition' nodes must have exactly one input.
+	createNodeRule<MyAppNodeTypeMap>(
+		'Condition needs one input',
+		node => node.type === 'condition',
+		node => ({
+			valid: node.inDegree === 1,
+			message: `Condition node '${node.id}' must have exactly one input, but has ${node.inDegree}.`
+		})
+	),
+]
+
+/**
+ * The main validation function for our application.
+ */
+function validateMyWorkflow(graph: TypedWorkflowGraph<MyAppNodeTypeMap>): { isValid: boolean, errors: ValidationError[] } {
+	const analysis = analyzeGraph(graph)
+	// Apply every rule in the ruleset to the graph analysis
+	const errors = myRules.flatMap(rule => rule(analysis, graph))
+
+	return {
+		isValid: errors.length === 0,
+		errors,
+	}
+}
+```
+
+## Flexible API: Type-Safe vs. Untyped Validation
+
+The validation utilities offer a flexible, overloaded API to accommodate different needs. You can work with strongly-typed graphs for maximum safety or use basic types for simplicity.
+
+### 1. Type-Safe Validation (Recommended)
+
+This is the most powerful way to use the library. By defining a `NodeTypeMap` and using `TypedWorkflowGraph`, you get full autocompletion and compile-time checking of your node types and their `data` payloads within your validation rules.
+
+> [!TIP]
+> The `createNodeRule` function is generic and integrates with `TypedWorkflowGraph`. This enables **compile-time type checking and autocompletion** even on the `data` property of your nodes.
+
+**Example**: Let's ensure all our `api-call` nodes have a valid `retries` property.
+
+```typescript
+import { createNodeRule, isNodeType, TypedWorkflowGraph } from 'flowcraft'
+
+// 1. Define your application's specific node types
+interface MyAppNodeTypeMap {
+	'api-call': { url: string, retries: number }
+	'output': { destination: string }
+}
+
+// Your graph is strongly typed
+const myGraph: TypedWorkflowGraph<MyAppNodeTypeMap> = { /* ... */ }
+
+// 2. Use the `isNodeType` helper for a clean, readable filter
+const rule_apiRetries = createNodeRule<MyAppNodeTypeMap>(
+	'API calls must have retries',
+	// The helper creates the type guard for you!
+	isNodeType('api-call'),
+	(node) => {
+		// Because of the type guard, `node` is correctly narrowed.
+		// `node.data.retries` is fully typed and autocompletes in your IDE!
+		const valid = node.data.retries > 0
+		return { valid, message: `API call '${node.id}' must have at least 1 retry.` }
+	}
+)
+```
+
+### 2. Untyped Validation (Flexible)
+
+If you are working with a graph where the types are dynamic or you don't have a `NodeTypeMap` available, you can use the untyped version of the API. The functions will work with the base `WorkflowGraph` and `GraphNode` types.
+
+```typescript
+import { createNodeRule, WorkflowGraph } from 'flowcraft'
+
+// The graph is of the basic, untyped shape
+const myGraph: WorkflowGraph = { /* ... */ }
+
+const rule_noOrphans = createNodeRule(
+	'No orphaned nodes',
+	// The `node` parameter is of the base `GraphNode` type
+	_node => true, // Apply to all nodes
+	node => ({
+		valid: node.inDegree > 0 || node.outDegree > 0,
+		message: `Node '${node.id}' has no connections.`
+	})
+)
+```

package/docs/guide/tooling/mermaid.md

@@ -0,0 +1,156 @@
+# Visualizing Workflows with Mermaid.js
+
+Complex workflows with multiple branches, loops, and fan-outs can be difficult to reason about from code alone. To help with this, Flowcraft includes a `generateMermaidGraph` utility that can automatically create a visual diagram of any `Flow` instance.
+
+This utility is an invaluable tool for:
+
+- **Debugging**: Quickly verify that your nodes are wired together exactly as you intended.
+- **Documentation**: Embed diagrams directly into your project's `README.md` or technical documentation.
+- **Onboarding**: Help new team members understand the control flow of a complex business process at a glance.
+
+## Quick Start
+
+To use the utility, simply import `generateMermaidGraph`, create your `Flow` instance, and pass it to the function.
+
+Let's visualize the "Research Agent" from the sandbox examples, which contains a decision loop:
+
+```typescript
+import { DEFAULT_ACTION, Flow, generateMermaidGraph, Node } from 'flowcraft'
+
+// Define the nodes for the agent
+class DecideActionNode extends Node<void, void, 'search' | 'answer'> {
+	async post() { return 'search' /* or 'answer' */ }
+}
+class SearchWebNode extends Node {}
+class AnswerQuestionNode extends Node {}
+
+// Create instances
+const decideNode = new DecideActionNode()
+const searchNode = new SearchWebNode()
+const answerNode = new AnswerQuestionNode()
+
+// Wire the graph
+decideNode.next(searchNode, 'search')
+decideNode.next(answerNode, 'answer')
+searchNode.next(decideNode, DEFAULT_ACTION) // Loop back to the decision node
+
+const researchAgentFlow = new Flow(decideNode)
+
+// Generate and print the Mermaid syntax
+const mermaidGraph = generateMermaidGraph(researchAgentFlow)
+console.log(mermaidGraph)
+```
+
+### Generated Syntax
+
+Running the code above will print the following Mermaid.js syntax to the console:
+
+```mmd
+graph TD
+  DecideActionNode_0[DecideActionNode]
+  SearchWebNode_0[SearchWebNode]
+  AnswerQuestionNode_0[AnswerQuestionNode]
+  DecideActionNode_0 -- "search" --> SearchWebNode_0
+  DecideActionNode_0 -- "answer" --> AnswerQuestionNode_0
+  SearchWebNode_0 --> DecideActionNode_0
+```
+
+### Rendered Graph
+
+When this syntax is rendered, it produces the following diagram:
+
+```mermaid
+graph TD
+    DecideActionNode_0[DecideActionNode]
+    SearchWebNode_0[SearchWebNode]
+    AnswerQuestionNode_0[AnswerQuestionNode]
+    DecideActionNode_0 -- "search" --> SearchWebNode_0
+    DecideActionNode_0 -- "answer" --> AnswerQuestionNode_0
+    SearchWebNode_0 --> DecideActionNode_0
+```
+
+## How to Render the Graph
+
+You can render the generated syntax in several places:
+
+- **GitHub**: Directly in markdown files (`.md`), issues, and pull requests.
+- **VS Code**: Using a markdown previewer with a Mermaid extension installed.
+- **Online Editors**: Paste the syntax into the [Mermaid Live Editor](https://mermaid.live).
+
+## Supported Features
+
+The visualizer correctly represents all of Flowcraft's core branching and flow control patterns.
+
+### Conditional Branching
+
+Custom action strings are rendered as labels on the connecting arrows.
+
+**Code**:
+
+```typescript
+const decision = new DecisionNode()
+decision.next(new PathANode(), 'path_a')
+decision.next(new PathBNode(), 'path_b')
+```
+
+**Graph**:
+
+```mermaid
+graph TD
+    DecisionNode_0[DecisionNode]
+    DecisionNode_0 -- "path_a" --> PathANode_0[PathANode]
+    DecisionNode_0 -- "path_b" --> PathBNode_0[PathBNode]
+```
+
+### Filter Logic
+
+The special `FILTER_FAILED` action is given a descriptive label. The `DEFAULT_ACTION` has no label for clarity.
+
+**Code**:
+
+```typescript
+const filter = new FilterNode()
+filter.next(new SuccessNode(), DEFAULT_ACTION)
+filter.next(new FailureNode(), FILTER_FAILED)
+```
+
+**Graph**:
+
+```mermaid
+graph TD
+    FilterNode_0[FilterNode]
+    FilterNode_0 --> SuccessNode_0[SuccessNode]
+    FilterNode_0 -- "filter failed" --> FailureNode_0[FailureNode]
+```
+
+### Fan-In / Convergence
+
+When multiple nodes connect to the same successor, the graph shows all arrows converging.
+
+**Code**:
+
+```typescript
+const branchA = new PathANode()
+const branchB = new PathBNode()
+const end = new EndNode()
+branchA.next(end)
+branchB.next(end)
+```
+
+**Graph**:
+
+```mermaid
+graph TD
+    subgraph Fan-Out
+        StartNode --> PathANode
+        StartNode --> PathBNode
+    end
+    subgraph Fan-In
+        PathANode --> EndNode
+        PathBNode --> EndNode
+    end
+```
+
+### Node Naming
+
+If your flow uses multiple instances of the same `Node` class, the generator will append a unique index to each one (e.g., `ProcessNode_0`, `ProcessNode_1`) to distinguish them in the graph.