@graphty/algorithms 1.2.0 → 1.3.1

package/README.md

@@ -4,18 +4,57 @@
 [![Coverage Status](https://coveralls.io/repos/github/graphty-org/algorithms/badge.svg)](https://coveralls.io/github/graphty-org/algorithms)
 [![npm version](https://img.shields.io/npm/v/@graphty/algorithms.svg)](https://www.npmjs.com/package/@graphty/algorithms)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Examples](https://img.shields.io/badge/demo-github%20pages-blue)](https://graphty-org.github.io/algorithms/)
 
-A comprehensive TypeScript graph algorithms library with 100+ algorithms optimized for browser environments and visualization applications.
+A comprehensive TypeScript graph algorithms library with 98 algorithms optimized for browser environments and visualization applications.
 
 ## Features
 
 - **TypeScript-first**: Full type safety with comprehensive type definitions
 - **Browser-optimized**: Designed to run efficiently in web browsers
 - **Modular**: Import only the algorithms you need
-- **Comprehensive**: 100+ graph algorithms including traversal, shortest paths, centrality, clustering, flow, matching, link prediction, and more
+- **Comprehensive**: 98 graph algorithms including traversal, shortest paths, centrality, clustering, flow, matching, link prediction, and more
+- **Interactive Examples**: [Live demos](https://graphty-org.github.io/algorithms/) with visualizations for all algorithms
+- **Performance Analysis**: [Detailed benchmarks](https://graphty-org.github.io/algorithms/benchmarks/) comparing algorithm performance
 - **Well-tested**: Extensive test suite with high coverage
 - **Standards-compliant**: Follows conventional commits and semantic versioning
 
+## Performance Optimizations
+
+The library automatically optimizes performance for large graphs (≥10,000 nodes) using:
+
+- **Direction-Optimized BFS**: Dynamically switches between top-down and bottom-up search strategies, providing up to 42x speedup on large graphs
+- **CSR Graph Format**: Compressed Sparse Row format for cache-efficient memory access
+- **Bit-Packed Data Structures**: 8x memory reduction using bit arrays for boolean data
+
+These optimizations are applied automatically - no configuration needed! Just use the standard API:
+
+```typescript
+// Automatically uses optimized implementation for large graphs
+const result = breadthFirstSearch(largeGraph, startNode);
+```
+
+All BFS-based algorithms benefit from these optimizations:
+- `breadthFirstSearch`, `shortestPathBFS`, `singleSourceShortestPathBFS`
+- `betweennessCentrality`, `closenessCentrality`
+- Connected component algorithms
+
+### Performance Benchmarks
+
+| Graph Size | Standard BFS | Optimized BFS | Speedup |
+|------------|--------------|---------------|---------|
+| 10K nodes  | 4.40ms      | 6.34ms        | 0.69x   |
+| 50K nodes  | 158.64ms    | 44.27ms       | 3.58x   |
+| 100K nodes | 5,370ms     | 126ms         | 42.58x  |
+
+*Note: Optimizations activate automatically for graphs ≥10K nodes to avoid conversion overhead on smaller graphs.*
+
+### Learn More
+
+- 📖 [Performance Guide](docs/PERFORMANCE_GUIDE.md) - Detailed optimization explanations
+- 🔄 [Migration Guide](docs/MIGRATION_GUIDE.md) - Upgrading from older versions
+- 💾 [Memory vs Speed Tradeoffs](docs/PERFORMANCE_GUIDE.md#memory-vs-speed-tradeoffs) - Making the right choices
+
 ## Installation
 
 ```bash
@@ -25,31 +64,31 @@ npm install @graphty/algorithms
 ## Quick Start
 
 ```typescript
-import { Graph, breadthFirstSearch, dijkstra } from '@graphty/algorithms';
+import { Graph, breadthFirstSearch, dijkstra } from '@graphty/algorithms'
 
 // Create a new graph
-const graph = new Graph();
+const graph = new Graph()
 
 // Add nodes and edges
-graph.addNode('A');
-graph.addNode('B');
-graph.addNode('C');
-graph.addEdge('A', 'B', 1); // source, target, weight
-graph.addEdge('B', 'C', 2);
+graph.addNode('A')
+graph.addNode('B')
+graph.addNode('C')
+graph.addEdge('A', 'B', 1) // source, target, weight
+graph.addEdge('B', 'C', 2)
 
 // Basic graph operations
-console.log(graph.nodeCount); // 3
-console.log(graph.totalEdgeCount); // 2
-console.log(graph.hasEdge('A', 'B')); // true
+console.log(graph.nodeCount) // 3
+console.log(graph.totalEdgeCount) // 2
+console.log(graph.hasEdge('A', 'B')) // true
 
 // Run algorithms
-const traversal = breadthFirstSearch(graph, 'A');
-console.log(traversal.order); // ['A', 'B', 'C']
+const traversal = breadthFirstSearch(graph, 'A')
+console.log(traversal.order) // ['A', 'B', 'C']
 
-const shortestPaths = dijkstra(graph, 'A');
+const shortestPaths = dijkstra(graph, 'A')
 // Get distance to C
-const pathToC = shortestPaths.get('C');
-console.log(pathToC?.distance); // 3
+const pathToC = shortestPaths.get('C')
+console.log(pathToC?.distance) // 3
 ```
 
 ## API Reference
@@ -68,9 +107,9 @@ class Graph {
 
 ```typescript
 interface GraphConfig {
-  directed: boolean;         // Default: false
-  allowSelfLoops: boolean;   // Default: false
-  allowParallelEdges: boolean; // Default: false
+  directed: boolean // Default: false
+  allowSelfLoops: boolean // Default: false
+  allowParallelEdges: boolean // Default: false
 }
 ```
 
@@ -98,9 +137,9 @@ graph.nodes(): IterableIterator<Node>
 ```typescript
 // Add an edge with optional weight and data
 graph.addEdge(
-  source: NodeId, 
-  target: NodeId, 
-  weight?: number, 
+  source: NodeId,
+  target: NodeId,
+  weight?: number,
   data?: Record<string, unknown>
 ): void
 
@@ -167,6 +206,9 @@ graph.clone(): Graph
 
 // Clear all nodes and edges
 graph.clear(): void
+
+// Get a copy of the graph configuration
+graph.getConfig(): GraphConfig
 ```
 
 ### Traversal Algorithms
@@ -178,18 +220,24 @@ import { breadthFirstSearch, shortestPathBFS, singleSourceShortestPathBFS, isBip
 
 // Basic BFS traversal
 const result = breadthFirstSearch(graph, startNode, {
-  maxDepth?: number,     // Optional: limit traversal depth
-  visitCallback?: (node: NodeId, depth: number) => void
+  targetNode?: NodeId,     // Optional: stop when target is reached
+  visitCallback?: (node: NodeId, level: number) => void
 });
-// Returns: TraversalResult { visited: Set<NodeId>, order: NodeId[], tree?: Map<NodeId, NodeId> }
+// Returns: TraversalResult { visited: Set<NodeId>, order: NodeId[], tree?: Map<NodeId, NodeId | null> }
+
+// Note: For graphs with ≥10K nodes, BFS automatically uses:
+// - Direction-Optimized BFS (switches between top-down/bottom-up)
+// - CSR graph format for cache efficiency
+// - Bit-packed data structures for memory efficiency
 
 // Find shortest path between two nodes (unweighted)
 const path = shortestPathBFS(graph, source, target);
-// Returns: NodeId[] | null
+// Returns: ShortestPathResult | null
+// ShortestPathResult = { distance: number, path: NodeId[], predecessor: Map<NodeId, NodeId | null> }
 
 // Find all shortest paths from a source
 const paths = singleSourceShortestPathBFS(graph, source);
-// Returns: Map<NodeId, NodeId[]>
+// Returns: Map<NodeId, ShortestPathResult>
 
 // Check if graph is bipartite
 const bipartite = isBipartite(graph);
@@ -203,8 +251,10 @@ import { depthFirstSearch, topologicalSort, hasCycleDFS, findStronglyConnectedCo
 
 // Basic DFS traversal
 const result = depthFirstSearch(graph, startNode, {
-  previsitCallback?: (node: NodeId) => void,
-  postvisitCallback?: (node: NodeId) => void
+  targetNode?: NodeId,      // Optional: stop when target is reached
+  visitCallback?: (node: NodeId, level: number) => void,
+  recursive?: boolean,      // Use recursive implementation (default: false)
+  preOrder?: boolean        // Visit nodes in pre-order (default: true)
 });
 // Returns: TraversalResult
 
@@ -226,66 +276,79 @@ const sccs = findStronglyConnectedComponents(graph);
 #### Dijkstra's Algorithm
 
 ```typescript
-import { dijkstra, dijkstraPath, singleSourceShortestPath, allPairsShortestPath } from '@graphty/algorithms';
+import {
+  dijkstra,
+  dijkstraPath,
+  singleSourceShortestPath,
+  allPairsShortestPath
+} from '@graphty/algorithms'
 
 // Single-source shortest paths
 const result = dijkstra(graph, source, {
-  target?: NodeId        // Optional: stop when target is reached
-});
+  target?: NodeId // Optional: stop when target is reached
+})
 // Returns: Map<NodeId, ShortestPathResult>
 // ShortestPathResult = { distance: number, path: NodeId[], predecessor: Map<NodeId, NodeId | null> }
 
 // Get specific path
-const path = dijkstraPath(graph, source, target);
+const path = dijkstraPath(graph, source, target)
 // Returns: ShortestPathResult | null
 
 // All shortest paths from source
-const paths = singleSourceShortestPath(graph, source);
+const paths = singleSourceShortestPath(graph, source)
 // Returns: Map<NodeId, ShortestPathResult>
 
 // All pairs shortest paths
-const allPairs = allPairsShortestPath(graph);
+const allPairs = allPairsShortestPath(graph)
 // Returns: Map<NodeId, Map<NodeId, ShortestPathResult>>
 ```
 
 #### Bellman-Ford Algorithm
 
 ```typescript
-import { bellmanFord, bellmanFordPath, hasNegativeCycle } from '@graphty/algorithms';
+import {
+  bellmanFord,
+  bellmanFordPath,
+  hasNegativeCycle
+} from '@graphty/algorithms'
 
 // Single-source shortest paths (handles negative weights)
-const result = bellmanFord(graph, source);
-// Returns: BellmanFordResult { 
-//   distances: Map<NodeId, number>, 
+const result = bellmanFord(graph, source)
+// Returns: BellmanFordResult {
+//   distances: Map<NodeId, number>,
 //   predecessors: Map<NodeId, NodeId | null>,
 //   hasNegativeCycle: boolean,
 //   negativeCycleNodes?: Set<NodeId>
 // }
 
 // Get specific path
-const path = bellmanFordPath(graph, source, target);
+const path = bellmanFordPath(graph, source, target)
 // Returns: ShortestPathResult | null
 
 // Check for negative cycles
-const result = hasNegativeCycle(graph);
+const result = hasNegativeCycle(graph)
 // Returns: BellmanFordResult with hasNegativeCycle boolean
 ```
 
 #### Floyd-Warshall Algorithm
 
 ```typescript
-import { floydWarshall, floydWarshallPath, transitiveClosure } from '@graphty/algorithms';
+import {
+  floydWarshall,
+  floydWarshallPath,
+  transitiveClosure
+} from '@graphty/algorithms'
 
 // All pairs shortest paths
-const result = floydWarshall(graph);
+const result = floydWarshall(graph)
 // Returns: { distances: Map<NodeId, Map<NodeId, number>>, next: Map<NodeId, Map<NodeId, NodeId | null>> }
 
 // Get specific path between any pair
-const path = floydWarshallPath(result, source, target);
+const path = floydWarshallPath(result, source, target)
 // Returns: NodeId[] | null
 
 // Compute transitive closure
-const closure = transitiveClosure(graph);
+const closure = transitiveClosure(graph)
 // Returns: Map<NodeId, Set<NodeId>>
 ```
 
@@ -294,141 +357,169 @@ const closure = transitiveClosure(graph);
 #### Degree Centrality
 
 ```typescript
-import { degreeCentrality, nodeDegreeCentrality } from '@graphty/algorithms';
+import { degreeCentrality, nodeDegreeCentrality } from '@graphty/algorithms'
 
 // Calculate for all nodes
 const centralities = degreeCentrality(graph, {
-  normalized?: boolean,   // Default: false
-  weight?: string        // Optional: edge property for weighted degree
-});
+  normalized: boolean, // Default: false
+  weight: string // Optional: edge property for weighted degree
+})
 // Returns: CentralityResult (Record<string, number>)
 
 // Calculate for single node
-const centrality = nodeDegreeCentrality(graph, nodeId, { normalized?: boolean });
+const centrality = nodeDegreeCentrality(graph, nodeId, { normalized: boolean })
 // Returns: number
 ```
 
 #### Betweenness Centrality
 
 ```typescript
-import { betweennessCentrality, nodeBetweennessCentrality, edgeBetweennessCentrality } from '@graphty/algorithms';
+import {
+  betweennessCentrality,
+  nodeBetweennessCentrality,
+  edgeBetweennessCentrality
+} from '@graphty/algorithms'
 
 // Node betweenness for all nodes
 const centralities = betweennessCentrality(graph, {
-  normalized?: boolean,   // Default: false
-  weight?: string,       // Optional: use weighted shortest paths
-  endpoints?: boolean    // Default: false, include endpoints in paths
-});
+  normalized: boolean, // Default: false
+  weight: string, // Optional: use weighted shortest paths
+  endpoints: boolean // Default: false, include endpoints in paths
+})
 // Returns: CentralityResult (Record<string, number>)
 
 // Single node betweenness
-const centrality = nodeBetweennessCentrality(graph, nodeId, options);
+const centrality = nodeBetweennessCentrality(graph, nodeId, options)
 // Returns: number
 
 // Edge betweenness
-const edgeCentralities = edgeBetweennessCentrality(graph, options);
+const edgeCentralities = edgeBetweennessCentrality(graph, options)
 // Returns: Map<string, number> (edge ID to centrality)
 ```
 
 #### Closeness Centrality
 
 ```typescript
-import { closenessCentrality, nodeClosenessCentrality, weightedClosenessCentrality } from '@graphty/algorithms';
+import {
+  closenessCentrality,
+  nodeClosenessCentrality,
+  weightedClosenessCentrality
+} from '@graphty/algorithms'
 
 // Closeness for all nodes
 const centralities = closenessCentrality(graph, {
-  normalized?: boolean    // Default: false
-});
+  normalized: boolean // Default: false
+})
 // Returns: CentralityResult (Record<string, number>)
 
 // Single node closeness
