Added a 28px × 64px grab tab that extends to the right of the resize
handle divider, providing a larger visual target when the sidebar is
collapsed or near-collapsed.
**Changes:**
- Thin 8px divider remains the draggable area
- Visual grab tab (28px × 64px) extends to right with:
- Rounded corners on top-right and bottom-right (borderRadius)
- Vertical knurled texture for grip appearance
- Drop shadow for depth
- Positioned absolutely, centered vertically
- Tab is visual decoration only (pointerEvents: none)
- Divider remains fully draggable
**Note:** Tab is not draggable itself (library limitation - child elements
outside parent bounds don't trigger drag). The 8px divider is the
interactive area. Tab provides visual affordance when sidebar is collapsed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
**Root Cause:**
Server was generating ALL pages during SSR and passing them as initialData,
which pre-populated the entire loadedPages Map. This bypassed the
virtualization system because pagesToFetch was always empty.
**Changes:**
1. **page.tsx** - Only generate first 3 pages on server
- Changed generateWorksheetPreview() to include startPage/endPage params
- Server now generates min(3, totalPages) instead of all pages
- Added clear comments explaining SSR vs virtualization split
2. **WorksheetPreview.tsx** - Cleaned up debug logging
- Removed all console.log statements added during investigation
- Virtualization logic unchanged (was already correct)
**Result:**
- Initial page load: Fast (only 3 pages)
- Scrolling: Progressive loading with visible network activity
- 100-page worksheet: Loads incrementally as user scrolls
- Memory usage: Only loaded pages in memory, not entire set
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Integrate problem space validation warnings directly into page selector controls with visual indicators and tooltips.
**Visual Indicators:**
- Color-coded dots on page buttons (1-3) and dropdown trigger (4+)
- Yellow dot for low/medium risk, red dot for high/extreme risk
- Consistent styling across all page selection controls
**Tooltips:**
- Hover over page buttons shows detailed validation warnings
- Hover over dropdown trigger shows warnings for selected page
- Hover over dropdown menu items shows warnings for that page count
- Instant show/hide with no delays (delayDuration=0, disableHoverableContent)
**Dropdown Indicator:**
- Trigger button shows mildest (most severe) warning among all items (4, 10, 25, 50, 100)
- Alerts user to warnings before opening dropdown
**Single Source of Truth:**
- All validation uses validateProblemSpace() from utils/validateProblemSpace.ts
- No duplicated logic - banner and page selector share same validation function
- Risk mapping: none → no indicator, low/medium → yellow, high/extreme → red
**UX Improvements:**
- Tooltip closes immediately when dropdown opens (tracked with state)
- Dropdown menu items show inline warning dots before page count
- All tooltips close instantly on mouseout (no hoverable content)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implemented proactive duplicate risk warnings directly in the page selector
UI to guide users toward valid configurations before they encounter issues.
**Features:**
- Color-coded page buttons based on duplicate risk
- Green/brand: Safe (< 50% of space)
- Yellow: Caution (50-80% of space)
- Red: Danger (> 80% of space)
- Warning indicator dots on risky page counts
- Radix UI tooltips on hover explaining the risk
- Live problem space calculation based on current config
**Visual Indicators:**
- Border colors change to yellow/red for risky page counts
- Background tints match risk level when selected
- Small dot in top-right corner for at-risk buttons
- Hover shows detailed tooltip with:
- Total problems requested vs available
- Duplicate risk level
- Actionable recommendations
**Implementation:**
- OrientationPanel.tsx: Added problem space validation logic
- Passes digitRange, pAnyStart, operator, mode from form state
- Uses estimateUniqueProblemSpace() for real-time calculation
- Tooltip messages formatted with recommendations
- Skips validation for mastery+mixed mode (consistent with banner)
**Example:**
1-digit 100% regrouping with 15 problems/page:
- Page 1: Green (15 of 45 available)
- Page 2: Yellow warning (30 of 45)
- Page 3: Red danger (45 of 45 - duplicates inevitable)
Tooltip on page 3: "🚫 Too many duplicates: 45 problems requested, only
~45 unique available. Consider: • Reduce to 1 pages • Increase digit range
• Lower regrouping %"
**Next:** Problem space indicator in config panel showing live estimate
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Created worksheet README and updated root README to ensure all problem
generation documentation is discoverable via linked path.
**Documentation Graph:**
```
README.md (root)
→ apps/web/src/app/create/worksheets/README.md
→ PROBLEM_GENERATION_ARCHITECTURE.md
→ USER_WARNING_IMPROVEMENTS.md
→ .claude/PROBLEM_GENERATION.md
```
**New Files:**
- `apps/web/src/app/create/worksheets/README.md` - Overview of worksheet
system with links to all documentation
**Updated Files:**
- `README.md` - Added "Additional Documentation" section with worksheet
generator and abacus react component links
- `.claude/CLAUDE.md` - Added "Documentation Graph Requirement" at top
stating ALL docs must be reachable from root README
**Why This Matters:**
- Documentation that isn't linked gets forgotten and becomes stale
- New developers start at root README and follow links
- Ensures docs stay discoverable and maintained
- Now enforced as a critical requirement in Claude Code instructions
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
**Problem**: When requesting more problems than exist in the problem space (e.g., 100 problems from 45 unique 1-digit regrouping problems), the generator would repeat the same problem over and over after exhausting unique problems.
**Root Cause**:
- Non-interpolate branch: Used `shuffled.slice(0, ...)` in a loop, always taking from the beginning of the array instead of cycling through
- Interpolate branch: When exhausting unique problems, would mark problem as "seen" and add it, then continue adding the same problem repeatedly
**Fixes**:
1. **Non-interpolate branch** (no progressive difficulty):
- Changed from `while` loop with `slice(0, ...)` to simple `for` loop with modulo
- Now uses `shuffled[i % shuffled.length]` to cycle through entire array
- Example: Problems 0-44 = first shuffle, 45-89 = second shuffle (same order), etc.
2. **Interpolate branch** (progressive difficulty enabled):
- When all unique problems exhausted, now clears the `seen` set to start fresh cycle
- Maintains progressive difficulty curve across all cycles
- Logs cycle count: "Exhausted all 45 unique problems at position 45. Starting cycle 2."
- Example: Each cycle maintains easy→hard progression, just repeats the sorted sequence
**Testing**: With 1-digit regrouping (45 unique problems), requesting 100 problems now produces:
- First 45: All unique problems
- Next 45: Complete repeat of the set
- Final 10: First 10 problems from third cycle
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Problem Generation Improvements:
- Implement hybrid approach: generate-all + shuffle for small problem spaces (< 10k), retry-based for large spaces
- Add countRegroupingOperations() for accurate difficulty sorting
- Support progressive difficulty in generate-all mode by sorting problems before sampling
- Fix problem space estimation for 1-digit problems (was 6075, now correctly returns 45 for 100% regrouping)
Duplicate Warning System:
- Add validateProblemSpace() utility to estimate unique problems and warn users
- Create dismissable warning banner with visual styling (yellow bg, 15px rounded corners, drop shadow)
- Position warning banner as floating element alongside page indicator and action button
- Auto-reset dismissed state when worksheet config changes
- Skip validation for complex mastery+mixed mode
Component Refactoring:
- Extract WorksheetPreviewContext for shared state (warnings, theme, form state)
- Extract DuplicateWarningBanner component with context integration
- Move floating elements (warning banner, page indicator) to PreviewCenter for correct positioning
- Fix scroll container structure: preview-center is positioned container, nested div handles scrolling
- Export page data from WorksheetPreview via onPageDataReady callback
Technical Details:
- FloatingPageIndicator changed from position: sticky to position: absolute
- Warning banner positioned at top: 24px, right: 20px to avoid action button overlap
- Remove maxW constraint on scroll container to allow full width flex
- Server logs now show: "0 retries, generate-all method" for small problem spaces
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Created validateProblemSpace utility to estimate unique problem count
and warn users when worksheet config will produce many duplicates.
Validation levels:
- none: < 30% of space used
- low: 30-50% (minor duplicates expected)
- medium: 50-80% (suggest reducing pages or expanding constraints)
- high: 80-150% (strong warnings with specific recommendations)
- extreme: >150% (mostly duplicates, block generation)
Provides actionable suggestions:
- Reduce page count
- Increase digit range
- Lower regrouping probability
Next: Wire this into the UI to show warnings before generation.
**Problem**: Large worksheets with constrained digit ranges were hanging.
Example: 1000 single-digit problems with 100% regrouping = 168,608 retries
for just 100 problems (1,686 retries/problem on average).
**Root Cause**: Only 9 single-digit numbers (1-9) with 100% regrouping
requirement = very few valid unique combinations. The 3000-retry limit
meant millions of iterations for 1000-2000 problem worksheets.
**Solution**: Reduced retry limit from 3000 to 100 in both:
- generateProblems() (addition)
- generateSubtractionProblems()
This allows some duplicate problems when the constraint space is tight,
but prevents the server from hanging on large worksheet generation.
**Impact**: 100-page worksheets should now generate in seconds instead
of timing out.
Same logging pattern as subtraction generation:
- Log start parameters (count, digit range, probabilities)
- Progress updates every 100 problems
- Track total retry attempts
- Log completion time and average retries per problem
This will show if generateProblems is the bottleneck for 1000 addition
problems in mastery+mixed mode.
Track potential performance bottleneck in generateSubtractionProblems:
- Log start parameters (count, digit range, probabilities)
- Progress updates every 100 problems
- Track total retry attempts across all problems
- Log completion time and average retries per problem
This will show if the 3000-retry loop is causing the hang when
generating 1000 subtraction problems for 100-page worksheets.
Added detailed logging to track performance and identify bottlenecks:
**generatePreview.ts:**
- Step 1: Configuration validation
- Step 2: Problem generation (with count and mode)
- Step 3: Typst source generation (with timing)
- Step 4: SVG compilation (per-page timing and totals)
**preview/route.ts:**
- Log request parameters (pages, problems, range)
- Log total request time
This will help diagnose why 100-page worksheets cause the server to hang.
Removed console.log statements for:
- TYPST PROBLEM additionDisplayRules/subtractionDisplayRules
- TYPST PROBLEM subtraction resolved display
- TYPST DEBUG first problem data
These were creating excessive noise in server logs.
**Problem**: Seeds were being saved to the database but lost when loading
because Zod schemas didn't include seed/prngAlgorithm fields. Zod strips
unknown fields during parsing, so even though extractConfigFields() included
the seed and the database had the seed, parseAdditionConfig() was removing it.
**Root Cause**: The migration from summary showed seed was being extracted and
saved, but server logs showed `hasSavedSeed: false, savedSeed: undefined`.
Database query confirmed seed WAS in the JSON (seed: 1977890241), but
migrateAdditionConfig() → additionConfigSchema.safeParse() was stripping it.
**Fix**: Added seed and prngAlgorithm as optional fields to ALL schema versions:
- V1: Added to additionConfigV1Schema
- V2: Added to additionConfigV2Schema
- V3: Added to additionConfigV3BaseSchema (inherited by Smart/Manual modes)
- V4: Added to additionConfigV4BaseSchema (inherited by Smart/Manual/Mastery modes)
**Impact**: Seeds will now persist correctly through the full save/load cycle.
Users can reload the page and see the exact same problems.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
**Problem**: Worksheet seeds were not persisting because configs with >20 pages
failed Zod schema validation (max was 20), even though the code elsewhere allowed
up to 2000 total problems. When validation failed, the config fell back to defaults,
losing the saved seed.
**Changes**:
1. Created `constants/validation.ts` with centralized limits:
- MAX_PAGES: 100 (was 20 in schemas)
- MAX_TOTAL_PROBLEMS: 2000
- MAX_PROBLEMS_PER_PAGE: 100
- MAX_COLS: 10
- DIGIT_RANGE: { MIN: 1, MAX: 5 }
- FONT_SIZE: { MIN: 8, MAX: 32 }
- Helper function validateWorksheetLimits()
2. Updated all Zod schema versions (V1-V4) in `config-schemas.ts` to use constants
3. Updated runtime validation in `validation.ts` to use constants
4. Enhanced settings API (`route.ts`) to:
- Validate worksheet limits before saving
- Validate against Zod schema
- Return clear error messages with actionable guidance
5. Enhanced auto-save hook (`useWorksheetAutoSave.ts`) to:
- Return saveError state
- Surface validation errors to user
- Clear errors on successful save
6. Removed TEN-FRAMES DEBUG logging from displayRules.ts
**Impact**: Worksheet configs with 21-100 pages will now pass validation and
persist correctly, including the seed. Users will see clear error messages if
their config exceeds limits.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The bug: Server-side page.tsx was ALWAYS generating a new seed with
Date.now() on every page load, even when loading saved settings from
the database. This caused different problems on every reload.
The fix:
- Check if saved config has a seed, use it if present
- Only generate new seed if no saved seed exists (first visit)
- Also preserve prngAlgorithm from saved config
This ensures:
- Reloading the page shows the same problems (from auto-saved seed)
- Shared worksheets show same problems (from shared seed)
- First-time visitors get a new random seed
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Ensures that shared and auto-saved worksheets generate the exact same
problems when loaded:
Seed & Algorithm Persistence:
- Added seed and prngAlgorithm to extractConfigFields()
- Both fields now included in auto-save, sharing, and settings persistence
- prngAlgorithm defaults to 'mulberry32' (current implementation)
Type Updates:
- Added prngAlgorithm: string to WorksheetConfig (required)
- Added prngAlgorithm?: string to WorksheetFormState (optional)
- Updated extractConfigFields return type to include both fields
Problem Reproducibility:
- Same seed + same algorithm = exact same problems
- Critical for sharing worksheets with specific problem sets
- Allows reload to show same problems (via auto-save)
- Future-proofs for potential algorithm changes
Documentation Updates:
- Updated useWorksheetAutoSave comments to reflect seed persistence
- Clarified that seed/algo are critical for reproducibility, not transient
Bug Fix:
- Fixed broken link on /create page (/create/worksheets/addition → /create/worksheets)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Enhanced PagePlaceholder component to show a visual preview of the actual
worksheet layout:
Layout Matching:
- Calculate rows per page correctly (problemsPerPage / cols)
- Match exact page dimensions (816×1056 portrait, 1056×816 landscape)
- Display cartoonish grid with correct rows × cols matching worksheet
Visual Design:
- Header bars mimicking name/date fields
- Problem cells with mini bars representing:
- Problem number (top-left)
- Two operands (right-aligned)
- Answer line separator
- Semi-transparent grid overlay with centered info badge
Unified Loading States:
- Single component handles both idle and loading states
- Idle: "Scroll to load" with slower pulse
- Loading: Spinning hourglass with "Loading page X..."
- Both show same grid layout for consistency
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Update PagePlaceholder to match the actual worksheet page size:
**Changes**
- Add orientation prop to PagePlaceholder (portrait/landscape)
- Use CSS aspect-ratio to match 8.5" × 11" pages
- Portrait: aspect ratio 1:1.294 (8.5:11)
- Landscape: aspect ratio 1.294:1 (11:8.5)
- Replace minHeight with width: 100% + aspectRatio
- Remove minHeight from page container
- Pass orientation from formState to placeholder
**Benefits**
- No layout shift when pages load
- Placeholders are exactly the same size as loaded pages
- Proper aspect ratio for both portrait and landscape
- Maintains scroll position during lazy loading
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Move page counts 10+ (10, 25, 50, 100) into a Radix UI dropdown menu:
**UI Improvements**
- Keep buttons for 1-4 pages (quick access)
- Add "10+" dropdown button for larger page counts
- Show selected page count in dropdown button when > 4
- Dark mode support for dropdown with proper theming
- Checkmark indicator for selected page count in menu
**Benefits**
- Cleaner UI - only 5 buttons instead of 8
- Less visual clutter in layout panel
- Maintains quick access for common cases (1-4 pages)
- Dropdown provides context with "X pages" labels
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add efficient lazy loading for large worksheets with animated page indicators:
**Lazy Loading & Pagination**
- Implement range-based and cursor-based pagination in API
- Only generate SVG for visible pages (3 initially, more on scroll)
- Use IntersectionObserver to detect when pages enter viewport
- Fetch pages in batches as user scrolls through worksheet
- Support up to 2000 problems (100 pages × 20 problems/page)
**API Changes**
- Update /api/create/worksheets/preview to accept pagination params
- Support cursor-based: ?cursor=3&limit=5 (GraphQL style)
- Support range-based: ?startPage=3&endPage=7 (traditional)
- Return metadata: totalPages, startPage, endPage, nextCursor
**Generation Logic**
- Modified generateWorksheetPreview() to accept startPage/endPage
- Generate all problems deterministically (required for seed)
- Generate all Typst sources (lightweight)
- Only compile requested page range to SVG (expensive)
**UI Improvements**
- Add page count options: 1, 2, 3, 4, 10, 25, 50, 100 pages
- Show loading spinner (⏳) while fetching pages
- Add NumberFlow for smooth animated page number transitions
- Fix page indicator flickering with hysteresis (0.6 threshold)
**Performance**
- 100-page worksheet: ~30s load → ~1s initial + lazy loading
- Only generates 3 pages initially instead of all 100
- Smooth scrolling with preloaded adjacent pages
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Created generateSinglePage() function that:
- Generates all problems (using seed + random algorithm)
- Generates all Typst sources (lightweight)
- Only compiles the requested page to SVG (expensive operation)
This avoids compiling 100 pages of Typst when you only need page 1.
New API endpoint: POST /api/create/worksheets/preview/[pageNumber]
Returns: { page: string, totalPages: number }
Next: Update frontend to lazy-load pages as they become visible.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added detailed logging showing which pages are actually rendering SVG
content vs showing placeholders. Also added data-page-rendered attribute
to make it easy to inspect in DevTools.
This will confirm whether virtualization is actually preventing DOM
rendering or if all pages are being rendered.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The virtualization was adding pages but never removing them, causing
all pages to eventually be rendered and defeating the purpose.
Changed logic to:
1. Start with empty set for each observer callback
2. Add currently intersecting pages + adjacent pages
3. Keep pages that weren't observed in this callback (unchanged)
4. Remove pages that are observed but not intersecting
This ensures pages are removed from the visible set when scrolled away.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Changed all console.log calls to use string concatenation instead of
object logging, making output easy to copy/paste as plain text.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Removed general page indicator logging and added focused logging for:
- shouldVirtualize decision
- visiblePages state changes
- Observer setup confirmation
- When pages are added to visible set
- What's actually being rendered (pages vs placeholders)
This will help identify why virtualization isn't working.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Virtualization should be based on page count, not whether config came
from a share link or user session. This separates concerns properly:
- initialData: Only for React Query SSR/initial data (avoid spinner)
- shouldVirtualize: Based on totalPages > 1 (performance decision)
Benefits:
- Shared worksheets now virtualize multi-page content
- Creator worksheets virtualize regardless of config source
- Simpler logic, no special cases for isFromShare
- Performance optimization applies uniformly
Before: shouldVirtualize = !initialData (wrong coupling)
After: shouldVirtualize = totalPages > 1 (correct decision)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Only pass initialPreview to WorksheetPreview when viewing a shared
worksheet (isFromShare). In the worksheet creator, we want
virtualization enabled for performance with multi-page worksheets.
This ensures:
- Worksheet creator: virtualizes pages (lazy render)
- Shared worksheets: shows all pages immediately (no lazy loading)
The page indicator now works correctly in both modes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The IntersectionObserver was only set up when virtualizing pages,
but the page indicator needs to work in both modes:
- Virtualized mode (worksheet creator): lazy load pages
- Non-virtualized mode (shared worksheets): show all pages
Changed observer setup to always run when totalPages > 1, regardless
of virtualization mode. The visible pages update logic still only
runs when virtualizing to avoid unnecessary state updates.
This fixes the page indicator being stuck on page 1 when initialData
is provided (non-virtualized mode).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added detailed logging to track:
- When currentPage state changes
- When IntersectionObserver setup runs
- Observer callback triggers with entry details
- Most visible page calculation
- Refs ready status
This will help identify why page indicator stays on page 1.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The IntersectionObserver callback was using currentPage from closure to
initialize mostVisiblePage, but this was always stale (stuck at 0).
Changed to start mostVisiblePage at 0 instead of currentPage, so it
correctly tracks the most visible page across all entries without
relying on stale state.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implement comprehensive skill customization system allowing teachers to:
- Configure existing default skills with custom difficulty settings
- Create entirely new custom skills from scratch
- Visualize skills in mastery progression context with directional edges
- Interact with difficulty space using 2D plot with hover tooltips
Database Schema:
- custom_skills table: Stores user-created skills
- skill_customizations table: Stores modifications to default skills
- Both tables track regrouping config, display rules, and metadata
API Endpoints:
- POST /api/worksheets/skills/custom - Create custom skill
- GET /api/worksheets/skills/custom - List custom skills
- PUT /api/worksheets/skills/custom/[id] - Update custom skill
- DELETE /api/worksheets/skills/custom/[id] - Delete custom skill
- POST /api/worksheets/skills/[skillId]/customize - Save customization
- GET /api/worksheets/skills/customizations - List customizations
Components:
- DifficultyPlot2D: Interactive 2D visualization of difficulty space
- Regrouping Intensity (x-axis) × Scaffolding Level (y-axis)
- Dual mode: Default presets vs Mastery progression skills
- Directional edges showing skill progression sequence
- Hover tooltips with skill details
- Click to select configuration
- Visual legend explaining elements
- SkillConfigurationModal: Modal for skill configuration
- Name and description fields
- Digit range slider
- 2D difficulty plot integration
- Shows mastery progression context when editing
- Real-time configuration summary
- MasteryModePanel Integration:
- "Configure Skill" button for existing skills
- "Create Custom Skill" button for new skills
- Passes mastery progression to modal for context
Visual Design:
- Purple theme (#9333ea) for mastery progression skills
- Green theme (#10b981) for current configuration
- Dashed arrows with triangular arrow heads
- Numbered skill circles with hover tooltips
- Compact legend in top-right corner
Technical Features:
- PlotPoint interface for custom skill plotting
- Conditional snapping to either presets or custom points
- Vector math for arrow head calculations
- Z-ordering: edges before points
- Event propagation control for hover interactions
- Storybook examples for both components
Bug Fixes:
- Fix page indicator stuck on page 1 in WorksheetPreview
- Changed from threshold-based to most-visible-page tracking
- Works correctly for both scroll directions
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Database changes:
- Add custom_skills table for user-created skills
- Add skill_customizations table for modified default skills
- Both tables support per-user, per-operator configurations
- Include digit range, regrouping config, and display rules
Schema includes:
- Foreign keys to users table with cascade delete
- Composite primary key for skill_customizations
- Index on (user_id, operator) for efficient queries
This enables:
- Teachers to create custom skills for mastery progression
- Teachers to customize default skill configurations
- Per-user skill configurations (don't affect other users)
- Full reversi bility (reset to defaults)
Next steps: API endpoints, SkillConfigurationModal UI
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Removed console.log statements added during debugging:
- Theme change logging in SharedWorksheetPage
- Fetch and preview generation logging
- WorksheetPreview page visibility logging
- generatePreview problem count logging
All issues have been resolved, debug logs no longer needed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Problem: View count was incrementing by 2 on each page load due to React
StrictMode causing useEffect to run twice in development.
Solution: Use a ref to track if the fetch has already been initiated and
skip duplicate calls. This ensures:
- Dev behavior matches production (single API call)
- View count increments correctly (by 1, not 2)
- No duplicate network requests
This is the correct pattern for effects that should only run once,
even in StrictMode.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Bug fix:
- Preview API was not calculating `total` field (pages × problemsPerPage)
- This caused only 1 page to generate even when config specified 4 pages
- Now correctly calculates total, rows, and other derived fields
Added debug logging:
- Log problem count and config in generatePreview
- Log Typst sources page count
- Log preview page count in shared worksheet viewer
- These logs help diagnose multi-page rendering issues
This fixes the issue where shared worksheets only showed the first page
even when the config specified multiple pages.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Changes to shared worksheet viewer (/worksheets/shared/[id]):
- Move Download, Share, Edit actions from banner to floating action menu
- Main button shows "Edit" in read-only mode (most common action)
- Download and Share available in dropdown menu
- Simplified banner to show only read-only indicator
- Made banner light/dark mode ready with theme-aware colors
Changes to PreviewCenter component:
- Added onShare and onEdit props for read-only mode
- Main button adapts: "Edit" for read-only, "Download" for edit mode
- Dropdown menu adapts based on mode (Download/Share vs Share/Upload)
- Floating action button now always visible
Changes to WorksheetPreview component:
- Fixed virtualization to show all pages when initialData provided
- Shared worksheets now display all pages immediately (no lazy loading)
- Interactive editor still uses virtualization for performance
- Added debug logging for page visibility and theme changes
Bug fixes:
- Fixed page virtualization preventing multiple pages from showing
- Made shouldVirtualize persistent across re-renders
- Added comprehensive logging for debugging theme and page issues
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fix banner positioning to properly sit below the nav bar:
- Changed from `position: fixed; top: 16` to `paddingTop: var(--app-nav-height)`
- Matches the same approach used in AdditionWorksheetClient
- Added `flexShrink: 0` to banner to prevent it from shrinking
- Changed PanelGroup from `overflow: hidden` to `minHeight: 0` for proper flex layout
- Now banner and panels are correctly positioned within PageWithNav
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add action buttons to shared worksheet banner for quick actions:
**Download Button (⬇️)**
- Generates and downloads the worksheet as PDF
- Uses current date for generation
- Filename includes share ID for reference
**Re-share Button (🔗)**
- Creates a new share link for the same configuration
- Copies link to clipboard automatically
- Shows alert confirmation (TODO: replace with toast)
**Edit Button**
- Renamed from "Edit This Worksheet" to just "Edit" for consistency
- Same functionality (opens modal with overwrite warning)
All three buttons styled consistently in the blue banner with hover effects.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Transform shared worksheet experience from simple info page to full read-only studio:
**Shared Worksheet Viewer (/worksheets/shared/[id])**
- Show full worksheet studio UI in read-only mode
- Display live preview with actual worksheet rendering
- Blue banner indicates "Shared Worksheet (Read-Only)"
- Config sidebar shows all settings but disabled for interaction
- Clear "Edit This Worksheet" button with overwrite warning modal
**Edit Modal**
- Warns that editing will overwrite current worksheet settings
- Provides tips (download current worksheet first, or use different browser)
- Two-step confirmation prevents accidental data loss
- Saves shared config to user's session before navigating to editor
**Read-Only Mode Infrastructure**
- WorksheetConfigContext: Added isReadOnly prop
- ConfigSidebar: Shows "👁️ Read-Only" badge, disables inputs with pointer-events
- PreviewCenter: Hides Download/Share/Upload buttons when read-only
- StudentNameInput: Added readOnly prop with disabled styling
**Mastery Mode Field Persistence**
- extractConfigFields: Now includes currentStepId, currentAdditionSkillId, currentSubtractionSkillId
- Fixes issue where mastery mode worksheets couldn't be shared properly
- Future shares will include all required mastery mode fields
**Error Handling**
- Created /api/worksheets/preview route for server-side preview generation
- generatePreview: Returns detailed error messages instead of fallbacks
- Shared viewer: Shows prominent error card with diagnostic details
- Error format: "Missing skill IDs - addition: none, subtraction: none. This config may have been shared before mastery mode fields were added."
**Architecture Changes**
- Shared page now calls API for preview (avoids importing Node.js child_process in client)
- Clear separation between client components and server-side generation
- Proper error propagation from preview generation to UI
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implement comprehensive fix to ensure worksheet sharing uses the same
persistence/loading logic as user session management.
**Problem:**
- Share save sent unfiltered formState with derived/UI state
- Share load used JSON.parse without validation/migration
- Inconsistent with user session which extracts specific fields and validates
**Solution:**
1. Create extractConfigFields helper (DRY principle)
- Single source of truth for persisted fields
- Excludes derived state (rows, total, date, seed)
- Type-safe extraction of 24 config fields
2. Update useWorksheetAutoSave to use helper
- Replace 50+ lines of manual extraction
- Ensures consistency across all save operations
3. Update all share creation paths
- PreviewCenter: extractConfigFields(formState)
- ActionsSidebar: extractConfigFields(formState)
- ShareModal: extractConfigFields(config)
4. Update share load API to use parseAdditionConfig
- Validates config structure
- Migrates old versions (v1/v2/v3) to v4
- Matches user session loading logic exactly
**Benefits:**
- Consistency: Share and session use identical logic
- Validation: All configs validated before saving/loading
- Migration: Old shared configs auto-migrate to current schema
- Maintainability: 100+ lines reduced to ~30, single source of truth
**Files Changed:**
- utils/extractConfigFields.ts (new helper)
- hooks/useWorksheetAutoSave.ts (refactored to use helper)
- components/PreviewCenter.tsx (use helper)
- components/ActionsSidebar.tsx (use helper)
- components/ShareModal.tsx (use helper + type fix)
- api/worksheets/share/[id]/route.ts (use parseAdditionConfig)
Fixes ensure shared worksheets are persisted and loaded with the same
validation, versioning, and migration as user settings.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add two comprehensive blog posts introducing subtraction and multi-digit
worksheet features with visual examples:
**Subtraction Worksheets Post:**
- 7 progressive scaffolding levels (no-borrowing through cascading borrows)
- Side-by-side comparisons showing impact of borrow notation
- Teaching progression guide (7+ week curriculum)
- 9 SVG examples demonstrating different scaffolding options
- Focus on borrow notation boxes and place value colors
**Multi-Digit Worksheets Post:**
- Support for 1-5 digit arithmetic problems
- 6-color place value system across all digit ranges
- Mixed problem sizes within single worksheet
- Adaptive scaffolding based on digit count
- 6 SVG examples (2-digit baseline through 5-digit advanced)
**Code Fixes:**
- Fix typstGenerator.ts: Pass showBorrowNotation instead of showCarryBoxes
to subtraction-problem-stack function (line 220)
- Simplify hint text rendering in borrowBoxes.ts (remove nested text elements)
**Generated Assets:**
- 9 subtraction examples in public/blog/subtraction-examples/
- 6 multi-digit examples in public/blog/multi-digit-examples/
- New generation scripts: generateSubtractionExamples.ts,
generateMultiDigitExamples.ts
Note: Borrowing hints feature (arrows with calculations) needs additional
debugging in Typst rendering layer. Current blog posts focus on working
features: borrow notation boxes, place value colors, and progressive
scaffolding.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Switch from client-side sessionStorage to server-side database loading:
Server-Side Loading (page.tsx):
- Accept searchParams with optional ?share=abc123X query param
- loadWorksheetSettings() now takes optional shareId parameter
- If shareId provided, loads from worksheet_shares table
- Falls back to user settings if share not found
- Uses same parseAdditionConfig() for consistency
Shared Worksheet Viewer:
- Simplified handleOpenInEditor to pass share ID in URL
- No longer uses sessionStorage for config transfer
- Navigates to /create/worksheets?share=abc123X
- Server handles loading on next page
Client Component:
- Removed sessionStorage logic and useSearchParams
- Removed useEffect and useState for config loading
- Simplified back to original implementation
- Just receives initialSettings from server
Benefits:
- Consistent loading pattern for both user and shared configs
- Server-side validation and parsing before rendering
- No client-side state management for config loading
- Eliminates race conditions and hydration issues
- Share loading identical to database settings loading
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add complete viewer page for shared worksheet links:
Shared Worksheet Page (/worksheets/shared/[id]):
- Fetches shared config from GET /api/worksheets/share/[id]
- Displays worksheet type, view count, creation date
- Shows configuration summary (operator, problems, pages, digit range)
- Loading state with spinner during fetch
- Error handling for 404/failed loads
Open in Editor:
- "Open in Editor" button loads config into worksheet creator
- Uses sessionStorage to pass config from viewer to editor
- Navigates to /create/worksheets?from=share
- Auto-clears sessionStorage after loading
Editor Integration:
- AdditionWorksheetClient checks for ?from=share query param
- Reads sharedWorksheetConfig from sessionStorage on mount
- Replaces initialSettings with shared config
- Cleans up sessionStorage after load
Navigation:
- Error state includes "Create Your Own Worksheet" button
- All navigation uses correct /create/worksheets path
User Flow:
1. User receives share link (/worksheets/shared/abc123X)
2. Views config details and QR code
3. Clicks "Open in Editor"
4. Editor loads with exact shared configuration
5. Can modify and save as their own
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
