soroban-abacus-flashcards/apps/web/src/app/create/worksheets/README.md

Worksheet Generator

Create customizable math worksheets with progressive difficulty, problem space validation, and Typst-powered PDF generation.

Features

• Addition & Subtraction: Full support for multi-digit problems (1-5 digits)
• Progressive Difficulty: Smart Mode automatically scales difficulty based on skill level
• Problem Space Validation: Real-time warnings when configurations have limited unique problems
• Typst Integration: High-quality PDF generation with customizable layouts
• Display Rules: Configurable visual aids (carry boxes, ten frames, place-value colors, etc.)
• Mastery System: Adaptive learning with skill tracking and progression

Quick Start

// Access the worksheet studio at /create/worksheets/addition
// Configure settings, preview problems, download PDF

Architecture Documentation

Core Systems

Problem Generation - PROBLEM_GENERATION_ARCHITECTURE.md

• Complete technical documentation of problem generation algorithms
• Two generation strategies: generate-all + shuffle (small spaces) vs retry-based (large spaces)
• Problem space estimation and duplicate risk calculation
• Edge cases: single-digit constraints, mixed mastery mode, subtraction borrowing
• Performance considerations and testing guide

Quick Reference - .claude/PROBLEM_GENERATION.md

• Fast lookup for developers and Claude Code
• Strategy selection logic with code examples
• Debugging commands and common modifications
• Q&A troubleshooting section

UX Improvements - USER_WARNING_IMPROVEMENTS.md

• Recommended UI enhancements for problem space warnings
• Design mockups for config panel indicators
• Implementation phases and component structure

Additional Documentation

• Configuration Schema - CONFIG_SCHEMA_GUIDE.md - Complete guide to worksheet configuration
• Smart Difficulty - addition/SMART_DIFFICULTY_SPEC.md - Smart Mode progression spec
• Subtraction System - SUBTRACTION_AND_OPERATOR_PLAN.md - Subtraction implementation
• ⚠️ Operator-Specific Settings - OPERATOR_SPECIFIC_SETTINGS.md - [NEEDS REFACTORING] Mixed mode architecture & refactoring plan

Key Concepts

Problem Space

The "problem space" is the set of all unique problems possible given your constraints:

• 1-digit 100% regrouping: Only 45 unique problems exist (e.g., 2+8, 3+7, 4+9...)
• 2-digit mixed regrouping: ~4,000 unique problems
• 3-digit problems: ~400,000 unique problems

Why it matters: Requesting more problems than exist in the space results in duplicates. The system warns you when this happens.

Generation Strategies

Generate-All + Shuffle (Small spaces < 10,000)

• Enumerates all valid problems upfront
• Shuffles deterministically
• Zero retries, guaranteed coverage
• Cycles through full set when requesting more than available

Retry-Based (Large spaces ≥ 10,000)

• Randomly generates problems
• Retries on duplicates (up to 100 times)
• Allows some duplicates to prevent performance issues

Progressive Difficulty

Smart Mode - Automatically adjusts difficulty based on:

• Student skill level (tracked via mastery system)
• Previous performance
• Target regrouping/borrowing probability

Manual Mode - You control:

• Digit range (1-5 digits)
• Regrouping/borrowing probability (0-100%)
• Progressive vs constant difficulty

Common Edge Cases

Single-Digit 100% Regrouping

Problem: Only 45 unique problems where both operands are 0-9 and result requires carrying.

Solution:

• Reduce pages to 1-2 (20-40 problems)
• Lower regrouping to 50%
• Increase to 2-digit problems

Mastery + Mixed Mode

Problem: Addition and subtraction use separate skill-based configs, making combined problem space estimation complex.

Solution: Validation is skipped for this mode. Each operator uses its own config independently.

Subtraction Multiple Borrowing

Problem: 1-2 digit subtraction cannot have 2+ borrow operations (mathematical impossibility).

Solution: System automatically falls back to single-borrow problems for these ranges.

File Structure

worksheets/
├── README.md (this file)
├── PROBLEM_GENERATION_ARCHITECTURE.md    # Technical deep-dive
├── USER_WARNING_IMPROVEMENTS.md          # UX enhancement plan
├── problemGenerator.ts                   # Core generation logic
├── utils/
│   └── validateProblemSpace.ts          # Space estimation
├── components/
│   ├── config-panel/                    # Configuration UI
│   └── worksheet-preview/               # Preview + warnings
│       ├── WorksheetPreviewContext.tsx  # Validation state
│       └── DuplicateWarningBanner.tsx   # Warning display
└── addition/
    ├── SMART_DIFFICULTY_SPEC.md         # Smart Mode spec
    └── page.tsx                         # Addition worksheet page

Testing

# Type check
npm run type-check

# Run all checks before committing
npm run pre-commit

See PROBLEM_GENERATION_ARCHITECTURE.md for comprehensive testing checklist.

Contributing

When modifying problem generation:

1. Read PROBLEM_GENERATION_ARCHITECTURE.md for complete system understanding
2. Check .claude/PROBLEM_GENERATION.md for quick reference
3. Run the testing checklist
4. Update inline comments if changing generation strategy
5. Consider UX impact (see USER_WARNING_IMPROVEMENTS.md)

Related Documentation

Parent: apps/web/README.md - Web application overview Abacus Component: packages/abacus-react/README.md - Abacus visualization library