-const centrality = nodeClosenessCentrality(graph, nodeId, { normalized?: boolean });
+const centrality = nodeClosenessCentrality(graph, nodeId, {
+  normalized: boolean
+})
 // Returns: number
 
 // Weighted closeness
 const centralities = weightedClosenessCentrality(graph, {
-  normalized?: boolean,
-  weight?: string        // Edge property for weights
-});
+  normalized: boolean,
+  weight: string // Edge property for weights
+})
 // Returns: CentralityResult (Record<string, number>)
+
+// Single node weighted closeness
+const centrality = nodeWeightedClosenessCentrality(graph, nodeId, {
+  normalized: boolean,
+  weight: string // Edge property for weights
+})
+// Returns: number
 ```
 
 #### PageRank
 
 ```typescript
-import { pageRank, personalizedPageRank, topPageRankNodes } from '@graphty/algorithms';
+import {
+  pageRank,
+  personalizedPageRank,
+  topPageRankNodes
+} from '@graphty/algorithms'
 
 // Standard PageRank
 const result = pageRank(graph, {
-  dampingFactor?: number,    // Default: 0.85
-  maxIterations?: number,    // Default: 100
-  tolerance?: number,        // Default: 1e-6
-  initialRanks?: Record<string, number>,
-  personalization?: Record<string, number>
-});
+  dampingFactor: number, // Default: 0.85
+  maxIterations: number, // Default: 100
+  tolerance: number, // Default: 1e-6
+  initialRanks: Record<string, number>,
+  personalization: Record<string, number>
+})
 // Returns: { ranks: Record<string, number>, iterations: number, converged: boolean }
 
 // Personalized PageRank (with bias)
