fix level progression and optimize ai word selection

- Fix level progression bug where advancement only considered second passage
- Add round-level result tracking for proper level advancement
- Improve AI prompts to prevent selection from first/last clauses
- Add JSON parsing robustness for trailing commas and malformed arrays
- Enhance word selection criteria to avoid ALL-CAPS and table contents
- Update difficulty scaling: 1-5 (1 blank), 6-10 (2 blanks), 11+ (3 blanks)
- Optimize batch processing with exact word count requirements

docs/ai-prompts-and-parameters.md

@@ -6,6 +6,23 @@ This document outlines the different types of AI requests, prompts, and paramete
 
 The Cloze Reader uses OpenRouter's API with the `google/gemma-3-27b-it:free` model to power various AI-driven features. All requests use a consistent retry mechanism with exponential backoff (3 attempts, 0.5s initial delay).
 
+## Difficulty Progression
+
+The game uses a level-based system to control difficulty:
+
+### Blank Count by Level
+- **Levels 1-5**: 1 blank per passage
+- **Levels 6-10**: 2 blanks per passage
+- **Level 11+**: 3 blanks per passage
+
+### Word Length Constraints by Level
+- **Levels 1-3**: 3-10 letters (easier, shorter words)
+- **Levels 4+**: 5-13 letters (longer, more challenging words)
+
+### Hint System by Level
+- **Levels 1-2**: Shows word length, first letter, and last letter
+- **Level 3+**: Shows word length and first letter only
+
 ## Request Types
 
 ### 1. Contextual Hint Generation
@@ -55,14 +72,18 @@ The Cloze Reader uses OpenRouter's API with the `google/gemma-3-27b-it:free` mod
   "messages": [
     {
       "role": "user",
-      "content": "You are a cluemaster vocabulary selector for educational cloze exercises. Select exactly [COUNT] words from this passage for a cloze exercise.\n\nREQUIREMENTS:\n- Choose clear, properly-spelled words (no OCR errors like \"andsatires\")\n- Select meaningful nouns, verbs, or adjectives (4-12 letters)\n- Words must appear EXACTLY as written in the passage\n- Avoid: capitalized words, function words, archaic terms, proper nouns, technical jargon\n- Skip any words that look malformed or concatenated\n\nReturn ONLY a JSON array of the selected words.\n\nPassage: \"[PASSAGE_TEXT]\""
+      "content": "You are a cluemaster vocabulary selector for educational cloze exercises. Select exactly [COUNT] words from this passage for a cloze exercise.\n\nCLOZE DELETION PRINCIPLES:\n- Select words that require understanding context and vocabulary to identify\n- Choose words essential for comprehension that test language ability\n- Target words where deletion creates meaningful cognitive gaps\n\nREQUIREMENTS:\n- Choose clear, properly-spelled words (no OCR errors like \"andsatires\")\n- Select meaningful nouns, verbs, or adjectives ([WORD_LENGTH] letters)\n- Words must appear EXACTLY as written in the passage\n- Avoid: capitalized words, function words, archaic terms, proper nouns, technical jargon\n- Skip any words that look malformed or concatenated\n\nReturn ONLY a JSON array of the selected words.\n\nPassage: \"[PASSAGE_TEXT]\""
     }
   ],
   "max_tokens": 100,
-  "temperature": 0.5
+  "temperature": 0.3
 }
 ```
 
+**Word Length by Level:**
+- Levels 1-3: 3-10 letters
+- Levels 4+: 5-13 letters
+
 **Response Format:** JSON array of strings
 ```json
 ["word1", "word2", "word3"]
