@visutry/tryon-core 0.2.0

package/dist/i18n/index.js

@@ -0,0 +1,91 @@
+/**
+ * VisuTry SDK — lightweight i18n for user-facing error messages.
+ *
+ * The SDK keeps all hard-coded user-facing strings behind the `t()` lookup so
+ * that platform adapters (web / wechat) and host applications can localise the
+ * error messages surfaced to end users. The message catalogue is intentionally
+ * small: it only covers the canonical SDK error strings emitted via
+ * `createSDKError`. Callers can switch the active locale at runtime with
+ * `setLocale()`; unknown keys fall back to English, then to the key itself.
+ */
+const messages = {
+    "en": {
+        "error.camera_not_initialized": "Camera is not initialized.",
+        "error.camera_permission_denied": "Camera permission denied.",
+        "error.camera_not_available": "No suitable camera device found.",
+        "error.camera_unsupported": "getUserMedia is not available on this platform.",
+        "error.tracker_init_failed": "Failed to initialize face tracker.",
+        "error.tracker_not_initialized": "Face tracker is not initialized.",
+        "error.tracker_detect_failed": "Face detection failed.",
+        "error.renderer_init_failed": "Failed to initialize renderer.",
+        "error.glasses_load_failed": "Failed to load glasses model.",
+        "error.snapshot_failed": "Snapshot capture failed.",
+        "error.snapshot_disabled": "Snapshot export is disabled by privacy policy.",
+        "error.analysis_timeout": "Face analysis timed out waiting for quality frames.",
+        "error.analysis_in_progress": "Face shape analysis already in progress.",
+        "error.sdk_destroyed": "SDK has been destroyed.",
+        "error.renderer_disposed": "Renderer has been disposed.",
+    },
+    "zh-CN": {
+        "error.camera_not_initialized": "摄像头未初始化。",
+        "error.camera_permission_denied": "摄像头权限被拒绝。",
+        "error.camera_not_available": "未找到合适的摄像头设备。",
+        "error.camera_unsupported": "当前平台不支持摄像头功能。",
+        "error.tracker_init_failed": "人脸追踪器初始化失败。",
+        "error.tracker_not_initialized": "人脸追踪器未初始化。",
+        "error.tracker_detect_failed": "人脸检测失败。",
+        "error.renderer_init_failed": "渲染器初始化失败。",
+        "error.glasses_load_failed": "眼镜模型加载失败。",
+        "error.snapshot_failed": "截图失败。",
+        "error.snapshot_disabled": "隐私策略已禁用截图导出。",
+        "error.analysis_timeout": "脸型分析超时，未获取到足够的高质量帧。",
+        "error.analysis_in_progress": "脸型分析正在进行中。",
+        "error.sdk_destroyed": "SDK 已被销毁。",
+        "error.renderer_disposed": "渲染器已被销毁。",
+    },
+    "ja": {
+        "error.camera_not_initialized": "カメラが初期化されていません。",
+        "error.camera_permission_denied": "カメラの権限が拒否されました。",
+        "error.camera_not_available": "適切なカメラデバイスが見つかりません。",
+        "error.camera_unsupported": "このプラットフォームではカメラ機能を使用できません。",
+        "error.tracker_init_failed": "顔トラッカーの初期化に失敗しました。",
+        "error.tracker_not_initialized": "顔トラッカーが初期化されていません。",
+        "error.tracker_detect_failed": "顔検出に失敗しました。",
+        "error.renderer_init_failed": "レンダラーの初期化に失敗しました。",
+        "error.glasses_load_failed": "眼鏡モデルの読み込みに失敗しました。",
+        "error.snapshot_failed": "スクリーンショットの取得に失敗しました。",
+        "error.snapshot_disabled": "プライバシーポリシーによりスクリーンショットエクスポートが無効です。",
+        "error.analysis_timeout": "顔分析がタイムアウトしました。",
+        "error.analysis_in_progress": "顔分析は既に進行中です。",
+        "error.sdk_destroyed": "SDKは破棄されました。",
+        "error.renderer_disposed": "レンダラーは破棄されました。",
+    },
+    "ko": {
+        "error.camera_not_initialized": "카메라가 초기화되지 않았습니다.",
+        "error.camera_permission_denied": "카메라 권한이 거부되었습니다.",
+        "error.camera_not_available": "적합한 카메라 장치를 찾을 수 없습니다.",
+        "error.camera_unsupported": "이 플랫폼에서는 카메라 기능을 사용할 수 없습니다.",
+        "error.tracker_init_failed": "얼굴 트래커 초기화에 실패했습니다.",
+        "error.tracker_not_initialized": "얼굴 트래커가 초기화되지 않았습니다.",
+        "error.tracker_detect_failed": "얼굴 감지에 실패했습니다.",
+        "error.renderer_init_failed": "렌더러 초기화에 실패했습니다.",
+        "error.glasses_load_failed": "안경 모델 로드에 실패했습니다.",
+        "error.snapshot_failed": "스냅샷 캡처에 실패했습니다.",
+        "error.snapshot_disabled": "개인정보 보호 정책으로 인해 스냅샷 내보내기가 비활성화되었습니다.",
+        "error.analysis_timeout": "얼굴 분석 시간이 초과되었습니다.",
+        "error.analysis_in_progress": "얼굴 분석이 이미 진행 중입니다.",
+        "error.sdk_destroyed": "SDK가 폐기되었습니다.",
+        "error.renderer_disposed": "렌더러가 폐기되었습니다.",
+    },
+};
+let currentLocale = "en";
+export function setLocale(locale) {
+    currentLocale = locale;
+}
+export function getLocale() {
+    return currentLocale;
+}
+export function t(key) {
+    return messages[currentLocale]?.[key] ?? messages["en"][key] ?? key;
+}
+//# sourceMappingURL=index.js.map