-const ranks = personalizedPageRank(graph, personalization, options);
+const ranks = personalizedPageRank(graph, personalization, options)
 // personalization: Map<NodeId, number> - restart probabilities
 // Returns: CentralityResult (Record<string, number>)
 
 // Get top N nodes by PageRank
-const topNodes = topPageRankNodes(graph, n, options);
+const topNodes = topPageRankNodes(graph, n, options)
 // Returns: Array<{ node: NodeId, rank: number }>
+
+// Alternative PageRank that returns CentralityResult format
+const centralities = pageRankCentrality(graph, options)
+// Returns: CentralityResult (Record<string, number>)
 ```
 
 #### Eigenvector Centrality
 
 ```typescript
-import { eigenvectorCentrality, nodeEigenvectorCentrality } from '@graphty/algorithms';
+import {
+  eigenvectorCentrality,
+  nodeEigenvectorCentrality
+} from '@graphty/algorithms'
 
 // Calculate eigenvector centrality for all nodes
 const centralities = eigenvectorCentrality(graph, {
-  maxIterations?: number,    // Default: 100
-  tolerance?: number         // Default: 1e-6
-});
+  maxIterations: number, // Default: 100
+  tolerance: number // Default: 1e-6
+})
 // Returns: CentralityResult (Record<string, number>)
 
 // Single node eigenvector centrality
-const centrality = nodeEigenvectorCentrality(graph, nodeId, options);
+const centrality = nodeEigenvectorCentrality(graph, nodeId, options)
 // Returns: number
 ```
 
 #### Katz Centrality
 
 ```typescript
-import { katzCentrality, nodeKatzCentrality } from '@graphty/algorithms';
+import { katzCentrality, nodeKatzCentrality } from '@graphty/algorithms'
 
 // Calculate Katz centrality for all nodes
 const centralities = katzCentrality(graph, {
-  alpha?: number,           // Attenuation factor (default: 0.1)
-  beta?: number,            // Weight for direct connections (default: 1.0)
-  maxIterations?: number,   // Default: 100
-  tolerance?: number,       // Default: 1e-6
-  normalized?: boolean      // Default: true
-});
+  alpha: number, // Attenuation factor (default: 0.1)
+  beta: number, // Weight for direct connections (default: 1.0)
+  maxIterations: number, // Default: 100
+  tolerance: number, // Default: 1e-6
+  normalized: boolean // Default: true
+})
 // Returns: CentralityResult (Record<string, number>)
 
 // Single node Katz centrality
-const centrality = nodeKatzCentrality(graph, nodeId, options);
+const centrality = nodeKatzCentrality(graph, nodeId, options)
 // Returns: number
 ```
 
 #### HITS Algorithm
 
 ```typescript
-import { hits, nodeHITS } from '@graphty/algorithms';
+import { hits, nodeHITS } from '@graphty/algorithms'
 
 // Calculate hub and authority scores
 const result = hits(graph, {
-  maxIterations?: number,   // Default: 100
-  tolerance?: number        // Default: 1e-6
-});
+  maxIterations: number, // Default: 100
+  tolerance: number // Default: 1e-6
+})
 // Returns: HITSResult { hubs: CentralityResult, authorities: CentralityResult }
 
 // Single node HITS scores
-const scores = nodeHITS(graph, nodeId, options);
+const scores = nodeHITS(graph, nodeId, options)
 // Returns: { hub: number, authority: number }
 ```
 
@@ -437,77 +528,80 @@ const scores = nodeHITS(graph, nodeId, options);
 #### Basic Component Operations
 
 ```typescript
-import { 
-  connectedComponents, 
-  isConnected, 
+import {
+  connectedComponents,
+  isConnected,
   numberOfConnectedComponents,
   largestConnectedComponent,
-  getConnectedComponent 
-} from '@graphty/algorithms';
+  getConnectedComponent
+} from '@graphty/algorithms'
 
 // Find all components
-const components = connectedComponents(graph);
+const components = connectedComponents(graph)
 // Returns: NodeId[][] (array of component arrays)
 
 // Check if graph is connected
-const connected = isConnected(graph);
+const connected = isConnected(graph)
 // Returns: boolean
 
 // Count components
-const count = numberOfConnectedComponents(graph);
+const count = numberOfConnectedComponents(graph)
 // Returns: number
 
 // Get largest component
-const largest = largestConnectedComponent(graph);
+const largest = largestConnectedComponent(graph)
 // Returns: NodeId[]
 
 // Get component containing a specific node
-const component = getConnectedComponent(graph, nodeId);
+const component = getConnectedComponent(graph, nodeId)
 // Returns: Set<NodeId>
 ```
 
 #### Strongly Connected Components
 
 ```typescript
-import { 
+import {
   stronglyConnectedComponents,
   findStronglyConnectedComponents,
   isStronglyConnected,
-  condensationGraph 
-} from '@graphty/algorithms';
+  condensationGraph
+} from '@graphty/algorithms'
 
 // Find SCCs using Tarjan's algorithm
-const sccs = stronglyConnectedComponents(graph);
+const sccs = stronglyConnectedComponents(graph)
 // Returns: ComponentResult
 
 // Alternative: using DFS
-const sccs = findStronglyConnectedComponents(graph);
+const sccs = findStronglyConnectedComponents(graph)
 // Returns: NodeId[][]
 
 // Check if directed graph is strongly connected
-const stronglyConnected = isStronglyConnected(graph);
+const stronglyConnected = isStronglyConnected(graph)
 // Returns: boolean
 
 // Create condensation graph (DAG of SCCs)
-const condensation = condensationGraph(graph);
+const condensation = condensationGraph(graph)
 // Returns: { graph: Graph, componentMap: Map<NodeId, number> }
 
 // Alternative DFS-based connected components
-const components = connectedComponentsDFS(graph);
+const components = connectedComponentsDFS(graph)
 // Returns: ComponentResult
 ```
 
 #### Weakly Connected Components
 
 ```typescript
-import { weaklyConnectedComponents, isWeaklyConnected } from '@graphty/algorithms';
+import {
+  weaklyConnectedComponents,
+  isWeaklyConnected
+} from '@graphty/algorithms'
 
 // Find WCCs (ignoring edge direction)
-const wccs = weaklyConnectedComponents(graph);
+const wccs = weaklyConnectedComponents(graph)
 // Returns: ComponentResult
 
 // Check if directed graph is weakly connected
-const weaklyConnected = isWeaklyConnected(graph);
+const weaklyConnected = isWeaklyConnected(graph)
 // Returns: boolean
 ```
 
@@ -518,16 +612,16 @@ const weaklyConnected = isWeaklyConnected(graph);
 Min-heap implementation used internally by algorithms.
 
 ```typescript
