feat: add source-only HEIC/HEIF image converter

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

package-lock.json

@@ -15,6 +15,7 @@
         "express": "^5.2.1",
         "express-rate-limit": "^8.6.1",
         "file-type": "^22.0.1",
+        "heic-convert": "^2.1.0",
         "icojs": "^1.0.0",
         "mammoth": "^1.12.0",
         "markdown-it": "^15.0.0",
@@ -3656,6 +3657,41 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/heic-convert": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/heic-convert/-/heic-convert-2.1.0.tgz",
+      "integrity": "sha512-1qDuRvEHifTVAj3pFIgkqGgJIr0M3X7cxEPjEp0oG4mo8GFjq99DpCo8Eg3kg17Cy0MTjxpFdoBHOatj7ZVKtg==",
+      "license": "ISC",
+      "dependencies": {
+        "heic-decode": "^2.0.0",
+        "jpeg-js": "^0.4.4",
+        "pngjs": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
+    "node_modules/heic-convert/node_modules/pngjs": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/pngjs/-/pngjs-6.0.0.tgz",
+      "integrity": "sha512-TRzzuFRRmEoSW/p1KVAmiOgPco2Irlah+bGFCeNfJXxxYGwSw7YwAOAcd7X28K/m5bjBWKsC29KyoMfHbypayg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.13.0"
+      }
+    },
+    "node_modules/heic-decode": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/heic-decode/-/heic-decode-2.1.0.tgz",
+      "integrity": "sha512-0fB3O3WMk38+PScbHLVp66jcNhsZ/ErtQ6u2lMYu/YxXgbBtl+oKOhGQHa4RpvE68k8IzbWkABzHnyAIjR758A==",
+      "license": "ISC",
+      "dependencies": {
+        "libheif-js": "^1.19.8"
+      },
+      "engines": {
+        "node": ">=8.0.0"
+      }
+    },
     "node_modules/http-errors": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
@@ -3897,6 +3933,15 @@
         "node": ">= 0.6.3"
       }
     },
