@lovelace_lol/embody 0.0.1

package/dist/validation/analyzeModel.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Embody - Unified Model Analysis API
+ *
+ * Combines model extraction, validation, and correction suggestions
+ * into a single comprehensive analysis report.
+ */
+import * as THREE from 'three';
+import type { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import type { Profile } from '../mappings/types';
+import { type ModelData } from './extractModelData';
+import { type ValidationResult } from './validateMappings';
+/**
+ * Animation analysis results
+ */
+export interface AnimationAnalysis {
+    count: number;
+    hasIdleCandidate: boolean;
+    clips: Array<{
+        name: string;
+        duration: number;
+        affectedBones: string[];
+        affectedMorphs: string[];
+    }>;
+}
+/**
+ * Complete model analysis report
+ */
+export interface ModelAnalysisReport {
+    /** Extracted model data */
+    model: ModelData;
+    /** Validation results (if preset provided) */
+    validation?: ValidationResult;
+    /** Animation analysis */
+    animations: AnimationAnalysis;
+    /** Overall health score (0-100) */
+    overallScore: number;
+    /** Human-readable summary */
+    summary: string;
+}
+/**
+ * Options for model analysis
+ */
+export interface AnalyzeModelOptions {
+    /** The model source */
+    source: {
+        type: 'gltf';
+        gltf: GLTF;
+    } | {
+        type: 'runtime';
+        model: THREE.Object3D;
+        meshes: THREE.Mesh[];
+        animations: THREE.AnimationClip[];
+    };
+    /** Optional preset to validate against */
+    preset?: Profile;
+    /** Request correction suggestions */
+    suggestCorrections?: boolean;
+}
+/**
+ * Analyze a 3D model comprehensively
+ *
+ * Extracts model data, validates against a preset (if provided),
+ * analyzes animations, and returns a comprehensive report.
+ *
+ * @param options - Analysis options
+ * @returns Complete analysis report
+ */
+export declare function analyzeModel(options: AnalyzeModelOptions): Promise<ModelAnalysisReport>;

package/dist/validation/extractModelData.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Embody - Model Data Extraction
+ *
+ * Extracts bones, morph targets, meshes, and animations from 3D models.
+ * Works with both GLTF files and runtime Three.js models.
+ */
+import * as THREE from 'three';
+import type { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+/**
+ * Bone information extracted from skeleton
+ */
+export interface BoneInfo {
+    name: string;
+    parent: string | null;
+    children: string[];
+    worldPosition: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Depth in hierarchy (0 = root) */
+    depth: number;
+}
+/**
+ * Morph target information
+ */
+export interface MorphInfo {
+    name: string;
+    meshName: string;
+    index: number;
+}
+/**
+ * Model mesh information (from extraction)
+ */
+export interface ModelMeshInfo {
+    name: string;
+    hasMorphTargets: boolean;
+    morphCount: number;
+}
+/**
+ * Animation track information
+ */
+export interface TrackInfo {
+    name: string;
+    targetName: string;
+    property: string;
+    type: 'position' | 'rotation' | 'scale' | 'morph' | 'unknown';
+    keyframeCount: number;
+    valueRange?: {
+        min: number[];
+        max: number[];
+    };
+}
+/**
+ * Animation clip information
+ */
+export interface AnimationInfo {
+    name: string;
+    duration: number;
+    tracks: TrackInfo[];
+    animatedBones: string[];
+    animatedMorphs: string[];
+}
+/**
+ * Complete model data extraction result
+ */
+export interface ModelData {
+    bones: BoneInfo[];
+    morphs: MorphInfo[];
+    meshes: ModelMeshInfo[];
+    animations: AnimationInfo[];
+    /** Quick lookups */
+    boneNames: string[];
+    morphNames: string[];
+    meshNames: string[];
+}
+/**
+ * Extract all data from a runtime Three.js model
+ *
+ * @param model - The root Object3D of the loaded model
+ * @param meshes - Array of meshes with morph targets (optional, will be collected if not provided)
+ * @param animations - Array of AnimationClips from the GLTF (optional)
+ */
+export declare function extractModelData(model: THREE.Object3D, meshes?: THREE.Mesh[], animations?: THREE.AnimationClip[]): ModelData;
+/**
+ * Extract all data from a GLTF file
+ *
+ * @param gltf - The loaded GLTF object
+ */
+export declare function extractFromGLTF(gltf: GLTF): ModelData;

package/dist/validation/generateMappingCorrections.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Embody - Mapping Corrections
+ *
+ * Attempts to generate a corrected mapping configuration using fuzzy matching.
+ * This is a best-effort helper that can be layered on top of validation.
+ */
+import type { Profile } from '../mappings/types';
+import type { ValidationMorphMesh as MorphMesh, ValidationSkeleton as Skeleton } from './types';
+export interface MappingCorrection {
+    type: 'bone' | 'morph' | 'viseme' | 'mesh';
+    source: string;
+    target: string;
+    confidence: number;
+    reason: string;
+    applied: boolean;
+    auId?: number;
+    key?: string;
+}
+export interface MappingCorrectionResult {
+    correctedConfig: Profile;
+    corrections: MappingCorrection[];
+    unresolved: MappingCorrection[];
+}
+export interface MappingCorrectionOptions {
+    minConfidence?: number;
+    /**
+     * When true, normalize names to resolved full names and clear prefix/suffix.
+     * This is useful when target names don't follow the prefix/suffix pattern.
+     */
+    useResolvedNames?: boolean;
+}
+export declare function generateMappingCorrections(meshes: MorphMesh[], skeleton: Skeleton | null, config: Profile, options?: MappingCorrectionOptions): MappingCorrectionResult;

package/dist/validation/geometryHelpers.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Embody - Geometry Helpers
+ *
+ * Helper functions for finding face positions, annotation centers,
+ * and other geometry-related calculations for character models.
+ */
+import * as THREE from 'three';
+/**
+ * Result of finding a face center position
+ */
+export interface FaceCenterResult {
+    /** The calculated face center position in world space */
+    center: THREE.Vector3;
+    /** The head bone position (if found) */
+    headBonePosition?: THREE.Vector3;
+    /** How the center was determined */
+    method: 'head-bone-offset' | 'bone-average' | 'mesh-center' | 'fallback';
+    /** Debug info about what was found */
+    debugInfo: string[];
+}
+/**
+ * Options for finding face center
+ */
+export interface FindFaceCenterOptions {
+    /** Names of bones to search for head bone (e.g., ['CC_Base_Head']) */
+    headBoneNames?: string[];
+    /** Names of face meshes - when provided, uses mesh bounding box center for positioning */
+    faceMeshNames?: string[];
+    /** Forward offset from head bone to face surface (default: 0.08 = 8cm) */
+    forwardOffset?: number;
+    /** Reference model height for scaling (default: 1.8m) */
+    referenceHeight?: number;
+}
+/**
+ * Find the center position of a character's face.
+ *
+ * Strategy:
+ * 1. If face mesh names provided and they're face-only meshes, use mesh center
+ * 2. Otherwise find head bone and use EYE positions to determine forward direction
+ *    (Eyes are reliably IN FRONT of the head bone, unlike jaw which is below)
+ *
+ * @param model - The root Object3D of the character model
+ * @param options - Configuration options
+ * @returns FaceCenterResult with the calculated position
+ */
+export declare function findFaceCenter(model: THREE.Object3D, options?: FindFaceCenterOptions): FaceCenterResult;
+/**
+ * Get the forward direction of a model in world space.
+ * Assumes the model's local forward is positive Z.
+ *
+ * @param model - The model to get forward direction for
+ * @returns Normalized forward direction vector in world space
+ */
+export declare function getModelForwardDirection(model: THREE.Object3D): THREE.Vector3;
+/**
+ * Check if a character model is facing forward (toward camera at origin).
+ * Uses head/eye bone positions to determine facing direction.
+ *
+ * @param model - The character model
+ * @param eyeBoneNames - Names of eye bones to search for
+ * @returns 'forward' if facing camera, 'backward' if facing away, 'unknown' if can't determine
+ */
+export declare function detectFacingDirection(model: THREE.Object3D, eyeBoneNames?: {
+    left: string[];
+    right: string[];
+}): 'forward' | 'backward' | 'unknown';

package/dist/validation/types.d.ts

@@ -0,0 +1,10 @@
+export interface ValidationMorphMesh {
+    name: string;
+    morphTargetDictionary?: Record<string, number>;
+    morphTargetInfluences?: number[];
+}
+export interface ValidationSkeleton {
+    bones: Array<{
+        name: string;
+    }>;
+}

package/dist/validation/validateMappings.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Embody - Mapping Validation
+ *
+ * Validates that AU mapping presets are compatible with a loaded character model.
+ * Checks that bones, morph targets, and meshes referenced in the preset exist in the model.
+ */
+import type { Profile } from '../mappings/types';
+import type { MappingCorrection, MappingCorrectionOptions } from './generateMappingCorrections';
+import type { ValidationMorphMesh as MorphMesh, ValidationSkeleton as Skeleton } from './types';
+/**
+ * Result of validating a preset against a model
+ */
+export interface ValidationResult {
+    /** Overall validity - true if essential mappings are found */
+    valid: boolean;
+    /** Compatibility score from 0-100 */
+    score: number;
+    /** Morph targets referenced in preset but not found in model */
+    missingMorphs: string[];
+    /** Bones referenced in preset but not found in model */
+    missingBones: string[];
+    /** Morph targets successfully matched */
+    foundMorphs: string[];
+    /** Bones successfully matched */
+    foundBones: string[];
+    /** Morph targets in model not used by preset */
+    unmappedMorphs: string[];
+    /** Bones in model not used by preset */
+    unmappedBones: string[];
+    /** Meshes referenced by morphToMesh but not found in model */
+    missingMeshes: string[];
+    /** Meshes referenced by morphToMesh and found in model */
+    foundMeshes: string[];
+    /** Meshes in model not referenced by morphToMesh */
+    unmappedMeshes: string[];
+    /** Non-fatal warnings and suggestions */
+    warnings: string[];
+    /** Optional: corrected config when suggestions are requested */
+    suggestedConfig?: Profile;
+    /** Optional: corrections applied or suggested */
+    corrections?: MappingCorrection[];
+    /** Optional: unresolved mappings that could not be corrected */
+    unresolved?: MappingCorrection[];
+}
+export type IssueSeverity = 'error' | 'warning';
+export interface MappingIssue {
+    code: string;
+    severity: IssueSeverity;
+    message: string;
+    data?: Record<string, unknown>;
+}
+export interface MappingConsistencyResult {
+    valid: boolean;
+    errors: MappingIssue[];
+    warnings: MappingIssue[];
+    issues: MappingIssue[];
+}
+export interface ValidateMappingOptions extends MappingCorrectionOptions {
+    suggestCorrections?: boolean;
+}
+/**
+ * Validate that the mapping dictionaries are internally consistent.
+ */
+export declare function validateMappingConfig(config: Profile): MappingConsistencyResult;
+export declare function validateMappings(meshes: MorphMesh[], skeleton: Skeleton | null, config: Profile, options?: ValidateMappingOptions): ValidationResult;
+/**
+ * Quick check if a preset is compatible with a model.
+ * Returns true if at least 50% of mappings are found.
+ */
+export declare function isPresetCompatible(meshes: MorphMesh[], skeleton: Skeleton | null, config: Profile): boolean;
+/**
+ * Suggest the best preset from a list based on validation scores.
+ */
+export declare function suggestBestPreset<T extends Profile>(meshes: MorphMesh[], skeleton: Skeleton | null, presets: T[]): {
+    preset: T;
+    score: number;
+} | null;

package/dist/wasm/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Jonathan Sutton Fields
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/wasm/README.md

@@ -0,0 +1,72 @@
+# Embody Wasm Core
+
+This crate provides the Rust/Wasm artifact used by the host-neutral Embody core.
+The npm build now produces the generated Wasm package under `dist/wasm` and
+the public `@lovelace_lol/embody/wasm` entrypoint initializes it explicitly.
+
+The current Rust surface focuses on batched numeric operations that match the
+core JS/Wasm boundary shape:
+
+- inputs are number slices / typed arrays
+- outputs are packed numeric buffers
+- no Three.js, Babylon, Unity, or host objects cross the boundary
+
+Skeleton fitting, fit metadata, and automatic skin binding should follow the
+same descriptor boundary. Rust can own host-neutral math over mesh descriptors,
+template skeleton descriptors, rest-pose transforms, bone envelopes, topology,
+inverse bind data, normals, scale, and manual fit adjustments. Host adapters
+must still own real mesh, material, GLB, skinning, and engine-object mutation.
+The TypeScript core contract exposes `TemplateSkeletonFitMetadata` so hosts can
+persist template id, source character id, fit transform, height/spans, status,
+vertical axis/anchor, confidence, and manual adjustments separately from actual
+skin weights. Both TypeScript and Rust/Wasm expose helpers that compose a
+solved fit transform with a user's manual scale and xyz offset.
+
+Automatic skin binding is not a per-frame Wasm target by default. It should be
+treated as research/offline-capable work until fixtures prove acceptable
+deformation quality for clothing, hands, face, hair, non-standard poses, and
+other hard cases. The runtime package should expose stable metadata and helper
+math first, then only move weight generation into Rust/Wasm if benchmarks and
+visual tests justify doing it in the browser.
+
+`validate_generated_template_fit_metadata(template_id, source_character_id,
+metadata)` validates persisted generated-template fit metadata without treating
+it as imported rig or skinning data. The packed metadata layout is:
+
+```text
+[
+  schema_version,
+  metadata_kind,
+  template_lookup_status,
+  fit_status,
+  vertical_axis,
+  vertical_anchor,
+  fit_scale,
+  translate_x, translate_y, translate_z,
+  solver_confidence,
+  manual_scale_multiplier,
+  manual_offset_x, manual_offset_y, manual_offset_z
+]
+```
+
+The validator returns a bitmask. `0` means valid; nonzero values identify
+unsupported versions, non-generated metadata kinds, unknown templates, invalid
+axis/anchor/status codes, non-finite transform fields, invalid confidence, or
+invalid ids.
+
+Automatic skin binding and weight generation are intentionally tracked as a
+separate research problem. See `docs/HUMANOID_TEMPLATE_SKINNING_TDR.md`.
+
+Build locally:
+
+```sh
+cargo test --manifest-path rust/embody-wasm/Cargo.toml
+cargo build --manifest-path rust/embody-wasm/Cargo.toml --target wasm32-unknown-unknown --release
+npm run build
+node scripts/smoke/package-exports.mjs
+```
+
+The npm build uses `wasm-pack` to generate JS glue and the `.wasm` binary after
+`tsup` writes the TypeScript package artifacts. Consumers should call
+`initEmbodyCore()` from `@lovelace_lol/embody/wasm` before using direct Wasm
+exports.