8.3 KiB

Raw Blame History

Progressive Multi-Step Instruction System Plan

Overview

Implement a comprehensive system that coordinates multi-step instructions, bead highlighting, and directional movement indicators to create a step-by-step progressive tutorial experience.

Current System Analysis

1. Bead Highlighting System

Location: packages/abacus-react/src/AbacusReact.tsx
Interface: BeadHighlight (union of PlaceValueBead | ColumnIndexBead)
Current functionality: Static highlighting of beads
Limitation: Shows all highlighted beads at once, no progressive revelation

2. Multi-Step Instructions

Location: apps/web/src/utils/abacusInstructionGenerator.ts
Data: multiStepInstructions: string[]
Current functionality: Generates step-by-step text instructions
Example (99+1):
1. "Click earth bead 1 in the hundreds column to add it"
2. "Remove 9 from ones column (subtracting second part of decomposition)"
3. "Remove 90 from tens column (subtracting first part of decomposition)"

3. Progressive Display (GuidedAdditionTutorial)

Location: apps/web/src/components/GuidedAdditionTutorial.tsx
State: multiStepProgress: number (tracks current step)
Functionality: Shows current step in bold, dims future steps
Limitation: No coordination with bead highlighting

4. Bead Generation Logic

Location: apps/web/src/utils/abacusInstructionGenerator.ts:generateBeadHighlights()
Current: Generates all beads for entire operation
Limitation: No step-by-step bead breakdown

Proposed Solution Architecture

Phase 1: Enhanced Data Structures

1.1 Extended BeadHighlight Interface

export interface StepBeadHighlight extends BeadHighlight {
  stepIndex: number  // Which instruction step this bead belongs to
  direction: 'up' | 'down' | 'activate' | 'deactivate'  // Movement direction
  order?: number     // Order within the step (for multiple beads per step)
}

1.2 Enhanced GeneratedInstruction Interface

export interface GeneratedInstruction {
  // ... existing fields
  multiStepInstructions?: string[]
  stepBeadHighlights?: StepBeadHighlight[]  // NEW: beads grouped by step
  totalSteps?: number                       // NEW: total number of steps
}

1.3 Progressive Instruction State

interface ProgressiveInstructionState {
  currentStep: number
  totalSteps: number
  currentStepBeads: BeadHighlight[]        // Beads for current step only
  completedStepBeads: BeadHighlight[]      // All beads from previous steps
  currentStepInstruction: string
}

Phase 2: Enhanced Instruction Generation

2.1 Modify generateEnhancedStepInstructions()

Generate beads per step, not just text instructions
Map each bead operation to its corresponding instruction step
Determine movement direction for each bead

2.2 New Function: generateStepBeadMapping()

function generateStepBeadMapping(
  startValue: number,
  targetValue: number,
  additions: BeadHighlight[],
  removals: BeadHighlight[],
  decomposition: any,
  multiStepInstructions: string[]
): StepBeadHighlight[]

Phase 3: AbacusReact Component Enhancements

3.1 Add Directional Indicators

New Props:

interface AbacusReactProps {
  // ... existing props
  stepBeadHighlights?: StepBeadHighlight[]
  showDirectionIndicators?: boolean
}

Visual Implementation:
- Arrow overlays on beads (↑ for up/activate, ↓ for down/deactivate)
- Different highlight colors for different directions
- Animation hints for movement direction

3.2 Enhanced Bead Styling

interface BeadDirectionStyle extends BeadStyle {
  directionIndicator?: {
    show: boolean
    direction: 'up' | 'down' | 'activate' | 'deactivate'
    color?: string
    size?: number
  }
}

Phase 4: TutorialPlayer Progressive Display

4.1 Add Progressive State Management

interface TutorialPlayerState {
  // ... existing state
  progressiveInstruction: ProgressiveInstructionState | null
}

4.2 Progressive Instruction Logic

Track current step within multi-step instructions
Update highlighted beads based on current step
Show only current step instruction in bold
Dim future steps, mark completed steps

4.3 Step Advancement Logic

User completes current step → advance to next step
Update bead highlights to show next step's beads
Maintain previously completed beads in "completed" state

Phase 5: Testing Strategy

5.1 Unit Tests for Step-by-Step Generation

describe('Progressive Instruction Generation', () => {
  test('99+1 generates correct step-bead mapping', () => {
    const instruction = generateAbacusInstructions(99, 100)
    expect(instruction.stepBeadHighlights).toHaveLength(3)

    // Step 0: Add 1 to hundreds
    expect(instruction.stepBeadHighlights[0]).toEqual({
      stepIndex: 0,
      placeValue: 2,
      beadType: 'earth',
      position: 0,
      direction: 'activate'
    })

    // Step 1: Remove 9 from ones (heaven + 4 earth)
    const step1Beads = instruction.stepBeadHighlights.filter(b => b.stepIndex === 1)
    expect(step1Beads).toHaveLength(5) // 1 heaven + 4 earth

    // Step 2: Remove 90 from tens (heaven + 4 earth)
    const step2Beads = instruction.stepBeadHighlights.filter(b => b.stepIndex === 2)
    expect(step2Beads).toHaveLength(5) // 1 heaven + 4 earth
  })

  test('3+98 generates correct step-bead mapping', () => {
    // Test simpler complement case
  })
})

5.2 Integration Tests for Progressive Display

describe('Progressive Tutorial Player', () => {
  test('shows only current step beads', () => {
    // Render tutorial player with 99+1 case
    // Verify only step 0 beads are highlighted initially
    // Advance step, verify step 1 beads appear
  })

  test('direction indicators display correctly', () => {
    // Verify arrows/indicators show correct directions
  })
})

5.3 Visual Regression Tests

Storybook stories for each progression state
Visual comparisons for direction indicators
Progressive highlighting behavior

Implementation Plan

Iteration 1: Data Structure Foundation

Design and implement enhanced interfaces ✓
Modify instruction generator to produce step-bead mapping
Unit tests for step-bead generation
Validate with 99+1 and 3+98 test cases

Iteration 2: AbacusReact Direction Indicators

Add direction indicator props to AbacusReact
Implement visual direction indicators (arrows/styling)
Create Storybook stories for direction indicators
Test various direction combinations

Iteration 3: Progressive TutorialPlayer

Add progressive state management to TutorialPlayer
Implement step advancement logic
Coordinate instruction text with bead highlights
Test tutorial progression flow

Iteration 4: Integration and Polish

Integrate all components in tutorial editor preview
End-to-end testing of complete progressive experience
Performance optimization
Accessibility improvements

Success Criteria

Bead-Instruction Correspondence: Each instruction step highlights only its relevant beads
Direction Clarity: Users can see which direction each bead needs to move
Progressive Revelation: Only current step is active, future steps are dimmed
Pedagogical Alignment: Visual progression matches mathematical decomposition
99+1 Test Case:
- Step 1: Show only hundreds bead with "up" indicator
- Step 2: Show only ones column beads with "down" indicators
- Step 3: Show only tens column beads with "down" indicators

Technical Considerations

Performance

Minimize re-renders during step progression
Efficient bead highlight calculations
Smooth animations for step transitions

Accessibility

Screen reader announcements for step changes
Keyboard navigation through steps
High contrast direction indicators

Backward Compatibility

Maintain existing single-step tutorial functionality
Graceful fallback for tutorials without multi-step data
Preserve existing AbacusReact API surface

This plan provides a comprehensive roadmap for implementing the progressive multi-step instruction system with proper coordination between pedagogy, visual display, and user interaction.

8.3 KiB Raw Blame History