@cognima/banners 0.0.1-beta

package/utils.js

@@ -0,0 +1,710 @@
+"use strict";
+
+/**
+ * Módulo de Utilitários para @cognima/banners
+ * 
+ * Este módulo contém funções auxiliares para manipulação de imagens, fontes,
+ * desenho em canvas e formatação de dados utilizados pelos geradores de banners.
+ * 
+ * @author Cognima Team (melhorado)
+ * @version 2.0.0
+ */
+
+const pureimage = require("pureimage");
+const fs = require("fs");
+const path = require("path");
+const axios = require("axios");
+const { Readable } = require("stream");
+
+// --- Constantes para Padronização ---
+const DEFAULT_FONT_FAMILY = "Poppins";
+const DEFAULT_FONT_DIR = path.join(__dirname, "/assets/fonts/Poppins");
+const FONT_WEIGHTS = {
+    bold: "Poppins-Bold.ttf",
+    medium: "Poppins-Medium.ttf",
+    regular: "Poppins-Regular.ttf",
+};
+
+// --- Validação de Cores ---
+/**
+ * Verifica se uma string é uma cor hexadecimal válida
+ * @param {string} color - Cor em formato hexadecimal (#RRGGBB ou #RGB)
+ * @returns {boolean} - Verdadeiro se for uma cor hexadecimal válida
+ */
+function isValidHexColor(color) {
+    return /^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$/.test(color);
+}
+
+// --- Registro de Fontes ---
+let fontsRegistered = false;
+const registeredFontNames = new Set(); // Controla nomes de fontes registradas com sucesso
+
+/**
+ * Registra as fontes padrão do sistema
+ * @returns {Promise<string>} - Nome da família de fonte registrada
+ */
+async function registerDefaultFonts() {
+    if (fontsRegistered) {
+        return DEFAULT_FONT_FAMILY;
+    }
+    
+    try {
+        const fontPromises = [];
+        
+        // Registra cada peso de fonte
+        for (const weight in FONT_WEIGHTS) {
+            const fontPath = path.join(DEFAULT_FONT_DIR, FONT_WEIGHTS[weight]);
+            
+            if (fs.existsSync(fontPath)) {
+                const fontName = `${DEFAULT_FONT_FAMILY}-${weight.charAt(0).toUpperCase() + weight.slice(1)}`;
+                const font = pureimage.registerFont(fontPath, fontName);
+                
+                fontPromises.push(
+                    font.load().then(() => {
+                        registeredFontNames.add(fontName);
+                    }).catch(err => {
+                        console.error(`Falha ao carregar fonte ${fontName}:`, err);
+                        throw err;
+                    })
+                );
+            } else {
+                console.warn(`Arquivo de fonte padrão não encontrado: ${fontPath}`);
+            }
+        }
+        
+        if (fontPromises.length > 0) {
+            await Promise.all(fontPromises);
+            
+            if (registeredFontNames.size === Object.keys(FONT_WEIGHTS).length) {
+                 fontsRegistered = true;
+                 return DEFAULT_FONT_FAMILY;
+            } else {
+                throw new Error(`Apenas ${registeredFontNames.size}/${Object.keys(FONT_WEIGHTS).length} fontes padrão foram registradas com sucesso.`);
+            }
+        } else {
+            throw new Error("Nenhum arquivo de fonte padrão encontrado no diretório esperado.");
+        }
+    } catch (err) {
+        console.error("Erro ao registrar fontes padrão:", err);
+        throw new Error("Falha ao carregar fontes padrão. Certifique-se de que os arquivos da fonte Poppins (Bold, Medium, Regular) estão em assets/fonts/Poppins.");
+    }
+}
+
+/**
+ * Registra uma fonte personalizada se necessário
+ * @param {Object} fontConfig - Configuração da fonte (nome e caminho)
+ * @returns {Promise<string>} - Nome da família de fonte registrada
+ */
+async function registerFontIfNeeded(fontConfig) {
+    if (!fontConfig || !fontConfig.path || !fontConfig.name) {
+        // Usa fontes padrão se nenhuma fonte personalizada for fornecida ou a configuração estiver incompleta
+        return await registerDefaultFonts();
+    }
+
+    try {
+        if (fs.existsSync(fontConfig.path)) {
+            const font = pureimage.registerFont(fontConfig.path, fontConfig.name);
+            await font.load();
+            registeredFontNames.add(fontConfig.name);
+            return fontConfig.name; // Retorna o nome da fonte personalizada registrada
+        } else {
+            console.warn(`Arquivo de fonte personalizada não encontrado: ${fontConfig.path}. Usando fontes padrão.`);
+            return await registerDefaultFonts();
+        }
+    } catch (err) {
+        console.error(`Erro ao registrar fonte personalizada ${fontConfig.name}:`, err);
+        console.warn("Usando fontes padrão como alternativa.");
+        return await registerDefaultFonts();
+    }
+}
+
+// --- Carregamento de Imagens ---
+/**
+ * Carrega uma imagem a partir de várias fontes possíveis (URL, Buffer, caminho local)
+ * @param {string|Buffer|Object} source - Fonte da imagem (URL, Buffer ou caminho local)
+ * @returns {Promise<Object>} - Objeto bitmap da imagem carregada
+ */
+async function loadImageWithAxios(source) {
+    if (!source) throw new Error("A fonte da imagem não pode ser nula ou vazia.");
+
+    // Carrega imagem a partir de URL
+    if (typeof source === "string" && source.startsWith("http")) {
+        try {
+            const response = await axios.get(source, { responseType: "arraybuffer" });
+            const buffer = Buffer.from(response.data, "binary");
+            const contentType = response.headers["content-type"];
+
+            // Tenta decodificar com base no tipo de conteúdo
+            if (contentType && contentType.includes("png")) {
+                return await pureimage.decodePNGFromStream(Readable.from(buffer));
+            } else if (contentType && (contentType.includes("jpeg") || contentType.includes("jpg"))) {
+                return await pureimage.decodeJPEGFromStream(Readable.from(buffer));
+            } else {
+                // Tenta decodificar, priorizando PNG e depois JPEG
+                try { 
+                    return await pureimage.decodePNGFromStream(Readable.from(buffer)); 
+                } catch (e) { /* ignora */ }
+                
+                try { 
+                    return await pureimage.decodeJPEGFromStream(Readable.from(buffer)); 
+                } catch (e) { /* ignora */ }
+                
+                throw new Error(`Tipo de imagem não suportado '${contentType}' da URL: ${source}`);
+            }
+        } catch (error) {
+            console.error(`Erro ao carregar imagem da URL ${source}:`, error.message);
+            throw new Error(`Falha ao carregar imagem da URL: ${source}. Verifique se a URL está correta e o formato da imagem é PNG ou JPEG.`);
+        }
+    } 
+    // Carrega imagem a partir de Buffer
+    else if (Buffer.isBuffer(source)) {
+        try { 
+            return await pureimage.decodePNGFromStream(Readable.from(source)); 
+        } catch (e) { /* ignora */ }
+        
+        try { 
+            return await pureimage.decodeJPEGFromStream(Readable.from(source)); 
+        } catch (e) { /* ignora */ }
+        
+        throw new Error("Falha ao decodificar imagem do buffer. Certifique-se de que é um buffer PNG ou JPEG válido.");
+    } 
+    // Carrega imagem a partir de caminho local
+    else if (typeof source === "string") {
+        try {
+            const stream = fs.createReadStream(source);
+            
+            if (source.toLowerCase().endsWith(".png")) {
+                return await pureimage.decodePNGFromStream(stream);
+            }
+            
+            if (source.toLowerCase().endsWith(".jpg") || source.toLowerCase().endsWith(".jpeg")) {
+                return await pureimage.decodeJPEGFromStream(stream);
+            }
+            
+            throw new Error("Tipo de arquivo de imagem local não suportado. Apenas PNG e JPEG são suportados.");
+        } catch (error) {
+            console.error(`Erro ao carregar imagem do caminho ${source}:`, error.message);
+            throw new Error(`Falha ao carregar imagem do caminho: ${source}. Verifique se o caminho está correto e o arquivo é PNG ou JPEG.`);
+        }
+    } 
+    // Já é um bitmap
+    else if (source && source.width && source.height && source.data) {
+        return source;
+    }
+    
+    throw new Error("Fonte de imagem inválida fornecida. Deve ser uma URL (http/https), Buffer, caminho local ou um bitmap pureimage.");
+}
+
+// --- Codificação de Canvas ---
+/**
+ * Codifica um canvas para um buffer PNG
+ * @param {Object} canvas - Objeto canvas do pureimage
+ * @returns {Promise<Buffer>} - Buffer contendo a imagem PNG
+ */
+async function encodeToBuffer(canvas) {
+    const writableStream = new (require("stream").Writable)({
+        write(chunk, encoding, callback) {
+            if (!this.data) this.data = [];
+            this.data.push(chunk);
+            callback();
+        },
+    });
+    
+    await pureimage.encodePNGToStream(canvas, writableStream);
+    
+    if (!writableStream.data) throw new Error("Falha ao codificar imagem para buffer.");
+    
+    return Buffer.concat(writableStream.data);
+}
+
+// --- Auxiliares de Desenho ---
+/**
+ * Desenha um retângulo com cantos arredondados
+ * @param {Object} ctx - Contexto de renderização 2D
+ * @param {number} x - Posição X do retângulo
+ * @param {number} y - Posição Y do retângulo
+ * @param {number} width - Largura do retângulo
+ * @param {number} height - Altura do retângulo
+ * @param {number|Object} radius - Raio dos cantos (número ou objeto com raios específicos)
+ * @param {boolean} fill - Se deve preencher o retângulo
+ * @param {boolean} stroke - Se deve desenhar o contorno do retângulo
+ */
+function roundRect(ctx, x, y, width, height, radius, fill, stroke) {
+    // Normaliza o raio para um objeto com todos os cantos
+    if (typeof radius === "number") {
+        radius = { tl: radius, tr: radius, br: radius, bl: radius };
+    } else {
+        radius = { ...{ tl: 0, tr: 0, br: 0, bl: 0 }, ...radius };
+    }
+    
+    // Desenha o caminho do retângulo arredondado
+    ctx.beginPath();
+    ctx.moveTo(x + radius.tl, y);
+    ctx.lineTo(x + width - radius.tr, y);
+    ctx.quadraticCurveTo(x + width, y, x + width, y + radius.tr);
+    ctx.lineTo(x + width, y + height - radius.br);
+    ctx.quadraticCurveTo(x + width, y + height, x + width - radius.br, y + height);
+    ctx.lineTo(x + radius.bl, y + height);
+    ctx.quadraticCurveTo(x, y + height, x, y + height - radius.bl);
+    ctx.lineTo(x, y + radius.tl);
+    ctx.quadraticCurveTo(x, y, x + radius.tl, y);
+    ctx.closePath();
+    
+    // Aplica preenchimento e/ou contorno conforme solicitado
+    if (fill) {
+        ctx.fill();
+    }
+    if (stroke) {
+        ctx.stroke();
+    }
+}
+
+/**
+ * Quebra texto em múltiplas linhas para caber em uma largura máxima
+ * @param {Object} context - Contexto de renderização 2D
+ * @param {string} text - Texto a ser quebrado
+ * @param {number} x - Posição X inicial do texto
+ * @param {number} y - Posição Y inicial do texto
+ * @param {number} maxWidth - Largura máxima para o texto
+ * @param {number} lineHeight - Altura da linha
+ * @param {string} baseFontName - Nome base da fonte
+ * @returns {number} - Posição Y final após desenhar o texto
+ */
+function wrapText(context, text, x, y, maxWidth, lineHeight, baseFontName) {
+    const words = text.split(" ");
+    let line = "";
+    let currentY = y;
+    
+    // Extrai informações da fonte atual
+    const initialFont = context.font || `16px ${baseFontName}-Regular`;
+    const fontMatch = initialFont.match(/\d+px/);
+    const fontSize = fontMatch ? fontMatch[0] : "16px";
+    const fontWeight = initialFont.includes("Bold") ? "Bold" : initialFont.includes("Medium") ? "Medium" : "Regular";
+    const fontName = `${baseFontName}-${fontWeight}`;
+
+    // Verifica se a fonte está registrada
+    if (!registeredFontNames.has(fontName)) {
+        context.font = `${fontSize} ${baseFontName}-Regular`;
+    } else {
+        context.font = `${fontSize} ${fontName}`;
+    }
+
+    // Processa cada palavra e quebra em linhas
+    for (let n = 0; n < words.length; n++) {
+        const testLine = line + words[n] + " ";
+        context.font = `${fontSize} ${fontName}`;
+        const metrics = context.measureText(testLine);
+        const testWidth = metrics.width;
+
+        if (testWidth > maxWidth && n > 0) {
+            context.fillText(line.trim(), x, currentY);
+            line = words[n] + " ";
+            currentY += lineHeight;
+        } else {
+            line = testLine;
+        }
+    }
+    
+    // Desenha a última linha
+    context.font = `${fontSize} ${fontName}`;
+    context.fillText(line.trim(), x, currentY);
+    
+    return currentY + lineHeight; // Retorna a posição Y para a próxima linha
+}
+
+// --- Auxiliares de Formatação ---
+/**
+ * Formata um tempo em milissegundos para o formato MM:SS
+ * @param {number} ms - Tempo em milissegundos
+ * @returns {string} - Tempo formatado (MM:SS)
+ */
+function formatTime(ms) {
+    if (typeof ms !== "number" || isNaN(ms) || ms < 0) return "0:00";
+    
+    const totalSeconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    
+    return `${minutes}:${seconds < 10 ? "0" : ""}${seconds}`;
+}
+
+/**
+ * Formata um número para exibição amigável (com K, M para milhares e milhões)
+ * @param {number} num - Número a ser formatado
+ * @returns {string} - Número formatado
+ */
+function formatNumber(num) {
+    if (typeof num !== "number" || isNaN(num)) return "0";
+    
+    // Formatação simples K/M para números grandes
+    if (num >= 1000000) return (num / 1000000).toFixed(1).replace(/\.0$/, "") + "M";
+    if (num >= 1000) return (num / 1000).toFixed(1).replace(/\.0$/, "") + "K";
+    
+    return num.toString();
+}
+
+/**
+ * Aplica um efeito de sombra de texto padronizado
+ * @param {Object} ctx - Contexto de renderização 2D
+ * @param {string} color - Cor da sombra (hexadecimal)
+ * @param {number} blur - Desfoque da sombra
+ * @param {number} offsetX - Deslocamento X da sombra
+ * @param {number} offsetY - Deslocamento Y da sombra
+ */
+function applyTextShadow(ctx, color = "#000000", blur = 3, offsetX = 1, offsetY = 1) {
+    ctx.shadowColor = color;
+    ctx.shadowBlur = blur;
+    ctx.shadowOffsetX = offsetX;
+    ctx.shadowOffsetY = offsetY;
+}
+
+/**
+ * Remove efeitos de sombra do contexto
+ * @param {Object} ctx - Contexto de renderização 2D
+ */
+function clearShadow(ctx) {
+    ctx.shadowColor = "transparent";
+    ctx.shadowBlur = 0;
+    ctx.shadowOffsetX = 0;
+    ctx.shadowOffsetY = 0;
+}
+
+/**
+ * Aplica um efeito de gradiente linear ao contexto
+ * @param {Object} ctx - Contexto de renderização 2D
+ * @param {number} x - Posição X inicial do gradiente
+ * @param {number} y - Posição Y inicial do gradiente
+ * @param {number} width - Largura do gradiente
+ * @param {number} height - Altura do gradiente
+ * @param {string} startColor - Cor inicial do gradiente (hexadecimal)
+ * @param {string} endColor - Cor final do gradiente (hexadecimal)
+ * @param {string} direction - Direção do gradiente ('horizontal', 'vertical', 'diagonal')
+ * @returns {Object} - Objeto de gradiente criado
+ */
+function createLinearGradient(ctx, x, y, width, height, startColor, endColor, direction = 'vertical') {
+    let gradient;
+    
+    switch (direction.toLowerCase()) {
+        case 'horizontal':
+            gradient = ctx.createLinearGradient(x, y, x + width, y);
+            break;
+        case 'diagonal':
+            gradient = ctx.createLinearGradient(x, y, x + width, y + height);
+            break;
+        case 'vertical':
+        default:
+            gradient = ctx.createLinearGradient(x, y, x, y + height);
+            break;
+    }
+    
+    gradient.addColorStop(0, startColor);
+    gradient.addColorStop(1, endColor);
+    
+    return gradient;
+}
+
+/**
+ * Converte uma cor hexadecimal para RGBA
+ * @param {string} hex - Cor em formato hexadecimal
+ * @param {number} alpha - Valor de transparência (0-1)
+ * @returns {string} - Cor em formato RGBA
+ */
+function hexToRgba(hex, alpha = 1) {
+    if (!isValidHexColor(hex)) {
+        return `rgba(0, 0, 0, ${alpha})`;
+    }
+    
+    // Expande formato abreviado (#RGB para #RRGGBB)
+    let r, g, b;
+    if (hex.length === 4) {
+        r = parseInt(hex[1] + hex[1], 16);
+        g = parseInt(hex[2] + hex[2], 16);
+        b = parseInt(hex[3] + hex[3], 16);
+    } else {
+        r = parseInt(hex.slice(1, 3), 16);
+        g = parseInt(hex.slice(3, 5), 16);
+        b = parseInt(hex.slice(5, 7), 16);
+    }
+    
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+
+// --- Funções Adicionais de Utilidade ---
+
+/**
+ * Alias para loadImageWithAxios para compatibilidade
+ * @param {string|Buffer|Object} source - Fonte da imagem
+ * @returns {Promise<Object>} - Objeto bitmap da imagem carregada
+ */
+async function loadImage(source) {
+    return loadImageWithAxios(source);
+}
+
+/**
+ * Alias para encodeToBuffer para compatibilidade
+ * @param {Object} canvas - Objeto canvas do pureimage
+ * @returns {Promise<Buffer>} - Buffer contendo a imagem PNG
+ */
+async function getBufferFromImage(canvas) {
+    return encodeToBuffer(canvas);
+}
+
+/**
+ * Desenha uma imagem mantendo proporção e preenchendo a área especificada
+ * @param {Object} ctx - Contexto de renderização 2D
+ * @param {Object} img - Imagem a ser desenhada
+ * @param {number} x - Posição X
+ * @param {number} y - Posição Y
+ * @param {number} w - Largura da área
+ * @param {number} h - Altura da área
+ * @param {number} offsetX - Deslocamento X (0-1, padrão 0.5 = centro)
+ * @param {number} offsetY - Deslocamento Y (0-1, padrão 0.5 = centro)
+ */
+function drawImageProp(ctx, img, x, y, w, h, offsetX = 0.5, offsetY = 0.5) {
+    if (!img || !img.width || !img.height) return;
+    
+    const iw = img.width;
+    const ih = img.height;
+    const r = Math.min(w / iw, h / ih);
+    let nw = iw * r;
+    let nh = ih * r;
+    let cx, cy, cw, ch, ar = 1;
+
+    // Decide qual dimensão ajustar
+    if (nw < w) ar = w / nw;
+    if (Math.abs(ar - 1) < 1e-14 && nh < h) ar = h / nh;
+    nw *= ar;
+    nh *= ar;
+
+    // Calcula a posição de recorte
+    cw = iw / (nw / w);
+    ch = ih / (nh / h);
+    cx = (iw - cw) * offsetX;
+    cy = (ih - ch) * offsetY;
+
+    // Garante que os valores não sejam negativos
+    if (cx < 0) cx = 0;
+    if (cy < 0) cy = 0;
+    if (cw > iw) cw = iw;
+    if (ch > ih) ch = ih;
+
+    ctx.drawImage(img, cx, cy, cw, ch, x, y, w, h);
+}
+
+/**
+ * Quebra texto em múltiplas linhas centralizadas
+ * @param {Object} ctx - Contexto de renderização 2D
+ * @param {string} text - Texto a ser quebrado
+ * @param {number} x - Posição X central
+ * @param {number} y - Posição Y inicial
+ * @param {number} maxWidth - Largura máxima
+ * @param {number} lineHeight - Altura da linha
+ * @returns {number} - Posição Y final
+ */
+function wrapTextCentered(ctx, text, x, y, maxWidth, lineHeight) {
+    const words = text.split(" ");
+    let line = "";
+    let currentY = y;
+    const lines = [];
+
+    // Primeiro, calcula todas as linhas
+    for (let n = 0; n < words.length; n++) {
+        const testLine = line + words[n] + " ";
+        const metrics = ctx.measureText(testLine);
+        const testWidth = metrics.width;
+
+        if (testWidth > maxWidth && n > 0) {
+            lines.push(line.trim());
+            line = words[n] + " ";
+        } else {
+            line = testLine;
+        }
+    }
+    lines.push(line.trim());
+
+    // Ajusta Y para centralizar verticalmente
+    const totalHeight = lines.length * lineHeight;
+    currentY = y - totalHeight / 2 + lineHeight / 2;
+
+    // Desenha cada linha centralizada
+    const originalAlign = ctx.textAlign;
+    ctx.textAlign = "center";
+    
+    for (const l of lines) {
+        ctx.fillText(l, x, currentY);
+        currentY += lineHeight;
+    }
+    
+    ctx.textAlign = originalAlign;
+    return currentY;
+}
+
+/**
+ * Ajusta o brilho de uma cor
+ * @param {string} color - Cor em formato hexadecimal ou rgba
+ * @param {number} amount - Quantidade de ajuste (-1 a 1)
+ * @returns {string} - Cor ajustada
+ */
+function adjustColor(color, amount) {
+    // Se for rgba, extrai os valores
+    if (color.startsWith("rgba")) {
+        const match = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/);
+        if (match) {
+            let r = parseInt(match[1]);
+            let g = parseInt(match[2]);
+            let b = parseInt(match[3]);
+            const a = match[4] ? parseFloat(match[4]) : 1;
+            
+            r = Math.max(0, Math.min(255, r + Math.round(255 * amount)));
+            g = Math.max(0, Math.min(255, g + Math.round(255 * amount)));
+            b = Math.max(0, Math.min(255, b + Math.round(255 * amount)));
+            
+            return `rgba(${r}, ${g}, ${b}, ${a})`;
+        }
+    }
+    
+    // Se for hexadecimal
+    let hex = color.replace("#", "");
+    
+    // Expande formato abreviado
+    if (hex.length === 3) {
+        hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+    }
+    
+    let r = parseInt(hex.substring(0, 2), 16);
+    let g = parseInt(hex.substring(2, 4), 16);
+    let b = parseInt(hex.substring(4, 6), 16);
+    
+    r = Math.max(0, Math.min(255, r + Math.round(255 * amount)));
+    g = Math.max(0, Math.min(255, g + Math.round(255 * amount)));
+    b = Math.max(0, Math.min(255, b + Math.round(255 * amount)));
+    
+    return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+}
+
+/**
+ * Gera uma cor aleatória
+ * @param {number} minBrightness - Brilho mínimo (0-255)
+ * @param {number} maxBrightness - Brilho máximo (0-255)
+ * @returns {string} - Cor hexadecimal aleatória
+ */
+function getRandomColor(minBrightness = 0, maxBrightness = 255) {
+    const range = maxBrightness - minBrightness;
+    const r = Math.floor(Math.random() * range + minBrightness);
+    const g = Math.floor(Math.random() * range + minBrightness);
+    const b = Math.floor(Math.random() * range + minBrightness);
+    
+    return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+}
+
+/**
+ * Desenha uma estrela
+ * @param {Object} ctx - Contexto de renderização 2D
+ * @param {number} cx - Centro X
+ * @param {number} cy - Centro Y
+ * @param {number} spikes - Número de pontas
+ * @param {number} outerRadius - Raio externo
+ * @param {number} innerRadius - Raio interno
+ * @param {string} fillColor - Cor de preenchimento
+ * @param {string} strokeColor - Cor do contorno (opcional)
+ * @param {number} lineWidth - Largura do contorno (opcional)
+ */
+function drawStar(ctx, cx, cy, spikes, outerRadius, innerRadius, fillColor, strokeColor = null, lineWidth = 1) {
+    let rot = Math.PI / 2 * 3;
+    let x = cx;
+    let y = cy;
+    const step = Math.PI / spikes;
+
+    ctx.beginPath();
+    ctx.moveTo(cx, cy - outerRadius);
+    
+    for (let i = 0; i < spikes; i++) {
+        x = cx + Math.cos(rot) * outerRadius;
+        y = cy + Math.sin(rot) * outerRadius;
+        ctx.lineTo(x, y);
+        rot += step;
+
+        x = cx + Math.cos(rot) * innerRadius;
+        y = cy + Math.sin(rot) * innerRadius;
+        ctx.lineTo(x, y);
+        rot += step;
+    }
+    
+    ctx.lineTo(cx, cy - outerRadius);
+    ctx.closePath();
+    
+    if (fillColor) {
+        ctx.fillStyle = fillColor;
+        ctx.fill();
+    }
+    
+    if (strokeColor) {
+        ctx.strokeStyle = strokeColor;
+        ctx.lineWidth = lineWidth;
+        ctx.stroke();
+    }
+}
+
+/**
+ * Trunca texto para caber em uma largura máxima
+ * @param {Object} ctx - Contexto de renderização 2D
+ * @param {string} text - Texto a ser truncado
+ * @param {number} maxWidth - Largura máxima
+ * @param {string} ellipsis - Caracteres de truncamento (padrão: "...")
+ * @returns {string} - Texto truncado
+ */
+function truncateText(ctx, text, maxWidth, ellipsis = "...") {
+    if (!text) return "";
+    
+    const textWidth = ctx.measureText(text).width;
+    if (textWidth <= maxWidth) return text;
+    
+    const ellipsisWidth = ctx.measureText(ellipsis).width;
+    let truncated = text;
+    
+    while (ctx.measureText(truncated).width + ellipsisWidth > maxWidth && truncated.length > 0) {
+        truncated = truncated.slice(0, -1);
+    }
+    
+    return truncated + ellipsis;
+}
+
+// --- Exportações ---
+module.exports = {
+    // Funções de validação
+    isValidHexColor,
+    
+    // Funções de gerenciamento de fontes
+    registerDefaultFonts,
+    registerFontIfNeeded,
+    
+    // Funções de manipulação de imagens
+    loadImageWithAxios,
+    loadImage,
+    encodeToBuffer,
+    getBufferFromImage,
+    drawImageProp,
+    
+    // Funções de desenho
+    roundRect,
+    wrapText,
+    wrapTextCentered,
+    applyTextShadow,
+    clearShadow,
+    createLinearGradient,
+    drawStar,
+    
+    // Funções de cor
+    hexToRgba,
+    adjustColor,
+    getRandomColor,
+    
+    // Funções de formatação
+    formatTime,
+    formatNumber,
+    truncateText,
+    
+    // Constantes
+    DEFAULT_FONT_FAMILY
+};
+