package/dist/i18n/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/i18n/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,QAAQ,GAA2C;IACvD,IAAI,EAAE;QACJ,8BAA8B,EAAE,4BAA4B;QAC5D,gCAAgC,EAAE,2BAA2B;QAC7D,4BAA4B,EAAE,kCAAkC;QAChE,0BAA0B,EAAE,iDAAiD;QAC7E,2BAA2B,EAAE,oCAAoC;QACjE,+BAA+B,EAAE,kCAAkC;QACnE,6BAA6B,EAAE,wBAAwB;QACvD,4BAA4B,EAAE,gCAAgC;QAC9D,2BAA2B,EAAE,+BAA+B;QAC5D,uBAAuB,EAAE,0BAA0B;QACnD,yBAAyB,EAAE,gDAAgD;QAC3E,wBAAwB,EAAE,qDAAqD;QAC/E,4BAA4B,EAAE,0CAA0C;QACxE,qBAAqB,EAAE,yBAAyB;QAChD,yBAAyB,EAAE,6BAA6B;KACzD;IACD,OAAO,EAAE;QACP,8BAA8B,EAAE,UAAU;QAC1C,gCAAgC,EAAE,WAAW;QAC7C,4BAA4B,EAAE,cAAc;QAC5C,0BAA0B,EAAE,eAAe;QAC3C,2BAA2B,EAAE,aAAa;QAC1C,+BAA+B,EAAE,YAAY;QAC7C,6BAA6B,EAAE,SAAS;QACxC,4BAA4B,EAAE,WAAW;QACzC,2BAA2B,EAAE,WAAW;QACxC,uBAAuB,EAAE,OAAO;QAChC,yBAAyB,EAAE,cAAc;QACzC,wBAAwB,EAAE,qBAAqB;QAC/C,4BAA4B,EAAE,YAAY;QAC1C,qBAAqB,EAAE,WAAW;QAClC,yBAAyB,EAAE,UAAU;KACtC;IACD,IAAI,EAAE;QACJ,8BAA8B,EAAE,iBAAiB;QACjD,gCAAgC,EAAE,iBAAiB;QACnD,4BAA4B,EAAE,qBAAqB;QACnD,0BAA0B,EAAE,4BAA4B;QACxD,2BAA2B,EAAE,oBAAoB;QACjD,+BAA+B,EAAE,oBAAoB;QACrD,6BAA6B,EAAE,aAAa;QAC5C,4BAA4B,EAAE,mBAAmB;QACjD,2BAA2B,EAAE,oBAAoB;QACjD,uBAAuB,EAAE,sBAAsB;QAC/C,yBAAyB,EAAE,oCAAoC;QAC/D,wBAAwB,EAAE,iBAAiB;QAC3C,4BAA4B,EAAE,cAAc;QAC5C,qBAAqB,EAAE,cAAc;QACrC,yBAAyB,EAAE,gBAAgB;KAC5C;IACD,IAAI,EAAE;QACJ,8BAA8B,EAAE,mBAAmB;QACnD,gCAAgC,EAAE,kBAAkB;QACpD,4BAA4B,EAAE,wBAAwB;QACtD,0BAA0B,EAAE,8BAA8B;QAC1D,2BAA2B,EAAE,qBAAqB;QAClD,+BAA+B,EAAE,sBAAsB;QACvD,6BAA6B,EAAE,gBAAgB;QAC/C,4BAA4B,EAAE,kBAAkB;QAChD,2BAA2B,EAAE,mBAAmB;QAChD,uBAAuB,EAAE,iBAAiB;QAC1C,yBAAyB,EAAE,sCAAsC;QACjE,wBAAwB,EAAE,oBAAoB;QAC9C,4BAA4B,EAAE,oBAAoB;QAClD,qBAAqB,EAAE,eAAe;QACtC,yBAAyB,EAAE,eAAe;KAC3C;CACF,CAAC;AAEF,IAAI,aAAa,GAAW,IAAI,CAAC;AAEjC,MAAM,UAAU,SAAS,CAAC,MAAc;IACtC,aAAa,GAAG,MAAM,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,CAAC,CAAC,GAAW;IAC3B,OAAO,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;AACtE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @visutry/tryon-core
+ *
+ * Platform-agnostic core of the VisuTry Face Geometry & AR Glasses Try-On SDK.
+ * No DOM, MediaPipe, Three.js or WeChat dependencies live here.
+ */
+export * from "./types/index.js";
+export { setLocale, getLocale, t } from "./i18n/index.js";
+export type { Locale } from "./i18n/index.js";
+export { CoordinateSystem } from "./coordinate/CoordinateSystem.js";
+export { FaceSemanticMapper, MEDIAPIPE_SEMANTIC_INDEX_MAP, } from "./face/FaceSemanticMapper.js";
+export type { SemanticIndexMap, FaceSemanticMapperOptions } from "./face/FaceSemanticMapper.js";
+export { FaceMetricsCalculator } from "./face/FaceMetricsCalculator.js";
+export { FaceShapeScorer, FACE_SHAPE_SCORER_VERSION } from "./face/FaceShapeScorer.js";
+export { GlassesPoseSolver, DEFAULT_FITTING_CONFIG, MM_TO_RENDER_WORLD, decomposeMatrixToEuler, degreesToRadians, } from "./pose/GlassesPoseSolver.js";
+export { PoseSmoother, DEFAULT_POSE_SMOOTHING_CONFIG, } from "./smoothing/PoseSmoothing.js";
+export { QualityGate } from "./quality/QualityGate.js";
+export { PrivacyGuard, DEFAULT_PRIVACY_CONFIG } from "./privacy/PrivacyGuard.js";
+export { ManifestValidator, } from "./manifest/ManifestValidator.js";
+export type { ManifestValidationIssue, ManifestValidationResult, } from "./manifest/ManifestValidator.js";
+export { createSDKError } from "./utils/errors.js";
+export * as math from "./utils/math.js";
+export { clamp, clamp01, clampAngle, lerp, lerpVec3, distance2D, distance3D, mean, median, trimmedMean, standardDeviation, softmax, minMaxNormalize, mapRange, DEG2RAD, RAD2DEG, } from "./utils/math.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAC1D,YAAY,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAG9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAGpE,OAAO,EACL,kBAAkB,EAClB,4BAA4B,GAC7B,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAGhG,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAGxE,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAGvF,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,YAAY,EACZ,6BAA6B,GAC9B,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAGjF,OAAO,EACL,iBAAiB,GAClB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EACV,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,EACL,KAAK,EACL,OAAO,EACP,UAAU,EACV,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,UAAU,EACV,IAAI,EACJ,MAAM,EACN,WAAW,EACX,iBAAiB,EACjB,OAAO,EACP,eAAe,EACf,QAAQ,EACR,OAAO,EACP,OAAO,GACR,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * @visutry/tryon-core
+ *
+ * Platform-agnostic core of the VisuTry Face Geometry & AR Glasses Try-On SDK.
+ * No DOM, MediaPipe, Three.js or WeChat dependencies live here.
+ */
+// Types
+export * from "./types/index.js";
+// i18n (user-facing error message localisation)
+export { setLocale, getLocale, t } from "./i18n/index.js";
+// Coordinate system
+export { CoordinateSystem } from "./coordinate/CoordinateSystem.js";
+// Face semantic mapping
+export { FaceSemanticMapper, MEDIAPIPE_SEMANTIC_INDEX_MAP, } from "./face/FaceSemanticMapper.js";
+// Face metrics
+export { FaceMetricsCalculator } from "./face/FaceMetricsCalculator.js";
+// Face shape scoring
+export { FaceShapeScorer, FACE_SHAPE_SCORER_VERSION } from "./face/FaceShapeScorer.js";
+// Glasses pose solver
+export { GlassesPoseSolver, DEFAULT_FITTING_CONFIG, MM_TO_RENDER_WORLD, decomposeMatrixToEuler, degreesToRadians, } from "./pose/GlassesPoseSolver.js";
+// Pose smoothing
+export { PoseSmoother, DEFAULT_POSE_SMOOTHING_CONFIG, } from "./smoothing/PoseSmoothing.js";
+// Quality gate
+export { QualityGate } from "./quality/QualityGate.js";
+// Privacy
+export { PrivacyGuard, DEFAULT_PRIVACY_CONFIG } from "./privacy/PrivacyGuard.js";
+// Manifest validation
+export { ManifestValidator, } from "./manifest/ManifestValidator.js";
+// Utilities
+export { createSDKError } from "./utils/errors.js";
+export * as math from "./utils/math.js";
+export { clamp, clamp01, clampAngle, lerp, lerpVec3, distance2D, distance3D, mean, median, trimmedMean, standardDeviation, softmax, minMaxNormalize, mapRange, DEG2RAD, RAD2DEG, } from "./utils/math.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,QAAQ;AACR,cAAc,kBAAkB,CAAC;AAEjC,gDAAgD;AAChD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAG1D,oBAAoB;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEpE,wBAAwB;AACxB,OAAO,EACL,kBAAkB,EAClB,4BAA4B,GAC7B,MAAM,8BAA8B,CAAC;AAGtC,eAAe;AACf,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAExE,qBAAqB;AACrB,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAEvF,sBAAsB;AACtB,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AAErC,iBAAiB;AACjB,OAAO,EACL,YAAY,EACZ,6BAA6B,GAC9B,MAAM,8BAA8B,CAAC;AAEtC,eAAe;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,UAAU;AACV,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAEjF,sBAAsB;AACtB,OAAO,EACL,iBAAiB,GAClB,MAAM,iCAAiC,CAAC;AAMzC,YAAY;AACZ,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,EACL,KAAK,EACL,OAAO,EACP,UAAU,EACV,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,UAAU,EACV,IAAI,EACJ,MAAM,EACN,WAAW,EACX,iBAAiB,EACjB,OAAO,EACP,eAAe,EACf,QAAQ,EACR,OAAO,EACP,OAAO,GACR,MAAM,iBAAiB,CAAC"}

