clean production deployment with comprehensive readme

.dockerignore

@@ -0,0 +1,53 @@
+# Node modules
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+
+# Git
+.git/
+.gitignore
+
+# Environment files
+.env
+.env.*
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Temporary files
+tmp/
+temp/
+.aider*
+
+# Documentation
+*.md
+!README.md
+
+# Planning documents
+*_PLAN.md
+IMPLEMENTATION_*.md
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Coverage
+coverage/
+.nyc_output/
+
+# Build artifacts
+dist/
+build/

.env.example

@@ -0,0 +1,13 @@
+# OpenRouter API Key (for AI functionality)
+OPENROUTER_API_KEY=your_openrouter_key_here
+
+# Hugging Face API Token (for leaderboard persistence)
+# Get your token from: https://huggingface.co/settings/tokens
+# Required permissions: write access to datasets
+HF_TOKEN=your_hf_token_here
+# OR use HF_API_KEY (both work)
+HF_API_KEY=your_hf_token_here
+
+# Hugging Face Leaderboard Repository (optional, defaults to zmuhls/cloze-reader-leaderboard)
+# Format: username/repo-name
+HF_LEADERBOARD_REPO=your_username/cloze-reader-leaderboard

.gitignore

@@ -0,0 +1,84 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build outputs
+dist/
+.parcel-cache/
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs
+logs
+*.log
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Leaderboard data (stored in dedicated HF Space)
+leaderboard.json
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Coverage directory used by tools like istanbul
+coverage/
+
+# Temporary folders
+tmp/
+temp/
+.aider*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Planning documents
+HF_DATASET_INTEGRATION_PLAN.md
+*_PLAN.md
+IMPLEMENTATION_*.md
+
+# Local configuration files
+*.local
+.env
+
+# Development and testing files
+favicon.ico
+package-lock.json
+test-*.html
+
+# Temporary files and screenshots
+Screenshot*.png
+*-screenshot.png
+error-screenshot.png

Dockerfile

@@ -0,0 +1,14 @@
+# Read the doc: https://huggingface.co/docs/hub/spaces-sdks-docker
+FROM python:3.9
+
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+COPY --chown=user . /app
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

Makefile

@@ -0,0 +1,47 @@
+.PHONY: help dev dev-python dev-docker build test clean install docker-build docker-run docker-dev
+
+help: ## Show this help message
+	@echo "Available commands:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install dependencies
+	@echo "Installing Python dependencies..."
+	pip install -r requirements.txt
+	@echo "No Node dependencies to install (vanilla JS)"
+
+dev: ## Start local static server (for frontend only)
+	@echo "Starting local static server on http://localhost:8000"
+	python -m http.server 8000
+
+dev-python: ## Start FastAPI development server
+	@echo "Starting FastAPI server on http://localhost:7860"
+	python app.py
+
+dev-docker: ## Start development environment with Docker Compose
+	docker-compose --profile dev up --build
+
+build: ## Build the application (no-op for vanilla JS)
+	@echo "No build step needed for vanilla JS application"
+
+test: ## Run tests (placeholder)
+	@echo "No tests configured yet"
+
+clean: ## Clean temporary files
+	find . -type f -name "*.pyc" -delete
+	find . -type d -name "__pycache__" -delete
+	find . -type d -name "node_modules" -exec rm -rf {} + 2>/dev/null || true
+
+docker-build: ## Build Docker image
+	docker build -t cloze-reader .
+
+docker-run: ## Run Docker container
+	docker run -p 7860:7860 --env-file .env cloze-reader
+
+docker-dev: ## Start with docker-compose
+	docker-compose up --build
+
+logs: ## Show Docker logs
+	docker-compose logs -f
+
+stop: ## Stop Docker containers
+	docker-compose down

README.md

