loomlarge 1.0.0 → 1.0.1

package/dist/index.cjs

@@ -2,6 +2,8 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var three = require('three');
+
 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);
@@ -243,121 +245,224 @@ var VISEME_KEYS = [
 ];
 var BONE_AU_TO_BINDINGS = {
   // Head turn and tilt (M51-M56) - use HEAD bone only (NECK should not rotate with head)
-  // Three.js Y rotation: positive = counter-clockwise from above = head turns LEFT (character POV)
   51: [
-    { node: "HEAD", channel: "ry", scale: 1, maxDegrees: 30 }
+    { node: "HEAD", channel: "ry", scale: 1, maxDegrees: 30, axis: "yaw" }
     // Head turn left
   ],
   52: [
-    { node: "HEAD", channel: "ry", scale: -1, maxDegrees: 30 }
+    { node: "HEAD", channel: "ry", scale: -1, maxDegrees: 30, axis: "yaw" }
     // Head turn right
   ],
   53: [
-    { node: "HEAD", channel: "rx", scale: -1, maxDegrees: 20 }
+    { node: "HEAD", channel: "rx", scale: -1, maxDegrees: 20, axis: "pitch" }
     // Head up
   ],
   54: [
-    { node: "HEAD", channel: "rx", scale: 1, maxDegrees: 20 }
+    { node: "HEAD", channel: "rx", scale: 1, maxDegrees: 20, axis: "pitch" }
     // Head down
   ],
   55: [
-    { node: "HEAD", channel: "rz", scale: -1, maxDegrees: 15 }
+    { node: "HEAD", channel: "rz", scale: -1, maxDegrees: 15, axis: "roll" }
     // Head tilt left
   ],
   56: [
-    { node: "HEAD", channel: "rz", scale: 1, maxDegrees: 15 }
+    { node: "HEAD", channel: "rz", scale: 1, maxDegrees: 15, axis: "roll" }
     // Head tilt right
   ],
   // Eyes horizontal (yaw) - CC4 rigs use rz for horizontal eye rotation
   61: [
-    { node: "EYE_L", channel: "rz", scale: 1, maxDegrees: 32 },
+    { node: "EYE_L", channel: "rz", scale: 1, maxDegrees: 32, axis: "yaw" },
     // Eyes look left
-    { node: "EYE_R", channel: "rz", scale: 1, maxDegrees: 32 }
+    { node: "EYE_R", channel: "rz", scale: 1, maxDegrees: 32, axis: "yaw" }
   ],
   62: [
-    { node: "EYE_L", channel: "rz", scale: -1, maxDegrees: 32 },
+    { node: "EYE_L", channel: "rz", scale: -1, maxDegrees: 32, axis: "yaw" },
     // Eyes look right
-    { node: "EYE_R", channel: "rz", scale: -1, maxDegrees: 32 }
+    { node: "EYE_R", channel: "rz", scale: -1, maxDegrees: 32, axis: "yaw" }
   ],
   63: [
-    { node: "EYE_L", channel: "rx", scale: -1, maxDegrees: 32 },
-    { node: "EYE_R", channel: "rx", scale: -1, maxDegrees: 32 }
+    { node: "EYE_L", channel: "rx", scale: -1, maxDegrees: 32, axis: "pitch" },
+    // Eyes Up
+    { node: "EYE_R", channel: "rx", scale: -1, maxDegrees: 32, axis: "pitch" }
   ],
   64: [
-    { node: "EYE_L", channel: "rx", scale: 1, maxDegrees: 32 },
-    { node: "EYE_R", channel: "rx", scale: 1, maxDegrees: 32 }
+    { node: "EYE_L", channel: "rx", scale: 1, maxDegrees: 32, axis: "pitch" },
+    // Eyes Down
+    { node: "EYE_R", channel: "rx", scale: 1, maxDegrees: 32, axis: "pitch" }
   ],
   // Single-eye (Left) — horizontal (rz for CC4) and vertical (rx)
-  65: [{ node: "EYE_L", channel: "rz", scale: -1, maxDegrees: 15 }],
-  66: [{ node: "EYE_L", channel: "rz", scale: 1, maxDegrees: 15 }],
-  67: [{ node: "EYE_L", channel: "rx", scale: -1, maxDegrees: 12 }],
-  68: [{ node: "EYE_L", channel: "rx", scale: 1, maxDegrees: 12 }],
+  65: [{ node: "EYE_L", channel: "rz", scale: -1, maxDegrees: 15, axis: "yaw" }],
+  66: [{ node: "EYE_L", channel: "rz", scale: 1, maxDegrees: 15, axis: "yaw" }],
+  67: [{ node: "EYE_L", channel: "rx", scale: -1, maxDegrees: 12, axis: "pitch" }],
+  // Left Eye Up
+  68: [{ node: "EYE_L", channel: "rx", scale: 1, maxDegrees: 12, axis: "pitch" }],
+  // Left Eye Down
   // Single-eye (Right) — horizontal (rz for CC4) and vertical (rx)
-  69: [{ node: "EYE_R", channel: "rz", scale: -1, maxDegrees: 15 }],
-  70: [{ node: "EYE_R", channel: "rz", scale: 1, maxDegrees: 15 }],
-  71: [{ node: "EYE_R", channel: "rx", scale: -1, maxDegrees: 12 }],
-  72: [{ node: "EYE_R", channel: "rx", scale: 1, maxDegrees: 12 }],
+  69: [{ node: "EYE_R", channel: "rz", scale: -1, maxDegrees: 15, axis: "yaw" }],
+  70: [{ node: "EYE_R", channel: "rz", scale: 1, maxDegrees: 15, axis: "yaw" }],
+  71: [{ node: "EYE_R", channel: "rx", scale: -1, maxDegrees: 12, axis: "pitch" }],
+  // Right Eye Up
+  72: [{ node: "EYE_R", channel: "rx", scale: 1, maxDegrees: 12, axis: "pitch" }],
+  // Right Eye Down
   // Jaw / Mouth
   8: [
     // Lips Toward Each Other - slight jaw open helps sell the lip press
-    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 8 }
-    // Small downward rotation (jaw opening slightly)
+    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 8, axis: "roll" }
   ],
   25: [
     // Lips Part — small jaw open
-    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 5.84 }
-    // 73% of 8
+    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 5.84, axis: "roll" }
   ],
   26: [
-    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 28 }
-    // 73% of 20
+    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 28, axis: "roll" }
   ],
   27: [
     // Mouth Stretch — larger jaw open
-    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 32 }
-    // 73% of 25
+    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 32, axis: "roll" }
   ],
   29: [
     { node: "JAW", channel: "tz", scale: -1, maxUnits: 0.02 }
-    // Negative for forward thrust
+    // Translation - no axis needed
   ],
   30: [
     // Jaw Left
-    { node: "JAW", channel: "ry", scale: -1, maxDegrees: 5 }
+    { node: "JAW", channel: "ry", scale: -1, maxDegrees: 5, axis: "yaw" }
   ],
   35: [
     // Jaw Right
-    { node: "JAW", channel: "ry", scale: 1, maxDegrees: 5 }
+    { node: "JAW", channel: "ry", scale: 1, maxDegrees: 5, axis: "yaw" }
   ],
   // Tongue
   19: [
     { node: "TONGUE", channel: "tz", scale: -1, maxUnits: 8e-3 }
+    // Translation - no axis needed
   ],
   37: [
     // Tongue Up
-    { node: "TONGUE", channel: "rz", scale: -1, maxDegrees: 45 }
+    { node: "TONGUE", channel: "rz", scale: -1, maxDegrees: 45, axis: "pitch" }
   ],
   38: [
     // Tongue Down
-    { node: "TONGUE", channel: "rz", scale: 1, maxDegrees: 45 }
+    { node: "TONGUE", channel: "rz", scale: 1, maxDegrees: 45, axis: "pitch" }
   ],
   39: [
     // Tongue Left
-    { node: "TONGUE", channel: "ry", scale: -1, maxDegrees: 10 }
+    { node: "TONGUE", channel: "ry", scale: -1, maxDegrees: 10, axis: "yaw" }
   ],
   40: [
     // Tongue Right
-    { node: "TONGUE", channel: "ry", scale: 1, maxDegrees: 10 }
+    { node: "TONGUE", channel: "ry", scale: 1, maxDegrees: 10, axis: "yaw" }
   ],
   41: [
     // Tongue Tilt Left
-    { node: "TONGUE", channel: "rx", scale: -1, maxDegrees: 20 }
+    { node: "TONGUE", channel: "rx", scale: -1, maxDegrees: 20, axis: "roll" }
   ],
   42: [
     // Tongue Tilt Right
-    { node: "TONGUE", channel: "rx", scale: 1, maxDegrees: 20 }
+    { node: "TONGUE", channel: "rx", scale: 1, maxDegrees: 20, axis: "roll" }
   ]
 };