-import { PriorityQueue } from '@graphty/algorithms';
+import { PriorityQueue } from '@graphty/algorithms'
 
-const pq = new PriorityQueue<T>((a, b) => a.priority - b.priority);
+const pq = new PriorityQueue<T>((a, b) => a.priority - b.priority)
 
-pq.enqueue(item);
-pq.dequeue();
-pq.peek();
-pq.isEmpty();
-pq.size;
-pq.clear();
+pq.enqueue(item)
+pq.dequeue()
+pq.peek()
+pq.isEmpty()
+pq.size
+pq.clear()
 ```
 
 #### Union-Find (Disjoint Set)
@@ -535,16 +629,16 @@ pq.clear();
 Efficient data structure for tracking connected components.
 
 ```typescript
-import { UnionFind } from '@graphty/algorithms';
+import { UnionFind } from '@graphty/algorithms'
 
-const uf = new UnionFind<T>();
+const uf = new UnionFind<T>()
 
-uf.makeSet(item);
-uf.find(item);
-uf.union(item1, item2);
-uf.connected(item1, item2);
-uf.getSetSize(item);
-uf.numberOfSets;
+uf.makeSet(item)
+uf.find(item)
+uf.union(item1, item2)
+uf.connected(item1, item2)
+uf.getSetSize(item)
+uf.numberOfSets
 ```
 
 ### Minimum Spanning Tree Algorithms
@@ -552,14 +646,14 @@ uf.numberOfSets;
 #### Kruskal's Algorithm
 
 ```typescript
-import { kruskalMST, minimumSpanningTree } from '@graphty/algorithms';
+import { kruskalMST, minimumSpanningTree } from '@graphty/algorithms'
 
 // Find MST using Kruskal's algorithm
-const mst = kruskalMST(graph);
+const mst = kruskalMST(graph)
 // Returns: { edges: Edge[], weight: number }
 
 // Alternative alias
-const mst = minimumSpanningTree(graph);
+const mst = minimumSpanningTree(graph)
 ```
 
 #### Prim's Algorithm
@@ -577,77 +671,79 @@ const mst = primMST(graph, startNode?);
 #### Louvain Method
 
 ```typescript
-import { louvain } from '@graphty/algorithms';
+import { louvain } from '@graphty/algorithms'
 
 // Detect communities using Louvain method
 const communities = louvain(graph, {
-  resolution?: number,      // Default: 1.0
-  randomSeed?: number
-});
+  resolution: number, // Default: 1.0
+  randomSeed: number
+})
 // Returns: { communities: Map<NodeId, number>, modularity: number }
 ```
 
 #### Leiden Algorithm
 
 ```typescript
-import { leiden } from '@graphty/algorithms';
+import { leiden } from '@graphty/algorithms'
 
 // Improved community detection
 const communities = leiden(graph, {
-  resolution?: number,      // Default: 1.0
-  iterations?: number,      // Default: 10
-  randomSeed?: number
-});
+  resolution: number, // Default: 1.0
+  iterations: number, // Default: 10
+  randomSeed: number
+})
 // Returns: { communities: Map<NodeId, number>, modularity: number }
 ```
 
 #### Label Propagation
 
 ```typescript
-import { labelPropagation, labelPropagationAsync, labelPropagationSemiSupervised } from '@graphty/algorithms';
+import {
+  labelPropagation,
+  labelPropagationAsync,
+  labelPropagationSemiSupervised
+} from '@graphty/algorithms'
 
 // Basic label propagation
 const labels = labelPropagation(graph, {
-  maxIterations?: number    // Default: 100
-});
+  maxIterations: number // Default: 100
+})
 // Returns: Map<NodeId, number>
 
 // Asynchronous version
-const labels = labelPropagationAsync(graph, options);
+const labels = labelPropagationAsync(graph, options)
 
 // Semi-supervised with seed communities
-const labels = labelPropagationSemiSupervised(graph, seedLabels, options);
+const labels = labelPropagationSemiSupervised(graph, seedLabels, options)
 ```
 
 #### Girvan-Newman Algorithm
 
 ```typescript
-import { girvanNewman } from '@graphty/algorithms';
+import { girvanNewman } from '@graphty/algorithms'
 
 // Edge betweenness based community detection
 const dendrogram = girvanNewman(graph, {
-  targetCommunities?: number  // Stop at this many communities
-});
+  targetCommunities: number // Stop at this many communities
+})
 // Returns: { levels: Array<{ modularity: number, communities: NodeId[][] }> }
 ```
 
 ### Pathfinding Algorithms
 
-#### A* Algorithm
+#### A\* Algorithm
 
 ```typescript
-import { astar, astarWithDetails, heuristics } from '@graphty/algorithms';
+import { astar } from '@graphty/algorithms'
 
 // A* pathfinding with heuristic
-const path = astar(graph, start, goal, {
-  heuristic: heuristics.euclidean,  // or manhattan, chebyshev, zero
-  weight?: (edge: Edge) => number
-});
-// Returns: { path: NodeId[], cost: number } | null
-
-// A* with search details
-const result = astarWithDetails(graph, start, goal, options);
-// Returns: { path: NodeId[], cost: number, explored: Set<NodeId>, parent: Map<NodeId, NodeId> } | null
+const path = astar(
+  graph, // Map<T, Map<T, number>> adjacency list
+  start,
+  goal,
+  heuristic // (node: T, goal: T) => number
+)
+// Returns: { path: T[], cost: number } | null
 ```
 
 ### Flow Algorithms
@@ -694,74 +790,87 @@ const cut = kargerMinCut(graph, iterations?);
 #### Hierarchical Clustering
 
 ```typescript
-import { hierarchicalClustering, cutDendrogram, cutDendrogramKClusters } from '@graphty/algorithms';
+import {
+  hierarchicalClustering,
+  cutDendrogram,
+  cutDendrogramKClusters
+} from '@graphty/algorithms'
 
 // Agglomerative clustering
-const result = hierarchicalClustering(graph, linkage);
+const result = hierarchicalClustering(graph, linkage)
 // graph: Map<NodeId, Set<NodeId>>
 // linkage: 'single' | 'complete' | 'average' | 'ward' (default: 'single')
 // Returns: HierarchicalClusteringResult { root: ClusterNode, dendrogram: ClusterNode[], clusters: Map<number, Set<NodeId>[]> }
 
 // Cut at specific height
-const clusters = cutDendrogram(result.root, height);
+const clusters = cutDendrogram(result.root, height)
 // Returns: Set<NodeId>[]
 
 // Get exactly k clusters
-const clusters = cutDendrogramKClusters(result.root, k);
+const clusters = cutDendrogramKClusters(result.root, k)
 // Returns: Set<NodeId>[]
 ```
 
 #### K-Core Decomposition
 
 ```typescript
-import { kCoreDecomposition, getKCore, kTruss, degeneracyOrdering } from '@graphty/algorithms';
+import {
+  kCoreDecomposition,
+  getKCore,
+  kTruss,
+  degeneracyOrdering
+} from '@graphty/algorithms'
 
 // Find all k-cores
-const result = kCoreDecomposition(graph);
+const result = kCoreDecomposition(graph)
 // graph: Map<NodeId, Set<NodeId>>
 // Returns: KCoreResult { cores: Map<number, Set<NodeId>>, coreness: Map<NodeId, number>, maxCore: number }
 
 // Extract specific k-core subgraph
-const kCore = getKCore(graph, k);
+const kCore = getKCore(graph, k)
 // Returns: Set<NodeId>
 
 // Find k-truss (triangular cores)