@@ -0,0 +1,312 @@
+# Cloze Reader: Recovering Deep Reading Through Algorithmic Assessment
+
+## Introduction
+
+The Cloze Reader transforms classic literature from the public domain into interactive vocabulary exercises powered by large language models. The application uses Google's Gemma-3 architecture to analyze passages from Project Gutenberg, select contextually appropriate words for deletion, and provide adaptive guidance through a conversational interface. Rather than generating novel text, the system surfaces forgotten public domain literature and invites users back to sustained engagement with individual texts—an act of critical resistance against generative systems designed for infinite, undifferentiated content production.
+
+This project stages a recursive relationship: language models trained on prediction tasks are now used to generate prediction exercises for human readers. It forces us to ask what happens when assessment methodology and training methodology become instrumentalized through identical computational systems, when algorithmic selection replaces human pedagogical judgment, and when the boundary between human and machine comprehension becomes difficult to locate.
+
+## Historical Context: Two Parallel Histories That Have Collapsed Into Each Other
+
+### The Educational Assessment History: 1953
+
+Wilson L. Taylor, a reading researcher, published a foundational paper introducing the cloze procedure as a tool for measuring reading comprehension. The methodology is deceptively simple: systematically delete words from a passage, ask readers to fill in the blanks, and score accuracy. Taylor argued that successful completion requires more than mere vocabulary recall. Instead, cloze tests measure contextual understanding—the capacity to integrate syntactic, semantic, pragmatic, and discourse cues to reconstruct deleted language.
+
+The appeal was immediate and substantial. By the 1960s, cloze testing had become standard in American educational assessment, literacy research, and second-language instruction. The procedure offered educators what they desperately wanted: efficiency (many items from a single passage), objectivity (matching against answer keys rather than interpreting essays), and empirical rigor. Cloze tests promised to bypass the messiness of subjective evaluation while producing quantifiable measures of reading ability.
+
+Cloze testing became embedded in the architecture of standardized testing across the United States. It shaped how literacy was defined, measured, and valued. The procedure was not merely an assessment instrument—it codified assumptions about what reading comprehension was and how it should be operationalized for institutional purposes.
+
+### The AI Training History: 2018
+
+In October 2018, researchers at Google, Facebook, and University of Washington published BERT: Pre-training of Deep Bidirectional Transformers for Language Understanding. The paper introduced masked language modeling (MLM) as a pre-training objective. The approach: randomly mask 15% of tokens in a sequence, train the model to predict the missing tokens from context, and iterate across internet-scale text corpora.
+
+Remarkably, the researchers did not reference Taylor or invoke the language of educational assessment. They did not frame their work as a reinvention of the cloze procedure. Yet they had independently converged on cloze methodology as the core training objective for modern transformer models. The theoretical justification was different (learning contextualized embeddings rather than measuring comprehension), but the operational logic was identical: masking creates inference demands; understanding means predicting from context; success can be scored deterministically.
+
+BERT and its successors (RoBERTa, ELECTRA, and countless variants) demonstrated that masked prediction is a powerful inductive bias for learning language. Models trained on MLM objectives developed robust representations of language structure, semantic relationships, and pragmatic patterns. The technique scaled to billions of parameters and trillions of tokens. It became foundational to modern large language models and consumer-facing AI systems.
+
+The methodology migrated from educational psychology to computational linguistics because both domains had discovered something fundamental: understanding language, whether human or algorithmic, is fundamentally about prediction from context.
+
+### The Convergence: Training Becomes Assessment, Assessment Becomes Training
+
+Cloze testing and masked language modeling operate on identical premises:
+
+- **Masking creates inference demands**: Removing a token forces reliance on surrounding structure rather than surface pattern matching.
+- **Context integration**: Success requires synthesizing information across syntactic, semantic, and discourse boundaries.
+- **Efficiency and scalability**: Many items can be processed rapidly; scoring is deterministic (for humans, match vs. non-match; for models, cross-entropy loss).
+- **Variable difficulty**: Some blanks are trivial to fill (limited candidates, high probability); others require deep contextual reasoning.
+
+Recent research explicitly draws these connections. Matsumori et al. (2023) used masked language models to generate open cloze questions for L2 English learners, treating MLM-equipped models as natural question generators. Ondov et al. (2024, NAACL) demonstrated that "the cloze training objective of Masked Language Models makes them a natural choice for generating plausible distractors for human cloze questions." Zhang & Hashimoto (2021) analyzed the inductive biases learned by masked tokens in transformer models, showing that these models acquire statistical and syntactic dependencies—precisely the linguistic phenomena that cloze tests aim to measure in human readers.
+
+The Cloze Reader stages this convergence in a different way. While Gemma-3 (the model powering the system) was trained on next-token prediction rather than masked language modeling, the conceptual framework remains: we are using a language model trained on prediction tasks to generate prediction exercises for human learners. The system demonstrates that cloze generation and evaluation methodologies—once separate domains—are now instrumentalized through the same computational substrate. The boundary between training methodology and evaluation methodology has become permeable.
+
+## Critical Framework: What This Convergence Reveals
+
+### Recursive Assessment
+
+Traditional assessment assumed a clean separation: educators design instruments; students complete them; data informs pedagogy. The Cloze Reader collapses this boundary. The same prediction task that trains state-of-the-art language models now serves as an assessment tool. This recursion raises uncomfortable questions. Can a model trained on surface pattern prediction—albeit at scale and with sophisticated architectures—generate assessment instruments that genuinely measure comprehension? Or does it reproduce the same surface-level pattern matching that enabled its own training? When human users solve cloze exercises generated by such a model, are they engaging in comprehension or replicating the model's own heuristics?
+
+### Standardization Versus Serendipity
+
+Educational cloze testing sought psychometric validity. Practitioners conducted readability studies, piloted passages with student populations, refined difficulty levels, and designed items to discriminate across ability ranges. The entire enterprise was about controlling and calibrating difficulty through human expertise.
+
+The Cloze Reader abandons this control. It uses Gemma models trained on internet-scale text, applies them to the full Project Gutenberg corpus (70,000+ books with no curricular planning), and relies on statistical algorithms to select words for deletion. Difficulty emerges from the algorithmic interaction between passage content and model parameters, not from designed pedagogical intent. The same passage might yield wildly different difficulty levels depending on which words the model selects. What does "appropriate difficulty" mean when the system that determines it is a black box trained on patterns that nobody fully understands?
+
+### Surface Cues Versus Deep Comprehension
+
+Educational researchers have long critiqued cloze testing on the grounds that it measures local, sentence-level inference rather than global text comprehension. A reader might successfully complete a cloze passage by exploiting surface regularities and syntactic patterns without grasping the broader meaning of the text. Similarly, critics of masked language modeling note that models can achieve high accuracy by exploiting spurious statistical correlations rather than developing genuine semantic understanding. When a model trained on surface patterns generates cloze exercises, and human users solve those exercises using similar heuristics, where is comprehension happening? Are we measuring something real, or are we staging an elaborate performance of mutual statistical prediction?
+
+### Authority and Transparency in Assessment Design
+
+For most of the twentieth century, assessment authority was vested in institutional expertise. Teachers selected texts. Curriculum experts designed items. Psychometricians validated instruments. Authority was hierarchical, but it was also documentable: you could point to a specific teacher's choice or a specific item-analysis report. Assessment design was legible, even if it was unequally distributed.
+
+The Cloze Reader distributes authority differently. The models it uses (Gemma-3) are open-weight models that anyone can download, inspect, and run locally. The system is designed for interrogation rather than institutional gatekeeping. You can examine the model's outputs, trace its decisions, modify its behavior, and deploy it on your own hardware. But this distribution of authority comes at a cost. Assessment design is now black-boxed in model weights rather than documented in curriculum guides. Patterns that determine difficulty are learned from billions of internet text samples rather than articulated through expert judgment. Authority is distributed, but it is also obscured.
+
+### The Project Gutenberg Paradox
+
+Project Gutenberg texts occupy a peculiar position in contemporary information ecology. These works are public domain—legally and technically available to everyone. Yet they are remarkably absent from popular consciousness. Most readers encounter these texts, if at all, through abridged excerpts in educational settings. The original, uncut texts languish in digital repositories.
+
+Simultaneously, these same texts have been appropriated relentlessly as training data for large language models. Every major AI system trained on internet-scale corpora has incorporated Project Gutenberg texts. Commercial models have profited from and learned from this public archive without returning anything to the public sphere. The texts that should be most widely read have become most thoroughly invisible—present only as statistical patterns embedded in proprietary model weights.
+
+The Cloze Reader inverts this trajectory. It surfaces Project Gutenberg texts. It makes them the primary content, not auxiliary training material. It asks users to read actual passages, carefully selected for quality but not processed or summarized. The design philosophy is explicit: bring people back to deep reading practices, precisely through engagement with a fill-in-the-blank game that generates genuinely novel exercises for each reader, each session. Unlike generative AI systems designed to produce infinite novel text, the Cloze Reader is designed to deepen engagement with finite, singular texts.
+
+This is not a return to pre-digital reading practices. The system is thoroughly computational. But it is a return to the idea that reading means sustained engagement with specific texts, that repetition and variation can deepen understanding, and that computational systems can serve that deepening rather than obscuring it.
+
+## Architecture and Data Flow
+
+### System Overview
+
+The Cloze Reader is a vanilla JavaScript application with a minimal FastAPI backend. The entire frontend runs in the browser using ES6 modules; there is no build step. This architectural choice prioritizes transparency and modifiability—users can inspect every component without specialized tooling.
+
+### Application Flow
+
+When a user loads the application, the initialization sequence follows a precise path:
+
+1. **Welcome Overlay** displays onboarding instructions for first-time users.
+2. **Game Engine Initialization** loads book data and AI services.
+3. **First Round Generation** creates the initial cloze exercise.
+4. **UI Activation** reveals the interactive game interface.
+
+```tree
+Page Load → app.js initialization
+├─ welcomeOverlay.js → First-time user onboarding
+├─ clozeGameEngine.js → Game state initialization
+│  ├─ bookDataService.js → Stream from Hugging Face Datasets API
+│  │  ├─ Primary: manu/project_gutenberg (70,000+ books)
+│  │  └─ Fallback: Local embedded canonical works
+│  ├─ aiService.js → Gemma-3-27b model selection and word generation
+│  │  ├─ Level-based vocabulary constraints
+│  │  ├─ Passage analysis and candidate filtering
+│  │  └─ Distribution algorithm for blank placement
+│  └─ Content quality filtering (statistical analysis)
+└─ leaderboardService.js → localStorage persistence
+
+User Interaction Loop:
+├─ Input validation → app.js
+├─ Chat interface → chatInterface.js
+│  └─ conversationManager.js → AI conversation state
+├─ Answer submission → clozeGameEngine.js scoring
+└─ Round progression → Level advancement logic
+```
+
+### Core Module Interactions
+
+**bookDataService.js** streams text from the Hugging Face Datasets API, accessing the manu/project_gutenberg dataset containing 70,000+ public domain texts. When streaming fails or APIs become unavailable, the system falls back to locally embedded canonical works (Pride and Prejudice, Tom Sawyer, Great Expectations, and others). Book selection is level-aware: levels 1-2 draw from 1900s publications; levels 3-4 from the 1800s; levels 5+ from any historical period.
+
+**aiService.js** handles all AI operations using Gemma-3-27b via OpenRouter. The same model handles word selection, hint generation, literary contextualization, and conversational responses. For local deployment, the system automatically switches to Gemma-3-12b when `?local=true` is appended to the URL, connecting to port 1234 (compatible with LM Studio and similar tools).
+
+Word selection follows a sophisticated multi-step process: level-based constraints define vocabulary difficulty ranges; passage analysis identifies candidate words while avoiding capitalized words, proper nouns, sentence beginnings, and artifacts; a distribution algorithm ensures blanks are spread throughout the passage; validation filtering confirms words exist in the passage and meet length requirements.
+
+**chatInterface.js** provides word-level assistance through a modal-based interface. Users can ask questions about grammar, meaning, context, or request clues. The system preserves chat history per blank across the entire round, allowing for progressive disclosure of information.
+
+**leaderboardService.js** manages high scores, player statistics, and localStorage persistence. The system tracks highest level reached, round numbers, total passages passed and attempted, and longest consecutive success streaks. Leaderboard data resets on each page load (ensuring fresh competition), but performance statistics persist within a session.
+
+### Content Quality Filtering
+
+The passage extraction system includes sophisticated quality detection to avoid dictionary entries, academic references, technical documentation, and formatting artifacts. The system analyzes capitalization ratios, punctuation density, and sentence structure. It applies pattern recognition for academic material (citations, abbreviations, etymology brackets, Roman numeral references). It detects dictionary-specific formatting (hash symbols used for entry organization) and technical terminology. A progressive scoring system rejects passages above a quality threshold.
+
+### Difficulty Progression
+
+The game implements level-aware difficulty scaling:
+
+- **Levels 1-5**: 1 blank per passage, easier vocabulary (4-7 letters), full hints available
+- **Levels 6-10**: 2 blanks per passage, medium vocabulary (4-10 letters), partial hints
+- **Levels 11+**: 3 blanks per passage, challenging vocabulary (5-14 letters), minimal hints
+
+Level advancement requires passing a single round. Each round contains two passages. Scoring is strict: for 1 blank, 100% accuracy; for 2 blanks, both correct; for 3+ blanks, all but one correct.
+
+## Data Source and Content Pipeline
+
+### Hugging Face Datasets Integration
+
+The primary data source is the manu/project_gutenberg dataset available at [https://huggingface.co/datasets/manu/project_gutenberg](https://huggingface.co/datasets/manu/project_gutenberg). This dataset contains full texts from 70,000+ public domain works, updated continuously as new texts enter the public domain. The system uses lazy loading and on-demand processing, streaming excerpts rather than loading entire books into memory.
+
+### Content Processing
+
+Books undergo sophisticated cleaning to remove Project Gutenberg metadata (scanning notes, OCR artifacts, structural markers), chapter headers, page numbers, and formatting noise. The system identifies the actual narrative content and validates it for sufficient length and narrative structure. This processing is deferred until a book is selected for gameplay, optimizing overall performance.
+
+### Quality Validation
+
+Passages are subject to multiple quality checks. The system analyzes statistical properties (capitalization density, punctuation distribution, sentence length variance), applies pattern detection for reference material and technical content, and screens for dictionary-specific formatting. A passage that fails quality validation is rejected and the system selects a different excerpt or book.
+
+## Technology Stack and Deployment
+
+### Frontend Architecture
+
+The application uses vanilla JavaScript with ES6 modules. There is no build process. This architectural choice is intentional: it keeps the machinery visible and modifiable rather than obscured behind tooling. The application is Progressive Web App (PWA) compatible, with manifest configuration supporting installation on mobile devices.
+
+### Backend and API Integration
+
+The FastAPI server (`app.py`) serves static files and injects API credentials securely into the browser via meta tags. This approach allows the system to handle sensitive credentials (like OpenRouter API keys) without exposing them in client-side code.
+
+### AI Models
+
+**Production Deployment**: Gemma-3-27b via OpenRouter API
+
+**Local Deployment**: Gemma-3-12b on port 1234 (LM Studio, ollama, or OpenAI-compatible servers)
+
+The model selection prioritizes:
+
+- **Open-weight models**: Enables local deployment and inspection
+- **Consistent architecture**: Same model family across production and local deployment
+- **Performance**: Sufficient scale for sophisticated language tasks while remaining computationally feasible
+
+### State Management
+
+All game state persists in `localStorage`. There is no backend database. Storage keys are:
+
+- `cloze-reader-leaderboard`: Top 10 high scores
+- `cloze-reader-player`: Player profile (initials, session metadata)
+- `cloze-reader-stats`: Comprehensive performance analytics
+
+This client-side approach ensures the assessment system is fully auditable. All data transformations occur transparently in browser-side code, not on remote servers.
+
+## Quick Start
+
+### Docker Deployment (Recommended)
+
+```bash
+# Build the image
+docker build -t cloze-reader .
+
+# Run with OpenRouter API key
+docker run -p 7860:7860 -e OPENROUTER_API_KEY=your_key_here cloze-reader
+
+# Access at http://localhost:7860
+```
+
+### Local Python Development
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Start FastAPI server
+python app.py
+
+# Access at http://localhost:7860
+```
+
+### Local Development with Simple HTTP Server
+
+```bash
+# Minimal setup without FastAPI
+python -m http.server 8000
+
+# Access at http://localhost:8000
+```
+
+### Local LLM Integration
+
+To run with a local language model server (no API key required):
+
+```bash
+# Start local LLM server on port 1234 (LM Studio, ollama, or similar)
+# Then access the application with:
+http://localhost:8000?local=true
+```
+
+### Environment Variables
+
+- `OPENROUTER_API_KEY`: Required for production deployment (get from [https://openrouter.ai](https://openrouter.ai))
+- `HF_API_KEY`: Optional, for accessing Hugging Face APIs
+- `HF_TOKEN`: Optional, for Hugging Face Hub leaderboard integration
+
+## Development Commands
+
+Use the provided Makefile for convenience:
+
+```bash
+make install          # Install Python and Node.js dependencies
+make dev             # Start development server (simple HTTP)
+make dev-python      # Start FastAPI development server
+make docker-build    # Build Docker image
+make docker-run      # Run Docker container
+make docker-dev      # Full Docker development environment
+make clean           # Clean build artifacts and cache
+make logs            # View Docker container logs
+make stop            # Stop Docker containers
+```
+
+## Critical Questions This System Poses
+
+1. **Recursive Collapse**: What happens when training methodology becomes assessment tool, and assessment data becomes training data? Where is the meaningful boundary?
+
+2. **Pedagogical Authority**: Can algorithmic selection of passages and words, guided by statistical patterns learned from internet-scale corpora, capture what human educators mean by "appropriate difficulty"?
+
+3. **The Nature of Comprehension**: When a model trained on surface pattern prediction generates cloze exercises, and humans solve those exercises using similar heuristics, what is being measured? Is comprehension happening, or are we staging an elaborate performance of mutual statistical inference?
+
+4. **Institutional Authority**: Traditional assessment vested authority in documented expert judgment. This system distributes authority through open-weight models and client-side code, making it interrogable rather than institutional. What is gained or lost in this distribution?
+
+5. **Reading in the Age of Algorithmic Text Generation**: When generative systems produce infinite novel text, what does it mean to ask users to engage deeply with finite, singular public domain texts? Is this a form of resistance, or capitulation to the same systems that trained the models?
+
+6. **Data Extraction and Repatriation**: Public domain texts have been appropriated relentlessly for AI training. What does it mean to surface these texts, return them to visibility, and ask people to read them directly rather than through algorithmic summaries?
+
+## Technical Details and Error Handling
+
+### AI Service Resilience
+
+The system implements multiple fallback layers:
+
+1. **Retry with exponential backoff**: Up to 3 attempts with increasing delays
+2. **Response extraction hierarchy**: Primary (message.content), secondary (reasoning field), tertiary (reasoning_details array), final (regex pattern matching)
+3. **Manual word selection**: If AI fails, the system falls back to statistical selection based on content analysis
+4. **Generic hint generation**: Fallback responses based on question type when AI service is unavailable
+
+### Content Service Resilience
+
+1. **HF API availability check**: Test connection before streaming attempts
+2. **Preloaded content**: Cached books for immediate access
+3. **Local book fallback**: 10 embedded classics guarantee offline functionality
+4. **Quality validation retry**: Multiple attempts with different passage selections if quality filtering rejects initial selections
+5. **Timeout handling**: 15-second request timeout with automatic fallback to sequential processing
+
+## On This Codebase's Design Philosophy
+
+The technical decisions in this codebase reflect the conceptual interests outlined above:
+
+- **Vanilla JavaScript, no build step**: Keeps machinery visible rather than obscured behind tooling
+- **Open-weight Gemma models**: Enables inspection, local deployment, and interrogation of the assessment generator
+- **Streaming from Project Gutenberg**: Makes the pipeline reproducible without proprietary content
+- **Local LLM support**: Removes dependency on API providers; you can run the entire system on personal hardware
+- **No backend database**: All state is client-side localStorage; the assessment system is fully auditable
+- **Vanilla HTML and CSS**: Aesthetic choices reflect mid-century design rather than contemporary web trends, creating temporal distance between the user and algorithmic systems
+
+The goal is not to resolve the tensions between human assessment and algorithmic generation, between deep reading and computational efficiency, between transparent pedagogy and black-boxed AI. Instead, the goal is to **stage these tensions**—to make them experientially tangible through gameplay. Every passage you encounter is a collision between seventy years of educational assessment theory and seven years of masked language modeling. Every blank you fill is an act of both comprehension and statistical prediction.
+
+## References and Further Reading
+
+Recent research connecting cloze assessment and masked language modeling:
+
+- Matsumori, A., et al. (2023). CLOZER: Generating open cloze questions with masked language models. Proceedings of the 2023 Conference on Empirical Methods in Natural Language Processing.
+- Ondov, B., et al. (2024). Masked language models as natural generators for cloze questions. Proceedings of the 2024 Conference of the North American Chapter of the Association for Computational Linguistics (NAACL).
+- Zhang, Y., & Hashimoto, K. (2021). What do language models learn about the structure of their language? Proceedings of the 59th Annual Meeting of the Association for Computational Linguistics.
+
+## Attribution
+
+This project was created by [Zach Muhlbauer](https://huggingface.co/milwright) at the CUNY Graduate Center. The application draws on extensive research in both educational assessment and natural language processing, bringing two disciplinary histories into dialogue through interactive gameplay.
+
+For more information, visit the development space at [https://huggingface.co/spaces/milwright/cloze-reader](https://huggingface.co/spaces/milwright/cloze-reader) or the underlying dataset at [https://huggingface.co/datasets/manu/project_gutenberg](https://huggingface.co/datasets/manu/project_gutenberg).
+
+---
+
+*The Cloze Reader invites you to encounter public domain literature on its own terms, to practice contextual reasoning in real time, and to confront the strange convergence between how humans and machines understand language through prediction.*

app.py

@@ -0,0 +1,638 @@
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import HTMLResponse, RedirectResponse, FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+from typing import List, Optional
+import os
+import time
+import json
+import asyncio
+import urllib.request
+import urllib.parse
+from dotenv import load_dotenv
+import logging
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Import Leaderboard Services (Redis primary, HF fallback)
+from redis_leaderboard import RedisLeaderboardService
+from redis_analytics import RedisAnalyticsService
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+app = FastAPI()
+
+# Add CORS middleware for local development
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Initialize Leaderboard Service (Redis primary, HF Space fallback)
+# REDIS_URL is auto-injected by Railway when Redis plugin is added
+try:
+    leaderboard_service = RedisLeaderboardService(
+        redis_url=os.getenv("REDIS_URL"),
+        hf_fallback_url="https://milwright-cloze-leaderboard.hf.space",
+        hf_token=os.getenv("HF_TOKEN"),
+    )
+    if leaderboard_service.is_redis_available():
+        logger.info("Leaderboard using Redis (primary) with HF Space (fallback)")
+    else:
+        logger.info("Leaderboard using HF Space (Redis unavailable)")
+except Exception as e:
+    logger.warning(f"Could not initialize Leaderboard Service: {e}")
+    logger.warning("Leaderboard will use localStorage fallback only")
+    leaderboard_service = None
+
+# Initialize Analytics Service (Redis)
+try:
+    analytics_service = RedisAnalyticsService(redis_url=os.getenv("REDIS_URL"))
+    if analytics_service.is_available():
+        logger.info("Analytics Service using Redis")
+    else:
+        logger.info("Analytics Service unavailable (Redis not connected)")
+except Exception as e:
+    logger.warning(f"Could not initialize Analytics Service: {e}")
+    analytics_service = None
+
+# Pydantic models for API
+class LeaderboardEntry(BaseModel):
+    initials: str
+    level: int
+    round: int
+    passagesPassed: int
+    date: str
+
+class LeaderboardResponse(BaseModel):
+    success: bool
+    leaderboard: List[LeaderboardEntry]
+    message: Optional[str] = None
+
+
+# Pydantic models for Analytics API
+class WordAnalytics(BaseModel):
+    word: str
+    length: Optional[int] = None
+    attemptsToCorrect: int = 1
+    # Avoid mutable default list
+    hintsUsed: List[str] = Field(default_factory=list)
+    finalCorrect: bool = False
+
+
+class PassageAnalytics(BaseModel):
+    passageId: str
+    sessionId: str
+    bookTitle: str
+    bookAuthor: str
+    level: int
+    round: int
+    words: List[WordAnalytics]
+    totalBlanks: int
+    correctOnFirstTry: int
+    totalHintsUsed: int
+    passed: bool
+    timestamp: Optional[str] = None
+
+# Mount static files
+app.mount("/src", StaticFiles(directory="src"), name="src")
+
+@app.get("/icon.png")
+async def get_icon():
+    """Serve the app icon locally if available, else fallback to GitHub."""
+    local_icon = "icon.png"
+    if os.path.exists(local_icon):
+        return FileResponse(local_icon, media_type="image/png")
+    # Fallback to GitHub-hosted icon
+    return RedirectResponse(url="https://media.githubusercontent.com/media/milwrite/cloze-reader/main/icon.png")
+
+@app.get("/favicon.png")
+async def get_favicon_png():
+    """Serve favicon as PNG by pointing to the canonical PNG icon."""
+    return await get_icon()
+
+@app.get("/favicon.ico")
+async def get_favicon_ico():
+    """Serve an ICO route that points to our PNG so browsers can find it."""
+    # Many browsers request /favicon.ico explicitly; return PNG is acceptable
+    return await get_favicon_png()
+
+@app.get("/favicon.svg")
+async def get_favicon_svg():
+    """Serve SVG favicon for browsers that support it."""
+    # Prefer `icon.svg` if available
+    for candidate in ["favicon.svg", "icon.svg"]:
+        if os.path.exists(candidate):
+            return FileResponse(candidate, media_type="image/svg+xml")
+    # If missing, fall back to PNG icon
+    return await get_favicon_png()
+
+@app.get("/icon.svg")
+async def get_icon_svg():
+    """Serve the SVG icon at /icon.svg if present, else fallback to PNG."""
+    candidate = "icon.svg"
+    if os.path.exists(candidate):
+        return FileResponse(candidate, media_type="image/svg+xml")
+    return await get_icon()
+
+@app.get("/apple-touch-icon.png")
+async def get_apple_touch_icon():
+    """Serve Apple touch icon, fallback to main icon."""
+    candidate = "apple-touch-icon.png"
+    if os.path.exists(candidate):
+        return FileResponse(candidate, media_type="image/png")
+    return await get_icon()
+
+@app.get("/site.webmanifest")
+async def site_manifest():
+    """Serve the web app manifest if present, else a minimal generated one."""
+    manifest_path = "site.webmanifest"
+    if os.path.exists(manifest_path):
+        return FileResponse(manifest_path, media_type="application/manifest+json")
+    # Minimal default manifest
+    content = {
+        "name": "Cloze Reader",
+        "short_name": "Cloze",
+        "icons": [
+            {"src": "./icon-192.png", "type": "image/png", "sizes": "192x192"},
+            {"src": "./icon-512.png", "type": "image/png", "sizes": "512x512"}
+        ],
+        "start_url": "./",
+        "display": "standalone",
+        "background_color": "#ffffff",
+        "theme_color": "#2c2826"
+    }
+    return JSONResponse(content=content, media_type="application/manifest+json")
+
+@app.get("/icon-192.png")
+async def get_icon_192():
+    path = "icon-192.png"
+    if os.path.exists(path):
+        return FileResponse(path, media_type="image/png")
+    return await get_icon()
+
+@app.get("/icon-512.png")
+async def get_icon_512():
+    path = "icon-512.png"
+    if os.path.exists(path):
+        return FileResponse(path, media_type="image/png")
+    return await get_icon()
+
+@app.get("/admin")
+async def admin_dashboard():
+    """Serve the analytics admin dashboard"""
+    with open("admin.html", "r") as f:
+        return HTMLResponse(content=f.read())
+
+
+@app.get("/")
+async def read_root():
+    # Read the HTML file and inject environment variables
+    with open("index.html", "r") as f:
+        html_content = f.read()
+    
+    # Inject environment variables as a script
+    openrouter_key = os.getenv("OPENROUTER_API_KEY", "")
+    hf_key = os.getenv("HF_API_KEY", "")
+    
+    # Create a CSP-compliant way to inject the keys
+    env_script = f"""
+    <meta name="openrouter-key" content="{openrouter_key}">
+    <meta name="hf-key" content="{hf_key}">
+    <script src="./src/init-env.js"></script>
+    """
+    
+    # Insert the script before closing head tag
+    html_content = html_content.replace("</head>", env_script + "</head>")
+    
+    return HTMLResponse(content=html_content)
+
+
+# ===== LEADERBOARD API ENDPOINTS =====
+
+@app.get("/api/leaderboard", response_model=LeaderboardResponse)
+async def get_leaderboard():
+    """
+    Get current leaderboard data (Redis primary, HF Space fallback)
+    """
+    if not leaderboard_service:
+        return {
+            "success": True,
+            "leaderboard": [],
+            "message": "Leaderboard service not available (using localStorage only)"
+        }
+
+    try:
+        leaderboard = leaderboard_service.get_leaderboard()
+        return {
+            "success": True,
+            "leaderboard": leaderboard,
+            "message": f"Retrieved {len(leaderboard)} entries"
+        }
+    except Exception as e:
+        logger.error(f"Error fetching leaderboard: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/leaderboard/add")
+async def add_leaderboard_entry(entry: LeaderboardEntry):
+    """
+    Add new entry to leaderboard
+    """
+    if not leaderboard_service:
+        raise HTTPException(status_code=503, detail="Leaderboard service not available")
+
+    try:
+        success = leaderboard_service.add_entry(entry.dict())
+        if success:
+            return {
+                "success": True,
+                "message": f"Added {entry.initials} to leaderboard"
+            }
+        else:
+            raise HTTPException(status_code=500, detail="Failed to add entry")
+    except ValueError as e:
+        raise HTTPException(status_code=403, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error adding entry: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/leaderboard/update")
+async def update_leaderboard(entries: List[LeaderboardEntry]):
+    """
+    Update entire leaderboard (replace all data)
+    """
+    if not leaderboard_service:
+        raise HTTPException(status_code=503, detail="Leaderboard service not available")
+
+    try:
+        success = leaderboard_service.update_leaderboard([e.dict() for e in entries])
+        if success:
+            return {
+                "success": True,
+                "message": "Leaderboard updated successfully"
+            }
+        else:
+            raise HTTPException(status_code=500, detail="Failed to update leaderboard")
+    except ValueError as e:
+        raise HTTPException(status_code=403, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error updating leaderboard: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.delete("/api/leaderboard/clear")
+async def clear_leaderboard():
+    """
+    Clear all leaderboard data (admin only)
+    """
+    if not leaderboard_service:
+        raise HTTPException(status_code=503, detail="Leaderboard service not available")
+
+    try:
+        success = leaderboard_service.clear_leaderboard()
+        if success:
+            return {
+                "success": True,
+                "message": "Leaderboard cleared"
+            }
+        else:
+            raise HTTPException(status_code=500, detail="Failed to clear leaderboard")
+    except ValueError as e:
+        raise HTTPException(status_code=403, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error clearing leaderboard: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/leaderboard/seed-from-hf")
+async def seed_leaderboard_from_hf():
+    """
+    Force re-seed Redis leaderboard from HF Space (admin function).
+    Use this to migrate existing HF Space data to Redis.
+    """
+    if not leaderboard_service:
+        raise HTTPException(status_code=503, detail="Leaderboard service not available")
+
+    try:
+        success = leaderboard_service.force_seed_from_hf()
+        if success:
+            leaderboard = leaderboard_service.get_leaderboard()
+            return {
+                "success": True,
+                "message": f"Seeded Redis with {len(leaderboard)} entries from HF Space",
+                "entries": len(leaderboard)
+            }
+        else:
+            return {
+                "success": False,
+                "message": "No entries found in HF Space to seed"
+            }
+    except Exception as e:
+        logger.error(f"Error seeding leaderboard from HF: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# ===== ANALYTICS API ENDPOINTS =====
+
+@app.post("/api/analytics/passage")
+async def record_passage_analytics(data: PassageAnalytics):
+    """
+    Record a completed passage attempt with analytics data.
+    Called by frontend when a passage is completed (pass or fail).
+    """
+    if not analytics_service or not analytics_service.is_available():
+        # Gracefully degrade - don't fail the game if analytics unavailable
+        return {
+            "success": False,
+            "message": "Analytics service unavailable"
+        }
+
+    try:
+        # Convert Pydantic models to dicts
+        data_dict = data.dict()
+        data_dict["words"] = [w.dict() for w in data.words]
+
+        entry_id = analytics_service.record_passage(data_dict)
+        if entry_id:
+            return {
+                "success": True,
+                "entryId": entry_id,
+                "message": "Passage analytics recorded"
+            }
+        else:
+            return {
+                "success": False,
+                "message": "Failed to record analytics"
+            }
+    except Exception as e:
+        logger.error(f"Error recording passage analytics: {e}")
+        # Don't raise - analytics failure shouldn't break gameplay
+        return {
+            "success": False,
+            "message": str(e)
+        }
+
+
+@app.get("/api/analytics/summary")
+async def get_analytics_summary():
+    """
+    Get aggregate analytics statistics for admin dashboard.
+    Returns totals, hardest/easiest words, and popular books.
+    """
+    if not analytics_service:
+        return {
+            "success": True,
+            "data": {
+                "totalPassages": 0,
+                "totalSessions": 0,
+                "hardestWords": [],
+                "easiestWords": [],
+                "popularBooks": []
+            },
+            "message": "Analytics service unavailable"
+        }
+
+    try:
+        summary = analytics_service.get_summary()
+        return {
+            "success": True,
+            "data": summary,
+            "message": f"Retrieved analytics summary"
+        }
+    except Exception as e:
+        logger.error(f"Error getting analytics summary: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/analytics/recent")
+async def get_recent_analytics(count: int = 50):
+    """
+    Get recent passage attempts for admin review.
+
+    Args:
+        count: Number of recent entries to retrieve (default: 50, max: 200)
+    """
+    if not analytics_service:
+        return {
+            "success": True,
+            "passages": [],
+            "message": "Analytics service unavailable"
+        }
+
+    # Cap at 200 entries
+    count = min(count, 200)
+
+    try:
+        passages = analytics_service.get_recent_passages(count)
+        return {
+            "success": True,
+            "passages": passages,
+            "count": len(passages),
+            "message": f"Retrieved {len(passages)} recent passages"
+        }
+    except Exception as e:
+        logger.error(f"Error getting recent analytics: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/analytics/export")
+async def export_all_analytics():
+    """
+    Export all analytics data as JSON (admin function).
+    Use for backup or external analysis.
+    """
+    if not analytics_service:
+        return {
+            "success": False,
+            "passages": [],
+            "message": "Analytics service unavailable"
+        }
+
+    try:
+        all_data = analytics_service.export_all()
+        return {
+            "success": True,
+            "passages": all_data,
+            "count": len(all_data),
+            "message": f"Exported {len(all_data)} passage records"
+        }
+    except Exception as e:
+        logger.error(f"Error exporting analytics: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/analytics/word/{word}")
+async def get_word_statistics(word: str):
+    """
+    Get statistics for a specific word.
+    Shows how often the word was correct on first try vs needing retries.
+    """
+    if not analytics_service:
+        return {
+            "success": True,
+            "data": {"word": word, "firstTryCount": 0, "retryCount": 0},
+            "message": "Analytics service unavailable"
+        }
+
+    try:
+        stats = analytics_service.get_word_stats(word)
+        return {
+            "success": True,
+            "data": stats,
+            "message": f"Retrieved stats for '{word}'"
+        }
+    except Exception as e:
+        logger.error(f"Error getting word stats: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.delete("/api/analytics/clear")
+async def clear_all_analytics():
+    """
+    Clear all analytics data (admin function).
+    WARNING: This permanently deletes all recorded analytics.
+    """
+    if not analytics_service:
+        raise HTTPException(status_code=503, detail="Analytics service unavailable")
+
+    try:
+        success = analytics_service.clear_analytics()
+        if success:
+            return {
+                "success": True,
+                "message": "All analytics data cleared"
+            }
+        else:
+            raise HTTPException(status_code=500, detail="Failed to clear analytics")
+    except Exception as e:
+        logger.error(f"Error clearing analytics: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)
+
+
+# ================== HF DATASETS PROXY ENDPOINTS ==================
+
+HF_DATASETS_BASE = "https://datasets-server.huggingface.co"
+
+# very small in-memory cache suitable for single-process app
+_proxy_cache = {
+    "splits": {},  # key -> {value, ts, ttl}
+    "rows": {},
+}
+
+
+def _cache_get(bucket: str, key: str):
+    entry = _proxy_cache.get(bucket, {}).get(key)
+    if not entry:
+        return None
+    if time.time() - entry["ts"] > entry["ttl"]:
+        try:
+            del _proxy_cache[bucket][key]
+        except Exception:
+            pass
+        return None
+    return entry["value"]
+
+
+def _cache_set(bucket: str, key: str, value, ttl: int):
+    _proxy_cache.setdefault(bucket, {})[key] = {
+        "value": value,
+        "ts": time.time(),
+        "ttl": ttl,
+    }
+
+
+def _fetch_sync(url: str, timeout: float = 3.0):
+    req = urllib.request.Request(
+        url,
+        headers={
+            "Accept": "application/json",
+            "User-Agent": "cloze-reader/1.0 (+fastapi-proxy)",
+        },
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        status = resp.getcode()
+        body = resp.read()
+        return status, body
+
+
+async def _fetch_json(url: str, timeout: float = 3.0):
+    try:
+        status, body = await asyncio.to_thread(_fetch_sync, url, timeout)
+        if status != 200:
+            raise HTTPException(status_code=status, detail=f"Upstream returned {status}")
+        return json.loads(body.decode("utf-8"))
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=502, detail=f"Upstream fetch failed: {e}")
+
+
+@app.get("/api/books/splits")
+async def proxy_hf_splits(
+    dataset: str = Query(..., description="HF dataset repo id, e.g. manu/project_gutenberg"),
+    cache_ttl: int = Query(300, description="Cache TTL seconds (default 300)"),
+):
+    """Proxy the HF datasets splits endpoint with caching and timeout.
+
+    Example: /api/books/splits?dataset=manu/project_gutenberg
+    """
+    dataset_q = urllib.parse.quote(dataset, safe="")
+    url = f"{HF_DATASETS_BASE}/splits?dataset={dataset_q}"
+
+    cached = _cache_get("splits", url)
+    if cached is not None:
+        return cached
+
+    data = await _fetch_json(url, timeout=3.0)
+    _cache_set("splits", url, data, ttl=max(1, cache_ttl))
+    return data
+
+
+@app.get("/api/books/rows")
+async def proxy_hf_rows(
+    dataset: str = Query(...),
+    config: str = Query("default"),
+    split: str = Query("en"),
+    offset: int = Query(0, ge=0, le=1000000),
+    length: int = Query(1, ge=1, le=50),
+    cache_ttl: int = Query(60, description="Cache TTL seconds for identical queries (default 60)"),
+):
+    """Proxy the HF datasets rows endpoint with short timeout and small cache.
+
+    Example:
+    /api/books/rows?dataset=manu/project_gutenberg&config=default&split=en&offset=0&length=2
+    """
+    params = {
+        "dataset": dataset,
+        "config": config,
+        "split": split,
+        "offset": str(offset),
+        "length": str(length),
+    }
+    qs = urllib.parse.urlencode(params)
+    url = f"{HF_DATASETS_BASE}/rows?{qs}"
+
+    cached = _cache_get("rows", url)
+    if cached is not None:
+        return cached
+
+    # Allow longer timeout for HF API which can be slow under load
+    # 15s should handle most cases without client-side abort racing
+    data = await _fetch_json(url, timeout=15.0)
+    # Cache briefly to smooth bursts; rows vary by offset so cache is typically small
+    _cache_set("rows", url, data, ttl=max(1, cache_ttl))
+    return data

docker-compose.yml

@@ -0,0 +1,27 @@
+version: '3.8'
+
+services:
+  cloze-reader:
+    build: .
+    ports:
+      - "7860:7860"
+    environment:
+      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY:-}
+      - HF_API_KEY=${HF_API_KEY:-}
+    volumes:
+      - ./src:/app/src:ro
+      - ./index.html:/app/index.html:ro
+    restart: unless-stopped
+    
+  dev-server:
+    image: python:3.9-slim
+    working_dir: /app
+    ports:
+      - "8000:8000"
+    volumes:
+      - .:/app
+    command: python -m http.server 8000
+    environment:
+      - PYTHONUNBUFFERED=1
+    profiles:
+      - dev

index.html

@@ -0,0 +1,88 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Cloze Reader</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <link href="https://fonts.googleapis.com/css2?family=Special+Elite&display=swap" rel="stylesheet">
+    <link href="./src/styles.css" rel="stylesheet">
+    <link rel="icon" type="image/svg+xml" href="./favicon.svg">
+    <link rel="icon" type="image/png" href="./favicon.png">
+    <link rel="shortcut icon" href="./favicon.ico">
+    <link rel="apple-touch-icon" href="./apple-touch-icon.png">
+    <link rel="manifest" href="./site.webmanifest">
+</head>
+<body class="min-h-screen">
+    <div id="app" class="container mx-auto px-4 py-8 max-w-4xl">
+        <header class="text-center mb-8">
+            <div class="flex items-center justify-center mb-4 gap-3">
+                <img src="https://media.githubusercontent.com/media/milwrite/cloze-reader/main/icon.png" alt="Cloze Reader" class="w-12 h-12">
+                <h1 class="text-4xl font-bold typewriter-text">Cloze Reader</h1>
+            </div>
+            <p class="typewriter-subtitle text-center">Fill in the blanks to practice reading comprehension</p>
+        </header>
+        
+        <main id="game-container" class="space-y-6">
+            <div id="loading" class="text-center py-8">
+                <p class="text-lg loading-text">Loading passages...</p>
+            </div>
+            
+            <div id="game-area" class="paper-sheet rounded-lg p-6 hidden">
+                <div class="paper-content">
+                    <div class="flex justify-between items-center mb-4">
+                        <div id="book-info" class="biblio-info"></div>
+                        <div class="flex gap-2 items-center">
+                            <div id="streak-info" class="round-badge px-3 py-1 rounded-full text-sm hidden"></div>
+                            <div id="round-info" class="round-badge px-3 py-1 rounded-full text-sm"></div>
+                        </div>
+                    </div>
+                    <div id="contextualization" class="context-box mb-4 p-3 rounded-lg"></div>
+                    <div id="passage-content" class="prose max-w-none mb-6"></div>
+                    <div id="hints-section" class="hints-box mb-4 p-3 rounded-lg">
+                        <div class="text-sm font-semibold mb-2">👉👈 Hints:</div>
+                        <div id="hints-list" class="text-sm space-y-1"></div>
+                    </div>
+                    <div id="controls" class="hidden">
+                        <!-- Controls moved to sticky footer -->
+                    </div>
+                    <div id="result" class="mt-4 text-center result-text"></div>
+                </div>
+            </div>
+        </main>
+    </div>
+    
+    <!-- Sticky Control Panel -->
+    <div id="sticky-controls" class="sticky-controls hidden">
+        <div class="controls-inner">
+            <button type="button" id="submit-btn" class="typewriter-button">
+                Submit
+            </button>
+            <button type="button" id="skip-btn" class="typewriter-button hidden">
+                Skip
+            </button>
+            <button type="button" id="next-btn" class="typewriter-button hidden">
+                Next Passage
+            </button>
+            <div class="controls-divider"></div>
+            <button type="button" id="hint-btn" class="typewriter-button">
+                Show Hints
+            </button>
+            <div class="controls-divider"></div>
+            <button type="button" id="leaderboard-btn" class="leaderboard-footer-btn" title="View leaderboard">
+                🏅
+            </button>
+        </div>
+    </div>
+    
+    <script src="./src/app.js?v=20260109-2" type="module"></script>
+    <script type="module">
+        // Load test runner and ranking interface only in test mode
+        const urlParams = new URLSearchParams(window.location.search);
+        if (urlParams.get('testMode') === 'true') {
+            import('./src/testGameRunner.js');
+            import('./src/userRankingInterface.js');
+        }
+    </script>
+</body>
+</html>

requirements.txt

@@ -0,0 +1,5 @@
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+python-dotenv==1.0.0
+redis>=5.0.0
+httpx>=0.25.0

site.webmanifest

@@ -0,0 +1,12 @@
+{
+  "name": "Cloze Reader",
+  "short_name": "Cloze",
+  "icons": [
+    { "src": "./icon-192.png", "type": "image/png", "sizes": "192x192" },
+    { "src": "./icon-512.png", "type": "image/png", "sizes": "512x512" }
+  ],
+  "start_url": "./",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#2c2826"
+}

src/aiService.js

@@ -0,0 +1,736 @@
+class OpenRouterService {
+  constructor() {
+    // Check for local LLM mode
+    this.isLocalMode = this.checkLocalMode();
+    this.apiUrl = this.isLocalMode ? 'http://localhost:1234/v1/chat/completions' : 'https://openrouter.ai/api/v1/chat/completions';
+    this.apiKey = this.getApiKey();
+    
+    // Single model configuration: Gemma-3-27b for all operations
+    this.hintModel = this.isLocalMode ? 'gemma-3-12b' : 'google/gemma-3-27b-it';
+    this.primaryModel = this.isLocalMode ? 'gemma-3-12b' : 'google/gemma-3-27b-it';
+    this.model = this.primaryModel; // Default model for backward compatibility
+
+    console.log('🤖 AI Service initialized', {
+      mode: this.isLocalMode ? 'Local LLM' : 'OpenRouter',
+      url: this.apiUrl,
+      primaryModel: this.primaryModel,
+      hintModel: this.hintModel
+    });
+  }
+
+  // Helper: Extract content from API response (handles reasoning mode variants)
+  _extractContentFromResponse(data) {
+    const msg = data?.choices?.[0]?.message;
+    if (!msg) return null;
+    return msg.content || msg.reasoning || msg.reasoning_details?.[0]?.text || null;
+  }
+
+  // Helper: Build word map from passage for validation
+  _createPassageWordMap(passage) {
+    const passageWords = passage.split(/\s+/);
+    const map = new Map();
+    passageWords.forEach((word, idx) => {
+      const clean = word.replace(/[^\w]/g, '');
+      const lower = clean.toLowerCase();
+      const isCapitalized = clean.length > 0 && clean[0] === clean[0].toUpperCase();
+      if (!isCapitalized && idx >= 10) {
+        if (!map.has(lower)) map.set(lower, []);
+        map.get(lower).push(idx);
+      }
+    });
+    return map;
+  }
+
+  // Helper: Validate words against passage and level constraints
+  // Note: Length constraints relaxed to ensure playability - difficulty comes from
+  // AI word selection prompts ("easy/common" vs "challenging"), not strict length limits
+  _validateWords(words, passageWordMap, level, passageText = null) {
+    return words.filter(word => {
+      if (!/[a-zA-Z]/.test(word)) return false;
+      const clean = word.replace(/[^a-zA-Z]/g, '');
+      if (!clean.length) return false;
+      if (/^(from|to|and)(the|a)$/i.test(clean)) return false;
+      if (!passageWordMap.has(clean.toLowerCase())) return false;
+      if (passageText && passageText.includes(word.toUpperCase()) && word === word.toUpperCase()) return false;
+      // Relaxed: 4-12 letters for levels 1-4, 4-14 for level 5+
+      // Matches manual fallback in clozeGameEngine.js selectWordsManually()
+      if (level <= 4) return clean.length >= 4 && clean.length <= 12;
+      return clean.length >= 4 && clean.length <= 14;
+    });
+  }
+
+  // Helper: Clean up AI response artifacts
+  _cleanupAIResponse(content) {
+    return content
+      .replace(/^\s*["']|["']\s*$/g, '')
+      .replace(/^\s*[:;.!?]+\s*/, '')
+      .replace(/\*+/g, '')
+      .replace(/_+/g, '')
+      .replace(/#+\s*/g, '')
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+
+  checkLocalMode() {
+    if (typeof window !== 'undefined' && window.location) {
+      const urlParams = new URLSearchParams(window.location.search);
+      return urlParams.get('local') === 'true';
+    }
+    return false;
+  }
+
+  getApiKey() {
+    // Local mode doesn't need API key
+    if (this.isLocalMode) {
+      return 'local-mode-no-key';
+    }
+    if (typeof process !== 'undefined' && process.env && process.env.OPENROUTER_API_KEY) {
+      return process.env.OPENROUTER_API_KEY;
+    }
+    if (typeof window !== 'undefined' && window.OPENROUTER_API_KEY) {
+      return window.OPENROUTER_API_KEY;
+    }
+    // console.warn('No API key found in getApiKey()');
+    return '';
+  }
+
+  setApiKey(key) {
+    this.apiKey = key;
+  }
+
+  async retryRequest(requestFn, maxRetries = 3, delayMs = 500) {
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        return await requestFn();
+      } catch (error) {
+        if (attempt === maxRetries) {
+          throw error; // Final attempt failed, throw the error
+        }
+        // Wait before retrying, with exponential backoff
+        const delay = delayMs * Math.pow(2, attempt - 1);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  async generateContextualHint(prompt) {
+    // Check for API key at runtime
+    const currentKey = this.getApiKey();
+    if (currentKey && !this.apiKey) {
+      this.apiKey = currentKey;
+    }
+    
+    if (!this.apiKey) {
+      return 'API key required for hints';
+    }
+
+    try {
+      const headers = {
+        'Content-Type': 'application/json'
+      };
+      
+      // Only add auth headers for OpenRouter
+      if (!this.isLocalMode) {
+        headers['Authorization'] = `Bearer ${this.apiKey}`;
+        headers['HTTP-Referer'] = window.location.origin;
+        headers['X-Title'] = 'Cloze Reader';
+      }
+      
+      const response = await fetch(this.apiUrl, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+          model: this.hintModel,  // Use Gemma-3-27b for hints
+          messages: [{
+            role: 'system',
+            content: 'You are a helpful assistant that provides hints for word puzzles. Never reveal the answer word directly.'
+          }, {
+            role: 'user',
+            content: prompt
+          }],
+          max_tokens: 150,
+          temperature: 0.7,
+          // Try to disable reasoning mode for hints
+          response_format: { type: "text" }
+        })
+      });
+
+      if (!response.ok) {
+        throw new Error(`API request failed: ${response.status}`);
+      }
+
+      const data = await response.json();
+      
+      
+      // Check if data and choices exist before accessing
+      if (!data || !data.choices || data.choices.length === 0) {
+        console.error('Invalid API response structure:', data);
+        return 'Unable to generate hint at this time';
+      }
+      
+      // Check if message exists
+      if (!data.choices[0].message) {
+        console.error('No message in API response');
+        return 'Unable to generate hint at this time';
+      }
+
+      // Extract content from response (handles reasoning mode variants)
+      let content = this._extractContentFromResponse(data);
+
+      if (!content) {
+        console.error('No content found in hint response');
+        // Provide a generic hint based on the prompt type
+        if (prompt.toLowerCase().includes('synonym')) {
+          return 'Think of a word that means something similar';
+        } else if (prompt.toLowerCase().includes('definition')) {
+          return 'Consider what this word means in context';
+        } else if (prompt.toLowerCase().includes('category')) {
+          return 'Think about what type or category this word belongs to';
+        } else {
+          return 'Consider the context around the blank';
+        }
+      }
+      
+      content = content.trim();
+      
+      // For OSS-20B, extract hint from reasoning text if needed
+      if (content.includes('The user') || content.includes('We need to')) {
+        // This looks like reasoning text, try to extract the actual hint
+        // Look for text about synonyms, definitions, or clues
+        const hintPatterns = [
+          /synonym[s]?.*?(?:is|are|include[s]?|would be)\s+([^.]+)/i,
+          /means?\s+([^.]+)/i,
+          /refers? to\s+([^.]+)/i,
+          /describes?\s+([^.]+)/i,
+        ];
+        
+        for (const pattern of hintPatterns) {
+          const match = content.match(pattern);
+          if (match) {
+            content = match[1];
+            break;
+          }
+        }
+        
+        // If still has reasoning markers, just return a fallback
+        if (content.includes('The user') || content.includes('We need to')) {
+          return 'Think about words that mean something similar';
+        }
+      }
+      
+      // Clean up AI response artifacts
+      return this._cleanupAIResponse(content);
+    } catch (error) {
+      console.error('Error generating contextual hint:', error);
+      return 'Unable to generate hint at this time';
+    }
+  }
+
+
+  async selectSignificantWords(passage, count, level = 1) {
+    
+    // Check for API key at runtime in case it was loaded after initialization
+    const currentKey = this.getApiKey();
+    if (currentKey && !this.apiKey) {
+      this.apiKey = currentKey;
+    }
+    
+    
+    if (!this.apiKey) {
+      console.error('No API key for word selection');
+      throw new Error('API key required for word selection');
+    }
+
+    // Define level-based constraints (relaxed length to ensure playability)
+    let wordLengthConstraint, difficultyGuidance;
+    if (level <= 2) {
+      wordLengthConstraint = "4-12 letters";
+      difficultyGuidance = "Select EASY vocabulary words - common, everyday words that most readers know.";
+    } else if (level <= 4) {
+      wordLengthConstraint = "4-12 letters";
+      difficultyGuidance = "Select MEDIUM difficulty words - mix of common and moderately challenging vocabulary.";
+    } else {
+      wordLengthConstraint = "4-14 letters";
+      difficultyGuidance = "Select CHALLENGING words - sophisticated vocabulary that requires strong reading skills.";
+    }
+
+    try {
+      return await this.retryRequest(async () => {
+        const response = await fetch(this.apiUrl, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${this.apiKey}`,
+            'HTTP-Referer': window.location.origin,
+            'X-Title': 'Cloze Reader'
+          },
+          body: JSON.stringify({
+            model: this.primaryModel,  // Use Gemma-3-12b for word selection
+            messages: [{
+              role: 'system',
+              content: 'Select words for a cloze exercise. Return ONLY a JSON array of words, nothing else.'
+            }, {
+              role: 'user',
+              content: `Select ${count} ${level <= 2 ? 'easy' : level <= 4 ? 'medium' : 'challenging'} words (${wordLengthConstraint}) from this passage.
+
+CRITICAL RULES:
+- Select EXACT words that appear in the passage (copy them exactly as written)
+- ONLY select lowercase words (no capitalized words, no proper nouns)
+- ONLY select words from the MIDDLE or END of the passage (skip the first ~10 words)
+- Words must be ${wordLengthConstraint}
+- Choose nouns, verbs, or adjectives
+- AVOID compound words like "courthouse" or "steamboat" - choose single, verifiable words with semantic inbetweenness
+- AVOID indexes, tables of contents, and capitalized content
+- Return ONLY a JSON array like ["word1", "word2"]
+
+Passage: "${passage}"`
+            }],
+            max_tokens: 200,
+            temperature: 0.5,
+            // Try to disable reasoning mode for word selection
+            response_format: { type: "text" }
+          })
+        });
+
+        if (!response.ok) {
+          throw new Error(`API request failed: ${response.status}`);
+        }
+
+        const data = await response.json();
+        
+        // Check for OpenRouter error response
+        if (data.error) {
+          console.error('OpenRouter API error for word selection:', data.error);
+          throw new Error(`OpenRouter API error: ${data.error.message || JSON.stringify(data.error)}`);
+        }
+        
+        // Log the full response to debug structure
+        
+        // Check if response has expected structure
+        if (!data.choices || !data.choices[0] || !data.choices[0].message) {
+          console.error('Invalid word selection API response structure:', data);
+          console.error('Choices[0]:', data.choices?.[0]);
+          throw new Error('API response missing expected structure');
+        }
+        
+        // Extract content from response (handles reasoning mode variants)
+        let content = this._extractContentFromResponse(data);
+
+        if (!content) {
+          console.error('No content found in API response');
+          throw new Error('API response missing content');
+        }
+        
+        content = content.trim();
+        
+        // Clean up local LLM artifacts
+        if (this.isLocalMode) {
+          content = this.cleanLocalLLMResponse(content);
+        }
+        
+        // Try to parse as JSON array
+        try {
+          let words;
+          
+          // Try to parse JSON first
+          try {
+            // Check if content contains JSON array anywhere in it
+            const jsonMatch = content.match(/\[[\s\S]*?\]/);
+            if (jsonMatch) {
+              words = JSON.parse(jsonMatch[0]);
+            } else {
+              words = JSON.parse(content);
+            }
+          } catch {
+            // If not JSON, check if this is reasoning text from OSS-20B
+            if (content.includes('pick') || content.includes('Let\'s')) {
+              // Extract words from reasoning text
+              // Look for quoted words or words after "pick"
+              const quotedWords = content.match(/"([^"]+)"/g);
+              if (quotedWords) {
+                words = quotedWords.map(w => w.replace(/"/g, ''));
+              } else {
+                // Look for pattern like "Let's pick 'word'" or "pick word"
+                const pickMatch = content.match(/pick\s+['"]?(\w+)['"]?/i);
+                if (pickMatch) {
+                  words = [pickMatch[1]];
+                } else {
+                  // For local LLM, try comma-separated
+                  if (this.isLocalMode && content.includes(',')) {
+                    words = content.split(',').map(w => w.trim());
+                  } else {
+                    // Single word
+                    words = [content.trim()];
+                  }
+                }
+              }
+            } else if (this.isLocalMode) {
+              // For local LLM, try comma-separated
+              if (content.includes(',')) {
+                words = content.split(',').map(w => w.trim());
+              } else {
+                // Single word
+                words = [content.trim()];
+              }
+            } else {
+              throw new Error('Could not parse words from response');
+            }
+          }
+          
+          if (Array.isArray(words)) {
+            // Create passage word map and validate words
+            const passageWordMap = this._createPassageWordMap(passage);
+            const validWords = this._validateWords(words, passageWordMap, level);
+
+            if (validWords.length > 0) {
+              return validWords.slice(0, count);
+            } else {
+              console.warn(`No words met requirements for level ${level}`);
+              throw new Error(`No valid words for level ${level}`);
+            }
+          }
+        } catch (e) {
+          // If not valid JSON, try to extract words from the response
+          const matches = content.match(/"([^"]+)"/g);
+          if (matches) {
+            const words = matches.map(m => m.replace(/"/g, ''));
+
+            // Create passage word map and validate words
+            const passageWordMap = this._createPassageWordMap(passage);
+            const validWords = this._validateWords(words, passageWordMap, level);
+
+            if (validWords.length > 0) {
+              return validWords.slice(0, count);
+            } else {
+              throw new Error(`No valid words for level ${level}`);
+            }
+          }
+        }
+        
+        throw new Error('Failed to parse AI response');
+      });
+    } catch (error) {
+      console.error('Error selecting words with AI:', error);
+      throw error;
+    }
+  }
+
+  async processBothPassages(passage1, book1, passage2, book2, blanksPerPassage, level = 1) {
+    // Process both passages in a single API call to avoid rate limits
+    const currentKey = this.getApiKey();
+    if (currentKey && !this.apiKey) {
+      this.apiKey = currentKey;
+    }
+    
+    if (!this.apiKey) {
+      throw new Error('API key required for passage processing');
+    }
+
+    // Define level-based constraints (relaxed length to ensure playability)
+    let wordLengthConstraint, difficultyGuidance;
+    if (level <= 2) {
+      wordLengthConstraint = "4-12 letters";
+      difficultyGuidance = "Select EASY vocabulary words - common, everyday words that most readers know.";
+    } else if (level <= 4) {
+      wordLengthConstraint = "4-12 letters";
+      difficultyGuidance = "Select MEDIUM difficulty words - mix of common and moderately challenging vocabulary.";
+    } else {
+      wordLengthConstraint = "4-14 letters";
+      difficultyGuidance = "Select CHALLENGING words - sophisticated vocabulary that requires strong reading skills.";
+    }
+
+    try {
+      // Add timeout controller to prevent aborted operations
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 15000); // 15 second timeout
+      
+      const headers = {
+        'Content-Type': 'application/json'
+      };
+      
+      // Only add auth headers for OpenRouter
+      if (!this.isLocalMode) {
+        headers['Authorization'] = `Bearer ${this.apiKey}`;
+        headers['HTTP-Referer'] = window.location.origin;
+        headers['X-Title'] = 'Cloze Reader';
+      }
+      
+      const response = await fetch(this.apiUrl, {
+        method: 'POST',
+        headers,
+        signal: controller.signal,
+        body: JSON.stringify({
+          model: this.primaryModel,  // Use Gemma-3-12b for batch processing
+          messages: [{
+            role: 'system',
+            content: 'Process passages for cloze exercises. Return ONLY a JSON object.'
+          }, {
+            role: 'user',
+            content: `Select ${blanksPerPassage} ${level <= 2 ? 'easy' : level <= 4 ? 'medium' : 'challenging'} words (${wordLengthConstraint}) from each passage.
+
+CRITICAL RULES:
+- ONLY select lowercase words (no capitalized words, no proper nouns)
+- ONLY select words from the MIDDLE or END of each passage (skip the first ~10 words)
+- Words must be ${wordLengthConstraint}
+- AVOID compound words like "courthouse" or "steamboat" - choose single, verifiable words with semantic inbetweenness
+- AVOID indexes, tables of contents, and capitalized content
+
+Passage 1 ("${book1.title}" by ${book1.author}):
+${passage1}
+
+Passage 2 ("${book2.title}" by ${book2.author}):
+${passage2}
+
+Return JSON: {"passage1": {"words": [${blanksPerPassage} words], "context": "one sentence about book"}, "passage2": {"words": [${blanksPerPassage} words], "context": "one sentence about book"}}`
+          }],
+          max_tokens: 800,
+          temperature: 0.5,
+          response_format: { type: "text" }
+        })
+      });
+
+      // Clear timeout on successful response
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        throw new Error(`API request failed: ${response.status}`);
+      }
+
+      const data = await response.json();
+      
+      // Check for error response
+      if (data.error) {
+        console.error('OpenRouter API error for batch processing:', data.error);
+        throw new Error(`OpenRouter API error: ${data.error.message || JSON.stringify(data.error)}`);
+      }
+      
+      
+      // Check if response has expected structure
+      if (!data.choices || !data.choices[0] || !data.choices[0].message) {
+        console.error('Invalid batch API response structure:', data);
+        console.error('Choices[0]:', data.choices?.[0]);
+        throw new Error('API response missing expected structure');
+      }
+      
+      // Extract content from response (handles reasoning mode variants)
+      let content = this._extractContentFromResponse(data);
+
+      if (!content) {
+        console.error('No content found in batch API response');
+        throw new Error('API response missing content');
+      }
+      
+      content = content.trim();
+      
+      try {
+        // Try to extract JSON from the response
+        // Sometimes the model returns JSON wrapped in markdown code blocks
+        const jsonMatch = content.match(/```json\s*([\s\S]*?)\s*```/) || content.match(/```\s*([\s\S]*?)\s*```/);
+        let jsonString = jsonMatch ? jsonMatch[1] : content;
+        
+        // Clean up the JSON string
+        jsonString = jsonString
+          .replace(/^\s*```json\s*/, '')
+          .replace(/\s*```\s*$/, '')
+          .trim();
+        
+        // Try to fix common JSON issues
+        // Fix trailing commas in arrays
+        jsonString = jsonString.replace(/,(\s*])/g, '$1');
+        
+        // Check for truncated strings (unterminated quotes)
+        const quoteCount = (jsonString.match(/"/g) || []).length;
+        if (quoteCount % 2 !== 0) {
+          // Add missing closing quote
+          jsonString += '"';
+        }
+        
+        // Check if JSON is truncated (missing closing braces)
+        const openBraces = (jsonString.match(/{/g) || []).length;
+        const closeBraces = (jsonString.match(/}/g) || []).length;
+        
+        if (openBraces > closeBraces) {
+          // Add missing closing braces
+          jsonString += '}'.repeat(openBraces - closeBraces);
+        }
+        
+        // Remove any trailing garbage after the last closing brace
+        const lastBrace = jsonString.lastIndexOf('}');
+        if (lastBrace !== -1 && lastBrace < jsonString.length - 1) {
+          jsonString = jsonString.substring(0, lastBrace + 1);
+        }
+        
+        const parsed = JSON.parse(jsonString);
+        
+        // Validate the structure
+        if (!parsed.passage1 || !parsed.passage2) {
+          console.error('Parsed response missing expected structure:', parsed);
+          throw new Error('Response missing passage1 or passage2');
+        }
+        
+        // Ensure words arrays exist and are arrays
+        if (!Array.isArray(parsed.passage1.words)) {
+          parsed.passage1.words = [];
+        }
+        if (!Array.isArray(parsed.passage2.words)) {
+          parsed.passage2.words = [];
+        }
+        
+        // Filter out empty strings from words arrays (caused by trailing commas)
+        parsed.passage1.words = parsed.passage1.words.filter(word => word && word.trim() !== '');
+        parsed.passage2.words = parsed.passage2.words.filter(word => word && word.trim() !== '');
+
+        // Validate words using helper methods
+        const map1 = this._createPassageWordMap(passage1);
+        const map2 = this._createPassageWordMap(passage2);
+        parsed.passage1.words = this._validateWords(parsed.passage1.words, map1, level, passage1);
+        parsed.passage2.words = this._validateWords(parsed.passage2.words, map2, level, passage2);
+
+        return parsed;
+      } catch (e) {
+        console.error('Failed to parse batch response:', e);
+        console.error('Raw content:', content);
+        
+        // Try to extract any usable data from the partial response
+        try {
+          // Extract passage contexts using regex
+          const context1Match = content.match(/"context":\s*"([^"]+)"/);
+          const context2Match = content.match(/"passage2"[\s\S]*?"context":\s*"([^"]+)"/);
+          
+          // Extract words arrays using regex
+          const words1Match = content.match(/"words":\s*\[([^\]]+)\]/);
+          const words2Match = content.match(/"passage2"[\s\S]*?"words":\s*\[([^\]]+)\]/);
+          
+          const extractWords = (match) => {
+            if (!match) return [];
+            try {
+              return JSON.parse(`[${match[1]}]`);
+            } catch {
+              return match[1].split(',').map(w => w.trim().replace(/['"]/g, ''));
+            }
+          };
+          
+          return {
+            passage1: { 
+              words: extractWords(words1Match), 
+              context: context1Match ? context1Match[1] : `From "${book1.title}" by ${book1.author}` 
+            },
+            passage2: { 
+              words: extractWords(words2Match), 
+              context: context2Match ? context2Match[1] : `From "${book2.title}" by ${book2.author}` 
+            }
+          };
+        } catch (extractError) {
+          console.error('Failed to extract partial data:', extractError);
+          throw new Error('Invalid API response format');
+        }
+      }
+    } catch (error) {
+      // Clear timeout in error case too
+      if (typeof timeoutId !== 'undefined') {
+        clearTimeout(timeoutId);
+      }
+      
+      // Handle specific abort error
+      if (error.name === 'AbortError') {
+        console.error('Batch processing timed out after 15 seconds');
+        throw new Error('Request timed out - falling back to sequential processing');
+      }
+      
+      console.error('Error processing passages:', error);
+      throw error;
+    }
+  }
+
+  async generateContextualization(title, author, passage) {
+
+    // Check for API key at runtime
+    const currentKey = this.getApiKey();
+    if (currentKey && !this.apiKey) {
+      this.apiKey = currentKey;
+    }
+
+
+    if (!this.apiKey) {
+      return `A passage from ${author}'s "${title}"`;
+    }
+
+    try {
+      return await this.retryRequest(async () => {
+        const response = await fetch(this.apiUrl, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${this.apiKey}`,
+            'HTTP-Referer': window.location.origin,
+            'X-Title': 'Cloze Reader'
+          },
+          body: JSON.stringify({
+            model: this.primaryModel,  // Use Gemma-3-27b for contextualization
+            messages: [{
+              role: 'system',
+              content: 'Provide a single contextual insight about the passage: historical context, literary technique, thematic observation, or relevant fact. Be specific and direct. Maximum 25 words. Do not use dashes or em-dashes. Output ONLY the insight itself with no preamble, acknowledgments, or meta-commentary.'
+            }, {
+              role: 'user',
+              content: `From "${title}" by ${author}:\n\n${passage}`
+            }],
+            max_tokens: 150,
+            temperature: 0.7,
+            response_format: { type: "text" }
+          })
+        });
+
+        if (!response.ok) {
+          const errorText = await response.text();
+          console.error('Contextualization API error:', response.status, errorText);
+          throw new Error(`API request failed: ${response.status}`);
+        }
+
+        const data = await response.json();
+        
+        // Check for OpenRouter error response
+        if (data.error) {
+          console.error('OpenRouter API error for contextualization:', data.error);
+          throw new Error(`OpenRouter API error: ${data.error.message || JSON.stringify(data.error)}`);
+        }
+        
+        
+        // Check if response has expected structure
+        if (!data.choices || !data.choices[0] || !data.choices[0].message) {
+          console.error('Invalid contextualization API response structure:', data);
+          console.error('Choices[0]:', data.choices?.[0]);
+          throw new Error('API response missing expected structure');
+        }
+        
+        // Extract content from response (handles reasoning mode variants)
+        let content = this._extractContentFromResponse(data);
+
+        if (!content) {
+          console.error('No content found in context API response');
+          throw new Error('API response missing content');
+        }
+
+        // Clean up AI response artifacts
+        content = this._cleanupAIResponse(content.trim());
+
+        return content;
+      });
+    } catch (error) {
+      console.error('Error getting contextualization:', error);
+      return `A passage from ${author}'s "${title}"`;
+    }
+  }
+
+  cleanLocalLLMResponse(content) {
+    // Remove common artifacts from local LLM responses
+    return content
+      .replace(/\["?/g, '')       // Remove opening bracket and quote
+      .replace(/"?\]/g, '')       // Remove closing quote and bracket  
+      .replace(/^[>"|']+/g, '')   // Remove leading > or quotes
+      .replace(/[>"|']+$/g, '')   // Remove trailing > or quotes
+      .replace(/\\n/g, ' ')       // Replace escaped newlines
+      .trim();
+  }
+}
+
+export { OpenRouterService as AIService };

src/analyticsService.js

@@ -0,0 +1,350 @@
+/**
+ * Analytics Service
+ * Frontend client for tracking passage attempts, word difficulty, and hint usage.
+ * Sends summary data to backend Redis analytics service.
+ */
+
+export class AnalyticsService {
+  constructor() {
+    // Generate unique session ID for this browser session
+    this.sessionId = this._generateUUID();
+
+    // Current passage tracking state
+    this.currentPassage = null;
+
+    // Base URL - uses same origin as the app
+    this.baseUrl = window.location.origin;
+
+  }
+
+  /**
+   * Generate a UUID v4
+   */
+  _generateUUID() {
+    // Use crypto.randomUUID if available, otherwise fallback
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+      return crypto.randomUUID();
+    }
+    // Fallback for older browsers
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+      const r = Math.random() * 16 | 0;
+      const v = c === 'x' ? r : (r & 0x3 | 0x8);
+      return v.toString(16);
+    });
+  }
+
+  /**
+   * Start tracking a new passage attempt.
+   * Call this when a new passage is loaded.
+   *
+   * @param {Object} book - Book info {title, author}
+   * @param {Array} blanks - Array of blank objects with originalWord
+   * @param {number} level - Current game level
+   * @param {number} round - Current round number
+   */
+  startPassage(book, blanks, level, round) {
+    this.currentPassage = {
+      passageId: this._generateUUID(),
+      sessionId: this.sessionId,
+      bookTitle: book?.title || 'Unknown',
+      bookAuthor: book?.author || 'Unknown',
+      level: level || 1,
+      round: round || 1,
+      words: blanks.map(blank => ({
+        word: blank.originalWord || '',
+        length: (blank.originalWord || '').length,
+        attemptsToCorrect: 0,
+        hintsUsed: [],
+        finalCorrect: false
+      })),
+      startTime: Date.now()
+    };
+
+    console.debug('📊 Analytics: Started passage', {
+      passageId: this.currentPassage.passageId,
+      book: this.currentPassage.bookTitle,
+      blanks: this.currentPassage.words.length,
+      level,
+      round
+    });
+  }
+
+  /**
+   * Record an attempt on a specific word.
+   * Call this each time the user submits an answer for a blank.
+   *
+   * @param {number} blankIndex - Index of the blank in the passage
+   * @param {boolean} correct - Whether the attempt was correct
+   */
+  recordAttempt(blankIndex, correct) {
+    if (!this.currentPassage) {
+      console.warn('📊 Analytics: No active passage to record attempt');
+      return;
+    }
+
+    if (blankIndex < 0 || blankIndex >= this.currentPassage.words.length) {
+      console.warn('📊 Analytics: Invalid blank index', blankIndex);
+      return;
+    }
+
+    const wordData = this.currentPassage.words[blankIndex];
+    wordData.attemptsToCorrect++;
+
+    if (correct) {
+      wordData.finalCorrect = true;
+    }
+
+    console.debug('📊 Analytics: Recorded attempt', {
+      word: wordData.word,
+      attempt: wordData.attemptsToCorrect,
+      correct
+    });
+  }
+
+  /**
+   * Record all attempts at once (batch mode).
+   * Use when results come in as an array.
+   *
+   * @param {Array} results - Array of {blankIndex, isCorrect} objects
+   */
+  recordAttemptsBatch(results) {
+    if (!this.currentPassage) {
+      console.warn('📊 Analytics: No active passage to record attempts');
+      return;
+    }
+
+    results.forEach(result => {
+      if (result.blankIndex !== undefined) {
+        this.recordAttempt(result.blankIndex, result.isCorrect);
+      }
+    });
+  }
+
+  /**
+   * Record a hint request for a specific word.
+   *
+   * @param {number} blankIndex - Index of the blank
+   * @param {string} hintType - Type of hint requested (e.g., 'part_of_speech', 'synonym', 'first_letter')
+   */
+  recordHint(blankIndex, hintType) {
+    if (!this.currentPassage) {
+      console.warn('📊 Analytics: No active passage to record hint');
+      return;
+    }
+
+    if (blankIndex < 0 || blankIndex >= this.currentPassage.words.length) {
+      console.warn('📊 Analytics: Invalid blank index for hint', blankIndex);
+      return;
+    }
+
+    const wordData = this.currentPassage.words[blankIndex];
+    wordData.hintsUsed.push(hintType || 'unknown');
+
+    console.debug('📊 Analytics: Recorded hint', {
+      word: wordData.word,
+      hintType,
+      totalHints: wordData.hintsUsed.length
+    });
+  }
+
+  /**
+   * Complete the current passage and send analytics to backend.
+   *
+   * @param {boolean} passed - Whether the user passed the passage
+   * @returns {Promise<Object>} - Response from analytics API
+   */
+  async completePassage(passed) {
+    if (!this.currentPassage) {
+      console.warn('📊 Analytics: No active passage to complete');
+      return { success: false, message: 'No active passage' };
+    }
+
+    // Calculate summary statistics
+    const totalBlanks = this.currentPassage.words.length;
+    const correctOnFirstTry = this.currentPassage.words.filter(
+      w => w.attemptsToCorrect === 1 && w.finalCorrect
+    ).length;
+    const totalHintsUsed = this.currentPassage.words.reduce(
+      (sum, w) => sum + w.hintsUsed.length, 0
+    );
+
+    const data = {
+      passageId: this.currentPassage.passageId,
+      sessionId: this.currentPassage.sessionId,
+      bookTitle: this.currentPassage.bookTitle,
+      bookAuthor: this.currentPassage.bookAuthor,
+      level: this.currentPassage.level,
+      round: this.currentPassage.round,
+      words: this.currentPassage.words,
+      totalBlanks,
+      correctOnFirstTry,
+      totalHintsUsed,
+      passed,
+      timestamp: new Date().toISOString()
+    };
+
+    console.debug('📊 Analytics: Completing passage', {
+      passageId: data.passageId,
+      passed,
+      correctOnFirstTry,
+      totalBlanks,
+      totalHintsUsed
+    });
+
+    // Clear current passage state
+    this.currentPassage = null;
+
+    // Send to backend
+    try {
+      const response = await fetch(`${this.baseUrl}/api/analytics/passage`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(data)
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      const result = await response.json();
+      return result;
+
+    } catch (error) {
+      // Don't throw - analytics failure shouldn't break the game
+      console.warn('📊 Analytics: Failed to send (non-critical)', error.message);
+      return { success: false, message: error.message };
+    }
+  }
+
+  /**
+   * Cancel tracking for current passage without sending.
+   * Use if the user abandons a passage mid-attempt.
+   */
+  cancelPassage() {
+    if (this.currentPassage) {
+      console.debug('📊 Analytics: Cancelled passage', {
+        passageId: this.currentPassage.passageId
+      });
+      this.currentPassage = null;
+    }
+  }
+
+  /**
+   * Check if there's an active passage being tracked.
+   * @returns {boolean}
+   */
+  isTrackingPassage() {
+    return this.currentPassage !== null;
+  }
+
+  /**
+   * Get current passage statistics (for UI display).
+   * @returns {Object|null}
+   */
+  getCurrentStats() {
+    if (!this.currentPassage) return null;
+
+    const totalBlanks = this.currentPassage.words.length;
+    const correctOnFirstTry = this.currentPassage.words.filter(
+      w => w.attemptsToCorrect === 1 && w.finalCorrect
+    ).length;
+    const totalCorrect = this.currentPassage.words.filter(w => w.finalCorrect).length;
+    const totalHintsUsed = this.currentPassage.words.reduce(
+      (sum, w) => sum + w.hintsUsed.length, 0
+    );
+
+    return {
+      passageId: this.currentPassage.passageId,
+      bookTitle: this.currentPassage.bookTitle,
+      level: this.currentPassage.level,
+      round: this.currentPassage.round,
+      totalBlanks,
+      correctOnFirstTry,
+      totalCorrect,
+      totalHintsUsed,
+      words: this.currentPassage.words.map(w => ({
+        word: w.word,
+        attempts: w.attemptsToCorrect,
+        hintsUsed: w.hintsUsed.length,
+        correct: w.finalCorrect
+      }))
+    };
+  }
+
+  // ===== ADMIN API METHODS =====
+
+  /**
+   * Get analytics summary (admin dashboard data).
+   * @returns {Promise<Object>}
+   */
+  async getSummary() {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/analytics/summary`);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+      return await response.json();
+    } catch (error) {
+      console.error('📊 Analytics: Failed to get summary', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get recent passage attempts.
+   * @param {number} count - Number of entries (max 200)
+   * @returns {Promise<Object>}
+   */
+  async getRecentPassages(count = 50) {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/analytics/recent?count=${count}`);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+      return await response.json();
+    } catch (error) {
+      console.error('📊 Analytics: Failed to get recent passages', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Export all analytics data.
+   * @returns {Promise<Object>}
+   */
+  async exportAll() {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/analytics/export`);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+      return await response.json();
+    } catch (error) {
+      console.error('📊 Analytics: Failed to export', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get statistics for a specific word.
+   * @param {string} word
+   * @returns {Promise<Object>}
+   */
+  async getWordStats(word) {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/analytics/word/${encodeURIComponent(word)}`);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+      return await response.json();
+    } catch (error) {
+      console.error('📊 Analytics: Failed to get word stats', error);
+      throw error;
+    }
+  }
+}
+
+// Export singleton instance
+export const analyticsService = new AnalyticsService();

src/app.js

@@ -0,0 +1,592 @@
+// Main application entry point
+import ClozeGame from './clozeGameEngine.js';
+import ChatUI from './chatInterface.js';
+import WelcomeOverlay from './welcomeOverlay.js';
+import { LeaderboardUI } from './leaderboardUI.js';
+import { analyticsService } from './analyticsService.js';
+
+class App {
+  constructor() {
+    this.game = new ClozeGame();
+    this.chatUI = new ChatUI(this.game);
+    this.welcomeOverlay = new WelcomeOverlay();
+    this.leaderboardUI = new LeaderboardUI(this.game.leaderboardService);
+    this.analytics = analyticsService;
+    // Prevent double-trigger on rapid Skip clicks
+    this._skipInProgress = false;
+    this.lastRevealWasSkip = false; // Controls reveal styling after skip
+    this.elements = {
+      loading: document.getElementById('loading'),
+      gameArea: document.getElementById('game-area'),
+      stickyControls: document.getElementById('sticky-controls'),
+      bookInfo: document.getElementById('book-info'),
+      roundInfo: document.getElementById('round-info'),
+      streakInfo: document.getElementById('streak-info'),
+      contextualization: document.getElementById('contextualization'),
+      passageContent: document.getElementById('passage-content'),
+      hintsSection: document.getElementById('hints-section'),
+      hintsList: document.getElementById('hints-list'),
+      skipBtn: document.getElementById('skip-btn'),
+      submitBtn: document.getElementById('submit-btn'),
+      nextBtn: document.getElementById('next-btn'),
+      hintBtn: document.getElementById('hint-btn'),
+      result: document.getElementById('result'),
+      leaderboardBtn: document.getElementById('leaderboard-btn')
+    };
+
+    this.currentResults = null;
+    this.isRetrying = false; // Track if we're in retry mode
+    this.setupEventListeners();
+  }
+
+  async initialize() {
+    try {
+      this.showLoading(true);
+      await this.game.initialize();
+      await this.startNewGame();
+      this.showLoading(false);
+    } catch (error) {
+      console.error('Failed to initialize app:', error);
+      this.showError('Failed to load the game. Please refresh and try again.');
+    }
+  }
+
+  setupEventListeners() {
+    if (this.elements.skipBtn) {
+      this.elements.skipBtn.addEventListener('click', () => {
+        // Ensure any unexpected async errors are surfaced but don’t crash UI
+        Promise.resolve(this.handleSkip()).catch(err => console.error('handleSkip (event) ERROR:', err));
+      });
+    } else {
+    }
+    this.elements.submitBtn.addEventListener('click', () => this.handleSubmit());
+    this.elements.nextBtn.addEventListener('click', () => this.handleNext());
+    this.elements.hintBtn.addEventListener('click', () => this.toggleHints());
+
+    // Leaderboard button
+    if (this.elements.leaderboardBtn) {
+      this.elements.leaderboardBtn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        this.leaderboardUI.show();
+      });
+    }
+
+    // Note: Enter key handling is done per-input in setupInputListeners()
+  }
+
+  async startNewGame() {
+    try {
+      const roundData = await this.game.startNewRound();
+      this.displayRound(roundData);
+      this.resetUI();
+    } catch (error) {
+      console.error('Error starting new game:', error);
+      this.showError('Could not load a new passage. Please try again.');
+    }
+  }
+
+  displayRound(roundData) {
+    // Start analytics tracking for this passage
+    this.analytics.startPassage(
+      { title: roundData.title, author: roundData.author },
+      roundData.blanks,
+      this.game.currentLevel,
+      this.game.currentRound
+    );
+
+    // Reset retry state
+    this.isRetrying = false;
+
+    // Show book information
+    this.elements.bookInfo.innerHTML = `
+      <strong>${roundData.title}</strong> by ${roundData.author}
+    `;
+
+    // Show level information
+    const blanksCount = roundData.blanks.length;
+    const levelInfo = `Level ${this.game.currentLevel} • ${blanksCount} blank${blanksCount > 1 ? 's' : ''}`;
+
+    this.elements.roundInfo.innerHTML = levelInfo;
+
+    // Update streak display
+    this.updateStreakDisplay();
+
+    // Show contextualization from AI agent
+    this.elements.contextualization.innerHTML = `
+      <div class="flex items-start gap-2">
+        <span class="text-blue-600">📜</span>
+        <span>${roundData.contextualization || 'Loading context...'}</span>
+      </div>
+    `;
+
+    // Render the cloze text with input fields and chat buttons
+    const clozeHtml = this.game.renderClozeTextWithChat();
+    this.elements.passageContent.innerHTML = `<p>${clozeHtml}</p>`;
+
+    // Store hints for later display
+    this.currentHints = roundData.hints || [];
+    this.populateHints();
+    
+    // Hide hints initially
+    this.elements.hintsSection.style.display = 'none';
+
+    // Set up input field listeners
+    this.setupInputListeners();
+    
+    // Set up chat buttons
+    this.chatUI.setupChatButtons();
+  }
+
+  setupInputListeners() {
+    const inputs = this.elements.passageContent.querySelectorAll('.cloze-input');
+    
+    inputs.forEach((input, index) => {
+      input.addEventListener('input', () => {
+        // Remove any previous styling
+        input.classList.remove('correct', 'incorrect');
+        this.updateSubmitButton();
+      });
+      
+      input.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter') {
+          e.preventDefault();
+          
+          // Move to next input or submit if last
+          const nextInput = inputs[index + 1];
+          if (nextInput) {
+            nextInput.focus();
+          } else {
+            this.handleSubmit();
+          }
+        }
+      });
+    });
+
+    // Focus first input
+    if (inputs.length > 0) {
+      inputs[0].focus();
+    }
+  }
+
+  updateSubmitButton() {
+    const inputs = this.elements.passageContent.querySelectorAll('.cloze-input');
+    // Only check non-disabled (non-locked) inputs
+    const nonLockedInputs = Array.from(inputs).filter(input => !input.disabled);
+    const allFilled = nonLockedInputs.every(input => input.value.trim() !== '');
+    this.elements.submitBtn.disabled = !allFilled || nonLockedInputs.length === 0;
+  }
+
+  handleSubmit() {
+    const inputs = this.elements.passageContent.querySelectorAll('.cloze-input');
+    const answers = Array.from(inputs).map(input => input.value.trim());
+
+    // Check if all non-locked fields are filled
+    const nonLockedInputs = Array.from(inputs).filter((input, index) => !this.game.isBlankLocked(index));
+    const nonLockedAnswers = nonLockedInputs.map(input => input.value.trim());
+
+    if (nonLockedAnswers.some(answer => answer === '')) {
+      alert('Please fill in all blanks before submitting.');
+      return;
+    }
+
+    // Submit answers and get results
+    this.currentResults = this.game.submitAnswers(answers);
+
+    // Record attempts in analytics only for blanks attempted in this submission
+    this.currentResults.results.forEach(result => {
+      if (result.attemptedThisRound) {
+        this.analytics.recordAttempt(result.blankIndex, result.isCorrect);
+      }
+    });
+
+    // Handle retry vs final display
+    if (this.currentResults.canRetry) {
+      this.displayRetryUI(this.currentResults);
+    } else {
+      // Final submission - send analytics
+      this.sendAnalytics(this.currentResults.passed);
+      this.displayResults(this.currentResults);
+    }
+  }
+
+  /**
+   * Display UI for retry mode - lock correct answers, highlight wrong ones
+   */
+  displayRetryUI(results) {
+    this.isRetrying = true;
+    // Ensure skip can be used during this retry cycle
+    this._skipInProgress = false;
+    const inputs = this.elements.passageContent.querySelectorAll('.cloze-input');
+
+    results.results.forEach((result, index) => {
+      const input = inputs[index];
+      if (!input) return;
+
+      if (result.isCorrect || result.isLocked) {
+        // Lock correct answers - show green background and disable
+        input.classList.add('correct');
+        input.classList.remove('incorrect');
+        input.style.backgroundColor = '#dcfce7'; // Light green
+        input.style.borderColor = '#16a34a';
+        input.disabled = true;
+        input.value = result.correctAnswer;
+      } else {
+        // Highlight wrong answers - show red border, keep editable
+        input.classList.add('incorrect');
+        input.classList.remove('correct');
+        input.style.backgroundColor = '#fef2f2'; // Light red
+        input.style.borderColor = '#dc2626';
+        input.disabled = false;
+        // Clear wrong answer for retry
+        input.value = '';
+      }
+    });
+
+    // Update result message
+    this.elements.result.textContent = results.feedbackText;
+    this.elements.result.className = 'mt-4 text-center font-semibold text-amber-600';
+
+    // Update submit button text and show skip button
+    this.elements.submitBtn.textContent = 'Try Again';
+    this.elements.submitBtn.disabled = true; // Will be enabled when user types
+    if (this.elements.skipBtn) {
+      this.elements.skipBtn.classList.remove('hidden');
+      this.elements.skipBtn.disabled = false; // Ensure skip is clickable on retries
+      this.elements.skipBtn.removeAttribute('disabled');
+      this.elements.skipBtn.setAttribute('aria-disabled', 'false');
+    } else {
+    }
+
+    // Focus first wrong input
+    const firstWrongInput = Array.from(inputs).find(
+      (input, index) => results.retryableIndices.includes(index)
+    );
+    if (firstWrongInput) {
+      firstWrongInput.focus();
+    }
+
+    // Don't update streak display during retry - wait for final result
+  }
+
+  /**
+   * Handle skip button - skip passage and move to next
+   */
+  async handleSkip() {
+    console.log('handleSkip: START - v2');
+
+    try {
+      // Debounce multiple rapid clicks
+      if (this._skipInProgress) {
+        console.warn('handleSkip: already in progress, ignoring');
+        return;
+      }
+      this._skipInProgress = true;
+      if (this.elements?.skipBtn) {
+        this.elements.skipBtn.disabled = true;
+      }
+      // Early exit if no game or blanks
+      if (!this.game || !Array.isArray(this.game.blanks) || this.game.blanks.length === 0) {
+        console.warn('handleSkip: No game/blanks, going to next passage');
+        this.handleNext();
+        return;
+      }
+
+      // Send analytics as failed (non-blocking)
+      console.log('📊 Sending analytics (skip - passage failed)...');
+      this.sendAnalytics(false).catch(err => console.warn('📊 Analytics (skip) failed non-critically:', err));
+
+      // Use engine to force-complete this passage to ensure consistent results/state
+      const finalResults = this.game.forceCompletePassage();
+      console.log('handleSkip: forceCompletePassage results:', finalResults);
+
+      // Show the results (which reveals correct answers)
+      console.log('handleSkip: calling displayResults');
+      this.lastRevealWasSkip = true;
+      this.displayResults(finalResults);
+      console.log('handleSkip: displayResults completed');
+
+      // Hide skip button
+      this.elements.skipBtn.classList.add('hidden');
+
+      // Hide submit button
+      this.elements.submitBtn.style.display = 'none';
+
+      // Show the next button immediately after skip
+      this.elements.nextBtn.classList.remove('hidden');
+    } catch (error) {
+      console.error('handleSkip ERROR:', error);
+      // Fallback: attempt to force-complete and reveal, or at least enable Next
+      try {
+        if (this.game?.forceCompletePassage) {
+          const fallbackResults = this.game.forceCompletePassage();
+          this.lastRevealWasSkip = true;
+          this.displayResults(fallbackResults);
+        } else {
+          this.elements.nextBtn.classList.remove('hidden');
+        }
+      } catch (fallbackError) {
+        console.warn('handleSkip fallback failed; showing Next button:', fallbackError);
+        this.elements.nextBtn.classList.remove('hidden');
+      }
+    } finally {
+      // Reset guard so future rounds can skip normally
+      this._skipInProgress = false;
+    }
+  }
+
+  /**
+   * Send analytics data to backend
+   */
+  async sendAnalytics(passed) {
+    try {
+      await this.analytics.completePassage(passed);
+    } catch (error) {
+      // Non-critical - don't break gameplay
+      console.warn('📊 Analytics send failed (non-critical):', error);
+    }
+  }
+
+  displayResults(results) {
+    let message = `Score: ${results.correct}/${results.total}`;
+
+    if (results.passed) {
+      // Check if level was just advanced
+      if (results.justAdvancedLevel) {
+        message += ` - Level ${results.currentLevel} unlocked!`;
+
+        // Check for milestone notification (every 5 levels)
+        if (results.currentLevel % 5 === 0) {
+          this.leaderboardUI.showMilestoneNotification(results.currentLevel);
+        }
+
+        // Check for high score
+        this.checkForHighScore();
+      } else {
+        message += ` - Passed!`;
+      }
+      this.elements.result.className = 'mt-4 text-center font-semibold text-green-600';
+    } else {
+      message += ` - Failed (need ${results.requiredCorrect} correct)`;
+      this.elements.result.className = 'mt-4 text-center font-semibold text-red-600';
+    }
+
+    this.elements.result.textContent = message;
+
+    // Always reveal answers at the end of each round
+    this.revealAnswersInPlace(results.results);
+
+    // Show next button and hide submit/skip buttons
+    this.elements.submitBtn.style.display = 'none';
+    if (this.elements.skipBtn) {
+      this.elements.skipBtn.classList.add('hidden');
+    }
+    this.elements.nextBtn.classList.remove('hidden');
+
+    // Update streak display after processing results
+    this.updateStreakDisplay();
+  }
+
+  updateStreakDisplay() {
+    const stats = this.game.leaderboardService.getPlayerStats();
+    const currentStreak = stats.currentStreak;
+    
+    if (currentStreak > 0) {
+      this.elements.streakInfo.innerHTML = `🔥 ${currentStreak} streak`;
+      this.elements.streakInfo.classList.remove('hidden');
+    } else {
+      this.elements.streakInfo.classList.add('hidden');
+    }
+  }
+
+  highlightAnswers(results) {
+    const inputs = this.elements.passageContent.querySelectorAll('.cloze-input');
+    
+    results.forEach((result, index) => {
+      const input = inputs[index];
+      if (input) {
+        if (result.isCorrect) {
+          input.classList.add('correct');
+        } else {
+          input.classList.add('incorrect');
+          // Show correct answer as placeholder or title
+          input.title = `Correct answer: ${result.correctAnswer}`;
+        }
+        input.disabled = true;
+      }
+    });
+  }
+
+  async handleNext() {
+    try {
+      // Show loading immediately with specific message
+      this.showLoading(true, 'Loading passages...');
+
+      // Clear chat history when starting new round
+      this.chatUI.clearChatHistory();
+
+      // Always show loading for at least 1 second for smooth UX
+      const startTime = Date.now();
+
+      // Load next round
+      const roundData = await this.game.nextRound();
+
+      // Ensure loading is shown for at least half a second
+      const elapsedTime = Date.now() - startTime;
+      if (elapsedTime < 500) {
+        await new Promise(resolve => setTimeout(resolve, 500 - elapsedTime));
+      }
+
+      this.displayRound(roundData);
+      this.resetUI();
+      this.showLoading(false);
+    } catch (error) {
+      console.error('Error loading next round:', error);
+      this.showError('Could not load next round. Please try again.');
+    }
+  }
+
+  // Reveal correct answers immediately after submission
+  revealAnswersInPlace(results) {
+    const inputs = this.elements.passageContent.querySelectorAll('.cloze-input');
+    // Remove any previously rendered external labels to avoid duplicates
+    const existingLabels = this.elements.passageContent.querySelectorAll('.correct-answer-reveal');
+    existingLabels.forEach(node => node.remove());
+
+    results.forEach((result, index) => {
+      const input = inputs[index];
+      if (input) {
+        // Always set the correct answer in the input
+        input.value = result.correctAnswer;
+
+        if (this.lastRevealWasSkip) {
+          // Neutral reveal on skip: no red/green styling
+          input.classList.remove('correct', 'incorrect');
+          input.style.backgroundColor = '';
+          input.style.borderColor = '';
+        } else {
+          // Normal reveal with visual feedback
+          if (result.isCorrect) {
+            input.classList.add('correct');
+            input.classList.remove('incorrect');
+            input.style.backgroundColor = '#dcfce7'; // Light green
+            input.style.borderColor = '#16a34a'; // Green border
+          } else {
+            input.classList.add('incorrect');
+            input.classList.remove('correct');
+            input.style.backgroundColor = '#fef2f2'; // Light red
+            input.style.borderColor = '#dc2626'; // Red border
+          }
+        }
+        input.disabled = true;
+      }
+    });
+  }
+
+  populateHints() {
+    if (!this.currentHints || this.currentHints.length === 0) {
+      this.elements.hintsList.innerHTML = '<div class="text-yellow-600">No hints available for this passage.</div>';
+      return;
+    }
+
+    const hintsHtml = this.currentHints.map((hintData, index) => 
+      `<div class="flex items-start gap-2">
+        <span class="font-semibold text-yellow-800">${index + 1}.</span>
+        <span>${hintData.hint}</span>
+      </div>`
+    ).join('');
+    
+    this.elements.hintsList.innerHTML = hintsHtml;
+  }
+
+  toggleHints() {
+    const isHidden = this.elements.hintsSection.style.display === 'none';
+    this.elements.hintsSection.style.display = isHidden ? 'block' : 'none';
+    this.elements.hintBtn.textContent = isHidden ? 'Hide Hints' : 'Show Hints';
+  }
+
+  resetUI() {
+    this.elements.result.textContent = '';
+    this.elements.submitBtn.style.display = 'inline-block';
+    this.elements.submitBtn.disabled = true;
+    this.elements.submitBtn.textContent = 'Submit'; // Reset button text
+    if (this.elements.skipBtn) {
+      this.elements.skipBtn.classList.add('hidden'); // Hide skip button
+      this.elements.skipBtn.disabled = false; // Re-enable for new round
+      this.elements.skipBtn.removeAttribute('disabled');
+      this.elements.skipBtn.setAttribute('aria-disabled', 'false');
+    }
+    this.elements.nextBtn.classList.add('hidden');
+    this.elements.hintsSection.style.display = 'none';
+    this.elements.hintBtn.textContent = 'Show Hints';
+    this.currentResults = null;
+    this.currentHints = [];
+    this.isRetrying = false; // Reset retry state
+    this._skipInProgress = false; // Allow skip again in new round
+    this.lastRevealWasSkip = false;
+  }
+
+  showLoading(show, message = 'Loading passages...') {
+    if (show) {
+      this.elements.loading.innerHTML = `
+        <div class="text-center py-8">
+          <p class="text-lg loading-text">${message}</p>
+        </div>
+      `;
+      this.elements.loading.classList.remove('hidden');
+      this.elements.gameArea.classList.add('hidden');
+      this.elements.stickyControls.classList.add('hidden');
+    } else {
+      this.elements.loading.classList.add('hidden');
+      this.elements.gameArea.classList.remove('hidden');
+      this.elements.stickyControls.classList.remove('hidden');
+    }
+  }
+
+  showError(message) {
+    this.elements.loading.innerHTML = `
+      <div class="text-center py-8">
+        <p class="text-lg text-red-600 mb-4">${message}</p>
+        <button onclick="location.reload()" class="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700">
+          Reload
+        </button>
+      </div>
+    `;
+    this.elements.loading.classList.remove('hidden');
+    this.elements.gameArea.classList.add('hidden');
+  }
+
+  checkForHighScore() {
+    // Check if current score qualifies for leaderboard
+    if (this.game.checkForHighScore()) {
+      const rank = this.game.getHighScoreRank();
+      const stats = this.game.leaderboardService.getStats();
+
+      // Always show initials entry when achieving a high score
+      // Pre-fills with previous initials if available, allowing changes
+      this.leaderboardUI.showInitialsEntry(
+        stats.highestLevel,
+        stats.roundAtHighestLevel,
+        rank,
+        (initials) => {
+          // Save to leaderboard
+          const finalRank = this.game.addToLeaderboard(initials);
+        }
+      );
+    }
+  }
+}
+
+// Initialize the app when DOM is loaded
+document.addEventListener('DOMContentLoaded', () => {
+  const app = new App();
+  
+  // Show welcome overlay immediately before any loading
+  app.welcomeOverlay.show();
+  
+  app.initialize();
+  
+  // Expose API key setter for browser console
+  window.setOpenRouterKey = (key) => {
+    app.game.chatService.aiService.setApiKey(key);
+  };
+});

src/bookDataService.js

@@ -0,0 +1,631 @@
+// Hugging Face Project Gutenberg Dataset Service
+class HuggingFaceDatasetService {
+  constructor() {
+    // Use Hugging Face Datasets API for streaming
+    this.datasetName = 'manu/project_gutenberg';
+    this.apiBase = 'https://datasets-server.huggingface.co';
+    this.proxyBase = '/api/books'; // server-side proxy for CORS-safe HF access
+    this.hfConfig = 'default';
+    this.hfSplit = 'en';
+    this.books = [];
+    this.isLoaded = false;
+    this.streamingEnabled = false;
+    this.cache = new Map();
+    this.preloadedBooks = [];
+    this.usedBooks = new Set(); // Track books used this session
+  }
+
+  // Local fallback books for when HF streaming is unavailable
+  getSampleBooks() {
+    return [
+      {
+        id: 1,
+        title: "Pride and Prejudice",
+        author: "Jane Austen",
+        year: 1813,
+        text: "It is a truth universally acknowledged, that a single man in possession of a good fortune, must be in want of a wife. However little known the feelings or views of such a man may be on his first entering a neighbourhood, this truth is so well fixed in the minds of the surrounding families, that he is considered the rightful property of some one or other of their daughters. \"My dear Mr. Bennet,\" said his lady to him one day, \"have you heard that Netherfield Park is let at last?\" Mr. Bennet replied that he had not. \"But it is,\" returned she; \"for Mrs. Long has just been here, and she told me all about it.\" Mr. Bennet made no answer. \"Do you not want to know who has taken it?\" cried his wife impatiently. \"You want to tell me, and I have no objection to hearing it.\" This was invitation enough."
+      },
+      {
+        id: 2,
+        title: "The Adventures of Tom Sawyer",
+        author: "Mark Twain",
+        year: 1876,
+        text: "\"Tom!\" No answer. \"Tom!\" No answer. \"What's gone with that boy, I wonder? You TOM!\" No answer. The old lady pulled her spectacles down and looked over them about the room; then she put them up and looked out under them. She seldom or never looked through them for so small a thing as a boy; they were her state pair, the pride of her heart, and were built for \"style,\" not service--she could have seen through a pair of stove-lids just as well. She looked perplexed for a moment, and then said, not fiercely, but still loud enough for the furniture to hear: \"Well, I lay if I get hold of you I'll--\""
+      },
+      {
+        id: 3,
+        title: "Great Expectations",
+        author: "Charles Dickens",
+        year: 1861,
+        text: "My father's family name being Pirrip, and my Christian name Philip, my infant tongue could make of both names nothing longer or more explicit than Pip. So, I called myself Pip, and came to be called Pip. I give Pirrip as my father's family name, on the authority of his tombstone and my sister,--Mrs. Joe Gargery, who married the blacksmith. As I never saw my father or my mother, and never saw any likeness of them (for their days were long before the days of photographs), my first fancies regarding what they were like were unreasonably derived from their tombstones."
+      },
+      {
+        id: 4,
+        title: "Alice's Adventures in Wonderland",
+        author: "Lewis Carroll",
+        year: 1865,
+        text: "Alice was beginning to get very tired of sitting by her sister on the bank, and of having nothing to do: once or twice she had peeped into the book her sister was reading, but it had no pictures or conversations in it, 'and what is the use of a book,' thought Alice 'without pictures or conversation?' So she was considering in her own mind (as well as she could, for the hot day made her feel very sleepy and stupid), whether the pleasure of making a daisy-chain would be worth the trouble of getting up and picking the daisies, when suddenly a White Rabbit with pink eyes ran close by her."
+      },
+      {
+        id: 5,
+        title: "The Picture of Dorian Gray",
+        author: "Oscar Wilde",
+        year: 1890,
+        text: "The studio was filled with the rich odour of roses, and when the strong summer wind stirred, amidst the trees of the garden, there came through the open door the heavy scent of the lilac, or the more delicate perfume of the pink-flowering thorn. From the corner of the divan of Persian saddle-bags on which he was lying, smoking, as was his custom, innumerable cigarettes, Lord Henry Wotton could just catch the gleam of the honey-sweet and honey-coloured blossoms of a laburnum, whose tremulous branches seemed hardly able to bear the burden of a beauty so flamelike as theirs."
+      },
+      {
+        id: 6,
+        title: "Moby Dick",
+        author: "Herman Melville",
+        year: 1851,
+        text: "Call me Ishmael. Some years ago—never mind how long precisely—having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world. It is a way I have of driving off the spleen and regulating the circulation. Whenever I find myself growing grim about the mouth; whenever it is a damp, drizzly November in my soul; whenever I find myself involuntarily pausing before coffin warehouses, and bringing up the rear of every funeral I meet; and especially whenever my hypos get such an upper hand of me, that it requires a strong moral principle to prevent me from deliberately stepping into the street, and methodically knocking people's hats off—then, I account it high time to get to sea as soon as possible."
+      },
+      {
+        id: 7,
+        title: "Jane Eyre",
+        author: "Charlotte Bronte",
+        year: 1847,
+        text: "There was no possibility of taking a walk that day. We had been wandering, indeed, in the leafless shrubbery an hour in the morning; but since dinner (Mrs. Reed, when there was no company, dined early) the cold winter wind had brought with it clouds so sombre, and a rain so penetrating, that further out-door exercise was now out of the question. I was glad of it: I never liked long walks, especially on chilly afternoons: dreadful to me was the coming home in the raw twilight, with nipped fingers and toes, and a heart saddened by the chidings of Bessie, the nurse, and humbled by the consciousness of my physical inferiority to Eliza, John, and Georgiana Reed."
+      },
+      {
+        id: 8,
+        title: "The Count of Monte Cristo",
+        author: "Alexandre Dumas",
+        year: 1844,
+        text: "On the first Monday of February, 1815, the watchtower at Marseilles signaled the arrival of the three-master Pharaon from Smyrna, Trieste, and Naples. As was customary, the pilot immediately left the port and steered toward the château d'If to conduct the ship through the narrow passage that leads to the harbor. However, a young sailor of about nineteen or twenty years, standing on the ship's bow, had signaled the pilot even before he had time to ask the traditional questions that are exchanged between the pilot and the captain. The young man had already assumed command, being the ship's owner and captain."
+      },
+      {
+        id: 9,
+        title: "Wuthering Heights",
+        author: "Emily Bronte",
+        year: 1847,
+        text: "I have just returned from a visit to my landlord—the solitary neighbour that I shall be troubled with. This is certainly a beautiful country! In all England, I do not believe that I could have fixed on a situation so completely removed from the stir of society. A perfect misanthropist's Heaven: and Mr. Heathcliff and I are such a suitable pair to divide the desolation between us. A capital fellow! He little imagined how my heart warmed towards him when I beheld his black eyes withdraw so suspiciously under their brows, as I rode up, and when his fingers sheltered themselves, with a jealous resolution, still further in his waistcoat, as I announced my name."
+      },
+      {
+        id: 10,
+        title: "Frankenstein",
+        author: "Mary Shelley",
+        year: 1818,
+        text: "It was on a dreary night of November that I beheld the accomplishment of my toils. With an anxiety that almost amounted to agony, I collected the instruments of life around me, that I might infuse a spark of being into the lifeless thing that lay at my feet. It was already one in the morning; the rain pattered dismally against the panes, and my candle was nearly burnt out, when, by the glimmer of the half-extinguished light, I saw the dull yellow eye of the creature open; it breathed hard, and a convulsive motion agitated its limbs. How can I describe my emotions at this catastrophe, or how delineate the wretch whom with such infinite pains and care I had endeavoured to form?"
+      }
+    ];
+  }
+
+  async loadDataset() {
+    try {
+      // Try to connect to HF Datasets API
+      await this.initializeStreaming();
+      
+      if (this.streamingEnabled) {
+        // Preload some books for immediate access
+        await this.preloadBooks(2);
+        if (this.preloadedBooks.length > 0) {
+        } else {
+          // Fast fallback if HF is slow/unavailable
+          console.warn('HF streaming returned 0 books; falling back to local samples for this session');
+          this.streamingEnabled = false;
+          this.books = this.getSampleBooks();
+        }
+      } else {
+        // Fall back to local samples
+        this.books = this.getSampleBooks();
+      }
+      
+      this.isLoaded = true;
+      return this.books;
+    } catch (error) {
+      console.error('Error loading dataset:', error);
+      // Ensure we always have local fallback
+      this.books = this.getSampleBooks();
+      this.isLoaded = true;
+      return this.books;
+    }
+  }
+
+  async initializeStreaming() {
+    try {
+      // Test HF Datasets API availability
+      const testUrl = `${this.proxyBase}/splits?dataset=${encodeURIComponent(this.datasetName)}`;
+      const response = await this.fetchWithTimeout(testUrl, { timeoutMs: 3000 });
+      
+      if (response.ok) {
+        const data = await response.json();
+        // Check if English split is available
+        let chosenSplit = null;
+        let chosenConfig = null;
+        const splits = Array.isArray(data.splits) ? data.splits : [];
+        // Prefer explicit English split on default config
+        const enDefault = splits.find(s => s.split === 'en' && s.config === 'default');
+        if (enDefault) {
+          chosenSplit = 'en';
+          chosenConfig = 'default';
+        } else {
+          // Otherwise prefer 'train' on default config
+          const trainDefault = splits.find(s => s.split === 'train' && s.config === 'default');
+          if (trainDefault) {
+            chosenSplit = 'train';
+            chosenConfig = 'default';
+          } else if (splits.length > 0) {
+            // Last resort: take the first available split/config
+            chosenSplit = splits[0].split;
+            chosenConfig = splits[0].config;
+          }
+        }
+
+        this.hfSplit = chosenSplit || this.hfSplit;
+        this.hfConfig = chosenConfig || this.hfConfig;
+        this.streamingEnabled = Boolean(chosenSplit);
+        if (this.streamingEnabled) {
+        }
+      }
+    } catch (error) {
+      console.warn('HF Datasets API test failed:', error);
+      this.streamingEnabled = false;
+    }
+  }
+
+  async preloadBooks(count = 2) {
+    if (!this.streamingEnabled) return;
+
+    try {
+      // Use random offset to avoid always getting the same books
+      const randomOffset = Math.floor(Math.random() * 1000);
+      const url = `${this.proxyBase}/rows?dataset=${encodeURIComponent(this.datasetName)}&config=${encodeURIComponent(this.hfConfig)}&split=${encodeURIComponent(this.hfSplit)}&offset=${randomOffset}&length=${count}`;
+
+      // Use retry logic with 20s timeout to handle slow HF API
+      const response = await this.retryFetch(
+        () => this.fetchWithTimeout(url, { timeoutMs: 20000 }),
+        3,  // max retries
+        1000 // base delay 1s
+      );
+
+      if (response.ok) {
+        const data = await response.json();
+
+        // Check if data has expected structure
+        if (!data.rows || !Array.isArray(data.rows)) {
+          console.error('Unexpected HF API response structure:', data);
+          return;
+        }
+
+
+        this.preloadedBooks = data.rows
+          .map(row => {
+            try {
+              return this.processHFBookLazy(row.row);
+            } catch (e) {
+              console.warn('Error processing book:', e);
+              return null;
+            }
+          })
+          .filter(book => book !== null);
+
+      } else {
+        console.error(`HF API request failed: ${response.status} ${response.statusText}`);
+      }
+    } catch (error) {
+      console.warn('Failed to preload books after retries:', error);
+    }
+  }
+
+  processHFBookLazy(rowData) {
+    // Minimal processing - defer text cleaning and validation until book is selected
+    const rawText = rowData.text || '';
+    
+    // Do basic metadata extraction to get proper title/author
+    const extractedMetadata = this.extractMetadata(rawText);
+    const title = extractedMetadata.title || rowData.title || 'Classic Literature';
+    const author = extractedMetadata.author || rowData.author || 'Unknown Author';
+    
+    return {
+      id: rowData.id || Math.random().toString(36),
+      title: title,
+      author: author,
+      rawText: rawText,
+      text: null, // Will clean when needed
+      language: rowData.language || 'en',
+      source: 'project_gutenberg',
+      processed: false
+    };
+  }
+
+  async processBookOnDemand(book) {
+    if (book.processed) return book;
+    
+    const startTime = Date.now();
+    
+    // Clean text when actually needed
+    const cleanedText = this.cleanProjectGutenbergText(book.rawText);
+    
+    book.text = cleanedText;
+    book.processed = true;
+    
+    // Validate after processing
+    if (!this.isValidForCloze(book)) {
+      return null;
+    }
+    
+    return book;
+  }
+
+
+  cleanProjectGutenbergText(text) {
+    if (!text) return '';
+    
+    let cleaned = text;
+    
+    // Remove Project Gutenberg start markers and everything before
+    const startPatterns = [
+      /\*\*\* START OF .*? \*\*\*/i,
+      /\*\*\*START OF .*?\*\*\*/i,
+      /START OF THE PROJECT GUTENBERG/i,
+      /GUTENBERG.*?EBOOK/i
+    ];
+    
+    for (const pattern of startPatterns) {
+      const match = cleaned.match(pattern);
+      if (match) {
+        const startIndex = match.index + match[0].length;
+        // Skip to next line
+        const nextLine = cleaned.indexOf('\n', startIndex);
+        if (nextLine !== -1) {
+          cleaned = cleaned.substring(nextLine + 1);
+        }
+        break;
+      }
+    }
+    
+    // Remove Project Gutenberg end markers and everything after
+    const endPatterns = [
+      /\*\*\* END OF .*? \*\*\*/i,
+      /\*\*\*END OF .*?\*\*\*/i,
+      /END OF THE PROJECT GUTENBERG/i,
+      /End of the Project Gutenberg/i
+    ];
+    
+    for (const pattern of endPatterns) {
+      const match = cleaned.match(pattern);
+      if (match) {
+        cleaned = cleaned.substring(0, match.index);
+        break;
+      }
+    }
+    
+    // Remove common Project Gutenberg artifacts and scanning notes
+    cleaned = cleaned
+      .replace(/\r\n/g, '\n')                           // Normalize line endings
+      .replace(/produced from images generously.*?\n/gi, '') // Remove scanning notes
+      .replace(/^.*page\s+scan\s+source:.*$/gmi, '')       // Remove IA page scan source lines
+      .replace(/^\s*https?:\/\/\S+.*$/gmi, '')            // Remove standalone URL lines
+      .replace(/\n\s*\n\s*\n+/g, '\n\n')               // Remove excessive line breaks
+      .replace(/^\s*CHAPTER.*$/gm, '')                  // Remove chapter headers
+      .replace(/^\s*Chapter.*$/gm, '')                  // Remove chapter headers
+      .replace(/^\s*\d+\s*$/gm, '')                     // Remove page numbers
+      .replace(/^\s*\[.*?\]\s*$/gm, '')                 // Remove bracketed notes
+      .replace(/^\s*_.*_\s*$/gm, '')                    // Remove italic notes
+      .replace(/[_*]/g, '')                             // Remove underscores and asterisks
+      .trim();
+    
+    // Find the actual start of narrative content
+    const lines = cleaned.split('\n');
+    let contentStart = 0;
+    
+    for (let i = 0; i < Math.min(80, lines.length); i++) {
+      const line = lines[i].trim();
+      
+      // Skip empty lines, title pages, and metadata
+      const looksAllCaps = /^[^a-z]*[A-Z][A-Z\s'.,:&;-]*$/.test(line) && line.length <= 60;
+      const looksPublisher = /(PUBLISHER|PRESS|NEW YORK|LONDON|BOSTON|PARIS|MURRAY STREET|COMPANY|LIMITED)/i.test(line);
+      const looksFrontMatter = /(^BY\s+[A-Z .'-]{2,}$|A NOVEL|REVISED AND CORRECTED|COPYRIGHT|Entered according to Act of Congress)/i.test(line);
+      const looksScanOrUrl = /(archive\.org|Internet Archive|Google|HathiTrust|scann?ed|page\s+scan|https?:\/\/|www\.)/i.test(line);
+
+      if (!line || 
+          line.includes('Title:') || 
+          line.includes('Author:') ||
+          line.includes('Release Date:') ||
+          line.includes('Language:') ||
+          line.includes('Character set') ||
+          line.includes('www.gutenberg') ||
+          line.includes('Project Gutenberg') ||
+          looksAllCaps ||
+          looksPublisher ||
+          looksFrontMatter ||
+          looksScanOrUrl ||
+          line.length < 20) {
+        contentStart = i + 1;
+        continue;
+      }
+      
+      // Found actual content
+      break;
+    }
+    
+    if (contentStart > 0 && contentStart < lines.length) {
+      cleaned = lines.slice(contentStart).join('\n').trim();
+    }
+    
+    return cleaned;
+  }
+
+  extractMetadata(text) {
+    const metadata = { title: 'Classic Literature', author: 'Unknown Author' };
+    
+    if (!text) return metadata;
+    
+    // Look for the standard Project Gutenberg header format
+    const firstLine = text.split('\n')[0].trim();
+    
+    // Parse the standard format: "The Project Gutenberg EBook of [TITLE], by [AUTHOR]"
+    const pgMatch = firstLine.match(/^.*?The Project Gutenberg EBook of (.+?),\s*by\s+(.+?)$/i);
+    if (pgMatch) {
+      const title = pgMatch[1].trim();
+      const author = pgMatch[2].trim();
+      
+      if (title && this.isValidTitle(title)) {
+        metadata.title = this.cleanMetadataField(title);
+      }
+      if (author && this.isValidAuthor(author)) {
+        metadata.author = this.cleanMetadataField(author);
+      }
+      
+      return metadata;
+    }
+    
+    // Fallback: Look for explicit Title: and Author: fields in first 50 lines
+    const lines = text.split('\n').slice(0, 50);
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      
+      if (line.startsWith('Title:')) {
+        const title = line.replace('Title:', '').trim();
+        if (title && title.length > 1) {
+          metadata.title = this.cleanMetadataField(title);
+        }
+      } else if (line.startsWith('Author:')) {
+        const author = line.replace('Author:', '').trim();
+        if (author && author.length > 1) {
+          metadata.author = this.cleanMetadataField(author);
+        }
+      }
+    }
+    
+    return metadata;
+  }
+
+  cleanMetadataField(field) {
+    return field
+      .replace(/\[.*?\]/g, '') // Remove bracketed info
+      .replace(/\s+/g, ' ')     // Normalize whitespace
+      .trim();
+  }
+
+
+  isValidTitle(title) {
+    if (!title || title.length < 3 || title.length > 100) return false;
+    // Avoid fragments that are clearly not titles
+    if (title.includes('Project Gutenberg') || 
+        title.includes('www.') || 
+        title.includes('produced from') ||
+        title.includes('images generously')) return false;
+    return true;
+  }
+
+  isValidAuthor(author) {
+    if (!author || author.length < 3 || author.length > 50) return false;
+    // Basic validation - should look like a name
+    if (author.includes('Project Gutenberg') || 
+        author.includes('www.') ||
+        author.includes('produced from')) return false;
+    return true;
+  }
+
+  isValidForCloze(book) {
+    if (!book.text) return false;
+    
+    const textLength = book.text.length;
+    
+    // Basic length criteria
+    if (textLength < 2000) return false;        // Minimum readable length
+    if (textLength > 500000) return false;      // Too long for performance
+    
+    // Check for excessive formatting (likely reference material)
+    const lineBreakRatio = (book.text.match(/\n\n/g) || []).length / textLength;
+    if (lineBreakRatio > 0.05) return false;    // Fragmentation threshold
+    
+    // Ensure it has actual narrative content
+    const sentenceCount = (book.text.match(/[.!?]+/g) || []).length;
+    if (sentenceCount < 10) return false;       // Sentence requirement
+    
+    // Sample text for quality check (first 5000 chars should be representative)
+    const sampleText = book.text.substring(0, 5000);
+    
+    // Check for index/TOC patterns
+    const indexPatterns = [
+      'CONTENTS', 'INDEX', 'CHAPTER', 'Volume', 'Vol.', 
+      'Part I', 'Part II', 'BOOK I', 'APPENDIX'
+    ];
+    const indexCount = indexPatterns.reduce((count, pattern) => 
+      count + (sampleText.match(new RegExp(pattern, 'gi')) || []).length, 0
+    );
+    const indexRatio = indexCount / (sampleText.split(/\s+/).length || 1);
+    
+    if (indexRatio > 0.05) {
+      return false;
+    }
+    
+    // Check for catalog/bibliography patterns
+    if (book.title && (
+      book.title.toLowerCase().includes('index') ||
+      book.title.toLowerCase().includes('catalog') ||
+      book.title.toLowerCase().includes('bibliography') ||
+      book.title.toLowerCase().includes('contents')
+    )) {
+      return false;
+    }
+    
+    return true;
+  }
+
+  async getRandomBook() {
+    if (!this.isLoaded) {
+      throw new Error('Dataset not loaded');
+    }
+    
+    // First, try to find a successfully processed HF book
+    if (this.streamingEnabled && this.preloadedBooks.length > 0) {
+      const availableHFBooks = this.preloadedBooks.filter(book => 
+        !this.usedBooks.has(this.getBookId(book))
+      );
+      
+      for (const book of availableHFBooks) {
+        const processedBook = await this.processBookOnDemand(book);
+        if (processedBook) {
+          this.usedBooks.add(this.getBookId(processedBook));
+          return processedBook;
+        }
+      }
+      
+      // If no HF books worked, try streaming
+      const streamedBook = await this.getStreamingBook();
+      if (streamedBook) {
+        this.usedBooks.add(this.getBookId(streamedBook));
+        return streamedBook;
+      }
+    }
+    
+    // Fallback to local samples
+    const fallbackBooks = this.books.length > 0 ? this.books : this.getSampleBooks();
+    const availableBooks = fallbackBooks.filter(book => 
+      !this.usedBooks.has(this.getBookId(book))
+    );
+    
+    if (availableBooks.length > 0) {
+      const randomIndex = Math.floor(Math.random() * availableBooks.length);
+      const book = availableBooks[randomIndex];
+      this.usedBooks.add(this.getBookId(book));
+      return book;
+    }
+    
+    // If all books used, clear cache and start over
+    this.usedBooks.clear();
+    return this.getRandomBook();
+  }
+
+  getBookId(book) {
+    // Create unique ID from title and author to track duplicates
+    return `${book.title}_${book.author}`.replace(/\s+/g, '_').toLowerCase();
+  }
+
+  async getStreamingBook() {
+    // Use preloaded books for immediate access
+    if (this.preloadedBooks.length > 0) {
+      const randomIndex = Math.floor(Math.random() * this.preloadedBooks.length);
+      let book = this.preloadedBooks[randomIndex];
+      
+      // Process on demand if needed
+      if (!book.processed) {
+        book = await this.processBookOnDemand(book);
+      }
+      
+      return book;
+    }
+    
+    // If no preloaded books, try to fetch directly with retry
+    try {
+      if (!this.streamingEnabled) return null;
+      const offset = Math.floor(Math.random() * 1000);
+      const url = `${this.proxyBase}/rows?dataset=${encodeURIComponent(this.datasetName)}&config=${encodeURIComponent(this.hfConfig)}&split=${encodeURIComponent(this.hfSplit)}&offset=${offset}&length=1`;
+
+      const response = await this.retryFetch(
+        () => this.fetchWithTimeout(url, { timeoutMs: 10000 }),
+        2,  // fewer retries for on-demand fetch
+        500
+      );
+
+      if (response.ok) {
+        const data = await response.json();
+        if (data.rows && data.rows.length > 0) {
+          const book = this.processHFBookLazy(data.rows[0].row);
+          return await this.processBookOnDemand(book);
+        }
+      }
+    } catch (error) {
+      console.warn('Direct streaming failed after retries:', error);
+    }
+    
+    return null;
+  }
+
+  async getBookByLevelCriteria(level) {
+    return await this.getRandomBook();
+  }
+
+
+
+  getBookById(id) {
+    // Search in both preloaded and local books
+    const allBooks = [...this.preloadedBooks, ...this.books];
+    return allBooks.find(book => book.id === id);
+  }
+
+  searchBooks(query) {
+    if (!query) return [...this.preloadedBooks, ...this.books];
+    
+    const lowerQuery = query.toLowerCase();
+    const allBooks = [...this.preloadedBooks, ...this.books];
+    return allBooks.filter(book => 
+      book.title.toLowerCase().includes(lowerQuery) ||
+      book.author.toLowerCase().includes(lowerQuery)
+    );
+  }
+
+  // Health check for streaming status
+  getStatus() {
+    return {
+      streamingEnabled: this.streamingEnabled,
+      preloadedBooks: this.preloadedBooks.length,
+      localBooks: this.books.length,
+      totalAvailable: this.preloadedBooks.length + this.books.length,
+      source: this.streamingEnabled ? 'HuggingFace Datasets' : 'Local Samples'
+    };
+  }
+
+  // Refresh preloaded books cache
+  async refreshCache() {
+    if (this.streamingEnabled) {
+      await this.preloadBooks(20);
+    }
+  }
+
+  // Small helper for fast-fail network calls
+  async fetchWithTimeout(resource, options = {}) {
+    const { timeoutMs = 5000, ...rest } = options;
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      return await fetch(resource, { ...rest, signal: controller.signal });
+    } finally {
+      clearTimeout(id);
+    }
+  }
+
+  // Retry wrapper with exponential backoff
+  async retryFetch(fetchFn, maxRetries = 3, baseDelayMs = 500) {
+    let lastError;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        return await fetchFn();
+      } catch (error) {
+        lastError = error;
+        if (attempt < maxRetries) {
+          const delay = baseDelayMs * Math.pow(2, attempt - 1);
+          await new Promise(resolve => setTimeout(resolve, delay));
+        }
+      }
+    }
+    throw lastError;
+  }
+}
+
+export default new HuggingFaceDatasetService();

