@assetopt/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# @assetopt/core
+
+Pure asset optimization functions for images (sharp), CSS (lightningcss), JS (esbuild), and SVG (svgo). The engine behind the [`@assetopt/cli`](https://www.npmjs.com/package/@assetopt/cli) command-line tool, exported as a standalone library for programmatic use.
+
+Open source, MIT.
+
+## Install
+
+```bash
+npm install @assetopt/core
+```
+
+## Quick start
+
+```ts
+import { optimizeImage, optimizeCss, optimizeJs, optimizeSvg } from '@assetopt/core';
+import { readFile } from 'node:fs/promises';
+
+const buf = await readFile('photo.jpg');
+const result = await optimizeImage(buf, { quality: { jpeg: 80 } });
+
+console.log(result.format); // 'jpeg'
+console.log(result.originalSize); // 824133
+console.log(result.outputSize); // 245912
+console.log(result.buffer); // Buffer with optimized bytes
+```
+
+Every optimizer is a pure function: a buffer in, an optimized buffer out. No hidden I/O, no global state.
+
+## API
+
+### Optimizers
+
+| Function                          | Underlying lib | Returns                      |
+| --------------------------------- | -------------- | ---------------------------- |
+| `optimizeImage(buffer, options?)` | `sharp`        | `Promise<ImageBufferResult>` |
+| `optimizeCss(buffer, options?)`   | `lightningcss` | `CssBufferResult`            |
+| `optimizeJs(buffer, options?)`    | `esbuild`      | `Promise<JsBufferResult>`    |
+| `optimizeSvg(buffer, options?)`   | `svgo`         | `SvgBufferResult`            |
+
+All option types are optional with sensible defaults:
+
+- `ImageOptimizeOptions` — `{ outputFormat?, formatMatrix?, quality?, stripMetadata?, skip? }`
+- `CssOptimizeOptions` — `{ minify? }`
+- `JsOptimizeOptions` — `{ minify? }`
+- `SvgOptimizeOptions` — `{ multipass?, minifyIds? }`
+
+### Pipeline
+
+For folder-level orchestration:
+
+```ts
+import { runPipeline, buildReport, loadConfig } from '@assetopt/core';
+
+const { config } = await loadConfig(); // walk-up .assetoptrc
+const assets = await runPipeline('./public', config);
+const report = buildReport(assets, /* durationMs */ 0);
+```
+
+### Format matrix with smart routing
+
+`formatMatrix` accepts function values for content-aware routing:
+
+```ts
+import { optimizeImage } from '@assetopt/core';
+
+await optimizeImage(buf, {
+  formatMatrix: {
+    // AVIF for transparent PNGs, WebP for opaque ones
+    png: (ctx) => (ctx.hasAlpha ? 'avif' : 'webp'),
+    jpeg: 'webp',
+    webp: 'keep',
+    avif: 'keep',
+  },
+});
+```
+
+This is exactly how the built-in `web-perf` preset works.
+
+### Exports
+
+```ts
+// Optimizers (pure functions)
+export { optimizeImage, optimizeCss, optimizeJs, optimizeSvg };
+
+// Pipeline / orchestration
+export { dispatch, runPipeline, buildReport };
+
+// Config
+export { loadConfig, mergeConfig, resolveConfig, DEFAULTS, PRESETS };
+export type { LoadedConfig };
+
+// Utilities
+export { scanDirectory, getAssetType, getFileSize };
+export { CACHE_FILE }; // name of the on-disk cache manifest, relative to output.dir
+
+// Types
+export type {
+  AssetType,
+  AssetResult,
+  OptimizeResult,
+  ImageQualityOptions,
+  ImageOptimizeOptions,
+  ImageBufferResult,
+  ImageSourceFormat,
+  ImageMatrixTarget,
+  FormatMatrixValue,
+  FormatMatrixResolver,
+  FormatRoutingContext,
+  PresetName,
+  CssOptimizeOptions,
+  CssBufferResult,
+  JsOptimizeOptions,
+  JsBufferResult,
+  SvgOptimizeOptions,
+  SvgBufferResult,
+  DispatchResult,
+  AssetoptConfig,
+};
+```
+
+## Documentation
+
+- [Configuration reference](https://github.com/Nathmaxx/assetopt/blob/main/docs/config.md) — every option, every default, programmatic API for `formatMatrix` functions
+- [Feature catalog](https://github.com/Nathmaxx/assetopt/blob/main/docs/features.md) — behavior of each optimizer in plain English
+- [Project README](https://github.com/Nathmaxx/assetopt#readme)
+
+For the command-line interface, see [`@assetopt/cli`](https://www.npmjs.com/package/@assetopt/cli).
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,185 @@
+declare const IMAGE_SOURCE_FORMATS: readonly ["jpeg", "png", "webp", "avif"];
+declare const IMAGE_MATRIX_TARGETS: readonly ["jpeg", "png", "webp", "avif", "keep"];
+declare const IMAGE_OUTPUT_FORMATS: readonly ["keep", "webp", "avif"];
+declare const PRESET_NAMES: readonly ["web-perf", "max-compression", "quality", "compatibility"];
+type ImageSourceFormat = (typeof IMAGE_SOURCE_FORMATS)[number];
+type ImageMatrixTarget = (typeof IMAGE_MATRIX_TARGETS)[number];
+type ImageOutputFormat = (typeof IMAGE_OUTPUT_FORMATS)[number];
+type PresetName = (typeof PRESET_NAMES)[number];
+
+type AssetType = 'image' | 'css' | 'js' | 'svg';
+interface AssetResult {
+    inputPath: string;
+    outputPath: string;
+    inputSize: number;
+    outputSize: number;
+    savedBytes: number;
+    savedPercent: number;
+    assetType: AssetType;
+    durationMs: number;
+    cached: boolean;
+}
+interface OptimizeResult {
+    assets: AssetResult[];
+    totalInputSize: number;
+    totalOutputSize: number;
+    totalSavedBytes: number;
+    totalSavedPercent: number;
+    durationMs: number;
+    cachedCount: number;
+}
+interface ImageQualityOptions {
+    jpeg?: number;
+    png?: number;
+    webp?: number;
+    avif?: number;
+}
+interface FormatRoutingContext {
+    hasAlpha: boolean;
+}
+type FormatMatrixResolver = (ctx: FormatRoutingContext) => ImageMatrixTarget;
+type FormatMatrixValue = ImageMatrixTarget | FormatMatrixResolver;
+interface ImageOptimizeOptions {
+    outputFormat?: ImageOutputFormat;
+    formatMatrix?: Partial<Record<ImageSourceFormat, FormatMatrixValue>>;
+    quality?: ImageQualityOptions;
+    stripMetadata?: boolean;
+    skip?: ImageSourceFormat[];
+}
+interface ImageBufferResult {
+    buffer: Buffer;
+    format: ImageSourceFormat;
+    originalSize: number;
+    outputSize: number;
+}
+interface CssOptimizeOptions {
+    minify?: boolean;
+}
+interface CssBufferResult {
+    buffer: Buffer;
+    originalSize: number;
+    outputSize: number;
+}
+interface JsOptimizeOptions {
+    minify?: boolean;
+}
+interface JsBufferResult {
+    buffer: Buffer;
+    originalSize: number;
+    outputSize: number;
+}
+interface SvgOptimizeOptions {
+    multipass?: boolean;
+    minifyIds?: boolean;
+}
+interface SvgBufferResult {
+    buffer: Buffer;
+    originalSize: number;
+    outputSize: number;
+}
+type DispatchResult = (ImageBufferResult & {
+    assetType: 'image';
+}) | (CssBufferResult & {
+    assetType: 'css';
+}) | (JsBufferResult & {
+    assetType: 'js';
+}) | (SvgBufferResult & {
+    assetType: 'svg';
+});
+interface AssetoptConfig {
+    preset?: PresetName;
+    images?: ImageOptimizeOptions;
+    css?: CssOptimizeOptions;
+    js?: JsOptimizeOptions;
+    svg?: SvgOptimizeOptions;
+    output?: {
+        dir?: string;
+    };
+}
+
+/**
+ * Optimize an image buffer using sharp.
+ *
+ * The output format is resolved with this priority:
+ *   1. `options.formatMatrix[inputFormat]` if defined (target format, `'keep'`, or a function)
+ *   2. `options.outputFormat` if not `'keep'`
+ *   3. The input format (no conversion)
+ *
+ * Function values in `formatMatrix` receive a `FormatRoutingContext` built from sharp
+ * metadata (currently exposes `hasAlpha`). This is how the `web-perf` preset routes
+ * PNG to WebP (opaque) or AVIF (transparent) automatically.
+ *
+ * Defaults come from `IMAGE_DEFAULTS` (quality 85/80/82/75 for jpeg/png/webp/avif,
+ * `stripMetadata: true`, `outputFormat: 'keep'`).
+ *
+ * @param input - Image buffer. Supported source formats: JPEG, PNG, WebP, AVIF.
+ *                Unrecognized formats fall back to JPEG handling.
+ * @param options - All fields optional. See `ImageOptimizeOptions`.
+ * @returns Resolved buffer with output format and size metadata.
+ *
+ * @example
+ * ```ts
+ * // Simple global conversion
+ * await optimizeImage(buf, { outputFormat: 'webp' });
+ *
+ * // Per-format rules (JSON-serializable, usable in .assetoptrc)
+ * await optimizeImage(buf, {
+ *   formatMatrix: { jpeg: 'webp', png: 'avif', webp: 'keep', avif: 'keep' },
+ * });
+ *
+ * // Smart routing (programmatic only — functions can't live in JSON)
+ * await optimizeImage(buf, {
+ *   formatMatrix: { png: (ctx) => ctx.hasAlpha ? 'avif' : 'webp' },
+ * });
+ * ```
+ */
+declare function optimizeImage(input: Buffer, options?: ImageOptimizeOptions): Promise<ImageBufferResult>;
+
+declare function optimizeCss(input: Buffer, options?: CssOptimizeOptions): CssBufferResult;
+
+declare function optimizeJs(input: Buffer, options?: JsOptimizeOptions): Promise<JsBufferResult>;
+
+declare function optimizeSvg(input: Buffer, options?: SvgOptimizeOptions): SvgBufferResult;
+
+declare function dispatch(filePath: string, buffer: Buffer, config?: AssetoptConfig): Promise<DispatchResult>;
+
+declare function runPipeline(inputDir: string, config?: AssetoptConfig, options?: {
+    dryRun?: boolean;
+    useCache?: boolean;
+    onProgress?: (current: number, total: number, filePath: string) => void;
+}): Promise<AssetResult[]>;
+
+declare function buildReport(assets: AssetResult[], durationMs: number): OptimizeResult;
+
+/** Conventional file name for the on-disk manifest, relative to `output.dir`. */
+declare const CACHE_FILE = ".assetopt-cache.json";
+
+type Config = AssetoptConfig;
+
+declare const DEFAULTS: Config;
+/**
+ * Result of {@link loadConfig}: the resolved config plus the absolute path of
+ * the `.assetoptrc` it came from, or `null` if no config file was found and
+ * `DEFAULTS` are being used. Callers (CLI) use `source` to surface a clear
+ * indicator about whether the user's config took effect.
+ */
+interface LoadedConfig {
+    config: Config;
+    source: string | null;
+}
+/**
+ * Walks up from `cwd` (default `process.cwd()`) looking for `.assetoptrc` or
+ * `.assetoptrc.json`. Returns the resolved config plus the absolute path it
+ * was loaded from, or `DEFAULTS` with `source: null` if nothing was found.
+ */
+declare function loadConfig(cwd?: string): Promise<LoadedConfig>;
+declare function resolveConfig(userConfig: Config): Config;
+declare function mergeConfig(base: Config, override: Partial<Config>): Config;
+
+declare const PRESETS: Record<PresetName, Partial<AssetoptConfig>>;
+
+declare function getAssetType(filePath: string): AssetType | null;
+declare function scanDirectory(dirPath: string, recursive?: boolean): Promise<string[]>;
+declare function getFileSize(filePath: string): Promise<number>;
+
+export { type AssetResult, type AssetType, type AssetoptConfig, CACHE_FILE, type CssBufferResult, type CssOptimizeOptions, DEFAULTS, type DispatchResult, type FormatMatrixResolver, type FormatMatrixValue, type FormatRoutingContext, type ImageBufferResult, type ImageMatrixTarget, type ImageOptimizeOptions, type ImageQualityOptions, type ImageSourceFormat, type JsBufferResult, type JsOptimizeOptions, type LoadedConfig, type OptimizeResult, PRESETS, type PresetName, type SvgBufferResult, type SvgOptimizeOptions, buildReport, dispatch, getAssetType, getFileSize, loadConfig, mergeConfig, optimizeCss, optimizeImage, optimizeJs, optimizeSvg, resolveConfig, runPipeline, scanDirectory };

package/dist/index.js

@@ -0,0 +1,582 @@
+// src/optimizers/images.ts
+import sharp from "sharp";
+
+// src/types/formats.ts
+var IMAGE_SOURCE_FORMATS = ["jpeg", "png", "webp", "avif"];
+var IMAGE_MATRIX_TARGETS = ["jpeg", "png", "webp", "avif", "keep"];
+var IMAGE_OUTPUT_FORMATS = ["keep", "webp", "avif"];
+var PRESET_NAMES = ["web-perf", "max-compression", "quality", "compatibility"];
+
+// src/optimizers/images.ts
+var SUPPORTED_INPUT_FORMATS = new Set(IMAGE_SOURCE_FORMATS);
+var IMAGE_DEFAULTS = {
+  outputFormat: "keep",
+  quality: { jpeg: 85, png: 80, webp: 82, avif: 75 },
+  stripMetadata: true
+};
+function normalizeInputFormat(format) {
+  if (format === "heif") return "avif";
+  if (SUPPORTED_INPUT_FORMATS.has(format)) return format;
+  return "jpeg";
+}
+function resolveOutputFormat(inputFormat, outputFormat, formatMatrix, context) {
+  const matrixValue = formatMatrix?.[inputFormat];
+  if (matrixValue !== void 0) {
+    const resolved = typeof matrixValue === "function" ? matrixValue(context) : matrixValue;
+    return resolved === "keep" ? inputFormat : resolved;
+  }
+  if (outputFormat !== "keep") return outputFormat;
+  return inputFormat;
+}
+async function optimizeImage(input, options = {}) {
+  const outputFormat = options.outputFormat ?? IMAGE_DEFAULTS.outputFormat;
+  const quality = { ...IMAGE_DEFAULTS.quality, ...options.quality };
+  const stripMetadata = options.stripMetadata ?? IMAGE_DEFAULTS.stripMetadata;
+  const image = sharp(input);
+  const metadata = await image.metadata();
+  const inputFormat = normalizeInputFormat(metadata.format ?? "jpeg");
+  const targetFormat = resolveOutputFormat(inputFormat, outputFormat, options.formatMatrix, {
+    hasAlpha: metadata.hasAlpha ?? false
+  });
+  let pipeline = stripMetadata ? image : image.withMetadata();
+  switch (targetFormat) {
+    case "jpeg":
+      pipeline = pipeline.jpeg({ quality: quality.jpeg });
+      break;
+    case "png":
+      pipeline = pipeline.png({ quality: quality.png });
+      break;
+    case "webp":
+      pipeline = pipeline.webp({ quality: quality.webp });
+      break;
+    case "avif":
+      pipeline = pipeline.avif({ quality: quality.avif });
+      break;
+  }
+  const outputBuffer = await pipeline.toBuffer();
+  return {
+    buffer: outputBuffer,
+    format: targetFormat,
+    originalSize: input.length,
+    outputSize: outputBuffer.length
+  };
+}
+
+// src/optimizers/css.ts
+import { transform } from "lightningcss";
+var CSS_DEFAULTS = {
+  minify: true
+};
+function optimizeCss(input, options = {}) {
+  const minify = options.minify ?? CSS_DEFAULTS.minify;
+  const { code } = transform({
+    filename: "style.css",
+    code: input,
+    minify
+  });
+  return {
+    buffer: Buffer.from(code),
+    originalSize: input.length,
+    outputSize: code.length
+  };
+}
+
+// src/optimizers/js.ts
+import { transform as transform2 } from "esbuild";
+var JS_DEFAULTS = {
+  minify: true
+};
+async function optimizeJs(input, options = {}) {
+  const minify = options.minify ?? JS_DEFAULTS.minify;
+  const { code } = await transform2(input.toString("utf-8"), {
+    minifyWhitespace: minify,
+    minifyIdentifiers: minify,
+    minifySyntax: minify
+  });
+  const outputBuffer = Buffer.from(code, "utf-8");
+  return {
+    buffer: outputBuffer,
+    originalSize: input.length,
+    outputSize: outputBuffer.length
+  };
+}
+
+// src/optimizers/svg.ts
+import { optimize } from "svgo";
+var SVG_DEFAULTS = {
+  multipass: true,
+  minifyIds: false
+};
+function optimizeSvg(input, options = {}) {
+  const multipass = options.multipass ?? SVG_DEFAULTS.multipass;
+  const minifyIds = options.minifyIds ?? SVG_DEFAULTS.minifyIds;
+  const result = optimize(input.toString("utf-8"), {
+    multipass,
+    plugins: [
+      {
+        name: "preset-default",
+        params: {
+          overrides: minifyIds ? {} : { cleanupIds: { minify: false } }
+        }
+      }
+    ]
+  });
+  const outputBuffer = Buffer.from(result.data, "utf-8");
+  return {
+    buffer: outputBuffer,
+    originalSize: input.length,
+    outputSize: outputBuffer.length
+  };
+}
+
+// src/utils/fs.ts
+import { readdir, stat, readFile, writeFile, mkdir } from "fs/promises";
+import { extname, resolve, dirname } from "path";
+var EXTENSION_TO_TYPE = {
+  ".jpg": "image",
+  ".jpeg": "image",
+  ".png": "image",
+  ".webp": "image",
+  ".avif": "image",
+  ".css": "css",
+  ".js": "js",
+  ".mjs": "js",
+  ".svg": "svg"
+};
+var EXTENSION_TO_IMAGE_FORMAT = {
+  ".jpg": "jpeg",
+  ".jpeg": "jpeg",
+  ".png": "png",
+  ".webp": "webp",
+  ".avif": "avif"
+};
+function getAssetType(filePath) {
+  return EXTENSION_TO_TYPE[extname(filePath).toLowerCase()] ?? null;
+}
+function getImageSourceFormat(filePath) {
+  return EXTENSION_TO_IMAGE_FORMAT[extname(filePath).toLowerCase()] ?? null;
+}
+async function scanDirectory(dirPath, recursive = true) {
+  const entries = await readdir(dirPath, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const fullPath = resolve(dirPath, entry.name);
+    if (entry.isDirectory() && recursive) {
+      files.push(...await scanDirectory(fullPath, recursive));
+    } else if (entry.isFile() && getAssetType(fullPath) !== null) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+async function getFileSize(filePath) {
+  const stats = await stat(filePath);
+  return stats.size;
+}
+async function ensureDir(dirPath) {
+  await mkdir(dirPath, { recursive: true });
+}
+async function readBuffer(filePath) {
+  return readFile(filePath);
+}
+async function writeBuffer(filePath, data) {
+  await ensureDir(dirname(filePath));
+  await writeFile(filePath, data);
+}
+
+// src/pipeline/dispatch.ts
+async function dispatch(filePath, buffer, config = {}) {
+  const assetType = getAssetType(filePath);
+  switch (assetType) {
+    case "image": {
+      const result = await optimizeImage(buffer, config.images);
+      return { ...result, assetType: "image" };
+    }
+    case "css": {
+      const result = optimizeCss(buffer, config.css);
+      return { ...result, assetType: "css" };
+    }
+    case "js": {
+      const result = await optimizeJs(buffer, config.js);
+      return { ...result, assetType: "js" };
+    }
+    case "svg": {
+      const result = optimizeSvg(buffer, config.svg);
+      return { ...result, assetType: "svg" };
+    }
+    default:
+      throw new Error(`Unsupported asset type for file: ${filePath}`);
+  }
+}
+
+// src/pipeline/pipeline.ts
+import path from "path";
+import { existsSync, readFileSync } from "fs";
+import { fileURLToPath } from "url";
+
+// src/utils/savings.ts
+function computeSavedPercent(savedBytes, totalBytes) {
+  if (totalBytes <= 0) return 0;
+  return Math.round(savedBytes / totalBytes * 1e4) / 100;
+}
+
+// src/cache/manifest.ts
+import { createHash } from "crypto";
+import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, sep } from "path";
+function toPosixPath(p) {
+  return sep === "/" ? p : p.split(sep).join("/");
+}
+var CACHE_FILE = ".assetopt-cache.json";
+function stableStringify(value) {
+  if (typeof value === "function") {
+    return JSON.stringify(value.toString());
+  }
+  if (value === null || typeof value !== "object") {
+    const serialized = JSON.stringify(value);
+    return serialized === void 0 ? "null" : serialized;
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  const obj = value;
+  const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+  const parts = keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k]));
+  return "{" + parts.join(",") + "}";
+}
+function computeCacheKey(buffer, options, version) {
+  const hash = createHash("sha256");
+  hash.update(buffer);
+  hash.update("\0");
+  hash.update(stableStringify(options));
+  hash.update("\0");
+  hash.update(version);
+  return hash.digest("hex");
+}
+async function readManifest(path2) {
+  let content;
+  try {
+    content = await readFile2(path2, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") return {};
+    throw err;
+  }
+  return JSON.parse(content);
+}
+async function writeManifest(path2, manifest) {
+  await ensureDir(dirname2(path2));
+  await writeFile2(path2, JSON.stringify(manifest, null, 2));
+}
+
+// src/pipeline/pipeline.ts
+function findCoreVersion() {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 10; i++) {
+    const candidate = path.join(dir, "package.json");
+    try {
+      const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
+      if (pkg.name === "@assetopt/core" && pkg.version) return pkg.version;
+    } catch {
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return "0.0.0-unknown";
+}
+var CORE_VERSION = findCoreVersion();
+var FORMAT_TO_EXT = {
+  jpeg: ".jpg",
+  png: ".png",
+  webp: ".webp",
+  avif: ".avif"
+};
+function resolveOutputPath(inputPath, inputDir, outputDir, newExt) {
+  const relative = path.relative(inputDir, inputPath);
+  const ext = path.extname(relative);
+  const renamed = newExt && newExt !== ext ? relative.slice(0, -ext.length) + newExt : relative;
+  return path.resolve(outputDir, renamed);
+}
+function configForHash(config) {
+  const { output: _output, ...rest } = config;
+  return rest;
+}
+async function runPipeline(inputDir, config = {}, options = {}) {
+  const { dryRun = false, useCache = true, onProgress } = options;
+  const outputDir = config.output?.dir ?? "./optimized";
+  const skip = new Set(config.images?.skip ?? []);
+  const manifestPath = path.resolve(outputDir, CACHE_FILE);
+  const hashableConfig = configForHash(config);
+  const manifest = useCache ? await readManifest(manifestPath) : {};
+  const allFiles = await scanDirectory(inputDir);
+  const files = allFiles.filter((filePath) => {
+    const sourceFormat = getImageSourceFormat(filePath);
+    return sourceFormat === null || !skip.has(sourceFormat);
+  });
+  const results = [];
+  for (let i = 0; i < files.length; i++) {
+    const filePath = files[i];
+    onProgress?.(i + 1, files.length, filePath);
+    const start = Date.now();
+    const buffer = await readBuffer(filePath);
+    const cacheKey = useCache ? computeCacheKey(buffer, hashableConfig, CORE_VERSION) : null;
+    if (cacheKey !== null) {
+      const entry = manifest[cacheKey];
+      const assetType = getAssetType(filePath);
+      if (entry && assetType !== null) {
+        const absoluteOutputPath = path.resolve(outputDir, entry.outputPath);
+        if (existsSync(absoluteOutputPath)) {
+          const savedBytes2 = entry.inputSize - entry.outputSize;
+          results.push({
+            inputPath: filePath,
+            outputPath: absoluteOutputPath,
+            inputSize: entry.inputSize,
+            outputSize: entry.outputSize,
+            savedBytes: savedBytes2,
+            savedPercent: computeSavedPercent(savedBytes2, entry.inputSize),
+            assetType,
+            durationMs: Date.now() - start,
+            cached: true
+          });
+          continue;
+        }
+      }
+    }
+    const dispatched = await dispatch(filePath, buffer, config);
+    const newExt = dispatched.assetType === "image" ? FORMAT_TO_EXT[dispatched.format] : void 0;
+    const outputPath = resolveOutputPath(filePath, inputDir, outputDir, newExt);
+    if (!dryRun) {
+      await writeBuffer(outputPath, dispatched.buffer);
+    }
+    if (cacheKey !== null && !dryRun) {
+      manifest[cacheKey] = {
+        inputSize: dispatched.originalSize,
+        outputSize: dispatched.outputSize,
+        outputPath: toPosixPath(path.relative(outputDir, outputPath)),
+        outputFormat: dispatched.assetType === "image" ? dispatched.format : void 0,
+        timestamp: Date.now()
+      };
+    }
+    const savedBytes = dispatched.originalSize - dispatched.outputSize;
+    results.push({
+      inputPath: filePath,
+      outputPath,
+      inputSize: dispatched.originalSize,
+      outputSize: dispatched.outputSize,
+      savedBytes,
+      savedPercent: computeSavedPercent(savedBytes, dispatched.originalSize),
+      assetType: dispatched.assetType,
+      durationMs: Date.now() - start,
+      cached: false
+    });
+  }
+  if (useCache && !dryRun) {
+    await writeManifest(manifestPath, manifest);
+  }
+  return results;
+}
+
+// src/analyzers/report.ts
+function buildReport(assets, durationMs) {
+  const totalInputSize = assets.reduce((sum, a) => sum + a.inputSize, 0);
+  const totalOutputSize = assets.reduce((sum, a) => sum + a.outputSize, 0);
+  const totalSavedBytes = totalInputSize - totalOutputSize;
+  const cachedCount = assets.reduce((n, a) => n + (a.cached ? 1 : 0), 0);
+  return {
+    assets,
+    totalInputSize,
+    totalOutputSize,
+    totalSavedBytes,
+    totalSavedPercent: computeSavedPercent(totalSavedBytes, totalInputSize),
+    durationMs,
+    cachedCount
+  };
+}
+
+// src/config/loader.ts
+import { readFile as readFile3 } from "fs/promises";
+import { dirname as dirname3, resolve as resolve2 } from "path";
+
+// src/config/schema.ts
+import { z } from "zod";
+var imageQualitySchema = z.object({
+  jpeg: z.number().min(1).max(100).optional(),
+  png: z.number().min(1).max(100).optional(),
+  webp: z.number().min(1).max(100).optional(),
+  avif: z.number().min(1).max(100).optional()
+});
+var matrixTargetSchema = z.enum(IMAGE_MATRIX_TARGETS);
+var formatMatrixSchema = z.object({
+  jpeg: matrixTargetSchema.optional(),
+  png: matrixTargetSchema.optional(),
+  webp: matrixTargetSchema.optional(),
+  avif: matrixTargetSchema.optional()
+}).strict();
+var imageOptionsSchema = z.object({
+  outputFormat: z.enum(IMAGE_OUTPUT_FORMATS).optional(),
+  formatMatrix: formatMatrixSchema.optional(),
+  quality: imageQualitySchema.optional(),
+  stripMetadata: z.boolean().optional(),
+  skip: z.array(z.enum(IMAGE_SOURCE_FORMATS)).optional()
+});
+var cssOptionsSchema = z.object({
+  minify: z.boolean().optional()
+});
+var jsOptionsSchema = z.object({
+  minify: z.boolean().optional()
+});
+var svgOptionsSchema = z.object({
+  multipass: z.boolean().optional(),
+  minifyIds: z.boolean().optional()
+});
+var configSchema = z.object({
+  preset: z.enum(PRESET_NAMES).optional(),
+  images: imageOptionsSchema.optional(),
+  css: cssOptionsSchema.optional(),
+  js: jsOptionsSchema.optional(),
+  svg: svgOptionsSchema.optional(),
+  output: z.object({
+    dir: z.string().optional()
+  }).optional()
+});
+
+// src/config/presets.ts
+var PRESETS = {
+  // PNG smart routing: AVIF preserves transparency at smaller size than PNG,
+  // but for opaque images WebP is lighter than AVIF. So we route based on
+  // the actual presence of an alpha channel rather than the PNG container.
+  "web-perf": {
+    images: {
+      formatMatrix: {
+        jpeg: "webp",
+        png: (ctx) => ctx.hasAlpha ? "avif" : "webp",
+        webp: "keep",
+        avif: "keep"
+      }
+    }
+  },
+  // Smallest possible output: everything converges to AVIF (the densest format
+  // we support) at aggressive quality, and SVGs get the full svgo treatment.
+  // Quality is keyed by the OUTPUT format, so only `avif` matters here.
+  "max-compression": {
+    images: {
+      formatMatrix: {
+        jpeg: "avif",
+        png: "avif",
+        webp: "avif",
+        avif: "keep"
+      },
+      quality: { avif: 50 },
+      stripMetadata: true
+    },
+    svg: { multipass: true, minifyIds: true }
+  },
+  // Fidelity-first: keep every source format (no lossy format switch) and
+  // re-encode at high quality. Metadata is preserved (e.g. color profiles,
+  // EXIF) — useful for photography or print workflows. Not bit-for-bit
+  // lossless: JPEG/WebP/AVIF stay lossy codecs, just at a high quality floor.
+  quality: {
+    images: {
+      formatMatrix: {
+        jpeg: "keep",
+        png: "keep",
+        webp: "keep",
+        avif: "keep"
+      },
+      quality: { jpeg: 95, png: 95, webp: 95, avif: 90 },
+      stripMetadata: false
+    }
+  },
+  // Maximum target compatibility: never produce a format more modern than the
+  // source. Every format is kept as-is (only re-compressed at defaults), so the
+  // output is guaranteed to be as widely supported as the input.
+  compatibility: {
+    images: {
+      formatMatrix: {
+        jpeg: "keep",
+        png: "keep",
+        webp: "keep",
+        avif: "keep"
+      }
+    }
+  }
+};
+
+// src/config/loader.ts
+var CONFIG_FILENAMES = [".assetoptrc", ".assetoptrc.json"];
+var DEFAULTS = {
+  images: IMAGE_DEFAULTS,
+  css: CSS_DEFAULTS,
+  js: JS_DEFAULTS,
+  svg: SVG_DEFAULTS,
+  output: { dir: "./optimized" }
+};
+async function findConfigFile(startDir) {
+  let dir = startDir;
+  while (true) {
+    for (const filename of CONFIG_FILENAMES) {
+      const candidate = resolve2(dir, filename);
+      try {
+        await readFile3(candidate, "utf-8");
+        return candidate;
+      } catch (err) {
+        if (err.code !== "ENOENT") throw err;
+      }
+    }
+    const parent = dirname3(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+async function loadConfig(cwd = process.cwd()) {
+  const filePath = await findConfigFile(cwd);
+  if (filePath === null) return { config: DEFAULTS, source: null };
+  const raw = await readFile3(filePath, "utf-8");
+  try {
+    const parsed = configSchema.parse(JSON.parse(raw));
+    return { config: resolveConfig(parsed), source: filePath };
+  } catch (err) {
+    throw new Error(`Invalid ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+function resolveConfig(userConfig) {
+  const presetConfig = userConfig.preset ? PRESETS[userConfig.preset] : {};
+  return mergeConfig(mergeConfig(DEFAULTS, presetConfig), userConfig);
+}
+function mergeConfig(base, override) {
+  const baseMatrix = base.images?.formatMatrix;
+  const overrideMatrix = override.images?.formatMatrix;
+  const mergedMatrix = baseMatrix || overrideMatrix ? { ...baseMatrix, ...overrideMatrix } : void 0;
+  return {
+    ...base,
+    ...override,
+    images: {
+      ...base.images,
+      ...override.images,
+      quality: { ...base.images?.quality, ...override.images?.quality },
+      ...mergedMatrix && { formatMatrix: mergedMatrix }
+    },
+    css: { ...base.css, ...override.css },
+    js: { ...base.js, ...override.js },
+    svg: { ...base.svg, ...override.svg },
+    output: { ...base.output, ...override.output }
+  };
+}
+export {
+  CACHE_FILE,
+  DEFAULTS,
+  PRESETS,
+  buildReport,
+  dispatch,
+  getAssetType,
+  getFileSize,
+  loadConfig,
+  mergeConfig,
+  optimizeCss,
+  optimizeImage,
+  optimizeJs,
+  optimizeSvg,
+  resolveConfig,
+  runPipeline,
+  scanDirectory
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@assetopt/core",
+  "version": "1.0.0",
+  "description": "Pure asset optimization functions for images (sharp), CSS (lightningcss), JS (esbuild), and SVG (svgo). Core engine behind the assetopt CLI.",
+  "license": "MIT",
+  "author": "Nath",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "asset-optimization",
+    "image-optimization",
+    "css-minification",
+    "js-minification",
+    "svg-optimization",
+    "sharp",
+    "lightningcss",
+    "esbuild",
+    "svgo",
+    "web-performance"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nathmaxx/assetopt.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/Nathmaxx/assetopt/issues"
+  },
+  "homepage": "https://github.com/Nathmaxx/assetopt#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.1",
+    "lightningcss": "^1.28.0",
+    "sharp": "^0.33.0",
+    "svgo": "^3.3.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0"
+  }
+}