-const truss = kTruss(graph, k);
+const truss = kTruss(graph, k)
 // Returns: Set<string> (edge strings)
 
 // Degeneracy ordering
-const ordering = degeneracyOrdering(graph);
+const ordering = degeneracyOrdering(graph)
 // Returns: NodeId[]
 ```
 
 #### Spectral Clustering
 
 ```typescript
-import { spectralClustering } from '@graphty/algorithms';
+import { spectralClustering } from '@graphty/algorithms'
 
 // Spectral clustering using graph Laplacian
 const result = spectralClustering(graph, {
-  k: number,                // Number of clusters
-  laplacianType?: 'unnormalized' | 'normalized' | 'randomWalk',  // Default: 'normalized'
-  maxIterations?: number,   // Default: 100
-  tolerance?: number        // Default: 1e-4
-});
+  k: number, // Number of clusters
+  laplacianType: 'unnormalized' | 'normalized' | 'randomWalk', // Default: 'normalized'
+  maxIterations: number, // Default: 100
+  tolerance: number // Default: 1e-4
+})
 // Returns: SpectralClusteringResult { communities: NodeId[][], clusterAssignments: Map<NodeId, number> }
 ```
 
 #### Markov Clustering (MCL)
 
 ```typescript
-import { markovClustering } from '@graphty/algorithms';
+import { markovClustering, calculateMCLModularity } from '@graphty/algorithms'
 
 // MCL algorithm for network clustering
 const result = markovClustering(graph, {
-  expansion?: number,       // Expansion parameter (default: 2)
-  inflation?: number,       // Inflation parameter (default: 2)
-  maxIterations?: number,   // Default: 100
-  tolerance?: number        // Default: 1e-6
-});
+  expansion: number, // Expansion parameter (default: 2)
+  inflation: number, // Inflation parameter (default: 2)
+  maxIterations: number, // Default: 100
+  tolerance: number // Default: 1e-6
+})
 // Returns: MCLResult { communities: NodeId[][], attractors: Set<NodeId>, iterations: number, converged: boolean }
+
+// Calculate modularity of MCL clustering result
+const modularity = calculateMCLModularity(graph, result.communities)
+// Returns: number
 ```
 
 ### Matching Algorithms
@@ -769,38 +878,47 @@ const result = markovClustering(graph, {
 #### Bipartite Matching
 
 ```typescript
-import { maximumBipartiteMatching, greedyBipartiteMatching, bipartitePartition } from '@graphty/algorithms';
+import {
+  maximumBipartiteMatching,
+  greedyBipartiteMatching,
+  bipartitePartition
+} from '@graphty/algorithms'
 
 // Maximum bipartite matching (Hungarian algorithm)
 const matching = maximumBipartiteMatching(graph, {
-  leftNodes?: Set<NodeId>,   // Optional: specify left partition
-  rightNodes?: Set<NodeId>,  // Optional: specify right partition
-});
+  leftNodes: Set<NodeId>, // Optional: specify left partition
+  rightNodes: Set<NodeId> // Optional: specify right partition
+})
 // Returns: BipartiteMatchingResult { matching: Map<NodeId, NodeId>, size: number }
 
 // Greedy bipartite matching (faster, approximate)
-const matching = greedyBipartiteMatching(graph, options);
+const matching = greedyBipartiteMatching(graph, options)
 
 // Partition graph into bipartite sets
-const partition = bipartitePartition(graph);
+const partition = bipartitePartition(graph)
 // Returns: { left: Set<NodeId>, right: Set<NodeId> } | null
 ```
 
 #### Graph Isomorphism
 
 ```typescript
-import { isGraphIsomorphic, findAllIsomorphisms } from '@graphty/algorithms';
+import { isGraphIsomorphic, findAllIsomorphisms } from '@graphty/algorithms'
 
 // Check if two graphs are isomorphic
 const result = isGraphIsomorphic(graph1, graph2, {
-  nodeMatch?: (node1: NodeId, node2: NodeId, g1: Graph, g2: Graph) => boolean,
-  edgeMatch?: (edge1: [NodeId, NodeId], edge2: [NodeId, NodeId], g1: Graph, g2: Graph) => boolean,
-  findAllMappings?: boolean     // Find all possible isomorphisms
-});
+  nodeMatch: (node1: NodeId, node2: NodeId, g1: Graph, g2: Graph) => boolean,
+  edgeMatch: (
+    edge1: [NodeId, NodeId],
+    edge2: [NodeId, NodeId],
+    g1: Graph,
+    g2: Graph
+  ) => boolean,
+  findAllMappings: boolean // Find all possible isomorphisms
+})
 // Returns: IsomorphismResult { isIsomorphic: boolean, mapping?: Map<NodeId, NodeId> }
 
 // Find all isomorphism mappings
-const mappings = findAllIsomorphisms(graph1, graph2, options);
+const mappings = findAllIsomorphisms(graph1, graph2, options)
 // Returns: Array<Map<NodeId, NodeId>>
 ```
 
@@ -809,64 +927,74 @@ const mappings = findAllIsomorphisms(graph1, graph2, options);
 #### Common Neighbors
 
 ```typescript
-import { commonNeighborsScore, commonNeighborsPrediction, commonNeighborsForPairs } from '@graphty/algorithms';
+import {
+  commonNeighborsScore,
+  commonNeighborsPrediction,
+  commonNeighborsForPairs
+} from '@graphty/algorithms'
 
 // Score for a specific pair
-const score = commonNeighborsScore(graph, node1, node2);
+const score = commonNeighborsScore(graph, node1, node2)
 // Returns: number
 
 // Predict links for all non-connected pairs
 const predictions = commonNeighborsPrediction(graph, {
-  directed?: boolean,        // Consider direction
-  includeExisting?: boolean, // Include existing edges
-  topK?: number             // Return only top K predictions
-});
+  directed: boolean, // Consider direction
+  includeExisting: boolean, // Include existing edges
+  topK: number // Return only top K predictions
+})
 // Returns: LinkPredictionScore[]
 
 // Score multiple specific pairs
-const scores = commonNeighborsForPairs(graph, pairs, options);
+const scores = commonNeighborsForPairs(graph, pairs, options)
 // Returns: LinkPredictionScore[]
 
 // Evaluate prediction performance
-const evaluation = evaluateCommonNeighbors(graph, testEdges);
+const evaluation = evaluateCommonNeighbors(graph, testEdges)
 // Returns: { precision, recall, f1Score }
 
 // Get top candidates for a node
-const candidates = getTopCandidatesForNode(graph, nodeId, { topK?: number });
+const candidates = getTopCandidatesForNode(graph, nodeId, { topK: number })
 // Returns: LinkPredictionScore[]
 ```
 
 #### Adamic-Adar Index
 
 ```typescript
-import { adamicAdarScore, adamicAdarPrediction, adamicAdarForPairs } from '@graphty/algorithms';
+import {
+  adamicAdarScore,
+  adamicAdarPrediction,
+  adamicAdarForPairs
+} from '@graphty/algorithms'
 
 // Adamic-Adar score for a pair (weighted by neighbor degrees)
-const score = adamicAdarScore(graph, node1, node2);
+const score = adamicAdarScore(graph, node1, node2)
 // Returns: number
 
 // Predict links using Adamic-Adar
 const predictions = adamicAdarPrediction(graph, {
-  directed?: boolean,
-  includeExisting?: boolean,
-  topK?: number
-});
+  directed: boolean,
+  includeExisting: boolean,
+  topK: number
+})
 // Returns: LinkPredictionScore[]
 
 // Score multiple pairs
-const scores = adamicAdarForPairs(graph, pairs, options);
+const scores = adamicAdarForPairs(graph, pairs, options)
 // Returns: LinkPredictionScore[]
 
 // Compare Adamic-Adar with Common Neighbors
