@sage-rsc/talking-head-react 1.0.45 → 1.0.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-rsc/talking-head-react",
-  "version": "1.0.45",
+  "version": "1.0.47",
   "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

@@ -4,8 +4,14 @@ import TalkingHeadAvatar from './TalkingHeadAvatar';
 /**
  * CurriculumLearning - A controller component for curriculum-based learning
  * 
- * This component manages curriculum flow programmatically. It has no UI elements.
- * All interactions are controlled via props and callbacks.
+ * This component manages curriculum flow interactively. It has no UI elements.
+ * All progression is controlled by the parent app via ref methods (e.g., startTeaching, nextQuestion, nextLesson).
+ * The component exposes methods that can be called from buttons or other UI controls in the consuming app.
+ * 
+ * INTERACTIVE MODE: The component does NOT automatically progress. Instead, it:
+ * - Reads content when methods are called (startTeaching, startQuestions, nextQuestion, etc.)
+ * - Triggers events via onCustomAction when actions complete (teachingComplete, answerFeedbackComplete, etc.)
+ * - Waits for parent app to call the next method via ref
  * 
  * @param {Object} props
  * @param {Object} props.curriculumData - Curriculum data object
@@ -16,7 +22,28 @@ import TalkingHeadAvatar from './TalkingHeadAvatar';
  * @param {Function} props.onQuestionAnswer - Callback when question is answered
  * @param {Function} props.onCurriculumComplete - Callback when curriculum completes
  * @param {Function} props.onCustomAction - Callback for custom actions (receives action type and data)
- * @param {boolean} props.autoStart - Whether to auto-start the curriculum
+ *   - 'teachingComplete': Fired when teaching finishes. Check data.hasQuestions to know if questions are available.
+ *   - 'answerFeedbackComplete': Fired when answer feedback finishes. Check data.hasNextQuestion to know if more questions exist.
+ *   - 'lessonCompleteFeedbackDone': Fired when lesson completion feedback finishes. Check data.hasNextLesson to know if more lessons exist.
+ *   - 'allQuestionsComplete': Fired when all questions in a lesson are done. Parent should call completeLesson() when ready.
+ * @param {boolean} props.autoStart - Whether to auto-start teaching when avatar is ready (only affects initial start, not progression)
+ * 
+ * @example
+ * // In your app component:
+ * const curriculumRef = useRef(null);
+ * 
+ * // Call methods via ref to control progression:
+ * <button onClick={() => curriculumRef.current?.startTeaching()}>Start Lesson</button>
+ * <button onClick={() => curriculumRef.current?.startQuestions()}>Start Questions</button>
+ * <button onClick={() => curriculumRef.current?.nextQuestion()}>Next Question</button>
+ * <button onClick={() => curriculumRef.current?.nextLesson()}>Next Lesson</button>
+ * 
+ * // Listen to events to enable/disable buttons:
+ * onCustomAction={(action) => {
+ *   if (action.type === 'teachingComplete') {
+ *     setCanStartQuestions(action.hasQuestions);
+ *   }
+ * }}
  */
 const CurriculumLearning = forwardRef(({ 
   curriculumData = null,
@@ -208,29 +235,22 @@ const CurriculumLearning = forwardRef(({
       
       const config = defaultAvatarConfigRef.current || { lipsyncLang: 'en' };
       
-      if (hasNextLesson) {
-        // Wait for speech to finish, then automatically move to next lesson
-        avatarRef.current.speakText(feedbackMessage, { 
-          lipsyncLang: config.lipsyncLang,
-          onSpeechEnd: () => {
-            // Immediately transition to next lesson with no delay
-            if (nextLessonRef.current) {
-              nextLessonRef.current();
-            }
-          }
-        });
-    } else {
-        // This is the last lesson in the last module, complete curriculum instead
-        avatarRef.current.speakText(feedbackMessage, { 
-          lipsyncLang: config.lipsyncLang,
-          onSpeechEnd: () => {
-            // Immediately complete curriculum with no delay
-            if (completeCurriculumRef.current) {
-              completeCurriculumRef.current();
-            }
-          }
-        });
-      }
+      // Read completion feedback - no automatic progression, user controls via buttons
+      avatarRef.current.speakText(feedbackMessage, { 
+        lipsyncLang: config.lipsyncLang,
+        onSpeechEnd: () => {
+          // Notify parent that lesson completion feedback is done - parent decides next action
+          callbacksRef.current.onCustomAction({
+            type: 'lessonCompleteFeedbackDone',
+            moduleIndex: stateRef.current.currentModuleIndex,
+            lessonIndex: stateRef.current.currentLessonIndex,
+            score: stateRef.current.score,
+            totalQuestions: stateRef.current.totalQuestions,
+            percentage: percentage,
+            hasNextLesson: hasNextLesson
+          });
+        }
+      });
     }
   }, [animations.lessonComplete]);
 
@@ -372,10 +392,15 @@ const CurriculumLearning = forwardRef(({
         }
       }
     } else {
-      // Use ref to avoid circular dependency
-      if (completeLessonRef.current) {
-        completeLessonRef.current();
-      }
+      // No more questions - notify parent that all questions are done
+      // Parent can call completeLesson() when ready
+      callbacksRef.current.onCustomAction({
+        type: 'allQuestionsComplete',
+        moduleIndex: stateRef.current.currentModuleIndex,
+        lessonIndex: stateRef.current.currentLessonIndex,
+        totalQuestions: stateRef.current.totalQuestions,
+        score: stateRef.current.score
+      });
     }
   }, [animations.nextQuestion, getCurrentLesson, getCurrentQuestion]);
 
@@ -397,21 +422,23 @@ const CurriculumLearning = forwardRef(({
       stateRef.current.score = 0;
       stateRef.current.totalQuestions = 0;
       
-      // Clear current question in UI
+      // Clear current question in UI and notify parent
       callbacksRef.current.onCustomAction({
         type: 'lessonStart',
         moduleIndex: stateRef.current.currentModuleIndex,
         lessonIndex: stateRef.current.currentLessonIndex
       });
       
+      // Notify parent that lesson has changed - parent decides when to start teaching
+      callbacksRef.current.onLessonStart({
+        moduleIndex: stateRef.current.currentModuleIndex,
+        lessonIndex: stateRef.current.currentLessonIndex,
+        lesson: getCurrentLesson()
+      });
+      
       if (avatarRef.current) {
-      avatarRef.current.setMood("happy");
+        avatarRef.current.setMood("happy");
         avatarRef.current.setBodyMovement("idle");
-        
-          // Immediately start teaching the next lesson
-          if (startTeachingRef.current) {
-            startTeachingRef.current();
-          }
       }
     } else {
       // No more lessons in current module - check if there's a next module
@@ -428,21 +455,23 @@ const CurriculumLearning = forwardRef(({
         stateRef.current.score = 0;
         stateRef.current.totalQuestions = 0;
         
-        // Clear current question in UI
+        // Clear current question in UI and notify parent
         callbacksRef.current.onCustomAction({
           type: 'lessonStart',
           moduleIndex: stateRef.current.currentModuleIndex,
           lessonIndex: stateRef.current.currentLessonIndex
         });
     
-    if (avatarRef.current) {
+        // Notify parent that lesson has changed - parent decides when to start teaching
+        callbacksRef.current.onLessonStart({
+          moduleIndex: stateRef.current.currentModuleIndex,
+          lessonIndex: stateRef.current.currentLessonIndex,
+          lesson: getCurrentLesson()
+        });
+    
+        if (avatarRef.current) {
           avatarRef.current.setMood("happy");
-      avatarRef.current.setBodyMovement("idle");
-          
-          // Immediately start teaching the next lesson
-          if (startTeachingRef.current) {
-            startTeachingRef.current();
-          }
+          avatarRef.current.setBodyMovement("idle");
         }
     } else {
         // No more modules or lessons - complete curriculum
@@ -508,23 +537,19 @@ const CurriculumLearning = forwardRef(({
         lesson: currentLesson
       });
       
-      // Wait for avatar to finish speaking before moving to questions
+      // Read teaching content - no automatic progression, user controls via buttons
       avatarRef.current.speakText(teachingText, { 
         lipsyncLang: config.lipsyncLang,
-          onSpeechEnd: () => {
+        onSpeechEnd: () => {
           stateRef.current.isTeaching = false;
-          // Immediately transition to next step with no delay
-          if (currentLesson.questions && currentLesson.questions.length > 0) {
-            // 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();
-            }
-          }
+          // Notify parent that teaching is complete - parent decides next action
+          callbacksRef.current.onCustomAction({
+            type: 'teachingComplete',
+            moduleIndex: stateRef.current.currentModuleIndex,
+            lessonIndex: stateRef.current.currentLessonIndex,
+            lesson: currentLesson,
+            hasQuestions: currentLesson.questions && currentLesson.questions.length > 0
+          });
         }
       });
     }
@@ -565,14 +590,19 @@ const CurriculumLearning = forwardRef(({
         
         const config = defaultAvatarConfigRef.current || { lipsyncLang: 'en' };
         
-        // Wait for speech to finish before moving to next question
+        // Read feedback - no automatic progression, user controls via buttons
         avatarRef.current.speakText(successMessage, { 
           lipsyncLang: config.lipsyncLang,
           onSpeechEnd: () => {
-            // Immediately move to next question with no delay
-            if (nextQuestionRef.current) {
-              nextQuestionRef.current();
-            }
+            // Notify parent that feedback is complete - parent decides next action
+            callbacksRef.current.onCustomAction({
+              type: 'answerFeedbackComplete',
+              moduleIndex: stateRef.current.currentModuleIndex,
+              lessonIndex: stateRef.current.currentLessonIndex,
+              questionIndex: stateRef.current.currentQuestionIndex,
+              isCorrect: true,
+              hasNextQuestion: stateRef.current.currentQuestionIndex < (getCurrentLesson()?.questions?.length || 0) - 1
+            });
           }
         });
       } else {
@@ -591,24 +621,35 @@ const CurriculumLearning = forwardRef(({
         
         const config = defaultAvatarConfigRef.current || { lipsyncLang: 'en' };
         
-        // Wait for speech to finish before moving to next question
+        // Read feedback - no automatic progression, user controls via buttons
         avatarRef.current.speakText(failureMessage, { 
           lipsyncLang: config.lipsyncLang,
           onSpeechEnd: () => {
-            // Immediately move to next question with no delay
-            if (nextQuestionRef.current) {
-              nextQuestionRef.current();
-            }
+            // Notify parent that feedback is complete - parent decides next action
+            callbacksRef.current.onCustomAction({
+              type: 'answerFeedbackComplete',
+              moduleIndex: stateRef.current.currentModuleIndex,
+              lessonIndex: stateRef.current.currentLessonIndex,
+              questionIndex: stateRef.current.currentQuestionIndex,
+              isCorrect: false,
+              hasNextQuestion: stateRef.current.currentQuestionIndex < (getCurrentLesson()?.questions?.length || 0) - 1
+            });
           }
         });
       }
     } else {
-      // If avatar not ready, move to next question immediately
-      if (nextQuestionRef.current) {
-        nextQuestionRef.current();
-      }
+      // Avatar not ready - notify parent
+      callbacksRef.current.onCustomAction({
+        type: 'answerFeedbackComplete',
+        moduleIndex: stateRef.current.currentModuleIndex,
+        lessonIndex: stateRef.current.currentLessonIndex,
+        questionIndex: stateRef.current.currentQuestionIndex,
+        isCorrect: isCorrect,
+        hasNextQuestion: stateRef.current.currentQuestionIndex < (getCurrentLesson()?.questions?.length || 0) - 1,
+        avatarNotReady: true
+      });
     }
-  }, [animations.correct, animations.incorrect, getCurrentQuestion, checkAnswer]);
+  }, [animations.correct, animations.incorrect, getCurrentQuestion, getCurrentLesson, checkAnswer]);
 
   // Handle code test result submission
   const handleCodeTestResult = useCallback((testResult) => {

package/src/components/TalkingHeadAvatar.jsx

@@ -308,6 +308,23 @@ const TalkingHeadAvatar = forwardRef(({
               checkInterval = setInterval(checkSpeechFinished, 50);
             }
             
+            // Also check if speech queue is empty and not speaking (meaning all sentences processed)
+            // This handles the case where text was split into sentences but all are processed
+            const speechQueueEmpty = !talkingHead.speechQueue || talkingHead.speechQueue.length === 0;
+            
+            if (talkingHead && !talkingHead.isSpeaking && speechQueueEmpty && 
+                (!talkingHead.audioPlaylist || talkingHead.audioPlaylist.length === 0) &&
+                (!talkingHead.isAudioPlaying || talkingHead.isAudioPlaying === false)) {
+              // All speech has finished (all sentences processed and audio finished)
+              clearInterval(waitForAudioStart);
+              try {
+                options.onSpeechEnd();
+              } catch (e) {
+                console.error('Error in onSpeechEnd callback:', e);
+              }
+              return;
+            }
+            
             // Timeout if audio doesn't start within reasonable time
             if (waitForAudioStartCount * 50 > maxWaitForAudioStart) {
               clearInterval(waitForAudioStart);
@@ -317,7 +334,9 @@ const TalkingHeadAvatar = forwardRef(({
                 // Still waiting for API, but assume it will start soon
                 audioStarted = true;
                 checkInterval = setInterval(checkSpeechFinished, 50);
-              } else {
+              } else if (talkingHead && !talkingHead.isSpeaking && speechQueueEmpty &&
+                         (!talkingHead.audioPlaylist || talkingHead.audioPlaylist.length === 0) &&
+                         (!talkingHead.isAudioPlaying || talkingHead.isAudioPlaying === false)) {
                 // Speech never started or finished immediately, call callback
                 try {
                   options.onSpeechEnd();
@@ -353,10 +372,14 @@ const TalkingHeadAvatar = forwardRef(({
             // 1. Not speaking OR speech queue is empty
             // 2. Audio playlist is empty (no more audio to play)
             // 3. Not currently playing audio
+            // 4. Speech queue is empty (all sentences have been processed)
+            const speechQueueEmpty = !talkingHead.speechQueue || talkingHead.speechQueue.length === 0;
+            
             const isFinished = talkingHead && 
               (!talkingHead.isSpeaking || talkingHead.isSpeaking === false) && 
               (!talkingHead.audioPlaylist || talkingHead.audioPlaylist.length === 0) &&
-              (!talkingHead.isAudioPlaying || talkingHead.isAudioPlaying === false);
+              (!talkingHead.isAudioPlaying || talkingHead.isAudioPlaying === false) &&
+              speechQueueEmpty;
             
             if (isFinished) {
               if (checkInterval) {