+var isMixedAU = (id) => !!(AU_TO_MORPHS[id]?.length && BONE_AU_TO_BINDINGS[id]?.length);
+var hasLeftRightMorphs = (auId) => {
+  const keys = AU_TO_MORPHS[auId] || [];
+  return keys.some((k) => /_L$|_R$| L$| R$|Left$|Right$/i.test(k));
+};
+var COMPOSITE_ROTATIONS = [
+  {
+    node: "JAW",
+    pitch: { aus: [25, 26, 27], axis: "rz" },
+    // Jaw drop (opens mouth downward)
+    yaw: { aus: [30, 35], axis: "ry", negative: 30, positive: 35 },
+    // Jaw lateral (left/right)
+    roll: null
+    // Jaw doesn't have roll
+  },
+  {
+    node: "HEAD",
+    pitch: { aus: [54, 53], axis: "rx", negative: 54, positive: 53 },
+    // Head down/up
+    yaw: { aus: [51, 52], axis: "ry", negative: 51, positive: 52 },
+    // Head turn left/right
+    roll: { aus: [55, 56], axis: "rz", negative: 55, positive: 56 }
+    // Head tilt left/right
+  },
+  {
+    node: "EYE_L",
+    pitch: { aus: [64, 63], axis: "rx", negative: 64, positive: 63 },
+    // Eyes down/up
+    yaw: { aus: [61, 62], axis: "rz", negative: 61, positive: 62 },
+    // 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 },
+    // Eyes down/up
+    yaw: { aus: [61, 62], axis: "rz", negative: 61, positive: 62 },
+    // Eyes left/right (rz for CC4)
+    roll: null
+    // Eyes don't have roll
+  },
+  {
+    node: "TONGUE",
+    pitch: { aus: [38, 37], axis: "rz", negative: 38, positive: 37 },
+    // Tongue down/up
+    yaw: { aus: [39, 40], axis: "ry", negative: 39, positive: 40 },
+    // Tongue left/right
+    roll: { aus: [41, 42], axis: "rx", negative: 41, positive: 42 }
+    // Tongue tilt left/right
+  }
+];
+var CONTINUUM_PAIRS_MAP = {
+  // Eyes horizontal (yaw) - both eyes share same AUs
+  61: { pairId: 62, isNegative: true, axis: "yaw", node: "EYE_L" },
+  62: { pairId: 61, isNegative: false, axis: "yaw", node: "EYE_L" },
+  // Eyes vertical (pitch)
+  64: { pairId: 63, isNegative: true, axis: "pitch", node: "EYE_L" },
+  63: { pairId: 64, isNegative: false, axis: "pitch", node: "EYE_L" },
+  // Head yaw (turn left/right)
+  51: { pairId: 52, isNegative: true, axis: "yaw", node: "HEAD" },
+  52: { pairId: 51, isNegative: false, axis: "yaw", node: "HEAD" },
+  // Head pitch (up/down)
+  54: { pairId: 53, isNegative: true, axis: "pitch", node: "HEAD" },
+  53: { pairId: 54, isNegative: false, axis: "pitch", node: "HEAD" },
+  // Head roll (tilt left/right)
+  55: { pairId: 56, isNegative: true, axis: "roll", node: "HEAD" },
+  56: { pairId: 55, isNegative: false, axis: "roll", node: "HEAD" },
+  // Jaw yaw (left/right)
+  30: { pairId: 35, isNegative: true, axis: "yaw", node: "JAW" },
+  35: { pairId: 30, isNegative: false, axis: "yaw", node: "JAW" },
+  // Tongue yaw (left/right)
+  39: { pairId: 40, isNegative: true, axis: "yaw", node: "TONGUE" },
+  40: { pairId: 39, isNegative: false, axis: "yaw", node: "TONGUE" },
+  // Tongue pitch (up/down)
+  38: { pairId: 37, isNegative: true, axis: "pitch", node: "TONGUE" },
+  37: { pairId: 38, isNegative: false, axis: "pitch", node: "TONGUE" },
+  // Tongue roll (tilt left/right)
+  41: { pairId: 42, isNegative: true, axis: "roll", node: "TONGUE" },
+  42: { pairId: 41, isNegative: false, axis: "roll", node: "TONGUE" },
+  // Extended tongue morphs (continuum pairs)
+  73: { pairId: 74, isNegative: true, axis: "yaw", node: "TONGUE" },
+  // Tongue Narrow/Wide
+  74: { pairId: 73, isNegative: false, axis: "yaw", node: "TONGUE" },
+  76: { pairId: 77, isNegative: false, axis: "pitch", node: "TONGUE" },
+  // Tongue Tip Up/Down
+  77: { pairId: 76, isNegative: true, axis: "pitch", node: "TONGUE" }
+};
+var CONTINUUM_LABELS = {
+  "61-62": "Eyes \u2014 Horizontal",
+  "64-63": "Eyes \u2014 Vertical",
+  "51-52": "Head \u2014 Horizontal",
+  "54-53": "Head \u2014 Vertical",
+  "55-56": "Head \u2014 Tilt",
+  "30-35": "Jaw \u2014 Horizontal",
+  "38-37": "Tongue \u2014 Vertical",
+  "39-40": "Tongue \u2014 Horizontal",
+  "41-42": "Tongue \u2014 Tilt",
+  "73-74": "Tongue \u2014 Width",
+  "76-77": "Tongue Tip \u2014 Vertical"
+};
 var CC4_BONE_NODES = {
   EYE_L: "CC_Base_L_Eye",
   EYE_R: "CC_Base_R_Eye",
@@ -490,6 +595,41 @@ var AU_MIX_DEFAULTS = {
   35: 0.5
   // jaw left/right
 };
+var CC4_MESHES = {
+  // Body (6 meshes, 80 morphs each) - default render order 0
+  "CC_Base_Body_1": { category: "body", morphCount: 80 },
+  "CC_Base_Body_2": { category: "body", morphCount: 80 },
+  "CC_Base_Body_3": { category: "body", morphCount: 80 },
+  "CC_Base_Body_4": { category: "body", morphCount: 80 },
+  "CC_Base_Body_5": { category: "body", morphCount: 80 },
+  "CC_Base_Body_6": { category: "body", morphCount: 80 },
+  // Eyes (bone-driven, no morphs) - render first (behind everything)
+  "CC_Base_Eye": { category: "eye", morphCount: 0, material: { renderOrder: -10 } },
+  "CC_Base_Eye_1": { category: "eye", morphCount: 0, material: { renderOrder: -10 } },
+  "CC_Base_Eye_2": { category: "eye", morphCount: 0, material: { renderOrder: -10 } },
+  "CC_Base_Eye_3": { category: "eye", morphCount: 0, material: { renderOrder: -10 } },
+  "CC_Base_Eye_4": { category: "eye", morphCount: 0, material: { renderOrder: -10 } },
+  // Eye occlusion (94 morphs each) - render on top of eyes with transparency support
+  "CC_Base_EyeOcclusion_1": { category: "eyeOcclusion", morphCount: 94, material: { renderOrder: 2, transparent: true, opacity: 1, depthWrite: true, depthTest: true, blending: "Normal" } },
+  "CC_Base_EyeOcclusion_2": { category: "eyeOcclusion", morphCount: 94, material: { renderOrder: 2, transparent: true, opacity: 1, depthWrite: true, depthTest: true, blending: "Normal" } },
+  // Tear lines (90 morphs each) - on top of eyes/face
+  "CC_Base_TearLine_1": { category: "tearLine", morphCount: 90, material: { renderOrder: 2 } },
+  "CC_Base_TearLine_2": { category: "tearLine", morphCount: 90, material: { renderOrder: 2 } },
+  // Cornea (no morphs) - render first with eyes
+  "CC_Base_Cornea": { category: "cornea", morphCount: 0, material: { renderOrder: -10 } },
+  "CC_Base_Cornea_1": { category: "cornea", morphCount: 0, material: { renderOrder: -10 } },
+  // Teeth (no morphs, follow jaw bone) - default render order
+  "CC_Base_Teeth_1": { category: "teeth", morphCount: 0 },
+  "CC_Base_Teeth_2": { category: "teeth", morphCount: 0 },
+  // Tongue (23 morphs) - default render order
+  "CC_Base_Tongue": { category: "tongue", morphCount: 23 },
+  // Eyebrows (91 morphs each) - above face
+  "Male_Bushy_1": { category: "eyebrow", morphCount: 91, material: { renderOrder: 5 } },
+  "Male_Bushy_2": { category: "eyebrow", morphCount: 91, material: { renderOrder: 5 } },
+  // Hair (14 styling morphs each) - render last (on top of everything)
+  "Side_part_wavy_1": { category: "hair", morphCount: 14, material: { renderOrder: 10 } },
+  "Side_part_wavy_2": { category: "hair", morphCount: 14, material: { renderOrder: 10 } }
+};
 var MORPH_TO_MESH = {
   // Face/AU morphs affect the main face mesh and both eyebrow meshes.
   face: ["CC_Base_Body_1", "Male_Bushy_1", "Male_Bushy_2"],
@@ -541,6 +681,10 @@ var _LoomLargeThree = class _LoomLargeThree {
     __publicField(this, "mixWeights", {});
     // Viseme state
     __publicField(this, "visemeValues", new Array(15).fill(0));
+    // Internal RAF loop
+    __publicField(this, "clock", new three.Clock());
+    __publicField(this, "rafId", null);
+    __publicField(this, "running", false);
     this.config = config.auMappings || CC4_PRESET;
     this.mixWeights = { ...this.config.auMixDefaults };
     this.animation = animation || new AnimationThree();
@@ -577,6 +721,7 @@ var _LoomLargeThree = class _LoomLargeThree {
     this.rigReady = true;
     this.missingBoneWarnings.clear();
     this.initBoneRotations();
+    this.applyMeshMaterialSettings(model);
   }
   update(deltaSeconds) {
     const dtSeconds = Math.max(0, deltaSeconds || 0);
@@ -584,7 +729,30 @@ var _LoomLargeThree = class _LoomLargeThree {
     this.animation.tick(dtSeconds);
     this.flushPendingComposites();
   }
+  /** Start the internal RAF loop */
+  start() {
+    if (this.running) return;
+    this.running = true;
+    this.clock.start();
+    const tick = () => {
+      if (!this.running) return;
+      const dt = this.clock.getDelta();
+      this.update(dt);
+      this.rafId = requestAnimationFrame(tick);
+    };
+    this.rafId = requestAnimationFrame(tick);
+  }
+  /** Stop the internal RAF loop */
+  stop() {
+    this.running = false;
+    if (this.rafId !== null) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+    this.clock.stop();
+  }
   dispose() {
+    this.stop();
     this.clearTransitions();
     this.meshes = [];
     this.model = null;
@@ -633,8 +801,9 @@ var _LoomLargeThree = class _LoomLargeThree {
     if (bindings) {
       for (const binding of bindings) {
         if (binding.channel === "rx" || binding.channel === "ry" || binding.channel === "rz") {
-          const axis = binding.channel === "rx" ? "pitch" : binding.channel === "ry" ? "yaw" : "roll";
-          this.updateBoneRotation(binding.node, axis, v * binding.scale, binding.maxDegrees ?? 0);
+          if (binding.axis) {
+            this.updateBoneRotation(binding.node, binding.axis, v * binding.scale, binding.maxDegrees ?? 0);
+          }
         } else if (binding.channel === "tx" || binding.channel === "ty" || binding.channel === "tz") {
           if (binding.maxUnits !== void 0) {
             this.updateBoneTranslation(binding.node, binding.channel, v * binding.scale, binding.maxUnits);
@@ -672,8 +841,9 @@ var _LoomLargeThree = class _LoomLargeThree {
     }
     for (const binding of bindings) {
       if (binding.channel === "rx" || binding.channel === "ry" || binding.channel === "rz") {
-        const axis = binding.channel === "rx" ? "pitch" : binding.channel === "ry" ? "yaw" : "roll";
-        handles.push(this.transitionBoneRotation(binding.node, axis, target * binding.scale, binding.maxDegrees ?? 0, durationMs));
+        if (binding.axis) {
+          handles.push(this.transitionBoneRotation(binding.node, binding.axis, target * binding.scale, binding.maxDegrees ?? 0, durationMs));
+        }
       } else if (binding.channel === "tx" || binding.channel === "ty" || binding.channel === "tz") {
         if (binding.maxUnits !== void 0) {
           handles.push(this.transitionBoneTranslation(binding.node, binding.channel, target * binding.scale, binding.maxUnits, durationMs));
@@ -685,11 +855,16 @@ var _LoomLargeThree = class _LoomLargeThree {
   getAU(id) {
     return this.auValues[id] ?? 0;
   }
-  // ============================================================================
-  // MORPH CONTROL
-  // ============================================================================
-  setMorph(key, v, meshNames) {
+  setMorph(key, v, meshNamesOrTargets) {
     const val = clamp01(v);
+    if (Array.isArray(meshNamesOrTargets) && meshNamesOrTargets.length > 0 && typeof meshNamesOrTargets[0] === "object" && "infl" in meshNamesOrTargets[0]) {
+      const targets2 = meshNamesOrTargets;
+      for (const target of targets2) {
+        target.infl[target.idx] = val;
+      }
+      return;
+    }
+    const meshNames = meshNamesOrTargets;
     const targetMeshes = meshNames || this.config.morphToMesh?.face || [];
     const cached = this.morphCache.get(key);
     if (cached) {
@@ -728,11 +903,54 @@ var _LoomLargeThree = class _LoomLargeThree {
       this.morphCache.set(key, targets);
     }
   }
+  /**
+   * Resolve morph key to direct targets for ultra-fast repeated access.
+   * Use this when you need to set the same morph many times (e.g., in animation loops).
+   */
+  resolveMorphTargets(key, meshNames) {
+    const cached = this.morphCache.get(key);
+    if (cached) return cached;
+    const targetMeshes = meshNames || this.config.morphToMesh?.face || [];
+    const targets = [];
+    if (targetMeshes.length) {
+      for (const name of targetMeshes) {
+        const mesh = this.meshByName.get(name);
+        if (!mesh) continue;
+        const dict = mesh.morphTargetDictionary;
+        const infl = mesh.morphTargetInfluences;
+        if (!dict || !infl) continue;
+        const idx = dict[key];
+        if (idx !== void 0) {
+          targets.push({ infl, idx });
+        }
+      }
+    } else {
+      for (const mesh of this.meshes) {
+        const dict = mesh.morphTargetDictionary;
+        const infl = mesh.morphTargetInfluences;
+        if (!dict || !infl) continue;
+        const idx = dict[key];
+        if (idx !== void 0) {
+          targets.push({ infl, idx });
+        }
+      }
+    }
+    if (targets.length > 0) {
+      this.morphCache.set(key, targets);
+    }
+    return targets;
+  }
   transitionMorph(key, to, durationMs = 120, meshNames) {
     const transitionKey = `morph_${key}`;
     const from = this.getMorphValue(key);
     const target = clamp01(to);
-    return this.animation.addTransition(transitionKey, from, target, durationMs, (value) => this.setMorph(key, value, meshNames));
+    const targets = this.resolveMorphTargets(key, meshNames);
+    return this.animation.addTransition(transitionKey, from, target, durationMs, (value) => {
+      const val = clamp01(value);
+      for (const t of targets) {
+        t.infl[t.idx] = val;
+      }
+    });
   }
   // ============================================================================
   // VISEME CONTROL
@@ -835,6 +1053,33 @@ var _LoomLargeThree = class _LoomLargeThree {
     });
     return result;
   }
+  /** Get all morph targets grouped by mesh name */
+  getMorphTargets() {
+    const result = {};
+    for (const mesh of this.meshes) {
+      const dict = mesh.morphTargetDictionary;
+      if (dict) {
+        result[mesh.name] = Object.keys(dict).sort();
+      }
+    }
+    return result;
+  }
+  /** Get all resolved bone names and their current transforms */
+  getBones() {
+    const result = {};
+    for (const name of Object.keys(this.bones)) {
+      const entry = this.bones[name];
+      if (entry) {
+        const pos = entry.obj.position;
+        const rot = entry.obj.rotation;
+        result[name] = {
+          position: [pos.x, pos.y, pos.z],
+          rotation: [rot.x * 180 / Math.PI, rot.y * 180 / Math.PI, rot.z * 180 / Math.PI]
+        };
+      }
+    }
+    return result;
+  }
   setMeshVisible(meshName, visible) {
     if (!this.model) return;
     this.model.traverse((obj) => {
@@ -843,6 +1088,70 @@ var _LoomLargeThree = class _LoomLargeThree {
       }
     });
   }
+  /** Get material config for a mesh */
+  getMeshMaterialConfig(meshName) {
+    if (!this.model) return null;
+    let result = null;
+    this.model.traverse((obj) => {
+      if (obj.isMesh && obj.name === meshName) {
+        const mat = obj.material;
+        if (mat) {
+          let blendingName = "Normal";
+          for (const [name, value] of Object.entries(_LoomLargeThree.BLENDING_MODES)) {
+            if (mat.blending === value) {
+              blendingName = name;
+              break;
+            }
+          }
+          result = {
+            renderOrder: obj.renderOrder,
+            transparent: mat.transparent,
+            opacity: mat.opacity,
+            depthWrite: mat.depthWrite,
+            depthTest: mat.depthTest,
+            blending: blendingName
+          };
+        }
+      }
+    });
+    return result;
+  }
+  /** Set material config for a mesh */
+  setMeshMaterialConfig(meshName, config) {
+    if (!this.model) return;
+    this.model.traverse((obj) => {
+      if (obj.isMesh && obj.name === meshName) {
+        const mat = obj.material;
+        if (config.renderOrder !== void 0) {
+          obj.renderOrder = config.renderOrder;
+        }
+        if (mat) {
+          if (config.opacity !== void 0) {
+            mat.opacity = config.opacity;
+            if (config.opacity < 1 && config.transparent === void 0) {
+              mat.transparent = true;
+            }
+          }
+          if (config.transparent !== void 0) {
+            mat.transparent = config.transparent;
+          }
+          if (config.depthWrite !== void 0) {
+            mat.depthWrite = config.depthWrite;
+          }
+          if (config.depthTest !== void 0) {
+            mat.depthTest = config.depthTest;
+          }
+          if (config.blending !== void 0) {
+            const blendValue = _LoomLargeThree.BLENDING_MODES[config.blending];
+            if (blendValue !== void 0) {
+              mat.blending = blendValue;
+            }
+          }
+          mat.needsUpdate = true;
+        }
+      }
+    });
+  }
   // ============================================================================
   // CONFIGURATION
   // ============================================================================
@@ -1008,6 +1317,42 @@ var _LoomLargeThree = class _LoomLargeThree {
       cancel: () => handles.forEach((h) => h.cancel())
     };
   }
+  /**
+   * Apply render order and material settings from CC4_MESHES to all meshes.
+   * This ensures proper layering (e.g., hair renders on top of eyebrows).
+   */
+  applyMeshMaterialSettings(root) {
+    root.traverse((obj) => {
+      if (!obj.isMesh || !obj.name) return;
+      const meshInfo = CC4_MESHES[obj.name];
+      if (!meshInfo?.material) return;
+      const settings = meshInfo.material;
+      if (typeof settings.renderOrder === "number") {
+        obj.renderOrder = settings.renderOrder;
+      }
+      if (obj.material) {
+        if (typeof settings.transparent === "boolean") {
+          obj.material.transparent = settings.transparent;
+        }
+        if (typeof settings.opacity === "number") {
+          obj.material.opacity = settings.opacity;
+        }
+        if (typeof settings.depthWrite === "boolean") {
+          obj.material.depthWrite = settings.depthWrite;
+        }
+        if (typeof settings.depthTest === "boolean") {
+          obj.material.depthTest = settings.depthTest;
+        }
+        if (typeof settings.blending === "string") {
+          const blendValue = _LoomLargeThree.BLENDING_MODES[settings.blending];
+          if (blendValue !== void 0) {
+            obj.material.blending = blendValue;
+          }
+        }
+        obj.material.needsUpdate = true;
+      }
+    });
+  }
 };
 // Viseme jaw amounts
 __publicField(_LoomLargeThree, "VISEME_JAW_AMOUNTS", [
@@ -1028,6 +1373,19 @@ __publicField(_LoomLargeThree, "VISEME_JAW_AMOUNTS", [
   0.4
 ]);
 __publicField(_LoomLargeThree, "JAW_MAX_DEGREES", 28);
+/** Blending mode options for Three.js materials */
+__publicField(_LoomLargeThree, "BLENDING_MODES", {
+  "Normal": 1,
+  // THREE.NormalBlending
+  "Additive": 2,
+  // THREE.AdditiveBlending
+  "Subtractive": 3,
+  // THREE.SubtractiveBlending
+  "Multiply": 4,
+  // THREE.MultiplyBlending
+  "None": 0
+  // THREE.NoBlending
+});
 var LoomLargeThree = _LoomLargeThree;
 function collectMorphMeshes(root) {
   const meshes = [];
@@ -1041,6 +1399,20 @@ function collectMorphMeshes(root) {
   return meshes;
 }
 
+// src/mappings/types.ts
+var BLENDING_MODES = {
+  "Normal": 1,
+  // THREE.NormalBlending
+  "Additive": 2,
+  // THREE.AdditiveBlending
+  "Subtractive": 3,
+  // THREE.SubtractiveBlending
+  "Multiply": 4,
+  // THREE.MultiplyBlending
+  "None": 0
+  // THREE.NoBlending
+};
+
 // src/physics/HairPhysics.ts
 var DEFAULT_HAIR_PHYSICS_CONFIG = {
   mass: 1,
@@ -1165,12 +1537,27 @@ var HairPhysics = class {
   }
 };
 
+exports.AU_INFO = AU_INFO;
+exports.AU_MIX_DEFAULTS = AU_MIX_DEFAULTS;
+exports.AU_TO_MORPHS = AU_TO_MORPHS;
 exports.AnimationThree = AnimationThree;
+exports.BLENDING_MODES = BLENDING_MODES;
+exports.BONE_AU_TO_BINDINGS = BONE_AU_TO_BINDINGS;
+exports.CC4_BONE_NODES = CC4_BONE_NODES;
+exports.CC4_EYE_MESH_NODES = CC4_EYE_MESH_NODES;
+exports.CC4_MESHES = CC4_MESHES;
 exports.CC4_PRESET = CC4_PRESET;
+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.HairPhysics = HairPhysics;
 exports.LoomLargeThree = LoomLargeThree;
+exports.MORPH_TO_MESH = MORPH_TO_MESH;
+exports.VISEME_KEYS = VISEME_KEYS;
 exports.collectMorphMeshes = collectMorphMeshes;
 exports.default = LoomLargeThree;
+exports.hasLeftRightMorphs = hasLeftRightMorphs;
+exports.isMixedAU = isMixedAU;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map