@lovelace_lol/loom3 1.0.3 → 1.0.6

package/dist/index.cjs

@@ -26,11 +26,53 @@ var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
+// src/core/compositeAxis.ts
+function toAUList(value) {
+  if (value === void 0) return [];
+  return Array.isArray(value) ? value : [value];
+}
+function findBoneBindingForNode(auToBones, auId, nodeKey) {
+  return auToBones[auId]?.find((candidate) => candidate.node === nodeKey) ?? null;
+}
+function getCompositeAxisValue(axisConfig, getValue) {
+  if (!axisConfig) return 0;
+  const negativeAUs = toAUList(axisConfig.negative);
+  const positiveAUs = toAUList(axisConfig.positive);
+  if (negativeAUs.length > 0 && positiveAUs.length > 0) {
+    const negativeValue = Math.max(...negativeAUs.map(getValue), 0);
+    const positiveValue = Math.max(...positiveAUs.map(getValue), 0);
+    return positiveValue - negativeValue;
+  }
+  if (axisConfig.aus.length > 1) {
+    return Math.max(...axisConfig.aus.map(getValue), 0);
+  }
+  return getValue(axisConfig.aus[0]);
+}
+function getCompositeAxisBinding(nodeKey, axisConfig, direction, getValue, auToBones) {
+  if (!axisConfig) return null;
+  const directionalAUs = direction < 0 ? toAUList(axisConfig.negative) : toAUList(axisConfig.positive);
+  const candidates = directionalAUs.length > 0 ? directionalAUs : axisConfig.aus;
+  const ranked = [...candidates].sort((a, b) => getValue(b) - getValue(a));
+  for (const auId of ranked) {
+    const binding = findBoneBindingForNode(auToBones, auId, nodeKey);
+    if (binding) return binding;
+  }
+  return null;
+}
+
 // src/engines/three/balanceUtils.ts
 function clampBalance(value) {
   if (!Number.isFinite(value)) return 0;
   return Math.max(-1, Math.min(1, value));
 }