src/chatInterface.js

@@ -0,0 +1,335 @@
+// Chat UI components for contextual hints
+import { analyticsService } from './analyticsService.js';
+
+class ChatUI {
+  constructor(gameLogic) {
+    this.game = gameLogic;
+    this.activeChatBlank = null;
+    this.chatModal = null;
+    this.isOpen = false;
+    this.messageHistory = new Map(); // blankId -> array of messages for persistent history
+    this.analytics = analyticsService;
+    this.setupChatModal();
+  }
+
+  // Create and setup chat modal
+  setupChatModal() {
+    // Create modal HTML
+    const modalHTML = `
+      <div id="chat-modal" class="fixed inset-0 bg-black bg-opacity-50 z-50 hidden flex items-center justify-center">
+        <div class="bg-white rounded-lg shadow-xl max-w-md w-full mx-4 max-h-[80vh] flex flex-col">
+          <!-- Header -->
+          <div class="flex items-center justify-between p-4 border-b">
+            <h3 id="chat-title" class="text-lg font-semibold text-gray-900">
+              Chat about Word #1
+            </h3>
+            <button id="chat-close" class="text-gray-400 hover:text-gray-600">
+              <svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"></path>
+              </svg>
+            </button>
+          </div>
+          
+          <!-- Chat messages area -->
+          <div id="chat-messages" class="flex-1 overflow-y-auto p-4 min-h-[200px] max-h-[400px]">
+            <div class="text-center text-gray-500 text-sm">
+              Ask me anything about this word! I can help with meaning, context, grammar, or give you hints.
+            </div>
+          </div>
+          
+          <!-- Suggested questions -->
+          <div id="suggested-questions" class="px-4 py-2 border-t border-gray-100">
+            <div id="suggestion-buttons" class="flex flex-wrap gap-1">
+              <!-- Suggestion buttons will be inserted here -->
+            </div>
+          </div>
+          
+          <!-- Question dropdown area -->
+          <div class="p-4 border-t">
+            <!-- Dropdown for all devices -->
+            <select id="question-dropdown" class="w-full p-2 border rounded mb-4">
+              <option value="">Select a question...</option>
+            </select>
+          </div>
+        </div>
+      </div>
+    `;
+
+    // Insert modal into page
+    document.body.insertAdjacentHTML('beforeend', modalHTML);
+    
+    this.chatModal = document.getElementById('chat-modal');
+    this.setupEventListeners();
+  }
+
+  // Setup event listeners for chat modal
+  setupEventListeners() {
+    const closeBtn = document.getElementById('chat-close');
+    
+    // Close modal
+    closeBtn.addEventListener('click', () => this.closeChat());
+    this.chatModal.addEventListener('click', (e) => {
+      if (e.target === this.chatModal) this.closeChat();
+    });
+    
+    // ESC key to close
+    document.addEventListener('keydown', (e) => {
+      if (e.key === 'Escape' && this.isOpen) this.closeChat();
+    });
+  }
+
+  // Open chat for specific blank
+  async openChat(blankIndex) {
+    this.activeChatBlank = blankIndex;
+    this.isOpen = true;
+    
+    // Update title
+    const title = document.getElementById('chat-title');
+    title.textContent = `Help with Word #${blankIndex + 1}`;
+    
+    // Restore previous messages or show intro
+    this.restoreMessages(blankIndex);
+    
+    // Load question buttons
+    this.loadQuestionButtons();
+    
+    // Show modal
+    this.chatModal.classList.remove('hidden');
+  }
+
+  // Close chat modal
+  closeChat() {
+    this.isOpen = false;
+    this.chatModal.classList.add('hidden');
+    this.activeChatBlank = null;
+  }
+
+  // Clear messages and show intro
+  clearMessages() {
+    const messagesContainer = document.getElementById('chat-messages');
+    messagesContainer.innerHTML = `
+      <div class="text-center text-gray-500 text-sm mb-4">
+        Choose a question below to get help with this word.
+      </div>
+    `;
+  }
+
+  // Restore messages for a specific blank or show intro
+  restoreMessages(blankIndex) {
+    const messagesContainer = document.getElementById('chat-messages');
+    const blankId = `blank_${blankIndex}`;
+    const history = this.messageHistory.get(blankId);
+    
+    if (history && history.length > 0) {
+      // Restore previous messages
+      messagesContainer.innerHTML = '';
+      history.forEach(msg => {
+        this.displayMessage(msg.sender, msg.content, msg.isUser);
+      });
+    } else {
+      // Show intro for new conversation
+      this.clearMessages();
+    }
+  }
+
+  // Display a message without storing it (used for restoration)
+  displayMessage(sender, content, isUser) {
+    const messagesContainer = document.getElementById('chat-messages');
+    const alignment = isUser ? 'flex justify-end' : 'flex justify-start';
+    const messageClass = isUser 
+      ? 'bg-blue-500 text-white' 
+      : 'bg-gray-100 text-gray-900';
+    const displaySender = isUser ? 'You' : sender;
+
+    const messageHTML = `
+      <div class="mb-3 ${alignment}">
+        <div class="${messageClass} rounded-lg px-3 py-2 max-w-[80%]">
+          <div class="text-xs font-medium mb-1">${displaySender}</div>
+          <div class="text-sm">${this.escapeHtml(content)}</div>
+        </div>
+      </div>
+    `;
+    
+    messagesContainer.insertAdjacentHTML('beforeend', messageHTML);
+    messagesContainer.scrollTop = messagesContainer.scrollHeight;
+  }
+
+  // Clear all chat history (called when round ends)
+  clearChatHistory() {
+    this.messageHistory.clear();
+  }
+
+  // Load question dropdown with disabled state for used questions
+  loadQuestionButtons() {
+    const dropdown = document.getElementById('question-dropdown');
+    const questions = this.game.getSuggestedQuestionsForBlank(this.activeChatBlank);
+    
+    // Clear existing content
+    dropdown.innerHTML = '<option value="">Select a question...</option>';
+    
+    // Build dropdown options
+    questions.forEach(question => {
+      const isDisabled = question.used;
+      const optionText = isDisabled ? `${question.text} ✓` : question.text;
+      
+      // Add all options but mark used ones as disabled
+      const option = document.createElement('option');
+      option.value = isDisabled ? '' : question.type;
+      option.textContent = optionText;
+      option.disabled = isDisabled;
+      option.style.color = isDisabled ? '#9CA3AF' : '#111827';
+      dropdown.appendChild(option);
+    });
+    
+    // Add change listener to dropdown
+    dropdown.addEventListener('change', (e) => {
+      if (e.target.value) {
+        this.askQuestion(e.target.value);
+        e.target.value = ''; // Reset dropdown
+      }
+    });
+  }
+
+  // Ask a specific question
+  async askQuestion(questionType) {
+    if (this.activeChatBlank === null) return;
+    
+    // Get current user input for the blank
+    const currentInput = this.getCurrentBlankInput();
+    
+    // Get the actual question text from the button that was clicked
+    const questions = this.game.getSuggestedQuestionsForBlank(this.activeChatBlank);
+    const selectedQuestion = questions.find(q => q.type === questionType);
+    const questionText = selectedQuestion ? selectedQuestion.text : this.getQuestionText(questionType);
+    
+    // Show question and loading
+    this.addMessageToChat('You', questionText, true);
+    this.showTypingIndicator();
+    
+    try {
+      // Send to chat service with question type
+      const response = await this.game.askQuestionAboutBlank(
+        this.activeChatBlank,
+        questionType,
+        currentInput
+      );
+      
+      this.hideTypingIndicator();
+      
+      if (response.success) {
+        // Make sure we're displaying the response string, not the object
+        const responseText = typeof response.response === 'string'
+          ? response.response
+          : response.response.response || 'Sorry, I had trouble with that question.';
+        this.addMessageToChat('Cluemaster', responseText, false);
+
+        // Track hint usage in analytics
+        this.analytics.recordHint(this.activeChatBlank, questionType);
+
+        // Refresh question buttons to show the used question as disabled
+        this.loadQuestionButtons();
+      } else {
+        this.addMessageToChat('Cluemaster', response.message || 'Sorry, I had trouble with that question.', false);
+      }
+      
+    } catch (error) {
+      this.hideTypingIndicator();
+      console.error('Chat error:', error);
+      this.addMessageToChat('Cluemaster', 'Sorry, I encountered an error. Please try again.', false);
+    }
+  }
+
+  // Get question text for display
+  getQuestionText(questionType) {
+    const questions = {
+      'grammar': 'What type of word is this?',
+      'meaning': 'What does this word mean?',
+      'context': 'Why does this word fit here?',
+      'clue': 'Give me a clue'
+    };
+    return questions[questionType] || questions['clue'];
+  }
+
+  // Get current input for the active blank
+  getCurrentBlankInput() {
+    const input = document.querySelector(`input[data-blank-index="${this.activeChatBlank}"]`);
+    return input ? input.value.trim() : '';
+  }
+
+  // Add message to chat display and store in history
+  addMessageToChat(sender, content, isUser) {
+    // Store message in history for current blank
+    if (this.activeChatBlank !== null) {
+      const blankId = `blank_${this.activeChatBlank}`;
+      if (!this.messageHistory.has(blankId)) {
+        this.messageHistory.set(blankId, []);
+      }
+      
+      // Change "Tutor" to "Cluemaster" for display and storage
+      const displaySender = sender === 'Tutor' ? 'Cluemaster' : sender;
+      
+      this.messageHistory.get(blankId).push({
+        sender: displaySender,
+        content: content,
+        isUser: isUser,
+        timestamp: Date.now()
+      });
+    }
+    
+    // Display the message
+    this.displayMessage(sender === 'Tutor' ? 'Cluemaster' : sender, content, isUser);
+  }
+
+  // Show typing indicator
+  showTypingIndicator() {
+    const messagesContainer = document.getElementById('chat-messages');
+    const typingHTML = `
+      <div id="typing-indicator" class="mb-3 mr-auto max-w-[80%]">
+        <div class="bg-gray-100 text-gray-900 rounded-lg px-3 py-2">
+          <div class="text-xs font-medium mb-1">Cluemaster</div>
+          <div class="text-sm">
+            <span class="typing-dots">
+              <span>.</span><span>.</span><span>.</span>
+            </span>
+          </div>
+        </div>
+      </div>
+    `;
+    
+    messagesContainer.insertAdjacentHTML('beforeend', typingHTML);
+    messagesContainer.scrollTop = messagesContainer.scrollHeight;
+  }
+
+  // Hide typing indicator
+  hideTypingIndicator() {
+    const indicator = document.getElementById('typing-indicator');
+    if (indicator) indicator.remove();
+  }
+
+  // Escape HTML to prevent XSS
+  escapeHtml(text) {
+    const div = document.createElement('div');
+    div.textContent = text;
+    return div.innerHTML;
+  }
+
+  // Setup chat buttons for blanks
+  setupChatButtons() {
+    // Remove existing listeners
+    document.querySelectorAll('.chat-button').forEach(btn => {
+      btn.replaceWith(btn.cloneNode(true));
+    });
+    
+    // Add new listeners
+    document.querySelectorAll('.chat-button').forEach(btn => {
+      btn.addEventListener('click', (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        const blankIndex = parseInt(btn.dataset.blankIndex);
+        this.openChat(blankIndex);
+      });
+    });
+  }
+}
+
+export default ChatUI;

