apexify.js 4.9.28 → 5.0.0

package/README.md

@@ -1,456 +1,727 @@
-# 🎨 ApexPainter - Advanced Canvas Rendering Library
-
-<div align="center">
-
-![ApexPainter Banner](apex-banner.png)
-
-**The Ultimate TypeScript Canvas Library for Node.js**
-
-[![npm version](https://badge.fury.io/js/apexify.svg)](https://badge.fury.io/js/apexify)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-16%2B-green.svg)](https://nodejs.org/)
-[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-
-*Create stunning visuals with professional-grade canvas rendering, image processing, and text effects*
-
-</div>
-
-## ✨ Features Overview
-
-### 🖼️ **Advanced Image Processing**
-- **Professional Filters**: 22+ filters including blur, sharpen, vintage, cinematic effects
-- **Shape Drawing**: 8+ shapes (rectangle, circle, heart, star, polygon, etc.)
-- **Gradient Support**: Linear and radial gradients for fills and strokes
-- **Shadow & Stroke Effects**: Customizable shadows and strokes for all shapes
-- **Rotation & Positioning**: Full control over image placement and rotation
-
-### 🎨 **Rich Background System**
-- **Multiple Background Types**: Solid colors, gradients, custom images
-- **Pattern Overlays**: 12+ built-in patterns (grid, dots, stripes, hexagons, etc.)
-- **Custom Patterns**: Use your own images as repeating patterns
-- **Blend Modes**: 11+ blend modes for professional compositing
-- **Noise Effects**: Add texture with customizable noise intensity
-
-### 📝 **Enhanced Text Rendering**
-- **Font Management**: Custom fonts, sizes, families, and styles
-- **Text Decorations**: Bold, italic, underline, overline, strikethrough, highlight
-- **Advanced Effects**: Glow, shadow, stroke with gradient support
-- **Spacing Control**: Letter spacing, word spacing, line height
-- **Text Wrapping**: Automatic text wrapping with size constraints
-- **Rotation**: Full 360° text rotation support
-
-### 🔧 **Professional Tools**
-- **Chart Generation**: Bar charts, pie charts, line charts
-- **GIF Creation**: Animated GIFs from image sequences
-- **Format Conversion**: Convert between PNG, JPEG, WebP, and more
-- **Image Manipulation**: Crop, resize, background removal
-- **Color Detection**: Extract and analyze colors from images
-
----
-
-## 🚀 Quick Start
-
-### Installation
-
-```bash
-npm install apexify
-```
-
-### Basic Usage
-
-```typescript
-import { ApexPainter } from 'apexify';
-
-const painter = new ApexPainter();
-
-// Create a canvas with gradient background
-const canvas = await painter.createCanvas({
-  width: 800,
-  height: 600,
-  gradientBg: {
-    type: 'linear',
-    colors: [
-      { color: '#FF6B6B', position: 0 },
-      { color: '#4ECDC4', position: 0.5 },
-      { color: '#45B7D1', position: 1 }
-    ],
-    direction: { x1: 0, y1: 0, x2: 800, y2: 600 }
-  },
-  shadow: {
-    color: '#000',
-    offsetX: 10,
-    offsetY: 10,
-    blur: 20
-  },
-  borderRadius: 20
-});
-
-// Add a beautiful heart shape (single object)
-const heartImage = await painter.createImage({
-  source: 'heart',
-  x: 300,
-  y: 200,
-  width: 200,
-  height: 200,
-  shape: {
-    fill: true,
-    gradient: {
-      type: 'radial',
-      colors: [
-        { color: '#FF6B6B', position: 0 },
-        { color: '#FF1744', position: 1 }
-      ],
-      center: { x: 100, y: 100 },
-      radius: 100
-    }
-  },
-  shadow: {
-    color: '#000',
-    offsetX: 15,
-    offsetY: 15,
-    blur: 25
-  },
-  stroke: {
-    color: '#FFF',
-    width: 5
-  }
-}, canvas.buffer);
-
-// Add stunning text (single object)
-const textImage = await painter.createText({
-  text: 'ApexPainter',
-  x: 400,
-  y: 450,
-  fontSize: 48,
-  fontFamily: 'Arial',
-  bold: true,
-  gradient: {
-    type: 'linear',
-    colors: [
-      { color: '#FFD700', position: 0 },
-      { color: '#FF6B6B', position: 1 }
-    ],
-    direction: { x1: 0, y1: 0, x2: 300, y2: 0 }
-  },
-  glow: {
-    color: '#FFD700',
-    intensity: 0.8,
-    opacity: 0.9
-  },
-  shadow: {
-    color: '#000',
-    offsetX: 8,
-    offsetY: 8,
-    blur: 15
-  },
-  stroke: {
-    color: '#FFF',
-    width: 3
-  }
-}, heartImage);
-
-// Save the result
-fs.writeFileSync('beautiful-artwork.png', textImage);
-```
-
-### 📝 **Flexible Array Support**
-
-Both `createImage()` and `createText()` methods accept **single objects** OR **arrays of objects**:
-
-```typescript
-// ✅ Single Object
-await painter.createImage({
-  source: 'heart',
-  x: 100, y: 100,
-  width: 200, height: 200,
-  shape: { fill: true, color: '#ff6b6b' }
-}, canvasBuffer);
-
-// ✅ Array of Objects
-await painter.createImage([
-  {
-    source: 'rectangle',
-    x: 50, y: 50,
-    width: 100, height: 80,
-    shape: { fill: true, color: '#ff6b6b' }
-  },
-  {
-    source: 'circle',
-    x: 200, y: 50,
-    width: 80, height: 80,
-    shape: { fill: true, color: '#4ecdc4' }
-  },
-  {
-    source: 'star',
-    x: 350, y: 50,
-    width: 80, height: 80,
-    shape: { fill: true, color: '#45b7d1' }
-  }
-], canvasBuffer);
-
-// ✅ Single Text Object
-await painter.createText({
-  text: 'Hello World',
-  x: 100, y: 100,
-  fontSize: 24,
-  color: '#ff6b6b'
-}, canvasBuffer);
-
-// ✅ Array of Text Objects
-await painter.createText([
-  {
-    text: 'Title',
-    x: 100, y: 50,
-    fontSize: 32,
-    bold: true,
-    color: '#2c3e50'
-  },
-  {
-    text: 'Subtitle',
-    x: 100, y: 100,
-    fontSize: 18,
-    color: '#666'
-  },
-  {
-    text: 'Body text with effects',
-    x: 100, y: 150,
-    fontSize: 14,
-    color: '#333',
-    glow: { color: '#ffd700', intensity: 0.5 },
-    shadow: { color: '#000', offsetX: 2, offsetY: 2, blur: 4 }
-  }
-], canvasBuffer);
-```
-
----
-
-## 🎯 Real-World Examples
-
-### 🏢 **Business Cards & Marketing Materials**
-
-```typescript
-// Create a professional business card
-const businessCard = await painter.createCanvas({
-  width: 400,
-  height: 250,
-  gradientBg: {
-    type: 'linear',
-    colors: [
-      { color: '#2C3E50', position: 0 },
-      { color: '#34495E', position: 1 }
-    ],
-    direction: { x1: 0, y1: 0, x2: 400, y2: 250 }
-  },
-  patternBg: {
-    type: 'dots',
-    color: '#FFF',
-    opacity: 0.1,
-    size: 5,
-    spacing: 20
-  }
-});
-
-// Add company logo (star shape)
-const logo = await painter.createImage({
-  source: 'star',
-  x: 50,
-  y: 50,
-  width: 60,
-  height: 60,
-  fill: true,
-  color: '#FFD700',
-  shadow: { color: '#000', offsetX: 3, offsetY: 3, blur: 8 }
-}, businessCard.buffer);
-
-// Add company name
-const companyText = await painter.createText({
-  text: 'ACME Corp',
-  x: 130,
-  y: 80,
-  fontSize: 24,
-  fontFamily: 'Arial',
-  bold: true,
-  color: '#FFF',
-  shadow: { color: '#000', offsetX: 2, offsetY: 2, blur: 4 }
-}, logo);
-
-// Add contact info
-const contactText = await painter.createText({
-  text: 'john@acme.com\n+1 (555) 123-4567',
-  x: 50,
-  y: 150,
-  fontSize: 14,
-  fontFamily: 'Arial',
-  color: '#BDC3C7',
-  lineHeight: 1.5
-}, companyText);
-```
-
-### 🎮 **Game UI Elements**
-
-```typescript
-// Create a game button
-const gameButton = await painter.createCanvas({
-  width: 200,
-  height: 60,
-  gradientBg: {
-    type: 'linear',
-    colors: [
-      { color: '#FF6B6B', position: 0 },
-      { color: '#FF1744', position: 1 }
-    ],
-    direction: { x1: 0, y1: 0, x2: 200, y2: 60 }
-  },
-  shadow: {
-    color: '#000',
-    offsetX: 5,
-    offsetY: 5,
-    blur: 15
-  },
-  borderRadius: 30
-});
-
-// Add button text with glow effect
-const buttonText = await painter.createText({
-  text: 'PLAY NOW',
-  x: 100,
-  y: 35,
-  fontSize: 20,
-  fontFamily: 'Arial',
-  bold: true,
-  color: '#FFF',
-  textAlign: 'center',
-  textBaseline: 'middle',
-  glow: {
-    color: '#FFD700',
-    intensity: 0.6,
-    opacity: 0.8
-  },
-  shadow: {
-    color: '#000',
-    offsetX: 2,
-    offsetY: 2,
-    blur: 4
-  }
-}, gameButton.buffer);
-```
-
----
-
-## 📚 API Reference
-
-### Core Methods
-
-| Method | Description | Parameters |
-|--------|-------------|------------|
-| `createCanvas()` | Create a new canvas with background | `CanvasConfig` |
-| `createImage()` | Add shapes/images to canvas | `ImageProperties \| ImageProperties[]` |
-| `createText()` | Add text to canvas | `TextProperties \| TextProperties[]` |
-| `createChart()` | Generate charts | `ChartConfig` |
-| `createGIF()` | Create animated GIFs | `GIFConfig` |
-
-### 🔄 **Flexible Parameters**
-
-Both `createImage()` and `createText()` methods accept:
-- **Single Object**: `ImageProperties` or `TextProperties`
-- **Array of Objects**: `ImageProperties[]` or `TextProperties[]`
-
-This allows you to add multiple elements in one call for better performance and cleaner code.
-
-### Shape Types
-
-- `rectangle` - Standard rectangle
-- `square` - Perfect square
-- `circle` - Perfect circle
-- `triangle` - Equilateral triangle
-- `trapezium` - Trapezoid shape
-- `star` - 5-pointed star
-- `heart` - Heart shape with bezier curves
-- `polygon` - Custom polygon
-
-### Pattern Types
-
-- `grid` - Grid pattern
-- `dots` - Dot pattern
-- `diagonal` - Diagonal lines
-- `stripes` - Horizontal/vertical stripes
-- `waves` - Wave pattern
-- `crosses` - Cross pattern
-- `hexagons` - Hexagonal pattern
-- `checkerboard` - Checkerboard pattern
-- `diamonds` - Diamond pattern
-- `triangles` - Triangle pattern
-- `stars` - Star pattern
-- `polka` - Polka dot pattern
-- `custom` - Custom image pattern
-
----
-
-## 🤝 Contributing
-
-We welcome contributions! Here's how you can help:
-
-1. **Report Bugs**: Found a bug? Open an issue with detailed information
-2. **Feature Requests**: Have an idea? We'd love to hear it!
-3. **Code Contributions**: Submit pull requests for improvements
-4. **Documentation**: Help improve our docs and examples
-
-### Development Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/your-username/apexify.git
-
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-
-# Build the project
-npm run build
-```
-
----
-
-## 📞 Support & Community
-
-<div align="center">
-
-### Join Our Discord Community
-
-[![Jedi Studio](https://img.shields.io/badge/Discord-Jedi%20Studio-7289DA?style=for-the-badge&logo=discord)](https://discord.gg/CS2NRSPyze)
-[![FresedGPT](https://img.shields.io/badge/Discord-FresedGPT-7289DA?style=for-the-badge&logo=discord)](https://discord.gg/94qUZWhwFE)
-[![ElectronHub](https://img.shields.io/badge/Discord-ElectronHub-7289DA?style=for-the-badge&logo=discord)](https://discord.gg/83XcjD8vgW)
-
-### Documentation & Resources
-
-[![Documentation](https://img.shields.io/badge/Docs-Apexify.js-blue?style=for-the-badge)](http://apexifyjs.jedi-studio.com)
-[![Support Server](https://img.shields.io/badge/Support-Discord-7289DA?style=for-the-badge&logo=discord)](https://discord.gg/mDyXV9hzXw)
-
-</div>
-
----
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
----
-
-## 🙏 Acknowledgments
-
-- **@napi-rs/canvas** - High-performance canvas rendering
-- **Sharp** - Professional image processing
-- **Jimp** - JavaScript image manipulation
-- **TypeScript** - Type-safe development
-
----
-
-<div align="center">
-
-**Made with ❤️ by [Jedi Studio](https://discord.gg/CS2NRSPyze)**
-
-*Create stunning visuals with ApexPainter - The ultimate canvas library for Node.js*
-
-</div>
+# 🎨 ApexPainter - Advanced Canvas Rendering Library
+
+<div align="center">
+
+![ApexPainter Banner](./apex-banner.png)
+
+**The Ultimate TypeScript Canvas Library for Node.js**
+
+[![npm version](https://badge.fury.io/js/apexify.svg)](https://badge.fury.io/js/apexify)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-16%2B-green.svg)](https://nodejs.org/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+*Create stunning visuals with professional-grade canvas rendering, image processing, and text effects*
+
+</div>
+
+## ✨ Features Overview
+
+### 🖼️ **Advanced Image Processing**
+- **Professional Filters**: 22+ filters including blur, sharpen, vintage, cinematic effects
+- **Image Masking**: Apply masks with alpha, luminance, or inverse modes
+- **Image Distortion**: Perspective, bulge, pinch, and mesh warping effects
+- **Effects Stack**: Vignette, lens flare, chromatic aberration, film grain
+- **Shape Drawing**: 8+ shapes (rectangle, circle, heart, star, polygon, etc.)
+- **Gradient Support**: Linear and radial gradients for fills and strokes
+- **Shadow & Stroke Effects**: Customizable shadows and strokes for all shapes
+- **Rotation & Positioning**: Full control over image placement and rotation
+- **Image Stitching**: Combine multiple images into panoramas or grids
+- **Collage Maker**: Create beautiful collages with multiple layout options
+- **Image Compression**: Optimize images with quality control (JPEG, WebP, AVIF)
+- **Color Palette Extraction**: Extract color palettes using multiple algorithms
+
+### 🎨 **Rich Background System**
+- **Multiple Background Types**: Solid colors, gradients, custom images
+- **Video Backgrounds**: Extract frames from videos for dynamic backgrounds
+- **Background Filters**: Apply filters directly to background images
+- **Pattern Overlays**: 12+ built-in patterns (grid, dots, stripes, hexagons, etc.)
+- **Custom Patterns**: Use your own images as repeating patterns
+- **Blend Modes**: 11+ blend modes for professional compositing
+- **Noise Effects**: Add texture with customizable noise intensity
+
+### 📝 **Enhanced Text Rendering**
+- **Font Management**: Custom fonts, sizes, families, and styles
+- **Text on Paths**: Render text along curves (line, arc, bezier, quadratic)
+- **Text Decorations**: Bold, italic, underline, overline, strikethrough, highlight
+- **Advanced Effects**: Glow, shadow, stroke with gradient support
+- **Spacing Control**: Letter spacing, word spacing, line height
+- **Text Wrapping**: Automatic text wrapping with size constraints
+- **Rotation**: Full 360° text rotation support
+
+### 🎯 **Advanced Custom Lines**
+- **Smooth Paths**: Bezier, Catmull-Rom, and smooth interpolation
+- **Arrow Markers**: Customizable start/end arrows with multiple styles
+- **Path Markers**: Add markers at any position along paths
+- **Line Patterns**: Dots, dashes, and custom pattern segments
+- **Line Textures**: Apply texture images to lines
+
+### 🔧 **Professional Tools**
+- **Chart Generation**: Bar charts, pie charts, line charts
+- **GIF Creation**: Animated GIFs from image sequences
+- **Format Conversion**: Convert between PNG, JPEG, WebP, AVIF, and more
+- **Image Manipulation**: Crop, resize, background removal
+- **Color Detection**: Extract and analyze colors from images
+- **Batch Operations**: Process multiple operations in parallel
+- **Chain Operations**: Chain operations sequentially for complex workflows
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install apexify
+```
+
+### Basic Usage
+
+```typescript
+import { ApexPainter } from 'apexify';
+
+const painter = new ApexPainter();
+
+// Create a canvas with gradient background
+const canvas = await painter.createCanvas({
+  width: 800,
+  height: 600,
+  gradientBg: {
+    type: 'linear',
+    colors: [
+      { color: '#FF6B6B', position: 0 },
+      { color: '#4ECDC4', position: 0.5 },
+      { color: '#45B7D1', position: 1 }
+    ],
+    direction: { x1: 0, y1: 0, x2: 800, y2: 600 }
+  },
+  shadow: {
+    color: '#000',
+    offsetX: 10,
+    offsetY: 10,
+    blur: 20
+  },
+  borderRadius: 20
+});
+
+// Add a beautiful heart shape (single object)
+const heartImage = await painter.createImage({
+  source: 'heart',
+  x: 300,
+  y: 200,
+  width: 200,
+  height: 200,
+  shape: {
+    fill: true,
+    gradient: {
+      type: 'radial',
+      colors: [
+        { color: '#FF6B6B', position: 0 },
+        { color: '#FF1744', position: 1 }
+      ],
+      center: { x: 100, y: 100 },
+      radius: 100
+    }
+  },
+  shadow: {
+    color: '#000',
+    offsetX: 15,
+    offsetY: 15,
+    blur: 25
+  },
+  stroke: {
+    color: '#FFF',
+    width: 5
+  }
+}, canvas.buffer);
+
+// Add stunning text (single object)
+const textImage = await painter.createText({
+  text: 'ApexPainter',
+  x: 400,
+  y: 450,
+  fontSize: 48,
+  fontFamily: 'Arial',
+  bold: true,
+  gradient: {
+    type: 'linear',
+    colors: [
+      { color: '#FFD700', position: 0 },
+      { color: '#FF6B6B', position: 1 }
+    ],
+    direction: { x1: 0, y1: 0, x2: 300, y2: 0 }
+  },
+  glow: {
+    color: '#FFD700',
+    intensity: 0.8,
+    opacity: 0.9
+  },
+  shadow: {
+    color: '#000',
+    offsetX: 8,
+    offsetY: 8,
+    blur: 15
+  },
+  stroke: {
+    color: '#FFF',
+    width: 3
+  }
+}, heartImage);
+
+// Save the result
+fs.writeFileSync('beautiful-artwork.png', textImage);
+```
+
+### 📝 **Flexible Array Support**
+
+Both `createImage()` and `createText()` methods accept **single objects** OR **arrays of objects**:
+
+```typescript
+// ✅ Single Object
+await painter.createImage({
+  source: 'heart',
+  x: 100, y: 100,
+  width: 200, height: 200,
+  shape: { fill: true, color: '#ff6b6b' }
+}, canvasBuffer);
+
+// ✅ Array of Objects
+await painter.createImage([
+  {
+    source: 'rectangle',
+    x: 50, y: 50,
+    width: 100, height: 80,
+    shape: { fill: true, color: '#ff6b6b' }
+  },
+  {
+    source: 'circle',
+    x: 200, y: 50,
+    width: 80, height: 80,
+    shape: { fill: true, color: '#4ecdc4' }
+  },
+  {
+    source: 'star',
+    x: 350, y: 50,
+    width: 80, height: 80,
+    shape: { fill: true, color: '#45b7d1' }
+  }
+], canvasBuffer);
+
+// ✅ Single Text Object
+await painter.createText({
+  text: 'Hello World',
+  x: 100, y: 100,
+  fontSize: 24,
+  color: '#ff6b6b'
+}, canvasBuffer);
+
+// ✅ Array of Text Objects
+await painter.createText([
+  {
+    text: 'Title',
+    x: 100, y: 50,
+    fontSize: 32,
+    bold: true,
+    color: '#2c3e50'
+  },
+  {
+    text: 'Subtitle',
+    x: 100, y: 100,
+    fontSize: 18,
+    color: '#666'
+  },
+  {
+    text: 'Body text with effects',
+    x: 100, y: 150,
+    fontSize: 14,
+    color: '#333',
+    glow: { color: '#ffd700', intensity: 0.5 },
+    shadow: { color: '#000', offsetX: 2, offsetY: 2, blur: 4 }
+  }
+], canvasBuffer);
+```
+
+### 🎨 **Advanced Stroke Styles**
+
+All stroke properties now support **6 different stroke styles**:
+
+```typescript
+// ✅ Basic Stroke Styles
+await painter.createImage({
+  source: 'rectangle',
+  x: 100, y: 100,
+  width: 200, height: 150,
+  shape: { fill: true, color: '#ffffff' },
+  stroke: {
+    color: '#ff6b6b',
+    width: 8,
+    style: 'dashed'  // solid, dashed, dotted, groove, ridge, double
+  }
+}, canvasBuffer);
+
+// ✅ Gradient Strokes with Styles
+await painter.createImage({
+  source: 'circle',
+  x: 200, y: 200,
+  width: 150, height: 150,
+  shape: { fill: true, color: '#ffffff' },
+  stroke: {
+    gradient: {
+      type: 'linear',
+      colors: [
+        { stop: 0, color: '#ff6b6b' },
+        { stop: 1, color: '#4ecdc4' }
+      ]
+    },
+    width: 6,
+    style: 'ridge'  // Works with all styles!
+  }
+}, canvasBuffer);
+
+// ✅ Text Strokes with Styles
+await painter.createText({
+  text: 'Styled Text',
+  x: 100, y: 100,
+  fontSize: 32,
+  color: '#ffffff',
+  stroke: {
+    color: '#ff6b6b',
+    width: 4,
+    style: 'double'  // All 6 styles supported!
+  }
+}, canvasBuffer);
+```
+
+**Available Stroke Styles:**
+- `solid` - Clean solid line (default)
+- `dashed` - Dashed line pattern
+- `dotted` - Dotted line pattern  
+- `groove` - 3D grooved effect (dark outer, light inner)
+- `ridge` - 3D ridged effect (light outer, dark inner)
+- `double` - Double parallel lines
+
+### 🔤 **Organized Font Management**
+
+Text fonts are now organized in a clean `font` object structure:
+
+```typescript
+// ✅ New Font Object Structure
+await painter.createText({
+  text: 'Organized Font',
+  x: 100, y: 100,
+  font: {
+    size: 24,           // Font size in pixels
+    family: 'Arial',    // Font family name
+    name: 'customFont', // Custom font name (for registration)
+    path: './fonts/custom.ttf' // Path to custom font file
+  },
+  color: '#333333',
+  bold: true,
+  italic: true
+}, canvasBuffer);
+
+// ✅ Backward Compatibility (Legacy Properties)
+await painter.createText({
+  text: 'Legacy Font Properties',
+  x: 100, y: 150,
+  fontSize: 24,         // Still works!
+  fontFamily: 'Arial',  // Still works!
+  fontName: 'customFont', // Still works!
+  fontPath: './fonts/custom.ttf', // Still works!
+  color: '#333333'
+}, canvasBuffer);
+
+// ✅ Mixed Usage (New Object Takes Priority)
+await painter.createText({
+  text: 'Mixed Usage',
+  x: 100, y: 200,
+  font: {
+    size: 28,
+    family: 'Georgia'
+  },
+  fontSize: 24,        // Ignored (font.size takes priority)
+  fontFamily: 'Arial', // Ignored (font.family takes priority)
+  color: '#333333'
+}, canvasBuffer);
+```
+
+**Font Object Properties:**
+- `size` - Font size in pixels (replaces `fontSize`)
+- `family` - Font family name (replaces `fontFamily`)
+- `name` - Custom font name for registration (replaces `fontName`)
+- `path` - Path to custom font file (replaces `fontPath`)
+
+**Benefits:**
+- **Cleaner Structure**: All font properties in one organized object
+- **Better IntelliSense**: IDE autocomplete for font properties
+- **Backward Compatible**: Legacy properties still work
+- **Priority System**: New `font` object overrides legacy properties
+
+### 🌈 **Advanced Text Gradient Features**
+
+Text effects now support **gradients** for enhanced visual appeal:
+
+```typescript
+// ✅ Gradient Glow
+await painter.createText({
+  text: 'Gradient Glow Text',
+  x: 100, y: 100,
+  fontSize: 32,
+  color: '#ffffff',
+  glow: {
+    gradient: {
+      type: 'linear',
+      colors: [
+        { stop: 0, color: '#ff6b6b' },
+        { stop: 1, color: '#4ecdc4' }
+      ]
+    },
+    intensity: 15,
+    opacity: 0.9
+  }
+}, canvasBuffer);
+
+// ✅ Gradient Highlight
+await painter.createText({
+  text: 'Gradient Highlight',
+  x: 100, y: 150,
+  fontSize: 24,
+  color: '#000000',
+  highlight: {
+    gradient: {
+      type: 'radial',
+      colors: [
+        { stop: 0, color: '#ffd700' },
+        { stop: 1, color: '#ff6b6b' }
+      ]
+    },
+    opacity: 0.6
+  }
+}, canvasBuffer);
+
+// ✅ Gradient Text Decorations
+await painter.createText({
+  text: 'Styled Decorations',
+  x: 100, y: 200,
+  fontSize: 28,
+  color: '#ffffff',
+  underline: {
+    gradient: {
+      type: 'linear',
+      colors: [
+        { stop: 0, color: '#ff6b6b' },
+        { stop: 1, color: '#4ecdc4' }
+      ]
+    },
+    width: 4
+  },
+  overline: {
+    gradient: {
+      type: 'linear',
+      colors: [
+        { stop: 0, color: '#feca57' },
+        { stop: 1, color: '#ff9ff3' }
+      ]
+    },
+    width: 3
+  },
+  strikethrough: {
+    gradient: {
+      type: 'linear',
+      colors: [
+        { stop: 0, color: '#96ceb4' },
+        { stop: 1, color: '#45b7d1' }
+      ]
+    },
+    width: 5
+  }
+}, canvasBuffer);
+
+// ✅ Backward Compatibility (Simple Boolean)
+await painter.createText({
+  text: 'Simple Decorations',
+  x: 100, y: 250,
+  fontSize: 24,
+  color: '#ffffff',
+  underline: true,        // Uses default color
+  overline: true,         // Uses default color  
+  strikethrough: true     // Uses default color
+}, canvasBuffer);
+```
+
+**Gradient Support:**
+- **Glow**: Gradient glow effects with intensity and opacity
+- **Highlight**: Gradient background highlights
+- **Underline**: Custom gradient underlines with width control
+- **Overline**: Custom gradient overlines with width control  
+- **Strikethrough**: Custom gradient strikethrough with width control
+- **Backward Compatible**: Simple `boolean` values still work
+
+---
+
+## 🎯 Real-World Examples
+
+### 🏢 **Business Cards & Marketing Materials**
+
+```typescript
+// Create a professional business card
+const businessCard = await painter.createCanvas({
+  width: 400,
+  height: 250,
+  gradientBg: {
+    type: 'linear',
+    colors: [
+      { color: '#2C3E50', position: 0 },
+      { color: '#34495E', position: 1 }
+    ],
+    direction: { x1: 0, y1: 0, x2: 400, y2: 250 }
+  },
+  patternBg: {
+    type: 'dots',
+    color: '#FFF',
+    opacity: 0.1,
+    size: 5,
+    spacing: 20
+  }
+});
+
+// Add company logo (star shape)
+const logo = await painter.createImage({
+  source: 'star',
+  x: 50,
+  y: 50,
+  width: 60,
+  height: 60,
+  fill: true,
+  color: '#FFD700',
+  shadow: { color: '#000', offsetX: 3, offsetY: 3, blur: 8 }
+}, businessCard.buffer);
+
+// Add company name
+const companyText = await painter.createText({
+  text: 'ACME Corp',
+  x: 130,
+  y: 80,
+  fontSize: 24,
+  fontFamily: 'Arial',
+  bold: true,
+  color: '#FFF',
+  shadow: { color: '#000', offsetX: 2, offsetY: 2, blur: 4 }
+}, logo);
+
+// Add contact info
+const contactText = await painter.createText({
+  text: 'john@acme.com\n+1 (555) 123-4567',
+  x: 50,
+  y: 150,
+  fontSize: 14,
+  fontFamily: 'Arial',
+  color: '#BDC3C7',
+  lineHeight: 1.5
+}, companyText);
+```
+
+### 🎮 **Game UI Elements**
+
+```typescript
+// Create a game button
+const gameButton = await painter.createCanvas({
+  width: 200,
+  height: 60,
+  gradientBg: {
+    type: 'linear',
+    colors: [
+      { color: '#FF6B6B', position: 0 },
+      { color: '#FF1744', position: 1 }
+    ],
+    direction: { x1: 0, y1: 0, x2: 200, y2: 60 }
+  },
+  shadow: {
+    color: '#000',
+    offsetX: 5,
+    offsetY: 5,
+    blur: 15
+  },
+  borderRadius: 30
+});
+
+// Add button text with glow effect
+const buttonText = await painter.createText({
+  text: 'PLAY NOW',
+  x: 100,
+  y: 35,
+  fontSize: 20,
+  fontFamily: 'Arial',
+  bold: true,
+  color: '#FFF',
+  textAlign: 'center',
+  textBaseline: 'middle',
+  glow: {
+    color: '#FFD700',
+    intensity: 0.6,
+    opacity: 0.8
+  },
+  shadow: {
+    color: '#000',
+    offsetX: 2,
+    offsetY: 2,
+    blur: 4
+  }
+}, gameButton.buffer);
+```
+
+---
+
+## 📚 API Reference
+
+### Core Methods
+
+| Method | Description | Parameters |
+|--------|-------------|------------|
+| `createCanvas()` | Create a new canvas with background | `CanvasConfig` |
+| `createImage()` | Add shapes/images to canvas | `ImageProperties \| ImageProperties[]` |
+| `createText()` | Add text to canvas | `TextProperties \| TextProperties[]` |
+| `createChart()` | Generate charts | `ChartConfig` |
+| `createGIF()` | Create animated GIFs | `GIFConfig` |
+
+### 🔄 **Flexible Parameters**
+
+Both `createImage()` and `createText()` methods accept:
+- **Single Object**: `ImageProperties` or `TextProperties`
+- **Array of Objects**: `ImageProperties[]` or `TextProperties[]`
+
+This allows you to add multiple elements in one call for better performance and cleaner code.
+
+### Shape Types
+
+- `rectangle` - Standard rectangle
+- `square` - Perfect square
+- `circle` - Perfect circle
+- `triangle` - Equilateral triangle
+- `trapezium` - Trapezoid shape
+- `star` - 5-pointed star
+- `heart` - Heart shape with bezier curves
+- `polygon` - Custom polygon
+
+### Pattern Types
+
+- `grid` - Grid pattern
+- `dots` - Dot pattern
+- `diagonal` - Diagonal lines
+- `stripes` - Horizontal/vertical stripes
+- `waves` - Wave pattern
+- `crosses` - Cross pattern
+- `hexagons` - Hexagonal pattern
+- `checkerboard` - Checkerboard pattern
+- `diamonds` - Diamond pattern
+- `triangles` - Triangle pattern
+- `stars` - Star pattern
+- `polka` - Polka dot pattern
+- `custom` - Custom image pattern
+
+---
+
+## 🆕 What's New in v4.9.30
+
+### 🎉 Major Feature Release
+
+#### Background Enhancements
+- ✨ **Video Backgrounds**: Use video frames as dynamic backgrounds
+- 🎨 **Background Filters**: Apply filters directly to background images
+- 🔧 **Background Opacity**: Control transparency of background images
+
+#### Image Processing
+- 🎭 **Image Masking**: Apply masks with multiple modes (alpha, luminance, inverse)
+- 🔄 **Image Distortion**: Perspective, bulge, pinch, and mesh warping
+- ✨ **Effects Stack**: Vignette, lens flare, chromatic aberration, film grain
+- 🎛️ **Enhanced Filters**: Filter intensity and order control
+
+#### Text Features
+- 📐 **Text on Paths**: Render text along curves and custom paths
+
+#### Custom Lines
+- ➡️ **Arrow Markers**: Start/end arrows with customizable styles
+- 📍 **Path Markers**: Add markers at any position along paths
+- 🎨 **Line Patterns**: Dots, dashes, and custom patterns
+- 🖼️ **Line Textures**: Apply texture images to lines
+
+#### New Utilities
+- ⚡ **Batch Operations**: Process multiple operations in parallel
+- 🔗 **Chain Operations**: Chain operations sequentially
+- 🖼️ **Image Stitching**: Combine images into panoramas
+- 🎨 **Collage Maker**: Create beautiful image collages
+- 📦 **Image Compression**: Optimize images with quality control
+- 🎨 **Color Palette Extraction**: Extract color palettes from images
+
+See [CHANGELOG.md](CHANGELOG.md) for complete details.
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Here's how you can help:
+
+1. **Report Bugs**: Found a bug? Open an issue with detailed information
+2. **Feature Requests**: Have an idea? We'd love to hear it!
+3. **Code Contributions**: Submit pull requests for improvements
+4. **Documentation**: Help improve our docs and examples
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/apexify.git
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build the project
+npm run build
+```
+
+---
+
+## 📞 Support & Community
+
+<div align="center">
+
+### Join Our Discord Community
+
+[![Jedi Studio](https://img.shields.io/badge/Discord-Jedi%20Studio-7289DA?style=for-the-badge&logo=discord)](https://discord.gg/CS2NRSPyze)
+[![FresedGPT](https://img.shields.io/badge/Discord-FresedGPT-7289DA?style=for-the-badge&logo=discord)](https://discord.gg/94qUZWhwFE)
+[![ElectronHub](https://img.shields.io/badge/Discord-ElectronHub-7289DA?style=for-the-badge&logo=discord)](https://discord.gg/83XcjD8vgW)
+
+### Documentation & Resources
+
+[![Documentation](https://img.shields.io/badge/Docs-Apexify.js-blue?style=for-the-badge)](http://apexifyjs.jedi-studio.com)
+[![Support Server](https://img.shields.io/badge/Support-Discord-7289DA?style=for-the-badge&logo=discord)](https://discord.gg/mDyXV9hzXw)
+
+</div>
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+- **@napi-rs/canvas** - High-performance canvas rendering
+- **Sharp** - Professional image processing
+- **Jimp** - JavaScript image manipulation
+- **TypeScript** - Type-safe development
+
+---
+
+<div align="center">
+
+**Made with ❤️ by [Jedi Studio](https://discord.gg/CS2NRSPyze)**
+
+*Create stunning visuals with ApexPainter - The ultimate canvas library for Node.js*
+
+</div>