feat: pybe v2.2 ship major learning experience overhaul

[Just-Here-TO-Code]

PR: PyBe v2.2, First-Principles Learning Engine, Dynamic Dashboard Themes & Socratic Misconception Spotter

IIT Ropar Summer Internship 2026 | Contributor: Sukrit Aryan
Target Release: PyBe v2.2.0

---

Overview & Core Objective

This Pull Request introduces PyBe v2.2, elevating PyBe from a scenario-based learning platform into a First-Principles Problem-Based Learning (PBL) Engine.

Instead of teaching syntax rules upfront, PyBe v2.2 forces learners to experience the exact friction point where manual code breaks, guiding them to rediscover Python constructs from memory architecture up. In addition, v2.2 introduces 4 immersive theme worlds (Default, Potterheads, Marvel, and Anime) with dynamic scenario switching across all 13 curriculum chapters.

---

Key Features Introduced

1. First-Principles Learning Engine

• Friction Simulator (Before vs. After): Embedded in every chapter's Theory phase. Displays side-by-side cards comparing fragile manual code without the construct vs. clean Python code, explaining the exact pain point that forced computer scientists to invent the abstraction.
• Interactive Mental Model Lab: Live hands-on visualizers embedded in the Theory phase showing:
  • RAM Memory Slot Inspector (variables): Live RAM address 0x7F8 value allocation.
  • Arithmetic Operator Pipeline (operators): Interactive multiplication & division node calculations.
  • Zero-Indexed Character Memory (strings): Array cell decomposition ([0] -> 'P', [1] -> 'y').
  • Decision Tree Flowchart (conditionals): Live branching logic with score sliders.
  • Loop Iteration Stepper (loops): Interactive execution cursor stepping across items.
  • Container Array Controls (lists): Live + append() and - pop() memory counters.
  • Hash Table Lookup (dictionaries): Direct $O(1)$ key-value hash mapping.
  • Unique Element Buckets (sets): Instant deduplication filter.
  • Function Machine (functions): Parameter input substitution and return value processing.
  • Array Search Scanner (search-filter): Sequential pattern-matching target highlight.
  • try/except Shield Simulator (error-handling): Interactive exception blocker preventing app crashes.
  • Array Sort Stepper (algorithms): Ascending/descending sorting step-by-step.
  • RAM $\rightarrow$ Disk Storage Buffer (files): Volatile RAM data transfer to permanent disk files.
• Instant Micro-Sandbox / Interactive Try-It Widget: Embedded browser-based Python code editor allowing students to edit variables, hit "Run Code", and view stdout in an authentic dark terminal console ($ python main.py).
• Socratic Misconception Spotter: Automated analysis during the Reasoning Summary phase (SummaryPhase). Detects 5 common beginner mental traps:
  1. 0-Indexing Offsets (confusing 1st position with index 1).
  2. Assignment vs Equality (confusing = with ==).
  3. String Immutability in RAM (expecting in-place string modification).
  4. Parallel List Desynchronization (relying on separate un-synced lists).
  5. Unhandled Edge Cases (negative quantities or 0 division).
     Provides targeted Socratic prompts guiding the student to re-evaluate their mental model.

---

2. Dynamic Dashboard Theme Engine & Theme-Switched Curriculum

• 4 Immersive Theme Worlds: Logged-in users can switch between themes directly on their dashboard:
  1. Default Theme: Classic Chai Stall, ISRO Mission Control, and Kota Coaching.
  2. Potterheads: Hogwarts potions brewing, Marauder's Map, and DADA spellbooks.
  3. Marvel: Avengers AI, Mark 85 J.A.R.V.I.S. suit telemetry & Infinity Stone grid.
  4. Anime: Hidden Leaf Jutsu chakra engine & Legendary Creature hunter.
• Strict Scenario Filtering: Express backend (/api/casestudies and /api/scenarios) strictly filters content by queried theme.
• Complete Chapter Adaptations: Every single one of the 13 curriculum chapters dynamically adapts its scenario questions, vibe, real-world connection, and code examples per active theme.

---

3. Tailored Light & Dark Mode Color Palettes

Introduced bespoke HSL color tokens for both Light and Dark modes across all themes:

• Potterheads: Hogwarts Dark Parchment (#1E1610) & Warm Light Parchment (#FAF4E8) with Dark Wizard Ink (#291E16).
• Marvel: Stark Cyber Dark (#0B132B) & Titanium Light (#F1F5F9) with Slate Ink (#0F172A).
• Anime: Tokyo Neon Dark (#120D1D) & Sakura Lavender Light (#FAF5FF) with Cyber Ink (#1E1B4B).
• Landing Page Integrity: Unauthenticated visitors on / retain original public landing page styling untouched.

---

4. Database Expansion (93 Total Scenarios)

• 54 Default/Classic Scenarios: Real-world scenarios spanning 6 UADE themes.
• 39 Theme-Specific Scenarios: 13 Potterheads + 13 Marvel + 13 Anime scenarios covering all 13 curriculum chapters.

---

Curriculum Matrix (13 Chapters)

Section	Chapter ID	Concept Covered	Interactive Visualizer
Getting Started	variables	Variables & Memory	RAM Address 0x7F8 Slot Inspector
	operators	Math & Arithmetic	Arithmetic Node Pipeline Calculator
	strings	Text & Quotes	Zero-Indexed String Character Array
Basics	conditionals	Decision Branching	Flowchart Decision Tree (If/Elif/Else)
	loops	Iteration	Step Loop Cursor Stepper
	lists	Ordered Collections	Array Append/Pop Length Counter
Intermediate	dictionaries	Key-Value Pairs	$O(1)$ Hash Table Key Mapper
	sets	Unique Elements	Duplicate Element Set Bucket Filter
	functions	Reusable Logic	Function Parameter Machine
	search-filter	Pattern Matching	Array Search Scanner
Advanced	error-handling	Exception Safety	try/except Shield Simulator
	algorithms	Sorting & Efficiency	Step-by-Step Array Sort Stepper
	files	Data Persistence	RAM $\rightarrow$ Disk Storage Buffer

---

Files Changed

• client/src/pages/ChapterPage.jsx: Added BeforeVsAfter, MentalModelLab, MicroSandbox, and SocraticSpotter in SummaryPhase and TheoryPhase.
• client/src/data/curriculum.js: Added beforeVsAfter definitions for all 13 chapters & exported getThemedChapter().
• client/src/styles/index.css: Added Light & Dark mode color variables for Potterheads, Marvel, and Anime themes.
• client/src/pages/AppHome.jsx & CaseStudies.jsx: Theme selector UI & strict theme filter tabs.
• server/src/seed.js & server/src/data/db.json: Seeded 93 scenarios across all themes.
• server/src/routes/casestudies.js & store.js: Backend theme filtering API routes.
• README.md, product.md, WIKI.md: Comprehensive documentation updates.
• .gitignore: Cleaned up to exclude build output, logs, and IDE files.

---

Verification & Testing

1. Client Production Build: Executed npm run build in client/, Passed cleanly (2.80s) without warnings.
2. Database Seeding: Executed node server/src/seed.js, Seeded 93 PyBe scenarios successfully.
3. Phase Flow & Animations: Verified GSAP phase transitions (Intro $\rightarrow$ Questions $\rightarrow$ Summary $\rightarrow$ Theory) function smoothly across all 13 chapters.
4. Interactive Widgets: Tested live Python code execution in MicroSandbox, state updates in MentalModelLab, and Socratic prompt generation in SummaryPhase.

---

💬 Reviewer Notes

All changes maintain 100% backward compatibility with existing user sessions and offline localStorage progress tracking.