# Table of Contents
- [Learn French — Advanced K-12 French Learning Web App](#learn-french--advanced-k-12-french-learning-web-app)
  - [Live Demo & Quick Start](#live-demo--quick-start)
  - [Current Release Snapshot](#current-release-snapshot)
  - [Product Snapshot](#product-snapshot)
  - [Feature Highlights](#feature-highlights)
  - [Scope & Sequence Roadmap](#scope--sequence-roadmap)
    - [How to Use This Map](#how-to-use-this-map)
  - [Curriculum Planning Resources](#curriculum-planning-resources)
    - [Spiral Practice Lesson Pack](#spiral-practice-lesson-pack)
  - [Application Structure](#application-structure)
  - [Data & Storage Model](#data--storage-model)
  - [Running the App Locally](#running-the-app-locally)
  - [Quality Assurance](#quality-assurance)
  - [Deployment Notes](#deployment-notes)
  - [Automated Versioning & Build Metadata](#automated-versioning--build-metadata)
    - [Updating versions locally](#updating-versions-locally)
- [Support Utilities](#support-utilities)
  - [Audio Integration Toolkit](#audio-integration-toolkit)
    - [Current Audio Implementation (2025)](#current-audio-implementation-2025)
    - [Toolkit Scripts](#toolkit-scripts)
    - [Implementation Status](#implementation-status)
    - [Roadmap to Native Audio Integration](#roadmap-to-native-audio-integration)
    - [Migration Benefits](#migration-benefits)
    - [Quick Start Checklist](#quick-start-checklist)
- [Changelog](#changelog)

# Learn French — Advanced K-12 French Learning Web App

**🇫🇷 A comprehensive, modern Progressive Web App (PWA) for K-12 students, homeschool families, and independent learners.**

Learn French ships as a static web application that combines a 13-level curriculum, 690+ interactive lessons, and native-audio activities inside a mobile-first interface. The repository contains everything required to run the site locally, audit the lesson library, and deploy the PWA to the web.

---

## Live Demo & Quick Start

### Live Demo
- **Production build:** [https://alainrafiki.github.io/learnfrench/](https://alainrafiki.github.io/learnfrench/)
- Works in any modern browser with offline caching, install prompts, and background update checks.

### Quick Local Preview
```bash
# Clone the repository
git clone https://github.com/alainrafiki/learnfrench.git
cd learnfrench

# Serve the static site (choose any HTTP server)
python3 -m http.server 8000
# or
npx serve . -p 8001

# Visit the chosen port in your browser
```

---

## Current Release Snapshot

| Detail | Current State |
| --- | --- |
| **App version** | `v2.0.461` (rolling release for the 2025-2026 curriculum expansion) |
| **Cache version** | `cache-2.0.461-1e6b4b6-20251011-191505` |
| **Latest production commit** | `1e6b4b6` on `main` (772 commits merged to date) |
| **Build timestamp** | October 11, 2025 at 19:15 UTC |
| **Target platforms** | Chromium, Firefox, Safari, and Edge with installable PWA support |

The current major release (v2) ships expanded intermediate/advanced lessons, refreshed progress analytics, and the adaptive spiral review system described below. Version metadata is regenerated automatically after each merge so educators always see an up-to-date build identifier inside the app footer.

---

## Product Snapshot

| Attribute | Details |
| --- | --- |
| Grade coverage | 13 distinct levels (Kindergarten through Grade 12) with CEFR alignment from A1 to C2 |
| Lesson count | 690+ hand-authored lessons delivered through `data/lessons/*.json` collections |
| Activity types | 21 interactive formats including flashcards, matching, fill-in-the-blank, essays, dialogues, and cultural reflections |
| Target users | K-12 students, families, and educators who prefer offline-friendly study plans |
| Pricing | Free to use, no ads, and fully accessible without creating an account |

---

## Feature Highlights

### Lesson & Activity Experience
- Grade-specific lesson browsers (`grades.html`, `lessons.html`) surface curated cards with level tags, estimated time, and quick actions.
- `lesson.html` renders multi-phase lesson flows: introduction, vocabulary with native audio, interactive practice, application tasks, and reflection prompts.
- Activities range from low-friction flashcards to advanced debates and writing labs managed by `assets/scripts/activities.js`.

### Personalization & Family Support
- `welcome.html` and `family-setup.html` onboard solo learners or multi-profile households with age, goal, and preference capture.
- Household dashboards show streaks, review queues, and milestone tracking inside `dashboard.html` with context-aware reminders.

### Progress & Motivation
- `progress.html` visualizes mastery chips, CEFR-aligned summaries, and export-ready reports for accountability partners.
- `progress.html` and `dashboard.html` share persistent progress data through local storage with recovery safeguards.
- `assets/scripts/achievement-notifier.js` surfaces celebratory toasts the moment achievements unlock, complete with gentle audio cues for learners and families.
- `assets/scripts/certificate-generator.js` creates printable lesson, level, and achievement certificates so households can commemorate milestones without leaving the app.

### Offline-First PWA
- `sw.js` powers caching for lessons, audio, and UI assets; background update checks surface English notifications when new content is ready.
- `assets/scripts/update-manager.js` throttles version checks, ensures cache busting, and presents "App is up to date" messaging.
- `assets/scripts/cache-utils.js` and `assets/scripts/version-sync.js` coordinate service worker cache identifiers across tabs for smooth background refreshes.

### Accessibility & UX
- Consolidated styling in `assets/styles/main.css` maintains WCAG-friendly contrast, generous touch targets, and keyboard navigation patterns.
- `assets/scripts/accessibility-enhancer.js` reduces console noise while keeping live-region announcements responsive for assistive tech.
- `assets/scripts/performance-monitor.js` tracks storage usage, render times, and memory pressure so developers can keep experiences smooth on low-power classroom devices.

---

## Scope & Sequence Roadmap

This printable roadmap distills the can-do statements, grammar priorities, and cultural threads that power the Learn French experience across every grade/CEFR pairing. Use it alongside the adaptive dashboards to plan pacing, confirm coverage, and communicate progress with co-ops or reporting portals.

| Grade | CEFR / Phase | Can-do Highlights | Priority Grammar | Cultural & Project Focus |
| --- | --- | --- | --- | --- |
| K | A1.0 · Discovery | Greetings, colour hunts, family introductions | Je/tu, être/avoir present, gender agreement | Songs, playground games, family celebrations |
| 1 | A1.1 · Essential Basics | Feelings dialogues, weather chats, show-and-tell | Articles, patterned negation, possessive **de** | Snack time, weather around la francophonie |
| 2 | A1.2 · Consolidation | Story retells, market role-plays, preference Q&A | Regular -er verbs, *est-ce que*, adjective agreement | Festivals, food markets, seasonal traditions |
| 3 | A1.3 · Improvement | Daily routine vlogs, map quests, hobby interviews | Reflexive verbs, prepositions, *faire* expressions | School life, transport, sports & hobbies |
| 4 | A2.0 · Elementary | Pen-pal exchanges, travel itineraries, negotiations | Passé composé (avoir), irregular verbs, comparatives | Pen pals, geography, family traditions |
| 5 | A2.1 · Development | Sustainability debates, recipe podcasts, narratives | Passé composé (être), imparfait, sequencing connectors | Environment, cuisine, francophone inventors |
| 6 | A2.2 · Mastery | News broadcasts, interviews, explanatory writing | Future tenses, object pronouns, relative clauses | Journalism, STEM innovations, civic engagement |
| 7 | B1.0 · Intermediate | Socratic seminars, service pitches, editorials | Subjunctive starters, reported speech, conditional | Literature circles, entrepreneurship, citizenship |
| 8 | B1.1 · Expansion | Source synthesis, panel discussions, rubrics | Complex pronouns, passive voice, *si* (Type 1) | Youth culture, media literacy, STEAM projects |
| 9 | B1.2 · Autonomy | Long-form debates, analytic essays, current events pods | Advanced connectors, reported speech, *dont/lequel* | Media bias, policy, arts analysis |
| 10 | B2.0 · Upper Intermediate | DALF-style essays, film critiques, oral simulations | *Si* (Type 2), opinion subjunctive, nominalisation | Cinema, social justice, philosophy |
| 11 | B2.2 · Expertise | Research dossiers, mock DALF C1 exams, comparative lit | Advanced subjunctive, passive nuance, discourse markers | Philosophy, global policy, comparative literature |
| 12 | C1–C2 · Advanced | Capstone portfolios, bilingual symposia, publishable works | Stylistic register shifts, academic connectors, idioms | Universities, diplomacy, artistic movements |

### How to Use This Map

1. **Confirm prerequisites** – Each grade entry in `data/scope_sequence.json` lists prerequisite habits and spiral connections so you can see which earlier lessons to review before moving ahead.
2. **Plan adaptive pacing** – Pair the can-do goals with the diagnostic placement tool to set a starting point, then use progress recommendations to trigger review playlists when mastery dips.
3. **Document mastery** – Attach this roadmap to homeschool binders or accreditation submissions. The built-in export tools on the dashboard can pull attendance, intervention notes, and mastery summaries that align with the themes here.
4. **Extend learning** – Advanced phases include authentic performance tasks (DALF-style exams, dossiers, symposiums) that you can assign as capstones or portfolio evidence.

> For the interactive version with filters, open **Levels → Scope & Sequence** within the app or download this README as PDF for printing.

---

## Curriculum Planning Resources

The curriculum ships with printable and in-app planning aids so households can balance new instruction with spaced review. These resources pair with the adaptive placements, family controls, and exportable progress reports to keep weekly rhythms intentional without requiring extra tooling.

### Spiral Practice Lesson Pack

This printable pack helps families rotate through previously learned material while steadily introducing new French content. Each section is designed to fit inside a weekly homeschool rhythm and pairs with the in-app lesson recommendations.

#### What's Included

- **Weekly spiral plan:** Suggested focus areas for morning basket warm-ups, independent study, and group review sessions.
- **Core skill rotation:** Guidance on weaving listening, speaking, reading, and writing activities across the week.
- **Celebration trackers:** Printable badges, certificate prompts, and milestone checklists to keep learners motivated.
- **Conversation prompts:** Short questions and role-play ideas tied to the cultural themes featured in the lesson library.

#### How to Use

1. Print the pages you need and keep them in your homeschool binder (download this README as a PDF and jump to this section).
2. Choose a "spoke" (vocabulary, grammar, culture, or pronunciation) for each day and pair it with an in-app lesson.
3. Mark completed activities so every child cycles back through past skills at least once every two weeks.
4. Celebrate wins using the included trackers or the in-app achievements page.

For more planning resources, open **Settings → Family Preferences** in the app to tailor pacing, reminders, and celebration milestones. Progress dashboards will automatically surface spiral-ready lessons when mastery dips, so the printable pack stays aligned with each learner's needs.

---

## Application Structure

| Page | Purpose |
| --- | --- |
| `index.html` | Landing experience with resume prompts, quick shortcuts, and install-ready PWA shell |
| `dashboard.html` | Personalized momentum cues, mastery planner cards, and quick review queues |
| `lessons.html` | Searchable lesson directory with filters, skill grouping, and solo journey guidance |
| `lesson.html` | Full lesson execution with audio playback, activities, assessments, and reflection checklists |
| `grades.html` | Grade-by-grade overview linking to lesson sets and CEFR explanations |
| `progress.html` | Mastery heatmap, exports, streak summaries, and celebration milestones |
| `settings.html` | Appearance, audio preferences, storage management, and version reset options |
| `welcome.html` & `family-setup.html` | Guided setup for solo learners and families |
| `about.html` & `welcome.html` | Platform philosophy, onboarding context, and curricular overview |
| `debug-progress.html` | Developer utility to inspect progress data structures |

Additional HTML files in the root (such as `debug-progress.html`) provide internal utilities and prototypes for verifying design experiments and data health checks.

---

## Data & Storage Model

- Lesson content, activities, and playlist metadata live in `data/` JSON files (`lessons`, `activities`, `solo_journey_playlists`, etc.).
- Client-side data persists in `localStorage` with corruption recovery handled by `assets/scripts/storage-recovery.js`.
- `manifest.webmanifest` defines install metadata and icons for the PWA shell, while `assets/icons/` holds platform-specific art.

---

## Running the App Locally

1. **Install dependencies:** No package installation is required; the project runs with any static file server.
2. **Serve the root directory:** Use Python, `npx serve`, or another HTTP server to avoid CORS issues when loading JSON data.
3. **Test offline:** Open DevTools → Application → Service Workers, then check "Offline" to confirm cached assets continue to work.
4. **Reset storage between tests:** Use the "Reset app" control in `settings.html` or clear browser storage to simulate a new learner.

---

## Quality Assurance

- **Manual smoke tests:**
  - Load `lessons.html` and confirm lesson cards render across multiple grades.
  - Perform a search query (e.g., "sports") and verify filtered results.
  - Open several activity types to ensure audio, validation, and completion states operate correctly.
- **Offline validation:** Toggle network offline in DevTools and refresh to confirm cached views continue to work and update messaging appears.
- **Console hygiene:** Verify that only meaningful logs appear; errors should be filtered by the accessibility enhancer and update manager.

---

## Deployment Notes

- The site is designed for GitHub Pages or any static host. Deploy the root directory and ensure `sw.js` is served from the same scope.
- Update version metadata via `assets/scripts/update-manager.js` when invalidating caches; the script handles throttled notifications and reload prompts.
- A GitHub Actions workflow (`Update build metadata`) automatically runs `tools/update-build-info.js` after every push to `main` or `master`, ensuring `assets/build-info.*` always reflects the latest merged PR.
- For custom domains, update canonical URLs in `index.html` and `manifest.webmanifest` to preserve SEO signals.

---

## Automated Versioning & Build Metadata

Recent releases introduced an automated version policy so the app can roll forward without manual edits:

- **Policy driven majors.** `config/version-policy.json` defines scheduled major releases (e.g., the v2 curriculum refresh) and the default increment strategies for minor and patch numbers.
- **Deterministic build metadata.** `tools/update-build-info.js` reads the active policy, the git commit history, and the previous `assets/build-info.json` snapshot to decide whether the current build is a major rollover or a rolling update. It persists the resolved state (baselines, activation timestamps, and the release schedule) back into the build artifact.
- **Runtime awareness.** Front-end helpers in `assets/scripts/version-config.js` expose the current app version, cache version, and policy snapshot to UI components, cache utilities, and the service worker. When the script fetches updated build info, connected modules receive the new identifiers automatically.
- **Service worker sync.** `sw.js` and `assets/scripts/version-sync.js` listen for version updates and rebroadcast cache identifiers so precached assets stay aligned with the active release.

### Updating versions locally

```bash
# Recompute app/cache versions and rebuild metadata
node tools/update-build-info.js

# Commit the refreshed assets/build-info.* files with your changes
```

The script will bump the major version as soon as a scheduled release date passes, reset the patch baseline for the new major, and continue incrementing patch numbers based on commit counts. If git metadata is unavailable (for example in a ZIP download), the script gracefully falls back to predictable timestamps so the app still exposes a coherent version identifier.

---

## Support Utilities

- `/tools/` contains developer aids such as mastery lesson generators, the audio integration toolkit, and the build metadata updater described below.
- `mobile-conversion-test.js` helps simulate lesson rendering on small devices during responsive audits.
- `tools/update-build-info.js` synchronizes release metadata, ensuring the service worker and UI display consistent version identifiers.
- `CHANGELOG.md` documents every major release, architecture upgrade, and feature verification pass.

### Audio Integration Toolkit

The audio utilities in `/tools/` extend the enhanced text-to-speech (TTS) system that currently powers lesson audio while preparing the codebase for native speaker recordings.

#### Current Audio Implementation (2025)
The production app ships with a refined TTS pipeline that balances pronunciation quality with low-latency playback.

- **French voice prioritization:** Automatically selects `fr-FR` voices ahead of other dialects while preferring local device voices for faster playback.
- **Voice caching & monitoring:** Persists selected voices, tracks performance metrics, and maintains consistent pronunciation quality across Chrome, Firefox, Safari, and Edge.
- **Deterministic selection flow:** The initialization routine below illustrates how the voice list is filtered and ranked before playback.

```javascript
function initializeVoices() {
  const voices = synth.getVoices();
  frenchVoices = voices
    .filter(voice => voice.lang.startsWith('fr'))
    .sort((a, b) => {
      if (a.lang === 'fr-FR' && b.lang !== 'fr-FR') return -1;
      if (b.lang === 'fr-FR' && a.lang !== 'fr-FR') return 1;
      if (a.localService && !b.localService) return -1;
      if (b.localService && !a.localService) return 1;
      return 0;
    });
}
```

#### Toolkit Scripts
- **Recording manifest template:** `data/audio_index_example.json` documents the structure expected by the runtime audio helpers so native clips can be indexed alongside the existing synthesized library.
- **Audio content extractor (planned):** Upcoming scripting support will analyze lesson JSON files and export prioritized phrase lists for studio sessions. Until then, contributors can manually gather lines from `data/lessons/*.json`.
- **Audio index generator (planned):** Future automation will scan recorded clips and build a manifest compatible with the AudioManager pipeline so native audio can ship with minimal manual work.

#### Implementation Status
- ✅ Enhanced TTS system deployed and stable.
- ⚠️ Native audio tooling ready for use as soon as recording begins.
- 🔄 Migration path established to blend native audio with existing TTS fallbacks.

#### Roadmap to Native Audio Integration
1. **Preparation:** Analyze lesson content, finalize recording specifications, and define file organization conventions.
2. **Hybrid launch:** Introduce an AudioManager with graceful TTS fallbacks while progressively replacing synthesized clips. (The manager is currently scoped for development and will ship alongside the extractor tooling.)
3. **Optimization:** Continue cache, performance, and monitoring improvements as the native library grows.

#### Migration Benefits

**Immediate (Enhanced TTS):**
- 60–70% improvement in French pronunciation quality compared to the legacy voice pipeline.
- Consistent voice selection across sessions, backed by caching and monitoring.
- Better perceived performance thanks to local voice prioritization.

**Future (Native Audio):**
- Authentic pronunciation recorded by native speakers with cultural nuance.
- Progressive rollout with seamless TTS fallback support.
- Expanded opportunities for lesson-specific acting direction and emphasis.

#### Quick Start Checklist
1. Confirm the enhanced TTS experience locally—no additional setup is required for the default voice system.
2. Review this toolkit section and align on recording standards before studio work begins.
3. Coordinate on the upcoming extractor workflow (or manually export phrases from the lesson JSON files) to assemble recording queues, then register finalized clips with the manifest template.
4. Capture any bespoke recording environment notes alongside the tooling scripts within `/tools/` so future contributors can iterate quickly.

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a complete history of improvements, including the CSS consolidation, lesson loading fixes, and documentation refresh completed in v1.47.x.