package/dist/manifest/ManifestValidator.d.ts

@@ -0,0 +1,23 @@
+import type { GlassesAssetManifest } from "../types/index.js";
+export interface ManifestValidationIssue {
+    field: string;
+    message: string;
+    severity: "error" | "warning";
+}
+export interface ManifestValidationResult {
+    valid: boolean;
+    issues: ManifestValidationIssue[];
+}
+/**
+ * Validates a `GlassesAssetManifest` against the SDK model standard (spec §14).
+ *
+ * The validator is used at glasses-load time to fail fast on malformed assets,
+ * and by the eval tooling to keep the official demo models compliant.
+ */
+export declare class ManifestValidator {
+    validate(manifest: unknown): ManifestValidationResult;
+    /** Throw if invalid — convenience for load-time enforcement. */
+    validateOrThrow(manifest: unknown): asserts manifest is GlassesAssetManifest;
+    private isVector3;
+}
+//# sourceMappingURL=ManifestValidator.d.ts.map

package/dist/manifest/ManifestValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ManifestValidator.d.ts","sourceRoot":"","sources":["../../src/manifest/ManifestValidator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,uBAAuB,EAAE,CAAC;CACnC;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,wBAAwB;IAgHrD,gEAAgE;IAChE,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,IAAI,oBAAoB;IAU5E,OAAO,CAAC,SAAS;CASlB"}

