@lovelace_lol/loom3 1.0.39 → 1.0.41

package/README.md

@@ -15,7 +15,7 @@ Loom3 provides mappings that connect [Facial Action Coding System (FACS)](https:
 
 Loom3 is broader than a face-controller wrapper. The library spans four practical areas:
 - Runtime control: Action Units, visemes, direct morphs, continuum pairs, composite rotations, transitions, and mixer playback.
-- Rig configuration: built-in presets, profile overrides, preset resolution, name resolution, viseme routing, mix weights, and skeletal-only preset support.
+- Rig configuration: built-in presets, profile overrides, preset lookup and extension, name resolution, viseme routing, mix weights, and skeletal-only preset support.
 - Inspection and validation: mesh, morph, and bone discovery; preset-fit checks; correction suggestions; and full model analysis.
 - Runtime tooling: mesh/material debugging, baked animation clip helpers, hair physics, and region/geometry helpers for annotation or camera tooling.
 
@@ -366,7 +366,7 @@ For the current runtime-oriented documentation, including:
 - `cameraOffset`
 - `style.lineDirection`
 - the difference between `cameraAngle: 0` and omitting `cameraAngle`
-- the current LoomLarge runtime note that annotations have not been moved from the demo project into Loom3 yet
+- runtime compatibility and legacy `config.regions` fallback behavior
 
 see [ANNOTATION_CONFIGURATION.md](./ANNOTATION_CONFIGURATION.md).
 
@@ -380,7 +380,7 @@ Open in LoomLarge: [Properties tab](https://www.characterloom.com/?drawer=open&t
 
 Before you tune AUs or hand-edit a profile, confirm that you picked the right preset and that the model actually matches it. Loom3 exposes a full preset-selection and validation workflow, not just low-level control APIs.
 
-### Resolving presets by type
+### Looking Up and Extending Presets by Type
 
 Use preset helpers when you want a stable entry point by model class instead of importing a preset constant directly:
 
@@ -1356,6 +1356,25 @@ const targets = loom.resolveMorphTargets('Mouth_Smile_L', ['CC_Base_Body']);
 const value = targets.length > 0 ? (targets[0].infl[targets[0].idx] ?? 0) : 0;
 ```
 
+### Adding runtime morph targets
+
+Generated or sidecar morph targets can be registered after a model loads. Deltas use the same relative `POSITION` format as glTF morph targets: one XYZ delta per base mesh vertex. Optional `normal` and `tangent` deltas can be supplied when available.
+
+```typescript
+const index = loom.addMorphTarget({
+  meshName: 'CC_Base_Body',
+  name: 'BodyType_Muscular',
+  position: bodyTypeMuscularDeltas,
+});
+
+loom.setMorphInfluence(index, 0.6, ['CC_Base_Body']);
+loom.setMorph('BodyType_Muscular', 0.6, ['CC_Base_Body']);
+```
+
+By default, Loom3 replaces and disposes the mesh `BufferGeometry` before appending morph attributes. This is intentional: Three.js does not support mutating `geometry.morphAttributes` in place after a geometry has rendered. For pre-render authoring paths, pass `{ forceGeometryReplacement: false }`.
+
+If you need a named slot before real deltas are available, use `ensureMorphInfluence(meshName, morphName)`. It creates a zero-delta target and returns the assigned `morphTargetInfluences` index. After external code changes morph dictionaries or geometry, call `refreshMorphTargets()` so AU, viseme, hair, and clip-building caches see the updated targets.
+
 ### Morph caching
 
 Loom3 caches morph target lookups for performance. The first time you access a morph, it searches all meshes and caches the index. Subsequent accesses are O(1).
@@ -2128,6 +2147,7 @@ This is a compact reference for the public surface exported by `@lovelace_lol/lo
 - Lifecycle: `onReady()`, `update()`, `start()`, `stop()`, `dispose()`.
 - Preset state: `setProfile()`, `getProfile()`.
 - Control APIs: `setAU()`, `transitionAU()`, `setContinuum()`, `transitionContinuum()`, `setMorph()`, `transitionMorph()`, `setViseme()`, `transitionViseme()`.
+- Runtime morph authoring: `addMorphTarget()`, `addMorphTargets()`, `ensureMorphInfluence()`, `refreshMorphTargets()`.
 - Transition state: `pause()`, `resume()`, `getPaused()`, `clearTransitions()`, `getActiveTransitionCount()`, `resetToNeutral()`.
 
 ### Presets and profiles

package/dist/index.cjs

@@ -3573,7 +3573,7 @@ var mergeAnnotationRegion = (base, override) => {
   merged.meshes = override.meshes ? [...override.meshes] : base.meshes ? [...base.meshes] : void 0;
   merged.objects = override.objects ? [...override.objects] : base.objects ? [...base.objects] : void 0;
   merged.children = override.children ? [...override.children] : base.children ? [...base.children] : void 0;
-  merged.cameraOffset = override.cameraOffset ? { ...override.cameraOffset } : base.cameraOffset ? { ...base.cameraOffset } : void 0;
+  merged.cameraOffset = override.cameraOffset ? { ...base.cameraOffset, ...override.cameraOffset } : base.cameraOffset ? { ...base.cameraOffset } : void 0;
   merged.style = override.style ? {
     ...base.style,
     ...override.style,
@@ -4638,11 +4638,7 @@ var _Loom3 = class _Loom3 {
     this.morphIndexCache.clear();
     model.traverse((obj) => {
       if (obj.isMesh && obj.name) {
-        const infl = obj.morphTargetInfluences;
-        const dict = obj.morphTargetDictionary;
-        if (Array.isArray(infl) && infl.length > 0 || dict && Object.keys(dict).length > 0) {
-          this.meshByName.set(obj.name, obj);
-        }
+        this.meshByName.set(obj.name, obj);
       }
     });
     this.bones = this.resolveBones(model);
@@ -5010,6 +5006,58 @@ var _Loom3 = class _Loom3 {
     const currentContinuum = currentPos - currentNeg;
     return this.animation.addTransition(driverKey, currentContinuum, target, durationMs, (value) => this.setContinuum(negAU, posAU, value, balance));
   }
+  // ============================================================================
+  // MORPH CONTROL
+  // ============================================================================
+  addMorphTarget(target, options = {}) {
+    const staleMorphTargets = this.collectResolvedExpressionMorphTargets();
+    const index = this.applyMorphTargetDelta(target, options);
+    this.refreshMorphTargets([target.meshName]);
+    this.reinitializeRuntimeStateFromCurrentControls(staleMorphTargets);
+    return index;
+  }
+  addMorphTargets(targets, options = {}) {
+    const staleMorphTargets = this.collectResolvedExpressionMorphTargets();
+    const result = {};
+    for (const target of targets) {
+      const index = this.applyMorphTargetDelta(target, options);
+      result[`${target.meshName}:${target.name}`] = index;
+    }
+    this.refreshMorphTargets(Array.from(new Set(targets.map((target) => target.meshName))));
+    this.reinitializeRuntimeStateFromCurrentControls(staleMorphTargets);
+    return result;
+  }
+  ensureMorphInfluence(meshName, morphName) {
+    const mesh = this.requireNamedMesh(meshName);
+    const dict = this.getMeshMorphDictionary(mesh);
+    const existing = dict[morphName];
+    if (existing !== void 0) return existing;
+    const position = mesh.geometry.getAttribute("position");
+    if (!position) {
+      throw new Error(`Cannot create morph target "${morphName}" on mesh "${meshName}": geometry has no position attribute.`);
+    }
+    return this.addMorphTarget({
+      meshName,
+      name: morphName,
+      position: new Float32Array(position.count * position.itemSize),
+      relative: true
+    });
+  }
+  refreshMorphTargets(_meshNames) {
+    this.morphKeyCache.clear();
+    this.morphIndexCache.clear();
+    if (this.model) {
+      this.meshByName.clear();
+      this.model.traverse((obj) => {
+        if (obj.isMesh && obj.name) {
+          this.meshByName.set(obj.name, obj);
+        }
+      });
+      this.meshes = collectMorphMeshes(this.model);
+    }
+    this.rebuildMorphTargetsCache();
+    this.hairPhysics.refreshMeshSelection();
+  }
   setMorph(key, v, meshNamesOrTargets) {
     const val = clamp012(v);
     if (Array.isArray(meshNamesOrTargets) && meshNamesOrTargets.length > 0 && typeof meshNamesOrTargets[0] === "object" && "infl" in meshNamesOrTargets[0]) {
@@ -5628,6 +5676,148 @@ var _Loom3 = class _Loom3 {
     }
     return 0;
   }
+  applyMorphTargetDelta(target, options) {
+    const mesh = this.requireNamedMesh(target.meshName);
+    const sourceGeometry = mesh.geometry;
+    const position = sourceGeometry.getAttribute("position");
+    if (!position) {
+      throw new Error(`Cannot add morph target "${target.name}" to mesh "${target.meshName}": geometry has no position attribute.`);
+    }
+    if (!target.name || !target.name.trim()) {
+      throw new Error(`Cannot add morph target to mesh "${target.meshName}": target name is required.`);
+    }
+    const replace = options.replace === true;
+    const resetInfluence = options.resetInfluence !== false;
+    const forceGeometryReplacement = options.forceGeometryReplacement !== false;
+    const previousInfluences = mesh.morphTargetInfluences ? [...mesh.morphTargetInfluences] : [];
+    const previousDictionary = this.getMeshMorphDictionary(mesh);
+    const existingIndex = previousDictionary[target.name];
+    if (existingIndex !== void 0 && !replace) {
+      throw new Error(`Morph target "${target.name}" already exists on mesh "${target.meshName}". Pass replace: true to overwrite it.`);
+    }
+    const geometry = forceGeometryReplacement ? sourceGeometry.clone() : sourceGeometry;
+    const dictionary = { ...previousDictionary };
+    const usedIndices = Object.values(dictionary).filter(Number.isInteger);
+    const existingAttributeTargetCount = Math.max(
+      0,
+      ...Object.values(geometry.morphAttributes).map((attributes) => attributes?.length ?? 0)
+    );
+    const nextIndex = Math.max(existingAttributeTargetCount, usedIndices.length ? Math.max(...usedIndices) + 1 : 0);
+    const index = existingIndex ?? nextIndex;
+    dictionary[target.name] = index;
+    this.setMorphAttributeAtIndex(geometry, "position", target.position, position.itemSize, position.count, index, target.name);
+    const normal = geometry.getAttribute("normal");
+    if (target.normal) {
+      this.setMorphAttributeAtIndex(geometry, "normal", target.normal, normal?.itemSize ?? 3, position.count, index, target.name);
+    } else {
+      this.setZeroMorphAttributeAtIndex(geometry, "normal", normal?.itemSize ?? 3, position.count, index, target.name);
+    }
+    const tangent = geometry.getAttribute("tangent");
+    if (target.tangent) {
+      this.setMorphAttributeAtIndex(geometry, "tangent", target.tangent, tangent?.itemSize ?? 4, position.count, index, target.name);
+    } else {
+      this.setZeroMorphAttributeAtIndex(geometry, "tangent", tangent?.itemSize ?? 4, position.count, index, target.name);
+    }
+    const color = geometry.getAttribute("color");
+    const existingColorMorph = geometry.morphAttributes.color?.find(Boolean);
+    this.setZeroMorphAttributeAtIndex(
+      geometry,
+      "color",
+      color?.itemSize ?? existingColorMorph?.itemSize ?? 3,
+      position.count,
+      index,
+      target.name
+    );
+    geometry.morphTargetsRelative = target.relative !== false;
+    geometry.morphTargetDictionary = dictionary;
+    if (forceGeometryReplacement) {
+      mesh.geometry = geometry;
+      sourceGeometry.dispose();
+    }
+    const influenceLength = Math.max(previousInfluences.length, index + 1);
+    const influences = previousInfluences.slice(0, influenceLength);
+    while (influences.length < influenceLength) {
+      influences.push(0);
+    }
+    if (resetInfluence) {
+      influences[index] = 0;
+    }
+    mesh.morphTargetDictionary = dictionary;
+    mesh.morphTargetInfluences = influences;
+    this.addRuntimeMorphMesh(mesh);
+    if (!this.config.morphToMesh?.face?.length) {
+      this.config.morphToMesh = {
+        ...this.config.morphToMesh,
+        face: [mesh.name]
+      };
+    }
+    return index;
+  }
+  requireNamedMesh(meshName) {
+    const mesh = this.meshByName.get(meshName);
+    if (mesh) return mesh;
+    if (this.model) {
+      let found = null;
+      this.model.traverse((obj) => {
+        if (!found && obj.isMesh && obj.name === meshName) {
+          found = obj;
+        }
+      });
+      if (found) {
+        this.meshByName.set(meshName, found);
+        return found;
+      }
+    }
+    throw new Error(`Mesh "${meshName}" was not found in the current model.`);
+  }
+  getMeshMorphDictionary(mesh) {
+    const meshDictionary = mesh.morphTargetDictionary;
+    const geometryDictionary = mesh.geometry.morphTargetDictionary;
+    const dictionary = meshDictionary || geometryDictionary || {};
+    mesh.morphTargetDictionary = dictionary;
+    mesh.geometry.morphTargetDictionary = dictionary;
+    return dictionary;
+  }
+  setMorphAttributeAtIndex(geometry, semantic, data, itemSize, vertexCount, index, name) {
+    const expectedLength = vertexCount * itemSize;
+    if (data.length !== expectedLength) {
+      throw new Error(
+        `Morph target "${name}" ${semantic} data has ${data.length} values; expected ${expectedLength} (${vertexCount} vertices * itemSize ${itemSize}).`
+      );
+    }
+    const attributes = geometry.morphAttributes[semantic] ? [...geometry.morphAttributes[semantic]] : [];
+    while (attributes.length < index) {
+      const empty = new THREE2.BufferAttribute(new Float32Array(expectedLength), itemSize);
+      empty.name = `morph_${attributes.length}`;
+      attributes.push(empty);
+    }
+    const values = data instanceof Float32Array ? new Float32Array(data) : Float32Array.from(data);
+    const attribute = new THREE2.BufferAttribute(values, itemSize);
+    attribute.name = name;
+    attributes[index] = attribute;
+    geometry.morphAttributes[semantic] = attributes;
+  }
+  setZeroMorphAttributeAtIndex(geometry, semantic, itemSize, vertexCount, index, name) {
+    if (!geometry.morphAttributes[semantic]?.length) return;
+    const expectedLength = vertexCount * itemSize;
+    const attributes = [...geometry.morphAttributes[semantic]];
+    while (attributes.length < index) {
+      const empty2 = new THREE2.BufferAttribute(new Float32Array(expectedLength), itemSize);
+      empty2.name = `morph_${attributes.length}`;
+      attributes.push(empty2);
+    }
+    const empty = new THREE2.BufferAttribute(new Float32Array(expectedLength), itemSize);
+    empty.name = name;
+    attributes[index] = empty;
+    geometry.morphAttributes[semantic] = attributes;
+  }
+  addRuntimeMorphMesh(mesh) {
+    const key = mesh.name || mesh.uuid;
+    const exists = this.meshes.some((candidate) => (candidate.name || candidate.uuid) === key);
+    if (!exists) {
+      this.meshes.push(mesh);
+    }
+  }
   getMorphKeyCacheKey(key, meshNames) {
     return meshNames?.length ? `key:${key}@${meshNames.join(",")}` : `key:${key}`;
   }
@@ -6222,22 +6412,32 @@ function mergeRegionsByName(base, override) {
   }
   return Array.from(merged.values());
 }
+function getAnnotationRegions(value) {
+  return Array.isArray(value) ? value : void 0;
+}
+function getLegacyNestedOverrides(config) {
+  return isPlainObject2(config.profile) ? config.profile : {};
+}
+function getLegacyRuntimeRegions(config) {
+  return Array.isArray(config.regions) && config.regions.length > 0 ? config.regions : void 0;
+}
+function getCanonicalAnnotationOverrides(config) {
+  return mergeRegionsByName(
+    getAnnotationRegions(getLegacyNestedOverrides(config).annotationRegions),
+    getAnnotationRegions(config.annotationRegions)
+  );
+}
 function extractProfileOverrides(config) {
   const topLevelConfig = config;
-  const legacyNestedOverrides = isPlainObject2(config.profile) ? config.profile : {};
+  const legacyNestedOverrides = getLegacyNestedOverrides(config);
+  const canonicalAnnotationOverrides = getCanonicalAnnotationOverrides(config);
+  const legacyRuntimeRegions = getLegacyRuntimeRegions(config);
+  const annotationOverrides = canonicalAnnotationOverrides ?? (legacyRuntimeRegions ? legacyRuntimeRegions.map((region) => cloneRegion(region)) : void 0);
   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 legacyRegionFallback = Array.isArray(config.regions) && config.regions.length > 0 ? config.regions : void 0;
-      const legacyProfileRegions = mergeRegionsByName(legacyRegionFallback, legacyAnnotationRegions);
-      const regions = mergeRegionsByName(
-        legacyProfileRegions,
-        topLevelAnnotationRegions
-      );
-      if (regions) {
-        overrides.annotationRegions = regions.map((region) => cloneRegion(region));
+      if (annotationOverrides) {
+        overrides.annotationRegions = annotationOverrides.map((region) => cloneRegion(region));
       }
       continue;
     }
@@ -6250,13 +6450,6 @@ function extractProfileOverrides(config) {
   }
   return overrides;
 }
-function hasCanonicalAnnotationRegionOverrides(config) {
-  const topLevelConfig = config;
-  if (Array.isArray(topLevelConfig.annotationRegions)) {
-    return true;
-  }
-  return isPlainObject2(config.profile) && Array.isArray(config.profile.annotationRegions);
-}
 function applyCharacterProfileToPreset(config) {
   const presetType = config.auPresetType;
   if (!presetType) {
@@ -6288,24 +6481,34 @@ function extendCharacterConfigWithPreset(config) {
   if (!presetType || presetType === "custom") {
     return config;
   }
+  const canonicalAnnotationOverrides = getCanonicalAnnotationOverrides(config);
+  const legacyRuntimeRegions = getLegacyRuntimeRegions(config);
   const profileOverrides = extractProfileOverrides(config);
   const extendedPresetProfile = applyCharacterProfileToPreset(config);
   if (!extendedPresetProfile) {
     return config;
   }
-  const presetRegions = extendedPresetProfile.annotationRegions;
-  const mergedRegions = hasCanonicalAnnotationRegionOverrides(config) ? mergeRegionsByName(config.regions, presetRegions) : mergeRegionsByName(presetRegions, config.regions);
-  const normalizedRegions = normalizeRegionTree(
-    mergedRegions,
+  const presetRegionNames = new Set(
+    (getPreset(presetType).annotationRegions ?? []).map((region) => region.name)
+  );
+  const extendedAnnotationRegions = normalizeRegionTree(
+    extendedPresetProfile.annotationRegions,
+    profileOverrides.disabledRegions
+  );
+  const extendedRegionNames = new Set((extendedAnnotationRegions ?? []).map((region) => region.name));
+  const legacyExtraRegions = canonicalAnnotationOverrides && legacyRuntimeRegions ? legacyRuntimeRegions.filter((region) => !presetRegionNames.has(region.name) && !extendedRegionNames.has(region.name)).map((region) => cloneRegion(region)) : void 0;
+  const mergedRegions = normalizeRegionTree(
+    mergeRegionsByName(extendedAnnotationRegions, legacyExtraRegions),
     profileOverrides.disabledRegions
   );
   const extendedRegions = orderExtendedRegions(
-    normalizedRegions,
-    [config.regions, profileOverrides.annotationRegions, presetRegions]
+    mergedRegions,
+    canonicalAnnotationOverrides ? [extendedAnnotationRegions, legacyExtraRegions] : [legacyRuntimeRegions, extendedAnnotationRegions]
   );
   return {
     ...config,
     ...extendedPresetProfile,
+    annotationRegions: extendedRegions ?? extendedAnnotationRegions,
     regions: extendedRegions ?? config.regions
   };
 }
@@ -7465,7 +7668,7 @@ function extractMorphs(meshes) {
   for (const mesh of meshes) {
     const geo = mesh.geometry;
     if (!geo.morphAttributes) continue;
-    const dict = geo.morphTargetDictionary;
+    const dict = mesh.morphTargetDictionary || geo.morphTargetDictionary;
     if (dict) {
       for (const [name, index] of Object.entries(dict)) {
         morphs.push({