@lovelace_lol/loom3 1.0.27 → 1.0.28

package/README.md

@@ -349,6 +349,15 @@ const loom = new Loom3({
 
 `annotationRegions` is the Loom3 field for camera/marker region defaults and profile overrides.
 
+If your app fetches a full saved `CharacterConfig` from Firestore or another backend, use `resolveCharacterConfig(...)` to build the runtime shape before handing that config to camera/marker tooling:
+
+```typescript
+import { resolveCharacterConfig } from '@lovelace_lol/loom3';
+
+const savedConfig = await fetchCharacterConfig();
+const runtimeConfig = resolveCharacterConfig(savedConfig);
+```
+
 For the current runtime-oriented documentation, including:
 
 - `paddingFactor`

package/dist/index.cjs

@@ -3005,6 +3005,9 @@ function resolveProfile(base, override) {
     hairPhysics: mergeHairPhysicsConfig(base.hairPhysics, override.hairPhysics)
   };
 }
+function applyProfileToPreset(base, override) {
+  return override ? resolveProfile(base, override) : base;
+}
 
 // src/presets/bettaFish.ts
 var BONES = [
@@ -3677,6 +3680,9 @@ var MESHES = {
     morphCount: 0,
     // Fish model has no morphs
     material: {
+      renderOrder: 20,
+      transparent: true,
+      opacity: 1,
       depthWrite: true,
       depthTest: true,
       blending: "Normal"
@@ -3687,29 +3693,126 @@ var MESHES = {
     category: "eye",
     morphCount: 0,
     material: {
-      renderOrder: -10,
-      // Render early (behind body)
+      renderOrder: 17,
+      transparent: true,
+      opacity: 1,
+      depthWrite: true,
+      depthTest: true,
+      blending: "Normal"
+    }
+  },
+  // Hidden helper shell from the source asset; keep it suppressed by default
+  // so Betta does not rely on a Firestore-only mesh override.
+  "Cube_0": {
+    category: "body",
+    morphCount: 0,
+    material: {
+      renderOrder: -20,
+      transparent: true,
+      opacity: 0,
       depthWrite: true,
       depthTest: true,
       blending: "Normal"
     }
   }
 };
-var BETTA_FISH_PRESET = {
-  name: "Betta Fish",
-  animalType: "fish",
-  emoji: "\u{1F41F}",
-  bones: BONES,
-  boneNodes: BONE_NODES,
-  boneBindings: BONE_BINDINGS,
-  actionInfo: AU_INFO2,
-  eyeMeshNodes: EYE_MESH_NODES,
-  // No morph targets in this model
-  auToMorphs: {},
-  morphToMesh: {},
-  visemeKeys: []
-};
-var AU_MAPPING_CONFIG = {
+var ANNOTATION_REGIONS = [
+  {
+    name: "full_body",
+    objects: ["*"],
+    paddingFactor: 2.5
+  },
+  {
+    name: "head",
+    bones: ["HEAD"],
+    paddingFactor: 1.8,
+    children: ["left_eye", "right_eye", "mouth"],
+    expandAnimation: "staggered"
+  },
+  {
+    name: "left_eye",
+    meshes: ["EYES_0"],
+    parent: "head",
+    paddingFactor: 1.4,
+    cameraAngle: 270
+  },
+  {
+    name: "right_eye",
+    meshes: ["EYES_0"],
+    parent: "head",
+    paddingFactor: 1.4,
+    cameraAngle: 90
+  },
+  {
+    name: "mouth",
+    bones: ["HEAD"],
+    parent: "head",
+    paddingFactor: 1.5
+  },
+  {
+    name: "body",
+    bones: ["BODY_FRONT", "BODY_MID", "BODY_BACK"],
+    paddingFactor: 1.8
+  },
+  {
+    name: "tail",
+    bones: ["TAIL_BASE", "TAIL_TOP", "TAIL_MID"],
+    paddingFactor: 1.6
+  },
+  {
+    name: "dorsal_fin",
+    bones: ["DORSAL_ROOT", "DORSAL_L", "DORSAL_R"],
+    paddingFactor: 1.8
+  },
+  {
+    name: "pectoral_fins",
+    bones: ["PECTORAL_L_ROOT", "PECTORAL_R_ROOT"],
+    paddingFactor: 1.8,
+    children: ["pectoral_fin_left", "pectoral_fin_right"],
+    expandAnimation: "outward"
+  },
+  {
+    name: "pectoral_fin_left",
+    bones: ["PECTORAL_L_ROOT", "PECTORAL_L_CHAIN1", "PECTORAL_L_CHAIN2"],
+    parent: "pectoral_fins",
+    paddingFactor: 1.6,
+    cameraAngle: 270
+  },
+  {
+    name: "pectoral_fin_right",
+    bones: ["PECTORAL_R_ROOT", "PECTORAL_R_CHAIN1", "PECTORAL_R_ROOT2"],
+    parent: "pectoral_fins",
+    paddingFactor: 1.6,
+    cameraAngle: 90
+  },
+  {
+    name: "ventral_fins",
+    bones: ["VENTRAL_L", "VENTRAL_R"],
+    paddingFactor: 1.6
+  },
+  {
+    name: "gills",
+    bones: ["GILL_L", "GILL_R"],
+    paddingFactor: 1.6,
+    children: ["throat", "gill"],
+    expandAnimation: "outward"
+  },
+  {
+    name: "throat",
+    bones: ["GILL_L", "GILL_L_MID", "GILL_L_TIP"],
+    parent: "gills",
+    paddingFactor: 1.4,
+    cameraAngle: 270
+  },
+  {
+    name: "gill",
+    bones: ["GILL_R", "GILL_R_MID", "GILL_R_TIP"],
+    parent: "gills",
+    paddingFactor: 1.4,
+    cameraAngle: 90
+  }
+];
+var BETTA_FISH_PROFILE = {
   name: "Betta Fish",
   animalType: "fish",
   emoji: "\u{1F41F}",
@@ -3727,18 +3830,27 @@ var AU_MAPPING_CONFIG = {
   compositeRotations: COMPOSITE_ROTATIONS2,
   eyeMeshNodes: EYE_MESH_NODES,
   meshes: MESHES,
+  annotationRegions: ANNOTATION_REGIONS,
   auMixDefaults: {},
   // No mixed AUs (morph+bone) in this model
   continuumPairs: CONTINUUM_PAIRS_MAP2,
   continuumLabels: CONTINUUM_LABELS2
 };
+var BETTA_FISH_PRESET = {
+  ...BETTA_FISH_PROFILE,
+  bones: BONES,
+  boneBindings: BONE_BINDINGS,
+  actionInfo: AU_INFO2
+};
+var AU_MAPPING_CONFIG = BETTA_FISH_PRESET;
+var FISH_AU_MAPPING_CONFIG = BETTA_FISH_PRESET;
 
 // src/presets/index.ts
 function resolvePreset(presetType) {
   switch (presetType) {
     case "fish":
     case "skeletal":
-      return AU_MAPPING_CONFIG;
+      return BETTA_FISH_PRESET;
     case "cc4":
     case "custom":
     default:
@@ -3747,7 +3859,7 @@ function resolvePreset(presetType) {
 }
 function resolvePresetWithOverrides(presetType, overrides) {
   const base = resolvePreset(presetType);
-  return overrides ? resolveProfile(base, overrides) : base;
+  return applyProfileToPreset(base, overrides);
 }
 
 // src/engines/three/Loom3.ts
@@ -3824,7 +3936,7 @@ var _Loom3 = class _Loom3 {
     /** Store original emissive colors for highlight reset */
     __publicField(this, "originalEmissive", /* @__PURE__ */ new Map());
     const basePreset = config.presetType ? resolvePreset(config.presetType) : CC4_PRESET;
-    this.config = config.profile ? resolveProfile(basePreset, config.profile) : basePreset;
+    this.config = applyProfileToPreset(basePreset, config.profile);
     this.mixWeights = { ...this.config.auMixDefaults };
     this.animation = animation || new AnimationThree();
     this.compositeRotations = this.config.compositeRotations || COMPOSITE_ROTATIONS;
@@ -5232,6 +5344,206 @@ var BLENDING_MODES = {
   "None": 0
   // THREE.NoBlending
 };
+
+// src/characters/resolveCharacterConfig.ts
+var PROFILE_OVERRIDE_KEYS = [
+  "name",
+  "animalType",
+  "emoji",
+  "auToMorphs",
+  "auToBones",
+  "boneNodes",
+  "bonePrefix",
+  "boneSuffix",
+  "morphPrefix",
+  "morphSuffix",
+  "suffixPattern",
+  "leftMorphSuffixes",
+  "rightMorphSuffixes",
+  "morphToMesh",
+  "auFacePartToMeshCategory",
+  "visemeKeys",
+  "visemeMeshCategory",
+  "visemeJawAmounts",
+  "auMixDefaults",
+  "auInfo",
+  "eyeMeshNodes",
+  "compositeRotations",
+  "meshes",
+  "continuumPairs",
+  "continuumLabels",
+  "annotationRegions",
+  "hairPhysics"
+];
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function cloneArray(value) {
+  return value ? value.map((entry) => cloneValue2(entry)) : void 0;
+}
+function cloneValue2(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => cloneValue2(entry));
+  }
+  if (isPlainObject2(value)) {
+    const next = {};
+    for (const [key, entry] of Object.entries(value)) {
+      next[key] = cloneValue2(entry);
+    }
+    return next;
+  }
+  return value;
+}
+function mergeProfileOverrideValue(base, override) {
+  if (override === void 0) {
+    return base === void 0 ? void 0 : cloneValue2(base);
+  }
+  if (Array.isArray(override)) {
+    return cloneValue2(override);
+  }
+  if (isPlainObject2(base) && isPlainObject2(override)) {
+    return {
+      ...cloneValue2(base),
+      ...cloneValue2(override)
+    };
+  }
+  return cloneValue2(override);
+}
+function cloneVector3(value) {
+  return value ? { ...value } : void 0;
+}
+function cloneRegion(region) {
+  return {
+    ...region,
+    bones: cloneArray(region.bones),
+    meshes: cloneArray(region.meshes),
+    objects: cloneArray(region.objects),
+    children: cloneArray(region.children),
+    cameraOffset: cloneVector3(region.cameraOffset),
+    customPosition: region.customPosition ? { ...region.customPosition } : void 0,
+    style: region.style ? {
+      ...region.style,
+      line: region.style.line ? { ...region.style.line } : void 0
+    } : void 0
+  };
+}
+function mergeRegion(base, override) {
+  return {
+    ...base,
+    ...override,
+    bones: override.bones !== void 0 ? [...override.bones] : base.bones ? [...base.bones] : void 0,
+    meshes: override.meshes !== void 0 ? [...override.meshes] : base.meshes ? [...base.meshes] : void 0,
+    objects: override.objects !== void 0 ? [...override.objects] : base.objects ? [...base.objects] : void 0,
+    children: override.children !== void 0 ? [...override.children] : base.children ? [...base.children] : void 0,
+    cameraOffset: override.cameraOffset ? { ...base.cameraOffset, ...override.cameraOffset } : cloneVector3(base.cameraOffset),
+    customPosition: override.customPosition ? { ...override.customPosition } : base.customPosition ? { ...base.customPosition } : void 0,
+    style: override.style ? {
+      ...base.style,
+      ...override.style,
+      line: override.style.line ? { ...base.style?.line, ...override.style.line } : base.style?.line ? { ...base.style.line } : void 0
+    } : base.style ? {
+      ...base.style,
+      line: base.style.line ? { ...base.style.line } : void 0
+    } : void 0
+  };
+}
+function mergeStringRecord(base, override) {
+  if (!base && !override) return void 0;
+  return {
+    ...base ? { ...base } : {},
+    ...override ? { ...override } : {}
+  };
+}
+function mergeRegionsByName(base, override) {
+  if (!base && !override) return void 0;
+  const merged = /* @__PURE__ */ new Map();
+  for (const region of base ?? []) {
+    merged.set(region.name, cloneRegion(region));
+  }
+  for (const region of override ?? []) {
+    const existing = merged.get(region.name);
+    merged.set(region.name, existing ? mergeRegion(existing, region) : cloneRegion(region));
+  }
+  return Array.from(merged.values());
+}
+function extractProfileOverrides(config) {
+  const topLevelConfig = config;
+  const legacyNestedOverrides = isPlainObject2(config.profile) ? config.profile : {};
+  const overrides = {};
+  for (const key of PROFILE_OVERRIDE_KEYS) {
+    if (key === "annotationRegions") {
+      const topLevelAnnotationRegions = Array.isArray(topLevelConfig.annotationRegions) ? topLevelConfig.annotationRegions : void 0;
+      const legacyAnnotationRegions = Array.isArray(legacyNestedOverrides.annotationRegions) ? legacyNestedOverrides.annotationRegions : void 0;
+      const presetOverrideRegions = mergeRegionsByName(legacyAnnotationRegions, topLevelAnnotationRegions);
+      const regions = mergeRegionsByName(
+        presetOverrideRegions,
+        Array.isArray(config.regions) && config.regions.length > 0 ? config.regions : void 0
+      );
+      if (regions) {
+        overrides.annotationRegions = regions.map((region) => cloneRegion(region));
+      }
+      continue;
+    }
+    const topLevelValue = topLevelConfig[key];
+    const legacyValue = legacyNestedOverrides[key];
+    const mergedValue = mergeProfileOverrideValue(legacyValue, topLevelValue);
+    if (mergedValue !== void 0) {
+      overrides[key] = mergedValue;
+    }
+  }
+  return overrides;
+}
+function applyCharacterProfileToPreset(config) {
+  const presetType = config.auPresetType;
+  if (!presetType) {
+    return null;
+  }
+  return applyProfileToPreset(resolvePreset(presetType), extractProfileOverrides(config));
+}
+function orderResolvedRegions(resolvedRegions, prioritizedLists) {
+  if (!resolvedRegions) return void 0;
+  const resolvedByName = new Map(resolvedRegions.map((region) => [region.name, region]));
+  const orderedNames = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const regions of prioritizedLists) {
+    for (const region of regions ?? []) {
+      if (seen.has(region.name)) continue;
+      seen.add(region.name);
+      orderedNames.push(region.name);
+    }
+  }
+  for (const region of resolvedRegions) {
+    if (seen.has(region.name)) continue;
+    seen.add(region.name);
+    orderedNames.push(region.name);
+  }
+  return orderedNames.map((name) => resolvedByName.get(name)).filter((region) => Boolean(region));
+}
+function resolveCharacterConfig(config) {
+  const presetType = config.auPresetType;
+  if (!presetType || presetType === "custom") {
+    return config;
+  }
+  const profileOverrides = extractProfileOverrides(config);
+  const presetResolvedProfile = applyCharacterProfileToPreset(config);
+  if (!presetResolvedProfile) {
+    return config;
+  }
+  const presetRegions = presetResolvedProfile.annotationRegions;
+  const mergedRegions = mergeRegionsByName(presetRegions, config.regions);
+  const resolvedRegions = orderResolvedRegions(
+    mergedRegions,
+    [config.regions, profileOverrides.annotationRegions, presetRegions]
+  );
+  return {
+    ...config,
+    bonePrefix: config.bonePrefix ?? presetResolvedProfile.bonePrefix,
+    boneSuffix: config.boneSuffix ?? presetResolvedProfile.boneSuffix,
+    boneNodes: mergeStringRecord(presetResolvedProfile.boneNodes, config.boneNodes),
+    suffixPattern: config.suffixPattern ?? presetResolvedProfile.suffixPattern,
+    regions: resolvedRegions ?? config.regions
+  };
+}
 var DEFAULT_HEAD_BONE_NAMES = ["CC_Base_Head", "Head", "head", "Bip01_Head"];
 var DEFAULT_REFERENCE_HEIGHT = 1.8;
 var DEFAULT_FORWARD_OFFSET = 0.08;
@@ -5416,6 +5728,9 @@ function detectFacingDirection(model, eyeBoneNames = {
 }
 
 // src/regions/regionMapping.ts
+function normalizeLooseName(value) {
+  return value.replace(/\./g, "");
+}
 function resolveBoneName(semanticName, config) {
   if (!config) return semanticName;
   const { bonePrefix, boneSuffix, boneNodes } = config;
@@ -5436,6 +5751,7 @@ function resolveBoneNames(names, config) {
 }
 function fuzzyNameMatch(objectName, targetName, suffixPattern) {
   if (objectName === targetName) return true;
+  if (normalizeLooseName(objectName) === normalizeLooseName(targetName)) return true;
   if (!objectName.startsWith(targetName)) return false;
   const suffix = objectName.slice(targetName.length);
   if (suffix === "") return true;
@@ -5582,6 +5898,9 @@ var HairPhysics = class {
 
 // src/validation/generateMappingCorrections.ts
 var DEFAULT_MIN_CONFIDENCE = 0.6;
+function normalizeLooseName2(value) {
+  return value.replace(/\./g, "");
+}
 function levenshteinDistance(a, b) {
   const matrix = [];
   const aLen = a.length;
@@ -5618,6 +5937,9 @@ function scoreCandidate(targetBase, candidate, fullTarget, suffixPattern) {
   if (candidate === fullTarget) {
     return { score: 1, reason: "exact match" };
   }
+  if (normalizeLooseName2(candidate) === normalizeLooseName2(fullTarget)) {
+    return { score: 1, reason: "separator-normalized exact match" };
+  }
   if (suffixPattern && candidate.startsWith(fullTarget)) {
     const suffix = candidate.slice(fullTarget.length);
     if (suffix === "" || suffixPattern.test(suffix)) {
@@ -5806,11 +6128,17 @@ function generateMappingCorrections(meshes, skeleton, config, options = {}) {
 }
 
 // src/validation/validateMappings.ts
+function normalizeLooseName3(value) {
+  return value.replace(/\./g, "");
+}
 function fuzzyMatch(targetName, candidateName, prefix, suffix, suffixPattern) {
   const fullTarget = prefix + targetName + suffix;
   if (candidateName === fullTarget) {
     return true;
   }
+  if (normalizeLooseName3(candidateName) === normalizeLooseName3(fullTarget)) {
+    return true;
+  }
   if (suffixPattern && candidateName.startsWith(fullTarget)) {
     const suffix2 = candidateName.slice(fullTarget.length);
     return suffix2 === "" || suffixPattern.test(suffix2);
@@ -6526,6 +6854,7 @@ async function analyzeModel(options) {
 }
 
 exports.AU_INFO = AU_INFO;
+exports.AU_MAPPING_CONFIG = AU_MAPPING_CONFIG;
 exports.AU_MIX_DEFAULTS = AU_MIX_DEFAULTS;
 exports.AU_TO_MORPHS = AU_TO_MORPHS;
 exports.AnimationThree = AnimationThree;
@@ -6542,7 +6871,7 @@ exports.COMPOSITE_ROTATIONS = COMPOSITE_ROTATIONS;
 exports.CONTINUUM_LABELS = CONTINUUM_LABELS;
 exports.CONTINUUM_PAIRS_MAP = CONTINUUM_PAIRS_MAP;
 exports.DEFAULT_HAIR_PHYSICS_CONFIG = DEFAULT_HAIR_PHYSICS_CONFIG;
-exports.FISH_AU_MAPPING_CONFIG = AU_MAPPING_CONFIG;
+exports.FISH_AU_MAPPING_CONFIG = FISH_AU_MAPPING_CONFIG;
 exports.HairPhysics = HairPhysics;
 exports.Loom3 = Loom3;
 exports.Loom3Three = Loom3;
@@ -6551,10 +6880,13 @@ exports.MORPH_TO_MESH = MORPH_TO_MESH;
 exports.VISEME_JAW_AMOUNTS = VISEME_JAW_AMOUNTS;
 exports.VISEME_KEYS = VISEME_KEYS;
 exports.analyzeModel = analyzeModel;
+exports.applyCharacterProfileToPreset = applyCharacterProfileToPreset;
+exports.applyProfileToPreset = applyProfileToPreset;
 exports.collectMorphMeshes = collectMorphMeshes;
 exports.detectFacingDirection = detectFacingDirection;
 exports.extractFromGLTF = extractFromGLTF;
 exports.extractModelData = extractModelData;
+exports.extractProfileOverrides = extractProfileOverrides;
 exports.findFaceCenter = findFaceCenter;
 exports.fuzzyNameMatch = fuzzyNameMatch;
 exports.generateMappingCorrections = generateMappingCorrections;
@@ -6562,8 +6894,10 @@ exports.getModelForwardDirection = getModelForwardDirection;
 exports.hasLeftRightMorphs = hasLeftRightMorphs;
 exports.isMixedAU = isMixedAU;
 exports.isPresetCompatible = isPresetCompatible;
+exports.mergeCharacterRegionsByName = mergeRegionsByName;
 exports.resolveBoneName = resolveBoneName;
 exports.resolveBoneNames = resolveBoneNames;
+exports.resolveCharacterConfig = resolveCharacterConfig;
 exports.resolveFaceCenter = resolveFaceCenter;
 exports.resolvePreset = resolvePreset;
 exports.resolvePresetWithOverrides = resolvePresetWithOverrides;