update README with plugin explanation

Author: danylaksono

README.md

@@ -4,7 +4,7 @@
 
 A GPU/Canvas hybrid Screen-Space Grid Aggregation library for MapLibre GL JS. This library provides efficient real-time aggregation of point data into screen-space grids with customizable styling, interactive features, and advanced glyph drawing capabilities.
 
-This library is inspired by Aidan Slingsby's Gridded Glyphmaps and deck.gl's `ScreenGridLayer` but is built from the ground up with a modular architecture, focusing on performance, flexibility, and ease of use.
+This library is inspired by Aidan Slingsby's [Gridded Glyphmaps](https://openaccess.city.ac.uk/id/eprint/31115/) and borrows some basic concepts from deck.gl's [`ScreenGridLayer`](https://deck.gl/docs/api-reference/aggregation-layers/screen-grid-layer), but is built from the ground up with a modular architecture, focusing on performance, flexibility, and ease of use, particularly for MaplibreGL ecosystem.
 
 ![](./screengrid.png)
 
@@ -14,6 +14,8 @@ This library is inspired by Aidan Slingsby's Gridded Glyphmaps and deck.gl's `Sc
 - **Customizable Styling**: Flexible color scales and cell sizing
 - **Interactive Events**: Hover and click handlers for grid cells
 - **Glyph Drawing**: Custom glyph rendering with Canvas 2D for advanced visualizations
+- **Plugin Ecosystem**: Reusable, named glyph plugins with registry system, lifecycle hooks, and legend integration
+- **Built-in Plugins**: Four ready-to-use plugins (`circle`, `bar`, `pie`, `heatmap`) plus utilities for custom plugins
 - **MapLibre Integration**: Seamless integration with MapLibre GL JS
 - **Performance Optimized**: Uses Canvas 2D rendering for optimal performance
 - **Responsive Design**: Automatically adjusts to map viewport changes
@@ -180,7 +182,7 @@ const maplibregl = require('maplibre-gl');
 `maplibre-gl` is a peer dependency and is not bundled. In UMD builds, it is expected as a global `maplibregl`.                                                                                                                                             
 ## 🎨 Glyph Drawing
 
-The library supports custom glyph drawing through the `onDrawCell` callback. This enables rich multivariate visualizations including time series, categorical breakdowns, and complex relationships.
+The library supports custom glyph drawing through the `onDrawCell` callback and a powerful **Plugin Ecosystem** for reusable glyph visualizations. This enables rich multivariate visualizations including time series, categorical breakdowns, and complex relationships.
 
 📖 **📚 Comprehensive Guide**: See [docs/GLYPH_DRAWING_GUIDE.md](./docs/GLYPH_DRAWING_GUIDE.md) for detailed documentation on:
 - All built-in glyph utilities (8 types including time series)
@@ -189,7 +191,7 @@ The library supports custom glyph drawing through the `onDrawCell` callback. Thi
 - Time series and spatio-temporal visualization
 - Advanced patterns and best practices
 
-### Quick Example
+### Quick Example: Using onDrawCell
 
 ```javascript
 const gridLayer = new ScreenGridLayerGL({
@@ -219,6 +221,115 @@ const gridLayer = new ScreenGridLayerGL({
 });
 ```
 
+## 🔌 Plugin Ecosystem
+
+ScreenGrid includes a **Plugin Ecosystem** that allows you to create reusable, named glyph visualizations. This system provides:
+
+- **Built-in Plugins**: Four ready-to-use plugins (`circle`, `bar`, `pie`, `heatmap`)
+- **Plugin Registry**: Register custom plugins by name for reuse across multiple layers
+- **Lifecycle Hooks**: Support for initialization and cleanup
+- **Legend Integration**: Automatic legend generation for plugins
+- **Backward Compatible**: Existing `onDrawCell` callbacks work with highest precedence
+
+📖 **📚 Full Documentation**: See [docs/PLUGIN_GLYPH_ECOSYSTEM.md](./docs/PLUGIN_GLYPH_ECOSYSTEM.md) for comprehensive plugin documentation, API reference, and usage patterns.
+
+### Using Built-in Plugins
+
+```javascript
+import { ScreenGridLayerGL } from 'screengrid';
+
+// Use a built-in plugin
+const layer = new ScreenGridLayerGL({
+  data,
+  getPosition: (d) => d.coordinates,
+  glyph: 'circle',  // Built-in plugin name
+  glyphConfig: {
+    radius: 15,
+    color: '#3498db',
+    alpha: 0.9
+  },
+  enableGlyphs: true
+});
+```
+
+### Available Built-in Plugins
+
+1. **`circle`** - Simple filled circle with customizable size, color, and opacity
+2. **`bar`** - Horizontal bar chart showing multiple values side-by-side
+3. **`pie`** - Pie chart showing proportional distribution of values
+4. **`heatmap`** - Circle with color intensity representing normalized values
+
+### Creating Custom Plugins
+
+```javascript
+import { ScreenGridLayerGL, GlyphRegistry } from 'screengrid';
+
+// Define a custom plugin
+const MyCustomGlyph = {
+  draw(ctx, x, y, normalizedValue, cellInfo, config) {
+    const radius = config.radius || cellInfo.glyphRadius;
+    ctx.fillStyle = config.color || '#3498db';
+    ctx.beginPath();
+    ctx.arc(x, y, radius, 0, 2 * Math.PI);
+    ctx.fill();
+  },
+  
+  // Optional: initialization hook
+  init({ layer, config }) {
+    console.log(`Initializing plugin for layer ${layer.id}`);
+    return {
+      destroy() {
+        console.log('Cleaning up plugin');
+      }
+    };
+  },
+  
+  // Optional: legend support
+  getLegend(gridData, config) {
+    return {
+      type: 'custom',
+      title: 'My Visualization',
+      items: [
+        { label: 'Category A', color: '#ff0000' },
+        { label: 'Category B', color: '#00ff00' }
+      ]
+    };
+  }
+};
+
+// Register the plugin
+GlyphRegistry.register('myGlyph', MyCustomGlyph);
+
+// Use the registered plugin
+const layer = new ScreenGridLayerGL({
+  data,
+  glyph: 'myGlyph',  // Use by name
+  glyphConfig: { radius: 15, color: '#ff6600' },
+  enableGlyphs: true
+});
+```
+
+### Plugin Precedence
+
+When rendering glyphs, the system uses the following precedence order (highest to lowest):
+
+1. **User-provided `onDrawCell` callback** (full backward compatibility)
+2. **Registered plugin via `glyph` name**
+3. **Color-mode rendering** (no glyphs)
+
+This ensures backward compatibility while allowing gradual migration to the plugin system.
+
+### Plugin Example
+
+See [`examples/plugin-glyph.html`](./examples/plugin-glyph.html) for a complete example demonstrating:
+- Custom plugin registration (`grouped-bar` plugin)
+- Lifecycle hooks (`init` and `destroy`)
+- Legend integration
+- Global state management for cross-cell normalization
+- Interactive hover effects
+
+📖 **For detailed plugin API documentation**: See [docs/PLUGIN_GLYPH_ECOSYSTEM.md](./docs/PLUGIN_GLYPH_ECOSYSTEM.md)
+
 ## 📚 Examples
 
 ### Running the Examples
@@ -238,6 +349,7 @@ npx http-server -p 8000
 4. **Legend Example** (`examples/legend-example.html`) - Demonstrates legend functionality
 5. **Time Series** (`examples/timeseries.html`) - Temporal data visualization
 6. **Multivariate Time Series** (`examples/multivariate-timeseries.html`) - Advanced multi-attribute temporal visualization
+7. **Plugin Glyph** (`examples/plugin-glyph.html`) - Complete plugin ecosystem example with custom `grouped-bar` plugin, lifecycle hooks, and legend integration
 
 ### Example Features
 
@@ -266,8 +378,10 @@ npx http-server -p 8000
 | `onAggregate` | Function | `null` | Callback when grid is aggregated |
 | `onHover` | Function | `null` | Callback when hovering over cells |
 | `onClick` | Function | `null` | Callback when clicking cells |
-| `onDrawCell` | Function | `null` | Callback for custom glyph drawing |
+| `onDrawCell` | Function | `null` | Callback for custom glyph drawing (highest precedence) |
 | `enableGlyphs` | boolean | `false` | Enable glyph-based rendering |
+| `glyph` | string | `null` | Registered plugin name to use (e.g., `'circle'`, `'bar'`, `'pie'`, `'heatmap'`) |
+| `glyphConfig` | object | `{}` | Configuration object passed to plugin's `draw()` method |
 | `glyphSize` | number | `0.8` | Size of glyphs relative to cell size |
 | `adaptiveCellSize` | boolean | `false` | Enable adaptive cell sizing |
 | `minCellSize` | number | `20` | Minimum cell size in pixels |
@@ -300,6 +414,34 @@ ScreenGridLayerGL.drawHeatmapGlyph(ctx, x, y, radius, normalizedValue, colorScal
 ScreenGridLayerGL.drawRadialBarGlyph(ctx, x, y, values, maxValue, maxRadius, color);
 ```
 
+### GlyphRegistry API
+
+The `GlyphRegistry` manages the plugin ecosystem and provides methods for registering and managing glyph plugins:
+
+```javascript
+import { GlyphRegistry } from 'screengrid';
+
+// Register a plugin
+GlyphRegistry.register(name, plugin, { overwrite = false })
+
+// Retrieve a plugin
+GlyphRegistry.get(name)
+
+// Check if plugin exists
+GlyphRegistry.has(name)
+
+// List all registered plugins
+GlyphRegistry.list()
+
+// Unregister a plugin
+GlyphRegistry.unregister(name)
+
+// Clear all plugins (use with caution)
+GlyphRegistry.clear()
+```
+
+See [Plugin Ecosystem](#-plugin-ecosystem) section above for detailed usage examples.
+
 ## 📊 Legend Module
 
 The library includes a powerful Legend module for automatically generating data-driven legends:

docs/PLUGIN_GLYPHS.md

@@ -18,9 +18,9 @@ Status: ✅ **Fully implemented and production-ready**. Complete implementation
 - Registration: `GlyphRegistry.register(name, plugin, { overwrite=false })`
 - Plugin shape (required/optional fields):
   - `draw(ctx, x, y, normalizedValue, cellInfo, config)` — required. Draw into the provided Canvas 2D context.
-  - `init?(opts)` — optional. Called by a layer if the layer wants to invoke initialization. (Not used in MVP.)
-  - `destroy?()` — optional. Called on layer removal if used.
-  - `getLegend?(cellInfo)` — optional. Return legend entries for the cell.
+  - `init?({ layer, config })` — optional. Called when a layer using this plugin is created. Can return an object with a `destroy()` method for cleanup.
+  - `destroy?({ layer })` — optional. Called on layer removal if used (or if `init()` didn't return a destroy method).
+  - `getLegend?(gridData, config)` — optional. Return legend entries for the plugin visualization.
 
 ## Layer integration
 
@@ -40,7 +40,7 @@ Implementation detail: the layer constructs a wrapper `onDrawCell` function from
 Register a glyph in your app startup code:
 
 ```javascript
-import { GlyphRegistry } from 'screengrid/src/glyphs/GlyphRegistry.js';
+import { GlyphRegistry } from 'screengrid';
 
 GlyphRegistry.register('myGauge', {
   draw(ctx, x, y, normalizedValue, cellInfo, config) {

docs/PLUGIN_GLYPH_ECOSYSTEM.md

@@ -244,43 +244,59 @@ Custom plugins can be created by implementing the plugin interface. The ecosyste
 
 ### `grouped-bar` — Grouped Bar Chart Plugin
 
-**Location**: `examples/plugin-glyph.html` (lines 203-384)
+**Location**: `examples/plugin-glyph.html` (lines 203-391)
 
-**Description**: A sophisticated custom plugin that visualizes carbon savings vs. cost comparison across multiple technology categories (ASHP, EV, PV) and cost types (Labour, Material).
+**Description**: A sophisticated custom plugin that visualizes parking capacity data comparing bike racks vs. parking spaces using grouped bars. This plugin demonstrates advanced plugin features including global state management, cross-cell normalization, and interactive hover effects.
 
 **Features**:
-- Multivariate data aggregation (carbon and cost values)
-- Category-specific color schemes
-- Dual-axis visualization (carbon for technologies, cost for expenses)
+- Multivariate data aggregation (racks and spaces values)
+- Category-specific color schemes (blue for racks, green for spaces)
+- Global normalization for cross-cell comparison
 - Integrated legend support via `getLegend()` method
 - Lifecycle hooks (`init()` and `destroy()`)
+- Interactive hover effects with comparison outlines
+- Global statistics tracking across all cells
 
 **Key Implementation Details**:
 
 ```javascript
 const GroupedBarGlyph = {
+  // Global stats for normalization across all cells
+  globalStats: {
+    maxRacks: 0,
+    maxSpaces: 0,
+    maxTotal: 0,
+    initialized: false
+  },
+  
   init({ layer, config } = {}) {
-    // Optional initialization per layer instance
+    // Store layer reference and reset global stats
+    this.layerRef = layer;
+    this.globalStats = { maxRacks: 0, maxSpaces: 0, maxTotal: 0, initialized: false };
     return {
       destroy() {
-        // Cleanup if needed
+        console.log('GroupedBarGlyph instance destroyed');
       }
     };
   },
 
   draw(ctx, x, y, normalizedValue, cellInfo, config = {}) {
-    // 1. Aggregate data from cellData
+    // 1. Aggregate data from cellData (racks and spaces)
     // 2. Calculate chart dimensions
-    // 3. Draw bars for each category
-    // 4. Apply color schemes
+    // 3. Draw grouped bars for each category (racks vs spaces)
+    // 4. Apply color schemes (blue for racks, green for spaces)
+    // 5. Show comparison outline when hovering over different cell
   },
 
   getLegend(gridData, config = {}) {
-    // Return legend metadata
     return {
       type: 'custom',
-      title: 'Carbon vs Cost Comparison',
-      items: [...]
+      title: 'Parking Capacity',
+      description: 'Grouped bar chart comparing bike racks and parking spaces:',
+      items: [
+        { label: 'Racks', description: 'Number of bike racks (blue)', color: 'rgba(52, 152, 219, 0.85)' },
+        { label: 'Spaces', description: 'Number of parking spaces (green)', color: 'rgba(46, 204, 113, 0.85)' }
+      ]
     };
   }
 };