vortx-gl 1.0.30 → 1.0.31

package/README.md

@@ -1,305 +1,560 @@
-# 🎨 VortxGL
+# VortxGL 🎨
 
-[![WebGL2](https://img.shields.io/badge/WebGL2-GPU--Accelerated-orange?style=flat-square&logo=webgl)](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext)
-[![Vue3](https://img.shields.io/badge/Vue%203-Composition%20API-4FC08D?style=flat-square&logo=vue.js)](https://vuejs.org/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Strict%20Types-3178C6?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
-[![Performance](https://img.shields.io/badge/Performance-100k%2B%20Nodes%20%40%2060fps-brightgreen?style=flat-square)](#-performance-benchmarks)
-[![WebWorker](https://img.shields.io/badge/Layout-Multi--Threaded%20Worker-blueviolet?style=flat-square)](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)
-[![License](https://img.shields.io/badge/License-Apache%202.0-red?style=flat-square)](LICENSE)
-
-VortxGL is a world-class, ultra-high-performance graph visualization library built with **WebGL2**, **Vue 3 (Composition API)**, and **TypeScript**.
-
-It was engineered from the ground up to address the limitations of traditional SVG and Canvas-based graph visualizers. While libraries like D3 or Cytoscape choke when handling more than 5,000 nodes due to DOM bloat and main-thread computation bottlenecks, VortxGL easily renders **100,000+ nodes and edges** at a locked **60 FPS**.
+A world-class, high-performance graph visualization engine built with **Vue 3**, **WebGL2**, and **TypeScript**. Engineered for extreme scale and architectural flexibility, VortxGL effortlessly handles **100,000+ nodes and edges** while maintaining a locked 60 FPS.
 
 ---
 
-## 🌐 Live Demo
-
-🚀 **Experience the Speed**: [VortxGL Live Interactive Sandbox](https://webgl-graph.vercel.app)
-
----
-
-## ⚡ Performance Benchmarks
-
-| Metric / Graph Size     | 1,000 Nodes | 10,000 Nodes | 50,000 Nodes |    100,000 Nodes     |
-| :---------------------- | :---------: | :----------: | :----------: | :------------------: |
-| **VortxGL FPS**         | **60 FPS**  |  **60 FPS**  |  **60 FPS**  |      **60 FPS**      |
-| **Standard Canvas FPS** |   60 FPS    |    24 FPS    |    5 FPS     | Crashed/Unresponsive |
-| **Standard SVG FPS**    |   30 FPS    |    2 FPS     | Unresponsive |     Unresponsive     |
-
----
-
-## 🏎️ The Tech Behind the Speed (Architectural Highlights)
-
-VortxGL achieves locked 60 FPS at scale by replacing common browser render bottlenecks with low-level graphics techniques:
-
-### 1. Hybrid WebGL2 + Canvas2D Pipeline
-
-WebGL2 excels at instanced rendering of millions of points and lines, but rendering anti-aliased text (labels), curved hulls, and vector badges in pure shaders is notoriously complex and slow. VortxGL uses a **dual-canvas architecture**:
+## 🚀 Key Evolutionary Features
 
-- Core nodes and edges are drawn on the GPU in a single WebGL2 render pass.
-- High-definition labels, badges, and selections are painted on a 2D HTML5 Canvas overlay.
-- **The "Punch-Out" Technique**: To keep edge lines visual beneath nodes, the overlay draws connections behind, then uses a `destination-out` blending operation to "punch" circular holes in the overlay exactly where the GPU nodes sit. Text and selection rings are then drawn on top.
+### 🎬 Energy Flow Visualization
 
-### 2. O(1) GPU Color Picking
+Bring your data to life with real-time particle animations along graph edges.
 
-Instead of running costly CPU bounding-box calculations or iterating through arrays on every mouse movement:
+- **Dynamic Velocity**: Adjust stream speed in real-time.
+- **Precision Filtering**: Target specific data flows by property and value (e.g., animate only `type: "transaction"`).
+- **GPU-Ready**: Performance-optimized rendering that scales with your dataset.
 
-- VortxGL renders the entire scene to an offscreen buffer (Framebuffer Object) where each node is painted with a unique, color-coded RGB value mapping to its index.
-- When clicking or hovering, the engine queries the exact pixel color under the mouse in $O(1)$ time, providing instantaneous selection feedback even on 100k+ elements.
+### 📁 Advanced Combo (Grouping) System
 
-### 3. Multi-Threaded Layout Worker
+Full support for hierarchical data structures and interactive clustering.
 
-Physics simulations and force layouts are mathematically heavy ($O(N^2)$ or $O(N \log N)$).
+- **Smart Hulls**: Automatically generated convex hulls for expanded groups.
+- **Interactive Collapsing**: Swap complex clusters for intuitive summary nodes.
+- **Cluster Translation**: Drag entire groups while preserving internal layouts.
 
-- VortxGL moves these physics computations entirely off the browser's main thread to a **background Web Worker**.
-- The worker and main thread exchange coordinate data using **Transferable Objects** (`Float32Array` buffers). This allows memory ownership to be passed back and forth instantly with zero copy overhead, completely eliminating Garbage Collection frame drops.
-
-### 4. Incremental Spatial Indexing
-
-To support spatial actions (like zoom-to-fit, group boundary calculations, and camera culling), VortxGL maintains an internal coordinate search index.
-
-- Rather than rebuilding the index on every single tick or position change (an $O(N)$ operation), the engine updates the spatial index incrementally in $O(1)$ time per node mutation.
-
-### 5. Screen-Space Projection Caching
-
-The engine projects world coordinates into screen coordinates to position overlay text. The projection calculations are cached in memory and marked dirty only when the Camera moves or Node positions change. This saves millions of redundant matrix-multiplication operations per second.
-
----
-
-## 🚀 Key Features
-
-### 🎬 Energy Flow Animation
-
-- Highlight data pathways (e.g. tracking transactions or packet routing) via hardware-accelerated particle flow along edges.
-- Real-time controls for velocity, particle size, and opacity.
-- Target flows dynamically by attributes (e.g. only animate edges matching `type === "transaction"`).
-
-### 📁 Collapsible Combos (Groups)
+### ⛓️ Interactive Relation Builder
 
-- Group nodes into logical cluster units.
-- **Smart Hulls**: Automatically draws bounding convex hulls around expanded groups.
-- **Smart Collapsing**: Collapses groups into single representative nodes, calculating the group centroid.
-- **Cluster Translation**: Dragging a group moves all internal member nodes in sync.
+Engineered for semantic graph creation with real-time visual feedback.
 
-### ⛓️ Interactive Relation Builder
+- **Phantom Edges**: Real-time dashed preview line that follows the cursor during connection.
+- **On-the-Fly Configuration**: Set labels, colors, and thickness via an interactive toast before finalizing.
+- **Adaptive Labels**: Screen-space edge labels that automatically render for high-zoom clarity.
 
-- Draw semantic relationships with drag-and-drop actions.
-- **Phantom Edges**: Dashed preview line that tracks the mouse pointer during node-to-node connection.
-- **On-the-fly Config**: Instantly modify connection weights, colors, and metadata before finalizing.
+### 🏎️ Tactical Optimization
 
-### 🎨 Cytoscape-Style Stylesheet System
+Built with a performance-first mindset:
 
-- Apply high-performance styling rules using class selectors (similar to CSS).
-- Fallback hierarchies: Explicit properties > Classes > Theme Defaults.
-- Built-in Dark and Light themes with automatic contrast shifts.
+- **Screen-Space Projection Cache**: Eliminates redundant O(NodeCount) matrix operations for labels and effects.
+- **Zero-Allocation Loops**: Uses specialized scratch buffers to minimize Garbage Collection impact.
 
 ---
 
-## 📦 Quick Start
+## ⚡ Quick Start
 
-### 1. Install
+### 1. Installation
 
 ```bash
 npm install vortx-gl
 ```
 
-### 2. Setup (Vue 3 Component)
-
-Initialize the visualizer using the Vue 3 component. Simply provide a list of nodes and edges formatted with clean metadata.
+### 2. Basic Usage (Vue 3)
 
 ```vue
 <script setup lang="ts">
-import { ref } from "vue";
 import { GraphCanvas } from "vortx-gl";
 import "vortx-gl/dist/vortx-gl.css";
 
-const graphData = ref({
+const graphData = {
   nodes: [
     {
       data: {
-        id: "node-1",
-        label: "Primary Database",
-        color: "#3178C6",
-        size: 60,
-        icon: "🖥️",
-      },
-    },
-    {
-      data: {
-        id: "node-2",
-        label: "API Gateway",
-        color: "#4FC08D",
-        size: 50,
-        icon: "🌐",
-      },
-    },
-    {
-      data: {
-        id: "node-3",
-        label: "Client App",
-        color: "#ff4757",
-        size: 40,
-        icon: "📱",
+        id: "1",
+        label: "Node 1",
+        color: "#00ffcc",
+        backgroundImage: "https://example.com/icon.png",
       },
     },
   ],
   edges: [
     {
-      data: {
-        id: "edge-1",
-        source: "node-3",
-        target: "node-2",
-        label: "HTTPS Request",
-      },
-    },
-    {
-      data: {
-        id: "edge-2",
-        source: "node-2",
-        target: "node-1",
-        label: "SQL Query",
-      },
+      data: { source: "1", target: "2", type: "transfer" },
     },
   ],
-});
+};
 </script>
 
 <template>
-  <div class="canvas-container">
+  <div style="width: 100vw; height: 100vh;">
     <GraphCanvas :data="graphData" />
   </div>
 </template>
+```
+
+---
+
+## 🌐 Live Demo & Docs
+
+🚀 **Experience the Speed**: [View the Live Demo](https://webgl-graph.vercel.app)
+
+---
 
-<style scoped>
-.canvas-container {
-  width: 100vw;
-  height: 100vh;
-  background-color: #0f172a;
+## 📊 Data Schema & Types
+
+VortxGL uses a robust, TypeScript-first schema. All element metadata is stored in a dedicated `data` record for application use.
+
+```json
+{
+  "nodes": [
+    {
+      "data": {
+        "id": "node-1",
+        "label": "Engineering",
+        "color": "#ff4757",
+        "backgroundImage": "data:image/png;base64,...",
+        "metadata": { "status": "active" }
+      }
+    }
+  ],
+  "edges": [
+    {
+      "data": {
+        "id": "edge-1",
+        "source": "node-1",
+        "target": "node-2",
+        "label": "Data Link"
+      }
+    }
+  ]
 }
-</style>
 ```
 
 ---
 
-## 🛠️ Developer API Examples
+## 🎨 Visual Polish
 
-VortxGL provides an imperative, high-performance API for dynamic run-time adjustments.
+VortxGL provides rich options for making your graph look premium and intuitive.
 
-### Add & Update Elements Programmatically
+### 1. Icons & Images
+Nodes can render text-based icons (emojis) or high-resolution images.
 
-All layout and position updates are batch-uploaded directly to GPU buffers:
+```typescript
+engine.addNode({
+  id: "node-1",
+  icon: "📂",      // Renders text/emoji in center
+  image: "url...",  // Renders rounded image inside
+  size: 60
+});
+```
+
+### 2. Color Formats
+Colors accept standard CSS hex strings or precision arrays for hardware-level control.
 
 ```typescript
-import { GraphEngine } from "vortx-gl";
+// CSS Hex
+color: "#ff4757"
+
+// RGBA Array (0-1 range)
+color: [1.0, 0.28, 0.34, 1.0]
+
+// Transparent
+color: [0, 0, 0, 0] // Useful for "ghost" nodes
+```
+
+### 3. Theme Switching
+The engine supports built-in Dark and Light mode, affecting the background clear color and label contrast automatically.
+
+```typescript
+engine.setTheme("light"); // Switches to light background
+```
+
+---
+
+## 📁 Combo Management
+
+Combos (Groups) allow you to cluster related nodes into logical units. They support two modes: **Expanded** (showing a bounding hull) and **Collapsed** (showing a summary representative node).
+
+### 1. Creating a Group
+Groups are created by specifying a unique ID and a list of node IDs to include.
+
+```typescript
+engine.createGroup("group-alpha", "Engineers", ["node-1", "node-2", "node-3"]);
+```
+
+### 2. Collapsing & Expanding
+Collapsing a group hides all member nodes except for one **representative**, which snaps to the centroid of the group.
+
+```typescript
+// Programmatically toggle state
+engine.toggleComboCollapse("group-alpha");
+
+// Listen for collapse events
+engine.on('combo:update', (data) => {
+  console.log(`Group ${data.id} is now ${data.state ? 'collapsed' : 'expanded'}`);
+});
+```
+
+### 3. Interaction Logic
+- **Dragging**: When a group is collapsed, dragging its representative moves all hidden members in sync.
+- **Hulls**: When expanded, a convex hull is automatically rendered around the members with customizable padding and color.
+- **Picking**: You can select a group by clicking on its hull (expanded) or its representative node (collapsed).
+
+---
+
+## ⌨️ Pro Shortcuts
+
+| Command          | Action                     |
+| :--------------- | :------------------------- |
+| **Left Click**   | Select Node / Edge / Combo |
+| **Drag**         | Pan the world              |
+| **Scroll**       | Zoom at mouse focal point  |
+| **Shift + Drag** | Precise Box Selection      |
+| **Radial Right Click** | Contextual Command Menu    |
+| **F**            | Snap to Fit View           |
+
+---
+
+## 🔘 Context Menus
+
+VortxGL is designed to work seamlessly with domestic UI frameworks (Vue, React). Instead of drawing menus on the WebGL canvas, it is recommended to use standard DOM components positioned over the canvas.
+
+### 1. Triggering Menus
+Listen for the `contextmenu` event on the canvas. Use `engine.pick()` or `engine.getEdgeAt()` to identify the element under the cursor.
+
+```typescript
+canvas.addEventListener('contextmenu', (e) => {
+  e.preventDefault();
+  const rect = canvas.getBoundingClientRect();
+  const x = e.clientX - rect.left;
+  const y = e.clientY - rect.top;
+
+  // Identify target
+  const nodeId = engine.pick(x, y);
+  const edgeId = engine.getEdgeAt(x, y);
+
+  // Show your Vue/React menu at e.clientX/Y
+  showMenu({ x: e.clientX, y: e.clientY, target: nodeId || edgeId });
+});
+```
+
+### 2. Customizing Menu Items
+You can configure the segments of the circular menu for nodes, edges, and combos through the engine instance.
+
+```typescript
+engine.setRadialMenu('node', [
+  { label: 'Inspect', icon: 'search', action: 'inspect' },
+  { label: 'Delete', icon: 'trash-2', action: 'delete' },
+  { label: 'Highlight', icon: 'zap', action: 'highlight' }
+]);
+```
 
-const engine = new GraphEngine(canvasElement);
+### 3. Group HUD (Heads-Up Display)
+For combos (groups), the engine draws a built-in HUD with an expand/collapse button. You can detect clicks on these HUD elements using `pickHUD()`.
 
-// Ingest a new node
+```typescript
+engine.on('node:mousedown', (e) => {
+  const hudAction = engine.pickHUD(e.x, e.y);
+  if (hudAction) {
+    if (hudAction.action === 'expand') {
+      engine.toggleComboCollapse(hudAction.comboId);
+    }
+  }
+});
+```
+
+### 4. Interactive Connection Workflow
+
+VortxGL includes a built-in workflow for creating new relations between nodes with real-time feedback.
+
+1. **Trigger**: Call `engine.startConnect(sourceNodeId)` to enter connection mode.
+2. **Preview**: A "Phantom Edge" (dashed line) will follow the cursor from the source node to the mouse position.
+3. **Configure**: Users can set properties like `label` and `color` during the preview phase.
+4. **Complete**: Clicking a target node finalizes the connection and creates a permanent "Styled Edge".
+
+---
+
+
+## 🏗️ Graph Mutation
+
+VortxGL provides a high-performance imperative API for modifying the graph in real-time. Changes are immediately synced to GPU buffers using minimal memory copies.
+
+### 1. Adding Elements
+```typescript
+// Add a node
 engine.addNode({
-  id: "node-99",
-  label: "Microservice A",
-  position: { x: 150, y: -200 },
-  color: "#ff4757",
-  size: 55,
+  id: "node-1",
+  label: "New Node",
+  position: { x: 100, y: 100 },
+  color: "#ff00ff"
 });
 
-// Update node colors or sizes dynamically
+// Add an edge
+engine.addEdge({ 
+  source: "node-1", 
+  target: "node-2", 
+  label: "Connected" 
+});
+```
+
+### 2. Updating Elements
+Updates are partial; you only need to provide the fields you want to change.
+```typescript
 engine.updateNode({
-  id: "node-99",
-  color: "#ffd2df",
-  label: "Microservice A (Dormant)",
+  id: "node-1",
+  color: "#00ff00", // Change color
+  label: "Updated Name"
+});
+
+engine.updateEdge({
+  id: "edge-1",
+  label: "New Relationship"
 });
+```
+
+### 3. Removing Elements
+```typescript
+// Removes node and all connected edges
+engine.removeNode("node-1");
 
-// Delete elements (automatically cleans up connected edges and compacts the array buffers)
-engine.removeNode("node-99");
+// Removes a single edge
+engine.removeEdge("edge-1");
+
+// Complete reset
+engine.clear();
 ```
 
-### Apply CSS-like Classes for Bulk Styling
+### 3. Visual Properties Reference
+
+| Property | Type | Target | Description |
+|---|---|---|---|
+| `label` | string | Both | Primary text label (Edges show at >30% zoom) |
+| `size` | number | Node | Diameter of the node circle |
+| `width` | number | Both | Bounding width for node labels |
+| `customSize` | number | Edge | Precision line thickness (supports <1 and >10) |
+| `customColor`| string | Edge | Per-edge override color (HEX/RGBA) |
+| `color` | string | Node | CSS Hex or RGBA value |
+| `icon` | string | Node | Lucide icon name or Emoji |
+| `image` | string | Node | URL for an image shown inside the node |
+| `opacity`| number | Both | Global transparency (0-1) |
+
+```typescript
+// Style a large node
+engine.updateNode({
+  id: "node-1",
+  label: "Large Server",
+  size: 80,       // Diameter
+  width: 120,     // Label boundary width
+  color: "#ff3300"
+});
+
+// Create a premium styled connection
+engine.addEdge({
+  source: "node-1", 
+  target: "node-2",
+  label: "Critical Link",
+  data: {
+    customColor: "#ff00ff", // Override WebGL global color
+    customSize: 4.5         // Precise thickness in pixels
+  }
+});
+```
+
+---
+
+## 🔍 Querying Elements
+
+Retrieve element data from the engine for inspection or state management.
+
+### 1. Selection by ID
+```typescript
+const node = engine.getNode("node-1");
+console.log(node.position, node.label);
+```
+
+### 2. Selection by Class
+Retrieve groups of elements that share a specific class.
+
+```typescript
+// Get all critical servers
+const criticalNodes = engine.getNodesByClass("critical");
+
+// Get all standard cables
+const standardEdges = engine.getEdgesByClass("standard-link");
+```
+
+### 3. Global Retrieval
+```typescript
+const allNodes = engine.getAllNodes();
+const allEdges = engine.getAllEdges();
+```
+
+---
+
+## 🎨 Styling with Classes
+
+VortxGL supports a high-performance stylesheet system, allowing you to define visual presets and apply them via class names, similar to CSS or Cytoscape.
+
+### 1. Defining a Stylesheet
+A stylesheet is a dictionary where keys are class names and values are style objects. Use `engine.setStylesheet()` to apply it globally.
 
 ```typescript
-const stylesheet = {
-  database: { color: "#3178C6", size: 60, icon: "🗄️" },
-  gateway: { color: "#4FC08D", size: 50, icon: "🔌" },
-  unstable: { color: "#ff4757", size: 45, icon: "⚠️" },
+const theme = {
+  'critical': { color: '#ff4757', size: 60, icon: '⚠️' } ,
+  'server': { color: '#2f3542', size: 45, icon: '🖥️' },
+  'standard-link': { color: 'rgba(255,255,255,0.2)' }
 };
 
-engine.setStylesheet(stylesheet);
+engine.setStylesheet(theme);
+```
+
+### 2. Applying Classes
+Apply classes when adding or updating elements. Multiple classes can be applied as an array; later classes override previous ones.
 
-// Apply style via class names
+```typescript
 engine.addNode({
-  id: "db-node",
-  classes: ["database", "unstable"],
-  label: "User DB",
+  id: "node-1",
+  classes: ["server", "critical"],
+  label: "Database 01"
+});
+
+engine.addEdge({
+  source: "node-1",
+  target: "node-2",
+  classes: ["standard-link"]
 });
 ```
 
-### Triggering Layouts (Circle, Grid, Force-Directed)
+### 3. Priority Rules
+Visual properties are applied in the following order of precedence:
+1. **Explicit Properties**: Properties set directly on the node (e.g., `color: '#fff'`) always win.
+2. **Class Styles**: Properties defined in the stylesheet for the applied classes.
+3. **Engine Defaults**: Hardcoded fallback values.
 
-Layout math runs completely inside the Web Worker thread:
+---
 
-```typescript
-// Circular layout
-engine.runLayout("circle");
+## ⚡ Energy Flow Animation
 
-// Concentric layout with custom spacings
-engine.runLayout("concentric", { spacing: 2 });
+VortxGL includes a custom, hardware-accelerated "Energy Flow" animation for highlighting data movements along edges.
 
-// Run layout exclusively on selected nodes
-engine.runLayout("grid", { selectedOnly: true });
+### 1. Basic Configuration
+```typescript
+engine.setFlowConfig({
+  enabled: true,
+  velocity: 0.005,
+  size: 2,
+  color: "#00ffcc"
+});
 ```
 
-### Animating Edge Particle Flows
+### 2. Selective Flow (Advanced)
+You can restrict the animation to only run on edges connected to the currently selected nodes. This is extremely useful for tracing paths or focusing on specific network segments.
 
 ```typescript
 engine.setFlowConfig({
   enabled: true,
-  velocity: 0.004, // Particle movement speed
-  size: 2.5, // Particle radius in pixels
-  color: "#ffd32a", // Glowing yellow particle streams
+  selectedOnly: true
 });
 ```
 
+### 3. All Options
+| Property | Type | Description |
+|---|---|---|
+| `enabled` | boolean | Toggle the animation |
+| `velocity` | number | Speed of particles (0.001 - 0.01 recommended) |
+| `size` | number | Radius of particles in pixels |
+| `opacity` | number | Transparency (0 - 1) |
+| `pulse` | boolean | Adds a subtle breathing effect to particles |
+| `selectedOnly`| boolean | Show only on edges of selected nodes |
+
 ---
 
-## ⌨️ Shortcuts & Interaction HUD
+## 🏗️ Events & Interactivity
+
+VortxGL features a powerful, Cytoscape-inspired event system for deep integration with your application logic.
+
+### 1. Subscribing to Events
+Use the `on()` API to listen for interactions. Use the returned function to unsubscribe.
+
+```typescript
+// Subscribe
+const unsub = engine.on('node:click', ({ id }) => {
+  console.log('Clicked node:', id);
+});
+
+// Unsubscribe when component is destroyed
+unsub();
+```
 
-| Control                | Action     | Description                                     |
-| :--------------------- | :--------- | :---------------------------------------------- |
-| **Left-Click**         | Select     | Selects nodes, edges, or group hulls            |
-| **Left-Drag**          | Pan        | Drags the viewport camera                       |
-| **Scroll Wheel**       | Zoom       | Zooms in/out centered at mouse pointer          |
-| **Shift + Drag**       | Box Select | Selects multiple nodes via selection marquee    |
-| **Radial Right-Click** | Menu       | Opens dynamic, context-aware command HUD        |
-| **F** Key              | Frame Fit  | Instantly center and snap viewport to fit graph |
+### 2. Available Events
+| Category | Event Keys | Description |
+| :--- | :--- | :--- |
+| **Nodes** | `node:click`, `node:hover`, `node:drag`, `node:select` | Individual element interactions |
+| **Edges** | `edge:click`, `edge:hover`, `edge:select` | Edge-specific interactions |
+| **Combos** | `combo:click`, `combo:hover`, `combo:select` | Group-specific interactions |
+| **Viewport** | `graph:click`, `graph:pan`, `graph:zoom`, `viewport` | Global camera movement |
+| **Selection**| `boxstart`, `boxselect`, `boxend` | Marquee/Box selection lifecycle |
 
 ---
 
-## 🧬 Event Hooks
+## 📸 Viewport & Camera
 
-VortxGL features an event listener pipeline for building interactive dashboards:
+Control the view programmatically to create cinematic transitions or automated "focus" actions.
 
+### 1. Focus & Fit
 ```typescript
-// Subscribe to clicks
-const unsubscribe = engine.on("node:click", ({ id }) => {
-  console.log(`User selected node ID: ${id}`);
-});
+// Auto-scale and center to show the entire graph
+engine.fitToView();
 
-// Unsubscribe during clean up
-unsubscribe();
+// Move camera to a specific world coordinate
+engine.setCameraCenter(0, 0);
 ```
 
-| Event Key                     | Trigger Condition                                    |
-| :---------------------------- | :--------------------------------------------------- |
-| `node:click` / `node:hover`   | Interacting with a node                              |
-| `edge:click` / `edge:hover`   | Interacting with an edge                             |
-| `combo:click` / `combo:hover` | Interacting with a group hull or representative node |
-| `graph:click`                 | Clicking empty space on the canvas                   |
-| `graph:pan` / `graph:zoom`    | Moving the camera viewport                           |
-| `boxstart` / `boxend`         | Triggering or ending marquee selection               |
+### 2. Zoom Controls
+```typescript
+engine.zoomIn();
+engine.zoomOut();
+
+// Precise focal zoom (screen coordinates)
+engine.zoomAt(mouseX, mouseY, delta);
+```
+
+---
+
+## 🧬 Layouts & Batch Updates
+
+VortxGL provides built-in geometric layouts and supports seamless integration with external layout engines (like Cytoscape.js or d3-force).
+
+### 1. Built-in Geometric Layouts
+Trigger fast, animated layouts directly from the engine instance.
+
+```typescript
+// Arrange all nodes in a circle
+engine.runLayout('circle');
+
+// Arrange nodes in a grid
+engine.runLayout('grid');
+
+// Random scatter
+engine.runLayout('random');
+```
+
+### 2. Layouts on Selection
+You can restrict any built-in layout to only affect currently selected elements, keeping the rest of the graph anchored.
+
+```typescript
+engine.runLayout('circle', { selectedOnly: true });
+```
+
+### 3. External Layouts (e.g. Cytoscape)
+For complex force-directed or hierarchical layouts, calculate positions externally and sync them:
+
+#### Batch Sync (Most Efficient)
+Use `setData` for an O(1) buffer swap when a layout finishes.
+
+```typescript
+engine.setData(newPositions, newColors, newIds, metadata, edgeIndices);
+```
+
+#### Incremental Sync (Real-time Animation)
+For live layout animations, use `updateNode` in your layout's tick function.
+
+```typescript
+nodes.forEach(n => {
+  engine.updateNode({ id: n.id, position: { x: n.x, y: n.y } });
+});
+```
 
 ---
 
 ## 📜 License
 
-VortxGL is distributed under the Apache License 2.0. See the [LICENSE](LICENSE) file for complete details.
+This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.