@sage-rsc/talking-head-react 1.0.46 → 1.0.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-rsc/talking-head-react",
-  "version": "1.0.46",
+  "version": "1.0.48",
   "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,
@@ -79,7 +106,7 @@ const CurriculumLearning = forwardRef(({
     ttsApiKey: avatarConfig.ttsApiKey || null,
     bodyMovement: avatarConfig.bodyMovement || "gesturing",
     movementIntensity: avatarConfig.movementIntensity || 0.7,
-    showFullAvatar: avatarConfig.showFullAvatar !== undefined ? avatarConfig.showFullAvatar : true,
+    showFullAvatar: avatarConfig.showFullAvatar !== undefined ? avatarConfig.showFullAvatar : false,
     animations: animations,
     lipsyncLang: 'en'
   });
@@ -114,7 +141,7 @@ const CurriculumLearning = forwardRef(({
       ttsApiKey: avatarConfig.ttsApiKey || null,
       bodyMovement: avatarConfig.bodyMovement || "gesturing",
       movementIntensity: avatarConfig.movementIntensity || 0.7,
-      showFullAvatar: avatarConfig.showFullAvatar !== undefined ? avatarConfig.showFullAvatar : true,
+      showFullAvatar: avatarConfig.showFullAvatar !== undefined ? avatarConfig.showFullAvatar : false,
       animations: animations,
       lipsyncLang: 'en'
     };
@@ -159,7 +186,7 @@ const CurriculumLearning = forwardRef(({
     let feedbackMessage = `Congratulations! You've completed this lesson`;
     if (stateRef.current.totalQuestions > 0) {
       feedbackMessage += ` with a score of ${stateRef.current.score} out of ${stateRef.current.totalQuestions} (${percentage}%). `;
-    } else {
+        } else {
       feedbackMessage += `! `;
     }
     
@@ -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]);
 
@@ -301,7 +321,7 @@ const CurriculumLearning = forwardRef(({
         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: config.lipsyncLang });
-      } else {
+        } else {
         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.isReady) {
@@ -338,7 +358,7 @@ const CurriculumLearning = forwardRef(({
       }
     
       if (avatarRef.current && nextQuestionObj) {
-        avatarRef.current.setMood("happy");
+      avatarRef.current.setMood("happy");
         avatarRef.current.setBodyMovement("idle");
       
         // Play custom animation if available
@@ -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
       });
       
-      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();
-          }
       }
     } else {
       // No more lessons in current module - check if there's a next module
@@ -428,22 +455,24 @@ 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
         if (completeCurriculumRef.current) {
@@ -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) => {
@@ -782,7 +823,7 @@ const CurriculumLearning = forwardRef(({
     ttsApiKey: null,
     bodyMovement: "gesturing",
     movementIntensity: 0.7,
-    showFullAvatar: true,
+    showFullAvatar: false,
     animations: animations,
     lipsyncLang: 'en'
   };