apexify.js 4.9.30 → 5.0.1

package/dist/cjs/Canvas/ApexPainter.js

@@ -16,6 +16,7 @@ const enhancedTextRenderer_1 = require("./utils/Texts/enhancedTextRenderer");
 const enhancedPatternRenderer_1 = require("./utils/Patterns/enhancedPatternRenderer");
 class ApexPainter {
     format;
+    saveCounter = 1;
     constructor({ type } = { type: 'buffer' }) {
         this.format = { type: type || 'buffer' };
     }
@@ -46,7 +47,13 @@ class ApexPainter {
      * @param textProps - Text properties
      */
     async #renderEnhancedText(ctx, textProps) {
-        await enhancedTextRenderer_1.EnhancedTextRenderer.renderText(ctx, textProps);
+        // Check if text should be rendered on a path
+        if (textProps.path && textProps.textOnPath) {
+            (0, utils_1.renderTextOnPath)(ctx, textProps.text, textProps.path, textProps.path.offset ?? 0);
+        }
+        else {
+            await enhancedTextRenderer_1.EnhancedTextRenderer.renderText(ctx, textProps);
+        }
     }
     /**
      * Creates a canvas with the given configuration.
@@ -79,75 +86,162 @@ class ApexPainter {
      * const buffer = result.buffer;
      * ```
      */
+    /**
+     * Validates canvas configuration.
+     * @private
+     * @param canvas - Canvas configuration to validate
+     */
+    #validateCanvasConfig(canvas) {
+        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) {
-        // Handle inherit sizing
-        if (canvas.customBg?.inherit) {
-            let p = canvas.customBg.source;
-            if (!/^https?:\/\//i.test(p))
-                p = path_1.default.join(process.cwd(), p);
-            try {
-                const img = await (0, canvas_1.loadImage)(p);
-                canvas.width = img.width;
-                canvas.height = img.height;
-            }
-            catch (e) {
-                console.error('inherit load failed:', e?.message ?? e);
-            }
-        }
-        // 2) Use final width/height after inherit
-        const width = canvas.width ?? 500;
-        const height = canvas.height ?? 500;
-        const { x = 0, y = 0, rotation = 0, borderRadius = 0, borderPosition = 'all', opacity = 1, colorBg, customBg, gradientBg, patternBg, noiseBg, blendMode, zoom, stroke, shadow, blur } = canvas;
-        // Validate background configuration
-        const bgSources = [
-            canvas.colorBg ? 'colorBg' : null,
-            canvas.gradientBg ? 'gradientBg' : null,
-            canvas.customBg ? 'customBg' : null
-        ].filter(Boolean);
-        if (bgSources.length > 1) {
-            throw new Error(`createCanvas: only one of colorBg, gradientBg, or customBg can be used. You provided: ${bgSources.join(', ')}`);
-        }
-        const cv = (0, canvas_1.createCanvas)(width, height);
-        const ctx = cv.getContext('2d');
-        if (!ctx)
-            throw new Error('Unable to get 2D context');
-        ctx.globalAlpha = opacity;
-        // ---- BACKGROUND (clipped) ----
-        ctx.save();
-        (0, utils_1.applyRotation)(ctx, rotation, x, y, width, height);
-        (0, utils_1.buildPath)(ctx, x, y, width, height, borderRadius, borderPosition);
-        ctx.clip();
-        (0, utils_1.applyCanvasZoom)(ctx, width, height, zoom);
-        ctx.translate(x, y);
-        if (typeof blendMode === 'string') {
-            ctx.globalCompositeOperation = blendMode;
-        }
-        if (customBg)
-            await (0, utils_1.customBackground)(ctx, { ...canvas, blur });
-        else if (gradientBg)
-            await (0, utils_1.drawBackgroundGradient)(ctx, { ...canvas, blur });
-        else
-            await (0, utils_1.drawBackgroundColor)(ctx, { ...canvas, blur, colorBg: colorBg ?? '#000' });
-        if (patternBg)
-            await enhancedPatternRenderer_1.EnhancedPatternRenderer.renderPattern(ctx, cv, patternBg);
-        if (noiseBg)
-            (0, utils_1.applyNoise)(ctx, width, height, noiseBg.intensity ?? 0.05);
-        ctx.restore();
-        // Apply shadow effect
-        if (shadow) {
+        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_1.default.join(process.cwd(), p);
+                try {
+                    const img = await (0, canvas_1.loadImage)(p);
+                    canvas.width = img.width;
+                    canvas.height = img.height;
+                }
+                catch (e) {
+                    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 (0, canvas_1.loadImage)(frameBuffer);
+                        if (!canvas.width)
+                            canvas.width = img.width;
+                        if (!canvas.height)
+                            canvas.height = img.height;
+                    }
+                }
+                catch (e) {
+                    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;
+            const { x = 0, y = 0, rotation = 0, borderRadius = 0, borderPosition = 'all', opacity = 1, colorBg, customBg, gradientBg, videoBg, patternBg, noiseBg, blendMode, zoom, stroke, shadow, blur } = canvas;
+            // Validate background configuration
+            const bgSources = [
+                canvas.colorBg ? 'colorBg' : null,
+                canvas.gradientBg ? 'gradientBg' : null,
+                canvas.customBg ? 'customBg' : null
+            ].filter(Boolean);
+            if (bgSources.length > 1) {
+                throw new Error(`createCanvas: only one of colorBg, gradientBg, or customBg can be used. You provided: ${bgSources.join(', ')}`);
+            }
+            const cv = (0, canvas_1.createCanvas)(width, height);
+            const ctx = cv.getContext('2d');
+            if (!ctx)
+                throw new Error('Unable to get 2D context');
+            ctx.globalAlpha = opacity;
+            // ---- BACKGROUND (clipped) ----
             ctx.save();
+            (0, utils_1.applyRotation)(ctx, rotation, x, y, width, height);
             (0, utils_1.buildPath)(ctx, x, y, width, height, borderRadius, borderPosition);
-            (0, utils_1.applyShadow)(ctx, shadow, x, y, width, height);
+            ctx.clip();
+            (0, utils_1.applyCanvasZoom)(ctx, width, height, zoom);
+            ctx.translate(x, y);
+            if (typeof blendMode === 'string') {
+                ctx.globalCompositeOperation = blendMode;
+            }
+            // Draw video background if specified
+            if (videoBg) {
+                try {
+                    const frameBuffer = await this.#extractVideoFrame(videoBg.source, videoBg.frame ?? 0);
+                    if (frameBuffer) {
+                        const videoImg = await (0, canvas_1.loadImage)(frameBuffer);
+                        ctx.globalAlpha = videoBg.opacity ?? 1;
+                        ctx.drawImage(videoImg, 0, 0, width, height);
+                        ctx.globalAlpha = opacity;
+                    }
+                }
+                catch (e) {
+                    console.warn('createCanvas: Failed to load video background frame');
+                }
+            }
+            // Draw custom background with filters and opacity support
+            if (customBg) {
+                await (0, utils_1.customBackground)(ctx, { ...canvas, blur });
+                // Apply filters to background if specified
+                if (customBg.filters && customBg.filters.length > 0) {
+                    const tempCanvas = (0, canvas_1.createCanvas)(width, height);
+                    const tempCtx = tempCanvas.getContext('2d');
+                    if (tempCtx) {
+                        tempCtx.drawImage(cv, 0, 0);
+                        await (0, utils_1.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 (0, utils_1.customBackground)(ctx, { ...canvas, blur });
+                    ctx.globalAlpha = opacity;
+                }
+                else {
+                    await (0, utils_1.customBackground)(ctx, { ...canvas, blur });
+                }
+            }
+            else if (gradientBg) {
+                await (0, utils_1.drawBackgroundGradient)(ctx, { ...canvas, blur });
+            }
+            else {
+                await (0, utils_1.drawBackgroundColor)(ctx, { ...canvas, blur, colorBg: colorBg ?? '#000' });
+            }
+            if (patternBg)
+                await enhancedPatternRenderer_1.EnhancedPatternRenderer.renderPattern(ctx, cv, patternBg);
+            if (noiseBg)
+                (0, utils_1.applyNoise)(ctx, width, height, noiseBg.intensity ?? 0.05);
             ctx.restore();
+            // Apply shadow effect
+            if (shadow) {
+                ctx.save();
+                (0, utils_1.buildPath)(ctx, x, y, width, height, borderRadius, borderPosition);
+                (0, utils_1.applyShadow)(ctx, shadow, x, y, width, height);
+                ctx.restore();
+            }
+            // Apply stroke effect
+            if (stroke) {
+                ctx.save();
+                (0, utils_1.buildPath)(ctx, x, y, width, height, borderRadius, borderPosition);
+                (0, utils_1.applyStroke)(ctx, stroke, x, y, width, height);
+                ctx.restore();
+            }
+            return { buffer: cv.toBuffer('image/png'), canvas };
         }
-        // Apply stroke effect
-        if (stroke) {
-            ctx.save();
-            (0, utils_1.buildPath)(ctx, x, y, width, height, borderRadius, borderPosition);
-            (0, utils_1.applyStroke)(ctx, stroke, x, y, width, height);
-            ctx.restore();
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            throw new Error(`createCanvas failed: ${errorMessage}`);
         }
-        return { buffer: cv.toBuffer('image/png'), canvas };
     }
     /**
      * Draws one or more images (or shapes) on an existing canvas buffer.
@@ -191,24 +285,49 @@ class ApexPainter {
      * ], canvasBuffer);
      * ```
      */
-    async createImage(images, canvasBuffer) {
+    /**
+     * Validates image/shape properties array.
+     * @private
+     * @param images - Image properties to validate
+     */
+    #validateImageArray(images) {
         const list = Array.isArray(images) ? images : [images];
-        // Load base canvas buffer
-        const base = Buffer.isBuffer(canvasBuffer)
-            ? await (0, canvas_1.loadImage)(canvasBuffer)
-            : await (0, canvas_1.loadImage)(canvasBuffer.buffer);
-        const cv = (0, canvas_1.createCanvas)(base.width, base.height);
-        const ctx = cv.getContext("2d");
-        if (!ctx)
-            throw new Error("Unable to get 2D rendering context");
-        // Paint bg
-        ctx.drawImage(base, 0, 0);
-        // Draw each image/shape on canvas
+        if (list.length === 0) {
+            throw new Error("createImage: At least one image/shape is required.");
+        }
         for (const ip of list) {
-            await this.#drawImageBitmap(ctx, ip);
+            this.#validateImageProperties(ip);
+        }
+    }
+    async createImage(images, canvasBuffer) {
+        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 = Buffer.isBuffer(canvasBuffer)
+                ? await (0, canvas_1.loadImage)(canvasBuffer)
+                : await (0, canvas_1.loadImage)(canvasBuffer.buffer);
+            const cv = (0, canvas_1.createCanvas)(base.width, base.height);
+            const ctx = cv.getContext("2d");
+            if (!ctx)
+                throw new Error("Unable to get 2D rendering context");
+            // Paint bg
+            ctx.drawImage(base, 0, 0);
+            // Draw each image/shape on canvas
+            for (const ip of list) {
+                await this.#drawImageBitmap(ctx, ip);
+            }
+            // 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}`);
         }
-        // Return updated buffer
-        return cv.toBuffer("image/png");
     }
     /**
      * Draws a single bitmap or shape with independent shadow & stroke.
@@ -217,7 +336,7 @@ class ApexPainter {
      * @param ip - Image properties
      */
     async #drawImageBitmap(ctx, ip) {
-        const { source, x, y, width, height, inherit, fit = "fill", align = "center", rotation = 0, opacity = 1, blur = 0, borderRadius = 0, borderPosition = "all", shadow, stroke, boxBackground, shape, filters } = ip;
+        const { source, x, y, width, height, inherit, fit = "fill", align = "center", rotation = 0, opacity = 1, blur = 0, borderRadius = 0, borderPosition = "all", shadow, stroke, boxBackground, shape, filters, filterIntensity = 1, filterOrder = 'post', mask, clipPath, distortion, meshWarp, effects } = ip;
         this.#validateImageProperties(ip);
         // Check if source is a shape
         if ((0, utils_1.isShapeSource)(source)) {
@@ -248,23 +367,126 @@ class ApexPainter {
         (0, utils_1.applyShadow)(ctx, box, shadow);
         // 2) Optional box background (under bitmap, inside clip) — color or gradient
         (0, utils_1.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();
-        (0, utils_1.buildPath)(ctx, box.x, box.y, box.w, box.h, borderRadius, borderPosition);
-        ctx.clip();
+        if (clipPath && clipPath.length >= 3) {
+            (0, utils_1.applyClipPath)(ctx, clipPath);
+        }
+        else {
+            (0, utils_1.buildPath)(ctx, box.x, box.y, box.w, box.h, borderRadius, borderPosition);
+            ctx.clip();
+        }
         const { dx, dy, dw, dh, sx, sy, sw, sh } = (0, utils_1.fitInto)(box.x, box.y, box.w, box.h, img.width, img.height, fit, align);
         const prevAlpha = ctx.globalAlpha;
         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 (0, utils_1.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 (0, utils_1.applySimpleProfessionalFilters)(ctx, adjustedFilters, dw, dh);
+        }
+        // Apply distortion if specified (before drawing)
+        if (distortion) {
+            if (distortion.type === 'perspective' && distortion.points && distortion.points.length === 4) {
+                (0, utils_1.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);
+                (0, utils_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) {
+            (0, utils_1.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 (0, utils_1.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.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 = (0, canvas_1.createCanvas)(box.w, box.h);
+            const tempCtx = tempCanvas.getContext('2d');
+            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 (0, utils_1.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) {
+                (0, utils_1.applyVignette)(effectsCtx, effects.vignette.intensity, effects.vignette.size, box.w, box.h);
+            }
+            if (effects.lensFlare) {
+                (0, utils_1.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 = (0, canvas_1.createCanvas)(box.w, box.h);
+                const tempCtx = tempCanvas.getContext('2d');
+                if (tempCtx) {
+                    tempCtx.putImageData(imageData, 0, 0);
+                    (0, utils_1.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 = (0, canvas_1.createCanvas)(box.w, box.h);
+                const tempCtx = tempCanvas.getContext('2d');
+                if (tempCtx) {
+                    tempCtx.putImageData(imageData, 0, 0);
+                    (0, utils_1.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
         (0, utils_1.applyStroke)(ctx, box, stroke);
         ctx.restore();
@@ -488,14 +710,29 @@ class ApexPainter {
      * ], canvasBuffer);
      * ```
      */
+    /**
+     * Validates text properties array.
+     * @private
+     * @param textArray - Text properties to validate
+     */
+    #validateTextArray(textArray) {
+        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, canvasBuffer) {
         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;
             if (Buffer.isBuffer(canvasBuffer)) {
@@ -525,15 +762,37 @@ class ApexPainter {
             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}`);
+        }
+    }
+    /**
+     * Validates custom line options.
+     * @private
+     * @param options - Custom options to validate
+     */
+    #validateCustomOptions(options) {
+        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.");
+            }
         }
     }
     async createCustom(options, buffer) {
         try {
-            if (!Array.isArray(options)) {
-                options = [options];
+            // Validate inputs
+            if (!buffer) {
+                throw new Error("createCustom: buffer is required.");
             }
+            this.#validateCustomOptions(options);
+            const opts = Array.isArray(options) ? options : [options];
             let existingImage;
             if (Buffer.isBuffer(buffer)) {
                 existingImage = await (0, canvas_1.loadImage)(buffer);
@@ -550,65 +809,68 @@ class ApexPainter {
             const canvas = (0, canvas_1.createCanvas)(existingImage.width, existingImage.height);
             const ctx = canvas.getContext("2d");
             ctx.drawImage(existingImage, 0, 0);
-            (0, utils_1.customLines)(ctx, options);
+            await (0, utils_1.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, options) {
-        async function resizeImage(image, targetWidth, targetHeight) {
-            const canvas = (0, canvas_1.createCanvas)(targetWidth, targetHeight);
-            const ctx = canvas.getContext("2d");
-            ctx.drawImage(image, 0, 0, targetWidth, targetHeight);
-            return canvas;
-        }
-        function createOutputStream(outputFile) {
-            return fs_1.default.createWriteStream(outputFile);
-        }
-        function createBufferStream() {
-            const bufferStream = new stream_1.PassThrough();
-            const chunks = [];
-            bufferStream.on('data', (chunk) => {
-                chunks.push(chunk);
-            });
-            return {
-                ...bufferStream,
-                getBuffer: function () {
-                    return Buffer.concat(chunks);
-                }
-            };
+    /**
+     * Validates GIF options and frames.
+     * @private
+     * @param gifFrames - GIF frames to validate
+     * @param options - GIF options to validate
+     */
+    #validateGIFOptions(gifFrames, options) {
+        if (!gifFrames || gifFrames.length === 0) {
+            throw new Error("createGIF: At least one frame is required.");
         }
-        function validateOptions(options) {
-            if (options.outputFormat === "file" && !options.outputFile) {
-                throw new Error("Output file path is required when using file output format.");
+        for (const frame of gifFrames) {
+            if (!frame.background) {
+                throw new Error("createGIF: Each frame must have a background property.");
             }
-            if (options.repeat !== undefined && (typeof options.repeat !== "number" || options.repeat < 0)) {
-                throw new Error("Repeat must be a non-negative number or undefined.");
+            if (typeof frame.duration !== 'number' || frame.duration < 0) {
+                throw new Error("createGIF: Each frame duration must be a non-negative number.");
             }
-            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.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, options) {
+        try {
+            this.#validateGIFOptions(gifFrames, options);
+            async function resizeImage(image, targetWidth, targetHeight) {
+                const canvas = (0, canvas_1.createCanvas)(targetWidth, targetHeight);
+                const ctx = canvas.getContext("2d");
+                ctx.drawImage(image, 0, 0, targetWidth, targetHeight);
+                return canvas;
             }
-            if (options.watermark && typeof options.watermark.enable !== "boolean") {
-                throw new Error("Watermark must be a boolean or undefined.");
+            function createOutputStream(outputFile) {
+                return fs_1.default.createWriteStream(outputFile);
             }
-            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.");
-                }
+            function createBufferStream() {
+                const bufferStream = new stream_1.PassThrough();
+                const chunks = [];
+                bufferStream.on('data', (chunk) => {
+                    chunks.push(chunk);
+                });
+                return {
+                    ...bufferStream,
+                    getBuffer: function () {
+                        return Buffer.concat(chunks);
+                    }
+                };
             }
-        }
-        try {
-            validateOptions(options);
+            // Validation is done in #validateGIFOptions
             const canvasWidth = options.width || 1200;
             const canvasHeight = options.height || 1200;
             const encoder = new gifencoder_1.default(canvasWidth, canvasHeight);
@@ -619,6 +881,8 @@ class ApexPainter {
             encoder.setQuality(options.quality || 10);
             const canvas = (0, canvas_1.createCanvas)(canvasWidth, canvasHeight);
             const ctx = canvas.getContext("2d");
+            if (!ctx)
+                throw new Error("Unable to get 2D context");
             for (const frame of gifFrames) {
                 const image = await (0, canvas_1.loadImage)(frame.background);
                 const resizedImage = await resizeImage(image, canvasWidth, canvasHeight);
@@ -639,12 +903,13 @@ class ApexPainter {
             encoder.finish();
             outputStream.end();
             if (options.outputFormat === "file") {
-                await new Promise((resolve) => outputStream.on("finish", resolve));
+                await new Promise((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();
@@ -654,42 +919,204 @@ class ApexPainter {
                 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) {
-            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) {
+        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) {
-        return (0, utils_1.resizingImg)(resizeOptions);
+        try {
+            this.#validateResizeOptions(resizeOptions);
+            return await (0, utils_1.resizingImg)(resizeOptions);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            throw new Error(`resize failed: ${errorMessage}`);
+        }
+    }
+    /**
+     * Validates image converter inputs.
+     * @private
+     * @param source - Image source to validate
+     * @param newExtension - Extension to validate
+     */
+    #validateConverterInputs(source, newExtension) {
+        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 imgConverter(source, newExtension) {
-        return (0, utils_1.converter)(source, newExtension);
+        try {
+            this.#validateConverterInputs(source, newExtension);
+            return await (0, utils_1.converter)(source, newExtension);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            throw new Error(`imgConverter failed: ${errorMessage}`);
+        }
+    }
+    /**
+     * Validates effects inputs.
+     * @private
+     * @param source - Image source to validate
+     * @param filters - Filters array to validate
+     */
+    #validateEffectsInputs(source, filters) {
+        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 effects(source, filters) {
-        return (0, utils_1.imgEffects)(source, filters);
+        try {
+            this.#validateEffectsInputs(source, filters);
+            return await (0, utils_1.imgEffects)(source, filters);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            throw new Error(`effects failed: ${errorMessage}`);
+        }
+    }
+    /**
+     * Validates color filter inputs.
+     * @private
+     * @param source - Image source to validate
+     * @param opacity - Opacity to validate
+     */
+    #validateColorFilterInputs(source, opacity) {
+        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 colorsFilter(source, filterColor, opacity) {
-        return (0, utils_1.applyColorFilters)(source, filterColor, opacity);
+        try {
+            this.#validateColorFilterInputs(source, opacity);
+            return await (0, utils_1.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) {
-        return (0, utils_1.detectColors)(source);
+        try {
+            if (!source) {
+                throw new Error("colorAnalysis: source is required.");
+            }
+            return await (0, utils_1.detectColors)(source);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            throw new Error(`colorAnalysis failed: ${errorMessage}`);
+        }
     }
     async colorsRemover(source, colorToRemove) {
-        return (0, utils_1.removeColor)(source, colorToRemove);
+        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 (0, utils_1.removeColor)(source, colorToRemove);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            throw new Error(`colorsRemover failed: ${errorMessage}`);
+        }
     }
     async removeBackground(imageURL, apiKey) {
-        return (0, utils_1.bgRemoval)(imageURL, apiKey);
+        try {
+            if (!imageURL) {
+                throw new Error("removeBackground: imageURL is required.");
+            }
+            if (!apiKey) {
+                throw new Error("removeBackground: apiKey is required.");
+            }
+            return await (0, utils_1.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, baseImageBuffer) {
+        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, baseImageBuffer, defaultBlendMode = 'source-over') {
         try {
+            this.#validateBlendInputs(layers, baseImageBuffer);
             const baseImage = await (0, canvas_1.loadImage)(baseImageBuffer);
             const canvas = (0, canvas_1.createCanvas)(baseImage.width, baseImage.height);
             const ctx = canvas.getContext('2d');
+            if (!ctx)
+                throw new Error("Unable to get 2D context");
             ctx.globalCompositeOperation = defaultBlendMode;
             ctx.drawImage(baseImage, 0, 0);
             for (const layer of layers) {
@@ -703,323 +1130,921 @@ class ApexPainter {
             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}`);
+        }
+    }
+    /**
+     * Validates chart inputs.
+     * @private
+     * @param data - Chart data to validate
+     * @param type - Chart type configuration to validate
+     */
+    #validateChartInputs(data, type) {
+        if (!data || typeof data !== 'object' || Object.keys(data).length === 0) {
+            throw new Error("createChart: data object with datasets is required.");
+        }
+        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(', ')}`);
         }
     }
     async createChart(data, type) {
-        if (!data || Object.keys(data).length === 0) {
-            throw new Error('You need to provide datasets to create charts.');
-        }
-        if (!type || !type.chartNumber || !type.chartType) {
-            throw new Error('Type arguments are missing.');
-        }
-        const { chartType, chartNumber } = type;
-        switch (chartType.toLowerCase()) {
-            case 'bar':
-                switch (chartNumber) {
-                    case 1:
-                        return await (0, utils_1.verticalBarChart)(data);
-                    case 2:
-                        throw new Error('Type 2 is still under development.');
-                    default:
-                        throw new Error('Invalid chart number for chart type "bar".');
-                }
-            case 'line':
-                switch (chartNumber) {
-                    case 1:
-                        return await (0, utils_1.lineChart)(data);
-                    case 2:
-                        throw new Error('Type 2 is still under development.');
-                    default:
-                        throw new Error('Invalid chart number for chart type "line".');
-                }
-            case 'pie':
-                switch (chartNumber) {
-                    case 1:
-                        return await (0, utils_1.pieChart)(data);
-                    case 2:
-                        throw new Error('Type 2 is still under development.');
-                    default:
-                        throw new Error('Invalid chart number for chart type "pie".');
-                }
-            default:
-                throw new Error(`Unsupported chart type "${chartType}".`);
+        try {
+            this.#validateChartInputs(data, type);
+            const { chartType, chartNumber } = type;
+            switch (chartType.toLowerCase()) {
+                case 'bar':
+                    switch (chartNumber) {
+                        case 1:
+                            const barResult = await (0, utils_1.verticalBarChart)(data);
+                            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:
+                            throw new Error('Invalid chart number for chart type "bar".');
+                    }
+                case 'line':
+                    switch (chartNumber) {
+                        case 1:
+                            // LineChart expects DataPoint[][] where DataPoint has { label: string; y: number }
+                            // Type assertion needed because there are two different DataPoint interfaces
+                            return await (0, utils_1.lineChart)(data);
+                        case 2:
+                            throw new Error('Type 2 is still under development.');
+                        default:
+                            throw new Error('Invalid chart number for chart type "line".');
+                    }
+                case 'pie':
+                    switch (chartNumber) {
+                        case 1:
+                            return await (0, utils_1.pieChart)(data);
+                        case 2:
+                            throw new Error('Type 2 is still under development.');
+                        default:
+                            throw new Error('Invalid chart number for chart type "pie".');
+                    }
+                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}`);
+        }
+    }
+    /**
+     * Validates crop options.
+     * @private
+     * @param options - Crop options to validate
+     */
+    #validateCropOptions(options) {
+        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) {
         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 (0, utils_1.cropOuter)(options);
             }
-            else if (options.crop === 'inner') {
+            else {
                 return await (0, utils_1.cropInner)(options);
             }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            throw new Error(`cropImage failed: ${errorMessage}`);
+        }
+    }
+    /**
+   * 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, frameNumber = 0) {
+        try {
+            const frameDir = path_1.default.join(process.cwd(), '.temp-frames');
+            if (!fs_1.default.existsSync(frameDir)) {
+                fs_1.default.mkdirSync(frameDir, { recursive: true });
+            }
+            const tempVideoPath = path_1.default.join(frameDir, `temp-video-${Date.now()}.mp4`);
+            const frameOutputPath = path_1.default.join(frameDir, `frame-${Date.now()}.jpg`);
+            // Handle video source
+            if (Buffer.isBuffer(videoSource)) {
+                fs_1.default.writeFileSync(tempVideoPath, videoSource);
+            }
+            else if (typeof videoSource === 'string' && videoSource.startsWith('http')) {
+                const response = await (0, axios_1.default)({
+                    method: 'get',
+                    url: videoSource,
+                    responseType: 'arraybuffer'
+                });
+                fs_1.default.writeFileSync(tempVideoPath, Buffer.from(response.data));
+            }
             else {
-                throw new Error('Invalid crop option. Please specify "inner" or "outer".');
+                // Local file path
+                if (!fs_1.default.existsSync(videoSource)) {
+                    throw new Error(`Video file not found: ${videoSource}`);
+                }
+                // Use the existing path
+                return await new Promise((resolve, reject) => {
+                    (0, fluent_ffmpeg_1.default)(videoSource)
+                        .seekInput(frameNumber / 1000) // Convert frame to seconds (approximate)
+                        .frames(1)
+                        .output(frameOutputPath)
+                        .on('end', () => {
+                        try {
+                            const buffer = fs_1.default.readFileSync(frameOutputPath);
+                            // Cleanup
+                            if (fs_1.default.existsSync(frameOutputPath))
+                                fs_1.default.unlinkSync(frameOutputPath);
+                            resolve(buffer);
+                        }
+                        catch (e) {
+                            resolve(null);
+                        }
+                    })
+                        .on('error', (err) => {
+                        reject(err);
+                    })
+                        .run();
+                });
             }
+            // Extract frame from temp video
+            return await new Promise((resolve, reject) => {
+                (0, fluent_ffmpeg_1.default)(tempVideoPath)
+                    .seekInput(frameNumber / 1000)
+                    .frames(1)
+                    .output(frameOutputPath)
+                    .on('end', () => {
+                    try {
+                        const buffer = fs_1.default.readFileSync(frameOutputPath);
+                        // Cleanup
+                        if (fs_1.default.existsSync(tempVideoPath))
+                            fs_1.default.unlinkSync(tempVideoPath);
+                        if (fs_1.default.existsSync(frameOutputPath))
+                            fs_1.default.unlinkSync(frameOutputPath);
+                        resolve(buffer);
+                    }
+                    catch (e) {
+                        resolve(null);
+                    }
+                })
+                    .on('error', (err) => {
+                    // Cleanup on error
+                    if (fs_1.default.existsSync(tempVideoPath))
+                        fs_1.default.unlinkSync(tempVideoPath);
+                    if (fs_1.default.existsSync(frameOutputPath))
+                        fs_1.default.unlinkSync(frameOutputPath);
+                    reject(err);
+                })
+                    .run();
+            });
         }
         catch (error) {
-            console.error('An error occurred:', error);
-            throw error;
+            console.error('Error extracting video frame:', error);
+            return null;
         }
     }
-    async drawImage(ctx, image) {
+    /**
+     * Validates extract frames inputs.
+     * @private
+     * @param videoSource - Video source to validate
+     * @param options - Extract frames options to validate
+     */
+    #validateExtractFramesInputs(videoSource, options) {
+        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, options) {
-        const frames = [];
-        const frameDir = path_1.default.join(__dirname, 'frames');
-        if (!fs_1.default.existsSync(frameDir)) {
-            fs_1.default.mkdirSync(frameDir);
-        }
-        const videoPath = typeof videoSource === 'string' ? videoSource : path_1.default.join(frameDir, 'temp-video.mp4');
-        if (Buffer.isBuffer(videoSource)) {
-            fs_1.default.writeFileSync(videoPath, videoSource);
-        }
-        else if (videoSource.startsWith('http')) {
-            await (0, axios_1.default)({
-                method: 'get',
-                url: videoSource,
-                responseType: 'arraybuffer'
-            })
-                .then((response) => {
-                fs_1.default.writeFileSync(videoPath, response.data);
-            })
-                .catch(err => {
-                throw new Error(`Error downloading video: ${err.message}`);
+        try {
+            this.#validateExtractFramesInputs(videoSource, options);
+            const frames = [];
+            const frameDir = path_1.default.join(__dirname, 'frames');
+            if (!fs_1.default.existsSync(frameDir)) {
+                fs_1.default.mkdirSync(frameDir);
+            }
+            const videoPath = typeof videoSource === 'string' ? videoSource : path_1.default.join(frameDir, 'temp-video.mp4');
+            if (Buffer.isBuffer(videoSource)) {
+                fs_1.default.writeFileSync(videoPath, videoSource);
+            }
+            else if (videoSource.startsWith('http')) {
+                await (0, axios_1.default)({
+                    method: 'get',
+                    url: videoSource,
+                    responseType: 'arraybuffer'
+                })
+                    .then((response) => {
+                    fs_1.default.writeFileSync(videoPath, response.data);
+                })
+                    .catch(err => {
+                    throw new Error(`Error downloading video: ${err.message}`);
+                });
+            }
+            else if (!fs_1.default.existsSync(videoPath)) {
+                throw new Error("Video file not found at specified path.");
+            }
+            function processVideoExtraction(videoPath, frames, options, resolve, reject) {
+                const outputFormat = options.outputFormat || 'jpg';
+                const outputFileTemplate = `frame-%03d.${outputFormat}`;
+                (0, fluent_ffmpeg_1.default)(videoPath)
+                    .on('end', () => {
+                    console.log('Frames extracted successfully.');
+                    resolve(frames);
+                })
+                    .on('error', (err) => {
+                    console.error('Error extracting frames:', err.message);
+                    reject(err);
+                })
+                    .outputOptions([`-vf fps=1/${options.interval / 1000}`, `-q:v 2`])
+                    .saveToFile(path_1.default.join(frameDir, outputFileTemplate));
+                fluent_ffmpeg_1.default.ffprobe(videoPath, (err, metadata) => {
+                    if (err) {
+                        return reject(err);
+                    }
+                    const duration = metadata?.format?.duration;
+                    if (typeof duration !== "number") {
+                        return reject(new Error("Video duration not found in metadata."));
+                    }
+                    const totalFrames = Math.floor(duration * 1000 / options.interval);
+                    for (let i = 0; i < totalFrames; i++) {
+                        if (options.frameSelection && (i < (options.frameSelection.start || 0) || i > (options.frameSelection.end || totalFrames - 1))) {
+                            continue;
+                        }
+                        frames.push({
+                            source: path_1.default.join(frameDir, `frame-${String(i).padStart(3, '0')}.${outputFormat}`),
+                            isRemote: false
+                        });
+                    }
+                });
+            }
+            return new Promise((resolve, reject) => {
+                processVideoExtraction(videoPath, frames, options, resolve, reject);
             });
         }
-        else if (!fs_1.default.existsSync(videoPath)) {
-            throw new Error("Video file not found at specified path.");
-        }
-        function processVideoExtraction(videoPath, frames, options, resolve, reject) {
-            const outputFormat = options.outputFormat || 'jpg';
-            const outputFileTemplate = `frame-%03d.${outputFormat}`;
-            (0, fluent_ffmpeg_1.default)(videoPath)
-                .on('end', () => {
-                console.log('Frames extracted successfully.');
-                resolve(frames);
-            })
-                .on('error', (err) => {
-                console.error('Error extracting frames:', err.message);
-                reject(err);
-            })
-                .outputOptions([`-vf fps=1/${options.interval / 1000}`, `-q:v 2`])
-                .saveToFile(path_1.default.join(frameDir, outputFileTemplate));
-            fluent_ffmpeg_1.default.ffprobe(videoPath, (err, metadata) => {
-                if (err) {
-                    return reject(err);
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            throw new Error(`extractFrames failed: ${errorMessage}`);
+        }
+    }
+    /**
+     * Validates masking inputs.
+     * @private
+     * @param source - Source image to validate
+     * @param maskSource - Mask image to validate
+     * @param options - Mask options to validate
+     */
+    #validateMaskingInputs(source, maskSource, options) {
+        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, maskSource, options = { type: "alpha" }) {
+        try {
+            this.#validateMaskingInputs(source, maskSource, options);
+            const img = await (0, canvas_1.loadImage)(source);
+            const mask = await (0, canvas_1.loadImage)(maskSource);
+            const canvas = (0, canvas_1.createCanvas)(img.width, img.height);
+            const ctx = canvas.getContext("2d");
+            ctx.drawImage(img, 0, 0, img.width, img.height);
+            const maskCanvas = (0, canvas_1.createCanvas)(img.width, img.height);
+            const maskCtx = maskCanvas.getContext("2d");
+            maskCtx.drawImage(mask, 0, 0, img.width, img.height);
+            const maskData = maskCtx.getImageData(0, 0, img.width, img.height);
+            const imgData = ctx.getImageData(0, 0, img.width, img.height);
+            for (let i = 0; i < maskData.data.length; i += 4) {
+                let alphaValue = 255;
+                if (options.type === "grayscale") {
+                    const grayscale = maskData.data[i] * 0.3 + maskData.data[i + 1] * 0.59 + maskData.data[i + 2] * 0.11;
+                    alphaValue = grayscale >= (options.threshold ?? 128) ? 255 : 0;
                 }
-                const duration = metadata?.format?.duration;
-                if (typeof duration !== "number") {
-                    return reject(new Error("Video duration not found in metadata."));
+                else if (options.type === "alpha") {
+                    alphaValue = maskData.data[i + 3];
                 }
-                const totalFrames = Math.floor(duration * 1000 / options.interval);
-                for (let i = 0; i < totalFrames; i++) {
-                    if (options.frameSelection && (i < (options.frameSelection.start || 0) || i > (options.frameSelection.end || totalFrames - 1))) {
-                        continue;
-                    }
-                    frames.push({
-                        source: path_1.default.join(frameDir, `frame-${String(i).padStart(3, '0')}.${outputFormat}`),
-                        isRemote: false
-                    });
+                else if (options.type === "color" && options.colorKey) {
+                    const colorMatch = maskData.data[i] === parseInt(options.colorKey.slice(1, 3), 16) &&
+                        maskData.data[i + 1] === parseInt(options.colorKey.slice(3, 5), 16) &&
+                        maskData.data[i + 2] === parseInt(options.colorKey.slice(5, 7), 16);
+                    alphaValue = colorMatch ? 0 : 255;
                 }
-            });
+                if (options.invert)
+                    alphaValue = 255 - alphaValue;
+                imgData.data[i + 3] = alphaValue;
+            }
+            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 new Promise((resolve, reject) => {
-            processVideoExtraction(videoPath, frames, options, resolve, reject);
-        });
     }
-    async masking(source, maskSource, options = { type: "alpha" }) {
-        const img = await (0, canvas_1.loadImage)(source);
-        const mask = await (0, canvas_1.loadImage)(maskSource);
-        const canvas = (0, canvas_1.createCanvas)(img.width, img.height);
-        const ctx = canvas.getContext("2d");
-        ctx.drawImage(img, 0, 0, img.width, img.height);
-        const maskCanvas = (0, canvas_1.createCanvas)(img.width, img.height);
-        const maskCtx = maskCanvas.getContext("2d");
-        maskCtx.drawImage(mask, 0, 0, img.width, img.height);
-        const maskData = maskCtx.getImageData(0, 0, img.width, img.height);
-        const imgData = ctx.getImageData(0, 0, img.width, img.height);
-        for (let i = 0; i < maskData.data.length; i += 4) {
-            let alphaValue = 255;
-            if (options.type === "grayscale") {
-                const grayscale = maskData.data[i] * 0.3 + maskData.data[i + 1] * 0.59 + maskData.data[i + 2] * 0.11;
-                alphaValue = grayscale >= (options.threshold ?? 128) ? 255 : 0;
-            }
-            else if (options.type === "alpha") {
-                alphaValue = maskData.data[i + 3];
-            }
-            else if (options.type === "color" && options.colorKey) {
-                const colorMatch = maskData.data[i] === parseInt(options.colorKey.slice(1, 3), 16) &&
-                    maskData.data[i + 1] === parseInt(options.colorKey.slice(3, 5), 16) &&
-                    maskData.data[i + 2] === parseInt(options.colorKey.slice(5, 7), 16);
-                alphaValue = colorMatch ? 0 : 255;
-            }
-            if (options.invert)
-                alphaValue = 255 - alphaValue;
-            imgData.data[i + 3] = alphaValue;
-        }
-        ctx.putImageData(imgData, 0, 0);
-        return canvas.toBuffer("image/png");
+    /**
+     * Validates gradient blend inputs.
+     * @private
+     * @param source - Source image to validate
+     * @param options - Blend options to validate
+     */
+    #validateGradientBlendInputs(source, options) {
+        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, options) {
-        const img = await (0, canvas_1.loadImage)(source);
-        const canvas = (0, canvas_1.createCanvas)(img.width, img.height);
-        const ctx = canvas.getContext("2d");
-        ctx.drawImage(img, 0, 0, img.width, img.height);
-        let gradient;
-        if (options.type === "linear") {
-            const angle = options.angle ?? 0;
-            const radians = (angle * Math.PI) / 180;
-            const x1 = img.width / 2 - (Math.cos(radians) * img.width) / 2;
-            const y1 = img.height / 2 - (Math.sin(radians) * img.height) / 2;
-            const x2 = img.width / 2 + (Math.cos(radians) * img.width) / 2;
-            const y2 = img.height / 2 + (Math.sin(radians) * img.height) / 2;
-            gradient = ctx.createLinearGradient(x1, y1, x2, y2);
-        }
-        else if (options.type === "radial") {
-            gradient = ctx.createRadialGradient(img.width / 2, img.height / 2, 0, img.width / 2, img.height / 2, Math.max(img.width, img.height));
+        try {
+            this.#validateGradientBlendInputs(source, options);
+            const img = await (0, canvas_1.loadImage)(source);
+            const canvas = (0, canvas_1.createCanvas)(img.width, img.height);
+            const ctx = canvas.getContext("2d");
+            if (!ctx)
+                throw new Error("Unable to get 2D context");
+            ctx.drawImage(img, 0, 0, img.width, img.height);
+            let gradient;
+            if (options.type === "linear") {
+                const angle = options.angle ?? 0;
+                const radians = (angle * Math.PI) / 180;
+                const x1 = img.width / 2 - (Math.cos(radians) * img.width) / 2;
+                const y1 = img.height / 2 - (Math.sin(radians) * img.height) / 2;
+                const x2 = img.width / 2 + (Math.cos(radians) * img.width) / 2;
+                const y2 = img.height / 2 + (Math.sin(radians) * img.height) / 2;
+                gradient = ctx.createLinearGradient(x1, y1, x2, y2);
+            }
+            else if (options.type === "radial") {
+                gradient = ctx.createRadialGradient(img.width / 2, img.height / 2, 0, img.width / 2, img.height / 2, Math.max(img.width, img.height));
+            }
+            else {
+                gradient = ctx.createConicGradient(Math.PI, img.width / 2, img.height / 2);
+            }
+            options.colors.forEach(({ stop, color }) => gradient.addColorStop(stop, color));
+            ctx.fillStyle = gradient;
+            ctx.globalCompositeOperation = options.blendMode ?? "multiply";
+            ctx.fillRect(0, 0, img.width, img.height);
+            if (options.maskSource) {
+                const mask = await (0, canvas_1.loadImage)(options.maskSource);
+                ctx.globalCompositeOperation = "destination-in";
+                ctx.drawImage(mask, 0, 0, img.width, img.height);
+            }
+            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}`);
+        }
+    }
+    /**
+     * 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, defaultDuration, defaultWidth, defaultHeight, options) {
+        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.");
         }
-        else {
-            gradient = ctx.createConicGradient(Math.PI, img.width / 2, img.height / 2);
-        }
-        options.colors.forEach(({ stop, color }) => gradient.addColorStop(stop, color));
-        ctx.fillStyle = gradient;
-        ctx.globalCompositeOperation = options.blendMode ?? "multiply";
-        ctx.fillRect(0, 0, img.width, img.height);
-        if (options.maskSource) {
-            const mask = await (0, canvas_1.loadImage)(options.maskSource);
-            ctx.globalCompositeOperation = "destination-in";
-            ctx.drawImage(mask, 0, 0, img.width, img.height);
-        }
-        ctx.globalCompositeOperation = "source-over";
-        return canvas.toBuffer("image/png");
     }
     async animate(frames, defaultDuration, defaultWidth = 800, defaultHeight = 600, options) {
-        const buffers = [];
-        const isNode = typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
-        if (options?.onStart)
-            options.onStart();
-        let encoder = null;
-        let gifStream = null;
-        if (options?.gif) {
-            if (!options.gifPath) {
-                throw new Error("GIF generation enabled but no gifPath provided.");
-            }
-            encoder = new gifencoder_1.default(defaultWidth, defaultHeight);
-            gifStream = fs_1.default.createWriteStream(options.gifPath);
-            encoder.createReadStream().pipe(gifStream);
-            encoder.start();
-            encoder.setRepeat(0);
-            encoder.setQuality(10);
-        }
-        for (let i = 0; i < frames.length; i++) {
-            const frame = frames[i];
-            const width = frame.width || defaultWidth;
-            const height = frame.height || defaultHeight;
-            const canvas = (0, canvas_1.createCanvas)(width, height);
-            const ctx = canvas.getContext('2d');
-            if (!isNode) {
-                canvas.width = width;
-                canvas.height = height;
-                document.body.appendChild(canvas);
-            }
-            ctx.clearRect(0, 0, width, height);
-            if (frame.transformations) {
-                const { scaleX = 1, scaleY = 1, rotate = 0, translateX = 0, translateY = 0 } = frame.transformations;
-                ctx.save();
-                ctx.translate(translateX, translateY);
-                ctx.rotate((rotate * Math.PI) / 180);
-                ctx.scale(scaleX, scaleY);
-            }
-            let fillStyle = null;
-            if (frame.gradient) {
-                const { type, startX, startY, endX, endY, startRadius, endRadius, colors } = frame.gradient;
-                let gradient = null;
-                if (type === 'linear') {
-                    gradient = ctx.createLinearGradient(startX || 0, startY || 0, endX || width, endY || height);
-                }
-                else if (type === 'radial') {
-                    gradient = ctx.createRadialGradient(startX || width / 2, startY || height / 2, startRadius || 0, endX || width / 2, endY || height / 2, endRadius || Math.max(width, height));
+        try {
+            this.#validateAnimateInputs(frames, defaultDuration, defaultWidth, defaultHeight, options);
+            const buffers = [];
+            const isNode = typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
+            if (options?.onStart)
+                options.onStart();
+            let encoder = null;
+            let gifStream = null;
+            if (options?.gif) {
+                if (!options.gifPath) {
+                    throw new Error("animate: gifPath is required when gif is enabled.");
                 }
-                colors.forEach((colorStop) => {
-                    if (gradient)
-                        gradient.addColorStop(colorStop.stop, colorStop.color);
-                });
-                fillStyle = gradient;
+                encoder = new gifencoder_1.default(defaultWidth, defaultHeight);
+                gifStream = fs_1.default.createWriteStream(options.gifPath);
+                encoder.createReadStream().pipe(gifStream);
+                encoder.start();
+                encoder.setRepeat(0);
+                encoder.setQuality(10);
             }
-            if (frame.pattern) {
-                const patternImage = await (0, canvas_1.loadImage)(frame.pattern.source);
-                const pattern = ctx.createPattern(patternImage, frame.pattern.repeat || 'repeat');
-                fillStyle = pattern;
+            for (let i = 0; i < frames.length; i++) {
+                const frame = frames[i];
+                const width = frame.width || defaultWidth;
+                const height = frame.height || defaultHeight;
+                const canvas = (0, canvas_1.createCanvas)(width, height);
+                const ctx = canvas.getContext('2d');
+                if (!isNode) {
+                    canvas.width = width;
+                    canvas.height = height;
+                    document.body.appendChild(canvas);
+                }
+                ctx.clearRect(0, 0, width, height);
+                if (frame.transformations) {
+                    const { scaleX = 1, scaleY = 1, rotate = 0, translateX = 0, translateY = 0 } = frame.transformations;
+                    ctx.save();
+                    ctx.translate(translateX, translateY);
+                    ctx.rotate((rotate * Math.PI) / 180);
+                    ctx.scale(scaleX, scaleY);
+                }
+                let fillStyle = null;
+                if (frame.gradient) {
+                    const { type, startX, startY, endX, endY, startRadius, endRadius, colors } = frame.gradient;
+                    let gradient = null;
+                    if (type === 'linear') {
+                        gradient = ctx.createLinearGradient(startX || 0, startY || 0, endX || width, endY || height);
+                    }
+                    else if (type === 'radial') {
+                        gradient = ctx.createRadialGradient(startX || width / 2, startY || height / 2, startRadius || 0, endX || width / 2, endY || height / 2, endRadius || Math.max(width, height));
+                    }
+                    colors.forEach((colorStop) => {
+                        if (gradient)
+                            gradient.addColorStop(colorStop.stop, colorStop.color);
+                    });
+                    fillStyle = gradient;
+                }
+                if (frame.pattern) {
+                    const patternImage = await (0, canvas_1.loadImage)(frame.pattern.source);
+                    const pattern = ctx.createPattern(patternImage, frame.pattern.repeat || 'repeat');
+                    fillStyle = pattern;
+                }
+                if (!fillStyle && frame.backgroundColor) {
+                    fillStyle = frame.backgroundColor;
+                }
+                if (fillStyle) {
+                    ctx.fillStyle = fillStyle;
+                    ctx.fillRect(0, 0, width, height);
+                }
+                if (frame.source) {
+                    const image = await (0, canvas_1.loadImage)(frame.source);
+                    ctx.globalCompositeOperation = frame.blendMode || 'source-over';
+                    ctx.drawImage(image, 0, 0, width, height);
+                }
+                if (frame.onDrawCustom) {
+                    frame.onDrawCustom(ctx, canvas);
+                }
+                if (frame.transformations) {
+                    ctx.restore();
+                }
+                const buffer = canvas.toBuffer('image/png');
+                buffers.push(buffer);
+                if (encoder) {
+                    const frameDuration = frame.duration || defaultDuration;
+                    encoder.setDelay(frameDuration);
+                    encoder.addFrame(ctx);
+                }
+                if (options?.onFrame)
+                    options.onFrame(i);
+                await new Promise(resolve => setTimeout(resolve, frame.duration || defaultDuration));
             }
-            if (!fillStyle && frame.backgroundColor) {
-                fillStyle = frame.backgroundColor;
+            if (encoder) {
+                encoder.finish();
             }
-            if (fillStyle) {
-                ctx.fillStyle = fillStyle;
-                ctx.fillRect(0, 0, width, height);
+            if (options?.onEnd)
+                options.onEnd();
+            return options?.gif ? undefined : buffers;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            throw new Error(`animate failed: ${errorMessage}`);
+        }
+    }
+    /**
+     * Processes multiple operations in parallel
+     * @param operations - Array of operations to process
+     * @returns Array of result buffers
+     */
+    async batch(operations) {
+        try {
+            return await (0, utils_1.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) {
+        try {
+            return await (0, utils_1.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, options) {
+        try {
+            if (!images || images.length === 0) {
+                throw new Error("stitchImages: images array is required");
             }
-            if (frame.source) {
-                const image = await (0, canvas_1.loadImage)(frame.source);
-                ctx.globalCompositeOperation = frame.blendMode || 'source-over';
-                ctx.drawImage(image, 0, 0, width, height);
+            return await (0, utils_1.stitchImages)(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, layout) {
+        try {
+            if (!images || images.length === 0) {
+                throw new Error("createCollage: images array is required");
             }
-            if (frame.onDrawCustom) {
-                frame.onDrawCustom(ctx, canvas);
+            if (!layout) {
+                throw new Error("createCollage: layout configuration is required");
             }
-            if (frame.transformations) {
-                ctx.restore();
+            return await (0, utils_1.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, options) {
+        try {
+            if (!image) {
+                throw new Error("compress: image is required");
             }
-            const buffer = canvas.toBuffer('image/png');
-            buffers.push(buffer);
-            if (encoder) {
-                const frameDuration = frame.duration || defaultDuration;
-                encoder.setDelay(frameDuration);
-                encoder.addFrame(ctx);
+            return await (0, utils_1.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, options) {
+        try {
+            if (!image) {
+                throw new Error("extractPalette: image is required");
             }
-            if (options?.onFrame)
-                options.onFrame(i);
-            await new Promise(resolve => setTimeout(resolve, frame.duration || defaultDuration));
+            return await (0, utils_1.extractPalette)(image, options);
         }
-        if (encoder) {
-            encoder.finish();
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            throw new Error(`extractPalette failed: ${errorMessage}`);
         }
-        if (options?.onEnd)
-            options.onEnd();
-        return options?.gif ? undefined : buffers;
     }
+    /**
+     * 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
+     * ```
+     */
     validHex(hexColor) {
+        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'.");
+            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
+     * ```
+     */
     async outPut(results) {
-        const formatType = this.format?.type || 'buffer';
-        switch (formatType) {
-            case 'buffer':
-                return results;
-            case 'url':
-                return await (0, utils_1.url)(results);
-            case 'dataURL':
-                return (0, utils_1.dataURL)(results);
-            case 'blob':
-                return (0, utils_1.blob)(results);
-            case 'base64':
-                return (0, utils_1.base64)(results);
-            case 'arraybuffer':
-                return (0, utils_1.arrayBuffer)(results);
-            default:
-                throw new Error('Unsupported format');
+        try {
+            if (!Buffer.isBuffer(results)) {
+                throw new Error("outPut: results must be a Buffer.");
+            }
+            const formatType = this.format?.type || 'buffer';
+            switch (formatType) {
+                case 'buffer':
+                    return results;
+                case 'url':
+                    return await (0, utils_1.url)(results);
+                case 'dataURL':
+                    return (0, utils_1.dataURL)(results);
+                case 'blob':
+                    return (0, utils_1.blob)(results);
+                case 'base64':
+                    return (0, utils_1.base64)(results);
+                case 'arraybuffer':
+                    return (0, utils_1.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'
+     * });
+     * ```
+     */
+    async save(buffer, options) {
+        try {
+            if (!Buffer.isBuffer(buffer)) {
+                throw new Error("save: buffer must be a Buffer.");
+            }
+            const opts = {
+                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_1.default.existsSync(opts.directory)) {
+                fs_1.default.mkdirSync(opts.directory, { recursive: true });
+            }
+            // Generate filename
+            let filename;
+            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_1.default.join(opts.directory, filename);
+            if (!opts.overwrite && fs_1.default.existsSync(filePath)) {
+                // Add number suffix if file exists
+                let counter = 1;
+                let newPath = filePath;
+                const ext = path_1.default.extname(filePath);
+                const baseName = path_1.default.basename(filePath, ext);
+                const dir = path_1.default.dirname(filePath);
+                while (fs_1.default.existsSync(newPath)) {
+                    newPath = path_1.default.join(dir, `${baseName}_${counter}${ext}`);
+                    counter++;
+                }
+                filename = path_1.default.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_1.default.join(opts.directory, filename);
+            fs_1.default.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'
+     * });
+     * ```
+     */
+    async saveMultiple(buffers, options) {
+        try {
+            if (!Array.isArray(buffers) || buffers.length === 0) {
+                throw new Error("saveMultiple: buffers must be a non-empty array.");
+            }
+            const results = [];
+            const baseCounter = options?.counterStart ?? this.saveCounter;
+            for (let i = 0; i < buffers.length; i++) {
+                const bufferOptions = {
+                    ...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).
+     */
+    resetSaveCounter() {
+        this.saveCounter = 1;
+    }
     /**
      * Applies stroke style to shape context
      * @private