package/dist/manifest/ManifestValidator.js

@@ -0,0 +1,129 @@
+/**
+ * Validates a `GlassesAssetManifest` against the SDK model standard (spec §14).
+ *
+ * The validator is used at glasses-load time to fail fast on malformed assets,
+ * and by the eval tooling to keep the official demo models compliant.
+ */
+export class ManifestValidator {
+    validate(manifest) {
+        const issues = [];
+        // --- Structural type guard -------------------------------------------------
+        if (manifest === null || typeof manifest !== "object") {
+            return {
+                valid: false,
+                issues: [{ field: "(root)", message: "manifest must be a non-null object", severity: "error" }],
+            };
+        }
+        const m = manifest;
+        // --- Top-level identity ----------------------------------------------
+        if (typeof m.id !== "string" || m.id.length === 0) {
+            issues.push({ field: "id", message: "id must be a non-empty string", severity: "error" });
+        }
+        if (typeof m.name !== "string" || m.name.length === 0) {
+            issues.push({ field: "name", message: "name must be a non-empty string", severity: "error" });
+        }
+        if (typeof m.modelUrl !== "string" || m.modelUrl.length === 0) {
+            issues.push({ field: "modelUrl", message: "modelUrl must be a non-empty string", severity: "error" });
+        }
+        if (typeof m.format !== "string" || (m.format !== "glb" && m.format !== "gltf")) {
+            issues.push({ field: "format", message: "format must be 'glb' or 'gltf'", severity: "error" });
+        }
+        // --- Coordinate system ------------------------------------------------
+        const cs = m.coordinateSystem;
+        if (!cs || typeof cs !== "object") {
+            issues.push({ field: "coordinateSystem", message: "coordinateSystem is required and must be an object", severity: "error" });
+        }
+        else {
+            if (!["millimeter", "centimeter", "meter"].includes(cs.unit ?? "")) {
+                issues.push({ field: "coordinateSystem.unit", message: "unit must be millimeter|centimeter|meter", severity: "error" });
+            }
+            if (cs.forwardAxis !== "+z" && cs.forwardAxis !== "-z") {
+                issues.push({ field: "coordinateSystem.forwardAxis", message: "forwardAxis must be '+z' or '-z'", severity: "error" });
+            }
+            if (cs.upAxis !== "+y" && cs.upAxis !== "+z") {
+                issues.push({ field: "coordinateSystem.upAxis", message: "upAxis must be '+y' or '+z'", severity: "error" });
+            }
+        }
+        // --- Dimensions -------------------------------------------------------
+        const dims = m.dimensions;
+        if (!dims) {
+            issues.push({ field: "dimensions", message: "dimensions is required", severity: "error" });
+        }
+        else {
+            if (typeof dims.frameWidthMm !== "number" || dims.frameWidthMm <= 0) {
+                issues.push({ field: "dimensions.frameWidthMm", message: "frameWidthMm must be a positive number", severity: "error" });
+            }
+            else if (dims.frameWidthMm < 80 || dims.frameWidthMm > 200) {
+                issues.push({
+                    field: "dimensions.frameWidthMm",
+                    message: "frameWidthMm outside typical range 80–200mm — verify model units",
+                    severity: "warning",
+                });
+            }
+            if (dims.lensWidthMm !== undefined && (dims.lensWidthMm <= 0 || dims.lensWidthMm > 80)) {
+                issues.push({ field: "dimensions.lensWidthMm", message: "lensWidthMm should be in (0, 80]", severity: "warning" });
+            }
+        }
+        // --- Anchors ----------------------------------------------------------
+        const anchors = m.anchors;
+        if (!anchors) {
+            issues.push({ field: "anchors", message: "anchors is required", severity: "error" });
+        }
+        else {
+            if (!this.isVector3(anchors.origin)) {
+                issues.push({ field: "anchors.origin", message: "origin must be a Vector3", severity: "error" });
+            }
+            if (!this.isVector3(anchors.noseBridge)) {
+                issues.push({ field: "anchors.noseBridge", message: "noseBridge must be a Vector3", severity: "error" });
+            }
+        }
+        // --- Fitting ----------------------------------------------------------
+        const fitting = m.fitting;
+        if (!fitting) {
+            issues.push({ field: "fitting", message: "fitting is required", severity: "error" });
+        }
+        else {
+            if (typeof fitting.defaultScale !== "number" || fitting.defaultScale <= 0) {
+                issues.push({ field: "fitting.defaultScale", message: "defaultScale must be a positive number", severity: "error" });
+            }
+            if (!this.isVector3(fitting.defaultOffset)) {
+                issues.push({ field: "fitting.defaultOffset", message: "defaultOffset must be a Vector3", severity: "error" });
+            }
+            if (!this.isVector3(fitting.defaultRotation)) {
+                issues.push({ field: "fitting.defaultRotation", message: "defaultRotation must be a Vector3", severity: "error" });
+            }
+            if (fitting.minScale !== undefined &&
+                fitting.maxScale !== undefined &&
+                fitting.minScale > fitting.maxScale) {
+                issues.push({ field: "fitting.minScale", message: "minScale must be <= maxScale", severity: "error" });
+            }
+        }
+        // --- Material (optional but type-checked) ----------------------------
+        if (m.material) {
+            if (m.material.lensOpacity !== undefined && (m.material.lensOpacity < 0 || m.material.lensOpacity > 1)) {
+                issues.push({ field: "material.lensOpacity", message: "lensOpacity must be in [0,1]", severity: "error" });
+            }
+            if (m.material.frameRoughness !== undefined && (m.material.frameRoughness < 0 || m.material.frameRoughness > 1)) {
+                issues.push({ field: "material.frameRoughness", message: "frameRoughness must be in [0,1]", severity: "error" });
+            }
+        }
+        const valid = issues.filter((i) => i.severity === "error").length === 0;
+        return { valid, issues };
+    }
+    /** Throw if invalid — convenience for load-time enforcement. */
+    validateOrThrow(manifest) {
+        const result = this.validate(manifest);
+        if (!result.valid) {
+            const errors = result.issues.filter((i) => i.severity === "error");
+            throw new Error(`Invalid glasses manifest: ${errors.map((e) => `${e.field} (${e.message})`).join("; ")}`);
+        }
+    }
+    isVector3(v) {
+        return (!!v &&
+            typeof v === "object" &&
+            typeof v.x === "number" &&
+            typeof v.y === "number" &&
+            typeof v.z === "number");
+    }
+}
+//# sourceMappingURL=ManifestValidator.js.map

