poops-images 1.0.0 → 1.1.0

package/README.md

@@ -16,6 +16,7 @@ Features:
 - Smart format selection — compares JPEG vs WebP, keeps whichever is smaller
 - Transparency detection — auto-converts opaque PNGs and GIFs to JPEG
 - Never upscales — skips sizes larger than the source
+- Preprocessors — apply transformations (blur, grayscale, custom handlers, etc.) before generating variants, great for LQIP placeholders, hover effects, and artistic filters like halftone
 - Watch mode with incremental processing
 - Configurable concurrency for parallel processing
 - Keeps track with cache
@@ -76,6 +77,7 @@ Usage: poops-images [input] [options]
   -w, --watch            Watch for changes and process incrementally
   -f, --force            Ignore cache, regenerate everything
       --dry-run          Show what would be processed without writing
+  -P, --preprocess <ops> Preprocess operations (e.g. blur:20,grayscale,sharpen:1.5)
   -q, --quiet            Suppress progress output
   -v, --version          Show version
   -h, --help             Show help
@@ -146,7 +148,15 @@ The config file is resolved in order:
   "exclude": [],
   "concurrency": 4,
   "skipOriginal": false,
-  "cache": true
+  "cache": true,
+  "preprocessors": [
+    {
+      "name": "lqip",
+      "operations": [{ "type": "blur", "sigma": 30 }],
+      "sizes": [{ "width": 32 }],
+      "skipOriginal": true
+    }
+  ]
 }
 ```
 
@@ -163,6 +173,7 @@ The config file is resolved in order:
 | `include`      | `string`               | `"**/*.{jpg,jpeg,png,tiff,tif,webp,heic,heif}"` | Glob pattern for source images                                                                                                                        |
 | `exclude`      | `array`                | `[]`                                            | Glob patterns to exclude                                                                                                                              |
 | `concurrency`  | `number`               | `4`                                             | Max parallel image operations                                                                                                                         |
+| `preprocessors`| `array`                | `[]`                                            | Preprocessor definitions (see [Preprocessors](#preprocessors) below)                                                                                  |
 | `cache`        | `true\|false\|string`  | `true`                                          | Cache behavior. `true` = default cache file in output dir, `false` = no cache, `"path"` = custom cache file path (relative to output dir or absolute) |
 
 ### Size definitions
@@ -234,6 +245,14 @@ const processor2 = new ImageProcessor({
   ],
   format: "webp",
   quality: { jpg: 85, webp: 80 },
+  preprocessors: [
+    {
+      name: "lqip",
+      operations: [{ type: "blur", sigma: 30 }],
+      sizes: [{ width: 32 }],
+      skipOriginal: true,
+    },
+  ],
 });
 
 const stats = await processor2.processAll();
@@ -427,12 +446,248 @@ src/images/icons/logo.svg
   → dist/static/images/icons/logo.svg  (minified)
 ```
 