-const comparison = compareAdamicAdarWithCommonNeighbors(graph, pairs);
+const comparison = compareAdamicAdarWithCommonNeighbors(graph, pairs)
 // Returns: Array<{ source, target, adamicAdar, commonNeighbors }>
 
 // Evaluate prediction performance
-const evaluation = evaluateAdamicAdar(graph, testEdges);
+const evaluation = evaluateAdamicAdar(graph, testEdges)
 // Returns: { precision, recall, f1Score }
 
 // Get top candidates for a node
-const candidates = getTopAdamicAdarCandidatesForNode(graph, nodeId, { topK?: number });
+const candidates = getTopAdamicAdarCandidatesForNode(graph, nodeId, {
+  topK: number
+})
 // Returns: LinkPredictionScore[]
 ```
 
@@ -877,18 +1005,18 @@ Cutting-edge graph algorithms based on recent research.
 #### SynC - Synergistic Deep Graph Clustering
 
 ```typescript
-import { syncClustering } from '@graphty/algorithms';
+import { syncClustering } from '@graphty/algorithms'
 
 // Deep learning based clustering
 const result = syncClustering(graph, {
-  k: number,                  // Number of clusters
-  maxIterations?: number,     // Default: 100
-  learningRate?: number,      // Default: 0.01
-  hiddenDim?: number,         // Default: 64
-  randomSeed?: number
-});
-// Returns: SynCResult { 
-//   communities: NodeId[][], 
+  k: number, // Number of clusters
+  maxIterations: number, // Default: 100
+  learningRate: number, // Default: 0.01
+  hiddenDim: number, // Default: 64
+  randomSeed: number
+})
+// Returns: SynCResult {
+//   communities: NodeId[][],
 //   clusterAssignments: Map<NodeId, number>,
 //   embeddings: Map<NodeId, number[]>,
 //   iterations: number,
@@ -899,16 +1027,16 @@ const result = syncClustering(graph, {
 #### TeraHAC - Scalable Hierarchical Agglomerative Clustering
 
 ```typescript
-import { teraHAC } from '@graphty/algorithms';
+import { teraHAC } from '@graphty/algorithms'
 
 // Scalable hierarchical clustering
 const result = teraHAC(graph, {
-  linkage?: 'single' | 'complete' | 'average',  // Default: 'average'
-  k?: number,                   // Target number of clusters
-  threshold?: number,           // Distance threshold for merging
-  sampleSize?: number,          // Default: 1000
-  randomSeed?: number
-});
+  linkage: 'single' | 'complete' | 'average', // Default: 'average'
+  k: number, // Target number of clusters
+  threshold: number, // Distance threshold for merging
+  sampleSize: number, // Default: 1000
+  randomSeed: number
+})
 // Returns: TeraHACResult {
 //   root: TeraHACClusterNode,
 //   dendrogram: TeraHACClusterNode[],
@@ -920,15 +1048,15 @@ const result = teraHAC(graph, {
 #### GRSBM - Greedy Recursive Spectral Bisection with Modularity
 
 ```typescript
-import { grsbm } from '@graphty/algorithms';
+import { grsbm } from '@graphty/algorithms'
 
 // Explainable community detection
 const result = grsbm(graph, {
-  minClusterSize?: number,      // Default: 5
-  maxDepth?: number,            // Default: 10
-  modularityThreshold?: number, // Default: 0.1
-  explainClusters?: boolean     // Default: true
-});
+  minClusterSize: number, // Default: 5
+  maxDepth: number, // Default: 10
+  modularityThreshold: number, // Default: 0.1
+  explainClusters: boolean // Default: true
+})
 // Returns: GRSBMResult {
 //   clusters: GRSBMCluster[],   // Each cluster has id, nodes, modularity, explanation
 //   hierarchy: Map<number, number[]>,
