soroban-abacus-flashcards/apps/web/.claude/TUTORIAL_SYSTEM.md

Tutorial System Documentation

Overview

The tutorial system is a sophisticated interactive learning platform for teaching soroban abacus concepts. It features step-by-step guidance, bead highlighting, pedagogical decomposition, and progress tracking.

Key Components

1. TutorialPlayer (/src/components/tutorial/TutorialPlayer.tsx)

The main tutorial playback component that:

• Displays tutorial steps progressively
• Highlights specific beads users should interact with
• Provides real-time feedback and tooltips
• Shows step-by-step instructions for multi-step operations
• Tracks user progress through the tutorial
• Auto-advances to next step on correct completion

Key Features:

• Bead Highlighting: Visual indicators showing which beads to manipulate
• Step Progress: Shows current step out of total steps
• Error Feedback: Provides hints when user makes mistakes
• Multi-Step Support: Breaks complex operations into sequential sub-steps
• Pedagogical Decomposition: Explains the "why" behind each operation

2. TutorialEditor (/src/components/tutorial/TutorialEditor.tsx)

A full-featured editor for creating and editing tutorials:

• Visual step editor
• Bead highlight configuration
• Multi-step instruction editor
• Live preview
• Import/export functionality
• Access control

Editor URL: /tutorial-editor

3. Tutorial Data Structure (/src/types/tutorial.ts)

interface Tutorial {
  id: string;
  title: string;
  description: string;
  category: string;
  difficulty: "beginner" | "intermediate" | "advanced";
  estimatedDuration: number; // minutes
  steps: TutorialStep[];
  tags: string[];
  author: string;
  version: string;
  createdAt: Date;
  updatedAt: Date;
  isPublished: boolean;
}

interface TutorialStep {
  id: string;
  title: string;
  problem: string; // e.g. "2 + 3"
  description: string; // User-facing explanation
  startValue: number; // Initial abacus value
  targetValue: number; // Goal value
  expectedAction: "add" | "remove" | "multi-step";
  actionDescription: string;

  // Bead highlighting
  highlightBeads?: Array<{
    placeValue: number; // 0=ones, 1=tens, etc.
    beadType: "heaven" | "earth";
    position?: number; // For earth beads: 0-3
  }>;

  // Progressive step highlighting
  stepBeadHighlights?: Array<{
    placeValue: number;
    beadType: "heaven" | "earth";
    position?: number;
    stepIndex: number; // Which instruction step
    direction: "up" | "down" | "activate" | "deactivate";
    order?: number; // Order within step
  }>;

  totalSteps?: number; // For multi-step operations
  multiStepInstructions?: string[]; // Sequential instructions

  // Tooltips and guidance
  tooltip: {
    content: string; // Short title
    explanation: string; // Detailed explanation
  };
}

4. Tutorial Converter (/src/utils/tutorialConverter.ts)

Utility that converts the original GuidedAdditionTutorial data into the new tutorial format:

• guidedAdditionSteps: Array of tutorial steps from basic addition to complements
• convertGuidedAdditionTutorial(): Converts to Tutorial object
• getTutorialForEditor(): Main export used in the app

Current Tutorial Steps:

1. Basic Addition (0+1, 1+1, 2+1, 3+1)
2. Heaven Bead Introduction (0+5, 5+1)
3. Five Complements (3+4, 2+3 using 5-complement method)
4. Complex Operations (6+2, 7+4 with carrying)

5. Supporting Utilities

/src/utils/abacusInstructionGenerator.ts

• Automatically generates step-by-step instructions from start/target values
• Creates bead highlight data
• Determines movement directions

/src/utils/beadDiff.ts

• Calculates differences between abacus states
• Generates visual feedback tooltips
• Explains what changed and why

Usage Examples

Basic Usage in a Page

import { TutorialPlayer } from '@/components/tutorial/TutorialPlayer'
import { getTutorialForEditor } from '@/utils/tutorialConverter'

export function MyPage() {
  return (
    <TutorialPlayer
      tutorial={getTutorialForEditor()}
      isDebugMode={false}
      showDebugPanel={false}
    />
  )
}

Using a Subset of Steps

import { getTutorialForEditor } from '@/utils/tutorialConverter'

const fullTutorial = getTutorialForEditor()

// Extract specific steps (e.g., just "Friends of 5")
const friendsOf5Tutorial = {
  ...fullTutorial,
  id: 'friends-of-5-demo',
  title: 'Friends of 5',
  steps: fullTutorial.steps.filter(step =>
    step.id === 'complement-2' // The 2+3=5 step
  )
}

return <TutorialPlayer tutorial={friendsOf5Tutorial} />

Creating a Custom Tutorial

const customTutorial: Tutorial = {
  id: "my-tutorial",
  title: "My Custom Tutorial",
  description: "Learning something new",
  category: "Custom",
  difficulty: "beginner",
  estimatedDuration: 5,
  steps: [
    {
      id: "step-1",
      title: "Add 2",
      problem: "0 + 2",
      description: "Move two earth beads up",
      startValue: 0,
      targetValue: 2,
      expectedAction: "add",
      actionDescription: "Add two earth beads",
      highlightBeads: [
        { placeValue: 0, beadType: "earth", position: 0 },
        { placeValue: 0, beadType: "earth", position: 1 },
      ],
      tooltip: {
        content: "Adding 2",
        explanation: "Push two earth beads up to represent 2",
      },
    },
  ],
  tags: ["custom"],
  author: "Me",
  version: "1.0.0",
  createdAt: new Date(),
  updatedAt: new Date(),
  isPublished: true,
};

Current Implementation Locations

Live Tutorials:

• /guide - Second tab "Arithmetic Operations" contains the full guided addition tutorial

Editor:

• /tutorial-editor - Full tutorial editing interface

Storybook:

• Multiple tutorial stories in /src/components/tutorial/*.stories.tsx

Key Design Principles

1. Progressive Disclosure: Users see one step at a time
2. Immediate Feedback: Real-time validation and hints
3. Visual Guidance: Bead highlighting shows exactly what to do
4. Pedagogical Decomposition: Multi-step operations broken into atomic actions
5. Auto-Advancement: Successful completion automatically moves to next step
6. Error Recovery: Helpful hints when user makes mistakes

Notes

• The tutorial system uses the existing AbacusReact component
• Tutorials can be created/edited through the TutorialEditor
• Tutorial data can be exported/imported as JSON
• The system supports both single-step and multi-step operations
• Bead highlighting uses place value indexing (0=ones, 1=tens, etc.)