@visutry/tryon-core 0.2.0

package/README.md

@@ -0,0 +1,58 @@
+# @visutry/tryon-core
+
+Platform-agnostic core of the [VisuTry](https://github.com/franksunye/visutry-tryon-sdk) AR glasses try-on SDK.
+
+It contains no platform (browser / WeChat) code — only the shared foundation:
+shared types, coordinate-system transforms, face semantic mapping, face metrics,
+face-shape scoring, the glasses pose solver, pose smoothing, the quality gate,
+the asset-manifest validator, error helpers, and the i18n message catalogue.
+
+This package is consumed by the platform adapters (`@visutry/tryon-web`,
+`@visutry/tryon-wechat`) and the `@visutry/recommender`. Application code
+usually depends on a platform adapter rather than the core directly.
+
+## Install
+
+```bash
+pnpm add @visutry/tryon-core
+# or
+npm install @visutry/tryon-core
+```
+
+> Requires Node.js >= 18.
+
+## Basic usage
+
+```ts
+import {
+  createSDKError,
+  GlassesPoseSolver,
+  QualityGate,
+  setLocale,
+  t,
+  type FaceShapeResult,
+} from "@visutry/tryon-core";
+
+// Localise user-facing SDK error messages (default locale: "en").
+setLocale("zh-CN");
+
+try {
+  // ...core pipeline helpers run here...
+} catch (err) {
+  // err is a normalised SDKError whose message comes from the i18n catalogue.
+  console.error(t("error.sdk_destroyed"));
+  throw createSDKError("UNKNOWN", t("error.sdk_destroyed"), err);
+}
+```
+
+## API surface
+
+- Types: `VisuTrySDK`, `VisuTrySDKConfig`, `FaceShapeResult`, `FaceMetrics`,
+  `GlassesAssetManifest`, `GlassesItem`, `RecommendationInput`, ...
+- Pipeline: `GlassesPoseSolver`, `PoseSmoother`, `QualityGate`,
+  `FaceShapeScorer`, `PrivacyGuard`.
+- Helpers: `createSDKError`, `ManifestValidator`, `setLocale` / `getLocale` / `t`.
+
+## Full documentation
+
+See the monorepo docs: <https://github.com/franksunye/visutry-tryon-sdk#readme>

package/dist/__fixtures__/faceFixtures.d.ts

@@ -0,0 +1,13 @@
+import type { FaceSemanticPoints, NormalizedFaceResult, GlassesAssetManifest } from "../types/index.js";
+/**
+ * Build a synthetic `FaceSemanticPoints` representing a specific face shape.
+ * Coordinates are in normalized image space (origin top-left, y down).
+ *
+ * The geometry is constructed so each shape exhibits the discriminating
+ * feature ratios the scorer relies on (width/height, jaw/cheek,
+ * jaw/eye-outer, eye-outer/cheek, chin type).
+ */
+export declare function buildSemanticPoints(shape: "oval" | "round" | "square" | "heart" | "diamond" | "oblong"): FaceSemanticPoints;
+export declare function buildFaceResult(semantic: FaceSemanticPoints, overrides?: Partial<NormalizedFaceResult>): NormalizedFaceResult;
+export declare function buildManifest(overrides?: Partial<GlassesAssetManifest>): GlassesAssetManifest;
+//# sourceMappingURL=faceFixtures.d.ts.map

package/dist/__fixtures__/faceFixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"faceFixtures.d.ts","sourceRoot":"","sources":["../../src/__fixtures__/faceFixtures.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EAEpB,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAG3B;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAClE,kBAAkB,CAyHpB;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,kBAAkB,EAC5B,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,oBAAoB,CAqCtB;AAED,wBAAgB,aAAa,CAAC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAAG,oBAAoB,CA4CjG"}

package/dist/__fixtures__/faceFixtures.js

@@ -0,0 +1,206 @@
+import { MEDIAPIPE_SEMANTIC_INDEX_MAP } from "../face/FaceSemanticMapper.js";
+/**
+ * Build a synthetic `FaceSemanticPoints` representing a specific face shape.
+ * Coordinates are in normalized image space (origin top-left, y down).
+ *
+ * The geometry is constructed so each shape exhibits the discriminating
+ * feature ratios the scorer relies on (width/height, jaw/cheek,
+ * jaw/eye-outer, eye-outer/cheek, chin type).
+ */
+export function buildSemanticPoints(shape) {
+    const cx = 0.5;
+    const cy = 0.5;
+    // Eye geometry (symmetric, level by default).
+    const eyeHalfSpan = 0.12; // outer corner half-span → eyeOuterDistance = 0.24
+    const eyeInnerOffset = 0.04;
+    const eyeY = cy - 0.08; // 0.42
+    const leftEyeOuter = { x: cx - eyeHalfSpan, y: eyeY, z: -0.02 };
+    const leftEyeInner = { x: cx - eyeInnerOffset, y: eyeY, z: -0.02 };
+    const rightEyeInner = { x: cx + eyeInnerOffset, y: eyeY, z: -0.02 };
+    const rightEyeOuter = { x: cx + eyeHalfSpan, y: eyeY, z: -0.02 };
+    const leftEyeCenter = { x: (leftEyeOuter.x + leftEyeInner.x) / 2, y: eyeY, z: -0.02 };
+    const rightEyeCenter = { x: (rightEyeInner.x + rightEyeOuter.x) / 2, y: eyeY, z: -0.02 };
+    const eyesCenter = { x: cx, y: eyeY, z: -0.02 };
+    const noseBridge = { x: cx, y: cy - 0.02, z: -0.03 };
+    const noseTip = { x: cx, y: cy + 0.04, z: -0.08 };
+    const foreheadCenter = { x: cx, y: cy - 0.18, z: -0.02 }; // y = 0.32
+    // Per-shape jaw / cheek geometry, tuned to hit target feature ratios.
+    //   faceWidth = cheekboneWidth = 2 * cheekHalf
+    //   jawWidth  = 2 * jawHalf
+    //   faceHeight = chinY - 0.32
+    //   whr = cheekboneWidth / faceHeight
+    //   jcr = jawWidth / cheekboneWidth
+    let cheekHalf = 0.15;
+    let jawHalf = 0.12;
+    let chinY = cy + 0.195; // 0.695
+    let browHalf = 0.07;
+    // visutry additions: face outline, forehead, nose wing half-widths
+    let faceHalf = 0.16; // leftFace/rightFace
+    let foreheadHalf = 0.14; // leftForehead/rightForehead
+    let noseHalf = 0.05; // noseLeft/noseRight
+    switch (shape) {
+        case "oval": // whr~0.80, jcr~0.80, rounded chin
+            cheekHalf = 0.15;
+            jawHalf = 0.12;
+            chinY = 0.695;
+            faceHalf = 0.155;
+            foreheadHalf = 0.135;
+            noseHalf = 0.045;
+            break;
+        case "round": // whr~0.96, jcr~0.91, rounded chin
+            cheekHalf = 0.16;
+            jawHalf = 0.1455;
+            chinY = 0.653;
+            faceHalf = 0.165;
+            foreheadHalf = 0.15;
+            noseHalf = 0.05;
+            break;
+        case "square": // whr~0.85, jcr~0.93, square chin
+            cheekHalf = 0.156;
+            jawHalf = 0.145;
+            chinY = 0.687;
+            faceHalf = 0.158;
+            foreheadHalf = 0.148; // broad forehead (fcr ~0.95, not triangle)
+            noseHalf = 0.048;
+            break;
+        case "heart": // whr~0.80, jcr~0.58, pointed chin, upper wide
+            cheekHalf = 0.12;
+            jawHalf = 0.0695;
+            chinY = 0.62;
+            browHalf = 0.09;
+            faceHalf = 0.125;
+            foreheadHalf = 0.13; // broad forehead (fcr > 0.9)
+            noseHalf = 0.04;
+            break;
+        case "diamond": // whr~0.75, jcr~0.64, pointed chin, cheek dominant
+            cheekHalf = 0.171;
+            jawHalf = 0.11;
+            chinY = 0.777;
+            faceHalf = 0.175;
+            foreheadHalf = 0.12; // narrow forehead (fcr < 0.8)
+            noseHalf = 0.042;
+            break;
+        case "oblong": // whr~0.66, jcr~0.82, rounded chin
+            cheekHalf = 0.1395;
+            jawHalf = 0.115;
+            chinY = 0.743;
+            faceHalf = 0.142;
+            foreheadHalf = 0.13;
+            noseHalf = 0.044;
+            break;
+    }
+    const leftCheek = { x: cx - cheekHalf, y: cy + 0.02, z: -0.03 };
+    const rightCheek = { x: cx + cheekHalf, y: cy + 0.02, z: -0.03 };
+    const leftJaw = { x: cx - jawHalf, y: cy + 0.13, z: -0.02 };
+    const rightJaw = { x: cx + jawHalf, y: cy + 0.13, z: -0.02 };
+    const chin = { x: cx, y: chinY, z: -0.04 };
+    return {
+        leftEyeOuter,
+        leftEyeInner,
+        rightEyeInner,
+        rightEyeOuter,
+        leftEyeCenter,
+        rightEyeCenter,
+        eyesCenter,
+        noseBridge,
+        noseTip,
+        leftBrowCenter: { x: cx - browHalf, y: eyeY - 0.04, z: -0.02 },
+        rightBrowCenter: { x: cx + browHalf, y: eyeY - 0.04, z: -0.02 },
+        foreheadCenter,
+        chin,
+        leftCheek,
+        rightCheek,
+        leftJaw,
+        rightJaw,
+        // visutry additions
+        leftFace: { x: cx - faceHalf, y: cy, z: -0.01 },
+        rightFace: { x: cx + faceHalf, y: cy, z: -0.01 },
+        leftForehead: { x: cx - foreheadHalf, y: cy - 0.14, z: -0.02 },
+        rightForehead: { x: cx + foreheadHalf, y: cy - 0.14, z: -0.02 },
+        noseLeft: { x: cx - noseHalf, y: cy, z: -0.03 },
+        noseRight: { x: cx + noseHalf, y: cy, z: -0.03 },
+    };
+}
+export function buildFaceResult(semantic, overrides = {}) {
+    const raw = [];
+    const maxIndex = Math.max(...Object.values(MEDIAPIPE_SEMANTIC_INDEX_MAP).filter((v) => v !== undefined));
+    for (let i = 0; i <= maxIndex; i++)
+        raw.push({ x: 0.5, y: 0.5, z: 0 });
+    for (const [key, idx] of Object.entries(MEDIAPIPE_SEMANTIC_INDEX_MAP)) {
+        const pt = semantic[key];
+        if (pt && idx !== undefined)
+            raw[idx] = { ...pt };
+    }
+    return {
+        source: "mediapipe",
+        timestamp: Date.now(),
+        landmarks: {
+            raw,
+            normalized: raw,
+            semantic,
+        },
+        pose: {
+            yaw: 0,
+            pitch: 0,
+            roll: 0,
+            confidence: 0.95,
+            ...overrides.pose,
+        },
+        bbox: { x: 0.2, y: 0.15, width: 0.6, height: 0.7, ...overrides.bbox },
+        quality: {
+            confidence: 0.92,
+            faceVisible: true,
+            frontalScore: 0.9,
+            stabilityScore: 0.85,
+            warnings: [],
+            ...overrides.quality,
+        },
+        ...overrides,
+    };
+}
+export function buildManifest(overrides = {}) {
+    return {
+        id: "test-glasses",
+        name: "Test Glasses",
+        modelUrl: "https://example.com/glasses.glb",
+        format: "glb",
+        coordinateSystem: {
+            unit: "millimeter",
+            forwardAxis: "+z",
+            upAxis: "+y",
+        },
+        dimensions: {
+            frameWidthMm: 140,
+            lensWidthMm: 50,
+            lensHeightMm: 40,
+            bridgeWidthMm: 20,
+            templeLengthMm: 140,
+        },
+        anchors: {
+            origin: { x: 0, y: 0, z: 0 },
+            noseBridge: { x: 0, y: 0, z: 0 },
+            leftHinge: { x: -70, y: 0, z: 0 },
+            rightHinge: { x: 70, y: 0, z: 0 },
+        },
+        fitting: {
+            defaultScale: 1,
+            defaultOffset: { x: 0, y: 0, z: 0 },
+            defaultRotation: { x: 0, y: 0, z: 0 },
+            minScale: 0.2,
+            maxScale: 3,
+        },
+        material: {
+            lensOpacity: 0.5,
+            frameRoughness: 0.4,
+            supportsTransparency: true,
+        },
+        metadata: {
+            brand: "VisuTry",
+            shapeCategory: "rectangle",
+            colors: ["black"],
+            tags: ["demo"],
+        },
+        ...overrides,
+    };
+}
+//# sourceMappingURL=faceFixtures.js.map

package/dist/__fixtures__/faceFixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"faceFixtures.js","sourceRoot":"","sources":["../../src/__fixtures__/faceFixtures.ts"],"names":[],"mappings":"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"}

