image-guard 5.1.2 → 5.2.1

package/.github/FUNDING.yml

@@ -1,3 +1,3 @@
-buy_me_a_coffee: meiert
+# buy_me_a_coffee: meiert
 github: j9t
-liberapay: j9t
+# liberapay: j9t

package/.github/dependabot.yml

@@ -1,4 +1,4 @@
-# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference
+# https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference
 
 version: 2
 updates:

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+Starting with version 5.2.0, all notable changes to Image Guard are documented in this file, which is (mostly) AI-generated and (always) human-edited. Dependency updates may or may not be called out specifically.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [5.2.1] - 2026-02-17
+
+### Changed
+
+* HEIC-to-AVIF conversion now uses lossy encoding (quality 80) instead of lossless, producing files smaller than the HEIC originals
+* Removed redundant lossless compression pass after HEIC conversion
+* Documented Display P3 to sRGB color space mapping during HEIC conversion
+
+## [5.2.0] - 2026-02-17
+
+### Added
+
+* Added opt-in HEIC/HEIF-to-AVIF conversion via `--heic-to-avif` (with `--keep-heic` to preserve originals)
+* Introduced changelog

package/README.md

@@ -2,9 +2,9 @@
 
 [![npm version](https://img.shields.io/npm/v/image-guard.svg)](https://www.npmjs.com/package/image-guard) [![Build status](https://github.com/j9t/image-guard/workflows/Tests/badge.svg)](https://github.com/j9t/image-guard/actions) [![Socket](https://badge.socket.dev/npm/package/image-guard)](https://socket.dev/npm/package/image-guard)
 
-(This project was based on [sum.cumo’s imagemin-merlin](https://github.com/sumcumo/imagemin-merlin). [Changes are documented](https://github.com/sumcumo/imagemin-merlin/compare/master...j9t:master), and include this README. Image Guard supports two additional file formats—WebP and AVIF—, comes with improved code and documentation, and is being maintained. For this reason, it’s [not based on any Imagemin packages](https://meiert.com/blog/image-guard-4/) anymore.)
+(This project was based on [sum.cumo’s imagemin-merlin](https://github.com/sumcumo/imagemin-merlin). [Changes are documented](https://github.com/sumcumo/imagemin-merlin/compare/master...j9t:master), and include this README. Image Guard supports additional file formats—WebP, AVIF, and HEIC/HEIF—, comes with improved code and documentation, and is being maintained. For this reason, it’s [not based on any Imagemin packages](https://meiert.com/blog/image-guard-4/) anymore.)
 
-Image Guard takes care of near-lossless compression of your images, to help you avoid bloat in your repositories. It makes it convenient and as safe as possible to automatically compress PNG, JPG, GIF, WebP, and AVIF images.
+Image Guard takes care of near-lossless compression of your images, to help you avoid bloat in your repositories. It makes it convenient and as safe as possible to automatically compress PNG, JPG, GIF, WebP, and AVIF images. It can also convert HEIC/HEIF files to AVIF (opt-in via `--heic-to-avif`).
 
 It’s convenient because setup is simple. Run it right away—done. Or install, run, add hook—done.
 
@@ -48,7 +48,7 @@ Install Image Guard in your project:
 npm i -D image-guard
 ```
 
-To compress images already in the code base, run Image Guard once by calling
+To compress images already in the codebase, run Image Guard once by calling
 
 ```console
 npx image-guard
@@ -109,7 +109,11 @@ npm pkg set scripts.postprepare="grep -qxF 'npx image-guard --staged' .husky/pre
 
 * `--ignore` allows you to specify paths to be ignored (as in `--ignore=example,test`). Multiple paths must be separated by commas. The option supports glob patterns (e.g., `assets/**`, `**/*.png`); matching is case‑insensitive and honors `.gitignore`.
 
-* `--staged` (recommended with automated use) triggers a mode that watches PNG, JPG, GIF, WebP, and AVIF files in `git diff` and only compresses those files—that approach makes Image Guard more efficient in operation.
+* `--staged` (recommended with automated use) triggers a mode that watches PNG, JPG, GIF, WebP, and AVIF files (and HEIC/HEIF, when `--heic-to-avif` is used) in `git diff` and only processes those files—that approach makes Image Guard more efficient in operation.
+
+* `--heic-to-avif` converts HEIC/HEIF files to AVIF. Because HEIC sources are already lossy-compressed (HEVC), the conversion uses lossy AVIF encoding (quality 80) to produce files smaller than the originals at near-identical visual quality. Original HEIC/HEIF files are deleted after conversion by default. (Note: The conversion maps Display P3 colors—common on iPhones—to sRGB, which may result in slightly less vivid colors.)
+
+  - `--keep-heic` (used with `--heic-to-avif`) preserves the original HEIC/HEIF files instead of deleting them after conversion.
 
 * `--quiet` suppresses per‑file logs and prints only the final summary (plus errors). This reduces console noise and speeds up runs in CI and Git hooks.
 
@@ -134,6 +138,7 @@ Roughly like this:
 ![Screenshot of Image Guard in operation.](https://raw.githubusercontent.com/j9t/image-guard/master/media/output.png)
 
 * Green: The image file has been compressed.
+* Cyan: The image file has been converted (HEIC/HEIF to AVIF).
 * White (light gray): The image file has not been changed.
 * Blue: The image file had already been compressed more aggressively than the new result, and was therefore skipped, too.
 
@@ -143,7 +148,7 @@ Tip: Use `--quiet` to suppress these per‑file lines and keep only the final su
 
 Image Guard is a Node script that uses [sharp](https://www.npmjs.com/package/sharp) under the hood.
 
-Automated compression works by monitoring whether a given [change list](https://webglossary.info/terms/change-list/) includes any PNGs, JPGs, GIFs, WebPs, or AVIFs. It’s initiated by a Git hook. Only those images are compressed where there is an improvement. The compressed images can then be committed to the underlying repository.
+Automated compression works by monitoring whether a given [change list](https://webglossary.info/terms/change-list/) includes any PNGs, JPGs, GIFs, WebPs, or AVIFs (and HEIC/HEIF when opted in). It’s initiated by a Git hook. Only those images are compressed where there is an improvement. HEIC conversion uses [heic-decode](https://www.npmjs.com/package/heic-decode) for patent-free decoding and sharp for lossy AVIF encoding (quality 80). The processed images can then be committed to the underlying repository.
 
 Through this approach, though glossed over here, Image Guard makes up for what’s missing or complicated in other packages, namely easy, near-riskless, automatable, resource-friendly in-repo optimization.
 
@@ -167,7 +172,7 @@ Feedback is appreciated: Please [file an issue](https://github.com/j9t/image-gua
 
 ## License
 
-Copyright 2019 [sum.cumo GmbH](https://web.archive.org/web/20191208211414/https://www.sumcumo.com/)
+Copyright 2019 [sum.cumo GmbH](https://web.archive.org/web/20191208211414/https://www.sumcumo.com/)<br>
 Copyright 2022 [Jens Oliver Meiert](https://meiert.com/)
 
 Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

package/bin/image-guard.test.js

@@ -389,4 +389,137 @@ describe('Image Guard', () => {
     // Cleanup
     fs.rmSync(tempDir, { recursive: true, force: true })
   })
+
+  test('Convert HEIC to AVIF with `--heic-to-avif`', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-heic-'))
+    const tempTestFolder = path.join(tempDir, 'test')
+    copyFiles(testFolder, tempTestFolder)
+
+    // Ensure HEIC test fixture exists
+    const heicFile = path.join(tempTestFolder, 'test.heic')
+    assert.strictEqual(fs.existsSync(heicFile), true, 'HEIC test fixture must exist')
+
+    // Remove pre-existing AVIF so we can verify the conversion actually creates it
+    const avifFile = path.join(tempTestFolder, 'test.avif')
+    if (fs.existsSync(avifFile)) {
+      fs.unlinkSync(avifFile)
+    }
+
+    const originalCwd = process.cwd()
+    try {
+      process.chdir(tempDir)
+      execSync(`node "${imageGuardScript}" --heic-to-avif`, { stdio: 'pipe' })
+    } finally {
+      process.chdir(originalCwd)
+    }
+
+    // AVIF should be created by the conversion
+    assert.strictEqual(fs.existsSync(avifFile), true, 'AVIF file should be created')
+    const avifSize = fs.statSync(avifFile).size
+    assert.ok(avifSize > 0, 'AVIF file should not be empty')
+
+    // Lossy AVIF should not be larger than the HEIC source
+    const heicSize = fs.statSync(path.join(testFolder, 'test.heic')).size
+    assert.ok(avifSize <= heicSize, `AVIF (${avifSize}) should not be larger than HEIC (${heicSize})`)
+
+    // Original HEIC should be deleted
+    assert.strictEqual(fs.existsSync(heicFile), false, 'Original HEIC should be deleted')
+
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  test('`--keep-heic` preserves original HEIC file', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-keep-heic-'))
+    const tempTestFolder = path.join(tempDir, 'test')
+    copyFiles(testFolder, tempTestFolder)
+
+    const heicFile = path.join(tempTestFolder, 'test.heic')
+    assert.strictEqual(fs.existsSync(heicFile), true, 'HEIC test fixture must exist')
+
+    const originalCwd = process.cwd()
+    try {
+      process.chdir(tempDir)
+      execSync(`node "${imageGuardScript}" --heic-to-avif --keep-heic`, { stdio: 'pipe' })
+    } finally {
+      process.chdir(originalCwd)
+    }
+
+    // Both files should exist
+    assert.strictEqual(fs.existsSync(path.join(tempTestFolder, 'test.avif')), true, 'AVIF file should be created')
+    assert.strictEqual(fs.existsSync(heicFile), true, 'HEIC file should be preserved with `--keep-heic`')
+
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  test('Dry run does not convert HEIC files', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-heic-dry-'))
+    const tempTestFolder = path.join(tempDir, 'test')
+    copyFiles(testFolder, tempTestFolder)
+
+    const heicFile = path.join(tempTestFolder, 'test.heic')
+    const heicBefore = fs.statSync(heicFile)
+    const filesBefore = fs.readdirSync(tempTestFolder).sort()
+
+    const originalCwd = process.cwd()
+    try {
+      process.chdir(tempDir)
+      execSync(`node "${imageGuardScript}" --heic-to-avif --dry`, { stdio: 'pipe' })
+    } finally {
+      process.chdir(originalCwd)
+    }
+
+    // HEIC should be unchanged
+    const heicAfter = fs.statSync(heicFile)
+    assert.strictEqual(heicAfter.size, heicBefore.size)
+    assert.strictEqual(heicAfter.mtime.getTime(), heicBefore.mtime.getTime())
+
+    // No files should be added or removed
+    const filesAfter = fs.readdirSync(tempTestFolder).sort()
+    assert.deepStrictEqual(filesAfter, filesBefore)
+
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  test('HEIC files are ignored without `--heic-to-avif` flag', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-heic-noflag-'))
+    const tempTestFolder = path.join(tempDir, 'test')
+    copyFiles(testFolder, tempTestFolder)
+
+    const heicFile = path.join(tempTestFolder, 'test.heic')
+    const heicBefore = fs.statSync(heicFile)
+
+    const originalCwd = process.cwd()
+    try {
+      process.chdir(tempDir)
+      execSync(`node "${imageGuardScript}"`, { stdio: 'pipe' })
+    } finally {
+      process.chdir(originalCwd)
+    }
+
+    // HEIC should be untouched
+    const heicAfter = fs.statSync(heicFile)
+    assert.strictEqual(heicAfter.size, heicBefore.size)
+    assert.strictEqual(heicAfter.mtime.getTime(), heicBefore.mtime.getTime())
+
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  test('`--keep-heic` without `--heic-to-avif` warns', () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'image-guard-keep-warn-'))
+    const tempTestFolder = path.join(tempDir, 'test')
+    copyFiles(testFolder, tempTestFolder)
+
+    const originalCwd = process.cwd()
+    let output = ''
+    try {
+      process.chdir(tempDir)
+      output = execSync(`node "${imageGuardScript}" --keep-heic 2>&1`, { encoding: 'utf8' })
+    } finally {
+      process.chdir(originalCwd)
+    }
+
+    assert.match(output, /`--keep-heic` has no effect without `--heic-to-avif`/)
+
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  })
 })

package/package.json

@@ -7,12 +7,13 @@
   },
   "dependencies": {
     "globby": "^16.1.0",
+    "heic-decode": "^2.1.0",
     "sharp": "^0.34.5",
     "simple-git": "^3.30.0"
   },
   "description": "Near-lossless image compressor that’s easy to use and easy to automate",
   "devDependencies": {
-    "eslint": "^9.39.2"
+    "eslint": "^10.0.0"
   },
   "funding": "https://github.com/j9t/image-guard?sponsor=1",
   "homepage": "https://github.com/j9t/image-guard",
@@ -22,6 +23,8 @@
     "compression",
     "gif",
     "graphics",
+    "heic",
+    "heif",
     "images",
     "jpeg",
     "jpg",
@@ -43,5 +46,5 @@
     "test": "node --test bin/image-guard.test.js"
   },
   "type": "module",
-  "version": "5.1.2"
+  "version": "5.2.1"
 }

package/src/index.js

@@ -11,26 +11,38 @@ import { utils } from './utils.js'
 // Files to be compressed
 export const fileTypes = ['avif', 'gif', 'jpg', 'jpeg', 'png', 'webp'];
 
+// Files to be converted (require explicit opt-in)
+export const convertTypes = ['heic', 'heif'];
+
 export async function runImageGuard() {
   const options = {
     dry: { type: 'boolean', default: false },
+    'heic-to-avif': { type: 'boolean', default: false },
     ignore: { type: 'string', multiple: false, default: '' },
+    'keep-heic': { type: 'boolean', default: false },
     staged: { type: 'boolean', default: false },
     quiet: { type: 'boolean', default: false }
   }
   const { values: argv } = parseArgs({ options })
 
   // Share status
-  const summary = (run) => {
+  const summary = (run, includesConversion = false) => {
     if (run) {
-      console.info(styleText(['bold'], `\nDefensive base compression completed. You saved ${utils.sizeReadable(savedKB)}.`))
+      const action = includesConversion ? 'compression and conversion' : 'compression'
+      console.info(styleText(['bold'], `\nDefensive base ${action} completed. You saved ${utils.sizeReadable(savedKB)}.`))
     } else {
-      console.info(styleText(['bold'], 'There were no images to compress.'))
+      const what = includesConversion ? 'images to compress or convert' : 'images to compress'
+      console.info(styleText(['bold'], `There were no ${what}.`))
     }
   }
 
+  if (argv['keep-heic'] && !argv['heic-to-avif']) {
+    console.warn(styleText('yellow', '`--keep-heic` has no effect without `--heic-to-avif`'))
+  }
+
+  const allTypes = argv['heic-to-avif'] ? [...fileTypes, ...convertTypes] : fileTypes
   if (!argv.quiet) {
-    console.log(`(Search pattern: ${fileTypes.join(', ')})\n`)
+    console.log(`(Search pattern: ${allTypes.join(', ')})\n`)
   }
 
   let savedKB = 0
@@ -71,66 +83,74 @@ export async function runImageGuard() {
     })
   }
 
-  const compress = async (files, dry) => {
-    if (files.length === 0) {
-      summary(false)
-      return
-    }
-
-    const desiredFileConcurrency = Math.min(os.cpus().length, 4)
-    // Tune libvips threads to avoid oversubscription
-    const perTaskThreads = Math.max(1, Math.floor(os.cpus().length / Math.max(1, desiredFileConcurrency)))
-    try {
-      sharp.concurrency(perTaskThreads)
-    } catch {
-      // Best-effort; ignore if not supported (could log in debug mode)
-    }
-
-    const limit = createLimiter(desiredFileConcurrency)
-    const tasks = files.map(file => limit(() => utils.compression(file, dry, argv.quiet)))
-    const results = await Promise.allSettled(tasks)
+  const desiredFileConcurrency = Math.min(os.cpus().length, 4)
+  const perTaskThreads = Math.max(1, Math.floor(os.cpus().length / Math.max(1, desiredFileConcurrency)))
+  try {
+    sharp.concurrency(perTaskThreads)
+  } catch {
+    // Best-effort; ignore if not supported
+  }
+  const limit = createLimiter(desiredFileConcurrency)
 
+  const processResults = (results) => {
     let hadFailures = false
+    let addedKB = 0
     for (const r of results) {
       if (r.status === 'fulfilled') {
         if (typeof r.value === 'number') {
-          savedKB += r.value
+          addedKB += r.value
         } else {
-          // Treat non-numeric fulfillment as a failure signal
           hadFailures = true
         }
       } else {
         hadFailures = true
-        // Log the underlying reason to aid troubleshooting
         const reason = r.reason && r.reason.message ? r.reason.message : String(r.reason)
-        console.error(styleText('red', 'Compression task failed:'), reason)
+        console.error(styleText('red', 'Task failed:'), reason)
       }
     }
+    return { hadFailures, addedKB }
+  }
 
-    if (hadFailures) {
-      process.exitCode = 1
-      summary(false)
-      return
-    }
+  const compress = async (files, dry) => {
+    if (files.length === 0) return false
+
+    const tasks = files.map(file => limit(() => utils.compression(file, dry, argv.quiet)))
+    const results = await Promise.allSettled(tasks)
 
-    summary(true)
+    const { hadFailures, addedKB } = processResults(results)
+    savedKB += addedKB
+    return hadFailures
   }
 
-  const getFilePattern = (ignore) => {
-    const patterns = []
+  const convert = async (files, dry, keepOriginal) => {
+    if (files.length === 0) return false
 
-    // Rely on `caseSensitiveMatch: false` instead of duplicating upper/lower-case
-    for (const fileType of fileTypes) {
-      patterns.push(`**/*.${fileType}`)
-    }
+    const tasks = files.map(file => limit(() => utils.conversion(file, dry, keepOriginal, argv.quiet)))
+    const results = await Promise.allSettled(tasks)
 
-    const ignoreList = (ignore || '')
+    const { hadFailures, addedKB } = processResults(results)
+    savedKB += addedKB
+    return hadFailures
+  }
+
+  const getIgnorePatterns = (ignore) => {
+    return (ignore || '')
       .split(',')
       .map(s => s.trim())
       .filter(Boolean)
+      .map(p => (p.startsWith('!') ? p : `!${p}`))
+  }
 
-    for (const p of ignoreList) {
-      patterns.push(p.startsWith('!') ? p : `!${p}`)
+  const getFilePattern = (ignore, types = fileTypes) => {
+    const patterns = []
+
+    // Rely on `caseSensitiveMatch: false` instead of duplicating upper/lower-case
+    for (const fileType of types) {
+      patterns.push(`**/*.${fileType}`)
+    }
+
+    for (const p of getIgnorePatterns(ignore)) {
+      patterns.push(p)
     }
 
     return patterns
@@ -145,51 +165,74 @@ export async function runImageGuard() {
     })
   }
 
-  const patterns = getFilePattern(argv.ignore)
-  let files = []
-  let compressionFiles = []
+  const filterStagedFiles = async (stagedFiles, types) => {
+    const allowedExts = new Set(types)
+    const byExt = stagedFiles.filter(f => allowedExts.has(path.extname(f).slice(1).toLowerCase()))
+    const ignoreList = getIgnorePatterns(argv.ignore)
+
+    if (ignoreList.length > 0) {
+      const escapedPaths = byExt.map(p => convertPathToPattern(p))
+      return globby([...escapedPaths, ...ignoreList], {
+        gitignore: true,
+        expandDirectories: false,
+        onlyFiles: true,
+        caseSensitiveMatch: false
+      })
+    }
+    return byExt
+  }
+
+  const doConversion = argv['heic-to-avif']
+  let hadFailures = false
+  let totalFiles = 0
 
-  // Search for staged files
   if (argv.staged) {
     const git = simpleGit()
     try {
-      // Get staged file paths directly from Git
       const diffOutput = await git.raw(['diff', '--name-only', '--cached', '--diff-filter=ACMRT'])
       const stagedFiles = diffOutput.split('\n').map(s => s.trim()).filter(Boolean)
-      // Filter by allowed extensions
-      const allowedExts = new Set(fileTypes)
-      const byExt = stagedFiles.filter(f => allowedExts.has(path.extname(f).slice(1).toLowerCase()))
-      // Apply `--ignore` using the same glob semantics as non-staged by delegating to globby
-      const ignoreList = (argv.ignore || '')
-        .split(',')
-        .map(s => s.trim())
-        .filter(Boolean)
-        .map(p => (p.startsWith('!') ? p : `!${p}`))
-
-      if (ignoreList.length > 0) {
-        // Use globby to filter the staged list with identical options; avoid repo-wide scan
-        // Pass the staged file paths as include patterns and the ignores as negatives
-        const escapedPaths = byExt.map(p => convertPathToPattern(p))
-        const filtered = await globby([...escapedPaths, ...ignoreList], {
-          gitignore: true,
-          expandDirectories: false,
-          onlyFiles: true,
-          caseSensitiveMatch: false
-        })
-        compressionFiles = filtered
-      } else {
-        compressionFiles = byExt
+
+      const compressionFiles = await filterStagedFiles(stagedFiles, fileTypes)
+      totalFiles += compressionFiles.length
+      hadFailures = await compress(compressionFiles, argv.dry)
+
+      if (doConversion) {
+        const conversionFiles = await filterStagedFiles(stagedFiles, convertTypes)
+        totalFiles += conversionFiles.length
+        const convFailed = await convert(conversionFiles, argv.dry, argv['keep-heic'])
+        hadFailures = hadFailures || convFailed
       }
-      await compress(compressionFiles, argv.dry)
     } catch (err) {
       console.error(err)
-      // Ensure non-zero exit and failure summary on staged path errors
-      process.exitCode = 1
-      summary(false)
+      hadFailures = true
+    }
+  } else {
+    const patterns = getFilePattern(argv.ignore)
+    const compressionFiles = await findFiles(patterns)
+    totalFiles += compressionFiles.length
+    hadFailures = await compress(compressionFiles, argv.dry)
+
+    if (doConversion) {
+      const convPatterns = getFilePattern(argv.ignore, convertTypes)
+      const conversionFiles = await findFiles(convPatterns)
+      totalFiles += conversionFiles.length
+      const convFailed = await convert(conversionFiles, argv.dry, argv['keep-heic'])
+      hadFailures = hadFailures || convFailed
+    }
+  }
+
+  if (hadFailures) {
+    process.exitCode = 1
+    if (totalFiles > 0) {
+      const action = doConversion ? 'compression and conversion' : 'compression'
+      const savings = savedKB > 0 ? ` You saved ${utils.sizeReadable(savedKB)}.` : ''
+      console.info(styleText(['bold'], `\nDefensive base ${action} partially completed (some tasks failed).${savings}`))
+    } else {
+      summary(false, doConversion)
     }
+  } else if (totalFiles > 0) {
+    summary(true, doConversion)
   } else {
-    files = await findFiles(patterns)
-    compressionFiles = files
-    await compress(compressionFiles, argv.dry)
+    summary(false, doConversion)
   }
 }

package/src/utils.js

@@ -4,6 +4,7 @@ import fs from 'fs'
 import path from 'path'
 import sharp from 'sharp'
 import { styleText } from 'node:util'
+import decode from 'heic-decode'
 
 const logMessage = (message, dry, color = 'yellow', quiet = false) => {
   if (quiet) return
@@ -190,6 +191,86 @@ const compression = async (filename, dry, quiet = false) => {
   }
 }
 
+const conversion = async (filename, dry, keepOriginal, quiet = false) => {
+  const fileSizeBefore = await size(filename)
+
+  if (fileSizeBefore === 0) {
+    logMessage(`Skipped ${filename} (${sizeReadable(fileSizeBefore)})`, dry, 'yellow', quiet)
+    return 0
+  }
+
+  const maxFileSize = 100 * 1024 * 1024 // 100 MB
+
+  if (fileSizeBefore > maxFileSize) {
+    logMessage(`Skipped ${filename} (file too large: ${sizeReadable(fileSizeBefore)})`, dry, 'yellow', quiet)
+    return 0
+  }
+
+  if (!/\.hei[cf]$/i.test(filename)) {
+    logMessage(`Skipped ${filename} (not a HEIC/HEIF file)`, dry, 'yellow', quiet)
+    return 0
+  }
+
+  const avifPath = filename.replace(/\.hei[cf]$/i, '.avif')
+
+  // Avoid overwriting an existing AVIF file
+  try {
+    await fs.promises.access(avifPath)
+    logMessage(`Skipped ${filename} (${path.basename(avifPath)} already exists)`, dry, 'yellow', quiet)
+    return 0
+  } catch {
+    // File does not exist—proceed with conversion
+  }
+
+  try {
+    // Decode HEIC/HEIF to raw pixel data
+    const inputBuffer = await fs.promises.readFile(filename)
+    const { width, height, data } = await decode({ buffer: inputBuffer })
+
+    if (dry) {
+      logMessage(`Converted ${filename} → ${path.basename(avifPath)}`, dry, 'cyan', quiet)
+      return 0
+    }
+
+    // Encode as lossy AVIF—HEIC sources are already lossy (HEVC), so lossless
+    // re-encoding would inflate file sizes without any quality benefit
+    await sharp(data, { raw: { width, height, channels: 4 } })
+      .toFormat('avif', { quality: 80, effort: 5 })
+      .toFile(avifPath)
+
+    const fileSizeAfter = await size(avifPath)
+
+    logMessage(`Converted ${filename} → ${path.basename(avifPath)} (${sizeReadable(fileSizeBefore)} → ${sizeReadable(fileSizeAfter)})`, dry, 'cyan', quiet)
+
+    // Delete original HEIC/HEIF file unless `--keep-heic` is set
+    if (!keepOriginal) {
+      await retryFileOperation(() => fs.promises.unlink(filename))
+    }
+
+    return fileSizeAfter < fileSizeBefore ? fileSizeBefore - fileSizeAfter : 0
+
+  } catch (err) {
+    // Clean up partial AVIF if it was created
+    try {
+      await fs.promises.unlink(avifPath)
+    } catch (cleanupErr) {
+      if (cleanupErr.code !== 'ENOENT') {
+        console.warn(styleText('yellow', `Failed to clean up ${avifPath}:`), cleanupErr)
+      }
+    }
+
+    if (err.message && (
+      err.message.includes('not a HEIC image') ||
+      err.message.includes('HEIF image not found')
+    )) {
+      logMessage(`Skipped ${filename} (corrupt or unsupported HEIC/HEIF file)`, dry, 'yellow', quiet)
+    } else {
+      console.error(styleText('red', `Error converting ${filename}:`), err)
+    }
+    return 0
+  }
+}
+
 const size = async (file) => {
   const stats = await fs.promises.stat(file)
   return stats.size
@@ -197,4 +278,4 @@ const size = async (file) => {
 
 const sizeReadable = (size) => `${(size / 1024).toFixed(2)} KB`
 
-export const utils = { compression, sizeReadable }
+export const utils = { compression, conversion, sizeReadable }