@@ -83,14 +104,18 @@ The Cloze Reader uses OpenRouter's API with the `google/gemma-3-27b-it:free` mod
     },
     {
       "role": "user",
-      "content": "Process these two passages for cloze exercises:\n\nPASSAGE 1:\nTitle: \"[BOOK1_TITLE]\" by [BOOK1_AUTHOR]\nText: \"[PASSAGE1_TEXT]\"\nSelect [COUNT] words for blanks.\n\nPASSAGE 2:\nTitle: \"[BOOK2_TITLE]\" by [BOOK2_AUTHOR]\nText: \"[PASSAGE2_TEXT]\"\nSelect [COUNT] words for blanks.\n\nFor each passage return:\n- \"words\": array of selected words (exactly as they appear)\n- \"context\": one-sentence intro about the book/author\n\nReturn as JSON: {\"passage1\": {...}, \"passage2\": {...}}"
+      "content": "Process these two passages for cloze exercises:\n\nPASSAGE 1:\nTitle: \"[BOOK1_TITLE]\" by [BOOK1_AUTHOR]\nText: \"[PASSAGE1_TEXT]\"\nSelect [COUNT] words for blanks.\n\nPASSAGE 2:\nTitle: \"[BOOK2_TITLE]\" by [BOOK2_AUTHOR]\nText: \"[PASSAGE2_TEXT]\"\nSelect [COUNT] words for blanks.\n\nWORD SELECTION CRITERIA:\n[WORD_LENGTH_CRITERIA]\n- Choose meaningful nouns, verbs, or adjectives\n- Avoid capitalized words, function words, archaic terms\n- Words must appear EXACTLY as written in the passage\n\nFor each passage return:\n- \"words\": array of selected words (exactly as they appear)\n- \"context\": one-sentence intro about the book/author\n\nReturn as JSON: {\"passage1\": {...}, \"passage2\": {...}}"
     }
   ],
-  "max_tokens": 500,
+  "max_tokens": 800,
   "temperature": 0.5
 }
 ```
 
+**Word Length by Level:**
+- Levels 1-3: Select words 3-10 letters long
+- Levels 4+: Select words 5-13 letters long
+
 **Response Format:**
 ```json
 {
@@ -150,12 +175,12 @@ All requests include these headers:
 |---------|------------|-------------|-------------|
 | Hints | 50 | 0.6 | 3 attempts |
 | Word Selection | 100 | 0.3 | 3 attempts |
-| Batch Processing | 500 | 0.3 | 3 attempts |
-| Contextualization | 80 | 0.2 | 3 attempts |
+| Batch Processing | 800 | 0.5 | 3 attempts |
+| Contextualization | 80 | 0.5 | 3 attempts |
 
 ### Temperature Guidelines
-- **0.2**: Factual content (contextualization)
-- **0.3**: Structured tasks (word selection, batch processing)
+- **0.3**: Structured tasks (word selection)
+- **0.5**: Semi-structured tasks (batch processing, contextualization)
 - **0.6**: Creative tasks (hint generation)
 
 ## Response Processing

index.html

@@ -7,6 +7,7 @@
     <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/x-icon" href="/favicon.ico">
 </head>
 <body class="min-h-screen">
     <div id="app" class="container mx-auto px-4 py-8 max-w-4xl">

package.json

@@ -30,9 +30,8 @@
   "devDependencies": {
     "http-server": "^14.1.1"
   },
-  "dependencies": {},
   "engines": {
     "node": ">=14.0.0",
     "python": ">=3.9"
   }
-}
+}

src/aiService.js

@@ -151,8 +151,10 @@ REQUIREMENTS:
 - Choose clear, properly-spelled words (no OCR errors like "andsatires")
 - Select meaningful nouns, verbs, or adjectives (4-12 letters)
 - Words must appear EXACTLY as written in the passage
-- Avoid: capitalized words, function words, archaic terms, proper nouns, technical jargon
+- Avoid: capitalized words, ALL-CAPS words, function words, archaic terms, proper nouns, technical jargon
 - Skip any words that look malformed or concatenated
+- NEVER select words from the first or last sentence/clause of the passage
+- Choose words from the middle portions for better context dependency
 
 Return ONLY a JSON array of the selected words.
 
@@ -243,10 +245,20 @@ Title: "${book2.title}" by ${book2.author}
 Text: "${passage2}"
 Select ${blanksPerPassage} words for blanks.
 
+SELECTION RULES:
+- Select EXACTLY ${blanksPerPassage} word${blanksPerPassage > 1 ? 's' : ''} per passage, no more, no less
+- Choose meaningful nouns, verbs, or adjectives (4-12 letters)
+- Avoid capitalized words, ALL-CAPS words, and table of contents entries
+- NEVER select words from the first or last sentence/clause of each passage
+- Choose words from the middle portions for better context dependency
+- Words must appear EXACTLY as written in the passage
+
 For each passage return:
-- "words": array of selected words (exactly as they appear)
+- "words": array of EXACTLY ${blanksPerPassage} selected word${blanksPerPassage > 1 ? 's' : ''} (exactly as they appear in the text)
 - "context": one-sentence intro about the book/author
 
