Study cards: from-your-notes, read aloud, timed runs

From your notes: the generator now stores a verbatim source quote with every
activity (schema + prompt + a server-side clamp so a chatty model cannot drop a
card), and the feedback panel shows the sentence that carries it with the quote
highlighted green. Decks made before the change, and quotes the model trimmed,
fall back to a local IDF-weighted match over the saved notes text
(lib/notes-source.ts): nothing is shown unless at least two distinct terms
land. The passage hides in exam mode with the other reveals.

Read aloud: a Web Speech API speaker control on the text a learner reads
(flashcard faces, questions, statements, sentences, instructions) via
lib/speech.ts and components/SpeakButton.tsx — one utterance app-wide, a voice
matched to the deck's language, and no button at all where the browser has no
speech synthesis. It used to sit inside the flashcard's flip button (nested
buttons, tapping it flipped the card); it now lives next to the hint row.

Timed runs: the feed chrome carries a timer chip (off by default) that gives
each card 30 seconds; a card that runs out is recorded as a miss through the
same path as a wrong answer (history + SRS agree), shows a toast, and the feed
moves straight on with a fresh budget. handleAnswered ignores a second result
per card, so a timeout plus a manual answer cannot record twice.

The generator's type spec now names what each type suits (language decks lean
on flashcards/matching/fill blank, ordering needs a real sequence, short answer
reasoning), so the deck-aware guidance covers all seven types.

New activities-test suite (24 checks: quote path, local path, the green mark,
the speech stub, the timed run on Playwright's fake clock), registered in
run-all; phase2 pins that the notes passage stays hidden in exam mode; en+cs
keys for every new string; no new dependencies. Version 0.6.1, SW v83.

lib/prompts.ts

@@ -64,28 +64,28 @@ export const VISION_USER_INSTRUCTION = `Transcribe these notes and extract the s
 /* Step 2 - activity generation                                        */
 /* ------------------------------------------------------------------ */
 
-export const ACTIVITY_JSON_SPEC = `Each activity is one JSON object with a "type" field. Exactly these seven types exist:
+export const ACTIVITY_JSON_SPEC = `Each activity is one JSON object with a "type" field. Exactly these seven types exist. Each one names the material it suits best - pick types that fit the notes, never force a type that does not.
 
-1. flashcard - tap to flip
+1. flashcard - tap to flip. Best for language vocabulary, terms to remember and quick recall.
    { "type": "flashcard", "topic": "short label", "front": "question or term", "back": "answer or definition", "explanation": "why this matters" }
 
-2. multiple_choice - exactly 4 options, exactly one correct
+2. multiple_choice - exactly 4 options, exactly one correct. Best for single facts that are easy to confuse, and for definitions that need a plausible-sounding wrong option.
    { "type": "multiple_choice", "topic": "short label", "question": "...", "options": ["A", "B", "C", "D"], "correctIndex": 0, "explanation": "why the correct option is right and the others are wrong" }
    Put the correct answer at a varied position across the deck (not always 0!).
 
-3. true_false - one statement
+3. true_false - one statement. Best for fine distinctions, exceptions and common mix-ups.
    { "type": "true_false", "topic": "short label", "statement": "...", "answer": true, "explanation": "why it is true/false" }
    Roughly half of them should be false, and false statements must be subtly wrong (a swapped term, a wrong number), never absurd.
 
-4. fill_blank - the sentence contains the placeholder "____"
+4. fill_blank - the sentence contains the placeholder "____". Best for key terms, formulas and language vocabulary that has to be produced inside a sentence (genders, prepositions, endings).
    { "type": "fill_blank", "topic": "short label", "sentence": "Mitochondria produce ____ for the cell.", "answer": "ATP", "options": ["ATP", "DNA", "glucose", "water"], "explanation": "..." }
    "options" is optional but preferred: 3-6 plausible choices including the answer.
 
-5. matching - 3 to 6 term/definition pairs
+5. matching - 3 to 6 term/definition pairs. Best for vocabulary, terms to definitions, symbols to meanings, words to translations, dates to events - the strongest type for language decks.
    Every term and definition must be distinct: a definition describes exactly one term, so never reuse a definition for two pairs.
    { "type": "matching", "topic": "short label", "instruction": "Match each term to its definition.", "pairs": [{ "term": "Osmosis", "definition": "diffusion of water across a membrane" }], "explanation": "..." }
 
-6. ordering - 3 to 7 items given in the CORRECT order (the app shuffles them)
+6. ordering - 3 to 7 items given in the CORRECT order (the app shuffles them). Best for material with a real sequence.
    Use it ONLY when the notes contain a real sequence the learner can reason about: historical or
    chronological events, the stages of a process, steps of a procedure, a lifecycle, a ranked scale.
    If the notes only list unrelated things (works, authors, terms, places, values), do NOT invent an
@@ -95,11 +95,11 @@ export const ACTIVITY_JSON_SPEC = `Each activity is one JSON object with a "type
    the learner has to work out the order from what each item says, not read it off.
    { "type": "ordering", "topic": "short label", "instruction": "Put the events in the order they happened.", "items": ["The Allies land in Normandy", "Paris is liberated", "Germany surrenders"], "explanation": "..." }
 
-7. short_answer - typed answer, graded by AI
+7. short_answer - typed answer, graded by AI. Best for asking why or how something works, or for applying a rule.
    { "type": "short_answer", "topic": "short label", "question": "...", "referenceAnswer": "a model answer in one or two sentences", "keyPoints": ["idea the question asks for", "second idea"], "explanation": "..." }
    keyPoints must contain only the ideas needed to answer the question — never extras the question does not ask about (dates, places, names, numbers). For a "why" question require the reason, not the year.
 
-Every activity must also have "topic" (2-4 words) and "explanation" (one or two sentences, plain language).`;
+Every activity must also have "topic" (2-4 words), "explanation" (one or two sentences, plain language) and "source": the exact words from the notes that prove the answer — one phrase or one sentence, at most 25 words, copied verbatim (no ellipses, no edits, same language as the notes). If several places mention it, pick the clearest one. The app shows this quote back to the learner under "From your notes".`;
 
 export const GENERATION_SYSTEM_PROMPT = `You are Freezmo's activity designer. You turn a student's own notes into a deck of short, playful, interactive study activities.
 
@@ -109,6 +109,7 @@ Hard rules:
 - Use ONLY information contained in the provided notes. Never invent facts, definitions, numbers, dates or formulas. If the notes do not contain enough material for the requested number of activities, create fewer - quality over quantity.
 - Every explanation must be answerable from the notes; do not introduce outside knowledge.
 - Vary the activity types. Use a healthy mix of all seven types below, and never put more than two activities of the same type in a row.
+- Match the mix to the material: language decks lean on flashcards, matching and fill_blank; historical or process material on ordering and true_false; reasoning and explanations on short_answer and multiple_choice.
 - Cover the whole notes, not just the first paragraph. Spread activities across the different topics, definitions, formulas and facts.
 - Make the wrong options plausible (common mix-ups from the same notes), never silly filler.
 - Every option, item, term and definition on a card must be unique: never repeat the same wording