vanilla-builder 0.2.0 → 0.3.0

package/src/config.js

@@ -3,6 +3,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { BuildError } from './util.js';
+import { L } from './i18n.js';
+import { resolveBrowsers } from './browsers.js';
+import { validateBudgets } from './budgets.js';
+import { validatePlugins, loadPlugins } from './plugins.js';
 
 export const CONFIG_FILES = ['builder.config.json', 'builder.config.mjs', 'builder.config.js'];
 
@@ -43,6 +47,14 @@ export const DEFAULTS = {
   cache: true,
   // Hilos para ofuscar/comprimir en paralelo: "auto" (núcleos - 1, máx. 8), un número, o 0 (sin hilos).
   workers: 'auto',
+  // Navegadores objetivo: 'auto' (browserslist del proyecto si existe), false, o una consulta de browserslist.
+  browsers: 'auto',
+  // Optimizar PNG (sin pérdida) y JPEG/WebP (calidad indicada) con sharp: false, true o { quality: 80 }.
+  images: false,
+  // Presupuestos de tamaño por patrón de salida (o "total"): { "js/**/*.js": "50 KB", "total": "1 MB gzip" }.
+  budgets: false,
+  // Plugins: objetos con ganchos (builder.config.mjs) o nombres de paquete. Ver src/plugins.js.
+  plugins: [],
 };
 
 const NESTED = ['html', 'css', 'js', 'json', 'dependencies'];