src/clozeGameEngine.js

@@ -0,0 +1,970 @@
+// Core game logic for minimal cloze reader
+import bookDataService from './bookDataService.js';
+import { AIService } from './aiService.js';
+import ChatService from './conversationManager.js';
+import { LeaderboardService } from './leaderboardService.js';
+
+const aiService = new AIService();
+
+class ClozeGame {
+  constructor() {
+    this.currentBook = null;
+    this.originalText = '';
+    this.clozeText = '';
+    this.blanks = [];
+    this.userAnswers = [];
+    this.score = 0;
+    this.currentRound = 1;
+    this.currentLevel = 1; // Track difficulty level separately from round
+    this.contextualization = '';
+    this.hints = [];
+    this.chatService = new ChatService(aiService);
+    this.lastResults = null; // Store results for answer revelation
+    this.leaderboardService = new LeaderboardService();
+    this.passagesPassedAtCurrentLevel = 0; // Track progress toward level advancement
+
+    // Multiple retry support
+    this.attemptCounts = {}; // blankIndex -> number of attempts
+    this.lockedBlanks = new Set(); // blanks that are correct and locked
+    this.maxRetries = 5; // Maximum retry attempts before forcing completion
+
+  }
+
+  // --- User-visible framing helpers ---
+  getBlanksPerPassage(level = this.currentLevel) {
+    if (level <= 5) return 1;
+    if (level <= 10) return 2;
+    return 3;
+  }
+
+  getProgressSnapshot() {
+    return {
+      round: this.currentRound,
+      level: this.currentLevel,
+      blanksPerPassage: this.getBlanksPerPassage()
+    };
+  }
+
+  formatProgressText(snapshot = this.getProgressSnapshot()) {
+    const blanksLabel = `${snapshot.blanksPerPassage} blank${snapshot.blanksPerPassage > 1 ? 's' : ''}`;
+    return `Level ${snapshot.level} • ${blanksLabel}`;
+  }
+
+  formatAdvancementText({ passed, correctCount, requiredCorrect, justAdvancedLevel }) {
+    if (passed) {
+      if (justAdvancedLevel) {
+        return `✓ Passed • Level up! Welcome to Level ${this.currentLevel}`;
+      }
+      return `✓ Passed • Advancing to next level!`;
+    }
+    return `Try again • Need ${requiredCorrect}/${this.blanks.length} correct (you got ${correctCount})`;
+  }
+
+  async initialize() {
+    try {
+      await bookDataService.loadDataset();
+    } catch (error) {
+      console.error('Failed to initialize game:', error);
+      throw error;
+    }
+  }
+
+  async startNewRound() {
+    try {
+
+      // Reset retry tracking for new round
+      this.attemptCounts = {};
+      this.lockedBlanks = new Set();
+
+      // Get one book for this round based on current level criteria
+      const book = await bookDataService.getBookByLevelCriteria(this.currentLevel);
+
+      // Extract passage from book
+      const passage = this.extractCoherentPassage(book.text);
+
+      // Store book and passage (normalize whitespace to prevent compound words)
+      this.currentBook = book;
+      this.originalText = passage.trim().replace(/\s+/g, ' ');
+
+      // Create cloze text using AI
+      try {
+        await this.createClozeText();
+        await this.generateContextualization();
+      } catch (error) {
+        console.warn('AI processing failed:', error);
+        throw error;
+      }
+
+      const snapshot = this.getProgressSnapshot();
+      return {
+        title: this.currentBook.title,
+        author: this.currentBook.author,
+        text: this.clozeText,
+        blanks: this.blanks,
+        contextualization: this.contextualization,
+        hints: this.hints,
+        progressText: this.formatProgressText(snapshot)
+      };
+    } catch (error) {
+      console.error('Error starting new round:', error);
+      throw error;
+    }
+  }
+
+  extractCoherentPassage(text) {
+    // Simple elegant solution: start from middle third of book where actual content is
+    const textLength = text.length;
+    const startFromMiddle = Math.floor(textLength * 0.3); // Skip first 30%
+    const endAtThreeQuarters = Math.floor(textLength * 0.8); // Stop before last 20%
+    
+    let attempts = 0;
+    let passage = '';
+    
+    while (attempts < 8) {
+      // Random position in the middle section
+      const availableLength = endAtThreeQuarters - startFromMiddle;
+      const randomOffset = Math.floor(Math.random() * Math.max(0, availableLength - 1000));
+      const startIndex = startFromMiddle + randomOffset;
+      
+      // Extract longer initial passage for better sentence completion
+      passage = text.substring(startIndex, startIndex + 1000);
+    
+    // Clean up start - find first complete sentence that starts with capital letter
+    const firstSentenceMatch = passage.match(/[.!?]\s+([A-Z][^.!?]*)/);
+    if (firstSentenceMatch && firstSentenceMatch.index < 200) {
+      // Start from the capital letter after punctuation
+      passage = passage.substring(firstSentenceMatch.index + firstSentenceMatch[0].length - firstSentenceMatch[1].length);
+    } else {
+      // If no good sentence break found, find first capital letter
+      const firstCapitalMatch = passage.match(/[A-Z][^.!?]*/);
+      if (firstCapitalMatch) {
+        passage = passage.substring(firstCapitalMatch.index);
+      }
+    }
+    
+      // Clean up end - ensure we end at a complete sentence
+      const sentences = passage.split(/(?<=[.!?])\s+/);
+      if (sentences.length > 1) {
+        // Remove the last sentence if it might be incomplete
+        sentences.pop();
+        passage = sentences.join(' ');
+      }
+      
+      // Immediate rejects for known front-matter/meta patterns
+      const frontMatterRegexes = [
+        /(archive\.org|Internet Archive|HathiTrust|Google)/i,
+        /page\s+scan\s+source/i,
+        /Entered according to Act of Congress/i,
+        /COPYRIGHT/i,
+        /PUBLISHER|PRESS|MURRAY STREET|NEW YORK|LONDON|BOSTON/i,
+        /\bBY\s+[A-Z .'-]{2,}\b/,
+        /\bA NOVEL\b/i,
+        /https?:\/\//i,
+      ];
+      if (frontMatterRegexes.some(r => r.test(passage))) {
+        attempts++;
+        continue;
+      }
+
+      // Enhanced quality check based on narrative flow characteristics
+      const words = passage.split(/\s+/);
+      const totalWords = words.length;
+      
+      // Count various quality indicators
+      const capsWords = words.filter(w => w.length > 1 && w === w.toUpperCase() && !/^\d+$/.test(w));
+      const capsCount = capsWords.length;
+      const numbersCount = words.filter(w => /\d/.test(w)).length;
+      const shortWords = words.filter(w => w.length <= 3).length;
+      const punctuationMarks = (passage.match(/[;:()[\]{}—–]/g) || []).length;
+      const sentenceList = passage.split(/[.!?]+/).filter(s => s.trim().length > 10);
+      const lines = passage.split('\n').filter(l => l.trim());
+      
+      // Debug logging for caps detection
+      if (capsCount > 5) {
+      }
+      
+      // Count excessive dashes (n-dashes, m-dashes, hyphens in sequence)
+      const dashSequences = (passage.match(/[-—–]{3,}/g) || []).length;
+      const totalDashes = (passage.match(/[-—–]/g) || []).length;
+      
+      // Count additional formatting patterns
+      const asteriskSequences = (passage.match(/\*{3,}/g) || []).length;
+      const asteriskLines = (passage.match(/^\s*\*+\s*$/gm) || []).length;
+      const underscoreSequences = (passage.match(/_{3,}/g) || []).length;
+      const equalSequences = (passage.match(/={3,}/g) || []).length;
+      const pipeCount = (passage.match(/\|/g) || []).length;
+      const numberedLines = (passage.match(/^\s*\d+[\.\)]\s/gm) || []).length;
+      const parenthesesCount = (passage.match(/[()]/g) || []).length;
+      const squareBrackets = (passage.match(/[\[\]]/g) || []).length;
+      
+      // Dictionary/glossary patterns
+      const hashSymbols = (passage.match(/#/g) || []).length;
+      const abbreviationPattern = /\b(n\.|adj\.|adv\.|v\.|pl\.|sg\.|cf\.|e\.g\.|i\.e\.|etc\.|vs\.|viz\.|OE\.|OFr\.|L\.|ME\.|NE\.|AN\.|ON\.|MDu\.|MLG\.|MHG\.|Ger\.|Du\.|Dan\.|Sw\.|Icel\.)\b/gi;
+      const abbreviations = (passage.match(abbreviationPattern) || []).length;
+      const etymologyBrackets = (passage.match(/\[[^\]]+\]/g) || []).length;
+      const referenceNumbers = (passage.match(/\b[IVX]+\s+[abc]?\s*\d+/g) || []).length;
+      const definitionPattern = /^[^.]+,\s*(n\.|adj\.|adv\.|v\.)/gm;
+      const definitionLines = (passage.match(definitionPattern) || []).length;
+      
+      // Academic/reference patterns
+      const citationPattern = /\(\d{4}\)|p\.\s*\d+|pp\.\s*\d+-\d+|vol\.\s*\d+|ch\.\s*\d+/gi;
+      const citations = (passage.match(citationPattern) || []).length;
+      const technicalTerms = ['etymology', 'phoneme', 'morpheme', 'lexicon', 'syntax', 'semantics', 'glossary', 'vocabulary', 'dialect', 'pronunciation'];
+      const technicalTermCount = technicalTerms.reduce((count, term) => 
+        count + (passage.match(new RegExp(term, 'gi')) || []).length, 0
+      );
+      
+      // Check for repetitive patterns (common in indexes/TOCs)
+      const repeatedPhrases = ['CONTENTS', 'CHAPTER', 'Volume', 'Vol.', 'Part', 'Book'];
+      const repetitionCount = repeatedPhrases.reduce((count, phrase) => 
+        count + (passage.match(new RegExp(phrase, 'gi')) || []).length, 0
+      );
+      
+      // Check for title patterns (common in TOCs)
+      const titlePattern = /^[A-Z][A-Z\s]+$/m;
+      const titleLines = lines.filter(line => titlePattern.test(line.trim())).length;
+      
+      // Check for consecutive all-caps lines (title pages, copyright notices)
+      let consecutiveCapsLines = 0;
+      let maxConsecutiveCaps = 0;
+      lines.forEach(line => {
+        const trimmed = line.trim();
+        if (trimmed.length > 3 && trimmed === trimmed.toUpperCase() && !/^\d+$/.test(trimmed)) {
+          consecutiveCapsLines++;
+          maxConsecutiveCaps = Math.max(maxConsecutiveCaps, consecutiveCapsLines);
+        } else {
+          consecutiveCapsLines = 0;
+        }
+      });
+      
+      // Calculate quality ratios
+      const capsRatio = capsCount / totalWords;
+      const numbersRatio = numbersCount / totalWords;
+      const shortWordRatio = shortWords / totalWords;
+      const punctuationRatio = punctuationMarks / totalWords;
+      const avgWordsPerSentence = totalWords / Math.max(1, sentenceList.length);
+      const repetitionRatio = repetitionCount / totalWords;
+      const titleLineRatio = titleLines / Math.max(1, lines.length);
+      const dashRatio = totalDashes / totalWords;
+      const parenthesesRatio = parenthesesCount / totalWords;
+      const squareBracketRatio = squareBrackets / totalWords;
+      const hashRatio = hashSymbols / totalWords;
+      const abbreviationRatio = abbreviations / totalWords;
+      const etymologyRatio = etymologyBrackets / totalWords;
+      const definitionRatio = definitionLines / Math.max(1, lines.length);
+      const technicalRatio = technicalTermCount / totalWords;
+      
+      // Stricter thresholds for higher levels
+      const capsThreshold = this.currentLevel >= 3 ? 0.03 : 0.05;
+      const numbersThreshold = this.currentLevel >= 3 ? 0.02 : 0.03;
+      
+      // Reject if passage shows signs of being technical/reference material
+      let qualityScore = 0;
+      let issues = [];
+      
+      // Immediate rejection for excessive caps (title pages, headers, etc)
+      if (capsRatio > 0.12) {
+        attempts++;
+        continue;
+      }
+      
+      // Immediate rejection for consecutive all-caps lines (title pages, copyright)
+      if (maxConsecutiveCaps >= 2) {
+        attempts++;
+        continue;
+      }
+      
+      if (capsRatio > capsThreshold) { qualityScore += capsRatio * 100; issues.push(`caps: ${Math.round(capsRatio * 100)}%`); }
+      if (numbersRatio > numbersThreshold) { qualityScore += numbersRatio * 40; issues.push(`numbers: ${Math.round(numbersRatio * 100)}%`); }
+      if (punctuationRatio > 0.08) { qualityScore += punctuationRatio * 15; issues.push(`punct: ${Math.round(punctuationRatio * 100)}%`); }
+      if (avgWordsPerSentence < 8 || avgWordsPerSentence > 40) { qualityScore += 2; issues.push(`sent-len: ${Math.round(avgWordsPerSentence)}`); }
+      if (shortWordRatio < 0.3) { qualityScore += 2; issues.push(`short-words: ${Math.round(shortWordRatio * 100)}%`); }
+      if (repetitionRatio > 0.02) { qualityScore += repetitionRatio * 50; issues.push(`repetitive: ${Math.round(repetitionRatio * 100)}%`); }
+      if (titleLineRatio > 0.2) { qualityScore += 5; issues.push(`title-lines: ${Math.round(titleLineRatio * 100)}%`); }
+      if (dashSequences > 0) { qualityScore += dashSequences * 3; issues.push(`dash-sequences: ${dashSequences}`); }
+      if (dashRatio > 0.02) { qualityScore += dashRatio * 25; issues.push(`dashes: ${Math.round(dashRatio * 100)}%`); }
+      if (asteriskSequences > 0 || asteriskLines > 0) { qualityScore += (asteriskSequences + asteriskLines) * 2; issues.push(`asterisk-separators: ${asteriskSequences + asteriskLines}`); }
+      if (underscoreSequences > 0) { qualityScore += underscoreSequences * 2; issues.push(`underscore-lines: ${underscoreSequences}`); }
+      if (equalSequences > 0) { qualityScore += equalSequences * 2; issues.push(`equal-lines: ${equalSequences}`); }
+      if (pipeCount > 5) { qualityScore += 3; issues.push(`table-formatting: ${pipeCount} pipes`); }
+      if (numberedLines > 3) { qualityScore += 2; issues.push(`numbered-list: ${numberedLines} items`); }
+      if (parenthesesRatio > 0.05) { qualityScore += 2; issues.push(`excessive-parentheses: ${Math.round(parenthesesRatio * 100)}%`); }
+      if (squareBracketRatio > 0.02) { qualityScore += 2; issues.push(`excessive-brackets: ${Math.round(squareBracketRatio * 100)}%`); }
+      
+      // Dictionary/glossary/academic content detection
+      if (hashRatio > 0.01) { qualityScore += hashRatio * 100; issues.push(`hash-symbols: ${hashSymbols}`); }
+      if (abbreviationRatio > 0.03) { qualityScore += abbreviationRatio * 50; issues.push(`abbreviations: ${abbreviations}`); }
+      if (etymologyRatio > 0.005) { qualityScore += etymologyRatio * 100; issues.push(`etymology-brackets: ${etymologyBrackets}`); }
+      if (definitionRatio > 0.1) { qualityScore += definitionRatio * 20; issues.push(`definition-lines: ${Math.round(definitionRatio * 100)}%`); }
+      if (referenceNumbers > 0) { qualityScore += referenceNumbers * 2; issues.push(`reference-numbers: ${referenceNumbers}`); }
+      if (citations > 0) { qualityScore += citations * 2; issues.push(`citations: ${citations}`); }
+      if (technicalRatio > 0.01) { qualityScore += technicalRatio * 30; issues.push(`technical-terms: ${technicalTermCount}`); }
+      
+      // Reject if quality score indicates technical/non-narrative content
+      if (qualityScore > 2.5) {
+        attempts++;
+        continue;
+      }
+      
+      // Good passage found
+      break;
+    }
+    
+    // Ensure minimum length - if too short, return what we have rather than infinite recursion
+    if (passage.length < 400) {
+      console.warn('Short passage extracted, using fallback approach');
+      // Try one more time with a simpler approach
+      const simpleStart = text.indexOf('. ') + 2;
+      if (simpleStart > 1 && simpleStart < text.length - 500) {
+        passage = text.substring(simpleStart, simpleStart + 600);
+        const lastPeriod = passage.lastIndexOf('.');
+        if (lastPeriod > 200) {
+          passage = passage.substring(0, lastPeriod + 1);
+        }
+      }
+    }
+    
+    return passage.trim();
+  }
+
+
+  async createClozeText() {
+    const words = this.originalText.split(' ');
+    // Progressive difficulty: levels 1-5 = 1 blank, levels 6-10 = 2 blanks, level 11+ = 3 blanks
+    let numberOfBlanks;
+    if (this.currentLevel <= 5) {
+      numberOfBlanks = 1;
+    } else if (this.currentLevel <= 10) {
+      numberOfBlanks = 2;
+    } else {
+      numberOfBlanks = 3;
+    }
+    
+    // Update chat service with current level
+    this.chatService.setLevel(this.currentLevel);
+    
+    // Always use AI for word selection with fallback
+    let significantWords;
+    try {
+      significantWords = await aiService.selectSignificantWords(
+        this.originalText, 
+        numberOfBlanks,
+        this.currentLevel
+      );
+    } catch (error) {
+      console.warn('AI word selection failed, using manual fallback:', error);
+      significantWords = this.selectWordsManually(words, numberOfBlanks);
+    }
+    
+    // Ensure we have valid words
+    if (!significantWords || significantWords.length === 0) {
+      console.warn('No words selected, using emergency fallback');
+      significantWords = this.selectWordsManually(words, numberOfBlanks);
+    }
+
+    // Find word indices for selected significant words, distributed throughout passage
+    const selectedIndices = [];
+    const wordsLower = words.map(w => w.toLowerCase().replace(/[^\w]/g, ''));
+    
+    // Create sections of the passage to ensure distribution
+    const passageSections = this.dividePassageIntoSections(words.length, numberOfBlanks);
+    
+    significantWords.forEach((significantWord, index) => {
+      // Clean the significant word for matching
+      const cleanSignificant = significantWord.toLowerCase().replace(/[^\w]/g, '');
+      
+      // Look for the word within the appropriate section for better distribution
+      const sectionStart = passageSections[index] ? passageSections[index].start : 0;
+      const sectionEnd = passageSections[index] ? passageSections[index].end : words.length;
+      
+      let wordIndex = -1;
+      
+      // First try to find the word in the designated section (avoiding first 10 words and capitalized words)
+      for (let i = Math.max(10, sectionStart); i < sectionEnd; i++) {
+        const originalWord = words[i].replace(/[^\w]/g, '');
+        const isCapitalized = originalWord.length > 0 && originalWord[0] === originalWord[0].toUpperCase();
+        if (wordsLower[i] === cleanSignificant && !selectedIndices.includes(i) && !isCapitalized) {
+          wordIndex = i;
+          break;
+        }
+      }
+      
+      // If not found in section, try progressively more relaxed searches
+      if (wordIndex === -1) {
+        // Try 1: Global search avoiding caps and first 10 words
+        wordIndex = wordsLower.findIndex((word, idx) => {
+          const originalWord = words[idx].replace(/[^\w]/g, '');
+          const isCapitalized = originalWord.length > 0 && originalWord[0] === originalWord[0].toUpperCase();
+          return word === cleanSignificant && !selectedIndices.includes(idx) && idx >= 10 && !isCapitalized;
+        });
+      }
+      
+      // Try 2: Allow capitalized words but still avoid first 10 words
+      if (wordIndex === -1) {
+        wordIndex = wordsLower.findIndex((word, idx) => {
+          return word === cleanSignificant && !selectedIndices.includes(idx) && idx >= 10;
+        });
+      }
+      
+      // Try 3: Allow words from position 5 onwards (more relaxed)
+      if (wordIndex === -1) {
+        wordIndex = wordsLower.findIndex((word, idx) => {
+          return word === cleanSignificant && !selectedIndices.includes(idx) && idx >= 5;
+        });
+      }
+      
+      // Try 4: Check if word contains the target (partial match)
+      if (wordIndex === -1) {
+        wordIndex = wordsLower.findIndex((word, idx) => {
+          return word.includes(cleanSignificant) && !selectedIndices.includes(idx) && idx >= 10;
+        });
+      }
+      
+      if (wordIndex !== -1) {
+        selectedIndices.push(wordIndex);
+      } else {
+        console.warn(`Could not find word "${significantWord}" in passage`);
+      }
+    });
+    
+    
+    // If no words were matched, fall back to manual selection
+    if (selectedIndices.length === 0) {
+      console.warn('No AI words matched in passage, using manual selection');
+      const manualWords = this.selectWordsManually(words, numberOfBlanks);
+      
+      // Try to match manual words with relaxed criteria
+      manualWords.forEach((manualWord) => {
+        const cleanManual = manualWord.toLowerCase().replace(/[^\w]/g, '');
+        let wordIndex = wordsLower.findIndex((word, idx) => {
+          const originalWord = words[idx].replace(/[^\w]/g, '');
+          const isCapitalized = originalWord.length > 0 && originalWord[0] === originalWord[0].toUpperCase();
+          return word === cleanManual && !selectedIndices.includes(idx) && idx >= 10 && !isCapitalized;
+        });
+        
+        // If not found, try allowing capitalized words
+        if (wordIndex === -1) {
+          wordIndex = wordsLower.findIndex((word, idx) => {
+            return word === cleanManual && !selectedIndices.includes(idx) && idx >= 5;
+          });
+        }
+        
+        if (wordIndex !== -1) {
+          selectedIndices.push(wordIndex);
+        }
+      });
+      
+    }
+
+    // Sort indices for easier processing
+    selectedIndices.sort((a, b) => a - b);
+    
+    // Final safety check - if still no words found, pick random content words (avoiding first 10)
+    if (selectedIndices.length === 0) {
+      console.error('Critical: No words could be selected, using emergency fallback');
+      const contentWords = words.map((word, idx) => ({ word: word.toLowerCase().replace(/[^\w]/g, ''), idx }))
+        .filter(item => item.word.length > 3 && !['the', 'and', 'but', 'for', 'are', 'was'].includes(item.word) && item.idx >= 10)
+        .slice(0, numberOfBlanks);
+      
+      selectedIndices.push(...contentWords.map(item => item.idx));
+    }
+
+    // Create blanks array and cloze text
+    this.blanks = [];
+    this.hints = [];
+    const clozeWords = [...words];
+    
+    for (let i = 0; i < selectedIndices.length; i++) {
+      const index = selectedIndices[i];
+      const originalWord = words[index];
+      const cleanWord = originalWord.replace(/[^\w]/g, '');
+      
+      const blankData = {
+        index: i,
+        originalWord: cleanWord,
+        wordIndex: index
+      };
+      
+      this.blanks.push(blankData);
+      
+      // Initialize chat context for this word
+      const wordContext = {
+        originalWord: cleanWord,
+        sentence: this.originalText,
+        passage: this.originalText,
+        bookTitle: this.currentBook.title,
+        author: this.currentBook.author,
+        year: this.currentBook.year,
+        wordPosition: index,
+        difficulty: this.calculateWordDifficulty(cleanWord, index, words)
+      };
+      
+      this.chatService.initializeWordContext(`blank_${i}`, wordContext);
+      
+      // Generate structural hint based on level
+      let structuralHint;
+      if (this.currentLevel <= 2) {
+        // Levels 1-2: show length, first letter, and last letter
+        structuralHint = `${cleanWord.length} letters, starts with "${cleanWord[0]}", ends with "${cleanWord[cleanWord.length - 1]}"`;
+      } else {
+        // Level 3+: show length and first letter only
+        structuralHint = `${cleanWord.length} letters, starts with "${cleanWord[0]}"`;
+      }
+      this.hints.push({ index: i, hint: structuralHint });
+      
+      // Replace word with input field placeholder
+      clozeWords[index] = `___BLANK_${i}___`;
+    }
+
+    this.clozeText = clozeWords.join(' ');
+    this.userAnswers = new Array(this.blanks.length).fill('');
+    
+    // Debug: Log the created cloze text
+    
+    return true; // Return success indicator
+  }
+
+  dividePassageIntoSections(totalWords, numberOfBlanks) {
+    const sections = [];
+    const sectionSize = Math.floor(totalWords / numberOfBlanks);
+    
+    for (let i = 0; i < numberOfBlanks; i++) {
+      const start = i * sectionSize;
+      const end = i === numberOfBlanks - 1 ? totalWords : (i + 1) * sectionSize;
+      sections.push({ start, end });
+    }
+    
+    return sections;
+  }
+
+  selectWordsManually(words, numberOfBlanks) {
+    // Fallback manual word selection - avoid function words completely
+    const functionWords = new Set([
+      // Articles
+      'the', 'a', 'an',
+      // Prepositions  
+      'in', 'on', 'at', 'to', 'for', 'of', 'with', 'by', 'from', 'up', 'about', 'into', 'over', 'after',
+      // Conjunctions
+      'and', 'or', 'but', 'so', 'yet', 'nor', 'because', 'since', 'although', 'if', 'when', 'while',
+      // Pronouns
+      'i', 'you', 'he', 'she', 'it', 'we', 'they', 'me', 'him', 'her', 'us', 'them', 'my', 'your', 'his', 'her', 'its', 'our', 'their',
+      'this', 'that', 'these', 'those', 'who', 'what', 'which', 'whom', 'whose',
+      // Auxiliary verbs
+      'is', 'are', 'was', 'were', 'be', 'been', 'being', 'have', 'has', 'had', 'do', 'does', 'did',
+      'will', 'would', 'could', 'should', 'may', 'might', 'must', 'can', 'shall'
+    ]);
+
+    // Get content words with their indices for better distribution
+    const contentWordIndices = [];
+    words.forEach((word, index) => {
+      const cleanWord = word.toLowerCase().replace(/[^\w]/g, '');
+      const originalCleanWord = word.replace(/[^\w]/g, '');
+      // Skip capitalized words, function words, and words that are too short/long
+      if (cleanWord.length > 3 && cleanWord.length <= 12 && 
+          !functionWords.has(cleanWord) && 
+          originalCleanWord[0] === originalCleanWord[0].toLowerCase()) {
+        contentWordIndices.push({ word: cleanWord, index });
+      }
+    });
+
+    // Distribute selection across sections
+    const passageSections = this.dividePassageIntoSections(words.length, numberOfBlanks);
+    const selectedWords = [];
+    
+    for (let i = 0; i < numberOfBlanks && i < passageSections.length; i++) {
+      const section = passageSections[i];
+      const sectionWords = contentWordIndices.filter(item => 
+        item.index >= section.start && item.index < section.end
+      );
+      
+      if (sectionWords.length > 0) {
+        const randomIndex = Math.floor(Math.random() * sectionWords.length);
+        selectedWords.push(sectionWords[randomIndex].word);
+      }
+    }
+
+    // Fill remaining slots if needed
+    while (selectedWords.length < numberOfBlanks && contentWordIndices.length > 0) {
+      const availableWords = contentWordIndices
+        .map(item => item.word)
+        .filter(word => !selectedWords.includes(word));
+      
+      if (availableWords.length > 0) {
+        const randomIndex = Math.floor(Math.random() * availableWords.length);
+        selectedWords.push(availableWords[randomIndex]);
+      } else {
+        break;
+      }
+    }
+
+    return selectedWords;
+  }
+
+  async generateContextualization() {
+    // Always use AI for contextualization
+    try {
+      this.contextualization = await aiService.generateContextualization(
+        this.currentBook.title,
+        this.currentBook.author,
+        this.originalText
+      );
+      return this.contextualization;
+    } catch (error) {
+      console.warn('AI contextualization failed, using fallback:', error);
+      this.contextualization = `"${this.currentBook.title}" by ${this.currentBook.author} - A classic work of literature.`;
+      return this.contextualization;
+    }
+  }
+
+  renderClozeText() {
+    let html = this.clozeText;
+    
+    this.blanks.forEach((blank, index) => {
+      const inputHtml = `<input type="text" 
+        class="cloze-input" 
+        data-blank-index="${index}" 
+        placeholder="${'_'.repeat(Math.max(3, blank.originalWord.length))}"
+        style="width: ${Math.max(50, blank.originalWord.length * 10)}px;">`;
+      
+      html = html.replace(`___BLANK_${index}___`, inputHtml);
+    });
+
+    return html;
+  }
+
+  submitAnswers(answers, forceComplete = false) {
+    this.userAnswers = answers;
+    let correctCount = 0;
+    let newlyCorrectCount = 0;
+    const results = [];
+    const retryableIndices = [];
+
+    this.blanks.forEach((blank, index) => {
+      // Skip already locked (correct) blanks
+      if (this.lockedBlanks.has(index)) {
+        correctCount++;
+        results.push({
+          blankIndex: index,
+          userAnswer: answers[index],
+          correctAnswer: blank.originalWord,
+          isCorrect: true,
+          isLocked: true,
+          attemptNumber: this.attemptCounts[index] || 1,
+          attemptedThisRound: false
+        });
+        return;
+      }
+
+      // Track attempt for this blank
+      if (!this.attemptCounts[index]) {
+        this.attemptCounts[index] = 0;
+      }
+      this.attemptCounts[index]++;
+
+      const userAnswer = answers[index].trim().toLowerCase();
+      const correctAnswer = blank.originalWord.toLowerCase();
+      const isCorrect = userAnswer === correctAnswer;
+
+      if (isCorrect) {
+        correctCount++;
+        newlyCorrectCount++;
+        this.lockedBlanks.add(index); // Lock this blank
+      } else {
+        retryableIndices.push(index);
+      }
+
+      results.push({
+        blankIndex: index,
+        userAnswer: answers[index],
+        correctAnswer: blank.originalWord,
+        isCorrect,
+        isLocked: isCorrect, // Newly correct answers get locked
+        attemptNumber: this.attemptCounts[index],
+        attemptedThisRound: true
+      });
+    });
+
+    const scorePercentage = Math.round((correctCount / this.blanks.length) * 100);
+    this.score = scorePercentage;
+
+    // Calculate pass requirements based on number of blanks
+    const totalBlanks = this.blanks.length;
+    const requiredCorrect = this.calculateRequiredCorrect(totalBlanks);
+
+    // Check if all blanks are correct
+    const allCorrect = correctCount === totalBlanks;
+
+    // Check if we've exceeded max retries
+    const maxAttemptsReached = Object.values(this.attemptCounts).some(
+      count => count >= this.maxRetries
+    );
+
+    // Determine if user can retry
+    // Can retry if: not all correct, not forced complete, and under max retries
+    const canRetry = !allCorrect && !forceComplete && !maxAttemptsReached;
+
+    // Only finalize (pass/fail) if no retry possible
+    const isFinal = !canRetry;
+    const passed = allCorrect || (correctCount >= requiredCorrect && isFinal);
+
+    // Track if we're advancing level (only on final submission)
+    let justAdvancedLevel = false;
+
+    if (isFinal) {
+      if (passed) {
+        const previousLevel = this.currentLevel;
+        this.currentLevel++;
+        justAdvancedLevel = true;
+      } else {
+      }
+    } else {
+    }
+
+    const snapshot = this.getProgressSnapshot();
+
+    // Update passage tracking (only on final)
+    const stats = this.leaderboardService.getStats();
+    const totalPassagesPassed = (passed && isFinal) ? (stats.totalPassagesPassed + 1) : stats.totalPassagesPassed;
+
+    const resultsData = {
+      correct: correctCount,
+      total: this.blanks.length,
+      percentage: scorePercentage,
+      passed: passed,
+      results,
+      canAdvanceLevel: passed && isFinal,
+      shouldRevealAnswers: isFinal && !passed,
+      requiredCorrect: requiredCorrect,
+      currentLevel: this.currentLevel,
+      justAdvancedLevel: justAdvancedLevel,
+      round: snapshot.round,
+      passagesPassed: totalPassagesPassed,
+      progressText: this.formatProgressText(snapshot),
+      feedbackText: canRetry
+        ? `${correctCount}/${totalBlanks} correct • Retry the highlighted blank${retryableIndices.length > 1 ? 's' : ''}`
+        : this.formatAdvancementText({ passed, correctCount, requiredCorrect, justAdvancedLevel }),
+
+      // Retry system fields
+      canRetry,
+      retryableIndices,
+      isFinal,
+      attemptCounts: { ...this.attemptCounts },
+      lockedIndices: Array.from(this.lockedBlanks),
+      maxRetriesReached: maxAttemptsReached
+    };
+
+    // Update leaderboard stats only on final submission
+    if (isFinal) {
+      this.leaderboardService.updateStats(resultsData);
+    }
+
+    // Store results for potential answer revelation
+    this.lastResults = resultsData;
+
+    return resultsData;
+  }
+
+  /**
+   * Force complete the current passage (skip remaining retries)
+   * Called when user wants to give up and see answers
+   */
+  forceCompletePassage() {
+    return this.submitAnswers(this.userAnswers, true);
+  }
+
+  /**
+   * Check if a specific blank is locked (already correct)
+   */
+  isBlankLocked(blankIndex) {
+    return this.lockedBlanks.has(blankIndex);
+  }
+
+  /**
+   * Get current attempt count for a blank
+   */
+  getAttemptCount(blankIndex) {
+    return this.attemptCounts[blankIndex] || 0;
+  }
+
+  /**
+   * Get analytics data for the current passage attempt
+   * Used by AnalyticsService to record data
+   */
+  getAnalyticsData() {
+    if (!this.currentBook || !this.blanks.length) return null;
+
+    return {
+      bookTitle: this.currentBook.title,
+      bookAuthor: this.currentBook.author,
+      level: this.currentLevel,
+      round: this.currentRound,
+      blanks: this.blanks.map((blank, index) => ({
+        word: blank.originalWord,
+        length: blank.originalWord.length,
+        attemptsToCorrect: this.attemptCounts[index] || 0,
+        finalCorrect: this.lockedBlanks.has(index)
+      }))
+    };
+  }
+
+  // Calculate required correct answers based on total blanks
+  calculateRequiredCorrect(totalBlanks) {
+    if (totalBlanks === 1) {
+      // 1 blank: Must get it correct
+      return 1;
+    } else if (totalBlanks === 2) {
+      // 2 blanks: Need both correct (keeps current Level 6-10 difficulty)
+      return 2;
+    } else {
+      // 3+ blanks: Need all but one (fixes Level 11+ to be harder than Level 10)
+      return totalBlanks - 1;
+    }
+  }
+
+  showAnswers() {
+    return this.blanks.map(blank => ({
+      index: blank.index,
+      word: blank.originalWord
+    }));
+  }
+
+  nextRound() {
+    // Always increment round counter
+    this.currentRound++;
+
+    // Level advancement is now handled in submitAnswers() based on pass/fail
+
+    // Clear chat conversations for new round
+    this.chatService.clearConversations();
+
+    // Clear results since we're moving to new round
+    this.lastResults = null;
+
+    return this.startNewRound();
+  }
+
+  // Get answers for current round (for revelation when switching passages)
+  getCurrentAnswers() {
+    if (!this.lastResults) return null;
+    
+    return {
+      hasResults: true,
+      passed: this.lastResults.passed,
+      shouldRevealAnswers: this.lastResults.shouldRevealAnswers,
+      currentLevel: this.lastResults.currentLevel,
+      requiredCorrect: this.lastResults.requiredCorrect,
+      answers: this.blanks.map(blank => ({
+        index: blank.index,
+        correctAnswer: blank.originalWord,
+        userAnswer: this.lastResults.results[blank.index]?.userAnswer || '',
+        isCorrect: this.lastResults.results[blank.index]?.isCorrect || false
+      }))
+    };
+  }
+
+  // Calculate difficulty of a word based on various factors
+  calculateWordDifficulty(word, position, allWords) {
+    let difficulty = 1;
+    
+    // Length factor
+    if (word.length > 8) difficulty += 2;
+    else if (word.length > 5) difficulty += 1;
+    
+    // Position factor (middle words might be harder)
+    const relativePosition = position / allWords.length;
+    if (relativePosition > 0.3 && relativePosition < 0.7) difficulty += 1;
+    
+    // Complexity factors
+    if (word.includes('ing') || word.includes('ed')) difficulty += 0.5;
+    if (word.includes('tion') || word.includes('sion')) difficulty += 1;
+    
+    // Current level factor
+    difficulty += (this.currentLevel - 1) * 0.5;
+    
+    return Math.min(5, Math.max(1, Math.round(difficulty)));
+  }
+
+  // Simple, clean hint with just essential info based on level
+  generateContextualFallbackHint(word) {
+    if (this.currentLevel <= 2) {
+      return `${word.length} letters, starts with "${word[0]}", ends with "${word[word.length - 1]}"`;
+    } else {
+      return `${word.length} letters, starts with "${word[0]}"`;
+    }
+  }
+
+  // Chat functionality methods
+  async askQuestionAboutBlank(blankIndex, questionType, currentInput = '') {
+    const blankId = `blank_${blankIndex}`;
+    return await this.chatService.askQuestion(blankId, questionType, currentInput);
+  }
+
+  getSuggestedQuestionsForBlank(blankIndex) {
+    const blankId = `blank_${blankIndex}`;
+    return this.chatService.getSuggestedQuestions(blankId);
+  }
+
+
+  // Enhanced render method to include chat buttons
+  renderClozeTextWithChat() {
+    let html = this.clozeText;
+
+    this.blanks.forEach((blank, index) => {
+      const chatButtonId = `chat-btn-${index}`;
+      const inputHtml = `
+        <span class="inline-flex items-center">
+          <input type="text"
+            class="cloze-input"
+            data-blank-index="${index}"
+            placeholder="${'_'.repeat(Math.max(3, blank.originalWord.length))}"
+            style="width: ${Math.max(50, blank.originalWord.length * 10)}px;">
+          <button id="${chatButtonId}"
+            class="chat-button text-blue-500 hover:text-blue-700"
+            data-blank-index="${index}"
+            title="Ask question about this word"
+            style="font-size: 1.5rem; line-height: 1;">
+            💬
+          </button>
+        </span>`;
+
+      html = html.replace(`___BLANK_${index}___`, inputHtml);
+    });
+
+    return html;
+  }
+
+  // Leaderboard integration methods
+  checkForHighScore() {
+    const stats = this.leaderboardService.getStats();
+    return this.leaderboardService.qualifiesForLeaderboard(
+      stats.highestLevel,
+      stats.roundAtHighestLevel,
+      stats.totalPassagesPassed
+    );
+  }
+
+  getHighScoreRank() {
+    const stats = this.leaderboardService.getStats();
+    return this.leaderboardService.getRankForScore(
+      stats.highestLevel,
+      stats.roundAtHighestLevel,
+      stats.totalPassagesPassed
+    );
+  }
+
+  addToLeaderboard(initials) {
+    const stats = this.leaderboardService.getStats();
+    return this.leaderboardService.addEntry(
+      initials,
+      stats.highestLevel,
+      stats.roundAtHighestLevel,
+      stats.totalPassagesPassed
+    );
+  }
+
+  getLeaderboardStats() {
+    return this.leaderboardService.getPlayerStats();
+  }
+}
+
+export default ClozeGame;

src/conversationManager.js

@@ -0,0 +1,165 @@
+// Chat service for contextual, personalized hints
+class ChatService {
+  constructor(aiService) {
+    this.aiService = aiService;
+    this.conversations = new Map(); // blankId -> conversation history
+    this.wordContexts = new Map(); // blankId -> detailed context
+    this.blankQuestions = new Map(); // blankId -> Set of used question types (per-blank tracking)
+    this.currentLevel = 1; // Track current difficulty level
+    
+    // Distinct, non-overlapping question set
+    this.questions = [
+      { text: "What is its part of speech?", type: "part_of_speech" },
+      { text: "What role does it play in the sentence?", type: "sentence_role" },
+      { text: "Is it abstract or a person, place, or thing?", type: "word_category" },
+      { text: "What is a synonym for this word?", type: "synonym" }
+    ];
+  }
+
+  // Initialize chat context for a specific blank
+  initializeWordContext(blankId, wordData) {
+    const context = {
+      blankId,
+      targetWord: wordData.originalWord,
+      sentence: wordData.sentence,
+      fullPassage: wordData.passage,
+      bookTitle: wordData.bookTitle,
+      author: wordData.author,
+      year: wordData.year || null,
+      wordPosition: wordData.wordPosition,
+      difficulty: wordData.difficulty,
+      previousAttempts: [],
+      userQuestions: [],
+      hintLevel: 0 // Progressive hint difficulty
+    };
+    
+    this.wordContexts.set(blankId, context);
+    this.conversations.set(blankId, []);
+    return context;
+  }
+
+  // Per-blank question tracking with level awareness
+  async askQuestion(blankId, questionType, userInput = '') {
+    const context = this.wordContexts.get(blankId);
+    
+    if (!context) {
+      return {
+        error: true,
+        message: "Context not found for this word."
+      };
+    }
+
+    // Mark question as used for this specific blank
+    if (!this.blankQuestions.has(blankId)) {
+      this.blankQuestions.set(blankId, new Set());
+    }
+    this.blankQuestions.get(blankId).add(questionType);
+
+    try {
+      const response = await this.generateSpecificResponse(context, questionType, userInput);
+      return {
+        success: true,
+        response: response,
+        questionType: questionType
+      };
+    } catch (error) {
+      console.error('Chat error:', error);
+      return this.getSimpleFallback(context, questionType);
+    }
+  }
+
+  // Generate specific response based on question type
+  async generateSpecificResponse(context, questionType, userInput) {
+    const word = context.targetWord;
+    const sentence = context.sentence;
+    const bookTitle = context.bookTitle;
+    const author = context.author;
+    
+    // Create sentence with blank for context, but tell AI the actual word
+    const sentenceWithBlank = sentence.replace(new RegExp(`\\b${word}\\b`, 'gi'), '____');
+    
+    try {
+      // Build focused prompt that includes the target word but forbids revealing it
+      const prompt = this.buildFocusedPrompt({
+        ...context,
+        sentence: sentenceWithBlank,
+        targetWord: word
+      }, questionType, userInput);
+      
+      // Use the AI service as a simple API wrapper
+      const aiResponse = await this.aiService.generateContextualHint(prompt);
+      
+      if (aiResponse && typeof aiResponse === 'string' && aiResponse.length > 10) {
+        return aiResponse;
+      }
+    } catch (error) {
+      console.warn('AI response failed:', error);
+    }
+    
+    // Fallback - return simple fallback response
+    return this.getSimpleFallback(context, questionType);
+  }
+
+  // Build focused prompt for specific question types
+  buildFocusedPrompt(context, questionType, userInput) {
+    const { sentence, bookTitle, author, targetWord, year } = context;
+    const yearPrefix = year ? `Published in ${year}, ` : '';
+    const baseContext = `${yearPrefix}from "${bookTitle}" by ${author}: "${sentence}"`;
+    const safetyRule = `Important: The hidden word is "${targetWord}". Never say this word directly - use "it," "this word," or "the word" instead.`;
+    
+    const prompts = {
+      part_of_speech: `${baseContext}\n\n${safetyRule}\n\nIdentify the part of speech and share one interesting grammar tip about this type of word. Keep it conversational and under 25 words.\nExample: "It's a verb! These words show action or states of being, like 'run' or 'exist'."`,
+      
+      sentence_role: `${baseContext}\n\n${safetyRule}\n\nExplain what role this word plays in the sentence - what's its job here? Be specific to THIS sentence. Keep it under 20 words and conversational.\nExample: "Here it connects two ideas, showing how one thing relates to another."`,
+      
+      word_category: `${baseContext}\n\n${safetyRule}\n\nWhat general category does this word belong to? Think broadly - is it about people, things, actions, qualities, feelings, places, or ideas? Explain briefly in under 20 words.\nExample: "This word fits in the 'qualities' category - it describes how something looks or feels."`,
+      
+      synonym: `${baseContext}\n\n${safetyRule}\n\nSuggest a word that could replace it in this sentence. Pick something simple and explain why it works. Under 15 words.\nExample: "You could use 'bright' here - it captures the same feeling of intensity."`
+    };
+    
+    return prompts[questionType] || `${baseContext}\n\n${safetyRule}\n\nProvide a helpful hint about "${targetWord}" without revealing it.`;
+  }
+
+  // Simple fallback responses
+  getSimpleFallback(context, questionType) {
+    const fallbacks = {
+      part_of_speech: "Look at the surrounding words. Is it describing something, showing action, or naming something?",
+      sentence_role: "Consider how this word connects to the other parts of the sentence.",
+      word_category: "Think about whether this represents something concrete or an abstract idea.",
+      synonym: "What other word could fit in this same spot with similar meaning?"
+    };
+    
+    return fallbacks[questionType] || "Consider the context and what word would make sense here.";
+  }
+
+
+  // Clear conversations and reset tracking
+  clearConversations() {
+    this.conversations.clear();
+    this.wordContexts.clear();
+    this.blankQuestions.clear();
+  }
+
+  // Set current level for question selection
+  setLevel(level) {
+    this.currentLevel = level;
+  }
+
+  // Get suggested questions for a specific blank
+  getSuggestedQuestions(blankId) {
+    const usedQuestions = this.blankQuestions.get(blankId) || new Set();
+    
+    return this.questions.map(q => ({
+      ...q,
+      used: usedQuestions.has(q.type)
+    }));
+  }
+
+  // Reset for new game (clears everything including across-game state)
+  resetForNewGame() {
+    this.clearConversations();
+    this.currentLevel = 1;
+  }
+}
+
+export default ChatService;

src/hfLeaderboardAPI.js

@@ -0,0 +1,295 @@
+/**
+ * Leaderboard API Client
+ * Communicates with FastAPI backend (Redis primary, HF Space fallback)
+ * Supports near real-time polling for live updates
+ */
+
+export class HFLeaderboardAPI {
+  constructor(baseUrl = '') {
+    // HF Space URL (used as fallback and for GitHub Pages hosting)
+    const HF_LEADERBOARD_SPACE = 'https://milwright-cloze-leaderboard.hf.space';
+
+    // For local development, use local server
+    // For production (Railway), use same origin (backend serves frontend)
+    // For GitHub Pages, fall back to HF Space
+    const isLocalDev = window.location.hostname === 'localhost' ||
+                       window.location.hostname === '127.0.0.1';
+    const isGitHubPages = window.location.hostname.includes('github.io');
+
+    if (baseUrl) {
+      this.baseUrl = baseUrl;
+    } else if (isLocalDev) {
+      this.baseUrl = window.location.origin;
+    } else if (isGitHubPages) {
+      this.baseUrl = HF_LEADERBOARD_SPACE;
+    } else {
+      // Railway or other hosting: use same origin (FastAPI serves both)
+      this.baseUrl = window.location.origin;
+    }
+
+    // Polling state
+    this.pollInterval = null;
+    this.pollIntervalMs = 5000; // 5 seconds default
+    this.listeners = new Set();
+    this.lastLeaderboard = null;
+  }
+
+  /**
+   * Start polling for leaderboard updates
+   * @param {number} intervalMs - Polling interval in milliseconds (default: 5000)
+   */
+  startPolling(intervalMs = 5000) {
+    if (this.pollInterval) {
+      return;
+    }
+
+    this.pollIntervalMs = intervalMs;
+
+    // Initial fetch
+    this._pollOnce();
+
+    // Set up interval
+    this.pollInterval = setInterval(() => {
+      this._pollOnce();
+    }, intervalMs);
+  }
+
+  /**
+   * Stop polling for updates
+   */
+  stopPolling() {
+    if (this.pollInterval) {
+      clearInterval(this.pollInterval);
+      this.pollInterval = null;
+    }
+  }
+
+  /**
+   * Check if polling is currently active
+   * @returns {boolean}
+   */
+  isPolling() {
+    return this.pollInterval !== null;
+  }
+
+  /**
+   * Subscribe to leaderboard updates
+   * @param {Function} callback - Called with leaderboard data when updates occur
+   * @returns {Function} Unsubscribe function
+   */
+  onUpdate(callback) {
+    this.listeners.add(callback);
+
+    // If we have cached data, call immediately
+    if (this.lastLeaderboard) {
+      callback(this.lastLeaderboard);
+    }
+
+    // Return unsubscribe function
+    return () => {
+      this.listeners.delete(callback);
+    };
+  }
+
+  /**
+   * Internal: Fetch leaderboard and notify listeners if changed
+   */
+  async _pollOnce() {
+    try {
+      const leaderboard = await this.getLeaderboard();
+
+      // Check if data changed (simple JSON comparison)
+      const newData = JSON.stringify(leaderboard);
+      const oldData = JSON.stringify(this.lastLeaderboard);
+
+      if (newData !== oldData) {
+        this.lastLeaderboard = leaderboard;
+        this._notifyListeners(leaderboard);
+      }
+    } catch (error) {
+      // Silent fail for polling - don't spam console
+      console.debug('⏱️ Leaderboard: Poll failed (will retry)', error.message);
+    }
+  }
+
+  /**
+   * Internal: Notify all listeners of leaderboard update
+   */
+  _notifyListeners(leaderboard) {
+    for (const callback of this.listeners) {
+      try {
+        callback(leaderboard);
+      } catch (error) {
+        console.error('⏱️ Leaderboard: Listener error', error);
+      }
+    }
+  }
+
+  /**
+   * Get leaderboard from backend
+   * @returns {Promise<Array>} Array of leaderboard entries
+   */
+  async getLeaderboard() {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/leaderboard`, {
+        method: 'GET',
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      const data = await response.json();
+
+      if (data.success) {
+        console.debug('📥 Leaderboard API: Retrieved', {
+          entries: data.leaderboard.length,
+          message: data.message
+        });
+        return data.leaderboard;
+      } else {
+        throw new Error(data.message || 'Failed to retrieve leaderboard');
+      }
+    } catch (error) {
+      console.error('❌ Leaderboard API: Error fetching:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Add new entry to leaderboard
+   * @param {Object} entry - Leaderboard entry {initials, level, round, passagesPassed, date}
+   * @returns {Promise<Object>} Response object
+   */
+  async addEntry(entry) {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/leaderboard/add`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(entry)
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({ detail: response.statusText }));
+        throw new Error(`HTTP ${response.status}: ${errorData.detail || response.statusText}`);
+      }
+
+      const data = await response.json();
+
+      console.log('✅ Leaderboard API: Entry added', {
+        initials: entry.initials,
+        level: entry.level,
+        message: data.message
+      });
+
+      // Trigger immediate poll to refresh data
+      if (this.pollInterval) {
+        this._pollOnce();
+      }
+
+      return data;
+    } catch (error) {
+      console.error('❌ Leaderboard API: Error adding entry:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Update entire leaderboard
+   * @param {Array} entries - Array of leaderboard entries
+   * @returns {Promise<Object>} Response object
+   */
+  async updateLeaderboard(entries) {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/leaderboard/update`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(entries)
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({ detail: response.statusText }));
+        throw new Error(`HTTP ${response.status}: ${errorData.detail || response.statusText}`);
+      }
+
+      const data = await response.json();
+
+      console.log('✅ Leaderboard API: Updated', {
+        entries: entries.length,
+        message: data.message
+      });
+
+      // Trigger immediate poll to refresh data
+      if (this.pollInterval) {
+        this._pollOnce();
+      }
+
+      return data;
+    } catch (error) {
+      console.error('❌ Leaderboard API: Error updating:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Clear all leaderboard data (admin function)
+   * @returns {Promise<Object>} Response object
+   */
+  async clearLeaderboard() {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/leaderboard/clear`, {
+        method: 'DELETE',
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({ detail: response.statusText }));
+        throw new Error(`HTTP ${response.status}: ${errorData.detail || response.statusText}`);
+      }
+
+      const data = await response.json();
+
+      console.log('✅ Leaderboard API: Cleared', {
+        message: data.message
+      });
+
+      // Trigger immediate poll to refresh data
+      if (this.pollInterval) {
+        this._pollOnce();
+      }
+
+      return data;
+    } catch (error) {
+      console.error('❌ Leaderboard API: Error clearing:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Check if backend is available
+   * @returns {Promise<boolean>} True if backend is reachable
+   */
+  async isAvailable() {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/leaderboard`, {
+        method: 'GET',
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      });
+      return response.ok;
+    } catch (error) {
+      console.warn('⚠️ Leaderboard API: Backend not available, will use localStorage fallback');
+      return false;
+    }
+  }
+}

src/init-env.js

@@ -0,0 +1,14 @@
+// Initialize environment variables from meta tags
+document.addEventListener('DOMContentLoaded', function() {
+    const openrouterMeta = document.querySelector('meta[name="openrouter-key"]');
+    const hfMeta = document.querySelector('meta[name="hf-key"]');
+    
+    if (openrouterMeta && openrouterMeta.content) {
+        window.OPENROUTER_API_KEY = openrouterMeta.content;
+    } else {
+    }
+    
+    if (hfMeta && hfMeta.content) {
+        window.HF_API_KEY = hfMeta.content;
+    }
+});

src/leaderboardService.js

@@ -0,0 +1,429 @@
+/**
+ * Leaderboard Service
+ * Manages high scores, player stats, with HF Hub persistence and localStorage fallback
+ * Following arcade conventions with 3-letter initials and top 10 tracking
+ */
+
+import { HFLeaderboardAPI } from './hfLeaderboardAPI.js';
+
+export class LeaderboardService {
+  constructor() {
+    this.storageKeys = {
+      leaderboard: 'cloze-reader-leaderboard',
+      player: 'cloze-reader-player',
+      stats: 'cloze-reader-stats'
+    };
+
+    this.maxEntries = 10;
+
+    // Initialize HF API client
+    this.hfAPI = new HFLeaderboardAPI();
+    this.useHF = false; // Will be set based on availability check
+
+    // Check HF availability and initialize
+    this.initializeAsync();
+  }
+
+  /**
+   * Async initialization to check HF availability
+   */
+  async initializeAsync() {
+    try {
+      this.useHF = await this.hfAPI.isAvailable();
+    } catch (error) {
+      console.warn('⚠️ LEADERBOARD: HF backend unavailable, using localStorage', error);
+      this.useHF = false;
+    }
+
+    // Reset all data on initialization (fresh start each session)
+    this.resetAll();
+    this.initializeStorage();
+
+    // If HF is available, sync from HF to localStorage
+    if (this.useHF) {
+      await this.syncFromHF();
+    }
+  }
+
+  /**
+   * Sync leaderboard from HF Hub to localStorage
+   */
+  async syncFromHF() {
+    try {
+      const hfLeaderboard = await this.hfAPI.getLeaderboard();
+      if (hfLeaderboard && hfLeaderboard.length > 0) {
+        this.saveLeaderboard(hfLeaderboard);
+      }
+    } catch (error) {
+      console.error('❌ LEADERBOARD: Failed to sync from HF', error);
+    }
+  }
+
+  /**
+   * Initialize localStorage with default values if needed
+   */
+  initializeStorage() {
+    if (!this.getLeaderboard()) {
+      this.saveLeaderboard([]);
+    }
+
+    if (!this.getPlayerProfile()) {
+      this.savePlayerProfile({
+        initials: null,
+        hasEnteredInitials: false,
+        gamesPlayed: 0,
+        lastPlayed: null
+      });
+    }
+
+    if (!this.getStats()) {
+      this.saveStats(this.createEmptyStats());
+    }
+  }
+
+  /**
+   * Create empty stats object
+   */
+  createEmptyStats() {
+    return {
+      highestLevel: 1,
+      roundAtHighestLevel: 1,
+      totalPassagesPassed: 0,
+      totalPassagesAttempted: 0,
+      longestStreak: 0,
+      currentStreak: 0,
+      totalCorrectWords: 0,
+      uniqueWordsCorrect: new Set(),
+      gamesPlayed: 0,
+      lastPlayed: null
+    };
+  }
+
+  /**
+   * Get leaderboard from localStorage
+   */
+  getLeaderboard() {
+    try {
+      const data = localStorage.getItem(this.storageKeys.leaderboard);
+      return data ? JSON.parse(data) : null;
+    } catch (e) {
+      console.error('Error reading leaderboard:', e);
+      return [];
+    }
+  }
+
+  /**
+   * Save leaderboard to localStorage
+   */
+  saveLeaderboard(entries) {
+    try {
+      localStorage.setItem(this.storageKeys.leaderboard, JSON.stringify(entries));
+    } catch (e) {
+      console.error('Error saving leaderboard:', e);
+    }
+  }
+
+  /**
+   * Get player profile from localStorage
+   */
+  getPlayerProfile() {
+    try {
+      const data = localStorage.getItem(this.storageKeys.player);
+      return data ? JSON.parse(data) : null;
+    } catch (e) {
+      console.error('Error reading player profile:', e);
+      return null;
+    }
+  }
+
+  /**
+   * Save player profile to localStorage
+   */
+  savePlayerProfile(profile) {
+    try {
+      localStorage.setItem(this.storageKeys.player, JSON.stringify(profile));
+    } catch (e) {
+      console.error('Error saving player profile:', e);
+    }
+  }
+
+  /**
+   * Get stats from localStorage
+   */
+  getStats() {
+    try {
+      const data = localStorage.getItem(this.storageKeys.stats);
+      if (!data) return null;
+
+      const stats = JSON.parse(data);
+      // Convert uniqueWordsCorrect back to Set
+      if (stats.uniqueWordsCorrect && Array.isArray(stats.uniqueWordsCorrect)) {
+        stats.uniqueWordsCorrect = new Set(stats.uniqueWordsCorrect);
+      } else {
+        stats.uniqueWordsCorrect = new Set();
+      }
+      return stats;
+    } catch (e) {
+      console.error('Error reading stats:', e);
+      return null;
+    }
+  }
+
+  /**
+   * Save stats to localStorage
+   */
+  saveStats(stats) {
+    try {
+      // Convert Set to Array for JSON serialization
+      const statsToSave = {
+        ...stats,
+        uniqueWordsCorrect: Array.from(stats.uniqueWordsCorrect || [])
+      };
+      localStorage.setItem(this.storageKeys.stats, JSON.stringify(statsToSave));
+    } catch (e) {
+      console.error('Error saving stats:', e);
+    }
+  }
+
+  /**
+   * Validate and sanitize initials (3 letters, A-Z only)
+   */
+  validateInitials(initials) {
+    if (!initials || typeof initials !== 'string') {
+      return false;
+    }
+
+    const sanitized = initials.toUpperCase().replace(/[^A-Z]/g, '');
+    return sanitized.length === 3 ? sanitized : false;
+  }
+
+  /**
+   * Sort leaderboard entries
+   * Primary: Level (desc), Secondary: Round (desc), Tertiary: Passages passed (desc)
+   */
+  sortLeaderboard(entries) {
+    return entries.sort((a, b) => {
+      // Primary: Level (higher is better)
+      if (b.level !== a.level) {
+        return b.level - a.level;
+      }
+
+      // Secondary: Round at that level (higher is better)
+      if (b.round !== a.round) {
+        return b.round - a.round;
+      }
+
+      // Tertiary: Total passages passed (higher is better)
+      if (b.passagesPassed !== a.passagesPassed) {
+        return b.passagesPassed - a.passagesPassed;
+      }
+
+      // Quaternary: Date (newer is better)
+      return new Date(b.date) - new Date(a.date);
+    });
+  }
+
+  /**
+   * Check if a score qualifies for the leaderboard
+   */
+  qualifiesForLeaderboard(level, round, passagesPassed) {
+    const leaderboard = this.getLeaderboard();
+
+    // If leaderboard isn't full, always qualifies
+    if (leaderboard.length < this.maxEntries) {
+      return true;
+    }
+
+    // Check if better than lowest entry
+    const lowestEntry = leaderboard[leaderboard.length - 1];
+
+    if (level > lowestEntry.level) return true;
+    if (level === lowestEntry.level && round > lowestEntry.round) return true;
+    if (level === lowestEntry.level && round === lowestEntry.round && passagesPassed > lowestEntry.passagesPassed) return true;
+
+    return false;
+  }
+
+  /**
+   * Get the rank position for a score (1-10, or null if doesn't qualify)
+   */
+  getRankForScore(level, round, passagesPassed) {
+    if (!this.qualifiesForLeaderboard(level, round, passagesPassed)) {
+      return null;
+    }
+
+    const leaderboard = this.getLeaderboard();
+    const tempEntry = { level, round, passagesPassed, date: new Date().toISOString() };
+    const tempLeaderboard = [...leaderboard, tempEntry];
+    const sorted = this.sortLeaderboard(tempLeaderboard);
+
+    return sorted.findIndex(entry => entry === tempEntry) + 1;
+  }
+
+  /**
+   * Add a new entry to the leaderboard
+   */
+  async addEntry(initials, level, round, passagesPassed) {
+    const validInitials = this.validateInitials(initials);
+    if (!validInitials) {
+      console.error('Invalid initials:', initials);
+      return false;
+    }
+
+    const leaderboard = this.getLeaderboard();
+    const newEntry = {
+      initials: validInitials,
+      level,
+      round,
+      passagesPassed,
+      date: new Date().toISOString()
+    };
+
+    leaderboard.push(newEntry);
+    const sorted = this.sortLeaderboard(leaderboard);
+
+    // Keep only top 10
+    const trimmed = sorted.slice(0, this.maxEntries);
+    this.saveLeaderboard(trimmed);
+
+    const rank = sorted.findIndex(entry => entry === newEntry) + 1;
+
+    // If HF is available, also save to HF Hub
+    if (this.useHF) {
+      try {
+        await this.hfAPI.addEntry(newEntry);
+      } catch (error) {
+        console.error('❌ LEADERBOARD: Failed to save to HF, localStorage only', error);
+      }
+    }
+
+    return rank; // Return rank
+  }
+
+  /**
+   * Update session stats after a passage attempt
+   */
+  updateStats(data) {
+    const stats = this.getStats() || this.createEmptyStats();
+
+    console.log('📊 LEADERBOARD: Updating stats', {
+      before: { attempted: stats.totalPassagesAttempted, passed: stats.totalPassagesPassed, level: stats.highestLevel },
+      passResult: data.passed,
+      currentLevel: data.currentLevel
+    });
+
+    stats.totalPassagesAttempted++;
+
+    if (data.passed) {
+      stats.totalPassagesPassed++;
+      
+      // Break streak if user had to retry (any blank took more than 1 attempt)
+      const hadToRetry = data.attemptCounts && Object.values(data.attemptCounts).some(count => count > 1);
+      
+      if (hadToRetry) {
+        // Passed but had to retry - break streak
+        stats.currentStreak = 0;
+      } else {
+        // Passed on first attempt - continue streak
+        stats.currentStreak++;
+        stats.longestStreak = Math.max(stats.longestStreak, stats.currentStreak);
+      }
+    } else {
+      stats.currentStreak = 0;
+    }
+
+    // Track highest level reached
+    if (data.currentLevel > stats.highestLevel) {
+      stats.highestLevel = data.currentLevel;
+      stats.roundAtHighestLevel = data.round;
+    } else if (data.currentLevel === stats.highestLevel) {
+      stats.roundAtHighestLevel = Math.max(stats.roundAtHighestLevel, data.round);
+    }
+
+    // Track correct words
+    if (data.results) {
+      data.results.forEach(result => {
+        if (result.isCorrect) {
+          stats.totalCorrectWords++;
+          const word = result.correctAnswer.toLowerCase();
+          stats.uniqueWordsCorrect.add(word);
+        }
+      });
+    }
+
+    stats.lastPlayed = new Date().toISOString();
+
+    console.log('📊 LEADERBOARD: Stats updated', {
+      after: { attempted: stats.totalPassagesAttempted, passed: stats.totalPassagesPassed, level: stats.highestLevel }
+    });
+
+    this.saveStats(stats);
+    return stats;
+  }
+
+  /**
+   * Get formatted leaderboard for display
+   */
+  getFormattedLeaderboard() {
+    const leaderboard = this.getLeaderboard();
+    const player = this.getPlayerProfile();
+    const stats = this.getStats();
+
+    return {
+      entries: leaderboard.map((entry, index) => ({
+        rank: index + 1,
+        initials: entry.initials,
+        level: entry.level,
+        round: entry.round,
+        passagesPassed: entry.passagesPassed,
+        date: entry.date,
+        isPlayer: player && player.initials === entry.initials
+      })),
+      playerBest: stats ? {
+        level: stats.highestLevel,
+        round: stats.roundAtHighestLevel,
+        passagesPassed: stats.totalPassagesPassed
+      } : null,
+      playerInitials: player ? player.initials : null
+    };
+  }
+
+  /**
+   * Reset all leaderboard data (fresh start each session)
+   */
+  resetAll() {
+    this.saveLeaderboard([]);
+    this.savePlayerProfile({
+      initials: null,
+      hasEnteredInitials: false,
+      gamesPlayed: 0,
+      lastPlayed: null
+    });
+    this.saveStats(this.createEmptyStats());
+  }
+
+  /**
+   * Get player stats summary
+   */
+  getPlayerStats() {
+    const stats = this.getStats() || this.createEmptyStats();
+    const profile = this.getPlayerProfile();
+
+    return {
+      initials: profile?.initials || '---',
+      highestLevel: stats.highestLevel,
+      roundAtHighestLevel: stats.roundAtHighestLevel,
+      totalPassagesPassed: stats.totalPassagesPassed,
+      totalPassagesAttempted: stats.totalPassagesAttempted,
+      successRate: stats.totalPassagesAttempted > 0
+        ? Math.round((stats.totalPassagesPassed / stats.totalPassagesAttempted) * 100)
+        : 0,
+      longestStreak: stats.longestStreak,
+      currentStreak: stats.currentStreak,
+      totalCorrectWords: stats.totalCorrectWords,
+      uniqueWords: stats.uniqueWordsCorrect.size,
+      gamesPlayed: stats.gamesPlayed,
+      lastPlayed: stats.lastPlayed
+    };
+  }
+}

src/leaderboardUI.js

@@ -0,0 +1,590 @@
+/**
+ * Leaderboard UI
+ * Modal display and initials entry interface
+ * Following arcade conventions with vintage aesthetic
+ * Supports near real-time updates via polling
+ */
+
+export class LeaderboardUI {
+  constructor(leaderboardService) {
+    this.service = leaderboardService;
+    this.modal = null;
+    this.initialsModal = null;
+    this.currentSlot = 0;
+    this.initials = ['A', 'A', 'A'];
+    this.onInitialsSubmit = null;
+    this.canSubmitInitials = false; // Prevent accidental immediate submission
+    this.pollUnsubscribe = null; // Cleanup function for polling subscription
+  }
+
+  /**
+   * Show the leaderboard modal
+   */
+  show() {
+    // Remove existing modal if any
+    this.hide();
+
+    const data = this.service.getFormattedLeaderboard();
+    const playerStats = this.service.getPlayerStats();
+
+    // Create modal HTML
+    this.modal = document.createElement('div');
+    this.modal.className = 'leaderboard-overlay';
+    this.modal.innerHTML = `
+      <div class="leaderboard-modal">
+        <div class="leaderboard-header">
+          <h2 class="leaderboard-title">High Scores</h2>
+          <span class="leaderboard-live-indicator" title="Live updates enabled">●</span>
+          <button class="leaderboard-close" aria-label="Close leaderboard">×</button>
+        </div>
+
+        <div class="leaderboard-content">
+          <div class="leaderboard-list">
+            ${this.generateLeaderboardHTML(data.entries, data.playerInitials)}
+          </div>
+
+          ${playerStats.highestLevel > 1 ? `
+            <div class="leaderboard-player-stats">
+              <div class="player-best">
+                Your Best: <span class="highlight">Level ${playerStats.highestLevel}</span>
+              </div>
+              <div class="player-stats-details">
+                <div>Passages: ${playerStats.totalPassagesPassed}/${playerStats.totalPassagesAttempted} (${playerStats.successRate}%)</div>
+                <div>Longest Streak: ${playerStats.longestStreak}</div>
+              </div>
+            </div>
+          ` : ''}
+        </div>
+      </div>
+    `;
+
+    document.body.appendChild(this.modal);
+
+    // Animate in
+    requestAnimationFrame(() => {
+      this.modal.classList.add('visible');
+    });
+
+    // Add event listeners
+    this.modal.querySelector('.leaderboard-close').addEventListener('click', () => this.hide());
+
+    // Prevent clicks inside modal content from closing
+    this.modal.querySelector('.leaderboard-modal').addEventListener('click', (e) => {
+      e.stopPropagation();
+    });
+
+    // Close on backdrop click
+    this.modal.addEventListener('click', (e) => {
+      if (e.target === this.modal) {
+        this.hide();
+      }
+    });
+
+    // ESC key to close
+    this.escHandler = (e) => {
+      if (e.key === 'Escape') {
+        this.hide();
+      }
+    };
+    document.addEventListener('keydown', this.escHandler);
+
+    // Start polling for live updates
+    this.startPolling();
+  }
+
+  /**
+   * Start polling for live leaderboard updates
+   */
+  startPolling() {
+    // Only poll if HF API is available via service
+    if (this.service.hfAPI && this.service.useHF) {
+      // Subscribe to updates
+      this.pollUnsubscribe = this.service.hfAPI.onUpdate((leaderboard) => {
+        this.handleLeaderboardUpdate(leaderboard);
+      });
+
+      // Start the polling (5 second interval)
+      this.service.hfAPI.startPolling(5000);
+
+    }
+  }
+
+  /**
+   * Stop polling for updates
+   */
+  stopPolling() {
+    if (this.pollUnsubscribe) {
+      this.pollUnsubscribe();
+      this.pollUnsubscribe = null;
+    }
+
+    if (this.service.hfAPI) {
+      this.service.hfAPI.stopPolling();
+    }
+
+  }
+
+  /**
+   * Handle incoming leaderboard update from polling
+   */
+  handleLeaderboardUpdate(leaderboard) {
+    // Update localStorage with new data
+    this.service.saveLeaderboard(leaderboard);
+
+    // Re-render the leaderboard list if modal is open
+    if (this.modal) {
+      const data = this.service.getFormattedLeaderboard();
+      const listContainer = this.modal.querySelector('.leaderboard-list');
+
+      if (listContainer) {
+        listContainer.innerHTML = this.generateLeaderboardHTML(data.entries, data.playerInitials);
+
+        // Flash the live indicator to show update received
+        const indicator = this.modal.querySelector('.leaderboard-live-indicator');
+        if (indicator) {
+          indicator.classList.add('pulse');
+          setTimeout(() => indicator.classList.remove('pulse'), 500);
+        }
+
+      }
+    }
+  }
+
+  /**
+   * Generate HTML for leaderboard entries
+   */
+  generateLeaderboardHTML(entries, playerInitials) {
+    if (entries.length === 0) {
+      return `
+        <div class="leaderboard-empty">
+          <p>No high scores yet!</p>
+          <p class="text-sm">Be the first to reach Level 2!</p>
+        </div>
+      `;
+    }
+
+    return entries.map(entry => {
+      const rankClass = this.getRankClass(entry.rank);
+      const isPlayer = entry.initials === playerInitials;
+      const playerClass = isPlayer ? 'player-entry' : '';
+
+      return `
+        <div class="leaderboard-entry ${rankClass} ${playerClass}">
+          <span class="entry-rank">#${entry.rank}</span>
+          <span class="entry-initials">${entry.initials}</span>
+          <span class="entry-score">Level ${entry.level}</span>
+        </div>
+      `;
+    }).join('');
+  }
+
+  /**
+   * Get CSS class for rank-based styling
+   */
+  getRankClass(rank) {
+    if (rank === 1) return 'rank-gold';
+    if (rank === 2 || rank === 3) return 'rank-silver';
+    return 'rank-standard';
+  }
+
+  /**
+   * Hide the leaderboard modal
+   */
+  hide() {
+    // Stop polling when modal closes
+    this.stopPolling();
+
+    if (this.modal) {
+      this.modal.classList.remove('visible');
+      setTimeout(() => {
+        if (this.modal && this.modal.parentNode) {
+          this.modal.parentNode.removeChild(this.modal);
+        }
+        this.modal = null;
+      }, 300);
+    }
+
+    if (this.escHandler) {
+      document.removeEventListener('keydown', this.escHandler);
+      this.escHandler = null;
+    }
+  }
+
+  /**
+   * Show initials entry screen for new high score
+   */
+  showInitialsEntry(level, round, rank, onSubmit) {
+    // Store callback
+    this.onInitialsSubmit = onSubmit;
+
+    // Reset initials state
+    this.currentSlot = 0;
+    this.canSubmitInitials = false; // Disable submission until user has had time to interact
+
+    // Get existing player initials if available
+    const profile = this.service.getPlayerProfile();
+    if (profile && profile.initials) {
+      this.initials = profile.initials.split('');
+    } else {
+      this.initials = ['A', 'A', 'A'];
+    }
+
+    // Remove existing modal
+    this.hideInitialsEntry();
+
+    // Create modal HTML
+    this.initialsModal = document.createElement('div');
+    this.initialsModal.className = 'leaderboard-overlay initials-overlay';
+    this.initialsModal.innerHTML = `
+      <div class="initials-modal">
+        <div class="initials-header">
+          <h2 class="initials-title">New High Score</h2>
+          <div class="initials-achievement">
+            You reached <span class="highlight">Level ${level}</span>
+            <br>
+            <span class="rank-text">${this.getRankText(rank)}</span>
+          </div>
+        </div>
+
+        <div class="initials-content">
+          <p class="initials-prompt">Enter or update your initials:</p>
+
+          <!-- Text Input Method -->
+          <div class="text-input-section">
+            <input type="text" id="initials-text-input" class="initials-text-input" maxlength="3" value="${this.initials.join('')}" placeholder="ABC">
+            <p class="input-help">Type your 3-letter initials directly</p>
+          </div>
+
+          <!-- Divider -->
+          <div class="input-divider">
+            <span>or use arcade controls</span>
+          </div>
+
+          <!-- Arcade Style Method -->
+          <div class="initials-slots">
+            ${this.initials.map((letter, index) => `
+              <div class="initial-slot ${index === 0 ? 'active' : ''}" data-slot="${index}">
+                <div class="slot-letter">${letter}</div>
+                <div class="slot-arrows">
+                  <button class="arrow-up" data-slot="${index}" data-direction="up" aria-label="Increase letter">▲</button>
+                  <button class="arrow-down" data-slot="${index}" data-direction="down" aria-label="Decrease letter">▼</button>
+                </div>
+              </div>
+            `).join('')}
+          </div>
+
+          <div class="initials-instructions">
+            <p>Use arrow keys ↑↓ to change letters</p>
+            <p>Press Tab or ←→ to move between slots</p>
+            <p>Press Enter to submit</p>
+          </div>
+
+          <button class="initials-submit typewriter-button">
+            Submit
+          </button>
+        </div>
+      </div>
+    `;
+
+    document.body.appendChild(this.initialsModal);
+
+    // Animate in
+    requestAnimationFrame(() => {
+      this.initialsModal.classList.add('visible');
+    });
+
+    // Add event listeners with a delay to prevent Enter key from passage submission
+    // from immediately triggering the modal's submit handler
+    setTimeout(() => {
+      this.setupInitialsEventListeners();
+      // Focus the text input for easier typing
+      const textInput = this.initialsModal.querySelector('#initials-text-input');
+      if (textInput) {
+        textInput.focus();
+        textInput.select(); // Select all text for easy overwriting
+      }
+      // Enable submission after a longer delay to ensure user has time to interact
+      setTimeout(() => {
+        this.canSubmitInitials = true;
+      }, 300);
+    }, 100);
+  }
+
+  /**
+   * Get rank description text
+   */
+  getRankText(rank) {
+    const ordinal = this.getOrdinal(rank);
+    if (rank === 1) return `${ordinal} place - Top Score`;
+    if (rank === 2) return `${ordinal} place`;
+    if (rank === 3) return `${ordinal} place`;
+    return `${ordinal} place on the leaderboard`;
+  }
+
+  /**
+   * Get ordinal suffix for rank (1st, 2nd, 3rd, etc.)
+   */
+  getOrdinal(n) {
+    const s = ['th', 'st', 'nd', 'rd'];
+    const v = n % 100;
+    return n + (s[(v - 20) % 10] || s[v] || s[0]);
+  }
+
+  /**
+   * Setup event listeners for initials entry
+   */
+  setupInitialsEventListeners() {
+    // Text input field
+    const textInput = this.initialsModal.querySelector('#initials-text-input');
+    textInput.addEventListener('input', (e) => {
+      const value = e.target.value.toUpperCase().slice(0, 3);
+      e.target.value = value;
+      
+      // Update arcade slots to match text input
+      this.updateInitialsFromText(value);
+    });
+
+    // Arrow buttons
+    this.initialsModal.querySelectorAll('.arrow-up, .arrow-down').forEach(button => {
+      button.addEventListener('click', (e) => {
+        const slot = parseInt(e.target.dataset.slot);
+        const direction = e.target.dataset.direction;
+        this.changeInitialLetter(slot, direction === 'up' ? 1 : -1);
+      });
+    });
+
+    // Slot clicking to select
+    this.initialsModal.querySelectorAll('.initial-slot').forEach(slot => {
+      slot.addEventListener('click', (e) => {
+        if (!e.target.closest('.arrow-up') && !e.target.closest('.arrow-down')) {
+          const slotIndex = parseInt(slot.dataset.slot);
+          this.selectSlot(slotIndex);
+        }
+      });
+    });
+
+    // Submit button
+    this.initialsModal.querySelector('.initials-submit').addEventListener('click', () => {
+      this.submitInitials();
+    });
+
+    // Keyboard controls
+    this.initialsKeyHandler = (e) => {
+      // If focus is on text input, handle differently
+      if (e.target.id === 'initials-text-input') {
+        switch(e.key) {
+          case 'Enter':
+            e.preventDefault();
+            this.submitInitials();
+            break;
+          case 'Escape':
+            e.preventDefault();
+            this.hideInitialsEntry();
+            break;
+        }
+        return;
+      }
+
+      // Arcade controls when not focused on text input
+      switch(e.key) {
+        case 'ArrowUp':
+          e.preventDefault();
+          this.changeInitialLetter(this.currentSlot, 1);
+          break;
+        case 'ArrowDown':
+          e.preventDefault();
+          this.changeInitialLetter(this.currentSlot, -1);
+          break;
+        case 'ArrowLeft':
+          e.preventDefault();
+          this.selectSlot(Math.max(0, this.currentSlot - 1));
+          break;
+        case 'ArrowRight':
+        case 'Tab':
+          e.preventDefault();
+          this.selectSlot(Math.min(2, this.currentSlot + 1));
+          break;
+        case 'Enter':
+          e.preventDefault();
+          this.submitInitials();
+          break;
+        case 'Escape':
+          e.preventDefault();
+          this.hideInitialsEntry();
+          break;
+      }
+    };
+    document.addEventListener('keydown', this.initialsKeyHandler);
+
+    // Prevent modal close on backdrop click for initials entry
+    this.initialsModal.addEventListener('click', (e) => {
+      e.stopPropagation();
+    });
+  }
+
+  /**
+   * Change letter in current slot
+   */
+  changeInitialLetter(slot, delta) {
+    const currentChar = this.initials[slot].charCodeAt(0);
+    let newChar = currentChar + delta;
+
+    // Wrap around A-Z
+    if (newChar > 90) newChar = 65; // After Z, go to A
+    if (newChar < 65) newChar = 90; // Before A, go to Z
+
+    this.initials[slot] = String.fromCharCode(newChar);
+    this.updateInitialsDisplay();
+    this.updateTextFromInitials();
+  }
+
+  /**
+   * Select a specific slot
+   */
+  selectSlot(slot) {
+    this.currentSlot = slot;
+    this.initialsModal.querySelectorAll('.initial-slot').forEach((el, index) => {
+      el.classList.toggle('active', index === slot);
+    });
+  }
+
+  /**
+   * Update arcade slots from text input
+   */
+  updateInitialsFromText(text) {
+    // Pad with 'A' if less than 3 characters
+    const paddedText = text.padEnd(3, 'A');
+    this.initials = paddedText.split('');
+    this.updateInitialsDisplay();
+  }
+
+  /**
+   * Update text input from arcade slots
+   */
+  updateTextFromInitials() {
+    const textInput = this.initialsModal.querySelector('#initials-text-input');
+    if (textInput) {
+      textInput.value = this.initials.join('');
+    }
+  }
+
+  /**
+   * Update the visual display of initials
+   */
+  updateInitialsDisplay() {
+    this.initialsModal.querySelectorAll('.initial-slot').forEach((slot, index) => {
+      slot.querySelector('.slot-letter').textContent = this.initials[index];
+    });
+  }
+
+  /**
+   * Submit initials and save to leaderboard
+   */
+  submitInitials() {
+    // Prevent accidental immediate submission
+    if (!this.canSubmitInitials) {
+      return;
+    }
+
+    const initialsString = this.initials.join('');
+
+    // Save to player profile
+    const profile = this.service.getPlayerProfile();
+    profile.initials = initialsString;
+    profile.hasEnteredInitials = true;
+    this.service.savePlayerProfile(profile);
+
+    // Call the callback
+    if (this.onInitialsSubmit) {
+      this.onInitialsSubmit(initialsString);
+    }
+
+    // Hide modal
+    this.hideInitialsEntry();
+
+    // Show success message briefly, then show leaderboard
+    this.showSuccessMessage(() => {
+      this.show();
+    });
+  }
+
+  /**
+   * Hide initials entry modal
+   */
+  hideInitialsEntry() {
+    if (this.initialsModal) {
+      this.initialsModal.classList.remove('visible');
+      setTimeout(() => {
+        if (this.initialsModal && this.initialsModal.parentNode) {
+          this.initialsModal.parentNode.removeChild(this.initialsModal);
+        }
+        this.initialsModal = null;
+      }, 300);
+    }
+
+    if (this.initialsKeyHandler) {
+      document.removeEventListener('keydown', this.initialsKeyHandler);
+      this.initialsKeyHandler = null;
+    }
+  }
+
+  /**
+   * Show success message after submitting initials
+   */
+  showSuccessMessage(onComplete) {
+    const successDiv = document.createElement('div');
+    successDiv.className = 'leaderboard-overlay visible';
+    successDiv.innerHTML = `
+      <div class="leaderboard-modal success-message">
+        <div class="success-content">
+          <h2>Score Saved</h2>
+          <p>Your initials have been added to the leaderboard</p>
+        </div>
+      </div>
+    `;
+
+    document.body.appendChild(successDiv);
+
+    setTimeout(() => {
+      successDiv.classList.remove('visible');
+      setTimeout(() => {
+        if (successDiv.parentNode) {
+          successDiv.parentNode.removeChild(successDiv);
+        }
+        if (onComplete) {
+          onComplete();
+        }
+      }, 300);
+    }, 1500);
+  }
+
+  /**
+   * Show notification toast for milestone achievement
+   */
+  showMilestoneNotification(level) {
+    const toast = document.createElement('div');
+    toast.className = 'milestone-toast';
+    toast.innerHTML = `
+      <div class="toast-content">
+        Milestone Reached: Level ${level}
+      </div>
+    `;
+
+    document.body.appendChild(toast);
+
+    // Animate in
+    requestAnimationFrame(() => {
+      toast.classList.add('visible');
+    });
+
+    // Auto-hide after 3 seconds
+    setTimeout(() => {
+      toast.classList.remove('visible');
+      setTimeout(() => {
+        if (toast.parentNode) {
+          toast.parentNode.removeChild(toast);
+        }
+      }, 300);
+    }, 3000);
+  }
+}

src/styles.css

@@ -0,0 +1,1242 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* Chat functionality styles */
+.typing-dots span {
+  animation: typing 1.5s infinite;
+}
+
+.typing-dots span:nth-child(2) {
+  animation-delay: 0.5s;
+}
+
+.typing-dots span:nth-child(3) {
+  animation-delay: 1s;
+}
+
+@keyframes typing {
+  0%, 60%, 100% { opacity: 0.3; }
+  30% { opacity: 1; }
+}
+
+.chat-button {
+  transition: all 0.2s ease;
+  border-radius: 4px;
+  padding: 4px 6px;
+  font-size: 1.5rem;
+  vertical-align: middle;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 32px;
+  min-height: 32px;
+}
+
+.chat-button:hover {
+  background-color: rgba(59, 130, 246, 0.1);
+  transform: scale(1.15);
+}
+
+/* Responsive sizing for mobile */
+@media (max-width: 640px) {
+  .chat-button {
+    font-size: 1.25rem;
+    min-width: 28px;
+    min-height: 28px;
+  }
+}
+
+/* Larger screens get bigger icons */
+@media (min-width: 1024px) {
+  .chat-button {
+    font-size: 1.75rem;
+    min-width: 36px;
+    min-height: 36px;
+  }
+}
+
+/* Chat modal styling to match game font */
+#chat-modal {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+}
+
+#chat-modal .bg-white {
+  background-color: var(--aged-paper-light);
+  border: 2px solid rgba(0, 0, 0, 0.1);
+}
+
+#chat-modal h3 {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+  color: var(--typewriter-ink);
+  font-weight: 600;
+}
+
+#chat-messages {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+  color: var(--typewriter-ink);
+  line-height: 1.6;
+}
+
+#chat-messages .text-gray-500 {
+  color: #666 !important;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+}
+
+.suggestion-btn, .question-btn {
+  transition: all 0.2s ease;
+  padding: 14px 18px;
+  background: #f8f9fa;
+  border: 2px solid #e9ecef;
+  border-radius: 8px;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+  font-size: 15px;
+  font-weight: 500;
+  text-align: center;
+  cursor: pointer;
+  line-height: 1.4;
+  min-height: 64px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  box-sizing: border-box;
+}
+
+.suggestion-btn:hover, .question-btn:hover:not(:disabled) {
+  background: #e9ecef;
+  border-color: #6c757d;
+  transform: translateY(-1px);
+}
+
+.suggestion-btn:disabled, .question-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  background: #f8f9fa;
+}
+
+/* Answer revelation styles */
+.revealed-answer {
+  background-color: #fef3c7 !important;
+  font-weight: bold !important;
+  color: #92400e !important;
+  border: 2px solid #f59e0b !important;
+}
+
+/* Correct and incorrect answer styles */
+
+/* Welcome overlay styles */
+.welcome-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background: rgba(0, 0, 0, 0.8);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+  opacity: 0;
+  transition: opacity 0.3s ease;
+}
+
+.welcome-modal {
+  background: white;
+  border-radius: 12px;
+  padding: 24px;
+  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.3);
+  max-height: 80vh;
+  overflow-y: auto;
+}
+
+.welcome-title {
+  margin: 0 0 16px 0;
+  color: #1f2937;
+  font-size: 22px;
+  font-weight: 600;
+}
+
+.welcome-content {
+  text-align: left;
+  color: #4b5563;
+  line-height: 1.4;
+  margin-bottom: 20px;
+  font-size: 14px;
+}
+
+.welcome-content p {
+  margin: 0 0 12px 0;
+}
+
+.welcome-overlay .typewriter-button {
+  background: #1f2937;
+  color: white;
+  border: 2px solid #374151;
+  padding: 8px 14px;
+  font-weight: 600;
+  font-size: 14px;
+  min-width: 100px;
+  min-height: 36px;
+  transition: all 0.2s ease;
+}
+
+.welcome-overlay .typewriter-button:hover {
+  background: #374151;
+  border-color: #4b5563;
+  transform: translateY(-1px);
+}
+.cloze-input.correct {
+  background-color: #dcfce7 !important;
+  border-color: #16a34a !important;
+  color: #15803d !important;
+  font-weight: bold !important;
+}
+
+.cloze-input.incorrect {
+  background-color: #fef2f2 !important;
+  border-color: #dc2626 !important;
+  color: #dc2626 !important;
+  font-weight: bold !important;
+}
+
+.cloze-input:disabled {
+  opacity: 0.8;
+  cursor: not-allowed;
+}
+
+/* Custom typewriter color scheme */
+:root {
+  --aged-paper: #faf7f0;
+  --aged-paper-dark: #f5f1e8;
+  --aged-paper-light: #fefcf7;
+  --typewriter-ink: #2c2c2c;
+  --typewriter-ribbon: #8b5cf6;
+  --paper-shadow: rgba(0, 0, 0, 0.08);
+}
+
+@layer base {
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+    background-color: var(--aged-paper);
+    color: var(--typewriter-ink);
+    line-height: 1.6;
+    font-size: 16px;
+    background-image: 
+      radial-gradient(circle at 25% 25%, rgba(139, 92, 246, 0.02) 0%, transparent 50%),
+      radial-gradient(circle at 75% 75%, rgba(139, 92, 246, 0.02) 0%, transparent 50%);
+  }
+}
+
+@layer components {
+  .typewriter-text {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+    color: var(--typewriter-ink);
+    font-weight: 600;
+    line-height: 1.7;
+  }
+
+  .typewriter-subtitle {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+    color: #666;
+    font-size: 1rem;
+    line-height: 1.5;
+  }
+
+  .paper-sheet {
+    background-color: var(--aged-paper-light);
+    border: 1px solid rgba(139, 92, 246, 0.1);
+    box-shadow: 
+      0 2px 8px var(--paper-shadow),
+      inset 0 1px 0 rgba(255, 255, 255, 0.5);
+    position: relative;
+  }
+
+  .paper-sheet::before {
+    content: '';
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    background: repeating-linear-gradient(
+      to bottom,
+      transparent,
+      transparent 23px,
+      rgba(139, 92, 246, 0.03) 23px,
+      rgba(139, 92, 246, 0.03) 24px
+    );
+    pointer-events: none;
+    z-index: 1;
+  }
+
+  .paper-content {
+    position: relative;
+    z-index: 2;
+  }
+
+  .cloze-input {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+    background-color: transparent;
+    border: none;
+    border-bottom: 2px dotted black;
+    color: var(--typewriter-ink);
+    text-align: center;
+    outline: none;
+    padding: 3px 4px;
+    margin: 0 1px;
+    min-width: 4ch;
+    width: auto;
+    font-size: inherit;
+    line-height: inherit;
+    transition: all 0.2s ease;
+  }
+  
+  .cloze-input:focus {
+    border-bottom: 2px dotted black;
+    box-shadow: 0 2px 0 rgba(0, 0, 0, 0.2);
+    background-color: rgba(0, 0, 0, 0.05);
+  }
+  
+  .cloze-input.correct {
+    border-bottom: 2px dotted #10b981;
+    background-color: rgba(16, 185, 129, 0.1);
+  }
+  
+  .cloze-input.incorrect {
+    border-bottom: 2px dotted #ef4444;
+    background-color: rgba(239, 68, 68, 0.1);
+  }
+
+  .cloze-input::placeholder {
+    color: rgba(0, 0, 0, 0.4);
+    font-style: normal;
+    font-family: monospace;
+    letter-spacing: 0.1em;
+  }
+
+  .typewriter-button {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+    min-width: 100px;
+    min-height: 36px;
+    padding: 8px 14px;
+    background-color: var(--aged-paper-dark);
+    color: var(--typewriter-ink);
+    border: 2px solid black;
+    border-radius: 6px;
+    font-weight: 600;
+    font-size: 14px;
+    cursor: pointer;
+    transition: all 0.15s ease;
+    box-shadow: 
+      0 3px 0 rgba(0, 0, 0, 0.3),
+      0 4px 8px rgba(0, 0, 0, 0.1);
+    position: relative;
+    overflow: hidden;
+  }
+
+  .typewriter-button:hover:not(:disabled) {
+    background-color: rgba(0, 0, 0, 0.05);
+    transform: translateY(-1px);
+    box-shadow: 
+      0 4px 0 rgba(0, 0, 0, 0.3),
+      0 6px 12px rgba(0, 0, 0, 0.15);
+  }
+
+  .typewriter-button:active:not(:disabled) {
+    transform: translateY(2px);
+    box-shadow: 
+      0 1px 0 rgba(0, 0, 0, 0.3),
+      0 2px 4px rgba(0, 0, 0, 0.1);
+  }
+
+  .typewriter-button:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+    transform: translateY(2px);
+    box-shadow: 
+      0 2px 0 rgba(0, 0, 0, 0.2),
+      0 3px 6px rgba(0, 0, 0, 0.05);
+  }
+
+  .typewriter-button:focus {
+    outline: none;
+    box-shadow: 
+      0 4px 0 rgba(0, 0, 0, 0.3),
+      0 6px 12px rgba(0, 0, 0, 0.1),
+      0 0 0 3px rgba(0, 0, 0, 0.2);
+  }
+
+  .prose {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+    font-size: 1.125rem;
+    line-height: 1.7;
+    color: var(--typewriter-ink);
+    overflow-wrap: break-word;
+  }
+  
+  .prose p {
+    margin-bottom: 1.5rem;
+    text-align: justify;
+  }
+
+  .biblio-info {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+    font-size: 0.85rem;
+    color: #666;
+    font-style: italic;
+  }
+
+  .context-box {
+    background-color: rgba(245, 158, 11, 0.08);
+    border-left: 4px solid #f59e0b;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+    font-size: 0.9rem;
+    line-height: 1.6;
+  }
+
+  .hints-box {
+    background-color: rgba(245, 158, 11, 0.08);
+    border-left: 4px solid #f59e0b;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+    font-size: 0.9rem;
+    line-height: 1.6;
+  }
+
+  .round-badge {
+    background-color: rgba(245, 158, 11, 0.1);
+    color: #666;
+    border: 1px solid rgba(245, 158, 11, 0.2);
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+    font-weight: 600;
+  }
+
+  /* Ensure specific game info elements use accessible font */
+  #book-info, #round-info, #contextualization {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+  }
+
+  .loading-text {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+    color: #666;
+  }
+
+  .result-text {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+    font-weight: 600;
+  }
+
+  /* Leaderboard button in footer */
+  .leaderboard-footer-btn {
+    background-color: var(--aged-paper-dark);
+    color: var(--typewriter-ink);
+    border: 2px solid black;
+    border-radius: 0 8px 8px 0;
+    padding: 8px 16px;
+    cursor: pointer;
+    font-size: 1.5rem;
+    line-height: 1;
+    transition: all 0.15s ease;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex: 0 0 auto;
+    min-width: 60px;
+    min-height: 44px;
+    box-shadow:
+      0 3px 0 rgba(0, 0, 0, 0.3),
+      0 4px 8px rgba(0, 0, 0, 0.1);
+    touch-action: manipulation;
+    -webkit-tap-highlight-color: rgba(0, 0, 0, 0.1);
+    user-select: none;
+  }
+
+  .leaderboard-footer-btn:hover {
+    background-color: rgba(0, 0, 0, 0.05);
+    transform: translateY(-1px);
+    box-shadow:
+      0 4px 0 rgba(0, 0, 0, 0.3),
+      0 6px 12px rgba(0, 0, 0, 0.15);
+  }
+
+  .leaderboard-footer-btn:active {
+    transform: translateY(2px);
+    box-shadow:
+      0 1px 0 rgba(0, 0, 0, 0.3),
+      0 2px 4px rgba(0, 0, 0, 0.1);
+  }
+
+
+  /* Mobile responsive */
+  @media (max-width: 768px) {
+    .typewriter-subtitle {
+      display: none;
+    }
+  }
+
+  @media (max-width: 640px) {
+    .prose {
+      font-size: 1rem;
+    }
+
+    .typewriter-text {
+      font-size: 1.75rem;
+    }
+
+    .typewriter-button {
+      min-width: 100px;
+      min-height: 38px;
+      font-size: 0.9rem;
+    }
+
+    .leaderboard-footer-btn {
+      font-size: 1.25rem;
+      padding: 12px 10px;
+      min-width: 50px;
+      min-height: 48px;
+    }
+  }
+
+  @media (max-width: 480px) {
+    .prose {
+      font-size: 0.95rem;
+    }
+
+    .typewriter-text {
+      font-size: 1.5rem;
+    }
+
+    .cloze-input {
+      min-width: 2.5ch;
+    }
+
+    header img {
+      width: 2rem;
+      height: 2rem;
+    }
+
+    .leaderboard-footer-btn {
+      font-size: 1.1rem;
+      padding: 12px 8px;
+      min-width: 48px;
+    }
+  }
+
+  /* Compact question buttons for chat interface */
+  #chat-modal .question-btn {
+    padding: 6px 8px;
+    min-height: auto;
+    font-size: 12px;
+    line-height: 1.3;
+    font-weight: 400;
+    transition: all 0.15s ease;
+  }
+
+  /* Mobile dropdown styling */
+  #question-dropdown {
+    background: var(--aged-paper-dark);
+    border: 2px solid rgba(0, 0, 0, 0.1);
+    border-radius: 8px;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Helvetica Neue', Arial, sans-serif;
+    font-size: 16px;
+    font-weight: 500;
+    color: var(--typewriter-ink);
+    transition: all 0.2s ease;
+  }
+
+  #question-dropdown:focus {
+    outline: none;
+    border-color: rgba(0, 0, 0, 0.3);
+    box-shadow: 0 0 0 3px rgba(0, 0, 0, 0.1);
+  }
+
+  /* Sticky Control Panel */
+  .sticky-controls {
+    position: fixed;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    background: var(--aged-paper-light);
+    border-top: 2px solid rgba(0, 0, 0, 0.1);
+    box-shadow: 0 -4px 12px rgba(0, 0, 0, 0.1);
+    padding: 12px 16px;
+    z-index: 1000;
+    backdrop-filter: blur(8px);
+  }
+
+  .sticky-controls .controls-inner {
+    position: relative;
+    max-width: 1024px;
+    margin: 0 auto;
+    display: flex;
+    gap: 1px;
+    justify-content: center;
+    align-items: center;
+  }
+
+  .sticky-controls .typewriter-button {
+    flex: 1;
+    max-width: 200px;
+    min-height: 44px;
+    margin: 0;
+    border-radius: 0;
+    font-size: 16px;
+    font-weight: 600;
+    position: relative;
+  }
+
+  .sticky-controls .typewriter-button:first-child {
+    border-top-left-radius: 8px;
+    border-bottom-left-radius: 8px;
+  }
+
+  .sticky-controls .typewriter-button:last-child {
+    border-top-right-radius: 8px;
+    border-bottom-right-radius: 8px;
+  }
+
+  .sticky-controls .typewriter-button:not(:last-child) {
+    border-right: 1px solid rgba(0, 0, 0, 0.2);
+  }
+
+  .controls-divider {
+    height: 24px;
+    width: 2px;
+    background: rgba(0, 0, 0, 0.3);
+    margin: 0 -1px;
+    z-index: 1;
+  }
+
+  /* Add bottom padding to main content to prevent overlap */
+  #game-container {
+    padding-bottom: 100px;
+  }
+
+  /* Mobile optimizations for sticky controls */
+  @media (max-width: 640px) {
+    .sticky-controls {
+      padding: 10px 12px;
+    }
+    
+    .sticky-controls .typewriter-button {
+      min-height: 48px;
+      font-size: 16px;
+      padding: 12px 8px;
+    }
+    
+    #game-container {
+      padding-bottom: 90px;
+    }
+  }
+
+  /* Ensure controls stay above mobile keyboards */
+  @media (max-width: 640px) and (max-height: 500px) {
+    .sticky-controls {
+      position: fixed;
+      bottom: 0;
+    }
+  }
+
+  /* Leaderboard Overlay */
+  .leaderboard-overlay {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background: rgba(0, 0, 0, 0.75);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: 2000;
+    opacity: 0;
+    transition: opacity 0.3s ease;
+    backdrop-filter: blur(3px);
+  }
+
+  .leaderboard-overlay.visible {
+    opacity: 1;
+  }
+
+  /* Leaderboard Modal */
+  .leaderboard-modal {
+    background: var(--aged-paper-light);
+    border: 3px solid rgba(0, 0, 0, 0.4);
+    border-radius: 8px;
+    padding: 0;
+    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.5);
+    max-width: 600px;
+    width: 90%;
+    max-height: 85vh;
+    overflow: hidden;
+    animation: slideIn 0.3s ease-out;
+  }
+
+  @keyframes slideIn {
+    from {
+      transform: translateY(-30px);
+      opacity: 0;
+    }
+    to {
+      transform: translateY(0);
+      opacity: 1;
+    }
+  }
+
+  /* Leaderboard Header */
+  .leaderboard-header {
+    background: linear-gradient(180deg, var(--aged-paper-dark) 0%, #d4c9b3 100%);
+    padding: 20px 24px;
+    border-bottom: 3px solid rgba(0, 0, 0, 0.3);
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+  }
+
+  .leaderboard-title {
+    font-family: 'Special Elite', 'Courier New', monospace;
+    font-size: 24px;
+    font-weight: 700;
+    color: var(--typewriter-ink);
+    margin: 0;
+    letter-spacing: 1px;
+  }
+
+  .leaderboard-live-indicator {
+    color: #4ade80;
+    font-size: 12px;
+    margin-left: 8px;
+    opacity: 0.8;
+    transition: opacity 0.3s ease, transform 0.3s ease;
+  }
+
+  .leaderboard-live-indicator.pulse {
+    animation: live-pulse 0.5s ease-out;
+  }
+
+  @keyframes live-pulse {
+    0% {
+      transform: scale(1);
+      opacity: 0.8;
+    }
+    50% {
+      transform: scale(1.5);
+      opacity: 1;
+    }
+    100% {
+      transform: scale(1);
+      opacity: 0.8;
+    }
+  }
+
+  .leaderboard-close {
+    background: transparent;
+    color: var(--typewriter-ink);
+    border: 2px solid rgba(0, 0, 0, 0.3);
+    border-radius: 4px;
+    width: 32px;
+    height: 32px;
+    font-size: 24px;
+    line-height: 1;
+    cursor: pointer;
+    transition: all 0.2s ease;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  .leaderboard-close:hover {
+    background: rgba(0, 0, 0, 0.1);
+    border-color: rgba(0, 0, 0, 0.5);
+  }
+
+  .leaderboard-close:active {
+    background: rgba(0, 0, 0, 0.15);
+  }
+
+  /* Leaderboard Content */
+  .leaderboard-content {
+    padding: 24px;
+    max-height: calc(85vh - 100px);
+    overflow-y: auto;
+    background: var(--aged-paper-light);
+  }
+
+  /* Leaderboard List */
+  .leaderboard-list {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    margin-bottom: 20px;
+  }
+
+  .leaderboard-entry {
+    display: grid;
+    grid-template-columns: 50px 80px 1fr;
+    align-items: center;
+    gap: 12px;
+    padding: 14px 16px;
+    background: var(--aged-paper-dark);
+    border: 3px solid rgba(0, 0, 0, 0.4);
+    border-radius: 6px;
+    font-family: 'Courier New', monospace;
+    transition: all 0.2s ease;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.15);
+  }
+
+  /* Rank Colors */
+  .leaderboard-entry.rank-gold {
+    background: linear-gradient(135deg, #fff7e6 0%, #ffd700 100%);
+    border-color: #b8860b;
+    border-width: 4px;
+    box-shadow: 0 4px 12px rgba(184, 134, 11, 0.4), inset 0 1px 0 rgba(255, 255, 255, 0.5);
+  }
+
+  .leaderboard-entry.rank-silver {
+    background: linear-gradient(135deg, #fff9f2 0%, #e6d7b8 100%);
+    border-color: #a0826d;
+    border-width: 3px;
+    box-shadow: 0 3px 8px rgba(160, 130, 109, 0.3);
+  }
+
+  .leaderboard-entry.rank-standard {
+    background: #ffffff;
+    border-color: rgba(0, 0, 0, 0.3);
+    border-width: 2px;
+  }
+
+  .leaderboard-entry.player-entry {
+    background: linear-gradient(135deg, #fff9f0 0%, #ffd89b 100%);
+    border-color: #cc8800;
+    border-width: 4px;
+    box-shadow: 0 4px 12px rgba(204, 136, 0, 0.35);
+  }
+
+  .leaderboard-entry:hover {
+    transform: translateX(4px);
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+  }
+
+  .entry-rank {
+    font-size: 20px;
+    font-weight: 700;
+    color: var(--typewriter-ink);
+    text-align: center;
+  }
+
+  .entry-initials {
+    font-size: 18px;
+    font-weight: 700;
+    color: var(--typewriter-ink);
+    letter-spacing: 2px;
+    text-align: center;
+    font-family: 'Courier New', monospace;
+  }
+
+  .entry-score {
+    font-size: 16px;
+    font-weight: 600;
+    color: #666;
+  }
+
+  .entry-round {
+    font-size: 14px;
+    color: #999;
+    font-weight: 400;
+  }
+
+  /* Empty State */
+  .leaderboard-empty {
+    text-align: center;
+    padding: 40px 20px;
+    color: #666;
+  }
+
+  .leaderboard-empty p {
+    margin: 8px 0;
+    font-size: 16px;
+  }
+
+  /* Player Stats */
+  .leaderboard-player-stats {
+    margin-top: 24px;
+    padding: 18px;
+    background: rgba(212, 165, 116, 0.08);
+    border: 2px solid rgba(212, 165, 116, 0.25);
+    border-radius: 6px;
+  }
+
+  .player-best {
+    font-size: 16px;
+    font-weight: 600;
+    color: var(--typewriter-ink);
+    margin-bottom: 8px;
+  }
+
+  .player-best .highlight {
+    color: #8b6914;
+    font-weight: 700;
+  }
+
+  .player-stats-details {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    font-size: 14px;
+    color: #666;
+  }
+
+  /* Initials Entry Modal */
+  .initials-overlay {
+    background: rgba(0, 0, 0, 0.9);
+  }
+
+  .initials-modal {
+    max-width: 500px;
+  }
+
+  .initials-header {
+    background: linear-gradient(180deg, #f5f1e8 0%, #e8dcc8 100%);
+    padding: 24px;
+    border-bottom: 3px solid rgba(0, 0, 0, 0.3);
+    text-align: center;
+  }
+
+  .initials-title {
+    font-family: 'Special Elite', 'Courier New', monospace;
+    font-size: 26px;
+    font-weight: 700;
+    color: #000000;
+    margin: 0 0 12px 0;
+    letter-spacing: 1px;
+  }
+
+  .initials-achievement {
+    font-size: 17px;
+    color: #1a1a1a;
+    line-height: 1.6;
+    font-weight: 500;
+  }
+
+  .initials-achievement .highlight {
+    color: #7d3c00;
+    font-weight: 700;
+    text-decoration: underline;
+  }
+
+  .rank-text {
+    font-size: 16px;
+    color: #2c2c2c;
+    font-weight: 600;
+    font-style: normal;
+  }
+
+  .initials-content {
+    padding: 32px 24px;
+    text-align: center;
+    background: var(--aged-paper-light);
+  }
+
+  .initials-prompt {
+    font-size: 20px;
+    font-weight: 700;
+    color: #000000;
+    margin-bottom: 24px;
+  }
+
+  /* Initials Slots */
+  .initials-slots {
+    display: flex;
+    justify-content: center;
+    gap: 16px;
+    margin-bottom: 24px;
+  }
+
+  .initial-slot {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 8px;
+  }
+
+  .initial-slot.active .slot-letter {
+    border-color: #2563eb;
+    background: #eff6ff;
+    box-shadow: 0 0 0 4px rgba(37, 99, 235, 0.3), 0 4px 0 rgba(0, 0, 0, 0.5);
+  }
+
+  .slot-letter {
+    width: 64px;
+    height: 80px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 48px;
+    font-weight: 700;
+    font-family: 'Courier New', monospace;
+    color: #000000;
+    background: #ffffff;
+    border: 3px solid #000000;
+    border-radius: 8px;
+    transition: all 0.2s ease;
+    box-shadow: 0 4px 0 rgba(0, 0, 0, 0.5);
+  }
+
+  .slot-arrows {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+  }
+
+  .arrow-up, .arrow-down {
+    width: 40px;
+    height: 32px;
+    background: var(--aged-paper-dark);
+    border: 2px solid black;
+    border-radius: 4px;
+    font-size: 16px;
+    cursor: pointer;
+    transition: all 0.15s ease;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  .arrow-up:hover, .arrow-down:hover {
+    background: rgba(0, 0, 0, 0.05);
+    transform: scale(1.1);
+  }
+
+  .arrow-up:active, .arrow-down:active {
+    transform: scale(0.95);
+  }
+
+  /* Initials Instructions */
+  /* Text Input Section */
+  .text-input-section {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    margin-bottom: 20px;
+  }
+
+  .initials-text-input {
+    width: 120px;
+    height: 64px;
+    font-size: 32px;
+    font-weight: 700;
+    font-family: 'Courier New', monospace;
+    text-align: center;
+    text-transform: uppercase;
+    letter-spacing: 8px;
+    background: #ffffff;
+    border: 3px solid #000000;
+    border-radius: 8px;
+    box-shadow: 0 4px 0 rgba(0, 0, 0, 0.5);
+    transition: all 0.2s ease;
+    margin-bottom: 8px;
+  }
+
+  .initials-text-input:focus {
+    outline: none;
+    border-color: #2563eb;
+    background: #eff6ff;
+    box-shadow: 0 0 0 4px rgba(37, 99, 235, 0.3), 0 4px 0 rgba(0, 0, 0, 0.5);
+  }
+
+  .input-help {
+    font-size: 12px;
+    color: #666;
+    margin: 0;
+    font-weight: 400;
+  }
+
+  /* Divider */
+  .input-divider {
+    display: flex;
+    align-items: center;
+    margin: 20px 0;
+    color: #666;
+    font-size: 14px;
+    font-weight: 500;
+  }
+
+  .input-divider::before,
+  .input-divider::after {
+    content: '';
+    flex: 1;
+    height: 1px;
+    background: #ddd;
+  }
+
+  .input-divider span {
+    padding: 0 16px;
+  }
+
+  .initials-instructions {
+    margin-bottom: 24px;
+    color: #000000;
+    font-size: 15px;
+    line-height: 1.7;
+    font-weight: 600;
+  }
+
+  .initials-instructions p {
+    margin: 6px 0;
+  }
+
+  .initials-submit {
+    width: 100%;
+    max-width: 200px;
+    min-height: 48px;
+    font-size: 17px;
+    font-weight: 700;
+    color: #000000 !important;
+  }
+
+  /* Success Message */
+  .success-message {
+    max-width: 400px;
+    padding: 32px;
+    text-align: center;
+  }
+
+  .success-content h2 {
+    font-size: 28px;
+    color: #2d5016;
+    margin-bottom: 12px;
+    font-family: 'Special Elite', 'Courier New', monospace;
+    letter-spacing: 1px;
+  }
+
+  .success-content p {
+    font-size: 16px;
+    color: #666;
+    font-family: 'Courier New', monospace;
+  }
+
+  /* Milestone Toast */
+  .milestone-toast {
+    position: fixed;
+    top: 20px;
+    left: 50%;
+    transform: translateX(-50%) translateY(-100px);
+    background: var(--aged-paper-dark);
+    color: var(--typewriter-ink);
+    padding: 16px 24px;
+    border-radius: 8px;
+    border: 3px solid rgba(0, 0, 0, 0.4);
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.3), 0 4px 0 rgba(0, 0, 0, 0.2);
+    z-index: 3000;
+    transition: transform 0.3s ease;
+    font-weight: 600;
+    font-size: 18px;
+    font-family: 'Special Elite', 'Courier New', monospace;
+    letter-spacing: 0.5px;
+  }
+
+  .milestone-toast.visible {
+    transform: translateX(-50%) translateY(0);
+  }
+
+  /* Mobile Responsive */
+  @media (max-width: 640px) {
+    .leaderboard-modal {
+      width: 95%;
+      max-height: 90vh;
+    }
+
+    .leaderboard-title {
+      font-size: 20px;
+    }
+
+    .leaderboard-entry {
+      grid-template-columns: 40px 70px 1fr;
+      gap: 8px;
+      padding: 12px;
+    }
+
+    .entry-rank {
+      font-size: 16px;
+    }
+
+    .entry-initials {
+      font-size: 16px;
+    }
+
+    .entry-score {
+      font-size: 14px;
+    }
+
+    .initials-modal {
+      width: 95%;
+    }
+
+    .slot-letter {
+      width: 56px;
+      height: 70px;
+      font-size: 40px;
+    }
+
+    .initials-slots {
+      gap: 12px;
+    }
+
+    .initials-text-input {
+      width: 100px;
+      height: 56px;
+      font-size: 28px;
+      letter-spacing: 6px;
+    }
+
+    .input-divider {
+      font-size: 12px;
+    }
+
+    .input-help {
+      font-size: 11px;
+    }
+  }
+
+  /* Print styles */
+  @media print {
+    body {
+      background: white;
+      color: black;
+    }
+
+    .paper-sheet::before {
+      display: none;
+    }
+
+    .typewriter-button {
+      display: none;
+    }
+
+    .sticky-controls {
+      display: none;
+    }
+
+    #game-container {
+      padding-bottom: 0;
+    }
+
+    .leaderboard-overlay,
+    .milestone-toast {
+      display: none;
+    }
+  }
+}
+
+/* Custom utility classes */
+@layer utilities {
+  .ink-ribbon-lines {
+    background: repeating-linear-gradient(
+      to bottom,
+      transparent,
+      transparent 23px,
+      rgba(139, 92, 246, 0.03) 23px,
+      rgba(139, 92, 246, 0.03) 24px
+    );
+  }
+}

src/welcomeOverlay.js

@@ -0,0 +1,106 @@
+// Welcome overlay for first-time users
+class WelcomeOverlay {
+  constructor() {
+    this.isVisible = false;
+    this.hasBeenShown = localStorage.getItem('cloze-reader-welcomed') === 'true';
+  }
+
+  show() {
+    // Always show overlay regardless of previous views
+    
+    this.isVisible = true;
+    const overlay = this.createOverlay();
+    document.body.appendChild(overlay);
+    
+    // Animate in
+    requestAnimationFrame(() => {
+      overlay.style.opacity = '1';
+    });
+  }
+
+  createOverlay() {
+    const overlay = document.createElement('div');
+    overlay.className = 'welcome-overlay';
+    overlay.style.opacity = '0';
+
+    const modal = document.createElement('div');
+    modal.className = 'welcome-modal';
+    modal.style.cssText = `
+      max-width: 500px;
+      margin: 20px;
+      text-align: center;
+    `;
+
+    modal.innerHTML = `
+      <div style="display: flex; justify-content: center; margin-bottom: 12px;">
+        <img src="https://media.githubusercontent.com/media/milwrite/cloze-reader/main/icon.png"
+             alt=""
+             style="width: 48px; height: 48px; border-radius: 6px;"
+             onerror="this.style.display='none'">
+      </div>
+      <h1 class="welcome-title">
+        Cloze Reader
+      </h1>
+      
+      <div class="welcome-content">
+        <p>
+          <strong>How to play:</strong> Fill in the blanks to advance through levels with increasing difficulty and vocabulary complexity.
+        </p>
+
+        <p>
+          <strong>Data source:</strong> Excerpted historical and literary texts from Project Gutenberg's public domain collection, processed via Hugging Face Datasets.
+        </p>
+
+        <p style="margin-bottom: 0;">
+          <strong>AI assistance:</strong> Powered by Google's Gemma-3-27b model via OpenRouter for word selection, hints, and contextualization.
+        </p>
+      </div>
+
+      <button id="welcome-start-btn" class="typewriter-button">
+        Start Reading
+      </button>
+    `;
+
+    overlay.appendChild(modal);
+
+    // Add click handler
+    const startBtn = modal.querySelector('#welcome-start-btn');
+    startBtn.addEventListener('click', () => this.hide());
+
+    // Allow clicking outside to close
+    overlay.addEventListener('click', (e) => {
+      if (e.target === overlay) this.hide();
+    });
+
+    return overlay;
+  }
+
+  hide() {
+    const overlay = document.querySelector('.welcome-overlay');
+    if (!overlay) return;
+
+    overlay.style.opacity = '0';
+    setTimeout(() => {
+      overlay.remove();
+      this.isVisible = false;
+      
+      // Remember that user has seen welcome
+      localStorage.setItem('cloze-reader-welcomed', 'true');
+      this.hasBeenShown = true;
+    }, 300);
+  }
+
+  // Method to reset welcome (for testing or new features)
+  reset() {
+    localStorage.removeItem('cloze-reader-welcomed');
+    this.hasBeenShown = false;
+  }
+
+  // Force show overlay (for testing)
+  forceShow() {
+    this.hasBeenShown = false;
+    this.show();
+  }
+}
+
+export default WelcomeOverlay;