.

README.md

@@ -11,6 +11,9 @@ A dynamic, real-time ASCII-based vertical bar chart library that renders beautif
 - 🏷️ **Customizable Labels**: Add title, X-axis, and vertical Y-axis labels
 - 🎯 **Scrolling Data**: Old data automatically scrolls off as new data arrives
 - 🎨 **Terminal Theme**: Retro green-on-black aesthetic
+- ⏱️ **Time Bin Mode**: Aggregate data into configurable time bins (e.g., count events per 10-second window)
+- 📈 **Multiple X-Axis Formats**: Display elapsed time, bin numbers, timestamps, or time ranges
+- 👁️ **Active Bin Indicator**: Visual marker shows which bin is currently accumulating data
 
 ## Demo
 
@@ -117,6 +120,9 @@ Creates a new ASCII bar chart instance.
 | `xAxisLabel` | string | `''` | X-axis label (displayed centered at bottom) |
 | `yAxisLabel` | string | `''` | Y-axis label (displayed vertically on left side) |
 | `autoFitWidth` | boolean | `true` | Automatically adjust font size to fit container width |
+| `useBinMode` | boolean | `false` | Enable time bin mode for data aggregation |
+| `binDuration` | number | `4000` | Duration of each time bin in milliseconds (4 seconds default) |
+| `xAxisLabelFormat` | string | `'elapsed'` | X-axis label format: `'elapsed'`, `'bins'`, `'timestamps'`, `'ranges'` |
 
 **Example:**
 
@@ -249,6 +255,47 @@ cpuChart.addValue(45);
 memChart.addValue(2048);
 ```
 
+## Time Bin Mode
+
+Time bin mode aggregates data points into time-based bins, showing the count of events within each time window. This is useful for visualizing event frequency over time.
+
+### Basic Time Bin Usage
+
+```javascript
+const chart = new ASCIIBarChart('chart-container', {
+    useBinMode: true,
+    binDuration: 10000,        // 10-second bins
+    xAxisLabelFormat: 'elapsed', // Show elapsed time
+    title: 'Event Counter',
+    yAxisLabel: 'Count'
+});
+
+// Each addValue() increments the count in the current active bin
+chart.addValue(1);  // Bin 1: count = 1
+chart.addValue(1);  // Bin 1: count = 2
+// ... after 10 seconds, automatically creates Bin 2
+```
+
+### X-Axis Label Formats
+
+- **`'elapsed'`** (default): Shows elapsed seconds since chart start ("0s", "10s", "20s")
+- **`'bins'`**: Shows bin numbers ("Bin 1", "Bin 2", "Bin 3")
+- **`'timestamps'`**: Shows actual timestamps ("103000", "103010", "103020")
+- **`'ranges'`**: Shows time ranges ("0-10s", "10-20s", "20-30s")
+
+### Visual Indicators
+
+- **X**: Regular bin data
+- **O**: Active bin currently accumulating data
+- Chart automatically scales when bin counts exceed chart height
+
+### Manual Bin Rotation
+
+```javascript
+// Force rotation to new bin (useful for testing)
+chart.rotateBin();
+```
+
 ## Styling
 
 The chart uses monospaced fonts and renders as plain text. Style the container element: