@dzhechkov/keysarium 1.3.0 → 1.5.0

package/templates/.claude/skills/edu-site-generator/modules/04-components.md

@@ -0,0 +1,130 @@
+# Step 4: Components
+
+## Goal
+Generate all React components: layout, interactive exercises, sections, pages, and common utilities.
+
+## Protocol
+
+Read `references/component-templates.md` for full component code.
+
+### Generation Order
+
+1. **Layout components** (no dependencies on data):
+   - `Header.jsx` — sticky top bar with title, score, progress %, dark mode toggle, nav toggle, final test link
+   - `Footer.jsx` — bottom bar with copyright, optional social link
+   - `Navigation.jsx` — sidebar with section links (uses `scrollIntoView` NOT `<a href="#...">` to avoid HashRouter conflicts)
+   - `ProgressBar.jsx` — visual bar showing course progress
+   - `SectionLayout.jsx` — wrapper for each section: icon, title, description, completion badge, theory, children
+
+2. **Interactive components** (reusable, data-driven):
+   - `Quiz.jsx` — multiple choice with score tracking
+   - `Flashcard.jsx` — flip cards for term memorization
+   - `MatchingExercise.jsx` — pair matching with shuffle
+   - `DragOrder.jsx` — drag-and-drop ordering (@dnd-kit)
+   - `CommandBuilder.jsx` — click-to-build command
+   - `ScenarioGame.jsx` — multi-step scenario with choices
+
+3. **Common components:**
+   - `Accordion.jsx` — expandable FAQ items
+   - `AchievementsPanel.jsx` — grid of achievement badges
+   - `Toast.jsx` — notification popup for achievements
+   - `useSwipeNav.js` — custom hook for swipe gesture navigation between sections (mobile). Uses native touch events (touchstart/touchend), 50px threshold, horizontal only. No external dependencies.
+     ```jsx
+     // src/hooks/useSwipeNav.js
+     import { useRef, useEffect } from 'react'
+
+     export default function useSwipeNav(sectionIds, containerRef) {
+       const touchStart = useRef(null)
+
+       useEffect(() => {
+         const el = containerRef?.current || document
+         function onTouchStart(e) { touchStart.current = e.touches[0].clientX }
+         function onTouchEnd(e) {
+           if (touchStart.current === null) return
+           const diff = touchStart.current - e.changedTouches[0].clientX
+           if (Math.abs(diff) < 50) return  // threshold
+           const currentIdx = sectionIds.findIndex(id =>
+             document.getElementById(id)?.getBoundingClientRect().top >= -100
+           )
+           if (currentIdx === -1) return
+           const nextIdx = diff > 0
+             ? Math.min(currentIdx + 1, sectionIds.length - 1)  // swipe left → next
+             : Math.max(currentIdx - 1, 0)                       // swipe right → prev
+           document.getElementById(sectionIds[nextIdx])?.scrollIntoView({ behavior: 'smooth' })
+           touchStart.current = null
+         }
+         el.addEventListener('touchstart', onTouchStart, { passive: true })
+         el.addEventListener('touchend', onTouchEnd, { passive: true })
+         return () => {
+           el.removeEventListener('touchstart', onTouchStart)
+           el.removeEventListener('touchend', onTouchEnd)
+         }
+       }, [sectionIds, containerRef])
+     }
+     ```
+     Usage in `HomePage.jsx`: `useSwipeNav(SECTIONS.map(s => s.id))`
+
+4. **Section components** (one per section):
+   - `Section1.jsx` through `SectionN.jsx`
+   - Each follows the pattern:
+     ```jsx
+     import SectionLayout from '../layout/SectionLayout'
+     import {InteractiveComponent} from '../interactive/{Component}'
+     import { useAppStore } from '../../store/useAppStore'
+     import { SECTIONS } from '../../data/sections'
+     import { exerciseData } from '../../data/exercises'  // or quizQuestions
+
+     const section = SECTIONS[INDEX]
+
+     export default function SectionN() {
+       const markComplete = useAppStore((s) => s.markSectionComplete)
+       return (
+         <SectionLayout {...section} theory={section.theory}>
+           <InteractiveComponent
+             {...data}
+             onComplete={(score) => markComplete(section.id, score)}
+           />
+         </SectionLayout>
+       )
+     }
+     ```
+
+5. **Page components:**
+   - `HomePage.jsx` — main page with Navigation sidebar, all sections, AchievementsPanel, FAQ, reset button
+   - `FinalTestPage.jsx` — final test with results display
+
+6. **App component:**
+   - `App.jsx` — HashRouter with routes, Header, Footer, ProgressBar, Toast
+
+## Critical Implementation Notes
+
+### Navigation: Use scrollIntoView, NOT href anchors
+HashRouter interprets `#section-id` as a route. Use `<button>` with `document.getElementById(id).scrollIntoView()`.
+
+### Quiz scoring: Do NOT double-count
+`handleSelect` increments `correctCount` on correct answer. `handleNext` must use `correctCount` directly without adding `+1` for the current answer (it's already counted).
+
+### ScenarioGame scoring: Same pattern
+`handleSelect` increments `score` on positive result. `handleNext` finished block uses `score` directly.
+
+### Dark mode: Toggle class on documentElement
+```javascript
+document.documentElement.classList.toggle('dark')
+```
+Persist to Zustand store + restore in `onRehydrateStorage`.
+
+### DragOrder: Randomize initial order
+Shuffle items on mount so user has to reorder them. Use Fisher-Yates shuffle.
+
+### MatchingExercise: Shuffle right side only
+Left side stays in order, right side is shuffled.
+
+## Checkpoint
+
+```
+Step 4/7: Components Complete
+Layout: 5 | Interactive: 6 | Common: 3 | Sections: N | Pages: 2 | App: 1
+Total components: {count}
+
+"ok" to continue | "[feedback]" to adjust
+```

package/templates/.claude/skills/edu-site-generator/modules/05-gamification.md

@@ -0,0 +1,163 @@
+# Step 5: Gamification
+
+## Goal
+Generate the state management layer: Zustand store, progress hook, achievements hook, toast system.
+
+## Protocol
+
+### 1. Generate `src/store/useAppStore.js`
+
+Zustand store with `persist` middleware (localStorage):
+
+```javascript
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+
+export const useAppStore = create(
+  persist(
+    (set, get) => ({
+      // Progress
+      completedSections: {},
+      sectionScores: {},
+      markSectionComplete: (id, score) =>
+        set((s) => ({
+          completedSections: { ...s.completedSections, [id]: true },
+          sectionScores: { ...s.sectionScores, [id]: score },
+        })),
+
+      // Achievements
+      unlockedAchievements: [],
+      unlockAchievement: (id) =>
+        set((s) => ({
+          unlockedAchievements: s.unlockedAchievements.includes(id)
+            ? s.unlockedAchievements
+            : [...s.unlockedAchievements, id],
+        })),
+
+      // Final test
+      finalTestScore: null,
+      finalTestAnswers: {},
+      setFinalTestResult: (score, answers) =>
+        set({ finalTestScore: score, finalTestAnswers: answers }),
+
+      // UI
+      navOpen: false,
+      toggleNav: () => set((s) => ({ navOpen: !s.navOpen })),
+      setNavOpen: (v) => set({ navOpen: v }),
+
+      // Dark mode
+      darkMode: false,
+      toggleDarkMode: () =>
+        set((s) => {
+          const next = !s.darkMode
+          document.documentElement.classList.toggle('dark', next)
+          return { darkMode: next }
+        }),
+
+      // Toast
+      toast: null,
+      showToast: (toast) => set({ toast }),
+      clearToast: () => set({ toast: null }),
+
+      // Reset
+      resetProgress: () =>
+        set({
+          completedSections: {},
+          sectionScores: {},
+          unlockedAchievements: [],
+          finalTestScore: null,
+          finalTestAnswers: {},
+        }),
+    }),
+    {
+      name: '{course-slug}-progress',  // Unique per course
+      partialize: (state) => ({
+        completedSections: state.completedSections,
+        sectionScores: state.sectionScores,
+        unlockedAchievements: state.unlockedAchievements,
+        finalTestScore: state.finalTestScore,
+        finalTestAnswers: state.finalTestAnswers,
+        darkMode: state.darkMode,
+      }),
+      onRehydrateStorage: () => (state) => {
+        if (state?.darkMode) {
+          document.documentElement.classList.add('dark')
+        }
+      },
+    }
+  )
+)
+```
+
+### 2. Generate `src/hooks/useProgress.js`
+
+```javascript
+import { useAppStore } from '../store/useAppStore'
+import { TOTAL_SECTIONS, SECTIONS } from '../data/sections'
+
+export function useProgress() {
+  const completedSections = useAppStore((s) => s.completedSections)
+  const sectionScores = useAppStore((s) => s.sectionScores)
+
+  const count = Object.keys(completedSections).length
+  const percentage = Math.round((count / TOTAL_SECTIONS) * 100)
+  const totalScore = Object.values(sectionScores).reduce((a, b) => a + b, 0)
+
+  return { count, total: TOTAL_SECTIONS, percentage, totalScore }
+}
+```
+
+### 3. Generate `src/hooks/useAchievements.js`
+
+```javascript
+import { useEffect } from 'react'
+import { useAppStore } from '../store/useAppStore'
+import { ACHIEVEMENTS } from '../data/achievements'
+
+export function useAchievements() {
+  const completedSections = useAppStore((s) => s.completedSections)
+  const sectionScores = useAppStore((s) => s.sectionScores)
+  const finalTestScore = useAppStore((s) => s.finalTestScore)
+  const unlocked = useAppStore((s) => s.unlockedAchievements)
+  const unlock = useAppStore((s) => s.unlockAchievement)
+  const showToast = useAppStore((s) => s.showToast)
+
+  useEffect(() => {
+    const state = useAppStore.getState()
+    for (const achievement of ACHIEVEMENTS) {
+      if (!unlocked.includes(achievement.id) && achievement.condition(state)) {
+        unlock(achievement.id)
+        showToast({
+          type: 'achievement',
+          title: achievement.title,
+          description: achievement.description,
+          icon: achievement.icon,
+        })
+      }
+    }
+  }, [completedSections, sectionScores, finalTestScore])
+}
+```
+
+### 4. Wire Toast in App.jsx
+
+Toast component auto-dismisses after 4 seconds. Displays at top-right with slide-in animation.
+
+## Score Calculation
+
+- Each section: 0-100 based on exercise performance
+- Total score: sum of all section scores (displayed in Header)
+- Final test: separate score (pass threshold: 70%)
+- Progress: count of completed sections / total sections
+
+## Checkpoint
+
+```
+Step 5/7: Gamification Complete
+Store: useAppStore.js (persist to localStorage)
+Hooks: useProgress.js, useAchievements.js
+Achievements: {count} defined
+Toast: wired in App.jsx
+
+"ok" to continue | "[feedback]" to adjust
+```

package/templates/.claude/skills/edu-site-generator/modules/06-deploy.md

@@ -0,0 +1,88 @@
+# Step 6: Deployment
+
+## Goal
+Configure GitHub Pages auto-deployment via GitHub Actions.
+
+## Protocol
+
+### 1. Create `.github/workflows/deploy.yml`
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build-and-deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - run: npm ci
+      - run: npm run build
+
+      - uses: actions/configure-pages@v4
+        with:
+          enablement: true
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+      - id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+### 2. Verify `vite.config.js` base path
+
+The `base` must match the GitHub repo name:
+- Repo: `https://github.com/user/my-course` -> `base: '/my-course/'`
+
+### 3. Verify `index.html` has correct asset paths
+
+All assets use relative paths (Vite handles this with `base` config).
+
+### 4. Verify HashRouter usage
+
+GitHub Pages serves `index.html` for all routes. HashRouter ensures client-side routing works:
+```jsx
+import { HashRouter, Routes, Route } from 'react-router-dom'
+// NOT BrowserRouter
+```
+
+## Important Notes
+
+- `enablement: true` in `actions/configure-pages@v4` auto-enables Pages if not yet configured
+- First deployment may take 1-2 minutes to propagate
+- If Pages was previously configured for Jekyll, it will be reconfigured for Actions
+
+## Checkpoint
+
+```
+Step 6/7: Deployment Complete
+Workflow: .github/workflows/deploy.yml
+Base path: /{repo-name}/
+Router: HashRouter
+
+"ok" to continue | "[feedback]" to adjust
+```

package/templates/.claude/skills/edu-site-generator/modules/07-verification.md

@@ -0,0 +1,97 @@
+# Step 7: Verification
+
+## Goal
+Build the project and verify everything works correctly.
+
+## Protocol
+
+### 1. Run build
+```bash
+npm run build
+```
+Must complete with zero errors.
+
+### 2. Verify file structure
+Check that all expected files exist:
+- [ ] `src/data/sections.js` — has correct number of sections
+- [ ] `src/data/exercises.js` — has data for each exercise type used
+- [ ] `src/data/quizQuestions.js` — has questions for quiz sections + final test
+- [ ] `src/data/achievements.js` — has 8+ achievements
+- [ ] `src/store/useAppStore.js` — Zustand store with persist
+- [ ] `src/hooks/useProgress.js` — progress calculations
+- [ ] `src/hooks/useAchievements.js` — achievement detection
+- [ ] All section components (`Section1.jsx` through `SectionN.jsx`)
+- [ ] All interactive components used by sections
+- [ ] All layout components
+- [ ] `src/App.jsx` — routing
+- [ ] `src/pages/HomePage.jsx` — main page
+- [ ] `src/pages/FinalTestPage.jsx` — test page
+- [ ] `.github/workflows/deploy.yml` — deployment
+
+### 3. Cross-reference checks
+- [ ] Every section in `SECTIONS` array has a corresponding `SectionN.jsx` component
+- [ ] Every section's `interactiveType` has matching exercise data
+- [ ] `finalTestQuestions` has one entry per section with valid `sectionId`
+- [ ] All imports in components resolve to existing files
+- [ ] No circular dependencies
+
+### 4. Known bug prevention
+- [ ] Quiz.jsx: `handleNext` uses `correctCount` directly, NOT `correctCount + (selected === correctAnswer ? 1 : 0)`
+- [ ] ScenarioGame.jsx: same pattern — no double-counting in `handleNext` or finished view
+- [ ] Navigation.jsx: uses `scrollIntoView()` NOT `<a href="#section-...">` (HashRouter conflict)
+- [ ] Dark mode: `onRehydrateStorage` restores `.dark` class
+
+### 5. Responsiveness check
+- [ ] Navigation hides on mobile (hamburger menu)
+- [ ] Sections stack vertically on small screens
+- [ ] Cards and buttons have proper touch targets (min 44px)
+- [ ] Text is readable at all breakpoints
+- [ ] Swipe gesture navigation works on mobile (left = next section, right = previous)
+- [ ] Swipe threshold (50px) prevents accidental navigation
+
+### 6. Flashcard toggle check
+- [ ] Cards flip from front to back on click
+- [ ] Cards flip back from back to front on second click
+- [ ] "Viewed" indicator shows on cards that have been flipped at least once
+- [ ] onComplete(100) fires when ALL cards have been viewed at least once (regardless of current flip state)
+- [ ] Keyboard navigation works (Enter/Space to flip)
+
+### 7. SEO files check
+- [ ] `public/robots.txt` exists with `User-agent: *`, `Allow: /`, and `Sitemap:` directive
+- [ ] `public/sitemap.xml` exists with valid XML structure
+- [ ] sitemap.xml contains URL for each section
+- [ ] Sitemap URL in robots.txt matches actual sitemap location
+
+### 6. Error Recovery
+
+If `npm run build` fails, diagnose and fix:
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Module not found: Can't resolve './components/...'` | Missing component file or wrong import path | Create the missing file or fix the import |
+| `'X' is not exported from 'Y'` | Wrong export name in data file | Check data file exports match imports |
+| `Cannot find module '@dnd-kit/...'` | Missing dependency | Run `npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities` |
+| `Unexpected token` in JSX | Syntax error in component | Check for unclosed tags, missing returns |
+| TailwindCSS class not resolving | Custom class without `@theme` definition | Verify all semantic colors defined in index.css |
+| `npm install` fails with ERESOLVE | Peer dependency conflict | Try `npm install --legacy-peer-deps` |
+| `npm install` fails with network error | No internet or registry down | Check network, retry, or use `--registry https://registry.npmjs.org` |
+
+**Recovery protocol:**
+1. Read the full error message
+2. Match to table above (or diagnose)
+3. Fix the specific issue
+4. Re-run `npm run build`
+5. Repeat until clean build
+
+## Output
+
+```
+Step 7/7: Verification Complete
+Build: SUCCESS
+Files: {count} verified
+Cross-references: OK
+Known bugs: mitigated
+
+Site ready for deployment. Push to main to trigger GitHub Pages deploy.
+URL: https://{user}.github.io/{repo}/
+```