+CRITICAL: The "words" array must contain exactly ${blanksPerPassage} element${blanksPerPassage > 1 ? 's' : ''} for each passage.
+
 Return as JSON: {"passage1": {...}, "passage2": {...}}`
           }],
           max_tokens: 800,
@@ -287,6 +299,9 @@ Return as JSON: {"passage1": {...}, "passage2": {...}}`
           .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) {
@@ -325,6 +340,10 @@ Return as JSON: {"passage1": {...}, "passage2": {...}}`
           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() !== '');
+        
         return parsed;
       } catch (e) {
         console.error('Failed to parse batch response:', e);

src/app.js

@@ -204,7 +204,7 @@ class App {
   async handleNext() {
     try {
       // Show loading immediately with specific message
-      this.showLoading(true, 'Loading passage...');
+      this.showLoading(true, 'Loading passages...');
       
       // Clear chat history when starting new passage/round
       this.chatUI.clearChatHistory();

src/clozeGameEngine.js

@@ -19,6 +19,7 @@ class ClozeGame {
     this.hints = [];
     this.chatService = new ChatService(aiService);
     this.lastResults = null; // Store results for answer revelation
+    this.roundResults = []; // Store results for both passages in current round
     
     // Two-passage system properties
     this.currentBooks = []; // Array of two books per round
@@ -52,11 +53,11 @@ class ClozeGame {
       this.currentPassageIndex = 0;
       
       // Calculate blanks per passage based on level
-      // Progressive difficulty: levels 1-2 = 1 blank, levels 3-4 = 2 blanks, level 5+ = 3 blanks
+      // Levels 1-5: 1 blank, Levels 6-10: 2 blanks, Level 11+: 3 blanks
       let blanksPerPassage;
-      if (this.currentLevel <= 2) {
+      if (this.currentLevel <= 5) {
         blanksPerPassage = 1;
-      } else if (this.currentLevel <= 4) {
+      } else if (this.currentLevel <= 10) {
         blanksPerPassage = 2;
       } else {
         blanksPerPassage = 3;
@@ -65,12 +66,17 @@ class ClozeGame {
       // Process both passages in a single API call
       try {
         const batchResult = await aiService.processBothPassages(
-          passage1, book1, passage2, book2, blanksPerPassage
+          passage1, book1, passage2, book2, blanksPerPassage, this.currentLevel
         );
         
         // Store the preprocessed data for both passages
         this.preprocessedData = batchResult;
         
+        // Debug: Log what the AI returned
+        console.log(`Level ${this.currentLevel}: Requested ${blanksPerPassage} blanks per passage`);
+        console.log(`Passage 1 received ${batchResult.passage1.words.length} words:`, batchResult.passage1.words);
+        console.log(`Passage 2 received ${batchResult.passage2.words.length} words:`, batchResult.passage2.words);
+        
         // Set up first passage using preprocessed data
         this.currentBook = book1;
         this.originalText = this.passages[0];
@@ -186,20 +192,49 @@ class ClozeGame {
   async createClozeTextFromPreprocessed(passageIndex) {
     // Use preprocessed word selection from batch API call
     const preprocessed = passageIndex === 0 ? this.preprocessedData.passage1 : this.preprocessedData.passage2;
-    const selectedWords = preprocessed.words;
+    let selectedWords = preprocessed.words;
+    
+    // Calculate expected number of blanks based on level
+    let expectedBlanks;
+    if (this.currentLevel <= 5) {
+      expectedBlanks = 1;
+    } else if (this.currentLevel <= 10) {
+      expectedBlanks = 2;
+    } else {
+      expectedBlanks = 3;
+    }
+    
+    // Limit selected words to expected number
+    if (selectedWords.length > expectedBlanks) {
+      console.log(`AI returned ${selectedWords.length} words but expected ${expectedBlanks}, limiting to ${expectedBlanks}`);
+      selectedWords = selectedWords.slice(0, expectedBlanks);
+    }
     
     // Split passage into words
     const words = this.originalText.split(/(\s+)/);
     const wordsOnly = words.filter(w => w.trim() !== '');
     
-    // Find indices of selected words
+    // Find indices of selected words using exact matching
     const selectedIndices = [];
     selectedWords.forEach(word => {
-      const index = wordsOnly.findIndex((w, idx) => 
-        w.toLowerCase().includes(word.toLowerCase()) && !selectedIndices.includes(idx)
-      );
+      // First try exact match (cleaned)
+      let index = wordsOnly.findIndex((w, idx) => {
+        const cleanW = w.replace(/[^\w]/g, '').toLowerCase();
+        const cleanWord = word.replace(/[^\w]/g, '').toLowerCase();
+        return cleanW === cleanWord && !selectedIndices.includes(idx);
+      });
+      
+      // Fallback to includes match if exact fails
+      if (index === -1) {
+        index = wordsOnly.findIndex((w, idx) => 
+          w.toLowerCase().includes(word.toLowerCase()) && !selectedIndices.includes(idx)
+        );
+      }
+      
       if (index !== -1) {
         selectedIndices.push(index);
+      } else {
+        console.warn(`Could not find word "${word}" in passage`);
       }
     });
     
@@ -208,6 +243,8 @@ class ClozeGame {
     this.hints = [];
     const clozeWords = [...wordsOnly];
     
+    console.log(`Creating ${selectedIndices.length} blanks from ${selectedWords.length} selected words`);
+    
     selectedIndices.forEach((wordIndex, blankIndex) => {
       const originalWord = wordsOnly[wordIndex];
       const cleanWord = originalWord.replace(/[^\w]/g, '');
@@ -259,11 +296,11 @@ class ClozeGame {
 
   async createClozeText() {
     const words = this.originalText.split(' ');
-    // Progressive difficulty: levels 1-2 = 1 blank, levels 3-4 = 2 blanks, level 5+ = 3 blanks
+    // Progressive difficulty: levels 1-5 = 1 blank, levels 6-10 = 2 blanks, level 11+ = 3 blanks
     let numberOfBlanks;
-    if (this.currentLevel <= 2) {
+    if (this.currentLevel <= 5) {
       numberOfBlanks = 1;
-    } else if (this.currentLevel <= 4) {
+    } else if (this.currentLevel <= 10) {
       numberOfBlanks = 2;
     } else {
       numberOfBlanks = 3;
@@ -277,7 +314,8 @@ class ClozeGame {
     try {
       significantWords = await aiService.selectSignificantWords(
         this.originalText, 
-        numberOfBlanks
+        numberOfBlanks,
+        this.currentLevel
       );
       console.log('AI selected words:', significantWords);
     } catch (error) {
@@ -580,6 +618,9 @@ class ClozeGame {
 
     // Store results for potential answer revelation
     this.lastResults = resultsData;
+    
+    // Store results for round-level tracking
+    this.roundResults[this.currentPassageIndex] = resultsData;
 
     return resultsData;
   }
@@ -616,7 +657,7 @@ class ClozeGame {
         // Clear chat conversations for new passage
         this.chatService.clearConversations();
         
-        // Clear last results
+        // Clear last results (but keep roundResults for level advancement)
         this.lastResults = null;
         
         // Use preprocessed data if available
@@ -651,14 +692,21 @@ class ClozeGame {
   }
 
   nextRound() {
-    // Check if user passed the previous round
-    const passed = this.lastResults && this.lastResults.passed;
+    // Check if user passed the previous round based on overall round performance
+    let roundPassed = false;
+    if (this.roundResults.length === 2) {
+      // Both passages completed - check if user passed at least one passage
+      roundPassed = this.roundResults.some(result => result && result.passed);
+    } else if (this.lastResults) {
+      // Fallback to single passage result
+      roundPassed = this.lastResults.passed;
+    }
     
     // Always increment round counter
     this.currentRound++;
     
-    // Only advance level if user passed
-    if (passed) {
+    // Only advance level if user passed the round
+    if (roundPassed) {
       this.currentLevel++;
     }
     // If failed, stay at same level
@@ -666,8 +714,9 @@ class ClozeGame {
     // Clear chat conversations for new round
     this.chatService.clearConversations();
     
-    // Clear last results since we're moving to new round
+    // Clear results since we're moving to new round
     this.lastResults = null;
+    this.roundResults = [];
     
     return this.startNewRound();
   }

src/init-env.js

@@ -13,7 +13,5 @@ document.addEventListener('DOMContentLoaded', function() {
     if (hfMeta && hfMeta.content) {
         window.HF_API_KEY = hfMeta.content;
         console.log('HF API key loaded');
-    } else {
-        console.log('No HF API key found in meta tags');
     }
 });