feat(passport-photo): SOTA passport photo maker with compliance validation (#64)

* feat(passport-photo): add passport specs database and tool constants

* feat(passport-photo): add MediaPipe FaceMesh landmark detection script

* feat(passport-photo): add TypeScript bridge for face landmark detection

* feat(passport-photo): add API routes with analyze and generate endpoints

* fix(passport-photo): accept landmarks from request body and fix pixel coordinate conversion

- Generate endpoint now accepts landmarks + imageWidth/imageHeight in request body
  instead of re-running AI face detection (makes generate phase instant)
- Fixed bug where normalized landmark coordinates (0-1) were used directly
  as pixel values in crop computation - now properly multiplied by imgW/imgH
- Fixed same bug in pipeline process function

* feat(passport-photo): add UI component with live preview and compliance overlay

---------

Co-authored-by: stirling-image <stirling-image@users.noreply.github.com>

packages/ai/src/face-landmarks.ts

@@ -0,0 +1,57 @@
+import { unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type ProgressCallback, runPythonWithProgress } from "./bridge.js";
+
+export interface FaceLandmarkPoint {
+  x: number;
+  y: number;
+}
+
+export interface FaceLandmarks {
+  leftEye: FaceLandmarkPoint;
+  rightEye: FaceLandmarkPoint;
+  eyeCenter: FaceLandmarkPoint;
+  chin: FaceLandmarkPoint;
+  forehead: FaceLandmarkPoint;
+  crown: FaceLandmarkPoint;
+  nose: FaceLandmarkPoint;
+  faceCenterX: number;
+}
+
+export interface FaceLandmarksResult {
+  faceDetected: boolean;
+  landmarks: FaceLandmarks | null;
+  imageWidth: number;
+  imageHeight: number;
+}
+
+export async function detectFaceLandmarks(
+  inputBuffer: Buffer,
+  onProgress?: ProgressCallback,
+): Promise<FaceLandmarksResult> {
+  const inputPath = join(tmpdir(), `face_landmarks_${Date.now()}.png`);
+
+  try {
+    await writeFile(inputPath, inputBuffer);
+    const { stdout } = await runPythonWithProgress(
+      "face_landmarks.py",
+      [inputPath, "unused", "{}"],
+      { onProgress },
+    );
+
+    const result = JSON.parse(stdout);
+    if (!result.success) {
+      throw new Error(result.error || "Face landmark detection failed");
+    }
+
+    return {
+      faceDetected: result.faceDetected,
+      landmarks: result.landmarks ?? null,
+      imageWidth: result.imageWidth ?? 0,
+      imageHeight: result.imageHeight ?? 0,
+    };
+  } finally {
+    await unlink(inputPath).catch(() => {});
+  }
+}

packages/ai/src/index.ts

@@ -4,6 +4,8 @@ export { colorize } from "./colorization.js";
 export type { DetectFacesResult, FaceRegion } from "./face-detection.js";
 export { blurFaces, detectFaces } from "./face-detection.js";
 export { enhanceFaces } from "./face-enhancement.js";
+export type { FaceLandmarkPoint, FaceLandmarks, FaceLandmarksResult } from "./face-landmarks.js";
+export { detectFaceLandmarks } from "./face-landmarks.js";
 export { inpaint } from "./inpainting.js";
 export { noiseRemoval } from "./noise-removal.js";
 export { extractText } from "./ocr.js";