feat: add HEIC/HEIF format support for input and output

Add bidirectional HEIC support using system libheif CLI tools (heif-enc/heif-dec)
for HEVC encoding/decoding, since Sharp's bundled libheif only supports AV1.

- HEIC input: all tools now accept iPhone HEIC photos via heif-dec pre-processing
- HEIC output: convert tool produces true HEIC (HEVC) via heif-enc
- Docker: adds libheif-examples package for heif-enc/heif-dec CLI tools
- Tests: full conversion matrix (7x7), unit tests, and Playwright e2e tests
- Docs: updated OpenAPI spec, image-engine docs, getting-started, llms-full.txt

apps/api/src/routes/pipeline.ts

@@ -15,6 +15,7 @@ import { z } from "zod";
 import { db, schema } from "../db/index.js";
 import { validateImageBuffer } from "../lib/file-validation.js";
 import { sanitizeFilename } from "../lib/filename.js";
+import { decodeHeic } from "../lib/heic-converter.js";
 import { createWorkspace } from "../lib/workspace.js";
 import { requireAuth } from "../plugins/auth.js";
 import { getRegisteredToolIds, getToolConfig } from "./tool-factory.js";
@@ -94,6 +95,18 @@ export async function registerPipelineRoutes(app: FastifyInstance): Promise<void
       });
     }
 
+    // Decode HEIC/HEIF input via system heif-dec
+    if (validation.format === "heif") {
+      try {
+        fileBuffer = await decodeHeic(fileBuffer);
+      } catch (err) {
+        return reply.status(422).send({
+          error: "Failed to decode HEIC file. Ensure libheif-examples is installed.",
+          details: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
     // Parse and validate the pipeline definition
     if (!pipelineRaw) {
       return reply.status(400).send({ error: "No pipeline definition provided" });