apexify.js 4.9.30 → 5.0.1

package/lib/Canvas/ApexPainter.ts

@@ -5,16 +5,26 @@ import { PassThrough} from "stream";
 import axios from 'axios';
 import fs, { PathLike } from "fs";
 import path from "path";
-import { OutputFormat, CanvasConfig, TextObject, TextProperties, ImageProperties, GIFOptions, GIFResults, CustomOptions, cropOptions,
-     drawBackgroundGradient, drawBackgroundColor, customBackground, customLines,
-      drawText, converter, resizingImg, applyColorFilters, imgEffects,verticalBarChart, pieChart,
-     lineChart, cropInner, cropOuter, bgRemoval, detectColors, removeColor, dataURL, base64, arrayBuffer, blob, url, GradientConfig, Frame,
-     PatternOptions, ExtractFramesOptions, buildPath, ResizeOptions, MaskOptions, BlendOptions,
+import { OutputFormat, CanvasConfig, TextProperties, ImageProperties, GIFOptions, GIFResults, CustomOptions, cropOptions,
+    drawBackgroundGradient, drawBackgroundColor, customBackground, customLines,
+    converter, resizingImg, applyColorFilters, imgEffects,verticalBarChart, pieChart,
+    lineChart, cropInner, cropOuter, bgRemoval, detectColors, removeColor, dataURL, 
+    base64, arrayBuffer, blob, url, GradientConfig, Frame,
+    ExtractFramesOptions, buildPath, ResizeOptions, MaskOptions, BlendOptions,
     applyCanvasZoom, applyNoise,
     applyStroke, applyRotation, applyShadow, drawBoxBackground, fitInto, loadImageCached,
-    drawShape, isShapeSource, ShapeType, createShapePath, createGradientFill, applyImageFilters, applySimpleProfessionalFilters
+    drawShape, isShapeSource, ShapeType, createShapePath, createGradientFill, applySimpleProfessionalFilters,
+    ImageFilter, barChart_1, PieChartData, LineChartConfig,
+    // New features
+    applyImageMask, applyClipPath, applyPerspectiveDistortion, applyBulgeDistortion, applyMeshWarp,
+    applyVignette, applyLensFlare, applyChromaticAberration, applyFilmGrain,
+    renderTextOnPath,
+    batchOperations, chainOperations,
+    stitchImages as stitchImagesUtil, createCollage,
+    compressImage, extractPalette as extractPaletteUtil,
+    BatchOperation, ChainOperation, StitchOptions, CollageLayout, CompressionOptions, PaletteOptions,
+    SaveOptions, SaveResult
     } from "./utils/utils";
-import { } from "./utils/Image/imageProperties";
 import { EnhancedTextRenderer } from "./utils/Texts/enhancedTextRenderer";
 import { EnhancedPatternRenderer } from "./utils/Patterns/enhancedPatternRenderer";
 
@@ -26,6 +36,7 @@ import { EnhancedPatternRenderer } from "./utils/Patterns/enhancedPatternRendere
 
 export class ApexPainter {
   private format?: OutputFormat;
+  private saveCounter: number = 1;
 
   constructor({ type }: OutputFormat = { type: 'buffer' }) {
     this.format = { type: type || 'buffer' };
@@ -60,7 +71,12 @@ export class ApexPainter {
    * @param textProps - Text properties
    */
   async #renderEnhancedText(ctx: SKRSContext2D, textProps: TextProperties): Promise<void> {
-    await EnhancedTextRenderer.renderText(ctx, textProps);
+    // Check if text should be rendered on a path
+    if (textProps.path && textProps.textOnPath) {
+      renderTextOnPath(ctx, textProps.text, textProps.path, textProps.path.offset ?? 0);
+    } else {
+      await EnhancedTextRenderer.renderText(ctx, textProps);
+    }
   }
 
   /**
@@ -94,20 +110,66 @@ export class ApexPainter {
    * const buffer = result.buffer;
    * ```
    */
-async createCanvas(canvas: CanvasConfig): Promise<CanvasResults> {
-  // Handle inherit sizing
-  if (canvas.customBg?.inherit) {
-    let p = canvas.customBg.source;
-    if (!/^https?:\/\//i.test(p)) p = path.join(process.cwd(), p);
-    try {
-      const img = await loadImage(p);
-      canvas.width = img.width;
-      canvas.height = img.height;
-    } catch (e:any) {
-      console.error('inherit load failed:', e?.message ?? e);
+  /**
+   * Validates canvas configuration.
+   * @private
+   * @param canvas - Canvas configuration to validate
+   */
+  #validateCanvasConfig(canvas: CanvasConfig): void {
+    if (!canvas) {
+      throw new Error("createCanvas: canvas configuration is required.");
+    }
+    
+    if (canvas.width !== undefined && (typeof canvas.width !== 'number' || canvas.width <= 0)) {
+      throw new Error("createCanvas: width must be a positive number.");
+    }
+    
+    if (canvas.height !== undefined && (typeof canvas.height !== 'number' || canvas.height <= 0)) {
+      throw new Error("createCanvas: height must be a positive number.");
+    }
+    
+    if (canvas.opacity !== undefined && (typeof canvas.opacity !== 'number' || canvas.opacity < 0 || canvas.opacity > 1)) {
+      throw new Error("createCanvas: opacity must be a number between 0 and 1.");
+    }
+    
+    if (canvas.zoom?.scale !== undefined && (typeof canvas.zoom.scale !== 'number' || canvas.zoom.scale <= 0)) {
+      throw new Error("createCanvas: zoom.scale must be a positive number.");
     }
   }
 
+  async createCanvas(canvas: CanvasConfig): Promise<CanvasResults> {
+    try {
+      // Validate canvas configuration
+      this.#validateCanvasConfig(canvas);
+      
+      // Handle inherit sizing
+      if (canvas.customBg?.inherit) {
+        let p = canvas.customBg.source;
+        if (!/^https?:\/\//i.test(p)) p = path.join(process.cwd(), p);
+        try {
+          const img = await loadImage(p);
+          canvas.width = img.width;
+          canvas.height = img.height;
+        } catch (e: unknown) {
+          const errorMessage = e instanceof Error ? e.message : String(e);
+          throw new Error(`createCanvas: Failed to load image for inherit sizing: ${errorMessage}`);
+        }
+      }
+
+      // Handle video background inherit sizing
+      if (canvas.videoBg) {
+        try {
+          const frameBuffer = await this.#extractVideoFrame(canvas.videoBg.source, canvas.videoBg.frame ?? 0);
+          if (frameBuffer) {
+            const img = await loadImage(frameBuffer);
+            if (!canvas.width) canvas.width = img.width;
+            if (!canvas.height) canvas.height = img.height;
+          }
+        } catch (e: unknown) {
+          console.warn('createCanvas: Failed to extract video frame for sizing, using defaults');
+        }
+      }
+
   // 2) Use final width/height after inherit
   const width  = canvas.width  ?? 500;
   const height = canvas.height ?? 500;
@@ -118,7 +180,7 @@ async createCanvas(canvas: CanvasConfig): Promise<CanvasResults> {
     borderRadius = 0,
     borderPosition = 'all',
     opacity = 1,
-    colorBg, customBg, gradientBg,
+    colorBg, customBg, gradientBg, videoBg,
     patternBg, noiseBg, blendMode,
     zoom, stroke, shadow,
     blur
@@ -135,54 +197,97 @@ async createCanvas(canvas: CanvasConfig): Promise<CanvasResults> {
     throw new Error(`createCanvas: only one of colorBg, gradientBg, or customBg can be used. You provided: ${bgSources.join(', ')}`);
   }
 
-  const cv = createCanvas(width, height);
-  const ctx = cv.getContext('2d') as SKRSContext2D;
-  if (!ctx) throw new Error('Unable to get 2D context');
+      const cv = createCanvas(width, height);
+      const ctx = cv.getContext('2d') as SKRSContext2D;
+      if (!ctx) throw new Error('Unable to get 2D context');
 
 
-  ctx.globalAlpha = opacity;
+      ctx.globalAlpha = opacity;
 
-  // ---- BACKGROUND (clipped) ----
-  ctx.save();
-  applyRotation(ctx, rotation, x, y, width, height);
+      // ---- BACKGROUND (clipped) ----
+      ctx.save();
+      applyRotation(ctx, rotation, x, y, width, height);
 
-  buildPath(ctx, x, y, width, height, borderRadius, borderPosition);
-  ctx.clip();
+      buildPath(ctx, x, y, width, height, borderRadius, borderPosition);
+      ctx.clip();
 
-  applyCanvasZoom(ctx, width, height, zoom);
+      applyCanvasZoom(ctx, width, height, zoom);
 
-  ctx.translate(x, y);
-  if (typeof blendMode === 'string') {
-    ctx.globalCompositeOperation = blendMode as any;
-  }
+      ctx.translate(x, y);
+      if (typeof blendMode === 'string') {
+        ctx.globalCompositeOperation = blendMode as GlobalCompositeOperation;
+      }
+
+      // Draw video background if specified
+      if (videoBg) {
+        try {
+          const frameBuffer = await this.#extractVideoFrame(videoBg.source, videoBg.frame ?? 0);
+          if (frameBuffer) {
+            const videoImg = await loadImage(frameBuffer);
+            ctx.globalAlpha = videoBg.opacity ?? 1;
+            ctx.drawImage(videoImg, 0, 0, width, height);
+            ctx.globalAlpha = opacity;
+          }
+        } catch (e: unknown) {
+          console.warn('createCanvas: Failed to load video background frame');
+        }
+      }
 
-  if (customBg)      await customBackground(ctx, { ...canvas, blur });
-  else if (gradientBg) await drawBackgroundGradient(ctx, { ...canvas, blur });
-  else               await drawBackgroundColor(ctx, { ...canvas, blur, colorBg: colorBg ?? '#000' });
+      // Draw custom background with filters and opacity support
+      if (customBg) {
+        await customBackground(ctx, { ...canvas, blur });
+        // Apply filters to background if specified
+        if (customBg.filters && customBg.filters.length > 0) {
+          const tempCanvas = createCanvas(width, height);
+          const tempCtx = tempCanvas.getContext('2d') as SKRSContext2D;
+          if (tempCtx) {
+            tempCtx.drawImage(cv, 0, 0);
+            await applySimpleProfessionalFilters(tempCtx, customBg.filters, width, height);
+            ctx.clearRect(0, 0, width, height);
+            ctx.globalAlpha = customBg.opacity ?? 1;
+            ctx.drawImage(tempCanvas, 0, 0);
+            ctx.globalAlpha = opacity;
+          }
+        } else if (customBg.opacity !== undefined && customBg.opacity !== 1) {
+          ctx.globalAlpha = customBg.opacity;
+          await customBackground(ctx, { ...canvas, blur });
+          ctx.globalAlpha = opacity;
+        } else {
+          await customBackground(ctx, { ...canvas, blur });
+        }
+      } else if (gradientBg) {
+        await drawBackgroundGradient(ctx, { ...canvas, blur });
+      } else {
+        await drawBackgroundColor(ctx, { ...canvas, blur, colorBg: colorBg ?? '#000' });
+      }
 
-  if (patternBg) await EnhancedPatternRenderer.renderPattern(ctx, cv, patternBg);
-  if (noiseBg)   applyNoise(ctx, width, height, noiseBg.intensity ?? 0.05);
+      if (patternBg) await EnhancedPatternRenderer.renderPattern(ctx, cv, patternBg);
+      if (noiseBg)   applyNoise(ctx, width, height, noiseBg.intensity ?? 0.05);
 
-  ctx.restore();
+      ctx.restore();
 
-  // Apply shadow effect
-  if (shadow) {
-    ctx.save();
-    buildPath(ctx, x, y, width, height, borderRadius, borderPosition);
-    applyShadow(ctx, shadow, x, y, width, height);
-    ctx.restore();
-  }
+      // Apply shadow effect
+      if (shadow) {
+        ctx.save();
+        buildPath(ctx, x, y, width, height, borderRadius, borderPosition);
+        applyShadow(ctx, shadow, x, y, width, height);
+        ctx.restore();
+      }
 
-  // Apply stroke effect
-  if (stroke) {
-    ctx.save();
-    buildPath(ctx, x, y, width, height, borderRadius, borderPosition);
-    applyStroke(ctx, stroke, x, y, width, height);
-    ctx.restore();
-  }
+      // Apply stroke effect
+      if (stroke) {
+        ctx.save();
+        buildPath(ctx, x, y, width, height, borderRadius, borderPosition);
+        applyStroke(ctx, stroke, x, y, width, height);
+        ctx.restore();
+      }
 
-  return { buffer: cv.toBuffer('image/png'), canvas };
-}
+      return { buffer: cv.toBuffer('image/png'), canvas };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`createCanvas failed: ${errorMessage}`);
+    }
+  }
 
 
 
@@ -228,31 +333,57 @@ async createCanvas(canvas: CanvasConfig): Promise<CanvasResults> {
    * ], canvasBuffer);
    * ```
    */
+  /**
+   * Validates image/shape properties array.
+   * @private
+   * @param images - Image properties to validate
+   */
+  #validateImageArray(images: ImageProperties | ImageProperties[]): void {
+    const list = Array.isArray(images) ? images : [images];
+    if (list.length === 0) {
+      throw new Error("createImage: At least one image/shape is required.");
+    }
+    for (const ip of list) {
+      this.#validateImageProperties(ip);
+    }
+  }
+
   async createImage(
     images: ImageProperties | ImageProperties[],
     canvasBuffer: CanvasResults | Buffer
   ): Promise<Buffer> {
-    const list = Array.isArray(images) ? images : [images];
+    try {
+      // Validate inputs
+      if (!canvasBuffer) {
+        throw new Error("createImage: canvasBuffer is required.");
+      }
+      this.#validateImageArray(images);
+      
+      const list = Array.isArray(images) ? images : [images];
 
-    // Load base canvas buffer
-    const base: Image = Buffer.isBuffer(canvasBuffer)
-      ? await loadImage(canvasBuffer)
-      : await loadImage((canvasBuffer as CanvasResults).buffer);
+      // Load base canvas buffer
+      const base: Image = Buffer.isBuffer(canvasBuffer)
+        ? await loadImage(canvasBuffer)
+        : await loadImage((canvasBuffer as CanvasResults).buffer);
 
-    const cv = createCanvas(base.width, base.height);
-    const ctx = cv.getContext("2d") as SKRSContext2D;
-    if (!ctx) throw new Error("Unable to get 2D rendering context");
+      const cv = createCanvas(base.width, base.height);
+      const ctx = cv.getContext("2d") as SKRSContext2D;
+      if (!ctx) throw new Error("Unable to get 2D rendering context");
 
-    // Paint bg
-    ctx.drawImage(base, 0, 0);
+      // Paint bg
+      ctx.drawImage(base, 0, 0);
 
-    // Draw each image/shape on canvas
-    for (const ip of list) {
-      await this.#drawImageBitmap(ctx, ip);
-    }
+      // Draw each image/shape on canvas
+      for (const ip of list) {
+        await this.#drawImageBitmap(ctx, ip);
+      }
 
-    // Return updated buffer
-    return cv.toBuffer("image/png");
+      // Return updated buffer
+      return cv.toBuffer("image/png");
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`createImage failed: ${errorMessage}`);
+    }
   }
 
   /**
@@ -277,7 +408,14 @@ async createCanvas(canvas: CanvasConfig): Promise<CanvasResults> {
       stroke,
       boxBackground,
       shape,
-      filters
+      filters,
+      filterIntensity = 1,
+      filterOrder = 'post',
+      mask,
+      clipPath,
+      distortion,
+      meshWarp,
+      effects
     } = ip;
 
     this.#validateImageProperties(ip);
@@ -318,10 +456,14 @@ async createCanvas(canvas: CanvasConfig): Promise<CanvasResults> {
     // 2) Optional box background (under bitmap, inside clip) — color or gradient
     drawBoxBackground(ctx, box, boxBackground, borderRadius, borderPosition);
 
-    // 3) Clip to image border radius, then draw the bitmap with blur/opacity and fit/align
+    // 3) Clip to image border radius or custom clip path, then draw the bitmap with blur/opacity and fit/align
     ctx.save();
-    buildPath(ctx, box.x, box.y, box.w, box.h, borderRadius, borderPosition);
-    ctx.clip();
+    if (clipPath && clipPath.length >= 3) {
+      applyClipPath(ctx, clipPath);
+    } else {
+      buildPath(ctx, box.x, box.y, box.w, box.h, borderRadius, borderPosition);
+      ctx.clip();
+    }
 
     const { dx, dy, dw, dh, sx, sy, sw, sh } =
       fitInto(box.x, box.y, box.w, box.h, img.width, img.height, fit, align);
@@ -330,17 +472,117 @@ async createCanvas(canvas: CanvasConfig): Promise<CanvasResults> {
     ctx.globalAlpha = opacity ?? 1;
     if ((blur ?? 0) > 0) ctx.filter = `blur(${blur}px)`;
 
-    // Apply professional image filters BEFORE drawing
-    if (filters && filters.length > 0) {
-      await applySimpleProfessionalFilters(ctx, filters, dw, dh);
+    // Apply professional image filters BEFORE drawing if filterOrder is 'pre'
+    if (filters && filters.length > 0 && filterOrder === 'pre') {
+      const adjustedFilters = filters.map(f => ({
+        ...f,
+        intensity: f.intensity !== undefined ? f.intensity * filterIntensity : (f.intensity ?? 1) * filterIntensity,
+        value: f.value !== undefined ? f.value * filterIntensity : f.value,
+        radius: f.radius !== undefined ? f.radius * filterIntensity : f.radius
+      }));
+      await applySimpleProfessionalFilters(ctx, adjustedFilters, dw, dh);
     }
 
-    ctx.drawImage(img, sx, sy, sw, sh, dx, dy, dw, dh);
+    // Apply distortion if specified (before drawing)
+    if (distortion) {
+      if (distortion.type === 'perspective' && distortion.points && distortion.points.length === 4) {
+        applyPerspectiveDistortion(ctx, img, distortion.points, dx, dy, dw, dh);
+        ctx.filter = "none";
+        ctx.globalAlpha = prevAlpha;
+        ctx.restore();
+        ctx.restore();
+        return;
+      } else if (distortion.type === 'bulge' || distortion.type === 'pinch') {
+        const centerX = dx + dw / 2;
+        const centerY = dy + dh / 2;
+        const radius = Math.min(dw, dh) / 2;
+        const intensity = (distortion.intensity ?? 0.5) * (distortion.type === 'pinch' ? -1 : 1);
+        applyBulgeDistortion(ctx, img, centerX, centerY, radius, intensity, dx, dy, dw, dh);
+        ctx.filter = "none";
+        ctx.globalAlpha = prevAlpha;
+        ctx.restore();
+        ctx.restore();
+        return;
+      }
+    }
+
+    // Apply mesh warp if specified
+    if (meshWarp && meshWarp.controlPoints) {
+      applyMeshWarp(ctx, img, meshWarp.gridX ?? 10, meshWarp.gridY ?? 10, meshWarp.controlPoints, dx, dy, dw, dh);
+      ctx.filter = "none";
+      ctx.globalAlpha = prevAlpha;
+      ctx.restore();
+      ctx.restore();
+      return;
+    }
+
+    // Draw image with or without masking
+    if (mask) {
+      await applyImageMask(ctx, img, mask.source, mask.mode ?? 'alpha', dx, dy, dw, dh);
+    } else {
+      ctx.drawImage(img, sx, sy, sw, sh, dx, dy, dw, dh);
+    }
 
     ctx.filter = "none";
     ctx.globalAlpha = prevAlpha;
     ctx.restore();
 
+    // Apply professional image filters AFTER drawing if filterOrder is 'post'
+    if (filters && filters.length > 0 && filterOrder === 'post') {
+      ctx.save();
+      const imageData = ctx.getImageData(box.x, box.y, box.w, box.h);
+      const tempCanvas = createCanvas(box.w, box.h);
+      const tempCtx = tempCanvas.getContext('2d') as SKRSContext2D;
+      if (tempCtx) {
+        tempCtx.putImageData(imageData, 0, 0);
+        const adjustedFilters = filters.map(f => ({
+          ...f,
+          intensity: f.intensity !== undefined ? f.intensity * filterIntensity : (f.intensity ?? 1) * filterIntensity,
+          value: f.value !== undefined ? f.value * filterIntensity : f.value,
+          radius: f.radius !== undefined ? f.radius * filterIntensity : f.radius
+        }));
+        await applySimpleProfessionalFilters(tempCtx, adjustedFilters, box.w, box.h);
+        ctx.clearRect(box.x, box.y, box.w, box.h);
+        ctx.drawImage(tempCanvas, box.x, box.y);
+      }
+      ctx.restore();
+    }
+
+    // Apply effects stack
+    if (effects) {
+      ctx.save();
+      const effectsCtx = ctx;
+      if (effects.vignette) {
+        applyVignette(effectsCtx, effects.vignette.intensity, effects.vignette.size, box.w, box.h);
+      }
+      if (effects.lensFlare) {
+        applyLensFlare(effectsCtx, box.x + effects.lensFlare.x, box.y + effects.lensFlare.y, effects.lensFlare.intensity, box.w, box.h);
+      }
+      if (effects.chromaticAberration) {
+        const imageData = ctx.getImageData(box.x, box.y, box.w, box.h);
+        const tempCanvas = createCanvas(box.w, box.h);
+        const tempCtx = tempCanvas.getContext('2d') as SKRSContext2D;
+        if (tempCtx) {
+          tempCtx.putImageData(imageData, 0, 0);
+          applyChromaticAberration(tempCtx, effects.chromaticAberration.intensity, box.w, box.h);
+          ctx.clearRect(box.x, box.y, box.w, box.h);
+          ctx.drawImage(tempCanvas, box.x, box.y);
+        }
+      }
+      if (effects.filmGrain) {
+        const imageData = ctx.getImageData(box.x, box.y, box.w, box.h);
+        const tempCanvas = createCanvas(box.w, box.h);
+        const tempCtx = tempCanvas.getContext('2d') as SKRSContext2D;
+        if (tempCtx) {
+          tempCtx.putImageData(imageData, 0, 0);
+          applyFilmGrain(tempCtx, effects.filmGrain.intensity, box.w, box.h);
+          ctx.clearRect(box.x, box.y, box.w, box.h);
+          ctx.drawImage(tempCanvas, box.x, box.y);
+        }
+      }
+      ctx.restore();
+    }
+
 
     // 4) Stroke (independent) — supports gradient or color
     applyStroke(ctx, box, stroke);
@@ -647,18 +889,34 @@ async createCanvas(canvas: CanvasConfig): Promise<CanvasResults> {
    * ], canvasBuffer);
    * ```
    */
+  /**
+   * Validates text properties array.
+   * @private
+   * @param textArray - Text properties to validate
+   */
+  #validateTextArray(textArray: TextProperties | TextProperties[]): void {
+    const textList = Array.isArray(textArray) ? textArray : [textArray];
+    if (textList.length === 0) {
+      throw new Error("createText: At least one text object is required.");
+    }
+    for (const textProps of textList) {
+      this.#validateTextProperties(textProps);
+    }
+  }
+
   async createText(textArray: TextProperties | TextProperties[], canvasBuffer: CanvasResults | Buffer): Promise<Buffer> {
     try {
+      // Validate inputs
+      if (!canvasBuffer) {
+        throw new Error("createText: canvasBuffer is required.");
+      }
+      this.#validateTextArray(textArray);
+      
       // Ensure textArray is an array
       const textList = Array.isArray(textArray) ? textArray : [textArray];
 
-      // Validate each text object
-      for (const textProps of textList) {
-        this.#validateTextProperties(textProps);
-      }
-
       // Load existing canvas buffer
-      let existingImage: any;
+      let existingImage: Image;
       
       if (Buffer.isBuffer(canvasBuffer)) {
         existingImage = await loadImage(canvasBuffer);
@@ -690,21 +948,44 @@ async createCanvas(canvas: CanvasConfig): Promise<CanvasResults> {
 
       return canvas.toBuffer("image/png");
     } catch (error) {
-      console.error("Error creating text:", error);
-      throw new Error("Failed to create text on canvas");
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`createText failed: ${errorMessage}`);
     }
   }
 
 
 
-  async createCustom(options: CustomOptions[], buffer: CanvasResults | Buffer, ): Promise<Buffer> {
-    try {
+  /**
+   * Validates custom line options.
+   * @private
+   * @param options - Custom options to validate
+   */
+  #validateCustomOptions(options: CustomOptions | CustomOptions[]): void {
+    const opts = Array.isArray(options) ? options : [options];
+    if (opts.length === 0) {
+      throw new Error("createCustom: At least one custom option is required.");
+    }
+    for (const opt of opts) {
+      if (!opt.startCoordinates || typeof opt.startCoordinates.x !== 'number' || typeof opt.startCoordinates.y !== 'number') {
+        throw new Error("createCustom: startCoordinates with valid x and y are required.");
+      }
+      if (!opt.endCoordinates || typeof opt.endCoordinates.x !== 'number' || typeof opt.endCoordinates.y !== 'number') {
+        throw new Error("createCustom: endCoordinates with valid x and y are required.");
+      }
+    }
+  }
 
-      if (!Array.isArray(options)) {
-        options = [options];
+  async createCustom(options: CustomOptions | CustomOptions[], buffer: CanvasResults | Buffer): Promise<Buffer> {
+    try {
+      // Validate inputs
+      if (!buffer) {
+        throw new Error("createCustom: buffer is required.");
       }
+      this.#validateCustomOptions(options);
+
+      const opts = Array.isArray(options) ? options : [options];
 
-      let existingImage: any;
+      let existingImage: Image;
         
       if (Buffer.isBuffer(buffer)) {
         existingImage = await loadImage(buffer);
@@ -723,17 +1004,49 @@ async createCanvas(canvas: CanvasConfig): Promise<CanvasResults> {
 
       ctx.drawImage(existingImage, 0, 0);
 
-      customLines(ctx, options);
+      await customLines(ctx, opts);
 
       return canvas.toBuffer("image/png");
     } catch (error) {
-        console.error("Error creating custom image:", error);
-        throw new Error("Failed to create custom image");
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`createCustom failed: ${errorMessage}`);
     }
-}
+  }
 
-async createGIF(gifFrames: { background: string; duration: number }[], options: GIFOptions): Promise<GIFResults | any> {
-  async function resizeImage(image: any, targetWidth: number, targetHeight: number) {
+  /**
+   * Validates GIF options and frames.
+   * @private
+   * @param gifFrames - GIF frames to validate
+   * @param options - GIF options to validate
+   */
+  #validateGIFOptions(gifFrames: { background: string; duration: number }[], options: GIFOptions): void {
+    if (!gifFrames || gifFrames.length === 0) {
+      throw new Error("createGIF: At least one frame is required.");
+    }
+    for (const frame of gifFrames) {
+      if (!frame.background) {
+        throw new Error("createGIF: Each frame must have a background property.");
+      }
+      if (typeof frame.duration !== 'number' || frame.duration < 0) {
+        throw new Error("createGIF: Each frame duration must be a non-negative number.");
+      }
+    }
+    if (options.outputFormat === "file" && !options.outputFile) {
+      throw new Error("createGIF: outputFile is required when outputFormat is 'file'.");
+    }
+    if (options.repeat !== undefined && (typeof options.repeat !== "number" || options.repeat < 0)) {
+      throw new Error("createGIF: repeat must be a non-negative number or undefined.");
+    }
+    if (options.quality !== undefined && (typeof options.quality !== "number" || options.quality < 1 || options.quality > 20)) {
+      throw new Error("createGIF: quality must be a number between 1 and 20 or undefined.");
+    }
+  }
+
+  async createGIF(gifFrames: { background: string; duration: number }[], options: GIFOptions): Promise<GIFResults | Buffer | string | Array<{ attachment: NodeJS.ReadableStream | any; name: string }> | undefined> {
+    try {
+      this.#validateGIFOptions(gifFrames, options);
+      
+      async function resizeImage(image: Image, targetWidth: number, targetHeight: number) {
       const canvas = createCanvas(targetWidth, targetHeight);
       const ctx = canvas.getContext("2d");
       ctx.drawImage(image, 0, 0, targetWidth, targetHeight);
@@ -757,38 +1070,10 @@ async createGIF(gifFrames: { background: string; duration: number }[], options:
           getBuffer: function (): Buffer {
               return Buffer.concat(chunks);
           }
-      } as any;
+      } as PassThrough & { getBuffer: () => Buffer };
   }
 
-  function validateOptions(options: GIFOptions) {
-      if (options.outputFormat === "file" && !options.outputFile) {
-          throw new Error("Output file path is required when using file output format.");
-      }
-      if (options.repeat !== undefined && (typeof options.repeat !== "number" || options.repeat < 0)) {
-          throw new Error("Repeat must be a non-negative number or undefined.");
-      }
-      if (options.quality !== undefined && (typeof options.quality !== "number" || options.quality < 1 || options.quality > 20)) {
-          throw new Error("Quality must be a number between 1 and 20 or undefined.");
-      }
-      if (options.watermark && typeof options.watermark.enable !== "boolean") {
-          throw new Error("Watermark must be a boolean or undefined.");
-      }
-      if (options.textOverlay) {
-          const textOptions = options.textOverlay;
-          if (!textOptions.text || typeof textOptions.text !== "string") {
-              throw new Error("Text overlay text is required and must be a string.");
-          }
-          if (textOptions.fontSize !== undefined && (!Number.isInteger(textOptions.fontSize) || textOptions.fontSize <= 0)) {
-              throw new Error("Text overlay fontSize must be a positive integer or undefined.");
-          }
-          if (textOptions.fontColor !== undefined && typeof textOptions.fontColor !== "string") {
-              throw new Error("Text overlay fontColor must be a string or undefined.");
-          }
-      }
-  }
-
-  try {
-      validateOptions(options);
+      // Validation is done in #validateGIFOptions
   
       const canvasWidth = options.width || 1200;
       const canvasHeight = options.height || 1200;
@@ -803,7 +1088,8 @@ async createGIF(gifFrames: { background: string; duration: number }[], options:
       encoder.setQuality(options.quality || 10);
 
       const canvas = createCanvas(canvasWidth, canvasHeight);
-      const ctx:any = canvas.getContext("2d");
+      const ctx = canvas.getContext("2d") as SKRSContext2D;
+      if (!ctx) throw new Error("Unable to get 2D context");
       
       for (const frame of gifFrames) {
           const image = await loadImage(frame.background);
@@ -824,18 +1110,19 @@ async createGIF(gifFrames: { background: string; duration: number }[], options:
           }
 
           encoder.setDelay(frame.duration);
-          encoder.addFrame(ctx);
+          encoder.addFrame(ctx as unknown as CanvasRenderingContext2D);
       }
       
       encoder.finish();
       outputStream.end();
       
       if (options.outputFormat === "file") {
-          await new Promise((resolve) => outputStream.on("finish", resolve));
+          await new Promise<void>((resolve) => outputStream.on("finish", () => resolve()));
       } else if (options.outputFormat === "base64") {
           if ('getBuffer' in outputStream) {
               return outputStream.getBuffer().toString("base64");
           }
+          throw new Error("createGIF: Unable to get buffer for base64 output.");
       } else if (options.outputFormat === "attachment") {
           const gifStream = encoder.createReadStream();
           return [{ attachment: gifStream, name: "gif.js" }];
@@ -843,69 +1130,225 @@ async createGIF(gifFrames: { background: string; duration: number }[], options:
           if ('getBuffer' in outputStream) {
               return outputStream.getBuffer();
           }
+          throw new Error("createGIF: Unable to get buffer for buffer output.");
       } else {
           throw new Error("Invalid output format. Supported formats are 'file', 'base64', 'attachment', and 'buffer'.");
       }
-  } catch (e: any) {
-      console.error(e.message);
-      throw e;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`createGIF failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Validates resize options.
+   * @private
+   * @param options - Resize options to validate
+   */
+  #validateResizeOptions(options: ResizeOptions): void {
+    if (!options || !options.imagePath) {
+      throw new Error("resize: imagePath is required.");
+    }
+    if (options.size) {
+      if (options.size.width !== undefined && (typeof options.size.width !== 'number' || options.size.width <= 0)) {
+        throw new Error("resize: size.width must be a positive number.");
+      }
+      if (options.size.height !== undefined && (typeof options.size.height !== 'number' || options.size.height <= 0)) {
+        throw new Error("resize: size.height must be a positive number.");
+      }
+    }
+    if (options.quality !== undefined && (typeof options.quality !== 'number' || options.quality < 0 || options.quality > 100)) {
+      throw new Error("resize: quality must be a number between 0 and 100.");
+    }
   }
-}
 
-  async resize(resizeOptions: ResizeOptions) {
-    return resizingImg(resizeOptions)
+  async resize(resizeOptions: ResizeOptions): Promise<Buffer> {
+    try {
+      this.#validateResizeOptions(resizeOptions);
+      return await resizingImg(resizeOptions);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`resize failed: ${errorMessage}`);
+    }
   }
 
-  async imgConverter(source: string, newExtension: string) {
-    return converter(source, newExtension)
+  /**
+   * Validates image converter inputs.
+   * @private
+   * @param source - Image source to validate
+   * @param newExtension - Extension to validate
+   */
+  #validateConverterInputs(source: string, newExtension: string): void {
+    if (!source) {
+      throw new Error("imgConverter: source is required.");
+    }
+    if (!newExtension) {
+      throw new Error("imgConverter: newExtension is required.");
+    }
+    const validExtensions = ['jpeg', 'png', 'webp', 'tiff', 'gif', 'avif', 'heif', 'raw', 'pdf', 'svg'];
+    if (!validExtensions.includes(newExtension.toLowerCase())) {
+      throw new Error(`imgConverter: Invalid extension. Supported: ${validExtensions.join(', ')}`);
+    }
   }
 
-  async effects(source: string, filters: any[]) {
-    return imgEffects(source, filters)
+  async imgConverter(source: string, newExtension: string): Promise<Buffer> {
+    try {
+      this.#validateConverterInputs(source, newExtension);
+      return await converter(source, newExtension);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`imgConverter failed: ${errorMessage}`);
+    }
   }
 
-  async colorsFilter(source: string, filterColor: any, opacity?: number) {
-    return applyColorFilters(source, filterColor, opacity)
+  /**
+   * Validates effects inputs.
+   * @private
+   * @param source - Image source to validate
+   * @param filters - Filters array to validate
+   */
+  #validateEffectsInputs(source: string, filters: ImageFilter[]): void {
+    if (!source) {
+      throw new Error("effects: source is required.");
+    }
+    if (!filters || !Array.isArray(filters) || filters.length === 0) {
+      throw new Error("effects: filters array with at least one filter is required.");
+    }
   }
 
-  async colorAnalysis(source: string) {
-    return detectColors(source)
+  async effects(source: string, filters: ImageFilter[]): Promise<Buffer> {
+    try {
+      this.#validateEffectsInputs(source, filters);
+      return await imgEffects(source, filters);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`effects failed: ${errorMessage}`);
+    }
   }
 
-  async colorsRemover(source: string, colorToRemove: { red: number, green: number, blue: number }) {
-    return removeColor(source, colorToRemove)
+  /**
+   * Validates color filter inputs.
+   * @private
+   * @param source - Image source to validate
+   * @param opacity - Opacity to validate
+   */
+  #validateColorFilterInputs(source: string, opacity?: number): void {
+    if (!source) {
+      throw new Error("colorsFilter: source is required.");
+    }
+    if (opacity !== undefined && (typeof opacity !== 'number' || opacity < 0 || opacity > 1)) {
+      throw new Error("colorsFilter: opacity must be a number between 0 and 1.");
+    }
   }
 
-  async removeBackground(imageURL: string, apiKey: string) {
-    return bgRemoval(imageURL, apiKey)
+  async colorsFilter(source: string, filterColor: string | GradientConfig, opacity?: number): Promise<Buffer> {
+    try {
+      this.#validateColorFilterInputs(source, opacity);
+      return await applyColorFilters(source, filterColor, opacity);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`colorsFilter failed: ${errorMessage}`);
+    }
+  }
+
+  async colorAnalysis(source: string): Promise<{ color: string; frequency: string }[]> {
+    try {
+      if (!source) {
+        throw new Error("colorAnalysis: source is required.");
+      }
+      return await detectColors(source);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`colorAnalysis failed: ${errorMessage}`);
+    }
+  }
+
+  async colorsRemover(source: string, colorToRemove: { red: number, green: number, blue: number }): Promise<Buffer | undefined> {
+    try {
+      if (!source) {
+        throw new Error("colorsRemover: source is required.");
+      }
+      if (!colorToRemove || typeof colorToRemove.red !== 'number' || typeof colorToRemove.green !== 'number' || typeof colorToRemove.blue !== 'number') {
+        throw new Error("colorsRemover: colorToRemove must be an object with red, green, and blue properties (0-255).");
+      }
+      if (colorToRemove.red < 0 || colorToRemove.red > 255 || 
+          colorToRemove.green < 0 || colorToRemove.green > 255 || 
+          colorToRemove.blue < 0 || colorToRemove.blue > 255) {
+        throw new Error("colorsRemover: colorToRemove RGB values must be between 0 and 255.");
+      }
+      return await removeColor(source, colorToRemove);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`colorsRemover failed: ${errorMessage}`);
+    }
+  }
+
+  async removeBackground(imageURL: string, apiKey: string): Promise<Buffer | undefined> {
+    try {
+      if (!imageURL) {
+        throw new Error("removeBackground: imageURL is required.");
+      }
+      if (!apiKey) {
+        throw new Error("removeBackground: apiKey is required.");
+      }
+      return await bgRemoval(imageURL, apiKey);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`removeBackground failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Validates blend inputs.
+   * @private
+   * @param layers - Layers to validate
+   * @param baseImageBuffer - Base image buffer to validate
+   */
+  #validateBlendInputs(
+    layers: Array<{
+      image: string | Buffer;
+      blendMode: GlobalCompositeOperation;
+      position?: { x: number; y: number };
+      opacity?: number;
+    }>,
+    baseImageBuffer: Buffer
+  ): void {
+    if (!baseImageBuffer || !Buffer.isBuffer(baseImageBuffer)) {
+      throw new Error("blend: baseImageBuffer must be a valid Buffer.");
+    }
+    if (!layers || !Array.isArray(layers) || layers.length === 0) {
+      throw new Error("blend: layers array with at least one layer is required.");
+    }
+    for (const layer of layers) {
+      if (!layer.image) {
+        throw new Error("blend: Each layer must have an image property.");
+      }
+      if (!layer.blendMode) {
+        throw new Error("blend: Each layer must have a blendMode property.");
+      }
+      if (layer.opacity !== undefined && (typeof layer.opacity !== 'number' || layer.opacity < 0 || layer.opacity > 1)) {
+        throw new Error("blend: Layer opacity must be a number between 0 and 1.");
+      }
+    }
   }
 
   async blend(
-    layers: {
+    layers: Array<{
       image: string | Buffer;
-      blendMode: 'source-over' | 'source-in' | 'source-out' | 'source-atop' |
-                 'destination-over' | 'destination-in' | 'destination-out' |
-                 'destination-atop' | 'lighter' | 'copy' | 'xor' |
-                 'multiply' | 'screen' | 'overlay' | 'darken' |
-                 'lighten' | 'color-dodge' | 'color-burn' |
-                 'hard-light' | 'soft-light' | 'difference' | 'exclusion' |
-                 'hue' | 'saturation' | 'color' | 'luminosity';
+      blendMode: GlobalCompositeOperation;
       position?: { x: number; y: number };
       opacity?: number;
-    }[],
+    }>,
     baseImageBuffer: Buffer,
-    defaultBlendMode: 'source-over' | 'source-in' | 'source-out' | 'source-atop' |
-                      'destination-over' | 'destination-in' | 'destination-out' |
-                      'destination-atop' | 'lighter' | 'copy' | 'xor' |
-                      'multiply' | 'screen' | 'overlay' | 'darken' |
-                      'lighten' | 'color-dodge' | 'color-burn' |
-                      'hard-light' | 'soft-light' | 'difference' | 'exclusion' |
-                      'hue' | 'saturation' | 'color' | 'luminosity' = 'source-over'
+    defaultBlendMode: GlobalCompositeOperation = 'source-over'
   ): Promise<Buffer> {
     try {
+      this.#validateBlendInputs(layers, baseImageBuffer);
+      
       const baseImage = await loadImage(baseImageBuffer);
       const canvas = createCanvas(baseImage.width, baseImage.height);
-      const ctx = canvas.getContext('2d');
+      const ctx = canvas.getContext('2d') as SKRSContext2D;
+      if (!ctx) throw new Error("Unable to get 2D context");
   
       ctx.globalCompositeOperation = defaultBlendMode;
       ctx.drawImage(baseImage, 0, 0);
@@ -923,29 +1366,52 @@ async createGIF(gifFrames: { background: string; duration: number }[], options:
   
       return canvas.toBuffer('image/png');
     } catch (error) {
-      console.error('Error creating layered composition:', error);
-      throw new Error('Failed to create layered composition');
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`blend failed: ${errorMessage}`);
     }
   }
   
 
-  async createChart(data: any, type: { chartType: string, chartNumber: number}) {
-
-    if (!data || Object.keys(data).length === 0) {
-        throw new Error('You need to provide datasets to create charts.');
+  /**
+   * Validates chart inputs.
+   * @private
+   * @param data - Chart data to validate
+   * @param type - Chart type configuration to validate
+   */
+  #validateChartInputs(data: unknown, type: { chartType: string; chartNumber: number }): void {
+    if (!data || typeof data !== 'object' || Object.keys(data).length === 0) {
+      throw new Error("createChart: data object with datasets is required.");
     }
-
-    if (!type || !type.chartNumber || !type.chartType) {
-        throw new Error('Type arguments are missing.');
+    if (!type || typeof type !== 'object') {
+      throw new Error("createChart: type configuration object is required.");
+    }
+    if (!type.chartType || typeof type.chartType !== 'string') {
+      throw new Error("createChart: type.chartType must be a string.");
     }
+    if (typeof type.chartNumber !== 'number' || type.chartNumber < 1) {
+      throw new Error("createChart: type.chartNumber must be a positive number.");
+    }
+    const validChartTypes = ['bar', 'line', 'pie'];
+    if (!validChartTypes.includes(type.chartType.toLowerCase())) {
+      throw new Error(`createChart: Invalid chartType. Supported: ${validChartTypes.join(', ')}`);
+    }
+  }
 
-    const { chartType, chartNumber } = type;
+  async createChart(data: unknown, type: { chartType: string; chartNumber: number }): Promise<Buffer> {
+    try {
+      this.#validateChartInputs(data, type);
+
+      const { chartType, chartNumber } = type;
 
     switch (chartType.toLowerCase()) {
         case 'bar':
             switch (chartNumber) {
                 case 1:
-                    return await verticalBarChart(data);
+                    const barResult = await verticalBarChart(data as barChart_1);
+                    if (!barResult) {
+                      throw new Error("createChart: Failed to generate bar chart.");
+                    }
+                    return barResult;
                 case 2:
                     throw new Error('Type 2 is still under development.');
                 default:
@@ -954,7 +1420,9 @@ async createGIF(gifFrames: { background: string; duration: number }[], options:
         case 'line':
             switch (chartNumber) {
                 case 1:
-                    return await lineChart(data);
+                    // LineChart expects DataPoint[][] where DataPoint has { label: string; y: number }
+                    // Type assertion needed because there are two different DataPoint interfaces
+                    return await lineChart(data as unknown as { data: Array<Array<{ label: string; y: number }>>; lineConfig: LineChartConfig });
                 case 2:
                     throw new Error('Type 2 is still under development.');
                 default:
@@ -963,7 +1431,7 @@ async createGIF(gifFrames: { background: string; duration: number }[], options:
         case 'pie':
             switch (chartNumber) {
                 case 1:
-                    return await pieChart(data);
+                    return await pieChart(data as PieChartData);
                 case 2:
                     throw new Error('Type 2 is still under development.');
                 default:
@@ -971,37 +1439,162 @@ async createGIF(gifFrames: { background: string; duration: number }[], options:
             }
         default:
             throw new Error(`Unsupported chart type "${chartType}".`);
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`createChart failed: ${errorMessage}`);
     }
   }
 
 
-  async  cropImage(options: cropOptions): Promise<Buffer> {
+  /**
+   * Validates crop options.
+   * @private
+   * @param options - Crop options to validate
+   */
+  #validateCropOptions(options: cropOptions): void {
+    if (!options) {
+      throw new Error("cropImage: options object is required.");
+    }
+    if (!options.imageSource) {
+      throw new Error("cropImage: imageSource is required.");
+    }
+    if (!options.coordinates || !Array.isArray(options.coordinates) || options.coordinates.length < 3) {
+      throw new Error("cropImage: coordinates array with at least 3 points is required.");
+    }
+    if (options.crop !== 'inner' && options.crop !== 'outer') {
+      throw new Error("cropImage: crop must be either 'inner' or 'outer'.");
+    }
+  }
+
+  async cropImage(options: cropOptions): Promise<Buffer> {
     try {
-      if (!options.imageSource) throw new Error('The "imageSource" option is needed. Please provide the path to the image to crop.');
-      if (!options.coordinates || options.coordinates.length < 3) throw new Error('The "coordinates" option is needed. Please provide coordinates to crop the image.');
+      this.#validateCropOptions(options);
 
       if (options.crop === 'outer') {
-          return await cropOuter(options);
-      } else if (options.crop === 'inner') {
-          return await cropInner(options);
+        return await cropOuter(options);
       } else {
-          throw new Error('Invalid crop option. Please specify "inner" or "outer".');
+        return await cropInner(options);
       }
     } catch (error) {
-      console.error('An error occurred:', error);
-      throw error;
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`cropImage failed: ${errorMessage}`);
     }
   }
 
-  private async drawImage(ctx: SKRSContext2D, image: ImageProperties): Promise<void> {
+    /**
+   * Extracts a single frame from a video
+   * @private
+   * @param videoSource - Video source (path, URL, or Buffer)
+   * @param frameNumber - Frame number to extract (default: 0)
+   * @returns Buffer containing the frame image
+   */
+  async #extractVideoFrame(videoSource: string | Buffer, frameNumber: number = 0): Promise<Buffer | null> {
+    try {
+      const frameDir = path.join(process.cwd(), '.temp-frames');
+      if (!fs.existsSync(frameDir)) {
+        fs.mkdirSync(frameDir, { recursive: true });
+      }
+
+      const tempVideoPath = path.join(frameDir, `temp-video-${Date.now()}.mp4`);
+      const frameOutputPath = path.join(frameDir, `frame-${Date.now()}.jpg`);
 
+      // Handle video source
+      if (Buffer.isBuffer(videoSource)) {
+        fs.writeFileSync(tempVideoPath, videoSource);
+      } else if (typeof videoSource === 'string' && videoSource.startsWith('http')) {
+        const response = await axios({
+          method: 'get',
+          url: videoSource,
+          responseType: 'arraybuffer'
+        });
+        fs.writeFileSync(tempVideoPath, Buffer.from(response.data));
+      } else {
+        // Local file path
+        if (!fs.existsSync(videoSource)) {
+          throw new Error(`Video file not found: ${videoSource}`);
+        }
+        // Use the existing path
+        return await new Promise<Buffer | null>((resolve, reject) => {
+          ffmpeg(videoSource)
+            .seekInput(frameNumber / 1000) // Convert frame to seconds (approximate)
+            .frames(1)
+            .output(frameOutputPath)
+            .on('end', () => {
+              try {
+                const buffer = fs.readFileSync(frameOutputPath);
+                // Cleanup
+                if (fs.existsSync(frameOutputPath)) fs.unlinkSync(frameOutputPath);
+                resolve(buffer);
+              } catch (e) {
+                resolve(null);
+              }
+            })
+            .on('error', (err: any) => {
+              reject(err);
+            })
+            .run();
+        });
+      }
 
+      // Extract frame from temp video
+      return await new Promise<Buffer | null>((resolve, reject) => {
+        ffmpeg(tempVideoPath)
+          .seekInput(frameNumber / 1000)
+          .frames(1)
+          .output(frameOutputPath)
+          .on('end', () => {
+            try {
+              const buffer = fs.readFileSync(frameOutputPath);
+              // Cleanup
+              if (fs.existsSync(tempVideoPath)) fs.unlinkSync(tempVideoPath);
+              if (fs.existsSync(frameOutputPath)) fs.unlinkSync(frameOutputPath);
+              resolve(buffer);
+            } catch (e) {
+              resolve(null);
+            }
+          })
+          .on('error', (err: any) => {
+            // Cleanup on error
+            if (fs.existsSync(tempVideoPath)) fs.unlinkSync(tempVideoPath);
+            if (fs.existsSync(frameOutputPath)) fs.unlinkSync(frameOutputPath);
+            reject(err);
+          })
+          .run();
+      });
+    } catch (error) {
+      console.error('Error extracting video frame:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Validates extract frames inputs.
+   * @private
+   * @param videoSource - Video source to validate
+   * @param options - Extract frames options to validate
+   */
+  #validateExtractFramesInputs(videoSource: string | Buffer, options: ExtractFramesOptions): void {
+    if (!videoSource) {
+      throw new Error("extractFrames: videoSource is required.");
+    }
+    if (!options || typeof options !== 'object') {
+      throw new Error("extractFrames: options object is required.");
+    }
+    if (typeof options.interval !== 'number' || options.interval <= 0) {
+      throw new Error("extractFrames: options.interval must be a positive number (milliseconds).");
+    }
+    if (options.outputFormat && !['jpg', 'png'].includes(options.outputFormat)) {
+      throw new Error("extractFrames: outputFormat must be 'jpg' or 'png'.");
+    }
   }
-  
 
-async extractFrames(videoSource: string | Buffer, options: ExtractFramesOptions): Promise<any[]> {
-  const frames: any[]= [];
-  const frameDir = path.join(__dirname, 'frames');
+  async extractFrames(videoSource: string | Buffer, options: ExtractFramesOptions): Promise<Array<{ source: string; isRemote: boolean }>> {
+    try {
+      this.#validateExtractFramesInputs(videoSource, options);
+      
+      const frames: Array<{ source: string; isRemote: boolean }> = [];
+      const frameDir = path.join(__dirname, 'frames');
 
   if (!fs.existsSync(frameDir)) {
       fs.mkdirSync(frameDir);
@@ -1064,10 +1657,14 @@ async extractFrames(videoSource: string | Buffer, options: ExtractFramesOptions)
       });
   }
 
-  return new Promise((resolve, reject) => {
-      processVideoExtraction(videoPath, frames, options, resolve, reject);
-  });
-}
+      return new Promise((resolve, reject) => {
+        processVideoExtraction(videoPath, frames, options, resolve, reject);
+      });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`extractFrames failed: ${errorMessage}`);
+    }
+  }
 
 
 
@@ -1077,13 +1674,45 @@ async extractFrames(videoSource: string | Buffer, options: ExtractFramesOptions)
   
 
 
-async masking(
-  source: string | Buffer | PathLike | Uint8Array, 
-  maskSource: string | Buffer | PathLike | Uint8Array, 
-  options: MaskOptions = { type: "alpha" }
-): Promise<Buffer> {
-  const img = await loadImage(source);
-  const mask = await loadImage(maskSource);
+  /**
+   * Validates masking inputs.
+   * @private
+   * @param source - Source image to validate
+   * @param maskSource - Mask image to validate
+   * @param options - Mask options to validate
+   */
+  #validateMaskingInputs(
+    source: string | Buffer | PathLike | Uint8Array,
+    maskSource: string | Buffer | PathLike | Uint8Array,
+    options: MaskOptions
+  ): void {
+    if (!source) {
+      throw new Error("masking: source is required.");
+    }
+    if (!maskSource) {
+      throw new Error("masking: maskSource is required.");
+    }
+    if (options.type && !['alpha', 'grayscale', 'color'].includes(options.type)) {
+      throw new Error("masking: type must be 'alpha', 'grayscale', or 'color'.");
+    }
+    if (options.type === 'color' && !options.colorKey) {
+      throw new Error("masking: colorKey is required when type is 'color'.");
+    }
+    if (options.threshold !== undefined && (typeof options.threshold !== 'number' || options.threshold < 0 || options.threshold > 255)) {
+      throw new Error("masking: threshold must be a number between 0 and 255.");
+    }
+  }
+
+  async masking(
+    source: string | Buffer | PathLike | Uint8Array, 
+    maskSource: string | Buffer | PathLike | Uint8Array, 
+    options: MaskOptions = { type: "alpha" }
+  ): Promise<Buffer> {
+    try {
+      this.#validateMaskingInputs(source, maskSource, options);
+      
+      const img = await loadImage(source);
+      const mask = await loadImage(maskSource);
 
   const canvas = createCanvas(img.width, img.height);
   const ctx = canvas.getContext("2d") as SKRSContext2D;
@@ -1115,21 +1744,58 @@ async masking(
 
       if (options.invert) alphaValue = 255 - alphaValue;
 
-      imgData.data[i + 3] = alphaValue;
-  }
+        imgData.data[i + 3] = alphaValue;
+      }
+
+      ctx.putImageData(imgData, 0, 0);
 
-  ctx.putImageData(imgData, 0, 0);
+      return canvas.toBuffer("image/png");
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`masking failed: ${errorMessage}`);
+    }
+  }
 
-  return canvas.toBuffer("image/png");
-}
+  /**
+   * Validates gradient blend inputs.
+   * @private
+   * @param source - Source image to validate
+   * @param options - Blend options to validate
+   */
+  #validateGradientBlendInputs(source: string | Buffer | PathLike | Uint8Array, options: BlendOptions): void {
+    if (!source) {
+      throw new Error("gradientBlend: source is required.");
+    }
+    if (!options || typeof options !== 'object') {
+      throw new Error("gradientBlend: options object is required.");
+    }
+    if (!options.colors || !Array.isArray(options.colors) || options.colors.length === 0) {
+      throw new Error("gradientBlend: options.colors array with at least one color stop is required.");
+    }
+    if (options.type && !['linear', 'radial', 'conic'].includes(options.type)) {
+      throw new Error("gradientBlend: type must be 'linear', 'radial', or 'conic'.");
+    }
+    for (const colorStop of options.colors) {
+      if (typeof colorStop.stop !== 'number' || colorStop.stop < 0 || colorStop.stop > 1) {
+        throw new Error("gradientBlend: Each color stop must have a stop value between 0 and 1.");
+      }
+      if (!colorStop.color || typeof colorStop.color !== 'string') {
+        throw new Error("gradientBlend: Each color stop must have a valid color string.");
+      }
+    }
+  }
 
-async gradientBlend(
-  source: string | Buffer | PathLike | Uint8Array, 
-  options: BlendOptions
-): Promise<Buffer> {
-  const img = await loadImage(source);
-  const canvas = createCanvas(img.width, img.height);
-  const ctx = canvas.getContext("2d") as SKRSContext2D;
+  async gradientBlend(
+    source: string | Buffer | PathLike | Uint8Array, 
+    options: BlendOptions
+  ): Promise<Buffer> {
+    try {
+      this.#validateGradientBlendInputs(source, options);
+      
+      const img = await loadImage(source);
+      const canvas = createCanvas(img.width, img.height);
+      const ctx = canvas.getContext("2d") as SKRSContext2D;
+      if (!ctx) throw new Error("Unable to get 2D context");
 
   ctx.drawImage(img, 0, 0, img.width, img.height);
 
@@ -1162,38 +1828,78 @@ async gradientBlend(
       ctx.drawImage(mask, 0, 0, img.width, img.height);
   }
 
-  ctx.globalCompositeOperation = "source-over";
+      ctx.globalCompositeOperation = "source-over";
+
+      return canvas.toBuffer("image/png");
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`gradientBlend failed: ${errorMessage}`);
+    }
+  }
 
-  return canvas.toBuffer("image/png");
-}
+  /**
+   * Validates animate inputs.
+   * @private
+   * @param frames - Animation frames to validate
+   * @param defaultDuration - Default duration to validate
+   * @param defaultWidth - Default width to validate
+   * @param defaultHeight - Default height to validate
+   * @param options - Animation options to validate
+   */
+  #validateAnimateInputs(
+    frames: Frame[],
+    defaultDuration: number,
+    defaultWidth: number,
+    defaultHeight: number,
+    options?: { gif?: boolean; gifPath?: string; onStart?: () => void; onFrame?: (index: number) => void; onEnd?: () => void }
+  ): void {
+    if (!frames || !Array.isArray(frames) || frames.length === 0) {
+      throw new Error("animate: frames array with at least one frame is required.");
+    }
+    if (typeof defaultDuration !== 'number' || defaultDuration < 0) {
+      throw new Error("animate: defaultDuration must be a non-negative number.");
+    }
+    if (typeof defaultWidth !== 'number' || defaultWidth <= 0) {
+      throw new Error("animate: defaultWidth must be a positive number.");
+    }
+    if (typeof defaultHeight !== 'number' || defaultHeight <= 0) {
+      throw new Error("animate: defaultHeight must be a positive number.");
+    }
+    if (options?.gif && !options.gifPath) {
+      throw new Error("animate: gifPath is required when gif is enabled.");
+    }
+  }
 
-async animate(
-  frames: Frame[],
-  defaultDuration: number, 
-  defaultWidth: number = 800,
-  defaultHeight: number = 600, 
-  options?: {
+  async animate(
+    frames: Frame[],
+    defaultDuration: number, 
+    defaultWidth: number = 800,
+    defaultHeight: number = 600, 
+    options?: {
       gif?: boolean;  
       gifPath?: string;  
       onStart?: () => void;
       onFrame?: (index: number) => void;
       onEnd?: () => void;
-  }
-): Promise<Buffer[] | undefined> {
-  const buffers: Buffer[] = [];
-  const isNode = typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
+    }
+  ): Promise<Buffer[] | undefined> {
+    try {
+      this.#validateAnimateInputs(frames, defaultDuration, defaultWidth, defaultHeight, options);
+      
+      const buffers: Buffer[] = [];
+      const isNode = typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
 
-  if (options?.onStart) options.onStart();
+      if (options?.onStart) options.onStart();
 
-  let encoder: GIFEncoder | null = null;
-  let gifStream: fs.WriteStream | null = null;
+      let encoder: GIFEncoder | null = null;
+      let gifStream: fs.WriteStream | null = null;
 
-  if (options?.gif) {
-      if (!options.gifPath) {
-          throw new Error("GIF generation enabled but no gifPath provided.");
-      }
-      encoder = new GIFEncoder(defaultWidth, defaultHeight);
-      gifStream = fs.createWriteStream(options.gifPath);
+      if (options?.gif) {
+        if (!options.gifPath) {
+          throw new Error("animate: gifPath is required when gif is enabled.");
+        }
+        encoder = new GIFEncoder(defaultWidth, defaultHeight);
+        gifStream = fs.createWriteStream(options.gifPath);
       encoder.createReadStream().pipe(gifStream);
       encoder.start();
       encoder.setRepeat(0); 
@@ -1298,40 +2004,395 @@ async animate(
       encoder.finish();
   }
 
-  if (options?.onEnd) options.onEnd();
+      if (options?.onEnd) options.onEnd();
 
-  return options?.gif ? undefined : buffers;
-}
+      return options?.gif ? undefined : buffers;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`animate failed: ${errorMessage}`);
+    }
+  }
 
 
 
-public validHex(hexColor: string): any {
+  /**
+   * Processes multiple operations in parallel
+   * @param operations - Array of operations to process
+   * @returns Array of result buffers
+   */
+  async batch(operations: BatchOperation[]): Promise<Buffer[]> {
+    try {
+      return await batchOperations(this, operations);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`batch failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Chains multiple operations sequentially
+   * @param operations - Array of operations to chain
+   * @returns Final result buffer
+   */
+  async chain(operations: ChainOperation[]): Promise<Buffer> {
+    try {
+      return await chainOperations(this, operations);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`chain failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Stitches multiple images together
+   * @param images - Array of image sources
+   * @param options - Stitching options
+   * @returns Stitched image buffer
+   */
+  async stitchImages(images: Array<string | Buffer>, options?: StitchOptions): Promise<Buffer> {
+    try {
+      if (!images || images.length === 0) {
+        throw new Error("stitchImages: images array is required");
+      }
+      return await stitchImagesUtil(images, options);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`stitchImages failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Creates an image collage
+   * @param images - Array of image sources with optional dimensions
+   * @param layout - Collage layout configuration
+   * @returns Collage image buffer
+   */
+  async createCollage(
+    images: Array<{ source: string | Buffer; width?: number; height?: number }>,
+    layout: CollageLayout
+  ): Promise<Buffer> {
+    try {
+      if (!images || images.length === 0) {
+        throw new Error("createCollage: images array is required");
+      }
+      if (!layout) {
+        throw new Error("createCollage: layout configuration is required");
+      }
+      return await createCollage(images, layout);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`createCollage failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Compresses an image with quality control
+   * @param image - Image source (path, URL, or Buffer)
+   * @param options - Compression options
+   * @returns Compressed image buffer
+   */
+  async compress(image: string | Buffer, options?: CompressionOptions): Promise<Buffer> {
+    try {
+      if (!image) {
+        throw new Error("compress: image is required");
+      }
+      return await compressImage(image, options);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`compress failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Extracts color palette from an image
+   * @param image - Image source (path, URL, or Buffer)
+   * @param options - Palette extraction options
+   * @returns Array of colors with percentages
+   */
+  async extractPalette(image: string | Buffer, options?: PaletteOptions): Promise<Array<{ color: string; percentage: number }>> {
+    try {
+      if (!image) {
+        throw new Error("extractPalette: image is required");
+      }
+      return await extractPaletteUtil(image, options);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`extractPalette failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Validates a hexadecimal color string.
+   * @param hexColor - Hexadecimal color string to validate (format: #RRGGBB)
+   * @returns True if the color is valid
+   * @throws Error if the color format is invalid
+   * 
+   * @example
+   * ```typescript
+   * painter.validHex('#ff0000'); // true
+   * painter.validHex('#FF00FF'); // true
+   * painter.validHex('invalid'); // throws Error
+   * ```
+   */
+  public validHex(hexColor: string): boolean {
+    if (typeof hexColor !== 'string') {
+      throw new Error("validHex: hexColor must be a string.");
+    }
     const hexPattern = /^#[0-9a-fA-F]{6}$/;
     if (!hexPattern.test(hexColor)) {
-        throw new Error("Invalid hexadecimal color format. It should be in the format '#RRGGBB'.");
-    }
-    return true
-  }
-
-  public async outPut(results: any): Promise< void | Buffer | string | Blob | Object | HTMLCanvasElement> {
-
-    const formatType: string = this.format?.type || 'buffer';
-    switch (formatType) {
-      case 'buffer':
-        return results;
-      case 'url':
-        return await url(results);
-      case 'dataURL':
-        return dataURL(results);
-      case 'blob':
-        return blob(results);
-      case 'base64':
-        return base64(results);
-      case 'arraybuffer':
-        return arrayBuffer(results);
-      default:
-        throw new Error('Unsupported format');
+      throw new Error("validHex: Invalid hexadecimal color format. It should be in the format '#RRGGBB'.");
     }
+    return true;
+  }
+
+  /**
+   * Converts results to the configured output format.
+   * @param results - Buffer or result to convert
+   * @returns Converted result in the configured format
+   * @throws Error if format is unsupported or conversion fails
+   * 
+   * @example
+   * ```typescript
+   * const painter = new ApexPainter({ type: 'base64' });
+   * const result = await painter.createCanvas({ width: 100, height: 100 });
+   * const base64String = await painter.outPut(result.buffer); // Returns base64 string
+   * ```
+   */
+  public async outPut(results: Buffer): Promise<Buffer | string | Blob | ArrayBuffer> {
+    try {
+      if (!Buffer.isBuffer(results)) {
+        throw new Error("outPut: results must be a Buffer.");
+      }
+      
+      const formatType: string = this.format?.type || 'buffer';
+      switch (formatType) {
+        case 'buffer':
+          return results;
+        case 'url':
+          return await url(results);
+        case 'dataURL':
+          return dataURL(results);
+        case 'blob':
+          return blob(results);
+        case 'base64':
+          return base64(results);
+        case 'arraybuffer':
+          return arrayBuffer(results);
+        default:
+          throw new Error(`outPut: Unsupported format '${formatType}'. Supported: buffer, url, dataURL, blob, base64, arraybuffer`);
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`outPut failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Advanced save method to save buffers to local files with extensive customization options.
+   * 
+   * @param buffer - Buffer to save (from createCanvas, createImage, createText, etc.)
+   * @param options - Save options for file path, format, naming, etc.
+   * @returns SaveResult with file path, name, size, and format
+   * 
+   * @example
+   * ```typescript
+   * // Simple save with auto-generated name
+   * const canvas = await painter.createCanvas({ width: 800, height: 600 });
+   * const result = await painter.save(canvas.buffer);
+   * // Saves to: ./ApexPainter_output/20241220_143025_123.png
+   * 
+   * // Custom filename and directory
+   * await painter.save(canvas.buffer, {
+   *   directory: './my-images',
+   *   filename: 'my-canvas',
+   *   format: 'jpg',
+   *   quality: 95
+   * });
+   * 
+   * // Save with counter naming
+   * await painter.save(canvas.buffer, {
+   *   naming: 'counter',
+   *   prefix: 'image-',
+   *   counterStart: 1
+   * });
+   * // Saves to: ./ApexPainter_output/image-1.png, image-2.png, etc.
+   * 
+   * // Save multiple buffers
+   * const buffers = [canvas1.buffer, canvas2.buffer, canvas3.buffer];
+   * const results = await painter.saveMultiple(buffers, {
+   *   prefix: 'batch-',
+   *   naming: 'counter'
+   * });
+   * ```
+   */
+  public async save(buffer: Buffer, options?: SaveOptions): Promise<SaveResult> {
+    try {
+      if (!Buffer.isBuffer(buffer)) {
+        throw new Error("save: buffer must be a Buffer.");
+      }
+
+      const opts: Required<Omit<SaveOptions, 'filename' | 'counterStart'>> & { filename?: string; counterStart?: number } = {
+        directory: options?.directory ?? './ApexPainter_output',
+        filename: options?.filename,
+        format: options?.format ?? 'png',
+        quality: options?.quality ?? 90,
+        createDirectory: options?.createDirectory ?? true,
+        naming: options?.naming ?? 'timestamp',
+        counterStart: options?.counterStart ?? 1,
+        prefix: options?.prefix ?? '',
+        suffix: options?.suffix ?? '',
+        overwrite: options?.overwrite ?? false
+      };
+
+      // Create directory if needed
+      if (opts.createDirectory && !fs.existsSync(opts.directory)) {
+        fs.mkdirSync(opts.directory, { recursive: true });
+      }
+
+      // Generate filename
+      let filename: string;
+      if (opts.filename) {
+        filename = opts.filename;
+        // Add extension if not present
+        if (!filename.includes('.')) {
+          filename += `.${opts.format}`;
+        }
+      } else {
+        // Auto-generate filename based on naming pattern
+        switch (opts.naming) {
+          case 'timestamp':
+            const now = new Date();
+            const timestamp = `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}_${String(now.getHours()).padStart(2, '0')}${String(now.getMinutes()).padStart(2, '0')}${String(now.getSeconds()).padStart(2, '0')}_${String(now.getMilliseconds()).padStart(3, '0')}`;
+            filename = `${opts.prefix}${timestamp}${opts.suffix}.${opts.format}`;
+            break;
+          case 'counter':
+            filename = `${opts.prefix}${this.saveCounter}${opts.suffix}.${opts.format}`;
+            this.saveCounter++;
+            break;
+          case 'custom':
+            filename = `${opts.prefix}${opts.suffix}.${opts.format}`;
+            break;
+          default:
+            filename = `${opts.prefix}${Date.now()}${opts.suffix}.${opts.format}`;
+        }
+      }
+
+      // Handle file overwrite
+      const filePath = path.join(opts.directory, filename);
+      if (!opts.overwrite && fs.existsSync(filePath)) {
+        // Add number suffix if file exists
+        let counter = 1;
+        let newPath = filePath;
+        const ext = path.extname(filePath);
+        const baseName = path.basename(filePath, ext);
+        const dir = path.dirname(filePath);
+        
+        while (fs.existsSync(newPath)) {
+          newPath = path.join(dir, `${baseName}_${counter}${ext}`);
+          counter++;
+        }
+        filename = path.basename(newPath);
+      }
+
+      // Convert buffer format if needed
+      let finalBuffer = buffer;
+      if (opts.format !== 'png') {
+        // Use Sharp for format conversion
+        const sharp = require('sharp');
+        let sharpImage = sharp(buffer);
+        
+        switch (opts.format) {
+          case 'jpg':
+          case 'jpeg':
+            finalBuffer = await sharpImage
+              .jpeg({ quality: opts.quality, progressive: false })
+              .toBuffer();
+            break;
+          case 'webp':
+            finalBuffer = await sharpImage
+              .webp({ quality: opts.quality })
+              .toBuffer();
+            break;
+          case 'avif':
+            finalBuffer = await sharpImage
+              .avif({ quality: opts.quality })
+              .toBuffer();
+            break;
+          case 'gif':
+            // GIF requires special handling - keep as PNG if not already GIF
+            if (!buffer.toString('ascii', 0, 3).includes('GIF')) {
+              console.warn('save: Converting to GIF may not preserve quality. Consider using PNG.');
+              finalBuffer = buffer; // Keep original for now
+            }
+            break;
+        }
+      }
+
+      // Write file
+      const finalPath = path.join(opts.directory, filename);
+      fs.writeFileSync(finalPath, finalBuffer);
+
+      return {
+        path: finalPath,
+        filename: filename,
+        size: finalBuffer.length,
+        format: opts.format
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`save failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Save multiple buffers at once with batch options.
+   * 
+   * @param buffers - Array of buffers to save
+   * @param options - Save options (applied to all files)
+   * @returns Array of SaveResult objects
+   * 
+   * @example
+   * ```typescript
+   * const canvas1 = await painter.createCanvas({ width: 800, height: 600 });
+   * const canvas2 = await painter.createCanvas({ width: 800, height: 600 });
+   * const results = await painter.saveMultiple([canvas1.buffer, canvas2.buffer], {
+   *   prefix: 'batch-',
+   *   naming: 'counter'
+   * });
+   * ```
+   */
+  public async saveMultiple(buffers: Buffer[], options?: SaveOptions): Promise<SaveResult[]> {
+    try {
+      if (!Array.isArray(buffers) || buffers.length === 0) {
+        throw new Error("saveMultiple: buffers must be a non-empty array.");
+      }
+
+      const results: SaveResult[] = [];
+      const baseCounter = options?.counterStart ?? this.saveCounter;
+
+      for (let i = 0; i < buffers.length; i++) {
+        const bufferOptions: SaveOptions = {
+          ...options,
+          counterStart: baseCounter + i,
+          naming: options?.naming === 'counter' ? 'counter' : options?.naming
+        };
+        
+        const result = await this.save(buffers[i], bufferOptions);
+        results.push(result);
+      }
+
+      return results;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      throw new Error(`saveMultiple failed: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Reset the save counter (useful when using 'counter' naming).
+   */
+  public resetSaveCounter(): void {
+    this.saveCounter = 1;
   }
 
   /**