✨ REDGOLD ✨

Textbooks are mid. Master the bridge from HSK 4 to real-world talk.
The perfect fusion of academic precision and colloquial soul.

---

🏮 The Philosophy: Red Meets Gold

In traditional Chinese learning, there has always been a disconnect.

• The Red (赤): Represents the formal, structured HSK curriculum—essential for exams but often sounding "robotic" in real life.
• The Gold (金): Represents the colloquial, native rhythm—the way people actually talk in the streets of Beijing or Shanghai.

RedGold bridges this gap. We transform the HSK 4 Standard Course into a premium, interactive experience that teaches you not just what to say, but how to say it like a native.

---

🚀 Core Features

🎬 Karaoke-Style Scroll Sync

Our intelligent Scroll Engine in the TextSection component provides a seamless reading experience.

• Forward-Only Logic: The viewport only moves forward with the audio, preventing distracting "snaps" back to previous lines.
• Timing Heuristics: Calculates line changes based on character weight and audio duration for frame-perfect synchronization.

🏷️ Proper Nouns Support

Unlike standard HSK tools, RedGold explicitly identifies and styles 专有名词 (Proper Nouns) — names, places, brands — with pinyin AND English meaning right there, no lookup needed. Styled in the signature Modern Han Elegant gold theme.

⚡ Smart Prefetching

Zero-latency transitions. The app predicts your learning path and pre-warms audio assets and lesson data as you browse, ensuring the next chapter is ready before you even click.

🎨 Modern Han Elegant UI

A premium "glassmorphic" interface designed for focus:

• Responsive Layout: Tailored for high-aspect-ratio mobile displays (Galaxy S26 / iPhone Pro Max).
• Sticky Navigation: Smooth tab switching between Vocab, Grammar, and Texts.
• Visual Selection: Browse lessons via high-resolution 3D-styled textbook covers.

🔢 Live Version Badge

The app header now shows the current version and last build date in real time — no more guessing what's deployed.

---

🛠 Tech Stack & Architecture

Built for performance, scalability, and the Google Cloud ecosystem:

• Frontend: Vite + TypeScript
• Architecture: Vanilla Web Components (Shadow DOM, 0-dependency runtime)
• Styling: Vanilla CSS with a centralized token system (Modern Han Elegant)
• Backend: Firebase (Hosting, Auth, Firestore ready)
• CI/CD: GitHub Actions deploys main to GitHub Pages. Local git hooks bump the patch version (+0.0.1) before each commit and stamp that version into the commit message.

---

📂 Project Structure

redgold/
├── data/               # HSK 4 Lesson JSONs (Vocab, Grammar, Texts)
├── plan/               # Technical specs and design documentation
├── public/             # Assets (Audio, Images, Logos)
├── scripts/            # Python automation for data processing
└── src/
    ├── components/     # Custom Web Components (TextSection, VocabCard, etc.)
    ├── styles/         # Global design tokens and CSS
    ├── utils/          # Security (XSS Sanitizer) and Helpers
    └── web/            # Main App container and routing

---

🛠 Installation & Development

1. Setup

# Clone the repo
git clone https://github.com/heroyik/redgold.git

# Install dependencies
npm install

2. Local Development

# Start the dev server
npm run dev

3. Production Build

# Build for deployment
npm run build

---

🗺 Roadmap

Phase	Milestone	Status
UI/UX	Landing Page Refresh (Book Covers + Hip Tagline)	✅ Done
Logic	Forward-only Scroll Sync Engine	✅ Done
Pedagogy	Proper Nouns with Pinyin + English Meaning	✅ Done
Versioning	Pre-commit patch bump + versioned commit messages + header badge	✅ Done
Auth	Firebase Authentication Implementation	✅ Done
Data	Mastery Quiz System & Progress Tracking	⏳ Next

---

📋 Changelog

Every local commit bumps the patch version by 0.0.1, and the commit message is auto-stamped with that exact version. Here's the human-readable tea:

---

v0.9.49 — 2026-05-05

Firebase Authentication & User Profile. Identity is now live.

• 🔐 Firebase Authentication — Implemented Google Sign-In with a custom UserMenu Web Component.
• 👤 User Profile UI — Added a sleek, glassmorphic profile menu to both the landing page and lesson view header, showing user name, email, and photo.
• 🛠 Auth Utility — Created a centralized auth.ts utility for handling user state and authentication logic.
• 🔢 Version Bump — Updated to v0.9.49 as part of the automated versioning workflow.

---

v0.9.46 — 2026-05-03

Mobile-First UX Optimization & Cloud Sync. The Review Tab gets a massive glow-up.

• ☁️ Firestore Integration — Migrated local lesson1.json data to Firebase Firestore, laying the groundwork for a true backend architecture.
• 📱 Mobile UI/UX Polish — Complete overhaul of the Review tab for modern, high-aspect-ratio screens (Galaxy S26 / iPhone Pro). Eliminated rogue left-margins and packed the top header icons perfectly into a single responsive row.
• 🔄 Click-to-Flip Refined — Resolved PC vs Mobile interaction conflicts. Cards now flip flawlessly on a simple click or tap through a centralized InteractionManager.
• 📐 Perfect Card Boundaries — Leveraged dvh calculations (calc(100dvh - 380px)) to aggressively subtract header real estate. Flashcard outlines now fit perfectly on-screen without clipping, and long texts (like complex meanings or examples) are neatly scrollable inside the card itself.
• 🎯 Absolute Center Alignment — Chinese characters on the front face are perfectly centered vertically and horizontally. Fixed descender drifts by applying line-height: 1 alongside precise flexbox layouts.
• 🎧 Visual Audio Triggers — Replaced text-based audio buttons with sleek, static PNG icons for better intuition.
• 📝 App Manifesto Update — Rewrote the intro messaging to sound more colloquial and explicitly highlight the "HSK4 learners" target audience, while strictly preserving the GitHub footer link.
• ⬅️ Navigation Enhancements — Added tactile left/right arrows flanking the progress counter (< 1/31 >) for immediate visual navigation cues.
• 🧹 Layout Compaction — Reduced unnecessary padding between the version badge and the logo to grant more breathing room to core content.

---

v0.9.0 — 2026-05-01

The version system drops. Things just got official.

• 🔢 Version badge is live — header now shows vX.X.X + last build date on both the landing page and the lesson view
• ⚙️ Automatic patch bump — local git hooks patch 0.0.1 before every commit and make sure the commit message includes the bumped version
• 🏷️ 专有名词 (Proper Nouns) overhaul — corrected all proper noun entries to match the actual textbook pages (images > assumptions, always)
• 📖 Dialogue 2 data fix — 李 is the only proper noun. 王静 and 李老师 were wrongly listed; axed. Textbook is the source of truth.
• ➕ 幸福 (xìngfú) added to Dialogue 2 vocabulary — it was literally in the textbook and we missed it. Fixed.
• 📏 Vocabulary meanings tightened up — part-of-speech labels (adj., v., adv.) now match the textbook format exactly

---

🤝 Reference & Credits

Redgold is an educational tool designed to complement the HSK Standard Course 4 textbook series authorized by Hanban and published by BLCUP.

Built with ❤️ by the RedGold Team.
Speak the Language, Not Just the Grammar.