@@ -68,13 +80,19 @@ function levenshtein(a, b) {
 
 function suggest(key, options) {
   const best = options.map((o) => [o, levenshtein(key, o)]).sort((x, y) => x[1] - y[1])[0];
-  return best && best[1] <= 3 ? ` ¿Quisiste decir "${best[0]}"?` : '';
+  return best && best[1] <= 3 ? L(` ¿Quisiste decir "${best[0]}"?`, ` Did you mean "${best[0]}"?`) : '';
 }
 
 function checkKeys(obj, defaults, prefix, errors) {
   for (const key of Object.keys(obj)) {
     if (key === '$schema') continue;
-    if (!(key in defaults)) errors.push(`Opción desconocida "${prefix}${key}".${suggest(key, Object.keys(defaults))}`);
+    if (!(key in defaults))
+      errors.push(
+        L(
+          `Opción desconocida "${prefix}${key}".${suggest(key, Object.keys(defaults))}`,
+          `Unknown option "${prefix}${key}".${suggest(key, Object.keys(defaults))}`,
+        ),
+      );
   }
 }
 
@@ -82,7 +100,8 @@ const asList = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
 
 export function normalizeConfig(raw, errors = []) {
   const user = raw ?? {};
-  if (typeof user !== 'object' || Array.isArray(user)) throw new BuildError('La configuración debe ser un objeto JSON.');
+  if (typeof user !== 'object' || Array.isArray(user))
+    throw new BuildError(L('La configuración debe ser un objeto JSON.', 'The configuration must be a JSON object.'));
   checkKeys(user, DEFAULTS, '', errors);
   const cfg = { ...DEFAULTS, ...user };
   for (const k of NESTED) {
@@ -92,47 +111,96 @@ export function normalizeConfig(raw, errors = []) {
     else if (typeof v === 'object') {
       checkKeys(v, DEFAULTS[k], `${k}.`, errors);
       cfg[k] = { ...DEFAULTS[k], ...v };
-    } else errors.push(`"${k}" debe ser un objeto o true/false.`);
+    } else errors.push(L(`"${k}" debe ser un objeto o true/false.`, `"${k}" must be an object or true/false.`));
   }
   for (const k of ['include', 'ignore']) {
     cfg[k] = asList(cfg[k]);
-    if (cfg[k].some((x) => typeof x !== 'string')) errors.push(`"${k}" debe ser una lista de rutas o patrones (texto).`);
+    if (cfg[k].some((x) => typeof x !== 'string'))
+      errors.push(L(`"${k}" debe ser una lista de rutas o patrones (texto).`, `"${k}" must be a list of paths or patterns (text).`));
   }
   for (const k of ['include', 'exclude']) {
     cfg.dependencies[k] = asList(cfg.dependencies[k]);
-    if (cfg.dependencies[k].some((x) => typeof x !== 'string')) errors.push(`"dependencies.${k}" debe ser una lista de rutas o patrones (texto).`);
+    if (cfg.dependencies[k].some((x) => typeof x !== 'string'))
+      errors.push(
+        L(`"dependencies.${k}" debe ser una lista de rutas o patrones (texto).`, `"dependencies.${k}" must be a list of paths or patterns (text).`),
+      );
   }
-  for (const k of ['detect', 'obfuscate']) if (typeof cfg.dependencies[k] !== 'boolean') errors.push(`"dependencies.${k}" debe ser true o false.`);
+  for (const k of ['detect', 'obfuscate'])
+    if (typeof cfg.dependencies[k] !== 'boolean')
+      errors.push(L(`"dependencies.${k}" debe ser true o false.`, `"dependencies.${k}" must be true or false.`));
   if (cfg.entries !== 'auto') {
     cfg.entries = asList(cfg.entries);
     if (!cfg.entries.length || cfg.entries.some((x) => typeof x !== 'string'))
-      errors.push('"entries" debe ser "auto" o una lista de archivos/patrones.');
+      errors.push(L('"entries" debe ser "auto" o una lista de archivos/patrones.', '"entries" must be "auto" or a list of files/patterns.'));
   }
   for (const [key, allowed] of Object.entries(ENUMS)) {
     const [a, b] = key.split('.');
     const value = b ? cfg[a][b] : cfg[a];
-    if (!allowed.includes(value)) errors.push(`"${key}" debe ser uno de: ${allowed.map((x) => JSON.stringify(x)).join(', ')}.`);
+    if (!allowed.includes(value))
+      errors.push(
+        L(
+          `"${key}" debe ser uno de: ${allowed.map((x) => JSON.stringify(x)).join(', ')}.`,
+          `"${key}" must be one of: ${allowed.map((x) => JSON.stringify(x)).join(', ')}.`,
+        ),
+      );
   }
-  if (typeof cfg.outDir !== 'string' || !cfg.outDir.trim()) errors.push('"outDir" debe ser una ruta.');
-  if (typeof cfg.base !== 'string' || !cfg.base.startsWith('/')) errors.push('"base" debe empezar con "/" (ej. "/" o "/mi-sitio/").');
+  if (typeof cfg.outDir !== 'string' || !cfg.outDir.trim()) errors.push(L('"outDir" debe ser una ruta.', '"outDir" must be a path.'));
+  if (typeof cfg.base !== 'string' || !cfg.base.startsWith('/'))
+    errors.push(L('"base" debe empezar con "/" (ej. "/" o "/mi-sitio/").', '"base" must start with "/" (e.g. "/" or "/my-site/").'));
   else if (!cfg.base.endsWith('/')) cfg.base += '/';
-  if (typeof cfg.hash !== 'boolean') errors.push('"hash" debe ser true o false.');
-  if (typeof cfg.cache !== 'boolean') errors.push('"cache" debe ser true o false.');
+  if (typeof cfg.hash !== 'boolean') errors.push(L('"hash" debe ser true o false.', '"hash" must be true or false.'));
+  const b = cfg.browsers;
+  if (!(
+    b === 'auto' ||
+    b === false ||
+    (typeof b === 'string' && b.trim()) ||
+    (Array.isArray(b) && b.length && b.every((x) => typeof x === 'string'))
+  ))
+    errors.push(
+      L(
+        '"browsers" debe ser "auto", false o una consulta de browserslist (texto o lista).',
+        '"browsers" must be "auto", false or a browserslist query (text or list).',
+      ),
+    );
+  const im = cfg.images;
+  if (!(
+    typeof im === 'boolean' ||
+    (im &&
+      typeof im === 'object' &&
+      !Array.isArray(im) &&
+      Object.keys(im).every((k) => k === 'quality') &&
+      (im.quality === undefined || (Number.isInteger(im.quality) && im.quality >= 1 && im.quality <= 100)))
+  ))
+    errors.push(L('"images" debe ser true, false o { "quality": 1-100 }.', '"images" must be true, false or { "quality": 1-100 }.'));
+  errors.push(...validateBudgets(cfg.budgets));
+  errors.push(...validatePlugins(cfg.plugins));
+  if (typeof cfg.cache !== 'boolean') errors.push(L('"cache" debe ser true o false.', '"cache" must be true or false.'));
   if (!(cfg.workers === 'auto' || (Number.isInteger(cfg.workers) && cfg.workers >= 0 && cfg.workers <= 64)))
-    errors.push('"workers" debe ser "auto" o un número entre 0 y 64.');
+    errors.push(L('"workers" debe ser "auto" o un número entre 0 y 64.', '"workers" must be "auto" or a number between 0 and 64.'));
   cfg.js.drop = asList(cfg.js.drop);
-  if (cfg.js.drop.some((d) => !['console', 'debugger'].includes(d))) errors.push('"js.drop" solo admite "console" y "debugger".');
+  if (cfg.js.drop.some((d) => !['console', 'debugger'].includes(d)))
+    errors.push(L('"js.drop" solo admite "console" y "debugger".', '"js.drop" only accepts "console" and "debugger".'));
   if (typeof cfg.js.chunkDir !== 'string' || /(^|\/)\.\.(\/|$)|^\//.test(cfg.js.chunkDir))
-    errors.push('"js.chunkDir" debe ser una carpeta relativa.');
+    errors.push(L('"js.chunkDir" debe ser una carpeta relativa.', '"js.chunkDir" must be a relative folder.'));
   for (const k of ['css', 'js']) {
     const t = cfg[k].target;
     if (!(typeof t === 'string' || (Array.isArray(t) && t.every((x) => typeof x === 'string'))))
-      errors.push(`"${k}.target" debe ser texto o lista (ej. "es2020" o ["chrome90","safari15"]).`);
+      errors.push(
+        L(
+          `"${k}.target" debe ser texto o lista (ej. "es2020" o ["chrome90","safari15"]).`,
+          `"${k}.target" must be text or a list (e.g. "es2020" or ["chrome90","safari15"]).`,
+        ),
+      );
   }
   const o = cfg.obfuscate;
   if (o === true) cfg.obfuscate = 'medium';
   else if (!(o === false || OBF_PRESETS.includes(o) || (o && typeof o === 'object' && !Array.isArray(o))))
-    errors.push(`"obfuscate" debe ser false, true, ${OBF_PRESETS.map((p) => `"${p}"`).join(', ')} o un objeto de opciones de javascript-obfuscator.`);
+    errors.push(
+      L(
+        `"obfuscate" debe ser false, true, ${OBF_PRESETS.map((p) => `"${p}"`).join(', ')} o un objeto de opciones de javascript-obfuscator.`,
+        `"obfuscate" must be false, true, ${OBF_PRESETS.map((p) => `"${p}"`).join(', ')} or an object of javascript-obfuscator options.`,
+      ),
+    );
   return cfg;
 }
 
@@ -142,7 +210,12 @@ async function readConfigFile(file) {
     try {
       return JSON.parse(text);
     } catch (err) {
-      throw new BuildError(`No pude leer ${path.basename(file)}: JSON inválido (${err.message}).`);
+      throw new BuildError(
+        L(
+          `No pude leer ${path.basename(file)}: JSON inválido (${err.message}).`,
+          `Could not read ${path.basename(file)}: invalid JSON (${err.message}).`,
+        ),
+      );
     }
   }
   const mod = await import(`${pathToFileURL(file).href}?t=${fs.statSync(file).mtimeMs}`);
@@ -163,22 +236,32 @@ export function findConfigFile(dir) {
  */
 export async function loadConfig({ dir = '.', config, overrides = {}, cwd = process.cwd() } = {}) {
   const projectDir = path.resolve(cwd, dir);
-  if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) throw new BuildError(`La carpeta del proyecto no existe: ${projectDir}`);
+  if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory())
+    throw new BuildError(L(`La carpeta del proyecto no existe: ${projectDir}`, `The project folder does not exist: ${projectDir}`));
   const configFile = config ? path.resolve(cwd, config) : findConfigFile(projectDir);
-  if (config && !fs.existsSync(configFile)) throw new BuildError(`No existe el archivo de configuración: ${configFile}`);
+  if (config && !fs.existsSync(configFile))
+    throw new BuildError(L(`No existe el archivo de configuración: ${configFile}`, `The configuration file does not exist: ${configFile}`));
   const fileCfg = configFile ? await readConfigFile(configFile) : {};
   const merged = mergeOverrides(fileCfg ?? {}, overrides);
   const errors = [];
   const cfg = normalizeConfig(merged, errors);
-  if (errors.length) throw new BuildError('La configuración tiene errores:', errors);
+  if (errors.length) throw new BuildError(L('La configuración tiene errores:', 'The configuration has errors:'), errors);
   const baseDir = configFile ? path.dirname(configFile) : projectDir;
   cfg.root = path.resolve(baseDir, cfg.root);
-  if (!fs.existsSync(cfg.root)) throw new BuildError(`"root" no existe: ${cfg.root}`);
+  if (!fs.existsSync(cfg.root)) throw new BuildError(L(`"root" no existe: ${cfg.root}`, `"root" does not exist: ${cfg.root}`));
   // esbuild resuelve los enlaces simbólicos de lo que importa; si la raíz no es la ruta real, el mismo
   // módulo aparece con dos rutas (pasa en macOS con /tmp → /private/tmp, o al abrir el proyecto por un enlace).
   cfg.root = fs.realpathSync(cfg.root);
   cfg.outDir = path.resolve(cfg.root, cfg.outDir);
   cfg.configFile = configFile;
+  // Navegadores objetivo (browserslist): solo cambian los targets que siguen con su valor por defecto.
+  cfg.plugins = await loadPlugins(cfg.plugins, cfg.root);
+  cfg.browserTargets = await resolveBrowsers(cfg.root, cfg.browsers);
+  const targets = cfg.browserTargets?.targets;
+  if (targets?.length) {
+    if (cfg.css.target === DEFAULTS.css.target) cfg.css.target = targets;
+    if (cfg.js.target === DEFAULTS.js.target) cfg.js.target = targets;
+  }
   return cfg;
 }
 

package/src/deps.js

@@ -1,5 +1,6 @@
 // Detección de librerías de terceros (jQuery, Bootstrap, paquetes de npm...).
 // No se ofuscan: no aporta nada, las hace más lentas y puede romper su licencia.
+import { L } from './i18n.js';
 
 const DEP_DIRS = /(^|\/)(node_modules|bower_components|jspm_packages|web_modules|vendors?|third[-_]?party|external|externals)\//i;
 const MIN_NAME = /[.-](min|prod|production)\.m?js$|\.umd(\.min)?\.m?js$/i;
@@ -177,23 +178,27 @@ export function packageNames(pkg) {
  * @param {{packages?: Map<string, string>}} [hints] nombres de package.json del proyecto
  */
 export function detectDependency(rel, code = '', hints = {}) {
-  if (DEP_DIRS.test(rel)) return `está en ${rel.match(DEP_DIRS)[2]}/`;
+  if (DEP_DIRS.test(rel)) return L(`está en ${rel.match(DEP_DIRS)[2]}/`, `in ${rel.match(DEP_DIRS)[2]}/`);
   const name = rel.split('/').pop();
-  if (KNOWN.test(name)) return 'nombre de librería conocida';
-  if (MIN_NAME.test(name)) return 'versión ya compilada (.min.js / .umd.js)';
+  if (KNOWN.test(name)) return L('nombre de librería conocida', 'well-known library name');
+  if (MIN_NAME.test(name)) return L('versión ya compilada (.min.js / .umd.js)', 'already compiled build (.min.js / .umd.js)');
   const pkgName = packageLikeName(name);
-  if (hints.packages?.has(pkgName)) return `se llama como el paquete "${hints.packages.get(pkgName)}" de tu package.json`;
+  if (hints.packages?.has(pkgName))
+    return L(
+      `se llama como el paquete "${hints.packages.get(pkgName)}" de tu package.json`,
+      `named like the "${hints.packages.get(pkgName)}" package in your package.json`,
+    );
   const edges = code.length > 8000 ? code.slice(0, 5000) + code.slice(-3000) : code;
-  if (UMD.some((re) => re.test(edges))) return 'envoltorio UMD/AMD (formato de librería publicada)';
+  if (UMD.some((re) => re.test(edges))) return L('envoltorio UMD/AMD (formato de librería publicada)', 'UMD/AMD wrapper (published library format)');
   // Cabecera de librería publicada: /*! o @license con número de versión (jQuery v3.7.1, Bootstrap v5.3.0...).
   // Una cabecera propia sin versión ("/*! Mi app (c) 2026 */") no basta.
   const header = /^\s*\/\*[\s\S]*?\*\//.exec(code.slice(0, 3000))?.[0] ?? '';
   if ((/^\s*\/\*!/.test(header) || /@(license|preserve)\b/.test(header)) && /\bv?\d+\.\d+(\.\d+)?\b/.test(header))
-    return 'cabecera de licencia con versión';
+    return L('cabecera de licencia con versión', 'license header with a version');
   // Código ya minificado: pocas líneas muy largas.
   if (code.length > 4000) {
     const lines = code.split('\n').length;
-    if (code.length / lines > 500) return 'código ya minificado';
+    if (code.length / lines > 500) return L('código ya minificado', 'already minified code');
   }
   return null;
 }

package/src/files.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import picomatch from 'picomatch';
 import { CONFIG_FILES } from './config.js';
 import { relFrom, toPosix, extOf } from './util.js';
+import { L } from './i18n.js';
 
 /** Archivos de desarrollo que nunca deberían publicarse. Se desactiva con defaultIgnore:false. */
 export const DEFAULT_IGNORE = [
@@ -85,7 +86,7 @@ export function scanProject(cfg) {
     try {
       entries = fs.readdirSync(dir, { withFileTypes: true });
     } catch (err) {
-      ignored.push({ rel: relFrom(root, dir) || '.', reason: `no se pudo leer (${err.code})` });
+      ignored.push({ rel: relFrom(root, dir) || '.', reason: L(`no se pudo leer (${err.code})`, `could not be read (${err.code})`) });
       return;
     }
     entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
@@ -100,9 +101,10 @@ export function scanProject(cfg) {
           const st = fs.statSync(abs);
           isFile = st.isFile();
           isDir = false;
-          if (st.isDirectory()) ignored.push({ rel, reason: 'enlace simbólico a carpeta (no se sigue)' });
+          if (st.isDirectory())
+            ignored.push({ rel, reason: L('enlace simbólico a carpeta (no se sigue)', 'symbolic link to a folder (not followed)') });
         } catch {
-          ignored.push({ rel, reason: 'enlace simbólico roto' });
+          ignored.push({ rel, reason: L('enlace simbólico roto', 'broken symbolic link') });
           continue;
         }
       }
@@ -113,7 +115,10 @@ export function scanProject(cfg) {
         const byUser = isUser(rel) || isUser(probe);
         const wanted = cfg.include.some((p) => normalizePattern(p).startsWith(`${rel}/`) || p.startsWith('**'));
         if ((byUser || isDefault(probe)) && !wanted) {
-          ignored.push({ rel: `${rel}/`, reason: byUser ? 'ignore (configuración)' : 'excluido por defecto' });
+          ignored.push({
+            rel: `${rel}/`,
+            reason: byUser ? L('ignore (configuración)', 'ignore (configuration)') : L('excluido por defecto', 'excluded by default'),
+          });
           continue;
         }
         walk(abs);
@@ -123,9 +128,9 @@ export function scanProject(cfg) {
       const forced = isIncluded(rel);
       let reason = null;
       if (!forced) {
-        if (isSecret(rel)) reason = 'posible secreto (excluido por seguridad)';
-        else if (isUser(rel)) reason = 'ignore (configuración)';
-        else if (isDefault(rel)) reason = 'excluido por defecto';
+        if (isSecret(rel)) reason = L('posible secreto (excluido por seguridad)', 'possible secret (excluded for safety)');
+        else if (isUser(rel)) reason = L('ignore (configuración)', 'ignore (configuration)');
+        else if (isDefault(rel)) reason = L('excluido por defecto', 'excluded by default');
       }
       if (reason) {
         ignored.push({ rel, reason });

package/src/html.js

@@ -1,5 +1,6 @@
 // HTML: extrae referencias con su posición exacta, aplica ediciones puntuales y minifica con verificación.
 import { parse } from 'parse5';
+import { L } from './i18n.js';
 
 const JS_TYPES = new Set([
   '',
@@ -215,7 +216,7 @@ export function applyEdits(text, edits) {
   let out = text;
   let limit = Infinity;
   for (const e of sorted) {
-    if (e.end > limit) throw new Error(`Ediciones superpuestas en la posición ${e.start}`);
+    if (e.end > limit) throw new Error(L(`Ediciones superpuestas en la posición ${e.start}`, `Overlapping edits at position ${e.start}`));
     out = out.slice(0, e.start) + e.text + out.slice(e.end);
     limit = e.start;
   }
@@ -324,7 +325,7 @@ export async function minifyHtml(text, { removeComments, collapseWhitespace }) {
   try {
     out = applyEdits(text, minifyEdits(text, { removeComments, collapseWhitespace }));
   } catch (err) {
-    return { code: text, note: `no se pudo minificar el HTML (${err.message})` };
+    return { code: text, note: L(`no se pudo minificar el HTML (${err.message})`, `could not minify the HTML (${err.message})`) };
   }
   const before = htmlSignature(text);
   const after = htmlSignature(out);
@@ -332,7 +333,13 @@ export async function minifyHtml(text, { removeComments, collapseWhitespace }) {
     let i = 0;
     while (i < before.length && before[i] === after[i]) i++;
     const near = before.slice(Math.max(0, i - 40), i + 40).replace(/\s+/g, ' ');
-    return { code: text, note: `la minificación cambiaba la estructura cerca de «${near}»; se deja sin minificar` };
+    return {
+      code: text,
+      note: L(
+        `la minificación cambiaba la estructura cerca de «${near}»; se deja sin minificar`,
+        `minification changed the structure near «${near}»; left unminified`,
+      ),
+    };
   }
   return { code: out };
 }

package/src/i18n.js

@@ -0,0 +1,33 @@
+// Idioma de los mensajes: inglés o español.
+// Prioridad: --lang / setLang() > BUILDER_LANG > LC_ALL / LC_MESSAGES / LANG > idioma del sistema > inglés.
+// Los campos de --json, la configuración y los nombres de fase no se traducen nunca.
+
+function detect() {
+  const env = process.env;
+  const explicit = env.BUILDER_LANG;
+  if (explicit) return /^es/i.test(explicit) ? 'es' : 'en';
+  const posix = env.LC_ALL || env.LC_MESSAGES || env.LANG;
+  // "C" y "POSIX" no dicen nada del idioma de la persona: se mira el del sistema.
+  if (posix && !/^(C|POSIX)(\.|$)/i.test(posix)) return /^es/i.test(posix) ? 'es' : 'en';
+  try {
+    return /^es\b/i.test(Intl.DateTimeFormat().resolvedOptions().locale) ? 'es' : 'en';
+  } catch {
+    return 'en';
+  }
+}
+
+let lang = detect();
+
+/** Cambia el idioma ('en' o 'es'). */
+export function setLang(value) {
+  lang = /^es/i.test(String(value)) ? 'es' : 'en';
+}
+
+export function getLang() {
+  return lang;
+}
+
+/** Devuelve el texto en el idioma activo. Ambos textos se escriben juntos en el código. */
+export function L(es, en) {
+  return lang === 'es' ? es : en;
+}

package/src/images.js

@@ -0,0 +1,61 @@
+// Optimización de imágenes con sharp (dependencia opcional). Mismo formato y mismo nombre: no cambia ninguna referencia.
+// - PNG: recompresión sin pérdida, comprobada píxel a píxel.
+// - JPEG y WebP: se recodifican con la calidad indicada (con pérdida, visualmente equivalente).
+// Se conservan los metadatos (orientación EXIF, perfil de color). Si el resultado no es más pequeño, se deja el original.
+import { importOptional } from './optional.js';
+import { L } from './i18n.js';
+
+export const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp']);
+
+let sharpMod = null;
+
+export async function ensureSharp(root) {
+  if (!sharpMod) {
+    const mod = await importOptional('sharp', root, L('para optimizar imágenes (--images)', 'to optimize images (--images)'));
+    sharpMod = mod.default ?? mod;
+  }
+  return sharpMod;
+}
+
+/** Opciones normalizadas de "images": false, true o { quality }. */
+export function imageOptions(setting) {
+  if (!setting) return null;
+  const quality = typeof setting === 'object' && Number.isInteger(setting.quality) ? setting.quality : 80;
+  return { quality };
+}
+
+async function samePixels(sharp, a, b) {
+  const [ra, rb] = await Promise.all([
+    sharp(a).ensureAlpha().raw().toBuffer({ resolveWithObject: true }),
+    sharp(b).ensureAlpha().raw().toBuffer({ resolveWithObject: true }),
+  ]);
+  return ra.info.width === rb.info.width && ra.info.height === rb.info.height && ra.data.equals(rb.data);
+}
+
+/**
+ * @returns {Promise<{data: Buffer} | {skip: string}>} la imagen optimizada, o el motivo para dejar la original.
+ */
+export async function optimizeImage(sharp, buf, ext, { quality }) {
+  let meta;
+  try {
+    meta = await sharp(buf).metadata();
+  } catch (err) {
+    return { skip: L(`no se pudo leer la imagen (${err.message})`, `could not read the image (${err.message})`) };
+  }
+  if ((meta.pages ?? 1) > 1) return { skip: L('imagen animada', 'animated image') };
+  const base = () => sharp(buf).keepMetadata();
+  let out;
+  try {
+    if (ext === '.png') out = await base().png({ compressionLevel: 9, effort: 10, palette: false, adaptiveFiltering: true }).toBuffer();
+    else if (ext === '.webp') out = await base().webp({ quality, effort: 6 }).toBuffer();
+    else out = await base().jpeg({ quality, mozjpeg: true }).toBuffer();
+  } catch (err) {
+    return { skip: L(`sharp falló (${err.message})`, `sharp failed (${err.message})`) };
+  }
+  if (out.length >= buf.length) return { skip: L('ya estaba optimizada', 'already optimized') };
+  const after = await sharp(out).metadata();
+  if (after.width !== meta.width || after.height !== meta.height || after.format !== meta.format)
+    return { skip: L('el resultado no conserva tamaño o formato', 'the result does not keep size or format') };
+  if (ext === '.png' && !(await samePixels(sharp, buf, out))) return { skip: L('los píxeles no coinciden', 'pixels do not match') };
+  return { data: out };
+}