+    "node_modules/libheif-js": {
+      "version": "1.19.8",
+      "resolved": "https://registry.npmjs.org/libheif-js/-/libheif-js-1.19.8.tgz",
+      "integrity": "sha512-vQJWusIxO7wavpON1dusciL8Go9jsIQ+EUrckauFYAiSTjcmLAsuJh3SszLpvkwPci3JcL41ek2n+LUZGFpPIQ==",
+      "license": "LGPL-3.0",
+      "engines": {
+        "node": ">=8.0.0"
+      }
+    },
     "node_modules/lie": {
       "version": "3.3.0",
       "resolved": "https://registry.npmjs.org/lie/-/lie-3.3.0.tgz",

package.json

@@ -22,6 +22,7 @@
     "express": "^5.2.1",
     "express-rate-limit": "^8.6.1",
     "file-type": "^22.0.1",
+    "heic-convert": "^2.1.0",
     "icojs": "^1.0.0",
     "mammoth": "^1.12.0",
     "markdown-it": "^15.0.0",

src/converters/heic.js

@@ -0,0 +1,43 @@
+import fs from 'node:fs/promises';
+import sharp from 'sharp';
+import convert from 'heic-convert';
+import { register } from './registry.js';
+import { sharpFormatName, buildFormatOptions } from './image.js';
+import { encodeIcoFromInput, DEFAULT_ICON_SIZE } from './ico.js';
+
+const IMAGE_FORMATS = ['jpg', 'jpeg', 'png', 'webp', 'gif', 'tiff', 'avif'];
+const HEIC_SOURCE_FORMATS = ['heic', 'heif'];
+
+async function decodeToPng(inputPath) {
+  const buffer = await fs.readFile(inputPath);
+  return convert({ buffer, format: 'PNG' });
+}
+
+export function registerHeicConverter() {
+  for (const sourceFormat of HEIC_SOURCE_FORMATS) {
+    for (const targetFormat of IMAGE_FORMATS) {
+      register({
+        family: 'image',
+        sourceFormat,
+        targetFormat,
+        convert: async (inputPath, outputPath, { quality } = {}) => {
+          const pngBuffer = await decodeToPng(inputPath);
+          await sharp(pngBuffer)
+            .toFormat(sharpFormatName(targetFormat), buildFormatOptions(targetFormat, quality))
+            .toFile(outputPath);
+        },
+      });
+    }
+
+    register({
+      family: 'image',
+      sourceFormat,
+      targetFormat: 'ico',
+      convert: async (inputPath, outputPath, { iconSize } = {}) => {
+        const pngBuffer = await decodeToPng(inputPath);
+        const icoBuffer = await encodeIcoFromInput(pngBuffer, iconSize ?? DEFAULT_ICON_SIZE);
+        await fs.writeFile(outputPath, icoBuffer);
+      },
+    });
+  }
+}

test/converters/heic.test.js

@@ -0,0 +1,86 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { registerHeicConverter } from '../../src/converters/heic.js';
+import { resolve, listTargetFormats } from '../../src/converters/registry.js';
+import { detectInputMime } from '../../src/mime.js';
+
+let tmpDir;
+
+beforeAll(async () => {
+  registerHeicConverter();
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'converter-heic-'));
+});
+
+afterAll(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+describe('HEIC/HEIF converter registration', () => {
+  it('registers heic and heif as source formats for every image target plus ico', () => {
+    expect(listTargetFormats('heic')).toEqual(
+      expect.arrayContaining(['jpg', 'jpeg', 'png', 'webp', 'gif', 'tiff', 'avif', 'ico'])
+    );
+    expect(listTargetFormats('heif')).toEqual(
+      expect.arrayContaining(['jpg', 'jpeg', 'png', 'webp', 'gif', 'tiff', 'avif', 'ico'])
+    );
+  });
+
+  it('never registers heic or heif as a target format', () => {
+    expect(listTargetFormats('png')).not.toContain('heic');
+    expect(listTargetFormats('png')).not.toContain('heif');
+  });
+});
+
+describe('heic -> image conversion', () => {
+  it('converts a HEIC fixture to PNG', async () => {
+    const inputPath = path.join(import.meta.dirname, '..', 'fixtures', 'sample.heic');
+    const outputPath = path.join(tmpDir, 'output.png');
+    const entry = resolve('heic', 'png');
+
+    await entry.convert(inputPath, outputPath);
+
+    const detected = await detectInputMime(outputPath);
+    expect(detected.mime).toBe('image/png');
+  });
+
+  it('converts a HEIC fixture to JPG', async () => {
+    const inputPath = path.join(import.meta.dirname, '..', 'fixtures', 'sample.heic');
+    const outputPath = path.join(tmpDir, 'output.jpg');
+    const entry = resolve('heic', 'jpg');
+
+    await entry.convert(inputPath, outputPath);
+
+    const detected = await detectInputMime(outputPath);
+    expect(detected.mime).toBe('image/jpeg');
+  });
+
+  it('converts a HEIC fixture to ICO at the requested size', async () => {
+    const inputPath = path.join(import.meta.dirname, '..', 'fixtures', 'sample.heic');
+    const outputPath = path.join(tmpDir, 'output.ico');
+    const entry = resolve('heic', 'ico');
+
+    await entry.convert(inputPath, outputPath, { iconSize: 32 });
+
+    const detected = await detectInputMime(outputPath);
+    expect(detected.mime).toBe('image/x-icon');
+
+    const { decodeIco } = await import('icojs');
+    const [image] = await decodeIco(await fs.readFile(outputPath), 'image/png');
+    expect(image.width).toBe(32);
+  });
+});
+
+describe('heif -> image conversion', () => {
+  it('converts a HEIF-declared fixture to PNG', async () => {
+    const inputPath = path.join(import.meta.dirname, '..', 'fixtures', 'sample.heif');
+    const outputPath = path.join(tmpDir, 'output-from-heif.png');
+    const entry = resolve('heif', 'png');
+
+    await entry.convert(inputPath, outputPath);
+
+    const detected = await detectInputMime(outputPath);
+    expect(detected.mime).toBe('image/png');
+  });
+});