feat: Lesson Stage System (#199) by Peleke · Pull Request #219 · Peleke/interlinear

Peleke · 2026-01-07T21:04:12Z

Summary

Implements the lesson stage system (Epic #199) with full integration.

Core Features

5-Stage Progression: Learn → Read → Practice → Review → Assess (inspired by Kanshudo)
Completion Criteria: Time-based, word clicks, exercise count, flashcard review, quiz scores
Progress Tracking: Per-user stage completion with RLS security

Database Changes

lesson_stage_type enum with 5 stages
lesson_stages table for stage configuration
user_lesson_stage_progress table for tracking progress
Helper functions for progress calculation
Backfill migration for existing lessons

Components Added

LessonStageViewer - Main stage progression container
StageProgressBar - Visual progress indicator with clickable stages
ViewModeToggle - 3-way toggle (Classic/Hub/Stages)
Stage content components:
- LearnStageContent - Time-based introduction
- ReadStageContent - Interactive reading with word tracking
- PracticeStageContent - Pick N of M exercises
- ReviewStageContent - Flashcard review integration
- AssessStageContent - Quiz with scoring and retry

Integration

Updated LessonViewer for 3 view modes
Updated lesson page to fetch and pass stages
Full backward compatibility with existing classic/hub views

Test Plan

Run migrations on staging database
Verify backfill creates stages for all existing lessons
Test stage toggle appears in lesson header
Test stage progression tracking persists
Test with Vibras Puras lessons
Verify XP integration works

Related Issues

Closes Stage schema and database migration #200 - Schema Migration
Closes LessonStageViewer component #201 - UI Components (Stage Viewer)
Closes Stage progress bar component #202 - UI Components (Content Components)
Closes Completion criteria logic #203 - Integration Mapping
Closes Add 3-way view toggle (classic/hub/stages) #221 - 3-way view toggle
Closes Wire up LessonStageViewer to lesson pages #222 - Wire up LessonStageViewer
Closes Create stage backfill migration script #223 - Backfill migration

🤖 Generated with Claude Code

- Add lesson_stage_type enum (learn, read, practice, review, assess) - Create lesson_stages table for configuring stage progression - Create user_lesson_stage_progress table for tracking user progress - Add RLS policies for stage access control - Add helper functions: calculate_lesson_progress, get_next_stage - Add TypeScript types for stages and progress data - Add lib/stages utilities for stage management Part of Epic #199 - Lesson Stage System 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

#202, #203) Components: - LessonStageViewer: Main container with stage navigation and progress tracking - StageProgressBar: Visual progress indicator with stage dots - StageProgressIndicator: Minimal progress bar for headers - Stage content components: Learn, Read, Practice, Review, Assess Features: - Sequential stage progression with completion tracking - "Pick N of M" exercise selection for Practice stage - Time-based completion criteria for Learn stage - Word click tracking for Read stage - Score-based assessment with retry option Tests: - 20 unit tests for checkStageCompletion function - All stage completion logic tested for each stage type Config: - Added coverage thresholds to vitest.config.ts (ratchet to prevent regression) - Fixed duplicate test script in package.json Part of Epic #199 - Lesson Stage System 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…#223) - Add ViewModeToggle component with classic/hub/stages modes - Integrate LessonStageViewer into LessonViewer for stages mode - Create backfill migration for existing lessons - Fetch and pass lesson stages to LessonViewer - Update hub index to export ViewModeToggle Part of Epic #220 - Stage System Integration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Peleke · 2026-01-07T21:09:42Z

Integration Update

Added stage system integration with the following changes:

New Components

ViewModeToggle - 3-way toggle (Classic/Hub/Stages views)

Modified Components

LessonViewer - Now supports 3 view modes, renders LessonStageViewer for stages view
page.tsx - Fetches lesson stages from database

Database Migrations

20260107_backfill_lesson_stages.sql - Backfills default stages for all existing lessons

Integration Plan

The following child issues track the work:

Add 3-way view toggle (classic/hub/stages) #221 - Add 3-way view toggle ✅
Wire up LessonStageViewer to lesson pages #222 - Wire up LessonStageViewer ✅
Create stage backfill migration script #223 - Create backfill migration ✅

Testing Status

TypeScript compilation: ✅ No stage-related errors
Components integrated: ✅

Next Steps

Run the backfill migration on the database
Test with Vibras Puras course lessons
Verify stage progression tracking works end-to-end

🤖 Generated with Claude Code

Renamed migrations with numeric prefixes to ensure correct ordering: - 20260107_01_lesson_stage_system.sql (schema first) - 20260107_02_backfill_lesson_stages.sql (backfill second) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Tests for the 5-stage lesson progression system: - View Mode Toggle: 3-way toggle display and switching - Stages View: Stage progression UI rendering - Learn Stage: Time-based progress tracking - Stage Navigation: Previous/Next button functionality - Progress Persistence: Stage progress indicator display All 7 tests passing: - should display 3-way view toggle in lesson header - should switch between Classic and Hub views - should display stage progression UI when Stages view is selected - should show time-based progress in Learn stage - should navigate between stages using Previous/Next buttons - should show stage progress indicator in header 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Peleke · 2026-01-07T21:17:20Z

E2E Tests Added

Added comprehensive Playwright E2E tests for the lesson stage system.

Test Results: ✅ All 7 tests passing

Running 7 tests using 5 workers

  ✓ [setup] authenticate (1.8s)
  ✓ should display 3-way view toggle in lesson header (6.6s)
  ✓ should switch between Classic and Hub views (8.3s)
  ✓ should display stage progression UI when Stages view is selected (9.1s)
  ✓ should navigate between stages using Previous/Next buttons (9.8s)
  ✓ should show time-based progress in Learn stage (10.9s)
  ✓ should show stage progress indicator in header (6.1s)

7 passed (15.8s)

Tests Cover:

View Mode Toggle
- 3-way toggle (Classic/Hub/Stages) is visible
- Switching between views works
Stages View
- Stage progression UI renders correctly
- Stage header shows current stage (e.g., "Stage 1: Learn")
- Navigation between stages via Previous/Next buttons
Learn Stage
- Time tracking UI displays correctly
- Progress messages appear ("Spend at least 30 seconds...")
Progress Persistence
- Stage progress indicator (0/5) is visible
- 10 stage indicator dots found (5 stages × 2 for progress + current)

File Location

tests/e2e/stages/lesson-stage-system.spec.ts

🤖 Generated with Claude Code

- Add ProgressRing SVG component with smooth fill animation - Position ring in top-right corner, out of content flow - Show percentage in center, checkmark when complete - Display elapsed time and target below ring - Update button text to show countdown ("27s remaining...") - Update E2E test selectors to match new UI 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…viewer - Add breadcrumb navigation: Course > Lesson > Current Stage - Integrate shimmer/gradient effects matching existing design system - Add gradient accent line at header top - Enhanced visual styling for lesson context and stage header - Update E2E tests to match new header format (numbered circle + label) - Add full stage completion flow E2E test with tutorial overlay handling - Fix test selectors for new stage UI patterns 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

## Schema (graph-ready architecture) - Enhanced `grammar_concepts` with language, slug, hierarchy, source_refs - New `lexicon_entries` for language-agnostic vocabulary - New `text_sources` for manuscripts/corpora (sagas, codexes, grammars) - New `text_occurrences` for specific text passages with glossing - Edge tables: `grammar_relationships`, `grammar_lexicon_links`, `lexicon_occurrences` - Helper functions: `get_grammar_tree()`, `get_related_concepts()` ## UI - `/grammar` index page with language tabs (Latin 🏛️, Old Norse ⚔️, Gothic 📜) - `/grammar/[slug]` detail page with breadcrumbs, examples, related concepts - Category filters (morphology, syntax, phonology) - Search functionality - CEFR difficulty badges ## Seed Content ### Latin (from Allen & Greenough, EIEOL) - 6 cases with full paradigms and examples - 3 declensions (1st, 2nd, 3rd) - 2 conjugations (1st, 2nd) ### Gothic (from Wright's Grammar, EIEOL) - Alphabet with Wulfila's script - Noun declension classes (strong/weak) - Verb classes (strong ablaut, weak dental) ### Old Norse (from EIEOL) - Umlaut (i-umlaut, u-umlaut) with sound change tables - Noun declensions with paradigms - Verb classes - Vǫluspá stanza 1 with full grammatical analysis ## Architecture Notes - Designed for future graph DB migration (Memgraph) - Source references tracked for all content - Leipzig glossing format for morphological analysis - Cross-language relationships for comparative linguistics 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Peleke · 2026-01-14T21:10:08Z

Closing - stages code was already merged to staging via PR #233 (squash merge included all stage components). No action needed.

Peleke Sengstacke and others added 2 commits January 7, 2026 15:50

Peleke mentioned this pull request Jan 7, 2026

Epic: Stage System Integration (#199) #220

Open

7 tasks

Peleke Sengstacke and others added 2 commits January 7, 2026 16:13

Peleke Sengstacke and others added 2 commits January 7, 2026 16:22

Peleke mentioned this pull request Jan 7, 2026

feat: Visual Image System - Schema, Storage, and Component Updates #225

Merged

6 tasks

Peleke closed this Jan 14, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Lesson Stage System (#199)#219

feat: Lesson Stage System (#199)#219
Peleke wants to merge 8 commits intostagingfrom
feature/lesson-stage-system

Peleke commented Jan 7, 2026 •

edited

Loading

Uh oh!

Peleke commented Jan 7, 2026

Uh oh!

Peleke commented Jan 7, 2026

Uh oh!

Peleke commented Jan 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Peleke commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Core Features

Database Changes

Components Added

Integration

Test Plan

Related Issues

Uh oh!

Peleke commented Jan 7, 2026

Integration Update

New Components

Modified Components

Database Migrations

Integration Plan

Testing Status

Next Steps

Uh oh!

Peleke commented Jan 7, 2026

E2E Tests Added

Test Results: ✅ All 7 tests passing

Tests Cover:

File Location

Uh oh!

Peleke commented Jan 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Peleke commented Jan 7, 2026 •

edited

Loading