From 408eb58792d6082fd33ea92bb40e42da7fec2597 Mon Sep 17 00:00:00 2001
From: Thomas Hallock <thomas@evolutioniq.com>
Date: Tue, 23 Sep 2025 08:09:38 -0500
Subject: [PATCH] feat: display pedagogical terms inline with current tutorial
 step
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Show mathematical terms (e.g., "10", "(5 - 1)", "-6") as badges next to the current
step in the Step-by-Step Instructions list. This provides clear context about the
mathematical reasoning behind each step.

Features:
- Added ExpectedStep interface with mathematicalTerm field
- Blue-styled badge appears only for the current active step
- Integrates pedagogical decomposition directly into the UI
- Properly typed with TypeScript for maintainability

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../components/tutorial/TutorialPlayer.tsx    | 59 ++++++++++++++-----
 1 file changed, 44 insertions(+), 15 deletions(-)

diff --git a/apps/web/src/components/tutorial/TutorialPlayer.tsx b/apps/web/src/components/tutorial/TutorialPlayer.tsx
index 41f7f8be..f2c7dae0 100644
--- a/apps/web/src/components/tutorial/TutorialPlayer.tsx
+++ b/apps/web/src/components/tutorial/TutorialPlayer.tsx
@@ -22,6 +22,15 @@ interface TutorialPlayerState {
   currentMultiStep: number // Current step within multi-step instructions (0-based)
 }
 
+interface ExpectedStep {
+  index: number
+  stepIndex: number
+  targetValue: number
+  startValue: number
+  description: string
+  mathematicalTerm?: string // Pedagogical term like "10", "(5 - 1)", "-6"
+}
+
 type TutorialPlayerAction =
   | { type: 'INITIALIZE_STEP'; stepIndex: number; startValue: number; stepId: string }
   | { type: 'USER_VALUE_CHANGE'; oldValue: number; newValue: number; stepId: string }
@@ -178,9 +187,8 @@ export function TutorialPlayer({
   }
 
   // Define the static expected steps using our unified step generator
-  const expectedSteps = useMemo(() => {
+  const expectedSteps: ExpectedStep[] = useMemo(() => {
     try {
-      console.log('🚀 Generating unified instruction sequence for TutorialPlayer')
       const unifiedSequence = generateUnifiedInstructionSequence(currentStep.startValue, currentStep.targetValue)
 
       // Convert unified sequence to expected steps format
@@ -189,13 +197,12 @@ export function TutorialPlayer({
         stepIndex: index,
         targetValue: step.expectedValue,
         startValue: index === 0 ? currentStep.startValue : unifiedSequence.steps[index - 1].expectedValue,
-        description: step.englishInstruction
+        description: step.englishInstruction,
+        mathematicalTerm: step.mathematicalTerm  // Add the pedagogical term
       }))
 
-      console.log('📋 Generated expected steps from unified sequence:', steps)
       return steps
     } catch (error) {
-      console.warn('⚠️ Failed to generate unified expected steps, falling back to empty:', error)
       return []
     }
   }, [currentStep.startValue, currentStep.targetValue])
@@ -822,16 +829,38 @@ export function TutorialPlayer({
                     color: 'yellow.700',
                     pl: 4
                   })}>
-                    {currentStep.multiStepInstructions.map((instruction, index) => (
-                      <li key={index} className={css({
-                        mb: 1,
-                        opacity: index === currentMultiStep ? '1' : index < currentMultiStep ? '0.7' : '0.4',
-                        fontWeight: index === currentMultiStep ? 'bold' : 'normal',
-                        color: index === currentMultiStep ? 'yellow.900' : index < currentMultiStep ? 'yellow.600' : 'yellow.400'
-                      })}>
-                        {index + 1}. {instruction}
-                      </li>
-                    ))}
+                    {currentStep.multiStepInstructions.map((instruction, index) => {
+                      // Get the mathematical term for this step
+                      const mathTerm = expectedSteps[index]?.mathematicalTerm
+                      const isCurrentStep = index === currentMultiStep
+
+                      return (
+                        <li key={index} className={css({
+                          mb: 1,
+                          opacity: index === currentMultiStep ? '1' : index < currentMultiStep ? '0.7' : '0.4',
+                          fontWeight: index === currentMultiStep ? 'bold' : 'normal',
+                          color: index === currentMultiStep ? 'yellow.900' : index < currentMultiStep ? 'yellow.600' : 'yellow.400'
+                        })}>
+                          {index + 1}. {instruction}
+                          {isCurrentStep && mathTerm && (
+                            <span className={css({
+                              ml: 2,
+                              px: 2,
+                              py: 1,
+                              bg: 'blue.100',
+                              color: 'blue.800',
+                              fontSize: 'xs',
+                              fontWeight: 'semibold',
+                              borderRadius: 'sm',
+                              border: '1px solid',
+                              borderColor: 'blue.200'
+                            })}>
+                              {mathTerm}
+                            </span>
+                          )}
+                        </li>
+                      )
+                    })}
                   </ol>
 
                   {/* Real-time bead movement feedback */}