@graphty/algorithms 1.2.0 → 1.4.2

package/README.md

@@ -4,18 +4,58 @@
 [![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,30 +65,30 @@ 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();
 
 // 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.hasEdge("A", "B")); // true
 
 // Run algorithms
-const traversal = breadthFirstSearch(graph, 'A');
+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');
+const pathToC = shortestPaths.get("C");
 console.log(pathToC?.distance); // 3
 ```
 
@@ -60,7 +100,7 @@ The core data structure for representing graphs.
 
 ```typescript
 class Graph {
-  constructor(config?: Partial<GraphConfig>)
+    constructor(config?: Partial<GraphConfig>);
 }
 ```
 
@@ -68,9 +108,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 +138,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 +207,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 +221,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 +252,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,37 +277,42 @@ 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>, 
+// Returns: BellmanFordResult {
+//   distances: Map<NodeId, number>,
 //   predecessors: Map<NodeId, NodeId | null>,
 //   hasNegativeCycle: boolean,
 //   negativeCycleNodes?: Set<NodeId>
@@ -274,7 +330,7 @@ const result = hasNegativeCycle(graph);
 #### 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);
@@ -294,30 +350,30 @@ 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>)
 
@@ -333,38 +389,47 @@ const edgeCentralities = edgeBetweennessCentrality(graph, options);
 #### 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 }
 
@@ -376,17 +441,21 @@ const ranks = personalizedPageRank(graph, personalization, options);
 // Get top N nodes by PageRank
 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>)
 
@@ -398,15 +467,15 @@ const centrality = nodeEigenvectorCentrality(graph, nodeId, options);
 #### 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>)
 
@@ -418,12 +487,12 @@ const centrality = nodeKatzCentrality(graph, nodeId, options);
 #### 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 }
 
@@ -437,13 +506,13 @@ const scores = nodeHITS(graph, nodeId, options);
 #### Basic Component Operations
 
 ```typescript
-import { 
-  connectedComponents, 
-  isConnected, 
-  numberOfConnectedComponents,
-  largestConnectedComponent,
-  getConnectedComponent 
-} from '@graphty/algorithms';
+import {
+    connectedComponents,
+    isConnected,
+    numberOfConnectedComponents,
+    largestConnectedComponent,
+    getConnectedComponent,
+} from "@graphty/algorithms";
 
 // Find all components
 const components = connectedComponents(graph);
@@ -469,12 +538,12 @@ const component = getConnectedComponent(graph, nodeId);
 #### Strongly Connected Components
 
 ```typescript
-import { 
-  stronglyConnectedComponents,
-  findStronglyConnectedComponents,
-  isStronglyConnected,
-  condensationGraph 
-} from '@graphty/algorithms';
+import {
+    stronglyConnectedComponents,
+    findStronglyConnectedComponents,
+    isStronglyConnected,
+    condensationGraph,
+} from "@graphty/algorithms";
 
 // Find SCCs using Tarjan's algorithm
 const sccs = stronglyConnectedComponents(graph);
@@ -500,7 +569,7 @@ const components = connectedComponentsDFS(graph);
 #### 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);
@@ -518,7 +587,7 @@ 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);
 
@@ -535,7 +604,7 @@ 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>();
 
@@ -552,7 +621,7 @@ 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);
@@ -577,12 +646,12 @@ 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 }
 ```
@@ -590,13 +659,13 @@ const communities = louvain(graph, {
 #### 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 }
 ```
@@ -604,11 +673,11 @@ const communities = leiden(graph, {
 #### 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>
 
@@ -622,32 +691,30 @@ 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,7 +761,7 @@ 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);
@@ -714,7 +781,7 @@ const clusters = cutDendrogramKClusters(result.root, k);
 #### 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);
@@ -737,14 +804,14 @@ const ordering = degeneracyOrdering(graph);
 #### 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> }
 ```
@@ -752,16 +819,20 @@ const result = spectralClustering(graph, {
 #### 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,12 +840,12 @@ 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 }
 
@@ -789,13 +860,13 @@ const partition = bipartitePartition(graph);
 #### 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> }
 
@@ -809,7 +880,7 @@ 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);
@@ -817,9 +888,9 @@ const score = commonNeighborsScore(graph, node1, node2);
 
 // 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[]
 
@@ -832,14 +903,14 @@ 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);
@@ -847,9 +918,9 @@ const score = adamicAdarScore(graph, node1, node2);
 
 // Predict links using Adamic-Adar
 const predictions = adamicAdarPrediction(graph, {
-  directed?: boolean,
-  includeExisting?: boolean,
-  topK?: number
+    directed: boolean,
+    includeExisting: boolean,
+    topK: number,
 });
 // Returns: LinkPredictionScore[]
 
@@ -866,7 +937,9 @@ 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 +950,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
+    k: number, // Number of clusters
+    maxIterations: number, // Default: 100
+    learningRate: number, // Default: 0.01
+    hiddenDim: number, // Default: 64
+    randomSeed: number,
 });
-// Returns: SynCResult { 
-//   communities: NodeId[][], 
+// Returns: SynCResult {
+//   communities: NodeId[][],
 //   clusterAssignments: Map<NodeId, number>,
 //   embeddings: Map<NodeId, number[]>,
 //   iterations: number,
@@ -899,15 +972,15 @@ 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,
@@ -920,14 +993,14 @@ 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
@@ -941,7 +1014,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 +1025,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. Find them in the [examples directory](https://github.com/graphty-org/algorithms/tree/main/examples):
+The library includes comprehensive examples demonstrating each algorithm. You can:
+
+- **[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 +1044,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 +1054,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
@@ -1016,13 +1104,13 @@ The library includes comprehensive examples demonstrating each algorithm. Find t
 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');
+const result = dijkstra(graph, "A");
+const pathToC = dijkstraPath(graph, "A", "C");
 console.log(pathToC); // { path: ['A', 'B', 'C'], distance: 8 }
 ```
 
@@ -1031,9 +1119,9 @@ console.log(pathToC); // { path: ['A', 'B', 'C'], distance: 8 }
 ```typescript
 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
@@ -1054,8 +1142,8 @@ 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);
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10);
 
 // Find communities (connected components)
 const communities = connectedComponents(graph);
@@ -1068,15 +1156,15 @@ console.log(`Found ${communities.components.length} communities`);
 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', { 
-  weightKey: 'distance' // Use 'distance' property as weight
+const result = dijkstra(graph, "A", {
+    weightKey: "distance", // Use 'distance' property as weight
 });
 ```
 
@@ -1091,18 +1179,18 @@ const centralities = degreeCentrality(graph, { normalized: true });
 const ranks = pageRank(graph);
 
 // Export for visualization
-const nodes = Array.from(graph.nodes()).map(node => ({
-  id: node.id,
-  data: node.data,
-  size: centralities.get(node.id) || 0,
-  importance: ranks.get(node.id) || 0
+const nodes = Array.from(graph.nodes()).map((node) => ({
+    id: node.id,
+    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
+const edges = Array.from(graph.edges()).map((edge) => ({
+    source: edge.source,
+    target: edge.target,
+    weight: edge.weight || 1,
+    data: edge.data,
 }));
 ```
 
@@ -1114,16 +1202,16 @@ const edges = Array.from(graph.edges()).map(edge => ({
 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 +1219,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>;
 
 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;
 }
 ```
 
@@ -1238,30 +1326,31 @@ interface GRSBMResult {
 
 - **Graph Representation**: Uses adjacency lists for O(1) neighbor access
 - **Algorithm Complexity**:
-  - BFS/DFS: O(V + E)
-  - Dijkstra: O((V + E) log V) with binary heap
-  - Bellman-Ford: O(VE)
-  - Floyd-Warshall: O(V³)
-  - PageRank: O(k(V + E)) where k is iterations
-  - 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
-  - Edmonds-Karp: O(VE²)
-  - Louvain/Leiden: O(n log n) average case
-  - Hierarchical Clustering: O(n² log n)
-  - SynC: O(kni) where k is clusters, n is nodes, i is iterations
-  - TeraHAC: O(n log n) with sampling
-  - GRSBM: O(m log n) where m is edges
+    - BFS/DFS: O(V + E)
+    - Dijkstra: O((V + E) log V) with binary heap
+    - Bellman-Ford: O(VE)
+    - Floyd-Warshall: O(V³)
+    - PageRank: O(k(V + E)) where k is iterations
+    - 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
+    - Edmonds-Karp: O(VE²)
+    - Louvain/Leiden: O(n log n) average case
+    - Hierarchical Clustering: O(n² log n)
+    - SynC: O(kni) where k is clusters, n is nodes, i is iterations
+    - TeraHAC: O(n log n) with sampling
+    - 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 +1386,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,30 +1405,34 @@ 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
-   ```
+
+    ```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
-   # HOST=0.0.0.0       # For network access
-   # HOST=my.server.com # Custom domain
 
-   # Server port (defaults to 9000)
-   PORT=9000           # Must be between 9000-9099
-   ```
+    ```bash
+    # Server host (defaults to true for network exposure)
+    HOST=localhost       # For local-only access
+    # HOST=0.0.0.0       # For network access
+    # HOST=my.server.com # Custom domain
+
+    # Server port (defaults to 9000)
+    PORT=9000           # Must be between 9000-9099
+    ```
 
 3. **Start the development server:**
-   ```bash
-   npm run examples:html
-   ```
+
+    ```bash
+    npm run examples:html
+    ```
 
 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