package/dist/manifest/ManifestValidator.js.map

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

package/dist/pose/GlassesPoseSolver.d.ts

@@ -0,0 +1,64 @@
+import type { GlassesFittingConfig, GlassesPose, GlassesPoseSolverInput } from "../types/index.js";
+/**
+ * Calibration constant: maps millimetres to render-world units.
+ *
+ * The render-world is defined so that the full frame height maps to 1.0 unit and
+ * the x-axis is scaled by aspect ratio. We assume a representative adult face
+ * height of ~200 mm, hence 1 mm ≈ 0.005 render-world units. This is a documented
+ * calibration anchor; the manifest `defaultScale` and `GlassesFittingConfig`
+ * fine-tune per model.
+ */
+export declare const MM_TO_RENDER_WORLD: number;
+/** Default fitting configuration. */
+export declare const DEFAULT_FITTING_CONFIG: GlassesFittingConfig;
+/**
+ * Converts a normalized `NormalizedFaceResult` into a `GlassesPose` that the
+ * renderer can apply directly to a glasses model.
+ *
+ * Coordinate contract:
+ *  - Face landmarks arrive in *normalized-image* space (origin top-left, y down).
+ *  - The solver converts them to *render-world* space (origin centre, y up,
+ *    x scaled by aspect ratio, 1.0 unit = frame height) before computing.
+ *  - The renderer must use the same render-world convention so that
+ *    `GlassesPose.position` lands the model on the face.
+ *
+ * Solve pipeline (spec §15.5):
+ *   1. eye centre line → roll
+ *   2. outer-eye distance → scale
+ *   3. noseBridge / eyeLine → position
+ *   4. yaw / pitch (or matrix) → 3D rotation
+ *   5. manifest defaults + config offsets applied
+ */
+export declare class GlassesPoseSolver {
+    /**
+     * Solve the glasses pose for a single face result.
+     */
+    solve(input: GlassesPoseSolverInput): GlassesPose;
+    private computeRoll;
+    private computeScale;
+    /**
+     * The face-side width in render-world units used to fit the glasses. The model
+     * frame width should match the outer-eye span, so we use that directly.
+     */
+    private fitMetricRW;
+    private modelFrameWidthMm;
+    private computePosition;
+    private computeRotation;
+    private applyPositionOffsets;
+    private applyRotationOffsets;
+    private clampScale;
+    private assessVisibility;
+    private deriveAspect;
+}
+/**
+ * Decompose a column-major 4x4 rigid transformation matrix into Euler angles
+ * (radians) in YXZ order. Used when `useTransformationMatrix` is enabled.
+ */
+export declare function decomposeMatrixToEuler(matrix: number[]): {
+    x: number;
+    y: number;
+    z: number;
+};
+/** Convert degrees to radians for manifest authors who think in degrees. */
+export declare function degreesToRadians(deg: number): number;
+//# sourceMappingURL=GlassesPoseSolver.d.ts.map

package/dist/pose/GlassesPoseSolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GlassesPoseSolver.d.ts","sourceRoot":"","sources":["../../src/pose/GlassesPoseSolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,oBAAoB,EACpB,WAAW,EACX,sBAAsB,EAIvB,MAAM,mBAAmB,CAAC;AAI3B;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,QAAU,CAAC;AAE1C,qCAAqC;AACrC,eAAO,MAAM,sBAAsB,EAAE,oBAQpC,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAiB;IAC5B;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,sBAAsB,GAAG,WAAW;IAkDjD,OAAO,CAAC,WAAW;IAkBnB,OAAO,CAAC,YAAY;IAoBpB;;;OAGG;IACH,OAAO,CAAC,WAAW;IA+BnB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,eAAe;IAkDvB,OAAO,CAAC,eAAe;IAiBvB,OAAO,CAAC,oBAAoB;IAc5B,OAAO,CAAC,oBAAoB;IAc5B,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,gBAAgB;IA4BxB,OAAO,CAAC,YAAY;CAUrB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CA2B5F;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD"}