- Change position from 'fixed' to 'absolute' to be relative to tutorial container
- Move from top-right corner of viewport to top-right of abacus area
- Now appears where users are actually looking instead of distant app nav
- Toast notification is much more noticeable and contextually relevant
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Replace large center-screen modal with small top-right toast
- Change from blocking 320px modal to non-blocking compact notification
- Auto-dismiss after 3 seconds instead of requiring click
- Use pointer-events: none to avoid interfering with user interactions
- Simple "✓ Step completed!" message instead of elaborate celebration
- Maintains user flow for speed running while still providing feedback
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Import useAbacusDisplay from AbacusDisplayContext
- Use abacusConfig.colorScheme instead of hard-coded "place-value"
- Add abacusConfig.beadShape and abacusConfig.hideInactiveBeads props
- Tutorial abacus now respects universal style controls in app nav
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove debug console logs from TutorialPlayer getCurrentStepBeads
- Remove debug logs from stepBeadHighlights useEffect
- Remove debug logs from AbacusReact getBeadStepHighlight function
- Restore normal legacy highlighting system functionality
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Created extensive test coverage to prevent regressions in the tutorial system fixes:
## AbacusReact Controlled Input Tests
- Controlled value prop initialization and updates
- User interaction vs programmatic change detection
- Feedback loop prevention
- Rapid value change handling
## TutorialContext State Management Tests
- Step initialization with correct startValue
- Navigation between steps and value reset
- Multi-step progression (advance, previous, reset)
- Value change handling and step completion
- Error handling for edge cases
## TutorialPlayer Integration Tests
- AbacusReact integration and value synchronization
- Multi-step instruction display and progression
- Context state consistency across components
- Feedback loop prevention between components
- Performance and error recovery testing
## End-to-End Workflow Tests
- Complete tutorial workflow from user perspective
- Cross-browser compatibility and responsive behavior
- User interaction patterns (bead clicks, navigation)
- Success feedback and completion handling
- Keyboard accessibility testing
Includes test utilities, setup files, and comprehensive test runner for CI/CD integration.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Replace local useReducer with TutorialContext hooks for single source of truth
- Update navigation functions to use context versions (goToStep, goToNextStep, etc.)
- Migrate multi-step actions to use context functions (advanceMultiStep, previousMultiStep)
- Wrap handleValueChange to track user interaction for step advancement logic
- Remove duplicate state management and consolidate into context pattern
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add useEffect to initialize first step with correct startValue on mount
- Add advanceMultiStep, previousMultiStep, resetMultiStep functions to context
- Implement isProgrammaticChange flag to prevent feedback loops during step navigation
- Auto-clear isProgrammaticChange flag after external value changes settle
- Ensures abacus displays correct startValue when navigating between tutorial steps
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Check for beads against reckoning bar (heaven beads when value ≥ 5, earth beads when value % 5 > 0)
- Include beads with direction arrows in collision detection
- Ensure tooltip never covers any bead contributing to current value or with instructional arrows
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add collision detection to check for active beads in columns to the left
- Position tooltip to the left when safe, above heaven bead when collision detected
- Remove fixed left margin since tooltips can now position above when needed
- Ensure tooltip never covers beads with direction arrows or highlights
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Only mark step as completed when all pedagogical multi-steps are finished
- Prevents "Excellent Work" popup from showing when users skip to final answer
- Maintains correct behavior for single-step problems
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add PedagogicalDecompositionDisplay component with tooltip and guidance variants
- Create Radix tooltip overlay system targeting specific beads with direction arrows
- Show pedagogical decomposition with current term highlighted in both tooltip and guidance pane
- Position tooltip to left of abacus with 60px left margin to prevent clipping
- Add hover opacity effects (85% default, 100% on hover) for subtle tooltip presence
- Include lightbulb emoji and action summary in tooltip for clear guidance
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Hide action description for multi-step problems to avoid duplicating pedagogical decomposition
- Remove redundant bead diff summary from guidance pane (now shown only in tooltip)
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add isSuccessPopupDismissed state that resets on step changes
- Make success overlay clickable with pointer events enabled
- Add hover effects and cursor pointer for better UX
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Replace the inline success message that caused abacus layout shift with a
beautiful fixed-position glassmorphism overlay featuring:
- Fixed center positioning to prevent layout shift
- Glassmorphism design with backdrop blur and gradients
- Smooth animations (pulse in, bounce emoji, shimmer effect)
- Non-interactive (pointerEvents: none) to avoid UI conflicts
- Celebration design with emoji and elegant typography
This eliminates the UX problem where completing steps moved the abacus,
while providing fantastic visual feedback for user achievements.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add integration tests for TutorialPlayer layout and helper functions
to ensure proper component behavior and tutorial flow.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Update tutorial editor to remove error message form fields
and validation, simplifying the tutorial authoring interface.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add findTopmostBeadWithArrows helper function that filters beads to only
include those with actual direction indicators, preventing tooltips from
appearing on irrelevant beads without highlighting.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Clean extracted components from context refactoring with proper styling
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Replace prop drilling with centralized state management using React Context.
TutorialPlayer now uses TutorialProvider wrapper with custom hooks for
clean access to state, actions, and computed values while preserving
all existing functionality.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Enhanced main guidance container with gradient backgrounds and glassmorphism effects
- Added layered shadows, backdrop blur, and subtle gradient overlays
- Improved typography for heading, decomposition text, and instructions
- Enhanced mathematical term highlighting with gradient backgrounds and modern shadows
- Maintained same screen footprint while creating more visually appealing interface
- Applied contemporary design principles for engaging yet non-distracting presentation
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Move 💡 emoji from separate paragraph to inline with suggestion text
- Add proper spacing with margin-right
- Create cleaner, more natural hint presentation
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add single 'Guidance' heading for entire tutorial help section
- Remove redundant 'Problem Breakdown:' and 'Current Step:' sub-headings
- Replace 'Next Action:' with intuitive lightbulb emoji (💡)
- Create cohesive guidance experience with less visual noise
- Maintain all functionality while improving information hierarchy
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Replace unstable render-time calculations with useState timer
- Add useEffect to manage 8-second help timer lifecycle
- Reset help state when advancing to new multi-step
- Fix issue where help only appeared momentarily during bead transitions
- Simplify logic: help shows after 8 seconds if user needs to act
- Provide stable, persistent help display until step completion
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add multiStepStartTime tracking to monitor user progress
- Hide Next Action by default to reduce interface clutter
- Show help only when user appears confused or stalled:
- After 10 seconds on current step (general confusion)
- After 5 seconds if user has wrong value (specific confusion)
- Reset timer when advancing to next multi-step
- Provides contextual assistance without overwhelming users
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove step number from current instruction display
- Remove mathematical term repetition in current step
- Pedagogical breakdown with highlighting provides sufficient context
- Cleaner, more focused interface without redundant information
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Replace step-by-step list with single current step display
- Hide non-current steps to reduce visual clutter
- Inline highlighting in pedagogical breakdown provides sufficient progress indication
- Cleaner interface focuses user attention on current action
- Maintains all functionality while reducing cognitive load
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add termPosition field to ExpectedStep interface
- Update renderHighlightedDecomposition to use precise string positions
- Replace problematic indexOf approach with exact position data
- Integrate position information from unified step generator
- Fix issue with repeated mathematical terms in decomposition
- Improve pedagogical feedback by highlighting current term precisely
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implement precise logic to avoid redundant Next Action display:
- First step (index 0): Hide if currentValue === tutorial step startValue
- Subsequent steps: Hide if currentValue === previous step's targetValue
This ensures users see step instructions without redundant bead movement
guidance when they're at the natural starting point for each step, while
still providing helpful guidance when they're mid-action or off-track.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Enhanced the logic to hide "Next Action" in more cases:
- Check if currentValue matches stepTargetValue (existing)
- Check if summary contains "No changes needed" (new)
- Only show when there are actual meaningful changes to display
This should reduce redundant information while maintaining helpful guidance
when users genuinely need specific bead movement instructions.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Only display the bead diff summary ("Next Action") when the current abacus
value differs from the target value for the current step. This eliminates
redundant information and provides a cleaner user experience.
Logic:
- Compare currentValue with expectedSteps[currentMultiStep].targetValue
- Show "Next Action" only when values don't match
- Automatically hides when user completes the step action
- Maintains pedagogical term display regardless of completion state
This creates a more intelligent UI that shows guidance only when needed.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Move the "Next Action" bead movement feedback from the bottom of the step list
to appear directly underneath the current active step. This creates better
visual grouping and clearer association between the step and its required actions.
Changes:
- Wrapped each step in a div to allow inline content
- Positioned bead diff summary with proper left margin alignment
- Removed duplicate "Next Action" section at bottom
- Maintains all existing styling and functionality
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
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>
Surface the bead diff summary as "Next Action" hints in the Step-by-Step Instructions panel.
Provides real-time pedagogical feedback like "remove heaven bead in tens column, then add 4 earth beads in ones column"
to help users understand exactly what bead movements are needed for each step.
Features:
- Dynamic bead diff summary calculation for current step
- Styled feedback panel with blue color scheme
- Only shows when there are actual bead movements needed
- Updates in real-time as user progresses through multi-step sequences
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
The bead diff calculation was hardcoding stepIndex to 0, but AbacusReact's
getBeadStepHighlight function only shows arrows when stepIndex matches currentStep.
This caused arrows to only appear for the first multi-step instruction.
Fixed by setting stepIndex to currentMultiStep to match the AbacusReact filtering logic.
Also removed debugging console logs used to isolate this issue.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Replaces the static getCurrentStepBeads() function with the new dynamic
bead diff algorithm. Now calculates arrows and highlights in real-time
based on current abacus state and target values.
Key improvements:
- Dynamic arrow calculation using calculateBeadDiffFromValues()
- Real-time state transition highlighting
- Comprehensive debug logging for bead diff calculations
- Consistent arrow display across all multi-step instructions
Fixes issue where only the first multi-step instruction showed arrows.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Integrates the dynamic bead diff algorithm into the tutorial editor's
multi-step instruction display. Now shows real-time bead movement
calculations and summaries for each step in the editing interface.
Features:
- calculateStepStatesAndDiffs() function for incremental state transitions
- Dynamic bead diff display with movement summaries
- Enhanced debugging output showing state transitions
- Visual feedback for each multi-step instruction
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add unified step generator to the tutorial editor with enhanced UI controls
and pedagogical decomposition display.
UI enhancements:
- ✨ Unified Generator button alongside Legacy Generator for comparison
- Prominent green display showing pedagogical decomposition expressions
- Integration in both main instruction generation and multi-step sections
- Backward compatibility with existing legacy system
The unified generator provides expressions like "3 + 14 = 3 + 10 + (5 - 1) = 17"
that directly map to bead movements, solving the "three scattered aspects" problem
by computing pedagogical decomposition, English instructions, and expected states
simultaneously in one function.
Users can now access the unified system at /tutorial-editor and see consistent
pedagogical breakdowns with guaranteed accuracy.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Updates TutorialPlayer to use the same auto-generation algorithm as Storybook stories,
removing hard-coded special cases and ensuring consistent pedagogical ordering.
Enhances Storybook stories with expected states calculation demonstration to showcase
the corrected step-by-step progression that matches tutorial editor functionality.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Removes "⚠️ Order mismatch detected" warning from tutorial editor and implements proper
expected state calculation now that multiStepInstructions use correct pedagogical ordering.
The tutorial editor now shows accurate step-by-step expected states by calculating
cumulative bead movements in pedagogical order, matching the fixed stepBeadHighlights.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
AbacusInstructionGenerator:
- Add stepBeadHighlights generation for progressive instruction support
- Implement generateStepBeadMapping for step-by-step bead coordination
- Add comprehensive multi-step instruction generation
- Support for totalSteps and step indexing
- Enhanced pedagogical decomposition with proper step breakdown
Tests:
- Add comprehensive test coverage for instruction generator enhancements
- Test step bead highlight generation and multi-step workflows
Components:
- Update GuidedAdditionTutorial to use direct place values instead of utilities
- Fix AutoInstructionDemo import paths for styled-system compatibility
- Update TutorialConverter to support new instruction format
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
TutorialPlayer:
- Add currentMultiStep state tracking for step progression
- Implement static expected steps generation with proper milestones
- Add step advancement logic with value change detection
- Support dynamic arrow generation toward current expected step target
- Add comprehensive debugging and state management
TutorialEditor:
- Add automatic instruction generation integration
- Implement generateInstructionsForStep function
- Add manual instruction editing UI with multi-step support
- Support for tooltips, error messages, and action descriptions
- Add UI controls for multi-step instruction management
Tutorial Types:
- Extend interfaces to support multi-step instruction workflows
- Add support for step bead highlights and progression tracking
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixed bug where tutorial highlighting appeared in wrong column:
- placeValue 0 (ones place) now correctly maps to columnIndex 4 (rightmost)
- placeValue 1 (tens place) now correctly maps to columnIndex 3
- Added comprehensive test suite to catch highlighting regressions
Tutorial steps now highlight beads in the correct columns.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Fix highlighting logic bug where multiple beads in same column would overwrite each other
- Migrate TutorialStep interface from columnIndex to placeValue system
- Update tutorial data to use place values (0=ones, 1=tens, etc.)
- Fix bead validation logic to use place values instead of legacy columnIndex
- Enable proper multi-step tutorial highlighting for complement operations
Tutorial steps like "3 + 4 = 5 - 1" now correctly highlight both the heaven bead
(add 5) and earth bead (remove 1) simultaneously.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Implement 150ms debounced value change handler to prevent tutorial
system bottlenecks during rapid bead dragging
- Allow abacus to render smoothly by deferring expensive tutorial
operations (validation, state updates, event logging) until
gestures settle
- Add proper cleanup and ref synchronization for debounced values
- This should eliminate UI lag when dragging beads up and down rapidly
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Memoize playerStepIndex calculation using useMemo to prevent
expensive recalculation on every render
- Memoize playerKey generation to avoid string concatenation overhead
- Replace complex inline ternary operations with clean memoized values
- This should further improve abacus gesture performance on tutorial-editor page
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Memoize custom styles calculation using useMemo to prevent expensive
recalculation on every render
- Move complex highlightBeads.reduce() operation out of inline prop
- Only recalculate when currentStep.highlightBeads actually changes
- This fixes sluggish gesture performance in tutorial abacus
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Updated tutorial and AbacusReact stories to use columnIndex: 4 for
bead highlighting examples, ensuring demonstrations show highlighting
on the correct column (ones place) for single-digit operations.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
Updated test files to use columnIndex: 4 (ones place) instead of
columnIndex: 0 (ten-thousands place) for consistent bead highlighting
in tutorial test scenarios.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Implement Radix UI DropdownMenu for BetweenStepAdd component
- Remove manual useState for dropdown state management
- Add proper Portal rendering to prevent z-index conflicts
- Ensure only one dropdown can be open at a time
- Automatically close dropdowns when clicking outside
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