+function getSideScale(balance, side) {
+  if (side !== "left" && side !== "right") return 1;
+  const clamped = clampBalance(balance);
+  if (side === "left") {
+    return clamped > 0 ? 1 - clamped : 1;
+  }
+  return clamped < 0 ? 1 + clamped : 1;
+}
 function resolveCurveBalance(curveId, globalBalance, balanceMap) {
   if (balanceMap && Object.prototype.hasOwnProperty.call(balanceMap, curveId)) {
     return clampBalance(Number(balanceMap[curveId]));
@@ -158,8 +200,22 @@ var BakedAnimationController = class {
       return this.host.getMeshNamesForAU(auId) || [];
     }
     const facePart = config.auInfo?.[String(auId)]?.facePart;
-    if (facePart === "Tongue") return config.morphToMesh?.tongue || [];
-    if (facePart === "Eye") return config.morphToMesh?.eye || [];
+    if (facePart) {
+      const category = config.auFacePartToMeshCategory?.[facePart];
+      if (category) return config.morphToMesh?.[category] || [];
+    }
+    return config.morphToMesh?.face || [];
+  }
+  getMeshNamesForViseme(config, explicitMeshNames) {
+    if (explicitMeshNames && explicitMeshNames.length > 0) {
+      return explicitMeshNames;
+    }
+    if (typeof this.host.getMeshNamesForViseme === "function") {
+      return this.host.getMeshNamesForViseme() || [];
+    }
+    const category = config.visemeMeshCategory || (config.morphToMesh?.viseme ? "viseme" : "face");
+    const visemeMeshes = config.morphToMesh?.[category];
+    if (visemeMeshes && visemeMeshes.length > 0) return visemeMeshes;
     return config.morphToMesh?.face || [];
   }
   update(dtSeconds) {
@@ -455,11 +511,12 @@ var BakedAnimationController = class {
       if (isNumericAU(curveId)) {
         const auId = Number(curveId);
         if (isVisemeIndex(curveId)) {
+          const visemeMeshNames = this.getMeshNamesForViseme(config, meshNames);
           const visemeKey = config.visemeKeys[auId];
           if (typeof visemeKey === "number") {
-            this.addMorphIndexTracks(tracks, visemeKey, keyframes, intensityScale, meshNames);
+            this.addMorphIndexTracks(tracks, visemeKey, keyframes, intensityScale, visemeMeshNames);
           } else if (visemeKey) {
-            this.addMorphTracks(tracks, visemeKey, keyframes, intensityScale, meshNames);
+            this.addMorphTracks(tracks, visemeKey, keyframes, intensityScale, visemeMeshNames);
           }
         } else {
           const auMeshNames = this.getMeshNamesForAU(auId, config, meshNames);
@@ -539,43 +596,23 @@ var BakedAnimationController = class {
         Object.keys(curves).filter(isNumericAU).map((id) => Number(id))
       );
       const getAxisBinding = (nodeKey, axisConfig, axisValue, t) => {
-        if (!axisConfig) return null;
-        if (axisConfig.negative !== void 0 && axisConfig.positive !== void 0) {
-          const auId2 = axisValue < 0 ? axisConfig.negative : axisConfig.positive;
-          return config.auToBones[auId2]?.find((b) => b.node === nodeKey) ?? null;
-        }
-        if (axisConfig.aus.length > 1) {
-          let maxAU = axisConfig.aus[0];
-          let maxVal = sampleCurve(String(maxAU), t);
-          for (const auId2 of axisConfig.aus) {
-            const val = sampleCurve(String(auId2), t);
-            if (val > maxVal) {
-              maxVal = val;
-              maxAU = auId2;
-            }
-          }
-          return config.auToBones[maxAU]?.find((b) => b.node === nodeKey) ?? null;
-        }
-        const auId = axisConfig.aus[0];
-        return config.auToBones[auId]?.find((b) => b.node === nodeKey) ?? null;
+        return getCompositeAxisBinding(
+          nodeKey,
+          axisConfig,
+          axisValue,
+          (auId) => getAxisSampleForNode(auId, nodeKey, t),
+          config.auToBones
+        );
       };
-      const getAxisValue = (axisConfig, t) => {
-        if (!axisConfig) return 0;
-        if (axisConfig.negative !== void 0 && axisConfig.positive !== void 0) {
-          const posValue = sampleCurve(String(axisConfig.positive), t);
-          const negValue = sampleCurve(String(axisConfig.negative), t);
-          return posValue - negValue;
-        }
-        if (axisConfig.aus.length > 1) {
-          let maxVal = 0;
-          for (const auId of axisConfig.aus) {
-            const val = sampleCurve(String(auId), t);
-            if (val > maxVal) maxVal = val;
-          }
-          return maxVal;
-        }
-        return sampleCurve(String(axisConfig.aus[0]), t);
+      const getAxisSampleForNode = (auId, nodeKey, t) => {
+        const rawValue = sampleCurve(String(auId), t);
+        if (rawValue <= 1e-6) return 0;
+        const binding = config.auToBones[auId]?.find((b) => b.node === nodeKey) ?? null;
+        if (!binding?.side) return rawValue;
+        const curveBalance = resolveCurveBalance(String(auId), globalBalance, balanceMap);
+        return rawValue * getSideScale(curveBalance, binding.side);
       };
+      const getAxisValue = (nodeKey, axisConfig, t) => getCompositeAxisValue(axisConfig, (auId) => getAxisSampleForNode(auId, nodeKey, t));
       const autoVisemeJawHandledJaw = autoVisemeJaw && jawScale > 0 && visemeJawAmounts && options?.snippetCategory === "visemeSnippet";
       for (const composite of compositeRotations) {
         const nodeKey = composite.node;
@@ -596,7 +633,7 @@ var BakedAnimationController = class {
           const compositeQ = new THREE.Quaternion().copy(entry.baseQuat);
           const applyAxis = (axisConfig) => {
             if (!axisConfig) return;
-            let axisValue = getAxisValue(axisConfig, t);
+            let axisValue = getAxisValue(nodeKey, axisConfig, t);
             if (Math.abs(axisValue) <= 1e-6) return;
             const binding = getAxisBinding(nodeKey, axisConfig, axisValue, t);
             if (!binding?.maxDegrees || !binding.channel) return;
@@ -1199,24 +1236,24 @@ var AU_TO_MORPHS = {
     center: []
   },
   61: {
-    left: ["Eye_L_Look_L", "Eye_R_Look_L"],
-    right: [],
+    left: ["Eye_L_Look_L"],
+    right: ["Eye_R_Look_L"],
     center: []
   },
   62: {
-    left: [],
-    right: ["Eye_L_Look_R", "Eye_R_Look_R"],
+    left: ["Eye_L_Look_R"],
+    right: ["Eye_R_Look_R"],
     center: []
   },
   63: {
-    left: [],
-    right: [],
-    center: ["Eye_L_Look_Up", "Eye_R_Look_Up"]
+    left: ["Eye_L_Look_Up"],
+    right: ["Eye_R_Look_Up"],
+    center: []
   },
   64: {
-    left: [],
-    right: [],
-    center: ["Eye_L_Look_Down", "Eye_R_Look_Down"]
+    left: ["Eye_L_Look_Down"],
+    right: ["Eye_R_Look_Down"],
+    center: []
   },
   65: {
     left: ["Eye_L_Look_L"],
@@ -1444,6 +1481,14 @@ var BONE_AU_TO_BINDINGS = {
     { node: "EYE_L", channel: "rx", scale: 1, maxDegrees: 20, side: "left" },
     { node: "EYE_R", channel: "rx", scale: 1, maxDegrees: 20, side: "right" }
   ],
+  65: [{ node: "EYE_L", channel: "rz", scale: 1, maxDegrees: 25, side: "left" }],
+  66: [{ node: "EYE_L", channel: "rz", scale: -1, maxDegrees: 25, side: "left" }],
+  67: [{ node: "EYE_L", channel: "rx", scale: -1, maxDegrees: 20, side: "left" }],
+  68: [{ node: "EYE_L", channel: "rx", scale: 1, maxDegrees: 20, side: "left" }],
+  69: [{ node: "EYE_R", channel: "rz", scale: 1, maxDegrees: 25, side: "right" }],
+  70: [{ node: "EYE_R", channel: "rz", scale: -1, maxDegrees: 25, side: "right" }],
+  71: [{ node: "EYE_R", channel: "rx", scale: -1, maxDegrees: 20, side: "right" }],
+  72: [{ node: "EYE_R", channel: "rx", scale: 1, maxDegrees: 20, side: "right" }],
   // Tongue controls (optional, for rigs that expose them)
   37: [{ node: "TONGUE", channel: "rz", scale: 1, maxDegrees: 20 }],
   38: [{ node: "TONGUE", channel: "rz", scale: -1, maxDegrees: 20 }],
@@ -1531,18 +1576,18 @@ var COMPOSITE_ROTATIONS = [
   },
   {
     node: "EYE_L",
-    pitch: { aus: [64, 63], axis: "rx", negative: 64, positive: 63 },
+    pitch: { aus: [64, 63, 68, 67], axis: "rx", negative: [64, 68], positive: [63, 67] },
     // Eyes down/up
-    yaw: { aus: [61, 62], axis: "rz", negative: 61, positive: 62 },
+    yaw: { aus: [61, 62, 65, 66], axis: "rz", negative: [61, 65], positive: [62, 66] },
     // Eyes left/right (rz for CC4)
     roll: null
     // Eyes don't have roll
   },
   {
     node: "EYE_R",
-    pitch: { aus: [64, 63], axis: "rx", negative: 64, positive: 63 },
+    pitch: { aus: [64, 63, 72, 71], axis: "rx", negative: [64, 72], positive: [63, 71] },
     // Eyes down/up
-    yaw: { aus: [61, 62], axis: "rz", negative: 61, positive: 62 },
+    yaw: { aus: [61, 62, 69, 70], axis: "rz", negative: [61, 69], positive: [62, 70] },
     // Eyes left/right (rz for CC4)
     roll: null
     // Eyes don't have roll
@@ -1561,9 +1606,17 @@ var CONTINUUM_PAIRS_MAP = {
   // Eyes horizontal - both eyes share same AUs (yaw maps to rz via COMPOSITE_ROTATIONS)
   61: { pairId: 62, isNegative: true, axis: "yaw", node: "EYE_L" },
   62: { pairId: 61, isNegative: false, axis: "yaw", node: "EYE_L" },
+  65: { pairId: 66, isNegative: true, axis: "yaw", node: "EYE_L" },
+  66: { pairId: 65, isNegative: false, axis: "yaw", node: "EYE_L" },
+  69: { pairId: 70, isNegative: true, axis: "yaw", node: "EYE_R" },
+  70: { pairId: 69, isNegative: false, axis: "yaw", node: "EYE_R" },
   // Eyes vertical (pitch)
   64: { pairId: 63, isNegative: true, axis: "pitch", node: "EYE_L" },
   63: { pairId: 64, isNegative: false, axis: "pitch", node: "EYE_L" },
+  68: { pairId: 67, isNegative: true, axis: "pitch", node: "EYE_L" },
+  67: { pairId: 68, isNegative: false, axis: "pitch", node: "EYE_L" },
+  72: { pairId: 71, isNegative: true, axis: "pitch", node: "EYE_R" },
+  71: { pairId: 72, isNegative: false, axis: "pitch", node: "EYE_R" },
   // Head yaw (turn left/right)
   51: { pairId: 52, isNegative: true, axis: "yaw", node: "HEAD" },
   52: { pairId: 51, isNegative: false, axis: "yaw", node: "HEAD" },
@@ -1596,6 +1649,10 @@ var CONTINUUM_PAIRS_MAP = {
 var CONTINUUM_LABELS = {
   "61-62": "Eyes \u2014 Horizontal",
   "64-63": "Eyes \u2014 Vertical",
+  "65-66": "Left Eye \u2014 Horizontal",
+  "68-67": "Left Eye \u2014 Vertical",
+  "69-70": "Right Eye \u2014 Horizontal",
+  "72-71": "Right Eye \u2014 Vertical",
   "51-52": "Head \u2014 Horizontal",
   "54-53": "Head \u2014 Vertical",
   "55-56": "Head \u2014 Tilt",
@@ -1784,6 +1841,12 @@ var MORPH_TO_MESH = {
   tongue: ["CC_Base_Tongue", "CC_Base_Tongue_1"],
   hair: ["Side_part_wavy", "Side_part_wavy_1", "Side_part_wavy_2"]
 };
+var AU_FACEPART_TO_MESH_CATEGORY = {
+  Eye: "eye",
+  Eyes: "eye",
+  Eyelids: "eye",
+  Tongue: "tongue"
+};
 var CC4_HAIR_PHYSICS = {
   stiffness: 7.5,
   damping: 0.18,
@@ -1829,7 +1892,9 @@ var CC4_PRESET = {
   bonePrefix: CC4_BONE_PREFIX,
   suffixPattern: CC4_SUFFIX_PATTERN,
   morphToMesh: MORPH_TO_MESH,
+  auFacePartToMeshCategory: AU_FACEPART_TO_MESH_CATEGORY,
   visemeKeys: VISEME_KEYS,
+  visemeMeshCategory: "viseme",
   visemeJawAmounts: VISEME_JAW_AMOUNTS,
   auMixDefaults: AU_MIX_DEFAULTS,
   auInfo: AU_INFO,
@@ -2149,9 +2214,10 @@ var HairPhysicsController = class {
     if (meshName) {
       targetMesh = this.registeredHairObjects.get(meshName);
     } else {
-      for (const [name, mesh] of this.registeredHairObjects) {
-        const info = CC4_MESHES[name];
-        if (info?.category === "hair") {
+      const hairMeshNames = this.getHairMeshNames();
+      for (const name of hairMeshNames) {
+        const mesh = this.registeredHairObjects.get(name) || this.host.getMeshByName(name);
+        if (mesh) {
           targetMesh = mesh;
           break;
         }
@@ -2245,6 +2311,15 @@ var HairPhysicsController = class {
   }
   getHairMeshNames() {
     if (this.cachedHairMeshNames) return this.cachedHairMeshNames;
+    if (typeof this.host.getSelectedHairMeshNames === "function") {
+      const selectedHairMeshNames = this.host.getSelectedHairMeshNames() || [];
+      const resolved = selectedHairMeshNames.filter((name) => {
+        const mesh = this.registeredHairObjects.get(name) || this.host.getMeshByName(name);
+        return !!mesh;
+      });
+      this.cachedHairMeshNames = Array.from(new Set(resolved));
+      return this.cachedHairMeshNames;
+    }
     const names = [];
     this.registeredHairObjects.forEach((mesh, name) => {
       const info = CC4_MESHES[name];
@@ -2260,6 +2335,18 @@ var HairPhysicsController = class {
     this.cachedHairMeshNames = names;
     return names;
   }
+  refreshMeshSelection() {
+    this.cachedHairMeshNames = null;
+    this.idleClipDirty = true;
+    this.gravityClipDirty = true;
+    this.impulseClipDirty = true;
+    this.warnMissingHairMorphTargets();
+    if (this.hairPhysicsEnabled) {
+      this.startIdleClip();
+      this.startGravityClip();
+      this.buildImpulseClips();
+    }
+  }
   supportsMixerClips() {
     return typeof this.host.buildClip === "function";
   }
@@ -2274,7 +2361,11 @@ var HairPhysicsController = class {
       return;
     }
     const hairMeshNames = this.getHairMeshNames();
-    if (hairMeshNames.length === 0) return;
+    if (hairMeshNames.length === 0) {
+      this.stopIdleClip();
+      this.idleClipDirty = false;
+      return;
+    }
     if (!this.idleClipDirty && this.idleClipHandle) return;
     this.stopIdleClip();
     const duration = Math.max(0.5, cfg.idleClipDuration);
@@ -2292,7 +2383,11 @@ var HairPhysicsController = class {
   startGravityClip() {
     if (!this.hairPhysicsEnabled || !this.supportsMixerClips()) return;
     const hairMeshNames = this.getHairMeshNames();
-    if (hairMeshNames.length === 0) return;
+    if (hairMeshNames.length === 0) {
+      this.stopGravityClip();
+      this.gravityClipDirty = false;
+      return;
+    }
     if (!this.gravityClipDirty && this.gravityClipHandle) return;
     this.stopGravityClip();
     const morphTargets = this.hairPhysicsConfig.morphTargets;
@@ -2345,7 +2440,11 @@ var HairPhysicsController = class {
   buildImpulseClips() {
     if (!this.hairPhysicsEnabled || !this.supportsMixerClips()) return;
     const hairMeshNames = this.getHairMeshNames();
-    if (hairMeshNames.length === 0) return;
+    if (hairMeshNames.length === 0) {
+      this.stopImpulseClips();
+      this.impulseClipDirty = false;
+      return;
+    }
     if (!this.impulseClipDirty && this.impulseClips.left && this.impulseClips.right && this.impulseClips.front) {
       return;
     }
@@ -2681,7 +2780,9 @@ function resolveProfile(base, override) {
     auToBones: mergeRecord(base.auToBones, override.auToBones),
     boneNodes: mergeRecord(base.boneNodes, override.boneNodes),
     morphToMesh: mergeRecord(base.morphToMesh, override.morphToMesh),
+    auFacePartToMeshCategory: base.auFacePartToMeshCategory || override.auFacePartToMeshCategory ? mergeRecord(base.auFacePartToMeshCategory || {}, override.auFacePartToMeshCategory || {}) : void 0,
     visemeKeys: override.visemeKeys ? [...override.visemeKeys] : [...base.visemeKeys],
+    visemeMeshCategory: override.visemeMeshCategory ?? base.visemeMeshCategory,
     auMixDefaults: base.auMixDefaults || override.auMixDefaults ? mergeRecord(base.auMixDefaults || {}, override.auMixDefaults || {}) : void 0,
     auInfo: base.auInfo || override.auInfo ? mergeRecord(base.auInfo || {}, override.auInfo || {}) : void 0,
     eyeMeshNodes: override.eyeMeshNodes ?? base.eyeMeshNodes,
@@ -3519,6 +3620,7 @@ var _Loom3 = class _Loom3 {
     this.auToCompositeMap = buildAUToCompositeMap(this.compositeRotations);
     this.hairPhysics = new HairPhysicsController({
       getMeshByName: (name) => this.meshByName.get(name),
+      getSelectedHairMeshNames: () => this.config.morphToMesh?.hair || [],
       buildClip: (clipName, curves, options) => this.buildClip(clipName, curves, options),
       cleanupSnippet: (name) => this.cleanupSnippet(name)
     });
@@ -3527,6 +3629,7 @@ var _Loom3 = class _Loom3 {
       getMeshes: () => this.meshes,
       getMeshByName: (name) => this.meshByName.get(name),
       getMeshNamesForAU: (auId) => this.getMeshNamesForAU(auId),
+      getMeshNamesForViseme: () => this.getMeshNamesForViseme(),
       getBones: () => this.bones,
       getConfig: () => this.config,
       getCompositeRotations: () => this.compositeRotations,
@@ -3623,7 +3726,8 @@ var _Loom3 = class _Loom3 {
     }
     for (let i = 0; i < (this.config.visemeKeys || []).length; i += 1) {
       const key = this.config.visemeKeys[i];
-      const targets = typeof key === "number" ? this.resolveMorphTargetsByIndex(key) : this.resolveMorphTargets(key);
+      const visemeMeshNames = this.getMeshNamesForViseme();
+      const targets = typeof key === "number" ? this.resolveMorphTargetsByIndex(key, visemeMeshNames) : this.resolveMorphTargets(key, visemeMeshNames);
       this.resolvedVisemeTargets[i] = targets;
     }
   }
@@ -3793,37 +3897,12 @@ var _Loom3 = class _Loom3 {
     }
     const compositeInfo = this.auToCompositeMap.get(id);
     if (compositeInfo) {
-      const storedBalance = this.auBalances[id] ?? 0;
-      const { left: leftVal, right: rightVal } = this.computeSideValues(clamp012(v), storedBalance);
       for (const nodeKey of compositeInfo.nodes) {
         const config = this.compositeRotations.find((c) => c.node === nodeKey);
         if (!config) continue;
         const axisConfig = config[compositeInfo.axis];
         if (!axisConfig) continue;
-        let axisValue;
-        if (axisConfig.negative !== void 0 && axisConfig.positive !== void 0) {
-          const negValue = this.auValues[axisConfig.negative] ?? 0;
-          const posValue = this.auValues[axisConfig.positive] ?? 0;
-          axisValue = posValue - negValue;
-        } else if (axisConfig.aus.length > 1) {
-          axisValue = Math.max(...axisConfig.aus.map((auId) => this.auValues[auId] ?? 0));
-        } else {
-          axisValue = v;
-        }
-        const auBoneBindings = this.config.auToBones[id] || [];
-        const sideByNode = /* @__PURE__ */ new Map();
-        for (const binding of auBoneBindings) {
-          if (binding.side === "left" || binding.side === "right") {
-            sideByNode.set(binding.node, binding.side);
-          }
-        }
-        const side = sideByNode.get(nodeKey);
-        if (side) {
-          const baseValue = clamp012(v);
-          const balanceValue = side === "left" ? leftVal : rightVal;
-          const denom = baseValue > 0 ? baseValue : 1;
-          axisValue = axisValue * (balanceValue / denom);
-        }
+        const axisValue = this.getCompositeAxisValueForNode(nodeKey, axisConfig);
         this.updateBoneRotation(nodeKey, compositeInfo.axis, axisValue);
         this.pendingCompositeNodes.add(nodeKey);
       }
@@ -3851,11 +3930,15 @@ var _Loom3 = class _Loom3 {
       }
     }
     const target = clamp012(to);
+    if (balance !== void 0) {
+      this.auBalances[numId] = balance;
+    }
+    const storedBalance = this.auBalances[numId] ?? 0;
     const { left: leftKeys, right: rightKeys, center: centerKeys } = this.getAUMorphsBySide(numId);
     const bindings = this.config.auToBones[numId] || [];
     const mixWeight = this.isMixedAU(numId) ? this.getAUMixWeight(numId) : 1;
     const base = target * mixWeight;
-    const { left: leftVal, right: rightVal } = this.computeSideValues(base, balance);
+    const { left: leftVal, right: rightVal } = this.computeSideValues(base, storedBalance);
     this.auValues[numId] = target;
     const handles = [];
     const meshNames = this.getMeshNamesForAU(numId);
@@ -3883,16 +3966,7 @@ var _Loom3 = class _Loom3 {
         if (!config) continue;
         const axisConfig = config[compositeInfo.axis];
         if (!axisConfig) continue;
-        let axisValue;
-        if (axisConfig.negative !== void 0 && axisConfig.positive !== void 0) {
-          const negValue = this.auValues[axisConfig.negative] ?? 0;
-          const posValue = this.auValues[axisConfig.positive] ?? 0;
-          axisValue = posValue - negValue;
-        } else if (axisConfig.aus.length > 1) {
-          axisValue = Math.max(...axisConfig.aus.map((auId) => this.auValues[auId] ?? 0));
-        } else {
-          axisValue = target;
-        }
+        const axisValue = this.getCompositeAxisValueForNode(nodeKey, axisConfig);
         handles.push(this.transitionBoneRotation(nodeKey, compositeInfo.axis, axisValue, durationMs));
       }
     }
@@ -4055,10 +4129,11 @@ var _Loom3 = class _Loom3 {
       this.applyMorphTargets(targets, val);
     } else {
       const morphKey = this.config.visemeKeys[visemeIndex];
+      const visemeMeshNames = this.getMeshNamesForViseme();
       if (typeof morphKey === "number") {
-        this.setMorphInfluence(morphKey, val);
+        this.setMorphInfluence(morphKey, val, visemeMeshNames);
       } else if (typeof morphKey === "string") {
-        this.setMorph(morphKey, val);
+        this.setMorph(morphKey, val, visemeMeshNames);
       }
     }
     const jawAmount = _Loom3.VISEME_JAW_AMOUNTS[visemeIndex] * val * jawScale;
@@ -4076,7 +4151,8 @@ var _Loom3 = class _Loom3 {
     const morphKey = this.config.visemeKeys[visemeIndex];
     const target = clamp012(to);
     this.visemeValues[visemeIndex] = target;
-    const morphHandle = typeof morphKey === "number" ? this.transitionMorphInfluence(morphKey, target, durationMs) : this.transitionMorph(morphKey, target, durationMs);
+    const visemeMeshNames = this.getMeshNamesForViseme();
+    const morphHandle = typeof morphKey === "number" ? this.transitionMorphInfluence(morphKey, target, durationMs, visemeMeshNames) : this.transitionMorph(morphKey, target, durationMs, visemeMeshNames);
     const jawAmount = _Loom3.VISEME_JAW_AMOUNTS[visemeIndex] * target * jawScale;
     if (Math.abs(jawScale) <= 1e-6 || Math.abs(jawAmount) <= 1e-6) {
       return morphHandle;
@@ -4380,6 +4456,7 @@ var _Loom3 = class _Loom3 {
     if (this.model) {
       this.rebuildMorphTargetsCache();
     }
+    this.hairPhysics.refreshMeshSelection();
     this.applyHairPhysicsProfileConfig();
   }
   getProfile() {
@@ -4387,20 +4464,24 @@ var _Loom3 = class _Loom3 {
   }
   /**
    * Get the mesh names that should receive morph influences for a given AU.
-   * Routes by facePart: Tongue → tongue, Eye → eye, everything else → face.
+   * Routing is driven by `auFacePartToMeshCategory` in profile config.
    */
   getMeshNamesForAU(auId) {
     const m = this.config.morphToMesh;
     const info = this.config.auInfo?.[String(auId)];
-    if (!info?.facePart) return m?.face || [];
-    switch (info.facePart) {
-      case "Tongue":
-        return m?.tongue || [];
-      case "Eye":
-        return m?.eye || [];
-      default:
-        return m?.face || [];
+    const facePart = info?.facePart;
+    if (facePart) {
+      const category = this.config.auFacePartToMeshCategory?.[facePart];
+      if (category) {
+        return m?.[category] || [];
+      }
     }
+    return m?.face || [];
+  }
+  getMeshNamesForViseme() {
+    const m = this.config.morphToMesh;
+    const category = this.config.visemeMeshCategory || (m?.viseme ? "viseme" : "face");
+    return m?.[category] || m?.face || [];
   }
   // ============================================================================
   // HAIR PHYSICS
@@ -4519,6 +4600,25 @@ var _Loom3 = class _Loom3 {
     const hasMorphs = !!(morphs?.left?.length || morphs?.right?.length || morphs?.center?.length);
     return !!(hasMorphs && this.config.auToBones[id]?.length);
   }
+  getEffectiveBoneAUValue(auId, nodeKey) {
+    const rawValue = clamp012(this.auValues[auId] ?? 0);
+    if (rawValue <= 1e-6) return 0;
+    const binding = this.config.auToBones[auId]?.find((candidate) => candidate.node === nodeKey) ?? null;
+    if (!binding?.side) return rawValue;
+    return rawValue * getSideScale(this.auBalances[auId] ?? 0, binding.side);
+  }
+  getCompositeAxisValueForNode(nodeKey, axisConfig) {
+    return getCompositeAxisValue(axisConfig, (auId) => this.getEffectiveBoneAUValue(auId, nodeKey));
+  }
+  getCompositeAxisBindingForNode(nodeKey, axisConfig, direction) {
+    return getCompositeAxisBinding(
+      nodeKey,
+      axisConfig,
+      direction,
+      (auId) => this.getEffectiveBoneAUValue(auId, nodeKey),
+      this.config.auToBones
+    );
+  }
   initBoneRotations() {
     this.rotations = {};
     this.pendingCompositeNodes.clear();
@@ -4594,30 +4694,10 @@ var _Loom3 = class _Loom3 {
     if (!config) {
       return;
     }
-    const getBindingForAxis = (axisConfig, direction) => {
-      if (!axisConfig) return null;
-      if (axisConfig.negative !== void 0 && axisConfig.positive !== void 0) {
-        const auId = direction < 0 ? axisConfig.negative : axisConfig.positive;
-        return this.config.auToBones[auId]?.find((b) => b.node === nodeKey);
-      }
-      if (axisConfig.aus.length > 1) {
-        let maxAU = axisConfig.aus[0];
-        let maxValue = this.auValues[maxAU] ?? 0;
-        for (const auId of axisConfig.aus) {
-          const val = this.auValues[auId] ?? 0;
-          if (val > maxValue) {
-            maxValue = val;
-            maxAU = auId;
-          }
-        }
-        return this.config.auToBones[maxAU]?.find((b) => b.node === nodeKey);
-      }
-      return this.config.auToBones[axisConfig.aus[0]]?.find((b) => b.node === nodeKey);
-    };
     const getAxis = (channel) => channel === "rx" ? X_AXIS2 : channel === "ry" ? Y_AXIS2 : Z_AXIS2;
     const compositeQ = new THREE.Quaternion().copy(baseQuat);
     if (config.yaw && rotState.yaw !== 0) {
-      const binding = getBindingForAxis(config.yaw, rotState.yaw);
+      const binding = this.getCompositeAxisBindingForNode(nodeKey, config.yaw, rotState.yaw);
       if (binding?.maxDegrees && binding.channel) {
         const radians = deg2rad(binding.maxDegrees) * Math.abs(rotState.yaw) * binding.scale;
         const axis = getAxis(binding.channel);
@@ -4626,7 +4706,7 @@ var _Loom3 = class _Loom3 {
       }
     }
     if (config.pitch && rotState.pitch !== 0) {
-      const binding = getBindingForAxis(config.pitch, rotState.pitch);
+      const binding = this.getCompositeAxisBindingForNode(nodeKey, config.pitch, rotState.pitch);
       if (binding?.maxDegrees && binding.channel) {
         const radians = deg2rad(binding.maxDegrees) * Math.abs(rotState.pitch) * binding.scale;
         const axis = getAxis(binding.channel);
@@ -4635,7 +4715,7 @@ var _Loom3 = class _Loom3 {
       }
     }
     if (config.roll && rotState.roll !== 0) {
-      const binding = getBindingForAxis(config.roll, rotState.roll);
+      const binding = this.getCompositeAxisBindingForNode(nodeKey, config.roll, rotState.roll);
       if (binding?.maxDegrees && binding.channel) {
         const radians = deg2rad(binding.maxDegrees) * Math.abs(rotState.roll) * binding.scale;
         const axis = getAxis(binding.channel);
@@ -5504,7 +5584,7 @@ function findMatches(targetNames, candidateNames, prefix, suffix, suffixPattern)
   return { found, missing };
 }
 function collectAxisConfigs(axisConfigs) {
-  return axisConfigs.filter((entry) => entry.config);
+  return axisConfigs.filter((entry) => entry.config !== null);
 }
 function isEyeNodeKey(nodeKey) {
   return nodeKey === "EYE_L" || nodeKey === "EYE_R";
@@ -5574,28 +5654,35 @@ function validateMappingConfig(config) {
         );
         continue;
       }
-      if (axisConfig.negative !== void 0 && !axisConfig.aus.includes(axisConfig.negative)) {
-        push(
-          "error",
-          "COMPOSITE_AU_MISSING",
-          `Composite axis for "${composite.node}" is missing negative AU ${axisConfig.negative} in aus list`,
-          { node: composite.node, auId: axisConfig.negative }
-        );
+      for (const auId of toAUList(axisConfig.negative)) {
+        if (!axisConfig.aus.includes(auId)) {
+          push(
+            "error",
+            "COMPOSITE_AU_MISSING",
+            `Composite axis for "${composite.node}" is missing negative AU ${auId} in aus list`,
+            { node: composite.node, auId }
+          );
+        }
       }
-      if (axisConfig.positive !== void 0 && !axisConfig.aus.includes(axisConfig.positive)) {
-        push(
-          "error",
-          "COMPOSITE_AU_MISSING",
-          `Composite axis for "${composite.node}" is missing positive AU ${axisConfig.positive} in aus list`,
-          { node: composite.node, auId: axisConfig.positive }
-        );
+      for (const auId of toAUList(axisConfig.positive)) {
+        if (!axisConfig.aus.includes(auId)) {
+          push(
+            "error",
+            "COMPOSITE_AU_MISSING",
+            `Composite axis for "${composite.node}" is missing positive AU ${auId} in aus list`,
+            { node: composite.node, auId }
+          );
+        }
       }
-      if (axisConfig.negative !== void 0 && axisConfig.positive !== void 0 && axisConfig.negative === axisConfig.positive) {
+      const negativeAUs = toAUList(axisConfig.negative);
+      const positiveAUs = toAUList(axisConfig.positive);
+      const overlappingAUs = negativeAUs.filter((auId) => positiveAUs.includes(auId));
+      if (overlappingAUs.length > 0) {
         push(
           "error",
           "COMPOSITE_AU_DUPLICATE",
-          `Composite axis for "${composite.node}" has identical negative/positive AU ${axisConfig.negative}`,
-          { node: composite.node, auId: axisConfig.negative }
+          `Composite axis for "${composite.node}" reuses AU ${overlappingAUs[0]} in both negative and positive groups`,
+          { node: composite.node, auId: overlappingAUs[0] }
         );
       }
     }
@@ -5685,11 +5772,11 @@ function validateMappingConfig(config) {
         );
         continue;
       }
-      const expectedNeg = axisConfig.negative;
-      const expectedPos = axisConfig.positive;
+      const expectedNeg = toAUList(axisConfig.negative);
+      const expectedPos = toAUList(axisConfig.positive);
       const negId = info.isNegative ? Number(auIdStr) : info.pairId;
       const posId = info.isNegative ? info.pairId : Number(auIdStr);
-      if (negId !== expectedNeg || posId !== expectedPos) {
+      if (!expectedNeg.includes(negId) || !expectedPos.includes(posId)) {
         push(
           "warning",
           "CONTINUUM_COMPOSITE_MISMATCH",