@sage-rsc/talking-head-react 1.0.29 → 1.0.31

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("./index-C3A1_CcE.cjs");exports.CurriculumLearning=i.CurriculumLearning;exports.TalkingHeadAvatar=i.TalkingHeadAvatar;exports.TalkingHeadComponent=i.TalkingHeadComponent;exports.animations=i.animations;exports.getActiveTTSConfig=i.getActiveTTSConfig;exports.getAnimation=i.getAnimation;exports.getVoiceOptions=i.getVoiceOptions;exports.hasAnimation=i.hasAnimation;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("./index-WXvj5jje.cjs");exports.CurriculumLearning=i.CurriculumLearning;exports.TalkingHeadAvatar=i.TalkingHeadAvatar;exports.TalkingHeadComponent=i.TalkingHeadComponent;exports.animations=i.animations;exports.getActiveTTSConfig=i.getActiveTTSConfig;exports.getAnimation=i.getAnimation;exports.getVoiceOptions=i.getVoiceOptions;exports.hasAnimation=i.hasAnimation;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { C as n, T as s, a as t, d as e, b as o, g, c as m, h as r } from "./index-BvDk1TRw.js";
+import { C as n, T as s, a as t, d as e, b as o, g, c as m, h as r } from "./index-iUfJQ70v.js";
 export {
   n as CurriculumLearning,
   s as TalkingHeadAvatar,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-rsc/talking-head-react",
-  "version": "1.0.29",
+  "version": "1.0.31",
   "description": "A reusable React component for 3D talking avatars with lip-sync and text-to-speech",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/src/components/CurriculumLearning.jsx

@@ -1,4 +1,4 @@
-import React, { useRef, useEffect, forwardRef, useImperativeHandle, useCallback } from 'react';
+import React, { useRef, useEffect, useLayoutEffect, forwardRef, useImperativeHandle, useCallback } from 'react';
 import TalkingHeadAvatar from './TalkingHeadAvatar';
 
 /**
@@ -55,45 +55,77 @@ const CurriculumLearning = forwardRef(({
   const startTeachingRef = useRef(null);
   const nextLessonRef = useRef(null);
   const completeLessonRef = useRef(null);
-
-  // Update callbacks ref when they change
-  useEffect(() => {
-    callbacksRef.current = {
-      onLessonStart,
-      onLessonComplete,
-      onQuestionAnswer,
-      onCurriculumComplete,
-      onCustomAction
-    };
-  }, [onLessonStart, onLessonComplete, onQuestionAnswer, onCurriculumComplete, onCustomAction]);
-
-  const curriculum = curriculumData?.curriculum || {
+  const nextQuestionRef = useRef(null);
+  const completeCurriculumRef = useRef(null);
+  const startQuestionsRef = useRef(null);
+  const handleAnswerSelectRef = useRef(null);
+  
+  // Store curriculum in ref to avoid dependency issues - initialize early
+  const curriculumRef = useRef(curriculumData?.curriculum || {
     title: "Default Curriculum",
     description: "No curriculum data provided",
     language: "en",
     modules: []
-  };
-
-  const defaultAvatarConfig = {
+  });
+  
+  // Store avatar config in ref to avoid dependency issues - initialize early
+  const defaultAvatarConfigRef = useRef({
     avatarUrl: avatarConfig.avatarUrl || "/avatars/brunette.glb",
     avatarBody: avatarConfig.avatarBody || "F",
     mood: avatarConfig.mood || "happy",
     ttsLang: avatarConfig.ttsLang || "en",
-    ttsService: avatarConfig.ttsService || null, // Don't default to "edge" - let config decide
-    ttsVoice: avatarConfig.ttsVoice || null, // Don't default - let config decide
+    ttsService: avatarConfig.ttsService || null,
+    ttsVoice: avatarConfig.ttsVoice || null,
     ttsApiKey: avatarConfig.ttsApiKey || null,
     bodyMovement: avatarConfig.bodyMovement || "gesturing",
     movementIntensity: avatarConfig.movementIntensity || 0.7,
     showFullAvatar: avatarConfig.showFullAvatar !== undefined ? avatarConfig.showFullAvatar : true,
     animations: animations,
-    lipsyncLang: 'en' // Default lipsync language
-  };
+    lipsyncLang: 'en'
+  });
+
+  // Update callbacks ref when they change
+  useEffect(() => {
+    callbacksRef.current = {
+      onLessonStart,
+      onLessonComplete,
+      onQuestionAnswer,
+      onCurriculumComplete,
+      onCustomAction
+    };
+  }, [onLessonStart, onLessonComplete, onQuestionAnswer, onCurriculumComplete, onCustomAction]);
+
+  // Update curriculum and config refs when they change
+  useEffect(() => {
+    curriculumRef.current = curriculumData?.curriculum || {
+      title: "Default Curriculum",
+      description: "No curriculum data provided",
+      language: "en",
+      modules: []
+    };
+    
+    defaultAvatarConfigRef.current = {
+      avatarUrl: avatarConfig.avatarUrl || "/avatars/brunette.glb",
+      avatarBody: avatarConfig.avatarBody || "F",
+      mood: avatarConfig.mood || "happy",
+      ttsLang: avatarConfig.ttsLang || "en",
+      ttsService: avatarConfig.ttsService || null,
+      ttsVoice: avatarConfig.ttsVoice || null,
+      ttsApiKey: avatarConfig.ttsApiKey || null,
+      bodyMovement: avatarConfig.bodyMovement || "gesturing",
+      movementIntensity: avatarConfig.movementIntensity || 0.7,
+      showFullAvatar: avatarConfig.showFullAvatar !== undefined ? avatarConfig.showFullAvatar : true,
+      animations: animations,
+      lipsyncLang: 'en'
+    };
+  }, [curriculumData, avatarConfig, animations]);
 
   // Helper to get current lesson/question
   const getCurrentLesson = useCallback(() => {
+    const curriculum = curriculumRef.current || { modules: [] };
     const module = curriculum.modules[stateRef.current.currentModuleIndex];
     return module?.lessons[stateRef.current.currentLessonIndex];
-  }, [curriculum]);
+  }, []);
 
   const getCurrentQuestion = useCallback(() => {
     const lesson = getCurrentLesson();
@@ -158,23 +190,26 @@ const CurriculumLearning = forwardRef(({
     });
     
     if (avatarRef.current) {
-        avatarRef.current.setMood("happy");
+      avatarRef.current.setMood("happy");
       if (animations.lessonComplete) {
         try {
           avatarRef.current.playAnimation(animations.lessonComplete, true);
         } catch (error) {
-        avatarRef.current.playCelebration();
+          avatarRef.current.playCelebration();
         }
       }
       
       // Check if there's a next lesson available
+      const curriculum = curriculumRef.current || { modules: [] };
       const currentModule = curriculum.modules[stateRef.current.currentModuleIndex];
       const hasNextLesson = stateRef.current.currentLessonIndex < (currentModule?.lessons?.length || 0) - 1;
       
+      const config = defaultAvatarConfigRef.current || { lipsyncLang: 'en' };
+      
       if (hasNextLesson) {
         // Wait for speech to finish, then automatically move to next lesson
         avatarRef.current.speakText(feedbackMessage, { 
-          lipsyncLang: defaultAvatarConfig.lipsyncLang,
+          lipsyncLang: config.lipsyncLang,
           onSpeechEnd: () => {
             // Add a small delay after speech ends for natural flow
             setTimeout(() => {
@@ -188,25 +223,25 @@ const CurriculumLearning = forwardRef(({
       } else {
         // This is the last lesson, complete curriculum instead
         avatarRef.current.speakText(feedbackMessage, { 
-          lipsyncLang: defaultAvatarConfig.lipsyncLang,
+          lipsyncLang: config.lipsyncLang,
           onSpeechEnd: () => {
             // Add a small delay after speech ends for natural flow
             setTimeout(() => {
-              completeCurriculum();
+              if (completeCurriculumRef.current) {
+                completeCurriculumRef.current();
+              }
             }, 1000);
           }
         });
       }
     }
-  }, [animations.lessonComplete, curriculum, completeCurriculum, defaultAvatarConfig]);
-  
-  // Assign ref immediately after function is defined
-  completeLessonRef.current = completeLesson;
+  }, [animations.lessonComplete]);
 
   // Complete entire curriculum
   const completeCurriculum = useCallback(() => {
     stateRef.current.curriculumCompleted = true;
     
+    const curriculum = curriculumRef.current || { modules: [] };
     callbacksRef.current.onCurriculumComplete({
       modules: curriculum.modules.length,
       totalLessons: curriculum.modules.reduce((sum, mod) => sum + mod.lessons.length, 0)
@@ -221,9 +256,10 @@ const CurriculumLearning = forwardRef(({
           avatarRef.current.playCelebration();
         }
       }
-      avatarRef.current.speakText("Amazing! You've completed the entire curriculum! You're now ready to move on to more advanced topics. Well done!", { lipsyncLang: defaultAvatarConfig.lipsyncLang });
+      const config = defaultAvatarConfigRef.current || { lipsyncLang: 'en' };
+      avatarRef.current.speakText("Amazing! You've completed the entire curriculum! You're now ready to move on to more advanced topics. Well done!", { lipsyncLang: config.lipsyncLang });
     }
-  }, [animations.curriculumComplete, curriculum, defaultAvatarConfig]);
+  }, [animations.curriculumComplete]);
 
   // Start asking questions
   const startQuestions = useCallback(() => {
@@ -258,20 +294,23 @@ const CurriculumLearning = forwardRef(({
         }
       }
       
+      const config = defaultAvatarConfigRef.current || { lipsyncLang: 'en' };
+      
       // Introduce the first question properly based on type
       if (firstQuestion.type === 'code_test') {
-        avatarRef.current.speakText(`Let's test your coding skills! Here's your first challenge: ${firstQuestion.question}`, { lipsyncLang: defaultAvatarConfig.lipsyncLang });
+        avatarRef.current.speakText(`Let's test your coding skills! Here's your first challenge: ${firstQuestion.question}`, { lipsyncLang: config.lipsyncLang });
       } else if (firstQuestion.type === 'multiple_choice') {
-        avatarRef.current.speakText(`Now let me ask you some questions. Here's the first one: ${firstQuestion.question}`, { lipsyncLang: defaultAvatarConfig.lipsyncLang });
+        avatarRef.current.speakText(`Now let me ask you some questions. Here's the first one: ${firstQuestion.question}`, { lipsyncLang: config.lipsyncLang });
       } else if (firstQuestion.type === 'true_false') {
-        avatarRef.current.speakText(`Let's start with some true or false questions. First question: ${firstQuestion.question}`, { lipsyncLang: defaultAvatarConfig.lipsyncLang });
+        avatarRef.current.speakText(`Let's start with some true or false questions. First question: ${firstQuestion.question}`, { lipsyncLang: config.lipsyncLang });
       } else {
-        avatarRef.current.speakText(`Now let me ask you some questions. Here's the first one: ${firstQuestion.question}`, { lipsyncLang: defaultAvatarConfig.lipsyncLang });
+        avatarRef.current.speakText(`Now let me ask you some questions. Here's the first one: ${firstQuestion.question}`, { lipsyncLang: config.lipsyncLang });
       }
     } else if (avatarRef.current) {
-      avatarRef.current.speakText("Now let me ask you some questions to test your understanding.", { lipsyncLang: defaultAvatarConfig.lipsyncLang });
+      const config = defaultAvatarConfigRef.current || { lipsyncLang: 'en' };
+      avatarRef.current.speakText("Now let me ask you some questions to test your understanding.", { lipsyncLang: config.lipsyncLang });
     }
-  }, [animations.questionStart, getCurrentLesson, getCurrentQuestion, defaultAvatarConfig]);
+  }, [animations.questionStart, getCurrentLesson, getCurrentQuestion]);
 
   // Move to next question
   const nextQuestion = useCallback(() => {
@@ -301,27 +340,29 @@ const CurriculumLearning = forwardRef(({
         if (animations.nextQuestion) {
           try {
             avatarRef.current.playAnimation(animations.nextQuestion, true);
-        } catch (error) {
+          } catch (error) {
             console.warn('Failed to play nextQuestion animation:', error);
           }
         }
         
+        const config = defaultAvatarConfigRef.current || { lipsyncLang: 'en' };
+        
         // Speak the question text with proper introduction
         if (nextQuestionObj.type === 'code_test') {
           avatarRef.current.speakText(`Great! Now let's move on to your next coding challenge: ${nextQuestionObj.question}`, { 
-            lipsyncLang: defaultAvatarConfig.lipsyncLang 
+            lipsyncLang: config.lipsyncLang 
           });
         } else if (nextQuestionObj.type === 'multiple_choice') {
           avatarRef.current.speakText(`Alright! Here's your next question: ${nextQuestionObj.question}`, { 
-            lipsyncLang: defaultAvatarConfig.lipsyncLang 
+            lipsyncLang: config.lipsyncLang 
           });
         } else if (nextQuestionObj.type === 'true_false') {
           avatarRef.current.speakText(`Now let's try this one: ${nextQuestionObj.question}`, { 
-            lipsyncLang: defaultAvatarConfig.lipsyncLang 
+            lipsyncLang: config.lipsyncLang 
           });
         } else {
           avatarRef.current.speakText(`Here's the next question: ${nextQuestionObj.question}`, { 
-            lipsyncLang: defaultAvatarConfig.lipsyncLang 
+            lipsyncLang: config.lipsyncLang 
           });
         }
       }
@@ -331,10 +372,11 @@ const CurriculumLearning = forwardRef(({
         completeLessonRef.current();
       }
     }
-  }, [animations.nextQuestion, getCurrentLesson, getCurrentQuestion, defaultAvatarConfig]);
+  }, [animations.nextQuestion, getCurrentLesson, getCurrentQuestion]);
 
   // Move to next lesson
   const nextLesson = useCallback(() => {
+    const curriculum = curriculumRef.current || { modules: [] };
     const currentModule = curriculum.modules[stateRef.current.currentModuleIndex];
     if (stateRef.current.currentLessonIndex < (currentModule?.lessons?.length || 0) - 1) {
       stateRef.current.currentLessonIndex += 1;
@@ -353,7 +395,7 @@ const CurriculumLearning = forwardRef(({
       });
       
       if (avatarRef.current) {
-      avatarRef.current.setMood("happy");
+        avatarRef.current.setMood("happy");
         avatarRef.current.setBodyMovement("idle");
         
         // Automatically start teaching the next lesson after a brief pause
@@ -364,12 +406,11 @@ const CurriculumLearning = forwardRef(({
         }, 500);
       }
     } else {
-      completeCurriculum();
+      if (completeCurriculumRef.current) {
+        completeCurriculumRef.current();
+      }
     }
-  }, [curriculum, completeCurriculum]);
-  
-  // Assign ref immediately after function is defined
-  nextLessonRef.current = nextLesson;
+  }, []);
 
   // Start teaching the lesson
   const startTeaching = useCallback(() => {
@@ -383,10 +424,10 @@ const CurriculumLearning = forwardRef(({
       // Play animation if available (can be overridden via custom action)
       let animationPlayed = false;
       if (animations.teaching) {
-      try {
+        try {
           avatarRef.current.playAnimation(animations.teaching, true);
           animationPlayed = true;
-      } catch (error) {
+        } catch (error) {
           console.warn('Failed to play teaching animation:', error);
         }
       }
@@ -395,7 +436,8 @@ const CurriculumLearning = forwardRef(({
         avatarRef.current.setBodyMovement("gesturing");
       }
       
-      avatarRef.current.speakText(currentLesson.avatar_script, { lipsyncLang: defaultAvatarConfig.lipsyncLang });
+      const config = defaultAvatarConfigRef.current || { lipsyncLang: 'en' };
+      avatarRef.current.speakText(currentLesson.avatar_script, { lipsyncLang: config.lipsyncLang });
       
       callbacksRef.current.onLessonStart({
         moduleIndex: stateRef.current.currentModuleIndex,
@@ -415,8 +457,11 @@ const CurriculumLearning = forwardRef(({
       setTimeout(() => {
         stateRef.current.isTeaching = false;
         if (currentLesson.questions && currentLesson.questions.length > 0) {
-          startQuestions();
-    } else {
+          // Use ref to avoid circular dependency
+          if (startQuestionsRef.current) {
+            startQuestionsRef.current();
+          }
+        } else {
           // No questions, complete the lesson using ref to avoid circular dependency
           if (completeLessonRef.current) {
             completeLessonRef.current();
@@ -424,10 +469,7 @@ const CurriculumLearning = forwardRef(({
         }
       }, 8000);
     }
-  }, [animations.teaching, getCurrentLesson, startQuestions, defaultAvatarConfig]);
-  
-  // Assign ref immediately after function is defined
-  startTeachingRef.current = startTeaching;
+  }, [animations.teaching, getCurrentLesson]);
 
   // Handle answer selection
   const handleAnswerSelect = useCallback((answer) => {
@@ -449,11 +491,11 @@ const CurriculumLearning = forwardRef(({
     
     if (avatarRef.current) {
       if (isCorrect) {
-      avatarRef.current.setMood("happy");
+        avatarRef.current.setMood("happy");
         if (animations.correct) {
-      try {
+          try {
             avatarRef.current.playReaction("happy");
-      } catch (error) {
+          } catch (error) {
             avatarRef.current.setBodyMovement("happy");
           }
         }
@@ -462,22 +504,26 @@ const CurriculumLearning = forwardRef(({
           ? `Great job! Your code passed all the tests! ${currentQuestion.explanation || ''}`
           : `Excellent! That's correct! ${currentQuestion.explanation || ''}`;
         
+        const config = defaultAvatarConfigRef.current || { lipsyncLang: 'en' };
+        
         // Wait for speech to finish before moving to next question
         avatarRef.current.speakText(successMessage, { 
-          lipsyncLang: defaultAvatarConfig.lipsyncLang,
+          lipsyncLang: config.lipsyncLang,
           onSpeechEnd: () => {
             // Add a small delay after speech ends for natural flow
             setTimeout(() => {
-              nextQuestion();
+              if (nextQuestionRef.current) {
+                nextQuestionRef.current();
+              }
             }, 500);
           }
         });
-    } else {
+      } else {
         avatarRef.current.setMood("sad");
         if (animations.incorrect) {
           try {
             avatarRef.current.playAnimation(animations.incorrect, true);
-      } catch (error) {
+          } catch (error) {
             avatarRef.current.setBodyMovement("idle");
           }
         }
@@ -486,22 +532,28 @@ const CurriculumLearning = forwardRef(({
           ? `Your code didn't pass all the tests. ${currentQuestion.explanation || 'Try again!'}`
           : `Not quite right, but don't worry! ${currentQuestion.explanation || ''} Let's move on to the next question.`;
         
+        const config = defaultAvatarConfigRef.current || { lipsyncLang: 'en' };
+        
         // Wait for speech to finish before moving to next question
         avatarRef.current.speakText(failureMessage, { 
-          lipsyncLang: defaultAvatarConfig.lipsyncLang,
+          lipsyncLang: config.lipsyncLang,
           onSpeechEnd: () => {
             // Add a small delay after speech ends for natural flow
             setTimeout(() => {
-              nextQuestion();
+              if (nextQuestionRef.current) {
+                nextQuestionRef.current();
+              }
             }, 500);
           }
         });
       }
     } else {
       // If avatar not ready, move to next question immediately
-      nextQuestion();
+      if (nextQuestionRef.current) {
+        nextQuestionRef.current();
+      }
     }
-  }, [animations.correct, animations.incorrect, getCurrentQuestion, checkAnswer, nextQuestion, defaultAvatarConfig]);
+  }, [animations.correct, animations.incorrect, getCurrentQuestion, checkAnswer]);
 
   // Handle code test result submission
   const handleCodeTestResult = useCallback((testResult) => {
@@ -542,8 +594,10 @@ const CurriculumLearning = forwardRef(({
     });
 
     // Handle answer using the same logic as regular questions
-    handleAnswerSelect(codeTestAnswer);
-  }, [getCurrentQuestion, handleAnswerSelect]);
+    if (handleAnswerSelectRef.current) {
+      handleAnswerSelectRef.current(codeTestAnswer);
+    }
+  }, [getCurrentQuestion, checkAnswer]);
 
   // Reset curriculum
   const resetCurriculum = useCallback(() => {
@@ -571,6 +625,18 @@ const CurriculumLearning = forwardRef(({
     }
   }, [autoStart, getCurrentLesson]);
 
+  // Set refs after all functions are defined - use useLayoutEffect for synchronous execution
+  // This ensures refs are set before React commits the render, avoiding initialization errors
+  useLayoutEffect(() => {
+    startTeachingRef.current = startTeaching;
+    nextLessonRef.current = nextLesson;
+    completeLessonRef.current = completeLesson;
+    nextQuestionRef.current = nextQuestion;
+    completeCurriculumRef.current = completeCurriculum;
+    startQuestionsRef.current = startQuestions;
+    handleAnswerSelectRef.current = handleAnswerSelect;
+  });
+
   // Expose methods via ref (for external control)
   useImperativeHandle(ref, () => ({
     // Curriculum control methods
@@ -594,7 +660,8 @@ const CurriculumLearning = forwardRef(({
     speakText: async (text, options = {}) => {
       // Ensure audio context is resumed before speaking
       await avatarRef.current?.resumeAudioContext?.();
-      avatarRef.current?.speakText(text, { ...options, lipsyncLang: options.lipsyncLang || defaultAvatarConfig.lipsyncLang });
+      const config = defaultAvatarConfigRef.current || { lipsyncLang: 'en' };
+      avatarRef.current?.speakText(text, { ...options, lipsyncLang: options.lipsyncLang || config.lipsyncLang });
     },
     resumeAudioContext: async () => {
       // Try to resume through avatar ref first
@@ -646,6 +713,22 @@ const CurriculumLearning = forwardRef(({
     isAvatarReady: () => avatarRef.current?.isReady || false
   }), [startTeaching, startQuestions, handleAnswerSelect, handleCodeTestResult, nextQuestion, nextLesson, completeLesson, completeCurriculum, resetCurriculum, getCurrentQuestion, getCurrentLesson]);
 
+  // Get current config for render
+  const defaultAvatarConfig = defaultAvatarConfigRef.current || {
+    avatarUrl: "/avatars/brunette.glb",
+    avatarBody: "F",
+    mood: "happy",
+    ttsLang: "en",
+    ttsService: null,
+    ttsVoice: null,
+    ttsApiKey: null,
+    bodyMovement: "gesturing",
+    movementIntensity: 0.7,
+    showFullAvatar: true,
+    animations: animations,
+    lipsyncLang: 'en'
+  };
+
   return (
     <div style={{ width: '100%', height: '100%' }}>
       <TalkingHeadAvatar
@@ -676,4 +759,4 @@ const CurriculumLearning = forwardRef(({
 
 CurriculumLearning.displayName = 'CurriculumLearning';
 
-export default CurriculumLearning;
+export default CurriculumLearning;

package/src/lib/talkinghead.mjs

@@ -3248,7 +3248,7 @@ class TalkingHead {
         const module = LIPSYNC_MODULES[langLower];
         
         if (module && module[className]) {
-          this.lipsync[lang] = new module[className];
+        this.lipsync[lang] = new module[className];
           console.log(`Loaded lip-sync module for ${lang}`);
         } else {
           console.warn(`Lip-sync module for ${lang} not found. Available modules:`, Object.keys(LIPSYNC_MODULES));