+SVGs can also be processed by preprocessors that have `"svg": true` set. The SVG is rasterized at its native dimensions, run through the preprocessor operations, and saved as a raster image (PNG) at original size only. See [Preprocessors](#preprocessors) for details.
+
 ### GIF handling
 
 **Static GIFs** (single-frame) are treated like any other raster image — resized, cropped, and format-converted. Opaque static GIFs become JPEG, transparent ones become PNG (or whatever `format` is set to).
 
 **Animated GIFs** (multi-frame) are copied to the output directory unchanged. No resizing or format conversion — animated GIFs would lose their frames through sharp's raster pipeline.
 
+### Preprocessors
+
+Preprocessors apply sharp transformations to the source image **before** the resize/format pipeline runs. Each preprocessor generates its own set of variants alongside the untouched original's variants. This is useful for generating blurred placeholder images (LQIP), grayscale variants for hover effects, watermarked versions for public galleries, etc.
+
+#### CLI usage
+
+The `--preprocess` / `-P` flag is a quick way to add a single preprocessor:
+
+```bash
+# Blur all images
+npx poops-images --in src/images --out dist --preprocess blur:20
+
+# Grayscale
+npx poops-images --in src/images --out dist --preprocess grayscale
+
+# Chain operations
+npx poops-images --in src/images --out dist --preprocess grayscale,blur:10
+```
+
+When used via CLI, the preprocessor is named `"preprocessed"` and produces files like `photo-preprocessed-medium-300w.jpg`.
+
+#### Config usage
+
+For full control, define preprocessors in the config file. Each preprocessor has a `name` (used in filenames) and an `operations` array:
+
+```json
+{
+  "in": "src/images",
+  "out": "dist/images",
+  "sizes": [
+    { "name": "small", "width": 480 },
+    { "name": "medium", "width": 1024 }
+  ],
+  "preprocessors": [
+    {
+      "name": "blurred",
+      "operations": [{ "type": "blur", "sigma": 15 }]
+    },
+    {
+      "name": "lqip",
+      "operations": [{ "type": "blur", "sigma": 30 }],
+      "sizes": [{ "width": 32 }],
+      "skipOriginal": true
+    },
+    {
+      "name": "gray",
+      "operations": [{ "type": "grayscale" }],
+      "sizes": [{ "name": "thumb", "width": 200, "height": 200, "crop": true }],
+      "skipOriginal": true
+    }
+  ]
+}
+```
+
+This produces for `photo.jpg` (assuming it's large enough):
+
+```
+photo.jpg                          # original passthrough
+photo-small-480w.jpg               # original sized
+photo-medium-1024w.jpg             # original sized
+photo-blurred.jpg                  # blurred passthrough
+photo-blurred-small-480w.jpg       # blurred sized
+photo-blurred-medium-1024w.jpg     # blurred sized
+photo-lqip-32w.jpg                 # tiny blurred placeholder only
+photo-gray-thumb-200w.jpg          # grayscale thumbnail only
+```
+
+#### Preprocessor definition
+
+| Field          | Type      | Default   | Description                                                            |
+| -------------- | --------- | --------- | ---------------------------------------------------------------------- |
+| `name`         | `string`  | required  | Identifier used in output filenames. Must be unique, alphanumeric/dash/underscore only |
+| `operations`   | `array`   | required  | Ordered list of operations to apply (see table below)                  |
+| `sizes`        | `array`   | _(global)_ | Override the global `sizes` for this preprocessor                      |
+| `format`       | same as global | _(global)_ | Override the global `format` for this preprocessor                |
+| `quality`      | same as global | _(global)_ | Override the global `quality` for this preprocessor               |
+| `skipOriginal` | `boolean` | _(global)_ | Override the global `skipOriginal` for this preprocessor               |
+| `svg`          | `boolean` | `false`    | Also process SVG source files through this preprocessor (rasterize → preprocess → save at original size) |
+| `resizeFirst`  | `boolean` or `object` | `false` | Resize before preprocessing instead of after (see below) |
+
+Operations are composable — they chain in sequence on the sharp pipeline. For example, `[{ "type": "grayscale" }, { "type": "blur", "sigma": 5 }]` first desaturates, then blurs.
+
+#### resizeFirst — order of resize and operations
+
+By default, operations run once on the full-size source, and size variants are generated from that result. That's the right order for most filters (blur, tint, grayscale look the same either way), but effects with a fixed pixel scale — pixelate blocks, halftone dots, ASCII cells — come out at a different visual density on every variant. `resizeFirst` flips the order:
+
+| Value             | Behavior                                                                    |
+| ----------------- | --------------------------------------------------------------------------- |
+| `false` (default) | Preprocess the full-size source once, then resize into variants             |
+| `true`            | Resize each variant first, then preprocess it — pixel-scale effects look identical across variants |
+| `{ width, height, crop }` | Resize the source to this base size once, preprocess once, then generate variants from the base — one preprocessing pass, and variants never exceed the base dimensions |
+
+```json
+{
+  "preprocessors": [
+    {
+      "name": "pixel",
+      "operations": [{ "type": "pixelate", "blockSize": 8 }],
+      "resizeFirst": true
+    },
+    {
+      "name": "lqip",
+      "operations": [{ "type": "blur", "sigma": 10 }],
+      "resizeFirst": { "width": 64 },
+      "sizes": [{ "width": 32 }],
+      "skipOriginal": true
+    }
+  ]
+}
+```
+
+With `"resizeFirst": true`, the 8-pixel blocks are 8 output pixels in every variant. Without it, blocks are 8 pixels of the source, so a 4000px source downscaled to 480px shows ~1px blocks.
+
+The object form accepts the same shape as a size definition (`width` and/or `height`, optional `crop`) and never upscales — a base larger than the source is clamped to the source, keeping the crop aspect ratio. It's also a performance lever: expensive operations run once on a small base instead of once per variant or once at full size.
+
+Sidecar-emitting handlers (like `halftone`'s SVG) write their sidecar once per preprocessor: from the full-size pass by default, from the first variant with `resizeFirst: true`, or from the base with the object form.
+
+#### Available operations
+
+All operations map directly to [sharp](https://sharp.pixelplumbing.com/) methods:
+
+| Operation   | Parameters                                              | Description                                      |
+| ----------- | ------------------------------------------------------- | ------------------------------------------------ |
+| `blur`      | `sigma` (number, 0.3–1000)                              | Gaussian blur                                    |
+| `grayscale` | _(none)_                                                | Convert to grayscale                             |
+| `sharpen`   | `sigma` (number, optional)                              | Sharpen                                          |
+| `tint`      | `color` (string, e.g. `"#ff0000"`)                      | Tint with a color                                |
+| `modulate`  | `brightness`, `saturation`, `hue`, `lightness` (numbers) | Adjust brightness/saturation/hue                 |
+| `negate`    | _(none)_                                                | Invert colors                                    |
+| `normalize` | _(none)_                                                | Stretch contrast to full range                   |
+| `rotate`    | `angle` (number, degrees)                               | Rotate by exact angle                            |
+| `flip`      | _(none)_                                                | Flip vertically                                  |
+| `flop`      | _(none)_                                                | Flip horizontally                                |
+| `gamma`     | `value` (number)                                        | Apply gamma correction                           |
+| `composite` | `input` (path), `gravity`, `blend`, `top`, `left`       | Overlay an image (e.g. watermark)                |
+| _(path)_    | any extra params                                         | Run a custom JS handler — use a file path as the `type` (see below) |
+
+The `composite` operation resolves the `input` path relative to the config file directory (or CWD). Example watermark config:
+
+```json
+{
+  "name": "watermarked",
+  "operations": [
+    { "type": "composite", "input": "assets/watermark.png", "gravity": "southeast" }
+  ]
+}
+```
+
+#### Custom handlers
+
+If the `type` is not a built-in operation, it's treated as a custom handler. Resolution order:
+
+1. **Short name** — `"type": "halftone"` resolves to `handlers/halftone.js` relative to the config file directory (or CWD)
+2. **File path** — `"type": "./effects/halftone.js"` resolves the path directly relative to the config file directory (or CWD)
+
+A custom handler is a JS module that exports a function:
+
+```javascript
+/**
+ * @param {Buffer} buffer - Current image as a raw buffer
+ * @param {object} params - All extra properties from the operation config, plus { width, height }
+ * @param {Function} sharp - The sharp module, for convenience
+ * @returns {Promise<Buffer|{buffer: Buffer, sidecars: Array}>} - Transformed image buffer, or object with sidecars
+ */
+export default async function (buffer, params, sharp) {
+  // Transform the image using any library
+  return sharp(buffer).negate().png().toBuffer()
+}
+```
+
+The handler receives:
+- `buffer` — the current image as a Buffer (already EXIF-rotated, and with any prior operations applied)
+- `params` — all extra properties from the operation config object (everything except `type`), plus `width` and `height` of the current image
+- `sharp` — the sharp module, so you don't need to import it separately
+
+The handler can return:
+- A `Buffer` — the transformed image
+- An object `{ buffer, sidecars }` — the transformed image plus extra files to save alongside it. Each sidecar is `{ ext, data }` where `ext` is the file extension (e.g. `"svg"`) and `data` is a `Buffer`. Sidecars are saved as `{name}-{ppName}.{ext}` in the output directory.
+
+**Config example (short name):**
+
+```json
+{
+  "name": "halftone",
+  "operations": [
+    {
+      "type": "halftone",
+      "dotSize": "0.8%",
+      "spacing": "1%",
+      "shape": "square",
+      "foreground": "#43523d",
+      "background": "#c7f0d8"
+    }
+  ],
+  "sizes": [{ "name": "medium", "width": 1024 }],
+  "svg": true
+}
+```
+
+This looks for `handlers/halftone.js` in the config directory. The handler receives `{ dotSize: "0.8%", spacing: "1%", shape: "square", foreground: "#43523d", background: "#c7f0d8", width: ..., height: ... }` as `params`. The `svg: true` flag makes this preprocessor also process SVG source files (rasterized at their native dimensions).
+
+**Chaining:** Custom handlers can be mixed with built-in operations in any order. When a handler operation is encountered, the pipeline flushes the current buffer, calls your handler, and creates a new sharp instance from the result:
+
+```json
+{
+  "name": "styled",
+  "operations": [
+    { "type": "grayscale" },
+    { "type": "halftone", "dotSize": 4 },
+    { "type": "blur", "sigma": 1 }
+  ]
+}
+```
+
+**Bundled example handlers** (in the `handlers/` directory):
+
+- `halftone` — converts images to a halftone dot pattern. Supports circular dots (classic newspaper print) and square dots (Nokia LCD look). Emits an SVG sidecar alongside the raster output. Params: `dotSize`, `spacing`, `shape` (`"circle"` or `"square"`), `background`, `foreground`. Both `dotSize` and `spacing` accept absolute pixels (e.g. `8`) or percentages relative to the shortest side (e.g. `"1%"`)
+- `pixelate` — chunky pixel art / retro Nokia look via nearest-neighbor downscale/upscale. Params: `blockSize`, `colors` (palette limit), `grayscale`
+
+#### Output naming
+
+The preprocessor name is inserted between the source name and the size name:
+
+```
+Original:      {name}-{sizeName}-{width}w.{ext}      → photo-medium-1024w.jpg
+Preprocessed:  {name}-{ppName}-{sizeName}-{width}w.{ext}  → photo-blurred-medium-1024w.jpg
+```
+
+#### Edge cases
+
+- **SVGs** — preprocessors with `"svg": true` also process SVG source files. The SVG is rasterized via sharp, run through the preprocessor operations, and saved at its native dimensions only (no resize variants). The minified SVG is still saved separately. Preprocessors without `"svg": true` skip SVG files
+- **Animated GIFs** — preprocessors do not apply (copied as-is). Static GIFs go through preprocessors normally
+- **Cache invalidation** — adding, removing, or changing any preprocessor invalidates all cache entries
+
 ### Caching
 
 A cache file (`.poops-images-cache.json`) is stored in the output directory. It tracks per image: source mtime, size, original dimensions, EXIF metadata, and generated outputs with their dimensions.
@@ -469,7 +724,7 @@ A cache file (`.poops-images-cache.json`) is stored in the output directory. It
 **Skip logic:**
 
 1. `--force` — always reprocess
-2. Config hash changed (sizes/format/quality/skipOriginal differ) — reprocess everything
+2. Config hash changed (sizes/format/quality/skipOriginal/preprocessors differ) — reprocess everything
 3. Per file: skip if source mtime + size unchanged AND all expected outputs exist on disk
 4. On source deletion (watch mode): remove all generated variants
 
@@ -575,6 +830,7 @@ If you deploy GitHub Pages, do not run `poops-images` in the GitHub Actions to w
 | Config file            | JSON, poops.json fallback                | CLI flags only                                      | JS API only                                                                              | JSON                                                                               | JS API (Eleventy-coupled)                                      |
 | CLI                    | Standalone                               | Standalone                                          | No (API only)                                                                            | No (API only)                                                                      | No (Eleventy plugin)                                           |
 | Concurrency control    | Configurable worker count                | No                                                  | No                                                                                       | Multi-threaded                                                                     | Yes                                                            |
+| Preprocessors          | Blur, grayscale, watermark, etc. per-image | No                                                | No                                                                                       | No                                                                                 | No                                                             |
 | SSG coupling           | Designed for poops, usable standalone    | None                                                | None                                                                                     | None                                                                               | Tightly coupled to Eleventy                                    |
 | Maintained             | Active                                   | Last publish 2022                                   | Last publish 2019                                                                        | Last publish 2018                                                                  | Active                                                         |
 
@@ -585,6 +841,7 @@ If you deploy GitHub Pages, do not run `poops-images` in the GitHub Actions to w
 - **WordPress-style crop API** — full 9-position anchor grid (`["left", "top"]`), not just center crop.
 - **Integrated SVG pipeline** — SVGO minification in the same tool. Others require a separate build step.
 - **Convention-based naming** — `{name}-{sizeName}-{width}w.{ext}` is purpose-built for poops' `discoverImageVariants()` srcset generation.
+- **Preprocessors** — generate LQIP placeholders, grayscale hover variants, or watermarked copies alongside originals, all from config. No other tool has a built-in preprocessor pipeline.
 - **Standalone CLI + API** — works with any build system or none at all, unlike Eleventy-coupled or webpack-coupled alternatives.
 
 ## License

package/lib/analyze.js

@@ -5,6 +5,15 @@ import { hasTransparency } from './formats.js'
 import { dmsToDecimal, formatDms } from './utils/format.js'
 import log from './utils/log.js'
 
+export function buildEffectiveSizes(sizes, skipOriginal) {
+  if (skipOriginal) return sizes
+
+  const hasPassthrough = sizes.some(s => s.width === 0 && s.height === 0)
+  if (hasPassthrough) return sizes
+
+  return [{ name: '', width: 0, height: 0, crop: false }, ...sizes]
+}
+
 function formatExposure(value) {
   if (value >= 1) return `${value}s`
   return `1/${Math.round(1 / value)}`
@@ -114,9 +123,11 @@ export async function analyzeImage(inputPath, config, stat) {
   // Formats that support alpha and need transparency detection
   const alphaFormats = new Set(['png', 'tiff', 'heic', 'heif', 'gif'])
 
-  // Check transparency for alpha-capable formats (needed for default + smart modes)
-  const formatIncludesSmart = config.format === 'smart' ||
-    (Array.isArray(config.format) && config.format.includes('smart'))
+  // Check transparency for alpha-capable formats (needed for default + smart modes) —
+  // smart may come from the global format or any preprocessor's format override
+  const includesSmart = (f) => f === 'smart' || (Array.isArray(f) && f.includes('smart'))
+  const formatIncludesSmart = includesSmart(config.format) ||
+    (config.preprocessors || []).some(pp => includesSmart(pp.format))
 
   const needsTransparencyCheck =
     alphaFormats.has(normalizedExt) &&
@@ -147,13 +158,7 @@ export async function analyzeImage(inputPath, config, stat) {
   }
 
   // Build effective sizes list — include original unless skipOriginal
-  let effectiveSizes = config.sizes
-  if (!config.skipOriginal) {
-    const hasPassthrough = effectiveSizes.some(s => s.width === 0 && s.height === 0)
-    if (!hasPassthrough) {
-      effectiveSizes = [{ name: '', width: 0, height: 0, crop: false }, ...effectiveSizes]
-    }
-  }
+  const effectiveSizes = buildEffectiveSizes(config.sizes, config.skipOriginal)
 
   // EXIF orientations 5-8 swap width/height
   const swapped = metadata.orientation >= 5

package/lib/config.js

@@ -2,6 +2,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import crypto from 'node:crypto'
 import { validateSize } from './sizes.js'
+import { validatePreprocessors } from './preprocess.js'
 
 // Output formats only — tiff/tif/heic/heif/gif are input formats normalized to jpg/png during processing
 const SUPPORTED_FORMATS = new Set(['jpg', 'jpeg', 'png', 'webp', 'avif'])
@@ -21,7 +22,8 @@ const DEFAULTS = {
   concurrency: 4,
   format: false,
   skipOriginal: false,
-  cache: true
+  cache: true,
+  preprocessors: []
 }
 
 export function loadConfig(configPath) {
@@ -68,6 +70,11 @@ export function loadConfig(configPath) {
     }
   }
 
+  // Custom handlers and composite overlays resolve relative to the config file
+  if (raw.configDir === undefined) {
+    raw.configDir = path.dirname(resolvedPath)
+  }
+
   return validateConfig(raw)
 }
 
@@ -124,10 +131,22 @@ export function validateConfig(raw) {
 
   config.skipOriginal = !!config.skipOriginal
 
+  config.configDir = typeof config.configDir === 'string'
+    ? path.resolve(config.configDir)
+    : process.cwd()
+
   if (config.cache !== false && config.cache !== true && typeof config.cache !== 'string') {
     throw new Error('Config "cache" must be false, true, or a string path')
   }
 
+  // Validate preprocessors
+  if (config.preprocessors && config.preprocessors.length > 0) {
+    const sizeNames = new Set(config.sizes.map(s => s.name).filter(Boolean))
+    config.preprocessors = validatePreprocessors(config.preprocessors, sizeNames)
+  } else {
+    config.preprocessors = []
+  }
+
   if (config.format !== false) {
     const fmts = Array.isArray(config.format)
       ? config.format
@@ -153,7 +172,8 @@ export function configHash(config) {
     sizes: config.sizes,
     format: config.format,
     quality: config.quality,
-    skipOriginal: config.skipOriginal
+    skipOriginal: config.skipOriginal,
+    preprocessors: config.preprocessors
   }
   return crypto.createHash('md5').update(JSON.stringify(hashable)).digest('hex')
 }

package/lib/discover.js

@@ -1,26 +1,30 @@
 import { glob } from 'glob'
 import path from 'node:path'
 
+// glob treats \ in patterns as an escape character, so patterns must use
+// forward slashes even on Windows
+const globJoin = (...parts) => path.join(...parts).split(path.sep).join('/')
+
 export async function discoverSources(config) {
-  const pattern = path.join(config.in, config.include)
+  const pattern = globJoin(config.in, config.include)
   const ignore = [
-    ...config.exclude.map(e => path.join(config.in, e)),
+    ...config.exclude.map(e => globJoin(config.in, e)),
     // SVG and GIF have dedicated pipelines — exclude from raster discovery
-    path.join(config.in, '**/*.svg'),
-    path.join(config.in, '**/*.gif')
+    globJoin(config.in, '**/*.svg'),
+    globJoin(config.in, '**/*.gif')
   ]
   return glob(pattern, { ignore, nodir: true })
 }
 
 export async function discoverSvgs(config) {
-  const pattern = path.join(config.in, '**/*.svg')
-  const ignore = config.exclude.map(e => path.join(config.in, e))
+  const pattern = globJoin(config.in, '**/*.svg')
+  const ignore = config.exclude.map(e => globJoin(config.in, e))
   return glob(pattern, { ignore, nodir: true })
 }
 
 export async function discoverGifs(config) {
-  const pattern = path.join(config.in, '**/*.gif')
-  const ignore = config.exclude.map(e => path.join(config.in, e))
+  const pattern = globJoin(config.in, '**/*.gif')
+  const ignore = config.exclude.map(e => globJoin(config.in, e))
   return glob(pattern, { ignore, nodir: true })
 }
 

package/lib/formats.js

@@ -1,5 +1,3 @@
-import sharp from 'sharp'
-
 const FORMAT_MAP = {
   jpg: 'jpeg',
   jpeg: 'jpeg',
@@ -63,7 +61,7 @@ export async function convertFormat(sharpInstance, targetFormat, qualityConfig)
   return buffer
 }
 
-export async function resolveTargetFormats(outputExt, transparent, rawData, formatConfig, qualityConfig) {
+export async function resolveTargetFormats(outputExt, transparent, toSharp, formatConfig, qualityConfig) {
   const preEncoded = new Map()
 
   // Default: just the normalized base format
@@ -82,10 +80,10 @@ export async function resolveTargetFormats(outputExt, transparent, rawData, form
     } else {
       // Compare jpg vs webp, pick smaller — keep the winner buffer to avoid re-encoding
       const [jpgBuf, webpBuf] = await Promise.all([
-        sharp(rawData)
+        toSharp()
           .toFormat('jpeg', { quality: getQuality('jpg', qualityConfig) })
           .toBuffer(),
-        sharp(rawData)
+        toSharp()
           .toFormat('webp', { quality: getQuality('webp', qualityConfig) })
           .toBuffer()
       ])

package/lib/preprocess.js

@@ -0,0 +1,242 @@
+import path from 'node:path'
+import fs from 'node:fs'
+import { pathToFileURL } from 'node:url'
+import sharp from 'sharp'
+import { validateSize } from './sizes.js'
+
+const OPERATION_REGISTRY = {
+  blur: (pipeline, params) => {
+    if (params.sigma == null) throw new Error('blur requires "sigma" parameter')
+    if (typeof params.sigma !== 'number' || params.sigma < 0.3 || params.sigma > 1000) {
+      throw new Error('blur "sigma" must be a number between 0.3 and 1000')
+    }
+    return pipeline.blur(params.sigma)
+  },
+
+  grayscale: (pipeline) => pipeline.grayscale(),
+
+  sharpen: (pipeline, params) => {
+    const opts = {}
+    if (params.sigma != null) opts.sigma = params.sigma
+    return pipeline.sharpen(opts)
+  },
+
+  tint: (pipeline, params) => {
+    if (!params.color) throw new Error('tint requires "color" parameter')
+    return pipeline.tint(params.color)
+  },
+
+  modulate: (pipeline, params) => {
+    const opts = {}
+    if (params.brightness != null) opts.brightness = params.brightness
+    if (params.saturation != null) opts.saturation = params.saturation
+    if (params.hue != null) opts.hue = params.hue
+    if (params.lightness != null) opts.lightness = params.lightness
+    return pipeline.modulate(opts)
+  },
+
+  negate: (pipeline) => pipeline.negate(),
+
+  normalize: (pipeline) => pipeline.normalize(),
+
+  rotate: (pipeline, params) => {
+    if (params.angle == null) throw new Error('rotate requires "angle" parameter')
+    return pipeline.rotate(params.angle)
+  },
+
+  flip: (pipeline) => pipeline.flip(),
+
+  flop: (pipeline) => pipeline.flop(),
+
+  gamma: (pipeline, params) => {
+    if (params.value == null) throw new Error('gamma requires "value" parameter')
+    return pipeline.gamma(params.value)
+  },
+
+  composite: (pipeline, params, configDir) => {
+    if (!params.input) throw new Error('composite requires "input" parameter')
+
+    const overlayPath = path.resolve(configDir || process.cwd(), params.input)
+    if (!fs.existsSync(overlayPath)) {
+      throw new Error(`composite overlay not found: ${overlayPath}`)
+    }
+
+    const compositeOpts = { input: overlayPath }
+    if (params.gravity) compositeOpts.gravity = params.gravity
+    if (params.blend) compositeOpts.blend = params.blend
+    if (params.top != null) compositeOpts.top = params.top
+    if (params.left != null) compositeOpts.left = params.left
+
+    return pipeline.composite([compositeOpts])
+  }
+}
+
+export const VALID_OPERATIONS = Object.keys(OPERATION_REGISTRY)
+
+// Cache for loaded custom handler modules, keyed by path + mtime so an edited
+// handler is re-imported on the next run (watch mode) without a restart
+const handlerCache = new Map()
+
+function resolveHandlerPath(name, configDir) {
+  const base = configDir || process.cwd()
+
+  // If name looks like a path (contains / or .), resolve directly
+  if (name.includes('/') || name.includes('.')) {
+    return path.resolve(base, name)
+  }
+
+  // Otherwise, look for handlers/{name}.js in the config directory
+  return path.resolve(base, 'handlers', `${name}.js`)
+}
+
+async function loadHandler(name, configDir) {
+  const resolved = resolveHandlerPath(name, configDir)
+
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`Custom handler not found: ${resolved}`)
+  }
+
+  // import() caches by URL for the process lifetime, so key both the local
+  // cache and the import URL by mtime — an edited handler loads fresh
+  const mtime = fs.statSync(resolved).mtimeMs
+  const key = `${resolved}:${mtime}`
+  if (handlerCache.has(key)) return handlerCache.get(key)
+
+  const mod = await import(`${pathToFileURL(resolved).href}?v=${mtime}`)
+  const fn = mod.default || mod
+
+  if (typeof fn !== 'function') {
+    throw new Error(`Custom handler must export a function: ${resolved}`)
+  }
+
+  handlerCache.set(key, fn)
+  return fn
+}
+
+function validateResizeFirst(value, name) {
+  if (value == null || value === false) return false
+  if (value === true) return true
+
+  if (typeof value === 'object' && !Array.isArray(value)) {
+    // 0 counts as unset — validation must be idempotent, since the config is
+    // validated twice (loadConfig and the processor constructor) and the first
+    // pass normalizes a missing dimension to 0
+    const okDim = (v) => v === undefined || (typeof v === 'number' && Number.isFinite(v) && v >= 0)
+    const width = value.width || 0
+    const height = value.height || 0
+    if (!okDim(value.width) || !okDim(value.height) || (width === 0 && height === 0)) {
+      throw new Error(`Preprocessor "${name}": "resizeFirst" object requires a positive numeric "width" and/or "height"`)
+    }
+    // Reuse size validation for crop rules
+    const validated = validateSize({ width: value.width || 0, height: value.height || 0, crop: value.crop })
+    return { width: validated.width, height: validated.height, crop: validated.crop }
+  }
+
+  throw new Error(`Preprocessor "${name}": "resizeFirst" must be true or an object like { width, height, crop }`)
+}
+
+export function validatePreprocessor(preprocessor) {
+  if (!preprocessor || typeof preprocessor !== 'object') {
+    throw new Error('Preprocessor must be an object')
+  }
+
+  if (!preprocessor.name || typeof preprocessor.name !== 'string') {
+    throw new Error('Preprocessor "name" is required and must be a non-empty string')
+  }
+
+  if (!/^[a-zA-Z0-9_-]+$/.test(preprocessor.name)) {
+    throw new Error(`Preprocessor name "${preprocessor.name}" must contain only letters, numbers, hyphens, and underscores`)
+  }
+
+  if (!Array.isArray(preprocessor.operations) || preprocessor.operations.length === 0) {
+    throw new Error(`Preprocessor "${preprocessor.name}": "operations" must be a non-empty array`)
+  }
+
+  for (const op of preprocessor.operations) {
+    if (!op.type || typeof op.type !== 'string') {
+      throw new Error(`Preprocessor "${preprocessor.name}": each operation must have a "type" string`)
+    }
+  }
+
+  return {
+    name: preprocessor.name,
+    operations: preprocessor.operations,
+    sizes: preprocessor.sizes || null,
+    format: preprocessor.format !== undefined ? preprocessor.format : null,
+    quality: preprocessor.quality !== undefined ? preprocessor.quality : null,
+    skipOriginal: preprocessor.skipOriginal !== undefined ? preprocessor.skipOriginal : null,
+    svg: !!preprocessor.svg,
+    resizeFirst: validateResizeFirst(preprocessor.resizeFirst, preprocessor.name)
+  }
+}
+
+export function validatePreprocessors(preprocessors, sizeNames) {
+  if (!Array.isArray(preprocessors)) {
+    throw new Error('Config "preprocessors" must be an array')
+  }
+
+  const names = new Set()
+  const validated = []
+
+  for (const pp of preprocessors) {
+    const result = validatePreprocessor(pp)
+
+    if (names.has(result.name)) {
+      throw new Error(`Duplicate preprocessor name: "${result.name}"`)
+    }
+
+    if (sizeNames && sizeNames.has(result.name)) {
+      throw new Error(`Preprocessor name "${result.name}" conflicts with a size name`)
+    }
+
+    names.add(result.name)
+    validated.push(result)
+  }
+
+  return validated
+}
+
+export async function applyOperations(input, operations, configDir, rawInfo = null) {
+  // Auto-rotate for EXIF only when input is a file path and no explicit rotate operation
+  const isBuffer = Buffer.isBuffer(input)
+  const hasExplicitRotate = operations.some(op => op.type === 'rotate')
+  // rawInfo = { width, height, channels } when input is a raw pixel buffer
+  const create = () => rawInfo ? sharp(input, { raw: rawInfo }) : sharp(input)
+  let pipeline = (!isBuffer && !hasExplicitRotate) ? create().rotate() : create()
+  const sidecars = []
+
+  for (const op of operations) {
+    if (OPERATION_REGISTRY[op.type]) {
+      const registryHandler = OPERATION_REGISTRY[op.type]
+      pipeline = registryHandler(pipeline, op, configDir)
+    } else {
+      // Treat type as a handler — flush pipeline to buffer, call handler, create new pipeline.
+      // Flush as fast lossless PNG: flushing in the source format would re-encode lossily.
+      const buf = await pipeline.png({ compressionLevel: 0 }).toBuffer()
+      const meta = await sharp(buf).metadata()
+      const handler = await loadHandler(op.type, configDir)
+
+      // Extract params (everything except type)
+      const { type: _type, ...params } = op
+      const result = await handler(buf, { ...params, width: meta.width, height: meta.height }, sharp)
+
+      // Handlers can return Buffer or { buffer, sidecars: [{ ext, data }] }
+      if (Buffer.isBuffer(result)) {
+        pipeline = sharp(result)
+      } else if (result && Buffer.isBuffer(result.buffer)) {
+        pipeline = sharp(result.buffer)
+        if (Array.isArray(result.sidecars)) {
+          sidecars.push(...result.sidecars)
+        }
+      } else {
+        throw new Error(`Custom handler "${op.type}" must return a Buffer or { buffer, sidecars }`)
+      }
+    }
+  }
+
+  // Fast lossless PNG — the final encode (format + quality) happens downstream;
+  // flushing in the source format here would add a hidden generation of loss.
+  const output = await pipeline.png({ compressionLevel: 0 }).toBuffer({ resolveWithObject: true })
+  output.sidecars = sidecars
+  return output
+}

package/lib/processor.js

@@ -6,7 +6,8 @@ import { validateConfig, configHash } from './config.js'
 import { toSharpOptions, filterByUpscale } from './sizes.js'
 import { convertFormat, resolveTargetFormats } from './formats.js'
 import { discoverAll } from './discover.js'
-import { analyzeImage } from './analyze.js'
+import { analyzeImage, buildEffectiveSizes } from './analyze.js'
+import { applyOperations } from './preprocess.js'
 import Cache from './cache.js'
 import { processSvg } from './svg.js'
 import log from './utils/log.js'
@@ -15,6 +16,7 @@ import { formatBytes, formatTime } from './utils/format.js'
 export default class ImageProcessor {
   constructor(config) {
     this.config = validateConfig(config)
+    this._configDir = this.config.configDir
     this.cache = new Cache(this.config.out, this.config.cache)
     this.stats = { processed: 0, variants: 0, skipped: 0, bytes: 0, startTime: 0 }
     this.watcher = null
@@ -104,20 +106,132 @@ export default class ImageProcessor {
     // Get previous outputs before processing (for stale cleanup)
     const previousOutputs = this.cache.getOutputs(relativePath)
 
-    // Filter sizes by upscale constraints
-    const eligibleSizes = filterByUpscale(
-      job.effectiveSizes, job.sourceWidth, job.sourceHeight
-    )
+    // 1. Original pipeline
+    await this._processVariants(inputPath, job, null, outputs, startTime)
+
+    // 2. Preprocessor pipelines
+    for (const preprocessor of this.config.preprocessors) {
+      try {
+        if (preprocessor.resizeFirst === true) {
+          // Per-variant: _processVariants resizes each variant, then preprocesses it
+          await this._processVariants(inputPath, job, preprocessor, outputs, startTime)
+        } else if (preprocessor.resizeFirst) {
+          // Object: resize to base size once, preprocess once, then generate variants.
+          // Base dims cap the variant sizes so nothing upscales past the base.
+          const base = await this._resizeToBase(inputPath, preprocessor.resizeFirst, job)
+          const result = await applyOperations(base.data, preprocessor.operations, this._configDir, {
+            width: base.info.width, height: base.info.height, channels: base.info.channels
+          })
+          await this._processVariants(result.data, job, preprocessor, outputs, startTime, base.info)
+          this._writeSidecars(result.sidecars, job, preprocessor, outputs, startTime)
+        } else {
+          const result = await applyOperations(inputPath, preprocessor.operations, this._configDir)
+          await this._processVariants(result.data, job, preprocessor, outputs, startTime)
+          this._writeSidecars(result.sidecars, job, preprocessor, outputs, startTime)
+        }
+      } catch (err) {
+        log({ tag: 'error', text: `Preprocessor "${preprocessor.name}" failed: ${err.message}`, link: relativePath })
+      }
+    }
+
+    // Clean up stale outputs from previous runs of this source file
+    const newPaths = new Set(outputs.map(o => o.path))
+    for (const prev of previousOutputs) {
+      const prevPath = typeof prev === 'string' ? prev : prev.path
+      if (!newPaths.has(prevPath)) {
+        const fullPath = path.join(this.config.out, prevPath)
+        if (fs.existsSync(fullPath)) {
+          fs.unlinkSync(fullPath)
+        }
+      }
+    }
+
+    this.cache.setEntry(relativePath, {
+      mtime: job.mtime,
+      size: job.fileSize,
+      width: job.sourceWidth,
+      height: job.sourceHeight,
+      exif: job.exif,
+      outputs
+    })
+
+    this.stats.processed++
+  }
+
+  /**
+   * Process size variants for a given input (file path or buffer).
+   * @param {string|Buffer} input - file path (original) or Buffer (preprocessed)
+   * @param {object} job - analysis result from analyzeImage
+   * @param {object|null} preprocessor - preprocessor config, or null for original pipeline
+   * @param {Array} outputs - accumulator for output entries
+   * @param {number} startTime - processing start timestamp
+   * @param {object|null} baseDims - dims of the input when it's a pre-shrunk base buffer
+   *   (resizeFirst object form); caps variant sizes so nothing upscales past the base
+   */
+  async _processVariants(input, job, preprocessor, outputs, startTime, baseDims = null) {
+    const relativePath = job.relativePath
+    // resizeFirst: true — operations run on each already-resized variant
+    const preprocessPerVariant = preprocessor?.resizeFirst === true
+
+    // Determine effective config — preprocessor overrides or global
+    const skipOrig = preprocessor?.skipOriginal != null ? preprocessor.skipOriginal : this.config.skipOriginal
+    let sizes
+    if (preprocessor?.sizes) {
+      sizes = buildEffectiveSizes(
+        preprocessor.sizes.map(s => ({ width: s.width || 0, height: s.height || 0, name: s.name || '', crop: s.crop || false })),
+        skipOrig
+      )
+    } else if (preprocessor && preprocessor.skipOriginal != null) {
+      // Preprocessor overrides skipOriginal but uses global sizes
+      sizes = buildEffectiveSizes(this.config.sizes, skipOrig)
+    } else {
+      sizes = job.effectiveSizes
+    }
+    const format = preprocessor?.format != null ? preprocessor.format : this.config.format
+    const quality = preprocessor?.quality != null
+      ? (typeof preprocessor.quality === 'number'
+          ? { jpg: preprocessor.quality, webp: preprocessor.quality, avif: preprocessor.quality, png: preprocessor.quality }
+          : { ...this.config.quality, ...preprocessor.quality })
+      : this.config.quality
+
+    const namePrefix = preprocessor ? `${job.parsed.name}-${preprocessor.name}` : job.parsed.name
+
+    // Filter sizes by upscale constraints — against the base buffer dims when pre-shrunk
+    const srcWidth = baseDims ? baseDims.width : job.sourceWidth
+    const srcHeight = baseDims ? baseDims.height : job.sourceHeight
+    const eligibleSizes = filterByUpscale(sizes, srcWidth, srcHeight)
+    let sidecarsWritten = false
 
     for (const sizeDef of eligibleSizes) {
       const conversionOnly = sizeDef.width === 0 && sizeDef.height === 0
 
-      // Resize
+      // Resize — flush to raw pixels; the only encode is the final one per format
       const sharpOpts = toSharpOptions(sizeDef)
-      const pipeline = sharpOpts ? sharp(inputPath).rotate().resize(sharpOpts) : sharp(inputPath).rotate()
-      const resizedBuffer = await pipeline.toBuffer({ resolveWithObject: true })
-      const actualWidth = resizedBuffer.info.width
-      const actualHeight = resizedBuffer.info.height
+      let pipeline = typeof input === 'string' ? sharp(input).rotate() : sharp(input)
+      if (sharpOpts) pipeline = pipeline.resize(sharpOpts)
+      const resized = await pipeline.raw().toBuffer({ resolveWithObject: true })
+
+      // data is either raw pixels (with rawInfo) or an encoded buffer (rawInfo null)
+      let data = resized.data
+      let rawInfo = { width: resized.info.width, height: resized.info.height, channels: resized.info.channels }
+      let actualWidth = resized.info.width
+      let actualHeight = resized.info.height
+
+      if (preprocessPerVariant) {
+        const ppResult = await applyOperations(data, preprocessor.operations, this._configDir, rawInfo)
+        data = ppResult.data
+        rawInfo = null
+        actualWidth = ppResult.info.width
+        actualHeight = ppResult.info.height
+
+        // Sidecar filename has no size suffix — write once, from the first variant
+        if (!sidecarsWritten && ppResult.sidecars.length > 0) {
+          this._writeSidecars(ppResult.sidecars, job, preprocessor, outputs, startTime)
+          sidecarsWritten = true
+        }
+      }
+
+      const toSharp = () => rawInfo ? sharp(data, { raw: rawInfo }) : sharp(data)
 
       // Build output path
       const outDir = path.join(this.config.out, job.parsed.dir)
@@ -125,26 +239,25 @@ export default class ImageProcessor {
 
       let baseName
       if (conversionOnly) {
-        baseName = job.parsed.name
+        baseName = namePrefix
       } else if (sizeDef.name) {
-        baseName = `${job.parsed.name}-${sizeDef.name}-${actualWidth}w`
+        baseName = `${namePrefix}-${sizeDef.name}-${actualWidth}w`
       } else {
-        baseName = `${job.parsed.name}-${actualWidth}w`
+        baseName = `${namePrefix}-${actualWidth}w`
       }
 
       // Resolve which formats to generate
       const { formats: targetFormats, preEncoded } = await resolveTargetFormats(
-        job.outputExt, job.transparent, resizedBuffer.data,
-        this.config.format, this.config.quality
+        job.outputExt, job.transparent, toSharp,
+        format, quality
       )
 
       // Encode + write each target format
       for (const targetExt of targetFormats) {
         let buffer
         try {
-          // Reuse pre-encoded buffer from smart format comparison when available
           buffer = preEncoded.get(targetExt) || await convertFormat(
-            sharp(resizedBuffer.data), targetExt, this.config.quality
+            toSharp(), targetExt, quality
           )
         } catch (err) {
           log({ tag: 'error', text: `Format conversion failed (${targetExt}): ${err.message}`, link: relativePath })
@@ -162,36 +275,70 @@ export default class ImageProcessor {
 
         log({
           tag: 'image',
-          text: 'Compiled:',
+          text: preprocessor ? `Compiled [${preprocessor.name}]:` : 'Compiled:',
           link: relPath,
           size: formatBytes(buffer.length),
           time: formatTime(Date.now() - startTime)
         })
       }
     }
+  }
 
-    // Clean up stale outputs from previous runs of this source file
-    const newPaths = new Set(outputs.map(o => o.path))
-    for (const prev of previousOutputs) {
-      const prevPath = typeof prev === 'string' ? prev : prev.path
-      if (!newPaths.has(prevPath)) {
-        const fullPath = path.join(this.config.out, prevPath)
-        if (fs.existsSync(fullPath)) {
-          fs.unlinkSync(fullPath)
-        }
-      }
+  /**
+   * Resize input to a base size before preprocessing.
+   * Used when resizeFirst is an object like { width: 800 } (validated size shape).
+   * Returns { data, info } — raw pixels at the base dimensions.
+   */
+  async _resizeToBase(input, resizeDef, job) {
+    // Don't upscale: clamp target to source dimensions
+    const def = {
+      name: '',
+      width: resizeDef.width || 0,
+      height: resizeDef.height || 0,
+      crop: resizeDef.crop || false
+    }
+    if (def.crop && def.width > 0 && def.height > 0) {
+      // Proportional clamp — independent clamping would change the crop aspect ratio
+      const scale = Math.min(job.sourceWidth / def.width, job.sourceHeight / def.height, 1)
+      def.width = Math.max(1, Math.round(def.width * scale))
+      def.height = Math.max(1, Math.round(def.height * scale))
+    } else {
+      def.width = Math.min(def.width, job.sourceWidth)
+      def.height = Math.min(def.height, job.sourceHeight)
     }
+    const opts = toSharpOptions(def)
 
-    this.cache.setEntry(relativePath, {
-      mtime: job.mtime,
-      size: job.fileSize,
-      width: job.sourceWidth,
-      height: job.sourceHeight,
-      exif: job.exif,
-      outputs
-    })
+    let pipeline = typeof input === 'string' ? sharp(input).rotate() : sharp(input)
+    if (opts) pipeline = pipeline.resize(opts)
 
-    this.stats.processed++
+    return pipeline.raw().toBuffer({ resolveWithObject: true })
+  }
+
+  _writeSidecars(sidecars, job, preprocessor, outputs, startTime) {
+    if (!sidecars || sidecars.length === 0) return
+
+    const namePrefix = preprocessor ? `${job.parsed.name}-${preprocessor.name}` : job.parsed.name
+    const outDir = path.join(this.config.out, job.parsed.dir)
+    fs.mkdirSync(outDir, { recursive: true })
+
+    for (const sidecar of sidecars) {
+      const filename = `${namePrefix}.${sidecar.ext}`
+      const outputPath = path.join(outDir, filename)
+      const relPath = path.join(job.parsed.dir, filename)
+
+      fs.writeFileSync(outputPath, sidecar.data)
+      outputs.push({ path: relPath, width: null, height: null })
+      this.stats.variants++
+      this.stats.bytes += sidecar.data.length
+
+      log({
+        tag: 'image',
+        text: preprocessor ? `Compiled [${preprocessor.name}]:` : 'Compiled:',
+        link: relPath,
+        size: formatBytes(sidecar.data.length),
+        time: formatTime(Date.now() - startTime)
+      })
+    }
   }
 
   watch() {
@@ -216,20 +363,9 @@ export default class ImageProcessor {
     })
 
     this.watcher.on('unlink', (filePath) => {
-      const relativePath = path.relative(this.config.in, filePath)
-      const outputs = this.cache.getOutputs(relativePath)
-
-      for (const output of outputs) {
-        const outputPath = typeof output === 'string' ? output : output.path
-        const fullPath = path.join(this.config.out, outputPath)
-        if (fs.existsSync(fullPath)) {
-          fs.unlinkSync(fullPath)
-          log({ tag: 'image', text: 'Removed:', link: outputPath })
-        }
-      }
-
-      this.cache.removeEntry(relativePath)
-      this.cache.save()
+      // Through the queue — deleting outputs mid-processing races with writes
+      this._watchQueue.push({ type: 'unlink', filePath })
+      this._drainWatchQueue()
     })
 
     return this.watcher
@@ -274,16 +410,58 @@ export default class ImageProcessor {
       }
 
       const result = await processSvg(svgFile, this.config.out, this.config.in)
-      if (result) {
-        this.cache.setEntry(relativePath, {
-          mtime: stat.mtimeMs,
-          size: stat.size,
-          outputs: [{ path: result.relativePath, width: result.width, height: result.height }]
-        })
-        this.stats.processed++
-        this.stats.variants++
-        this.stats.bytes += result.outputSize
+      if (!result) continue
+
+      const outputs = [{ path: result.relativePath, width: result.width, height: result.height }]
+      this.stats.variants++
+      this.stats.bytes += result.outputSize
+
+      // Run SVG-enabled preprocessors on rasterized SVG (original size only)
+      const svgPreprocessors = this.config.preprocessors.filter(pp => pp.svg)
+      if (svgPreprocessors.length > 0) {
+        const startTime = Date.now()
+        const parsed = path.parse(relativePath)
+
+        let meta
+        try {
+          meta = await sharp(svgFile).metadata()
+        } catch (err) {
+          log({ tag: 'error', text: `Failed to rasterize SVG: ${err.message}`, link: relativePath })
+        }
+
+        if (meta) {
+          const svgJob = {
+            relativePath,
+            parsed,
+            sourceWidth: meta.width,
+            sourceHeight: meta.height,
+            outputExt: 'png',
+            transparent: true,
+            effectiveSizes: [{ name: '', width: 0, height: 0, crop: false }]
+          }
+
+          for (const preprocessor of svgPreprocessors) {
+            try {
+              const ppResult = await applyOperations(svgFile, preprocessor.operations, this._configDir)
+              // Force original-only sizes for SVG preprocessing
+              const svgPP = { ...preprocessor, sizes: null, skipOriginal: null }
+              await this._processVariants(ppResult.data, svgJob, svgPP, outputs, startTime)
+              this._writeSidecars(ppResult.sidecars, svgJob, svgPP, outputs, startTime)
+            } catch (err) {
+              log({ tag: 'error', text: `Preprocessor "${preprocessor.name}" failed for SVG: ${err.message}`, link: relativePath })
+            }
+          }
+        }
       }
+
+      this.cache.setEntry(relativePath, {
+        mtime: stat.mtimeMs,
+        size: stat.size,
+        width: result.width,
+        height: result.height,
+        outputs
+      })
+      this.stats.processed++
     }
   }
 
@@ -348,18 +526,37 @@ export default class ImageProcessor {
   }
 
   _enqueueWatch(filePath, force) {
-    this._watchQueue.push({ filePath, force })
+    this._watchQueue.push({ type: 'process', filePath, force })
     this._drainWatchQueue()
   }
 
+  _watchRemoveOutputs(filePath) {
+    const relativePath = path.relative(this.config.in, filePath)
+    const outputs = this.cache.getOutputs(relativePath)
+
+    for (const output of outputs) {
+      const outputPath = typeof output === 'string' ? output : output.path
+      const fullPath = path.join(this.config.out, outputPath)
+      if (fs.existsSync(fullPath)) {
+        fs.unlinkSync(fullPath)
+        log({ tag: 'image', text: 'Removed:', link: outputPath })
+      }
+    }
+
+    this.cache.removeEntry(relativePath)
+    this.cache.save()
+  }
+
   async _drainWatchQueue() {
     if (this._watchProcessing) return
     this._watchProcessing = true
 
     while (this._watchQueue.length > 0) {
-      const { filePath, force } = this._watchQueue.shift()
+      const { type, filePath, force } = this._watchQueue.shift()
       try {
-        if (this._isSvg(filePath)) {
+        if (type === 'unlink') {
+          this._watchRemoveOutputs(filePath)
+        } else if (this._isSvg(filePath)) {
           await this._watchProcessSvg(filePath)
         } else if (this._isGif(filePath)) {
           await this._watchProcessGif(filePath, force)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poops-images",
   "description": "CLI tool for preparing images for the web.",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "license": "MIT",
   "type": "module",
   "main": "lib/processor.js",

package/poops-images.js

@@ -77,6 +77,32 @@ cli.option('quality', {
 })
 cli.option('dry-run', { description: 'Show what would be processed without writing' })
 cli.option('skip-original', { description: 'Skip the original (non-resized) compressed image' })
+cli.option('preprocess', {
+  short: 'P',
+  value: '<ops>',
+  description: 'Preprocess operations (e.g. blur:20,grayscale,sharpen:1.5)',
+  callback: (val) => {
+    const PRIMARY_PARAM = {
+      blur: 'sigma',
+      sharpen: 'sigma',
+      gamma: 'value',
+      rotate: 'angle',
+      tint: 'color'
+    }
+    return val.split(',').map(op => {
+      const [type, ...args] = op.trim().split(':')
+      const params = { type }
+      if (args.length === 1) {
+        const key = PRIMARY_PARAM[type]
+        if (key) {
+          const num = Number(args[0])
+          params[key] = isNaN(num) ? args[0] : num
+        }
+      }
+      return params
+    })
+  }
+})
 
 cli.line('')
 cli.line('Quick mode (no config file needed):')
@@ -97,6 +123,7 @@ try {
   const cliFormat = flags.format
   const cliQuality = flags.quality
   const skipOriginal = flags['skip-original']
+  const cliPreprocess = flags.preprocess
 
   if (quiet) setQuiet(true)
 
@@ -138,6 +165,7 @@ try {
     if (cliFormat !== null) raw.format = cliFormat
     if (cliQuality != null) raw.quality = cliQuality
     if (skipOriginal) raw.skipOriginal = true
+    if (cliPreprocess) raw.preprocessors = [{ name: 'preprocessed', operations: cliPreprocess }]
     config = validateConfig(raw)
   } else {
     config = loadConfig(configPath)
@@ -153,6 +181,10 @@ try {
       }
     }
     if (skipOriginal) config.skipOriginal = true
+    if (cliPreprocess) {
+      config.preprocessors = config.preprocessors || []
+      config.preprocessors.push({ name: 'preprocessed', operations: cliPreprocess })
+    }
   }
   const processor = new ImageProcessor(config)