package/dist/adapter/visutry-site.d.ts

@@ -0,0 +1,76 @@
+/**
+ * VisuTry main-site adapter.
+ *
+ * Converts the SDK's honest `FaceShapeResult` into the `landmark-v1`
+ * `FaceGeometryAnalysis` contract consumed by the VisuTry main site
+ * (`src/types/face-analysis.ts`). This is the SINGLE adapter the spec
+ * (§12) requires — the main site must not run a parallel classification
+ * path.
+ *
+ * Key conversions (spec §4.3):
+ * - SDK `faceWidthToHeight` (W/H)  →  site `faceAspectRatio` (H/W), i.e. reciprocal.
+ * - SDK `analysisQuality` (0..1)   →  site `qualityScore` (0..100 integer).
+ * - SDK `matchStrength` (0..1)     →  site `measuredConfidence` (kept as-is;
+ *   the field name is legacy but the value is match strength, NOT a probability).
+ * - SDK `classification: "unknown"` → site `status: "unavailable"`.
+ */
+import type { Classification, FaceMetrics, FaceShapeResult } from "../types/index.js";
+/** The 7 canonical face shapes used by the VisuTry main site. */
+export type SiteFaceShape = "round" | "square" | "oval" | "heart" | "diamond" | "oblong" | "triangle";
+/** Ratio block consumed by the main site's report builder and VLM prompt. */
+export interface SiteFaceGeometryRatios {
+    /** faceHeight / faceWidth — reciprocal of SDK `faceWidthToHeight`. */
+    faceAspectRatio: number;
+    /** cheekboneWidth / faceWidth. */
+    cheekToFaceWidth: number;
+    /** jawWidth / cheekboneWidth — same as SDK `jawCheekRatio`. */
+    jawToCheekWidth: number;
+    /** foreheadWidth / cheekboneWidth — same as SDK `foreheadCheekRatio`. */
+    foreheadToCheekWidth: number;
+    eyeLineTiltDeg: number;
+    symmetryOffset: number;
+    /** noseBridgeWidth / faceWidth — same as SDK `noseBridgeRatio`. */
+    noseBridgeToFaceWidth: number;
+}
+/** The `landmark-v1` geometry analysis contract consumed by the main site. */
+export interface SiteFaceGeometryAnalysis {
+    version: "landmark-v1";
+    status: "measured" | "unavailable";
+    source: "mediapipe-face-landmarker" | "ai-fallback";
+    faceDetected: boolean;
+    faceCount: number;
+    qualityScore: number;
+    measuredShape?: SiteFaceShape;
+    measuredConfidence?: number;
+    ratios?: SiteFaceGeometryRatios;
+    signals: string[];
+    warnings: string[];
+}
+/** Bumped when the mapping logic or mirrored contract changes. */
+export declare const VISUTRY_SITE_ADAPTER_VERSION = "1.0.0";
+/**
+ * Convert an SDK `FaceShapeResult` into the main-site `landmark-v1`
+ * `FaceGeometryAnalysis` contract.
+ *
+ * - `classification: "unknown"` → `status: "unavailable"` (no shape, no ratios).
+ * - `classification: "single" | "mixed"` → `status: "measured"` with ratios.
+ * - `analysisQuality` (0..1) is scaled to `qualityScore` (0..100).
+ * - `faceWidthToHeight` (W/H) is converted to `faceAspectRatio` (H/W).
+ *
+ * The result is fully serialisable and carries no MediaPipe references.
+ */
+export declare function toFaceGeometryAnalysis(result: FaceShapeResult): SiteFaceGeometryAnalysis;
+/**
+ * Build the ratio block from SDK metrics, applying the W/H → H/W conversion.
+ *
+ * Returns `undefined` when the essential raw measurements are missing or
+ * non-finite, so the main site's `normalizeGeometryAnalysis()` will treat
+ * the result as `unavailable`.
+ */
+export declare function buildRatios(metrics: FaceMetrics): SiteFaceGeometryRatios | undefined;
+/**
+ * Lightweight classification-to-status helper for callers that only need the
+ * status flag without building the full analysis object.
+ */
+export declare function classificationToStatus(classification: Classification): "measured" | "unavailable";
+//# sourceMappingURL=visutry-site.d.ts.map