@@ -941,7 +1069,7 @@ const result = grsbm(graph, {
 ### Available Algorithms by Category:
 
 - **Traversal**: BFS, DFS, Topological Sort, Cycle Detection, Bipartite Check
-- **Shortest Path**: Dijkstra, Bellman-Ford, Floyd-Warshall, A*
+- **Shortest Path**: Dijkstra, Bellman-Ford, Floyd-Warshall, A\*
 - **Centrality**: Degree, Betweenness, Closeness, PageRank, Eigenvector, Katz, HITS
 - **Components**: Connected, Strongly Connected, Weakly Connected, Condensation Graph
 - **Community Detection**: Louvain, Leiden, Label Propagation, Girvan-Newman
@@ -952,11 +1080,18 @@ const result = grsbm(graph, {
 - **Link Prediction**: Common Neighbors, Adamic-Adar
 - **Research Algorithms**: SynC, TeraHAC, GRSBM
 
-## Examples
+## Interactive Examples
+
+Try out all algorithms with interactive visualizations: **[Live Demo →](https://graphty-org.github.io/algorithms/)**
+
+The library includes comprehensive examples demonstrating each algorithm. You can:
 
-The library includes comprehensive examples demonstrating each algorithm. Find them in the [examples directory](https://github.com/graphty-org/algorithms/tree/main/examples):
+- **[Browse Interactive HTML Examples](https://graphty-org.github.io/algorithms/examples/)** - Visual demonstrations with step-by-step execution
+- **[View Performance Benchmarks](https://graphty-org.github.io/algorithms/benchmarks/)** - Comparative analysis of algorithm performance
+- **[Explore Code Examples](https://github.com/graphty-org/algorithms/tree/main/examples)** - Implementation examples for each algorithm
 
 ### Basic Algorithms
+
 - [BFS Traversal](https://github.com/graphty-org/algorithms/blob/main/examples/bfs-example.js) - Breadth-first search and shortest paths
 - [DFS Traversal](https://github.com/graphty-org/algorithms/blob/main/examples/dfs-example.js) - Depth-first search and applications
 - [Dijkstra's Algorithm](https://github.com/graphty-org/algorithms/blob/main/examples/dijkstra-example.js) - Weighted shortest paths
@@ -964,6 +1099,7 @@ The library includes comprehensive examples demonstrating each algorithm. Find t
 - [Floyd-Warshall](https://github.com/graphty-org/algorithms/blob/main/examples/floyd-warshall-example.js) - All pairs shortest paths
 
 ### Centrality Measures
+
 - [Degree Centrality](https://github.com/graphty-org/algorithms/blob/main/examples/degree-centrality-example.js) - Node importance by connections
 - [Betweenness Centrality](https://github.com/graphty-org/algorithms/blob/main/examples/betweenness-centrality-example.js) - Bridge nodes
 - [Closeness Centrality](https://github.com/graphty-org/algorithms/blob/main/examples/closeness-centrality-example.js) - Central nodes
@@ -973,37 +1109,44 @@ The library includes comprehensive examples demonstrating each algorithm. Find t
 - [HITS Algorithm](https://github.com/graphty-org/algorithms/blob/main/examples/hits-algorithm-example.js) - Hub and authority scores
 
 ### Graph Structure
+
 - [Connected Components](https://github.com/graphty-org/algorithms/blob/main/examples/connected-components-example.js) - Find graph components
 - [Kruskal's MST](https://github.com/graphty-org/algorithms/blob/main/examples/kruskal-example.js) - Minimum spanning tree
 - [Prim's MST](https://github.com/graphty-org/algorithms/blob/main/examples/prim-example.js) - Alternative MST algorithm
 
 ### Community Detection
+
 - [Louvain Method](https://github.com/graphty-org/algorithms/blob/main/examples/louvain-example.js) - Modularity-based communities
 - [Leiden Algorithm](https://github.com/graphty-org/algorithms/blob/main/examples/leiden-community.ts) - Improved Louvain
 - [Label Propagation](https://github.com/graphty-org/algorithms/blob/main/examples/label-propagation.ts) - Fast community detection
 - [Girvan-Newman](https://github.com/graphty-org/algorithms/blob/main/examples/girvan-newman-example.js) - Hierarchical communities
 
 ### Clustering
+
 - [Hierarchical Clustering](https://github.com/graphty-org/algorithms/blob/main/examples/hierarchical-clustering.ts) - Graph clustering
 - [K-Core Decomposition](https://github.com/graphty-org/algorithms/blob/main/examples/k-core-decomposition.ts) - Core analysis
 - [Spectral Clustering](https://github.com/graphty-org/algorithms/blob/main/examples/spectral-clustering-example.js) - Eigenvalue-based clustering
 - [MCL Clustering](https://github.com/graphty-org/algorithms/blob/main/examples/mcl-clustering-example.js) - Markov clustering
 
 ### Matching
+
 - [Bipartite Matching](https://github.com/graphty-org/algorithms/blob/main/examples/bipartite-matching-example.js) - Job assignment, dating apps
 - [Graph Isomorphism](https://github.com/graphty-org/algorithms/blob/main/examples/graph-isomorphism-example.js) - Structural equivalence
 
 ### Link Prediction
+
 - [Common Neighbors](https://github.com/graphty-org/algorithms/blob/main/examples/common-neighbors-example.js) - Friend suggestions
 - [Adamic-Adar](https://github.com/graphty-org/algorithms/blob/main/examples/adamic-adar-example.js) - Weighted predictions
 
 ### Advanced Algorithms
-- [A* Pathfinding](https://github.com/graphty-org/algorithms/blob/main/examples/astar-pathfinding.ts) - Heuristic pathfinding
+
+- [A\* Pathfinding](https://github.com/graphty-org/algorithms/blob/main/examples/astar-pathfinding.ts) - Heuristic pathfinding
 - [Flow Algorithms](https://github.com/graphty-org/algorithms/blob/main/examples/flow-algorithms.ts) - Maximum flow and applications
 - [Ford-Fulkerson Flow](https://github.com/graphty-org/algorithms/blob/main/examples/ford-fulkerson-flow.ts) - Maximum flow implementation
 - [Minimum Cut](https://github.com/graphty-org/algorithms/blob/main/examples/min-cut.ts) - Graph partitioning
 
 ### Research Algorithms
+
 - [SynC Clustering](https://github.com/graphty-org/algorithms/blob/main/examples/sync-example.js) - Deep learning based clustering
 - [TeraHAC](https://github.com/graphty-org/algorithms/blob/main/examples/terahac-example.js) - Scalable hierarchical clustering
 - [GRSBM](https://github.com/graphty-org/algorithms/blob/main/examples/grsbm-example.js) - Explainable community detection
@@ -1013,82 +1156,82 @@ The library includes comprehensive examples demonstrating each algorithm. Find t
 ### Working with Weighted Graphs
 
 ```typescript
-const graph = new Graph();
+const graph = new Graph()
 
 // Add weighted edges
-graph.addEdge('A', 'B', 5);
-graph.addEdge('B', 'C', 3);
-graph.addEdge('A', 'C', 10);
+graph.addEdge('A', 'B', 5)
+graph.addEdge('B', 'C', 3)
+graph.addEdge('A', 'C', 10)
 
 // Find shortest path considering weights
-const result = dijkstra(graph, 'A');
-const pathToC = dijkstraPath(graph, 'A', 'C');
-console.log(pathToC); // { path: ['A', 'B', 'C'], distance: 8 }
+const result = dijkstra(graph, 'A')
+const pathToC = dijkstraPath(graph, 'A', 'C')
+console.log(pathToC) // { path: ['A', 'B', 'C'], distance: 8 }
 ```
 
 ### Directed Graphs
 
 ```typescript
-const directedGraph = new Graph({ directed: true });
+const directedGraph = new Graph({ directed: true })
 
-directedGraph.addEdge('A', 'B');
-directedGraph.addEdge('B', 'C');
-directedGraph.addEdge('C', 'A');
+directedGraph.addEdge('A', 'B')
+directedGraph.addEdge('B', 'C')
+directedGraph.addEdge('C', 'A')
 
 // Check for cycles
-console.log(hasCycleDFS(directedGraph)); // true
+console.log(hasCycleDFS(directedGraph)) // true
 
 // Find strongly connected components
-const sccs = stronglyConnectedComponents(directedGraph);
-console.log(sccs.components); // [['A', 'B', 'C']]
+const sccs = stronglyConnectedComponents(directedGraph)
+console.log(sccs.components) // [['A', 'B', 'C']]
 ```
 
 ### Network Analysis
 
 ```typescript
 // Identify important nodes
-const graph = createSocialNetwork(); // Your graph
+const graph = createSocialNetwork() // Your graph
 
 // Find influencers (high PageRank)
-const influencers = topPageRankNodes(graph, 10);
+const influencers = topPageRankNodes(graph, 10)
 
 // Find bridges (high betweenness)
 const bridgers = Array.from(betweennessCentrality(graph).entries())
   .sort((a, b) => b[1] - a[1])
-  .slice(0, 10);
+  .slice(0, 10)
 
 // Find communities (connected components)
-const communities = connectedComponents(graph);
-console.log(`Found ${communities.components.length} communities`);
+const communities = connectedComponents(graph)
+console.log(`Found ${communities.components.length} communities`)
 ```
 
 ### Custom Edge Properties
 
 ```typescript
-const graph = new Graph();
+const graph = new Graph()
 
 // Add edges with custom data
-graph.addEdge('A', 'B', 1, { 
-  type: 'road', 
-  distance: 100, 
-  traffic: 'heavy' 
-});
+graph.addEdge('A', 'B', 1, {
+  type: 'road',
+  distance: 100,
+  traffic: 'heavy'
+})
 
 // Use custom weight in algorithms
-const result = dijkstra(graph, 'A', { 
+const result = dijkstra(graph, 'A', {
   weightKey: 'distance' // Use 'distance' property as weight
-});
+})
 ```
 
 ### Graph Visualization Preparation
 
 ```typescript
 // Prepare data for visualization
-const graph = loadGraph();
+const graph = loadGraph()
 
 // Calculate layout metrics
-const centralities = degreeCentrality(graph, { normalized: true });
-const ranks = pageRank(graph);
+const centralities = degreeCentrality(graph, { normalized: true })
+const ranks = pageRank(graph)
 
 // Export for visualization
 const nodes = Array.from(graph.nodes()).map(node => ({
@@ -1096,14 +1239,14 @@ const nodes = Array.from(graph.nodes()).map(node => ({
   data: node.data,
   size: centralities.get(node.id) || 0,
   importance: ranks.get(node.id) || 0
-}));
+}))
 
 const edges = Array.from(graph.edges()).map(edge => ({
   source: edge.source,
   target: edge.target,
   weight: edge.weight || 1,
   data: edge.data
-}));
+}))
 ```
 
 ## Type Definitions
@@ -1111,19 +1254,19 @@ const edges = Array.from(graph.edges()).map(edge => ({
 ### Core Types
 
 ```typescript
-type NodeId = string | number;
+type NodeId = string | number
 
 interface Node {
-  id: NodeId;
-  data?: Record<string, unknown>;
+  id: NodeId
+  data?: Record<string, unknown>
 }
 
 interface Edge {
-  source: NodeId;
-  target: NodeId;
-  weight?: number;
-  id?: string;
-  data?: Record<string, unknown>;
+  source: NodeId
+  target: NodeId
+  weight?: number
+  id?: string
+  data?: Record<string, unknown>
 }
 ```
 
@@ -1131,106 +1274,106 @@ interface Edge {
 
 ```typescript
 interface TraversalResult {
-  visited: Set<NodeId>;
-  order: NodeId[];
-  tree?: Map<NodeId, NodeId>;
+  visited: Set<NodeId>
+  order: NodeId[]
+  tree?: Map<NodeId, NodeId | null>
 }
 
 interface ShortestPathResult {
-  path: NodeId[];
-  distance: number;
-  predecessor: NodeId | null;
+  distance: number
+  path: NodeId[]
+  predecessor: Map<NodeId, NodeId | null>
 }
 
 interface BellmanFordResult {
-  distances: Map<NodeId, number>;
-  predecessors: Map<NodeId, NodeId | null>;
-  hasNegativeCycle: boolean;
-  negativeCycleNodes?: Set<NodeId>;
+  distances: Map<NodeId, number>
+  previous: Map<NodeId, NodeId | null>
+  hasNegativeCycle: boolean
+  negativeCycleNodes?: NodeId[]
 }
 
-type CentralityResult = Record<string, number>;
+type CentralityResult = Record<string, number>
 
 interface PageRankResult {
-  ranks: Record<string, number>;
-  iterations: number;
-  converged: boolean;
+  ranks: Record<string, number>
+  iterations: number
+  converged: boolean
 }
 
 interface CommunityResult {
-  communities: Map<NodeId, number>;
-  modularity: number;
+  communities: Map<NodeId, number>
+  modularity: number
 }
 
 interface ComponentResult {
-  components: NodeId[][];
-  componentMap: Map<NodeId, number>;
+  components: NodeId[][]
+  componentMap: Map<NodeId, number>
 }
 
 interface HITSResult {
-  hubs: CentralityResult;
-  authorities: CentralityResult;
+  hubs: CentralityResult
+  authorities: CentralityResult
 }
 
 interface SpectralClusteringResult {
-  communities: NodeId[][];
-  clusterAssignments: Map<NodeId, number>;
+  communities: NodeId[][]
+  clusterAssignments: Map<NodeId, number>
 }
 
 interface MCLResult {
-  communities: NodeId[][];
-  attractors: Set<NodeId>;
-  iterations: number;
-  converged: boolean;
+  communities: NodeId[][]
+  attractors: Set<NodeId>
+  iterations: number
+  converged: boolean
 }
 
 interface BipartiteMatchingResult {
-  matching: Map<NodeId, NodeId>;
-  size: number;
+  matching: Map<NodeId, NodeId>
+  size: number
 }
 
 interface LinkPredictionScore {
-  source: NodeId;
-  target: NodeId;
-  score: number;
+  source: NodeId
+  target: NodeId
+  score: number
 }
 
 interface HierarchicalClusteringResult<T> {
-  root: ClusterNode<T>;
-  dendrogram: ClusterNode<T>[];
-  clusters: Map<number, Set<T>[]>;
+  root: ClusterNode<T>
+  dendrogram: ClusterNode<T>[]
+  clusters: Map<number, Set<T>[]>
 }
 
 interface KCoreResult<T> {
-  cores: Map<number, Set<T>>;
-  coreness: Map<T, number>;
-  maxCore: number;
+  cores: Map<number, Set<T>>
+  coreness: Map<T, number>
+  maxCore: number
 }
 
 interface IsomorphismResult {
-  isIsomorphic: boolean;
-  mapping?: Map<NodeId, NodeId>;
+  isIsomorphic: boolean
+  mapping?: Map<NodeId, NodeId>
 }
 
 interface SynCResult {
-  communities: NodeId[][];
-  clusterAssignments: Map<NodeId, number>;
-  embeddings: Map<NodeId, number[]>;
-  iterations: number;
-  converged: boolean;
+  communities: NodeId[][]
+  clusterAssignments: Map<NodeId, number>
+  embeddings: Map<NodeId, number[]>
+  iterations: number
+  converged: boolean
 }
 
 interface TeraHACResult {
-  root: TeraHACClusterNode;
-  dendrogram: TeraHACClusterNode[];
-  clusters: NodeId[][];
-  mergeDistances: number[];
+  root: TeraHACClusterNode
+  dendrogram: TeraHACClusterNode[]
+  clusters: NodeId[][]
+  mergeDistances: number[]
 }
 
 interface GRSBMResult {
-  clusters: GRSBMCluster[];
-  hierarchy: Map<number, number[]>;
-  totalModularity: number;
+  clusters: GRSBMCluster[]
+  hierarchy: Map<number, number[]>
+  totalModularity: number
 }
 ```
 
@@ -1246,8 +1389,8 @@ interface GRSBMResult {
   - Connected Components: O(V + E)
   - Kruskal's MST: O(E log E)
   - Prim's MST: O((V + E) log V)
-  - A*: O((V + E) log V) - depends on heuristic quality
-  - Ford-Fulkerson: O(E * f) where f is max flow
+  - A\*: O((V + E) log V) - depends on heuristic quality
+  - Ford-Fulkerson: O(E \* f) where f is max flow
   - Edmonds-Karp: O(VE²)
   - Louvain/Leiden: O(n log n) average case
   - Hierarchical Clustering: O(n² log n)
@@ -1256,12 +1399,13 @@ interface GRSBMResult {
   - GRSBM: O(m log n) where m is edges
 - **Memory Usage**: O(V + E) for graph storage
 - **Browser Optimization**: Algorithms use iterative approaches where possible to avoid stack overflow
+- **Performance Benchmarks**: View detailed performance comparisons at [https://graphty-org.github.io/algorithms/benchmarks/](https://graphty-org.github.io/algorithms/benchmarks/)
 
 ## Development
 
 ### Prerequisites
 
-- Node.js 18+ 
+- Node.js 18+
 - npm 9+
 
 ### Setup
@@ -1297,12 +1441,18 @@ npm run lint         # Run ESLint
 npm run lint:fix     # Fix ESLint issues
 npm run lint:pkg     # Check for unused dependencies
 
-# Git
-npm run commit       # Conventional commit helper
+# Benchmarking
+npm run benchmark    # Run full benchmark suite
+npm run benchmark:quick # Run quick benchmark
+npm run benchmark:report # Generate performance report
 
-# HTML Examples
-npm run examples:html # Run interactive HTML examples
+# HTML Examples & Documentation
+npm run examples:html # Run interactive HTML examples locally
 npm run build:gh-pages # Build for GitHub Pages deployment
+npm run examples:run # Run all code examples
+
+# Git
+npm run commit       # Conventional commit helper
 ```
 
 ### Development Server
@@ -1310,12 +1460,14 @@ npm run build:gh-pages # Build for GitHub Pages deployment
 The project includes interactive HTML examples demonstrating each algorithm. To run them locally:
 
 1. **Copy the environment configuration:**
+
    ```bash
    cp .env.example .env
    ```
 
 2. **Configure the server (optional):**
    Edit `.env` to set your preferred host and port:
+
    ```bash
    # Server host (defaults to true for network exposure)
    HOST=localhost       # For local-only access
@@ -1327,6 +1479,7 @@ The project includes interactive HTML examples demonstrating each algorithm. To
    ```
 
 3. **Start the development server:**
+
    ```bash
    npm run examples:html
    ```
@@ -1334,6 +1487,7 @@ The project includes interactive HTML examples demonstrating each algorithm. To
 4. **Open your browser** to `http://localhost:9000` (or your configured host/port)
 
 The HTML examples provide:
+
 - Interactive visualizations for each algorithm
 - Step-by-step execution with play/pause controls
 - Multiple graph types for testing