package/dist/adapter/visutry-site.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visutry-site.d.ts","sourceRoot":"","sources":["../../src/adapter/visutry-site.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAEV,cAAc,EACd,WAAW,EAEX,eAAe,EAChB,MAAM,mBAAmB,CAAC;AAU3B,iEAAiE;AACjE,MAAM,MAAM,aAAa,GACrB,OAAO,GACP,QAAQ,GACR,MAAM,GACN,OAAO,GACP,SAAS,GACT,QAAQ,GACR,UAAU,CAAC;AAEf,6EAA6E;AAC7E,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,eAAe,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,gBAAgB,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,8EAA8E;AAC9E,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,UAAU,GAAG,aAAa,CAAC;IACnC,MAAM,EAAE,2BAA2B,GAAG,aAAa,CAAC;IACpD,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAMD,kEAAkE;AAClE,eAAO,MAAM,4BAA4B,UAAU,CAAC;AAqFpD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,eAAe,GACtB,wBAAwB,CAsC1B;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,WAAW,GACnB,sBAAsB,GAAG,SAAS,CAqCpC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,cAAc,GAC7B,UAAU,GAAG,aAAa,CAE5B"}

package/dist/adapter/visutry-site.js

@@ -0,0 +1,172 @@
+/**
+ * VisuTry main-site adapter.
+ *
+ * Converts the SDK's honest `FaceShapeResult` into the `landmark-v1`
+ * `FaceGeometryAnalysis` contract consumed by the VisuTry main site
+ * (`src/types/face-analysis.ts`). This is the SINGLE adapter the spec
+ * (§12) requires — the main site must not run a parallel classification
+ * path.
+ *
+ * Key conversions (spec §4.3):
+ * - SDK `faceWidthToHeight` (W/H)  →  site `faceAspectRatio` (H/W), i.e. reciprocal.
+ * - SDK `analysisQuality` (0..1)   →  site `qualityScore` (0..100 integer).
+ * - SDK `matchStrength` (0..1)     →  site `measuredConfidence` (kept as-is;
+ *   the field name is legacy but the value is match strength, NOT a probability).
+ * - SDK `classification: "unknown"` → site `status: "unavailable"`.
+ */
+// ---------------------------------------------------------------------------
+// Adapter version
+// ---------------------------------------------------------------------------
+/** Bumped when the mapping logic or mirrored contract changes. */
+export const VISUTRY_SITE_ADAPTER_VERSION = "1.0.0";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function round(value, digits = 3) {
+    if (!Number.isFinite(value))
+        return 0;
+    const factor = 10 ** digits;
+    return Math.round(value * factor) / factor;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/** Map SDK FaceShape (7 values) to site SiteFaceShape (same 7 values). */
+function toSiteShape(shape) {
+    if (!shape)
+        return undefined;
+    return shape;
+}
+/** Human-readable warning strings matching the main-site style. */
+const WARNING_MESSAGES = {
+    LOW_QUALITY: "Photo quality is too low for reliable face-shape measurement.",
+    AMBIGUOUS_MATCH: "The face shape is ambiguous — features match multiple shapes similarly.",
+    UNSTABLE_FRAMES: "Frame-to-frame measurements were unstable; try holding still.",
+    EXTREME_EXPRESSION: "An extreme expression was detected; use a neutral face for best results.",
+    MISSING_KEY_POINTS: "Some key facial reference points were missing or unreliable.",
+    NON_FRONTAL: "The face appears turned; use a straight-on photo.",
+    FACE_TOO_SMALL: "The face is too small in the photo. Move closer and keep the full face visible.",
+    MULTIPLE_FACES: "Multiple faces were detected. Use a photo with exactly one face.",
+};
+function mapWarnings(warnings) {
+    return warnings.map((w) => WARNING_MESSAGES[w] ?? w);
+}
+/**
+ * Build human-readable geometry signals from metrics, mirroring the main
+ * site's `buildGeometrySignals()` so the report text stays consistent.
+ */
+function buildSignals(shape, metrics) {
+    const signals = [];
+    if (shape) {
+        const label = shape[0].toUpperCase() + shape.slice(1);
+        signals.push(`${label} shape supported by measured proportions`);
+    }
+    const wth = metrics.faceWidthToHeight;
+    signals.push(wth < 0.83
+        ? "Longer vertical face proportion"
+        : wth > 0.93
+            ? "Compact face length relative to width"
+            : "Balanced face length-to-width ratio");
+    const jcr = metrics.jawCheekRatio;
+    signals.push(jcr >= 0.94
+        ? "Jaw width is close to cheekbone width"
+        : jcr <= 0.78
+            ? "Jawline tapers below the cheekbones"
+            : "Jawline has moderate taper");
+    const fcr = metrics.foreheadCheekRatio ?? 0;
+    signals.push(fcr >= 0.9
+        ? "Forehead width is close to cheekbone width"
+        : "Cheekbones read wider than the upper face");
+    return signals;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Convert an SDK `FaceShapeResult` into the main-site `landmark-v1`
+ * `FaceGeometryAnalysis` contract.
+ *
+ * - `classification: "unknown"` → `status: "unavailable"` (no shape, no ratios).
+ * - `classification: "single" | "mixed"` → `status: "measured"` with ratios.
+ * - `analysisQuality` (0..1) is scaled to `qualityScore` (0..100).
+ * - `faceWidthToHeight` (W/H) is converted to `faceAspectRatio` (H/W).
+ *
+ * The result is fully serialisable and carries no MediaPipe references.
+ */
+export function toFaceGeometryAnalysis(result) {
+    const { classification, metrics, warnings, analysisQuality, matchStrength } = result;
+    const isUnavailable = classification === "unknown";
+    // qualityScore: 0..1 → 0..100 integer, clamped.
+    const qualityScore = Math.round(clamp(analysisQuality * 100, 0, 100));
+    if (isUnavailable) {
+        return {
+            version: "landmark-v1",
+            status: "unavailable",
+            source: "mediapipe-face-landmarker",
+            faceDetected: true,
+            faceCount: 1,
+            qualityScore,
+            signals: [],
+            warnings: mapWarnings(warnings),
+        };
+    }
+    const ratios = buildRatios(metrics);
+    const measuredShape = toSiteShape(result.primary);
+    return {
+        version: "landmark-v1",
+        status: "measured",
+        source: "mediapipe-face-landmarker",
+        faceDetected: true,
+        faceCount: 1,
+        qualityScore,
+        measuredShape,
+        measuredConfidence: round(matchStrength, 2),
+        ratios,
+        signals: buildSignals(measuredShape, metrics),
+        warnings: mapWarnings(warnings),
+    };
+}
+/**
+ * Build the ratio block from SDK metrics, applying the W/H → H/W conversion.
+ *
+ * Returns `undefined` when the essential raw measurements are missing or
+ * non-finite, so the main site's `normalizeGeometryAnalysis()` will treat
+ * the result as `unavailable`.
+ */
+export function buildRatios(metrics) {
+    const { faceWidth, faceHeight, cheekboneWidth } = metrics;
+    if (!Number.isFinite(faceWidth) ||
+        !Number.isFinite(faceHeight) ||
+        !Number.isFinite(cheekboneWidth) ||
+        faceWidth <= 0 ||
+        faceHeight <= 0 ||
+        cheekboneWidth <= 0) {
+        return undefined;
+    }
+    const faceAspectRatio = round(faceHeight / faceWidth); // H/W — reciprocal
+    const cheekToFaceWidth = round(cheekboneWidth / faceWidth);
+    const jawToCheekWidth = round(metrics.jawCheekRatio);
+    const foreheadToCheekWidth = metrics.foreheadCheekRatio != null && Number.isFinite(metrics.foreheadCheekRatio)
+        ? round(metrics.foreheadCheekRatio)
+        : round((metrics.foreheadWidth ?? 0) / cheekboneWidth);
+    const noseBridgeToFaceWidth = metrics.noseBridgeRatio != null && Number.isFinite(metrics.noseBridgeRatio)
+        ? round(metrics.noseBridgeRatio)
+        : 0;
+    return {
+        faceAspectRatio,
+        cheekToFaceWidth,
+        jawToCheekWidth,
+        foreheadToCheekWidth,
+        eyeLineTiltDeg: round(metrics.eyeLineTiltDeg ?? 0, 1),
+        symmetryOffset: round(metrics.symmetryOffset ?? 0),
+        noseBridgeToFaceWidth,
+    };
+}
+/**
+ * Lightweight classification-to-status helper for callers that only need the
+ * status flag without building the full analysis object.
+ */
+export function classificationToStatus(classification) {
+    return classification === "unknown" ? "unavailable" : "measured";
+}
+//# sourceMappingURL=visutry-site.js.map

package/dist/adapter/visutry-site.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visutry-site.js","sourceRoot":"","sources":["../../src/adapter/visutry-site.ts"],"names":[],"mappings":"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"}

package/dist/analytics.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Analytics event types for face-shape analysis (spec §12).
+ *
+ * The host application wires these events into its analytics pipeline
+ * (e.g. GA4). Events carry algorithm metadata and outcome signals only —
+ * NEVER photos, base64, landmarks, or any reversible biometric data.
+ */
+import type { AnalysisWarning, Classification, FaceShape } from "./types/index.js";
+export type FaceAnalysisEventType = "start" | "complete" | "failed" | "abstained" | "retry";
+/** Common fields present on every analytics event. */
+interface AnalyticsEventBase {
+    /** Event type. */
+    type: FaceAnalysisEventType;
+    /** UTC epoch milliseconds. */
+    timestamp: number;
+    /** Input method. */
+    inputKind: "image" | "video";
+    /** Classification engine that produced (or attempted) the result. */
+    engine: "rules" | "logreg";
+    /** Algorithm version from `FaceShapeResult.model.version`. */
+    algorithmVersion: string;
+    /** SDK package version for audit / rollback tracking. */
+    sdkVersion?: string;
+}
+/** Emitted when an analysis session begins. */
+export interface FaceAnalysisStartEvent extends AnalyticsEventBase {
+    type: "start";
+}
+/** Emitted when analysis completes with a usable result. */
+export interface FaceAnalysisCompleteEvent extends AnalyticsEventBase {
+    type: "complete";
+    classification: Classification;
+    primary?: FaceShape;
+    secondary?: FaceShape;
+    /** 0..1 — analysis quality (NOT a probability). */
+    analysisQuality: number;
+    /** 0..1 — match strength of the primary shape. */
+    matchStrength: number;
+    /** Wall-clock duration from start to complete, in milliseconds. */
+    durationMs: number;
+    warnings: AnalysisWarning[];
+}
+/** Emitted when analysis fails with an error (no result produced). */
+export interface FaceAnalysisFailedEvent extends AnalyticsEventBase {
+    type: "failed";
+    /** Wall-clock duration from start to failure. */
+    durationMs: number;
+    /** SDK error code. */
+    errorCode: string;
+    /** Short, non-PII error message. */
+    errorMessage: string;
+}
+/** Emitted when the SDK abstains (`classification: "unknown"`). */
+export interface FaceAnalysisAbstainedEvent extends AnalyticsEventBase {
+    type: "abstained";
+    /** 0..1 — analysis quality at the point of abstention. */
+    analysisQuality: number;
+    /** Wall-clock duration from start to abstention. */
+    durationMs: number;
+    warnings: AnalysisWarning[];
+}
+/** Emitted when the user retries after a failure or abstention. */
+export interface FaceAnalysisRetryEvent extends AnalyticsEventBase {
+    type: "retry";
+    /** The event type that preceded this retry. */
+    previousOutcome: "failed" | "abstained";
+}
+export type FaceAnalysisAnalyticsEvent = FaceAnalysisStartEvent | FaceAnalysisCompleteEvent | FaceAnalysisFailedEvent | FaceAnalysisAbstainedEvent | FaceAnalysisRetryEvent;
+/**
+ * Callback that receives analytics events. The host application implements
+ * this to forward events to GA4, Axiom, etc.
+ */
+export type AnalyticsReporter = (event: FaceAnalysisAnalyticsEvent) => void;
+/**
+ * Create a no-op reporter (default when analytics is disabled).
+ * Useful as a safe default in tests and when `privacy.allowAnalytics` is false.
+ */
+export declare function noopReporter(): AnalyticsReporter;
+/**
+ * Create a reporter that buffers events and flushes them via the provided
+ * sink. Useful for batching in production.
+ */
+export declare function createBufferedReporter(sink: (events: FaceAnalysisAnalyticsEvent[]) => void, flushIntervalMs?: number): {
+    reporter: AnalyticsReporter;
+    flush: () => void;
+    destroy: () => void;
+};
+export {};
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAMnF,MAAM,MAAM,qBAAqB,GAC7B,OAAO,GACP,UAAU,GACV,QAAQ,GACR,WAAW,GACX,OAAO,CAAC;AAEZ,sDAAsD;AACtD,UAAU,kBAAkB;IAC1B,kBAAkB;IAClB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC;IAC7B,qEAAqE;IACrE,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC3B,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+CAA+C;AAC/C,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,IAAI,EAAE,OAAO,CAAC;CACf;AAED,4DAA4D;AAC5D,MAAM,WAAW,yBAA0B,SAAQ,kBAAkB;IACnE,IAAI,EAAE,UAAU,CAAC;IACjB,cAAc,EAAE,cAAc,CAAC;IAC/B,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,mDAAmD;IACnD,eAAe,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,sEAAsE;AACtE,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB;IACjE,IAAI,EAAE,QAAQ,CAAC;IACf,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,mEAAmE;AACnE,MAAM,WAAW,0BAA2B,SAAQ,kBAAkB;IACpE,IAAI,EAAE,WAAW,CAAC;IAClB,0DAA0D;IAC1D,eAAe,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,mEAAmE;AACnE,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,IAAI,EAAE,OAAO,CAAC;IACd,+CAA+C;IAC/C,eAAe,EAAE,QAAQ,GAAG,WAAW,CAAC;CACzC;AAED,MAAM,MAAM,0BAA0B,GAClC,sBAAsB,GACtB,yBAAyB,GACzB,uBAAuB,GACvB,0BAA0B,GAC1B,sBAAsB,CAAC;AAM3B;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAC;AAE5E;;;GAGG;AACH,wBAAgB,YAAY,IAAI,iBAAiB,CAIhD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,CAAC,MAAM,EAAE,0BAA0B,EAAE,KAAK,IAAI,EACpD,eAAe,SAAO,GACrB;IAAE,QAAQ,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CA4BzE"}